DEVITER(9)

💅 DEVITER(9) — like, the device iteration page, bestie

okay so this is the deviter(9) page from the Kernel Developer's Manual and honestly? it's a little icon. it's the machine-independent device iteration API and we're gonna get through it together, no cap 🫶

---

✨ NAME ✨

deviter, deviter_first, deviter_init, deviter_next, deviter_release — the machine-independent device iteration API. that's the whole vibe: iterating devices, but make it portable 💫

---

🌸 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);

look at her. four functions. absolutely slaying 💅

---

🦋 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. yes, any priority level, she's flexible like that ✨

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. that's the whole main character energy of this API — concurrent attach/detach and you're still fine, periodt 👑

---

🎀 DATA TYPES 🎀

Kernel subsystems using deviter may make use of the following data types, bestie:

• 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. it's giving bookmark, it's giving we know where we are 🔖

---

💖 FUNCTIONS 💖

⭐ deviter_init(di, flags)

Initialize the device iterator, di. set bits in flags to affect the order of iteration, iykyk:

• Set DEVITER_F_LEAVES_FIRST to visit each device only after visiting its children (visit the leaves of the device tree, first). go bottom-up, queen 🌱
• Set DEVITER_F_ROOT_FIRST to visit each device before visiting its children (visit the root of the device tree, first). go top-down 👑

If you set neither DEVITER_F_LEAVES_FIRST nor DEVITER_F_ROOT_FIRST, deviter returns devices in an arbitrary order. chaotic. we respect it 🙈

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.

heads up babe: DEVITER_F_SHUTDOWN implies DEVITER_F_RW. it's a package deal 🔥

🌈 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(). do not do this. bestie I am begging 🫶

🍓 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). it's literally the same thing, just a shortcut ✨

🧚 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. not "should". not "maybe". MUST. take out your trash, girlie 🗑️💅

---

🔥 CODE REFERENCES 🔥

Device iteration is implemented within the files sys/sys/device.h and sys/kern/subr_autoconf.c. that's where the magic lives 🪄

---

💜 SEE ALSO 💜

• autoconf(9)
• driver(9)

go read those next, they're also iconic, no cap 📚

---

🌸 HISTORY 🌸

deviter appeared in NetBSD 5.0. a legend was born ✨

---

👑 AUTHORS 👑

David Young <dyoung@NetBSD.org> — thank you for your service, king 🫡💖

---

and that's the whole page, bestie!! 🎀 this one came from Debian, dated November 4, 2009 — yeah she's vintage, she's a classic, and she still ate 💅✨