| blob | 4035658b01febec4b3bb6d2de32bc3b71c115195 |
1 '\" te
2 .\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH LIBDEVINFO 3LIB "May 15, 2008"
7 .SH NAME
8 libdevinfo \- device information library
9 .SH SYNOPSIS
10 .LP
11 .nf
12 cc [ \fIflag\fR... ] \fIfile\fR... \fB-ldevinfo\fR [ \fIlibrary\fR... ]
13 #include <libdevinfo.h>
14 .fi
16 .SH DESCRIPTION
17 .sp
18 .LP
19 Functions in this library access device configuration information.
20 .sp
21 .LP
22 Device configuration data is organized as a tree of device nodes, defined as
23 \fBdi_node_t\fR in the \fBlibdevinfo\fR interfaces. Each \fBdi_node_t\fR
24 represents a physical or logical (pseudo) device. The types of data associated
25 with device nodes are:
26 .RS +4
27 .TP
28 .ie t \(bu
29 .el o
30 data defined for all device nodes (attributes)
31 .RE
32 .RS +4
33 .TP
34 .ie t \(bu
35 .el o
36 data defined for all multipath path nodes
37 .RE
38 .RS +4
39 .TP
40 .ie t \(bu
41 .el o
42 data defined for all minor node data
43 .RE
44 .RS +4
45 .TP
46 .ie t \(bu
47 .el o
48 properties specific to nodes
49 .RE
50 .sp
51 .LP
52 All device nodes have a set of common attributes, such as a node name, an
53 instance number, and a driver binding name. Common device node attributes are
54 accessed by calling interfaces listed on the \fBdi_binding_name\fR(3DEVINFO)
55 manual page. Each device node also has a physical path, which is accessed by
56 calling \fBdi_devfs_path\fR(3DEVINFO).
57 .sp
58 .LP
59 Properties provide device specific information for device configuration and
60 usage. Properties can be defined by software (\fBdi_prop_t\fR) or by firmware
61 (\fBdi_prom_prop_t\fR). One way to access each \fBdi_prop_t\fR is to make
62 successive calls to \fBdi_prop_next\fR(3DEVINFO) until \fBDI_PROP_NIL\fR is
63 returned. For each \fBdi_prop_t\fR, use interfaces on the
64 \fBdi_prop_bytes\fR(3DEVINFO) manual page to obtain property names and values.
65 Another way to access these properties is to call
66 \fBdi_prop_lookup_bytes\fR(3DEVINFO) to find the value of a property with a
67 given name. Accessing a \fBdi_prom_prop_t\fR is similar to accessing a
68 \fBdi_prop_t\fR, except that the interface names start with \fBdi_prom_prop\fR
69 and additional calls to \fBdi_prom_init\fR(3DEVINFO) and
70 \fBdi_prom_fini\fR(3DEVINFO) are required.
71 .sp
72 .LP
73 Minor nodes contain information exported by the device for creating special
74 files for the device. Each device node has 0 or more minor nodes associated
75 with it. A list of minor nodes (\fBdi_minor_t\fR) can be obtained by making
76 successive calls to \fBdi_minor_next\fR(3DEVINFO) until \fBDI_MINOR_NIL\fR is
77 returned. For each minor node, \fBdi_minor_devt\fR(3DEVINFO) and related
78 interfaces are called to get minor node data.
79 .sp
80 .LP
81 In some configurations, multipath device access via a virtual host controller
82 interface (vHCI) abstraction is possible. An example of a driver using this
83 abstraction is \fBscsi_vhci\fR(7D). In such cases, devices are not directly
84 represented as children of their physical host controller interface (pHCI) bus
85 adapter. Instead, devices have an identity-oriented representation as a child
86 of a vHCI. All paths leading to the same identity are represented by a common
87 child endpoint of the vHCI called the "client" device node. The vHCI
88 virtualizes access among the underlying pHCI physical paths. The underlying
89 connection between vHCI-managed client endpoints and the pHCI paths to that
90 endpoint is represented by a class of nodes called "path" nodes
91 (\fBdi_path_t\fR).
92 .sp
93 .LP
94 Each path node is associated with two device nodes: its pHCI device node, and
95 its client device node. A list of paths associated with a specific pHCI device
96 node can be obtained using \fBdi_path_phci_next_path\fR(3DEVINFO), and a list
97 of paths associated with a specific client device node can be obtained using
98 \fBdi_path_client_next_path\fR(3DEVINFO). These functions return
99 \fBDI_PATH_NIL\fR when the end of the list of path nodes is reached.
100 .sp
101 .LP
102 For each path node, \fBdi_path_state\fR(3DEVINFO) and related interfaces are
103 called to get path node data.
104 .sp
105 .LP
106 Using \fBlibdevinfo\fR involves three steps:
107 .RS +4
108 .TP
109 .ie t \(bu
110 .el o
111 Creating a snapshot of the device tree
112 .RE
113 .RS +4
114 .TP
115 .ie t \(bu
116 .el o
117 Traversing the device tree to get information of interest
118 .RE
119 .RS +4
120 .TP
121 .ie t \(bu
122 .el o
123 Destroying the snapshot of the device tree
124 .RE
125 .sp
126 .LP
127 A snapshot of the device tree is created by calling \fBdi_init\fR(3DEVINFO) and
128 destroyed by calling \fBdi_fini\fR(3DEVINFO). An application can specify the
129 data to be included in the snapshot (full or partial tree, include or exclude
130 properties and minor nodes) and get a handle to the root of the device tree.
131 See \fBdi_init\fR(3DEVINFO) for details. The application then traverses the
132 device tree in the snapshot to obtain device configuration data.
133 .sp
134 .LP
135 The device tree is normally traversed through parent-child-sibling linkage.
136 Each device node contains references to its parent, its next sibling, and the
137 first of its children. Given the \fBdi_node_t\fR returned from \fBdi_init()\fR,
138 one can find all children by first calling \fBdi_child_node\fR(3DEVINFO),
139 followed by successive calls to \fBdi_sibling_node\fR(3DEVINFO) until
140 \fBDI_NODE_NIL\fR is returned. By following this procedure recursively, an
141 application can visit all device nodes contained in the snapshot. Two
142 interfaces,The \fBdi_walk_node\fR(3DEVINFO) and \fBdi_walk_minor\fR(3DEVINFO)
143 functions are provided to facilitate device tree traversal. The
144 \fBdi_walk_node()\fR function visits all device nodes and executes a
145 user-supplied callback function for each node visited. The
146 \fBdi_walk_minor()\fR function does the same for each minor node in the device
147 tree.
148 .sp
149 .LP
150 An alternative way to traverse the device tree is through the per-driver device
151 node linkage. Device nodes contain a reference to the next device node bound to
152 the same driver. Given the \fBdi_node_t\fR returned from \fBdi_init()\fR, an
153 application can find all device nodes bound to a driver by first calling
154 \fBdi_drv_first_node\fR(3DEVINFO), followed by successive calls to
155 \fBdi_drv_next_node\fR(3DEVINFO) until \fBDI_NODE_NIL\fR is returned.
156 Traversing the per-driver device node list works only when the snapshot
157 includes all device nodes.
158 .sp
159 .LP
160 See \fBdi_init\fR(3DEVINFO) for examples of \fBlibdevinfo\fR usage. See
161 \fIWriting Device Drivers\fR for information about Solaris device
162 configuration.
163 .SH INTERFACES
164 .sp
165 .LP
166 The shared object \fBlibdevinfo.so.1\fR provides the public interfaces defined
167 below. See \fBIntro\fR(3) for additional information on shared object
168 interfaces.
169 .sp
171 .sp
172 .TS
173 l l
174 l l .
175 \fBdi_binding_name\fR \fBdi_bus_addr\fR
176 \fBdi_child_node\fR \fBdi_compatible_names\fR
177 \fBdi_devfs_minor_path\fR \fBdi_devfs_path\fR
178 \fBdi_devfs_path_free\fR \fBdi_devid\fR
179 \fBdi_driver_major\fR \fBdi_driver_name\fR
180 \fBdi_driver_ops\fR \fBdi_drv_first_node\fR
181 \fBdi_drv_next_node\fR \fBdi_fini\fR
182 \fBdi_init\fR \fBdi_instance\fR
183 \fBdi_link_next_by_lnode\fR \fBdi_link_next_by_node\fR
184 \fBdi_link_private_get\fR \fBdi_link_private_set\fR
185 \fBdi_link_spectype\fR \fBdi_link_to_lnode\fR
186 \fBdi_lnode_devinfo\fR \fBdi_lnode_devt\fR
187 \fBdi_lnode_name\fR \fBdi_lnode_next\fR
188 \fBdi_lnode_private_get\fR \fBdi_lnode_private_set\fR
189 \fBdi_minor_devt\fR \fBdi_minor_name\fR
190 \fBdi_minor_next\fR \fBdi_minor_nodetype\fR
191 \fBdi_minor_private_get\fR \fBdi_minor_private_set\fR
192 \fBdi_minor_spectype\fR \fBdi_minor_type\fR
193 \fBdi_node_name\fR \fBdi_node_private_get\fR
194 \fBdi_node_private_set\fR \fBdi_nodeid\fR
195 \fBdi_parent_node\fR \fBdi_path_bus_addr\fR
196 \fBdi_path_client_devfs_path\fR \fBdi_path_client_next_path\fR
197 \fBdi_path_client_node\fR \fBdi_path_devfs_path\fR
198 \fBdi_path_instance\fR \fBdi_path_node_name\fR
199 \fBdi_path_phci_next_path\fR \fBdi_path_phci_node\fR
200 \fBdi_path_prop_bytes\fR \fBdi_path_prop_int64s\fR
201 \fBdi_path_prop_ints\fR \fBdi_path_prop_len\fR
202 \fBdi_path_prop_lookup_bytes\fR \fBdi_path_prop_lookup_int64s\fR
203 \fBdi_path_prop_lookup_ints\fR \fBdi_path_prop_lookup_strings\fR
204 \fBdi_path_prop_name\fR \fBdi_path_prop_strings\fR
205 \fBdi_path_prop_next\fR \fBdi_path_prop_type\fR
206 \fBdi_path_state\fR \fBdi_prom_fini\fR
207 \fBdi_prom_init\fR \fBdi_prom_prop_data\fR
208 \fBdi_prom_prop_lookup_bytes\fR \fBdi_prom_prop_lookup_ints\fR
209 \fBdi_prom_prop_lookup_strings\fR \fBdi_prom_prop_name\fR
210 \fBdi_prom_prop_next\fR \fBdi_prop_bytes\fR
211 \fBdi_prop_devt\fR \fBdi_prop_int64\fR
212 \fBdi_prop_ints\fR \fBdi_prop_lookup_bytes\fR
213 \fBdi_prop_lookup_int64\fR \fBdi_prop_lookup_ints\fR
214 \fBdi_prop_lookup_strings\fR \fBdi_prop_name\fR
215 \fBdi_prop_next\fR \fBdi_prop_strings\fR
216 \fBdi_prop_type\fR \fBdi_sibling_node\fR
217 \fBdi_state\fR \fBdi_walk_link\fR
218 \fBdi_walk_lnode\fR \fBdi_walk_minor\fR
219 \fBdi_walk_node\fR
220 .TE
222 .SH EXAMPLES
223 .LP
224 \fBExample 1 \fRInformation accessible through \fBlibdevinfo\fR interfaces
225 .sp
226 .LP
227 The following example illustrates the kind of information accessible through
228 \fBlibdevinfo\fR interfaces for a device node representing a hard disk (sd2):
230 .sp
231 .in +2
232 .nf
233 Attributes
234 node name: sd
235 instance: 2
236 physical path: /sbus@1f,0/espdma@e,8400000/esp@e,8800000/sd@2,0
238 Properties
239 target=2
240 lun=0
242 Minor nodes
243 (disk partition /dev/dsk/c0t2d0s0)
244 name: a
245 dev_t: 0x0080010 (32/16)
246 spectype: IF_BLK (block special)
247 (disk partition /dev/rdsk/c0t2d0s2)
248 name: c,raw
249 dev_t: 0x0080012 (32/18)
250 spectype: IF_CHR (character special)
251 .fi
252 .in -2
253 .sp
255 .SH FILES
256 .sp
257 .ne 2
258 .na
259 \fB\fB/lib/libdevinfo.so.1\fR\fR
260 .ad
261 .sp .6
262 .RS 4n
263 shared object
264 .RE
266 .sp
267 .ne 2
268 .na
269 \fB\fB/usr/lib/64/libdevinfo.so.1\fR\fR
270 .ad
271 .sp .6
272 .RS 4n
273 64-bit shared object
274 .RE
276 .SH ATTRIBUTES
277 .sp
278 .LP
279 See \fBattributes\fR(5) for descriptions of the following attributes:
280 .sp
282 .sp
283 .TS
284 box;
285 c | c
286 l | l .
287 ATTRIBUTE TYPE ATTRIBUTE VALUE
288 Interface Stability Committed
289 _
290 MT-Level Safe
291 .TE
293 .SH SEE ALSO
294 .sp
295 .LP
296 \fBpvs\fR(1), \fBdevlinks\fR(1M), \fBprtconf\fR(1M), \fBIntro\fR(3),
297 \fBdi_binding_name\fR(3DEVINFO), \fBdi_child_node\fR(3DEVINFO),
298 \fBdi_devfs_path\fR(3DEVINFO), \fBdi_init\fR(3DEVINFO),
299 \fBdi_minor_devt\fR(3DEVINFO), \fBdi_minor_next\fR(3DEVINFO),
300 \fBdi_path_bus_addr\fR(3DEVINFO), \fBdi_path_client_next_path\fR(3DEVINFO),
301 \fBdi_path_prop_bytes\fR(3DEVINFO), \fBdi_path_prop_lookup_bytes\fR(3DEVINFO),
302 \fBdi_path_prop_next\fR(3DEVINFO), \fBdi_prom_init\fR(3DEVINFO),
303 \fBdi_prop_bytes\fR(3DEVINFO), \fBdi_prop_lookup_bytes\fR(3DEVINFO),
304 \fBdi_prop_next\fR(3DEVINFO), \fBdi_walk_minor\fR(3DEVINFO),
305 \fBdi_walk_node\fR(3DEVINFO), \fBattributes\fR(5)
306 .sp
307 .LP
308 \fIWriting Device Drivers\fR