Page MenuHomeFreeBSD
Files F156711912

D14511.id39726.diff
No OneTemporary
Actions

D14511.id39726.diff
View Options

Index: share/man/man9/Makefile
===================================================================
--- share/man/man9/Makefile
+++ share/man/man9/Makefile
@@ -206,6 +206,12 @@
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 \
osd.9 \
owll.9 \
own.9 \
@@ -1516,6 +1522,21 @@
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 \
+ 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+=osd.9 osd_call.9 \
osd.9 osd_del.9 \
osd.9 osd_deregister.9 \
Index: share/man/man9/OF_child.9
===================================================================
--- /dev/null
+++ share/man/man9/OF_child.9
@@ -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 February 25, 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 phandle value of the first child of the
+.Fa node .
+0 if there are no child nodes.
+.Pp
+.Fn OF_parent
+returns phandle for the parent of the
+.Fa node
+0 if
+.Fa node
+is the root node.
+.Pp
+.Fn OF_peer
+returns phandle value of the next sibling of the
+.Fa node .
+0 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 .
Index: share/man/man9/OF_device_from_xref.9
===================================================================
--- /dev/null
+++ share/man/man9/OF_device_from_xref.9
@@ -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 February 25, 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 device tree node references another node, the driver may
+need to get device associated with the referenced node.
+For instance, ethernet driver accessing PHY device.
+To make this possible, the kernel maintains the table that
+maps effective handles to device_t instances.
+.Pp
+.Fn OF_device_register_xref
+adds map entry from effective phandle
+.Fa xref
+to device
+.Fa dev .
+If mapping entry for
+.Fa xref
+already exists, it is replaced with new one.
+The function always returns 0.
+.Pp
+.Fn OF_device_from_xref
+returns device_t instance associated with effective phandle
+.Fa xref .
+If no such mapping exists, the function returns NULL.
+.Pp
+.Fn OF_xref_from_device
+returns effective phandle associated with 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 .
Index: share/man/man9/OF_finddevice.9
===================================================================
--- /dev/null
+++ share/man/man9/OF_finddevice.9
@@ -0,0 +1,71 @@
+.\"
+.\" 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 February 25, 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 phandle for the node specified by the
+.Fa path .
+-1 if the path cannot be found in the tree.
+.Sh CAVEATS
+Return value should be checked only using equality
+operators (==, !=) and not relational comparison
+( <, > ). There is a discrepancy between IEEE 1275 standard and
+FreeBSD internal representation of phandle: IEEE 1275
+requires return value of this function to be -1 if path
+is not found but phandle_t is 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 .
Index: share/man/man9/OF_getprop.9
===================================================================
--- /dev/null
+++ share/man/man9/OF_getprop.9
@@ -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 February 25, 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 properties associated with them.
+Properties consist of name and value.
+A name is a human-readable string from 1 to 31 characters long.
+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 combination of any of these types.
+.Pp
+Property with zero bytes long 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 its 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 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 value associated with it
+or -1 if the property
+.Fa propname
+does not exist.
+.Pp
+.Fn OF_getprop
+copies 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 .
+The function returns actual size of the value or -1 if the
+property does not exist.
+.Pp
+.Fn OF_getencprop
+copies maximum of
+.Fa len
+bytes into memory specified by
+.Fa buf ,
+and then converts cell values from big-endian to host byte order.
+The function returns actual size of the value in bytes or -1
+if the property does not exist.
+.Fa len
+should be multiply of 4.
+.Pp
+.Fn OF_hasprop
+returns 1 if the device node
+.Fa node
+has property specified by
+.Fa propname ,
+and zero if there is 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 max
+.Fa len
+bytes of the value associated with the property
+into the memory specified by
+.Fa buf .
+The function returns actual size in bytes of the value,
+and -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 max
+.Fa len
+bytes of the value associated with the property
+into the memory specified by
+.Fa buf ,
+and then converts cell values from big-endian to host byte order.
+The function returns actual size in bytes of the value,
+and -1 if the property does not exist.
+.Pp
+.Fn OF_getprop_alloc
+allocates the amount of memory large enough to fit 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 function returns actual size of the value and stores
+address of allocated memory in
+.Fa *buf .
+If the property has zero-sized value
+.Fa *buf
+is set NULL.
+The function return -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 may sleep when allocating memory.
+.Pp
+.Fn OF_getencprop_alloc
+allocates the amount of memory large enough to fit 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 function returns actual size of the value and stores
+address of allocated memory in
+.Fa *buf .
+If the property has zero-sized value
+.Fa *buf
+is set NULL.
+The function return -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 may sleep when allocating memory.
+.Pp
+.Fn OF_prop_free
+releases memory at
+.Fa buf
+allocated by
+.Fn OF_getprop_alloc
+and
+.Fn OF_getencprop_alloc .
+.Pp
+.Fn OF_nextprop
+copies 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 .
Index: share/man/man9/OF_node_from_xref.9
===================================================================
--- /dev/null
+++ share/man/man9/OF_node_from_xref.9
@@ -0,0 +1,87 @@
+.\"
+.\" 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 February 25, 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, framebuffer controller may refer to GPIO
+controller and pin that controls the backlight.
+For such implementations, phandle used by the kernel to
+identify node does not match the value of cell property that
+points to the referred node.
+Otherwise, effective phandle is equal to the kernel phandle.
+.Pp
+.Pp
+.Fn OF_node_from_xref
+returns kernel phandle for the effective phandle
+.Fa xref .
+If one cannot be found or OpenFirmware implementation
+does not support effective phandles, the function returns
+input value.
+.Pp
+.Fn OF_xref_from_xref
+returns effective phandle for the kernel phandle
+.Fa xref .
+If one cannot be found or OpenFirmware implementation
+does not support effective phandles, the function returns
+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 .
Index: share/man/man9/OF_package_to_path.9
===================================================================
--- /dev/null
+++ share/man/man9/OF_package_to_path.9
@@ -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 February 25, 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 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 .

File Metadata

Mime Type
text/plain
Expires
Sat, May 16, 8:24 PM (8 h, 29 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
33125423
Default Alt Text
D14511.id39726.diff (23 KB)

Event Timeline