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 2003 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 
27 #ifndef	_POOL_IMPL_H
28 #define	_POOL_IMPL_H
29 
30 #ifdef	__cplusplus
31 extern "C" {
32 #endif
33 
34 /*
35  * This file contains the definitions of types and supporting
36  * functions to implement the libpool generic data manipulation
37  * facility.
38  *
39  * libpool is designed so that the data representation/storage method
40  * used may be easily replaced without affecting core functionality.
41  * A libpool configuration is connected to a particular data
42  * representation/storage "driver" via the pool_connection_t
43  * type. When a configuration is opened (see pool_conf_open) the
44  * libpool implementation allocates a specific data manipulation type
45  * and initialises it. For instance, see pool_xml_connection_alloc.
46  *
47  * This function represents a cross-over point and all routines used
48  * for data representation/storage are controlled by the type of
49  * allocated connection.
50  *
51  * Currently, there are two implemented methods of access. Data may be
52  * retrieved from the kernel, using the pool_knl_connection_t
53  * function. This implementation relies on a private interface
54  * provided by a driver, /dev/pool, and presents data retrieved from
55  * the kernel via the standard libpool interface. Alternatively, data
56  * may be retrieved from an XML file, via pool_xml_connection_t, and
57  * presented through the standard libpool interface. For details of
58  * these two implementations, see pool_kernel_impl.h and
59  * pool_xml_impl.h.
60  *
61  * In addition to defining a specific connection type for a desired
62  * data representation/storage medium, several other structures must
63  * be defined to allow manipulation of configuration elements.
64  *
65  * Configuration elements are represented as pool_elem_t instances, or
66  * as sub-types of this generic type (such as pool_t, which represents
67  * a pool element) with groups (or sets) of these instances available
68  * for manipulation via the pool_result_set_t type.
69  *
70  * For more information on the implementation of these types, read the
71  * detailed comments above each structure definition.
72  */
73 
74 /*
75  * The pool_elem_t is used to represent a configuration element.The
76  * class of the element is stored within the structure along with a
77  * pointer to the containing configuration and a pointer to the
78  * element's specific subtype.
79  *
80  * The function pointers are initialised when the element is allocated
81  * to use the specific functions provided by the concrete data
82  * representation.
83  *
84  * The full set of operations that can be performed on an element
85  * which require special treatment from the data
86  * representation/storage medium are defined.
87  */
88 struct pool_elem {
89 	pool_conf_t *pe_conf;				/* Configuration */
90 	pool_elem_class_t pe_class;			/* Element class */
91 	pool_resource_elem_class_t pe_resource_class;	/* Resource class */
92 	pool_component_elem_class_t pe_component_class;	/* Component class */
93 	struct pool_elem *pe_pair;			/* Static pair */
94 	pool_value_class_t (*pe_get_prop)(const pool_elem_t *, const char *,
95 	    pool_value_t *);
96 	int (*pe_put_prop)(pool_elem_t *, const char *, const pool_value_t *);
97 	int (*pe_rm_prop)(pool_elem_t *, const char *);
98 	pool_value_t **(*pe_get_props)(const pool_elem_t *, uint_t *);
99 	int (*pe_remove)(pool_elem_t *);
100 	pool_elem_t *(*pe_get_container)(const pool_elem_t *);
101 	int (*pe_set_container)(pool_elem_t *, pool_elem_t *);
102 };
103 
104 /*
105  * libpool performs many operations against a pool_elem_t. This basic
106  * type is extended to provide specific functionality and type safety
107  * for each of the different types of element supported by
108  * libpool. There are four types of element:
109  * - pool_system_t, represents an entire configuration
110  * - pool_t, represents a single pool
111  * - pool_resource_t, represents a single resource
112  * - pool_component_t, represents a single resource component
113  *
114  * pool_system_t is an internal structure, the other structures are
115  * externally visible and form a major part of the libpool interface.
116  */
117 typedef struct pool_system
118 {
119 	pool_elem_t ps_elem;
120 	void *pe_pad1;
121 	void *pe_pad2;
122 } pool_system_t;
123 
124 struct pool
125 {
126 	pool_elem_t pp_elem;
127 	/*
128 	 * Specific to pool_t
129 	 */
130 	int (*pp_associate)(pool_t *, const pool_resource_t *);
131 	int (*pp_dissociate)(pool_t *, const pool_resource_t *);
132 };
133 
134 struct pool_resource
135 {
136 	pool_elem_t pr_elem;
137 	/*
138 	 * Specific to pool_resource_t
139 	 */
140 	int (*pr_is_system)(const pool_resource_t *);
141 	int (*pr_can_associate)(const pool_resource_t *);
142 };
143 
144 struct pool_component
145 {
146 	pool_elem_t pc_elem;
147 	void *pe_pad1;
148 	void *pe_pad2;
149 };
150 
151 /*
152  * The pool_result_set_t is used to represent a collection (set) of
153  * configuration elements. The configuration to which this result set
154  * applies is stored along with an indicator as to whether the result
155  * set is still in use.
156  *
157  * The function pointers are initialised when the element is allocated
158  * to use the specific functions provided by the concrete data
159  * representation.
160  *
161  * The full set of operations that can be performed on an element
162  * which require special treatment from the data
163  * representation/storage medium are defined.
164  */
165 typedef struct pool_result_set {
166 	pool_conf_t *prs_conf;				/* Configuration */
167 	int prs_active;					/* Query active? */
168 	int prs_index;					/* Result Index */
169 	pool_elem_t *(*prs_next)(struct pool_result_set *);
170 	pool_elem_t *(*prs_prev)(struct pool_result_set *);
171 	pool_elem_t *(*prs_first)(struct pool_result_set *);
172 	pool_elem_t *(*prs_last)(struct pool_result_set *);
173 	int (*prs_set_index)(struct pool_result_set *, int);
174 	int (*prs_get_index)(struct pool_result_set *);
175 	int (*prs_close)(struct pool_result_set *);
176 	int (*prs_count)(struct pool_result_set *);
177 } pool_result_set_t;
178 
179 /*
180  * The pool_connection_t is used to represent a connection between a
181  * libpool configuration and a particular implementation of the
182  * libpool interface in a specific data representation/storage medium,
183  * e.g. XML.
184  *
185  * The name of the storage medium is stored along with the type of the
186  * data store.
187  *
188  * The function pointers are initialised when the element is allocated
189  * to use the specific functions provided by the concrete data
190  * representation.
191  *
192  * The full set of operations that can be performed on an element
193  * which require special treatment from the data
194  * representation/storage medium are defined.
195  */
196 typedef struct pool_connection {
197 	const char *pc_name;				/* Provider name */
198 	int pc_store_type;				/* Datastore type */
199 	int pc_oflags;					/* Open flags */
200 	int (*pc_close)(pool_conf_t *);
201 	int (*pc_validate)(const pool_conf_t *, pool_valid_level_t);
202 	int (*pc_commit)(pool_conf_t *);
203 	int (*pc_export)(const pool_conf_t *, const char *,
204 	    pool_export_format_t);
205 	int (*pc_rollback)(pool_conf_t *);
206 	pool_result_set_t *(*pc_exec_query)(const pool_conf_t *,
207 	    const pool_elem_t *, const char *, pool_elem_class_t,
208 	    pool_value_t **);
209 	pool_elem_t *(*pc_elem_create)(pool_conf_t *, pool_elem_class_t,
210 	    pool_resource_elem_class_t, pool_component_elem_class_t);
211 	int (*pc_remove)(pool_conf_t *);
212 	int (*pc_res_xfer)(pool_resource_t *, pool_resource_t *, uint64_t);
213 	int (*pc_res_xxfer)(pool_resource_t *, pool_resource_t *,
214 	    pool_component_t **);
215 	char *(*pc_get_binding)(pool_conf_t *, pid_t);
216 	int (*pc_set_binding)(pool_conf_t *, const char *, idtype_t, id_t);
217 	char *(*pc_get_resource_binding)(pool_conf_t *,
218 	    pool_resource_elem_class_t, pid_t);
219 } pool_connection_t;
220 
221 /*
222  * pool_conf represents a resource management configuration. The
223  * configuration location is stored in the pc_location member with the
224  * state of the configuration stored in pc_state.
225  *
226  * The pc_prov member provides data representation/storage abstraction
227  * for the configuration since all access to data is performed through
228  * this member.
229  */
230 struct pool_conf {
231 	const char *pc_location;			/* Location */
232 	pool_connection_t *pc_prov;			/* Data Provider */
233 	pool_conf_state_t pc_state;			/* State */
234 };
235 
236 /*
237  * Convert a pool_elem_t to it's appropriate sub-type.
238  */
239 extern pool_system_t	*pool_conf_system(const pool_conf_t *);
240 extern pool_system_t	*pool_elem_system(const pool_elem_t *);
241 extern pool_t		*pool_elem_pool(const pool_elem_t *);
242 extern pool_resource_t	*pool_elem_res(const pool_elem_t *);
243 extern pool_component_t	*pool_elem_comp(const pool_elem_t *);
244 
245 /*
246  * Convert a pool_system_t to a pool_elem_t.
247  */
248 extern pool_elem_t	*pool_system_elem(const pool_system_t *);
249 
250 /*
251  * Get/Set an element's "pair" element. A pair element is a temporary
252  * association at commit between an element in the dynamic
253  * configuration and an element in the static configuration. This
254  * relationship is stored in the pe_pair member of the element.
255  */
256 extern pool_elem_t	*pool_get_pair(const pool_elem_t *);
257 extern void		pool_set_pair(pool_elem_t *, pool_elem_t *);
258 
259 /*
260  * Result Set Manipulation
261  */
262 extern pool_elem_t	*pool_rs_next(pool_result_set_t *);
263 extern pool_elem_t	*pool_rs_prev(pool_result_set_t *);
264 extern pool_elem_t	*pool_rs_first(pool_result_set_t *);
265 extern pool_elem_t	*pool_rs_last(pool_result_set_t *);
266 extern int		pool_rs_count(pool_result_set_t *);
267 extern int		pool_rs_get_index(pool_result_set_t *);
268 extern int		pool_rs_set_index(pool_result_set_t *, int);
269 extern int		pool_rs_close(pool_result_set_t *);
270 
271 /*
272  * General Purpose Query
273  */
274 extern pool_result_set_t *pool_exec_query(const pool_conf_t *,
275     const pool_elem_t *, const char *, pool_elem_class_t, pool_value_t **);
276 
277 #ifdef	__cplusplus
278 }
279 #endif
280 
281 #endif	/* _POOL_IMPL_H */
282