usr/src/lib/fm/topo/libtopo/common/topo_mod.h

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