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 referencing that data in a U_BOOT_DEVICE() declaration. This 23bypasses the use of device tree completely, but is an available option for 24SPL. 25 26As an alternative, a new 'of-platdata' feature is provided. This converts 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 31 32Caveats 33------- 34 35There are many problems with this features. It should only be used when 36stricly necessary. Notable problems include: 37 38 - Device tree does not describe data types but the C code must define a 39 type for each property. Thesee are guessed using heuristics which 40 are wrong in several fairly common cases. For example an 8-byte value 41 is considered to be a 2-item integer array, and is byte-swapped. A 42 boolean value that is not present means 'false', but cannot be 43 included in the structures since there is generally no mention of it 44 in the device tree file. 45 46 - Naming of nodes and properties is automatic. This means that they follow 47 the naming in the device tree, which may result in C identifiers that 48 look a bit strange 49 50 - It is not possible to find a value given a property name. Code must use 51 the associated C member variable directly in the code. This makes 52 the code less robust in the face of device-tree changes. It also 53 makes it very unlikely that your driver code will be useful for more 54 than one SoC. Even if the code is common, each SoC will end up with 55 a different C struct and format for the platform data. 56 57 - The platform data is provided to drivers as a C structure. The driver 58 must use the same structure to access the data. Since a driver 59 normally also supports device tree it must use #ifdef to separate 60 out this code, since the structures are only available in SPL. 61 62 63How it works 64------------ 65 66The feature is enabled by CONFIG SPL_OF_PLATDATA. This is only available 67in SPL and should be tested with: 68 69 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA) 70 71A new tool called 'dtoc' converts a device tree file either into a set of 72struct declarations, one for each compatible node, or a set of 73U_BOOT_DEVICE() declarations along with the actual platform data for each 74device. As an example, consider this MMC node: 75 76 sdmmc: dwmmc@ff0c0000 { 77 compatible = "rockchip,rk3288-dw-mshc"; 78 clock-freq-min-max = <400000 150000000>; 79 clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>, 80 <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>; 81 clock-names = "biu", "ciu", "ciu_drv", "ciu_sample"; 82 fifo-depth = <0x100>; 83 interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; 84 reg = <0xff0c0000 0x4000>; 85 bus-width = <4>; 86 cap-mmc-highspeed; 87 cap-sd-highspeed; 88 card-detect-delay = <200>; 89 disable-wp; 90 num-slots = <1>; 91 pinctrl-names = "default"; 92 pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>; 93 vmmc-supply = <&vcc_sd>; 94 status = "okay"; 95 u-boot,dm-pre-reloc; 96 }; 97 98 99Some of these properties are dropped by U-Boot under control of the 100CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce 101the following C struct declaration: 102 103struct dtd_rockchip_rk3288_dw_mshc { 104 fdt32_t bus_width; 105 bool cap_mmc_highspeed; 106 bool cap_sd_highspeed; 107 fdt32_t card_detect_delay; 108 fdt32_t clock_freq_min_max[2]; 109 struct phandle_2_cell clocks[4]; 110 bool disable_wp; 111 fdt32_t fifo_depth; 112 fdt32_t interrupts[3]; 113 fdt32_t num_slots; 114 fdt32_t reg[2]; 115 bool u_boot_dm_pre_reloc; 116 fdt32_t vmmc_supply; 117}; 118 119and the following device declaration: 120 121static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = { 122 .fifo_depth = 0x100, 123 .cap_sd_highspeed = true, 124 .interrupts = {0x0, 0x20, 0x4}, 125 .clock_freq_min_max = {0x61a80, 0x8f0d180}, 126 .vmmc_supply = 0xb, 127 .num_slots = 0x1, 128 .clocks = {{&dtv_clock_controller_at_ff760000, 456}, {&dtv_clock_controller_at_ff760000, 68}, {&dtv_clock_controller_at_ff760000, 114}, {&dtv_clock_controller_at_ff760000, 118}}, 129 .cap_mmc_highspeed = true, 130 .disable_wp = true, 131 .bus_width = 0x4, 132 .u_boot_dm_pre_reloc = true, 133 .reg = {0xff0c0000, 0x4000}, 134 .card_detect_delay = 0xc8, 135}; 136U_BOOT_DEVICE(dwmmc_at_ff0c0000) = { 137 .name = "rockchip_rk3288_dw_mshc", 138 .platdata = &dtv_dwmmc_at_ff0c0000, 139}; 140 141The device is then instantiated at run-time and the platform data can be 142accessed using: 143 144 struct udevice *dev; 145 struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_platdata(dev); 146 147This avoids the code overhead of converting the device tree data to 148platform data in the driver. The ofdata_to_platdata() method should 149therefore do nothing in such a driver. 150 151 152How to structure your driver 153---------------------------- 154 155Drivers should always support device tree as an option. The of-platdata 156feature is intended as a add-on to existing drivers. 157 158Your driver should directly access the platdata struct in its probe() 159method. The existing device tree decoding logic should be kept in the 160ofdata_to_platdata() and wrapped with #ifdef. 161 162For example: 163 164 #include <dt-structs.h> 165 166 struct mmc_platdata { 167 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA) 168 /* Put this first */ 169 struct dtd_mmc dtplat; 170 #endif 171 /* 172 * Other fields can go here, to be filled in by decoding from 173 * the device tree. They will point to random memory in the 174 * of-plat case. 175 */ 176 int fifo_depth; 177 }; 178 179 static int mmc_ofdata_to_platdata(struct udevice *dev) 180 { 181 #if !CONFIG_IS_ENABLED(SPL_OF_PLATDATA) 182 struct mmc_platdata *plat = dev_get_platdata(dev); 183 const void *blob = gd->fdt_blob; 184 int node = dev->of_offset; 185 186 plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0); 187 #endif 188 189 return 0; 190 } 191 192 static int mmc_probe(struct udevice *dev) 193 { 194 struct mmc_platdata *plat = dev_get_platdata(dev); 195 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA) 196 struct dtd_mmc *dtplat = &plat->dtplat; 197 198 /* Set up the device from the dtplat data */ 199 writel(dtplat->fifo_depth, ...) 200 #else 201 /* Set up the device from the plat data */ 202 writel(plat->fifo_depth, ...) 203 #endif 204 } 205 206 static const struct udevice_id mmc_ids[] = { 207 { .compatible = "vendor,mmc" }, 208 { } 209 }; 210 211 U_BOOT_DRIVER(mmc_drv) = { 212 .name = "mmc", 213 .id = UCLASS_MMC, 214 .of_match = mmc_ids, 215 .ofdata_to_platdata = mmc_ofdata_to_platdata, 216 .probe = mmc_probe, 217 .priv_auto_alloc_size = sizeof(struct mmc_priv), 218 .platdata_auto_alloc_size = sizeof(struct mmc_platdata), 219 }; 220 221 222In the case where SPL_OF_PLATDATA is enabled, platdata_auto_alloc_size is 223ignored, and the platform data points to the C structure data. In the case 224where device tree is used, the platform data is allocated, and starts 225zeroed. In this case the ofdata_to_platdata() method should set up the 226platform data. 227 228SPL must use either of-platdata or device tree. Drivers cannot use both. 229The device tree becomes in accessible when CONFIG_SPL_OF_PLATDATA is enabled, 230since the device-tree access code is not compiled in. 231 232 233Internals 234--------- 235 236The dt-structs.h file includes the generated file 237(include/generated//dt-structs.h) if CONFIG_SPL_OF_PLATDATA is enabled. 238Otherwise (such as in U-Boot proper) these structs are not available. This 239prevents them being used inadvertently. 240 241The dt-platdata.c file contains the device declarations and is is built in 242spl/dt-platdata.c. 243 244Some phandles (thsoe that are recognised as such) are converted into 245points to platform data. This pointer can potentially be used to access the 246referenced device (by searching for the pointer value). This feature is not 247yet implemented, however. 248 249The beginnings of a libfdt Python module are provided. So far this only 250implements a subset of the features. 251 252The 'swig' tool is needed to build the libfdt Python module. 253 254 255Future work 256----------- 257- Add unit tests 258- Add a sandbox_spl functional test 259- Consider programmatically reading binding files instead of device tree 260 contents 261- Drop the device tree data from the SPL image 262- Complete the phandle feature 263- Get this running on a Rockchip board 264- Move to using a full Python libfdt module 265 266-- 267Simon Glass <sjg@chromium.org> 2686/6/16 269