xref: /dragonfly/lib/libdevinfo/devinfo.3 (revision 2038fb68) 
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.2 2008/09/30 21:08:10 swildner 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
82The
83.Nm
84library provides access to the kernel's internal device hierarchy
85and to the I/O resource manager.
86The library uses a
87.Xr sysctl 3
88interface to obtain a snapshot of the kernel's state,
89which is then made available to the application.
90.Pp
91Due to the fact that the information may be logically arranged
92in a number of different fashions,
93the library does not attempt to impose any structure on the data.
94.Pp
95Device, resource, and resource manager information is returned in
96data structures defined in
97.In devinfo.h :
98.Bd -literal -offset indent
99struct 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
112struct 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
119struct 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
128The
129.Vt devinfo_handle_t
130values can be used to look up the correspondingly referenced structures.
131.Pp
132.Fn devinfo_init
133takes a snapshot of the kernel's internal device and resource state.
134It returns nonzero
135if after a number of retries a consistent snapshot cannot be obtained.
136.Fn devinfo_init
137must be called before any other functions can be used.
138.Pp
139.Fn devinfo_free
140releases the memory associated with the snapshot.
141Any pointers returned by other functions are invalidated by this,
142and
143.Fn devinfo_init
144must be called again before using any other functions.
145.Pp
146.Fn devinfo_handle_to_device ,
147.Fn devinfo_handle_to_resource
148and
149.Fn devinfo_handle_to_rman
150return pointers to
151.Vt devinfo_dev ,
152.Vt devinfo_res
153and
154.Vt devinfo_rman
155structures respectively based on the
156.Vt devinfo_handle_t
157passed to them.
158These functions can be used to traverse the tree from any node to any
159other node.
160If
161.Fn devinfo_handle_to_device
162is passed the constant
163.Dv DEVINFO_ROOT_DEVICE
164it will return the handle to the root of the device tree.
165.Pp
166.Fn devinfo_foreach_device_child
167invokes its callback argument
168.Fa fn
169on every device which is an immediate child of
170.Fa device .
171The
172.Fa fn
173function is also passed
174.Fa arg ,
175allowing state to be passed to the callback function.
176If
177.Fa fn
178returns a nonzero error value the traversal is halted,
179and
180.Fn devinfo_foreach_device_child
181returns the error value to its caller.
182.Pp
183.Fn devinfo_foreach_device_resource
184invokes its callback argument
185.Fa fn
186on every resource which is owned by
187.Fa device .
188The
189.Fa fn
190function is also passed
191.Fa device
192and
193.Fa arg ,
194allowing state to be passed to the callback function.
195If
196.Fa fn
197returns a nonzero error value the traversal is halted,
198and
199.Fn devinfo_foreach_device_resource
200returns the error value to its caller.
201.Pp
202.Fn devinfo_foreach_rman_resource
203invokes its callback argument
204.Fa fn
205on every resource within the resource manager
206.Fa rman .
207The
208.Fa fn
209function is also passed
210.Fa arg ,
211allowing state to be passed to the callback function.
212If
213.Fa fn
214returns a nonzero error value the traversal is halted,
215and
216.Fn devinfo_foreach_rman_resource
217returns the error value to its caller.
218.Pp
219.Fn devinfo_foreach_rman
220invokes its callback argument
221.Fa fn
222on every resource manager.
223The
224.Fa fn
225function is also passed
226.Fa arg ,
227allowing state to be passed to the callback function.
228If
229.Fa fn
230returns a nonzero error value the traversal is halted,
231and
232.Fn devinfo_foreach_rman
233returns the error value to its caller.
234.Sh SEE ALSO
235.Xr devstat 3
236.Sh HISTORY
237The
238.Nm
239library first appeared in
240.Fx 5.0
241and was imported into
242.Dx 2.1 .
243.Sh AUTHORS
244.An Michael Smith Aq msmith@FreeBSD.org
245.Sh BUGS
246This is the first implementation of the library,
247and the interface is still subject to refinement.
248.Pp
249The interface does not report device classes or drivers,
250making it hard to sort by class or driver.
251