mirror of
https://github.com/AsahiLinux/u-boot
synced 2024-11-10 23:24:38 +00:00
doc: move README.fdt-overlays to HTML documentation
Convert doc/README.fdt-overlays to doc/usage/fdt_overlays.rst. Edit the text for readability. Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
This commit is contained in:
Heinrich Schuchardt
parent
c2febb2843
commit
4f792d232d
3 changed files with 136 additions and 114 deletions
|
|
@ -1,114 +0,0 @@
|
||||||
U-Boot FDT Overlay usage
|
|
||||||
=============================================
|
|
||||||
|
|
||||||
Overlays Syntax
|
|
||||||
---------------
|
|
||||||
|
|
||||||
Overlays require slightly different syntax compared to traditional overlays.
|
|
||||||
Please refer to dt-object-internal.txt in the dtc 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 dtb
|
|
||||||
or overlay has defined. It requires both the base and all the overlays
|
|
||||||
to be compiled with the -@ command line switch 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 an overlay follows the same process as building a traditional dtb.
|
|
||||||
|
|
||||||
For example:
|
|
||||||
|
|
||||||
base.dts
|
|
||||||
--------
|
|
||||||
|
|
||||||
/dts-v1/;
|
|
||||||
/ {
|
|
||||||
foo: foonode {
|
|
||||||
foo-property;
|
|
||||||
};
|
|
||||||
};
|
|
||||||
|
|
||||||
$ dtc -@ -I dts -O dtb -o base.dtb base.dts
|
|
||||||
|
|
||||||
bar.dts
|
|
||||||
-------
|
|
||||||
|
|
||||||
/dts-v1/;
|
|
||||||
/plugin/;
|
|
||||||
/ {
|
|
||||||
fragment@1 {
|
|
||||||
target = <&foo>;
|
|
||||||
__overlay__ {
|
|
||||||
overlay-1-property;
|
|
||||||
bar: barnode {
|
|
||||||
bar-property;
|
|
||||||
};
|
|
||||||
};
|
|
||||||
};
|
|
||||||
};
|
|
||||||
|
|
||||||
$ dtc -@ -I dts -O dtb -o bar.dtb bar.dts
|
|
||||||
|
|
||||||
Ways to Utilize Overlays in U-boot
|
|
||||||
----------------------------------
|
|
||||||
|
|
||||||
There are two ways to apply overlays in U-boot.
|
|
||||||
1. Include and define overlays within a FIT image and have overlays
|
|
||||||
automatically applied.
|
|
||||||
|
|
||||||
2. 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 blob and overlay blobs
|
|
||||||
|
|
||||||
=> load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb
|
|
||||||
=> load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtb
|
|
||||||
|
|
||||||
3. Set it as the working fdt tree.
|
|
||||||
|
|
||||||
=> fdtaddr $fdtaddr
|
|
||||||
|
|
||||||
4. Grow it enough so it can 'fit' all the 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.
|
|
||||||
|
|
||||||
Pantelis Antoniou
|
|
||||||
pantelis.antoniou@konsulko.com
|
|
||||||
11/7/2017
|
|
||||||
134
doc/usage/fdt_overlays.rst
Normal file
134
doc/usage/fdt_overlays.rst
Normal file
|
|
@ -0,0 +1,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.
|
||||||
|
|
@ -2,7 +2,9 @@ Use U-Boot
|
||||||
==========
|
==========
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
fdt_overlays
|
||||||
netconsole
|
netconsole
|
||||||
|
|
||||||
Shell commands
|
Shell commands
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue