1 Driver Model Compiled-in Device Tree / Platform Data 2 ==================================================== 3 4 5 Introduction 6 ------------ 7 8 Device tree is the standard configuration method in U-Boot. It is used to 9 define what devices are in the system and provide configuration information 10 to these devices. 11 12 The overhead of adding device tree access to U-Boot is fairly modest, 13 approximately 3KB on Thumb 2 (plus the size of the DT itself). This means 14 that in most cases it is best to use device tree for configuration. 15 16 However there are some very constrained environments where U-Boot needs to 17 work. These include SPL with severe memory limitations. For example, some 18 SoCs require a 16KB SPL image which must include a full MMC stack. In this 19 case the overhead of device tree access may be too great. 20 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 23 bypasses the use of device tree completely, effectively creating a parallel 24 configuration mechanism. But it is an available option for SPL. 25 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. 28 This saves the 3KB of code overhead and perhaps a few hundred more bytes due 29 to more efficient storage of the data. 30 31 Note: Quite a bit of thought has gone into the design of this feature. 32 However it still has many rough edges and comments and suggestions are 33 strongly encouraged! Quite possibly there is a much better approach. 34 35 36 Caveats 37 ------- 38 39 There are many problems with this features. It should only be used when 40 strictly 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 68 How it works 69 ------------ 70 71 The feature is enabled by CONFIG SPL_OF_PLATDATA. This is only available 72 in SPL and should be tested with: 73 74 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA) 75 76 A new tool called 'dtoc' converts a device tree file either into a set of 77 struct declarations, one for each compatible node, or a set of 78 U_BOOT_DEVICE() declarations along with the actual platform data for each 79 device. As an example, consider this MMC node: 80 81 sdmmc: dwmmc@ff0c0000 { 82 compatible = "rockchip,rk3288-dw-mshc"; 83 clock-freq-min-max = <400000 150000000>; 84 clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>, 85 <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>; 86 clock-names = "biu", "ciu", "ciu_drv", "ciu_sample"; 87 fifo-depth = <0x100>; 88 interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; 89 reg = <0xff0c0000 0x4000>; 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>; 99 status = "okay"; 100 u-boot,dm-pre-reloc; 101 }; 102 103 104 Some of these properties are dropped by U-Boot under control of the 105 CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce 106 the following C struct declaration: 107 108 struct dtd_rockchip_rk3288_dw_mshc { 109 fdt32_t bus_width; 110 bool cap_mmc_highspeed; 111 bool cap_sd_highspeed; 112 fdt32_t card_detect_delay; 113 fdt32_t clock_freq_min_max[2]; 114 struct phandle_1_arg clocks[4]; 115 bool disable_wp; 116 fdt32_t fifo_depth; 117 fdt32_t interrupts[3]; 118 fdt32_t num_slots; 119 fdt32_t reg[2]; 120 fdt32_t vmmc_supply; 121 }; 122 123 and the following device declaration: 124 125 static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = { 126 .fifo_depth = 0x100, 127 .cap_sd_highspeed = true, 128 .interrupts = {0x0, 0x20, 0x4}, 129 .clock_freq_min_max = {0x61a80, 0x8f0d180}, 130 .vmmc_supply = 0xb, 131 .num_slots = 0x1, 132 .clocks = {{&dtv_clock_controller_at_ff760000, 456}, 133 {&dtv_clock_controller_at_ff760000, 68}, 134 {&dtv_clock_controller_at_ff760000, 114}, 135 {&dtv_clock_controller_at_ff760000, 118}}, 136 .cap_mmc_highspeed = true, 137 .disable_wp = true, 138 .bus_width = 0x4, 139 .u_boot_dm_pre_reloc = true, 140 .reg = {0xff0c0000, 0x4000}, 141 .card_detect_delay = 0xc8, 142 }; 143 U_BOOT_DEVICE(dwmmc_at_ff0c0000) = { 144 .name = "rockchip_rk3288_dw_mshc", 145 .platdata = &dtv_dwmmc_at_ff0c0000, 146 .platdata_size = sizeof(dtv_dwmmc_at_ff0c0000), 147 }; 148 149 The device is then instantiated at run-time and the platform data can be 150 accessed using: 151 152 struct udevice *dev; 153 struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_platdata(dev); 154 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 157 therefore do nothing in such a driver. 158 159 Where a node has multiple compatible strings, a #define is used to make them 160 equivalent, e.g.: 161 162 #define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc 163 164 165 Converting of-platdata to a useful form 166 --------------------------------------- 167 168 Of course it would be possible use the of-platdata directly in your driver 169 whenever configuration information is required. However this meands that the 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 173 all the limitations metioned in caveats above. 174 175 Therefore it is recommended that the of-platdata structure should be used 176 only in the probe() method of your driver. It cannot be used in the 177 ofdata_to_platdata() method since this is not called when platform data is 178 already present. 179 180 181 How to structure your driver 182 ---------------------------- 183 184 Drivers should always support device tree as an option. The of-platdata 185 feature is intended as a add-on to existing drivers. 186 187 Your driver should convert the platdata struct in its probe() method. The 188 existing device tree decoding logic should be kept in the 189 ofdata_to_platdata() method and wrapped with #if. 190 191 For example: 192 193 #include <dt-structs.h> 194 195 struct mmc_platdata { 196 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA) 197 /* Put this first since driver model will copy the data here */ 198 struct dtd_mmc dtplat; 199 #endif 200 /* 201 * Other fields can go here, to be filled in by decoding from 202 * the device tree (or the C structures when of-platdata is used). 203 */ 204 int fifo_depth; 205 }; 206 207 static int mmc_ofdata_to_platdata(struct udevice *dev) 208 { 209 #if !CONFIG_IS_ENABLED(SPL_OF_PLATDATA) 210 /* Decode the device tree data */ 211 struct mmc_platdata *plat = dev_get_platdata(dev); 212 const void *blob = gd->fdt_blob; 213 int node = dev_of_offset(dev); 214 215 plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0); 216 #endif 217 218 return 0; 219 } 220 221 static int mmc_probe(struct udevice *dev) 222 { 223 struct mmc_platdata *plat = dev_get_platdata(dev); 224 225 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA) 226 /* Decode the of-platdata from the C structures */ 227 struct dtd_mmc *dtplat = &plat->dtplat; 228 229 plat->fifo_depth = dtplat->fifo_depth; 230 #endif 231 /* Set up the device from the plat data */ 232 writel(plat->fifo_depth, ...) 233 } 234 235 static const struct udevice_id mmc_ids[] = { 236 { .compatible = "vendor,mmc" }, 237 { } 238 }; 239 240 U_BOOT_DRIVER(mmc_drv) = { 241 .name = "mmc", 242 .id = UCLASS_MMC, 243 .of_match = mmc_ids, 244 .ofdata_to_platdata = mmc_ofdata_to_platdata, 245 .probe = mmc_probe, 246 .priv_auto_alloc_size = sizeof(struct mmc_priv), 247 .platdata_auto_alloc_size = sizeof(struct mmc_platdata), 248 }; 249 250 251 In the case where SPL_OF_PLATDATA is enabled, platdata_auto_alloc_size is 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). 255 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, 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). 261 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 264 optional. 265 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. 272 273 Internals 274 --------- 275 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 279 prevents them being used inadvertently. All usage must be bracketed with 280 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA). 281 282 The dt-platdata.c file contains the device declarations and is is built in 283 spl/dt-platdata.c. 284 285 Some phandles (thsoe that are recognised as such) are converted into 286 points to platform data. This pointer can potentially be used to access the 287 referenced device (by searching for the pointer value). This feature is not 288 yet implemented, however. 289 290 The beginnings of a libfdt Python module are provided. So far this only 291 implements a subset of the features. 292 293 The 'swig' tool is needed to build the libfdt Python module. If this is not 294 found then the Python model is not used and a fallback is used instead, which 295 makes use of fdtget. 296 297 298 Credits 299 ------- 300 301 This is an implementation of an idea by Tom Rini <trini (a] konsulko.com>. 302 303 304 Future work 305 ----------- 306 - Consider programmatically reading binding files instead of device tree 307 contents 308 - Complete the phandle feature 309 - Move to using a full Python libfdt module 310 311 -- 312 Simon Glass <sjg (a] chromium.org> 313 Google, Inc 314 6/6/16 315 Updated Independence Day 2016 316
