.\" .\" Copyright (c) 2018 Oleksandr Tymoshenko .\" .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD: releng/12.0/share/man/man9/OF_getprop.9 335587 2018-06-23 20:05:07Z gonzo $ .\" .Dd June 23, 2018 .Dt OF_GETPROP 9 .Os .Sh NAME .Nm OF_getprop , .Nm OF_getproplen , .Nm OF_getencprop , .Nm OF_hasprop , .Nm OF_searchprop , .Nm OF_searchencprop , .Nm OF_getprop_alloc , .Nm OF_getencprop_alloc , .Nm OF_getprop_alloc_multi , .Nm OF_getencprop_alloc_multi , .Nm OF_prop_free , .Nm OF_nextprop , .Nm OF_setprop .Nd access properties of device tree node .Sh SYNOPSIS .In dev/ofw/ofw_bus.h .In dev/ofw/ofw_bus_subr.h .Ft ssize_t .Fn OF_getproplen "phandle_t node" "const char *propname" .Ft ssize_t .Fn OF_getprop "phandle_t node" "const char *propname" \ "void *buf" "size_t len" .Ft ssize_t .Fn OF_getencprop "phandle_t node" "const char *prop" \ "pcell_t *buf" "size_t len" .Ft int .Fn OF_hasprop "phandle_t node" "const char *propname" .Ft ssize_t .Fn OF_searchprop "phandle_t node" "const char *propname" \ "void *buf" "size_t len" .Ft ssize_t .Fn OF_searchencprop "phandle_t node" "const char *propname" \ "pcell_t *buf" "size_t len" .Ft ssize_t .Fn OF_getprop_alloc "phandle_t node" "const char *propname" \ "void **buf" .Ft ssize_t .Fn OF_getencprop_alloc "phandle_t node" "const char *propname" \ "pcell_t **buf" .Ft ssize_t .Fn OF_getprop_alloc_multi "phandle_t node" "const char *propname" \ "int elsz" "void **buf" .Ft ssize_t .Fn OF_getencprop_alloc_multi "phandle_t node" "const char *propname" \ "int elsz" "pcell_t **buf" .Ft void .Fn OF_prop_free "void *buf" .Ft int .Fn OF_nextprop "phandle_t node" "const char *propname" \ "char *buf" "size_t len" .Ft int .Fn OF_setprop "phandle_t node" "const char *propname" \ "const void *buf" "size_t len" .Sh DESCRIPTION .Pp Device nodes can have associated properties. Properties consist of a name and a value. A name is a human-readable string from 1 to 31 characters long. A 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 any combination of these types. .Pp Property with a zero-length value usually represents boolean information. If the property is present, it signifies true, otherwise false. .Pp A byte array is encoded as a sequence of bytes and represents values like MAC addresses. .Pp 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 a terminating null character. .Pp Unsigned 32-bit values, also sometimes called cells, are encoded as a sequence of 4 bytes in big-endian order. .Pp .Fn OF_getproplen returns either the length of the value associated with the property .Fa propname in the node identified by .Fa node , or 0 if the property exists but has no associated value. If .Fa propname does not exist, -1 is returned. .Pp .Fn OF_getprop copies a maximum of .Fa len bytes from the value associated with the property .Fa propname of the device node .Fa node into the memory specified by .Fa buf . Returns the actual size of the value or -1 if the property does not exist. .Pp .Fn OF_getencprop copies a maximum of .Fa len bytes into memory specified by .Fa 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 does not exist. .Fa len must be a multiple of 4. .Pp .Fn OF_hasprop returns 1 if the device node .Fa node has a property specified by .Fa propname , and zero if the property does not exist. .Pp .Fn OF_searchprop recursively looks for the property specified by .Fa propname starting with the device node .Fa node followed by the parent node and up to the root node. If the property is found, the function copies a maximum of .Fa len bytes of the value associated with the property into the memory specified by .Fa buf . Returns the actual size in bytes of the value, or -1 if the property does not exist. .Pp .Fn OF_searchencprop recursively looks for the property specified by .Fa propname starting with the device node .Fa node followed by the parent node and up to the root node. If the property is found, the function copies a maximum of .Fa len bytes of the value associated with the property into the memory specified by .Fa 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 does not exist. .Pp .Fn OF_getprop_alloc allocates memory large enough to hold the value associated with the property .Fa propname of the device node .Fa 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 .Fa *buf . If the property has a zero-sized value .Fa *buf is set NULL. Returns -1 if the property does not exist or memory allocation failed. Allocated memory should be released when no longer required by calling .Fn OF_prop_free . The function might sleep when allocating memory. .Pp .Fn OF_getencprop_alloc allocates enough memory to hold the value associated with the property .Fa propname of the device node .Fa 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 .Fa *buf . If the property has zero-length value, .Fa *buf is set to NULL. Returns -1 if the property does not 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 .Fn OF_prop_free . The function might sleep when allocating memory. .Pp .Fn OF_getprop_alloc_multi allocates memory large enough to hold the value associated with the property .Fa propname of the device node .Fa node and copies the value into the newly allocated memory region. The value is expected to be an array of zero or more elements .Fa elsz bytes long. Returns the number of elements in the value and stores the address of the allocated memory in .Fa *buf . If the property has a zero-sized value .Fa *buf is set NULL. Returns -1 if the property does not exist or memory allocation failed or the size of the value is not divisible by .Fa elsz . Allocated memory should be released when no longer required by calling .Fn OF_prop_free . The function might sleep when allocating memory. .Pp .Fn OF_getencprop_alloc_multi allocates memory large enough to hold the value associated with the property .Fa propname of the device node .Fa node and 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 .Fa elsz bytes long. Returns the number of elements in the value and stores the address of the allocated memory in .Fa *buf . If the property has a zero-sized value .Fa *buf is set NULL. Returns -1 if the property does not exist or memory allocation failed or the size of the value is not divisible by .Fa elsz . Allocated memory should be released when no longer required by calling .Fn OF_prop_free . The function might sleep when allocating memory. .Pp .Fn OF_prop_free releases memory at .Fa buf that was allocated by .Fn OF_getprop_alloc , .Fn OF_getencprop_alloc , .Fn OF_getprop_alloc_multi , .Fn OF_getencprop_alloc_multi . .Pp .Fn OF_nextprop copies a maximum of .Fa size bytes of the name of the property following the .Fa propname property into .Fa buf . If .Fa propname is NULL, the function copies the name of the first property of the device node .Fa node . .Fn OF_nextprop returns -1 if .Fa propname is invalid or there is an internal error, 0 if there are no more properties after .Fa propname , or 1 otherwise. .Pp .Fn OF_setprop sets the value of the property .Fa propname in the device node .Fa node to the value beginning at the address specified by .Fa buf and running for .Fa len bytes. If the property does not exist, the function tries to create it. .Fn 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. .Sh EXAMPLES .Bd -literal 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; .Ed .Sh SEE ALSO .Xr OF_device_from_xref 9 .Xr OF_node_from_xref 9 .Sh AUTHORS .An -nosplit This manual page was written by .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .