mirror of
https://github.com/u-boot/u-boot.git
synced 2025-04-20 20:04:46 +00:00
doc: Bring in the FIT overlay information
Bring this file into the documentation. Signed-off-by: Simon Glass <sjg@chromium.org>
This commit is contained in:
Simon Glass
Heinrich Schuchardt
parent
51de69cda3
commit
6f6e8bb695
3 changed files with 228 additions and 225 deletions
|
|
@ -1,225 +0,0 @@
|
||||||
U-Boot FDT Overlay FIT usage
|
|
||||||
============================
|
|
||||||
|
|
||||||
Introduction
|
|
||||||
------------
|
|
||||||
In many cases it is desirable to have a single FIT image support a multitude
|
|
||||||
of similar boards and their expansion options. The same kernel on DT enabled
|
|
||||||
platforms can support this easily enough by providing a DT blob upon boot
|
|
||||||
that matches the desired configuration.
|
|
||||||
|
|
||||||
This document focuses on specifically using overlays as part of a FIT image.
|
|
||||||
General information regarding overlays including its syntax and building it
|
|
||||||
can be found in doc/README.fdt-overlays
|
|
||||||
|
|
||||||
Configuration without overlays
|
|
||||||
------------------------------
|
|
||||||
|
|
||||||
Take a hypothetical board named 'foo' where there are different supported
|
|
||||||
revisions, reva and revb. Assume that both board revisions can use add a bar
|
|
||||||
add-on board, while only the revb board can use a baz add-on board.
|
|
||||||
|
|
||||||
Without using overlays the configuration would be as follows for every case.
|
|
||||||
|
|
||||||
/dts-v1/;
|
|
||||||
/ {
|
|
||||||
images {
|
|
||||||
kernel {
|
|
||||||
data = /incbin/("./zImage");
|
|
||||||
type = "kernel";
|
|
||||||
arch = "arm";
|
|
||||||
os = "linux";
|
|
||||||
load = <0x82000000>;
|
|
||||||
entry = <0x82000000>;
|
|
||||||
};
|
|
||||||
fdt-1 {
|
|
||||||
data = /incbin/("./foo-reva.dtb");
|
|
||||||
type = "flat_dt";
|
|
||||||
arch = "arm";
|
|
||||||
};
|
|
||||||
fdt-2 {
|
|
||||||
data = /incbin/("./foo-revb.dtb");
|
|
||||||
type = "flat_dt";
|
|
||||||
arch = "arm";
|
|
||||||
};
|
|
||||||
fdt-3 {
|
|
||||||
data = /incbin/("./foo-reva-bar.dtb");
|
|
||||||
type = "flat_dt";
|
|
||||||
arch = "arm";
|
|
||||||
};
|
|
||||||
fdt-4 {
|
|
||||||
data = /incbin/("./foo-revb-bar.dtb");
|
|
||||||
type = "flat_dt";
|
|
||||||
arch = "arm";
|
|
||||||
};
|
|
||||||
fdt-5 {
|
|
||||||
data = /incbin/("./foo-revb-baz.dtb");
|
|
||||||
type = "flat_dt";
|
|
||||||
arch = "arm";
|
|
||||||
};
|
|
||||||
fdt-6 {
|
|
||||||
data = /incbin/("./foo-revb-bar-baz.dtb");
|
|
||||||
type = "flat_dt";
|
|
||||||
arch = "arm";
|
|
||||||
};
|
|
||||||
};
|
|
||||||
|
|
||||||
configurations {
|
|
||||||
default = "foo-reva.dtb;
|
|
||||||
foo-reva.dtb {
|
|
||||||
kernel = "kernel";
|
|
||||||
fdt = "fdt-1";
|
|
||||||
};
|
|
||||||
foo-revb.dtb {
|
|
||||||
kernel = "kernel";
|
|
||||||
fdt = "fdt-2";
|
|
||||||
};
|
|
||||||
foo-reva-bar.dtb {
|
|
||||||
kernel = "kernel";
|
|
||||||
fdt = "fdt-3";
|
|
||||||
};
|
|
||||||
foo-revb-bar.dtb {
|
|
||||||
kernel = "kernel";
|
|
||||||
fdt = "fdt-4";
|
|
||||||
};
|
|
||||||
foo-revb-baz.dtb {
|
|
||||||
kernel = "kernel";
|
|
||||||
fdt = "fdt-5";
|
|
||||||
};
|
|
||||||
foo-revb-bar-baz.dtb {
|
|
||||||
kernel = "kernel";
|
|
||||||
fdt = "fdt-6";
|
|
||||||
};
|
|
||||||
};
|
|
||||||
};
|
|
||||||
|
|
||||||
Note the blob needs to be compiled for each case and the combinatorial explosion of
|
|
||||||
configurations. A typical device tree blob is in the low hunderds of kbytes so a
|
|
||||||
multitude of configuration grows the image quite a bit.
|
|
||||||
|
|
||||||
Booting this image is done by using
|
|
||||||
|
|
||||||
# bootm <addr>#<config>
|
|
||||||
|
|
||||||
Where config is one of:
|
|
||||||
foo-reva.dtb, foo-revb.dtb, foo-reva-bar.dtb, foo-revb-bar.dtb,
|
|
||||||
foo-revb-baz.dtb, foo-revb-bar-baz.dtb
|
|
||||||
|
|
||||||
This selects the DTB to use when booting.
|
|
||||||
|
|
||||||
Configuration using overlays
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
Device tree overlays can be applied to a base DT and result in the same blob
|
|
||||||
being passed to the booting kernel. This saves on space and avoid the combinatorial
|
|
||||||
explosion problem.
|
|
||||||
|
|
||||||
/dts-v1/;
|
|
||||||
/ {
|
|
||||||
images {
|
|
||||||
kernel {
|
|
||||||
data = /incbin/("./zImage");
|
|
||||||
type = "kernel";
|
|
||||||
arch = "arm";
|
|
||||||
os = "linux";
|
|
||||||
load = <0x82000000>;
|
|
||||||
entry = <0x82000000>;
|
|
||||||
};
|
|
||||||
fdt-1 {
|
|
||||||
data = /incbin/("./foo.dtb");
|
|
||||||
type = "flat_dt";
|
|
||||||
arch = "arm";
|
|
||||||
load = <0x87f00000>;
|
|
||||||
};
|
|
||||||
fdt-2 {
|
|
||||||
data = /incbin/("./reva.dtbo");
|
|
||||||
type = "flat_dt";
|
|
||||||
arch = "arm";
|
|
||||||
load = <0x87fc0000>;
|
|
||||||
};
|
|
||||||
fdt-3 {
|
|
||||||
data = /incbin/("./revb.dtbo");
|
|
||||||
type = "flat_dt";
|
|
||||||
arch = "arm";
|
|
||||||
load = <0x87fc0000>;
|
|
||||||
};
|
|
||||||
fdt-4 {
|
|
||||||
data = /incbin/("./bar.dtbo");
|
|
||||||
type = "flat_dt";
|
|
||||||
arch = "arm";
|
|
||||||
load = <0x87fc0000>;
|
|
||||||
};
|
|
||||||
fdt-5 {
|
|
||||||
data = /incbin/("./baz.dtbo");
|
|
||||||
type = "flat_dt";
|
|
||||||
arch = "arm";
|
|
||||||
load = <0x87fc0000>;
|
|
||||||
};
|
|
||||||
};
|
|
||||||
|
|
||||||
configurations {
|
|
||||||
default = "foo-reva.dtb;
|
|
||||||
foo-reva.dtb {
|
|
||||||
kernel = "kernel";
|
|
||||||
fdt = "fdt-1", "fdt-2";
|
|
||||||
};
|
|
||||||
foo-revb.dtb {
|
|
||||||
kernel = "kernel";
|
|
||||||
fdt = "fdt-1", "fdt-3";
|
|
||||||
};
|
|
||||||
foo-reva-bar.dtb {
|
|
||||||
kernel = "kernel";
|
|
||||||
fdt = "fdt-1", "fdt-2", "fdt-4";
|
|
||||||
};
|
|
||||||
foo-revb-bar.dtb {
|
|
||||||
kernel = "kernel";
|
|
||||||
fdt = "fdt-1", "fdt-3", "fdt-4";
|
|
||||||
};
|
|
||||||
foo-revb-baz.dtb {
|
|
||||||
kernel = "kernel";
|
|
||||||
fdt = "fdt-1", "fdt-3", "fdt-5";
|
|
||||||
};
|
|
||||||
foo-revb-bar-baz.dtb {
|
|
||||||
kernel = "kernel";
|
|
||||||
fdt = "fdt-1", "fdt-3", "fdt-4", "fdt-5";
|
|
||||||
};
|
|
||||||
bar {
|
|
||||||
fdt = "fdt-4";
|
|
||||||
};
|
|
||||||
baz {
|
|
||||||
fdt = "fdt-5";
|
|
||||||
};
|
|
||||||
};
|
|
||||||
};
|
|
||||||
|
|
||||||
Booting this image is exactly the same as the non-overlay example.
|
|
||||||
u-boot will retrieve the base blob and apply the overlays in sequence as
|
|
||||||
they are declared in the configuration.
|
|
||||||
|
|
||||||
Note the minimum amount of different DT blobs, as well as the requirement for
|
|
||||||
the DT blobs to have a load address; the overlay application requires the blobs
|
|
||||||
to be writeable.
|
|
||||||
|
|
||||||
Configuration using overlays and feature selection
|
|
||||||
--------------------------------------------------
|
|
||||||
|
|
||||||
Although the configuration in the previous section works is a bit inflexible
|
|
||||||
since it requires all possible configuration options to be laid out before
|
|
||||||
hand in the FIT image. For the add-on boards the extra config selection method
|
|
||||||
might make sense.
|
|
||||||
|
|
||||||
Note the two bar & baz configuration nodes. To boot a reva board with
|
|
||||||
the bar add-on board enabled simply use:
|
|
||||||
|
|
||||||
# bootm <addr>#foo-reva.dtb#bar
|
|
||||||
|
|
||||||
While booting a revb with bar and baz is as follows:
|
|
||||||
|
|
||||||
# bootm <addr>#foo-revb.dtb#bar#baz
|
|
||||||
|
|
||||||
The limitation for a feature selection configuration node is that a single
|
|
||||||
fdt option is currently supported.
|
|
||||||
|
|
||||||
Pantelis Antoniou
|
|
||||||
pantelis.antoniou@konsulko.com
|
|
||||||
12/6/2017
|
|
||||||
|
|
@ -16,3 +16,4 @@ doc/uImage.FIT
|
||||||
signature
|
signature
|
||||||
verified-boot
|
verified-boot
|
||||||
beaglebone_vboot
|
beaglebone_vboot
|
||||||
|
overlay-fdt-boot
|
||||||
|
|
|
||||||
227
doc/usage/fit/overlay-fdt-boot.rst
Normal file
227
doc/usage/fit/overlay-fdt-boot.rst
Normal file
|
|
@ -0,0 +1,227 @@
|
||||||
|
.. SPDX-License-Identifier: GPL-2.0+
|
||||||
|
|
||||||
|
U-Boot FDT Overlay FIT usage
|
||||||
|
============================
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
------------
|
||||||
|
|
||||||
|
In many cases it is desirable to have a single FIT image support a multitude
|
||||||
|
of similar boards and their expansion options. The same kernel on DT enabled
|
||||||
|
platforms can support this easily enough by providing a DT blob upon boot
|
||||||
|
that matches the desired configuration.
|
||||||
|
|
||||||
|
This document focuses on specifically using overlays as part of a FIT image.
|
||||||
|
General information regarding overlays including its syntax and building it
|
||||||
|
can be found in doc/README.fdt-overlays
|
||||||
|
|
||||||
|
Configuration without overlays
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
Take a hypothetical board named 'foo' where there are different supported
|
||||||
|
revisions, reva and revb. Assume that both board revisions can use add a bar
|
||||||
|
add-on board, while only the revb board can use a baz add-on board.
|
||||||
|
|
||||||
|
Without using overlays the configuration would be as follows for every case::
|
||||||
|
|
||||||
|
/dts-v1/;
|
||||||
|
/ {
|
||||||
|
images {
|
||||||
|
kernel {
|
||||||
|
data = /incbin/("./zImage");
|
||||||
|
type = "kernel";
|
||||||
|
arch = "arm";
|
||||||
|
os = "linux";
|
||||||
|
load = <0x82000000>;
|
||||||
|
entry = <0x82000000>;
|
||||||
|
};
|
||||||
|
fdt-1 {
|
||||||
|
data = /incbin/("./foo-reva.dtb");
|
||||||
|
type = "flat_dt";
|
||||||
|
arch = "arm";
|
||||||
|
};
|
||||||
|
fdt-2 {
|
||||||
|
data = /incbin/("./foo-revb.dtb");
|
||||||
|
type = "flat_dt";
|
||||||
|
arch = "arm";
|
||||||
|
};
|
||||||
|
fdt-3 {
|
||||||
|
data = /incbin/("./foo-reva-bar.dtb");
|
||||||
|
type = "flat_dt";
|
||||||
|
arch = "arm";
|
||||||
|
};
|
||||||
|
fdt-4 {
|
||||||
|
data = /incbin/("./foo-revb-bar.dtb");
|
||||||
|
type = "flat_dt";
|
||||||
|
arch = "arm";
|
||||||
|
};
|
||||||
|
fdt-5 {
|
||||||
|
data = /incbin/("./foo-revb-baz.dtb");
|
||||||
|
type = "flat_dt";
|
||||||
|
arch = "arm";
|
||||||
|
};
|
||||||
|
fdt-6 {
|
||||||
|
data = /incbin/("./foo-revb-bar-baz.dtb");
|
||||||
|
type = "flat_dt";
|
||||||
|
arch = "arm";
|
||||||
|
};
|
||||||
|
};
|
||||||
|
|
||||||
|
configurations {
|
||||||
|
default = "foo-reva.dtb;
|
||||||
|
foo-reva.dtb {
|
||||||
|
kernel = "kernel";
|
||||||
|
fdt = "fdt-1";
|
||||||
|
};
|
||||||
|
foo-revb.dtb {
|
||||||
|
kernel = "kernel";
|
||||||
|
fdt = "fdt-2";
|
||||||
|
};
|
||||||
|
foo-reva-bar.dtb {
|
||||||
|
kernel = "kernel";
|
||||||
|
fdt = "fdt-3";
|
||||||
|
};
|
||||||
|
foo-revb-bar.dtb {
|
||||||
|
kernel = "kernel";
|
||||||
|
fdt = "fdt-4";
|
||||||
|
};
|
||||||
|
foo-revb-baz.dtb {
|
||||||
|
kernel = "kernel";
|
||||||
|
fdt = "fdt-5";
|
||||||
|
};
|
||||||
|
foo-revb-bar-baz.dtb {
|
||||||
|
kernel = "kernel";
|
||||||
|
fdt = "fdt-6";
|
||||||
|
};
|
||||||
|
};
|
||||||
|
};
|
||||||
|
|
||||||
|
Note the blob needs to be compiled for each case and the combinatorial explosion of
|
||||||
|
configurations. A typical device tree blob is in the low hunderds of kbytes so a
|
||||||
|
multitude of configuration grows the image quite a bit.
|
||||||
|
|
||||||
|
Booting this image is done by using::
|
||||||
|
|
||||||
|
# bootm <addr>#<config>
|
||||||
|
|
||||||
|
Where config is one of::
|
||||||
|
|
||||||
|
foo-reva.dtb, foo-revb.dtb, foo-reva-bar.dtb, foo-revb-bar.dtb,
|
||||||
|
foo-revb-baz.dtb, foo-revb-bar-baz.dtb
|
||||||
|
|
||||||
|
This selects the DTB to use when booting.
|
||||||
|
|
||||||
|
Configuration using overlays
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
Device tree overlays can be applied to a base DT and result in the same blob
|
||||||
|
being passed to the booting kernel. This saves on space and avoid the combinatorial
|
||||||
|
explosion problem::
|
||||||
|
|
||||||
|
/dts-v1/;
|
||||||
|
/ {
|
||||||
|
images {
|
||||||
|
kernel {
|
||||||
|
data = /incbin/("./zImage");
|
||||||
|
type = "kernel";
|
||||||
|
arch = "arm";
|
||||||
|
os = "linux";
|
||||||
|
load = <0x82000000>;
|
||||||
|
entry = <0x82000000>;
|
||||||
|
};
|
||||||
|
fdt-1 {
|
||||||
|
data = /incbin/("./foo.dtb");
|
||||||
|
type = "flat_dt";
|
||||||
|
arch = "arm";
|
||||||
|
load = <0x87f00000>;
|
||||||
|
};
|
||||||
|
fdt-2 {
|
||||||
|
data = /incbin/("./reva.dtbo");
|
||||||
|
type = "flat_dt";
|
||||||
|
arch = "arm";
|
||||||
|
load = <0x87fc0000>;
|
||||||
|
};
|
||||||
|
fdt-3 {
|
||||||
|
data = /incbin/("./revb.dtbo");
|
||||||
|
type = "flat_dt";
|
||||||
|
arch = "arm";
|
||||||
|
load = <0x87fc0000>;
|
||||||
|
};
|
||||||
|
fdt-4 {
|
||||||
|
data = /incbin/("./bar.dtbo");
|
||||||
|
type = "flat_dt";
|
||||||
|
arch = "arm";
|
||||||
|
load = <0x87fc0000>;
|
||||||
|
};
|
||||||
|
fdt-5 {
|
||||||
|
data = /incbin/("./baz.dtbo");
|
||||||
|
type = "flat_dt";
|
||||||
|
arch = "arm";
|
||||||
|
load = <0x87fc0000>;
|
||||||
|
};
|
||||||
|
};
|
||||||
|
|
||||||
|
configurations {
|
||||||
|
default = "foo-reva.dtb;
|
||||||
|
foo-reva.dtb {
|
||||||
|
kernel = "kernel";
|
||||||
|
fdt = "fdt-1", "fdt-2";
|
||||||
|
};
|
||||||
|
foo-revb.dtb {
|
||||||
|
kernel = "kernel";
|
||||||
|
fdt = "fdt-1", "fdt-3";
|
||||||
|
};
|
||||||
|
foo-reva-bar.dtb {
|
||||||
|
kernel = "kernel";
|
||||||
|
fdt = "fdt-1", "fdt-2", "fdt-4";
|
||||||
|
};
|
||||||
|
foo-revb-bar.dtb {
|
||||||
|
kernel = "kernel";
|
||||||
|
fdt = "fdt-1", "fdt-3", "fdt-4";
|
||||||
|
};
|
||||||
|
foo-revb-baz.dtb {
|
||||||
|
kernel = "kernel";
|
||||||
|
fdt = "fdt-1", "fdt-3", "fdt-5";
|
||||||
|
};
|
||||||
|
foo-revb-bar-baz.dtb {
|
||||||
|
kernel = "kernel";
|
||||||
|
fdt = "fdt-1", "fdt-3", "fdt-4", "fdt-5";
|
||||||
|
};
|
||||||
|
bar {
|
||||||
|
fdt = "fdt-4";
|
||||||
|
};
|
||||||
|
baz {
|
||||||
|
fdt = "fdt-5";
|
||||||
|
};
|
||||||
|
};
|
||||||
|
};
|
||||||
|
|
||||||
|
Booting this image is exactly the same as the non-overlay example.
|
||||||
|
u-boot will retrieve the base blob and apply the overlays in sequence as
|
||||||
|
they are declared in the configuration.
|
||||||
|
|
||||||
|
Note the minimum amount of different DT blobs, as well as the requirement for
|
||||||
|
the DT blobs to have a load address; the overlay application requires the blobs
|
||||||
|
to be writeable.
|
||||||
|
|
||||||
|
Configuration using overlays and feature selection
|
||||||
|
--------------------------------------------------
|
||||||
|
|
||||||
|
Although the configuration in the previous section works is a bit inflexible
|
||||||
|
since it requires all possible configuration options to be laid out before
|
||||||
|
hand in the FIT image. For the add-on boards the extra config selection method
|
||||||
|
might make sense.
|
||||||
|
|
||||||
|
Note the two bar & baz configuration nodes. To boot a reva board with
|
||||||
|
the bar add-on board enabled simply use::
|
||||||
|
|
||||||
|
=> bootm <addr>#foo-reva.dtb#bar
|
||||||
|
|
||||||
|
While booting a revb with bar and baz is as follows::
|
||||||
|
|
||||||
|
=> bootm <addr>#foo-revb.dtb#bar#baz
|
||||||
|
|
||||||
|
The limitation for a feature selection configuration node is that a single
|
||||||
|
fdt option is currently supported.
|
||||||
|
|
||||||
|
.. sectionauthor:: Pantelis Antoniou <pantelis.antoniou@konsulko.com>, 12/6/2017
|
||||||
Loading…
Add table
Reference in a new issue