1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 2018 Oleksandr Tymoshenko 4.\" 5.\" All rights reserved. 6.\" 7.\" This program is free software. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 21.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.\" 29.\" $FreeBSD$ 30.\" 31.Dd April 8, 2018 32.Dt ofw_bus_is_compatible 9 33.Os 34.Sh NAME 35.Nm ofw_bus_is_compatible , 36.Nm ofw_bus_is_compatible_strict , 37.Nm ofw_bus_node_is_compatible , 38.Nm ofw_bus_search_compatible 39.Nd check device tree nodes for compatibility with drivers 40.Sh SYNOPSIS 41.In dev/ofw/openfirm.h 42.In dev/ofw/ofw_bus.h 43.In dev/ofw/ofw_bus_subr.h 44.Ft int 45.Fn ofw_bus_is_compatible "device_t dev" "const char *compatstr" 46.Ft int 47.Fn ofw_bus_is_compatible_strict "device_t dev" "const char *compatstr" 48.Ft int 49.Fn ofw_bus_node_is_compatible "phandle_t node" "const char *compatstr" 50.Ft const struct ofw_compat_data * 51.Fn ofw_bus_search_compatible "device_t dev" "const struct ofw_compat_data *compat" 52.Sh DESCRIPTION 53The "compatible" property of the device tree node is used to 54identify the type of the device the node represents. 55The property is a list of one or more strings that represent 56hardware types the device is compatible with. 57The common format for such strings is "vendor,hardware" 58where "vendor" is an abbreviated name of the manufacturer 59and "hardware" is a device identifier, for instance, "fsl" 60for "Freescale" and "imx6ul-i2c" for the I2C controller. 61More than one string is required for compatibility with 62older revisions of the driver. 63If hardware revision B is backward compatible with revision 64A device tree node can signal this compatibility by 65providing both "vndr,hrdwrA" and "vndr,hrdwrB" strings in 66the "compatibile" property value. 67This way older driver can use features available only in 68revision A, and the new version of the driver can take 69advantage of revision B feature set. 70.Pp 71.Fn ofw_bus_is_compatible 72returns 1 if the 73.Fa compatstr 74value occurs in the "compatible" property list of the device 75tree node associated with the device 76.Fa dev , 77and 0 otherwise. 78.Pp 79.Fn ofw_bus_is_compatible_strict 80return 1 if the "compatible" 81property of the device tree node associated with the device 82.Fa dev 83consists of only one string and this string is equal to 84.Fa compatstr , 85and 0 otherwise. 86.Pp 87.Fn ofw_bus_node_is_compatible 88returns 1 if the 89.Fa compatstr 90value occurs in the "compatible" property list of the device 91tree node 92.Fa node , 93and 0 otherwise. 94.Pp 95.Fn ofw_bus_search_compatible 96returns pointer to the first entry of the 97.Fa compat 98table whose ocd_str field occurs in "compatible" property of 99the device tree node associated with the device 100.Fa dev . 101The 102.Fa compat 103table is an array of struct ofw_compat_data elements defined as follows: 104.Bd -literal -offset indent 105struct ofw_compat_data { 106 const char *ocd_str; 107 uintptr_t ocd_data; 108}; 109.Ed 110The 111.Fa compat 112table must be terminated by the entry with ocd_str set to NULL. 113If the device tree node is not compatible with any of 114the entries, the function returns the pointer to the 115terminating entry. 116.Sh EXAMPLES 117.Bd -literal -offset indent 118static struct ofw_compat_data compat_data[] = { 119 {"arm,hrdwrA", FEATURE_A}, 120 {"arm,hrdwrB", FEATURE_A | FEATURE_B}, 121 {NULL, 0} 122}; 123 124static int 125hrdwr_probe(device_t dev) 126{ 127 ... 128 if (!ofw_bus_search_compatible(dev, compat_data)->ocd_data) 129 return (ENXIO); 130 ... 131} 132 133static int 134hrdwr_attach(device_t dev) 135{ 136 ... 137 sc = device_get_softc(dev); 138 sc->sc_features = ofw_bus_search_compatible(dev, compat_data)->ocd_data; 139 ... 140} 141.Ed 142.Sh SEE ALSO 143.Xr ofw_bus_find_compatible 9 144.Sh AUTHORS 145This manual page was written by 146.An Oleksandr Tymoshenko . 147