Home | History | Annotate | Download | only in common
      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 2009 Sun Microsystems, Inc.  All rights reserved.
     24  * Use is subject to license terms.
     25  */
     26 
     27 #ifndef _TOPO_MOD_H
     28 #define	_TOPO_MOD_H
     29 
     30 #include <fm/libtopo.h>
     31 #include <fm/topo_hc.h>
     32 #include <libipmi.h>
     33 #include <libnvpair.h>
     34 #include <libdevinfo.h>
     35 #include <smbios.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 int topo_mod_nvl2str(topo_mod_t *, nvlist_t *, char **);
     97 extern int topo_mod_str2nvl(topo_mod_t *, const char *,  nvlist_t **);
     98 extern int topo_prop_setmutable(tnode_t *node, const char *pgname,
     99     const char *pname, int *err);
    100 extern int topo_prop_setnonvolatile(tnode_t *node, const char *pgname,
    101     const char *pname, int *err);
    102 /*
    103  * Snapshot walker support
    104  */
    105 typedef int (*topo_mod_walk_cb_t)(topo_mod_t *, tnode_t *, void *);
    106 
    107 extern topo_walk_t *topo_mod_walk_init(topo_mod_t *, tnode_t *,
    108     topo_mod_walk_cb_t, void *, int *);
    109 
    110 /*
    111  * Flags for topo_mod_memfmri
    112  */
    113 #define	TOPO_MEMFMRI_PA		0x0001	/* Valid physical address */
    114 #define	TOPO_MEMFMRI_OFFSET	0x0002	/* Valid offset */
    115 
    116 extern int topo_method_register(topo_mod_t *, tnode_t *, const topo_method_t *);
    117 extern void topo_method_unregister(topo_mod_t *, tnode_t *, const char *);
    118 extern void topo_method_unregister_all(topo_mod_t *, tnode_t *);
    119 
    120 extern di_node_t topo_mod_devinfo(topo_mod_t *);
    121 extern ipmi_handle_t *topo_mod_ipmi_hold(topo_mod_t *);
    122 extern void topo_mod_ipmi_rele(topo_mod_t *);
    123 extern smbios_hdl_t *topo_mod_smbios(topo_mod_t *);
    124 extern di_prom_handle_t topo_mod_prominfo(topo_mod_t *);
    125 extern nvlist_t *topo_mod_auth(topo_mod_t *, tnode_t *);
    126 
    127 extern int topo_method_sensor_failure(topo_mod_t *, tnode_t *, topo_version_t,
    128     nvlist_t *, nvlist_t **);
    129 
    130 /*
    131  * FMRI methods
    132  */
    133 #define	TOPO_METH_LABEL			"topo_label"
    134 #define	TOPO_METH_LABEL_DESC		"label constructor"
    135 #define	TOPO_METH_LABEL_VERSION0	0
    136 #define	TOPO_METH_LABEL_VERSION		TOPO_METH_LABEL_VERSION0
    137 #define	TOPO_METH_LABEL_ARG_NVL		"label-specific"
    138 #define	TOPO_METH_LABEL_RET_STR		"label-string"
    139 
    140 #define	TOPO_METH_PRESENT		"topo_present"
    141 #define	TOPO_METH_PRESENT_DESC		"presence indicator"
    142 #define	TOPO_METH_PRESENT_VERSION0	0
    143 #define	TOPO_METH_PRESENT_VERSION	TOPO_METH_PRESENT_VERSION0
    144 #define	TOPO_METH_PRESENT_RET		"present-ret"
    145 
    146 #define	TOPO_METH_REPLACED		"topo_replaced"
    147 #define	TOPO_METH_REPLACED_DESC		"replaced indicator"
    148 #define	TOPO_METH_REPLACED_VERSION0	0
    149 #define	TOPO_METH_REPLACED_VERSION	TOPO_METH_REPLACED_VERSION0
    150 #define	TOPO_METH_REPLACED_RET		"replaced-ret"
    151 
    152 #define	TOPO_METH_UNUSABLE		"topo_unusable"
    153 #define	TOPO_METH_UNUSABLE_DESC		"unusable indicator"
    154 #define	TOPO_METH_UNUSABLE_VERSION0	0
    155 #define	TOPO_METH_UNUSABLE_VERSION	TOPO_METH_UNUSABLE_VERSION0
    156 #define	TOPO_METH_UNUSABLE_RET		"unusable-ret"
    157 
    158 #define	TOPO_METH_SERVICE_STATE		"topo_service_state"
    159 #define	TOPO_METH_SERVICE_STATE_DESC	"service_state indicator"
    160 #define	TOPO_METH_SERVICE_STATE_VERSION0	0
    161 #define	TOPO_METH_SERVICE_STATE_VERSION	TOPO_METH_SERVICE_STATE_VERSION0
    162 #define	TOPO_METH_SERVICE_STATE_RET	"service_state-ret"
    163 
    164 #define	TOPO_METH_RETIRE		"topo_retire"
    165 #define	TOPO_METH_RETIRE_DESC		"retire action"
    166 #define	TOPO_METH_RETIRE_VERSION0	0
    167 #define	TOPO_METH_RETIRE_VERSION	TOPO_METH_RETIRE_VERSION0
    168 #define	TOPO_METH_RETIRE_RET		"retire-ret"
    169 
    170 #define	TOPO_METH_UNRETIRE		"topo_unretire"
    171 #define	TOPO_METH_UNRETIRE_DESC		"unretire action"
    172 #define	TOPO_METH_UNRETIRE_VERSION0	0
    173 #define	TOPO_METH_UNRETIRE_VERSION	TOPO_METH_UNRETIRE_VERSION0
    174 #define	TOPO_METH_UNRETIRE_RET		"unretire-ret"
    175 
    176 #define	TOPO_METH_EXPAND		"topo_expand"
    177 #define	TOPO_METH_EXPAND_DESC		"expand FMRI"
    178 #define	TOPO_METH_EXPAND_VERSION0	0
    179 #define	TOPO_METH_EXPAND_VERSION	TOPO_METH_EXPAND_VERSION0
    180 
    181 #define	TOPO_METH_CONTAINS		"topo_contains"
    182 #define	TOPO_METH_CONTAINS_DESC		"FMRI contains sub-FMRI"
    183 #define	TOPO_METH_CONTAINS_VERSION0	0
    184 #define	TOPO_METH_CONTAINS_VERSION	TOPO_METH_CONTAINS_VERSION0
    185 #define	TOPO_METH_CONTAINS_RET		"contains-return"
    186 #define	TOPO_METH_FMRI_ARG_FMRI		"fmri"
    187 #define	TOPO_METH_FMRI_ARG_SUBFMRI	"sub-fmri"
    188 
    189 #define	TOPO_METH_ASRU_COMPUTE		"topo_asru_compute"
    190 #define	TOPO_METH_ASRU_COMPUTE_VERSION	0
    191 #define	TOPO_METH_ASRU_COMPUTE_DESC	"Dynamic ASRU constructor"
    192 
    193 #define	TOPO_METH_FRU_COMPUTE		"topo_fru_compute"
    194 #define	TOPO_METH_FRU_COMPUTE_VERSION	0
    195 #define	TOPO_METH_FRU_COMPUTE_DESC	"Dynamic FRU constructor"
    196 
    197 #define	TOPO_METH_DISK_STATUS		"topo_disk_status"
    198 #define	TOPO_METH_DISK_STATUS_VERSION	0
    199 #define	TOPO_METH_DISK_STATUS_DESC	"Disk status"
    200 
    201 #define	TOPO_METH_SENSOR_FAILURE	"topo_sensor_failure"
    202 #define	TOPO_METH_SENSOR_FAILURE_VERSION	0
    203 #define	TOPO_METH_SENSOR_FAILURE_DESC	"Sensor failure state"
    204 
    205 #define	TOPO_PROP_METH_DESC		"Dynamic Property method"
    206 
    207 #define	TOPO_METH_IPMI_ENTITY		"ipmi_entity"
    208 #define	TOPO_METH_FAC_ENUM_DESC		"Facility Enumerator"
    209 
    210 extern void *topo_mod_alloc(topo_mod_t *, size_t);
    211 extern void *topo_mod_zalloc(topo_mod_t *, size_t);
    212 extern void topo_mod_free(topo_mod_t *, void *, size_t);
    213 extern char *topo_mod_strdup(topo_mod_t *, const char *);
    214 extern void topo_mod_strfree(topo_mod_t *, char *);
    215 extern int topo_mod_nvalloc(topo_mod_t *, nvlist_t **, uint_t);
    216 extern int topo_mod_nvdup(topo_mod_t *, nvlist_t *, nvlist_t **);
    217 
    218 extern void topo_mod_clrdebug(topo_mod_t *);
    219 extern void topo_mod_setdebug(topo_mod_t *);
    220 extern void topo_mod_dprintf(topo_mod_t *, const char *, ...);
    221 extern const char *topo_mod_errmsg(topo_mod_t *);
    222 extern int topo_mod_errno(topo_mod_t *);
    223 
    224 /*
    225  * Topo node utilities: callable from module enumeration, topo_mod_enumerate()
    226  */
    227 extern int topo_node_range_create(topo_mod_t *, tnode_t *, const char *,
    228     topo_instance_t, topo_instance_t);
    229 extern void topo_node_range_destroy(tnode_t *, const char *);
    230 extern tnode_t *topo_node_bind(topo_mod_t *, tnode_t *, const char *,
    231     topo_instance_t, nvlist_t *);
    232 extern tnode_t *topo_node_facbind(topo_mod_t *, tnode_t *, const char *,
    233     const char *);
    234 extern void topo_node_unbind(tnode_t *);
    235 extern void topo_node_setspecific(tnode_t *, void *);
    236 extern void *topo_node_getspecific(tnode_t *);
    237 extern int topo_node_asru_set(tnode_t *node, nvlist_t *, int, int *);
    238 extern int topo_node_fru_set(tnode_t *node, nvlist_t *, int, int *);
    239 extern int topo_node_label_set(tnode_t *node, char *, int *);
    240 
    241 #define	TOPO_ASRU_COMPUTE	0x0001	/* Compute ASRU dynamically */
    242 #define	TOPO_FRU_COMPUTE	0x0002	/* Compute FRU dynamically */
    243 
    244 extern int topo_prop_inherit(tnode_t *, const char *, const char *, int *);
    245 extern int topo_pgroup_create(tnode_t *, const topo_pgroup_info_t *, int *);
    246 
    247 /*
    248  * Topo property method registration
    249  */
    250 extern int topo_prop_method_register(tnode_t *, const char *, const char *,
    251     topo_type_t, const char *, const nvlist_t *, int *);
    252 extern void topo_prop_method_unregister(tnode_t *, const char *, const char *);
    253 
    254 /*
    255  * This enum definition is used to define a set of error tags associated with
    256  * the module api error conditions.  The shell script mkerror.sh is
    257  * used to parse this file and create a corresponding topo_error.c source file.
    258  * If you do something other than add a new error tag here, you may need to
    259  * update the mkerror shell script as it is based upon simple regexps.
    260  */
    261 typedef enum topo_mod_errno {
    262     EMOD_UNKNOWN = 2000, /* unknown libtopo error */
    263     EMOD_NOMEM,			/* module memory limit exceeded */
    264     EMOD_PARTIAL_ENUM,		/* module completed partial enumeration */
    265     EMOD_METHOD_INVAL,		/* method arguments invalid */
    266     EMOD_METHOD_NOTSUP,		/* method not supported */
    267     EMOD_FMRI_NVL,		/* nvlist allocation failure for FMRI */
    268     EMOD_FMRI_VERSION,		/* invalid FMRI scheme version */
    269     EMOD_FMRI_MALFORM,		/* malformed FMRI */
    270     EMOD_NODE_BOUND,		/* node already bound */
    271     EMOD_NODE_DUP,		/* duplicate node */
    272     EMOD_NODE_NOENT,		/* node not found */
    273     EMOD_NODE_RANGE,		/* invalid node range */
    274     EMOD_VER_ABI,		/* registered with invalid ABI version */
    275     EMOD_VER_OLD,		/* attempt to load obsolete module */
    276     EMOD_VER_NEW,		/* attempt to load a newer module */
    277     EMOD_NVL_INVAL,		/* invalid nvlist */
    278     EMOD_NONCANON,		/* non-canonical component name requested */
    279     EMOD_MOD_NOENT,		/* module lookup failed */
    280     EMOD_UKNOWN_ENUM,		/* unknown enumeration error */
    281     EMOD_END			/* end of mod errno list (to ease auto-merge) */
    282 } topo_mod_errno_t;
    283 
    284 extern int topo_mod_seterrno(topo_mod_t *, int);
    285 
    286 #ifdef	__cplusplus
    287 }
    288 #endif
    289 
    290 #endif	/* _TOPO_MOD_H */
    291