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