From patchwork Mon Sep 4 20:12:17 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Pantelis Antoniou X-Patchwork-Id: 809835 X-Patchwork-Delegate: sjg@chromium.org Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=none (mailfrom) smtp.mailfrom=lists.denx.de (client-ip=81.169.180.215; helo=lists.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=konsulko.com header.i=@konsulko.com header.b="BDL1aMIv"; dkim-atps=neutral Received: from lists.denx.de (dione.denx.de [81.169.180.215]) by ozlabs.org (Postfix) with ESMTP id 3xmLnr61rxz9t2R for ; Tue, 5 Sep 2017 06:20:48 +1000 (AEST) Received: by lists.denx.de (Postfix, from userid 105) id 94287C21F68; Mon, 4 Sep 2017 20:15:21 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on lists.denx.de X-Spam-Level: X-Spam-Status: No, score=-0.0 required=5.0 tests=RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, T_DKIM_INVALID autolearn=unavailable autolearn_force=no version=3.4.0 Received: from lists.denx.de (localhost [IPv6:::1]) by lists.denx.de (Postfix) with ESMTP id F0B7CC21F49; Mon, 4 Sep 2017 20:14:32 +0000 (UTC) Received: by lists.denx.de (Postfix, from userid 105) id 76BE0C21EF2; Mon, 4 Sep 2017 20:13:13 +0000 (UTC) Received: from mail-wm0-f53.google.com (mail-wm0-f53.google.com [74.125.82.53]) by lists.denx.de (Postfix) with ESMTPS id EFEF8C21F1C for ; Mon, 4 Sep 2017 20:13:06 +0000 (UTC) Received: by mail-wm0-f53.google.com with SMTP id 187so8639133wmn.1 for ; Mon, 04 Sep 2017 13:13:06 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=konsulko.com; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=P8H8vlnnbwGL09YifcqOyVbVNZSxrYRrhIMz5BM+aqI=; b=BDL1aMIvue3/InCrpv8SkBrwHGHVW8zzo8QxpejuPQpy6MiRvTZucxwTW1y5YNXecj zZI4qYrCKNRsIHCVRQsOZG634RYWe1kYwlXhNaso7hzAguNKINrTc520XC50Bgjj9Ydf Y6PQ9a4B5oaoOqshXePi3cOHpoI/kG78OtdlM= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=P8H8vlnnbwGL09YifcqOyVbVNZSxrYRrhIMz5BM+aqI=; b=DnZ5bsDDHzFAGo/lgXjth//QmitKxNobBRhGVKQ4hkr6lfBQBqkpKRWIUZPaFtGekz U/GjW1Mx7eZnzO6v3uJ+ewGN51AtH4QOxgUoza3Wb92PfKwGwOU4FB93B6uEmksgrH8e OSyY3q1RKzb+53lrkTS2+hOE3KaJBDZAZbsQKVD94pjwuyyMeA8m0n26q8paIE9qYQtx A471FqiiaLewbgyKlV58C+FXOVoCt9X/NJ+Bt8nO4CcooVZ1swwT1+kgHsqRfMWn5x7d TMCev5MFF/gBU+mWnwPk5eIFsYSdGc64VUg7vkTUyEFfIW1evat96RWQi8rY7784pfqM 0LYw== X-Gm-Message-State: AHPjjUgdmDtkN+4l47nzka0X1OmpfaqOKuodyb/uSjP+foacQnR2nous TXTMfsTM5nfrWD// X-Google-Smtp-Source: ADKCNb4jJ7NCqw71Mg1eeXy2epSlCO8CtKZ/IRvE5LvJc9HwYZ/HO1T9zzJqpFKU8d/SaSN7IXWViw== X-Received: by 10.28.126.199 with SMTP id z190mr1136755wmc.52.1504555986522; Mon, 04 Sep 2017 13:13:06 -0700 (PDT) Received: from localhost.localdomain ([195.97.110.117]) by smtp.gmail.com with ESMTPSA id u8sm3720435wrc.92.2017.09.04.13.13.04 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Mon, 04 Sep 2017 13:13:06 -0700 (PDT) From: Pantelis Antoniou To: Tom Rini Date: Mon, 4 Sep 2017 23:12:17 +0300 Message-Id: <1504555943-12893-9-git-send-email-pantelis.antoniou@konsulko.com> X-Mailer: git-send-email 2.1.4 In-Reply-To: <1504555943-12893-1-git-send-email-pantelis.antoniou@konsulko.com> References: <1504555943-12893-1-git-send-email-pantelis.antoniou@konsulko.com> Cc: Marek Vasut , Pantelis Antoniou , Tero Kristo , u-boot@lists.denx.de, Maxime Ripard , Stefan Roese , Alan Ott Subject: [U-Boot] [PATCH v3 08/14] fit: fdt overlays doc X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.18 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" Signed-off-by: Pantelis Antoniou Reviewed-by: Łukasz Majewski Acked-by: Simon Glass Acked-by: Simon Glass --- doc/uImage.FIT/command_syntax_extensions.txt | 12 +- doc/uImage.FIT/overlay-fdt-boot.txt | 221 +++++++++++++++++++++++++++ doc/uImage.FIT/source_file_format.txt | 6 +- 3 files changed, 236 insertions(+), 3 deletions(-) create mode 100644 doc/uImage.FIT/overlay-fdt-boot.txt diff --git a/doc/uImage.FIT/command_syntax_extensions.txt b/doc/uImage.FIT/command_syntax_extensions.txt index 6c99b1c..676f992 100644 --- a/doc/uImage.FIT/command_syntax_extensions.txt +++ b/doc/uImage.FIT/command_syntax_extensions.txt @@ -36,7 +36,7 @@ Old uImage: New uImage: 8. bootm 9. bootm []: -10. bootm []# +10. bootm []#[#]: []: 12. bootm []: []: []: 13. bootm []: []: @@ -129,6 +129,12 @@ following syntax: - new uImage configuration specification # +- new uImage configuration specification with extra configuration components +#[#[#..]] + +The extra configuration currently is supported only for additional device tree +overlays to apply on the base device tree supplied by the first configuration +unit. Examples: @@ -138,6 +144,10 @@ bootm 200000:kernel@1 - boot configuration "cfg@1" from a new uImage located at 200000: bootm 200000#cfg@1 +- boot configuration "cfg@1" with extra "cfg@2" from a new uImage located + at 200000: +bootm 200000#cfg@1#cfg@2 + - boot "kernel@1" from a new uImage at 200000 with initrd "ramdisk@2" found in some other new uImage stored at address 800000: bootm 200000:kernel@1 800000:ramdisk@2 diff --git a/doc/uImage.FIT/overlay-fdt-boot.txt b/doc/uImage.FIT/overlay-fdt-boot.txt new file mode 100644 index 0000000..dbdf2a1 --- /dev/null +++ b/doc/uImage.FIT/overlay-fdt-boot.txt @@ -0,0 +1,221 @@ +U-Boot FDT Overlay 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. + +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@1 { + 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@1"; + fdt = "fdt@1"; + }; + foo-revb.dtb { + kernel = "kernel@1"; + fdt = "fdt@2"; + }; + foo-reva-bar.dtb { + kernel = "kernel@1"; + fdt = "fdt@3"; + }; + foo-revb-bar.dtb { + kernel = "kernel@1"; + fdt = "fdt@4"; + }; + foo-revb-baz.dtb { + kernel = "kernel@1"; + fdt = "fdt@5"; + }; + foo-revb-bar-baz.dtb { + kernel = "kernel@1"; + 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 # + +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@1 { + 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@1"; + fdt = "fdt@1", "fdt@2"; + }; + foo-revb.dtb { + kernel = "kernel@1"; + fdt = "fdt@1", "fdt@3"; + }; + foo-reva-bar.dtb { + kernel = "kernel@1"; + fdt = "fdt@1", "fdt@2", "fdt@4"; + }; + foo-revb-bar.dtb { + kernel = "kernel@1"; + fdt = "fdt@1", "fdt@3", "fdt@4"; + }; + foo-revb-baz.dtb { + kernel = "kernel@1"; + fdt = "fdt@1", "fdt@3", "fdt@5"; + }; + foo-revb-bar-baz.dtb { + kernel = "kernel@1"; + 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 #foo-reva.dtb#bar + +While booting a revb with bar and baz is as follows: + + # bootm #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 diff --git a/doc/uImage.FIT/source_file_format.txt b/doc/uImage.FIT/source_file_format.txt index 136d3d7..ba8013a 100644 --- a/doc/uImage.FIT/source_file_format.txt +++ b/doc/uImage.FIT/source_file_format.txt @@ -235,7 +235,7 @@ o config@1 |- description = "configuration description" |- kernel = "kernel sub-node unit name" |- ramdisk = "ramdisk sub-node unit name" - |- fdt = "fdt sub-node unit-name" + |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...] |- fpga = "fpga sub-node unit-name" |- loadables = "loadables sub-node unit-name" @@ -249,7 +249,9 @@ o config@1 - ramdisk : Unit name of the corresponding ramdisk image (component image node of a "ramdisk" type). - fdt : Unit name of the corresponding fdt blob (component image node of a - "fdt type"). + "fdt type"). Additional fdt overlay nodes can be supplied which signify + that the resulting device tree blob is generated by the first base fdt + blob with all subsequent overlays applied. - setup : Unit name of the corresponding setup binary (used for booting an x86 kernel). This contains the setup.bin file built by the kernel. - fpga : Unit name of the corresponding fpga bitstream blob