lib/libdevinfo/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
   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
  82 The
  83 .Nm
  84 library provides access to the kernel's internal device hierarchy
  85 and to the I/O resource manager.
  86 The library uses a
  87 .Xr sysctl 3
  88 interface to obtain a snapshot of the kernel's state,
  89 which is then made available to the application.
  90 .Pp
  91 Due to the fact that the information may be logically arranged
  92 in a number of different fashions,
  93 the library does not attempt to impose any structure on the data.
  94 .Pp
  95 Device, resource, and resource manager information is returned in
  96 data structures defined in
  97 .In devinfo.h :
  98 .Bd -literal -offset indent
  99 struct 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
 112 struct 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
 119 struct 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
 128 The
 129 .Vt devinfo_handle_t
 130 values can be used to look up the correspondingly referenced structures.
 131 .Pp
 132 .Fn devinfo_init
 133 takes a snapshot of the kernel's internal device and resource state.
 134 It returns nonzero
 135 if after a number of retries a consistent snapshot cannot be obtained.
 136 .Fn devinfo_init
 137 must be called before any other functions can be used.
 138 .Pp
 139 .Fn devinfo_free
 140 releases the memory associated with the snapshot.
 141 Any pointers returned by other functions are invalidated by this,
 142 and
 143 .Fn devinfo_init
 144 must be called again before using any other functions.
 145 .Pp
 146 .Fn devinfo_handle_to_device ,
 147 .Fn devinfo_handle_to_resource
 148 and
 149 .Fn devinfo_handle_to_rman
 150 return pointers to
 151 .Vt devinfo_dev ,
 152 .Vt devinfo_res
 153 and
 154 .Vt devinfo_rman
 155 structures respectively based on the
 156 .Vt devinfo_handle_t
 157 passed to them.
 158 These functions can be used to traverse the tree from any node to any
 159 other node.
 160 If
 161 .Fn devinfo_handle_to_device
 162 is passed the constant
 163 .Dv DEVINFO_ROOT_DEVICE
 164 it will return the handle to the root of the device tree.
 165 .Pp
 166 .Fn devinfo_foreach_device_child
 167 invokes its callback argument
 168 .Fa fn
 169 on every device which is an immediate child of
 170 .Fa device .
 171 The
 172 .Fa fn
 173 function is also passed
 174 .Fa arg ,
 175 allowing state to be passed to the callback function.
 176 If
 177 .Fa fn
 178 returns a nonzero error value the traversal is halted,
 179 and
 180 .Fn devinfo_foreach_device_child
 181 returns the error value to its caller.
 182 .Pp
 183 .Fn devinfo_foreach_device_resource
 184 invokes its callback argument
 185 .Fa fn
 186 on every resource which is owned by
 187 .Fa device .
 188 The
 189 .Fa fn
 190 function is also passed
 191 .Fa device
 192 and
 193 .Fa arg ,
 194 allowing state to be passed to the callback function.
 195 If
 196 .Fa fn
 197 returns a nonzero error value the traversal is halted,
 198 and
 199 .Fn devinfo_foreach_device_resource
 200 returns the error value to its caller.
 201 .Pp
 202 .Fn devinfo_foreach_rman_resource
 203 invokes its callback argument
 204 .Fa fn
 205 on every resource within the resource manager
 206 .Fa rman .
 207 The
 208 .Fa fn
 209 function is also passed
 210 .Fa arg ,
 211 allowing state to be passed to the callback function.
 212 If
 213 .Fa fn
 214 returns a nonzero error value the traversal is halted,
 215 and
 216 .Fn devinfo_foreach_rman_resource
 217 returns the error value to its caller.
 218 .Pp
 219 .Fn devinfo_foreach_rman
 220 invokes its callback argument
 221 .Fa fn
 222 on every resource manager.
 223 The
 224 .Fa fn
 225 function is also passed
 226 .Fa arg ,
 227 allowing state to be passed to the callback function.
 228 If
 229 .Fa fn
 230 returns a nonzero error value the traversal is halted,
 231 and
 232 .Fn devinfo_foreach_rman
 233 returns the error value to its caller.
 234 .Sh SEE ALSO
 235 .Xr devstat 3
 236 .Sh HISTORY
 237 The
 238 .Nm
 239 library first appeared in
 240 .Fx 5.0
 241 and was imported into
 242 .Dx 2.1 .
 243 .Sh AUTHORS
 244 .An Michael Smith Aq msmith@FreeBSD.org
 245 .Sh BUGS
 246 This is the first implementation of the library,
 247 and the interface is still subject to refinement.
 248 .Pp
 249 The interface does not report device classes or drivers,
 250 making it hard to sort by class or driver.