/* * Device Iteration * * deviter_t: a device iterator. Holds state for a "walk" visiting * each device_t's in the device tree. * * deviter_init(di, flags): initialize the device iterator `di' * to "walk" the device tree. deviter_next(di) will return * the first device_t in the device tree, or NULL if there are * no devices. * * `flags' is one or more of DEVITER_F_RW, indicating that the * caller intends to modify the device tree by calling * config_detach(9) on devices in the order that the iterator * returns them; DEVITER_F_ROOT_FIRST, asking for the devices * nearest the "root" of the device tree to be returned, first; * DEVITER_F_LEAVES_FIRST, asking for the devices furthest from * the root of the device tree, first; and DEVITER_F_SHUTDOWN, * indicating both that deviter_init() should not respect any * locks on the device tree, and that deviter_next(di) may run * in more than one LWP before the walk has finished. * * Only one DEVITER_F_RW iterator may be in the device tree at * once. * * DEVITER_F_SHUTDOWN implies DEVITER_F_RW. * * Results are undefined if the flags DEVITER_F_ROOT_FIRST and * DEVITER_F_LEAVES_FIRST are used in combination. * * deviter_first(di, flags): initialize the device iterator `di' * and return the first device_t in the device tree, or NULL * if there are no devices. The statement * * dv = deviter_first(di); * * is shorthand for * * deviter_init(di); * dv = deviter_next(di); * * deviter_next(di): return the next device_t in the device tree, * or NULL if there are no more devices. deviter_next(di) * is undefined if `di' was not initialized with deviter_init() or * deviter_first(). * * deviter_release(di): stops iteration (subsequent calls to * deviter_next() will return NULL), releases any locks and * resources held by the device iterator. * * Device iteration does not return device_t's in any particular * order. An iterator will never return the same device_t twice. * Device iteration is guaranteed to complete---i.e., if deviter_next(di) * is called repeatedly on the same `di', it will eventually return * NULL. It is ok to attach/detach devices during device iteration. */