xref: /freebsd/lib/libdevinfo/devinfo.3 (revision b52b9d56d4e96089873a75f9e29062eec19fabba) 
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.Aq Pa 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};
105
106struct devinfo_rman {
107    devinfo_handle_t	dm_handle;	/* resource manager handle */
108    u_long		dm_start;	/* resource start */
109    u_long		dm_size;	/* resource size */
110    char		*dm_desc;	/* resource description */
111};
112
113struct devinfo_res {
114    devinfo_handle_t	dr_handle;	/* resource handle */
115    devinfo_handle_t	dr_rman;	/* resource manager handle */
116    devinfo_handle_t	dr_device;	/* owning device */
117    u_long		dr_start;	/* region start */
118    u_long		dr_size;	/* region size */
119};
120.Ed
121.Pp
122The
123.Vt devinfo_handle_t
124values can be used to look up the correspondingly referenced structures.
125.Pp
126.Fn devinfo_init
127takes a snapshot of the kernel's internal device and resource state.
128It returns nonzero
129if after a number of retries a consistent snapshot cannot be obtained.
130.Fn devinfo_init
131must be called before any other functions can be used.
132.Pp
133.Fn devinfo_free
134releases the memory associated with the snapshot.
135Any pointers returned by other functions are invalidated by this,
136and
137.Fn devinfo_init
138must be called again before using any other functions.
139.Pp
140.Fn devinfo_handle_to_device ,
141.Fn devinfo_handle_to_resource
142and
143.Fn devinfo_handle_to_rman
144return pointers to
145.Vt devinfo_dev ,
146.Vt devinfo_res
147and
148.Vt devinfo_rman
149structures respectively based on the
150.Vt devinfo_handle_t
151passed to them.
152These functions can be used to traverse the tree from any node to any
153other node.
154If
155.Fn devinfo_handle_to_device
156is passed the constant
157.Dv DEVINFO_ROOT_DEVICE
158it will return the handle to the root of the device tree.
159.Pp
160.Fn devinfo_foreach_device_child
161invokes its callback argument
162.Fa fn
163on every device which is an immediate child of
164.Fa device .
165.Fa fn
166is also passed
167.Fa arg ,
168allowing state to be passed to the callback function.
169If
170.Fa fn
171returns a nonzero error value the traversal is halted,
172and
173.Fn devinfo_foreach_device_child
174returns the error value to its caller.
175.Pp
176.Fn devinfo_foreach_device_resource
177invokes its callback argument
178.Fa fn
179on every resource which is owned by
180.Fa device .
181.Fa fn
182is also passed
183.Fa device
184and
185.Fa arg ,
186allowing state to be passed to the callback function.
187If
188.Fa fn
189returns a nonzero error value the traversal is halted,
190and
191.Fn devinfo_foreach_device_resource
192returns the error value to its caller.
193.Pp
194.Fn devinfo_foreach_rman_resource
195invokes its callback argument
196.Fa fn
197on every resource within the resource manager
198.Fa rman .
199.Fa fn
200is also passed
201.Fa arg ,
202allowing state to be passed to the callback function.
203If
204.Fa fn
205returns a nonzero error value the traversal is halted,
206and
207.Fn devinfo_foreach_rman_resource
208returns the error value to its caller.
209.Pp
210.Fn devinfo_foreach_rman
211invokes its callback argument
212.Fa fn
213on every resource manager.
214.Fa fn
215is also passed
216.Fa arg ,
217allowing state to be passed to the callback function.
218If
219.Fa fn
220returns a nonzero error value the traversal is halted,
221and
222.Fn devinfo_foreach_rman
223returns the error value to its caller.
224.Sh SEE ALSO
225.Xr devstat 3
226.Sh HISTORY
227The
228.Nm
229library first appeared in
230.Fx 5.0 .
231.Sh AUTHORS
232.An Michael Smith Aq msmith@FreeBSD.org
233.Sh BUGS
234This is the first implementation of the library,
235and the interface is still subject to refinement.
236.Pp
237The interface does not report device classes or drivers,
238making it hard to sort by class or driver.
239