fdt_overlays.rst 3.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134
  1. .. SPDX-License-Identifier: GPL-2.0+
  2. .. Copyright (c) 2017, Pantelis Antoniou <pantelis.antoniou@konsulko.com>
  3. Device Tree Overlays
  4. ====================
  5. Overlay Syntax
  6. --------------
  7. Device-tree overlays require a slightly different syntax compared to traditional
  8. device-trees. Please refer to dt-object-internal.txt in the device-tree compiler
  9. sources for information regarding the internal format of overlays:
  10. https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/dt-object-internal.txt
  11. Building Overlays
  12. -----------------
  13. In a nutshell overlays provides a means to manipulate a symbol a previous
  14. device-tree or device-tree overlay has defined. It requires both the base
  15. device-tree and all the overlays to be compiled with the *-@* command line
  16. switch of the device-tree compiler so that symbol information is included.
  17. Note
  18. Support for *-@* option can only be found in dtc version 1.4.4 or newer.
  19. Only version 4.14 or higher of the Linux kernel includes a built in version
  20. of dtc that meets this requirement.
  21. Building a binary device-tree overlay follows the same process as building a
  22. traditional binary device-tree. For example:
  23. **base.dts**
  24. ::
  25. /dts-v1/;
  26. / {
  27. foo: foonode {
  28. foo-property;
  29. };
  30. };
  31. .. code-block:: console
  32. $ dtc -@ -I dts -O dtb -o base.dtb base.dts
  33. **overlay.dts**
  34. ::
  35. /dts-v1/;
  36. /plugin/;
  37. / {
  38. fragment@1 {
  39. target = <&foo>;
  40. __overlay__ {
  41. overlay-1-property;
  42. bar: barnode {
  43. bar-property;
  44. };
  45. };
  46. };
  47. };
  48. .. code-block:: console
  49. $ dtc -@ -I dts -O dtb -o overlay.dtbo overlay.dts
  50. Ways to Utilize Overlays in U-Boot
  51. ----------------------------------
  52. There are two ways to apply overlays in U-Boot.
  53. * Include and define overlays within a FIT image and have overlays
  54. automatically applied.
  55. * Manually load and apply overlays
  56. The remainder of this document will discuss using overlays via the manual
  57. approach. For information on using overlays as part of a FIT image please see:
  58. doc/uImage.FIT/overlay-fdt-boot.txt
  59. Manually Loading and Applying Overlays
  60. --------------------------------------
  61. 1. Figure out where to place both the base device tree blob and the
  62. overlay. Make sure you have enough space to grow the base tree without
  63. overlapping anything.
  64. ::
  65. => setenv fdtaddr 0x87f00000
  66. => setenv fdtovaddr 0x87fc0000
  67. 2. Load the base binary device-tree and the binary device-tree overlay.
  68. ::
  69. => load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb
  70. => load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtbo
  71. 3. Set the base binary device-tree as the working fdt tree.
  72. ::
  73. => fdtaddr $fdtaddr
  74. 4. Grow it enough so it can encompass all applied overlays
  75. ::
  76. => fdt resize 8192
  77. 5. You are now ready to apply the overlay.
  78. ::
  79. => fdt apply $fdtovaddr
  80. 6. Boot system like you would do with a traditional dtb.
  81. For bootm:
  82. ::
  83. => bootm ${kerneladdr} - ${fdtaddr}
  84. For bootz:
  85. ::
  86. => bootz ${kerneladdr} - ${fdtaddr}
  87. Please note that in case of an error, both the base and overlays are going
  88. to be invalidated, so keep copies to avoid reloading.