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