diff options
Diffstat (limited to 'static/netbsd/man9/deviter.9')
| -rw-r--r-- | static/netbsd/man9/deviter.9 | 198 |
1 files changed, 198 insertions, 0 deletions
diff --git a/static/netbsd/man9/deviter.9 b/static/netbsd/man9/deviter.9 new file mode 100644 index 00000000..3c5f4ac9 --- /dev/null +++ b/static/netbsd/man9/deviter.9 @@ -0,0 +1,198 @@ +.\" $NetBSD: deviter.9,v 1.5 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2009 David Young <dyoung@NetBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY David Young ``AS IS'' AND ANY EXPRESS +.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL David Young BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE +.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER +.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" NetBSD: pmf.9,v 1.12 2009/10/21 16:06:59 snj Exp +.\" +.\" Copyright (c) 2007 Jared D. McNeill <jmcneill@invisible.ca> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 4, 2009 +.Dt DEVITER 9 +.Os +.Sh NAME +.Nm deviter , +.Nm deviter_first , +.Nm deviter_init , +.Nm deviter_next , +.Nm deviter_release +.Nd machine-independent device iteration API +.Sh SYNOPSIS +.In sys/device.h +.Ft void +.Fn deviter_init "deviter_t *di" "deviter_flags_t flags" +.Ft device_t +.Fn deviter_first "deviter_t *di" "deviter_flags_t flags" +.Ft device_t +.Fn deviter_next "deviter_t *di" +.Ft void +.Fn deviter_release "deviter_t *di" +.Sh DESCRIPTION +The machine-independent +.Nm +API lets interrupt handlers running at any priority level and kernel +threads iterate over the devices attached to the kernel. +Using +.Nm , +it is safe for an interrupt handler or a thread to iterate over +devices attached to the kernel while another thread attaches or +detaches the devices. +.Sh DATA TYPES +Kernel subsystems using +.Nm +may make use of the following data types: +.Bl -tag -width compact +.It Fa deviter_flags_t +The kernel can iterate over devices for different purposes and in +different orders. +The following flags affect device iteration: +.Bl -item -compact -offset indent +.It +.Dv DEVITER_F_RW +.It +.Dv DEVITER_F_SHUTDOWN +.It +.Dv DEVITER_F_LEAVES_FIRST +.It +.Dv DEVITER_F_ROOT_FIRST +.El +.It Fa deviter_t +This is a device iteration +.Dq cursor +or +.Dq iterator . +It holds iteration state such as the next device to visit. +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn deviter_init "di" "flags" +Initialize the device iterator, +.Fa di . +Set bits in +.Fa flags +to affect the order of iteration. +Set +.Dv DEVITER_F_LEAVES_FIRST +to visit each device only after visiting its children (visit the +leaves of the device tree, first). +Set +.Dv DEVITER_F_ROOT_FIRST +to visit each device before visiting its children (visit the root +of the device tree, first). +If you set neither +.Dv DEVITER_F_LEAVES_FIRST +nor +.Dv DEVITER_F_ROOT_FIRST , +.Nm +returns devices in an arbitrary order. +.Pp +Set +.Dv DEVITER_F_RW +if your purpose for iterating over devices is to modify the device +tree by attaching or detaching devices. +Set +.Dv DEVITER_F_SHUTDOWN +if your purpose for iterating over devices is to detach all of +the devices during system shutdown. +.Dv DEVITER_F_SHUTDOWN +implies +.Dv DEVITER_F_RW . +.It Fn deviter_next "di" +Advance the iterator +.Fa di +to the next device. +.Fn deviter_next +returns the current device or +.Dv NULL +if there are no more devices. +.Fn deviter_next +is undefined if +.Fa di +has not been initialized using +.Fn deviter_init +or +.Fn deviter_first . +.It Fn deviter_first "di" "flags" +Initialize the iterator +.Fa di +with +.Fa flags . +Return the first device according to the ordering +indicated by +.Fa flags +and advance +.Fa di +to the second device, or +return +.Dv NULL +if there are no devices. +This is equivalent to calling +.Fn deviter_init "di" "flags" +and then +.Fn deviter_next "di" . +.It Fn deviter_release "di" +Release all resources held by the iterator +.Fa di . +Every iterator that is initialized with +.Fn deviter_first +or +.Fn deviter_init +MUST be released. +.El +.Sh CODE REFERENCES +Device iteration is implemented within the files +.Pa sys/sys/device.h +and +.Pa sys/kern/subr_autoconf.c . +.Sh SEE ALSO +.Xr autoconf 9 , +.Xr driver 9 +.Sh HISTORY +.Nm +appeared in +.Nx 5.0 . +.Sh AUTHORS +.An David Young Aq Mt dyoung@NetBSD.org |