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 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 u_long dm_start; /* resource start */ 114 u_long 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 u_long dr_start; /* region start */ 123 u_long 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 . 170.Fa fn 171is also passed 172.Fa arg , 173allowing state to be passed to the callback function. 174If 175.Fa fn 176returns a nonzero error value the traversal is halted, 177and 178.Fn devinfo_foreach_device_child 179returns the error value to its caller. 180.Pp 181.Fn devinfo_foreach_device_resource 182invokes its callback argument 183.Fa fn 184on every resource which is owned by 185.Fa device . 186.Fa fn 187is also passed 188.Fa device 189and 190.Fa arg , 191allowing state to be passed to the callback function. 192If 193.Fa fn 194returns a nonzero error value the traversal is halted, 195and 196.Fn devinfo_foreach_device_resource 197returns the error value to its caller. 198.Pp 199.Fn devinfo_foreach_rman_resource 200invokes its callback argument 201.Fa fn 202on every resource within the resource manager 203.Fa rman . 204.Fa fn 205is also passed 206.Fa arg , 207allowing state to be passed to the callback function. 208If 209.Fa fn 210returns a nonzero error value the traversal is halted, 211and 212.Fn devinfo_foreach_rman_resource 213returns the error value to its caller. 214.Pp 215.Fn devinfo_foreach_rman 216invokes its callback argument 217.Fa fn 218on every resource manager. 219.Fa fn 220is also passed 221.Fa arg , 222allowing state to be passed to the callback function. 223If 224.Fa fn 225returns a nonzero error value the traversal is halted, 226and 227.Fn devinfo_foreach_rman 228returns the error value to its caller. 229.Sh SEE ALSO 230.Xr devstat 3 231.Sh HISTORY 232The 233.Nm 234library first appeared in 235.Fx 5.0 . 236.Sh AUTHORS 237.An Michael Smith Aq msmith@FreeBSD.org 238.Sh BUGS 239This is the first implementation of the library, 240and the interface is still subject to refinement. 241.Pp 242The interface does not report device classes or drivers, 243making it hard to sort by class or driver. 244