doc/usage/fdt_overlays.rst

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