Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 1 | .. SPDX-License-Identifier: GPL-2.0+ |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 2 | |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 3 | Compiled-in Device Tree / Platform Data |
| 4 | ======================================= |
| 5 | |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 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 |
Simon Glass | 1d8364a | 2020-12-28 20:34:54 -0700 | [diff] [blame] | 24 | for it, and reference that data in a U_BOOT_DRVINFO() declaration. This |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 25 | bypasses the use of device tree completely, effectively creating a parallel |
| 26 | configuration mechanism. But it is an available option for SPL. |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 27 | |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 28 | As an alternative, a new 'of-platdata' feature is provided. This converts the |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 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 | |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 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 | |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 37 | |
| 38 | Caveats |
| 39 | ------- |
| 40 | |
| 41 | There are many problems with this features. It should only be used when |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 42 | strictly necessary. Notable problems include: |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 43 | |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 44 | - Device tree does not describe data types. But the C code must define a |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 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. |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 51 | |
| 52 | - Naming of nodes and properties is automatic. This means that they follow |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 53 | the naming in the device tree, which may result in C identifiers that |
| 54 | look a bit strange. |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 55 | |
| 56 | - It is not possible to find a value given a property name. Code must use |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 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. |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 63 | |
| 64 | - The platform data is provided to drivers as a C structure. The driver |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 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. |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 68 | |
| 69 | |
| 70 | How it works |
| 71 | ------------ |
| 72 | |
Simon Goldschmidt | 49ce8ca | 2019-01-16 20:40:18 +0100 | [diff] [blame] | 73 | The feature is enabled by CONFIG OF_PLATDATA. This is only available in |
| 74 | SPL/TPL and should be tested with: |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 75 | |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 76 | .. code-block:: c |
| 77 | |
| 78 | #if CONFIG_IS_ENABLED(OF_PLATDATA) |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 79 | |
| 80 | A new tool called 'dtoc' converts a device tree file either into a set of |
Simon Goldschmidt | 49ce8ca | 2019-01-16 20:40:18 +0100 | [diff] [blame] | 81 | struct declarations, one for each compatible node, and a set of |
Simon Glass | 1d8364a | 2020-12-28 20:34:54 -0700 | [diff] [blame] | 82 | U_BOOT_DRVINFO() declarations along with the actual platform data for each |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 83 | device. As an example, consider this MMC node: |
| 84 | |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 85 | .. code-block:: none |
| 86 | |
| 87 | sdmmc: dwmmc@ff0c0000 { |
| 88 | compatible = "rockchip,rk3288-dw-mshc"; |
| 89 | clock-freq-min-max = <400000 150000000>; |
| 90 | clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>, |
| 91 | <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>; |
| 92 | clock-names = "biu", "ciu", "ciu_drv", "ciu_sample"; |
| 93 | fifo-depth = <0x100>; |
| 94 | interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; |
| 95 | reg = <0xff0c0000 0x4000>; |
| 96 | bus-width = <4>; |
| 97 | cap-mmc-highspeed; |
| 98 | cap-sd-highspeed; |
| 99 | card-detect-delay = <200>; |
| 100 | disable-wp; |
| 101 | num-slots = <1>; |
| 102 | pinctrl-names = "default"; |
| 103 | pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>; |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 104 | vmmc-supply = <&vcc_sd>; |
| 105 | status = "okay"; |
| 106 | u-boot,dm-pre-reloc; |
| 107 | }; |
| 108 | |
| 109 | |
| 110 | Some of these properties are dropped by U-Boot under control of the |
| 111 | CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce |
| 112 | the following C struct declaration: |
| 113 | |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 114 | .. code-block:: c |
| 115 | |
| 116 | struct dtd_rockchip_rk3288_dw_mshc { |
| 117 | fdt32_t bus_width; |
| 118 | bool cap_mmc_highspeed; |
| 119 | bool cap_sd_highspeed; |
| 120 | fdt32_t card_detect_delay; |
| 121 | fdt32_t clock_freq_min_max[2]; |
| 122 | struct phandle_1_arg clocks[4]; |
| 123 | bool disable_wp; |
| 124 | fdt32_t fifo_depth; |
| 125 | fdt32_t interrupts[3]; |
| 126 | fdt32_t num_slots; |
| 127 | fdt32_t reg[2]; |
| 128 | fdt32_t vmmc_supply; |
| 129 | }; |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 130 | |
Simon Glass | a772946 | 2020-10-03 11:31:42 -0600 | [diff] [blame] | 131 | and the following device declarations: |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 132 | |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 133 | .. code-block:: c |
| 134 | |
Simon Glass | a772946 | 2020-10-03 11:31:42 -0600 | [diff] [blame] | 135 | /* Node /clock-controller@ff760000 index 0 */ |
| 136 | ... |
| 137 | |
| 138 | /* Node /dwmmc@ff0c0000 index 2 */ |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 139 | static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = { |
| 140 | .fifo_depth = 0x100, |
| 141 | .cap_sd_highspeed = true, |
| 142 | .interrupts = {0x0, 0x20, 0x4}, |
| 143 | .clock_freq_min_max = {0x61a80, 0x8f0d180}, |
| 144 | .vmmc_supply = 0xb, |
| 145 | .num_slots = 0x1, |
Simon Glass | a772946 | 2020-10-03 11:31:42 -0600 | [diff] [blame] | 146 | .clocks = {{0, 456}, |
| 147 | {0, 68}, |
| 148 | {0, 114}, |
| 149 | {0, 118}}, |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 150 | .cap_mmc_highspeed = true, |
| 151 | .disable_wp = true, |
| 152 | .bus_width = 0x4, |
| 153 | .u_boot_dm_pre_reloc = true, |
| 154 | .reg = {0xff0c0000, 0x4000}, |
| 155 | .card_detect_delay = 0xc8, |
| 156 | }; |
| 157 | |
Simon Glass | 1d8364a | 2020-12-28 20:34:54 -0700 | [diff] [blame] | 158 | U_BOOT_DRVINFO(dwmmc_at_ff0c0000) = { |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 159 | .name = "rockchip_rk3288_dw_mshc", |
Simon Glass | 71fa5b4 | 2020-12-03 16:55:18 -0700 | [diff] [blame] | 160 | .plat = &dtv_dwmmc_at_ff0c0000, |
| 161 | .plat_size = sizeof(dtv_dwmmc_at_ff0c0000), |
Simon Glass | a772946 | 2020-10-03 11:31:42 -0600 | [diff] [blame] | 162 | .parent_idx = -1, |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 163 | }; |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 164 | |
| 165 | The device is then instantiated at run-time and the platform data can be |
| 166 | accessed using: |
| 167 | |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 168 | .. code-block:: c |
| 169 | |
| 170 | struct udevice *dev; |
Simon Glass | fa20e93 | 2020-12-03 16:55:20 -0700 | [diff] [blame] | 171 | struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_plat(dev); |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 172 | |
| 173 | This avoids the code overhead of converting the device tree data to |
Simon Glass | aad29ae | 2020-12-03 16:55:21 -0700 | [diff] [blame] | 174 | platform data in the driver. The of_to_plat() method should |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 175 | therefore do nothing in such a driver. |
| 176 | |
Simon Goldschmidt | 49ce8ca | 2019-01-16 20:40:18 +0100 | [diff] [blame] | 177 | Note that for the platform data to be matched with a driver, the 'name' |
Simon Glass | 1d8364a | 2020-12-28 20:34:54 -0700 | [diff] [blame] | 178 | property of the U_BOOT_DRVINFO() declaration has to match a driver declared |
Simon Goldschmidt | 49ce8ca | 2019-01-16 20:40:18 +0100 | [diff] [blame] | 179 | via U_BOOT_DRIVER(). This effectively means that a U_BOOT_DRIVER() with a |
| 180 | 'name' corresponding to the devicetree 'compatible' string (after converting |
| 181 | it to a valid name for C) is needed, so a dedicated driver is required for |
| 182 | each 'compatible' string. |
| 183 | |
Simon Glass | df65db8 | 2020-12-28 20:34:57 -0700 | [diff] [blame] | 184 | In order to make this a bit more flexible DM_DRIVER_ALIAS macro can be |
Walter Lozano | c38b491 | 2020-06-25 01:10:09 -0300 | [diff] [blame] | 185 | used to declare an alias for a driver name, typically a 'compatible' string. |
Simon Glass | 2f4455f | 2021-02-03 06:01:05 -0700 | [diff] [blame^] | 186 | This macro produces no code, but it is by dtoc tool. It must be located in the |
| 187 | same file as its associated driver, ideally just after it. |
Walter Lozano | c38b491 | 2020-06-25 01:10:09 -0300 | [diff] [blame] | 188 | |
Simon Glass | a772946 | 2020-10-03 11:31:42 -0600 | [diff] [blame] | 189 | The parent_idx is the index of the parent driver_info structure within its |
Simon Glass | 1d8364a | 2020-12-28 20:34:54 -0700 | [diff] [blame] | 190 | linker list (instantiated by the U_BOOT_DRVINFO() macro). This is used to support |
Simon Glass | 2500de2 | 2020-12-28 20:35:05 -0700 | [diff] [blame] | 191 | dev_get_parent(). |
Simon Glass | a772946 | 2020-10-03 11:31:42 -0600 | [diff] [blame] | 192 | |
Simon Glass | df65db8 | 2020-12-28 20:34:57 -0700 | [diff] [blame] | 193 | During the build process dtoc parses both U_BOOT_DRIVER and DM_DRIVER_ALIAS |
Walter Lozano | c38b491 | 2020-06-25 01:10:09 -0300 | [diff] [blame] | 194 | to build a list of valid driver names and driver aliases. If the 'compatible' |
| 195 | string used for a device does not not match a valid driver name, it will be |
| 196 | checked against the list of driver aliases in order to get the right driver |
| 197 | name to use. If in this step there is no match found a warning is issued to |
| 198 | avoid run-time failures. |
| 199 | |
Simon Glass | 934be0b | 2017-06-13 21:10:06 -0600 | [diff] [blame] | 200 | Where a node has multiple compatible strings, a #define is used to make them |
| 201 | equivalent, e.g.: |
| 202 | |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 203 | .. code-block:: c |
Simon Glass | 934be0b | 2017-06-13 21:10:06 -0600 | [diff] [blame] | 204 | |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 205 | #define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc |
| 206 | |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 207 | |
| 208 | Converting of-platdata to a useful form |
| 209 | --------------------------------------- |
| 210 | |
Simon Goldschmidt | 49ce8ca | 2019-01-16 20:40:18 +0100 | [diff] [blame] | 211 | Of course it would be possible to use the of-platdata directly in your driver |
| 212 | whenever configuration information is required. However this means that the |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 213 | driver will not be able to support device tree, since the of-platdata |
| 214 | structure is not available when device tree is used. It would make no sense |
| 215 | to use this structure if device tree were available, since the structure has |
| 216 | all the limitations metioned in caveats above. |
| 217 | |
| 218 | Therefore it is recommended that the of-platdata structure should be used |
| 219 | only in the probe() method of your driver. It cannot be used in the |
Simon Glass | aad29ae | 2020-12-03 16:55:21 -0700 | [diff] [blame] | 220 | of_to_plat() method since this is not called when platform data is |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 221 | already present. |
| 222 | |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 223 | |
| 224 | How to structure your driver |
| 225 | ---------------------------- |
| 226 | |
| 227 | Drivers should always support device tree as an option. The of-platdata |
| 228 | feature is intended as a add-on to existing drivers. |
| 229 | |
Simon Glass | 71fa5b4 | 2020-12-03 16:55:18 -0700 | [diff] [blame] | 230 | Your driver should convert the plat struct in its probe() method. The |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 231 | existing device tree decoding logic should be kept in the |
Simon Glass | aad29ae | 2020-12-03 16:55:21 -0700 | [diff] [blame] | 232 | of_to_plat() method and wrapped with #if. |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 233 | |
| 234 | For example: |
| 235 | |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 236 | .. code-block:: c |
| 237 | |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 238 | #include <dt-structs.h> |
| 239 | |
Simon Glass | b75b15b | 2020-12-03 16:55:23 -0700 | [diff] [blame] | 240 | struct mmc_plat { |
Lukasz Majewski | fd54ab2 | 2019-09-03 15:43:19 +0200 | [diff] [blame] | 241 | #if CONFIG_IS_ENABLED(OF_PLATDATA) |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 242 | /* Put this first since driver model will copy the data here */ |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 243 | struct dtd_mmc dtplat; |
| 244 | #endif |
| 245 | /* |
| 246 | * Other fields can go here, to be filled in by decoding from |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 247 | * the device tree (or the C structures when of-platdata is used). |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 248 | */ |
| 249 | int fifo_depth; |
| 250 | }; |
| 251 | |
Simon Glass | aad29ae | 2020-12-03 16:55:21 -0700 | [diff] [blame] | 252 | static int mmc_of_to_plat(struct udevice *dev) |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 253 | { |
Lukasz Majewski | fd54ab2 | 2019-09-03 15:43:19 +0200 | [diff] [blame] | 254 | #if !CONFIG_IS_ENABLED(OF_PLATDATA) |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 255 | /* Decode the device tree data */ |
Simon Glass | b75b15b | 2020-12-03 16:55:23 -0700 | [diff] [blame] | 256 | struct mmc_plat *plat = dev_get_plat(dev); |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 257 | const void *blob = gd->fdt_blob; |
Simon Glass | dd79d6e | 2017-01-17 16:52:55 -0700 | [diff] [blame] | 258 | int node = dev_of_offset(dev); |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 259 | |
| 260 | plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0); |
| 261 | #endif |
| 262 | |
| 263 | return 0; |
| 264 | } |
| 265 | |
| 266 | static int mmc_probe(struct udevice *dev) |
| 267 | { |
Simon Glass | b75b15b | 2020-12-03 16:55:23 -0700 | [diff] [blame] | 268 | struct mmc_plat *plat = dev_get_plat(dev); |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 269 | |
Lukasz Majewski | fd54ab2 | 2019-09-03 15:43:19 +0200 | [diff] [blame] | 270 | #if CONFIG_IS_ENABLED(OF_PLATDATA) |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 271 | /* Decode the of-platdata from the C structures */ |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 272 | struct dtd_mmc *dtplat = &plat->dtplat; |
| 273 | |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 274 | plat->fifo_depth = dtplat->fifo_depth; |
| 275 | #endif |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 276 | /* Set up the device from the plat data */ |
| 277 | writel(plat->fifo_depth, ...) |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 278 | } |
| 279 | |
| 280 | static const struct udevice_id mmc_ids[] = { |
| 281 | { .compatible = "vendor,mmc" }, |
| 282 | { } |
| 283 | }; |
| 284 | |
| 285 | U_BOOT_DRIVER(mmc_drv) = { |
Walter Lozano | c38b491 | 2020-06-25 01:10:09 -0300 | [diff] [blame] | 286 | .name = "mmc_drv", |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 287 | .id = UCLASS_MMC, |
| 288 | .of_match = mmc_ids, |
Simon Glass | aad29ae | 2020-12-03 16:55:21 -0700 | [diff] [blame] | 289 | .of_to_plat = mmc_of_to_plat, |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 290 | .probe = mmc_probe, |
Simon Glass | 8a2b47f | 2020-12-03 16:55:17 -0700 | [diff] [blame] | 291 | .priv_auto = sizeof(struct mmc_priv), |
Simon Glass | b75b15b | 2020-12-03 16:55:23 -0700 | [diff] [blame] | 292 | .plat_auto = sizeof(struct mmc_plat), |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 293 | }; |
| 294 | |
Simon Glass | df65db8 | 2020-12-28 20:34:57 -0700 | [diff] [blame] | 295 | DM_DRIVER_ALIAS(mmc_drv, vendor_mmc) /* matches compatible string */ |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 296 | |
Simon Glass | b75b15b | 2020-12-03 16:55:23 -0700 | [diff] [blame] | 297 | Note that struct mmc_plat is defined in the C file, not in a header. This |
Simon Glass | 63c19ed | 2019-12-06 21:42:43 -0700 | [diff] [blame] | 298 | is to avoid needing to include dt-structs.h in a header file. The idea is to |
| 299 | keep the use of each of-platdata struct to the smallest possible code area. |
| 300 | There is just one driver C file for each struct, that can convert from the |
| 301 | of-platdata struct to the standard one used by the driver. |
| 302 | |
Simon Glass | 71fa5b4 | 2020-12-03 16:55:18 -0700 | [diff] [blame] | 303 | In the case where SPL_OF_PLATDATA is enabled, plat_auto is |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 304 | still used to allocate space for the platform data. This is different from |
| 305 | the normal behaviour and is triggered by the use of of-platdata (strictly |
Simon Glass | 39edb95 | 2020-12-03 16:55:19 -0700 | [diff] [blame] | 306 | speaking it is a non-zero plat_size which triggers this). |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 307 | |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 308 | The of-platdata struct contents is copied from the C structure data to the |
| 309 | start of the newly allocated area. In the case where device tree is used, |
| 310 | the platform data is allocated, and starts zeroed. In this case the |
Simon Glass | aad29ae | 2020-12-03 16:55:21 -0700 | [diff] [blame] | 311 | of_to_plat() method should still set up the platform data (and the |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 312 | of-platdata struct will not be present). |
| 313 | |
| 314 | SPL must use either of-platdata or device tree. Drivers cannot use both at |
| 315 | the same time, but they must support device tree. Supporting of-platdata is |
| 316 | optional. |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 317 | |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 318 | The device tree becomes in accessible when CONFIG_SPL_OF_PLATDATA is enabled, |
| 319 | since the device-tree access code is not compiled in. A corollary is that |
| 320 | a board can only move to using of-platdata if all the drivers it uses support |
| 321 | it. There would be little point in having some drivers require the device |
| 322 | tree data, since then libfdt would still be needed for those drivers and |
| 323 | there would be no code-size benefit. |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 324 | |
| 325 | Internals |
| 326 | --------- |
| 327 | |
| 328 | The dt-structs.h file includes the generated file |
| 329 | (include/generated//dt-structs.h) if CONFIG_SPL_OF_PLATDATA is enabled. |
| 330 | Otherwise (such as in U-Boot proper) these structs are not available. This |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 331 | prevents them being used inadvertently. All usage must be bracketed with |
Lukasz Majewski | fd54ab2 | 2019-09-03 15:43:19 +0200 | [diff] [blame] | 332 | #if CONFIG_IS_ENABLED(OF_PLATDATA). |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 333 | |
Simon Glass | 71fa5b4 | 2020-12-03 16:55:18 -0700 | [diff] [blame] | 334 | The dt-plat.c file contains the device declarations and is is built in |
Simon Glass | 2500de2 | 2020-12-28 20:35:05 -0700 | [diff] [blame] | 335 | spl/dt-plat.c. |
| 336 | |
| 337 | The dm_populate_phandle_data() function that was previous needed has now been |
| 338 | removed, since dtoc can address the drivers directly from dt-plat.c and does |
| 339 | not need to fix up things at runtime. |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 340 | |
Simon Glass | a772946 | 2020-10-03 11:31:42 -0600 | [diff] [blame] | 341 | The pylibfdt Python module is used to access the devicetree. |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 342 | |
Simon Glass | 946c723 | 2016-07-04 11:58:42 -0600 | [diff] [blame] | 343 | |
| 344 | Credits |
| 345 | ------- |
| 346 | |
| 347 | This is an implementation of an idea by Tom Rini <trini@konsulko.com>. |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 348 | |
| 349 | |
| 350 | Future work |
| 351 | ----------- |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 352 | - Consider programmatically reading binding files instead of device tree |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 353 | contents |
Simon Glass | 261ad28 | 2016-07-04 11:58:07 -0600 | [diff] [blame] | 354 | |
Bin Meng | ae25869 | 2019-07-18 00:33:55 -0700 | [diff] [blame] | 355 | |
| 356 | .. Simon Glass <sjg@chromium.org> |
| 357 | .. Google, Inc |
| 358 | .. 6/6/16 |
| 359 | .. Updated Independence Day 2016 |
Simon Glass | a772946 | 2020-10-03 11:31:42 -0600 | [diff] [blame] | 360 | .. Updated 1st October 2020 |