blob: a5a6e46e3ece902b757035de8ab1f3427fe52f9b [file] [log] [blame]
Bin Mengae258692019-07-18 00:33:55 -07001.. SPDX-License-Identifier: GPL-2.0+
Simon Glass261ad282016-07-04 11:58:07 -06002
Bin Mengae258692019-07-18 00:33:55 -07003Compiled-in Device Tree / Platform Data
4=======================================
5
Simon Glass261ad282016-07-04 11:58:07 -06006
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 Glass1d8364a2020-12-28 20:34:54 -070024for it, and reference that data in a U_BOOT_DRVINFO() declaration. This
Simon Glass946c7232016-07-04 11:58:42 -060025bypasses the use of device tree completely, effectively creating a parallel
26configuration mechanism. But it is an available option for SPL.
Simon Glass261ad282016-07-04 11:58:07 -060027
Simon Glass946c7232016-07-04 11:58:42 -060028As an alternative, a new 'of-platdata' feature is provided. This converts the
Simon Glass261ad282016-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 Glass946c7232016-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 Glass261ad282016-07-04 11:58:07 -060037
38Caveats
39-------
40
41There are many problems with this features. It should only be used when
Simon Glass946c7232016-07-04 11:58:42 -060042strictly necessary. Notable problems include:
Simon Glass261ad282016-07-04 11:58:07 -060043
Simon Glass946c7232016-07-04 11:58:42 -060044 - Device tree does not describe data types. But the C code must define a
Bin Mengae258692019-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 Glass261ad282016-07-04 11:58:07 -060051
52 - Naming of nodes and properties is automatic. This means that they follow
Bin Mengae258692019-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 Glass261ad282016-07-04 11:58:07 -060055
56 - It is not possible to find a value given a property name. Code must use
Bin Mengae258692019-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 Glass261ad282016-07-04 11:58:07 -060063
64 - The platform data is provided to drivers as a C structure. The driver
Bin Mengae258692019-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 Glass261ad282016-07-04 11:58:07 -060068
69
70How it works
71------------
72
Simon Goldschmidt49ce8ca2019-01-16 20:40:18 +010073The feature is enabled by CONFIG OF_PLATDATA. This is only available in
74SPL/TPL and should be tested with:
Simon Glass261ad282016-07-04 11:58:07 -060075
Bin Mengae258692019-07-18 00:33:55 -070076.. code-block:: c
77
78 #if CONFIG_IS_ENABLED(OF_PLATDATA)
Simon Glass261ad282016-07-04 11:58:07 -060079
80A new tool called 'dtoc' converts a device tree file either into a set of
Simon Goldschmidt49ce8ca2019-01-16 20:40:18 +010081struct declarations, one for each compatible node, and a set of
Simon Glass1d8364a2020-12-28 20:34:54 -070082U_BOOT_DRVINFO() declarations along with the actual platform data for each
Simon Glass261ad282016-07-04 11:58:07 -060083device. As an example, consider this MMC node:
84
Bin Mengae258692019-07-18 00:33:55 -070085.. code-block:: none
86
87 sdmmc: dwmmc@ff0c0000 {
88 compatible = "rockchip,rk3288-dw-mshc";
89 clock-freq-min-max = <400000 150000000>;
90 clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>,
91 <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>;
92 clock-names = "biu", "ciu", "ciu_drv", "ciu_sample";
93 fifo-depth = <0x100>;
94 interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>;
95 reg = <0xff0c0000 0x4000>;
96 bus-width = <4>;
97 cap-mmc-highspeed;
98 cap-sd-highspeed;
99 card-detect-delay = <200>;
100 disable-wp;
101 num-slots = <1>;
102 pinctrl-names = "default";
103 pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>;
Simon Glass261ad282016-07-04 11:58:07 -0600104 vmmc-supply = <&vcc_sd>;
105 status = "okay";
106 u-boot,dm-pre-reloc;
107 };
108
109
110Some of these properties are dropped by U-Boot under control of the
111CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce
112the following C struct declaration:
113
Bin Mengae258692019-07-18 00:33:55 -0700114.. code-block:: c
115
116 struct dtd_rockchip_rk3288_dw_mshc {
117 fdt32_t bus_width;
118 bool cap_mmc_highspeed;
119 bool cap_sd_highspeed;
120 fdt32_t card_detect_delay;
121 fdt32_t clock_freq_min_max[2];
122 struct phandle_1_arg clocks[4];
123 bool disable_wp;
124 fdt32_t fifo_depth;
125 fdt32_t interrupts[3];
126 fdt32_t num_slots;
127 fdt32_t reg[2];
128 fdt32_t vmmc_supply;
129 };
Simon Glass261ad282016-07-04 11:58:07 -0600130
Simon Glassa7729462020-10-03 11:31:42 -0600131and the following device declarations:
Simon Glass261ad282016-07-04 11:58:07 -0600132
Bin Mengae258692019-07-18 00:33:55 -0700133.. code-block:: c
134
Simon Glassa7729462020-10-03 11:31:42 -0600135 /* Node /clock-controller@ff760000 index 0 */
136 ...
137
138 /* Node /dwmmc@ff0c0000 index 2 */
Bin Mengae258692019-07-18 00:33:55 -0700139 static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = {
140 .fifo_depth = 0x100,
141 .cap_sd_highspeed = true,
142 .interrupts = {0x0, 0x20, 0x4},
143 .clock_freq_min_max = {0x61a80, 0x8f0d180},
144 .vmmc_supply = 0xb,
145 .num_slots = 0x1,
Simon Glassa7729462020-10-03 11:31:42 -0600146 .clocks = {{0, 456},
147 {0, 68},
148 {0, 114},
149 {0, 118}},
Bin Mengae258692019-07-18 00:33:55 -0700150 .cap_mmc_highspeed = true,
151 .disable_wp = true,
152 .bus_width = 0x4,
153 .u_boot_dm_pre_reloc = true,
154 .reg = {0xff0c0000, 0x4000},
155 .card_detect_delay = 0xc8,
156 };
157
Simon Glass1d8364a2020-12-28 20:34:54 -0700158 U_BOOT_DRVINFO(dwmmc_at_ff0c0000) = {
Bin Mengae258692019-07-18 00:33:55 -0700159 .name = "rockchip_rk3288_dw_mshc",
Simon Glass71fa5b42020-12-03 16:55:18 -0700160 .plat = &dtv_dwmmc_at_ff0c0000,
161 .plat_size = sizeof(dtv_dwmmc_at_ff0c0000),
Simon Glassa7729462020-10-03 11:31:42 -0600162 .parent_idx = -1,
Bin Mengae258692019-07-18 00:33:55 -0700163 };
Simon Glass261ad282016-07-04 11:58:07 -0600164
165The device is then instantiated at run-time and the platform data can be
166accessed using:
167
Bin Mengae258692019-07-18 00:33:55 -0700168.. code-block:: c
169
170 struct udevice *dev;
Simon Glassfa20e932020-12-03 16:55:20 -0700171 struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_plat(dev);
Simon Glass261ad282016-07-04 11:58:07 -0600172
173This avoids the code overhead of converting the device tree data to
Simon Glassaad29ae2020-12-03 16:55:21 -0700174platform data in the driver. The of_to_plat() method should
Simon Glass261ad282016-07-04 11:58:07 -0600175therefore do nothing in such a driver.
176
Simon Goldschmidt49ce8ca2019-01-16 20:40:18 +0100177Note that for the platform data to be matched with a driver, the 'name'
Simon Glass1d8364a2020-12-28 20:34:54 -0700178property of the U_BOOT_DRVINFO() declaration has to match a driver declared
Simon Goldschmidt49ce8ca2019-01-16 20:40:18 +0100179via U_BOOT_DRIVER(). This effectively means that a U_BOOT_DRIVER() with a
180'name' corresponding to the devicetree 'compatible' string (after converting
181it to a valid name for C) is needed, so a dedicated driver is required for
182each 'compatible' string.
183
Simon Glassdf65db82020-12-28 20:34:57 -0700184In order to make this a bit more flexible DM_DRIVER_ALIAS macro can be
Walter Lozanoc38b4912020-06-25 01:10:09 -0300185used to declare an alias for a driver name, typically a 'compatible' string.
Simon Glass2f4455f2021-02-03 06:01:05 -0700186This macro produces no code, but it is by dtoc tool. It must be located in the
187same file as its associated driver, ideally just after it.
Walter Lozanoc38b4912020-06-25 01:10:09 -0300188
Simon Glassa7729462020-10-03 11:31:42 -0600189The parent_idx is the index of the parent driver_info structure within its
Simon Glass1d8364a2020-12-28 20:34:54 -0700190linker list (instantiated by the U_BOOT_DRVINFO() macro). This is used to support
Simon Glass2500de22020-12-28 20:35:05 -0700191dev_get_parent().
Simon Glassa7729462020-10-03 11:31:42 -0600192
Simon Glassdf65db82020-12-28 20:34:57 -0700193During the build process dtoc parses both U_BOOT_DRIVER and DM_DRIVER_ALIAS
Walter Lozanoc38b4912020-06-25 01:10:09 -0300194to build a list of valid driver names and driver aliases. If the 'compatible'
195string used for a device does not not match a valid driver name, it will be
196checked against the list of driver aliases in order to get the right driver
197name to use. If in this step there is no match found a warning is issued to
198avoid run-time failures.
199
Simon Glass934be0b2017-06-13 21:10:06 -0600200Where a node has multiple compatible strings, a #define is used to make them
201equivalent, e.g.:
202
Bin Mengae258692019-07-18 00:33:55 -0700203.. code-block:: c
Simon Glass934be0b2017-06-13 21:10:06 -0600204
Bin Mengae258692019-07-18 00:33:55 -0700205 #define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc
206
Simon Glass946c7232016-07-04 11:58:42 -0600207
208Converting of-platdata to a useful form
209---------------------------------------
210
Simon Goldschmidt49ce8ca2019-01-16 20:40:18 +0100211Of course it would be possible to use the of-platdata directly in your driver
212whenever configuration information is required. However this means that the
Simon Glass946c7232016-07-04 11:58:42 -0600213driver will not be able to support device tree, since the of-platdata
214structure is not available when device tree is used. It would make no sense
215to use this structure if device tree were available, since the structure has
216all the limitations metioned in caveats above.
217
218Therefore it is recommended that the of-platdata structure should be used
219only in the probe() method of your driver. It cannot be used in the
Simon Glassaad29ae2020-12-03 16:55:21 -0700220of_to_plat() method since this is not called when platform data is
Simon Glass946c7232016-07-04 11:58:42 -0600221already present.
222
Simon Glass261ad282016-07-04 11:58:07 -0600223
224How to structure your driver
225----------------------------
226
227Drivers should always support device tree as an option. The of-platdata
228feature is intended as a add-on to existing drivers.
229
Simon Glass71fa5b42020-12-03 16:55:18 -0700230Your driver should convert the plat struct in its probe() method. The
Simon Glass946c7232016-07-04 11:58:42 -0600231existing device tree decoding logic should be kept in the
Simon Glassaad29ae2020-12-03 16:55:21 -0700232of_to_plat() method and wrapped with #if.
Simon Glass261ad282016-07-04 11:58:07 -0600233
234For example:
235
Bin Mengae258692019-07-18 00:33:55 -0700236.. code-block:: c
237
Simon Glass261ad282016-07-04 11:58:07 -0600238 #include <dt-structs.h>
239
Simon Glassb75b15b2020-12-03 16:55:23 -0700240 struct mmc_plat {
Lukasz Majewskifd54ab22019-09-03 15:43:19 +0200241 #if CONFIG_IS_ENABLED(OF_PLATDATA)
Simon Glass946c7232016-07-04 11:58:42 -0600242 /* Put this first since driver model will copy the data here */
Simon Glass261ad282016-07-04 11:58:07 -0600243 struct dtd_mmc dtplat;
244 #endif
245 /*
246 * Other fields can go here, to be filled in by decoding from
Simon Glass946c7232016-07-04 11:58:42 -0600247 * the device tree (or the C structures when of-platdata is used).
Simon Glass261ad282016-07-04 11:58:07 -0600248 */
249 int fifo_depth;
250 };
251
Simon Glassaad29ae2020-12-03 16:55:21 -0700252 static int mmc_of_to_plat(struct udevice *dev)
Simon Glass261ad282016-07-04 11:58:07 -0600253 {
Lukasz Majewskifd54ab22019-09-03 15:43:19 +0200254 #if !CONFIG_IS_ENABLED(OF_PLATDATA)
Simon Glass946c7232016-07-04 11:58:42 -0600255 /* Decode the device tree data */
Simon Glassb75b15b2020-12-03 16:55:23 -0700256 struct mmc_plat *plat = dev_get_plat(dev);
Simon Glass261ad282016-07-04 11:58:07 -0600257 const void *blob = gd->fdt_blob;
Simon Glassdd79d6e2017-01-17 16:52:55 -0700258 int node = dev_of_offset(dev);
Simon Glass261ad282016-07-04 11:58:07 -0600259
260 plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0);
261 #endif
262
263 return 0;
264 }
265
266 static int mmc_probe(struct udevice *dev)
267 {
Simon Glassb75b15b2020-12-03 16:55:23 -0700268 struct mmc_plat *plat = dev_get_plat(dev);
Simon Glass946c7232016-07-04 11:58:42 -0600269
Lukasz Majewskifd54ab22019-09-03 15:43:19 +0200270 #if CONFIG_IS_ENABLED(OF_PLATDATA)
Simon Glass946c7232016-07-04 11:58:42 -0600271 /* Decode the of-platdata from the C structures */
Simon Glass261ad282016-07-04 11:58:07 -0600272 struct dtd_mmc *dtplat = &plat->dtplat;
273
Simon Glass946c7232016-07-04 11:58:42 -0600274 plat->fifo_depth = dtplat->fifo_depth;
275 #endif
Simon Glass261ad282016-07-04 11:58:07 -0600276 /* Set up the device from the plat data */
277 writel(plat->fifo_depth, ...)
Simon Glass261ad282016-07-04 11:58:07 -0600278 }
279
280 static const struct udevice_id mmc_ids[] = {
281 { .compatible = "vendor,mmc" },
282 { }
283 };
284
285 U_BOOT_DRIVER(mmc_drv) = {
Walter Lozanoc38b4912020-06-25 01:10:09 -0300286 .name = "mmc_drv",
Simon Glass261ad282016-07-04 11:58:07 -0600287 .id = UCLASS_MMC,
288 .of_match = mmc_ids,
Simon Glassaad29ae2020-12-03 16:55:21 -0700289 .of_to_plat = mmc_of_to_plat,
Simon Glass261ad282016-07-04 11:58:07 -0600290 .probe = mmc_probe,
Simon Glass8a2b47f2020-12-03 16:55:17 -0700291 .priv_auto = sizeof(struct mmc_priv),
Simon Glassb75b15b2020-12-03 16:55:23 -0700292 .plat_auto = sizeof(struct mmc_plat),
Simon Glass261ad282016-07-04 11:58:07 -0600293 };
294
Simon Glassdf65db82020-12-28 20:34:57 -0700295 DM_DRIVER_ALIAS(mmc_drv, vendor_mmc) /* matches compatible string */
Simon Glass261ad282016-07-04 11:58:07 -0600296
Simon Glassb75b15b2020-12-03 16:55:23 -0700297Note that struct mmc_plat is defined in the C file, not in a header. This
Simon Glass63c19ed2019-12-06 21:42:43 -0700298is to avoid needing to include dt-structs.h in a header file. The idea is to
299keep the use of each of-platdata struct to the smallest possible code area.
300There is just one driver C file for each struct, that can convert from the
301of-platdata struct to the standard one used by the driver.
302
Simon Glass71fa5b42020-12-03 16:55:18 -0700303In the case where SPL_OF_PLATDATA is enabled, plat_auto is
Simon Glass946c7232016-07-04 11:58:42 -0600304still used to allocate space for the platform data. This is different from
305the normal behaviour and is triggered by the use of of-platdata (strictly
Simon Glass39edb952020-12-03 16:55:19 -0700306speaking it is a non-zero plat_size which triggers this).
Simon Glass261ad282016-07-04 11:58:07 -0600307
Simon Glass946c7232016-07-04 11:58:42 -0600308The of-platdata struct contents is copied from the C structure data to the
309start of the newly allocated area. In the case where device tree is used,
310the platform data is allocated, and starts zeroed. In this case the
Simon Glassaad29ae2020-12-03 16:55:21 -0700311of_to_plat() method should still set up the platform data (and the
Simon Glass946c7232016-07-04 11:58:42 -0600312of-platdata struct will not be present).
313
314SPL must use either of-platdata or device tree. Drivers cannot use both at
315the same time, but they must support device tree. Supporting of-platdata is
316optional.
Simon Glass261ad282016-07-04 11:58:07 -0600317
Simon Glass946c7232016-07-04 11:58:42 -0600318The device tree becomes in accessible when CONFIG_SPL_OF_PLATDATA is enabled,
319since the device-tree access code is not compiled in. A corollary is that
320a board can only move to using of-platdata if all the drivers it uses support
321it. There would be little point in having some drivers require the device
322tree data, since then libfdt would still be needed for those drivers and
323there would be no code-size benefit.
Simon Glass261ad282016-07-04 11:58:07 -0600324
325Internals
326---------
327
328The dt-structs.h file includes the generated file
329(include/generated//dt-structs.h) if CONFIG_SPL_OF_PLATDATA is enabled.
330Otherwise (such as in U-Boot proper) these structs are not available. This
Simon Glass946c7232016-07-04 11:58:42 -0600331prevents them being used inadvertently. All usage must be bracketed with
Lukasz Majewskifd54ab22019-09-03 15:43:19 +0200332#if CONFIG_IS_ENABLED(OF_PLATDATA).
Simon Glass261ad282016-07-04 11:58:07 -0600333
Simon Glass71fa5b42020-12-03 16:55:18 -0700334The dt-plat.c file contains the device declarations and is is built in
Simon Glass2500de22020-12-28 20:35:05 -0700335spl/dt-plat.c.
336
337The dm_populate_phandle_data() function that was previous needed has now been
338removed, since dtoc can address the drivers directly from dt-plat.c and does
339not need to fix up things at runtime.
Simon Glass261ad282016-07-04 11:58:07 -0600340
Simon Glassa7729462020-10-03 11:31:42 -0600341The pylibfdt Python module is used to access the devicetree.
Simon Glass261ad282016-07-04 11:58:07 -0600342
Simon Glass946c7232016-07-04 11:58:42 -0600343
344Credits
345-------
346
347This is an implementation of an idea by Tom Rini <trini@konsulko.com>.
Simon Glass261ad282016-07-04 11:58:07 -0600348
349
350Future work
351-----------
Simon Glass261ad282016-07-04 11:58:07 -0600352- Consider programmatically reading binding files instead of device tree
Bin Mengae258692019-07-18 00:33:55 -0700353 contents
Simon Glass261ad282016-07-04 11:58:07 -0600354
Bin Mengae258692019-07-18 00:33:55 -0700355
356.. Simon Glass <sjg@chromium.org>
357.. Google, Inc
358.. 6/6/16
359.. Updated Independence Day 2016
Simon Glassa7729462020-10-03 11:31:42 -0600360.. Updated 1st October 2020