xref: /illumos-gate/usr/src/lib/libfru/include/libfru.h (revision 6bbe0590)
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 2009 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 
27 #ifndef	_LIBFRU_H
28 #define	_LIBFRU_H
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 #include <sys/types.h>
35 
36 #define	LIBFRU_VERSION 1
37 
38 /* fru errno return types */
39 typedef enum
40 {
41 	FRU_SUCCESS = 0,
42 	FRU_NODENOTFOUND,
43 	FRU_IOERROR,
44 	FRU_NOREGDEF,
45 	FRU_NOTCONTAINER,
46 	FRU_INVALHANDLE,
47 	FRU_INVALSEG,
48 	FRU_INVALPATH,
49 	FRU_INVALELEMENT,
50 	FRU_INVALDATASIZE,
51 	FRU_DUPSEG,
52 	FRU_NOTFIELD,
53 	FRU_NOSPACE,
54 	FRU_DATANOTFOUND,
55 	FRU_ITERFULL,
56 	FRU_INVALPERM,
57 	FRU_NOTSUP,
58 	FRU_ELEMNOTTAGGED,
59 	FRU_CONTFAILED,
60 	FRU_SEGCORRUPT,
61 	FRU_DATACORRUPT,
62 	FRU_FAILURE,
63 	FRU_WALK_TERMINATE,
64 	FRU_NORESPONSE
65 
66 } fru_errno_t;
67 
68 /*
69  * Structures for libfru.c
70  */
71 
72 /* Fru Display Types */
73 typedef enum { FDISP_Binary = 0, FDISP_Octal, FDISP_Hex, FDISP_Decimal,
74 	FDISP_String, FDISP_Time, FDISP_MSGID, FDISP_UUID, FDISP_UNDEFINED
75 } fru_displaytype_t;
76 
77 /* Fru Data Types */
78 typedef enum { FDTYPE_Binary = 0, FDTYPE_ByteArray, FDTYPE_ASCII,
79 		FDTYPE_Unicode, FDTYPE_Record, FDTYPE_Enumeration,
80 		FDTYPE_UNDEFINED
81 } fru_datatype_t;
82 
83 /* Fru Which Type */
84 typedef enum { FRU_No = 0, FRU_Yes, FRU_WHICH_UNDEFINED } fru_which_t;
85 
86 /* Fru Iteration Types */
87 typedef enum { FRU_FIFO = 0, FRU_Circular,
88 		FRU_Linear, FRU_LIFO, FRU_NOT_ITERATED } fru_itertype_t;
89 
90 /* Fru Handle Type */
91 typedef uint64_t fru_nodehdl_t;
92 
93 /* Node Types */
94 typedef enum
95 {
96 	FRU_NODE_UNKNOWN,
97 	FRU_NODE_LOCATION,
98 	FRU_NODE_FRU,
99 	FRU_NODE_CONTAINER
100 } fru_node_t;
101 
102 /* Sting list */
103 typedef struct {
104 	unsigned int num;
105 	char **strs;
106 } fru_strlist_t;
107 
108 #if defined(_LITTLE_ENDIAN)
109 typedef union
110 {
111 	uint32_t raw_data;
112 	struct
113 	{
114 		unsigned repair_perm : 3;
115 		unsigned engineering_perm : 3;
116 		unsigned operations_perm : 3;
117 		unsigned domain_perm : 3;
118 		unsigned field_perm : 3;
119 		unsigned unused : 13;
120 		unsigned fixed : 1;
121 		unsigned opaque : 1;
122 		unsigned ignore_checksum : 1;
123 		unsigned encrypted : 1;
124 
125 	} field;
126 } fru_segdesc_t;
127 #else
128 typedef union
129 {
130 	uint32_t raw_data;
131 	struct
132 	{
133 		unsigned encrypted : 1;
134 		unsigned ignore_checksum : 1;
135 		unsigned opaque : 1;
136 		unsigned fixed : 1;
137 		unsigned unused : 13;
138 		unsigned field_perm : 3;
139 		unsigned domain_perm : 3;
140 		unsigned operations_perm : 3;
141 		unsigned engineering_perm : 3;
142 		unsigned repair_perm : 3;
143 	} field;
144 } fru_segdesc_t;
145 #endif
146 
147 #define	FRU_SEGDESC_PERM_DELETE_MASK (1<<0)
148 #define	FRU_SEGDESC_PERM_WRITE_MASK (1<<1)
149 #define	FRU_SEGDESC_PERM_READ_MASK (1<<2)
150 #define	FRU_SEGDESC_PERM_RW_MASK ((1<<2) | (1<<1))
151 #define	FRU_SEGDESC_PERM_RD_MASK ((1<<2) | (1<<0))
152 #define	FRU_SEGDESC_PERM_WD_MASK ((1<<1) | (1<<0))
153 #define	FRU_SEGDESC_PERM_RWD_MASK ((1<<0) | (1<<1) | (1<<2))
154 
155 #define	FRU_SEGDESC_ALL_RO_MASK 0x000036db
156 
157 #define	FRU_SEGDESC_FIXED_MASK (1<<28)
158 #define	FRU_SEGDESC_OPAQUE_MASK (1<<29)
159 #define	FRU_SEGDESC_IGNORECHECKSUM_MASK (1<<30)
160 #define	FRU_SEGDESC_ENCRYPTED_MASK (1<<31)
161 
162 /* segment descriptor field perm. */
163 #define	SEGMENT_READ	4
164 #define	SEGMENT_WRITE	2
165 #define	SEGMENT_DELETE	1
166 
167 #if defined(_LITTLE_ENDIAN)
168 typedef union
169 {
170 	uint32_t all_bits;
171 	struct
172 	{
173 		unsigned : 8;
174 		unsigned : 8;
175 		unsigned : 8;
176 		unsigned : 7;
177 		uint32_t read_only : 1;
178 
179 	} field;
180 } fru_seg_hwdesc_t;
181 #else
182 typedef union
183 {
184 	uint32_t all_bits;
185 	struct
186 	{
187 		uint32_t read_only : 1;
188 		unsigned : 7;
189 		unsigned : 8;
190 		unsigned : 8;
191 		unsigned : 8;
192 	} field;
193 } fru_seg_hwdesc_t;
194 #endif
195 
196 #define	FRU_SEGNAMELEN 2
197 typedef struct {
198 	uint32_t version;
199 	char name[FRU_SEGNAMELEN + 1]; /* +1 to include '\0' byte. */
200 	fru_segdesc_t desc;
201 	uint32_t size;
202 	uint32_t address; /* used for fixed segments (0 otherwise) */
203 	fru_seg_hwdesc_t hw_desc;
204 } fru_segdef_t;
205 
206 /* Fru enumerations */
207 typedef struct {
208 	uint64_t value;
209 	char *text;
210 } fru_enum_t;
211 
212 /* Element/Field level operations */
213 #define	FRU_ELEMDEF_REV 1
214 typedef struct {
215 	uint32_t version;
216 	fru_datatype_t data_type;
217 	fru_which_t tagged;
218 	size_t data_length; /* in Bytes or Bits depending on data_type */
219 	fru_displaytype_t disp_type;
220 	fru_which_t purgeable;
221 	fru_which_t relocatable;
222 	unsigned int enum_count; /* number of enum values in table */
223 	fru_enum_t *enum_table; /* enum strings or sub-elements depending on */
224 					/* the data_type */
225 	unsigned int iteration_count;
226 	fru_itertype_t iteration_type;
227 	char *example_string;
228 } fru_elemdef_t;
229 
230 /* Data Source operations */
231 fru_errno_t fru_open_data_source(const char *name, ...);
232 fru_errno_t fru_close_data_source(void);
233 
234 /* Tree operations */
235 fru_errno_t fru_get_root(fru_nodehdl_t *handle);
236 fru_errno_t fru_get_child(fru_nodehdl_t handle, fru_nodehdl_t *child);
237 fru_errno_t fru_get_peer(fru_nodehdl_t handle, fru_nodehdl_t *peer);
238 fru_errno_t fru_get_parent(fru_nodehdl_t handle, fru_nodehdl_t *parent);
239 
240 /* Node information functions */
241 fru_errno_t fru_get_name_from_hdl(fru_nodehdl_t handle, char **name);
242 fru_errno_t fru_get_node_type(fru_nodehdl_t handle, fru_node_t *type);
243 
244 /* Segment Operations */
245 fru_errno_t fru_list_segments(fru_nodehdl_t container, fru_strlist_t *list);
246 fru_errno_t fru_create_segment(fru_nodehdl_t container, fru_segdef_t *def);
247 fru_errno_t fru_remove_segment(fru_nodehdl_t container, const char *seg_name);
248 fru_errno_t fru_get_segment_def(fru_nodehdl_t container, const char *seg_name,
249 				fru_segdef_t *definition);
250 fru_errno_t fru_list_elems_in(fru_nodehdl_t container, const char *seg_name,
251 				fru_strlist_t *list);
252 
253 /* Data operations */
254 fru_errno_t fru_read_field(fru_nodehdl_t container,
255 			char **seg_name, /* IN/OUT */
256 			unsigned int   instance,
257 			const char *field_path,
258 			void **data,
259 			size_t *data_len,
260 			char **found_path);
261 fru_errno_t fru_update_field(fru_nodehdl_t container,
262 				char *seg_name,
263 				unsigned int instance,
264 				const char *field_path,
265 				void *data,
266 				size_t length);
267 fru_errno_t fru_get_num_iterations(fru_nodehdl_t container,
268 					char **seg_name, /* IN/OUT */
269 					unsigned int instance,
270 					const char *iter_path,
271 					int *num_there,
272 					char **found_path);
273 
274 /* Tagged Element operations */
275 fru_errno_t fru_add_element(fru_nodehdl_t container, const char *seg_name,
276 				const char *element);
277 fru_errno_t fru_delete_element(fru_nodehdl_t container, const char *seg_name,
278 				unsigned int instance, const char *element);
279 
280 /* General library support */
281 fru_errno_t fru_get_definition(const char *element_name,
282 				fru_elemdef_t *definition);
283 fru_errno_t fru_get_registry(fru_strlist_t *list);
284 fru_errno_t fru_get_tagged_parents(const char *elem_name,
285 				fru_strlist_t *parents);
286 
287 /* Structure destroy functions */
288 fru_errno_t fru_destroy_strlist(fru_strlist_t *list);
289 fru_errno_t fru_destroy_elemdef(fru_elemdef_t *def);
290 
291 /* Enum to String Conversions */
292 const char *fru_strerror(fru_errno_t errnum);
293 const char *get_displaytype_str(fru_displaytype_t e);
294 const char *get_datatype_str(fru_datatype_t e);
295 const char *get_which_str(fru_which_t e);
296 const char *get_itertype_str(fru_itertype_t e);
297 
298 #ifdef	__cplusplus
299 }
300 #endif
301 
302 #endif /* _LIBFRU_H */
303