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,
16 However there are some very constrained environments where U-Boot needs to
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
26 As an alternative, a new 'of-platdata' feature is provided. This converts the
29 to more efficient storage of the data.
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
50    - Naming of nodes and properties is automatic. This means that they follow
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
60         platform data.
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
69 ------------
78 U_BOOT_DEVICE() declarations along with the actual platform data for each
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
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
156 platform data in the driver. The ofdata_to_platdata() method should
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
175 Therefore it is recommended that the of-platdata structure should be used
177 ofdata_to_platdata() method since this is not called when platform data is
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.
193     #include <dt-structs.h>
197             /* Put this first since driver model will copy the data here */
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, ...)
252 still used to allocate space for the platform data. This is different from
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
258 the platform data is allocated, and starts zeroed. In this case the
259 ofdata_to_platdata() method should still set up the platform data (and the
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
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
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.
286 points to platform data. This pointer can potentially be used to access the
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 --