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