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 .Dd April 19, 2001
  27 .Dt DEVINFO 3
  28 .Os
  29 .Sh NAME
  30 .Nm devinfo ,
  31 .Nm devinfo_init ,
  32 .Nm devinfo_free ,
  33 .Nm devinfo_handle_to_device ,
  34 .Nm devinfo_handle_to_resource ,
  35 .Nm devinfo_handle_to_rman ,
  36 .Nm devinfo_foreach_device_child ,
  37 .Nm devinfo_foreach_device_resource ,
  38 .Nm devinfo_foreach_rman_resource ,
  39 .Nm devinfo_foreach_rman
  40 .Nd device and resource information utility library
  41 .Sh LIBRARY
  42 .Lb libdevinfo
  43 .Sh SYNOPSIS
  44 .In devinfo.h
  45 .Ft int
  46 .Fn devinfo_init "void"
  47 .Ft void
  48 .Fn devinfo_free "void"
  49 .Ft struct devinfo_dev *
  50 .Fn devinfo_handle_to_device "devinfo_handle_t handle"
  51 .Ft struct devinfo_res *
  52 .Fn devinfo_handle_to_resource "devinfo_handle_t handle"
  53 .Ft struct devinfo_rman *
  54 .Fn devinfo_handle_to_rman "devinfo_handle_t handle"
  55 .Ft int
  56 .Fo devinfo_foreach_device_child
  57 .Fa "struct devinfo_dev *parent"
  58 .Fa "int \*[lp]*fn\*[rp]\*[lp]struct devinfo_dev *child, void *arg\*[rp]"
  59 .Fa "void *arg"
  60 .Fc
  61 .Ft int
  62 .Fo devinfo_foreach_device_resource
  63 .Fa "struct devinfo_dev *dev"
  64 .Fa "int \*[lp]*fn\*[rp]\*[lp]struct devinfo_dev *dev, \:struct devinfo_res *res, void *arg\*[rp]"
  65 .Fa "void *arg"
  66 .Fc
  67 .Ft int
  68 .Fo devinfo_foreach_rman_resource
  69 .Fa "struct devinfo_rman *rman"
  70 .Fa "int \*[lp]*fn\*[rp]\*[lp]struct devinfo_res *res, void *arg\*[rp]"
  71 .Fa "void *arg"
  72 .Fc
  73 .Ft int
  74 .Fo devinfo_foreach_rman
  75 .Fa "int \*[lp]*fn\*[rp]\*[lp]struct devinfo_rman *rman, void *arg\*[rp]"
  76 .Fa "void *arg"
  77 .Fc
  78 .Sh DESCRIPTION
  79 The
  80 .Nm
  81 library provides access to the kernel's internal device hierarchy
  82 and to the I/O resource manager.
  83 The library uses a
  84 .Xr sysctl 3
  85 interface to obtain a snapshot of the kernel's state,
  86 which is then made available to the application.
  87 .Pp
  88 Due to the fact that the information may be logically arranged
  89 in a number of different fashions,
  90 the library does not attempt to impose any structure on the data.
  91 .Pp
  92 Device, resource, and resource manager information is returned in
  93 data structures defined in
  94 .In devinfo.h :
  95 .Bd -literal -offset indent
  96 struct devinfo_dev {
  97     devinfo_handle_t    dd_handle;      /* device handle */
  98     devinfo_handle_t    dd_parent;      /* parent handle */
  99     char                *dd_name;       /* name of device */
 100     char                *dd_desc;       /* device description */
 101     char                *dd_drivername; /* name of attached driver */
 102     char                *dd_pnpinfo;    /* pnp info from parent bus */
 103     char                *dd_location;   /* Where bus thinks dev at */
 104     uint32_t            dd_devflags;    /* API flags */
 105     uint16_t            dd_flags;       /* internal dev flags */
 106     device_state_t      dd_state;       /* attachment state of dev */
 107 };
 108
 109 struct devinfo_rman {
 110     devinfo_handle_t    dm_handle;      /* resource manager handle */
 111     rman_res_t          dm_start;       /* resource start */
 112     rman_res_t          dm_size;        /* resource size */
 113     char                *dm_desc;       /* resource description */
 114 };
 115
 116 struct devinfo_res {
 117     devinfo_handle_t    dr_handle;      /* resource handle */
 118     devinfo_handle_t    dr_rman;        /* resource manager handle */
 119     devinfo_handle_t    dr_device;      /* owning device */
 120     rman_res_t          dr_start;       /* region start */
 121     rman_res_t          dr_size;        /* region size */
 122 };
 123 .Ed
 124 .Pp
 125 The
 126 .Vt devinfo_handle_t
 127 values can be used to look up the correspondingly referenced structures.
 128 .Pp
 129 .Fn devinfo_init
 130 takes a snapshot of the kernel's internal device and resource state.
 131 It returns nonzero
 132 if after a number of retries a consistent snapshot cannot be obtained.
 133 .Fn devinfo_init
 134 must be called before any other functions can be used.
 135 .Pp
 136 .Fn devinfo_free
 137 releases the memory associated with the snapshot.
 138 Any pointers returned by other functions are invalidated by this,
 139 and
 140 .Fn devinfo_init
 141 must be called again before using any other functions.
 142 .Pp
 143 .Fn devinfo_handle_to_device ,
 144 .Fn devinfo_handle_to_resource
 145 and
 146 .Fn devinfo_handle_to_rman
 147 return pointers to
 148 .Vt devinfo_dev ,
 149 .Vt devinfo_res
 150 and
 151 .Vt devinfo_rman
 152 structures respectively based on the
 153 .Vt devinfo_handle_t
 154 passed to them.
 155 These functions can be used to traverse the tree from any node to any
 156 other node.
 157 If
 158 .Fn devinfo_handle_to_device
 159 is passed the constant
 160 .Dv DEVINFO_ROOT_DEVICE
 161 it will return the handle to the root of the device tree.
 162 .Pp
 163 .Fn devinfo_foreach_device_child
 164 invokes its callback argument
 165 .Fa fn
 166 on every device which is an immediate child of
 167 .Fa device .
 168 The
 169 .Fa fn
 170 function is also passed
 171 .Fa arg ,
 172 allowing state to be passed to the callback function.
 173 If
 174 .Fa fn
 175 returns a nonzero error value the traversal is halted,
 176 and
 177 .Fn devinfo_foreach_device_child
 178 returns the error value to its caller.
 179 .Pp
 180 .Fn devinfo_foreach_device_resource
 181 invokes its callback argument
 182 .Fa fn
 183 on every resource which is owned by
 184 .Fa device .
 185 The
 186 .Fa fn
 187 function is also passed
 188 .Fa device
 189 and
 190 .Fa arg ,
 191 allowing state to be passed to the callback function.
 192 If
 193 .Fa fn
 194 returns a nonzero error value the traversal is halted,
 195 and
 196 .Fn devinfo_foreach_device_resource
 197 returns the error value to its caller.
 198 .Pp
 199 .Fn devinfo_foreach_rman_resource
 200 invokes its callback argument
 201 .Fa fn
 202 on every resource within the resource manager
 203 .Fa rman .
 204 The
 205 .Fa fn
 206 function is also passed
 207 .Fa arg ,
 208 allowing state to be passed to the callback function.
 209 If
 210 .Fa fn
 211 returns a nonzero error value the traversal is halted,
 212 and
 213 .Fn devinfo_foreach_rman_resource
 214 returns the error value to its caller.
 215 .Pp
 216 .Fn devinfo_foreach_rman
 217 invokes its callback argument
 218 .Fa fn
 219 on every resource manager.
 220 The
 221 .Fa fn
 222 function is also passed
 223 .Fa arg ,
 224 allowing state to be passed to the callback function.
 225 If
 226 .Fa fn
 227 returns a nonzero error value the traversal is halted,
 228 and
 229 .Fn devinfo_foreach_rman
 230 returns the error value to its caller.
 231 .Sh SEE ALSO
 232 .Xr devstat 3
 233 .Sh HISTORY
 234 The
 235 .Nm
 236 library first appeared in
 237 .Fx 5.0 .
 238 .Sh AUTHORS
 239 .An Michael Smith Aq Mt msmith@FreeBSD.org
 240 .Sh BUGS
 241 This is the first implementation of the library,
 242 and the interface is still subject to refinement.
 243 .Pp
 244 The interface does not report device classes or drivers,
 245 making it hard to sort by class or driver.