From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-12.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,NICE_REPLY_A,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED, USER_AGENT_SANE_1 autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 034D5C432BE for ; Sat, 28 Aug 2021 13:30:32 +0000 (UTC) Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 0DFD160ED3 for ; Sat, 28 Aug 2021 13:30:30 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 0DFD160ED3 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=gmx.de Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=lists.denx.de Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 2B51A832E8; Sat, 28 Aug 2021 15:30:29 +0200 (CEST) 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="dF1+7g6Q"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 5361A832E8; Sat, 28 Aug 2021 15:30:27 +0200 (CEST) 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 051C183130 for ; Sat, 28 Aug 2021 15:30:22 +0200 (CEST) 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=1630157421; bh=Vh3Il53NzrPjEPc7CTC2lDp54MJzbX9MlxwqSGK5+aI=; h=X-UI-Sender-Class:Subject:To:Cc:References:From:Date:In-Reply-To; b=dF1+7g6QuLC73DxQFZwAyhdDLiuHBDwhvQi2hJW6xdwNL7HpbMAfFetwyOgIcLXGJ TFcW/Tv56vgDH0gfbH0rAKo5GFxn372tw4XeAG7Ec6MawkHRMbIIGS40p9ApjOwZeD 3o3HF/4mWH1Du4OVRwTeqZwnhHDVAhzY48mlWh6M= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from [192.168.0.189] ([88.152.144.157]) by mail.gmx.net (mrgmx004 [212.227.17.190]) with ESMTPSA (Nemesis) id 1MKKZ3-1maGCx3G4l-00LpMQ; Sat, 28 Aug 2021 15:30:20 +0200 Subject: Re: [PATCH] doc: Add documentation about devicetree usage To: Tom Rini Cc: Simon Glass , Mark Kettenis , Sean Anderson , Bin Meng , U-Boot Mailing List , Ilias Apalodimas References: <20210828032348.4570-1-sjg@chromium.org> <20210828130151.GZ858@bill-the-cat> From: Heinrich Schuchardt Message-ID: Date: Sat, 28 Aug 2021 15:30:15 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.13.0 MIME-Version: 1.0 In-Reply-To: <20210828130151.GZ858@bill-the-cat> Content-Type: text/plain; charset=windows-1252; format=flowed Content-Language: en-US Content-Transfer-Encoding: quoted-printable X-Provags-ID: V03:K1:n7mBWdZoQsJ6DktGwTm71AvojmJzwIq5Cek121j5vLe2fw0DRvB Sv1RozE+AIOYbGULT2EJQamdp54SgwKm8vWo7LzZfgIoCKQUCXqgcWdXTDsYYRUsCoDU/U8 HfA3a7E2kwu1qEJ875akvUAN+rbE27363NRncOZNveKyqmRoLquiGSz+GoWoYNq1maPl6Jn z2aG/2GuFeTCfSeIaPUVg== X-UI-Out-Filterresults: notjunk:1;V03:K0:PSBQSiV9VAU=:YG/kmuGl9+CcnSr7pFPikI 9lz4q776xUXqYtbrfQTE6GyvQjPEj4FCnW64RuWiNkDT1z+yLEl4/wUmycZ3GjkzqHT1kXe2i VzRujGXOU8NupITir4oSayyYD0gfg5hqHB5I6+a9VbU63aPgKXz4N1t44DufDDwSamQBPkxlm sPcV1J6M7Y59oexrTpCDa3WdkJKRhDL5p4FMY58oEI3YMIGbnnlj6fuxXLHIn00Lq1PjWrf7A w6awGILaRXMQ8H+Y7XmP4YIsxDfxbEgqAIN2rBJuOlfoyGYXHbOLcjkaRUcemCVDjKWYdsNjg GYugaHjMkTUFTi6nysVOctjFNF4wdydERgOYSF0fmY7VWxVPUoCCpl4qWW636E7jvYZK2Bxb1 4YIFOF2gxRUfH5Z8D/MU2zzUGAd5M8s3QyhxtHrQmVp5eZ0wcVqJ0RczAxbIvR607jZaK8FZ6 GAhfy5vS+zlMD49Wuqc/49Tmoye5fOXMhbc8XNwGVhDVwcwIH8bN3A9wX7VYB3epEpQki4uAY To9YttqU20myRXqpFCRGLDO/YnViniSY2Kd1mSBlJhwzf7Jx36GjRmax2w7Jsv1he9Xv7Gbpk 23CHipcH0mvH2YyWWR1Hhl7C66glcTwU1pphbqEF/GAgEQYskszGqsh136zAkjqeoHSN9syKJ 2Yvwx83n6bL5TG1dhxfk5W1vFPQNGop7rO2tq+Vq96sG3zL1Qiks9qSCsdU28OgWLV0yEjYL8 OoDNNIFdHRkLmWDJZ8N7RoqReJsg4A7WAw4bGLcv+tV/w/EIulYMVwViMQeNoWcA1Gvka/j1m aeho2hvATFc11UkRAflcWk1MFSjAoaOifNBwgxoTWayVn2s3Kut0wcQaJnpepZaqo0BR0jCqd gSmHuYEJ9C2F+TKkIcvEJkVmneD1pO4ExMsaIxlFLuBF83JiK8ZevJSAOPlIc1NSAVJ2M+CgY t8qbVRlT5WdBmIlpHj5x0wtY+As4ueafvbTtknObc6coZwO66P9cuSL0SdNw50QenkWfUXdu5 L8GjVngALq3CkA2MQC+3s1EZe69comk2d3Lnxc3dv83CkvTP+uYlMHk7vUSGQZG7MWVAout5K kHiGc/untMkx/X7/zS/zd7oR5Ab4PAdesw/hZLpIoxmcR6LO5tH/xu6oQ== 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.103.2 at phobos.denx.de X-Virus-Status: Clean On 8/28/21 3:01 PM, Tom Rini wrote: > On Sat, Aug 28, 2021 at 02:29:21PM +0200, Heinrich Schuchardt wrote: >> On 8/28/21 5:23 AM, Simon Glass wrote: >>> At present some of the ideas and techniques behind devicetree in U-Boo= t >>> are assumed, implied or unsaid. Add some documentation to cover how >>> devicetree is build, how it can be modified and the rules about using >>> the various CONFIG_OF_... options. >>> >>> Signed-off-by: Simon Glass >>> --- >>> >>> doc/develop/index.rst | 1 + >>> doc/develop/package/devicetree.rst | 315 ++++++++++++++++++++++++++= +++ >>> doc/develop/package/index.rst | 1 + >>> 3 files changed, 317 insertions(+) >>> create mode 100644 doc/develop/package/devicetree.rst >>> >>> diff --git a/doc/develop/index.rst b/doc/develop/index.rst >>> index 83c929babda..d5ad8f9fe53 100644 >>> --- a/doc/develop/index.rst >>> +++ b/doc/develop/index.rst >>> @@ -36,6 +36,7 @@ Packaging >>> :maxdepth: 1 >>> >>> package/index >>> + package/devicetree >>> >>> Testing >>> ------- >>> diff --git a/doc/develop/package/devicetree.rst b/doc/develop/package/= devicetree.rst >>> new file mode 100644 >>> index 00000000000..fccbb182f3e >>> --- /dev/null >>> +++ b/doc/develop/package/devicetree.rst >>> @@ -0,0 +1,315 @@ >>> +.. SPDX-License-Identifier: GPL-2.0+ >>> + >>> +Updating the devicetree >>> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D >>> + >>> +U-Boot uses devicetree for runtime configuration and storing required= blobs or >>> +any other information it needs to operate. It is possible to update t= he >>> +devicetree separately from actually building U-Boot. This provides a = good degree >>> +of control and flexibility for firmware that uses U-Boot in conjuncti= on with >>> +other project. >>> + >>> +There are many reasons why it is useful to modify the devicetree afte= r building >>> +it: >>> + >>> +- Configuration can be changed, e.g. which UART to use >>> +- A serial number can be added >>> +- Public keys can be added to allow image verification >>> +- Console output can be changed (e.g. to select serial or vidconsole) >>> + >>> +This section describes how to work with devicetree to accomplish your= goals. >>> + >>> +See also :doc:`../devicetree/control` for a basic summary of the avai= lable >>> +features. >>> + >>> + >>> +Devicetree source >>> +----------------- >>> + >>> +Every board in U-Boot must include a devicetree sufficient to build a= nd boot >>> +that board on suitable hardware (or emulation). This is specified usi= ng the >>> +`CONFIG DEFAULT_DEVICE_TREE` option. >>> + >>> + >>> +Current situation (August 2021) >>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ >>> + >>> +As an aside, at present U-Boot allows `CONFIG_DEFAULT_DEVICE_TREE` to= be empty, >>> +e.g. if `CONFIG_OF_BOARD` or `CONFIG_OF_PRIOR_STAGE` are used. This h= as >>> +unfortunately created an enormous amount of confusion and some wasted= effort. >>> +This was not intended and this bug will be fixed soon. Specifically: >>> + >>> +- `CONFIG_OF_BOARD` was added in rpi_patch_ for Raspberry Pi, which d= oes have >>> + an in-tree devicetree, but this feature has since been used for boa= rds that >>> + don't >>> +- `CONFIG_OF_PRIOR_STAGE` was added in bcm_patch_ as part of a larger= Broadcom >>> + change with a tag indicating it only affected one board, so the cha= nge in >>> + behaviour was not noticed at the time. It has since been used by RI= SC-V qemu >>> + boards. >>> + >>> +Once this bug is fixed, CONFIG_OF_BOARD and CONFIG_OF_PRIOR_STAGE wil= l override >>> +(at runtime) the devicetree suppled with U-Boot, but will otherwise u= se >>> +CONFIG_OF_SEPARATE for the in-tree build. So these two will become op= tions, >>> +moving out of the 'choice' in `dts/Kconfig` >>> + >>> +Offending boards are: >>> + >>> +- bcm7260 >>> +- bcm7445 >>> +- qemu_arm64 >>> +- qemu_arm >>> +- qemu-ppce500 >>> +- qemu-riscv32 >>> +- qemu-riscv32_smode >>> +- qemu-riscv64 >>> +- qemu-riscv64_smode >>> + >>> +All of these need to have a devicetree added in-tree. This is targete= d to be >>> +fixed in the 2022.01 release. >>> + >>> + >>> +Building the devicetree >>> +----------------------- >>> + >>> +U-Boot automatically builds the devicetree for a board, from the >>> +`arch//dts` directory. The Makefile in those directories has ru= les for >>> +building devicetree files. It is preferable to avoid target-specific = rules in >>> +those files: i.e. all boards for a particular SoC should be built at = once, >>> +where practical. Apart from simplifying the Makefile, this helps to e= fficiently >>> +(and immediately) ensure that changes in one board's DT do not break = others that >>> +are related. Building devicetrees is fast, so performance is seldom a= concern >>> +here. >>> + >>> + >>> +Overriding the default devicetree >>> +--------------------------------- >>> + >>> +When building U-Boot, the `DEVICE_TREE` environment variable allows t= he >>> +default devicetree file to be overridden at build time. This can be u= seful if >>> +modifications have to be made to the in-tree devicetree file, for the= benefit >>> +of a downstream build system. Note that the in-tree devicetree must b= e >>> +sufficient to build and boot, so this is not a way to bypass that req= uirement. >>> + >>> + >>> +Modifying the devicetree after building >>> +--------------------------------------- >>> + >>> +While it is generally painful and hacky to modify the code or rodata = of a >>> +program after it is built, in many cases it is useul to do so, e.g. t= o add >>> +configuration information like serial numbers, enabling/disabling fea= tures, etc. >>> + >>> +Devicetree provides a very nice solution to these problems since it i= s >>> +structured data and it is relatively easy to change it, even in binar= y form >>> +(see fdtput). >>> + >>> +U-Boot takes care that the devicetree is easily accessible after the = build >>> +process. In fact it is placed in a separate file called `u-boot.dtb`.= If the >>> +build system wants to modify or replace that file, it can do so. Then= all that >>> +is needed is to run `binman update` to update the file inside the ima= ge. If >>> +binman is not used, then `u-boot-nodtb.bin` and the new `u-boot.dtb` = can simply >>> +be concatenated to achieve the desired result. U-Boot happily copes w= ith the >>> +devicetree growing or shrinking. >>> + >>> +The `u-boot.bin` image contains both pieces. While it is possible to = locate the >>> +devicetree within the image using the signature at the start of the f= ile, this >>> +is a bit messy. >>> + >>> +This is why `CONFIG_OF_SEPARATE` should always be used when building = U-Boot. >>> +The `CONFIG_OF_EMBED` option embeds the devicetree somewhere in the U= -Boot ELF >>> +image as rodata, meaning that it is hard to find it and it cannot inc= rease in >>> +size. >>> + >>> +When modifying the devicetree, the different cases to consider are as= follows: >>> + >>> +- CONFIG_OF_SEPARATE >>> + This is easy, described above. Just change, replace or rebuild th= e >>> + devicetree so it suits your needs, then rerun binman or redo the = `cat` >>> + operation to join `u-boot-nodtb.bin` and the new `u-boot.dtb` >>> + >>> +- CONFIG_OF_EMBD >>> + This is tricky, since the devicetree cannot easily be located. If= the EFL >>> + file is available, then the _dtb_dt_begin and __dtb_dt_end symbol= s can be >>> + examined to find it. While it is possible to contract the file, i= t is not >>> + possible to expand the file since that would involve re-linking >>> + >>> +- CONFIG_OF_PRIOR_STAGE >>> + In this case the devicetree must be modified in the project which= provides >>> + it, as described below >>> + >>> +- CONFIG_OF_BOARD >>> + This is a board-specific situation, so needs to be considered on = a >>> + case-by-case base. The devicetree must be modified so that the co= rrect >>> + one is provided to U-Boot. How this is done depends entirely on t= he >>> + implementation of this option for the board. It might require inj= ecting the >>> + changes into a different project somehow using tooling available = there, or >>> + it might involve merging an overlay file at runtime to obtain the= desired >>> + result. >>> + >>> + >>> +Devicetree in another project >>> +----------------------------- >>> + >>> +In some cases U-Boot receive its devicetree at runtime from a program= that calls >>> +it. For example ARM's Trusted Firmware A (`TF-A`_) may have a devicet= ree that it >>> +passes to U-Boot. This overrides any devicetree build by U-Boot. When= packaging >>> +the firmware, the U-Boot devicetree may in fact be left out if it can= be >>> +guaranteed that it will receive one from another project. >>> + >>> +In this case, the devicetree in the other project must track U-Boot's= use of >>> +device tree. It must provide a way to add configuration and other inf= ormation to >> >> U-Boot does not rule the world. So never ever is this going to happen. >> It is the other way round. U-Boot must consume what the prior bootstage >> delivers. If U-Boot needs extra nodes it has to provide these on its ow= n. >> >> Please, remove this assumption from the document. > > We need to figure out which compatibles we need to push upstream, and > which we need to see if we can solve another way. > >>> +the devicetree for use by U-Boot, such as the /config node. Note that= the >>> +U-Boot in-tree devicetree must be sufficient to build and boot, so th= is is not a >>> +way to bypass that requirement. >>> + >>> +If binman is used, the in-tree U-Boot devicetree must contain the bin= man >>> +definition so that a valid image can be build. >> >> No clue what an in-tree tree might be. Please, avoid such confusing >> language. > > Would "source tree devicetree" be less confusing? Or can you suggest an > alternative? > >> >>> + >>> +If verified boot is used, the project must provide a way to inject a = public key, >> >> %s/the project/U-Boot/ >> >>> +certificate or other material into the U-Boot devicetree so that it i= s available >>> +to U-Boot at runtime. See `Signing with U-Boot devicetree`_. This may= be >>> +through tooling in the project itself or by making use of U-Boot's to= oling. >>> + >>> + >>> +Devicetree generated on-the-fly in another project >>> +-------------------------------------------------- > > I think this is a confusing topic, and gets things a bit backwards. > >>> + >>> +In some rare cases, another project may wish to create a devicetree f= or U-Boot >>> +entirely on-the-fly, then pass it to U-Boot at runtime. The only know= n example >>> +of this at the time of writing (2021) is qemu, for ARM (`QEMU ARM`_) = and >>> +RISC-V (`QEMU RISC-V`_). > > What's the difference between QEMU and hardware that ships with a device > tree stored in flash? In both cases, we need to have the device tree > that's provided be the device tree that works. Like I was just raising > in another thread, there are not multiple device trees for a given > device, there is the device tree and it works for everyone that needs to > consume a device tree. > >>> +In this case, the devicetree in the other project must track U-Boot's= use of >>> +device tree, so that it remains compatible. If a particular version o= f the >> >> Why? U-Boot must support its internal needs itself! >> >> Don't try to force a bad U-Boot design on other projects. >> >> Please, come up with a concept that makes sense. > > This is the same situation as above, where we need to see about pushing > some changes upstream perhaps. > In U-Boot we currently have a lot of device-tree nodes that are irrelevant for anything but U-Boot, e.g. all those nodes marked as compatible to "u-boot,*". It does not make sense to push these upstream. So if a prior bootstage provides a devicetree, we need a separate devicetree in U-Boot. We can copy the incoming devicetree to a private copy and amend all our U-Boot specific stuff. Then let's use this private copy for $fdt_control_addr and bringing up U-Boot while keeping the original incoming devicetree as $fdt_addr so that we can pass it to the next boot stage. Best regards Heinrich