xref: /freebsd/lib/libdevinfo/devinfo.3 (revision 315ee00f) 
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.Dd April 19, 2001
27.Dt DEVINFO 3
28.Os
29.Sh NAME
30.Nm devinfo ,
31.Nm devinfo_init ,
32.Nm devinfo_free ,
33.Nm devinfo_handle_to_device ,
34.Nm devinfo_handle_to_resource ,
35.Nm devinfo_handle_to_rman ,
36.Nm devinfo_foreach_device_child ,
37.Nm devinfo_foreach_device_resource ,
38.Nm devinfo_foreach_rman_resource ,
39.Nm devinfo_foreach_rman
40.Nd device and resource information utility library
41.Sh LIBRARY
42.Lb libdevinfo
43.Sh SYNOPSIS
44.In devinfo.h
45.Ft int
46.Fn devinfo_init "void"
47.Ft void
48.Fn devinfo_free "void"
49.Ft struct devinfo_dev *
50.Fn devinfo_handle_to_device "devinfo_handle_t handle"
51.Ft struct devinfo_res *
52.Fn devinfo_handle_to_resource "devinfo_handle_t handle"
53.Ft struct devinfo_rman *
54.Fn devinfo_handle_to_rman "devinfo_handle_t handle"
55.Ft int
56.Fo devinfo_foreach_device_child
57.Fa "struct devinfo_dev *parent"
58.Fa "int \*[lp]*fn\*[rp]\*[lp]struct devinfo_dev *child, void *arg\*[rp]"
59.Fa "void *arg"
60.Fc
61.Ft int
62.Fo devinfo_foreach_device_resource
63.Fa "struct devinfo_dev *dev"
64.Fa "int \*[lp]*fn\*[rp]\*[lp]struct devinfo_dev *dev, \:struct devinfo_res *res, void *arg\*[rp]"
65.Fa "void *arg"
66.Fc
67.Ft int
68.Fo devinfo_foreach_rman_resource
69.Fa "struct devinfo_rman *rman"
70.Fa "int \*[lp]*fn\*[rp]\*[lp]struct devinfo_res *res, void *arg\*[rp]"
71.Fa "void *arg"
72.Fc
73.Ft int
74.Fo devinfo_foreach_rman
75.Fa "int \*[lp]*fn\*[rp]\*[lp]struct devinfo_rman *rman, void *arg\*[rp]"
76.Fa "void *arg"
77.Fc
78.Sh DESCRIPTION
79The
80.Nm
81library provides access to the kernel's internal device hierarchy
82and to the I/O resource manager.
83The library uses a
84.Xr sysctl 3
85interface to obtain a snapshot of the kernel's state,
86which is then made available to the application.
87.Pp
88Due to the fact that the information may be logically arranged
89in a number of different fashions,
90the library does not attempt to impose any structure on the data.
91.Pp
92Device, resource, and resource manager information is returned in
93data structures defined in
94.In devinfo.h :
95.Bd -literal -offset indent
96struct devinfo_dev {
97    devinfo_handle_t	dd_handle;	/* device handle */
98    devinfo_handle_t	dd_parent;	/* parent handle */
99    char		*dd_name;	/* name of device */
100    char		*dd_desc;	/* device description */
101    char		*dd_drivername;	/* name of attached driver */
102    char		*dd_pnpinfo;	/* pnp info from parent bus */
103    char		*dd_location;	/* Where bus thinks dev at */
104    uint32_t		dd_devflags;	/* API flags */
105    uint16_t		dd_flags;	/* internal dev flags */
106    device_state_t	dd_state;	/* attachment state of dev */
107};
108
109struct devinfo_rman {
110    devinfo_handle_t	dm_handle;	/* resource manager handle */
111    rman_res_t		dm_start;	/* resource start */
112    rman_res_t		dm_size;	/* resource size */
113    char		*dm_desc;	/* resource description */
114};
115
116struct devinfo_res {
117    devinfo_handle_t	dr_handle;	/* resource handle */
118    devinfo_handle_t	dr_rman;	/* resource manager handle */
119    devinfo_handle_t	dr_device;	/* owning device */
120    rman_res_t		dr_start;	/* region start */
121    rman_res_t		dr_size;	/* region size */
122};
123.Ed
124.Pp
125The
126.Vt devinfo_handle_t
127values can be used to look up the correspondingly referenced structures.
128.Pp
129.Fn devinfo_init
130takes a snapshot of the kernel's internal device and resource state.
131It returns nonzero
132if after a number of retries a consistent snapshot cannot be obtained.
133.Fn devinfo_init
134must be called before any other functions can be used.
135.Pp
136.Fn devinfo_free
137releases the memory associated with the snapshot.
138Any pointers returned by other functions are invalidated by this,
139and
140.Fn devinfo_init
141must be called again before using any other functions.
142.Pp
143.Fn devinfo_handle_to_device ,
144.Fn devinfo_handle_to_resource
145and
146.Fn devinfo_handle_to_rman
147return pointers to
148.Vt devinfo_dev ,
149.Vt devinfo_res
150and
151.Vt devinfo_rman
152structures respectively based on the
153.Vt devinfo_handle_t
154passed to them.
155These functions can be used to traverse the tree from any node to any
156other node.
157If
158.Fn devinfo_handle_to_device
159is passed the constant
160.Dv DEVINFO_ROOT_DEVICE
161it will return the handle to the root of the device tree.
162.Pp
163.Fn devinfo_foreach_device_child
164invokes its callback argument
165.Fa fn
166on every device which is an immediate child of
167.Fa device .
168The
169.Fa fn
170function is also passed
171.Fa arg ,
172allowing state to be passed to the callback function.
173If
174.Fa fn
175returns a nonzero error value the traversal is halted,
176and
177.Fn devinfo_foreach_device_child
178returns the error value to its caller.
179.Pp
180.Fn devinfo_foreach_device_resource
181invokes its callback argument
182.Fa fn
183on every resource which is owned by
184.Fa device .
185The
186.Fa fn
187function is also passed
188.Fa device
189and
190.Fa arg ,
191allowing state to be passed to the callback function.
192If
193.Fa fn
194returns a nonzero error value the traversal is halted,
195and
196.Fn devinfo_foreach_device_resource
197returns the error value to its caller.
198.Pp
199.Fn devinfo_foreach_rman_resource
200invokes its callback argument
201.Fa fn
202on every resource within the resource manager
203.Fa rman .
204The
205.Fa fn
206function is also passed
207.Fa arg ,
208allowing state to be passed to the callback function.
209If
210.Fa fn
211returns a nonzero error value the traversal is halted,
212and
213.Fn devinfo_foreach_rman_resource
214returns the error value to its caller.
215.Pp
216.Fn devinfo_foreach_rman
217invokes its callback argument
218.Fa fn
219on every resource manager.
220The
221.Fa fn
222function is also passed
223.Fa arg ,
224allowing state to be passed to the callback function.
225If
226.Fa fn
227returns a nonzero error value the traversal is halted,
228and
229.Fn devinfo_foreach_rman
230returns the error value to its caller.
231.Sh SEE ALSO
232.Xr devstat 3
233.Sh HISTORY
234The
235.Nm
236library first appeared in
237.Fx 5.0 .
238.Sh AUTHORS
239.An Michael Smith Aq Mt msmith@FreeBSD.org
240.Sh BUGS
241This is the first implementation of the library,
242and the interface is still subject to refinement.
243.Pp
244The interface does not report device classes or drivers,
245making it hard to sort by class or driver.
246