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 (c) 2006, 2010, Oracle and/or its affiliates. All rights reserved. 24 */ 25 /* 26 * Copyright 2020 Joyent, Inc. 27 * Copyright 2023 Oxide Computer Company 28 */ 29 30 #ifndef _TOPO_MOD_H 31 #define _TOPO_MOD_H 32 33 #include <fm/libtopo.h> 34 #include <fm/topo_hc.h> 35 #include <libipmi.h> 36 #include <libnvpair.h> 37 #include <libdevinfo.h> 38 #include <smbios.h> 39 #include <pcidb.h> 40 #include <stdarg.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /* 47 * Enumerator and method supplier module API 48 */ 49 typedef struct topo_mod topo_mod_t; 50 51 typedef int topo_method_f(topo_mod_t *, tnode_t *, topo_version_t, nvlist_t *, 52 nvlist_t **); 53 typedef int topo_enum_f(topo_mod_t *, tnode_t *, const char *, topo_instance_t, 54 topo_instance_t, void *, void *); 55 typedef void topo_release_f(topo_mod_t *, tnode_t *); 56 57 typedef struct topo_method { 58 const char *tm_name; /* Method name */ 59 const char *tm_desc; /* Method description */ 60 const topo_version_t tm_version; /* Method version */ 61 const topo_stability_t tm_stability; /* Attributes of method */ 62 topo_method_f *tm_func; /* Method function */ 63 } topo_method_t; 64 65 typedef struct topo_modops { 66 topo_enum_f *tmo_enum; /* enumeration op */ 67 topo_release_f *tmo_release; /* resource release op */ 68 } topo_modops_t; 69 70 typedef struct topo_mod_info { 71 const char *tmi_desc; /* module description */ 72 const char *tmi_scheme; /* enumeration scheme type */ 73 topo_version_t tmi_version; /* module version */ 74 const topo_modops_t *tmi_ops; /* module ops vector */ 75 } topo_modinfo_t; 76 77 extern topo_mod_t *topo_mod_load(topo_mod_t *, const char *, topo_version_t); 78 extern void topo_mod_unload(topo_mod_t *); 79 extern int topo_mod_register(topo_mod_t *, const topo_modinfo_t *, 80 topo_version_t); 81 extern void topo_mod_unregister(topo_mod_t *); 82 extern int topo_mod_enumerate(topo_mod_t *, tnode_t *, const char *, 83 const char *, topo_instance_t, topo_instance_t, void *); 84 extern int topo_mod_enummap(topo_mod_t *mod, tnode_t *, const char *, 85 const char *); 86 extern char *topo_mod_product(topo_mod_t *); 87 extern void topo_mod_release(topo_mod_t *, tnode_t *); 88 extern void topo_mod_setspecific(topo_mod_t *, void *); 89 extern void *topo_mod_getspecific(topo_mod_t *); 90 91 extern nvlist_t *topo_mod_cpufmri(topo_mod_t *, int, uint32_t, uint8_t, 92 const char *); 93 extern nvlist_t *topo_mod_devfmri(topo_mod_t *, int, const char *, 94 const char *); 95 extern nvlist_t *topo_mod_hcfmri(topo_mod_t *, tnode_t *, int, const char *, 96 topo_instance_t, nvlist_t *, nvlist_t *, const char *, const char *, 97 const char *); 98 extern nvlist_t *topo_mod_hcfmri_extend(topo_mod_t *, nvlist_t *, int, 99 const char *, topo_instance_t); 100 extern nvlist_t *topo_mod_memfmri(topo_mod_t *, int, uint64_t, uint64_t, 101 const char *, int); 102 extern nvlist_t *topo_mod_modfmri(topo_mod_t *, int, const char *); 103 extern nvlist_t *topo_mod_pkgfmri(topo_mod_t *, int, const char *); 104 extern nvlist_t *topo_mod_pciefmri(topo_mod_t *, tnode_t *, int, 105 const char *, topo_instance_t, const nvlist_t *); 106 extern nvlist_t *topo_mod_swfmri(topo_mod_t *, int, 107 char *, char *, nvlist_t *, 108 char *, char *, char *, char *, int64_t, 109 char *, char *, int64_t, char *, int64_t, char **, uint_t); 110 extern int topo_mod_nvl2str(topo_mod_t *, nvlist_t *, char **); 111 extern int topo_mod_str2nvl(topo_mod_t *, const char *, nvlist_t **); 112 extern int topo_prop_setmutable(tnode_t *node, const char *pgname, 113 const char *pname, int *err); 114 extern int topo_prop_setnonvolatile(tnode_t *node, const char *pgname, 115 const char *pname, int *err); 116 /* 117 * Snapshot walker support 118 */ 119 typedef int (*topo_mod_walk_cb_t)(topo_mod_t *, tnode_t *, void *); 120 121 extern topo_walk_t *topo_mod_walk_init(topo_mod_t *, tnode_t *, 122 topo_mod_walk_cb_t, void *, int *); 123 124 /* 125 * Flags for topo_mod_memfmri 126 */ 127 #define TOPO_MEMFMRI_PA 0x0001 /* Valid physical address */ 128 #define TOPO_MEMFMRI_OFFSET 0x0002 /* Valid offset */ 129 130 extern int topo_method_register(topo_mod_t *, tnode_t *, const topo_method_t *); 131 extern void topo_method_unregister(topo_mod_t *, tnode_t *, const char *); 132 extern void topo_method_unregister_all(topo_mod_t *, tnode_t *); 133 134 extern di_node_t topo_mod_devinfo(topo_mod_t *); 135 extern ipmi_handle_t *topo_mod_ipmi_hold(topo_mod_t *); 136 extern void topo_mod_ipmi_rele(topo_mod_t *); 137 extern smbios_hdl_t *topo_mod_smbios(topo_mod_t *); 138 extern pcidb_hdl_t *topo_mod_pcidb(topo_mod_t *); 139 extern di_prom_handle_t topo_mod_prominfo(topo_mod_t *); 140 extern nvlist_t *topo_mod_auth(topo_mod_t *, tnode_t *); 141 142 extern int topo_method_sensor_failure(topo_mod_t *, tnode_t *, topo_version_t, 143 nvlist_t *, nvlist_t **); 144 145 /* 146 * FMRI methods 147 */ 148 #define TOPO_METH_LABEL "topo_label" 149 #define TOPO_METH_LABEL_DESC "label constructor" 150 #define TOPO_METH_LABEL_VERSION0 0 151 #define TOPO_METH_LABEL_VERSION TOPO_METH_LABEL_VERSION0 152 #define TOPO_METH_LABEL_ARG_NVL "label-specific" 153 #define TOPO_METH_LABEL_RET_STR "label-string" 154 155 #define TOPO_METH_PRESENT "topo_present" 156 #define TOPO_METH_PRESENT_DESC "presence indicator" 157 #define TOPO_METH_PRESENT_VERSION0 0 158 #define TOPO_METH_PRESENT_VERSION TOPO_METH_PRESENT_VERSION0 159 #define TOPO_METH_PRESENT_RET "present-ret" 160 161 #define TOPO_METH_REPLACED "topo_replaced" 162 #define TOPO_METH_REPLACED_DESC "replaced indicator" 163 #define TOPO_METH_REPLACED_VERSION0 0 164 #define TOPO_METH_REPLACED_VERSION TOPO_METH_REPLACED_VERSION0 165 #define TOPO_METH_REPLACED_RET "replaced-ret" 166 167 #define TOPO_METH_UNUSABLE "topo_unusable" 168 #define TOPO_METH_UNUSABLE_DESC "unusable indicator" 169 #define TOPO_METH_UNUSABLE_VERSION0 0 170 #define TOPO_METH_UNUSABLE_VERSION TOPO_METH_UNUSABLE_VERSION0 171 #define TOPO_METH_UNUSABLE_RET "unusable-ret" 172 173 #define TOPO_METH_SERVICE_STATE "topo_service_state" 174 #define TOPO_METH_SERVICE_STATE_DESC "service_state indicator" 175 #define TOPO_METH_SERVICE_STATE_VERSION0 0 176 #define TOPO_METH_SERVICE_STATE_VERSION TOPO_METH_SERVICE_STATE_VERSION0 177 #define TOPO_METH_SERVICE_STATE_RET "service_state-ret" 178 179 #define TOPO_METH_RETIRE "topo_retire" 180 #define TOPO_METH_RETIRE_DESC "retire action" 181 #define TOPO_METH_RETIRE_VERSION0 0 182 #define TOPO_METH_RETIRE_VERSION TOPO_METH_RETIRE_VERSION0 183 #define TOPO_METH_RETIRE_RET "retire-ret" 184 185 #define TOPO_METH_UNRETIRE "topo_unretire" 186 #define TOPO_METH_UNRETIRE_DESC "unretire action" 187 #define TOPO_METH_UNRETIRE_VERSION0 0 188 #define TOPO_METH_UNRETIRE_VERSION TOPO_METH_UNRETIRE_VERSION0 189 #define TOPO_METH_UNRETIRE_RET "unretire-ret" 190 191 #define TOPO_METH_EXPAND "topo_expand" 192 #define TOPO_METH_EXPAND_DESC "expand FMRI" 193 #define TOPO_METH_EXPAND_VERSION0 0 194 #define TOPO_METH_EXPAND_VERSION TOPO_METH_EXPAND_VERSION0 195 196 #define TOPO_METH_CONTAINS "topo_contains" 197 #define TOPO_METH_CONTAINS_DESC "FMRI contains sub-FMRI" 198 #define TOPO_METH_CONTAINS_VERSION0 0 199 #define TOPO_METH_CONTAINS_VERSION TOPO_METH_CONTAINS_VERSION0 200 #define TOPO_METH_CONTAINS_RET "contains-return" 201 #define TOPO_METH_FMRI_ARG_FMRI "fmri" 202 #define TOPO_METH_FMRI_ARG_SUBFMRI "sub-fmri" 203 204 #define TOPO_METH_ASRU_COMPUTE "topo_asru_compute" 205 #define TOPO_METH_ASRU_COMPUTE_VERSION 0 206 #define TOPO_METH_ASRU_COMPUTE_DESC "Dynamic ASRU constructor" 207 208 #define TOPO_METH_FRU_COMPUTE "topo_fru_compute" 209 #define TOPO_METH_FRU_COMPUTE_VERSION 0 210 #define TOPO_METH_FRU_COMPUTE_DESC "Dynamic FRU constructor" 211 212 #define TOPO_METH_DISK_STATUS "topo_disk_status" 213 #define TOPO_METH_DISK_STATUS_VERSION 0 214 #define TOPO_METH_DISK_STATUS_DESC "Disk status" 215 216 #define TOPO_METH_SENSOR_FAILURE "topo_sensor_failure" 217 #define TOPO_METH_SENSOR_FAILURE_VERSION 0 218 #define TOPO_METH_SENSOR_FAILURE_DESC "Sensor failure state" 219 220 #define TOPO_PROP_METH_DESC "Dynamic Property method" 221 222 #define TOPO_METH_IPMI_ENTITY "ipmi_entity" 223 #define TOPO_METH_FAC_ENUM_DESC "Facility Enumerator" 224 225 extern void *topo_mod_alloc(topo_mod_t *, size_t); 226 extern void *topo_mod_zalloc(topo_mod_t *, size_t); 227 extern void topo_mod_free(topo_mod_t *, void *, size_t); 228 extern char *topo_mod_strdup(topo_mod_t *, const char *); 229 extern void topo_mod_strfree(topo_mod_t *, char *); 230 extern void topo_mod_strfreev(topo_mod_t *, char **, uint_t); 231 extern int topo_mod_nvalloc(topo_mod_t *, nvlist_t **, uint_t); 232 extern int topo_mod_nvdup(topo_mod_t *, nvlist_t *, nvlist_t **); 233 extern int topo_mod_vasprintf(topo_mod_t *, char **, const char *, 234 va_list) __VPRINTFLIKE(3); 235 extern int topo_mod_asprintf(topo_mod_t *, char **, const char *, 236 ...) __PRINTFLIKE(3); 237 238 extern void topo_mod_clrdebug(topo_mod_t *); 239 extern void topo_mod_setdebug(topo_mod_t *); 240 extern void topo_mod_dprintf(topo_mod_t *, const char *, ...) __PRINTFLIKE(2); 241 extern const char *topo_mod_errmsg(topo_mod_t *); 242 extern int topo_mod_errno(topo_mod_t *); 243 extern char *topo_mod_clean_str(topo_mod_t *, const char *); 244 extern char *topo_mod_clean_strn(topo_mod_t *, const char *, size_t); 245 246 /* 247 * Topo node utilities: callable from module enumeration, topo_mod_enumerate() 248 */ 249 extern int topo_node_range_create(topo_mod_t *, tnode_t *, const char *, 250 topo_instance_t, topo_instance_t); 251 extern void topo_node_range_destroy(tnode_t *, const char *); 252 extern tnode_t *topo_node_bind(topo_mod_t *, tnode_t *, const char *, 253 topo_instance_t, nvlist_t *); 254 extern tnode_t *topo_node_facbind(topo_mod_t *, tnode_t *, const char *, 255 const char *); 256 extern void topo_node_unbind(tnode_t *); 257 extern void topo_node_setspecific(tnode_t *, void *); 258 extern void *topo_node_getspecific(tnode_t *); 259 extern int topo_node_asru_set(tnode_t *node, nvlist_t *, int, int *); 260 extern int topo_node_fru_set(tnode_t *node, nvlist_t *, int, int *); 261 extern int topo_node_label_set(tnode_t *node, const char *, int *); 262 263 #define TOPO_ASRU_COMPUTE 0x0001 /* Compute ASRU dynamically */ 264 #define TOPO_FRU_COMPUTE 0x0002 /* Compute FRU dynamically */ 265 266 extern int topo_prop_inherit(tnode_t *, const char *, const char *, int *); 267 extern int topo_pgroup_create(tnode_t *, const topo_pgroup_info_t *, int *); 268 269 /* 270 * Conveience property group and property creation. 271 */ 272 extern int topo_create_props(topo_mod_t *, tnode_t *, int, 273 const topo_pgroup_info_t *, ...); 274 275 /* 276 * Topo property method registration 277 */ 278 extern int topo_prop_method_register(tnode_t *, const char *, const char *, 279 topo_type_t, const char *, const nvlist_t *, int *); 280 extern void topo_prop_method_unregister(tnode_t *, const char *, const char *); 281 282 extern tnode_t *topo_mod_create_ufm(topo_mod_t *, tnode_t *, topo_instance_t, 283 const char *, topo_ufm_slot_info_t *); 284 extern tnode_t *topo_mod_create_ufm_slot(topo_mod_t *, tnode_t *, 285 topo_ufm_slot_info_t *); 286 287 /* 288 * This enum definition is used to define a set of error tags associated with 289 * the module api error conditions. The shell script mkerror.sh is 290 * used to parse this file and create a corresponding topo_error.c source file. 291 * If you do something other than add a new error tag here, you may need to 292 * update the mkerror shell script as it is based upon simple regexps. 293 */ 294 typedef enum topo_mod_errno { 295 EMOD_UNKNOWN = 2000, /* unknown libtopo error */ 296 EMOD_NOMEM, /* module memory limit exceeded */ 297 EMOD_PARTIAL_ENUM, /* module completed partial enumeration */ 298 EMOD_METHOD_INVAL, /* method arguments invalid */ 299 EMOD_METHOD_NOTSUP, /* method not supported */ 300 EMOD_FMRI_NVL, /* nvlist allocation failure for FMRI */ 301 EMOD_FMRI_VERSION, /* invalid FMRI scheme version */ 302 EMOD_FMRI_MALFORM, /* malformed FMRI */ 303 EMOD_NODE_BOUND, /* node already bound */ 304 EMOD_NODE_DUP, /* duplicate node */ 305 EMOD_NODE_NOENT, /* node not found */ 306 EMOD_NODE_RANGE, /* invalid node range */ 307 EMOD_VER_ABI, /* registered with invalid ABI version */ 308 EMOD_VER_OLD, /* attempt to load obsolete module */ 309 EMOD_VER_NEW, /* attempt to load a newer module */ 310 EMOD_NVL_INVAL, /* invalid nvlist */ 311 EMOD_NONCANON, /* non-canonical component name requested */ 312 EMOD_MOD_NOENT, /* module lookup failed */ 313 EMOD_UKNOWN_ENUM, /* unknown enumeration error */ 314 EMOD_DIGRAPH_MAXSZ, /* max digraph size exceeded */ 315 EMOD_END /* end of mod errno list (to ease auto-merge) */ 316 } topo_mod_errno_t; 317 318 extern int topo_mod_seterrno(topo_mod_t *, int); 319 320 /* 321 * Function used by a module to try and open a file based on FM's search path. 322 */ 323 extern int topo_mod_file_search(topo_mod_t *, const char *file, int oflags); 324 325 extern topo_method_f topo_mod_hc_occupied; 326 327 /* 328 * Directed Graph topology interfaces 329 */ 330 extern topo_digraph_t *topo_digraph_new(topo_hdl_t *, topo_mod_t *, 331 const char *); 332 extern void topo_digraph_destroy(topo_digraph_t *); 333 334 extern topo_vertex_t *topo_vertex_new(topo_mod_t *, const char *, 335 topo_instance_t); 336 extern void topo_vertex_destroy(topo_mod_t *mod, topo_vertex_t *vtx); 337 338 extern int topo_edge_new(topo_mod_t *, topo_vertex_t *, topo_vertex_t *); 339 340 #ifdef __cplusplus 341 } 342 #endif 343 344 #endif /* _TOPO_MOD_H */ 345