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