summaryrefslogtreecommitdiff
path: root/doc/usage/fdt_overlays.rst
blob: ea39713434d716ddb8b3f218bc0c1ac599d2ec7d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
.. SPDX-License-Identifier: GPL-2.0+
.. Copyright (c) 2017, Pantelis Antoniou <pantelis.antoniou@konsulko.com>

Device Tree Overlays
====================

Overlay Syntax
--------------

Device-tree overlays require a slightly different syntax compared to traditional
device-trees. Please refer to dt-object-internal.txt in the device-tree compiler
sources for information regarding the internal format of overlays:
https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/dt-object-internal.txt

Building Overlays
-----------------

In a nutshell overlays provides a means to manipulate a symbol a previous
device-tree or device-tree overlay has defined. It requires both the base
device-tree and all the overlays to be compiled with the *-@* command line
switch of the device-tree compiler so that symbol information is included.

Note
    Support for *-@* option can only be found in dtc version 1.4.4 or newer.
    Only version 4.14 or higher of the Linux kernel includes a built in version
    of dtc that meets this requirement.

Building a binary device-tree overlay follows the same process as building a
traditional binary device-tree. For example:

**base.dts**

::

	/dts-v1/;
	/ {
		foo: foonode {
			foo-property;
		};
	};

.. code-block:: console

	$ dtc -@ -I dts -O dtb -o base.dtb base.dts

**overlay.dts**

::

	/dts-v1/;
	/plugin/;
	/ {
		fragment@1 {
			target = <&foo>;
			__overlay__ {
				overlay-1-property;
				bar: barnode {
					bar-property;
				};
			};
		};
	};

.. code-block:: console

	$ dtc -@ -I dts -O dtb -o overlay.dtbo overlay.dts

Ways to Utilize Overlays in U-Boot
----------------------------------

There are two ways to apply overlays in U-Boot.

* Include and define overlays within a FIT image and have overlays
  automatically applied.

* Manually load and apply overlays

The remainder of this document will discuss using overlays via the manual
approach. For information on using overlays as part of a FIT image please see:
doc/uImage.FIT/overlay-fdt-boot.txt

Manually Loading and Applying Overlays
--------------------------------------

1. Figure out where to place both the base device tree blob and the
   overlay. Make sure you have enough space to grow the base tree without
   overlapping anything.

::

    => setenv fdtaddr 0x87f00000
    => setenv fdtovaddr 0x87fc0000

2. Load the base binary device-tree and the binary device-tree overlay.

::

    => load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb
    => load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtbo

3. Set the base binary device-tree as the working fdt tree.

::

    => fdtaddr $fdtaddr

4. Grow it enough so it can encompass all applied overlays

::

    => fdt resize 8192

5. You are now ready to apply the overlay.

::

    => fdt apply $fdtovaddr

6. Boot system like you would do with a traditional dtb.

For bootm:

::

    => bootm ${kerneladdr} - ${fdtaddr}

For bootz:

::

    => bootz ${kerneladdr} - ${fdtaddr}

Please note that in case of an error, both the base and overlays are going
to be invalidated, so keep copies to avoid reloading.