of-plat.rst 14 KB

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