doc/driver-model/of-plat.txt

1 Driver Model Compiled-in Device Tree / Platform Data
6 ------------
8 Device tree is the standard configuration method in U-Boot. It is used to
12 The overhead of adding device tree access to U-Boot is fairly modest,
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
19 case the overhead of device tree access may be too great.
23 bypasses the use of device tree completely, effectively creating a parallel
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.
37 -------
42    - Device tree does not describe data types. But the C code must define a
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
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
56         the code less robust in the face of device-tree changes. It also
62    - The platform data is provided to drivers as a C structure. The driver
64         normally also supports device tree it must use #ifdef to separate
69 ------------
76 A new tool called 'dtoc' converts a device tree file either into a set of
79 device. As an example, consider this MMC node:
82                 compatible = "rockchip,rk3288-dw-mshc";
83                 clock-freq-min-max = <400000 150000000>;
86                 clock-names = "biu", "ciu", "ciu_drv", "ciu_sample";
87                 fifo-depth = <0x100>;
90                 bus-width = <4>;
91                 cap-mmc-highspeed;
92                 cap-sd-highspeed;
93                 card-detect-delay = <200>;
94                 disable-wp;
95                 num-slots = <1>;
96                 pinctrl-names = "default";
97                 pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>;
98                 vmmc-supply = <&vcc_sd>;
100                 u-boot,dm-pre-reloc;
104 Some of these properties are dropped by U-Boot under control of the
123 and the following device declaration:
149 The device is then instantiated at run-time and the platform data can be
155 This avoids the code overhead of converting the device tree data to
165 Converting of-platdata to a useful form
166 ---------------------------------------
168 Of course it would be possible use the of-platdata directly in your driver
170 driver will not be able to support device tree, since the of-platdata
171 structure is not available when device tree is used. It would make no sense
172 to use this structure if device tree were available, since the structure has
175 Therefore it is recommended that the of-platdata structure should be used
182 ----------------------------
184 Drivers should always support device tree as an option. The of-platdata
185 feature is intended as a add-on to existing drivers.
188 existing device tree decoding logic should be kept in the
193     #include <dt-structs.h>
202              * the device tree (or the C structures when of-platdata is used).
210             /* Decode the device tree data */
212             const void *blob = gd->fdt_blob;
215             plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0);
226             /* Decode the of-platdata from the C structures */
227             struct dtd_mmc *dtplat = &plat->dtplat;
229             plat->fifo_depth = dtplat->fifo_depth;
231             /* Set up the device from the plat data */
232             writel(plat->fifo_depth, ...)
253 the normal behaviour and is triggered by the use of of-platdata (strictly
254 speaking it is a non-zero platdata_size which triggers this).
256 The of-platdata struct contents is copied from the C structure data to the
257 start of the newly allocated area. In the case where device tree is used,
260 of-platdata struct will not be present).
262 SPL must use either of-platdata or device tree. Drivers cannot use both at
263 the same time, but they must support device tree. Supporting of-platdata is
266 The device tree becomes in accessible when CONFIG_SPL_OF_PLATDATA is enabled,
267 since the device-tree access code is not compiled in. A corollary is that
268 a board can only move to using of-platdata if all the drivers it uses support
269 it. There would be little point in having some drivers require the device
270 tree data, since then libfdt would still be needed for those drivers and
271 there would be no code-size benefit.
274 ---------
276 The dt-structs.h file includes the generated file
277 (include/generated//dt-structs.h) if CONFIG_SPL_OF_PLATDATA is enabled.
278 Otherwise (such as in U-Boot proper) these structs are not available. This
282 The dt-platdata.c file contains the device declarations and is is built in
283 spl/dt-platdata.c.
287 referenced device (by searching for the pointer value). This feature is not
299 -------
305 -----------
306 - Consider programmatically reading binding files instead of device tree
308 - Complete the phandle feature
309 - Move to using a full Python libfdt module
311 --