1 Driver Model Compiled-in Device Tree / Platform Data
2 ====================================================
8 Device tree is the standard configuration method in U-Boot. It is used to
9 define what devices are in the system and provide configuration information
12 The overhead of adding device tree access to U-Boot is fairly modest,
13 approximately 3KB on Thumb 2 (plus the size of the DT itself). This means
14 that in most cases it is best to use device tree for configuration.
16 However there are some very constrained environments where U-Boot needs to
17 work. These include SPL with severe memory limitations. For example, some
18 SoCs require a 16KB SPL image which must include a full MMC stack. In this
19 case the overhead of device tree access may be too great.
21 It is possible to create platform data manually by defining C structures
22 for it, and reference that data in a U_BOOT_DEVICE() declaration. This
23 bypasses the use of device tree completely, effectively creating a parallel
24 configuration mechanism. But it is an available option for SPL.
26 As an alternative, a new 'of-platdata' feature is provided. This converts the
27 device tree contents into C code which can be compiled into the SPL binary.
28 This saves the 3KB of code overhead and perhaps a few hundred more bytes due
29 to more efficient storage of the data.
31 Note: Quite a bit of thought has gone into the design of this feature.
32 However it still has many rough edges and comments and suggestions are
33 strongly encouraged! Quite possibly there is a much better approach.
39 There are many problems with this features. It should only be used when
40 strictly necessary. Notable problems include:
42 - Device tree does not describe data types. But the C code must define a
43 type for each property. These are guessed using heuristics which
44 are wrong in several fairly common cases. For example an 8-byte value
45 is considered to be a 2-item integer array, and is byte-swapped. A
46 boolean value that is not present means 'false', but cannot be
47 included in the structures since there is generally no mention of it
48 in the device tree file.
50 - Naming of nodes and properties is automatic. This means that they follow
51 the naming in the device tree, which may result in C identifiers that
54 - It is not possible to find a value given a property name. Code must use
55 the associated C member variable directly in the code. This makes
56 the code less robust in the face of device-tree changes. It also
57 makes it very unlikely that your driver code will be useful for more
58 than one SoC. Even if the code is common, each SoC will end up with
59 a different C struct name, and a likely a different format for the
62 - The platform data is provided to drivers as a C structure. The driver
63 must use the same structure to access the data. Since a driver
64 normally also supports device tree it must use #ifdef to separate
65 out this code, since the structures are only available in SPL.
67 - Correct relations between nodes are not implemented. This means that
68 parent/child relations (like bus device iteration) do not work yet.
69 Some phandles (those that are recognised as such) are converted into
70 a pointer to platform data. This pointer can potentially be used to
71 access the referenced device (by searching for the pointer value).
72 This feature is not yet implemented, however.
78 The feature is enabled by CONFIG OF_PLATDATA. This is only available in
79 SPL/TPL and should be tested with:
81 #if CONFIG_IS_ENABLED(OF_PLATDATA)
83 A new tool called 'dtoc' converts a device tree file either into a set of
84 struct declarations, one for each compatible node, and a set of
85 U_BOOT_DEVICE() declarations along with the actual platform data for each
86 device. As an example, consider this MMC node:
88 sdmmc: dwmmc@ff0c0000 {
89 compatible = "rockchip,rk3288-dw-mshc";
90 clock-freq-min-max = <400000 150000000>;
91 clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>,
92 <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>;
93 clock-names = "biu", "ciu", "ciu_drv", "ciu_sample";
95 interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>;
96 reg = <0xff0c0000 0x4000>;
100 card-detect-delay = <200>;
103 pinctrl-names = "default";
104 pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>;
105 vmmc-supply = <&vcc_sd>;
111 Some of these properties are dropped by U-Boot under control of the
112 CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce
113 the following C struct declaration:
115 struct dtd_rockchip_rk3288_dw_mshc {
117 bool cap_mmc_highspeed;
118 bool cap_sd_highspeed;
119 fdt32_t card_detect_delay;
120 fdt32_t clock_freq_min_max[2];
121 struct phandle_1_arg clocks[4];
124 fdt32_t interrupts[3];
130 and the following device declaration:
132 static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = {
134 .cap_sd_highspeed = true,
135 .interrupts = {0x0, 0x20, 0x4},
136 .clock_freq_min_max = {0x61a80, 0x8f0d180},
139 .clocks = {{&dtv_clock_controller_at_ff760000, 456},
140 {&dtv_clock_controller_at_ff760000, 68},
141 {&dtv_clock_controller_at_ff760000, 114},
142 {&dtv_clock_controller_at_ff760000, 118}},
143 .cap_mmc_highspeed = true,
146 .u_boot_dm_pre_reloc = true,
147 .reg = {0xff0c0000, 0x4000},
148 .card_detect_delay = 0xc8,
150 U_BOOT_DEVICE(dwmmc_at_ff0c0000) = {
151 .name = "rockchip_rk3288_dw_mshc",
152 .platdata = &dtv_dwmmc_at_ff0c0000,
153 .platdata_size = sizeof(dtv_dwmmc_at_ff0c0000),
156 The device is then instantiated at run-time and the platform data can be
160 struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_platdata(dev);
162 This avoids the code overhead of converting the device tree data to
163 platform data in the driver. The ofdata_to_platdata() method should
164 therefore do nothing in such a driver.
166 Note that for the platform data to be matched with a driver, the 'name'
167 property of the U_BOOT_DEVICE() declaration has to match a driver declared
168 via U_BOOT_DRIVER(). This effectively means that a U_BOOT_DRIVER() with a
169 'name' corresponding to the devicetree 'compatible' string (after converting
170 it to a valid name for C) is needed, so a dedicated driver is required for
171 each 'compatible' string.
173 Where a node has multiple compatible strings, a #define is used to make them
176 #define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc
179 Converting of-platdata to a useful form
180 ---------------------------------------
182 Of course it would be possible to use the of-platdata directly in your driver
183 whenever configuration information is required. However this means that the
184 driver will not be able to support device tree, since the of-platdata
185 structure is not available when device tree is used. It would make no sense
186 to use this structure if device tree were available, since the structure has
187 all the limitations metioned in caveats above.
189 Therefore it is recommended that the of-platdata structure should be used
190 only in the probe() method of your driver. It cannot be used in the
191 ofdata_to_platdata() method since this is not called when platform data is
195 How to structure your driver
196 ----------------------------
198 Drivers should always support device tree as an option. The of-platdata
199 feature is intended as a add-on to existing drivers.
201 Your driver should convert the platdata struct in its probe() method. The
202 existing device tree decoding logic should be kept in the
203 ofdata_to_platdata() method and wrapped with #if.
207 #include <dt-structs.h>
209 struct mmc_platdata {
210 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA)
211 /* Put this first since driver model will copy the data here */
212 struct dtd_mmc dtplat;
215 * Other fields can go here, to be filled in by decoding from
216 * the device tree (or the C structures when of-platdata is used).
221 static int mmc_ofdata_to_platdata(struct udevice *dev)
223 #if !CONFIG_IS_ENABLED(SPL_OF_PLATDATA)
224 /* Decode the device tree data */
225 struct mmc_platdata *plat = dev_get_platdata(dev);
226 const void *blob = gd->fdt_blob;
227 int node = dev_of_offset(dev);
229 plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0);
235 static int mmc_probe(struct udevice *dev)
237 struct mmc_platdata *plat = dev_get_platdata(dev);
239 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA)
240 /* Decode the of-platdata from the C structures */
241 struct dtd_mmc *dtplat = &plat->dtplat;
243 plat->fifo_depth = dtplat->fifo_depth;
245 /* Set up the device from the plat data */
246 writel(plat->fifo_depth, ...)
249 static const struct udevice_id mmc_ids[] = {
250 { .compatible = "vendor,mmc" },
254 U_BOOT_DRIVER(mmc_drv) = {
258 .ofdata_to_platdata = mmc_ofdata_to_platdata,
260 .priv_auto_alloc_size = sizeof(struct mmc_priv),
261 .platdata_auto_alloc_size = sizeof(struct mmc_platdata),
265 In the case where SPL_OF_PLATDATA is enabled, platdata_auto_alloc_size is
266 still used to allocate space for the platform data. This is different from
267 the normal behaviour and is triggered by the use of of-platdata (strictly
268 speaking it is a non-zero platdata_size which triggers this).
270 The of-platdata struct contents is copied from the C structure data to the
271 start of the newly allocated area. In the case where device tree is used,
272 the platform data is allocated, and starts zeroed. In this case the
273 ofdata_to_platdata() method should still set up the platform data (and the
274 of-platdata struct will not be present).
276 SPL must use either of-platdata or device tree. Drivers cannot use both at
277 the same time, but they must support device tree. Supporting of-platdata is
280 The device tree becomes in accessible when CONFIG_SPL_OF_PLATDATA is enabled,
281 since the device-tree access code is not compiled in. A corollary is that
282 a board can only move to using of-platdata if all the drivers it uses support
283 it. There would be little point in having some drivers require the device
284 tree data, since then libfdt would still be needed for those drivers and
285 there would be no code-size benefit.
290 The dt-structs.h file includes the generated file
291 (include/generated//dt-structs.h) if CONFIG_SPL_OF_PLATDATA is enabled.
292 Otherwise (such as in U-Boot proper) these structs are not available. This
293 prevents them being used inadvertently. All usage must be bracketed with
294 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA).
296 The dt-platdata.c file contains the device declarations and is is built in
299 The beginnings of a libfdt Python module are provided. So far this only
300 implements a subset of the features.
302 The 'swig' tool is needed to build the libfdt Python module. If this is not
303 found then the Python model is not used and a fallback is used instead, which
310 This is an implementation of an idea by Tom Rini <trini@konsulko.com>.
315 - Consider programmatically reading binding files instead of device tree
317 - Complete the phandle feature
318 - Move to using a full Python libfdt module
321 Simon Glass <sjg@chromium.org>
324 Updated Independence Day 2016