OF_DEVICE_FROM_XREF(9)

✨ OF_DEVICE_FROM_XREF(9) ✨

okay bestie, welcome to the Kernel Developer's Manual section 9, where we talk about OF_device_from_xref, OF_xref_from_device, and OF_device_register_xref — the little trio that handles the mappings between xrefs and devices. yes this is real and yes it slays 💅

🌸 NAME 🌸

• OF_device_from_xref, OF_xref_from_device, OF_device_register_xref — manage mappings between xrefs and devices 🦋

🎀 SYNOPSIS 🎀

#include <dev/ofw/ofw_bus.h>
#include <dev/ofw/ofw_bus_subr.h>

int
OF_device_register_xref(phandle_t xref, device_t dev);

device_t
OF_device_from_xref(phandle_t xref);

phandle_t
OF_xref_from_device(device_t dev);

💖 DESCRIPTION 💖

so here's the vibe: when a device tree node references another node, the driver might need to get a device_t instance that's associated with that referenced node. like, imagine an Ethernet driver trying to reach its PHY device. to make that whole thing possible, the kernel keeps a table mapping effective handles to device_t instances. iconic behavior fr fr 👑

• OF_device_register_xref() — adds a map entry from the effective phandle xref to dev. and if a mapping entry for xref already exists? it gets replaced with the new one, no hesitation, main character energy. this function always returns 0. always. periodt.
• OF_device_from_xref() — returns the device_t instance associated with the effective phandle xref. but if no such mapping exists, it returns NULL. sad but true 😭
• OF_xref_from_device() — returns the effective phandle associated with the device dev. and if no such mapping exists, it returns 0. ngl that's just how it is 🫶

🦋 EXAMPLES 🦋

static int
acmephy_attach(device_t dev)
{
    phandle_t node;

    /* PHY node is referenced from eth device, register it */
    node = ofw_bus_get_node(dev);
    OF_device_register_xref(OF_xref_from_node(node), dev);

    return (0);
}

look at that. registering the PHY node, returning (0), being adorable about it ✨

🌈 SEE ALSO 🌈

• OF_node_to_xref(9) — go read that one too bestie, iykyk 💜

👑 AUTHORS 👑

this manual page was written by Oleksandr Tymoshenko <gonzo@FreeBSD.org>. give them their flowers 💐

and that's the whole page, no cap. every flag, every return value, every NULL and every 0 accounted for 🎀

Debian • April 9, 2018 — k bye bestie, go map some xrefs 💖🦋✨