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