diff options
Diffstat (limited to 'usr/src/lib/libpool/common/pool_internal.h')
| -rw-r--r-- | usr/src/lib/libpool/common/pool_internal.h | 476 |
1 files changed, 476 insertions, 0 deletions
diff --git a/usr/src/lib/libpool/common/pool_internal.h b/usr/src/lib/libpool/common/pool_internal.h new file mode 100644 index 0000000..e172d23 --- /dev/null +++ b/usr/src/lib/libpool/common/pool_internal.h @@ -0,0 +1,476 @@ +/* + * CDDL HEADER START + * + * The contents of this file are subject to the terms of the + * Common Development and Distribution License (the "License"). + * You may not use this file except in compliance with the License. + * + * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE + * or http://www.opensolaris.org/os/licensing. + * See the License for the specific language governing permissions + * and limitations under the License. + * + * When distributing Covered Code, include this CDDL HEADER in each + * file and include the License file at usr/src/OPENSOLARIS.LICENSE. + * If applicable, add the following below this CDDL HEADER, with the + * fields enclosed by brackets "[]" replaced with your own identifying + * information: Portions Copyright [yyyy] [name of copyright owner] + * + * CDDL HEADER END + */ +/* + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + * Use is subject to license terms. + */ + +#ifndef _POOL_INTERNAL_H +#define _POOL_INTERNAL_H + +#pragma ident "%Z%%M% %I% %E% SMI" + +#include <libnvpair.h> +#include <stdarg.h> +#include <sys/pool.h> +#include <sys/pool_impl.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/* + * This file contains the libpool internal definitions which are not + * directly related to the data access abstraction logic. + */ + +/* + * Define the various query specifiers for use in the + * pool_connection_t query function, pc_exec_query. + */ + +#define PEC_QRY_ANY (PEC_QRY_SYSTEM | PEC_QRY_POOL | PEC_QRY_RES | \ + PEC_QRY_COMP) +#define PEC_QRY_SYSTEM (1 << PEC_SYSTEM) +#define PEC_QRY_POOL (1 << PEC_POOL) +#define PEC_QRY_RES (PEC_QRY_RES_COMP | PEC_QRY_RES_AGG) +#define PEC_QRY_RES_COMP (1 << PEC_RES_COMP) +#define PEC_QRY_RES_AGG (1 << PEC_RES_AGG) +#define PEC_QRY_COMP (1 << PEC_COMP) +#define PEC_QRY_ELEM(e) (1 << pool_elem_class(e)) + +/* + * Internal type conversion macros + */ +#define TO_ELEM(s) ((pool_elem_t *)s) +/* + * Get the configuration to which the supplied element belongs. + */ +#define TO_CONF(s) (s->pe_conf) + +/* + * Known Data Store Types + */ + +#define XML_DATA_STORE 0 +#define KERNEL_DATA_STORE 1 + +/* + * Limits on pool values names and strings + */ +#define PV_NAME_MAX_LEN 1024 +#define PV_VALUE_MAX_LEN 1024 + +/* + * CB_TAB_BUF_SIZE represents the maximum number of indents to which a + * char_buf_t is expected to grow. This value would need to be raised + * if it was ever exceeded. It is an arbitrary limit, but currently + * the implementation does not exceed a depth of 4. + */ + +#define CB_TAB_BUF_SIZE 8 +#define CB_DEFAULT_LEN 256 + +/* + * Helpful pset macros + */ +#define PSID_IS_SYSSET(psid) (psid == PS_NONE) +#define POOL_SYSID_BAD (-2) +#define POOL_SYSID_BAD_STRING "-2" + +/* + * Size of generated ref_id buffer + */ + +#define KEY_BUFFER_SIZE 48 + +/* + * Various useful constant strings which are often encountered + */ +extern const char *c_a_dtype; +extern const char *c_name; +extern const char *c_type; +extern const char *c_ref_id; +extern const char *c_max_prop; +extern const char *c_min_prop; +extern const char *c_size_prop; +extern const char *c_sys_prop; + +/* + * The char_buf_t type is a very simple string implementation which + * makes it easier to manipulate complex character data. + */ +typedef struct char_buf +{ + size_t cb_size; + char *cb_buf; + char cb_tab_buf[CB_TAB_BUF_SIZE]; +} char_buf_t; + +/* + * libpool uses an opaque discriminated union type, pool_value_t, to + * contain values which are used to get/set properties on + * configuration components. Each value is strictly typed and the + * functions to manipulate these types are exported through the + * external interface. + */ + +/* + * Initialize a pool_value_t + */ +#define POOL_VALUE_INITIALIZER /* = DEFAULT POOL VALUE */ \ + {POC_INVAL, NULL, NULL } + +struct pool_value { + pool_value_class_t pv_class; /* Value type */ + const char *pv_name; /* Value name */ + union + { + uint64_t u; + int64_t i; + double d; + uchar_t b; + const char *s; + } pv_u; +}; + +/* + * The pool_prop_op_t structure is used to perform property specific validation + * when setting the values of properties in a plugin and when getting a property + * value which is not stored (i.e. it is generated dynamically by the plugin at + * access. + * + * - ppo_get_value will provide a value for the specified property + * - ppo_set_value will allow a provider to validate a value before setting it + */ +typedef struct pool_prop_op { + int (*ppo_get_value)(const pool_elem_t *, pool_value_t *); + int (*ppo_set_value)(pool_elem_t *, const pool_value_t *); +} pool_prop_op_t; + +/* + * The pool_prop_t structure is used to hold all property related information + * for each property that a provider is interested in. + * + * - pp_pname is the name of the property + * - pp_value is the initial value of the property + * - pp_perms is an OR'd bitmap of the access characteristics for the property + * - pp_init is a function which initialises the value member of the property + * - pp_op is optional and supports access and validation of property values + */ +typedef struct pool_prop { + const char *pp_pname; + pool_value_t pp_value; + uint_t pp_perms; + int (*pp_init)(struct pool_prop *); + pool_prop_op_t pp_op; +} pool_prop_t; + +/* + * log state + */ +enum log_state { + LS_DO, + LS_UNDO, + LS_RECOVER, + LS_FAIL +}; + +/* + * Forward declaration + */ +typedef struct log log_t; + +/* + * log item. + * + * Used to describe each operation which needs to be logged. When + * modifications are desired to the kernel, they are logged in the + * configuration log file. If the user commits the changes, then the + * log entries are processed in sequence. If rollback is called, the + * log is dismissed without being processed. If the commit operation + * fails, then the log is "rolled back" to undo the previously + * successful operations. + */ +typedef struct log_item { + log_t *li_log; /* Log containing this item */ + int li_op; /* Type of operation */ + void *li_details; /* Operation details */ + struct log_item *li_next; /* List of log items */ + struct log_item *li_prev; /* List of log items */ + enum log_state li_state; /* Item state */ +} log_item_t; + +/* + * log. + * + * This maintains a list of log items. The sentinel is used to + * simplify processing around the "empty list". The state of the log + * indicates whether transactions are being processed normally, or + * whether recovery is in progress. + */ +struct log +{ + pool_conf_t *l_conf; /* Configuration for this log */ + log_item_t *l_sentinel; /* Log sentinel */ + enum log_state l_state; /* Log state */ +}; + + +/* + * log item action function type + */ +typedef int (*log_item_action_t)(log_item_t *); + +/* + * Get the max/min/size property value of a resource. + */ +extern int resource_get_max(const pool_resource_t *, uint64_t *); +extern int resource_get_min(const pool_resource_t *, uint64_t *); +extern int resource_get_size(const pool_resource_t *, uint64_t *); +extern int resource_get_pinned(const pool_resource_t *, + uint64_t *); + +/* + * Element utility operations. + */ +extern char *elem_get_name(const pool_elem_t *); +extern id_t elem_get_sysid(const pool_elem_t *); +extern int elem_is_default(const pool_elem_t *); +extern boolean_t elem_is_tmp(const pool_elem_t *); +extern const pool_elem_t *get_default_elem(const pool_elem_t *); +extern int qsort_elem_compare(const void *, const void *); + +/* + * Get the class of the supplied element. + */ +extern const char *pool_elem_class_string(const pool_elem_t *); +extern const char *pool_resource_type_string(pool_resource_elem_class_t); +extern const char *pool_component_type_string(pool_component_elem_class_t); + +/* + * Commit the supplied configuration to the system. This function + * attempts to make the system look like the supplied configuration. + */ +extern int pool_conf_commit_sys(pool_conf_t *, int); + +/* + * Allocate an XML/kernel connection to a data representation. + */ +extern int pool_xml_connection_alloc(pool_conf_t *, int); +extern int pool_knl_connection_alloc(pool_conf_t *, int); + +/* + * Create/Destroy a pool component belonging to the supplied resource + */ +extern pool_component_t *pool_component_create(pool_conf_t *, + const pool_resource_t *, int64_t); +extern int pool_component_destroy(pool_component_t *); + +/* + * Get/Set the owner (container) of a particular configuration + * element. + */ +extern pool_elem_t *pool_get_container(const pool_elem_t *); +extern int pool_set_container(pool_elem_t *, pool_elem_t *); + +/* + * These functions are used for debugging. Setting the environment + * variable LIBPOOL_DEBUG to 1, enables these functions. + */ +extern void do_dprintf(const char *, va_list); +extern void dprintf(const char *, ...); + +/* + * libpool maintains it's own error value, rather than further pollute + * errno, this function is used to set the current error value for + * retrieval. + */ +extern void pool_seterror(int); + +/* + * Element Class + */ +extern pool_elem_class_t pool_elem_class(const pool_elem_t *); +extern pool_resource_elem_class_t pool_resource_elem_class(const pool_elem_t *); +extern pool_component_elem_class_t pool_component_elem_class(const + pool_elem_t *); +extern int pool_elem_same_class(const pool_elem_t *, const pool_elem_t *); +extern pool_elem_class_t pool_elem_class_from_string(const char *); +extern pool_resource_elem_class_t pool_resource_elem_class_from_string(const + char *); +extern pool_component_elem_class_t pool_component_elem_class_from_string(const + char *); + +/* + * Element Equivalency + */ +extern int pool_elem_compare(const pool_elem_t *, + const pool_elem_t *); +extern int pool_elem_compare_name(const pool_elem_t *, + const pool_elem_t *); + +/* + * Dynamic character buffers. Limited functionality but enough for our + * purposes. + */ +extern char_buf_t *alloc_char_buf(size_t); +extern void free_char_buf(char_buf_t *); +extern int set_char_buf(char_buf_t *, const char *, ...); +extern int append_char_buf(char_buf_t *, const char *, ...); + +/* + * Internal functions for use with pool values. + */ +extern int pool_value_equal(pool_value_t *, pool_value_t *); +extern int pool_value_from_nvpair(pool_value_t *, nvpair_t *); + +/* + * Check to ensure that the supplied string is a valid name for a pool + * element. + */ +extern int is_valid_name(const char *); + +/* + * Functions related to element prefix manipulation. You can get the + * prefix for a supplied element or find out if a supplied string is a + * valid prefix for a certain class of element. + */ +extern const char *elem_get_prefix(const pool_elem_t *); +extern const char *is_a_known_prefix(pool_elem_class_t, const char *); + +/* + * Internal property manipulators + */ +extern int pool_put_ns_property(pool_elem_t *, const char *, + const pool_value_t *); +extern int pool_put_any_property(pool_elem_t *, const char *, + const pool_value_t *); +extern int pool_put_any_ns_property(pool_elem_t *, const char *, + const pool_value_t *); +extern pool_value_class_t pool_get_ns_property(const pool_elem_t *, + const char *, pool_value_t *); +extern int pool_walk_any_properties(pool_conf_t *, pool_elem_t *, + void *, int (*)(pool_conf_t *, pool_elem_t *, const char *, + pool_value_t *, void *), int); +extern int pool_set_temporary(pool_conf_t *, pool_elem_t *); + +/* + * Namespace aware utility functions. + */ +extern const char *is_ns_property(const pool_elem_t *, const char *); +extern const char *property_name_minus_ns(const pool_elem_t *, + const char *); + +/* + * Initialisation routines. + */ +extern void internal_init(void); + +/* + * Is the supplied configuration the dynamic configuration? + */ +extern int conf_is_dynamic(const pool_conf_t *); + +/* + * Update the library snapshot from the kernel + */ +extern int pool_knl_update(pool_conf_t *, int *); + +/* + * Resource property functions + */ +extern int resource_is_default(const pool_resource_t *); +extern int resource_is_system(const pool_resource_t *); +extern int resource_can_associate(const pool_resource_t *); +extern const pool_resource_t *get_default_resource(const pool_resource_t *); +extern pool_resource_t *resource_by_sysid(const pool_conf_t *, id_t, + const char *); + +/* + * Resource property provider functions + */ +extern uint_t pool_get_provider_count(void); +extern const pool_prop_t *provider_get_props(const pool_elem_t *); +extern const pool_prop_t *provider_get_prop(const pool_elem_t *, + const char *); +extern int prop_is_stored(const pool_prop_t *); +extern int prop_is_readonly(const pool_prop_t *); +extern int prop_is_init(const pool_prop_t *); +extern int prop_is_hidden(const pool_prop_t *); +extern int prop_is_optional(const pool_prop_t *); + +/* + * Component property functions + */ +extern int cpu_is_requested(pool_component_t *); + +/* + * Simple initialisation routines for values used when initialising the + * property arrays for each plugin + * Return PO_SUCCESS/PO_FAIL to indicate success/failure + */ +extern int uint_init(pool_prop_t *, uint64_t); +extern int int_init(pool_prop_t *, int64_t); +extern int double_init(pool_prop_t *, double); +extern int bool_init(pool_prop_t *, uchar_t); +extern int string_init(pool_prop_t *, const char *); + + +/* + * log functions + */ +extern log_t *log_alloc(pool_conf_t *); +extern void log_free(log_t *); +extern void log_empty(log_t *); +extern int log_walk(log_t *, log_item_action_t); +extern int log_reverse_walk(log_t *, log_item_action_t); +extern uint_t log_size(log_t *); +extern int log_append(log_t *, int, void *); + +/* + * log item functions + */ +extern log_item_t *log_item_alloc(log_t *, int, void *); +extern int log_item_free(log_item_t *); + +extern int pool_validate_resource(const pool_conf_t *, + const char *, const char *, int64_t); + +/* + * String atom functions + */ +extern const char *atom_string(const char *); +extern void atom_free(const char *); +/* + * debugging functions + */ +#ifdef DEBUG +extern void log_item_dprintf(log_item_t *); +extern void pool_value_dprintf(const pool_value_t *); +extern void pool_elem_dprintf(const pool_elem_t *); +#endif + +#ifdef __cplusplus +} +#endif + +#endif /* _POOL_INTERNAL_H */ |