80cb7cd44c
Add documentation and symlinks for OF_getprop_alloc_multi and OF_getencprop_alloc_multi functions. Also while here fix copy-pasted .Dt value and add one more failure condition for OF_getencprop_alloc.
354 lines
10 KiB
Groff
354 lines
10 KiB
Groff
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.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 .
|