libpool/common/pool.h

	pool.h revision 0209230bf1261579beab4f55226bb509e6b850cb
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys/*
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * CDDL HEADER START
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys *
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * The contents of this file are subject to the terms of the
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * Common Development and Distribution License (the "License").
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * You may not use this file except in compliance with the License.
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys *
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * or http://www.opensolaris.org/os/licensing.
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * See the License for the specific language governing permissions
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * and limitations under the License.
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys *
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * When distributing Covered Code, include this CDDL HEADER in each
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * If applicable, add the following below this CDDL HEADER, with the
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * fields enclosed by brackets "[]" replaced with your own identifying
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * information: Portions Copyright [yyyy] [name of copyright owner]
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys *
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * CDDL HEADER END
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys/*
30a5e8fa1253cb33980ee4514743cf683f584b4ewyllys * Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * Use is subject to license terms.
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys/*
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys *  NOTE
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys *
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys *  The following contents of this file are private to the
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys *  implementation of the Solaris system and are subject to change at
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys *  any time without notice.  Applications using these interfaces may
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys *  fail to run on future releases.
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#ifndef _POOL_H
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define _POOL_H
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#pragma ident   "%Z%%M% %I% %E% SMI"
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#include <sys/procset.h>
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#include <sys/types.h>
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#include <sys/pool.h>
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#ifdef  __cplusplus
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllysextern "C" {
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#endif
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys/*
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * Library versioning support (c.f. elf_version(3e)).
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys *
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * You can enquire about the version number of the library
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * by passing POOL_VER_NONE.  POOL_VER_CURRENT is the current
30a5e8fa1253cb33980ee4514743cf683f584b4ewyllys * (most capable) version.
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys *
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * You can set the version used by the library by passing the
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * required version number.  If this is not possible, the version
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * returned will be POOL_VER_NONE.
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POOL_VER_CURRENT    1
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POOL_VER_NONE       0
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllysextern uint_t pool_version(uint_t ver);
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#ifndef PO_TRUE
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define PO_TRUE 1
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#endif
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#ifndef PO_FALSE
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define PO_FALSE    0
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#endif
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#ifndef PO_SUCCESS
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define PO_SUCCESS  0
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#endif
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#ifndef PO_FAIL
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define PO_FAIL -1
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#endif
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys/* Error codes */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POE_OK          0
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POE_BAD_PROP_TYPE   1
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POE_INVALID_CONF    2
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POE_NOTSUP      3
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POE_INVALID_SEARCH      4
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POE_BADPARAM        5
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POE_PUTPROP         6
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POE_DATASTORE       7
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POE_SYSTEM      8
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POE_ACCESS      9
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys/* Open Flags */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define PO_RDONLY       0x0
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define PO_RDWR         0x1
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define PO_CREAT        0x2
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define PO_DISCO        0x4
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define PO_UPDATE       0x8
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define PO_TEMP         0x10
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys/* Allocation policy */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POA_IMPORTANCE      "importance based"
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POA_SURPLUS_TO_DEFAULT  "surplus to default"
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys/* Pools updates */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POU_SYSTEM      0x1
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POU_POOL        0x2
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POU_PSET        0x4
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys#define POU_CPU         0x8
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys/* Data Export Formats */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllystypedef enum pool_export_format {
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys    POX_NATIVE,     /* Native data representation format */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys    POX_TEXT        /* Text */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys} pool_export_format_t;
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys/* Property data types */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllystypedef enum pool_value_class {
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys    POC_INVAL = -1,
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys    POC_UINT,
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys    POC_INT,
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys    POC_DOUBLE,
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys    POC_BOOL,
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys    POC_STRING
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys} pool_value_class_t;
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys/* Validation levels */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllystypedef enum pool_valid_level {
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys    POV_NONE = 0,       /* No validation */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys    POV_LOOSE,      /* Loose validation */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys    POV_STRICT,     /* Strict validation */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys    POV_RUNTIME     /* Validate instantiation on current machine */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys} pool_valid_level_t;
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys/* conf states */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllystypedef enum pool_conf_state {
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys    POF_INVALID = -1,
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys    POF_VALID,
30a5e8fa1253cb33980ee4514743cf683f584b4ewyllys    POF_DESTROY
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys} pool_conf_state_t;
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys/* Element data values */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllystypedef struct pool_value pool_value_t;
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
30a5e8fa1253cb33980ee4514743cf683f584b4ewyllys/* Elements */
30a5e8fa1253cb33980ee4514743cf683f584b4ewyllystypedef struct pool_elem pool_elem_t;
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllystypedef struct pool pool_t;
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllystypedef struct pool_resource pool_resource_t;
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllystypedef struct pool_component pool_component_t;
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys/*
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys * Resource management configuration
30a5e8fa1253cb33980ee4514743cf683f584b4ewyllys */
30a5e8fa1253cb33980ee4514743cf683f584b4ewyllystypedef struct pool_conf pool_conf_t;
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllysextern int      pool_error(void);
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllysextern const char   *pool_strerror(int);
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllysextern int      pool_resource_type_list(const char **, uint_t *);
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllysextern int      pool_get_status(int *);
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllysextern int      pool_set_status(int);
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys/* Configuration manipulation */
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllysextern pool_conf_t *pool_conf_alloc(void);
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllysextern void pool_conf_free(pool_conf_t *);
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllysextern pool_conf_state_t pool_conf_status(const pool_conf_t *);
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllys
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllysextern int pool_conf_close(pool_conf_t *);
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllysextern int pool_conf_remove(pool_conf_t *);
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllysextern int pool_conf_open(pool_conf_t *, const char *, int);
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllysextern int pool_conf_rollback(pool_conf_t *);
99ebb4ca412cb0a19d77a3899a87c055b9c30fa8wyllysextern int pool_conf_commit(pool_conf_t *, int);
extern int pool_conf_export(const pool_conf_t *, const char *,
    pool_export_format_t);
extern int pool_conf_validate(const pool_conf_t *, pool_valid_level_t);
extern int pool_conf_update(const pool_conf_t *, int *);
extern pool_t *pool_get_pool(const pool_conf_t *, const char *);
extern pool_t **pool_query_pools(const pool_conf_t *, uint_t *,
    pool_value_t **);
extern pool_resource_t *pool_get_resource(const pool_conf_t *, const char *,
    const char *);
extern pool_resource_t **pool_query_resources(const pool_conf_t *, uint_t *,
    pool_value_t **);
extern pool_component_t **pool_query_components(const pool_conf_t *, uint_t *,
    pool_value_t **);
extern const char *pool_conf_location(const pool_conf_t *);
extern char *pool_conf_info(const pool_conf_t *, int);

/* Resource manipulation */
extern pool_resource_t *pool_resource_create(pool_conf_t *, const char *,
    const char *);
extern int pool_resource_destroy(pool_conf_t *, pool_resource_t *);
extern int pool_resource_transfer(pool_conf_t *, pool_resource_t *,
    pool_resource_t *, uint64_t);
extern int pool_resource_xtransfer(pool_conf_t *, pool_resource_t *,
    pool_resource_t *, pool_component_t **);
extern pool_component_t **pool_query_resource_components(const pool_conf_t *,
    const pool_resource_t *, uint_t *, pool_value_t **);
extern char *pool_resource_info(const pool_conf_t *, const pool_resource_t *,
    int);

/* Pool manipulation */
extern pool_t *pool_create(pool_conf_t *, const char *);
extern int pool_destroy(pool_conf_t *, pool_t *);
extern int pool_associate(pool_conf_t *, pool_t *, const pool_resource_t *);
extern int pool_dissociate(pool_conf_t *, pool_t *, const pool_resource_t *);
extern char *pool_info(const pool_conf_t *, const pool_t *, int);
extern pool_resource_t **pool_query_pool_resources(const pool_conf_t *,
    const pool_t *, uint_t *, pool_value_t **);

/* Resource Component Manipulation */
extern pool_resource_t *pool_get_owning_resource(const pool_conf_t *,
    const pool_component_t *);
extern char *pool_component_info(const pool_conf_t *, const pool_component_t *,
    int);

/* Property manipulation */
extern pool_value_class_t pool_get_property(const pool_conf_t *,
    const pool_elem_t *, const char *, pool_value_t *);
extern int pool_put_property(pool_conf_t *, pool_elem_t *, const char *,
    const pool_value_t *);
extern int pool_rm_property(pool_conf_t *, pool_elem_t *, const char *);

/*
 * Walk the associated properties of the supplied element calling the supplied
 * function for each property in turn. There is no implied order in the walk.
 * The arg parameter allows caller-specific data to be passed to the call.
 */
extern int pool_walk_properties(pool_conf_t *, pool_elem_t *, void *,
    int (*)(pool_conf_t *, pool_elem_t *, const char *, pool_value_t *,
        void *));

/* Get the underlying element */
extern pool_elem_t *pool_conf_to_elem(const pool_conf_t *);
extern pool_elem_t *pool_to_elem(const pool_conf_t *, const pool_t *);
extern pool_elem_t *pool_resource_to_elem(const pool_conf_t *,
    const pool_resource_t *);
extern pool_elem_t *pool_component_to_elem(const pool_conf_t *,
    const pool_component_t *);

/* Pool Property Value Manipulation */
/* Get/Set Pool Property Values and Type */
extern int pool_value_get_uint64(const pool_value_t *, uint64_t *);
extern int pool_value_get_int64(const pool_value_t *, int64_t *);
extern int pool_value_get_double(const pool_value_t *, double *);
extern int pool_value_get_bool(const pool_value_t *, uchar_t *);
extern int pool_value_get_string(const pool_value_t *, const char **);
extern pool_value_class_t pool_value_get_type(const pool_value_t *);
extern void pool_value_set_uint64(pool_value_t *, uint64_t);
extern void pool_value_set_int64(pool_value_t *, int64_t);
extern void pool_value_set_double(pool_value_t *, double);
extern void pool_value_set_bool(pool_value_t *, uchar_t);
extern int pool_value_set_string(pool_value_t *, const char *);
extern const char *pool_value_get_name(const pool_value_t *);
extern int pool_value_set_name(pool_value_t *, const char *);

/* Pool Property Value Creation/Destruction */
extern pool_value_t *pool_value_alloc(void);
extern void pool_value_free(pool_value_t *);

/* Default pool data store locations */
extern const char *pool_static_location(void);
extern const char *pool_dynamic_location(void);

/* Binding */
extern int pool_set_binding(const char *, idtype_t, id_t);
extern char *pool_get_binding(pid_t);
extern char *pool_get_resource_binding(const char *, pid_t);

/* Walking */
extern int pool_walk_pools(pool_conf_t *, void *,
    int (*)(pool_conf_t *, pool_t *, void *));
extern int pool_walk_resources(pool_conf_t *, pool_t *, void *,
    int (*)(pool_conf_t *, pool_resource_t *, void *));
extern int pool_walk_components(pool_conf_t *, pool_resource_t *, void *,
    int (*)(pool_conf_t *, pool_component_t *, void *));

#ifdef  __cplusplus
}
#endif

#endif  /* _POOL_H */