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 2008 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 * The following functions, error codes and data structures are private 49 * to libtopo snapshot consumers and enumerator modules. 50 */ 51 extern topo_hdl_t *topo_open(int, const char *, int *); 52 extern void topo_close(topo_hdl_t *); 53 extern char *topo_snap_hold(topo_hdl_t *, const char *, int *); 54 extern void topo_snap_release(topo_hdl_t *); 55 56 /* 57 * Snapshot walker support 58 */ 59 typedef int (*topo_walk_cb_t)(topo_hdl_t *, tnode_t *, void *); 60 61 extern topo_walk_t *topo_walk_init(topo_hdl_t *, const char *, topo_walk_cb_t, 62 void *, int *); 63 extern int topo_walk_step(topo_walk_t *, int); 64 extern void topo_walk_fini(topo_walk_t *); 65 66 /* 67 * Walk status returned from walker 68 */ 69 #define TOPO_WALK_ERR -1 70 #define TOPO_WALK_NEXT 0 71 #define TOPO_WALK_TERMINATE 1 72 73 /* 74 * Types of walks: depth-first (child) or breadth-first (sibling) 75 */ 76 #define TOPO_WALK_CHILD 0x0001 77 #define TOPO_WALK_SIBLING 0x0002 78 79 /* 80 * FMRI helper routines 81 */ 82 extern int topo_fmri_present(topo_hdl_t *, nvlist_t *, int *); 83 extern int topo_fmri_contains(topo_hdl_t *, nvlist_t *, nvlist_t *, int *); 84 extern int topo_fmri_expand(topo_hdl_t *, nvlist_t *, int *); 85 extern int topo_fmri_unusable(topo_hdl_t *, nvlist_t *, int *); 86 extern int topo_fmri_nvl2str(topo_hdl_t *, nvlist_t *, char **, int *); 87 extern int topo_fmri_str2nvl(topo_hdl_t *, const char *, nvlist_t **, int *); 88 extern int topo_fmri_asru(topo_hdl_t *, nvlist_t *, nvlist_t **, int *); 89 extern int topo_fmri_fru(topo_hdl_t *, nvlist_t *, nvlist_t **, 90 int *); 91 extern int topo_fmri_label(topo_hdl_t *, nvlist_t *, char **, int *); 92 extern int topo_fmri_serial(topo_hdl_t *, nvlist_t *, char **, int *); 93 extern int topo_fmri_compare(topo_hdl_t *, nvlist_t *, nvlist_t *, int *); 94 95 /* 96 * Private utility functions for fmd 97 */ 98 extern ulong_t topo_fmri_strhash(topo_hdl_t *, const char *); 99 extern boolean_t topo_fmri_strcmp(topo_hdl_t *, const char *, const char *); 100 101 /* 102 * Topo node utilities: callable from topo_walk_step() callback or module 103 * enumeration, topo_mod_enumerate() 104 */ 105 extern char *topo_node_name(tnode_t *); 106 extern topo_instance_t topo_node_instance(tnode_t *); 107 extern tnode_t *topo_node_parent(tnode_t *); 108 extern void *topo_node_private(tnode_t *); 109 extern int topo_node_asru(tnode_t *, nvlist_t **, nvlist_t *, int *); 110 extern int topo_node_fru(tnode_t *, nvlist_t **, nvlist_t *, int *); 111 extern int topo_node_resource(tnode_t *, nvlist_t **, int *); 112 extern int topo_node_label(tnode_t *, char **, int *); 113 extern int topo_method_invoke(tnode_t *node, const char *, topo_version_t, 114 nvlist_t *, nvlist_t **, int *); 115 116 extern int topo_prop_get_int32(tnode_t *, const char *, const char *, 117 int32_t *, int *); 118 extern int topo_prop_get_uint32(tnode_t *, const char *, const char *, 119 uint32_t *, int *); 120 extern int topo_prop_get_int64(tnode_t *, const char *, const char *, 121 int64_t *, int *); 122 extern int topo_prop_get_uint64(tnode_t *, const char *, const char *, 123 uint64_t *, int *); 124 extern int topo_prop_get_string(tnode_t *, const char *, const char *, 125 char **, int *); 126 extern int topo_prop_get_fmri(tnode_t *, const char *, const char *, 127 nvlist_t **, int *); 128 extern int topo_prop_get_int32_array(tnode_t *, const char *, const char *, 129 int32_t **, uint_t *, int *); 130 extern int topo_prop_get_uint32_array(tnode_t *, const char *, const char *, 131 uint32_t **, uint_t *, int *); 132 extern int topo_prop_get_int64_array(tnode_t *, const char *, const char *, 133 int64_t **, uint_t *, int *); 134 extern int topo_prop_get_uint64_array(tnode_t *, const char *, const char *, 135 uint64_t **, uint_t *, int *); 136 extern int topo_prop_get_string_array(tnode_t *, const char *, const char *, 137 char ***, uint_t *, int *); 138 extern int topo_prop_get_fmri_array(tnode_t *, const char *, const char *, 139 nvlist_t ***, uint_t *, int *); 140 141 #define TOPO_PROP_IMMUTABLE 0 142 #define TOPO_PROP_MUTABLE 1 143 144 /* Protocol property group and property names */ 145 #define TOPO_PGROUP_PROTOCOL "protocol" /* Required property group */ 146 #define TOPO_PROP_RESOURCE "resource" /* resource FMRI */ 147 #define TOPO_PROP_ASRU "ASRU" /* ASRU FMRI */ 148 #define TOPO_PROP_FRU "FRU" /* FRU FMRI */ 149 #define TOPO_PROP_MOD "module" /* software module FMRI */ 150 #define TOPO_PROP_PKG "package" /* software package FMRI */ 151 #define TOPO_PROP_LABEL "label" /* property LABEL */ 152 153 /* 154 * System property group 155 */ 156 #define TOPO_PGROUP_SYSTEM "system" 157 #define TOPO_PROP_ISA "isa" 158 #define TOPO_PROP_MACHINE "machine" 159 160 /* 161 * These enum definitions are used to define a set of error tags associated with 162 * libtopo error conditions occuring during the adminstration of 163 * properties, invocation of methods and fmri-based queries. The shell script 164 * mkerror.sh is used to parse this file and create a corresponding topo_error.c 165 * source file. 166 * 167 * If you do something other than add a new error tag here, you may need to 168 * update the mkerror shell script as it is based upon simple regexps. 169 */ 170 typedef enum topo_prop_errno { 171 ETOPO_PROP_UNKNOWN = 3000, /* unknown topo prop error */ 172 ETOPO_PROP_NOENT, /* undefined property or property group */ 173 ETOPO_PROP_DEFD, /* static property already defined */ 174 ETOPO_PROP_NOMEM, /* memory limit exceeded during property allocation */ 175 ETOPO_PROP_TYPE, /* invalid property type */ 176 ETOPO_PROP_NAME, /* invalid property name */ 177 ETOPO_PROP_NOINHERIT, /* can not inherit property */ 178 ETOPO_PROP_NVL, /* malformed property nvlist */ 179 ETOPO_PROP_METHOD, /* get property method failed */ 180 ETOPO_PROP_END /* end of prop errno list (to ease auto-merge) */ 181 } topo_prop_errno_t; 182 183 typedef enum topo_method_errno { 184 ETOPO_METHOD_UNKNOWN = 3100, /* unknown topo method error */ 185 ETOPO_METHOD_INVAL, /* invalid method registration */ 186 ETOPO_METHOD_NOTSUP, /* method not supported */ 187 ETOPO_METHOD_FAIL, /* method failed */ 188 ETOPO_METHOD_VEROLD, /* app is compiled to use obsolete method */ 189 ETOPO_METHOD_VERNEW, /* app is compiled to use obsolete method */ 190 ETOPO_METHOD_NOMEM, /* memory limit exceeded during method op */ 191 ETOPO_METHOD_DEFD, /* method op already defined */ 192 ETOPO_METHOD_END /* end of method errno list */ 193 } topo_method_errno_t; 194 195 typedef enum topo_fmri_errno { 196 ETOPO_FMRI_UNKNOWN = 3200, /* unknown topo fmri error */ 197 ETOPO_FMRI_NVL, /* nvlist allocation failure for FMRI */ 198 ETOPO_FMRI_VERSION, /* invalid FMRI scheme version */ 199 ETOPO_FMRI_MALFORM, /* malformed FMRI */ 200 ETOPO_FMRI_NOMEM, /* memory limit exceeded */ 201 ETOPO_FMRI_END /* end of fmri errno list */ 202 } topo_fmri_errno_t; 203 204 typedef enum topo_hdl_errno { 205 ETOPO_HDL_UNKNOWN = 3300, /* unknown topo handle error */ 206 ETOPO_HDL_ABIVER, /* handle opened with invalid ABI version */ 207 ETOPO_HDL_SNAP, /* snapshot already taken */ 208 ETOPO_HDL_INVAL, /* invalid argument specified */ 209 ETOPO_HDL_UUID, /* uuid already set */ 210 ETOPO_HDL_NOMEM, /* memory limit exceeded */ 211 ETOPO_HDL_END /* end of handle errno list */ 212 } topo_hdl_errno_t; 213 214 extern const char *topo_strerror(int); 215 extern void topo_hdl_strfree(topo_hdl_t *, char *); 216 extern void topo_debug_set(topo_hdl_t *, const char *, const char *); 217 218 /* 219 * The following functions and data structures to support property 220 * observability are private to the fmtopo command. 221 */ 222 223 /* 224 * Each topology node advertises the name and data stability of each of its 225 * modules and properties. (see attributes(5)). 226 */ 227 228 /* 229 * Topo stability attributes 230 */ 231 typedef enum topo_stability { 232 TOPO_STABILITY_UNKNOWN = 0, /* private to libtopo */ 233 TOPO_STABILITY_INTERNAL, /* private to libtopo */ 234 TOPO_STABILITY_PRIVATE, /* private to Sun */ 235 TOPO_STABILITY_OBSOLETE, /* scheduled for removal */ 236 TOPO_STABILITY_EXTERNAL, /* not controlled by Sun */ 237 TOPO_STABILITY_UNSTABLE, /* new or rapidly changing */ 238 TOPO_STABILITY_EVOLVING, /* less rapidly changing */ 239 TOPO_STABILITY_STABLE, /* mature interface from Sun */ 240 TOPO_STABILITY_STANDARD /* industry standard */ 241 } topo_stability_t; 242 243 #define TOPO_STABILITY_MAX TOPO_STABILITY_STANDARD /* max valid stab */ 244 245 typedef struct topo_pgroup_info { 246 const char *tpi_name; /* property group name */ 247 topo_stability_t tpi_namestab; /* stability of group name */ 248 topo_stability_t tpi_datastab; /* stability of all property values */ 249 topo_version_t tpi_version; /* version of pgroup definition */ 250 } topo_pgroup_info_t; 251 252 extern topo_stability_t topo_name2stability(const char *); 253 extern const char *topo_stability2name(topo_stability_t); 254 extern void topo_pgroup_destroy(tnode_t *, const char *); 255 extern topo_pgroup_info_t *topo_pgroup_info(tnode_t *, const char *, int *); 256 257 typedef enum { 258 TOPO_TYPE_INVALID = 0, 259 TOPO_TYPE_BOOLEAN, /* boolean */ 260 TOPO_TYPE_INT32, /* int32_t */ 261 TOPO_TYPE_UINT32, /* uint32_t */ 262 TOPO_TYPE_INT64, /* int64_t */ 263 TOPO_TYPE_UINT64, /* uint64_t */ 264 TOPO_TYPE_STRING, /* const char* */ 265 TOPO_TYPE_TIME, /* uint64_t */ 266 TOPO_TYPE_SIZE, /* uint64_t */ 267 TOPO_TYPE_FMRI, /* nvlist_t */ 268 TOPO_TYPE_INT32_ARRAY, /* array of int32_t */ 269 TOPO_TYPE_UINT32_ARRAY, /* array of uint32_t */ 270 TOPO_TYPE_INT64_ARRAY, /* array of int64_t */ 271 TOPO_TYPE_UINT64_ARRAY, /* array of uint64_t */ 272 TOPO_TYPE_STRING_ARRAY, /* array of const char* */ 273 TOPO_TYPE_FMRI_ARRAY /* array of nvlist_t */ 274 } topo_type_t; 275 276 extern nvlist_t *topo_prop_getprops(tnode_t *, int *err); 277 extern int topo_prop_getprop(tnode_t *, const char *, const char *, 278 nvlist_t *, nvlist_t **, int *); 279 extern int topo_prop_getpgrp(tnode_t *, const char *, nvlist_t **, int *); 280 extern int topo_prop_setprop(tnode_t *, const char *, nvlist_t *, 281 int, nvlist_t *, int *); 282 extern int topo_fmri_getprop(topo_hdl_t *, nvlist_t *, const char *, 283 const char *, nvlist_t *, nvlist_t **, int *); 284 extern int topo_fmri_getpgrp(topo_hdl_t *, nvlist_t *, const char *, 285 nvlist_t **, int *); 286 extern int topo_fmri_setprop(topo_hdl_t *, nvlist_t *, const char *, 287 nvlist_t *, int, nvlist_t *, int *); 288 289 /* Property node NVL names used in topo_prop_getprops */ 290 #define TOPO_PROP_GROUP "property-group" 291 #define TOPO_PROP_GROUP_NAME "property-group-name" 292 #define TOPO_PROP_GROUP_DSTAB "property-group-data-stability" 293 #define TOPO_PROP_GROUP_NSTAB "property-group-name-stability" 294 #define TOPO_PROP_GROUP_VERSION "property-group-version" 295 #define TOPO_PROP_VAL "property" 296 #define TOPO_PROP_VAL_NAME "property-name" 297 #define TOPO_PROP_VAL_VAL "property-value" 298 #define TOPO_PROP_VAL_TYPE "property-type" 299 #define TOPO_PROP_FLAG "property-flag" 300 301 /* 302 * ARGS list used in topo property methods 303 */ 304 #define TOPO_PROP_ARGS "args" 305 #define TOPO_PROP_PARGS "private-args" 306 307 extern int topo_xml_print(topo_hdl_t *, FILE *, const char *scheme, int *); 308 309 extern void *topo_hdl_alloc(topo_hdl_t *, size_t); 310 extern void *topo_hdl_zalloc(topo_hdl_t *, size_t); 311 extern void topo_hdl_free(topo_hdl_t *, void *, size_t); 312 extern int topo_hdl_nvalloc(topo_hdl_t *, nvlist_t **, uint_t); 313 extern int topo_hdl_nvdup(topo_hdl_t *, nvlist_t *, nvlist_t **); 314 extern char *topo_hdl_strdup(topo_hdl_t *, const char *); 315 316 #ifdef __cplusplus 317 } 318 #endif 319 320 #endif /* _LIBTOPO_H */ 321