/*
 * 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.
 */

/*
 *  NOTE
 *
 *  The following contents of this file are private to the
 *  implementation of the Solaris system and are subject to change at
 *  any time without notice.  Applications using these interfaces may
 *  fail to run on future releases.
 */

#ifndef _POOL_H
#define _POOL_H

#include <sys/procset.h>
#include <sys/types.h>
#include <sys/pool.h>

#ifdef  __cplusplus
extern "C" {
#endif

/*
 * Library versioning support (c.f. elf_version(3elf)).
 *
 * You can enquire about the version number of the library
 * by passing POOL_VER_NONE.  POOL_VER_CURRENT is the current
 * (most capable) version.
 *
 * You can set the version used by the library by passing the
 * required version number.  If this is not possible, the version
 * returned will be POOL_VER_NONE.
 */
#define POOL_VER_CURRENT        1
#define POOL_VER_NONE           0

extern uint_t pool_version(uint_t ver);

#ifndef PO_TRUE
#define PO_TRUE 1
#endif

#ifndef PO_FALSE
#define PO_FALSE        0
#endif

#ifndef PO_SUCCESS
#define PO_SUCCESS      0
#endif

#ifndef PO_FAIL
#define PO_FAIL -1
#endif

/* Error codes */
#define POE_OK                  0
#define POE_BAD_PROP_TYPE       1
#define POE_INVALID_CONF        2
#define POE_NOTSUP              3
#define POE_INVALID_SEARCH      4
#define POE_BADPARAM            5
#define POE_PUTPROP             6
#define POE_DATASTORE           7
#define POE_SYSTEM              8
#define POE_ACCESS              9

/* Open Flags */
#define PO_RDONLY               0x0
#define PO_RDWR                 0x1
#define PO_CREAT                0x2
#define PO_DISCO                0x4
#define PO_UPDATE               0x8
#define PO_TEMP                 0x10

/* Allocation policy */
#define POA_IMPORTANCE          "importance based"
#define POA_SURPLUS_TO_DEFAULT  "surplus to default"

/* Pools updates */
#define POU_SYSTEM              0x1
#define POU_POOL                0x2
#define POU_PSET                0x4
#define POU_CPU                 0x8

/* Data Export Formats */
typedef enum pool_export_format {
        POX_NATIVE,             /* Native data representation format */
        POX_TEXT                /* Text */
} pool_export_format_t;

/* Property data types */
typedef enum pool_value_class {
        POC_INVAL = -1,
        POC_UINT,
        POC_INT,
        POC_DOUBLE,
        POC_BOOL,
        POC_STRING
} pool_value_class_t;

/* Validation levels */
typedef enum pool_valid_level {
        POV_NONE = 0,           /* No validation */
        POV_LOOSE,              /* Loose validation */
        POV_STRICT,             /* Strict validation */
        POV_RUNTIME             /* Validate instantiation on current machine */
} pool_valid_level_t;

/* conf states */
typedef enum pool_conf_state {
        POF_INVALID = -1,
        POF_VALID,
        POF_DESTROY
} pool_conf_state_t;

/* Element data values */
typedef struct pool_value pool_value_t;

/* Elements */
typedef struct pool_elem pool_elem_t;
typedef struct pool pool_t;
typedef struct pool_resource pool_resource_t;
typedef struct pool_component pool_component_t;

/*
 * Resource management configuration
 */
typedef struct pool_conf pool_conf_t;

extern int              pool_error(void);
extern const char       *pool_strerror(int);
extern int              pool_resource_type_list(const char **, uint_t *);
extern int              pool_get_status(int *);
extern int              pool_set_status(int);

/* Configuration manipulation */
extern pool_conf_t *pool_conf_alloc(void);
extern void pool_conf_free(pool_conf_t *);
extern pool_conf_state_t pool_conf_status(const pool_conf_t *);

extern int pool_conf_close(pool_conf_t *);
extern int pool_conf_remove(pool_conf_t *);
extern int pool_conf_open(pool_conf_t *, const char *, int);
extern int pool_conf_rollback(pool_conf_t *);
extern 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 */