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