DEVICE_ADD_CHILD(9)

📦
version 15.1 · 2 versions
, in freebsd 15.1, nixpkgs unstable

💖 DEVICE_ADD_CHILD 💖

okay bestie, so this is a Kernel Developer's Manual page — section 9, the driver-writing corner of the universe — and it's all about how to make a brand-new baby device and adopt it into an existing device's family tree 🌳✨. The functions are device_add_child and device_add_child_ordered, and yes they're literally sisters, one of them just has opinions about birth order.

✨ SYNOPSIS ✨

first, the vibes check — you gotta include these headers or nothing works, no cap:

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

then the main character herself:

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

and her slightly more organized sister:

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

🌸 DESCRIPTION 🌸

So what we're doing here is creating a new child device of dev 🫶. The name and unit args are literally just telling the system what this device is called and which unit number it gets.

  • if the name is unknown? bestie, pass NULL 🙈
  • if the unit is unknown? pass DEVICE_UNIT_ANY and the system will pick the next available unit number for you, slay 💅

The name of the device is what tells the system which drivers might be a good match for it. So if you specify a name, only drivers with that name get probed. If you give no name, all the drivers for the owning bus get probed. Either way — and this is the iconic part — only the name of the device is stored, so you can safely unload/load a driver bound to that name 🔥. It's giving commit-phobia in the best way.

This whole setup lets buses that can uniquely identify device instances (thinking of you, PCI 👑) let each driver check each device instance for a match. But for buses that rely on supplied probe hints, where only one driver even has a chance of probing the device, you should specify the driver name as the device name. Different strokes, iykyk.

🎀 about unit numbers 🎀

Normally the system picks unit numbers automatically and you should just hand over DEVICE_UNIT_ANY. That's the default vibe, that's the move ✨. But when you specifically want a unit number — like wiring a particular piece of hardware to a pre-configured unit — then pass that unit. Small caveat: if the unit number you asked for is already allocated, a new unit gets allocated instead, and a diagnostic message gets printed 😭. So it's not a hard guarantee, it's a request, okay?

🦋 about ordering 🦋

Some buses need their devices probed in a specific order. ISA is the classic example — some devices are sensitive to failed probe attempts from unrelated drivers, so they gotta go first, periodt. That's what the order argument of device_add_child_ordered() is for: it specifies a partial ordering. The new device gets added before any existing device with a greater order 💜.

And if you just use plain device_add_child()? Then the new child gets added as if its order was zero. Simple as that 🍓.

🌈 the care-and-feeding rules 🌈

when you're adding a device inside a DEVICE_IDENTIFY(9) routine, use device_find_child(9) first to make sure the device hasn't already been added to the tree. Because the device name and devclass_t get associated at probe time (not child-addition time), previous instances of the driver — say, in a module that was later unloaded — may have already added the instance 🙈.

Bus driver authors, listen up 📢: you gotta be careful when adding children while loading and unloading, or you'll end up with duplicate children devices. Nobody wants that, fr fr.

also, when you're adding a child to another device node — like in an identify routine — use BUS_ADD_CHILD(9) instead of device_add_child(). BUS_ADD_CHILD(9) calls device_add_child() and adds the proper bus-specific data to the new child. Note that device_add_child() does not call BUS_ADD_CHILD(9) — the love is one-directional 💀.

⭐ RETURN VALUES ⭐

  • the new device, if it worked 🎉
  • NULL, otherwise 😔

👑 SEE ALSO 👑

go read these next, bestie, they're all connected:

💅 AUTHORS 💅

This manual page was written by Doug Rabson. Iconic of him, honestly 🫶.

and that's the whole page, no crumbs left 💖 this was the Debian build, dated February 11, 2018, and the manual name is DEVICE_ADD_CHILD(9) — section 9 forever, periodt 🌟

📦 where this page comes from