doc/README.fdt-overlays

   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@konsulko.com
 114 11/7/2017