DEVITER(9) | 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 iteration:
  - `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 arbitrary 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 ALSO

autoconf(9), driver(9)

# HISTORY

deviter appeared in NetBSD 5.0.

# AUTHORS

David Young <dyoung@NetBSD.org>

November 4, 2009 | NetBSD 8.2