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