d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document ofw_bus_subr helpers "compatible" and "status" properties

Browse Source 
Add documentation for following functions:

- ofw_bus_is_compatible
- ofw_bus_is_compatible_strict
- ofw_bus_node_is_compatible
- ofw_bus_search_compatible
- ofw_bus_get_status
- ofw_bus_status_okay
- ofw_bus_node_status_okay

MFC after:	1 week
Differential Revision:	https://reviews.freebsd.org/D14724
This commit is contained in:
Oleksandr Tymoshenko 2018-04-08 20:53:00 +00:00
parent b4b4b17687
commit f510c340ce
3 changed files with 231 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
share/man/man9/Makefile
View File

@ -208,6 +208,8 @@ MAN= accept_filter.9 \
namei.9 \
netisr.9 \
nv.9 \
ofw_bus_is_compatible.9 \
ofw_bus_status_okay.9 \
osd.9 \
owll.9 \
own.9 \
@ -1525,6 +1527,11 @@ MLINKS+=nv.9 libnv.9 \
nv.9 nvlist_take_string_array.9 \
nv.9 nvlist_unpack.9 \
nv.9 nvlist_xfer.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
MLINKS+= ofw_bus_status_okay.9 ofw_bus_get_status.9 \
ofw_bus_status_okay.9 ofw_bus_node_status_okay.9
MLINKS+=osd.9 osd_call.9 \
osd.9 osd_del.9 \
osd.9 osd_deregister.9 \

147
share/man/man9/ofw_bus_is_compatible.9 Normal file
View File

@ -0,0 +1,147 @@
.\" -*- nroff -*-
.\"
.\" Copyright (c) 2018 Oleksandr Tymoshenko
.\"
.\" All rights reserved.
.\"
.\" This program is free software.
.\"
.\" 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 8, 2018
.Dt ofw_bus_is_compatible 9
.Os
.Sh NAME
.Nm ofw_bus_is_compatible
.Nm ofw_bus_is_compatible_strict
.Nm ofw_bus_node_is_compatible
.Nm ofw_bus_search_compatible
.Nd check device tree nodes for compatibility with drivers
.Sh SYNOPSIS
.In dev/ofw/openfirm.h
.In dev/ofw/ofw_bus.h
.In dev/ofw/ofw_bus_subr.h
.Ft int
.Fn ofw_bus_is_compatible "device_t dev" "const char *compatstr"
.Ft int
.Fn ofw_bus_is_compatible_strict "device_t dev" "const char *compatstr"
.Ft int
.Fn ofw_bus_node_is_compatible "phandle_t node" "const char *compatstr"
.Ft const struct ofw_compat_data *
.Fn ofw_bus_search_compatible "device_t dev" "const struct ofw_compat_data *compat"
.Sh DESCRIPTION
.Pp
The "compatible" property of the device tree node is used to
identify the type of the device the node represents.
The property is a list of one or more strings that represent
hardware types the device is compatible with.
The common format for such strings is "vendor,hardware"
where "vendor" is an abbreviated name of the manufacturer
and "hardware" is a device identifier, for instance, "fsl"
for "Freescale" and "imx6ul-i2c" for the I2C controller.
More than one string is required for compatibility with
older revisions of the driver.
If hardware revision B is backward compatible with revision
A device tree node can signal this compatibility by
providing both "vndr,hrdwrA" and "vndr,hrdwrB" strings in
the "compatibile" property value.
This way older driver can use features available only in
revision A, and the new version of the driver can take
advantage of revision B feature set.
.Pp
.Fn ofw_bus_is_compatible
returns 1 if the
.Fa compatstr
value occurs in the "compatible" property list of the device
tree node associated with the device
.Fa dev ,
and 0 otherwise.
.Pp
.Fn ofw_bus_is_compatible_strict
return 1 if the "compatible"
property of the device tree node associated with the device
.Fa dev
consists of only one string and this string is equal to
.Fa compatstr ,
and 0 otherwise.
.Pp
.Fn ofw_bus_node_is_compatible
returns 1 if the
.Fa compatstr
value occurs in the "compatible" property list of the device
tree node
.Fa node ,
and 0 otherwise.
.Pp
.Fn ofw_bus_search_compatible
returns pointer to the first entry of the
.Fa compat
table whose ocd_str field occurs in "compatible" property of
the device tree node associated with the device
.Fa dev .
The
.Fa compat
table is an array of struct ofw_compat_data elements defined as follows:
.Bd -literal -offset indent
struct ofw_compat_data {
const char *ocd_str;
uintptr_t ocd_data;
};
.Ed
The
.Fa compat
table must be terminated by the entry with ocd_str set to NULL.
If the device tree node is not compatible with any of
the entries, the function returns the pointer to the
terminating entry.
.Sh EXAMPLES
.Bd -literal -offset indent
static struct ofw_compat_data compat_data[] = {
{"arm,hrdwrA", FEATURE_A},
{"arm,hrdwrB", FEATURE_A | FEATURE_B},
{NULL, 0}
};
static int
hrdwr_probe(device_t dev)
{
...
if (!ofw_bus_search_compatible(dev, compat_data)->ocd_data)
return (ENXIO);
...
}
static int
hrdwr_attach(device_t dev)
{
...
sc = device_get_softc(dev);
sc->sc_features = ofw_bus_search_compatible(dev, compat_data)->ocd_data;
...
}
.Ed
.Sh SEE ALSO
.Xr ofw_bus_find_compatible 9
.Sh AUTHORS
This manual page was written by
.An Oleksandr Tymoshenko .

77
share/man/man9/ofw_bus_status_okay.9 Normal file
View File

@ -0,0 +1,77 @@
.\" -*- nroff -*-
.\"
.\" Copyright (c) 2018 Oleksandr Tymoshenko
.\"
.\" All rights reserved.
.\"
.\" This program is free software.
.\"
.\" 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 8, 2018
.Dt ofw_bus_status_okay 9
.Os
.Sh NAME
.Nm ofw_bus_get_status
.Nm ofw_bus_status_okay
.Nm ofw_bus_node_status_okay
.Nd check status of the device tree node
.Sh SYNOPSIS
.In dev/ofw/openfirm.h
.In dev/ofw/ofw_bus.h
.In dev/ofw/ofw_bus_subr.h
.Ft const char *
.Fn ofw_bus_get_status "device_t dev"
.Ft int
.Fn ofw_bus_status_okay "device_t dev"
.Ft int
.Fn ofw_bus_node_status_okay "phandle_t node"
.Sh DESCRIPTION
.Pp
The "status" property of the device tree node indicates whether the device is
enabled or not.
Multiple hardware versions might be built using the same base System-on-Chip
but with a different set of blocks enabled.
It is common to use SoC device tree and only enable/disable device nodes for
the derivative boards.
The device tree node is considered enabled only if it has "status" property
with the value set to either "ok" or "okay".
.Pp
.Fn ofw_bus_get_status
returns the value of the "status" property of the device tree node associated with the device
.Fa dev .
If the node does not have "status" property or there is no node associated with
the device the function returns NULL.
.Pp
.Fn ofw_bus_status_okay
returns 1 if the device tree node associated with the device
.Fa dev
has "status" property and its value is either "ok" or "okay".
.Pp
.Fn ofw_bus_node_status_okay
returns 1 if the device tree node
.Fa node
has "status" property and its value is either "ok" or "okay".
.Sh AUTHORS
This manual page was written by
.An Oleksandr Tymoshenko .