PSARC 2008/357 libtopo ses enumerator
6705260 want to enumerate external enclosures in libtopo
6705266 hc walker should compare nodes by something other than instance
6708851 libtopo topology DTD is broken
6708854 libtopo maps should be validated against DTD as part of lint
6709113 x86 xmlgen files generate invalid topology files
6709331 path topology attribute still hanging around
6709332 disk nodes can have invalid authority members
/*
* 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 2008 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*/
#ifndef _LIBTOPO_H
#define _LIBTOPO_H
#pragma ident "%Z%%M% %I% %E% SMI"
#include <sys/nvpair.h>
#include <stdio.h>
#ifdef __cplusplus
extern "C" {
#endif
#define TOPO_VERSION 1 /* Library ABI Interface Version */
typedef struct topo_hdl topo_hdl_t;
typedef struct topo_node tnode_t;
typedef struct topo_walk topo_walk_t;
typedef int32_t topo_instance_t;
typedef uint32_t topo_version_t;
/*
* The following functions, error codes and data structures are private
* to libtopo snapshot consumers and enumerator modules.
*/
extern topo_hdl_t *topo_open(int, const char *, int *);
extern void topo_close(topo_hdl_t *);
extern char *topo_snap_hold(topo_hdl_t *, const char *, int *);
extern void topo_snap_release(topo_hdl_t *);
/*
* Snapshot walker support
*/
typedef int (*topo_walk_cb_t)(topo_hdl_t *, tnode_t *, void *);
extern topo_walk_t *topo_walk_init(topo_hdl_t *, const char *, topo_walk_cb_t,
void *, int *);
extern int topo_walk_step(topo_walk_t *, int);
extern void topo_walk_fini(topo_walk_t *);
/*
* Walk status returned from walker
*/
#define TOPO_WALK_ERR -1
#define TOPO_WALK_NEXT 0
#define TOPO_WALK_TERMINATE 1
/*
* Types of walks: depth-first (child) or breadth-first (sibling)
*/
#define TOPO_WALK_CHILD 0x0001
#define TOPO_WALK_SIBLING 0x0002
/*
* FMRI helper routines
*/
extern int topo_fmri_present(topo_hdl_t *, nvlist_t *, int *);
extern int topo_fmri_contains(topo_hdl_t *, nvlist_t *, nvlist_t *, int *);
extern int topo_fmri_expand(topo_hdl_t *, nvlist_t *, int *);
extern int topo_fmri_unusable(topo_hdl_t *, nvlist_t *, int *);
extern int topo_fmri_nvl2str(topo_hdl_t *, nvlist_t *, char **, int *);
extern int topo_fmri_str2nvl(topo_hdl_t *, const char *, nvlist_t **, int *);
extern int topo_fmri_asru(topo_hdl_t *, nvlist_t *, nvlist_t **, int *);
extern int topo_fmri_fru(topo_hdl_t *, nvlist_t *, nvlist_t **,
int *);
extern int topo_fmri_label(topo_hdl_t *, nvlist_t *, char **, int *);
extern int topo_fmri_serial(topo_hdl_t *, nvlist_t *, char **, int *);
extern int topo_fmri_compare(topo_hdl_t *, nvlist_t *, nvlist_t *, int *);
/*
* Private utility functions for fmd
*/
extern ulong_t topo_fmri_strhash(topo_hdl_t *, const char *);
extern boolean_t topo_fmri_strcmp(topo_hdl_t *, const char *, const char *);
/*
* Topo node utilities: callable from topo_walk_step() callback or module
* enumeration, topo_mod_enumerate()
*/
extern char *topo_node_name(tnode_t *);
extern topo_instance_t topo_node_instance(tnode_t *);
extern tnode_t *topo_node_parent(tnode_t *);
extern void *topo_node_private(tnode_t *);
extern int topo_node_asru(tnode_t *, nvlist_t **, nvlist_t *, int *);
extern int topo_node_fru(tnode_t *, nvlist_t **, nvlist_t *, int *);
extern int topo_node_resource(tnode_t *, nvlist_t **, int *);
extern int topo_node_label(tnode_t *, char **, int *);
extern int topo_method_invoke(tnode_t *node, const char *, topo_version_t,
nvlist_t *, nvlist_t **, int *);
extern int topo_prop_get_int32(tnode_t *, const char *, const char *,
int32_t *, int *);
extern int topo_prop_get_uint32(tnode_t *, const char *, const char *,
uint32_t *, int *);
extern int topo_prop_get_int64(tnode_t *, const char *, const char *,
int64_t *, int *);
extern int topo_prop_get_uint64(tnode_t *, const char *, const char *,
uint64_t *, int *);
extern int topo_prop_get_string(tnode_t *, const char *, const char *,
char **, int *);
extern int topo_prop_get_fmri(tnode_t *, const char *, const char *,
nvlist_t **, int *);
extern int topo_prop_get_int32_array(tnode_t *, const char *, const char *,
int32_t **, uint_t *, int *);
extern int topo_prop_get_uint32_array(tnode_t *, const char *, const char *,
uint32_t **, uint_t *, int *);
extern int topo_prop_get_int64_array(tnode_t *, const char *, const char *,
int64_t **, uint_t *, int *);
extern int topo_prop_get_uint64_array(tnode_t *, const char *, const char *,
uint64_t **, uint_t *, int *);
extern int topo_prop_get_string_array(tnode_t *, const char *, const char *,
char ***, uint_t *, int *);
extern int topo_prop_get_fmri_array(tnode_t *, const char *, const char *,
nvlist_t ***, uint_t *, int *);
#define TOPO_PROP_IMMUTABLE 0
#define TOPO_PROP_MUTABLE 1
/* Protocol property group and property names */
#define TOPO_PGROUP_PROTOCOL "protocol" /* Required property group */
#define TOPO_PROP_RESOURCE "resource" /* resource FMRI */
#define TOPO_PROP_ASRU "ASRU" /* ASRU FMRI */
#define TOPO_PROP_FRU "FRU" /* FRU FMRI */
#define TOPO_PROP_MOD "module" /* software module FMRI */
#define TOPO_PROP_PKG "package" /* software package FMRI */
#define TOPO_PROP_LABEL "label" /* property LABEL */
/*
* System property group
*/
#define TOPO_PGROUP_SYSTEM "system"
#define TOPO_PROP_ISA "isa"
#define TOPO_PROP_MACHINE "machine"
/*
* These enum definitions are used to define a set of error tags associated with
* libtopo error conditions occuring during the adminstration of
* properties, invocation of methods and fmri-based queries. The shell script
* mkerror.sh is used to parse this file and create a corresponding topo_error.c
* source file.
*
* If you do something other than add a new error tag here, you may need to
* update the mkerror shell script as it is based upon simple regexps.
*/
typedef enum topo_prop_errno {
ETOPO_PROP_UNKNOWN = 3000, /* unknown topo prop error */
ETOPO_PROP_NOENT, /* undefined property or property group */
ETOPO_PROP_DEFD, /* static property already defined */
ETOPO_PROP_NOMEM, /* memory limit exceeded during property allocation */
ETOPO_PROP_TYPE, /* invalid property type */
ETOPO_PROP_NAME, /* invalid property name */
ETOPO_PROP_NOINHERIT, /* can not inherit property */
ETOPO_PROP_NVL, /* malformed property nvlist */
ETOPO_PROP_METHOD, /* get property method failed */
ETOPO_PROP_END /* end of prop errno list (to ease auto-merge) */
} topo_prop_errno_t;
typedef enum topo_method_errno {
ETOPO_METHOD_UNKNOWN = 3100, /* unknown topo method error */
ETOPO_METHOD_INVAL, /* invalid method registration */
ETOPO_METHOD_NOTSUP, /* method not supported */
ETOPO_METHOD_FAIL, /* method failed */
ETOPO_METHOD_VEROLD, /* app is compiled to use obsolete method */
ETOPO_METHOD_VERNEW, /* app is compiled to use obsolete method */
ETOPO_METHOD_NOMEM, /* memory limit exceeded during method op */
ETOPO_METHOD_DEFD, /* method op already defined */
ETOPO_METHOD_END /* end of method errno list */
} topo_method_errno_t;
typedef enum topo_fmri_errno {
ETOPO_FMRI_UNKNOWN = 3200, /* unknown topo fmri error */
ETOPO_FMRI_NVL, /* nvlist allocation failure for FMRI */
ETOPO_FMRI_VERSION, /* invalid FMRI scheme version */
ETOPO_FMRI_MALFORM, /* malformed FMRI */
ETOPO_FMRI_NOMEM, /* memory limit exceeded */
ETOPO_FMRI_END /* end of fmri errno list */
} topo_fmri_errno_t;
typedef enum topo_hdl_errno {
ETOPO_HDL_UNKNOWN = 3300, /* unknown topo handle error */
ETOPO_HDL_ABIVER, /* handle opened with invalid ABI version */
ETOPO_HDL_SNAP, /* snapshot already taken */
ETOPO_HDL_INVAL, /* invalid argument specified */
ETOPO_HDL_UUID, /* uuid already set */
ETOPO_HDL_NOMEM, /* memory limit exceeded */
ETOPO_HDL_END /* end of handle errno list */
} topo_hdl_errno_t;
extern const char *topo_strerror(int);
extern void topo_hdl_strfree(topo_hdl_t *, char *);
extern void topo_debug_set(topo_hdl_t *, const char *, const char *);
/*
* The following functions and data structures to support property
* observability are private to the fmtopo command.
*/
/*
* Each topology node advertises the name and data stability of each of its
* modules and properties. (see attributes(5)).
*/
/*
* Topo stability attributes
*/
typedef enum topo_stability {
TOPO_STABILITY_UNKNOWN = 0, /* private to libtopo */
TOPO_STABILITY_INTERNAL, /* private to libtopo */
TOPO_STABILITY_PRIVATE, /* private to Sun */
TOPO_STABILITY_OBSOLETE, /* scheduled for removal */
TOPO_STABILITY_EXTERNAL, /* not controlled by Sun */
TOPO_STABILITY_UNSTABLE, /* new or rapidly changing */
TOPO_STABILITY_EVOLVING, /* less rapidly changing */
TOPO_STABILITY_STABLE, /* mature interface from Sun */
TOPO_STABILITY_STANDARD /* industry standard */
} topo_stability_t;
#define TOPO_STABILITY_MAX TOPO_STABILITY_STANDARD /* max valid stab */
typedef struct topo_pgroup_info {
const char *tpi_name; /* property group name */
topo_stability_t tpi_namestab; /* stability of group name */
topo_stability_t tpi_datastab; /* stability of all property values */
topo_version_t tpi_version; /* version of pgroup definition */
} topo_pgroup_info_t;
extern topo_stability_t topo_name2stability(const char *);
extern const char *topo_stability2name(topo_stability_t);
extern void topo_pgroup_destroy(tnode_t *, const char *);
extern topo_pgroup_info_t *topo_pgroup_info(tnode_t *, const char *, int *);
typedef enum {
TOPO_TYPE_INVALID = 0,
TOPO_TYPE_BOOLEAN, /* boolean */
TOPO_TYPE_INT32, /* int32_t */
TOPO_TYPE_UINT32, /* uint32_t */
TOPO_TYPE_INT64, /* int64_t */
TOPO_TYPE_UINT64, /* uint64_t */
TOPO_TYPE_STRING, /* const char* */
TOPO_TYPE_TIME, /* uint64_t */
TOPO_TYPE_SIZE, /* uint64_t */
TOPO_TYPE_FMRI, /* nvlist_t */
TOPO_TYPE_INT32_ARRAY, /* array of int32_t */
TOPO_TYPE_UINT32_ARRAY, /* array of uint32_t */
TOPO_TYPE_INT64_ARRAY, /* array of int64_t */
TOPO_TYPE_UINT64_ARRAY, /* array of uint64_t */
TOPO_TYPE_STRING_ARRAY, /* array of const char* */
TOPO_TYPE_FMRI_ARRAY /* array of nvlist_t */
} topo_type_t;
extern nvlist_t *topo_prop_getprops(tnode_t *, int *err);
extern int topo_prop_getprop(tnode_t *, const char *, const char *,
nvlist_t *, nvlist_t **, int *);
extern int topo_prop_getpgrp(tnode_t *, const char *, nvlist_t **, int *);
extern int topo_prop_setprop(tnode_t *, const char *, nvlist_t *,
int, nvlist_t *, int *);
extern int topo_fmri_getprop(topo_hdl_t *, nvlist_t *, const char *,
const char *, nvlist_t *, nvlist_t **, int *);
extern int topo_fmri_getpgrp(topo_hdl_t *, nvlist_t *, const char *,
nvlist_t **, int *);
extern int topo_fmri_setprop(topo_hdl_t *, nvlist_t *, const char *,
nvlist_t *, int, nvlist_t *, int *);
/* Property node NVL names used in topo_prop_getprops */
#define TOPO_PROP_GROUP "property-group"
#define TOPO_PROP_GROUP_NAME "property-group-name"
#define TOPO_PROP_GROUP_DSTAB "property-group-data-stability"
#define TOPO_PROP_GROUP_NSTAB "property-group-name-stability"
#define TOPO_PROP_GROUP_VERSION "property-group-version"
#define TOPO_PROP_VAL "property"
#define TOPO_PROP_VAL_NAME "property-name"
#define TOPO_PROP_VAL_VAL "property-value"
#define TOPO_PROP_VAL_TYPE "property-type"
#define TOPO_PROP_FLAG "property-flag"
/*
* ARGS list used in topo property methods
*/
#define TOPO_PROP_ARGS "args"
#define TOPO_PROP_PARGS "private-args"
extern int topo_xml_print(topo_hdl_t *, FILE *, const char *scheme, int *);
extern void *topo_hdl_alloc(topo_hdl_t *, size_t);
extern void *topo_hdl_zalloc(topo_hdl_t *, size_t);
extern void topo_hdl_free(topo_hdl_t *, void *, size_t);
extern int topo_hdl_nvalloc(topo_hdl_t *, nvlist_t **, uint_t);
extern int topo_hdl_nvdup(topo_hdl_t *, nvlist_t *, nvlist_t **);
extern char *topo_hdl_strdup(topo_hdl_t *, const char *);
#ifdef __cplusplus
}
#endif
#endif /* _LIBTOPO_H */