1.. SPDX-License-Identifier: GPL-2.0+ 2 3Compiled-in Device Tree / Platform Data 4======================================= 5 6 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 24for 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. 27 28As an alternative, a new 'of-platdata' feature is provided. This converts the 29device 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 33Note: 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 37 38Caveats 39------- 40 41There are many problems with this features. It should only be used when 42strictly necessary. Notable problems include: 43 44 - Device tree does not describe data types. But the C code must define a 45 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. 51 52 - Naming of nodes and properties is automatic. This means that they follow 53 the naming in the device tree, which may result in C identifiers that 54 look a bit strange. 55 56 - It is not possible to find a value given a property name. Code must use 57 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. 63 64 - The platform data is provided to drivers as a C structure. The driver 65 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. 68 69 - Correct relations between nodes are not implemented. This means that 70 parent/child relations (like bus device iteration) do not work yet. 71 Some phandles (those that are recognised as such) are converted into 72 a pointer to platform data. This pointer can potentially be used to 73 access the referenced device (by searching for the pointer value). 74 This feature is not yet implemented, however. 75 76 77How it works 78------------ 79 80The feature is enabled by CONFIG OF_PLATDATA. This is only available in 81SPL/TPL and should be tested with: 82 83.. code-block:: c 84 85 #if CONFIG_IS_ENABLED(OF_PLATDATA) 86 87A new tool called 'dtoc' converts a device tree file either into a set of 88struct declarations, one for each compatible node, and a set of 89U_BOOT_DEVICE() declarations along with the actual platform data for each 90device. As an example, consider this MMC node: 91 92.. code-block:: none 93 94 sdmmc: dwmmc@ff0c0000 { 95 compatible = "rockchip,rk3288-dw-mshc"; 96 clock-freq-min-max = <400000 150000000>; 97 clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>, 98 <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>; 99 clock-names = "biu", "ciu", "ciu_drv", "ciu_sample"; 100 fifo-depth = <0x100>; 101 interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; 102 reg = <0xff0c0000 0x4000>; 103 bus-width = <4>; 104 cap-mmc-highspeed; 105 cap-sd-highspeed; 106 card-detect-delay = <200>; 107 disable-wp; 108 num-slots = <1>; 109 pinctrl-names = "default"; 110 pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>; 111 vmmc-supply = <&vcc_sd>; 112 status = "okay"; 113 u-boot,dm-pre-reloc; 114 }; 115 116 117Some of these properties are dropped by U-Boot under control of the 118CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce 119the following C struct declaration: 120 121.. code-block:: c 122 123 struct dtd_rockchip_rk3288_dw_mshc { 124 fdt32_t bus_width; 125 bool cap_mmc_highspeed; 126 bool cap_sd_highspeed; 127 fdt32_t card_detect_delay; 128 fdt32_t clock_freq_min_max[2]; 129 struct phandle_1_arg clocks[4]; 130 bool disable_wp; 131 fdt32_t fifo_depth; 132 fdt32_t interrupts[3]; 133 fdt32_t num_slots; 134 fdt32_t reg[2]; 135 fdt32_t vmmc_supply; 136 }; 137 138and the following device declaration: 139 140.. code-block:: c 141 142 static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = { 143 .fifo_depth = 0x100, 144 .cap_sd_highspeed = true, 145 .interrupts = {0x0, 0x20, 0x4}, 146 .clock_freq_min_max = {0x61a80, 0x8f0d180}, 147 .vmmc_supply = 0xb, 148 .num_slots = 0x1, 149 .clocks = {{&dtv_clock_controller_at_ff760000, 456}, 150 {&dtv_clock_controller_at_ff760000, 68}, 151 {&dtv_clock_controller_at_ff760000, 114}, 152 {&dtv_clock_controller_at_ff760000, 118}}, 153 .cap_mmc_highspeed = true, 154 .disable_wp = true, 155 .bus_width = 0x4, 156 .u_boot_dm_pre_reloc = true, 157 .reg = {0xff0c0000, 0x4000}, 158 .card_detect_delay = 0xc8, 159 }; 160 161 U_BOOT_DEVICE(dwmmc_at_ff0c0000) = { 162 .name = "rockchip_rk3288_dw_mshc", 163 .platdata = &dtv_dwmmc_at_ff0c0000, 164 .platdata_size = sizeof(dtv_dwmmc_at_ff0c0000), 165 }; 166 167The device is then instantiated at run-time and the platform data can be 168accessed using: 169 170.. code-block:: c 171 172 struct udevice *dev; 173 struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_platdata(dev); 174 175This avoids the code overhead of converting the device tree data to 176platform data in the driver. The ofdata_to_platdata() method should 177therefore do nothing in such a driver. 178 179Note that for the platform data to be matched with a driver, the 'name' 180property of the U_BOOT_DEVICE() declaration has to match a driver declared 181via U_BOOT_DRIVER(). This effectively means that a U_BOOT_DRIVER() with a 182'name' corresponding to the devicetree 'compatible' string (after converting 183it to a valid name for C) is needed, so a dedicated driver is required for 184each 'compatible' string. 185 186Where a node has multiple compatible strings, a #define is used to make them 187equivalent, e.g.: 188 189.. code-block:: c 190 191 #define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc 192 193 194Converting of-platdata to a useful form 195--------------------------------------- 196 197Of course it would be possible to use the of-platdata directly in your driver 198whenever configuration information is required. However this means that the 199driver will not be able to support device tree, since the of-platdata 200structure is not available when device tree is used. It would make no sense 201to use this structure if device tree were available, since the structure has 202all the limitations metioned in caveats above. 203 204Therefore it is recommended that the of-platdata structure should be used 205only in the probe() method of your driver. It cannot be used in the 206ofdata_to_platdata() method since this is not called when platform data is 207already present. 208 209 210How to structure your driver 211---------------------------- 212 213Drivers should always support device tree as an option. The of-platdata 214feature is intended as a add-on to existing drivers. 215 216Your driver should convert the platdata struct in its probe() method. The 217existing device tree decoding logic should be kept in the 218ofdata_to_platdata() method and wrapped with #if. 219 220For example: 221 222.. code-block:: c 223 224 #include <dt-structs.h> 225 226 struct mmc_platdata { 227 #if CONFIG_IS_ENABLED(OF_PLATDATA) 228 /* Put this first since driver model will copy the data here */ 229 struct dtd_mmc dtplat; 230 #endif 231 /* 232 * Other fields can go here, to be filled in by decoding from 233 * the device tree (or the C structures when of-platdata is used). 234 */ 235 int fifo_depth; 236 }; 237 238 static int mmc_ofdata_to_platdata(struct udevice *dev) 239 { 240 #if !CONFIG_IS_ENABLED(OF_PLATDATA) 241 /* Decode the device tree data */ 242 struct mmc_platdata *plat = dev_get_platdata(dev); 243 const void *blob = gd->fdt_blob; 244 int node = dev_of_offset(dev); 245 246 plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0); 247 #endif 248 249 return 0; 250 } 251 252 static int mmc_probe(struct udevice *dev) 253 { 254 struct mmc_platdata *plat = dev_get_platdata(dev); 255 256 #if CONFIG_IS_ENABLED(OF_PLATDATA) 257 /* Decode the of-platdata from the C structures */ 258 struct dtd_mmc *dtplat = &plat->dtplat; 259 260 plat->fifo_depth = dtplat->fifo_depth; 261 #endif 262 /* Set up the device from the plat data */ 263 writel(plat->fifo_depth, ...) 264 } 265 266 static const struct udevice_id mmc_ids[] = { 267 { .compatible = "vendor,mmc" }, 268 { } 269 }; 270 271 U_BOOT_DRIVER(mmc_drv) = { 272 .name = "vendor_mmc", /* matches compatible string */ 273 .id = UCLASS_MMC, 274 .of_match = mmc_ids, 275 .ofdata_to_platdata = mmc_ofdata_to_platdata, 276 .probe = mmc_probe, 277 .priv_auto_alloc_size = sizeof(struct mmc_priv), 278 .platdata_auto_alloc_size = sizeof(struct mmc_platdata), 279 }; 280 281 282In the case where SPL_OF_PLATDATA is enabled, platdata_auto_alloc_size is 283still used to allocate space for the platform data. This is different from 284the normal behaviour and is triggered by the use of of-platdata (strictly 285speaking it is a non-zero platdata_size which triggers this). 286 287The of-platdata struct contents is copied from the C structure data to the 288start of the newly allocated area. In the case where device tree is used, 289the platform data is allocated, and starts zeroed. In this case the 290ofdata_to_platdata() method should still set up the platform data (and the 291of-platdata struct will not be present). 292 293SPL must use either of-platdata or device tree. Drivers cannot use both at 294the same time, but they must support device tree. Supporting of-platdata is 295optional. 296 297The device tree becomes in accessible when CONFIG_SPL_OF_PLATDATA is enabled, 298since the device-tree access code is not compiled in. A corollary is that 299a board can only move to using of-platdata if all the drivers it uses support 300it. There would be little point in having some drivers require the device 301tree data, since then libfdt would still be needed for those drivers and 302there would be no code-size benefit. 303 304Internals 305--------- 306 307The dt-structs.h file includes the generated file 308(include/generated//dt-structs.h) if CONFIG_SPL_OF_PLATDATA is enabled. 309Otherwise (such as in U-Boot proper) these structs are not available. This 310prevents them being used inadvertently. All usage must be bracketed with 311#if CONFIG_IS_ENABLED(OF_PLATDATA). 312 313The dt-platdata.c file contains the device declarations and is is built in 314spl/dt-platdata.c. 315 316The beginnings of a libfdt Python module are provided. So far this only 317implements a subset of the features. 318 319The 'swig' tool is needed to build the libfdt Python module. If this is not 320found then the Python model is not used and a fallback is used instead, which 321makes use of fdtget. 322 323 324Credits 325------- 326 327This is an implementation of an idea by Tom Rini <trini@konsulko.com>. 328 329 330Future work 331----------- 332- Consider programmatically reading binding files instead of device tree 333 contents 334- Complete the phandle feature 335- Move to using a full Python libfdt module 336 337 338.. Simon Glass <sjg@chromium.org> 339.. Google, Inc 340.. 6/6/16 341.. Updated Independence Day 2016 342