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