svn commit: r332305 - head/share/man/man9

Sun Apr 8 20:53:02 UTC 2018

Author: gonzo
Date: Sun Apr  8 20:53:00 2018
New Revision: 332305
URL: https://svnweb.freebsd.org/changeset/base/332305

Log:
  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

Added:
  head/share/man/man9/ofw_bus_is_compatible.9   (contents, props changed)
  head/share/man/man9/ofw_bus_status_okay.9   (contents, props changed)
Modified:
  head/share/man/man9/Makefile

Modified: head/share/man/man9/Makefile
==============================================================================

--- head/share/man/man9/Makefile	Sun Apr  8 20:52:09 2018	(r332304)
+++ head/share/man/man9/Makefile	Sun Apr  8 20:53:00 2018	(r332305)
@@ -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 \

Added: head/share/man/man9/ofw_bus_is_compatible.9
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ head/share/man/man9/ofw_bus_is_compatible.9	Sun Apr  8 20:53:00 2018	(r332305)
@@ -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 .

Added: head/share/man/man9/ofw_bus_status_okay.9
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ head/share/man/man9/ofw_bus_status_okay.9	Sun Apr  8 20:53:00 2018	(r332305)
@@ -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 .
