diff options
Diffstat (limited to 'static/freebsd/man9/OF_getprop.9')
| -rw-r--r-- | static/freebsd/man9/OF_getprop.9 | 354 |
1 files changed, 354 insertions, 0 deletions
diff --git a/static/freebsd/man9/OF_getprop.9 b/static/freebsd/man9/OF_getprop.9 new file mode 100644 index 00000000..8c93d92b --- /dev/null +++ b/static/freebsd/man9/OF_getprop.9 @@ -0,0 +1,354 @@ +.\" +.\" Copyright (c) 2018 Oleksandr Tymoshenko <gonzo@FreeBSD.org> +.\" +.\" 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. +.\" +.Dd April 16, 2026 +.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 bool +.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 +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 +.Dv true +if the device node +.Fa node +has a property specified by +.Fa propname , +and +.Dv false +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 . |