Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src Document the device iteration routines.
details: https://anonhg.NetBSD.org/src/rev/188c3cb8691a
branches: trunk
changeset: 748769:188c3cb8691a
user: dyoung <dyoung%NetBSD.org@localhost>
date: Thu Nov 05 00:20:24 2009 +0000
description:
Document the device iteration routines.
I derived this manual page from pmf(9), hence my retention of Jared's
copyright notice.
diffstat:
distrib/sets/lists/comp/mi | 17 +++-
share/man/man9/Makefile | 8 +-
share/man/man9/deviter.9 | 206 +++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 229 insertions(+), 2 deletions(-)
diffs (277 lines):
diff -r df7d701e2284 -r 188c3cb8691a distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi Wed Nov 04 23:34:59 2009 +0000
+++ b/distrib/sets/lists/comp/mi Thu Nov 05 00:20:24 2009 +0000
@@ -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 -r df7d701e2284 -r 188c3cb8691a share/man/man9/Makefile
--- a/share/man/man9/Makefile Wed Nov 04 23:34:59 2009 +0000
+++ b/share/man/man9/Makefile Thu Nov 05 00:20:24 2009 +0000
@@ -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+= 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 -r df7d701e2284 -r 188c3cb8691a share/man/man9/deviter.9
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/deviter.9 Thu Nov 05 00:20:24 2009 +0000
@@ -0,0 +1,206 @@
+.\" $NetBSD: deviter.9,v 1.1 2009/11/05 00:20:25 dyoung Exp $
+.\"
+.\" Copyright (c) 2009 David Young <dyoung%NetBSD.org@localhost>
+.\" 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@localhost>
+.\" 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@localhost
Home |
Main Index |
Thread Index |
Old Index