10010e23aSHasso Tepper.\" 20010e23aSHasso Tepper.\" Copyright (c) 2001 Michael Smith <msmith@FreeBSD.org> 30010e23aSHasso Tepper.\" All rights reserved. 40010e23aSHasso Tepper.\" 50010e23aSHasso Tepper.\" Redistribution and use in source and binary forms, with or without 60010e23aSHasso Tepper.\" modification, are permitted provided that the following conditions 70010e23aSHasso Tepper.\" are met: 80010e23aSHasso Tepper.\" 1. Redistributions of source code must retain the above copyright 90010e23aSHasso Tepper.\" notice, this list of conditions and the following disclaimer. 100010e23aSHasso Tepper.\" 2. Redistributions in binary form must reproduce the above copyright 110010e23aSHasso Tepper.\" notice, this list of conditions and the following disclaimer in the 120010e23aSHasso Tepper.\" documentation and/or other materials provided with the distribution. 130010e23aSHasso Tepper.\" 140010e23aSHasso Tepper.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 150010e23aSHasso Tepper.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 160010e23aSHasso Tepper.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 170010e23aSHasso Tepper.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 180010e23aSHasso Tepper.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 190010e23aSHasso Tepper.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 200010e23aSHasso Tepper.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 210010e23aSHasso Tepper.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 220010e23aSHasso Tepper.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 230010e23aSHasso Tepper.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 240010e23aSHasso Tepper.\" SUCH DAMAGE. 250010e23aSHasso Tepper.\" 260010e23aSHasso Tepper.\" $FreeBSD: src/lib/libdevinfo/devinfo.3,v 1.11 2006/09/17 21:27:35 ru Exp $ 270010e23aSHasso Tepper.\" 28*feaf0601SSascha Wildner.Dd June 27, 2021 290010e23aSHasso Tepper.Dt DEVINFO 3 300010e23aSHasso Tepper.Os 310010e23aSHasso Tepper.Sh NAME 320010e23aSHasso Tepper.Nm devinfo , 330010e23aSHasso Tepper.Nm devinfo_init , 340010e23aSHasso Tepper.Nm devinfo_free , 350010e23aSHasso Tepper.Nm devinfo_handle_to_device , 360010e23aSHasso Tepper.Nm devinfo_handle_to_resource , 370010e23aSHasso Tepper.Nm devinfo_handle_to_rman , 380010e23aSHasso Tepper.Nm devinfo_foreach_device_child , 390010e23aSHasso Tepper.Nm devinfo_foreach_device_resource , 400010e23aSHasso Tepper.Nm devinfo_foreach_rman_resource , 410010e23aSHasso Tepper.Nm devinfo_foreach_rman 420010e23aSHasso Tepper.Nd device and resource information utility library 430010e23aSHasso Tepper.Sh LIBRARY 440010e23aSHasso Tepper.Lb libdevinfo 450010e23aSHasso Tepper.Sh SYNOPSIS 460010e23aSHasso Tepper.In devinfo.h 470010e23aSHasso Tepper.Ft int 480010e23aSHasso Tepper.Fn devinfo_init "void" 490010e23aSHasso Tepper.Ft void 500010e23aSHasso Tepper.Fn devinfo_free "void" 510010e23aSHasso Tepper.Ft struct devinfo_dev * 520010e23aSHasso Tepper.Fn devinfo_handle_to_device "devinfo_handle_t handle" 530010e23aSHasso Tepper.Ft struct devinfo_res * 540010e23aSHasso Tepper.Fn devinfo_handle_to_resource "devinfo_handle_t handle" 550010e23aSHasso Tepper.Ft struct devinfo_rman * 560010e23aSHasso Tepper.Fn devinfo_handle_to_rman "devinfo_handle_t handle" 570010e23aSHasso Tepper.Ft int 580010e23aSHasso Tepper.Fo devinfo_foreach_device_child 590010e23aSHasso Tepper.Fa "struct devinfo_dev *parent" 601ddb9fd2SFranco Fichtner.Fa "int (*fn)(struct devinfo_dev *child, void *arg)" 610010e23aSHasso Tepper.Fa "void *arg" 620010e23aSHasso Tepper.Fc 630010e23aSHasso Tepper.Ft int 640010e23aSHasso Tepper.Fo devinfo_foreach_device_resource 650010e23aSHasso Tepper.Fa "struct devinfo_dev *dev" 661ddb9fd2SFranco Fichtner.Fa "int (*fn)(struct devinfo_dev *dev, \:struct devinfo_res *res, \:void *arg)" 670010e23aSHasso Tepper.Fa "void *arg" 680010e23aSHasso Tepper.Fc 690010e23aSHasso Tepper.Ft int 700010e23aSHasso Tepper.Fo devinfo_foreach_rman_resource 710010e23aSHasso Tepper.Fa "struct devinfo_rman *rman" 721ddb9fd2SFranco Fichtner.Fa "int (*fn)(struct devinfo_res *res, void *arg)" 730010e23aSHasso Tepper.Fa "void *arg" 740010e23aSHasso Tepper.Fc 750010e23aSHasso Tepper.Ft int 760010e23aSHasso Tepper.Fo devinfo_foreach_rman 771ddb9fd2SFranco Fichtner.Fa "int (*fn)(struct devinfo_rman *rman, void *arg)" 780010e23aSHasso Tepper.Fa "void *arg" 790010e23aSHasso Tepper.Fc 800010e23aSHasso Tepper.Sh DESCRIPTION 810010e23aSHasso TepperThe 820010e23aSHasso Tepper.Nm 830010e23aSHasso Tepperlibrary provides access to the kernel's internal device hierarchy 840010e23aSHasso Tepperand to the I/O resource manager. 850010e23aSHasso TepperThe library uses a 860010e23aSHasso Tepper.Xr sysctl 3 870010e23aSHasso Tepperinterface to obtain a snapshot of the kernel's state, 880010e23aSHasso Tepperwhich is then made available to the application. 890010e23aSHasso Tepper.Pp 900010e23aSHasso TepperDue to the fact that the information may be logically arranged 910010e23aSHasso Tepperin a number of different fashions, 920010e23aSHasso Tepperthe library does not attempt to impose any structure on the data. 930010e23aSHasso Tepper.Pp 940010e23aSHasso TepperDevice, resource, and resource manager information is returned in 950010e23aSHasso Tepperdata structures defined in 960010e23aSHasso Tepper.In devinfo.h : 970010e23aSHasso Tepper.Bd -literal -offset indent 980010e23aSHasso Tepperstruct devinfo_dev { 990010e23aSHasso Tepper devinfo_handle_t dd_handle; /* device handle */ 1000010e23aSHasso Tepper devinfo_handle_t dd_parent; /* parent handle */ 1010010e23aSHasso Tepper char *dd_name; /* name of device */ 1020010e23aSHasso Tepper char *dd_desc; /* device description */ 1030010e23aSHasso Tepper char *dd_drivername; /* name of attached driver */ 1040010e23aSHasso Tepper char *dd_pnpinfo; /* pnp info from parent bus */ 1050010e23aSHasso Tepper char *dd_location; /* Where bus thinks dev at */ 1060010e23aSHasso Tepper uint32_t dd_devflags; /* API flags */ 1070010e23aSHasso Tepper uint16_t dd_flags; /* internal dev flags */ 108*feaf0601SSascha Wildner devinfo_state_t dd_state; /* attachment state of dev */ 1090010e23aSHasso Tepper}; 1100010e23aSHasso Tepper 1110010e23aSHasso Tepperstruct devinfo_rman { 1120010e23aSHasso Tepper devinfo_handle_t dm_handle; /* resource manager handle */ 1130010e23aSHasso Tepper u_long dm_start; /* resource start */ 1140010e23aSHasso Tepper u_long dm_size; /* resource size */ 1150010e23aSHasso Tepper char *dm_desc; /* resource description */ 1160010e23aSHasso Tepper}; 1170010e23aSHasso Tepper 1180010e23aSHasso Tepperstruct devinfo_res { 1190010e23aSHasso Tepper devinfo_handle_t dr_handle; /* resource handle */ 1200010e23aSHasso Tepper devinfo_handle_t dr_rman; /* resource manager handle */ 1210010e23aSHasso Tepper devinfo_handle_t dr_device; /* owning device */ 1220010e23aSHasso Tepper u_long dr_start; /* region start */ 1230010e23aSHasso Tepper u_long dr_size; /* region size */ 1240010e23aSHasso Tepper}; 1250010e23aSHasso Tepper.Ed 1260010e23aSHasso Tepper.Pp 1270010e23aSHasso TepperThe 1280010e23aSHasso Tepper.Vt devinfo_handle_t 1290010e23aSHasso Teppervalues can be used to look up the correspondingly referenced structures. 1300010e23aSHasso Tepper.Pp 1310010e23aSHasso Tepper.Fn devinfo_init 1320010e23aSHasso Teppertakes a snapshot of the kernel's internal device and resource state. 1330010e23aSHasso TepperIt returns nonzero 1340010e23aSHasso Tepperif after a number of retries a consistent snapshot cannot be obtained. 1350010e23aSHasso Tepper.Fn devinfo_init 1360010e23aSHasso Teppermust be called before any other functions can be used. 1370010e23aSHasso Tepper.Pp 1380010e23aSHasso Tepper.Fn devinfo_free 1390010e23aSHasso Tepperreleases the memory associated with the snapshot. 1400010e23aSHasso TepperAny pointers returned by other functions are invalidated by this, 1410010e23aSHasso Tepperand 1420010e23aSHasso Tepper.Fn devinfo_init 1430010e23aSHasso Teppermust be called again before using any other functions. 1440010e23aSHasso Tepper.Pp 1450010e23aSHasso Tepper.Fn devinfo_handle_to_device , 1460010e23aSHasso Tepper.Fn devinfo_handle_to_resource 1470010e23aSHasso Tepperand 1480010e23aSHasso Tepper.Fn devinfo_handle_to_rman 1490010e23aSHasso Tepperreturn pointers to 1500010e23aSHasso Tepper.Vt devinfo_dev , 1510010e23aSHasso Tepper.Vt devinfo_res 1520010e23aSHasso Tepperand 1530010e23aSHasso Tepper.Vt devinfo_rman 1540010e23aSHasso Tepperstructures respectively based on the 1550010e23aSHasso Tepper.Vt devinfo_handle_t 1560010e23aSHasso Tepperpassed to them. 1570010e23aSHasso TepperThese functions can be used to traverse the tree from any node to any 1580010e23aSHasso Tepperother node. 1590010e23aSHasso TepperIf 1600010e23aSHasso Tepper.Fn devinfo_handle_to_device 1610010e23aSHasso Tepperis passed the constant 1620010e23aSHasso Tepper.Dv DEVINFO_ROOT_DEVICE 1630010e23aSHasso Tepperit will return the handle to the root of the device tree. 1640010e23aSHasso Tepper.Pp 1650010e23aSHasso Tepper.Fn devinfo_foreach_device_child 1660010e23aSHasso Tepperinvokes its callback argument 1670010e23aSHasso Tepper.Fa fn 1680010e23aSHasso Tepperon every device which is an immediate child of 1690010e23aSHasso Tepper.Fa device . 1700010e23aSHasso TepperThe 1710010e23aSHasso Tepper.Fa fn 1720010e23aSHasso Tepperfunction is also passed 1730010e23aSHasso Tepper.Fa arg , 1740010e23aSHasso Tepperallowing state to be passed to the callback function. 1750010e23aSHasso TepperIf 1760010e23aSHasso Tepper.Fa fn 1770010e23aSHasso Tepperreturns a nonzero error value the traversal is halted, 1780010e23aSHasso Tepperand 1790010e23aSHasso Tepper.Fn devinfo_foreach_device_child 1800010e23aSHasso Tepperreturns the error value to its caller. 1810010e23aSHasso Tepper.Pp 1820010e23aSHasso Tepper.Fn devinfo_foreach_device_resource 1830010e23aSHasso Tepperinvokes its callback argument 1840010e23aSHasso Tepper.Fa fn 1850010e23aSHasso Tepperon every resource which is owned by 1860010e23aSHasso Tepper.Fa device . 1870010e23aSHasso TepperThe 1880010e23aSHasso Tepper.Fa fn 1890010e23aSHasso Tepperfunction is also passed 1900010e23aSHasso Tepper.Fa device 1910010e23aSHasso Tepperand 1920010e23aSHasso Tepper.Fa arg , 1930010e23aSHasso Tepperallowing state to be passed to the callback function. 1940010e23aSHasso TepperIf 1950010e23aSHasso Tepper.Fa fn 1960010e23aSHasso Tepperreturns a nonzero error value the traversal is halted, 1970010e23aSHasso Tepperand 1980010e23aSHasso Tepper.Fn devinfo_foreach_device_resource 1990010e23aSHasso Tepperreturns the error value to its caller. 2000010e23aSHasso Tepper.Pp 2010010e23aSHasso Tepper.Fn devinfo_foreach_rman_resource 2020010e23aSHasso Tepperinvokes its callback argument 2030010e23aSHasso Tepper.Fa fn 2040010e23aSHasso Tepperon every resource within the resource manager 2050010e23aSHasso Tepper.Fa rman . 2060010e23aSHasso TepperThe 2070010e23aSHasso Tepper.Fa fn 2080010e23aSHasso Tepperfunction is also passed 2090010e23aSHasso Tepper.Fa arg , 2100010e23aSHasso Tepperallowing state to be passed to the callback function. 2110010e23aSHasso TepperIf 2120010e23aSHasso Tepper.Fa fn 2130010e23aSHasso Tepperreturns a nonzero error value the traversal is halted, 2140010e23aSHasso Tepperand 2150010e23aSHasso Tepper.Fn devinfo_foreach_rman_resource 2160010e23aSHasso Tepperreturns the error value to its caller. 2170010e23aSHasso Tepper.Pp 2180010e23aSHasso Tepper.Fn devinfo_foreach_rman 2190010e23aSHasso Tepperinvokes its callback argument 2200010e23aSHasso Tepper.Fa fn 2210010e23aSHasso Tepperon every resource manager. 2220010e23aSHasso TepperThe 2230010e23aSHasso Tepper.Fa fn 2240010e23aSHasso Tepperfunction is also passed 2250010e23aSHasso Tepper.Fa arg , 2260010e23aSHasso Tepperallowing state to be passed to the callback function. 2270010e23aSHasso TepperIf 2280010e23aSHasso Tepper.Fa fn 2290010e23aSHasso Tepperreturns a nonzero error value the traversal is halted, 2300010e23aSHasso Tepperand 2310010e23aSHasso Tepper.Fn devinfo_foreach_rman 2320010e23aSHasso Tepperreturns the error value to its caller. 2330010e23aSHasso Tepper.Sh SEE ALSO 2340010e23aSHasso Tepper.Xr devstat 3 2350010e23aSHasso Tepper.Sh HISTORY 2360010e23aSHasso TepperThe 2370010e23aSHasso Tepper.Nm 2380010e23aSHasso Tepperlibrary first appeared in 2390010e23aSHasso Tepper.Fx 5.0 2400010e23aSHasso Tepperand was imported into 2410f6d4e8bSSascha Wildner.Dx 2.1 . 2420010e23aSHasso Tepper.Sh AUTHORS 24398b3d9adSFranco Fichtner.An Michael Smith Aq Mt msmith@FreeBSD.org 2440010e23aSHasso Tepper.Sh BUGS 2450010e23aSHasso TepperThis is the first implementation of the library, 2460010e23aSHasso Tepperand the interface is still subject to refinement. 2470010e23aSHasso Tepper.Pp 2480010e23aSHasso TepperThe interface does not report device classes or drivers, 2490010e23aSHasso Teppermaking it hard to sort by class or driver. 250