usr/src/lib/libpool/common/pool_internal.h

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