The devinfo(3) library provides userspace access to the internal device
[dragonfly.git] / lib / libdevinfo / devinfo.3
1 .\"
2 .\" Copyright (c) 2001 Michael Smith <msmith@FreeBSD.org>
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\"    notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\"    notice, this list of conditions and the following disclaimer in the
12 .\"    documentation and/or other materials provided with the distribution.
13 .\"
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24 .\" SUCH DAMAGE.
25 .\"
26 .\" $FreeBSD: src/lib/libdevinfo/devinfo.3,v 1.11 2006/09/17 21:27:35 ru Exp $
27 .\" $DragonFly: src/lib/libdevinfo/devinfo.3,v 1.1 2008/09/30 12:20:29 hasso Exp $
28 .\"
29 .Dd September 30, 2008
30 .Dt DEVINFO 3
31 .Os
32 .Sh NAME
33 .Nm devinfo ,
34 .Nm devinfo_init ,
35 .Nm devinfo_free ,
36 .Nm devinfo_handle_to_device ,
37 .Nm devinfo_handle_to_resource ,
38 .Nm devinfo_handle_to_rman ,
39 .Nm devinfo_foreach_device_child ,
40 .Nm devinfo_foreach_device_resource ,
41 .Nm devinfo_foreach_rman_resource ,
42 .Nm devinfo_foreach_rman
43 .Nd device and resource information utility library
44 .Sh LIBRARY
45 .Lb libdevinfo
46 .Sh SYNOPSIS
47 .In devinfo.h
48 .Ft int
49 .Fn devinfo_init "void"
50 .Ft void
51 .Fn devinfo_free "void"
52 .Ft struct devinfo_dev *
53 .Fn devinfo_handle_to_device "devinfo_handle_t handle"
54 .Ft struct devinfo_res *
55 .Fn devinfo_handle_to_resource "devinfo_handle_t handle"
56 .Ft struct devinfo_rman *
57 .Fn devinfo_handle_to_rman "devinfo_handle_t handle"
58 .Ft int
59 .Fo devinfo_foreach_device_child
60 .Fa "struct devinfo_dev *parent"
61 .Fa "int \*[lp]*fn\*[rp]\*[lp]struct devinfo_dev *child, void *arg\*[rp]"
62 .Fa "void *arg"
63 .Fc
64 .Ft int
65 .Fo devinfo_foreach_device_resource
66 .Fa "struct devinfo_dev *dev"
67 .Fa "int \*[lp]*fn\*[rp]\*[lp]struct devinfo_dev *dev, \:struct devinfo_res *res, void *arg\*[rp]"
68 .Fa "void *arg"
69 .Fc
70 .Ft int
71 .Fo devinfo_foreach_rman_resource
72 .Fa "struct devinfo_rman *rman"
73 .Fa "int \*[lp]*fn\*[rp]\*[lp]struct devinfo_res *res, void *arg\*[rp]"
74 .Fa "void *arg"
75 .Fc
76 .Ft int
77 .Fo devinfo_foreach_rman
78 .Fa "int \*[lp]*fn\*[rp]\*[lp]struct devinfo_rman *rman, void *arg\*[rp]"
79 .Fa "void *arg"
80 .Fc
81 .Sh DESCRIPTION
82 The
83 .Nm
84 library provides access to the kernel's internal device hierarchy
85 and to the I/O resource manager.
86 The library uses a
87 .Xr sysctl 3
88 interface to obtain a snapshot of the kernel's state,
89 which is then made available to the application.
90 .Pp
91 Due to the fact that the information may be logically arranged
92 in a number of different fashions,
93 the library does not attempt to impose any structure on the data.
94 .Pp
95 Device, resource, and resource manager information is returned in
96 data structures defined in
97 .In devinfo.h :
98 .Bd -literal -offset indent
99 struct devinfo_dev {
100     devinfo_handle_t    dd_handle;      /* device handle */
101     devinfo_handle_t    dd_parent;      /* parent handle */
102     char                *dd_name;       /* name of device */
103     char                *dd_desc;       /* device description */
104     char                *dd_drivername; /* name of attached driver */
105     char                *dd_pnpinfo;    /* pnp info from parent bus */
106     char                *dd_location;   /* Where bus thinks dev at */
107     uint32_t            dd_devflags;    /* API flags */
108     uint16_t            dd_flags;       /* internal dev flags */
109     device_state_t      dd_state;       /* attachment state of dev */
110 };
111
112 struct devinfo_rman {
113     devinfo_handle_t    dm_handle;      /* resource manager handle */
114     u_long              dm_start;       /* resource start */
115     u_long              dm_size;        /* resource size */
116     char                *dm_desc;       /* resource description */
117 };
118
119 struct devinfo_res {
120     devinfo_handle_t    dr_handle;      /* resource handle */
121     devinfo_handle_t    dr_rman;        /* resource manager handle */
122     devinfo_handle_t    dr_device;      /* owning device */
123     u_long              dr_start;       /* region start */
124     u_long              dr_size;        /* region size */
125 };
126 .Ed
127 .Pp
128 The
129 .Vt devinfo_handle_t
130 values can be used to look up the correspondingly referenced structures.
131 .Pp
132 .Fn devinfo_init
133 takes a snapshot of the kernel's internal device and resource state.
134 It returns nonzero
135 if after a number of retries a consistent snapshot cannot be obtained.
136 .Fn devinfo_init
137 must be called before any other functions can be used.
138 .Pp
139 .Fn devinfo_free
140 releases the memory associated with the snapshot.
141 Any pointers returned by other functions are invalidated by this,
142 and
143 .Fn devinfo_init
144 must be called again before using any other functions.
145 .Pp
146 .Fn devinfo_handle_to_device ,
147 .Fn devinfo_handle_to_resource
148 and
149 .Fn devinfo_handle_to_rman
150 return pointers to
151 .Vt devinfo_dev ,
152 .Vt devinfo_res
153 and
154 .Vt devinfo_rman
155 structures respectively based on the
156 .Vt devinfo_handle_t
157 passed to them.
158 These functions can be used to traverse the tree from any node to any
159 other node.
160 If
161 .Fn devinfo_handle_to_device
162 is passed the constant
163 .Dv DEVINFO_ROOT_DEVICE
164 it will return the handle to the root of the device tree.
165 .Pp
166 .Fn devinfo_foreach_device_child
167 invokes its callback argument
168 .Fa fn
169 on every device which is an immediate child of
170 .Fa device .
171 The
172 .Fa fn
173 function is also passed
174 .Fa arg ,
175 allowing state to be passed to the callback function.
176 If
177 .Fa fn
178 returns a nonzero error value the traversal is halted,
179 and
180 .Fn devinfo_foreach_device_child
181 returns the error value to its caller.
182 .Pp
183 .Fn devinfo_foreach_device_resource
184 invokes its callback argument
185 .Fa fn
186 on every resource which is owned by
187 .Fa device .
188 The
189 .Fa fn
190 function is also passed
191 .Fa device
192 and
193 .Fa arg ,
194 allowing state to be passed to the callback function.
195 If
196 .Fa fn
197 returns a nonzero error value the traversal is halted,
198 and
199 .Fn devinfo_foreach_device_resource
200 returns the error value to its caller.
201 .Pp
202 .Fn devinfo_foreach_rman_resource
203 invokes its callback argument
204 .Fa fn
205 on every resource within the resource manager
206 .Fa rman .
207 The
208 .Fa fn
209 function is also passed
210 .Fa arg ,
211 allowing state to be passed to the callback function.
212 If
213 .Fa fn
214 returns a nonzero error value the traversal is halted,
215 and
216 .Fn devinfo_foreach_rman_resource
217 returns the error value to its caller.
218 .Pp
219 .Fn devinfo_foreach_rman
220 invokes its callback argument
221 .Fa fn
222 on every resource manager.
223 The
224 .Fa fn
225 function is also passed
226 .Fa arg ,
227 allowing state to be passed to the callback function.
228 If
229 .Fa fn
230 returns a nonzero error value the traversal is halted,
231 and
232 .Fn devinfo_foreach_rman
233 returns the error value to its caller.
234 .Sh SEE ALSO
235 .Xr devstat 3
236 .Sh HISTORY
237 The
238 .Nm
239 library first appeared in
240 .Fx 5.0
241 and was imported into
242 .Dx 1.11 .
243 .Sh AUTHORS
244 .An Michael Smith Aq msmith@FreeBSD.org
245 .Sh BUGS
246 This is the first implementation of the library,
247 and the interface is still subject to refinement.
248 .Pp
249 The interface does not report device classes or drivers,
250 making it hard to sort by class or driver.