mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-15 10:17:20 +00:00
Document ofw_bus_subr helpers "compatible" and "status" properties
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:
parent
b4b4b17687
commit
f510c340ce
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=332305
@ -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
147
share/man/man9/ofw_bus_is_compatible.9
Normal 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
77
share/man/man9/ofw_bus_status_okay.9
Normal 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 .
|
Loading…
Reference in New Issue
Block a user