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 0E455C432BE for ; Mon, 30 Aug 2021 14:48:52 +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 5432E60249 for ; Mon, 30 Aug 2021 14:48:51 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 5432E60249 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 9B9028338E; Mon, 30 Aug 2021 16:48: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="bk+oLkKS"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id AECF18338E; Mon, 30 Aug 2021 16:48:46 +0200 (CEST) Received: from mail-qk1-x72f.google.com (mail-qk1-x72f.google.com [IPv6:2607:f8b0:4864:20::72f]) (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 093AA8334F for ; Mon, 30 Aug 2021 16:48:42 +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-x72f.google.com with SMTP id p4so9570337qki.3 for ; Mon, 30 Aug 2021 07:48: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=Gv996K9IW85Mcg2VDye1PxpKEB3IPW4XA9ZR22H6m2w=; b=bk+oLkKSLviGrho2sEd7ygCIGzTNWMM4uVGVfcTLXrMcC9Nw37TUD2ELt/8GQ249wr RtA2U1/7I2tNW8N07IKrwRL3azaHM4Oyr3PQm5XyVr9ZNhusSUXytw1mQFQ3JF4Uth5x ErGvo4iPyHeuIixgAS9cpRiNYhM2xYdptuMlg= 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=Gv996K9IW85Mcg2VDye1PxpKEB3IPW4XA9ZR22H6m2w=; b=tTs14Mo/teHc4mG4kqoxy5BMsWafHYafazFb9agBgfHEnfFXcdLlWPuy1ojMJE8JCp rIdioADlmQlw199FPzYR4b4n7f5E2+FT4vhwTbWfDFFmW1D/v+baJnmR6kp5ckKdOTqf IpT+S/OJFl080TK2/SFfbsb2aZfQrveXOs+IwsYc3VnVq7GXQgterQI7MdlJd4QgBEIf e8Rk26WXk5BJfFpYB8bSch56//CeHe4yswNKGX2ns7sDuD5ZHO5FlpUvzDerB4b9v1cT myYXCg6kL6FDbNzX90MMP+JS8stPYuaFKax5XV0YVLjZWNNVYRlUrnaZ8A0ol8f7mH8z ImhA== X-Gm-Message-State: AOAM533NH9W6L1VeJKv4pY7Bspy5THkH4l51NRQ/1mrI+OhY7nDlm4e6 UYOPHq74m9wW61qR//I3oC3m4g== X-Google-Smtp-Source: ABdhPJz2IM6x4GS8DRsJcp5oj1TuZIv2YbgukuoNTQ94kDrbmvb/JIFblkoXqyQlULS6P3OFZfXqCg== X-Received: by 2002:a37:9606:: with SMTP id y6mr22673519qkd.13.1630334920597; Mon, 30 Aug 2021 07:48:40 -0700 (PDT) Received: from bill-the-cat (2603-6081-7b01-cbda-8d75-4e9a-efec-7167.res6.spectrum.com. [2603:6081:7b01:cbda:8d75:4e9a:efec:7167]) by smtp.gmail.com with ESMTPSA id r128sm11488364qke.98.2021.08.30.07.48.39 (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Mon, 30 Aug 2021 07:48:40 -0700 (PDT) Date: Mon, 30 Aug 2021 10:48:38 -0400 From: Tom Rini To: Heinrich Schuchardt Cc: Simon Glass , Ilias Apalodimas , Mark Kettenis , Sean Anderson , Bin Meng , U-Boot Mailing List Subject: Re: [PATCH v2 3/3] RFC: doc: Add documentation about devicetree usage Message-ID: <20210830144838.GX858@bill-the-cat> References: <20210828164630.81050-1-sjg@chromium.org> <20210828164630.81050-4-sjg@chromium.org> <593b807c-881e-2ab2-5ed8-03c521439f45@gmx.de> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="MnBib2rRfVB57Hi2" Content-Disposition: inline In-Reply-To: <593b807c-881e-2ab2-5ed8-03c521439f45@gmx.de> 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 --MnBib2rRfVB57Hi2 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Mon, Aug 30, 2021 at 04:30:55PM +0200, Heinrich Schuchardt wrote: >=20 >=20 > On 8/28/21 6:46 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. I feel like I should emphasize that this is "document what we have today" at least as much, if not more-so, than "document what we want to move to tomorrow". In that this highlights some design disagreements that need to be settled, good. But lets perhaps start separate threads on those areas? > > Signed-off-by: Simon Glass > > --- > >=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 | 563 +++++++++++++++++++++++++++++ > > doc/develop/package/index.rst | 1 + > > 3 files changed, 565 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..d922d3f87ae > > --- /dev/null > > +++ b/doc/develop/package/devicetree.rst > > @@ -0,0 +1,563 @@ > > +.. 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. > > + > > +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= nst, 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, but it is not clear what controls affect this generation. > > + > > +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. > > + > > +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`. > > + > > +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. > > + > > +To be clear, while U-Boot has its own copy of the devicetree source fo= r each > > +board, this must match the Linux source, perhaps with some u-boot.dtsi > > +additions. The intent here is not to create a separate binding, just t= o provide > > +a representative devicetree in U-Boot. >=20 > For many boards we lag far behind Linux' device-tree. Which is a huge problem that needs to be fixed. The intention has never been to "commit and forget". [snip] > > +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, for the following reasons: >=20 > Currently it is Linux that sets the standards not U-Boot. Well no, Linux isn't supposed to set "the standard" here either. It's OS-agnostic. > U-Boot can apply an overlay to the devicetree provided by the prior boot > stage. We should not try to force any U-Boot specific stuff onto other > projects. We should, when applicable, submit our bindings upstream just like any other project. We also want to make sure that when we do so, we hold ourselves to a high standard. > > +- U-Boot only has one devicetree. See `Why not have two devicetrees?`_. > > +- For a consistent firmware build, decisions made in early stages shou= ld be > > + communicated to later ones at runtime. For example, if the serial co= nsole is > > + enabled in an early stage, it should be enabled in U-Boot too. > > +- U-Boot is quite capable of managing its own copy of the devicetree. = If > > + another project wants to bypass this (often for good reason), it is = reasonable > > + that it should take on the (fairly small) requirements that U-Boot f= eatures > > + that rely on devicetree are still available > > +- The point here is not that *U-Boot needs this extra node*, or *U-Boo= t needs > > + to have this public key*. These features are present in U-Boot in se= rvice of > > + the entire firmware system. If the U-Boot features are used, but can= not be > > + supported in the normal way, then there is pressure to implement the= se > > + features in other ways. In the end, we would have a different mechan= ism for > > + every other project that uses U-Boot. This introduces duplicate ways= of doing > > + the same thing, needlessly increases the complexity of the U-Boot so= urce code, > > + forces authors to consider parallel implementations when writing new= features, > > + makes U-Boot harder to test, complicates documentation and confuses = the > > + runtime flow of U-Boot. If every board did things its own way rather= than > > + contributing to the common code, U-Boot would lose a lot of its cros= s-platform > > + value. >=20 > This paragraph is incomprehensible for me. >=20 > If both the prior boot stage and U-Boot comply to the standards set by > Linux we are fine. Any U-Boot quirks should be kept out of other projects. It's not the "Linux" device tree. It's the device tree for the system. --=20 Tom --MnBib2rRfVB57Hi2 Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQGzBAABCgAdFiEEGjx/cOCPqxcHgJu/FHw5/5Y0tywFAmEs78IACgkQFHw5/5Y0 tyyWiAv+MlqFJatarc8Z3WCELYqJRa0yjnkkoG8mMLhEOyzqmy5JqGoshO5Fj4B5 OWfyWy+moPVMdWcXCw9Y9AllMLjccDiEttnbKzy9kfBcjPRdQuhvC/ikakBk/uSH sZ8LOgbCswp4yutMU3+cLXB1y28POy13jP+kFwNDe2AFVb//xngnLJeKilse/ApW KcnjWdSlgiJxL6N6NrQHm/Wl99YQEdYo7/NNBJgwcBg7FV5v/JH6EeTHLCGfrUkP h4G4tZ2lMhfqEVEwOyLai4YhqiEGQuCJXPE0pTx9RC2QYdgm0zg/x8Uk6JZU4V14 AOAnl74nI6IQAIszh/TbyWrNYFwbvNm9sgAdWEmmLsBN31H9qxPjabjmmQyD6L8L CuStEvrJp+PCoHiB+NYWZVaatFju7kcjBvK+xthTAxDFNWV9FAyl/vy2CDlS7amm X3DroCWE0KgMZpz4F0gLyejo9nS5x0X1YPeZr9yrlcQcmITyVGG315JLJN1qCrZa fYU7/Ko4 =uKac -----END PGP SIGNATURE----- --MnBib2rRfVB57Hi2--