upstream/opnsense-src
1
0
Fork 0
mirror of https://github.com/opnsense/src.git synced 2026-06-09 00:32:25 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

[man] Add documentation for OpenFirmware API

Browse source 
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 2018-04-09 22:23:45 +00:00
parent f7604b1b27
commit ac32b99c2b
7 changed files with 707 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
share/man/man9/Makefile
View file

@ -208,6 +208,12 @@ MAN= accept_filter.9 \
namei.9 \ namei.9 \
netisr.9 \ netisr.9 \
nv.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_is_compatible.9 \
ofw_bus_status_okay.9 \ ofw_bus_status_okay.9 \
osd.9 \ osd.9 \
@ -1527,6 +1533,21 @@ MLINKS+=nv.9 libnv.9 \
nv.9 nvlist_take_string_array.9 \ nv.9 nvlist_take_string_array.9 \
nv.9 nvlist_unpack.9 \ nv.9 nvlist_unpack.9 \
nv.9 nvlist_xfer.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 \ 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_node_is_compatible.9 \
ofw_bus_is_compatible.9 ofw_bus_search_compatible.9 ofw_bus_is_compatible.9 ofw_bus_search_compatible.9

76
share/man/man9/OF_child.9 Normal file
View 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
View 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
View 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
View 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
View 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
View 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 .