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