OF_NODE_FROM_XREF(9)

✨ NAME ✨

OF_node_from_xref, OF_xref_from_node — the little glow-up that converts between a kernel phandle and an effective phandle 💫

okay so bestie, this is page OF_NODE_FROM_XREF(9) from the Kernel Developer's Manual, and it's genuinely iconic. two tiny functions, one big job: translating between two flavours of node ID so your device tree doesn't ghost you. 🦋

🌸 SYNOPSIS 🌸

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

phandle_t
OF_node_from_xref(phandle_t xref);

phandle_t
OF_xref_from_node(phandle_t node);

💖 DESCRIPTION 💖

so some OpenFirmware implementations (FDT, IBM) have this whole concept of an effective phandle, aka an xref. they exist to cross-reference device tree nodes, which is very main character of them. ✨

picture this 💅: a framebuffer controller wants to point at a GPIO controller <em>and</em> a pin, because that's what controls the backlight. in that setup, the GPIO node would have a cell (32-bit integer) property with a reserved name like "phandle" or "linux,phandle", and its value uniquely identifies the node. the actual name depends on the implementation, iykyk. then the framebuffer node would have a property with the name described by device bindings (that's the device-specific set of properties). it can be a cell property, or a combined property with one part of it being a cell. the value of the framebuffer node's property would be the same as the value of the GPIO "phandle" property — so yeah, we can say the framebuffer node refers to the GPIO node. obsessed. 🫶

but here's the plot twist 😭: the kernel uses its own internal logic to assign unique identifiers to the device tree nodes, and those values do not match the values of the "phandle" properties. so we need a translator. that's literally what these two are for — OF_node_from_xref() and OF_xref_from_node() perform the conversion between these two kinds of node identifiers. periodt. 💅

• OF_node_from_xref() — hands you the kernel phandle for the effective phandle xref. and if one can't be found, or the OpenFirmware implementation just doesn't support effective phandles at all? it returns the input value. no drama, no cap. 💖
• OF_xref_from_xref() — hands you the effective phandle for the kernel phandle xref. same deal: if one can't be found, or the implementation doesn't support effective phandles, it returns the input value. 🎀

🎀 EXAMPLES 🎀

phandle_t panelnode, panelxref;
char *model;

if (OF_getencprop(node, "lcd-panel", &panelxref) <= 0)
    return;

panelnode = OF_node_from_xref(panelxref);
if (OF_getprop_alloc(hdminode, "model", (void **)&model) <= 0)
    return;

look at her go 😭 so clean, so slay 🔥

🌈 SEE ALSO 🌈

• OF_device_from_xref(9)
• OF_device_register_xref(9)

👑 AUTHORS 👑

this manual page was written by Oleksandr Tymoshenko <gonzo@FreeBSD.org>. we stan. 🫶✨

and that's the whole vibe check, bestie — Debian, April 9, 2018, page OF_NODE_FROM_XREF(9), out. 💅🌸 bye babes! 🦋💖