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 BBFB4C432BE for ; Mon, 30 Aug 2021 16:15:58 +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 BD5D260462 for ; Mon, 30 Aug 2021 16:15:57 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org BD5D260462 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 D6BCC8334F; Mon, 30 Aug 2021 18:15:55 +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="e3nNv8/5"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id B429B8334F; Mon, 30 Aug 2021 18:15:54 +0200 (CEST) Received: from mail-qt1-x82c.google.com (mail-qt1-x82c.google.com [IPv6:2607:f8b0:4864:20::82c]) (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 9FF9582BDC for ; Mon, 30 Aug 2021 18:15: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=trini@konsulko.com Received: by mail-qt1-x82c.google.com with SMTP id g11so12110806qtk.5 for ; Mon, 30 Aug 2021 09:15:48 -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=ksdUgxL4lFL4wLpZZw38WxVUXbxY1b4prqIpgVA3Vaw=; b=e3nNv8/5wHbvPAild5yYe9ILEly0sVDsltzFAinFxjAQvIkKDZ6njHaHYSXbEKrWTQ S/zI6oBxZ3UI8ensIyyzxEMaTHYYyLFSmdHuaZObp8admn7hZOC6/1yl8VzpKKwf5zKF KomVcFNXdVXATufNJTajWgJazS4C2YTVc8yJk= 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=ksdUgxL4lFL4wLpZZw38WxVUXbxY1b4prqIpgVA3Vaw=; b=bmZGwNXuO7/JTW/W3ieDWwVPkOgFtxFojUlrYIF2pAlh+jkxaxCLLBSxHNJShfeJdn DdDQ/ieyAvKoAZQdQYmZpbr1gSfgUpy2Kf55MtMdZynBRqNDH8EioyJjQP3n6Z68JV/v kYFNGNJhoQpHmHhJGFV50wvXGXw7jfDLjZTafy7G5w1nSCC6vQJUROqwEsUDvsJR2fVG JPS+Soald8D+RpaanGr+yCOs1nD09cok7J3rOEPs/5u5ysde4yypAjtFjcI5vmPGHdiG WFAXV8TcCrR4ghUC70nyTt+AVX7UWJeQTlMVlpQ1yGH20JD3zjSqXNrmNbI7Sd8GWTJr uOHg== X-Gm-Message-State: AOAM533CyH+08DZkws+69m0K13r8uzKQxFgMUNiozEZtAWLtEHpOCaqf hoZmCnvwLErrqIfKVL/OHW6MBg== X-Google-Smtp-Source: ABdhPJyQvnFYRvufAGMK6rIDdErcNCR8QvBtC+TgnLirf+pyg2JeOlJ576F9C1Ef6WP+TdWLrX46Vw== X-Received: by 2002:ac8:4704:: with SMTP id f4mr21459816qtp.80.1630340147099; Mon, 30 Aug 2021 09:15:47 -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 g8sm11149213qkm.25.2021.08.30.09.15.45 (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Mon, 30 Aug 2021 09:15:46 -0700 (PDT) Date: Mon, 30 Aug 2021 12:15:44 -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: <20210830161544.GZ858@bill-the-cat> References: <20210828164630.81050-1-sjg@chromium.org> <20210828164630.81050-4-sjg@chromium.org> <593b807c-881e-2ab2-5ed8-03c521439f45@gmx.de> <20210830144838.GX858@bill-the-cat> <01da6121-4666-4c0d-5056-db401ae3690d@gmx.de> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="UJllxCU336Ql2dsa" Content-Disposition: inline In-Reply-To: <01da6121-4666-4c0d-5056-db401ae3690d@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 --UJllxCU336Ql2dsa Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Mon, Aug 30, 2021 at 05:14:53PM +0200, Heinrich Schuchardt wrote: >=20 >=20 > On 8/30/21 4:48 PM, Tom Rini wrote: > > 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 usi= ng > > > > the various CONFIG_OF_... options. > >=20 > > 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". > >=20 > > In that this highlights some design disagreements that need to be > > settled, good. But lets perhaps start separate threads on those areas? > >=20 > > > > 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 cmd= line > > > > - 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 devi= cetree > > > > 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-Boo= t' > > > > - Rewrite 'Devicetree generated on-the-fly in another project' to c= over > > > > 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/packa= ge/devicetree.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 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. > > > > + > > > > +Some of the problems created are: > > > > + > > > > +- It is not obvious that the devicetree is coming from another pro= ject > > > > + > > > > +- There is no way to see even a sample devicetree for these platfo= rm in U-Boot, > > > > + so it is hard to know what is going on, e.g. which devices are t= ypically > > > > + present > > > > + > > > > +- The other project may not provide a way to support U-Boot's requ= irements for > > > > + devicetree, such as the /config node. Note: On the U-Boot mailin= g linst, this > > > > + was only discovered after weeks of discussion and confusion > > > > + > > > > +- For QEMU specifically, consulting two QEMU source files is requi= red, for which > > > > + there are no references in U-Boot documentation. The code is gen= erating a > > > > + devicetree, but it is not clear what controls affect this genera= tion. > > > > + > > > > +Specifically on the changes in U-Boot: > > > > + > > > > +- `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`. > > > > + > > > > +This means that there is a basic devicetree build in the U-Boot tr= ee, for > > > > +build-testing, consistency and documentation purposes, but at runt= ime U-Boot can > > > > +accept its devicetree from another source. > > > > + > > > > +To be clear, while U-Boot has its own copy of the devicetree sourc= e for 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, ju= st to provide > > > > +a representative devicetree in U-Boot. > > >=20 > > > For many boards we lag far behind Linux' device-tree. > >=20 > > Which is a huge problem that needs to be fixed. The intention has never > > been to "commit and forget". > >=20 > > [snip] > > > > +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, for the following reasons: > > >=20 > > > Currently it is Linux that sets the standards not U-Boot. > >=20 > > Well no, Linux isn't supposed to set "the standard" here either. It's > > OS-agnostic. > >=20 > > > U-Boot can apply an overlay to the devicetree provided by the prior b= oot > > > stage. We should not try to force any U-Boot specific stuff onto other > > > projects. > >=20 > > 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. >=20 > What would you consider upstream for compatible( "u-boot,*" )? As I believe Simon is the main author of most of them, I'll let him chime in here as well. But I suspect things like "u-boot,bootcount*" are a good example of something to polish and push upstream. In the same vein as to how mtd partitions are valid in device trees, our binding for where environment is stored on MMC is likely another candidate. > Even if we upstream the binding to some global list of binding I think > U-Boot still should provide an overlay with this content. Depending if we have stuff that both we need and can't reasonably suggest moving upstream, sure. --=20 Tom --UJllxCU336Ql2dsa Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQGzBAABCgAdFiEEGjx/cOCPqxcHgJu/FHw5/5Y0tywFAmEtBC8ACgkQFHw5/5Y0 tyxMWQwArDMFm5MmWAG/Ep/XdG50aJWjwfHA6RhLxeN8rLdUAmkDhZbdfAMcoE5j OLeFDZ9c7R2zmLf9KtsFds8EGlEFwaUViyUoEhne1cg7hpao6E7O876ma6lK8ZVY 3ifR3Ge50J29IhdzzYhkw4+57EkBfGk2RFtfFtfmRtHjK5QUIefHtkr37E+T7711 PP+LQlONPR8jayi+hUGc4Koax6TbytoawwjteHt/nmpH6kGCjhVpB0ZEJjx7ov/x l7qfZQWtAZx7+jUGE0pYbXjynx6YUDqJUsJ6erJb7MMRKPxMOW6GVxW02FK49e8y xr0a9LybCV1nLoqqCf3ptiMoxjWe6vMhGbbGiC3T9iKVQXQel/SbD3Bs/uiSP7rb NlGBnXc+2Dqf++RoDw3jfjwBB43xcqmCh3oPThS2qdkkg1cQFhlx22E8rYjsXD51 iN5Fwxfb+V6cIsW2kqqVbTK6bqacNQdKCeJUFZZI+usTx19kdg/B4H2TWFfJP6XK U8TSY3Hk =usCU -----END PGP SIGNATURE----- --UJllxCU336Ql2dsa--