xref: /illumos-gate/usr/src/common/elfcap/elfcap.h (revision 1ba081ee)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 
22 /*
23  * Copyright (c) 2004, 2010, Oracle and/or its affiliates. All rights reserved.
24  * Copyright 2019, Joyent, Inc.
25  */
26 
27 #ifndef _ELFCAP_DOT_H
28 #define	_ELFCAP_DOT_H
29 
30 #include <sys/types.h>
31 
32 #ifdef	__cplusplus
33 extern "C" {
34 #endif
35 
36 /*
37  * Type used to represent capability bitmasks. This 32-bit type cannot be
38  * widened without breaking the ability to use them in ELFCLASS32 objects.
39  */
40 typedef uint32_t elfcap_mask_t;
41 
42 /*
43  * The elfcap code handles mappings to and from several string styles.
44  * The caller uses elfcap_style_t to specify the style to use.
45  *
46  * The bottom 16 bits are used to represent styles, and the upper 16
47  * bits are used for flags to modify default behavior.
48  */
49 #define	ELFCAP_STYLE_MASK(_style) (_style & 0xff)
50 
51 typedef enum {
52 	ELFCAP_STYLE_FULL =	1,	/* Full formal name (e.g. AV_386_SSE) */
53 	ELFCAP_STYLE_UC =	2,	/* Informal upper case (e.g. SSE) */
54 	ELFCAP_STYLE_LC =	3,	/* Informal lower case (e.g. sse) */
55 
56 	ELFCAP_STYLE_F_ICMP =	0x0100	 /* Use case insensitive strcmp */
57 } elfcap_style_t;
58 
59 /*
60  * String descriptor: Contains the string and strlen(string). elfcap can
61  * be used in contexts (ld.so.1) where we do not want to make calls to
62  * string processing functions, so the length is calculated at compile time.
63  */
64 typedef	struct {
65 	const char	*s_str;
66 	size_t		s_len;
67 } elfcap_str_t;
68 
69 /*
70  * Capabilities descriptor: This maps the integer bit value
71  * (c_val) to/from the various strings that represent it.
72  *
73  * c_val is normally expected to be a non-zero power of 2
74  * value (i.e. a single set bit). The value 0 is special, and
75  * used to represent a "reserved" placeholder in an array of
76  * capabilities. These reserved values have NULL string pointers,
77  * and are intended to be ignored by the processing code.
78  */
79 typedef	struct {
80 	elfcap_mask_t	c_val;		/* Bit value */
81 	elfcap_str_t	c_full;		/* ELFCAP_STYLE_FULL */
82 	elfcap_str_t	c_uc;		/* ELFCAP_STYLE_UC */
83 	elfcap_str_t	c_lc;		/* ELFCAP_STYLE_LC */
84 } elfcap_desc_t;
85 
86 /*
87  * Valid format values: The various formats in which a generated
88  * string representing bitmap values can be displayed.
89  *
90  * This must be kept in sync with the format[] array in elfcap.c.
91  */
92 typedef enum {
93 	ELFCAP_FMT_SNGSPACE =		0,
94 	ELFCAP_FMT_DBLSPACE =		1,
95 	ELFCAP_FMT_PIPSPACE =		2
96 } elfcap_fmt_t;
97 
98 /*
99  * Error codes:
100  */
101 typedef enum {
102 	ELFCAP_ERR_NONE =		0,	/* no error */
103 	ELFCAP_ERR_BUFOVFL =		1,	/* buffer overfow */
104 	ELFCAP_ERR_INVFMT =		2,	/* invalid format */
105 	ELFCAP_ERR_UNKTAG =		3,	/* unknown capabilities tag */
106 	ELFCAP_ERR_UNKMACH =		4,	/* unknown machine type */
107 	ELFCAP_ERR_INVSTYLE =		5	/* unknown style */
108 } elfcap_err_t;
109 
110 
111 /*
112  * # of each type of capability known to the system. These values
113  * must be kept in sync with the arrays found in elfcap.c.
114  */
115 #define	ELFCAP_NUM_SF1			3
116 #define	ELFCAP_NUM_HW1_SPARC		30
117 #define	ELFCAP_NUM_HW1_386		32
118 #define	ELFCAP_NUM_HW2_386		29
119 
120 
121 /*
122  * Given a capability section tag and value, call the proper underlying
123  * "to str" function to generate the string description.
124  */
125 extern elfcap_err_t elfcap_tag_to_str(elfcap_style_t, uint64_t,
126     elfcap_mask_t, char *, size_t, elfcap_fmt_t, ushort_t);
127 
128 /*
129  * The functions that convert from a specific capability value to
130  * a string representation all use the same common prototype.
131  */
132 typedef elfcap_err_t elfcap_to_str_func_t(elfcap_style_t, elfcap_mask_t, char *,
133     size_t, elfcap_fmt_t, ushort_t);
134 
135 extern elfcap_to_str_func_t elfcap_hw1_to_str;
136 extern elfcap_to_str_func_t elfcap_hw2_to_str;
137 extern elfcap_to_str_func_t elfcap_sf1_to_str;
138 
139 /*
140  * The reverse mapping: Given a string representation, turn it back into
141  * integer form.
142  */
143 typedef elfcap_mask_t elfcap_from_str_func_t(elfcap_style_t,
144     const char *, ushort_t mach);
145 
146 /*
147  * Given a capability section tag and string, call the proper underlying
148  * "from str" function to generate the numeric value.
149  */
150 extern elfcap_mask_t elfcap_tag_from_str(elfcap_style_t, uint64_t,
151     const char *, ushort_t);
152 
153 extern elfcap_from_str_func_t elfcap_hw1_from_str;
154 extern elfcap_from_str_func_t elfcap_hw2_from_str;
155 extern elfcap_from_str_func_t elfcap_sf1_from_str;
156 
157 /*
158  * These functions give access to the individual descriptor arrays.
159  * The caller is allowed to copy and use the string pointers contained
160  * in the descriptors, but must not alter them. Functions are used instead
161  * of making the arrays directly visible to preclude copy relocations in
162  * non-pic code.
163  */
164 extern const elfcap_desc_t *elfcap_getdesc_hw1_sparc(void);
165 extern const elfcap_desc_t *elfcap_getdesc_hw1_386(void);
166 extern const elfcap_desc_t *elfcap_getdesc_sf1(void);
167 
168 #ifdef	__cplusplus
169 }
170 #endif
171 
172 #endif /* _ELFCAP_DOT_H */
173