From patchwork Fri Aug 11 08:52:44 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pantelis Antoniou X-Patchwork-Id: 800472 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="f8azlET2"; dkim-atps=neutral Received: from lists.denx.de (dione.denx.de [81.169.180.215]) by ozlabs.org (Postfix) with ESMTP id 3xTJnc2FhXz9t2W for ; Fri, 11 Aug 2017 18:58:28 +1000 (AEST) Received: by lists.denx.de (Postfix, from userid 105) id 1B91FC21D79; Fri, 11 Aug 2017 08:57:04 +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 DB66EC21DAB; Fri, 11 Aug 2017 08:56:01 +0000 (UTC) Received: by lists.denx.de (Postfix, from userid 105) id 65385C21DAE; Fri, 11 Aug 2017 08:55:52 +0000 (UTC) Received: from mail-wm0-f52.google.com (mail-wm0-f52.google.com [74.125.82.52]) by lists.denx.de (Postfix) with ESMTPS id C9A7CC21DAD for ; Fri, 11 Aug 2017 08:55:46 +0000 (UTC) Received: by mail-wm0-f52.google.com with SMTP id t201so36982550wmt.1 for ; Fri, 11 Aug 2017 01:55:46 -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=g/KkphTAvDDi0tu9cxlEmixs5gqcglv4O11q2vNIoPc=; b=f8azlET25/zT4+SSoxvgn+Wnfxwz+MDVGxZHa03S3YnGFaYUQszOnfrcSDnilxW7FL X+AF1fORmK73cyuiJ0thoxqkDEzudViLpxfqkfVdDNZSpEA+HGYPaSBsX9UVcaXQ4KYt 8KUSzPo54KYgPE66VTykjeHQ1Zg4a3oBD3gqY= 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=g/KkphTAvDDi0tu9cxlEmixs5gqcglv4O11q2vNIoPc=; b=YQnzaOitjC7+Qsz0NdsCUX6Qnp9zK7HvgGHyCFpP/6iegB22SxwTVbItE7u6g0Ql4a MuCwl3bBhyUJcfSC44VP7pboRGG1KzaqAhP32NSVWXJy5GWuTkxnPannEWbQUy02dReG ay0+38XOFS9XJiBwI1pYDJjgXY5hOGEtpZEnCM7O/Tp+qgt+U0JR9ko31WlgIqeE3cY+ gbeAJ6FR687R4u73M6ni5ioniYKK20ptdZoQ5HOQ+12bxLEprT0+ZXPLthG0SGv/Nltm cGiEVmjMwDsjXO1uRf7qmRUAIgwEvu4wNUmIUiBz0dfw+g9vl+SwucZe8m00X0LULsqy 7AXw== X-Gm-Message-State: AHYfb5gUbGQsSouWSpD8KoJZBaZJTabBafVS/+r6GjTRWaFQTj1gpwOf wOrNFjX8FLL+/acw X-Received: by 10.28.128.215 with SMTP id b206mr8543367wmd.88.1502441746406; Fri, 11 Aug 2017 01:55:46 -0700 (PDT) Received: from localhost.localdomain ([195.97.110.117]) by smtp.gmail.com with ESMTPSA id o71sm759811wmg.15.2017.08.11.01.55.44 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Fri, 11 Aug 2017 01:55:45 -0700 (PDT) From: Pantelis Antoniou To: Tom Rini Date: Fri, 11 Aug 2017 11:52:44 +0300 Message-Id: <1502441568-22896-7-git-send-email-pantelis.antoniou@konsulko.com> X-Mailer: git-send-email 2.1.4 In-Reply-To: <1502441568-22896-1-git-send-email-pantelis.antoniou@konsulko.com> References: <1502441568-22896-1-git-send-email-pantelis.antoniou@konsulko.com> Cc: Marek Vasut , Tero Kristo , u-boot@lists.denx.de, Franklin S Cooper Jr , Maxime Ripard , Stefan Roese , Alan Ott Subject: [U-Boot] [PATCH v2 06/10] doc: overlays: Tweak documentation regarding overlays 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" From: Franklin S Cooper Jr 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 Reviewed-by: Simon Glass --- 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 ------------------------------