overlay-fdt-boot.txt 5.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225
  1. U-Boot FDT Overlay FIT usage
  2. ============================
  3. Introduction
  4. ------------
  5. In many cases it is desirable to have a single FIT image support a multitude
  6. of similar boards and their expansion options. The same kernel on DT enabled
  7. platforms can support this easily enough by providing a DT blob upon boot
  8. that matches the desired configuration.
  9. This document focuses on specifically using overlays as part of a FIT image.
  10. General information regarding overlays including its syntax and building it
  11. can be found in doc/README.fdt-overlays
  12. Configuration without overlays
  13. ------------------------------
  14. Take a hypothetical board named 'foo' where there are different supported
  15. revisions, reva and revb. Assume that both board revisions can use add a bar
  16. add-on board, while only the revb board can use a baz add-on board.
  17. Without using overlays the configuration would be as follows for every case.
  18. /dts-v1/;
  19. / {
  20. images {
  21. kernel {
  22. data = /incbin/("./zImage");
  23. type = "kernel";
  24. arch = "arm";
  25. os = "linux";
  26. load = <0x82000000>;
  27. entry = <0x82000000>;
  28. };
  29. fdt-1 {
  30. data = /incbin/("./foo-reva.dtb");
  31. type = "flat_dt";
  32. arch = "arm";
  33. };
  34. fdt-2 {
  35. data = /incbin/("./foo-revb.dtb");
  36. type = "flat_dt";
  37. arch = "arm";
  38. };
  39. fdt-3 {
  40. data = /incbin/("./foo-reva-bar.dtb");
  41. type = "flat_dt";
  42. arch = "arm";
  43. };
  44. fdt-4 {
  45. data = /incbin/("./foo-revb-bar.dtb");
  46. type = "flat_dt";
  47. arch = "arm";
  48. };
  49. fdt-5 {
  50. data = /incbin/("./foo-revb-baz.dtb");
  51. type = "flat_dt";
  52. arch = "arm";
  53. };
  54. fdt-6 {
  55. data = /incbin/("./foo-revb-bar-baz.dtb");
  56. type = "flat_dt";
  57. arch = "arm";
  58. };
  59. };
  60. configurations {
  61. default = "foo-reva.dtb;
  62. foo-reva.dtb {
  63. kernel = "kernel";
  64. fdt = "fdt-1";
  65. };
  66. foo-revb.dtb {
  67. kernel = "kernel";
  68. fdt = "fdt-2";
  69. };
  70. foo-reva-bar.dtb {
  71. kernel = "kernel";
  72. fdt = "fdt-3";
  73. };
  74. foo-revb-bar.dtb {
  75. kernel = "kernel";
  76. fdt = "fdt-4";
  77. };
  78. foo-revb-baz.dtb {
  79. kernel = "kernel";
  80. fdt = "fdt-5";
  81. };
  82. foo-revb-bar-baz.dtb {
  83. kernel = "kernel";
  84. fdt = "fdt-6";
  85. };
  86. };
  87. };
  88. Note the blob needs to be compiled for each case and the combinatorial explosion of
  89. configurations. A typical device tree blob is in the low hunderds of kbytes so a
  90. multitude of configuration grows the image quite a bit.
  91. Booting this image is done by using
  92. # bootm <addr>#<config>
  93. Where config is one of:
  94. foo-reva.dtb, foo-revb.dtb, foo-reva-bar.dtb, foo-revb-bar.dtb,
  95. foo-revb-baz.dtb, foo-revb-bar-baz.dtb
  96. This selects the DTB to use when booting.
  97. Configuration using overlays
  98. ----------------------------
  99. Device tree overlays can be applied to a base DT and result in the same blob
  100. being passed to the booting kernel. This saves on space and avoid the combinatorial
  101. explosion problem.
  102. /dts-v1/;
  103. / {
  104. images {
  105. kernel {
  106. data = /incbin/("./zImage");
  107. type = "kernel";
  108. arch = "arm";
  109. os = "linux";
  110. load = <0x82000000>;
  111. entry = <0x82000000>;
  112. };
  113. fdt-1 {
  114. data = /incbin/("./foo.dtb");
  115. type = "flat_dt";
  116. arch = "arm";
  117. load = <0x87f00000>;
  118. };
  119. fdt-2 {
  120. data = /incbin/("./reva.dtbo");
  121. type = "flat_dt";
  122. arch = "arm";
  123. load = <0x87fc0000>;
  124. };
  125. fdt-3 {
  126. data = /incbin/("./revb.dtbo");
  127. type = "flat_dt";
  128. arch = "arm";
  129. load = <0x87fc0000>;
  130. };
  131. fdt-4 {
  132. data = /incbin/("./bar.dtbo");
  133. type = "flat_dt";
  134. arch = "arm";
  135. load = <0x87fc0000>;
  136. };
  137. fdt-5 {
  138. data = /incbin/("./baz.dtbo");
  139. type = "flat_dt";
  140. arch = "arm";
  141. load = <0x87fc0000>;
  142. };
  143. };
  144. configurations {
  145. default = "foo-reva.dtb;
  146. foo-reva.dtb {
  147. kernel = "kernel";
  148. fdt = "fdt-1", "fdt-2";
  149. };
  150. foo-revb.dtb {
  151. kernel = "kernel";
  152. fdt = "fdt-1", "fdt-3";
  153. };
  154. foo-reva-bar.dtb {
  155. kernel = "kernel";
  156. fdt = "fdt-1", "fdt-2", "fdt-4";
  157. };
  158. foo-revb-bar.dtb {
  159. kernel = "kernel";
  160. fdt = "fdt-1", "fdt-3", "fdt-4";
  161. };
  162. foo-revb-baz.dtb {
  163. kernel = "kernel";
  164. fdt = "fdt-1", "fdt-3", "fdt-5";
  165. };
  166. foo-revb-bar-baz.dtb {
  167. kernel = "kernel";
  168. fdt = "fdt-1", "fdt-3", "fdt-4", "fdt-5";
  169. };
  170. bar {
  171. fdt = "fdt-4";
  172. };
  173. baz {
  174. fdt = "fdt-5";
  175. };
  176. };
  177. };
  178. Booting this image is exactly the same as the non-overlay example.
  179. u-boot will retrieve the base blob and apply the overlays in sequence as
  180. they are declared in the configuration.
  181. Note the minimum amount of different DT blobs, as well as the requirement for
  182. the DT blobs to have a load address; the overlay application requires the blobs
  183. to be writeable.
  184. Configuration using overlays and feature selection
  185. --------------------------------------------------
  186. Although the configuration in the previous section works is a bit inflexible
  187. since it requires all possible configuration options to be laid out before
  188. hand in the FIT image. For the add-on boards the extra config selection method
  189. might make sense.
  190. Note the two bar & baz configuration nodes. To boot a reva board with
  191. the bar add-on board enabled simply use:
  192. # bootm <addr>#foo-reva.dtb#bar
  193. While booting a revb with bar and baz is as follows:
  194. # bootm <addr>#foo-revb.dtb#bar#baz
  195. The limitation for a feature selection configuration node is that a single
  196. fdt option is currently supported.
  197. Pantelis Antoniou
  198. pantelis.antoniou@konsulko.com
  199. 12/6/2017