DEVITER(9) BSD Kernel Developer's Manual DEVITER(9)NAME
deviter, deviter_first, deviter_init, deviter_next, deviter_release —
machine-independent device iteration API
SYNOPSIS
#include <sys/device.h>
void
deviter_init(deviter_t *di, deviter_flags_t flags);
device_t
deviter_first(deviter_t *di, deviter_flags_t flags);
device_t
deviter_next(deviter_t *di);
void
deviter_release(deviter_t *di);
DESCRIPTION
The machine-independent deviter API lets interrupt handlers running at
any priority level and kernel threads iterate over the devices attached
to the kernel. Using deviter, 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.
DATA TYPES
Kernel subsystems using deviter may make use of the following data types:
deviter_flags_t
The kernel can iterate over devices for different purposes and
in different orders. The following flags affect device itera‐
tion:
DEVITER_F_RW
DEVITER_F_SHUTDOWN
DEVITER_F_LEAVES_FIRST
DEVITER_F_ROOT_FIRST
deviter_t
This is a device iteration “cursor” or “iterator”. It holds
iteration state such as the next device to visit.
FUNCTIONS
deviter_init(di, flags)
Initialize the device iterator, di. Set bits in flags to affect
the order of iteration. Set DEVITER_F_LEAVES_FIRST to visit
each device only after visiting its children (visit the leaves
of the device tree, first). Set DEVITER_F_ROOT_FIRST to visit
each device before visiting its children (visit the root of the
device tree, first). If you set neither DEVITER_F_LEAVES_FIRST
nor DEVITER_F_ROOT_FIRST, deviter returns devices in an arbi‐
trary order.
Set DEVITER_F_RW if your purpose for iterating over devices is
to modify the device tree by attaching or detaching devices.
Set DEVITER_F_SHUTDOWN if your purpose for iterating over
devices is to detach all of the devices during system shutdown.
DEVITER_F_SHUTDOWN implies DEVITER_F_RW.
deviter_next(di)
Advance the iterator di to the next device. deviter_next()
returns the current device or NULL if there are no more devices.
deviter_next() is undefined if di has not been initialized using
deviter_init() or deviter_first().
deviter_first(di, flags)
Initialize the iterator di with flags. Return the first device
according to the ordering indicated by flags and advance di to
the second device, or return NULL if there are no devices. This
is equivalent to calling deviter_init(di, flags) and then
deviter_next(di).
deviter_release(di)
Release all resources held by the iterator di. Every iterator
that is initialized with deviter_first() or deviter_init() MUST
be released.
CODE REFERENCES
Device iteration is implemented within the files sys/sys/device.h and
sys/kern/subr_autoconf.c.
SEE ALSOautoconf(9), driver(9)HISTORY
deviter appeared in NetBSD 5.0.
AUTHORS
David Young ⟨dyoung@NetBSD.org⟩
BSD November 4, 2009 BSD