Document the device iteration routines.
I derived this manual page from pmf(9), hence my retention of Jared's copyright notice.
This commit is contained in:
dyoung
parent
bfe9f6f3f4
commit
8f33cec11c
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 \
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
.\" 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 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
|
||||
Loading…
Reference in New Issue