Index: share/man/man9/Makefile =================================================================== --- share/man/man9/Makefile +++ share/man/man9/Makefile @@ -207,6 +207,8 @@ namei.9 \ netisr.9 \ nv.9 \ + ofw_bus_is_compatible.9 \ + ofw_bus_status_okay.9 \ osd.9 \ owll.9 \ own.9 \ @@ -1522,6 +1524,11 @@ 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 \ Index: share/man/man9/ofw_bus_is_compatible.9 =================================================================== --- /dev/null +++ share/man/man9/ofw_bus_is_compatible.9 @@ -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 March 17, 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 . Index: share/man/man9/ofw_bus_status_okay.9 =================================================================== --- /dev/null +++ share/man/man9/ofw_bus_status_okay.9 @@ -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 March 17, 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 .