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_DRVINFO() 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 70How it works 71------------ 72 73The feature is enabled by CONFIG OF_PLATDATA. This is only available in 74SPL/TPL and should be tested with: 75 76.. code-block:: c 77 78 #if CONFIG_IS_ENABLED(OF_PLATDATA) 79 80A new tool called 'dtoc' converts a device tree file either into a set of 81struct declarations, one for each compatible node, and a set of 82U_BOOT_DRVINFO() declarations along with the actual platform data for each 83device. As an example, consider this MMC node: 84 85.. code-block:: none 86 87 sdmmc: dwmmc@ff0c0000 { 88 compatible = "rockchip,rk3288-dw-mshc"; 89 clock-freq-min-max = <400000 150000000>; 90 clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>, 91 <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>; 92 clock-names = "biu", "ciu", "ciu_drv", "ciu_sample"; 93 fifo-depth = <0x100>; 94 interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; 95 reg = <0xff0c0000 0x4000>; 96 bus-width = <4>; 97 cap-mmc-highspeed; 98 cap-sd-highspeed; 99 card-detect-delay = <200>; 100 disable-wp; 101 num-slots = <1>; 102 pinctrl-names = "default"; 103 pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>; 104 vmmc-supply = <&vcc_sd>; 105 status = "okay"; 106 u-boot,dm-pre-reloc; 107 }; 108 109 110Some of these properties are dropped by U-Boot under control of the 111CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce 112the following C struct declaration: 113 114.. code-block:: c 115 116 struct dtd_rockchip_rk3288_dw_mshc { 117 fdt32_t bus_width; 118 bool cap_mmc_highspeed; 119 bool cap_sd_highspeed; 120 fdt32_t card_detect_delay; 121 fdt32_t clock_freq_min_max[2]; 122 struct phandle_1_arg clocks[4]; 123 bool disable_wp; 124 fdt32_t fifo_depth; 125 fdt32_t interrupts[3]; 126 fdt32_t num_slots; 127 fdt32_t reg[2]; 128 fdt32_t vmmc_supply; 129 }; 130 131and the following device declarations: 132 133.. code-block:: c 134 135 /* Node /clock-controller@ff760000 index 0 */ 136 ... 137 138 /* Node /dwmmc@ff0c0000 index 2 */ 139 static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = { 140 .fifo_depth = 0x100, 141 .cap_sd_highspeed = true, 142 .interrupts = {0x0, 0x20, 0x4}, 143 .clock_freq_min_max = {0x61a80, 0x8f0d180}, 144 .vmmc_supply = 0xb, 145 .num_slots = 0x1, 146 .clocks = {{0, 456}, 147 {0, 68}, 148 {0, 114}, 149 {0, 118}}, 150 .cap_mmc_highspeed = true, 151 .disable_wp = true, 152 .bus_width = 0x4, 153 .u_boot_dm_pre_reloc = true, 154 .reg = {0xff0c0000, 0x4000}, 155 .card_detect_delay = 0xc8, 156 }; 157 158 U_BOOT_DRVINFO(dwmmc_at_ff0c0000) = { 159 .name = "rockchip_rk3288_dw_mshc", 160 .plat = &dtv_dwmmc_at_ff0c0000, 161 .plat_size = sizeof(dtv_dwmmc_at_ff0c0000), 162 .parent_idx = -1, 163 }; 164 165The device is then instantiated at run-time and the platform data can be 166accessed using: 167 168.. code-block:: c 169 170 struct udevice *dev; 171 struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_plat(dev); 172 173This avoids the code overhead of converting the device tree data to 174platform data in the driver. The of_to_plat() method should 175therefore do nothing in such a driver. 176 177Note that for the platform data to be matched with a driver, the 'name' 178property of the U_BOOT_DRVINFO() declaration has to match a driver declared 179via U_BOOT_DRIVER(). This effectively means that a U_BOOT_DRIVER() with a 180'name' corresponding to the devicetree 'compatible' string (after converting 181it to a valid name for C) is needed, so a dedicated driver is required for 182each 'compatible' string. 183 184In order to make this a bit more flexible DM_DRIVER_ALIAS macro can be 185used to declare an alias for a driver name, typically a 'compatible' string. 186This macro produces no code, but it is by dtoc tool. 187 188The parent_idx is the index of the parent driver_info structure within its 189linker list (instantiated by the U_BOOT_DRVINFO() macro). This is used to support 190dev_get_parent(). 191 192During the build process dtoc parses both U_BOOT_DRIVER and DM_DRIVER_ALIAS 193to build a list of valid driver names and driver aliases. If the 'compatible' 194string used for a device does not not match a valid driver name, it will be 195checked against the list of driver aliases in order to get the right driver 196name to use. If in this step there is no match found a warning is issued to 197avoid run-time failures. 198 199Where a node has multiple compatible strings, a #define is used to make them 200equivalent, e.g.: 201 202.. code-block:: c 203 204 #define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc 205 206 207Converting of-platdata to a useful form 208--------------------------------------- 209 210Of course it would be possible to use the of-platdata directly in your driver 211whenever configuration information is required. However this means that the 212driver will not be able to support device tree, since the of-platdata 213structure is not available when device tree is used. It would make no sense 214to use this structure if device tree were available, since the structure has 215all the limitations metioned in caveats above. 216 217Therefore it is recommended that the of-platdata structure should be used 218only in the probe() method of your driver. It cannot be used in the 219of_to_plat() method since this is not called when platform data is 220already present. 221 222 223How to structure your driver 224---------------------------- 225 226Drivers should always support device tree as an option. The of-platdata 227feature is intended as a add-on to existing drivers. 228 229Your driver should convert the plat struct in its probe() method. The 230existing device tree decoding logic should be kept in the 231of_to_plat() method and wrapped with #if. 232 233For example: 234 235.. code-block:: c 236 237 #include <dt-structs.h> 238 239 struct mmc_plat { 240 #if CONFIG_IS_ENABLED(OF_PLATDATA) 241 /* Put this first since driver model will copy the data here */ 242 struct dtd_mmc dtplat; 243 #endif 244 /* 245 * Other fields can go here, to be filled in by decoding from 246 * the device tree (or the C structures when of-platdata is used). 247 */ 248 int fifo_depth; 249 }; 250 251 static int mmc_of_to_plat(struct udevice *dev) 252 { 253 #if !CONFIG_IS_ENABLED(OF_PLATDATA) 254 /* Decode the device tree data */ 255 struct mmc_plat *plat = dev_get_plat(dev); 256 const void *blob = gd->fdt_blob; 257 int node = dev_of_offset(dev); 258 259 plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0); 260 #endif 261 262 return 0; 263 } 264 265 static int mmc_probe(struct udevice *dev) 266 { 267 struct mmc_plat *plat = dev_get_plat(dev); 268 269 #if CONFIG_IS_ENABLED(OF_PLATDATA) 270 /* Decode the of-platdata from the C structures */ 271 struct dtd_mmc *dtplat = &plat->dtplat; 272 273 plat->fifo_depth = dtplat->fifo_depth; 274 #endif 275 /* Set up the device from the plat data */ 276 writel(plat->fifo_depth, ...) 277 } 278 279 static const struct udevice_id mmc_ids[] = { 280 { .compatible = "vendor,mmc" }, 281 { } 282 }; 283 284 U_BOOT_DRIVER(mmc_drv) = { 285 .name = "mmc_drv", 286 .id = UCLASS_MMC, 287 .of_match = mmc_ids, 288 .of_to_plat = mmc_of_to_plat, 289 .probe = mmc_probe, 290 .priv_auto = sizeof(struct mmc_priv), 291 .plat_auto = sizeof(struct mmc_plat), 292 }; 293 294 DM_DRIVER_ALIAS(mmc_drv, vendor_mmc) /* matches compatible string */ 295 296Note that struct mmc_plat is defined in the C file, not in a header. This 297is to avoid needing to include dt-structs.h in a header file. The idea is to 298keep the use of each of-platdata struct to the smallest possible code area. 299There is just one driver C file for each struct, that can convert from the 300of-platdata struct to the standard one used by the driver. 301 302In the case where SPL_OF_PLATDATA is enabled, plat_auto is 303still used to allocate space for the platform data. This is different from 304the normal behaviour and is triggered by the use of of-platdata (strictly 305speaking it is a non-zero plat_size which triggers this). 306 307The of-platdata struct contents is copied from the C structure data to the 308start of the newly allocated area. In the case where device tree is used, 309the platform data is allocated, and starts zeroed. In this case the 310of_to_plat() method should still set up the platform data (and the 311of-platdata struct will not be present). 312 313SPL must use either of-platdata or device tree. Drivers cannot use both at 314the same time, but they must support device tree. Supporting of-platdata is 315optional. 316 317The device tree becomes in accessible when CONFIG_SPL_OF_PLATDATA is enabled, 318since the device-tree access code is not compiled in. A corollary is that 319a board can only move to using of-platdata if all the drivers it uses support 320it. There would be little point in having some drivers require the device 321tree data, since then libfdt would still be needed for those drivers and 322there would be no code-size benefit. 323 324Internals 325--------- 326 327The dt-structs.h file includes the generated file 328(include/generated//dt-structs.h) if CONFIG_SPL_OF_PLATDATA is enabled. 329Otherwise (such as in U-Boot proper) these structs are not available. This 330prevents them being used inadvertently. All usage must be bracketed with 331#if CONFIG_IS_ENABLED(OF_PLATDATA). 332 333The dt-plat.c file contains the device declarations and is is built in 334spl/dt-plat.c. 335 336The dm_populate_phandle_data() function that was previous needed has now been 337removed, since dtoc can address the drivers directly from dt-plat.c and does 338not need to fix up things at runtime. 339 340The pylibfdt Python module is used to access the devicetree. 341 342 343Credits 344------- 345 346This is an implementation of an idea by Tom Rini <trini@konsulko.com>. 347 348 349Future work 350----------- 351- Consider programmatically reading binding files instead of device tree 352 contents 353 354 355.. Simon Glass <sjg@chromium.org> 356.. Google, Inc 357.. 6/6/16 358.. Updated Independence Day 2016 359.. Updated 1st October 2020 360