xref: /illumos-gate/usr/src/lib/libfru/include/libfru.h (revision 60405de4d8688d96dd05157c28db3ade5c9bc234)
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, Version 1.0 only
6  * (the "License").  You may not use this file except in compliance
7  * with the License.
8  *
9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10  * or http://www.opensolaris.org/os/licensing.
11  * See the License for the specific language governing permissions
12  * and limitations under the License.
13  *
14  * When distributing Covered Code, include this CDDL HEADER in each
15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16  * If applicable, add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your own identifying
18  * information: Portions Copyright [yyyy] [name of copyright owner]
19  *
20  * CDDL HEADER END
21  */
22 /*
23  * Copyright 2005 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 #pragma ident	"%Z%%M%	%I%	%E% SMI"
31 
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35 
36 #include <sys/types.h>
37 
38 #define	LIBFRU_VERSION 1
39 
40 /* fru errno return types */
41 typedef enum
42 {
43 	FRU_SUCCESS = 0,
44 	FRU_NODENOTFOUND,
45 	FRU_IOERROR,
46 	FRU_NOREGDEF,
47 	FRU_NOTCONTAINER,
48 	FRU_INVALHANDLE,
49 	FRU_INVALSEG,
50 	FRU_INVALPATH,
51 	FRU_INVALELEMENT,
52 	FRU_INVALDATASIZE,
53 	FRU_DUPSEG,
54 	FRU_NOTFIELD,
55 	FRU_NOSPACE,
56 	FRU_DATANOTFOUND,
57 	FRU_ITERFULL,
58 	FRU_INVALPERM,
59 	FRU_NOTSUP,
60 	FRU_ELEMNOTTAGGED,
61 	FRU_CONTFAILED,
62 	FRU_SEGCORRUPT,
63 	FRU_DATACORRUPT,
64 	FRU_FAILURE,
65 	FRU_WALK_TERMINATE,
66 	FRU_NORESPONSE
67 
68 } fru_errno_t;
69 
70 /*
71  * Structures for libfru.c
72  */
73 
74 /* Fru Display Types */
75 typedef enum { FDISP_Binary = 0, FDISP_Octal, FDISP_Hex, FDISP_Decimal,
76 	FDISP_String, FDISP_Time, FDISP_MSGID, FDISP_UUID, FDISP_UNDEFINED
77 } fru_displaytype_t;
78 
79 /* Fru Data Types */
80 typedef enum { FDTYPE_Binary = 0, FDTYPE_ByteArray, FDTYPE_ASCII,
81 		FDTYPE_Unicode, FDTYPE_Record, FDTYPE_Enumeration,
82 		FDTYPE_UNDEFINED
83 } fru_datatype_t;
84 
85 /* Fru Which Type */
86 typedef enum { FRU_No = 0, FRU_Yes, FRU_WHICH_UNDEFINED } fru_which_t;
87 
88 /* Fru Iteration Types */
89 typedef enum { FRU_FIFO = 0, FRU_Circular,
90 		FRU_Linear, FRU_LIFO, FRU_NOT_ITERATED } fru_itertype_t;
91 
92 /* Fru Handle Type */
93 typedef uint64_t fru_nodehdl_t;
94 
95 /* Node Types */
96 typedef enum
97 {
98 	FRU_NODE_UNKNOWN,
99 	FRU_NODE_LOCATION,
100 	FRU_NODE_FRU,
101 	FRU_NODE_CONTAINER
102 } fru_node_t;
103 
104 /* Sting list */
105 typedef struct {
106 	unsigned int num;
107 	char **strs;
108 } fru_strlist_t;
109 
110 typedef union
111 {
112 	uint32_t raw_data;
113 	struct
114 	{
115 		unsigned encrypted : 1;
116 		unsigned ignore_checksum : 1;
117 		unsigned opaque : 1;
118 		unsigned fixed : 1;
119 		unsigned unused : 13;
120 		unsigned field_perm : 3;
121 		unsigned domain_perm : 3;
122 		unsigned operations_perm : 3;
123 		unsigned engineering_perm : 3;
124 		unsigned repair_perm : 3;
125 	} field;
126 } fru_segdesc_t;
127 
128 #define	FRU_SEGDESC_PERM_DELETE_MASK (1<<0)
129 #define	FRU_SEGDESC_PERM_WRITE_MASK (1<<1)
130 #define	FRU_SEGDESC_PERM_READ_MASK (1<<2)
131 #define	FRU_SEGDESC_PERM_RW_MASK ((1<<2) | (1<<1))
132 #define	FRU_SEGDESC_PERM_RD_MASK ((1<<2) | (1<<0))
133 #define	FRU_SEGDESC_PERM_WD_MASK ((1<<1) | (1<<0))
134 #define	FRU_SEGDESC_PERM_RWD_MASK ((1<<0) | (1<<1) | (1<<2))
135 
136 #define	FRU_SEGDESC_ALL_RO_MASK 0x000036db
137 
138 #define	FRU_SEGDESC_FIXED_MASK (1<<28)
139 #define	FRU_SEGDESC_OPAQUE_MASK (1<<29)
140 #define	FRU_SEGDESC_IGNORECHECKSUM_MASK (1<<30)
141 #define	FRU_SEGDESC_ENCRYPTED_MASK (1<<31)
142 
143 /* segment descriptor field perm. */
144 #define	SEGMENT_READ	4
145 #define	SEGMENT_WRITE	2
146 #define	SEGMENT_DELETE	1
147 
148 typedef union
149 {
150 	uint32_t all_bits;
151 	struct
152 	{
153 		uint32_t read_only : 1;
154 		unsigned : 7;
155 		unsigned : 8;
156 		unsigned : 8;
157 		unsigned : 8;
158 	} field;
159 } fru_seg_hwdesc_t;
160 
161 #define	FRU_SEGNAMELEN 2
162 typedef struct {
163 	uint32_t version;
164 	char name[FRU_SEGNAMELEN + 1]; /* +1 to include '\0' byte. */
165 	fru_segdesc_t desc;
166 	uint32_t size;
167 	uint32_t address; /* used for fixed segments (0 otherwise) */
168 	fru_seg_hwdesc_t hw_desc;
169 } fru_segdef_t;
170 
171 /* Fru enumerations */
172 typedef struct {
173 	uint64_t value;
174 	char *text;
175 } fru_enum_t;
176 
177 /* Element/Field level operations */
178 #define	FRU_ELEMDEF_REV 1
179 typedef struct {
180 	uint32_t version;
181 	fru_datatype_t data_type;
182 	fru_which_t tagged;
183 	size_t data_length; /* in Bytes or Bits depending on data_type */
184 	fru_displaytype_t disp_type;
185 	fru_which_t purgeable;
186 	fru_which_t relocatable;
187 	unsigned int enum_count; /* number of enum values in table */
188 	fru_enum_t *enum_table; /* enum strings or sub-elements depending on */
189 					/* the data_type */
190 	unsigned int iteration_count;
191 	fru_itertype_t iteration_type;
192 	char *example_string;
193 } fru_elemdef_t;
194 
195 /* Data Source operations */
196 fru_errno_t fru_open_data_source(const char *name, ...);
197 fru_errno_t fru_close_data_source(void);
198 
199 /* Tree operations */
200 fru_errno_t fru_get_root(fru_nodehdl_t *handle);
201 fru_errno_t fru_get_child(fru_nodehdl_t handle, fru_nodehdl_t *child);
202 fru_errno_t fru_get_peer(fru_nodehdl_t handle, fru_nodehdl_t *peer);
203 fru_errno_t fru_get_parent(fru_nodehdl_t handle, fru_nodehdl_t *parent);
204 
205 /* Node information functions */
206 fru_errno_t fru_get_name_from_hdl(fru_nodehdl_t handle, char **name);
207 fru_errno_t fru_get_node_type(fru_nodehdl_t handle, fru_node_t *type);
208 
209 /* Segment Operations */
210 fru_errno_t fru_list_segments(fru_nodehdl_t container, fru_strlist_t *list);
211 fru_errno_t fru_create_segment(fru_nodehdl_t container, fru_segdef_t *def);
212 fru_errno_t fru_remove_segment(fru_nodehdl_t container, const char *seg_name);
213 fru_errno_t fru_get_segment_def(fru_nodehdl_t container, const char *seg_name,
214 				fru_segdef_t *definition);
215 fru_errno_t fru_list_elems_in(fru_nodehdl_t container, const char *seg_name,
216 				fru_strlist_t *list);
217 
218 /* Data operations */
219 fru_errno_t fru_read_field(fru_nodehdl_t container,
220 			char **seg_name, /* IN/OUT */
221 			unsigned int   instance,
222 			const char *field_path,
223 			void **data,
224 			size_t *data_len,
225 			char **found_path);
226 fru_errno_t fru_update_field(fru_nodehdl_t container,
227 				char *seg_name,
228 				unsigned int instance,
229 				const char *field_path,
230 				void *data,
231 				size_t length);
232 fru_errno_t fru_get_num_iterations(fru_nodehdl_t container,
233 					char **seg_name, /* IN/OUT */
234 					unsigned int instance,
235 					const char *iter_path,
236 					int *num_there,
237 					char **found_path);
238 
239 /* Tagged Element operations */
240 fru_errno_t fru_add_element(fru_nodehdl_t container, const char *seg_name,
241 				const char *element);
242 fru_errno_t fru_delete_element(fru_nodehdl_t container, const char *seg_name,
243 				unsigned int instance, const char *element);
244 
245 /* General library support */
246 fru_errno_t fru_get_definition(const char *element_name,
247 				fru_elemdef_t *definition);
248 fru_errno_t fru_get_registry(fru_strlist_t *list);
249 fru_errno_t fru_get_tagged_parents(const char *elem_name,
250 				fru_strlist_t *parents);
251 
252 /* Structure destroy functions */
253 fru_errno_t fru_destroy_strlist(fru_strlist_t *list);
254 fru_errno_t fru_destroy_elemdef(fru_elemdef_t *def);
255 
256 /* Enum to String Conversions */
257 const char *fru_strerror(fru_errno_t errnum);
258 const char *get_displaytype_str(fru_displaytype_t e);
259 const char *get_datatype_str(fru_datatype_t e);
260 const char *get_which_str(fru_which_t e);
261 const char *get_itertype_str(fru_itertype_t e);
262 
263 #ifdef	__cplusplus
264 }
265 #endif
266 
267 #endif /* _LIBFRU_H */
268