xref: /illumos-gate/usr/src/lib/libpool/common/pool_internal.h (revision 29d9204108fb7f70b8c101eae01e62aba6e0b901)
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 #ifndef	_POOL_INTERNAL_H
27 #define	_POOL_INTERNAL_H
28 
29 #include <libnvpair.h>
30 #include <stdarg.h>
31 #include <sys/pool.h>
32 #include <sys/pool_impl.h>
33 
34 #ifdef	__cplusplus
35 extern "C" {
36 #endif
37 
38 /*
39  * This file contains the libpool internal definitions which are not
40  * directly related to the data access abstraction logic.
41  */
42 
43 /*
44  * Define the various query specifiers for use in the
45  * pool_connection_t query function, pc_exec_query.
46  */
47 
48 #define	PEC_QRY_ANY		(PEC_QRY_SYSTEM | PEC_QRY_POOL | PEC_QRY_RES | \
49 				    PEC_QRY_COMP)
50 #define	PEC_QRY_SYSTEM		(1 << PEC_SYSTEM)
51 #define	PEC_QRY_POOL		(1 << PEC_POOL)
52 #define	PEC_QRY_RES		(PEC_QRY_RES_COMP | PEC_QRY_RES_AGG)
53 #define	PEC_QRY_RES_COMP	(1 << PEC_RES_COMP)
54 #define	PEC_QRY_RES_AGG		(1 << PEC_RES_AGG)
55 #define	PEC_QRY_COMP		(1 << PEC_COMP)
56 #define	PEC_QRY_ELEM(e)		(1 << pool_elem_class(e))
57 
58 /*
59  * Internal type conversion macros
60  */
61 #define	TO_ELEM(s)		((pool_elem_t *)s)
62 /*
63  * Get the configuration to which the supplied element belongs.
64  */
65 #define	TO_CONF(s)		(s->pe_conf)
66 
67 /*
68  * Known Data Store Types
69  */
70 
71 #define	XML_DATA_STORE	0
72 #define	KERNEL_DATA_STORE	1
73 
74 /*
75  * Limits on pool values names and strings
76  */
77 #define	PV_NAME_MAX_LEN		1024
78 #define	PV_VALUE_MAX_LEN	1024
79 
80 /*
81  * CB_TAB_BUF_SIZE represents the maximum number of indents to which a
82  * char_buf_t is expected to grow. This value would need to be raised
83  * if it was ever exceeded. It is an arbitrary limit, but currently
84  * the implementation does not exceed a depth of 4.
85  */
86 
87 #define	CB_TAB_BUF_SIZE	8
88 #define	CB_DEFAULT_LEN	256
89 
90 /*
91  * Helpful pset macros
92  */
93 #define	PSID_IS_SYSSET(psid)	(psid == PS_NONE)
94 #define	POOL_SYSID_BAD		(-2)
95 #define	POOL_SYSID_BAD_STRING	"-2"
96 
97 /*
98  * Size of generated ref_id buffer
99  */
100 
101 #define	KEY_BUFFER_SIZE	48
102 
103 /*
104  * Various useful constant strings which are often encountered
105  */
106 extern const char *c_a_dtype;
107 extern const char *c_name;
108 extern const char *c_type;
109 extern const char *c_ref_id;
110 extern const char *c_max_prop;
111 extern const char *c_min_prop;
112 extern const char *c_size_prop;
113 extern const char *c_sys_prop;
114 
115 /*
116  * The char_buf_t type is a very simple string implementation which
117  * makes it easier to manipulate complex character data.
118  */
119 typedef struct char_buf
120 {
121 	size_t cb_size;
122 	char *cb_buf;
123 	char cb_tab_buf[CB_TAB_BUF_SIZE];
124 } char_buf_t;
125 
126 /*
127  * libpool uses an opaque discriminated union type, pool_value_t, to
128  * contain values which are used to get/set properties on
129  * configuration components. Each value is strictly typed and the
130  * functions to manipulate these types are exported through the
131  * external interface.
132  */
133 
134 /*
135  * Initialize a pool_value_t
136  */
137 #define	POOL_VALUE_INITIALIZER	/* = DEFAULT POOL VALUE */	\
138 	{POC_INVAL, NULL, 0 }
139 
140 struct pool_value {
141 	pool_value_class_t	pv_class;		/* Value type */
142 	const char		*pv_name;		/* Value name */
143 	union
144 	{
145 		uint64_t	u;
146 		int64_t		i;
147 		double		d;
148 		uchar_t		b;
149 		const char	*s;
150 	} pv_u;
151 };
152 
153 /*
154  * The pool_prop_op_t structure is used to perform property specific validation
155  * when setting the values of properties in a plugin and when getting a property
156  * value which is not stored (i.e. it is generated dynamically by the plugin at
157  * access.
158  *
159  * - ppo_get_value will provide a value for the specified property
160  * - ppo_set_value will allow a provider to validate a value before setting it
161  */
162 typedef struct pool_prop_op {
163 	int	(*ppo_get_value)(const pool_elem_t *, pool_value_t *);
164 	int	(*ppo_set_value)(pool_elem_t *, const pool_value_t *);
165 } pool_prop_op_t;
166 
167 /*
168  * The pool_prop_t structure is used to hold all property related information
169  * for each property that a provider is interested in.
170  *
171  * - pp_pname is the name of the property
172  * - pp_value is the initial value of the property
173  * - pp_perms is an OR'd bitmap of the access characteristics for the property
174  * - pp_init is a function which initialises the value member of the property
175  * - pp_op is optional and supports access and validation of property values
176  */
177 typedef struct pool_prop {
178 	const char	*pp_pname;
179 	pool_value_t	pp_value;
180 	uint_t		pp_perms;
181 	int		(*pp_init)(struct pool_prop *);
182 	pool_prop_op_t	pp_op;
183 } pool_prop_t;
184 
185 /*
186  * log state
187  */
188 enum log_state {
189 	LS_DO,
190 	LS_UNDO,
191 	LS_RECOVER,
192 	LS_FAIL
193 };
194 
195 /*
196  * Forward declaration
197  */
198 typedef struct log log_t;
199 
200 /*
201  * log item.
202  *
203  * Used to describe each operation which needs to be logged. When
204  * modifications are desired to the kernel, they are logged in the
205  * configuration log file. If the user commits the changes, then the
206  * log entries are processed in sequence. If rollback is called, the
207  * log is dismissed without being processed. If the commit operation
208  * fails, then the log is "rolled back" to undo the previously
209  * successful operations.
210  */
211 typedef struct log_item {
212 	log_t *li_log;				/* Log containing this item */
213 	int li_op;				/* Type of operation */
214 	void *li_details;			/* Operation details */
215 	struct log_item *li_next;		/* List of log items */
216 	struct log_item *li_prev;		/* List of log items */
217 	enum log_state li_state;		/* Item state */
218 } log_item_t;
219 
220 /*
221  * log.
222  *
223  * This maintains a list of log items. The sentinel is used to
224  * simplify processing around the "empty list". The state of the log
225  * indicates whether transactions are being processed normally, or
226  * whether recovery is in progress.
227  */
228 struct log
229 {
230 	pool_conf_t *l_conf;			/* Configuration for this log */
231 	log_item_t *l_sentinel;			/* Log sentinel */
232 	enum log_state l_state;			/* Log state */
233 };
234 
235 
236 /*
237  * log item action function type
238  */
239 typedef int (*log_item_action_t)(log_item_t *);
240 
241 /*
242  * Get the max/min/size property value of a resource.
243  */
244 extern int		resource_get_max(const pool_resource_t *, uint64_t *);
245 extern int		resource_get_min(const pool_resource_t *, uint64_t *);
246 extern int		resource_get_size(const pool_resource_t *, uint64_t *);
247 extern int		resource_get_pinned(const pool_resource_t *,
248 			    uint64_t *);
249 
250 /*
251  * Element utility operations.
252  */
253 extern char		*elem_get_name(const pool_elem_t *);
254 extern id_t		elem_get_sysid(const pool_elem_t *);
255 extern int		elem_is_default(const pool_elem_t *);
256 extern boolean_t	elem_is_tmp(const pool_elem_t *);
257 extern const pool_elem_t *get_default_elem(const pool_elem_t *);
258 extern int		qsort_elem_compare(const void *, const void *);
259 
260 /*
261  * Get the class of the supplied element.
262  */
263 extern const char	*pool_elem_class_string(const pool_elem_t *);
264 extern const char	*pool_resource_type_string(pool_resource_elem_class_t);
265 extern const char *pool_component_type_string(pool_component_elem_class_t);
266 
267 /*
268  * Commit the supplied configuration to the system. This function
269  * attempts to make the system look like the supplied configuration.
270  */
271 extern int		pool_conf_commit_sys(pool_conf_t *, int);
272 
273 /*
274  * Allocate an XML/kernel connection to a data representation.
275  */
276 extern int		pool_xml_connection_alloc(pool_conf_t *, int);
277 extern int		pool_knl_connection_alloc(pool_conf_t *, int);
278 
279 /*
280  * Create/Destroy a pool component belonging to the supplied resource
281  */
282 extern pool_component_t *pool_component_create(pool_conf_t *,
283     const pool_resource_t *, int64_t);
284 extern int		pool_component_destroy(pool_component_t *);
285 
286 /*
287  * Get/Set the owner (container) of a particular configuration
288  * element.
289  */
290 extern pool_elem_t	*pool_get_container(const pool_elem_t *);
291 extern int		pool_set_container(pool_elem_t *, pool_elem_t *);
292 
293 /*
294  * These functions are used for debugging. Setting the environment
295  * variable LIBPOOL_DEBUG to 1, enables these functions.
296  */
297 extern void		do_dprintf(const char *, va_list);
298 extern void		dprintf(const char *, ...);
299 
300 /*
301  * libpool maintains it's own error value, rather than further pollute
302  * errno, this function is used to set the current error value for
303  * retrieval.
304  */
305 extern void		pool_seterror(int);
306 
307 /*
308  * Element Class
309  */
310 extern pool_elem_class_t pool_elem_class(const pool_elem_t *);
311 extern pool_resource_elem_class_t pool_resource_elem_class(const pool_elem_t *);
312 extern pool_component_elem_class_t pool_component_elem_class(const
313     pool_elem_t *);
314 extern int pool_elem_same_class(const pool_elem_t *, const pool_elem_t *);
315 extern pool_elem_class_t pool_elem_class_from_string(const char *);
316 extern pool_resource_elem_class_t pool_resource_elem_class_from_string(const
317     char *);
318 extern pool_component_elem_class_t pool_component_elem_class_from_string(const
319     char *);
320 
321 /*
322  * Element Equivalency
323  */
324 extern int		pool_elem_compare(const pool_elem_t *,
325     const pool_elem_t *);
326 extern int		pool_elem_compare_name(const pool_elem_t *,
327     const pool_elem_t *);
328 
329 /*
330  * Dynamic character buffers. Limited functionality but enough for our
331  * purposes.
332  */
333 extern char_buf_t	*alloc_char_buf(size_t);
334 extern void		free_char_buf(char_buf_t *);
335 extern int		set_char_buf(char_buf_t *, const char *, ...);
336 extern int		append_char_buf(char_buf_t *, const char *, ...);
337 
338 /*
339  * Internal functions for use with pool values.
340  */
341 extern int		pool_value_equal(pool_value_t *, pool_value_t *);
342 extern int		pool_value_from_nvpair(pool_value_t *, nvpair_t *);
343 
344 /*
345  * Check to ensure that the supplied string is a valid name for a pool
346  * element.
347  */
348 extern int		is_valid_name(const char *);
349 
350 /*
351  * Functions related to element prefix manipulation. You can get the
352  * prefix for a supplied element or find out if a supplied string is a
353  * valid prefix for a certain class of element.
354  */
355 extern const char	*elem_get_prefix(const pool_elem_t *);
356 extern const char	*is_a_known_prefix(pool_elem_class_t, const char *);
357 
358 /*
359  * Internal property manipulators
360  */
361 extern int		pool_put_ns_property(pool_elem_t *, const char *,
362     const pool_value_t *);
363 extern int		pool_put_any_property(pool_elem_t *, const char *,
364     const pool_value_t *);
365 extern int		pool_put_any_ns_property(pool_elem_t *, const char *,
366     const pool_value_t *);
367 extern pool_value_class_t pool_get_ns_property(const pool_elem_t *,
368     const char *, pool_value_t *);
369 extern int		pool_walk_any_properties(pool_conf_t *, pool_elem_t *,
370     void *, int (*)(pool_conf_t *, pool_elem_t *, const char *,
371     pool_value_t *, void *), int);
372 extern int		pool_set_temporary(pool_conf_t *, pool_elem_t *);
373 
374 /*
375  * Namespace aware utility functions.
376  */
377 extern const char	*is_ns_property(const pool_elem_t *, const char *);
378 extern const char	*property_name_minus_ns(const pool_elem_t *,
379     const char *);
380 
381 /*
382  * Initialisation routines.
383  */
384 extern void		internal_init(void);
385 
386 /*
387  * Is the supplied configuration the dynamic configuration?
388  */
389 extern int		conf_is_dynamic(const pool_conf_t *);
390 
391 /*
392  * Update the library snapshot from the kernel
393  */
394 extern int		pool_knl_update(pool_conf_t *, int *);
395 
396 /*
397  * Resource property functions
398  */
399 extern int		resource_is_default(const pool_resource_t *);
400 extern int		resource_is_system(const pool_resource_t *);
401 extern int		resource_can_associate(const pool_resource_t *);
402 extern const pool_resource_t	*get_default_resource(const pool_resource_t *);
403 extern pool_resource_t	*resource_by_sysid(const pool_conf_t *, id_t,
404     const char *);
405 
406 /*
407  * Resource property provider functions
408  */
409 extern uint_t		pool_get_provider_count(void);
410 extern const pool_prop_t *provider_get_props(const pool_elem_t *);
411 extern const pool_prop_t *provider_get_prop(const pool_elem_t *,
412     const char *);
413 extern int		prop_is_stored(const pool_prop_t *);
414 extern int		prop_is_readonly(const pool_prop_t *);
415 extern int		prop_is_init(const pool_prop_t *);
416 extern int		prop_is_hidden(const pool_prop_t *);
417 extern int		prop_is_optional(const pool_prop_t *);
418 
419 /*
420  * Component property functions
421  */
422 extern int		cpu_is_requested(pool_component_t *);
423 
424 /*
425  * Simple initialisation routines for values used when initialising the
426  * property arrays for each plugin
427  * Return PO_SUCCESS/PO_FAIL to indicate success/failure
428  */
429 extern int		uint_init(pool_prop_t *, uint64_t);
430 extern int		int_init(pool_prop_t *, int64_t);
431 extern int		double_init(pool_prop_t *, double);
432 extern int		bool_init(pool_prop_t *, uchar_t);
433 extern int		string_init(pool_prop_t *, const char *);
434 
435 
436 /*
437  * log functions
438  */
439 extern log_t		*log_alloc(pool_conf_t *);
440 extern void		log_free(log_t *);
441 extern void		log_empty(log_t *);
442 extern int		log_walk(log_t *, log_item_action_t);
443 extern int		log_reverse_walk(log_t *, log_item_action_t);
444 extern uint_t		log_size(log_t *);
445 extern int		log_append(log_t *, int, void *);
446 
447 /*
448  * log item functions
449  */
450 extern log_item_t	*log_item_alloc(log_t *, int, void *);
451 extern int		log_item_free(log_item_t *);
452 
453 extern int		pool_validate_resource(const pool_conf_t *,
454     const char *, const char *, int64_t);
455 
456 /*
457  * String atom functions
458  */
459 extern const char	*atom_string(const char *);
460 extern void		atom_free(const char *);
461 /*
462  * debugging functions
463  */
464 #ifdef DEBUG
465 extern void		log_item_dprintf(log_item_t *);
466 extern void		pool_value_dprintf(const pool_value_t *);
467 extern void		pool_elem_dprintf(const pool_elem_t *);
468 #endif
469 
470 #ifdef	__cplusplus
471 }
472 #endif
473 
474 #endif	/* _POOL_INTERNAL_H */
475