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.Dd April 8, 2018 30.Dt ofw_bus_is_compatible 9 31.Os 32.Sh NAME 33.Nm ofw_bus_is_compatible , 34.Nm ofw_bus_is_compatible_strict , 35.Nm ofw_bus_node_is_compatible , 36.Nm ofw_bus_search_compatible 37.Nd check device tree nodes for compatibility with drivers 38.Sh SYNOPSIS 39.In dev/ofw/openfirm.h 40.In dev/ofw/ofw_bus.h 41.In dev/ofw/ofw_bus_subr.h 42.Ft int 43.Fn ofw_bus_is_compatible "device_t dev" "const char *compatstr" 44.Ft int 45.Fn ofw_bus_is_compatible_strict "device_t dev" "const char *compatstr" 46.Ft int 47.Fn ofw_bus_node_is_compatible "phandle_t node" "const char *compatstr" 48.Ft const struct ofw_compat_data * 49.Fn ofw_bus_search_compatible "device_t dev" "const struct ofw_compat_data *compat" 50.Sh DESCRIPTION 51The "compatible" property of the device tree node is used to 52identify the type of the device the node represents. 53The property is a list of one or more strings that represent 54hardware types the device is compatible with. 55The common format for such strings is "vendor,hardware" 56where "vendor" is an abbreviated name of the manufacturer 57and "hardware" is a device identifier, for instance, "fsl" 58for "Freescale" and "imx6ul-i2c" for the I2C controller. 59More than one string is required for compatibility with 60older revisions of the driver. 61If hardware revision B is backward compatible with revision 62A device tree node can signal this compatibility by 63providing both "vndr,hrdwrA" and "vndr,hrdwrB" strings in 64the "compatibile" property value. 65This way older driver can use features available only in 66revision A, and the new version of the driver can take 67advantage of revision B feature set. 68.Pp 69.Fn ofw_bus_is_compatible 70returns 1 if the 71.Fa compatstr 72value occurs in the "compatible" property list of the device 73tree node associated with the device 74.Fa dev , 75and 0 otherwise. 76.Pp 77.Fn ofw_bus_is_compatible_strict 78return 1 if the "compatible" 79property of the device tree node associated with the device 80.Fa dev 81consists of only one string and this string is equal to 82.Fa compatstr , 83and 0 otherwise. 84.Pp 85.Fn ofw_bus_node_is_compatible 86returns 1 if the 87.Fa compatstr 88value occurs in the "compatible" property list of the device 89tree node 90.Fa node , 91and 0 otherwise. 92.Pp 93.Fn ofw_bus_search_compatible 94returns pointer to the first entry of the 95.Fa compat 96table whose ocd_str field occurs in "compatible" property of 97the device tree node associated with the device 98.Fa dev . 99The 100.Fa compat 101table is an array of struct ofw_compat_data elements defined as follows: 102.Bd -literal -offset indent 103struct ofw_compat_data { 104 const char *ocd_str; 105 uintptr_t ocd_data; 106}; 107.Ed 108The 109.Fa compat 110table must be terminated by the entry with ocd_str set to NULL. 111If the device tree node is not compatible with any of 112the entries, the function returns the pointer to the 113terminating entry. 114.Sh EXAMPLES 115.Bd -literal -offset indent 116static struct ofw_compat_data compat_data[] = { 117 {"arm,hrdwrA", FEATURE_A}, 118 {"arm,hrdwrB", FEATURE_A | FEATURE_B}, 119 {NULL, 0} 120}; 121 122static int 123hrdwr_probe(device_t dev) 124{ 125 ... 126 if (!ofw_bus_search_compatible(dev, compat_data)->ocd_data) 127 return (ENXIO); 128 ... 129} 130 131static int 132hrdwr_attach(device_t dev) 133{ 134 ... 135 sc = device_get_softc(dev); 136 sc->sc_features = ofw_bus_search_compatible(dev, compat_data)->ocd_data; 137 ... 138} 139.Ed 140.Sh SEE ALSO 141.Xr ofw_bus_find_compatible 9 142.Sh AUTHORS 143This manual page was written by 144.An Oleksandr Tymoshenko . 145