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.2 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,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 257EBC432BE for ; Sat, 28 Aug 2021 13:39:53 +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 5064A60ED3 for ; Sat, 28 Aug 2021 13:39:52 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 5064A60ED3 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 AFA668317A; Sat, 28 Aug 2021 15:39:50 +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="nhkiJnd4"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id C76C9832CE; Sat, 28 Aug 2021 15:39:49 +0200 (CEST) Received: from mail-qv1-xf2f.google.com (mail-qv1-xf2f.google.com [IPv6:2607:f8b0:4864:20::f2f]) (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 C9EB083130 for ; Sat, 28 Aug 2021 15:39:44 +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-qv1-xf2f.google.com with SMTP id v1so5700730qva.7 for ; Sat, 28 Aug 2021 06:39:44 -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=Ushrn+rxBpnJi00KI8pmB9Sa/CawPfMeteVT9eNCsxQ=; b=nhkiJnd4pV7YlZ2aor4ydGswzZ1fI00A8y2FzkU+R6dHFheI1J5uQnYXjHvuAwtODy Ci3+W4EmogG1ImClivbceTeWabsto2n/h7QfSlLcYWA1KXSfW6Fm9UC22tLTj+SIS9vC 7vb1z5hphxttxlxADh/EQ2g20frZ8GpG1R1ng= 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=Ushrn+rxBpnJi00KI8pmB9Sa/CawPfMeteVT9eNCsxQ=; b=U2qU1Tx2XMF6iebi4xJ0YU6+2SdUkCSbxhY+6tkZF/yAVrtD3BTy47thttvjJ+M1uy hHVjjjop80YI2iOPQedAsifhWMdc7pfvD3Uj/VWi2oZXzorACbUgPtglejzG1B/svVjO qbY6onTnhDawvxuL6m7z7unxo6BlstKEJZP1C3sqbsMDLhcRhTz0uv0++2f5Lkp7q23m /oTdji7WFavh6p2GHO2tL0zWBkKAQFvEL8p+ckVxD17MUGnJL8oeCYVWgp1/tn6QP+9G +svEzXzPL/01/9W0xBTuDPRR2uWC5RzdjICbXfKRhVxU0fLRkzg2aVX/e19xfvKF8Rni bFjQ== X-Gm-Message-State: AOAM532C1VGvsNX70w25EmfHtm4gH/gV8XuhwZyqoTK5sfhAwr9fuD4s SK04iCCDBusH327cZhLwNnW7lA== X-Google-Smtp-Source: ABdhPJzvPTPHN8BhVvftC+5lAW2VUsbgUZlYFA24mfrpRbDGP1RWedmoTJsgkLoV7TEEm/qasXItBw== X-Received: by 2002:a0c:aa52:: with SMTP id e18mr11775460qvb.38.1630157983191; Sat, 28 Aug 2021 06:39:43 -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 v128sm7077886qkh.27.2021.08.28.06.39.41 (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Sat, 28 Aug 2021 06:39:42 -0700 (PDT) Date: Sat, 28 Aug 2021 09:39:40 -0400 From: Tom Rini To: Heinrich Schuchardt Cc: Simon Glass , Mark Kettenis , Sean Anderson , Bin Meng , U-Boot Mailing List , Ilias Apalodimas Subject: Re: [PATCH] doc: Add documentation about devicetree usage Message-ID: <20210828133940.GA858@bill-the-cat> References: <20210828032348.4570-1-sjg@chromium.org> <20210828130151.GZ858@bill-the-cat> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="rJ7gvdN+6ch6txCD" 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 --rJ7gvdN+6ch6txCD Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sat, Aug 28, 2021 at 03:30:15PM +0200, Heinrich Schuchardt wrote: > 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-= Boot > > > > are assumed, implied or unsaid. Add some documentation to cover how > > > > devicetree is build, how it can be modified and the rules about usi= ng > > > > 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/packa= ge/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 requi= red blobs or > > > > +any other information it needs to operate. It is possible to updat= e the > > > > +devicetree separately from actually building U-Boot. This provides= a good degree > > > > +of control and flexibility for firmware that uses U-Boot in conjun= ction with > > > > +other project. > > > > + > > > > +There are many reasons why it is useful to modify the devicetree a= fter 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 vidconso= le) > > > > + > > > > +This section describes how to work with devicetree to accomplish y= our goals. > > > > + > > > > +See also :doc:`../devicetree/control` for a basic summary of the a= vailable > > > > +features. > > > > + > > > > + > > > > +Devicetree source > > > > +----------------- > > > > + > > > > +Every board in U-Boot must include a devicetree sufficient to buil= d and boot > > > > +that board on suitable hardware (or emulation). This is specified = using 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. Thi= s has > > > > +unfortunately created an enormous amount of confusion and some was= ted effort. > > > > +This was not intended and this bug will be fixed soon. Specificall= y: > > > > + > > > > +- `CONFIG_OF_BOARD` was added in rpi_patch_ for Raspberry Pi, whic= h does have > > > > + an in-tree devicetree, but this feature has since been used for = boards that > > > > + don't > > > > +- `CONFIG_OF_PRIOR_STAGE` was added in bcm_patch_ as part of a lar= ger Broadcom > > > > + change with a tag indicating it only affected one board, so the = change in > > > > + behaviour was not noticed at the time. It has since been used by= RISC-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 otherwis= e use > > > > +CONFIG_OF_SEPARATE for the in-tree build. So these two will become= options, > > > > +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 targ= eted 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= rules for > > > > +building devicetree files. It is preferable to avoid target-specif= ic 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 t= o efficiently > > > > +(and immediately) ensure that changes in one board's DT do not bre= ak others that > > > > +are related. Building devicetrees is fast, so performance is seldo= m a concern > > > > +here. > > > > + > > > > + > > > > +Overriding the default devicetree > > > > +--------------------------------- > > > > + > > > > +When building U-Boot, the `DEVICE_TREE` environment variable allow= s the > > > > +default devicetree file to be overridden at build time. This can b= e useful 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 mus= t be > > > > +sufficient to build and boot, so this is not a way to bypass that = requirement. > > > > + > > > > + > > > > +Modifying the devicetree after building > > > > +--------------------------------------- > > > > + > > > > +While it is generally painful and hacky to modify the code or roda= ta of a > > > > +program after it is built, in many cases it is useul to do so, e.g= =2E to add > > > > +configuration information like serial numbers, enabling/disabling = features, etc. > > > > + > > > > +Devicetree provides a very nice solution to these problems since i= t is > > > > +structured data and it is relatively easy to change it, even in bi= nary form > > > > +(see fdtput). > > > > + > > > > +U-Boot takes care that the devicetree is easily accessible after t= he build > > > > +process. In fact it is placed in a separate file called `u-boot.dt= b`. If the > > > > +build system wants to modify or replace that file, it can do so. T= hen all that > > > > +is needed is to run `binman update` to update the file inside the = image. If > > > > +binman is not used, then `u-boot-nodtb.bin` and the new `u-boot.dt= b` can simply > > > > +be concatenated to achieve the desired result. U-Boot happily cope= s with 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 th= e file, this > > > > +is a bit messy. > > > > + > > > > +This is why `CONFIG_OF_SEPARATE` should always be used when buildi= ng U-Boot. > > > > +The `CONFIG_OF_EMBED` option embeds the devicetree somewhere in th= e U-Boot ELF > > > > +image as rodata, meaning that it is hard to find it and it cannot = increase 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 t= he `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 sym= bols 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 wh= ich 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= correct > > > > + one is provided to U-Boot. How this is done depends entirely o= n the > > > > + implementation of this option for the board. It might require = injecting the > > > > + changes into a different project somehow using tooling availab= le 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 prog= ram that calls > > > > +it. For example ARM's Trusted Firmware A (`TF-A`_) may have a devi= cetree that it > > > > +passes to U-Boot. This overrides any devicetree build by U-Boot. W= hen 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-Boo= t's use of > > > > +device tree. It must provide a way to add configuration and other = information 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 bootsta= ge > > > delivers. If U-Boot needs extra nodes it has to provide these on its = own. > > >=20 > > > Please, remove this assumption from the document. > >=20 > > We need to figure out which compatibles we need to push upstream, and > > which we need to see if we can solve another way. > >=20 > > > > +the devicetree for use by U-Boot, such as the /config node. Note t= hat the > > > > +U-Boot in-tree devicetree must be sufficient to build and boot, so= this is not a > > > > +way to bypass that requirement. > > > > + > > > > +If binman is used, the in-tree U-Boot devicetree must contain the = binman > > > > +definition so that a valid image can be build. > > >=20 > > > No clue what an in-tree tree might be. Please, avoid such confusing > > > language. > >=20 > > Would "source tree devicetree" be less confusing? Or can you suggest an > > alternative? > >=20 > > >=20 > > > > + > > > > +If verified boot is used, the project must provide a way to inject= a public key, > > >=20 > > > %s/the project/U-Boot/ > > >=20 > > > > +certificate or other material into the U-Boot devicetree so that i= t 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= tooling. > > > > + > > > > + > > > > +Devicetree generated on-the-fly in another project > > > > +-------------------------------------------------- > >=20 > > I think this is a confusing topic, and gets things a bit backwards. > >=20 > > > > + > > > > +In some rare cases, another project may wish to create a devicetre= e for U-Boot > > > > +entirely on-the-fly, then pass it to U-Boot at runtime. The only k= nown example > > > > +of this at the time of writing (2021) is qemu, for ARM (`QEMU ARM`= _) and > > > > +RISC-V (`QEMU RISC-V`_). > >=20 > > 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. > >=20 > > > > +In this case, the devicetree in the other project must track U-Boo= t's use of > > > > +device tree, so that it remains compatible. If a particular versio= n 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. > >=20 > > This is the same situation as above, where we need to see about pushing > > some changes upstream perhaps. > >=20 >=20 > 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. >=20 > So if a prior bootstage provides a devicetree, we need a separate > devicetree in U-Boot. >=20 > 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. I'm not sure that's how this works? The "linux" vendor prefix is for Linux specific bindings and are expected to be present in the tree it receives, and not fixed up and added at runtime. But if you can proof of concept out what your idea, I suspect that would work to resolve a handful of problems all the same, so it would be good to see. --=20 Tom --rJ7gvdN+6ch6txCD Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQGzBAABCgAdFiEEGjx/cOCPqxcHgJu/FHw5/5Y0tywFAmEqPJgACgkQFHw5/5Y0 tyydSAv/UXaMRCiTkyL5jg2yhVLeZlbJ2YN1pgbFGRXOf/k/ZL8sB8oPc3JdjKgz 6YX+5qw+UaD0c/OoReTu2rOQMMf4ktS14HxGls4F3KxSpkg1Vyr31TwbDKCIVRd7 RezBXwKfEvw8uTt8EaiOCB3HDCcZxxhSXpA30SxSfqAducNdCusFQnIwU1/zi7+h qM4+vNOvw57cqJPLXiMFcyZmTrPKJgpQWFPtJyB0AtMycCFlKigpU0QYEgdoZ+Bl 7zcV2L0h2bKwpMPXD1WchVeZlMrQdzKERR1v+MdnhFnJ18oum+e27eK1ITZH8tB8 2ofFODokUNrFYFjZz/AgAii8NvItldofffTev63623emCOYV5+tLRv/z/blZ9bYV hxxk1OOCaOWHIW0lQzZ2iNTNipDuR6/XvODdY5nu0jYCuz46uoWMCNysu0cMOSd1 hBAjp8r1EfMJwIiLqca1JxX+7Uk6HrEart725jrIZXOH3MQL+EbrsZEvqgsVpph2 OgbWB3kP =VySC -----END PGP SIGNATURE----- --rJ7gvdN+6ch6txCD--