doc/driver-model/of-plat.txt

   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 referencing that data in a U_BOOT_DEVICE() declaration. This
  23 bypasses the use of device tree completely, but is an available option for
  24 SPL.
  25
  26 As an alternative, a new 'of-platdata' feature is provided. This converts
  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
  32 Caveats
  33 -------
  34
  35 There are many problems with this features. It should only be used when
  36 stricly 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
  63 How it works
  64 ------------
  65
  66 The feature is enabled by CONFIG SPL_OF_PLATDATA. This is only available
  67 in SPL and should be tested with:
  68
  69         #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA)
  70
  71 A new tool called 'dtoc' converts a device tree file either into a set of
  72 struct declarations, one for each compatible node, or a set of
  73 U_BOOT_DEVICE() declarations along with the actual platform data for each
  74 device. 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
  99 Some of these properties are dropped by U-Boot under control of the
 100 CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce
 101 the following C struct declaration:
 102
 103 struct 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
 119 and the following device declaration:
 120
 121 static 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 };
 136 U_BOOT_DEVICE(dwmmc_at_ff0c0000) = {
 137         .name           = "rockchip_rk3288_dw_mshc",
 138         .platdata       = &dtv_dwmmc_at_ff0c0000,
 139 };
 140
 141 The device is then instantiated at run-time and the platform data can be
 142 accessed using:
 143
 144         struct udevice *dev;
 145         struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_platdata(dev);
 146
 147 This avoids the code overhead of converting the device tree data to
 148 platform data in the driver. The ofdata_to_platdata() method should
 149 therefore do nothing in such a driver.
 150
 151
 152 How to structure your driver
 153 ----------------------------
 154
 155 Drivers should always support device tree as an option. The of-platdata
 156 feature is intended as a add-on to existing drivers.
 157
 158 Your driver should directly access the platdata struct in its probe()
 159 method. The existing device tree decoding logic should be kept in the
 160 ofdata_to_platdata() and wrapped with #ifdef.
 161
 162 For 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
 222 In the case where SPL_OF_PLATDATA is enabled, platdata_auto_alloc_size is
 223 ignored, and the platform data points to the C structure data. In the case
 224 where device tree is used, the platform data is allocated, and starts
 225 zeroed. In this case the ofdata_to_platdata() method should set up the
 226 platform data.
 227
 228 SPL must use either of-platdata or device tree. Drivers cannot use both.
 229 The device tree becomes in accessible when CONFIG_SPL_OF_PLATDATA is enabled,
 230 since the device-tree access code is not compiled in.
 231
 232
 233 Internals
 234 ---------
 235
 236 The dt-structs.h file includes the generated file
 237 (include/generated//dt-structs.h) if CONFIG_SPL_OF_PLATDATA is enabled.
 238 Otherwise (such as in U-Boot proper) these structs are not available. This
 239 prevents them being used inadvertently.
 240
 241 The dt-platdata.c file contains the device declarations and is is built in
 242 spl/dt-platdata.c.
 243
 244 Some phandles (thsoe that are recognised as such) are converted into
 245 points to platform data. This pointer can potentially be used to access the
 246 referenced device (by searching for the pointer value). This feature is not
 247 yet implemented, however.
 248
 249 The beginnings of a libfdt Python module are provided. So far this only
 250 implements a subset of the features.
 251
 252 The 'swig' tool is needed to build the libfdt Python module.
 253
 254
 255 Future 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 --
 267 Simon Glass <sjg@chromium.org>
 268 6/6/16