share/man/man9/deviter.9

   1 .\" $NetBSD: deviter.9,v 1.1 2009/11/05 00:20:25 dyoung Exp $
   2 .\"
   3 .\" Copyright (c) 2009 David Young <dyoung@NetBSD.org>
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY David Young ``AS IS'' AND ANY EXPRESS
  16 .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  17 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL David Young BE LIABLE FOR ANY
  19 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  21 .\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  22 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
  23 .\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  24 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
  25 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .\" NetBSD: pmf.9,v 1.12 2009/10/21 16:06:59 snj Exp
  28 .\"
  29 .\" Copyright (c) 2007 Jared D. McNeill <jmcneill@invisible.ca>
  30 .\" All rights reserved.
  31 .\"
  32 .\" Redistribution and use in source and binary forms, with or without
  33 .\" modification, are permitted provided that the following conditions
  34 .\" are met:
  35 .\" 1. Redistributions of source code must retain the above copyright
  36 .\"    notice, this list of conditions and the following disclaimer.
  37 .\" 2. Redistributions in binary form must reproduce the above copyright
  38 .\"    notice, this list of conditions and the following disclaimer in the
  39 .\"    documentation and/or other materials provided with the distribution.
  40 .\"
  41 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  42 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  43 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  44 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  45 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  46 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  47 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  48 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  49 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  50 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  51 .\" POSSIBILITY OF SUCH DAMAGE.
  52 .\"
  53 .Dd November 4, 2009
  54 .Dt DEVITER 9
  55 .Os
  56 .Sh NAME
  57 .Nm deviter ,
  58 .Nm deviter_first ,
  59 .Nm deviter_init ,
  60 .Nm deviter_next ,
  61 .Nm deviter_release
  62 .Nd machine-independent device iteration API
  63 .Sh SYNOPSIS
  64 .In sys/device.h
  65 .Ft void
  66 .Fn deviter_init "deviter_t *di" "deviter_flags_t flags"
  67 .Ft device_t
  68 .Fn deviter_first "deviter_t *di" "deviter_flags_t flags"
  69 .Ft device_t
  70 .Fn deviter_next "deviter_t *di"
  71 .Ft void
  72 .Fn deviter_release "deviter_t *di"
  73 .Sh DESCRIPTION
  74 The machine-independent
  75 .Nm
  76 API lets interrupt handlers running at any priority level and kernel
  77 threads iterate over the devices attached to the kernel.
  78 Using
  79 .Nm ,
  80 it is safe for an interrupt handler or a thread to iterate over
  81 devices attached to the kernel while another thread attaches or
  82 detaches the devices.
  83 .Sh DATA TYPES
  84 Kernel subsystems using
  85 .Nm
  86 may make use of the following data types:
  87 .Bl -tag -width compact
  88 .It Fa deviter_flags_t
  89 The kernel can iterate over devices for different purposes and in
  90 different orders.
  91 The following flags affect device iteration:
  92 .Bl -item -compact -offset indent
  93 .It
  94 .Dv DEVITER_F_RW
  95 .It
  96 .Dv DEVITER_F_SHUTDOWN
  97 .It
  98 .Dv DEVITER_F_LEAVES_FIRST
  99 .It
 100 .Dv DEVITER_F_ROOT_FIRST
 101 .El
 102 .It Fa deviter_t
 103 This is a device iteration
 104 .Dq cursor
 105 or
 106 .Dq iterator .
 107 It holds iteration state such as the next device to visit.
 108 .El
 109 .Sh FUNCTIONS
 110 .Bl -tag -width compact
 111 .It Fn deviter_init "di" "flags"
 112 Initialize the device iterator,
 113 .Fa di .
 114 Set bits in
 115 .Fa flags
 116 to affect the order of iteration.
 117 Set
 118 .Dv DEVITER_F_LEAVES_FIRST
 119 to visit each device only after visiting its children (visit the
 120 leaves of the device tree, first).
 121 Set
 122 .Dv DEVITER_F_ROOT_FIRST
 123 to visit each device before visiting its children (visit the root
 124 of the device tree, first).
 125 If you set neither
 126 .Dv DEVITER_F_LEAVES_FIRST
 127 nor
 128 .Dv DEVITER_F_ROOT_FIRST ,
 129 .Nm
 130 returns devices in an arbitrary order.
 131 .Pp
 132 Set
 133 .Dv DEVITER_F_RW
 134 if your purpose for iterating over devices is to modify the device
 135 tree by attaching or detaching devices.
 136 Set
 137 .Dv DEVITER_F_SHUTDOWN
 138 if your purpose for iterating over devices is to detach all of
 139 the devices during system shutdown.
 140 .Dv DEVITER_F_SHUTDOWN
 141 implies
 142 .Dv DEVITER_F_RW .
 143 .It Fn deviter_next "di"
 144 Advance the iterator
 145 .Fa di
 146 to the next device.
 147 .Fn deviter_next
 148 returns the current device or
 149 .Dv NULL
 150 if there are no more devices.
 151 .Fn deviter_next
 152 is undefined if
 153 .Fa di
 154 has not been initialized using
 155 .Fn deviter_init
 156 or
 157 .Fn deviter_first .
 158 .It Fn deviter_first "di" "flags"
 159 Initialize the iterator
 160 .Fa di
 161 with
 162 .Fa flags .
 163 Return the first device according to the ordering
 164 indicated by
 165 .Fa flags
 166 and advance
 167 .Fa di
 168 to the second device, or
 169 return
 170 .Dv NULL
 171 if there are no devices.
 172 This is equivalent to calling
 173 .Fn deviter_init "di" "flags"
 174 and then
 175 .Fn deviter_next "di" .
 176 .It Fn deviter_release "di"
 177 Release all resources held by the iterator
 178 .Fa di .
 179 Every iterator that is initialized with
 180 .Fn deviter_first
 181 or
 182 .Fn deviter_init
 183 MUST be released.
 184 .El
 185 .Sh CODE REFERENCES
 186 This section describes places within the
 187 .Nx
 188 source tree where actual code implementing
 189 .Nm
 190 can be found.
 191 All pathnames are relative to
 192 .Pa /usr/src .
 193 .Pp
 194 Device iteration is implemented within the files
 195 .Pa sys/sys/device.h
 196 and
 197 .Pa sys/kern/subr_autoconf.c .
 198 .Sh SEE ALSO
 199 .Xr autoconf 9 ,
 200 .Xr driver 9
 201 .Sh HISTORY
 202 .Nm
 203 appeared in
 204 .Nx 5.0 .
 205 .Sh AUTHORS
 206 .An David Young Aq dyoung@NetBSD.org