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