From 8f33cec11cdb34a1239ca2a7af26495ace68c677 Mon Sep 17 00:00:00 2001 From: dyoung Date: Thu, 5 Nov 2009 00:20:24 +0000 Subject: [PATCH] Document the device iteration routines. I derived this manual page from pmf(9), hence my retention of Jared's copyright notice. --- distrib/sets/lists/comp/mi | 17 ++- share/man/man9/Makefile | 8 +- share/man/man9/deviter.9 | 206 +++++++++++++++++++++++++++++++++++++ 3 files changed, 229 insertions(+), 2 deletions(-) create mode 100644 share/man/man9/deviter.9 diff --git a/distrib/sets/lists/comp/mi b/distrib/sets/lists/comp/mi index faa9abe5a329..3a4c1019b97a 100644 --- a/distrib/sets/lists/comp/mi +++ b/distrib/sets/lists/comp/mi @@ -1,4 +1,4 @@ -# $NetBSD: mi,v 1.1336 2009/11/03 05:12:10 dyoung Exp $ +# $NetBSD: mi,v 1.1337 2009/11/05 00:20:24 dyoung Exp $ # # Note: don't delete entries from here - mark them as "obsolete" instead. # @@ -8580,6 +8580,11 @@ ./usr/share/man/cat9/disk_resetstat.0 comp-obsolete obsolete ./usr/share/man/cat9/disk_unbusy.0 comp-sys-catman .cat ./usr/share/man/cat9/disklabel.0 comp-sys-catman .cat +./usr/share/man/cat9/deviter.0 comp-sys-catman .cat +./usr/share/man/cat9/deviter_first.0 comp-sys-catman .cat +./usr/share/man/cat9/deviter_init.0 comp-sys-catman .cat +./usr/share/man/cat9/deviter_next.0 comp-sys-catman .cat +./usr/share/man/cat9/deviter_release.0 comp-sys-catman .cat ./usr/share/man/cat9/dmover.0 comp-sys-catman .cat ./usr/share/man/cat9/dmover_backend_register.0 comp-sys-catman .cat ./usr/share/man/cat9/dmover_backend_unregister.0 comp-sys-catman .cat @@ -14005,6 +14010,11 @@ ./usr/share/man/html9/disk_init.html comp-sys-htmlman html ./usr/share/man/html9/disk_unbusy.html comp-sys-htmlman html ./usr/share/man/html9/disklabel.html comp-sys-htmlman html +./usr/share/man/html9/deviter.html comp-sys-htmlman html +./usr/share/man/html9/deviter_first.html comp-sys-htmlman html +./usr/share/man/html9/deviter_init.html comp-sys-htmlman html +./usr/share/man/html9/deviter_next.html comp-sys-htmlman html +./usr/share/man/html9/deviter_release.html comp-sys-htmlman html ./usr/share/man/html9/dmover.html comp-sys-htmlman html ./usr/share/man/html9/dmover_backend_register.html comp-sys-htmlman html ./usr/share/man/html9/dmover_backend_unregister.html comp-sys-htmlman html @@ -19581,6 +19591,11 @@ ./usr/share/man/man9/disk_resetstat.9 comp-obsolete obsolete ./usr/share/man/man9/disk_unbusy.9 comp-sys-man .man ./usr/share/man/man9/disklabel.9 comp-sys-man .man +./usr/share/man/man9/deviter.9 comp-sys-man .man +./usr/share/man/man9/deviter_first.9 comp-sys-man .man +./usr/share/man/man9/deviter_init.9 comp-sys-man .man +./usr/share/man/man9/deviter_next.9 comp-sys-man .man +./usr/share/man/man9/deviter_release.9 comp-sys-man .man ./usr/share/man/man9/dmover.9 comp-sys-man .man ./usr/share/man/man9/dmover_backend_register.9 comp-sys-man .man ./usr/share/man/man9/dmover_backend_unregister.9 comp-sys-man .man diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 319e2676f061..4cb1d229b017 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,4 +1,4 @@ -# $NetBSD: Makefile,v 1.296 2009/10/15 22:59:12 jym Exp $ +# $NetBSD: Makefile,v 1.297 2009/11/05 00:20:25 dyoung Exp $ # Makefile for section 9 (kernel function and variable) manual pages. @@ -60,6 +60,12 @@ MAN= accept_filter.9 accf_data.9 accf_http.9 \ MAN+= boothowto.9 MLINKS+=boothowto.9 BOOT_FLAG.9 +MAN+= deviter.9 +MLINKS+=deviter.9 deviter_first.9 \ + deviter.9 deviter_init.9 \ + deviter.9 deviter_next.9 \ + deviter.9 deviter_release.9 + MAN+= dmover.9 MLINKS+=dmover.9 dmover_backend_register.9 \ dmover.9 dmover_backend_unregister.9 \ diff --git a/share/man/man9/deviter.9 b/share/man/man9/deviter.9 new file mode 100644 index 000000000000..9913bb638265 --- /dev/null +++ b/share/man/man9/deviter.9 @@ -0,0 +1,206 @@ +.\" $NetBSD: deviter.9,v 1.1 2009/11/05 00:20:25 dyoung Exp $ +.\" +.\" Copyright (c) 2009 David Young +.\" 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 +.\" 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 Nov 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 +This section describes places within the +.Nx +source tree where actual code implementing +.Nm +can be found. +All pathnames are relative to +.Pa /usr/src . +.Pp +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 dyoung@NetBSD.org