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,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 B3213C433F5 for ; Fri, 10 Sep 2021 17:18:51 +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 24A4D611C7 for ; Fri, 10 Sep 2021 17:18:50 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 24A4D611C7 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 6124A836CB; Fri, 10 Sep 2021 19:18:48 +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="p/AUKqW2"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id BA1C1836D7; Fri, 10 Sep 2021 19:18:46 +0200 (CEST) Received: from mail-qk1-x733.google.com (mail-qk1-x733.google.com [IPv6:2607:f8b0:4864:20::733]) (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 B0CB4836A2 for ; Fri, 10 Sep 2021 19:18:41 +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-qk1-x733.google.com with SMTP id w78so2733731qkb.4 for ; Fri, 10 Sep 2021 10:18:41 -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=iFZUU23JdRKMfbFrLmsCa4capopalgQl/I8xmcy6kpA=; b=p/AUKqW25ma4wEwUTfnaQYiirebj+12v+4+Y/gTU0ThBuEfSYdcClLNX3xgcPpHvDl NL8Z7f/OkNuzlsuMGvjWV/rMTaJJY6vhpxKsVt2Kv0PBOYLBsk60h/Q7Q7gNwsenY1Bi r10KMNCXbMaxe4CiuRr0R7cESj0r47VBhv3t0= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to:user-agent; bh=iFZUU23JdRKMfbFrLmsCa4capopalgQl/I8xmcy6kpA=; b=4z5UG9kanNn2ZRPquNRpOUL8bGw9Bz4rnm8F1db02n38fuEfG+UcfdxPxSbOC9RosL 43NHnNeS0gRq9R8jM1r7GOZ3fP94pefz8vc9brI+AVvZ5Y5pP3dW4KIbn8Y6HOoGEw7b RBHtDG8ED4eLM4liZMC9GBoX0NnI38RphiDQf+4RihLvjFiLyLHwajq9ysco9oIYsrSo tmX/8NA1tv3hD6Gkisunhfh9NkBaXhG/QCXnc0HA72IF3APKTsN/TVVnWdKun5ouxC/G Ur2UD276hhECS9Yx/88QX3mNc5AHJX+9LLovpDw7KCJZ8skIvhhEviCqB+by36ghBOCB fPnA== X-Gm-Message-State: AOAM530BVjBwc/vdya1GDzYS8fcylfxwnhR5TPZqHnx/NI1iAq47jEJX KSH4tOsOklkBxKWDCKUZ8ue0EQ== X-Google-Smtp-Source: ABdhPJxkcI350QjxlfxYWVBCiNQJT5xAcVXyzexxYTBOYsedQMzbsqFl3RkjZjQ2xm4saZiv5Mz7fg== X-Received: by 2002:a05:620a:20db:: with SMTP id f27mr8649673qka.496.1631294320264; Fri, 10 Sep 2021 10:18:40 -0700 (PDT) Received: from bill-the-cat (2603-6081-7b01-cbda-55fd-c014-b2c6-676a.res6.spectrum.com. [2603:6081:7b01:cbda:55fd:c014:b2c6:676a]) by smtp.gmail.com with ESMTPSA id z186sm4039272qke.59.2021.09.10.10.18.39 (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Fri, 10 Sep 2021 10:18:39 -0700 (PDT) Date: Fri, 10 Sep 2021 13:18:37 -0400 From: Tom Rini To: Heinrich Schuchardt Cc: Simon Glass , U-Boot Mailing List , Sean Anderson , Mark Kettenis , Ilias Apalodimas , =?iso-8859-1?Q?Fran=E7ois?= Ozog , Bill Mills , Marcel Ziswiler Subject: Re: [PATCH v3 3/3] RFC: doc: Add documentation about devicetree usage Message-ID: <20210910171837.GS12964@bill-the-cat> References: <20210909201033.755713-1-sjg@chromium.org> <20210909201033.755713-4-sjg@chromium.org> <20210910123420.GL12964@bill-the-cat> <20210910163725.GP12964@bill-the-cat> <633f58d5-4615-66d6-2875-9ee9a4492d4b@gmx.de> <20210910165756.GQ12964@bill-the-cat> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="pZtAG9wM4xcPQMtr" 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 --pZtAG9wM4xcPQMtr Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Fri, Sep 10, 2021 at 07:09:30PM +0200, Heinrich Schuchardt wrote: >=20 >=20 > On 9/10/21 6:57 PM, Tom Rini wrote: > > On Fri, Sep 10, 2021 at 06:50:16PM +0200, Heinrich Schuchardt wrote: > > >=20 > > >=20 > > > On 9/10/21 6:37 PM, Tom Rini wrote: > > > > On Fri, Sep 10, 2021 at 06:28:36PM +0200, Heinrich Schuchardt wrote: > > > > >=20 > > > > >=20 > > > > > On 9/10/21 2:34 PM, Tom Rini wrote: > > > > > > On Fri, Sep 10, 2021 at 10:38:17AM +0200, Heinrich Schuchardt w= rote: > > > > > > >=20 > > > > > > >=20 > > > > > > > On 9/9/21 10:10 PM, Simon Glass wrote: > > > > > > > > At present some of the ideas and techniques behind devicetr= ee in U-Boot > > > > > > > > are assumed, implied or unsaid. Add some documentation to c= over how > > > > > > > > devicetree is build, how it can be modified and the rules a= bout using > > > > > > > > the various CONFIG_OF_... options. > > > > > > > >=20 > > > > > > > > Signed-off-by: Simon Glass > > > > > > > > Reviewed-by: Marcel Ziswiler > > > > > > > > --- > > > > > > > >=20 > > > > > > > > Changes in v3: > > > > > > > > - Fix typos linst suppled receive EFL > > > > > > > > - Drop 'and' before 'self-defeating' > > > > > > > > - Reword mention of control of QEMU's devicetree generation > > > > > > > > - Add mention of dropping CONFIG_OF_BOARD > > > > > > > > - Clarify the 'Once this bug is fixed' paragraph a bit > > > > > > > > - Expand ways that CONFIG_OF_PRIOR_STAGE can support the U-= Boot devicetree > > > > > > > > - Add a note at the top explaining that his patch covers 'n= ow', not 'future' > > > > > > > > - Add note 'Note: Some boards use a devicetree in U-Boot wh= ich does not match' > > > > > > > >=20 > > > > > > > > Changes in v2: > > > > > > > > - Fix typos per Sean (thank you!) and a few others > > > > > > > > - Add a 'Use of U-Boot /config node' section > > > > > > > > - Drop mention of dm-verity since that actually uses the ke= rnel cmdline > > > > > > > > - Explain that OF_BOARD will still work after these changes= (in > > > > > > > > 'Once this bug is fixed...' paragraph) > > > > > > > > - Expand a bit on the reason why the 'Current situation' is= bad > > > > > > > > - Clarify in a second place that Linux and U-Boot use the s= ame devicetree > > > > > > > > in 'To be clear, while U-Boot...' > > > > > > > > - Expand on why we should have rules for other projects in > > > > > > > > 'Devicetree in another project' > > > > > > > > - Add a comment as to why devicetree in U-Boot is not 'bad = design' > > > > > > > > - Reword 'in-tree U-Boot devicetree' to 'devicetree source = in U-Boot' > > > > > > > > - Rewrite 'Devicetree generated on-the-fly in another proje= ct' to cover > > > > > > > > points raised on v1 > > > > > > > > - Add 'Why does U-Boot have its nodes and properties?' > > > > > > > > - Add 'Why not have two devicetrees?' > > > > > > > >=20 > > > > > > > > doc/develop/index.rst | 1 + > > > > > > > > doc/develop/package/devicetree.rst | 583 +++++++++++++= ++++++++++++++++ > > > > > > > > doc/develop/package/index.rst | 1 + > > > > > > > > 3 files changed, 585 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/devel= op/package/devicetree.rst > > > > > > > > new file mode 100644 > > > > > > > > index 00000000000..b1bd310d906 > > > > > > > > --- /dev/null > > > > > > > > +++ b/doc/develop/package/devicetree.rst > > > > > > > > @@ -0,0 +1,583 @@ > > > > > > > > +.. 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 > > > > > > > > + > > > > > > > > +Note: This documentation describes how things are today, m= ostly, with some > > > > > > > > +mention of things that need to be fixed. It is not intende= d to point the way to > > > > > > > > +what might be done in the future. That should be the subje= ct of discussions on > > > > > > > > +the mailing list. > > > > > > > > + > > > > > > > > +U-Boot uses devicetree for runtime configuration and stori= ng 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 good degree > > > > > > > > +of control and flexibility for firmware that uses U-Boot i= n conjunction with > > > > > > > > +other project. > > > > > > > > + > > > > > > > > +There are many reasons why it is useful to modify the devi= cetree 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 acco= mplish your goals. > > > > > > > > + > > > > > > > > +See also :doc:`../devicetree/control` for a basic summary = of the available > > > > > > > > +features. > > > > > > > > + > > > > > > > > + > > > > > > > > +Devicetree source > > > > > > > > +----------------- > > > > > > > > + > > > > > > > > +Every board in U-Boot must include a devicetree sufficient= to build and boot > > > > > > > > +that board on suitable hardware (or emulation). This is sp= ecified using the > > > > > > > > +`CONFIG DEFAULT_DEVICE_TREE` option. > > > > > > > > + > > > > > > > > + > > > > > > > > +Current situation (August 2021) > > > > > > > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > > > > > > > + > > > > > > > > +As an aside, at present U-Boot allows `CONFIG_DEFAULT_DEVI= CE_TREE` to be empty, > > > > > > > > +e.g. if `CONFIG_OF_BOARD` or `CONFIG_OF_PRIOR_STAGE` are u= sed. This has > > > > > > > > +unfortunately created an enormous amount of confusion and = some wasted effort. > > > > > > > > +This was not intended and this bug will be fixed soon. > > > > > > > > + > > > > > > > > +Some of the problems created are: > > > > > > > > + > > > > > > > > +- It is not obvious that the devicetree is coming from ano= ther project > > > > > > > > + > > > > > > > > +- There is no way to see even a sample devicetree for thes= e platform in U-Boot, > > > > > > > > + so it is hard to know what is going on, e.g. which devic= es are typically > > > > > > > > + present > > > > > > > > + > > > > > > > > +- The other project may not provide a way to support U-Boo= t's requirements for > > > > > > > > + devicetree, such as the /config node. Note: On the U-Boo= t mailing list, this > > > > > > > > + was only discovered after weeks of discussion and confus= ion > > > > > > > > + > > > > > > > > +- For QEMU specifically, consulting two QEMU source files = is required, for which > > > > > > > > + there are no references in U-Boot documentation. The cod= e is generating a > > > > > > > > + devicetree, with some control from command-line args, bu= t it is not clear > > > > > > > > + how to add properties required by U-Boot. > > > > > > > > + > > > > > > > > +Specifically on the changes in U-Boot: > > > > > > > > + > > > > > > > > +- `CONFIG_OF_BOARD` was added in rpi_patch_ for Raspberry = Pi, which does have > > > > > > > > + an in-tree devicetree, but this feature has since been u= sed for boards 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 change in > > > > > > > > + behaviour was not noticed at the time. It has since been= used by RISC-V qemu > > > > > > > > + boards. > > > > > > > > + > > > > > > > > +Note: It is not clear that we actually need both of these.= Possibly > > > > > > > > +`CONFIG_OF_BOARD` can be dropped. > > > > > > > > + > > > > > > > > +Once this bug is fixed, CONFIG_OF_BOARD and CONFIG_OF_PRIO= R_STAGE will override > > > > > > >=20 > > > > > > > What does "bug" refer to? Above you describe the current desi= gn not a bug. > > > > > >=20 > > > > > > The bug is that we have two options to provide seemingly the sa= me > > > > > > functionality. Is there a functional difference between CONFIG= _OF_BOARD > > > > > > and CONFIG_OF_PRIOR_STAGE ? > > > >=20 > > > > Does this clarify your question? > >=20 > > Again, does this clarify or answer your question? Please answer here, thanks. > > > > > > > > +(at runtime) the devicetree supplied with U-Boot, but will= otherwise use > > > > > > > > +CONFIG_OF_SEPARATE for the in-tree build. So these two wil= l become options, > > > > > > > > +moving out of the 'choice' in `dts/Kconfig`. To be clear, = the devicetree in the > > > > > > > > +U-Boot tree may be largely for documentation and build-tes= ting purposes, if at > > > > > > > > +runtime the devicetree if provided by another project. But= the in-tree > > > > > > > > +devicetree is packaged with U-Boot as a fallback if it doe= s not get one from a > > > > > > > > +prior stage at runtime. This does not create two devicetre= es that need to be > > > > > > > > +merged, or anything like that. If the prior stage provides= one, it is used as > > > > > > > > +is, with the one provided by U-Boot being ignored. > > > > > > > > + > > > > > > > > +This means that there is a basic devicetree build in the U= -Boot tree, for > > > > > > > > +build-testing, consistency and documentation purposes, but= at runtime U-Boot can > > > > > > > > +accept its devicetree from another source. > > > > > > >=20 > > > > > > > The incoming devicetree may not contain any U-Boot specific s= tuff. So > > > > > > > don't you need the buildtime devicetree for all of this infor= mation at > > > > > > > runtime? E.g. you were requesting to move certificate blobs i= nto the > > > > > > > build-time devicetree. > > > > > >=20 > > > > > > This is wrong because (a) no, there's no functional reason the = prior > > > > > > stage cannot populate / be pre-populated with what we need and = (b) we're > > > > > > documenting what we have today. > > > > >=20 > > > > > The problem is not functional but organizational. The prior boot = stage > > > > > may be burnt into PROM while U-Boot is on an SD-card. > > > > >=20 > > > > > Don't expect that on a board where you could install EDK II or U-= Boot or > > > > > anything else the prior boot stage cares about U-Boot. > > > > >=20 > > > > > How could a prior boot stage possibly know years ahead what is no= t even > > > > > yet supported in U-Boot when the prior boot stage is created? > > > >=20 > > > > I don't follow you, sorry. Or perhaps, if you %s/U-Boot/Linux/ the > > > > above, what's your answer then? > > >=20 > > > The boot ROM is burnt into the SoC at production. You don't want to > > > unsolder it if you don't like the devicetree in the boot ROM. > > >=20 > > > Equally there should be no need to replace TF-A when moving from U-Bo= ot > > > v2020.10 to v2040.10 during the lifetime of a car. > > >=20 > > > This is why we cannot expect anything from a prior boot stage but an > > > accurate description of the hardware and the prior boot stage itself. > >=20 > > OK. But again, %s/U-Boot/Linux/ and then what? Or are you saying the > > device tree that's burned in shouldn't be used for Linux either? >=20 > Linux is *not* requiring that depending on config options of Linux the > prior boot stage adds properties to the devicetree. That's an odd way to phrase it I think. Linux very much does require that you modify the device tree before passing it over, in order to enable support for hardware. > Linux does not require to add build specific objects like Linux module > signing keys to the devicetree. Only in that "secure boot" is handled by a seemingly dozen other methods instead. > In theory any newer Linux should boot with any device-tree that a prior > Linux version booted with. Theory and practice can and do differ. Things are better than they have been historically and the Linux Kernel folks do make a very strong effort to support the device tree as written in flash for the few cases that have done it. But there's still the allowed cases of flat out breaking the device tree (when it's incorrect in some way or another) or just not bothering (how a ton of legacy clock/etc information was handled on OMAP means that you just cannot use an older DT and newer kernel). > If U-Boot does the same I am fine. Will we put in as much effort as we can to support old DT + new U-Boot? Yes. But I think given my first two answers, that's not the part you're looking for here. --=20 Tom --pZtAG9wM4xcPQMtr Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQGzBAABCgAdFiEEGjx/cOCPqxcHgJu/FHw5/5Y0tywFAmE7k2oACgkQFHw5/5Y0 tyxI2Av/a5bGsByv9sha006zspalWDP44fLspB/R5L1tzGHZGCEyQM7P6soqD+eW 3QsgR5BugupJuc1HN5RKsBxKC3KCJmokY5vpBc3G8oHllB1wGdCPx4KiPW/O89bP HU2Yfcio64GK2ckuoH9lQXG1sgSdeEOb9fa2L/YotJUComyij8vZyhdGb2+qoxS9 1iuHu/kE4a2t47FgVy7Fg1x25S9vsrkrIQZ3ojCJTS84IMBIuDEey3h7+u+L+o92 vfVG+rx8dWTT2v7khOSwQmGQntFUHbYLXEc9Oo78WaYkhVCfPwxKhY5x2gZrWIth WpzvqBs7WU+GlavkwgcssbktVDmT8/BNv68ymMLhrb3OJ8VmJLKtrQIWeB7bYeEm fi/+YSXSpolqpyJcRHaMKXIxUtWdie3UL/DJuEqZd1299ex8lRXKljxyV0ZUzZKh HlOzI1dooFz6NYYYxPn4y+jGFJkazmQr0c4z5Mh+BihHjx+CE9boDfxEjUa9DTh7 DMrjUdHg =ZiJH -----END PGP SIGNATURE----- --pZtAG9wM4xcPQMtr--