libdevinfo(3lib)

1libdevinfo(3LIB)              Interface Libraries             libdevinfo(3LIB)
2
3
4

NAME

6       libdevinfo - device information library
7

SYNOPSIS

9       cc [ flag... ] file... -ldevinfo [ library... ]
10       #include <libdevinfo.h>
11
12

DESCRIPTION

14       Functions in this library access device configuration information.
15
16
17       Device  configuration  data  is  organized  as  a tree of device nodes,
18       defined as di_node_t in the libdevinfo interfaces. Each di_node_t  rep‐
19       resents  a physical or logical (pseudo) device. The types of data asso‐
20       ciated with device nodes are:
21
22           o      data defined for all device nodes (attributes)
23
24           o      data defined for all multipath path nodes
25
26           o      data defined for all minor node data
27
28           o      properties specific to nodes
29
30
31       All device nodes have a set of common attributes, such as a node  name,
32       an  instance  number,  and  a  driver  binding name. Common device node
33       attributes are accessed by calling interfaces listed  on  the  di_bind‐
34       ing_name(3DEVINFO)  manual  page.  Each device node also has a physical
35       path, which is accessed by calling di_devfs_path(3DEVINFO).
36
37
38       Properties provide device specific information for device configuration
39       and  usage.  Properties  can  be  defined by software (di_prop_t) or by
40       firmware (di_prom_prop_t). One way to access each di_prop_t is to  make
41       successive   calls   to  di_prop_next(3DEVINFO)  until  DI_PROP_NIL  is
42       returned. For each di_prop_t, use interfaces on the di_prop_bytes(3DEV‐
43       INFO)  manual  page to obtain property names and values. Another way to
44       access these properties is to  call  di_prop_lookup_bytes(3DEVINFO)  to
45       find   the  value  of  a  property  with  a  given  name.  Accessing  a
46       di_prom_prop_t is similar to accessing a  di_prop_t,  except  that  the
47       interface  names  start  with  di_prom_prop  and  additional  calls  to
48       di_prom_init(3DEVINFO) and di_prom_fini(3DEVINFO) are required.
49
50
51       Minor nodes contain information exported by  the  device  for  creating
52       special  files  for  the  device.  Each device node has 0 or more minor
53       nodes associated with it. A list of minor  nodes  (di_minor_t)  can  be
54       obtained  by  making  successive calls to di_minor_next(3DEVINFO) until
55       DI_MINOR_NIL is returned. For each minor node,  di_minor_devt(3DEVINFO)
56       and related interfaces are called to get minor node data.
57
58
59       In some configurations, multipath device access via a virtual host con‐
60       troller interface (vHCI) abstraction  is  possible.  An  example  of  a
61       driver  using this abstraction is scsi_vhci(7D). In such cases, devices
62       are not directly represented as children of their  physical  host  con‐
63       troller  interface  (pHCI)  bus adapter. Instead, devices have an iden‐
64       tity-oriented representation as a child of a vHCI. All paths leading to
65       the  same  identity  are  represented by a common child endpoint of the
66       vHCI called the "client" device node. The vHCI virtualizes access among
67       the  underlying  pHCI physical paths. The underlying connection between
68       vHCI-managed client endpoints and the pHCI paths to  that  endpoint  is
69       represented by a class of nodes called "path" nodes (di_path_t).
70
71
72       Each  path  node  is  associated with two device nodes: its pHCI device
73       node, and its client device node. A list of  paths  associated  with  a
74       specific     pHCI     device     node    can    be    obtained    using
75       di_path_phci_next_path(3DEVINFO), and a list of paths associated with a
76       specific     client    device    node    can    be    obtained    using
77       di_path_client_next_path(3DEVINFO). These functions return  DI_PATH_NIL
78       when the end of the list of path nodes is reached.
79
80
81       For  each path node, di_path_state(3DEVINFO) and related interfaces are
82       called to get path node data.
83
84
85       Using libdevinfo involves three steps:
86
87           o      Creating a snapshot of the device tree
88
89           o      Traversing the device tree to get information of interest
90
91           o      Destroying the snapshot of the device tree
92
93
94       A snapshot of the device tree is created by  calling  di_init(3DEVINFO)
95       and  destroyed by calling di_fini(3DEVINFO). An application can specify
96       the data to be included in the snapshot (full or partial tree,  include
97       or  exclude properties and minor nodes) and get a handle to the root of
98       the device tree. See di_init(3DEVINFO)  for  details.  The  application
99       then traverses the device tree in the snapshot to obtain device config‐
100       uration data.
101
102
103       The device tree  is  normally  traversed  through  parent-child-sibling
104       linkage.  Each  device node contains references to its parent, its next
105       sibling, and the first of its children. Given  the  di_node_t  returned
106       from   di_init(),   one   can   find  all  children  by  first  calling
107       di_child_node(3DEVINFO),  followed  by  successive  calls  to   di_sib‐
108       ling_node(3DEVINFO)  until  DI_NODE_NIL  is returned. By following this
109       procedure recursively, an application can visit all device  nodes  con‐
110       tained  in  the snapshot. Two interfaces,The di_walk_node(3DEVINFO) and
111       di_walk_minor(3DEVINFO) functions are  provided  to  facilitate  device
112       tree traversal. The di_walk_node() function visits all device nodes and
113       executes a user-supplied callback function for each node  visited.  The
114       di_walk_minor()  function  does  the  same  for  each minor node in the
115       device tree.
116
117
118       An alternative way to traverse the device  tree  is  through  the  per-
119       driver  device  node  linkage.  Device nodes contain a reference to the
120       next device node bound to the same driver. Given the di_node_t returned
121       from  di_init(),  an  application  can find all device nodes bound to a
122       driver by first calling di_drv_first_node(3DEVINFO), followed  by  suc‐
123       cessive   calls  to  di_drv_next_node(3DEVINFO)  until  DI_NODE_NIL  is
124       returned. Traversing the per-driver device node list  works  only  when
125       the snapshot includes all device nodes.
126
127
128       See  di_init(3DEVINFO)  for  examples  of libdevinfo usage. See Writing
129       Device Drivers for information about Solaris device configuration.
130

INTERFACES

132       The  shared  object  libdevinfo.so.1  provides  the  public  interfaces
133       defined below. See Intro(3) for additional information on shared object
134       interfaces.
135
136
137
138
139       di_binding_name               di_bus_addr
140       di_child_node                 di_compatible_names
141       di_devfs_minor_path           di_devfs_path
142       di_devfs_path_free            di_devid
143       di_driver_major               di_driver_name
144       di_driver_ops                 di_drv_first_node
145       di_drv_next_node              di_fini
146       di_init                       di_instance
147       di_link_next_by_lnode         di_link_next_by_node
148       di_link_private_get           di_link_private_set
149       di_link_spectype              di_link_to_lnode
150       di_lnode_devinfo              di_lnode_devt
151       di_lnode_name                 di_lnode_next
152       di_lnode_private_get          di_lnode_private_set
153       di_minor_devt                 di_minor_name
154       di_minor_next                 di_minor_nodetype
155       di_minor_private_get          di_minor_private_set
156       di_minor_spectype             di_minor_type
157       di_node_name                  di_node_private_get
158       di_node_private_set           di_nodeid
159       di_parent_node                di_path_bus_addr
160       di_path_client_devfs_path     di_path_client_next_path
161       di_path_client_node           di_path_devfs_path
162       di_path_instance              di_path_node_name
163       di_path_phci_next_path        di_path_phci_node
164       di_path_prop_bytes            di_path_prop_int64s
165       di_path_prop_ints             di_path_prop_len
166       di_path_prop_lookup_bytes     di_path_prop_lookup_int64s
167       di_path_prop_lookup_ints      di_path_prop_lookup_strings
168       di_path_prop_name             di_path_prop_strings
169       di_path_prop_next             di_path_prop_type
170       di_path_state                 di_prom_fini
171       di_prom_init                  di_prom_prop_data
172       di_prom_prop_lookup_bytes     di_prom_prop_lookup_ints
173       di_prom_prop_lookup_strings   di_prom_prop_name
174       di_prom_prop_next             di_prop_bytes
175       di_prop_devt                  di_prop_int64
176       di_prop_ints                  di_prop_lookup_bytes
177       di_prop_lookup_int64          di_prop_lookup_ints
178       di_prop_lookup_strings        di_prop_name
179       di_prop_next                  di_prop_strings
180       di_prop_type                  di_sibling_node
181       di_state                      di_walk_link
182       di_walk_lnode                 di_walk_minor
183       di_walk_node
184
185

EXAMPLES

187       Example 1 Information accessible through libdevinfo interfaces
188
189
190       The following example illustrates the kind  of  information  accessible
191       through  libdevinfo  interfaces  for  a device node representing a hard
192       disk (sd2):
193
194
195         Attributes
196             node name:  sd
197             instance:   2
198             physical path:  /sbus@1f,0/espdma@e,8400000/esp@e,8800000/sd@2,0
199
200         Properties
201             target=2
202             lun=0
203
204         Minor nodes
205             (disk partition /dev/dsk/c0t2d0s0)
206                 name:       a
207                 dev_t:      0x0080010 (32/16)
208                 spectype:   IF_BLK (block special)
209             (disk partition /dev/rdsk/c0t2d0s2)
210                 name:       c,raw
211                 dev_t:      0x0080012 (32/18)
212                 spectype:   IF_CHR (character special)
213
214
215

FILES

217       /lib/libdevinfo.so.1
218
219           shared object
220
221
222       /usr/lib/64/libdevinfo.so.1
223
224           64-bit shared object
225
226

ATTRIBUTES

228       See attributes(5) for descriptions of the following attributes:
229
230
231
232
233       ┌─────────────────────────────┬─────────────────────────────┐
234       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
235       ├─────────────────────────────┼─────────────────────────────┤
236       │Availability                 │SUNWcsl, SUNWstatl (32-bit)  │
237       │                             │SUNWcslx (64-bit)            │
238       ├─────────────────────────────┼─────────────────────────────┤
239       │Interface Stability          │Committed                    │
240       ├─────────────────────────────┼─────────────────────────────┤
241       │MT-Level                     │Safe                         │
242       └─────────────────────────────┴─────────────────────────────┘
243