xref: /illumos-gate/usr/src/lib/libpicl/picl.h (revision 1da57d551424de5a9d469760be7c4b4d4f10a755)
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 2004 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 
27 #ifndef	_PICL_H
28 #define	_PICL_H
29 
30 #ifdef	__cplusplus
31 extern "C" {
32 #endif
33 
34 /*
35  * PICL Interface
36  */
37 
38 #include <sys/types.h>
39 
40 #define	PICL_VERSION_1	0x1
41 
42 /*
43  * A PICL handle
44  */
45 typedef uint64_t picl_nodehdl_t;
46 typedef uint64_t picl_prophdl_t;
47 
48 /*
49  * Maximum length of a property name
50  */
51 #define	PICL_PROPNAMELEN_MAX	256
52 #define	PICL_CLASSNAMELEN_MAX	(PICL_PROPNAMELEN_MAX - sizeof ("__"))
53 
54 /*
55  * Maximum size of a property value
56  */
57 #define	PICL_PROPSIZE_MAX	(512 * 1024)
58 
59 /*
60  * PICL property access modes
61  */
62 #define	PICL_READ		0x1
63 #define	PICL_WRITE		0x2
64 /* Not seen by clients */
65 #define	PICL_VOLATILE		0x4
66 
67 /*
68  * PICL error numbers
69  */
70 typedef enum {
71 	PICL_SUCCESS = 0x0,
72 	PICL_FAILURE,		/* general failure */
73 	PICL_NORESPONSE,	/* No response */
74 	PICL_UNKNOWNSERVICE,	/* unknown PICL service */
75 	PICL_NOTINITIALIZED,	/* interface not initialized */
76 	PICL_INVALIDARG,	/* invalid arguments passed */
77 	PICL_VALUETOOBIG,	/* value too big for buffer */
78 	PICL_PROPNOTFOUND,	/* property not found */
79 	PICL_NOTTABLE,		/* not a table */
80 	PICL_NOTNODE,		/* not a node */
81 	PICL_NOTPROP,		/* not a prop */
82 	PICL_ENDOFLIST,		/* end of list */
83 	PICL_PROPEXISTS,	/* prop already exists */
84 	PICL_NOTWRITABLE,	/* not writable */
85 	PICL_PERMDENIED,	/* permission denied */
86 	PICL_INVALIDHANDLE,	/* invalid handle */
87 	PICL_STALEHANDLE,	/* stale handle */
88 	PICL_NOTSUPPORTED,	/* version not supported */
89 	PICL_TIMEDOUT,		/* timed out */
90 	PICL_CANTDESTROY,	/* cannot destroy */
91 	PICL_TREEBUSY,		/* too busy to lock tree */
92 	PICL_CANTPARENT,	/* already has a parent */
93 	PICL_RESERVEDNAME,	/* property name is reserved */
94 	PICL_INVREFERENCE,	/* Invalid reference value */
95 	PICL_WALK_CONTINUE,	/* continue walking tree */
96 	PICL_WALK_TERMINATE,	/* stop walking tree */
97 	PICL_NODENOTFOUND,	/* node not found */
98 	PICL_NOSPACE,		/* not enough space available */
99 	PICL_NOTREADABLE,	/* property not readable */
100 	PICL_PROPVALUNAVAILABLE	/* property value unavailable */
101 } picl_errno_t;
102 
103 /*
104  * PICL property types
105  */
106 typedef	enum {
107 	PICL_PTYPE_UNKNOWN = 0x0,
108 	PICL_PTYPE_VOID,		/* exists or not */
109 	PICL_PTYPE_INT,			/* scalar */
110 	PICL_PTYPE_UNSIGNED_INT,	/* scalar */
111 	PICL_PTYPE_FLOAT,		/* scalar */
112 	PICL_PTYPE_REFERENCE,		/* reference handle */
113 	PICL_PTYPE_TABLE,		/* table handle */
114 	PICL_PTYPE_TIMESTAMP,		/* time stamp */
115 	PICL_PTYPE_BYTEARRAY,		/* array of bytes */
116 	PICL_PTYPE_CHARSTRING		/* nul terminated array of chars */
117 } picl_prop_type_t;
118 
119 typedef struct {
120 	picl_prop_type_t	type;
121 	unsigned int		accessmode;	/* always == PICL_READ */
122 	size_t			size;		/* item size or string size */
123 	char			name[PICL_PROPNAMELEN_MAX];
124 } picl_propinfo_t;
125 
126 /*
127  * -------------------------------------
128  * Function prototypes of PICL Interface
129  * -------------------------------------
130  */
131 
132 extern	int  picl_initialize(void);
133 extern	int  picl_shutdown(void);
134 extern	int  picl_get_root(picl_nodehdl_t *nodehandle);
135 extern	int  picl_get_propval(picl_prophdl_t proph, void *valbuf,
136 		size_t sz);
137 extern	int  picl_get_propval_by_name(picl_nodehdl_t nodeh,
138 		const char *propname, void *valbuf, size_t sz);
139 extern	int  picl_set_propval(picl_prophdl_t proph, void *valbuf,
140 		size_t sz);
141 extern	int  picl_set_propval_by_name(picl_nodehdl_t nodeh,
142 		const char *propname, void *valbuf, size_t sz);
143 extern  int  picl_get_propinfo(picl_prophdl_t proph, picl_propinfo_t *pi);
144 extern	int  picl_get_first_prop(picl_nodehdl_t nodeh, picl_prophdl_t *proph);
145 extern	int  picl_get_next_prop(picl_prophdl_t proph, picl_prophdl_t *nexth);
146 extern	int  picl_get_prop_by_name(picl_nodehdl_t nodeh, const char *nm,
147 			picl_prophdl_t *ph);
148 extern	int  picl_get_next_by_row(picl_prophdl_t thish, picl_prophdl_t *proph);
149 extern	int  picl_get_next_by_col(picl_prophdl_t thish, picl_prophdl_t *proph);
150 extern	int  picl_wait(unsigned int secs);
151 extern	char *picl_strerror(int err);
152 extern	int  picl_walk_tree_by_class(picl_nodehdl_t rooth,
153 		const char *classname, void *c_args,
154 		int (*callback_fn)(picl_nodehdl_t hdl, void *args));
155 extern	int  picl_get_propinfo_by_name(picl_nodehdl_t nodeh, const char *pname,
156 		picl_propinfo_t *pinfo, picl_prophdl_t *proph);
157 
158 extern	int  picl_find_node(picl_nodehdl_t rooth, char *pname,
159 		picl_prop_type_t ptype, void *pval, size_t valsize,
160 		picl_nodehdl_t *retnodeh);
161 
162 extern	int  picl_get_node_by_path(const char *piclpath, picl_nodehdl_t *nodeh);
163 
164 extern	int  picl_get_frutree_parent(picl_nodehdl_t devh, picl_nodehdl_t *fruh);
165 
166 /*
167  * Standard PICL names: properties and nodes
168  */
169 #define	PICL_NODE_ROOT		"/"
170 #define	PICL_NODE_PLATFORM	"platform"
171 #define	PICL_NODE_OBP		"obp"
172 #define	PICL_NODE_FRUTREE	"frutree"
173 
174 #define	PICL_PROP_NAME		"name"
175 #define	PICL_PROP_CLASSNAME	"_class"
176 #define	PICL_PROP_PARENT	"_parent"
177 #define	PICL_PROP_CHILD		"_child"
178 #define	PICL_PROP_PEER		"_peer"
179 
180 #define	PICL_CLASS_PICL		"picl"
181 
182 #ifdef	__cplusplus
183 }
184 #endif
185 
186 #endif	/* _PICL_H */
187