From patchwork Thu Dec 31 15:48:32 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Heinrich Schuchardt X-Patchwork-Id: 1421590 X-Patchwork-Delegate: trini@ti.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=lists.denx.de (client-ip=2a01:238:438b:c500:173d:9f52:ddab:ee01; helo=phobos.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=gmx.de Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; secure) header.d=gmx.net header.i=@gmx.net header.a=rsa-sha256 header.s=badeba3b8450 header.b=VPBHYh//; dkim-atps=neutral Received: from phobos.denx.de (unknown [IPv6:2a01:238:438b:c500:173d:9f52:ddab:ee01]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4D6CJ70nmWz9sRN for ; Fri, 1 Jan 2021 02:49:00 +1100 (AEDT) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 9945182564; Thu, 31 Dec 2020 16:48:45 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=fail (p=none dis=none) header.from=gmx.de Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (1024-bit key; secure) header.d=gmx.net header.i=@gmx.net header.b="VPBHYh//"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 98139825AA; Thu, 31 Dec 2020 16:48:44 +0100 (CET) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-2.6 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,FREEMAIL_FROM,RCVD_IN_DNSWL_LOW,RCVD_IN_MSPIKE_H2, SPF_HELO_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from mout.gmx.net (mout.gmx.net [212.227.15.15]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id BC1B68002F for ; Thu, 31 Dec 2020 16:48:37 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmx.de Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=xypron.glpk@gmx.de DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1609429716; bh=BHp0Ge4gsbjXe56MTCcfVfiiq5jg4FoAoi15OkApxnU=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date; b=VPBHYh//IPMDS24LqQWgGjoDDU6qb83EGta46r30orwBOrpeOrC5jPhKwCwzXDdYY jTAgPLh5Bhqfc2zJcpePyZBTMeEjjkDqEVcH8yfkJLIQsCEg54MGV96Wbw3jbEQwUd SEcHm0/4QJhwOhjd6hCRwPTpmqToI/aLu89yjAAw= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from LT02.fritz.box ([62.143.246.89]) by mail.gmx.com (mrgmx004 [212.227.17.184]) with ESMTPSA (Nemesis) id 1MXGrE-1kW8z42sJS-00Ym1i; Thu, 31 Dec 2020 16:48:36 +0100 From: Heinrich Schuchardt To: Tom Rini Cc: Pantelis Antoniou , u-boot@lists.denx.de, Heinrich Schuchardt Subject: [PATCH 1/1] doc: move README.fdt-overlays to HTML documentation Date: Thu, 31 Dec 2020 16:48:32 +0100 Message-Id: <20201231154832.55704-1-xypron.glpk@gmx.de> X-Mailer: git-send-email 2.29.2 MIME-Version: 1.0 X-Provags-ID: V03:K1:wCp7YC5Jcc2hYvR/zVap7LD9pG2wJfX+uA6edX/fRANWIZ7JY8o qzN8p1fAEgKVX53CK5cW9aJbcDHyV0u1bZkMGygpXblzLfbJbMinlz2LRqEcPbr1dM1MjPX HKiROMVO14xmF0Ymf3EUaidwy/vYIu11bmEBgWv8XKZqfth+nxz+GG0OD5TNJuDR0vdVPsh 9H1MVYYFmR65KdfArO3dg== X-UI-Out-Filterresults: notjunk:1;V03:K0:QrD18gXVxPU=:aLfF+/BiHKBfPplaRUoEbK Ilvu05DUj7ceyhDEwJ7l28HgIP/II4S9Xyq/Mzjsmplhv5D2jla4UPxDrfMUpfTQXGexbjX3u 4o959owWsjBeyeUv1ZyOv5zfSMQW+NsHzjGic9lLI1dZ1Khc+6V6d23idiNm+B9OMoVTYqc3l ey1IcioFn9U0f0k4yxxKRpcXsuYkKYHn0w+ij62kSSjIRh5TPNw1ei606/NNFge/0FDXC/4V/ wBoxFKNQUhwvaH36snV6+gChvC7qnE1j+ZmmVUVI1O18wSPe/iUrYsZ/5RerIp3FLV4BP4VAN GcVGwsCX1cGuHbWe53vGjtyZl5Vq6NR8LKlFBWNZ4ubmZTaM1Jc5xcTPY91YHaIEUghw0xthJ RY1PM5qYB/y1TitHKHIl2/faoVKhrqBk+EHcD7UknarQQrgMCHaTvY3VPg4BV7WRtos/N7yHa RhYyz6KfoKohsB3gvZLqvSa9/hnrPJUVKvqa5sUJe9GHgZQvVEYPvgxL303/EvNbv8Il836iT xmW+3avqcRtRdond+1Bp/5frcdF7zubb38okhYNbhEB4BbttxoC1Mut6uV5f3N3X4M/ZQqsV2 zzX5SBKAXZihAzDS6tSlhtpJ9TADbfcPPiE90nTQTkR3rfoLLvRBWYiyBq2jgcXRjJeODr5Rl v0ZUbmx9UjI+w+/i7iayMdpdlaRGnaZATbZngH+PKYbHIBP+lu2mLF4ju1NxGcgOa5YNAOjPh GppP1HXUX1d56MpOEIR9DotGt5hpfZfrFxpKQE71QY/TRyhmhqWPssFYxFB6b8UJdD1sax2aR 0CA1MB27VGL5JvBHgSVjs9SQ8kQg1f6AeiaXhdxMD897iR9GyNp2z+NSpREHnrZh4VmmPgc/5 6DlbGbPKwPY1t8oXPRUw== X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.34 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.102.3 at phobos.denx.de X-Virus-Status: Clean Convert doc/README.fdt-overlays to doc/usage/fdt_overlays.rst. Edit the text for readability. Signed-off-by: Heinrich Schuchardt --- doc/README.fdt-overlays | 114 ------------------------------- doc/usage/fdt_overlays.rst | 134 +++++++++++++++++++++++++++++++++++++ doc/usage/index.rst | 2 + 3 files changed, 136 insertions(+), 114 deletions(-) delete mode 100644 doc/README.fdt-overlays create mode 100644 doc/usage/fdt_overlays.rst -- 2.29.2 diff --git a/doc/README.fdt-overlays b/doc/README.fdt-overlays deleted file mode 100644 index 39139cb850..0000000000 --- a/doc/README.fdt-overlays +++ /dev/null @@ -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 diff --git a/doc/usage/fdt_overlays.rst b/doc/usage/fdt_overlays.rst new file mode 100644 index 0000000000..ea39713434 --- /dev/null +++ b/doc/usage/fdt_overlays.rst @@ -0,0 +1,134 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2017, Pantelis Antoniou + +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. diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 57bf4fe851..ada0df08c0 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -2,7 +2,9 @@ Use U-Boot ========== .. toctree:: + :maxdepth: 1 + fdt_overlays netconsole Shell commands