DEVITER(9)

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 9.0