share/man/man9/ofw_bus_is_compatible.9

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