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=-17.3 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,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 59795C432BE for ; Sat, 28 Aug 2021 13:02:07 +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 27562601FE for ; Sat, 28 Aug 2021 13:02:06 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 27562601FE Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=konsulko.com 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 2FDE7832E8; Sat, 28 Aug 2021 15:02:03 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=none (p=none dis=none) header.from=konsulko.com 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; unprotected) header.d=konsulko.com header.i=@konsulko.com header.b="ROuQv8Wm"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 8CD0E832EB; Sat, 28 Aug 2021 15:02:00 +0200 (CEST) Received: from mail-qt1-x834.google.com (mail-qt1-x834.google.com [IPv6:2607:f8b0:4864:20::834]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id CEB368317A for ; Sat, 28 Aug 2021 15:01:55 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=none (p=none dis=none) header.from=konsulko.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=trini@konsulko.com Received: by mail-qt1-x834.google.com with SMTP id d2so7647875qto.6 for ; Sat, 28 Aug 2021 06:01:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=konsulko.com; s=google; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to:user-agent; bh=/tWn8C4HzVs60g7IOYhpNQt2TnT7QOU10WX5FcQS9nI=; b=ROuQv8WmSoltF6/50GHDaugLhJ5g2IuBnDLmjt9F0pKaHN5SqETl6KURZZdP7yui+N DY61/xnN3m9+B3zJN167asBKdLv3/PgJOryJQ6Z0YI+kp4dfebGEa6zW+NczZofAgnJQ urwO4Vd/lOjfiXuefQBLbtHeZ4OBrTWzxS11w= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to:user-agent; bh=/tWn8C4HzVs60g7IOYhpNQt2TnT7QOU10WX5FcQS9nI=; b=DGF0EjGtiL6BAxKxdEi+5RoHQEZsRbPE5aYchKyx/v2PeeAli4lrIw1OcjlOHIFdt4 K/VmQckqODtaIGBRSK1cKHnVT90d1mrKoFspT9FRj4Sj0B+wOD156b5z2VLPnbllE8le GAiE6UZq2oKaKiaWNGIk61Wfdausgf+QyMX+6dM1gZqbB6qLiV2oKAHtI3Yx3XfzQigb Da12U8A4hBvy8WCzqKO+Fyq35ilPtTQ6BZ/amafwruMnTRVakqoPdidgcvu4tXDyugZG WEjturLvtdhwgj5KGs1rt9hWSNuZXzx9Ro3E+kOZv8Lwy9BoAPr8r/Zo7RAgRDqI2XCi KG0A== X-Gm-Message-State: AOAM532cZhkgNBuewY60IvTFidwQCNiM+ngO8BFodMlUfmqiAnGlF4d0 0ACObPW9d0ojVDKJnoO7SYs59w== X-Google-Smtp-Source: ABdhPJxGYRv2kbVz3ntrELSZEOeiyruuQEniAScO/GKATrvLXFzfMXFGCjGQHGV6a5/SbUGC+zHt9A== X-Received: by 2002:ac8:4454:: with SMTP id m20mr9286635qtn.64.1630155714219; Sat, 28 Aug 2021 06:01:54 -0700 (PDT) Received: from bill-the-cat (2603-6081-7b01-cbda-418f-a73c-75cc-f911.res6.spectrum.com. [2603:6081:7b01:cbda:418f:a73c:75cc:f911]) by smtp.gmail.com with ESMTPSA id j18sm6775207qke.75.2021.08.28.06.01.53 (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Sat, 28 Aug 2021 06:01:53 -0700 (PDT) Date: Sat, 28 Aug 2021 09:01:51 -0400 From: Tom Rini To: Heinrich Schuchardt Cc: Simon Glass , Mark Kettenis , Sean Anderson , Bin Meng , U-Boot Mailing List Subject: Re: [PATCH] doc: Add documentation about devicetree usage Message-ID: <20210828130151.GZ858@bill-the-cat> References: <20210828032348.4570-1-sjg@chromium.org> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="A17pC3c5I5+4reC+" Content-Disposition: inline In-Reply-To: X-Clacks-Overhead: GNU Terry Pratchett User-Agent: Mutt/1.9.4 (2018-02-28) 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 --A17pC3c5I5+4reC+ Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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-Boot > > 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. > >=20 > > Signed-off-by: Simon Glass > > --- > >=20 > > 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 > >=20 > > 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 > >=20 > > package/index > > + package/devicetree > >=20 > > Testing > > ------- > > diff --git a/doc/develop/package/devicetree.rst b/doc/develop/package/d= evicetree.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 the > > +devicetree separately from actually building U-Boot. This provides a g= ood degree > > +of control and flexibility for firmware that uses U-Boot in conjunctio= n with > > +other project. > > + > > +There are many reasons why it is useful to modify the devicetree after= 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 avail= able > > +features. > > + > > + > > +Devicetree source > > +----------------- > > + > > +Every board in U-Boot must include a devicetree sufficient to build an= d boot > > +that board on suitable hardware (or emulation). This is specified usin= g 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 has > > +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 do= es have > > + an in-tree devicetree, but this feature has since been used for boar= ds 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 chan= ge in > > + behaviour was not noticed at the time. It has since been used by RIS= C-V qemu > > + boards. > > + > > +Once this bug is fixed, CONFIG_OF_BOARD and CONFIG_OF_PRIOR_STAGE will= override > > +(at runtime) the devicetree suppled with U-Boot, but will otherwise use > > +CONFIG_OF_SEPARATE for the in-tree build. So these two will become opt= ions, > > +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 targeted= 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 rul= es for > > +building devicetree files. It is preferable to avoid target-specific r= ules in > > +those files: i.e. all boards for a particular SoC should be built at o= nce, > > +where practical. Apart from simplifying the Makefile, this helps to ef= ficiently > > +(and immediately) ensure that changes in one board's DT do not break o= thers 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 the > > +default devicetree file to be overridden at build time. This can be us= eful 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 be > > +sufficient to build and boot, so this is not a way to bypass that requ= irement. > > + > > + > > +Modifying the devicetree after building > > +--------------------------------------- > > + > > +While it is generally painful and hacky to modify the code or rodata o= f a > > +program after it is built, in many cases it is useul to do so, e.g. to= add > > +configuration information like serial numbers, enabling/disabling feat= ures, etc. > > + > > +Devicetree provides a very nice solution to these problems since it is > > +structured data and it is relatively easy to change it, even in binary= form > > +(see fdtput). > > + > > +U-Boot takes care that the devicetree is easily accessible after the b= uild > > +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 imag= e. If > > +binman is not used, then `u-boot-nodtb.bin` and the new `u-boot.dtb` c= an simply > > +be concatenated to achieve the desired result. U-Boot happily copes wi= th the > > +devicetree growing or shrinking. > > + > > +The `u-boot.bin` image contains both pieces. While it is possible to l= ocate the > > +devicetree within the image using the signature at the start of the fi= le, 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 incr= ease 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 the > > + 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 symbols= can be > > + examined to find it. While it is possible to contract the file, it= 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 cor= rect > > + one is provided to U-Boot. How this is done depends entirely on the > > + implementation of this option for the board. It might require inje= cting the > > + changes into a different project somehow using tooling available t= here, 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 devicetr= ee 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 info= rmation to >=20 > 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 own. >=20 > 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 thi= s is not a > > +way to bypass that requirement. > > + > > +If binman is used, the in-tree U-Boot devicetree must contain the binm= an > > +definition so that a valid image can be build. >=20 > 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? >=20 > > + > > +If verified boot is used, the project must provide a way to inject a p= ublic key, >=20 > %s/the project/U-Boot/ >=20 > > +certificate or other material into the U-Boot devicetree so that it is= 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 too= ling. > > + > > + > > +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 fo= r U-Boot > > +entirely on-the-fly, then pass it to U-Boot at runtime. The only known= example > > +of this at the time of writing (2021) is qemu, for ARM (`QEMU ARM`_) a= nd > > +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 of= the >=20 > Why? U-Boot must support its internal needs itself! >=20 > Don't try to force a bad U-Boot design on other projects. >=20 > 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. --=20 Tom --A17pC3c5I5+4reC+ Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQGzBAABCgAdFiEEGjx/cOCPqxcHgJu/FHw5/5Y0tywFAmEqM7QACgkQFHw5/5Y0 tyz96gv/TVRZoL4Ia6LFZ60ZgdoTT1e0yvnFjeJBLaQqMfQl/RwmRJFB0UmOkYXn U8V0sPlQpjZ82KTEHA6y2hsStS6cMCugIOuKvcv+9E+y5Z+WF2Wf/fZerrasaZjE AW9t1PduaIrj5+KOM1v2MTenFbTbt0l1v6TOW/fREwage+vshOXFKOU19tB8po+5 qg+h/IF9HucbA4Vk2xMVZYnJVoqOlk8hyH9ifH2Orbn3bVHFFQSt+bUfmLKK8jfo dfb5WqcEvbta71LMLR+0Ip0wMZZbkBS9BYsAlez6hF6RtrSWGZOCdycNMKWjgETJ jSek89GmEYjwup8+btVSnxnb32M4dVUyGw2BMHFSKpNwnaMLbxiu/TIEz+Drvn0l Wea1Du+Of2z8khmZMo3hQnbWiPOAXGhxS0Gf7ke/O9tdTRYhxfiUlXswY0WS9w8N RL08aFz7/2Sc5Cng2rYV5E4SD8JKiOdddpGjkdZ3Mkch3HYrYoTkSllf+30ecLGs 5922CtLR =y66D -----END PGP SIGNATURE----- --A17pC3c5I5+4reC+--