doc/driver-model/of-plat.rst

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