Page MenuHomeFreeBSD
Files F144627037

D14511.1775862395.diff
No OneTemporary
Actions

Size
24 KB
Referenced Files
None
Subscribers
None

D14511.1775862395.diff
View Options

Index: head/share/man/man9/Makefile
===================================================================
--- head/share/man/man9/Makefile
+++ head/share/man/man9/Makefile
@@ -208,6 +208,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 \
ofw_bus_is_compatible.9 \
ofw_bus_status_okay.9 \
osd.9 \
@@ -1527,6 +1533,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.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
Index: head/share/man/man9/OF_child.9
===================================================================
--- head/share/man/man9/OF_child.9
+++ head/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 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 .
Index: head/share/man/man9/OF_device_from_xref.9
===================================================================
--- head/share/man/man9/OF_device_from_xref.9
+++ head/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 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 .
Index: head/share/man/man9/OF_finddevice.9
===================================================================
--- head/share/man/man9/OF_finddevice.9
+++ head/share/man/man9/OF_finddevice.9
@@ -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 .
Index: head/share/man/man9/OF_getprop.9
===================================================================
--- head/share/man/man9/OF_getprop.9
+++ head/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 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 .
Index: head/share/man/man9/OF_node_from_xref.9
===================================================================
--- head/share/man/man9/OF_node_from_xref.9
+++ head/share/man/man9/OF_node_from_xref.9
@@ -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 .
Index: head/share/man/man9/OF_package_to_path.9
===================================================================
--- head/share/man/man9/OF_package_to_path.9
+++ head/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 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 .

File Metadata

Mime Type
text/plain
Expires
Fri, Apr 10, 11:06 PM (4 h, 14 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
28320602
Default Alt Text
D14511.1775862395.diff (24 KB)

Event Timeline