xref: /illumos-gate/usr/src/lib/libpool/common/pool.h (revision 4f364e7c95ee7fd9d5bbeddc1940e92405bb0e72)
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  * Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
23  * Use is subject to license terms.
24  */
25 
26 /*
27  *  NOTE
28  *
29  *  The following contents of this file are private to the
30  *  implementation of the Solaris system and are subject to change at
31  *  any time without notice.  Applications using these interfaces may
32  *  fail to run on future releases.
33  */
34 
35 #ifndef	_POOL_H
36 #define	_POOL_H
37 
38 #pragma ident	"%Z%%M%	%I%	%E% SMI"
39 
40 #include <sys/procset.h>
41 #include <sys/types.h>
42 #include <sys/pool.h>
43 
44 #ifdef	__cplusplus
45 extern "C" {
46 #endif
47 
48 /*
49  * Library versioning support (c.f. elf_version(3e)).
50  *
51  * You can enquire about the version number of the library
52  * by passing POOL_VER_NONE.  POOL_VER_CURRENT is the current
53  * (most capable) version.
54  *
55  * You can set the version used by the library by passing the
56  * required version number.  If this is not possible, the version
57  * returned will be POOL_VER_NONE.
58  */
59 #define	POOL_VER_CURRENT	1
60 #define	POOL_VER_NONE		0
61 
62 extern uint_t pool_version(uint_t ver);
63 
64 #ifndef PO_TRUE
65 #define	PO_TRUE	1
66 #endif
67 
68 #ifndef PO_FALSE
69 #define	PO_FALSE	0
70 #endif
71 
72 #ifndef PO_SUCCESS
73 #define	PO_SUCCESS	0
74 #endif
75 
76 #ifndef PO_FAIL
77 #define	PO_FAIL	-1
78 #endif
79 
80 /* Error codes */
81 #define	POE_OK			0
82 #define	POE_BAD_PROP_TYPE	1
83 #define	POE_INVALID_CONF	2
84 #define	POE_NOTSUP		3
85 #define	POE_INVALID_SEARCH    	4
86 #define	POE_BADPARAM    	5
87 #define	POE_PUTPROP    		6
88 #define	POE_DATASTORE		7
89 #define	POE_SYSTEM		8
90 #define	POE_ACCESS		9
91 
92 /* Open Flags */
93 #define	PO_RDONLY		0x0
94 #define	PO_RDWR			0x1
95 #define	PO_CREAT		0x2
96 #define	PO_DISCO		0x4
97 #define	PO_UPDATE		0x8
98 #define	PO_TEMP			0x10
99 
100 /* Allocation policy */
101 #define	POA_IMPORTANCE		"importance based"
102 #define	POA_SURPLUS_TO_DEFAULT	"surplus to default"
103 
104 /* Pools updates */
105 #define	POU_SYSTEM		0x1
106 #define	POU_POOL		0x2
107 #define	POU_PSET		0x4
108 #define	POU_CPU			0x8
109 
110 /* Data Export Formats */
111 typedef enum pool_export_format {
112 	POX_NATIVE,		/* Native data representation format */
113 	POX_TEXT		/* Text */
114 } pool_export_format_t;
115 
116 /* Property data types */
117 typedef enum pool_value_class {
118 	POC_INVAL = -1,
119 	POC_UINT,
120 	POC_INT,
121 	POC_DOUBLE,
122 	POC_BOOL,
123 	POC_STRING
124 } pool_value_class_t;
125 
126 /* Validation levels */
127 typedef enum pool_valid_level {
128 	POV_NONE = 0,		/* No validation */
129 	POV_LOOSE,		/* Loose validation */
130 	POV_STRICT,		/* Strict validation */
131 	POV_RUNTIME		/* Validate instantiation on current machine */
132 } pool_valid_level_t;
133 
134 /* conf states */
135 typedef enum pool_conf_state {
136 	POF_INVALID = -1,
137 	POF_VALID,
138 	POF_DESTROY
139 } pool_conf_state_t;
140 
141 /* Element data values */
142 typedef struct pool_value pool_value_t;
143 
144 /* Elements */
145 typedef struct pool_elem pool_elem_t;
146 typedef struct pool pool_t;
147 typedef struct pool_resource pool_resource_t;
148 typedef struct pool_component pool_component_t;
149 
150 /*
151  * Resource management configuration
152  */
153 typedef struct pool_conf pool_conf_t;
154 
155 extern int		pool_error(void);
156 extern const char	*pool_strerror(int);
157 extern int		pool_resource_type_list(const char **, uint_t *);
158 extern int		pool_get_status(int *);
159 extern int		pool_set_status(int);
160 
161 /* Configuration manipulation */
162 extern pool_conf_t *pool_conf_alloc(void);
163 extern void pool_conf_free(pool_conf_t *);
164 extern pool_conf_state_t pool_conf_status(const pool_conf_t *);
165 
166 extern int pool_conf_close(pool_conf_t *);
167 extern int pool_conf_remove(pool_conf_t *);
168 extern int pool_conf_open(pool_conf_t *, const char *, int);
169 extern int pool_conf_rollback(pool_conf_t *);
170 extern int pool_conf_commit(pool_conf_t *, int);
171 extern int pool_conf_export(const pool_conf_t *, const char *,
172     pool_export_format_t);
173 extern int pool_conf_validate(const pool_conf_t *, pool_valid_level_t);
174 extern int pool_conf_update(const pool_conf_t *, int *);
175 extern pool_t *pool_get_pool(const pool_conf_t *, const char *);
176 extern pool_t **pool_query_pools(const pool_conf_t *, uint_t *,
177     pool_value_t **);
178 extern pool_resource_t *pool_get_resource(const pool_conf_t *, const char *,
179     const char *);
180 extern pool_resource_t **pool_query_resources(const pool_conf_t *, uint_t *,
181     pool_value_t **);
182 extern pool_component_t **pool_query_components(const pool_conf_t *, uint_t *,
183     pool_value_t **);
184 extern const char *pool_conf_location(const pool_conf_t *);
185 extern char *pool_conf_info(const pool_conf_t *, int);
186 
187 /* Resource manipulation */
188 extern pool_resource_t *pool_resource_create(pool_conf_t *, const char *,
189     const char *);
190 extern int pool_resource_destroy(pool_conf_t *, pool_resource_t *);
191 extern int pool_resource_transfer(pool_conf_t *, pool_resource_t *,
192     pool_resource_t *, uint64_t);
193 extern int pool_resource_xtransfer(pool_conf_t *, pool_resource_t *,
194     pool_resource_t *, pool_component_t **);
195 extern pool_component_t **pool_query_resource_components(const pool_conf_t *,
196     const pool_resource_t *, uint_t *, pool_value_t **);
197 extern char *pool_resource_info(const pool_conf_t *, const pool_resource_t *,
198     int);
199 
200 /* Pool manipulation */
201 extern pool_t *pool_create(pool_conf_t *, const char *);
202 extern int pool_destroy(pool_conf_t *, pool_t *);
203 extern int pool_associate(pool_conf_t *, pool_t *, const pool_resource_t *);
204 extern int pool_dissociate(pool_conf_t *, pool_t *, const pool_resource_t *);
205 extern char *pool_info(const pool_conf_t *, const pool_t *, int);
206 extern pool_resource_t **pool_query_pool_resources(const pool_conf_t *,
207     const pool_t *, uint_t *, pool_value_t **);
208 
209 /* Resource Component Manipulation */
210 extern pool_resource_t *pool_get_owning_resource(const pool_conf_t *,
211     const pool_component_t *);
212 extern char *pool_component_info(const pool_conf_t *, const pool_component_t *,
213     int);
214 
215 /* Property manipulation */
216 extern pool_value_class_t pool_get_property(const pool_conf_t *,
217     const pool_elem_t *, const char *, pool_value_t *);
218 extern int pool_put_property(pool_conf_t *, pool_elem_t *, const char *,
219     const pool_value_t *);
220 extern int pool_rm_property(pool_conf_t *, pool_elem_t *, const char *);
221 
222 /*
223  * Walk the associated properties of the supplied element calling the supplied
224  * function for each property in turn. There is no implied order in the walk.
225  * The arg parameter allows caller-specific data to be passed to the call.
226  */
227 extern int pool_walk_properties(pool_conf_t *, pool_elem_t *, void *,
228     int (*)(pool_conf_t *, pool_elem_t *, const char *, pool_value_t *,
229 	    void *));
230 
231 /* Get the underlying element */
232 extern pool_elem_t *pool_conf_to_elem(const pool_conf_t *);
233 extern pool_elem_t *pool_to_elem(const pool_conf_t *, const pool_t *);
234 extern pool_elem_t *pool_resource_to_elem(const pool_conf_t *,
235     const pool_resource_t *);
236 extern pool_elem_t *pool_component_to_elem(const pool_conf_t *,
237     const pool_component_t *);
238 
239 /* Pool Property Value Manipulation */
240 /* Get/Set Pool Property Values and Type */
241 extern int pool_value_get_uint64(const pool_value_t *, uint64_t *);
242 extern int pool_value_get_int64(const pool_value_t *, int64_t *);
243 extern int pool_value_get_double(const pool_value_t *, double *);
244 extern int pool_value_get_bool(const pool_value_t *, uchar_t *);
245 extern int pool_value_get_string(const pool_value_t *, const char **);
246 extern pool_value_class_t pool_value_get_type(const pool_value_t *);
247 extern void pool_value_set_uint64(pool_value_t *, uint64_t);
248 extern void pool_value_set_int64(pool_value_t *, int64_t);
249 extern void pool_value_set_double(pool_value_t *, double);
250 extern void pool_value_set_bool(pool_value_t *, uchar_t);
251 extern int pool_value_set_string(pool_value_t *, const char *);
252 extern const char *pool_value_get_name(const pool_value_t *);
253 extern int pool_value_set_name(pool_value_t *, const char *);
254 
255 /* Pool Property Value Creation/Destruction */
256 extern pool_value_t *pool_value_alloc(void);
257 extern void pool_value_free(pool_value_t *);
258 
259 /* Default pool data store locations */
260 extern const char *pool_static_location(void);
261 extern const char *pool_dynamic_location(void);
262 
263 /* Binding */
264 extern int pool_set_binding(const char *, idtype_t, id_t);
265 extern char *pool_get_binding(pid_t);
266 extern char *pool_get_resource_binding(const char *, pid_t);
267 
268 /* Walking */
269 extern int pool_walk_pools(pool_conf_t *, void *,
270     int (*)(pool_conf_t *, pool_t *, void *));
271 extern int pool_walk_resources(pool_conf_t *, pool_t *, void *,
272     int (*)(pool_conf_t *, pool_resource_t *, void *));
273 extern int pool_walk_components(pool_conf_t *, pool_resource_t *, void *,
274     int (*)(pool_conf_t *, pool_component_t *, void *));
275 
276 #ifdef	__cplusplus
277 }
278 #endif
279 
280 #endif	/* _POOL_H */
281