DEVICE_IDENTIFY(9)

💖 DEVICE_IDENTIFY(9) 💖

okay bestie, so we're in the Kernel Developer's Manual today and the star of the show is DEVICE_IDENTIFY — the function that goes "hey, i see a device, let me tell the kernel about it" ✨

✨ NAME ✨

DEVICE_IDENTIFY — identify a device, register it 🫶

🌸 SYNOPSIS 🌸

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

void
DEVICE_IDENTIFY(driver_t *driver, device_t parent);

like, that's the whole signature. cute, right? 💅

🦋 DESCRIPTION 🦋

so the identify function for a device is only needed for devices on buses that literally cannot identify their own children independently — think the ISA bus, that's the classic example 👑

what it does: it recognizes the device (usually by poking at non-ambiguous registers in the hardware — iykyk) and then tells the kernel about it, which creates a brand new device instance. it's giving matchmaker energy fr fr 💖

then you use BUS_ADD_CHILD(9) to register the device as a child of the bus. and the device's resources — like IRQ and I/O ports — get registered with the kernel by calling bus_set_resource() for each resource. (go read bus_set_resource(9) for the whole tea, i'm not gonna re-explain it here 🍓)

now here's the part that's giving caution ⚠️ — the device tree and the device driver tree are disjoint, so DEVICE_IDENTIFY() has to keep that in mind. if you load and unload your device driver that has the identify routine, the child node has the potential to add the same node multiple times unless specific measures are taken to preclude that possibility. no cap, that's a real one. don't let it happen to you 😭

🎀 EXAMPLES 🎀

here's some pseudo-code showing a function that probes for a piece of hardware and registers it and its resource (an I/O port) with the kernel. slay 💅

void
foo_identify(driver_t *driver, device_t parent)
{
        device_t child;

        retrieve_device_information;
        if (devices matches one of your supported devices &&
            not already in device tree) {
                child = BUS_ADD_CHILD(parent, 0, "foo", -1);
                bus_set_resource(child, SYS_RES_IOPORT, 0, FOO_IOADDR, 1);
        }
}

notice that <purple>not already in device tree</purple> check? that's the whole "don't add the same node twice" thing from the description. main character behavior honestly 👑

🌈 SEE ALSO 🌈

• BUS_ADD_CHILD(9)
• bus_set_resource(9)
• device(9)
• device_add_child(9)
• DEVICE_ATTACH(9)
• DEVICE_DETACH(9)
• DEVICE_PROBE(9)
• DEVICE_SHUTDOWN(9)

go read them all bestie, they're all connected 🧚

👑 AUTHORS 👑

this manual page was written by Alexander Langer <alex@FreeBSD.org> 💜

and that's the whole page!! Debian, January 15, 2017 — periodt 💅✨ mwah, go register some devices responsibly 🫶🎀