xref: /titanic_41/usr/src/lib/fm/topo/libtopo/common/libtopo.h (revision 264a6e7478846334593be7663fb6b1a8f37784a0)
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 2006 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 
27 #ifndef _LIBTOPO_H
28 #define	_LIBTOPO_H
29 
30 #pragma ident	"%Z%%M%	%I%	%E% SMI"
31 
32 #include <sys/nvpair.h>
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 #define	TOPO_VERSION	1	/* Library ABI Interface Version */
39 
40 typedef struct topo_hdl topo_hdl_t;
41 typedef struct topo_node tnode_t;
42 typedef struct topo_walk topo_walk_t;
43 typedef int32_t topo_instance_t;
44 typedef uint32_t topo_version_t;
45 
46 /*
47  * Topo stability attributes
48  *
49  * Each topology node advertises the name and data stability of each of its
50  * modules and properties. (see attributes(5))
51  */
52 
53 typedef enum topo_stability {
54 	TOPO_STABILITY_INTERNAL = 0,	/* private to libtopo */
55 	TOPO_STABILITY_PRIVATE,		/* private to Sun */
56 	TOPO_STABILITY_OBSOLETE,	/* scheduled for removal */
57 	TOPO_STABILITY_EXTERNAL,	/* not controlled by Sun */
58 	TOPO_STABILITY_UNSTABLE,	/* new or rapidly changing */
59 	TOPO_STABILITY_EVOLVING,	/* less rapidly changing */
60 	TOPO_STABILITY_STABLE,		/* mature interface from Sun */
61 	TOPO_STABILITY_STANDARD,	/* industry standard */
62 	TOPO_STABILITY_MAX		/* end */
63 } topo_stability_t;
64 
65 #define	TOPO_STABILITY_MAX   TOPO_STABILITY_STANDARD /* max valid stability */
66 
67 typedef enum {
68 	TOPO_TYPE_INVALID = 0,
69 	TOPO_TYPE_BOOLEAN,	/* boolean */
70 	TOPO_TYPE_INT32,	/* int32_t */
71 	TOPO_TYPE_UINT32,	/* uint32_t */
72 	TOPO_TYPE_INT64,	/* int64_t */
73 	TOPO_TYPE_UINT64,	/* uint64_t */
74 	TOPO_TYPE_STRING,	/* const char* */
75 	TOPO_TYPE_TIME,		/* uint64_t */
76 	TOPO_TYPE_SIZE,		/* uint64_t */
77 	TOPO_TYPE_FMRI		/* nvlist_t */
78 } topo_type_t;
79 
80 typedef int (*topo_walk_cb_t)(topo_hdl_t *, tnode_t *, void *);
81 
82 extern topo_hdl_t *topo_open(int, const char *, int *);
83 extern void topo_close(topo_hdl_t *);
84 extern char *topo_snap_hold(topo_hdl_t *, const char *, int *);
85 extern void topo_snap_release(topo_hdl_t *);
86 extern topo_walk_t *topo_walk_init(topo_hdl_t *, const char *, topo_walk_cb_t,
87     void *, int *);
88 extern int topo_walk_step(topo_walk_t *, int);
89 extern void topo_walk_fini(topo_walk_t *);
90 
91 #define	TOPO_WALK_ERR		-1
92 #define	TOPO_WALK_NEXT		0
93 #define	TOPO_WALK_TERMINATE	1
94 
95 #define	TOPO_WALK_CHILD		0x0001
96 #define	TOPO_WALK_SIBLING	0x0002
97 
98 extern int topo_fmri_present(topo_hdl_t *, nvlist_t *, int *);
99 extern int topo_fmri_contains(topo_hdl_t *, nvlist_t *, nvlist_t *, int *);
100 extern int topo_fmri_unusable(topo_hdl_t *, nvlist_t *, int *);
101 extern int topo_fmri_nvl2str(topo_hdl_t *, nvlist_t *, char **, int *);
102 extern int topo_fmri_str2nvl(topo_hdl_t *, const char *, nvlist_t **, int *);
103 extern int topo_fmri_asru(topo_hdl_t *, nvlist_t *, nvlist_t **, int *);
104 extern int topo_fmri_fru(topo_hdl_t *, nvlist_t *, nvlist_t **,
105     int *);
106 extern int topo_fmri_compare(topo_hdl_t *, nvlist_t *, nvlist_t *, int *);
107 extern int topo_fmri_invoke(topo_hdl_t *, nvlist_t *, topo_walk_cb_t, void *,
108     int *);
109 extern nvlist_t *topo_fmri_create(topo_hdl_t *, const char *, const char *,
110     topo_instance_t, nvlist_t *, int *);
111 
112 /*
113  * Topo node utilities: callable from topo_walk_step() callback or module
114  * enumeration, topo_mod_enumerate()
115  */
116 extern char *topo_node_name(tnode_t *);
117 extern topo_instance_t topo_node_instance(tnode_t *);
118 extern void *topo_node_private(tnode_t *);
119 extern int topo_node_asru(tnode_t *, nvlist_t **, nvlist_t *, int *);
120 extern int topo_node_fru(tnode_t *, nvlist_t **, nvlist_t *, int *);
121 extern int topo_node_resource(tnode_t *, nvlist_t **, int *);
122 extern int topo_node_label(tnode_t *, char **, int *);
123 extern int topo_node_asru_set(tnode_t *node, nvlist_t *, int, int *);
124 extern int topo_node_fru_set(tnode_t *node, nvlist_t *, int, int *);
125 extern int topo_node_label_set(tnode_t *node, char *, int *);
126 extern int topo_method_invoke(tnode_t *node, const char *, topo_version_t,
127     nvlist_t *, nvlist_t **, int *);
128 
129 extern int topo_pgroup_create(tnode_t *, const char *, topo_stability_t, int *);
130 extern void topo_pgroup_destroy(tnode_t *, const char *);
131 extern int topo_prop_get_int32(tnode_t *, const char *, const char *,
132     int32_t *, int *);
133 extern int topo_prop_get_uint32(tnode_t *, const char *, const char *,
134     uint32_t *, int *);
135 extern int topo_prop_get_int64(tnode_t *, const char *, const char *,
136     int64_t *, int *);
137 extern int topo_prop_get_uint64(tnode_t *, const char *, const char *,
138     uint64_t *, int *);
139 extern int topo_prop_get_string(tnode_t *, const char *, const char *,
140     char **, int *);
141 extern int topo_prop_get_fmri(tnode_t *, const char *, const char *,
142     nvlist_t **, int *);
143 extern int topo_prop_set_int32(tnode_t *, const char *, const char *, int,
144     int32_t, int *);
145 extern int topo_prop_set_uint32(tnode_t *, const char *, const char *, int,
146     uint32_t, int *);
147 extern int topo_prop_set_int64(tnode_t *, const char *, const char *,
148     int, int64_t, int *);
149 extern int topo_prop_set_uint64(tnode_t *, const char *, const char *,
150     int, uint64_t, int *);
151 extern int topo_prop_set_string(tnode_t *, const char *, const char *,
152     int, const char *, int *);
153 extern int topo_prop_set_fmri(tnode_t *, const char *, const char *,
154     int, const nvlist_t *, int *);
155 extern int topo_prop_stability(tnode_t *, const char *, topo_stability_t *);
156 extern nvlist_t *topo_prop_get_all(topo_hdl_t *, tnode_t *);
157 extern int topo_prop_inherit(tnode_t *, const char *, const char *, int *);
158 
159 #define	TOPO_PROP_SET_ONCE	0
160 #define	TOPO_PROP_SET_MULTIPLE	1
161 
162 #define	TOPO_ASRU_COMPUTE	0x0001  /* Compute ASRU dynamically */
163 #define	TOPO_FRU_COMPUTE	0x0002  /* Compute FRU dynamically */
164 
165 /* Protocol property group and property names */
166 #define	TOPO_PGROUP_PROTOCOL	"protocol"	/* Required property group */
167 #define	TOPO_PROP_RESOURCE	"resource"	/* resource FMRI */
168 #define	TOPO_PROP_ASRU		"ASRU"		/* ASRU FMRI */
169 #define	TOPO_PROP_FRU		"FRU"		/* FRU FMRI */
170 #define	TOPO_PROP_MOD		"module"	/* software module FMRI */
171 #define	TOPO_PROP_PKG		"package"	/* software package FMRI */
172 #define	TOPO_PROP_LABEL		"label"		/*  property LABEL */
173 
174 /*
175  * Legacy TOPO property group: this group supports legacy platform.topo
176  * property names
177  */
178 #define	TOPO_PGROUP_LEGACY	"legacy"	/* Legacy property group */
179 #define	TOPO_PROP_PLATASRU	"PLAT-ASRU"
180 #define	TOPO_PROP_PLATFRU	"PLAT-FRU"
181 
182 /*
183  * System property group
184  */
185 #define	TOPO_PGROUP_SYSTEM	"system"
186 #define	TOPO_PROP_PLATFORM	"platform"
187 #define	TOPO_PROP_ISA		"isa"
188 #define	TOPO_PROP_MACHINE	"machine"
189 
190 /* Property node NVL names */
191 #define	TOPO_PROP_GROUP		"property-group"
192 #define	TOPO_PROP_GROUP_NAME	"property-group-name"
193 #define	TOPO_PROP_VAL		"property"
194 #define	TOPO_PROP_VAL_NAME	"property-name"
195 #define	TOPO_PROP_VAL_VAL	"property-value"
196 
197 extern const char *topo_strerror(int);
198 extern void topo_debug_set(topo_hdl_t *, int, char *);
199 extern void *topo_hdl_alloc(topo_hdl_t *, size_t);
200 extern void *topo_hdl_zalloc(topo_hdl_t *, size_t);
201 extern void topo_hdl_free(topo_hdl_t *, void *, size_t);
202 extern int topo_hdl_nvalloc(topo_hdl_t *, nvlist_t **, uint_t);
203 extern int topo_hdl_nvdup(topo_hdl_t *, nvlist_t *, nvlist_t **);
204 extern char *topo_hdl_strdup(topo_hdl_t *, const char *);
205 extern void topo_hdl_strfree(topo_hdl_t *, char *);
206 
207 #define	TOPO_DBG_ERR	0x0001	/* enable error handling debug messages */
208 #define	TOPO_DBG_MOD	0x0002	/* enable module subsystem debug messages */
209 #define	TOPO_DBG_LOG	0x0004	/* enable log subsystem debug messages */
210 #define	TOPO_DBG_WALK	0x0008	/* enable walker subsystem debug messages */
211 #define	TOPO_DBG_TREE	0x0010	/* enable tree subsystem debug messages */
212 #define	TOPO_DBG_ALL	0xffff	/* enable all debug modes */
213 
214 #ifdef __cplusplus
215 }
216 #endif
217 
218 #endif /* _LIBTOPO_H */
219