blob: 1e3fad137be5dac5a6108d6d11baa0bee67c97c5 [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 Glass946c7232016-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 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
Simon Goldschmidt49ce8ca2019-01-16 20:40:18 +010069 - Correct relations between nodes are not implemented. This means that
Bin Mengae258692019-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
Walter Lozanode707f42020-06-25 01:10:14 -030072 a pointer to struct driver_info. This pointer can be used to access
73 the referenced device.
Simon Goldschmidt49ce8ca2019-01-16 20:40:18 +010074
Simon Glass261ad282016-07-04 11:58:07 -060075
76How it works
77------------
78
Simon Goldschmidt49ce8ca2019-01-16 20:40:18 +010079The feature is enabled by CONFIG OF_PLATDATA. This is only available in
80SPL/TPL and should be tested with:
Simon Glass261ad282016-07-04 11:58:07 -060081
Bin Mengae258692019-07-18 00:33:55 -070082.. code-block:: c
83
84 #if CONFIG_IS_ENABLED(OF_PLATDATA)
Simon Glass261ad282016-07-04 11:58:07 -060085
86A new tool called 'dtoc' converts a device tree file either into a set of
Simon Goldschmidt49ce8ca2019-01-16 20:40:18 +010087struct declarations, one for each compatible node, and a set of
Simon Glass261ad282016-07-04 11:58:07 -060088U_BOOT_DEVICE() declarations along with the actual platform data for each
89device. As an example, consider this MMC node:
90
Bin Mengae258692019-07-18 00:33:55 -070091.. code-block:: none
92
93 sdmmc: dwmmc@ff0c0000 {
94 compatible = "rockchip,rk3288-dw-mshc";
95 clock-freq-min-max = <400000 150000000>;
96 clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>,
97 <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>;
98 clock-names = "biu", "ciu", "ciu_drv", "ciu_sample";
99 fifo-depth = <0x100>;
100 interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>;
101 reg = <0xff0c0000 0x4000>;
102 bus-width = <4>;
103 cap-mmc-highspeed;
104 cap-sd-highspeed;
105 card-detect-delay = <200>;
106 disable-wp;
107 num-slots = <1>;
108 pinctrl-names = "default";
109 pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>;
Simon Glass261ad282016-07-04 11:58:07 -0600110 vmmc-supply = <&vcc_sd>;
111 status = "okay";
112 u-boot,dm-pre-reloc;
113 };
114
115
116Some of these properties are dropped by U-Boot under control of the
117CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce
118the following C struct declaration:
119
Bin Mengae258692019-07-18 00:33:55 -0700120.. code-block:: c
121
122 struct dtd_rockchip_rk3288_dw_mshc {
123 fdt32_t bus_width;
124 bool cap_mmc_highspeed;
125 bool cap_sd_highspeed;
126 fdt32_t card_detect_delay;
127 fdt32_t clock_freq_min_max[2];
128 struct phandle_1_arg clocks[4];
129 bool disable_wp;
130 fdt32_t fifo_depth;
131 fdt32_t interrupts[3];
132 fdt32_t num_slots;
133 fdt32_t reg[2];
134 fdt32_t vmmc_supply;
135 };
Simon Glass261ad282016-07-04 11:58:07 -0600136
137and the following device declaration:
138
Bin Mengae258692019-07-18 00:33:55 -0700139.. code-block:: c
140
141 static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = {
142 .fifo_depth = 0x100,
143 .cap_sd_highspeed = true,
144 .interrupts = {0x0, 0x20, 0x4},
145 .clock_freq_min_max = {0x61a80, 0x8f0d180},
146 .vmmc_supply = 0xb,
147 .num_slots = 0x1,
Walter Lozanode707f42020-06-25 01:10:14 -0300148 .clocks = {{NULL, 456},
149 {NULL, 68},
150 {NULL, 114},
151 {NULL, 118}},
Bin Mengae258692019-07-18 00:33:55 -0700152 .cap_mmc_highspeed = true,
153 .disable_wp = true,
154 .bus_width = 0x4,
155 .u_boot_dm_pre_reloc = true,
156 .reg = {0xff0c0000, 0x4000},
157 .card_detect_delay = 0xc8,
158 };
159
160 U_BOOT_DEVICE(dwmmc_at_ff0c0000) = {
161 .name = "rockchip_rk3288_dw_mshc",
162 .platdata = &dtv_dwmmc_at_ff0c0000,
163 .platdata_size = sizeof(dtv_dwmmc_at_ff0c0000),
164 };
Simon Glass261ad282016-07-04 11:58:07 -0600165
Walter Lozanode707f42020-06-25 01:10:14 -0300166 void dm_populate_phandle_data(void) {
167 dtv_dwmmc_at_ff0c0000.clocks[0].node = DM_GET_DEVICE(clock_controller_at_ff760000);
168 dtv_dwmmc_at_ff0c0000.clocks[1].node = DM_GET_DEVICE(clock_controller_at_ff760000);
169 dtv_dwmmc_at_ff0c0000.clocks[2].node = DM_GET_DEVICE(clock_controller_at_ff760000);
170 dtv_dwmmc_at_ff0c0000.clocks[3].node = DM_GET_DEVICE(clock_controller_at_ff760000);
171 }
172
Simon Glass261ad282016-07-04 11:58:07 -0600173The device is then instantiated at run-time and the platform data can be
174accessed using:
175
Bin Mengae258692019-07-18 00:33:55 -0700176.. code-block:: c
177
178 struct udevice *dev;
179 struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_platdata(dev);
Simon Glass261ad282016-07-04 11:58:07 -0600180
181This avoids the code overhead of converting the device tree data to
182platform data in the driver. The ofdata_to_platdata() method should
183therefore do nothing in such a driver.
184
Simon Goldschmidt49ce8ca2019-01-16 20:40:18 +0100185Note that for the platform data to be matched with a driver, the 'name'
186property of the U_BOOT_DEVICE() declaration has to match a driver declared
187via U_BOOT_DRIVER(). This effectively means that a U_BOOT_DRIVER() with a
188'name' corresponding to the devicetree 'compatible' string (after converting
189it to a valid name for C) is needed, so a dedicated driver is required for
190each 'compatible' string.
191
Walter Lozanoc38b4912020-06-25 01:10:09 -0300192In order to make this a bit more flexible U_BOOT_DRIVER_ALIAS macro can be
193used to declare an alias for a driver name, typically a 'compatible' string.
194This macro produces no code, but it is by dtoc tool.
195
196During the build process dtoc parses both U_BOOT_DRIVER and U_BOOT_DRIVER_ALIAS
197to build a list of valid driver names and driver aliases. If the 'compatible'
198string used for a device does not not match a valid driver name, it will be
199checked against the list of driver aliases in order to get the right driver
200name to use. If in this step there is no match found a warning is issued to
201avoid run-time failures.
202
Simon Glass934be0b2017-06-13 21:10:06 -0600203Where a node has multiple compatible strings, a #define is used to make them
204equivalent, e.g.:
205
Bin Mengae258692019-07-18 00:33:55 -0700206.. code-block:: c
Simon Glass934be0b2017-06-13 21:10:06 -0600207
Bin Mengae258692019-07-18 00:33:55 -0700208 #define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc
209
Simon Glass946c7232016-07-04 11:58:42 -0600210
211Converting of-platdata to a useful form
212---------------------------------------
213
Simon Goldschmidt49ce8ca2019-01-16 20:40:18 +0100214Of course it would be possible to use the of-platdata directly in your driver
215whenever configuration information is required. However this means that the
Simon Glass946c7232016-07-04 11:58:42 -0600216driver will not be able to support device tree, since the of-platdata
217structure is not available when device tree is used. It would make no sense
218to use this structure if device tree were available, since the structure has
219all the limitations metioned in caveats above.
220
221Therefore it is recommended that the of-platdata structure should be used
222only in the probe() method of your driver. It cannot be used in the
223ofdata_to_platdata() method since this is not called when platform data is
224already present.
225
Simon Glass261ad282016-07-04 11:58:07 -0600226
227How to structure your driver
228----------------------------
229
230Drivers should always support device tree as an option. The of-platdata
231feature is intended as a add-on to existing drivers.
232
Simon Glass946c7232016-07-04 11:58:42 -0600233Your driver should convert the platdata struct in its probe() method. The
234existing device tree decoding logic should be kept in the
235ofdata_to_platdata() method and wrapped with #if.
Simon Glass261ad282016-07-04 11:58:07 -0600236
237For example:
238
Bin Mengae258692019-07-18 00:33:55 -0700239.. code-block:: c
240
Simon Glass261ad282016-07-04 11:58:07 -0600241 #include <dt-structs.h>
242
243 struct mmc_platdata {
Lukasz Majewskifd54ab22019-09-03 15:43:19 +0200244 #if CONFIG_IS_ENABLED(OF_PLATDATA)
Simon Glass946c7232016-07-04 11:58:42 -0600245 /* Put this first since driver model will copy the data here */
Simon Glass261ad282016-07-04 11:58:07 -0600246 struct dtd_mmc dtplat;
247 #endif
248 /*
249 * Other fields can go here, to be filled in by decoding from
Simon Glass946c7232016-07-04 11:58:42 -0600250 * the device tree (or the C structures when of-platdata is used).
Simon Glass261ad282016-07-04 11:58:07 -0600251 */
252 int fifo_depth;
253 };
254
255 static int mmc_ofdata_to_platdata(struct udevice *dev)
256 {
Lukasz Majewskifd54ab22019-09-03 15:43:19 +0200257 #if !CONFIG_IS_ENABLED(OF_PLATDATA)
Simon Glass946c7232016-07-04 11:58:42 -0600258 /* Decode the device tree data */
Simon Glass261ad282016-07-04 11:58:07 -0600259 struct mmc_platdata *plat = dev_get_platdata(dev);
260 const void *blob = gd->fdt_blob;
Simon Glassdd79d6e2017-01-17 16:52:55 -0700261 int node = dev_of_offset(dev);
Simon Glass261ad282016-07-04 11:58:07 -0600262
263 plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0);
264 #endif
265
266 return 0;
267 }
268
269 static int mmc_probe(struct udevice *dev)
270 {
271 struct mmc_platdata *plat = dev_get_platdata(dev);
Simon Glass946c7232016-07-04 11:58:42 -0600272
Lukasz Majewskifd54ab22019-09-03 15:43:19 +0200273 #if CONFIG_IS_ENABLED(OF_PLATDATA)
Simon Glass946c7232016-07-04 11:58:42 -0600274 /* Decode the of-platdata from the C structures */
Simon Glass261ad282016-07-04 11:58:07 -0600275 struct dtd_mmc *dtplat = &plat->dtplat;
276
Simon Glass946c7232016-07-04 11:58:42 -0600277 plat->fifo_depth = dtplat->fifo_depth;
278 #endif
Simon Glass261ad282016-07-04 11:58:07 -0600279 /* Set up the device from the plat data */
280 writel(plat->fifo_depth, ...)
Simon Glass261ad282016-07-04 11:58:07 -0600281 }
282
283 static const struct udevice_id mmc_ids[] = {
284 { .compatible = "vendor,mmc" },
285 { }
286 };
287
288 U_BOOT_DRIVER(mmc_drv) = {
Walter Lozanoc38b4912020-06-25 01:10:09 -0300289 .name = "mmc_drv",
Simon Glass261ad282016-07-04 11:58:07 -0600290 .id = UCLASS_MMC,
291 .of_match = mmc_ids,
292 .ofdata_to_platdata = mmc_ofdata_to_platdata,
293 .probe = mmc_probe,
294 .priv_auto_alloc_size = sizeof(struct mmc_priv),
295 .platdata_auto_alloc_size = sizeof(struct mmc_platdata),
296 };
297
Walter Lozanoc38b4912020-06-25 01:10:09 -0300298 U_BOOT_DRIVER_ALIAS(mmc_drv, vendor_mmc) /* matches compatible string */
Simon Glass261ad282016-07-04 11:58:07 -0600299
Simon Glass63c19ed2019-12-06 21:42:43 -0700300Note that struct mmc_platdata is defined in the C file, not in a header. This
301is to avoid needing to include dt-structs.h in a header file. The idea is to
302keep the use of each of-platdata struct to the smallest possible code area.
303There is just one driver C file for each struct, that can convert from the
304of-platdata struct to the standard one used by the driver.
305
Simon Glass261ad282016-07-04 11:58:07 -0600306In the case where SPL_OF_PLATDATA is enabled, platdata_auto_alloc_size is
Simon Glass946c7232016-07-04 11:58:42 -0600307still used to allocate space for the platform data. This is different from
308the normal behaviour and is triggered by the use of of-platdata (strictly
309speaking it is a non-zero platdata_size which triggers this).
Simon Glass261ad282016-07-04 11:58:07 -0600310
Simon Glass946c7232016-07-04 11:58:42 -0600311The of-platdata struct contents is copied from the C structure data to the
312start of the newly allocated area. In the case where device tree is used,
313the platform data is allocated, and starts zeroed. In this case the
314ofdata_to_platdata() method should still set up the platform data (and the
315of-platdata struct will not be present).
316
317SPL must use either of-platdata or device tree. Drivers cannot use both at
318the same time, but they must support device tree. Supporting of-platdata is
319optional.
Simon Glass261ad282016-07-04 11:58:07 -0600320
Simon Glass946c7232016-07-04 11:58:42 -0600321The device tree becomes in accessible when CONFIG_SPL_OF_PLATDATA is enabled,
322since the device-tree access code is not compiled in. A corollary is that
323a board can only move to using of-platdata if all the drivers it uses support
324it. There would be little point in having some drivers require the device
325tree data, since then libfdt would still be needed for those drivers and
326there would be no code-size benefit.
Simon Glass261ad282016-07-04 11:58:07 -0600327
328Internals
329---------
330
331The dt-structs.h file includes the generated file
332(include/generated//dt-structs.h) if CONFIG_SPL_OF_PLATDATA is enabled.
333Otherwise (such as in U-Boot proper) these structs are not available. This
Simon Glass946c7232016-07-04 11:58:42 -0600334prevents them being used inadvertently. All usage must be bracketed with
Lukasz Majewskifd54ab22019-09-03 15:43:19 +0200335#if CONFIG_IS_ENABLED(OF_PLATDATA).
Simon Glass261ad282016-07-04 11:58:07 -0600336
337The dt-platdata.c file contains the device declarations and is is built in
Walter Lozanode707f42020-06-25 01:10:14 -0300338spl/dt-platdata.c. It additionally contains the definition of
339dm_populate_phandle_data() which is responsible of filling the phandle
340information by adding references to U_BOOT_DEVICE by using DM_GET_DEVICE
Simon Glass261ad282016-07-04 11:58:07 -0600341
Simon Glass261ad282016-07-04 11:58:07 -0600342The beginnings of a libfdt Python module are provided. So far this only
343implements a subset of the features.
344
Simon Glass946c7232016-07-04 11:58:42 -0600345The 'swig' tool is needed to build the libfdt Python module. If this is not
346found then the Python model is not used and a fallback is used instead, which
347makes use of fdtget.
348
349
350Credits
351-------
352
353This is an implementation of an idea by Tom Rini <trini@konsulko.com>.
Simon Glass261ad282016-07-04 11:58:07 -0600354
355
356Future work
357-----------
Simon Glass261ad282016-07-04 11:58:07 -0600358- Consider programmatically reading binding files instead of device tree
Bin Mengae258692019-07-18 00:33:55 -0700359 contents
Simon Glass261ad282016-07-04 11:58:07 -0600360- Complete the phandle feature
Simon Glass261ad282016-07-04 11:58:07 -0600361- Move to using a full Python libfdt module
362
Bin Mengae258692019-07-18 00:33:55 -0700363
364.. Simon Glass <sjg@chromium.org>
365.. Google, Inc
366.. 6/6/16
367.. Updated Independence Day 2016