| Message ID | 1504555943-12893-11-git-send-email-pantelis.antoniou@konsulko.com |
|---|---|
| State | Accepted |
| Delegated to: | Simon Glass |
| Headers | show |
| Series | uboot overlays, FIT image & unittest | expand |
On 09/04/2017 10:12 PM, Pantelis Antoniou wrote: > From: Franklin S Cooper Jr <fcooper@ti.com> > > Pull some information regarding overlays from commit messages and > put them directly within the documentation. Also add some information > regarding required dtc version to properly use overlays. > > Signed-off-by: Franklin S Cooper Jr <fcooper@ti.com> > --- > doc/README.fdt-overlays | 85 +++++++++++++++++++++++++++++++++++-- > doc/uImage.FIT/overlay-fdt-boot.txt | 8 +++- > 2 files changed, 87 insertions(+), 6 deletions(-) > > diff --git a/doc/README.fdt-overlays b/doc/README.fdt-overlays > index ee868ec..39139cb 100644 > --- a/doc/README.fdt-overlays > +++ b/doc/README.fdt-overlays > @@ -1,9 +1,76 @@ > -U-Boot FDT Overlay usage (without FIT images) > +U-Boot FDT Overlay usage > ============================================= > > -FDT overlays are now available for use even without FIT images. > -It is not as automagic as with FIT images though and require a few > -manual steps. > +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 > @@ -29,6 +96,16 @@ overlapping anything. > > => 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. > > diff --git a/doc/uImage.FIT/overlay-fdt-boot.txt b/doc/uImage.FIT/overlay-fdt-boot.txt > index dbdf2a1..63e47da 100644 > --- a/doc/uImage.FIT/overlay-fdt-boot.txt > +++ b/doc/uImage.FIT/overlay-fdt-boot.txt > @@ -1,5 +1,5 @@ > -U-Boot FDT Overlay usage > -======================== > +U-Boot FDT Overlay FIT usage > +============================ > > Introduction > ------------ > @@ -8,6 +8,10 @@ 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 > ------------------------------ > > Reviwed-by: Łukasz Majewski
On 4 September 2017 at 14:12, Pantelis Antoniou <pantelis.antoniou@konsulko.com> wrote: > From: Franklin S Cooper Jr <fcooper@ti.com> > > Pull some information regarding overlays from commit messages and > put them directly within the documentation. Also add some information > regarding required dtc version to properly use overlays. > > Signed-off-by: Franklin S Cooper Jr <fcooper@ti.com> > --- > doc/README.fdt-overlays | 85 +++++++++++++++++++++++++++++++++++-- > doc/uImage.FIT/overlay-fdt-boot.txt | 8 +++- > 2 files changed, 87 insertions(+), 6 deletions(-) Acked-by: Simon Glass <sjg@chromium.org>
On 4 September 2017 at 14:12, Pantelis Antoniou <pantelis.antoniou@konsulko.com> wrote: > From: Franklin S Cooper Jr <fcooper@ti.com> > > Pull some information regarding overlays from commit messages and > put them directly within the documentation. Also add some information > regarding required dtc version to properly use overlays. > > Signed-off-by: Franklin S Cooper Jr <fcooper@ti.com> > --- > doc/README.fdt-overlays | 85 +++++++++++++++++++++++++++++++++++-- > doc/uImage.FIT/overlay-fdt-boot.txt | 8 +++- > 2 files changed, 87 insertions(+), 6 deletions(-) Acked-by: Simon Glass <sjg@chromium.org> Applied to u-boot-fdt thanks!
diff --git a/doc/README.fdt-overlays b/doc/README.fdt-overlays index ee868ec..39139cb 100644 --- a/doc/README.fdt-overlays +++ b/doc/README.fdt-overlays @@ -1,9 +1,76 @@ -U-Boot FDT Overlay usage (without FIT images) +U-Boot FDT Overlay usage ============================================= -FDT overlays are now available for use even without FIT images. -It is not as automagic as with FIT images though and require a few -manual steps. +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 @@ -29,6 +96,16 @@ overlapping anything. => 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. diff --git a/doc/uImage.FIT/overlay-fdt-boot.txt b/doc/uImage.FIT/overlay-fdt-boot.txt index dbdf2a1..63e47da 100644 --- a/doc/uImage.FIT/overlay-fdt-boot.txt +++ b/doc/uImage.FIT/overlay-fdt-boot.txt @@ -1,5 +1,5 @@ -U-Boot FDT Overlay usage -======================== +U-Boot FDT Overlay FIT usage +============================ Introduction ------------ @@ -8,6 +8,10 @@ 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 ------------------------------