BUS_ADD_CHILD(9)

💖 BUS_ADD_CHILD(9) 💖

okay bestie, welcome to section 9 of the Kernel Developer's Manual — this is the page for BUS_ADD_CHILD, and it's literally the plug for adding a device node to the tree with a given priority. let's get into it ✨

🎀 SYNOPSIS 🎀

#include <sys/param.h>
#include <sys/bus.h>

device_t
BUS_ADD_CHILD(device_t dev, int order, const char *name, int unit);

like, that's the whole signature, no cap. she takes a dev, an order, a name and a unit, and she hands you back a device_t. 💅

🌸 DESCRIPTION 🌸

so the BUS_ADD_CHILD() method is what your driver's identify routine uses to add devices to the tree. that's her main character job 🫶. she can also be used to add children to buses that implement this routine in other contexts, but lowkey the behavior is bus specific — so don't come for me if it's different per bus, that's just how it is. please go read device_add_child(9) for more details, she's the sibling page, they're a duo 💖.

the interface is the same as device_add_child(9) — same energy, same shape — however, the bus' BUS_ADD_CHILD() is the one that gets called. that distinction is the whole plot twist, iykyk.

now listen, buses that implement BUS_ADD_CHILD() should insert the device into the tree using device_add_child(9) before adding things such as their own ivars and resource lists to the device. order matters, bestie, don't do it backwards 🙈.

and important: BUS_ADD_CHILD() is not called by device_add_child(9). it's the other way around — BUS_ADD_CHILD() instead calls device_add_child(9). not me clarifying this twice but the manpage said it twice so I'm saying it twice, periodt 💀.

⚠️ and a big one: a panic will result when called for a bus that does not implement BUS_ADD_CHILD(). like, full crash. not cute. also, some buses require a special bus-specific routine to be called instead of BUS_ADD_CHILD() — so check before you commit, fr fr 😭

✨ RETURN VALUES ✨

• the BUS_ADD_CHILD() method returns the device_t added to the tree 🎉
• or NULL to indicate failure 💀

that's it, that's the whole vibe check.

👑 SEE ALSO 👑

• device(9)
• device_add_child(9)
• driver(9)

go read them all, they're iconic 🌈

💜 AUTHORS 💜

this manual page was written by M. Warner Losh. absolute legend, ate and left no crumbs 🍓

and that's the whole page, babe — BUS_ADD_CHILD(9), Debian, dated April 8, 2018. mwah 💅✨