Date: Mon, 9 Apr 2018 22:23:45 +0000 (UTC) From: Oleksandr Tymoshenko <gonzo@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r332342 - head/share/man/man9 Message-ID: <201804092223.w39MNjp5007268@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: gonzo Date: Mon Apr 9 22:23:45 2018 New Revision: 332342 URL: https://svnweb.freebsd.org/changeset/base/332342 Log: [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 Added: head/share/man/man9/OF_child.9 (contents, props changed) head/share/man/man9/OF_device_from_xref.9 (contents, props changed) head/share/man/man9/OF_finddevice.9 (contents, props changed) head/share/man/man9/OF_getprop.9 (contents, props changed) head/share/man/man9/OF_node_from_xref.9 (contents, props changed) head/share/man/man9/OF_package_to_path.9 (contents, props changed) Modified: head/share/man/man9/Makefile Modified: head/share/man/man9/Makefile ============================================================================== --- head/share/man/man9/Makefile Mon Apr 9 22:06:16 2018 (r332341) +++ head/share/man/man9/Makefile Mon Apr 9 22:23:45 2018 (r332342) @@ -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 Added: head/share/man/man9/OF_child.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/OF_child.9 Mon Apr 9 22:23:45 2018 (r332342) @@ -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 . Added: head/share/man/man9/OF_device_from_xref.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/OF_device_from_xref.9 Mon Apr 9 22:23:45 2018 (r332342) @@ -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 . Added: head/share/man/man9/OF_finddevice.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/OF_finddevice.9 Mon Apr 9 22:23:45 2018 (r332342) @@ -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 . Added: head/share/man/man9/OF_getprop.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/OF_getprop.9 Mon Apr 9 22:23:45 2018 (r332342) @@ -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 . Added: head/share/man/man9/OF_node_from_xref.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/OF_node_from_xref.9 Mon Apr 9 22:23:45 2018 (r332342) @@ -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 . Added: head/share/man/man9/OF_package_to_path.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/OF_package_to_path.9 Mon Apr 9 22:23:45 2018 (r332342) @@ -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 .
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201804092223.w39MNjp5007268>