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