NAME

OF_getprop, OF_getproplen, OF_getencprop, OF_hasprop, OF_searchprop, OF_searchencprop, OF_getprop_alloc, OF_getencprop_alloc, 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); 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

Device nodes can have properties associated with them. Properties consist of name and value. A name is a human-readable string from 1 to 31 characters long. Value is an array of zero or more bytes that encode certain information. The meaning of that bytes depends on how drivers interpret them. Properties can encode byte arrays, text strings, unsigned 32-bit values or combination of any of these types. Property with zero bytes long value usually represents boolean information. If the property is present, it signifies true, otherwise false. A byte array is encoded as a sequence of its bytes and represents values like MAC addresses. A text string is a sequence of n printable characters. It is encoded as a byte array of length n + 1 bytes with characters represented as bytes plus terminating null character. 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 value associated with it or -1 if the property propname does not exist. OF_getprop() copies maximum of len bytes from the value associated with the property propname of the device node node into the memory specified by buf. The function returns actual size of the value or -1 if the property does not exist. OF_getencprop() copies maximum of len bytes into memory specified by buf, and then converts cell values from big-endian to host byte order. The function returns actual size of the value in bytes or -1 if the property does not exist. len should be multiply of 4. OF_hasprop() returns 1 if the device node node has property specified by propname, and zero if there is the property does not exist. OF_searchprop() recursively looks for the property specified by propname starting with the device node node followed by the parent node and up to the root node. If the property is found the function copies max len bytes of the value associated with the property into the memory specified by buf. The function returns actual size in bytes of the value, and -1 if the property does not exist. OF_searchencprop() recursively looks for the property specified by propname starting with the device node node followed by the parent node and up to the root node. If the property is found the function copies max len bytes of the value associated with the property into the memory specified by buf, and then converts cell values from big-endian to host byte order. The function returns actual size in bytes of the value, and -1 if the property does not exist. OF_getprop_alloc() allocates the amount of memory large enough to fit the value associated with the property propname of the device node node and copies the value into the newly allocated memory region. The function returns actual size of the value and stores address of allocated memory in *buf. If the property has zero-sized value *buf is set NULL. The function return -1 if the property does not exist or memory allocation failed. Allocated memory should be released when no longer required by calling OF_prop_free(). The function may sleep when allocating memory. OF_getencprop_alloc() allocates the amount of memory large enough to fit 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 function returns actual size of the value and stores address of allocated memory in *buf. If the property has zero-sized value *buf is set NULL. The function return -1 if the property does not exist or memory allocation failed. Allocated memory should be released when no longer required by calling OF_prop_free(). The function may sleep when allocating memory. OF_prop_free() releases memory at buf allocated by OF_getprop_alloc() and OF_getencprop_alloc(). OF_nextprop() copies 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 does not exist the function tries to create it. OF_setprop() returns the actual size of the new value, or -1 if the property value cannot be changed or the new property cannot be created.

EXAMPLES

SEE ALSO

OF_device_from_xref(9) OF_node_from_xref(9)

AUTHORS

This manual page was written by Oleksandr Tymoshenko <gonzo@FreeBSD.org>.