xref: /illumos-gate/usr/src/lib/libdevinfo/libdevinfo.h (revision 602ca9ea8f9ce0933f0944601cc5d230e91a950d)
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  * Copyright 2008 Sun Microsystems, Inc.  All rights reserved.
23  * Use is subject to license terms.
24  */
25 
26 #ifndef	_LIBDEVINFO_H
27 #define	_LIBDEVINFO_H
28 
29 #pragma ident	"%Z%%M%	%I%	%E% SMI"
30 
31 #ifdef	__cplusplus
32 extern "C" {
33 #endif
34 
35 #include <errno.h>
36 #include <libnvpair.h>
37 #include <sys/param.h>
38 #include <sys/sunddi.h>
39 #include <sys/sunmdi.h>
40 #include <sys/openpromio.h>
41 #include <sys/ddi_impldefs.h>
42 #include <sys/devinfo_impl.h>
43 #include <limits.h>
44 
45 /*
46  * flags for di_walk_node
47  */
48 #define	DI_WALK_CLDFIRST	0
49 #define	DI_WALK_SIBFIRST	1
50 #define	DI_WALK_LINKGEN		2
51 
52 #define	DI_WALK_MASK		0xf
53 
54 /*
55  * flags for di_walk_link
56  */
57 #define	DI_LINK_SRC		1
58 #define	DI_LINK_TGT		2
59 
60 /*
61  * return code for node_callback
62  */
63 #define	DI_WALK_CONTINUE	0
64 #define	DI_WALK_PRUNESIB	-1
65 #define	DI_WALK_PRUNECHILD	-2
66 #define	DI_WALK_TERMINATE	-3
67 
68 /*
69  * flags for di_walk_minor
70  */
71 #define	DI_CHECK_ALIAS		0x10
72 #define	DI_CHECK_INTERNAL_PATH	0x20
73 
74 #define	DI_CHECK_MASK		0xf0
75 
76 /* nodeid types */
77 #define	DI_PSEUDO_NODEID	-1
78 #define	DI_SID_NODEID		-2
79 #define	DI_PROM_NODEID		-3
80 
81 /* node & device states */
82 #define	DI_DRIVER_DETACHED	0x8000
83 #define	DI_DEVICE_OFFLINE	0x1
84 #define	DI_DEVICE_DOWN		0x2
85 #define	DI_BUS_QUIESCED		0x100
86 #define	DI_BUS_DOWN		0x200
87 
88 /* property types */
89 #define	DI_PROP_TYPE_BOOLEAN	0
90 #define	DI_PROP_TYPE_INT	1
91 #define	DI_PROP_TYPE_STRING	2
92 #define	DI_PROP_TYPE_BYTE	3
93 #define	DI_PROP_TYPE_UNKNOWN	4
94 #define	DI_PROP_TYPE_UNDEF_IT	5
95 #define	DI_PROP_TYPE_INT64	6
96 
97 /* private macro for checking if a prop type is valid */
98 #define	DI_PROP_TYPE_VALID(type) \
99 	((((type) >= DI_PROP_TYPE_INT) && ((type) <= DI_PROP_TYPE_BYTE)) || \
100 	    ((type) == DI_PROP_TYPE_INT64))
101 
102 /* opaque handles */
103 typedef struct di_node		*di_node_t;		/* node */
104 typedef struct di_minor		*di_minor_t;		/* minor_node */
105 typedef struct di_path		*di_path_t;		/* path_node */
106 typedef struct di_link		*di_link_t;		/* link */
107 typedef struct di_lnode		*di_lnode_t;		/* endpoint */
108 typedef struct di_devlink	*di_devlink_t;		/* devlink */
109 
110 typedef struct di_prop		*di_prop_t;		/* node property */
111 typedef struct di_path_prop	*di_path_prop_t;	/* path property */
112 typedef struct di_prom_prop	*di_prom_prop_t;	/* prom property */
113 
114 typedef struct di_prom_handle	*di_prom_handle_t;	/* prom snapshot */
115 typedef struct di_devlink_handle *di_devlink_handle_t;	/* devlink snapshot */
116 
117 
118 /*
119  * Null handles to make handles really opaque
120  */
121 #define	DI_NODE_NIL		NULL
122 #define	DI_MINOR_NIL		NULL
123 #define	DI_PATH_NIL		NULL
124 #define	DI_LINK_NIL		NULL
125 #define	DI_LNODE_NIL		NULL
126 #define	DI_PROP_NIL		NULL
127 #define	DI_PROM_PROP_NIL	NULL
128 #define	DI_PROM_HANDLE_NIL	NULL
129 
130 /*
131  * IEEE 1275 properties and other standardized property names
132  */
133 #define	DI_PROP_FIRST_CHAS	"first-in-chassis"
134 #define	DI_PROP_SLOT_NAMES	"slot-names"
135 #define	DI_PROP_PHYS_SLOT	"physical-slot#"
136 #define	DI_PROP_DEV_TYPE	"device_type"
137 #define	DI_PROP_BUS_RANGE	"bus-range"
138 #define	DI_PROP_SERID		"serialid#"
139 #define	DI_PROP_REG		"reg"
140 #define	DI_PROP_AP_NAMES	"ap-names"
141 
142 /* Interface Prototypes */
143 
144 /*
145  * Snapshot initialization and cleanup
146  */
147 extern di_node_t	di_init(const char *phys_path, uint_t flag);
148 extern void		di_fini(di_node_t root);
149 
150 /*
151  * node: traversal, data access, and parameters
152  */
153 extern int		di_walk_node(di_node_t root, uint_t flag, void *arg,
154 			    int (*node_callback)(di_node_t node, void *arg));
155 
156 extern di_node_t	di_drv_first_node(const char *drv_name, di_node_t root);
157 extern di_node_t	di_drv_next_node(di_node_t node);
158 
159 extern di_node_t	di_parent_node(di_node_t node);
160 extern di_node_t	di_sibling_node(di_node_t node);
161 extern di_node_t	di_child_node(di_node_t node);
162 
163 extern char		*di_node_name(di_node_t node);
164 extern char		*di_bus_addr(di_node_t node);
165 extern char		*di_binding_name(di_node_t node);
166 extern int		di_compatible_names(di_node_t, char **names);
167 extern int		di_instance(di_node_t node);
168 extern int		di_nodeid(di_node_t node);
169 extern int		di_driver_major(di_node_t node);
170 extern uint_t		di_state(di_node_t node);
171 extern ddi_node_state_t	di_node_state(di_node_t node);
172 extern ddi_devid_t	di_devid(di_node_t node);
173 extern char		*di_driver_name(di_node_t node);
174 extern uint_t		di_driver_ops(di_node_t node);
175 
176 extern void		di_node_private_set(di_node_t node, void *data);
177 extern void		*di_node_private_get(di_node_t node);
178 
179 extern char		*di_devfs_path(di_node_t node);
180 extern char		*di_devfs_minor_path(di_minor_t minor);
181 extern void		di_devfs_path_free(char *path_buf);
182 
183 /*
184  * path_node: traversal, data access, and parameters
185  */
186 extern di_path_t	di_path_phci_next_path(di_node_t node, di_path_t);
187 extern di_path_t	di_path_client_next_path(di_node_t node, di_path_t);
188 
189 extern di_node_t	di_path_phci_node(di_path_t path);
190 extern di_node_t	di_path_client_node(di_path_t path);
191 
192 extern char		*di_path_node_name(di_path_t path);
193 extern char		*di_path_bus_addr(di_path_t path);
194 extern int		di_path_instance(di_path_t path);
195 extern di_path_state_t	di_path_state(di_path_t path);
196 
197 extern char		*di_path_devfs_path(di_path_t path);
198 extern char		*di_path_client_devfs_path(di_path_t path);
199 
200 extern void		di_path_private_set(di_path_t path, void *data);
201 extern void		*di_path_private_get(di_path_t path);
202 
203 /*
204  * minor_node: traversal, data access, and parameters
205  */
206 extern int		di_walk_minor(di_node_t root, const char *minortype,
207 			    uint_t flag, void *arg,
208 			    int (*minor_callback)(di_node_t node,
209 			    di_minor_t minor, void *arg));
210 extern di_minor_t	di_minor_next(di_node_t node, di_minor_t minor);
211 
212 extern di_node_t	di_minor_devinfo(di_minor_t minor);
213 extern ddi_minor_type	di_minor_type(di_minor_t minor);
214 extern char		*di_minor_name(di_minor_t minor);
215 extern dev_t		di_minor_devt(di_minor_t minor);
216 extern int		di_minor_spectype(di_minor_t minor);
217 extern char		*di_minor_nodetype(di_minor_t node);
218 
219 extern void		di_minor_private_set(di_minor_t minor, void *data);
220 extern void		*di_minor_private_get(di_minor_t minor);
221 
222 /*
223  * node: property access
224  */
225 extern di_prop_t	di_prop_next(di_node_t node, di_prop_t prop);
226 
227 extern char		*di_prop_name(di_prop_t prop);
228 extern int		di_prop_type(di_prop_t prop);
229 extern dev_t		di_prop_devt(di_prop_t prop);
230 
231 extern int		di_prop_ints(di_prop_t prop, int **prop_data);
232 extern int		di_prop_int64(di_prop_t prop, int64_t **prop_data);
233 extern int		di_prop_strings(di_prop_t prop, char **prop_data);
234 extern int		di_prop_bytes(di_prop_t prop, uchar_t **prop_data);
235 
236 extern int		di_prop_lookup_bytes(dev_t dev, di_node_t node,
237 			    const char *prop_name, uchar_t **prop_data);
238 extern int		di_prop_lookup_ints(dev_t dev, di_node_t node,
239 			    const char *prop_name, int **prop_data);
240 extern int		di_prop_lookup_int64(dev_t dev, di_node_t node,
241 			    const char *prop_name, int64_t **prop_data);
242 extern int		di_prop_lookup_strings(dev_t dev, di_node_t node,
243 			    const char *prop_name, char **prop_data);
244 
245 /*
246  * prom_node: property access
247  */
248 extern di_prom_handle_t	di_prom_init(void);
249 extern void		di_prom_fini(di_prom_handle_t ph);
250 
251 extern di_prom_prop_t	di_prom_prop_next(di_prom_handle_t ph, di_node_t node,
252 			    di_prom_prop_t prom_prop);
253 
254 extern char		*di_prom_prop_name(di_prom_prop_t prom_prop);
255 extern int		di_prom_prop_data(di_prom_prop_t prop,
256 			    uchar_t **prom_prop_data);
257 
258 extern int		di_prom_prop_lookup_ints(di_prom_handle_t prom,
259 			    di_node_t node, const char *prom_prop_name,
260 			    int **prom_prop_data);
261 extern int		di_prom_prop_lookup_strings(di_prom_handle_t prom,
262 			    di_node_t node, const char *prom_prop_name,
263 			    char **prom_prop_data);
264 extern int		di_prom_prop_lookup_bytes(di_prom_handle_t prom,
265 			    di_node_t node, const char *prom_prop_name,
266 			    uchar_t **prom_prop_data);
267 
268 /*
269  * path_node: property access
270  */
271 extern di_path_prop_t	di_path_prop_next(di_path_t path, di_path_prop_t prop);
272 
273 extern char		*di_path_prop_name(di_path_prop_t prop);
274 extern int		di_path_prop_type(di_path_prop_t prop);
275 extern int		di_path_prop_len(di_path_prop_t prop);
276 
277 extern int		di_path_prop_bytes(di_path_prop_t prop,
278 			    uchar_t **prop_data);
279 extern int		di_path_prop_ints(di_path_prop_t prop,
280 			    int **prop_data);
281 extern int		di_path_prop_int64s(di_path_prop_t prop,
282 			    int64_t **prop_data);
283 extern int		di_path_prop_strings(di_path_prop_t prop,
284 			    char **prop_data);
285 
286 extern int		di_path_prop_lookup_bytes(di_path_t path,
287 			    const char *prop_name, uchar_t **prop_data);
288 extern int		di_path_prop_lookup_ints(di_path_t path,
289 			    const char *prop_name, int **prop_data);
290 extern int		di_path_prop_lookup_int64s(di_path_t path,
291 			    const char *prop_name, int64_t **prop_data);
292 extern int		di_path_prop_lookup_strings(di_path_t path,
293 			    const char *prop_name, char **prop_data);
294 
295 /*
296  * layering link/lnode: traversal, data access, and parameters
297  */
298 extern int		di_walk_link(di_node_t root, uint_t flag,
299 			    uint_t endpoint, void *arg,
300 			    int (*link_callback)(di_link_t link, void *arg));
301 extern int		di_walk_lnode(di_node_t root, uint_t flag, void *arg,
302 			    int (*lnode_callback)(di_lnode_t lnode, void *arg));
303 
304 extern di_link_t	di_link_next_by_node(di_node_t node,
305 			    di_link_t link, uint_t endpoint);
306 extern di_link_t	di_link_next_by_lnode(di_lnode_t lnode,
307 			    di_link_t link, uint_t endpoint);
308 extern di_lnode_t	di_lnode_next(di_node_t node, di_lnode_t lnode);
309 extern char		*di_lnode_name(di_lnode_t lnode);
310 
311 extern int		di_link_spectype(di_link_t link);
312 extern di_lnode_t	di_link_to_lnode(di_link_t link, uint_t endpoint);
313 
314 extern di_node_t	di_lnode_devinfo(di_lnode_t lnode);
315 extern int		di_lnode_devt(di_lnode_t lnode, dev_t *devt);
316 
317 extern void		di_link_private_set(di_link_t link, void *data);
318 extern void		*di_link_private_get(di_link_t link);
319 extern void		di_lnode_private_set(di_lnode_t lnode, void *data);
320 extern void		*di_lnode_private_get(di_lnode_t lnode);
321 
322 
323 /*
324  * Private interfaces
325  *
326  * The interfaces and structures below are private to this implementation
327  * of Solaris and are subject to change at any time without notice.
328  *
329  * Applications and drivers using these interfaces may fail
330  * to run on future releases.
331  */
332 extern di_prop_t di_prop_find(dev_t match_dev, di_node_t node,
333     const char *name);
334 extern int di_devfs_path_match(const char *dp1, const char *dp2);
335 
336 extern di_node_t	di_vhci_first_node(di_node_t root);
337 extern di_node_t	di_vhci_next_node(di_node_t node);
338 extern di_node_t	di_phci_first_node(di_node_t vhci_node);
339 extern di_node_t	di_phci_next_node(di_node_t node);
340 
341 /*
342  * Interfaces for handling IEEE 1275 and other standardized properties
343  */
344 
345 /* structure for a single slot */
346 typedef struct di_slot_name {
347 	int num;	/* corresponding pci device number */
348 	char *name;
349 } di_slot_name_t;
350 
351 extern void di_slot_names_free(int count, di_slot_name_t *slot_names);
352 extern int di_slot_names_decode(uchar_t *rawdata, int rawlen,
353     di_slot_name_t **prop_data);
354 extern int di_prop_slot_names(di_prop_t prop, di_slot_name_t **prop_data);
355 extern int di_prom_prop_slot_names(di_prom_prop_t prom_prop,
356     di_slot_name_t **prop_data);
357 extern int di_prop_lookup_slot_names(dev_t dev, di_node_t node,
358     di_slot_name_t **prop_data);
359 extern int di_prom_prop_lookup_slot_names(di_prom_handle_t ph, di_node_t node,
360     di_slot_name_t **prop_data);
361 
362 /*
363  * XXX Remove the private di_path_(addr,next,next_phci,next_client) interfaces
364  * below after NWS consolidation switches to using di_path_bus_addr,
365  * di_path_phci_next_path, and di_path_client_next_path per CR6638521.
366  */
367 extern char *di_path_addr(di_path_t path, char *buf);
368 extern di_path_t di_path_next(di_node_t node, di_path_t path);
369 extern di_path_t di_path_next_phci(di_node_t node, di_path_t path);
370 extern di_path_t di_path_next_client(di_node_t node, di_path_t path);
371 
372 /*
373  * Interfaces for private data
374  */
375 extern di_node_t di_init_driver(const char *drv_name, uint_t flag);
376 extern di_node_t di_init_impl(const char *phys_path, uint_t flag,
377     struct di_priv_data *priv_data);
378 
379 /*
380  * Prtconf needs to know property lists, raw prop_data, and private data
381  */
382 extern di_prop_t di_prop_drv_next(di_node_t node, di_prop_t prop);
383 extern di_prop_t di_prop_sys_next(di_node_t node, di_prop_t prop);
384 extern di_prop_t di_prop_global_next(di_node_t node, di_prop_t prop);
385 extern di_prop_t di_prop_hw_next(di_node_t node, di_prop_t prop);
386 
387 extern int di_prop_rawdata(di_prop_t prop, uchar_t **prop_data);
388 extern void *di_parent_private_data(di_node_t node);
389 extern void *di_driver_private_data(di_node_t node);
390 
391 /*
392  * The value of the dip's devi_flags field
393  */
394 uint_t di_flags(di_node_t node);
395 
396 /*
397  * Types of links for devlink lookup
398  */
399 #define	DI_PRIMARY_LINK		0x01
400 #define	DI_SECONDARY_LINK	0x02
401 #define	DI_LINK_TYPES		0x03
402 
403 /*
404  * Flag for di_devlink_init()
405  */
406 #define	DI_MAKE_LINK	0x01
407 
408 /*
409  * Flag for di_devlink_close()
410  */
411 #define	DI_LINK_ERROR	0x01
412 
413 /*
414  * For devfsadm synchronous link creation interfaces
415  */
416 #define	DEVFSADM_SYNCH_DOOR	".devfsadm_synch_door"
417 
418 /*
419  * devlink create argument
420  */
421 struct dca_off {
422 	uint32_t	dca_root;
423 	uint32_t	dca_minor;
424 	uint32_t	dca_driver;
425 	int		dca_error;
426 	int		dca_flags;
427 	char		dca_name[PATH_MAX+MAXNAMELEN];
428 };
429 
430 extern di_devlink_handle_t di_devlink_init(const char *name, uint_t flags);
431 extern int di_devlink_walk(di_devlink_handle_t hdl, const char *re,
432     const char *minor_path, uint_t flags, void *arg,
433     int (*devlink_callback)(di_devlink_t, void *));
434 extern const char *di_devlink_path(di_devlink_t devlink);
435 extern const char *di_devlink_content(di_devlink_t devlink);
436 extern int di_devlink_type(di_devlink_t devlink);
437 extern di_devlink_t di_devlink_dup(di_devlink_t devlink);
438 extern int di_devlink_free(di_devlink_t devlink);
439 extern int di_devlink_fini(di_devlink_handle_t *hdlp);
440 
441 extern di_devlink_handle_t di_devlink_open(const char *root_dir, uint_t flags);
442 extern int di_devlink_close(di_devlink_handle_t *pp, int flag);
443 extern int di_devlink_rm_link(di_devlink_handle_t hdp, const char *link);
444 extern int di_devlink_add_link(di_devlink_handle_t hdp, const char *link,
445     const char *content, int flags);
446 extern int di_devlink_update(di_devlink_handle_t hdp);
447 extern di_devlink_handle_t di_devlink_init_root(const char *root,
448     const char *name, uint_t flags);
449 extern int di_devlink_cache_walk(di_devlink_handle_t hdp, const char *re,
450     const char *path, uint_t flags, void *arg,
451     int (*devlink_callback)(di_devlink_t, void *));
452 
453 /*
454  * Private interfaces for I/O retire
455  */
456 typedef struct di_retire {
457 	void	*rt_hdl;
458 	void	(*rt_abort)(void *hdl, const char *format, ...);
459 	void	(*rt_debug)(void *hdl, const char *format, ...);
460 } di_retire_t;
461 
462 extern int di_retire_device(char *path, di_retire_t *dp, int flags);
463 extern int di_unretire_device(char *path, di_retire_t *dp);
464 extern uint_t di_retired(di_node_t node);
465 
466 /*
467  * Private interfaces for /etc/logindevperm
468  */
469 extern int di_devperm_login(const char *, uid_t, gid_t, void (*)(char *));
470 extern int di_devperm_logout(const char *);
471 
472 /*
473  * Private interface for looking up, by path string, a node/path/minor
474  * in a snapshot.
475  */
476 extern di_path_t di_lookup_path(di_node_t root, char *path);
477 extern di_node_t di_lookup_node(di_node_t root, char *path);
478 
479 /*
480  * Private hotplug interfaces to be used between cfgadm pci plugin and
481  * devfsadm link generator.
482  */
483 extern char *di_dli_name(char *);
484 extern int di_dli_openr(char *);
485 extern int di_dli_openw(char *);
486 extern void di_dli_close(int);
487 
488 /*
489  * Private interface for parsing devname binding info
490  */
491 extern void di_devname_print_mapinfo(nvlist_t *);
492 extern int di_devname_get_mapinfo(char *, nvlist_t **);
493 extern int di_devname_get_mapent(char *, char *, nvlist_t **);
494 extern int di_devname_action_on_key(nvlist_t *, uint8_t, char *, void *);
495 
496 /*
497  * Private interface for parsing path_to_inst binding file
498  */
499 extern int devfs_parse_binding_file(const char *,
500 	int (*)(void *, const char *, int, const char *), void *);
501 extern int devfs_walk_minor_nodes(const char *,
502 	int (*)(void *, const char *), void *);
503 
504 /*
505  * finddev - alternate readdir to discover only /dev persisted device names
506  */
507 typedef struct __finddevhdl *finddevhdl_t;
508 
509 extern int		device_exists(const char *);
510 extern int		finddev_readdir(const char *, finddevhdl_t *);
511 extern int		finddev_emptydir(const char *);
512 extern void		finddev_close(finddevhdl_t);
513 extern const char	*finddev_next(finddevhdl_t);
514 
515 
516 /*
517  * Private interfaces for non-global /dev profile
518  */
519 typedef struct __di_prof	*di_prof_t;
520 
521 extern int	di_prof_init(const char *mountpt, di_prof_t *);
522 extern void	di_prof_fini(di_prof_t);
523 extern int	di_prof_commit(di_prof_t);
524 extern int	di_prof_add_dev(di_prof_t, const char *);
525 extern int	di_prof_add_exclude(di_prof_t, const char *);
526 extern int	di_prof_add_symlink(di_prof_t, const char *, const char *);
527 extern int	di_prof_add_map(di_prof_t, const char *, const char *);
528 
529 /*
530  * Private interfaces for <driver><instance><minor> to path conversion.
531  * NOTE: These interfaces do not require or cause attach.  The implementation
532  * uses the kernel instance-tree (/etc/path_to_inst) and the di_devlinks
533  * database information.
534  */
535 typedef struct __di_dim	*di_dim_t;
536 
537 extern di_dim_t	di_dim_init();
538 extern void	di_dim_fini(di_dim_t);
539 extern char	*di_dim_path_devices(di_dim_t,
540 		    char *drv_name, int instance, char *minor_name);
541 extern char	*di_dim_path_dev(di_dim_t,
542 		    char *drv_name, int instance, char *minor_name);
543 
544 
545 #ifdef	__cplusplus
546 }
547 #endif
548 
549 #endif	/* _LIBDEVINFO_H */
550