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