OF_GETPROP(9)

💅 OF_GETPROP — the "get stuff out of device tree nodes" girlies ✨

okay so bestie, welcome to OF_GETPROP(9) from the Kernel Developer's Manual 🎀 this is the whole squad of functions that read (and one that writes) properties on device tree nodes, and honestly? they ate. no cap.

🌸 NAME 🌸

OF_getprop, OF_getproplen, OF_getencprop, OF_hasprop, OF_searchprop, OF_searchencprop, OF_getprop_alloc, OF_getencprop_alloc, OF_getprop_alloc_multi, OF_getencprop_alloc_multi, OF_prop_free, OF_nextprop, OF_setprop — access properties of device tree node 💖

✨ SYNOPSIS ✨

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

ssize_t
OF_getproplen(phandle_t node, const char *propname);

ssize_t
OF_getprop(phandle_t node, const char *propname, void *buf, size_t len);

ssize_t
OF_getencprop(phandle_t node, const char *prop, pcell_t *buf,
    size_t len);

int
OF_hasprop(phandle_t node, const char *propname);

ssize_t
OF_searchprop(phandle_t node, const char *propname, void *buf,
    size_t len);

ssize_t
OF_searchencprop(phandle_t node, const char *propname, pcell_t *buf,
    size_t len);

ssize_t
OF_getprop_alloc(phandle_t node, const char *propname, void **buf);

ssize_t
OF_getencprop_alloc(phandle_t node, const char *propname,
    pcell_t **buf);

ssize_t
OF_getprop_alloc_multi(phandle_t node, const char *propname, int elsz,
    void **buf);

ssize_t
OF_getencprop_alloc_multi(phandle_t node, const char *propname,
    int elsz, pcell_t **buf);

void
OF_prop_free(void *buf);

int
OF_nextprop(phandle_t node, const char *propname, char *buf,
    size_t len);

int
OF_setprop(phandle_t node, const char *propname, const void *buf,
    size_t len);

🦋 DESCRIPTION 🦋

So device nodes have properties attached to them, right? A property = a name + a value. That's it, that's the whole vibe. 💫

• the name is a human-readable string, lowkey short: from 1 to 31 characters long
• the value is an array of zero or more bytes encoding... literally whatever. The meaning of those bytes is entirely up to how drivers interpret them 👀 Properties can encode byte arrays, text strings, unsigned 32-bit values, or any combination of those. main character energy, honestly.

A property with a zero-length value usually represents boolean info. If the property is present → true. If it's not → false. Simple as. ✅

A byte array is encoded as a sequence of bytes, and it represents stuff like MAC addresses. 🍓

A text string is a sequence of n printable characters. It's encoded as a byte array of length n + 1 bytes, with characters represented as bytes plus a terminating null character. (yes, the +1 is the null, she's always invited to the party 💅)

Unsigned 32-bit values, also sometimes called cells, are encoded as a sequence of 4 bytes in big-endian order. 🔥

• OF_getproplen() — returns either the length of the value associated with the property propname in the node identified by node, or 0 if the property exists but has no associated value. If propname doesn't exist, -1 is returned. 💀
• OF_getprop() — copies a maximum of len bytes from the value associated with the property propname of the device node node into the memory specified by buf. Returns the actual size of the value, or -1 if the property doesn't exist. 📦
• OF_getencprop() — copies a maximum of len bytes into memory specified by buf, then converts cell values from big-endian to host byte order. Returns the actual size of the value in bytes, or -1 if the property doesn't exist. Heads up: len must be a multiple of 4. 🚨
• OF_hasprop() — returns 1 if the device node node has a property specified by propname, and 0 if the property doesn't exist. the vibe check function fr fr 🫶
• OF_searchprop() — recursively looks for the property specified by propname, starting with the device node node, then the parent node, and up to the root node. If the property is found, it copies a maximum of len bytes of the value associated with the property into the memory specified by buf. Returns the actual size in bytes of the value, or -1 if the property doesn't exist. 🌈
• OF_searchencprop() — same recursive climb as above (node → parent → ... → root). If the property is found, it copies a maximum of len bytes of the value into buf, then converts cell values from big-endian to host byte order. Returns the actual size in bytes of the value, or -1 if the property doesn't exist. 🔍
• OF_getprop_alloc() — allocates memory large enough to hold the value associated with the property propname of the device node node and copies the value into the newly allocated memory region. Returns the actual size of the value and stores the address of the allocated memory in *buf. If the property has a zero-sized value, *buf is set NULL. Returns -1 if the property doesn't exist or memory allocation failed. Allocated memory should be released when no longer required by calling OF_prop_free(). ⚠️ The function might sleep when allocating memory.
• OF_getencprop_alloc() — allocates enough memory to hold the value associated with the property propname of the device node node, copies the value into the newly allocated memory region, and then converts cell values from big-endian to host byte order. The actual size of the value is returned and the address of allocated memory is stored in *buf. If the property has zero-length value, *buf is set to NULL. Returns -1 if the property doesn't exist or memory allocation failed or the size of the value is not divisible by a cell size (4 bytes). Allocated memory should be released when no longer required by calling OF_prop_free(). ⚠️ The function might sleep when allocating memory.
• OF_getprop_alloc_multi() — allocates memory large enough to hold the value associated with the property propname of the device node node and copies the value into the newly allocated memory region. The value is expected to be an array of zero or more elements elsz bytes long. Returns the number of elements in the value and stores the address of the allocated memory in *buf. If the property has a zero-sized value, *buf is set NULL. Returns -1 if the property doesn't exist or memory allocation failed or the size of the value is not divisible by elsz. Allocated memory should be released when no longer required by calling OF_prop_free(). ⚠️ The function might sleep when allocating memory.
• OF_getencprop_alloc_multi() — allocates memory large enough to hold the value associated with the property propname of the device node node, copies the value into the newly allocated memory region, and then converts cell values from big-endian to host byte order. The value is expected to be an array of zero or more elements elsz bytes long. Returns the number of elements in the value and stores the address of the allocated memory in *buf. If the property has a zero-sized value, *buf is set NULL. Returns -1 if the property doesn't exist or memory allocation failed or the size of the value is not divisible by elsz. Allocated memory should be released when no longer required by calling OF_prop_free(). ⚠️ The function might sleep when allocating memory.
• OF_prop_free() — releases memory at buf that was allocated by OF_getprop_alloc(), OF_getencprop_alloc(), OF_getprop_alloc_multi(), or OF_getencprop_alloc_multi(). clean up after yourself, bestie 🧹💖
• OF_nextprop() — copies a maximum of size bytes of the name of the property following the propname property into buf. If propname is NULL, the function copies the name of the first property of the device node node. OF_nextprop() returns -1 if propname is invalid or there is an internal error, 0 if there are no more properties after propname, or 1 otherwise. 👑
• OF_setprop() — sets the value of the property propname in the device node node to the value beginning at the address specified by buf and running for len bytes. If the property doesn't exist, the function tries to create it. OF_setprop() returns the actual size of the new value, or -1 if the property value can't be changed or the new property can't be created. ✍️

real talk: those _alloc girlies might sleep while allocating memory, and every single one of them wants OF_prop_free() when you're done with the buffer. don't ghost your allocations. 😭

💜 EXAMPLES 💜

phandle_t node;
phandle_t hdmixref, hdminode;
device_t hdmi;
uint8_t mac[6];
char *model;

/*
 * Get a byte array property
 */
if (OF_getprop(node, "eth,hwaddr", mac, sizeof(mac)) != sizeof(mac))
    return;

/*
 * Get internal node reference and device associated with it
 */
if (OF_getencprop(node, "hdmi", &hdmixref) <= 0)
    return;
hdmi = OF_device_from_xref(hdmixref);

/*
 * Get string value of model property of HDMI framer node
 */
hdminode = OF_node_from_xref(hdmixref);
if (OF_getprop_alloc(hdminode, "model", (void **)&model) <= 0)
    return;

🎀 SEE ALSO 🎀

OF_device_from_xref(9) OF_node_from_xref(9) — go read these too, they're the supporting cast and they understood the assignment 💖

⭐ AUTHORS ⭐

This manual page was written by Oleksandr Tymoshenko <gonzo@FreeBSD.org>. iconic behavior, we love a credited author 🫶

and that's the whole page bestie!! 🌸 written by that legend, dated June 23, 2018, shipped out under Debian, and part of the Kernel Developer's Manual — slay, go forth and read your device tree properties 💅✨🦋