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 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 08FD2C433FE for ; Wed, 13 Oct 2021 12:55:54 +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 4FDC161056 for ; Wed, 13 Oct 2021 12:55:53 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 4FDC161056 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 638608357B; Wed, 13 Oct 2021 14:55:51 +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="a9ldpMdV"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 535D283569; Wed, 13 Oct 2021 14:55:49 +0200 (CEST) Received: from mail-qv1-xf34.google.com (mail-qv1-xf34.google.com [IPv6:2607:f8b0:4864:20::f34]) (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 23A0C82D7E for ; Wed, 13 Oct 2021 14:55: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-xf34.google.com with SMTP id z15so1569921qvj.7 for ; Wed, 13 Oct 2021 05:55: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; bh=dS0rqGSlwctWtNeBG4PXj2Ig/I7t+Z8D/ErIZLWQUsI=; b=a9ldpMdVYprbnmb/KTT63918KgLDomFOgriQ/NCFEnGX3ILKy3CXJVSVHIIkRqe84x ZPckWboE5ImH48rDRg/aHtpx5TZcZyPwqaYOMZkvqcR0shOuhKHSv9yeHobAKd1l0U1u +AvYImKNDo0wfYefq8l/7lAsiFoFnC1nGgBLw= 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; bh=dS0rqGSlwctWtNeBG4PXj2Ig/I7t+Z8D/ErIZLWQUsI=; b=wHlm6br0C0hTj1rYpYswb00Lk5gDcCbmXjbCczJgKDUiy/PiXBdbaiEVpZDVbiUB4V qVTdBqJ4/ngEBx2SFp6GzP0uJ3TjDNCqHuO2DAkH5fbWq2PSMJsI0CsqqNpiNEulaUb9 YqwZZ1KGZ8iv3KVBcWKYfhv4ljLqdxgmYIj2T5y0TRagDSsSYgfpIZi1ugmxKQWODj5u QIS1AT1ZvLtvGMVNQm7z8nOv8hk7fCbHTUJm9RBx5UxBrnE9CJCCKo0RZEgzo5PB1nq3 oRZ3Ybg7Dr08KKm3re/PTWly/WKY1H5uAWSOefheJTvlGeStaavdALup/5J15iuVD/qn xO2Q== X-Gm-Message-State: AOAM530QW9BJbihCpAW8ymq6DOVDti/x//H6lIgji1BpPlWtQhj/30BR Kp2XiO3OFR2DAr0sY1CHatzqZw== X-Google-Smtp-Source: ABdhPJyUnVm8Uu98YzL6sSrp2chBg3IONbvxq0rCtaFsgpeH6sHuyypug9MVhpYHMezFK9TIp5nGYw== X-Received: by 2002:a0c:ffa9:: with SMTP id d9mr37073108qvv.53.1634129742653; Wed, 13 Oct 2021 05:55:42 -0700 (PDT) Received: from bill-the-cat (2603-6081-7b01-cbda-e98d-c49f-f596-1fb5.res6.spectrum.com. [2603:6081:7b01:cbda:e98d:c49f:f596:1fb5]) by smtp.gmail.com with ESMTPSA id m68sm7404681qkb.105.2021.10.13.05.55.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 13 Oct 2021 05:55:41 -0700 (PDT) Date: Wed, 13 Oct 2021 08:55:39 -0400 From: Tom Rini To: =?iso-8859-1?Q?Fran=E7ois?= Ozog Cc: Bin Meng , Mark Kettenis , Rick Chen , Simon Glass , bill.mills@linaro.org, ilias.apalodimas@linaro.org, marcel.ziswiler@toradex.com, seanga2@gmail.com, u-boot@lists.denx.de, xypron.glpk@gmx.de Subject: Re: [PATCH v3 3/3] RFC: doc: Add documentation about devicetree usage Message-ID: <20211013125539.GK7964@bill-the-cat> References: <20210909201033.755713-4-sjg@chromium.org> <20210910123420.GL12964@bill-the-cat> <5614507a14906226@bloch.sibelius.xs4all.nl> <20210910211737.GB12964@bill-the-cat> <561450ac28c24b92@bloch.sibelius.xs4all.nl> <20210910224448.GD12964@bill-the-cat> <20210918131816.GM8579@bill-the-cat> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="LXXtuus8Blsk4XO4" Content-Disposition: inline In-Reply-To: X-Clacks-Overhead: GNU Terry Pratchett 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 --LXXtuus8Blsk4XO4 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Wed, Oct 13, 2021 at 10:15:02AM +0200, Fran=E7ois Ozog wrote: > Le sam. 18 sept. 2021 =E0 15:18, Tom Rini a =E9crit : >=20 > > On Sat, Sep 18, 2021 at 03:38:45AM -0600, Simon Glass wrote: > > > Hi, > > > > > > On Fri, 10 Sept 2021 at 16:44, Tom Rini wrote: > > > > > > > > On Sat, Sep 11, 2021 at 12:09:40AM +0200, Mark Kettenis wrote: > > > > > > Date: Fri, 10 Sep 2021 17:17:37 -0400 > > > > > > From: Tom Rini > > > > > > > > > > > > On Fri, Sep 10, 2021 at 11:12:20PM +0200, Mark Kettenis wrote: > > > > > > > > Date: Fri, 10 Sep 2021 08:34:20 -0400 > > > > > > > > From: Tom Rini > > > > > > > > > > > > > > > > On Fri, Sep 10, 2021 at 10:38:17AM +0200, Heinrich Schuchar= dt > > wrote: > > > > > > > > > > > > > > > > > > > > > > > > > > > On 9/9/21 10:10 PM, 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 rul= es > > about using > > > > > > > > > > the various CONFIG_OF_... options. > > > > > > > > > > > > > > > > > > > > Signed-off-by: Simon Glass > > > > > > > > > > Reviewed-by: Marcel Ziswiler > > > > > > > > > > --- > > > > > > > > > > > > > > > > > > > > Changes in v3: > > > > > > > > > > - Fix typos linst suppled receive EFL > > > > > > > > > > - Drop 'and' before 'self-defeating' > > > > > > > > > > - Reword mention of control of QEMU's devicetree genera= tion > > > > > > > > > > - 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 > > 'now', not 'future' > > > > > > > > > > - Add note 'Note: Some boards use a devicetree in U-Boot > > which does not match' > > > > > > > > > > > > > > > > > > > > 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 > > kernel 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 t= he > > same 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 sou= rce > > in U-Boot' > > > > > > > > > > - Rewrite 'Devicetree generated on-the-fly in another > > project' to cover > > > > > > > > > > points raised on v1 > > > > > > > > > > - Add 'Why does U-Boot have its nodes and properties?' > > > > > > > > > > - Add 'Why not have two devicetrees?' > > > > > > > > > > > > > > > > > > > > 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 > > > > > > > > > > > > > > > > > > > > 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..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 toda= y, > > mostly, with some > > > > > > > > > > +mention of things that need to be fixed. It is not > > intended to point the way to > > > > > > > > > > +what might be done in the future. That should be the > > subject of discussions on > > > > > > > > > > +the mailing list. > > > > > > > > > > + > > > > > > > > > > +U-Boot uses devicetree for runtime configuration and > > storing required blobs or > > > > > > > > > > +any other information it needs to operate. It is possi= ble > > to update the > > > > > > > > > > +devicetree separately from actually building U-Boot. T= his > > provides a good degree > > > > > > > > > > +of control and flexibility for firmware that uses U-Bo= ot > > in conjunction 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 summ= ary > > 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 > > 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` a= re > > 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. > > > > > > > > > > + > > > > > > > > > > +Some of the problems created are: > > > > > > > > > > + > > > > > > > > > > +- It is not obvious that the devicetree is coming from > > another project > > > > > > > > > > + > > > > > > > > > > +- There is no way to see even a sample devicetree for > > these platform in U-Boot, > > > > > > > > > > + so it is hard to know what is going on, e.g. which > > devices are typically > > > > > > > > > > + present > > > > > > > > > > + > > > > > > > > > > +- The other project may not provide a way to support > > U-Boot's requirements for > > > > > > > > > > + devicetree, such as the /config node. Note: On the > > U-Boot mailing list, this > > > > > > > > > > + was only discovered after weeks of discussion and > > confusion > > > > > > > > > > + > > > > > > > > > > +- For QEMU specifically, consulting two QEMU source fi= les > > is required, for which > > > > > > > > > > + there are no references in U-Boot documentation. The > > code is generating a > > > > > > > > > > + devicetree, with some control from command-line args, > > but 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 Raspbe= rry > > Pi, which does have > > > > > > > > > > + an in-tree devicetree, but this feature has since be= en > > used for boards that > > > > > > > > > > + don't > > > > > > > > > > +- `CONFIG_OF_PRIOR_STAGE` was added in bcm_patch_ as p= art > > 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_PRIOR_STAGE will override > > > > > > > > > > > > > > > > > > What does "bug" refer to? Above you describe the current > > design not a bug. > > > > > > > > > > > > > > > > The bug is that we have two options to provide seemingly the > > same > > > > > > > > functionality. Is there a functional difference between > > CONFIG_OF_BOARD > > > > > > > > and CONFIG_OF_PRIOR_STAGE ? > > > > > > > > > > > > > > With CONFIG_OF_BOARD there is a function that returns the > > pointer to > > > > > > > the DTB, so you can do all sort of things with it. > > > > > > > > > > > > > > With CONFIG_OF_PRIOR_STAGE there is a variable that you need = to > > set in > > > > > > > low-level code to point at the DTB and there is a pre-defined > > function > > > > > > > that returns that pointer. > > > > > > > > > > > > > > CONFIG_OF_BOARD is more flexible than CONFIG_OF_PRIOR_STAGE, = but > > if > > > > > > > the only thing you want to do is to pass on a DTB that is pas= sed > > in a > > > > > > > CPU register to U-Boot then CONFIG_OF_PRIOR_STAGE is probably > > easier > > > > > > > to use. > > > > > > > > > > > > > > I'm not convinced there is a bug here. > > > > > > > > > > > > Thanks for explaining. Couldn't CONFIG_OF_PRIOR_STAGE be > > rewritten as > > > > > > an implementation of CONFIG_OF_BOARD, possibly at the same or l= ess > > > > > > overall code size? That I think is the potential bug. > > > > > > > > > > Probably a little bit more code: > > > > > > > > > > void * > > > > > board_fdt_blob_setup(void) > > > > > { > > > > > return (void *)(uintptr_t)prior_stage_fdt_address; > > > > > } > > > > > > > > Tiny bit more. Probably worth doing to make the choices clearer on > > > > which to select when? Bin, Rick, thoughts on this since riscv is t= he > > > > main user of CONFIG_OF_PRIOR_STAGE at this point? > > > > > > Bin, Rick? > > > > > > What is the prior stage in the RISC-V stage? Could we get it to set up > > > a bloblist? Then we can add a devicetree in there, with the option to > > > add more things in future. > > > > I'm suggesting we don't need to do anything upstream of us, just rework > > things to use the other hook for "provided a DTB by caller, use it", so > > that we have a single hook for that. > > > > -- > > Tom >=20 >=20 > What was the rationale in posting in kernel.org ( > https://lore.kernel.org/all/20211003125134.2.I7733f5a849476e908cc51f0c71b= 8a594337fbbdf@changeid/ > ) and not in U-Boot knowing there is still no consensus on the big pictur= e ? Well, because we need to get our bindings reviewed and made official, and that looked like a reasonable place and choice to start with? v2 cc'd a different set of lists, at Rob's suggestion. > We agreed you would defer the device tree documentation patch you proposed > because we did not agree on the painted overall picture. So I was surpris= ed > by your post. > I agree standardization of U-Boot bindings is a good thing. > Trustedfirnware.org does it internally and U-Boot can get inspiration from > this. > https://trustedfirmware-a.readthedocs.io/en/latest/components/cot-binding= =2Ehtml Note that your example there should also be reviewed and sent upstream as the problem is less "U-Boot's config binding isn't documented" but more "U-Boot's config binding isn't official". --=20 Tom --LXXtuus8Blsk4XO4 Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQGzBAABCgAdFiEEGjx/cOCPqxcHgJu/FHw5/5Y0tywFAmFm10gACgkQFHw5/5Y0 tywy2wv+OqEH86o13U8K6dH234Cp8++6CMe2LyEdNTAqb4xINeUDKg0Jxb7tMOCQ s8a9W+TloUa1BPFVoVeLlQDfc3MBYHTlAtndmEfXt9exGWGveBKegq4zbW0JGIkL mFMGMeBwxuceaOSTSnVqlK/KrDtCFG6n73Njm4O2ODiDDzFeTzOj0m4ozmOPMfJ2 kJRx71vkcDBzjinHG1SQYbcp87xeM9d81vb9f10xSjbiARf8fpc+2XbUyAd6GZ8v q5LzC+0Q6zlhYmLlLLKS9KOW7t83E3lk6zpx3kvSoDY7IVvdwaa0jfaDnmVmH2Ce 48JzDSxLFFcN65avEzN7H4iLLcbVU2bj0Qakivhm9fgou010QiBSzmlpU4ARcRyI qA9CC/nLM5HYTLQzPMI/PmWEnifSs/RzvzJaZrjn0jmC/7Y9rDwccrjvMZ0jR3NQ kK8Jh+A+m8zh3qkXwDFTsGflp9rL1kPLM1yTPRejD5je/VNelSGoIq/Rx2uqKz+i qlju95ip =b33o -----END PGP SIGNATURE----- --LXXtuus8Blsk4XO4--