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