README.fdt-overlays 2.7 KB

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