1Driver Model Compiled-in Device Tree / Platform Data 2==================================================== 3 4 5Introduction 6------------ 7 8Device tree is the standard configuration method in U-Boot. It is used to 9define what devices are in the system and provide configuration information 10to these devices. 11 12The overhead of adding device tree access to U-Boot is fairly modest, 13approximately 3KB on Thumb 2 (plus the size of the DT itself). This means 14that in most cases it is best to use device tree for configuration. 15 16However there are some very constrained environments where U-Boot needs to 17work. These include SPL with severe memory limitations. For example, some 18SoCs require a 16KB SPL image which must include a full MMC stack. In this 19case the overhead of device tree access may be too great. 20 21It is possible to create platform data manually by defining C structures 22for it, and reference that data in a U_BOOT_DEVICE() declaration. This 23bypasses the use of device tree completely, effectively creating a parallel 24configuration mechanism. But it is an available option for SPL. 25 26As an alternative, a new 'of-platdata' feature is provided. This converts the 27device tree contents into C code which can be compiled into the SPL binary. 28This saves the 3KB of code overhead and perhaps a few hundred more bytes due 29to more efficient storage of the data. 30 31Note: Quite a bit of thought has gone into the design of this feature. 32However it still has many rough edges and comments and suggestions are 33strongly encouraged! Quite possibly there is a much better approach. 34 35 36Caveats 37------- 38 39There are many problems with this features. It should only be used when 40strictly necessary. Notable problems include: 41 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. 49 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 52 look a bit strange. 53 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 60 platform data. 61 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. 66 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. 73 74 75How it works 76------------ 77 78The feature is enabled by CONFIG OF_PLATDATA. This is only available in 79SPL/TPL and should be tested with: 80 81 #if CONFIG_IS_ENABLED(OF_PLATDATA) 82 83A new tool called 'dtoc' converts a device tree file either into a set of 84struct declarations, one for each compatible node, and a set of 85U_BOOT_DEVICE() declarations along with the actual platform data for each 86device. As an example, consider this MMC node: 87 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"; 94 fifo-depth = <0x100>; 95 interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; 96 reg = <0xff0c0000 0x4000>; 97 bus-width = <4>; 98 cap-mmc-highspeed; 99 cap-sd-highspeed; 100 card-detect-delay = <200>; 101 disable-wp; 102 num-slots = <1>; 103 pinctrl-names = "default"; 104 pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>; 105 vmmc-supply = <&vcc_sd>; 106 status = "okay"; 107 u-boot,dm-pre-reloc; 108 }; 109 110 111Some of these properties are dropped by U-Boot under control of the 112CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce 113the following C struct declaration: 114 115struct dtd_rockchip_rk3288_dw_mshc { 116 fdt32_t bus_width; 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]; 122 bool disable_wp; 123 fdt32_t fifo_depth; 124 fdt32_t interrupts[3]; 125 fdt32_t num_slots; 126 fdt32_t reg[2]; 127 fdt32_t vmmc_supply; 128}; 129 130and the following device declaration: 131 132static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = { 133 .fifo_depth = 0x100, 134 .cap_sd_highspeed = true, 135 .interrupts = {0x0, 0x20, 0x4}, 136 .clock_freq_min_max = {0x61a80, 0x8f0d180}, 137 .vmmc_supply = 0xb, 138 .num_slots = 0x1, 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, 144 .disable_wp = true, 145 .bus_width = 0x4, 146 .u_boot_dm_pre_reloc = true, 147 .reg = {0xff0c0000, 0x4000}, 148 .card_detect_delay = 0xc8, 149}; 150U_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), 154}; 155 156The device is then instantiated at run-time and the platform data can be 157accessed using: 158 159 struct udevice *dev; 160 struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_platdata(dev); 161 162This avoids the code overhead of converting the device tree data to 163platform data in the driver. The ofdata_to_platdata() method should 164therefore do nothing in such a driver. 165 166Note that for the platform data to be matched with a driver, the 'name' 167property of the U_BOOT_DEVICE() declaration has to match a driver declared 168via U_BOOT_DRIVER(). This effectively means that a U_BOOT_DRIVER() with a 169'name' corresponding to the devicetree 'compatible' string (after converting 170it to a valid name for C) is needed, so a dedicated driver is required for 171each 'compatible' string. 172 173Where a node has multiple compatible strings, a #define is used to make them 174equivalent, e.g.: 175 176#define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc 177 178 179Converting of-platdata to a useful form 180--------------------------------------- 181 182Of course it would be possible to use the of-platdata directly in your driver 183whenever configuration information is required. However this means that the 184driver will not be able to support device tree, since the of-platdata 185structure is not available when device tree is used. It would make no sense 186to use this structure if device tree were available, since the structure has 187all the limitations metioned in caveats above. 188 189Therefore it is recommended that the of-platdata structure should be used 190only in the probe() method of your driver. It cannot be used in the 191ofdata_to_platdata() method since this is not called when platform data is 192already present. 193 194 195How to structure your driver 196---------------------------- 197 198Drivers should always support device tree as an option. The of-platdata 199feature is intended as a add-on to existing drivers. 200 201Your driver should convert the platdata struct in its probe() method. The 202existing device tree decoding logic should be kept in the 203ofdata_to_platdata() method and wrapped with #if. 204 205For example: 206 207 #include <dt-structs.h> 208 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; 213 #endif 214 /* 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). 217 */ 218 int fifo_depth; 219 }; 220 221 static int mmc_ofdata_to_platdata(struct udevice *dev) 222 { 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); 228 229 plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0); 230 #endif 231 232 return 0; 233 } 234 235 static int mmc_probe(struct udevice *dev) 236 { 237 struct mmc_platdata *plat = dev_get_platdata(dev); 238 239 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA) 240 /* Decode the of-platdata from the C structures */ 241 struct dtd_mmc *dtplat = &plat->dtplat; 242 243 plat->fifo_depth = dtplat->fifo_depth; 244 #endif 245 /* Set up the device from the plat data */ 246 writel(plat->fifo_depth, ...) 247 } 248 249 static const struct udevice_id mmc_ids[] = { 250 { .compatible = "vendor,mmc" }, 251 { } 252 }; 253 254 U_BOOT_DRIVER(mmc_drv) = { 255 .name = "mmc", 256 .id = UCLASS_MMC, 257 .of_match = mmc_ids, 258 .ofdata_to_platdata = mmc_ofdata_to_platdata, 259 .probe = mmc_probe, 260 .priv_auto_alloc_size = sizeof(struct mmc_priv), 261 .platdata_auto_alloc_size = sizeof(struct mmc_platdata), 262 }; 263 264 265In the case where SPL_OF_PLATDATA is enabled, platdata_auto_alloc_size is 266still used to allocate space for the platform data. This is different from 267the normal behaviour and is triggered by the use of of-platdata (strictly 268speaking it is a non-zero platdata_size which triggers this). 269 270The of-platdata struct contents is copied from the C structure data to the 271start of the newly allocated area. In the case where device tree is used, 272the platform data is allocated, and starts zeroed. In this case the 273ofdata_to_platdata() method should still set up the platform data (and the 274of-platdata struct will not be present). 275 276SPL must use either of-platdata or device tree. Drivers cannot use both at 277the same time, but they must support device tree. Supporting of-platdata is 278optional. 279 280The device tree becomes in accessible when CONFIG_SPL_OF_PLATDATA is enabled, 281since the device-tree access code is not compiled in. A corollary is that 282a board can only move to using of-platdata if all the drivers it uses support 283it. There would be little point in having some drivers require the device 284tree data, since then libfdt would still be needed for those drivers and 285there would be no code-size benefit. 286 287Internals 288--------- 289 290The dt-structs.h file includes the generated file 291(include/generated//dt-structs.h) if CONFIG_SPL_OF_PLATDATA is enabled. 292Otherwise (such as in U-Boot proper) these structs are not available. This 293prevents them being used inadvertently. All usage must be bracketed with 294#if CONFIG_IS_ENABLED(SPL_OF_PLATDATA). 295 296The dt-platdata.c file contains the device declarations and is is built in 297spl/dt-platdata.c. 298 299The beginnings of a libfdt Python module are provided. So far this only 300implements a subset of the features. 301 302The 'swig' tool is needed to build the libfdt Python module. If this is not 303found then the Python model is not used and a fallback is used instead, which 304makes use of fdtget. 305 306 307Credits 308------- 309 310This is an implementation of an idea by Tom Rini <trini@konsulko.com>. 311 312 313Future work 314----------- 315- Consider programmatically reading binding files instead of device tree 316 contents 317- Complete the phandle feature 318- Move to using a full Python libfdt module 319 320-- 321Simon Glass <sjg@chromium.org> 322Google, Inc 3236/6/16 324Updated Independence Day 2016 325