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