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