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 3E29CC433FE for ; Fri, 10 Sep 2021 12:34:34 +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 755686120A for ; Fri, 10 Sep 2021 12:34:33 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 755686120A 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 077E783655; Fri, 10 Sep 2021 14:34:31 +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="uj5Yv/hI"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 71A2183659; Fri, 10 Sep 2021 14:34:29 +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 D85EA83252 for ; Fri, 10 Sep 2021 14:34:24 +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 93so1115682qva.7 for ; Fri, 10 Sep 2021 05:34:24 -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=iOs8bWB/2RuZjaEPAvTkqiBAe8fh2NUwODNjNusmloY=; b=uj5Yv/hIA+O7QEo7LQewB6w/Q/RuchhPH2n/KSIg6bv+C/ULbBsedatJ8poEEV8rKm lk/LgKmfqMUKxFQCWOnprUcXXYaUdDaAUxOf6NRF+RR8cuFA/OqfFe1DK4CRxaBBxpFu yi9vZMbwUJlsFvKpnVKrxHVwgcrNgI3PGBXZA= 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=iOs8bWB/2RuZjaEPAvTkqiBAe8fh2NUwODNjNusmloY=; b=WdZQDS2Rm19lIupJ3SA6GHyewyJ5rluclwZfMWhGYVHxDuVcB2+S/umFqP+jcqITq5 sAxJCtxCG9cnbcLglFTOkutlbti7S9/Vw2ZmaGPT0EfxO27Vp7+EPM0VmVYqvP9FkYlm JDERhNfJmd7Z9M11fSh9JzgDyJn89ehYfCFCjElMPrYosS2Qc54Uxp9wdoQ4uZBLMetM dU7IDsU9X0g3zmj1sFWrYTXk/ucarxsp9ghXsbNWyuhRy+bj6mh2vzwAB7520p3iZ5Ed RbMAthd+K97m8N7PlsCBrpBOyM1ilXBlTRSkwGOTBtMzTECsUMPQjVTIl5vvxp9IDQ1J zCEA== X-Gm-Message-State: AOAM530L5cE9I28BJNIAWuH1cLUYZ6XW99mGVQCtaJUQGpWeYdgH7W4Z o0NW+tmbR8jzMHwqCjn6r0I76A== X-Google-Smtp-Source: ABdhPJyo/O1VDtiizpoa34XA9Vvd7qzPy5BKYCrUVoZrLXK30ea+rHBWGS0+NY2pLqrEA0lGzG1GtA== X-Received: by 2002:a0c:c490:: with SMTP id u16mr8179498qvi.26.1631277263440; Fri, 10 Sep 2021 05:34:23 -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 m16sm3331847qka.84.2021.09.10.05.34.22 (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Fri, 10 Sep 2021 05:34:22 -0700 (PDT) Date: Fri, 10 Sep 2021 08:34:20 -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: <20210910123420.GL12964@bill-the-cat> References: <20210909201033.755713-1-sjg@chromium.org> <20210909201033.755713-4-sjg@chromium.org> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="NGz5rmaP0KprYzG0" 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 --NGz5rmaP0KprYzG0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Fri, Sep 10, 2021 at 10:38:17AM +0200, Heinrich Schuchardt wrote: >=20 >=20 > 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 rules about 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 devicet= ree > > - Add a note at the top explaining that his patch covers 'now', not 'fu= ture' > > - Add note 'Note: Some boards use a devicetree in U-Boot which 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 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 the same devicetr= ee > > 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 project' 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/develop/package/d= evicetree.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, mostly, with = some > > +mention of things that need to be fixed. It is not intended to point t= he way to > > +what might be done in the future. That should be the subject of discus= sions 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 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. > > + > > +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 i= n U-Boot, > > + so it is hard to know what is going on, e.g. which devices are typic= ally > > + present > > + > > +- The other project may not provide a way to support U-Boot's requirem= ents for > > + devicetree, such as the /config node. Note: On the U-Boot mailing li= st, this > > + was only discovered after weeks of discussion and confusion > > + > > +- For QEMU specifically, consulting two QEMU source files is required,= for which > > + there are no references in U-Boot documentation. The code is generat= ing 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 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. > > + > > +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 >=20 > 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 ? > > +(at runtime) the devicetree supplied with U-Boot, but will otherwise u= se > > +CONFIG_OF_SEPARATE for the in-tree build. So these two will become opt= ions, > > +moving out of the 'choice' in `dts/Kconfig`. To be clear, the devicetr= ee in the > > +U-Boot tree may be largely for documentation and build-testing purpose= s, 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 does not get on= e from a > > +prior stage at runtime. This does not create two devicetrees 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 stuff. So > don't you need the buildtime devicetree for all of this information at > runtime? E.g. you were requesting to move certificate blobs into the > build-time devicetree. 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 Tom --NGz5rmaP0KprYzG0 Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQGzBAABCgAdFiEEGjx/cOCPqxcHgJu/FHw5/5Y0tywFAmE7UMUACgkQFHw5/5Y0 tyyU1gv/Vm1DQ5drOIxiJ/mG2nxBK3RmhE4nS8Jz/L+MwUSPnWJgpUbjUSgYncKG 1Eo+jt4ickYMf4l60X+hroyH/KcmfOUNSgZey7+vFQdUbi8isA0pOAWhzCPjzI3A 4TFHMgoEh87lUKn20EluCd3y2tmyGOteON1DO8TLk6ysxi9s0i69Rt8iT6RUjnRm /0o5DfIuTyRNJaYny9h0iA7PE3N9ELix6g4sFJhnAhbAiaYRMorObnVV1i1T93uv eQiBq1KxhOxz+YtMm6dW1Gsnnc/21Ems6R0H4v5OO2+1dFuhhh75DvOoHp0ut4AD 3iHXKGLT5D6U/Gm6AbiKmFB+lbbTDqxgpnNbQoUe+GOITmXQj8KUY147eMx/Ch2S o35auLKP71VlIz3R5NrZg3FArSr5N6/ohlYjHBrGxTAB2mBxILAkJcTHmgBtc0Sy xc7ZqvOVv+gxFksDnOnXD/fCSzQGFNKhGAmdjqL/YeU7oiuoWGhSjd7SCwRo6eYQ oxDEMVlP =w2p5 -----END PGP SIGNATURE----- --NGz5rmaP0KprYzG0--