1U-Boot FDT Overlay usage 2============================================= 3 4Overlays Syntax 5--------------- 6 7Overlays require slightly different syntax compared to traditional overlays. 8Please refer to dt-object-internal.txt in the dtc sources for information 9regarding the internal format of overlays: 10https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/dt-object-internal.txt 11 12Building Overlays 13----------------- 14 15In a nutshell overlays provides a means to manipulate a symbol a previous dtb 16or overlay has defined. It requires both the base and all the overlays 17to be compiled with the -@ command line switch so that symbol information is 18included. 19 20Note support for -@ option can only be found in dtc version 1.4.4 or newer. 21Only version 4.14 or higher of the Linux kernel includes a built in version 22of dtc that meets this requirement. 23 24Building an overlay follows the same process as building a traditional dtb. 25 26For example: 27 28base.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 40bar.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 59Ways to Utilize Overlays in U-boot 60---------------------------------- 61 62There are two ways to apply overlays in U-boot. 631. Include and define overlays within a FIT image and have overlays 64 automatically applied. 65 662. Manually load and apply overlays 67 68The remainder of this document will discuss using overlays via the manual 69approach. For information on using overlays as part of a FIT image please see: 70doc/uImage.FIT/overlay-fdt-boot.txt 71 72Manually Loading and Applying Overlays 73-------------------------------------- 74 751. Figure out where to place both the base device tree blob and the 76overlay. Make sure you have enough space to grow the base tree without 77overlapping anything. 78 79=> setenv fdtaddr 0x87f00000 80=> setenv fdtovaddr 0x87fc0000 81 822. 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 873. Set it as the working fdt tree. 88 89=> fdtaddr $fdtaddr 90 914. Grow it enough so it can 'fit' all the applied overlays 92 93=> fdt resize 8192 94 955. You are now ready to apply the overlay. 96 97=> fdt apply $fdtovaddr 98 996. Boot system like you would do with a traditional dtb. 100 101For bootm: 102 103=> bootm ${kerneladdr} - ${fdtaddr} 104 105For bootz: 106 107=> bootz ${kerneladdr} - ${fdtaddr} 108 109Please note that in case of an error, both the base and overlays are going 110to be invalidated, so keep copies to avoid reloading. 111 112Pantelis Antoniou 113pantelis.antoniou@konsulko.com 11411/7/2017 115