blob: 0d3cd8c01e21548436f586275fcd3c368203827e [file] [log] [blame]
Bin Meng45dbb4d2019-07-18 00:33:55 -07001.. SPDX-License-Identifier: GPL-2.0+
2
3Compiled-in Device Tree / Platform Data
4=======================================
Simon Glass39782af2016-07-04 11:58:07 -06005
6
7Introduction
8------------
9
10Device tree is the standard configuration method in U-Boot. It is used to
11define what devices are in the system and provide configuration information
12to these devices.
13
14The overhead of adding device tree access to U-Boot is fairly modest,
15approximately 3KB on Thumb 2 (plus the size of the DT itself). This means
16that in most cases it is best to use device tree for configuration.
17
18However there are some very constrained environments where U-Boot needs to
19work. These include SPL with severe memory limitations. For example, some
20SoCs require a 16KB SPL image which must include a full MMC stack. In this
21case the overhead of device tree access may be too great.
22
23It is possible to create platform data manually by defining C structures
Simon Glass12696252016-07-04 11:58:42 -060024for it, and reference that data in a U_BOOT_DEVICE() declaration. This
25bypasses the use of device tree completely, effectively creating a parallel
26configuration mechanism. But it is an available option for SPL.
Simon Glass39782af2016-07-04 11:58:07 -060027
Simon Glass12696252016-07-04 11:58:42 -060028As an alternative, a new 'of-platdata' feature is provided. This converts the
Simon Glass39782af2016-07-04 11:58:07 -060029device tree contents into C code which can be compiled into the SPL binary.
30This saves the 3KB of code overhead and perhaps a few hundred more bytes due
31to more efficient storage of the data.
32
Simon Glass12696252016-07-04 11:58:42 -060033Note: Quite a bit of thought has gone into the design of this feature.
34However it still has many rough edges and comments and suggestions are
35strongly encouraged! Quite possibly there is a much better approach.
36
Simon Glass39782af2016-07-04 11:58:07 -060037
38Caveats
39-------
40
41There are many problems with this features. It should only be used when
Simon Glass12696252016-07-04 11:58:42 -060042strictly necessary. Notable problems include:
Simon Glass39782af2016-07-04 11:58:07 -060043
Simon Glass12696252016-07-04 11:58:42 -060044 - Device tree does not describe data types. But the C code must define a
Bin Meng45dbb4d2019-07-18 00:33:55 -070045 type for each property. These are guessed using heuristics which
46 are wrong in several fairly common cases. For example an 8-byte value
47 is considered to be a 2-item integer array, and is byte-swapped. A
48 boolean value that is not present means 'false', but cannot be
49 included in the structures since there is generally no mention of it
50 in the device tree file.
Simon Glass39782af2016-07-04 11:58:07 -060051
52 - Naming of nodes and properties is automatic. This means that they follow
Bin Meng45dbb4d2019-07-18 00:33:55 -070053 the naming in the device tree, which may result in C identifiers that
54 look a bit strange.
Simon Glass39782af2016-07-04 11:58:07 -060055
56 - It is not possible to find a value given a property name. Code must use
Bin Meng45dbb4d2019-07-18 00:33:55 -070057 the associated C member variable directly in the code. This makes
58 the code less robust in the face of device-tree changes. It also
59 makes it very unlikely that your driver code will be useful for more
60 than one SoC. Even if the code is common, each SoC will end up with
61 a different C struct name, and a likely a different format for the
62 platform data.
Simon Glass39782af2016-07-04 11:58:07 -060063
64 - The platform data is provided to drivers as a C structure. The driver
Bin Meng45dbb4d2019-07-18 00:33:55 -070065 must use the same structure to access the data. Since a driver
66 normally also supports device tree it must use #ifdef to separate
67 out this code, since the structures are only available in SPL.
Simon Glass39782af2016-07-04 11:58:07 -060068
Simon Goldschmidt3600b462019-01-16 20:40:18 +010069 - Correct relations between nodes are not implemented. This means that
Bin Meng45dbb4d2019-07-18 00:33:55 -070070 parent/child relations (like bus device iteration) do not work yet.
71 Some phandles (those that are recognised as such) are converted into
72 a pointer to platform data. This pointer can potentially be used to
73 access the referenced device (by searching for the pointer value).
74 This feature is not yet implemented, however.
Simon Goldschmidt3600b462019-01-16 20:40:18 +010075
Simon Glass39782af2016-07-04 11:58:07 -060076
77How it works
78------------
79
Simon Goldschmidt3600b462019-01-16 20:40:18 +010080The feature is enabled by CONFIG OF_PLATDATA. This is only available in
81SPL/TPL and should be tested with:
Simon Glass39782af2016-07-04 11:58:07 -060082
Bin Meng45dbb4d2019-07-18 00:33:55 -070083.. code-block:: c
84
85 #if CONFIG_IS_ENABLED(OF_PLATDATA)
Simon Glass39782af2016-07-04 11:58:07 -060086
87A new tool called 'dtoc' converts a device tree file either into a set of
Simon Goldschmidt3600b462019-01-16 20:40:18 +010088struct declarations, one for each compatible node, and a set of
Simon Glass39782af2016-07-04 11:58:07 -060089U_BOOT_DEVICE() declarations along with the actual platform data for each
90device. As an example, consider this MMC node:
91
Bin Meng45dbb4d2019-07-18 00:33:55 -070092.. code-block:: none
93
94 sdmmc: dwmmc@ff0c0000 {
95 compatible = "rockchip,rk3288-dw-mshc";
96 clock-freq-min-max = <400000 150000000>;
97 clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>,
98 <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>;
99 clock-names = "biu", "ciu", "ciu_drv", "ciu_sample";
100 fifo-depth = <0x100>;
101 interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>;
102 reg = <0xff0c0000 0x4000>;
103 bus-width = <4>;
104 cap-mmc-highspeed;
105 cap-sd-highspeed;
106 card-detect-delay = <200>;
107 disable-wp;
108 num-slots = <1>;
109 pinctrl-names = "default";
110 pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>;
Simon Glass39782af2016-07-04 11:58:07 -0600111 vmmc-supply = <&vcc_sd>;
112 status = "okay";
113 u-boot,dm-pre-reloc;
114 };
115
116
117Some of these properties are dropped by U-Boot under control of the
118CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce
119the following C struct declaration:
120
Bin Meng45dbb4d2019-07-18 00:33:55 -0700121.. code-block:: c
122
123 struct dtd_rockchip_rk3288_dw_mshc {
124 fdt32_t bus_width;
125 bool cap_mmc_highspeed;
126 bool cap_sd_highspeed;
127 fdt32_t card_detect_delay;
128 fdt32_t clock_freq_min_max[2];
129 struct phandle_1_arg clocks[4];
130 bool disable_wp;
131 fdt32_t fifo_depth;
132 fdt32_t interrupts[3];
133 fdt32_t num_slots;
134 fdt32_t reg[2];
135 fdt32_t vmmc_supply;
136 };
Simon Glass39782af2016-07-04 11:58:07 -0600137
138and the following device declaration:
139
Bin Meng45dbb4d2019-07-18 00:33:55 -0700140.. code-block:: c
141
142 static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = {
143 .fifo_depth = 0x100,
144 .cap_sd_highspeed = true,
145 .interrupts = {0x0, 0x20, 0x4},
146 .clock_freq_min_max = {0x61a80, 0x8f0d180},
147 .vmmc_supply = 0xb,
148 .num_slots = 0x1,
149 .clocks = {{&dtv_clock_controller_at_ff760000, 456},
150 {&dtv_clock_controller_at_ff760000, 68},
151 {&dtv_clock_controller_at_ff760000, 114},
152 {&dtv_clock_controller_at_ff760000, 118}},
153 .cap_mmc_highspeed = true,
154 .disable_wp = true,
155 .bus_width = 0x4,
156 .u_boot_dm_pre_reloc = true,
157 .reg = {0xff0c0000, 0x4000},
158 .card_detect_delay = 0xc8,
159 };
160
161 U_BOOT_DEVICE(dwmmc_at_ff0c0000) = {
162 .name = "rockchip_rk3288_dw_mshc",
163 .platdata = &dtv_dwmmc_at_ff0c0000,
164 .platdata_size = sizeof(dtv_dwmmc_at_ff0c0000),
165 };
Simon Glass39782af2016-07-04 11:58:07 -0600166
167The device is then instantiated at run-time and the platform data can be
168accessed using:
169
Bin Meng45dbb4d2019-07-18 00:33:55 -0700170.. code-block:: c
171
172 struct udevice *dev;
173 struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_platdata(dev);
Simon Glass39782af2016-07-04 11:58:07 -0600174
175This avoids the code overhead of converting the device tree data to
176platform data in the driver. The ofdata_to_platdata() method should
177therefore do nothing in such a driver.
178
Simon Goldschmidt3600b462019-01-16 20:40:18 +0100179Note that for the platform data to be matched with a driver, the 'name'
180property of the U_BOOT_DEVICE() declaration has to match a driver declared
181via U_BOOT_DRIVER(). This effectively means that a U_BOOT_DRIVER() with a
182'name' corresponding to the devicetree 'compatible' string (after converting
183it to a valid name for C) is needed, so a dedicated driver is required for
184each 'compatible' string.
185
Simon Glass2cce5862017-06-13 21:10:06 -0600186Where a node has multiple compatible strings, a #define is used to make them
187equivalent, e.g.:
188
Bin Meng45dbb4d2019-07-18 00:33:55 -0700189.. code-block:: c
190
191 #define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc
Simon Glass2cce5862017-06-13 21:10:06 -0600192
Simon Glass39782af2016-07-04 11:58:07 -0600193
Simon Glass12696252016-07-04 11:58:42 -0600194Converting of-platdata to a useful form
195---------------------------------------
196
Simon Goldschmidt3600b462019-01-16 20:40:18 +0100197Of course it would be possible to use the of-platdata directly in your driver
198whenever configuration information is required. However this means that the
Simon Glass12696252016-07-04 11:58:42 -0600199driver will not be able to support device tree, since the of-platdata
200structure is not available when device tree is used. It would make no sense
201to use this structure if device tree were available, since the structure has
202all the limitations metioned in caveats above.
203
204Therefore it is recommended that the of-platdata structure should be used
205only in the probe() method of your driver. It cannot be used in the
206ofdata_to_platdata() method since this is not called when platform data is
207already present.
208
209
Simon Glass39782af2016-07-04 11:58:07 -0600210How to structure your driver
211----------------------------
212
213Drivers should always support device tree as an option. The of-platdata
214feature is intended as a add-on to existing drivers.
215
Simon Glass12696252016-07-04 11:58:42 -0600216Your driver should convert the platdata struct in its probe() method. The
217existing device tree decoding logic should be kept in the
218ofdata_to_platdata() method and wrapped with #if.
Simon Glass39782af2016-07-04 11:58:07 -0600219
220For example:
221
Bin Meng45dbb4d2019-07-18 00:33:55 -0700222.. code-block:: c
223
Simon Glass39782af2016-07-04 11:58:07 -0600224 #include <dt-structs.h>
225
226 struct mmc_platdata {
227 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA)
Simon Glass12696252016-07-04 11:58:42 -0600228 /* Put this first since driver model will copy the data here */
Simon Glass39782af2016-07-04 11:58:07 -0600229 struct dtd_mmc dtplat;
230 #endif
231 /*
232 * Other fields can go here, to be filled in by decoding from
Simon Glass12696252016-07-04 11:58:42 -0600233 * the device tree (or the C structures when of-platdata is used).
Simon Glass39782af2016-07-04 11:58:07 -0600234 */
235 int fifo_depth;
236 };
237
238 static int mmc_ofdata_to_platdata(struct udevice *dev)
239 {
240 #if !CONFIG_IS_ENABLED(SPL_OF_PLATDATA)
Simon Glass12696252016-07-04 11:58:42 -0600241 /* Decode the device tree data */
Simon Glass39782af2016-07-04 11:58:07 -0600242 struct mmc_platdata *plat = dev_get_platdata(dev);
243 const void *blob = gd->fdt_blob;
Simon Glasse160f7d2017-01-17 16:52:55 -0700244 int node = dev_of_offset(dev);
Simon Glass39782af2016-07-04 11:58:07 -0600245
246 plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0);
247 #endif
248
249 return 0;
250 }
251
252 static int mmc_probe(struct udevice *dev)
253 {
254 struct mmc_platdata *plat = dev_get_platdata(dev);
Simon Glass12696252016-07-04 11:58:42 -0600255
Simon Glass39782af2016-07-04 11:58:07 -0600256 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA)
Simon Glass12696252016-07-04 11:58:42 -0600257 /* Decode the of-platdata from the C structures */
Simon Glass39782af2016-07-04 11:58:07 -0600258 struct dtd_mmc *dtplat = &plat->dtplat;
259
Simon Glass12696252016-07-04 11:58:42 -0600260 plat->fifo_depth = dtplat->fifo_depth;
261 #endif
Simon Glass39782af2016-07-04 11:58:07 -0600262 /* Set up the device from the plat data */
263 writel(plat->fifo_depth, ...)
Simon Glass39782af2016-07-04 11:58:07 -0600264 }
265
266 static const struct udevice_id mmc_ids[] = {
267 { .compatible = "vendor,mmc" },
268 { }
269 };
270
271 U_BOOT_DRIVER(mmc_drv) = {
272 .name = "mmc",
273 .id = UCLASS_MMC,
274 .of_match = mmc_ids,
275 .ofdata_to_platdata = mmc_ofdata_to_platdata,
276 .probe = mmc_probe,
277 .priv_auto_alloc_size = sizeof(struct mmc_priv),
278 .platdata_auto_alloc_size = sizeof(struct mmc_platdata),
279 };
280
281
282In the case where SPL_OF_PLATDATA is enabled, platdata_auto_alloc_size is
Simon Glass12696252016-07-04 11:58:42 -0600283still used to allocate space for the platform data. This is different from
284the normal behaviour and is triggered by the use of of-platdata (strictly
285speaking it is a non-zero platdata_size which triggers this).
Simon Glass39782af2016-07-04 11:58:07 -0600286
Simon Glass12696252016-07-04 11:58:42 -0600287The of-platdata struct contents is copied from the C structure data to the
288start of the newly allocated area. In the case where device tree is used,
289the platform data is allocated, and starts zeroed. In this case the
290ofdata_to_platdata() method should still set up the platform data (and the
291of-platdata struct will not be present).
292
293SPL must use either of-platdata or device tree. Drivers cannot use both at
294the same time, but they must support device tree. Supporting of-platdata is
295optional.
296
Simon Glass39782af2016-07-04 11:58:07 -0600297The device tree becomes in accessible when CONFIG_SPL_OF_PLATDATA is enabled,
Simon Glass12696252016-07-04 11:58:42 -0600298since the device-tree access code is not compiled in. A corollary is that
299a board can only move to using of-platdata if all the drivers it uses support
300it. There would be little point in having some drivers require the device
301tree data, since then libfdt would still be needed for those drivers and
302there would be no code-size benefit.
Simon Glass39782af2016-07-04 11:58:07 -0600303
304Internals
305---------
306
307The dt-structs.h file includes the generated file
308(include/generated//dt-structs.h) if CONFIG_SPL_OF_PLATDATA is enabled.
309Otherwise (such as in U-Boot proper) these structs are not available. This
Simon Glass12696252016-07-04 11:58:42 -0600310prevents them being used inadvertently. All usage must be bracketed with
311#if CONFIG_IS_ENABLED(SPL_OF_PLATDATA).
Simon Glass39782af2016-07-04 11:58:07 -0600312
313The dt-platdata.c file contains the device declarations and is is built in
314spl/dt-platdata.c.
315
Simon Glass39782af2016-07-04 11:58:07 -0600316The beginnings of a libfdt Python module are provided. So far this only
317implements a subset of the features.
318
Simon Glass12696252016-07-04 11:58:42 -0600319The 'swig' tool is needed to build the libfdt Python module. If this is not
320found then the Python model is not used and a fallback is used instead, which
321makes use of fdtget.
322
323
324Credits
325-------
326
327This is an implementation of an idea by Tom Rini <trini@konsulko.com>.
Simon Glass39782af2016-07-04 11:58:07 -0600328
329
330Future work
331-----------
Simon Glass39782af2016-07-04 11:58:07 -0600332- Consider programmatically reading binding files instead of device tree
Bin Meng45dbb4d2019-07-18 00:33:55 -0700333 contents
Simon Glass39782af2016-07-04 11:58:07 -0600334- Complete the phandle feature
Simon Glass39782af2016-07-04 11:58:07 -0600335- Move to using a full Python libfdt module
336
Bin Meng45dbb4d2019-07-18 00:33:55 -0700337
338.. Simon Glass <sjg@chromium.org>
339.. Google, Inc
340.. 6/6/16
341.. Updated Independence Day 2016