[man] Add documentation for OpenFirmware API
Add man pages for following OpenFirmware functions: OF_child, OF_parent, OF_peer, OF_device_from_xref, OF_device_register_xref, OF_xref_from_device, OF_getprop, OF_getencprop, OF_getencprop_alloc, OF_getprop_alloc, OF_getproplen, OF_hasprop, OF_nextprop, OF_prop_free, OF_searchencprop, OF_searchprop, OF_setprop Edited by: wblock MFC after: 3 days Differential Revision: https://reviews.freebsd.org/D14511
This commit is contained in:
Oleksandr Tymoshenko
parent
f7604b1b27
commit
ac32b99c2b
@ -208,6 +208,12 @@ MAN= accept_filter.9 \
|
||||
namei.9 \
|
||||
netisr.9 \
|
||||
nv.9 \
|
||||
OF_child.9 \
|
||||
OF_device_from_xref.9 \
|
||||
OF_finddevice.9 \
|
||||
OF_getprop.9 \
|
||||
OF_node_from_xref.9 \
|
||||
OF_package_to_path.9 \
|
||||
ofw_bus_is_compatible.9 \
|
||||
ofw_bus_status_okay.9 \
|
||||
osd.9 \
|
||||
@ -1527,6 +1533,21 @@ MLINKS+=nv.9 libnv.9 \
|
||||
nv.9 nvlist_take_string_array.9 \
|
||||
nv.9 nvlist_unpack.9 \
|
||||
nv.9 nvlist_xfer.9
|
||||
MLINKS+=OF_child.9 OF_parent.9 \
|
||||
OF_child.9 OF_peer.9
|
||||
MLINKS+=OF_device_from_xref.9 OF_device_register_xref.9 \
|
||||
OF_device_from_xref.9 OF_xref_from_device.9
|
||||
MLINKS+=OF_getprop.9 OF_getencprop.9 \
|
||||
OF_getprop.9 OF_getencprop_alloc.9 \
|
||||
OF_getprop.9 OF_getprop_alloc.9 \
|
||||
OF_getprop.9 OF_getproplen.9 \
|
||||
OF_getprop.9 OF_hasprop.9 \
|
||||
OF_getprop.9 OF_nextprop.9 \
|
||||
OF_getprop.9 OF_prop_free.9 \
|
||||
OF_getprop.9 OF_searchencprop.9 \
|
||||
OF_getprop.9 OF_searchprop.9 \
|
||||
OF_getprop.9 OF_setprop.9
|
||||
MLINKS+=OF_node_from_xref.9 OF_xref_from_node.9
|
||||
MLINKS+=ofw_bus_is_compatible.9 ofw_bus_is_compatible_strict.9 \
|
||||
ofw_bus_is_compatible.9 ofw_bus_node_is_compatible.9 \
|
||||
ofw_bus_is_compatible.9 ofw_bus_search_compatible.9
|
||||
|
||||
76
share/man/man9/OF_child.9
Normal file
76
share/man/man9/OF_child.9
Normal file
@ -0,0 +1,76 @@
|
||||
.\"
|
||||
.\" 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 April 9, 2018
|
||||
.Dt OF_CHILD 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm OF_child ,
|
||||
.Nm OF_parent ,
|
||||
.Nm OF_peer
|
||||
.Nd navigate device tree
|
||||
.Sh SYNOPSIS
|
||||
.In dev/ofw/ofw_bus.h
|
||||
.In dev/ofw/ofw_bus_subr.h
|
||||
.Ft phandle_t
|
||||
.Fn OF_child "phandle_t node"
|
||||
.Ft phandle_t
|
||||
.Fn OF_parent "phandle_t node"
|
||||
.Ft phandle_t
|
||||
.Fn OF_peer "phandle_t node"
|
||||
.Sh DESCRIPTION
|
||||
.Pp
|
||||
.Fn OF_child
|
||||
returns the phandle value of the first child of the
|
||||
.Fa node .
|
||||
Zero is returned if there are no child nodes.
|
||||
.Pp
|
||||
.Fn OF_parent
|
||||
returns the phandle for the parent of the
|
||||
.Fa node .
|
||||
Zero is returned if
|
||||
.Fa node
|
||||
is the root node.
|
||||
.Pp
|
||||
.Fn OF_peer
|
||||
returns the phandle value of the next sibling of the
|
||||
.Fa node .
|
||||
Zero is returned if there is no sibling node.
|
||||
.Sh EXAMPLES
|
||||
.Bd -literal
|
||||
phandle_t node, child;
|
||||
...
|
||||
for (child = OF_child(node); child != 0; child = OF_peer(child) {
|
||||
...
|
||||
}
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr OF_finddevice 9
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This manual page was written by
|
||||
.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .
|
||||
91
share/man/man9/OF_device_from_xref.9
Normal file
91
share/man/man9/OF_device_from_xref.9
Normal file
@ -0,0 +1,91 @@
|
||||
.\"
|
||||
.\" 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 April 9, 2018
|
||||
.Dt OF_DEVICE_FROM_XREF 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm OF_device_from_xref ,
|
||||
.Nm OF_xref_from_device,
|
||||
.Nm OF_device_register_xref
|
||||
.Nd "manage mappings between xrefs and devices"
|
||||
.Sh SYNOPSIS
|
||||
.In dev/ofw/ofw_bus.h
|
||||
.In dev/ofw/ofw_bus_subr.h
|
||||
.Ft int
|
||||
.Fn OF_device_register_xref "phandle_t xref" "device_t dev"
|
||||
.Ft device_t
|
||||
.Fn OF_device_from_xref "phandle_t xref"
|
||||
.Ft phandle_t
|
||||
.Fn OF_xref_from_device "device_t dev"
|
||||
.Sh DESCRIPTION
|
||||
.Pp
|
||||
When a device tree node references another node, the driver may
|
||||
need to get a device_t instance associated with the referenced node.
|
||||
For instance, an Ethernet driver accessing a PHY device.
|
||||
To make this possible, the kernel maintains a table that
|
||||
maps effective handles to device_t instances.
|
||||
.Pp
|
||||
.Fn OF_device_register_xref
|
||||
adds a map entry from the effective phandle
|
||||
.Fa xref
|
||||
to device
|
||||
.Fa dev .
|
||||
If a mapping entry for
|
||||
.Fa xref
|
||||
already exists, it is replaced with the new one.
|
||||
The function always returns 0.
|
||||
.Pp
|
||||
.Fn OF_device_from_xref
|
||||
returns a device_t instance associated with the effective phandle
|
||||
.Fa xref .
|
||||
If no such mapping exists, the function returns NULL.
|
||||
.Pp
|
||||
.Fn OF_xref_from_device
|
||||
returns the effective phandle associated with the device
|
||||
.Fa dev .
|
||||
If no such mapping exists, the function returns 0.
|
||||
.Sh EXAMPLES
|
||||
.Bd -literal
|
||||
static int
|
||||
acmephy_attach(device_t dev)
|
||||
{
|
||||
phandle_t node;
|
||||
|
||||
/* PHY node is referenced from eth device, register it */
|
||||
node = ofw_bus_get_node(dev);
|
||||
OF_device_register_xref(OF_xref_from_node(node), dev);
|
||||
|
||||
return (0);
|
||||
}
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr OF_node_to_xref 9
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This manual page was written by
|
||||
.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .
|
||||
74
share/man/man9/OF_finddevice.9
Normal file
74
share/man/man9/OF_finddevice.9
Normal file
@ -0,0 +1,74 @@
|
||||
.\"
|
||||
.\" 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 April 9, 2018
|
||||
.Dt OF_FINDDEVICE 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm OF_finddevice
|
||||
.Nd find node in device tree
|
||||
.Sh SYNOPSIS
|
||||
.In dev/ofw/ofw_bus.h
|
||||
.In dev/ofw/ofw_bus_subr.h
|
||||
.Ft phandle_t
|
||||
.Fn OF_finddevice "const char *path"
|
||||
.Sh DESCRIPTION
|
||||
.Pp
|
||||
.Fn OF_finddevice
|
||||
returns the phandle for the node specified by the
|
||||
.Fa path .
|
||||
Returns -1 if the path cannot be found in the tree.
|
||||
.Sh CAVEATS
|
||||
The return value should only be checked with equality
|
||||
operators (equal to, not equal to) and not relational comparison
|
||||
(less than, greater than ).
|
||||
There is a discrepancy between IEEE 1275 standard and
|
||||
.Fx Ns 's
|
||||
internal representation of a phandle: IEEE 1275
|
||||
requires the return value of this function to be -1 if the path
|
||||
is not found.
|
||||
But phandle_t is an unsigned type, so it cannot
|
||||
be relationally compared with -1 or 0, this comparison
|
||||
is always true or always false.
|
||||
.Sh EXAMPLES
|
||||
.Bd -literal
|
||||
phandle_t root, i2c;
|
||||
|
||||
root = OF_finddevice("/");
|
||||
i2c = OF_finddevice("/soc/axi/i2c@a0e0000");
|
||||
if (i2c != -1) {
|
||||
...
|
||||
}
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr OF_child 9
|
||||
.Xr OF_parent 9
|
||||
.Xr OF_peer 9
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This manual page was written by
|
||||
.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .
|
||||
291
share/man/man9/OF_getprop.9
Normal file
291
share/man/man9/OF_getprop.9
Normal file
@ -0,0 +1,291 @@
|
||||
.\"
|
||||
.\" 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 April 9, 2018
|
||||
.Dt OF_CHILD 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_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 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.
|
||||
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
|
||||
or
|
||||
.Fn OF_getencprop_alloc .
|
||||
.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 .
|
||||
100
share/man/man9/OF_node_from_xref.9
Normal file
100
share/man/man9/OF_node_from_xref.9
Normal file
@ -0,0 +1,100 @@
|
||||
.\"
|
||||
.\" 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 April 9, 2018
|
||||
.Dt OF_NODE_FROM_XREF 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm OF_node_from_xref ,
|
||||
.Nm OF_xref_from_node
|
||||
.Nd convert between kernel phandle and effective phandle
|
||||
.Sh SYNOPSIS
|
||||
.In dev/ofw/ofw_bus.h
|
||||
.In dev/ofw/ofw_bus_subr.h
|
||||
.Ft phandle_t
|
||||
.Fn OF_node_from_xref "phandle_t xref"
|
||||
.Ft phandle_t
|
||||
.Fn OF_xref_from_node "phandle_t node"
|
||||
.Sh DESCRIPTION
|
||||
.Pp
|
||||
Some OpenFirmware implementations (FDT, IBM) have a concept
|
||||
of effective phandle or xrefs.
|
||||
They are used to cross-reference device tree nodes.
|
||||
For instance, a framebuffer controller may refer to a GPIO
|
||||
controller and pin that controls the backlight.
|
||||
In this example, the GPIO node would have a cell (32-bit integer)
|
||||
property with a reserved name like "phandle" or "linux,phandle"
|
||||
whose value uniquely identifies the node.
|
||||
The actual name depends on the implementation.
|
||||
The framebuffer node would have a property with the name
|
||||
described by device bindings (device-specific set of properties).
|
||||
It can be a cell property or a combined property with one part
|
||||
of it being a cell.
|
||||
The value of the framebuffer node's property would be the same
|
||||
as the value of the GPIO "phandle" property so it can be said
|
||||
that the framebuffer node refers to the GPIO node.
|
||||
The kernel uses internal logic to assign unique identifiers
|
||||
to the device tree nodes, and these values do not match
|
||||
the values of "phandle" properties.
|
||||
.Fn OF_node_from_xref
|
||||
and
|
||||
.Fn OF_xref_from_node
|
||||
are used to perform conversion between these two kinds of node
|
||||
identifiers.
|
||||
.Pp
|
||||
.Fn OF_node_from_xref
|
||||
returns the kernel phandle for the effective phandle
|
||||
.Fa xref .
|
||||
If one cannot be found or the OpenFirmware implementation
|
||||
does not support effective phandles, the function returns
|
||||
the input value.
|
||||
.Pp
|
||||
.Fn OF_xref_from_xref
|
||||
returns the effective phandle for the kernel phandle
|
||||
.Fa xref .
|
||||
If one cannot be found or the OpenFirmware implementation
|
||||
does not support effective phandles, the function returns
|
||||
the input value.
|
||||
.Sh EXAMPLES
|
||||
.Bd -literal
|
||||
phandle_t panelnode, panelxref;
|
||||
char *model;
|
||||
|
||||
if (OF_getencprop(node, "lcd-panel", &panelxref) <= 0)
|
||||
return;
|
||||
|
||||
panelnode = OF_node_from_xref(panelxref);
|
||||
if (OF_getprop_alloc(hdminode, "model", (void **)&model) <= 0)
|
||||
return;
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr OF_device_from_xref 9
|
||||
.Xr OF_device_register_xref 9
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This manual page was written by
|
||||
.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .
|
||||
54
share/man/man9/OF_package_to_path.9
Normal file
54
share/man/man9/OF_package_to_path.9
Normal file
@ -0,0 +1,54 @@
|
||||
.\"
|
||||
.\" 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 April 9, 2018
|
||||
.Dt OF_PACKAGE_TO_PATH 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm OF_package_to_path
|
||||
.Nd get fully qualified path to a device tree node
|
||||
.Sh SYNOPSIS
|
||||
.In dev/ofw/ofw_bus.h
|
||||
.In dev/ofw/ofw_bus_subr.h
|
||||
.Ft ssize_t
|
||||
.Fn OF_package_to_path "phandle_t node" "char *buf" "size_t len"
|
||||
.Sh DESCRIPTION
|
||||
.Pp
|
||||
.Fn OF_package_to_path
|
||||
copies at most
|
||||
.Fa len
|
||||
bytes of the fully qualified path to the device tree node
|
||||
.Fa node
|
||||
into the memory specified by
|
||||
.Fa buf .
|
||||
The function returns the number of bytes copied or -1 in case of the error.
|
||||
.Sh SEE ALSO
|
||||
.Xr OF_finddevice 9
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This manual page was written by
|
||||
.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .
|
||||
Loading…
Reference in New Issue
Block a user