{"id":809828,"url":"http://patchwork.ozlabs.org/api/1.0/patches/809828/?format=json","project":{"id":18,"url":"http://patchwork.ozlabs.org/api/1.0/projects/18/?format=json","name":"U-Boot","link_name":"uboot","list_id":"u-boot.lists.denx.de","list_email":"u-boot@lists.denx.de","web_url":null,"scm_url":null,"webscm_url":null},"msgid":"<1504555943-12893-11-git-send-email-pantelis.antoniou@konsulko.com>","date":"2017-09-04T20:12:19","name":"[U-Boot,v3,10/14] doc: overlays: Tweak documentation regarding overlays","commit_ref":null,"pull_url":null,"state":"accepted","archived":false,"hash":"4b80042c06269750dc95dadf651c135f125944de","submitter":{"id":64098,"url":"http://patchwork.ozlabs.org/api/1.0/people/64098/?format=json","name":"Pantelis Antoniou","email":"pantelis.antoniou@konsulko.com"},"delegate":{"id":3184,"url":"http://patchwork.ozlabs.org/api/1.0/users/3184/?format=json","username":"sjg","first_name":"Simon","last_name":"Glass","email":"sjg@chromium.org"},"mbox":"http://patchwork.ozlabs.org/project/uboot/patch/1504555943-12893-11-git-send-email-pantelis.antoniou@konsulko.com/mbox/","series":[{"id":1453,"url":"http://patchwork.ozlabs.org/api/1.0/series/1453/?format=json","date":"2017-09-04T20:12:09","name":"uboot overlays, FIT image & unittest","version":3,"mbox":"http://patchwork.ozlabs.org/series/1453/mbox/"}],"check":"pending","checks":"http://patchwork.ozlabs.org/api/patches/809828/checks/","tags":{},"headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":["ozlabs.org;\n\tspf=none (mailfrom) smtp.mailfrom=lists.denx.de\n\t(client-ip=81.169.180.215; helo=lists.denx.de;\n\tenvelope-from=u-boot-bounces@lists.denx.de;\n\treceiver=)","ozlabs.org;\n\tdkim=fail reason=\"signature verification failed\" (1024-bit key;\n\tunprotected) header.d=konsulko.com header.i=@konsulko.com\n\theader.b=\"eUq9pQMd\"; dkim-atps=neutral"],"Received":["from lists.denx.de (dione.denx.de [81.169.180.215])\n\tby ozlabs.org (Postfix) with ESMTP id 3xmLjx2Htkz9t2R\n\tfor ;\n\tTue, 5 Sep 2017 06:17:25 +1000 (AEST)","by lists.denx.de (Postfix, from userid 105)\n\tid 01609C21F6C; Mon, 4 Sep 2017 20:15:03 +0000 (UTC)","from lists.denx.de (localhost [IPv6:::1])\n\tby lists.denx.de (Postfix) with ESMTP id CF12FC21F53;\n\tMon, 4 Sep 2017 20:14:09 +0000 (UTC)","by lists.denx.de (Postfix, from userid 105)\n\tid 204DBC21EEC; Mon, 4 Sep 2017 20:13:13 +0000 (UTC)","from mail-wm0-f45.google.com (mail-wm0-f45.google.com\n\t[74.125.82.45])\n\tby lists.denx.de (Postfix) with ESMTPS id 68E6CC21E52\n\tfor ; Mon, 4 Sep 2017 20:13:10 +0000 (UTC)","by mail-wm0-f45.google.com with SMTP id f145so6736352wme.0\n\tfor ; Mon, 04 Sep 2017 13:13:10 -0700 (PDT)","from localhost.localdomain ([195.97.110.117])\n\tby smtp.gmail.com with ESMTPSA id\n\tu8sm3720435wrc.92.2017.09.04.13.13.08\n\t(version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128);\n\tMon, 04 Sep 2017 13:13:09 -0700 (PDT)"],"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,\n\tRCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL,\n\tT_DKIM_INVALID autolearn=unavailable\n\tautolearn_force=no version=3.4.0","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed; d=konsulko.com;\n\ts=google; \n\th=from:to:cc:subject:date:message-id:in-reply-to:references;\n\tbh=g/KkphTAvDDi0tu9cxlEmixs5gqcglv4O11q2vNIoPc=;\n\tb=eUq9pQMdP9FG0C+nZ0C/5OCGitxVdtVLnxcy+VaCzl++d72jVclzGtsh23I6Sdrv4x\n\tRloOJv4VsWFiwFc6F0HlE8yXYMK7vMthRA8nMB4fFX5xyCiaSAAPsMpE/CjW4YKuEh6H\n\tGkb6OF4lgLBPG/yfjqpsjzjQoo+bL5vyt68CU=","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20161025;\n\th=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to\n\t:references;\n\tbh=g/KkphTAvDDi0tu9cxlEmixs5gqcglv4O11q2vNIoPc=;\n\tb=U84juRjs5Xrt8lRT8W16LUtVxSauOZF3/cbeftSxucL/eznK30nqlPaCC/Du3qb8BU\n\tmIInn2/65lC9qIl1zGLpYYpmGHheFMY6Q2fsUVxZou8yxoSvvKHJpDVriLCjYQp/Y2uR\n\tHOMasZGdwIuDS4H+/CMsjPWuWAxGXBssxF0o9RwW2RJuvgirV5hYGhraiAY07mLG6ZUy\n\tXEUp7g/iK74N2IX82cEdLjulDOAt8kgz3t0lNfSnrB4RXLrewgTLhbUCF+XsbBIBsmW+\n\tLDnMlrF1FAgAESsQlcj72OXFCwcgcxgcq9bP5hLFATcXzjYbL58n5GfgggR9PyrvemO4\n\tmKkQ==","X-Gm-Message-State":"AHPjjUibBwfDZAGaIOvmHvrGpVnLDlnjJXX0HDa0W4qwIjMRkZIAqC53\n\tufKskDyXAbAGldwu","X-Google-Smtp-Source":"ADKCNb6+kszGZS077dLYzh8yFpKIcjO0paev7UScKK3zlF1ruVD21X6oFM/uLW+ekfivGObVILtJoQ==","X-Received":"by 10.28.93.146 with SMTP id r140mr868205wmb.133.1504555990075; \n\tMon, 04 Sep 2017 13:13:10 -0700 (PDT)","From":"Pantelis Antoniou ","To":"Tom Rini ","Date":"Mon, 4 Sep 2017 23:12:19 +0300","Message-Id":"<1504555943-12893-11-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 , Tero Kristo ,\n\tu-boot@lists.denx.de, Franklin S Cooper Jr ,\n\tMaxime Ripard ,\n\tStefan Roese , Alan Ott ","Subject":"[U-Boot] [PATCH v3 10/14] doc: overlays: Tweak documentation\n\tregarding overlays","X-BeenThere":"u-boot@lists.denx.de","X-Mailman-Version":"2.1.18","Precedence":"list","List-Id":"U-Boot discussion ","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","MIME-Version":"1.0","Content-Type":"text/plain; charset=\"utf-8\"","Content-Transfer-Encoding":"base64","Errors-To":"u-boot-bounces@lists.denx.de","Sender":"\"U-Boot\" "},"content":"From: Franklin S Cooper Jr \n\nPull some information regarding overlays from commit messages and\nput them directly within the documentation. Also add some information\nregarding required dtc version to properly use overlays.\n\nSigned-off-by: Franklin S Cooper Jr \n---\n doc/README.fdt-overlays | 85 +++++++++++++++++++++++++++++++++++--\n doc/uImage.FIT/overlay-fdt-boot.txt | 8 +++-\n 2 files changed, 87 insertions(+), 6 deletions(-)","diff":"diff --git a/doc/README.fdt-overlays b/doc/README.fdt-overlays\nindex ee868ec..39139cb 100644\n--- a/doc/README.fdt-overlays\n+++ b/doc/README.fdt-overlays\n@@ -1,9 +1,76 @@\n-U-Boot FDT Overlay usage (without FIT images)\n+U-Boot FDT Overlay usage\n =============================================\n \n-FDT overlays are now available for use even without FIT images.\n-It is not as automagic as with FIT images though and require a few\n-manual steps.\n+Overlays Syntax\n+---------------\n+\n+Overlays require slightly different syntax compared to traditional overlays.\n+Please refer to dt-object-internal.txt in the dtc sources for information\n+regarding the internal format of overlays:\n+https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/dt-object-internal.txt\n+\n+Building Overlays\n+-----------------\n+\n+In a nutshell overlays provides a means to manipulate a symbol a previous dtb\n+or overlay has defined. It requires both the base and all the overlays\n+to be compiled with the -@ command line switch so that symbol information is\n+included.\n+\n+Note support for -@ option can only be found in dtc version 1.4.4 or newer.\n+Only version 4.14 or higher of the Linux kernel includes a built in version\n+of dtc that meets this requirement.\n+\n+Building an overlay follows the same process as building a traditional dtb.\n+\n+For example:\n+\n+base.dts\n+--------\n+\n+\t/dts-v1/;\n+\t/ {\n+\t\tfoo: foonode {\n+\t\t\tfoo-property;\n+\t\t};\n+\t};\n+\n+\t$ dtc -@ -I dts -O dtb -o base.dtb base.dts\n+\n+bar.dts\n+-------\n+\n+\t/dts-v1/;\n+\t/plugin/;\n+\t/ {\n+\t\tfragment@1 {\n+\t\t\ttarget = <&foo>;\n+\t\t\t__overlay__ {\n+\t\t\t\toverlay-1-property;\n+\t\t\t\tbar: barnode {\n+\t\t\t\t\tbar-property;\n+\t\t\t\t};\n+\t\t\t};\n+\t\t};\n+\t};\n+\n+\t$ dtc -@ -I dts -O dtb -o bar.dtb bar.dts\n+\n+Ways to Utilize Overlays in U-boot\n+----------------------------------\n+\n+There are two ways to apply overlays in U-boot.\n+1. Include and define overlays within a FIT image and have overlays\n+ automatically applied.\n+\n+2. Manually load and apply overlays\n+\n+The remainder of this document will discuss using overlays via the manual\n+approach. For information on using overlays as part of a FIT image please see:\n+doc/uImage.FIT/overlay-fdt-boot.txt\n+\n+Manually Loading and Applying Overlays\n+--------------------------------------\n \n 1. Figure out where to place both the base device tree blob and the\n overlay. Make sure you have enough space to grow the base tree without\n@@ -29,6 +96,16 @@ overlapping anything.\n \n => fdt apply $fdtovaddr\n \n+6. Boot system like you would do with a traditional dtb.\n+\n+For bootm:\n+\n+=> bootm ${kerneladdr} - ${fdtaddr}\n+\n+For bootz:\n+\n+=> bootz ${kerneladdr} - ${fdtaddr}\n+\n Please note that in case of an error, both the base and overlays are going\n to be invalidated, so keep copies to avoid reloading.\n \ndiff --git a/doc/uImage.FIT/overlay-fdt-boot.txt b/doc/uImage.FIT/overlay-fdt-boot.txt\nindex dbdf2a1..63e47da 100644\n--- a/doc/uImage.FIT/overlay-fdt-boot.txt\n+++ b/doc/uImage.FIT/overlay-fdt-boot.txt\n@@ -1,5 +1,5 @@\n-U-Boot FDT Overlay usage\n-========================\n+U-Boot FDT Overlay FIT usage\n+============================\n \n Introduction\n ------------\n@@ -8,6 +8,10 @@ of similar boards and their expansion options. The same kernel on DT enabled\n platforms can support this easily enough by providing a DT blob upon boot\n that matches the desired configuration.\n \n+This document focuses on specifically using overlays as part of a FIT image.\n+General information regarding overlays including its syntax and building it\n+can be found in doc/README.fdt-overlays\n+\n Configuration without overlays\n ------------------------------\n \n","prefixes":["U-Boot","v3","10/14"]}