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