Home | History | Annotate | Download | only in doc 
      1 U-Boot FDT Overlay usage
      2 =============================================
      3 
      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 --------------------------------------
     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 
     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 
    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 (a] konsulko.com
    114 11/7/2017
    115