| devinfo.3 (a73a3ab56baabfbc4b63c100ee64951a407e9416) | devinfo.3 (09247921e52c4e85ef46e3fbca85382ab6b8cc5c) |
|---|---|
| 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 --- 13 unchanged lines hidden (view full) --- 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 | 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 --- 13 unchanged lines hidden (view full) --- 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 | 30.Os FreeBSD |
| 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 | 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 | 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 | 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]" | 59.Fa "struct devinfo_dev *parent" 60.Fa "int (* fn)(struct devinfo_dev *child, void *arg)" |
| 61.Fa "void *arg" 62.Fc 63.Ft int 64.Fo devinfo_foreach_device_resource 65.Fa "struct devinfo_dev *dev" | 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]" | 66.Fa "int (* fn)(struct devinfo_dev *dev, struct devinfo_res *res, void *arg)" |
| 67.Fa "void *arg" 68.Fc 69.Ft int 70.Fo devinfo_foreach_rman_resource 71.Fa "struct devinfo_rman *rman" | 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]" | 72.Fa "int (* fn)(struct devinfo_res *res, void *arg)" |
| 73.Fa "void *arg" 74.Fc 75.Ft int 76.Fo devinfo_foreach_rman | 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]" | 77.Fa "int (* fn)(struct devinfo_rman *rman, void *arg)" |
| 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 | 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 : | 95datastructures 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 */ | 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 | 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 |
| 128.Vt devinfo_handle_t | 123.Va 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. --- 4 unchanged lines hidden (view full) --- 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 | 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. --- 4 unchanged lines hidden (view full) --- 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 |
| 149return pointers to 150.Vt devinfo_dev , 151.Vt devinfo_res | 144return pointers to 145.Va devinfo_dev , 146.Va devinfo_res |
| 152and | 147and |
| 153.Vt devinfo_rman | 148.Va devinfo_rman |
| 154structures respectively based on the | 149structures respectively based on the |
| 155.Vt devinfo_handle_t | 150.Va 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 | 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 |
| 167.Fa fn | 162.Ar fn |
| 168on every device which is an immediate child of | 163on every device which is an immediate child of |
| 169.Fa device . 170The 171.Fa fn 172function is also passed 173.Fa arg , | 164.Ar device . 165.Ar fn 166is also passed 167.Ar arg , |
| 174allowing state to be passed to the callback function. 175If | 168allowing state to be passed to the callback function. 169If |
| 176.Fa fn | 170.Ar 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 | 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 |
| 182.Fn devinfo_foreach_device_resource | 176.Fr devinfo_foreach_device_resource |
| 183invokes its callback argument | 177invokes its callback argument |
| 184.Fa fn | 178.Ar fn |
| 185on every resource which is owned by | 179on every resource which is owned by |
| 186.Fa device . 187The 188.Fa fn 189function is also passed 190.Fa device | 180.Ar device . 181.Ar fn 182is also passed 183.Ar device |
| 191and | 184and |
| 192.Fa arg , | 185.Ar arg , |
| 193allowing state to be passed to the callback function. 194If | 186allowing state to be passed to the callback function. 187If |
| 195.Fa fn | 188.Ar 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 | 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 |
| 203.Fa fn | 196.Ar fn |
| 204on every resource within the resource manager | 197on every resource within the resource manager |
| 205.Fa rman . 206The 207.Fa fn 208function is also passed 209.Fa arg , | 198.Ar rman . 199.Ar fn 200is also passed 201.Ar arg , |
| 210allowing state to be passed to the callback function. 211If | 202allowing state to be passed to the callback function. 203If |
| 212.Fa fn | 204.Ar 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 | 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 |
| 220.Fa fn | 212.Ar fn |
| 221on every resource manager. | 213on every resource manager. |
| 222The 223.Fa fn 224function is also passed 225.Fa arg , | 214.Ar fn is also passed 215.Ar arg , |
| 226allowing state to be passed to the callback function. 227If | 216allowing state to be passed to the callback function. 217If |
| 228.Fa fn | 218.Ar 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 | 219returns a nonzero error value the traversal is halted, 220and 221.Fn devinfo_foreach_rman 222returns the error value to its caller. 223.Sh SEE ALSO 224.Xr devstat 3 225.Sh HISTORY |
| 236The | |
| 237.Nm | 226.Nm |
| 238library first appeared in 239.Fx 5.0 . | 227first appeared in 228.Os 229version 5.0 |
| 240.Sh AUTHORS 241.An Michael Smith Aq 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. | 230.Sh AUTHORS 231.An Michael Smith Aq msmith@FreeBSD.org 232.Sh BUGS 233This is the first implementation of the library, 234and the interface is still subject to refinement. 235.Pp 236The interface does not report device classes or drivers, 237making it hard to sort by class or driver. |