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 /* 23 * Copyright 2007 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 */ 26 27 #ifndef _LIBTOPO_H 28 #define _LIBTOPO_H 29 30 #pragma ident "%Z%%M% %I% %E% SMI" 31 32 #include <sys/nvpair.h> 33 #include <stdio.h> 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 #define TOPO_VERSION 1 /* Library ABI Interface Version */ 40 41 typedef struct topo_hdl topo_hdl_t; 42 typedef struct topo_node tnode_t; 43 typedef struct topo_walk topo_walk_t; 44 typedef int32_t topo_instance_t; 45 typedef uint32_t topo_version_t; 46 47 /* 48 * Topo stability attributes 49 * 50 * Each topology node advertises the name and data stability of each of its 51 * modules and properties. (see attributes(5)) 52 */ 53 54 typedef enum topo_stability { 55 TOPO_STABILITY_UNKNOWN = 0, /* private to libtopo */ 56 TOPO_STABILITY_INTERNAL, /* private to libtopo */ 57 TOPO_STABILITY_PRIVATE, /* private to Sun */ 58 TOPO_STABILITY_OBSOLETE, /* scheduled for removal */ 59 TOPO_STABILITY_EXTERNAL, /* not controlled by Sun */ 60 TOPO_STABILITY_UNSTABLE, /* new or rapidly changing */ 61 TOPO_STABILITY_EVOLVING, /* less rapidly changing */ 62 TOPO_STABILITY_STABLE, /* mature interface from Sun */ 63 TOPO_STABILITY_STANDARD /* industry standard */ 64 } topo_stability_t; 65 66 #define TOPO_STABILITY_MAX TOPO_STABILITY_STANDARD /* max valid stab */ 67 68 typedef enum { 69 TOPO_TYPE_INVALID = 0, 70 TOPO_TYPE_BOOLEAN, /* boolean */ 71 TOPO_TYPE_INT32, /* int32_t */ 72 TOPO_TYPE_UINT32, /* uint32_t */ 73 TOPO_TYPE_INT64, /* int64_t */ 74 TOPO_TYPE_UINT64, /* uint64_t */ 75 TOPO_TYPE_STRING, /* const char* */ 76 TOPO_TYPE_TIME, /* uint64_t */ 77 TOPO_TYPE_SIZE, /* uint64_t */ 78 TOPO_TYPE_FMRI, /* nvlist_t */ 79 TOPO_TYPE_INT32_ARRAY, /* array of int32_t */ 80 TOPO_TYPE_UINT32_ARRAY, /* array of uint32_t */ 81 TOPO_TYPE_INT64_ARRAY, /* array of int64_t */ 82 TOPO_TYPE_UINT64_ARRAY, /* array of uint64_t */ 83 TOPO_TYPE_STRING_ARRAY, /* array of const char* */ 84 TOPO_TYPE_FMRI_ARRAY /* array of nvlist_t */ 85 } topo_type_t; 86 87 typedef struct topo_pgroup_info { 88 const char *tpi_name; /* property group name */ 89 topo_stability_t tpi_namestab; /* stability of group name */ 90 topo_stability_t tpi_datastab; /* stability of all property values */ 91 topo_version_t tpi_version; /* version of pgroup definition */ 92 } topo_pgroup_info_t; 93 94 extern topo_stability_t topo_name2stability(const char *); 95 extern const char *topo_stability2name(topo_stability_t); 96 97 extern topo_hdl_t *topo_open(int, const char *, int *); 98 extern void topo_close(topo_hdl_t *); 99 extern char *topo_snap_hold(topo_hdl_t *, const char *, int *); 100 extern void topo_snap_release(topo_hdl_t *); 101 extern int topo_xml_print(topo_hdl_t *, FILE *, const char *scheme, int *); 102 103 /* 104 * Snapshot walker support 105 */ 106 typedef int (*topo_walk_cb_t)(topo_hdl_t *, tnode_t *, void *); 107 108 extern topo_walk_t *topo_walk_init(topo_hdl_t *, const char *, topo_walk_cb_t, 109 void *, int *); 110 extern int topo_walk_step(topo_walk_t *, int); 111 extern void topo_walk_fini(topo_walk_t *); 112 113 #define TOPO_WALK_ERR -1 114 #define TOPO_WALK_NEXT 0 115 #define TOPO_WALK_TERMINATE 1 116 117 #define TOPO_WALK_CHILD 0x0001 118 #define TOPO_WALK_SIBLING 0x0002 119 120 /* 121 * FMRI helper routines 122 */ 123 extern int topo_fmri_present(topo_hdl_t *, nvlist_t *, int *); 124 extern int topo_fmri_contains(topo_hdl_t *, nvlist_t *, nvlist_t *, int *); 125 extern int topo_fmri_expand(topo_hdl_t *, nvlist_t *, int *); 126 extern int topo_fmri_unusable(topo_hdl_t *, nvlist_t *, int *); 127 extern int topo_fmri_nvl2str(topo_hdl_t *, nvlist_t *, char **, int *); 128 extern int topo_fmri_str2nvl(topo_hdl_t *, const char *, nvlist_t **, int *); 129 extern int topo_fmri_asru(topo_hdl_t *, nvlist_t *, nvlist_t **, int *); 130 extern int topo_fmri_fru(topo_hdl_t *, nvlist_t *, nvlist_t **, 131 int *); 132 extern int topo_fmri_label(topo_hdl_t *, nvlist_t *, char **, int *); 133 extern int topo_fmri_compare(topo_hdl_t *, nvlist_t *, nvlist_t *, int *); 134 extern int topo_fmri_invoke(topo_hdl_t *, nvlist_t *, topo_walk_cb_t, void *, 135 int *); 136 137 /* 138 * Topo node utilities: callable from topo_walk_step() callback or module 139 * enumeration, topo_mod_enumerate() 140 */ 141 extern char *topo_node_name(tnode_t *); 142 extern topo_instance_t topo_node_instance(tnode_t *); 143 extern void *topo_node_private(tnode_t *); 144 extern int topo_node_asru(tnode_t *, nvlist_t **, nvlist_t *, int *); 145 extern int topo_node_fru(tnode_t *, nvlist_t **, nvlist_t *, int *); 146 extern int topo_node_resource(tnode_t *, nvlist_t **, int *); 147 extern int topo_node_label(tnode_t *, char **, int *); 148 extern int topo_method_invoke(tnode_t *node, const char *, topo_version_t, 149 nvlist_t *, nvlist_t **, int *); 150 151 extern int topo_pgroup_create(tnode_t *, const topo_pgroup_info_t *, int *); 152 extern void topo_pgroup_destroy(tnode_t *, const char *); 153 extern topo_pgroup_info_t *topo_pgroup_info(tnode_t *, const char *, int *); 154 extern int topo_prop_get_int32(tnode_t *, const char *, const char *, 155 int32_t *, int *); 156 extern int topo_prop_get_uint32(tnode_t *, const char *, const char *, 157 uint32_t *, int *); 158 extern int topo_prop_get_int64(tnode_t *, const char *, const char *, 159 int64_t *, int *); 160 extern int topo_prop_get_uint64(tnode_t *, const char *, const char *, 161 uint64_t *, int *); 162 extern int topo_prop_get_string(tnode_t *, const char *, const char *, 163 char **, int *); 164 extern int topo_prop_get_fmri(tnode_t *, const char *, const char *, 165 nvlist_t **, int *); 166 extern int topo_prop_get_int32_array(tnode_t *, const char *, const char *, 167 int32_t **, uint_t *, int *); 168 extern int topo_prop_get_uint32_array(tnode_t *, const char *, const char *, 169 uint32_t **, uint_t *, int *); 170 extern int topo_prop_get_int64_array(tnode_t *, const char *, const char *, 171 int64_t **, uint_t *, int *); 172 extern int topo_prop_get_uint64_array(tnode_t *, const char *, const char *, 173 uint64_t **, uint_t *, int *); 174 extern int topo_prop_get_string_array(tnode_t *, const char *, const char *, 175 char ***, uint_t *, int *); 176 extern int topo_prop_get_fmri_array(tnode_t *, const char *, const char *, 177 nvlist_t ***, uint_t *, int *); 178 extern int topo_prop_set_int32(tnode_t *, const char *, const char *, int, 179 int32_t, int *); 180 extern int topo_prop_set_uint32(tnode_t *, const char *, const char *, int, 181 uint32_t, int *); 182 extern int topo_prop_set_int64(tnode_t *, const char *, const char *, 183 int, int64_t, int *); 184 extern int topo_prop_set_uint64(tnode_t *, const char *, const char *, 185 int, uint64_t, int *); 186 extern int topo_prop_set_string(tnode_t *, const char *, const char *, 187 int, const char *, int *); 188 extern int topo_prop_set_fmri(tnode_t *, const char *, const char *, 189 int, const nvlist_t *, int *); 190 extern int topo_prop_set_int32_array(tnode_t *, const char *, const char *, int, 191 int32_t *, uint_t, int *); 192 extern int topo_prop_set_uint32_array(tnode_t *, const char *, const char *, 193 int, uint32_t *, uint_t, int *); 194 extern int topo_prop_set_int64_array(tnode_t *, const char *, const char *, 195 int, int64_t *, uint_t, int *); 196 extern int topo_prop_set_uint64_array(tnode_t *, const char *, const char *, 197 int, uint64_t *, uint_t, int *); 198 extern int topo_prop_set_string_array(tnode_t *, const char *, const char *, 199 int, const char **, uint_t, int *); 200 extern int topo_prop_set_fmri_array(tnode_t *, const char *, const char *, 201 int, const nvlist_t **, uint_t, int *); 202 extern nvlist_t *topo_prop_getprops(tnode_t *, int *err); 203 extern int topo_prop_inherit(tnode_t *, const char *, const char *, int *); 204 205 #define TOPO_PROP_IMMUTABLE 0 206 #define TOPO_PROP_MUTABLE 1 207 208 /* Protocol property group and property names */ 209 #define TOPO_PGROUP_PROTOCOL "protocol" /* Required property group */ 210 #define TOPO_PROP_RESOURCE "resource" /* resource FMRI */ 211 #define TOPO_PROP_ASRU "ASRU" /* ASRU FMRI */ 212 #define TOPO_PROP_FRU "FRU" /* FRU FMRI */ 213 #define TOPO_PROP_MOD "module" /* software module FMRI */ 214 #define TOPO_PROP_PKG "package" /* software package FMRI */ 215 #define TOPO_PROP_LABEL "label" /* property LABEL */ 216 217 /* 218 * System property group 219 */ 220 #define TOPO_PGROUP_SYSTEM "system" 221 #define TOPO_PROP_ISA "isa" 222 #define TOPO_PROP_MACHINE "machine" 223 224 /* Property node NVL names used in topo_prop_getprops */ 225 #define TOPO_PROP_GROUP "property-group" 226 #define TOPO_PROP_GROUP_NAME "property-group-name" 227 #define TOPO_PROP_GROUP_DSTAB "property-group-data-stability" 228 #define TOPO_PROP_GROUP_NSTAB "property-group-name-stability" 229 #define TOPO_PROP_GROUP_VERSION "property-group-version" 230 #define TOPO_PROP_VAL "property" 231 #define TOPO_PROP_VAL_NAME "property-name" 232 #define TOPO_PROP_VAL_VAL "property-value" 233 #define TOPO_PROP_VAL_TYPE "property-type" 234 235 /* 236 * This enum definition is used to define a set of error tags associated with 237 * the libtopo various error conditions occuring during the adminstration of 238 * properties. The shell script mkerror.sh is 239 * used to parse this file and create a corresponding topo_error.c source file. 240 * If you do something other than add a new error tag here, you may need to 241 * update the mkerror shell script as it is based upon simple regexps. 242 */ 243 typedef enum topo_prop_errno { 244 ETOPO_PROP_UNKNOWN = 3000, /* unknown topo prop error */ 245 ETOPO_PROP_NOENT, /* undefined property or property group */ 246 ETOPO_PROP_DEFD, /* static property already defined */ 247 ETOPO_PROP_NOMEM, /* memory limit exceeded during property allocation */ 248 ETOPO_PROP_TYPE, /* invalid property type */ 249 ETOPO_PROP_NOINHERIT, /* can not inherit property */ 250 ETOPO_PROP_NVL, /* malformed property nvlist */ 251 ETOPO_PROP_END /* end of prop errno list (to ease auto-merge) */ 252 } topo_prop_errno_t; 253 254 /* 255 * Similar to the above, this enum defines a set of errors associated with node 256 * methods. 257 */ 258 typedef enum topo_method_errno { 259 ETOPO_METHOD_UNKNOWN = 4000, /* unknown topo method error */ 260 ETOPO_METHOD_INVAL, /* invalid method registration */ 261 ETOPO_METHOD_NOTSUP, /* method not supported */ 262 ETOPO_METHOD_FAIL /* method failed */ 263 } topo_method_errno_t; 264 265 266 extern const char *topo_strerror(int); 267 extern void topo_debug_set(topo_hdl_t *, const char *, const char *); 268 extern void *topo_hdl_alloc(topo_hdl_t *, size_t); 269 extern void *topo_hdl_zalloc(topo_hdl_t *, size_t); 270 extern void topo_hdl_free(topo_hdl_t *, void *, size_t); 271 extern int topo_hdl_nvalloc(topo_hdl_t *, nvlist_t **, uint_t); 272 extern int topo_hdl_nvdup(topo_hdl_t *, nvlist_t *, nvlist_t **); 273 extern char *topo_hdl_strdup(topo_hdl_t *, const char *); 274 extern void topo_hdl_strfree(topo_hdl_t *, char *); 275 276 #ifdef __cplusplus 277 } 278 #endif 279 280 #endif /* _LIBTOPO_H */ 281