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