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.Fd #include <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