Changeset View
Changeset View
Standalone View
Standalone View
share/man/man9/OF_node_from_xref.9
- This file was added.
.\" | |||||
.\" 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 | |||||
wblockUnsubmitted Done Inline Actionswblock: ```For instance, a framebuffer controller may refer to a GPIO``` | |||||
controller and pin that controls the backlight. | |||||
For such implementations, phandle used by the kernel to | |||||
wblockUnsubmitted Done Inline ActionsFor such implementations, the phandle is used by the kernel to wblock: ```For such implementations, the phandle is used by the kernel to``` | |||||
identify node does not match the value of cell property that | |||||
wblockUnsubmitted Done Inline Actionsidentify the node does not match the value of the cell property that wblock: ```identify the node does not match the value of the cell property that```
| |||||
points to the referred node. | |||||
wblockUnsubmitted Done Inline ActionsThis sentence is difficult to understand. wblock: This sentence is difficult to understand. | |||||
gonzoAuthorUnsubmitted Not Done Inline ActionsI added more details to the example to illustrate the concept of reference. gonzo: I added more details to the example to illustrate the concept of reference. | |||||
Otherwise, effective phandle is equal to the kernel phandle. | |||||
wblockUnsubmitted Done Inline ActionsOtherwise, the effective phandle is equal to the kernel phandle. wblock: ```Otherwise, the effective phandle is equal to the kernel phandle.``` | |||||
.Pp | |||||
.Pp | |||||
.Fn OF_node_from_xref | |||||
returns kernel phandle for the effective phandle | |||||
wblockUnsubmitted Done Inline Actionsreturns the kernel phandle for the effective phandle wblock: ```returns the kernel phandle for the effective phandle```
| |||||
.Fa xref . | |||||
If one cannot be found or OpenFirmware implementation | |||||
wblockUnsubmitted Done Inline ActionsIf one cannot be found or the OpenFirmware implementation wblock: ```If one cannot be found or the OpenFirmware implementation``` | |||||
does not support effective phandles, the function returns | |||||
input value. | |||||
wblockUnsubmitted Done Inline Actionsthe input value. wblock: ```the input value.``` | |||||
.Pp | |||||
.Fn OF_xref_from_xref | |||||
returns effective phandle for the kernel phandle | |||||
wblockUnsubmitted Done Inline Actionsreturns the effective phandle for the kernel phandle wblock: ```returns the effective phandle for the kernel phandle``` | |||||
.Fa xref . | |||||
If one cannot be found or OpenFirmware implementation | |||||
wblockUnsubmitted Done Inline ActionsIf one cannot be found or the OpenFirmware implementation wblock: ```If one cannot be found or the OpenFirmware implementation``` | |||||
does not support effective phandles, the function returns | |||||
input value. | |||||
wblockUnsubmitted Done Inline Actionsthe input value. wblock: ```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 . |