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 33 extern "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 */ 90 struct 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 */ 119 typedef struct pool_system 120 { 121 pool_elem_t ps_elem; 122 void *pe_pad1; 123 void *pe_pad2; 124 } pool_system_t; 125 126 struct 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 136 struct 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 146 struct 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 */ 167 typedef 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 */ 198 typedef 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 */ 232 struct 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 */ 241 extern pool_system_t *pool_conf_system(const pool_conf_t *); 242 extern pool_system_t *pool_elem_system(const pool_elem_t *); 243 extern pool_t *pool_elem_pool(const pool_elem_t *); 244 extern pool_resource_t *pool_elem_res(const pool_elem_t *); 245 extern pool_component_t *pool_elem_comp(const pool_elem_t *); 246 247 /* 248 * Convert a pool_system_t to a pool_elem_t. 249 */ 250 extern 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 */ 258 extern pool_elem_t *pool_get_pair(const pool_elem_t *); 259 extern void pool_set_pair(pool_elem_t *, pool_elem_t *); 260 261 /* 262 * Result Set Manipulation 263 */ 264 extern pool_elem_t *pool_rs_next(pool_result_set_t *); 265 extern pool_elem_t *pool_rs_prev(pool_result_set_t *); 266 extern pool_elem_t *pool_rs_first(pool_result_set_t *); 267 extern pool_elem_t *pool_rs_last(pool_result_set_t *); 268 extern int pool_rs_count(pool_result_set_t *); 269 extern int pool_rs_get_index(pool_result_set_t *); 270 extern int pool_rs_set_index(pool_result_set_t *, int); 271 extern int pool_rs_close(pool_result_set_t *); 272 273 /* 274 * General Purpose Query 275 */ 276 extern 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