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 9EEFAC433F5 for ; Sat, 18 Sep 2021 13:18:31 +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 DCF3D6128A for ; Sat, 18 Sep 2021 13:18:30 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org DCF3D6128A 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 934C1829FC; Sat, 18 Sep 2021 15:18:28 +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="RU5VGeme"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 60F1582849; Sat, 18 Sep 2021 15:18:26 +0200 (CEST) Received: from mail-qt1-x833.google.com (mail-qt1-x833.google.com [IPv6:2607:f8b0:4864:20::833]) (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 3AB0782849 for ; Sat, 18 Sep 2021 15:18:21 +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-x833.google.com with SMTP id o10so1081513qtk.0 for ; Sat, 18 Sep 2021 06:18:21 -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=rNBEgZBQ2XtV6bBrJtCdbHGTtzigmhZv0GBORWLWjwA=; b=RU5VGemeW3YlYAsBHlpz3l4v1K+JJn8yftZ+vYiPtvme/b0UMxAY9RqkQGH6HnrQq0 DoVT4fBUJFqg3vqUmhKaviOBK0xlPL2p3poHgSZyoibVR+n000hqkW5Zib2GoCHCRFNs JkrdF4/yJqJyHfYuxbVkQJi2hizoW+TD95saM= 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=rNBEgZBQ2XtV6bBrJtCdbHGTtzigmhZv0GBORWLWjwA=; b=nBYdIvBRfMGbhfoo1JrK73dHGZkxsLROp3cBcEloWhR2E+UQk1r8p7nLmMrZuwI2cX xdJkMAmST4Bjj1VoNrZOX6Ww6yOhJAsTJKCFSESDMzB80wRumeMNL6pPmQSavE+2z1cK jZuWwyElPomf50WNefGPt4Z07UqzdvnuWTi3mWhBGi1kzPKaR8Ww+5inxWOq4DV6laUv tDE/10s0OprAQWLO75Wu7GRmfEiPbL8j8GaSgRoAwY0nUVJTXhL7+3u8UGGrMaX2PAbh E/K95yFhDyCTsYF/ae8J8IdyxwBkCHv9RfpYwg1co/JiUCAIDnzUSwsP6cOq8i2O38X0 qCoQ== X-Gm-Message-State: AOAM531sRDWCbu+pwZTXIRnyMPuBokL/szW60Hl/x0SEevb02XLm0Ruh e/3PSfvkiUvGtnGH6oIFf7GDEQ== X-Google-Smtp-Source: ABdhPJyI5oO+7q3iZF80l3TsrMC510opPNdNFHtvUp1KR7aL7Jqaz/ScjZlA49ML7dRqkIT9PfCTzA== X-Received: by 2002:ac8:148b:: with SMTP id l11mr15066631qtj.298.1631971099771; Sat, 18 Sep 2021 06:18:19 -0700 (PDT) Received: from bill-the-cat (2603-6081-7b01-cbda-11d5-faa7-99fc-5b2d.res6.spectrum.com. [2603:6081:7b01:cbda:11d5:faa7:99fc:5b2d]) by smtp.gmail.com with ESMTPSA id l1sm3743959qkj.65.2021.09.18.06.18.18 (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Sat, 18 Sep 2021 06:18:18 -0700 (PDT) Date: Sat, 18 Sep 2021 09:18:16 -0400 From: Tom Rini To: Simon Glass Cc: Mark Kettenis , Bin Meng , Rick Chen , xypron.glpk@gmx.de, u-boot@lists.denx.de, seanga2@gmail.com, ilias.apalodimas@linaro.org, francois.ozog@linaro.org, bill.mills@linaro.org, marcel.ziswiler@toradex.com Subject: Re: [PATCH v3 3/3] RFC: doc: Add documentation about devicetree usage Message-ID: <20210918131816.GM8579@bill-the-cat> References: <20210909201033.755713-1-sjg@chromium.org> <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> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="j3olVFx0FsM75XyV" 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 --j3olVFx0FsM75XyV Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sat, Sep 18, 2021 at 03:38:45AM -0600, Simon Glass wrote: > Hi, >=20 > 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 Schuchardt w= rote: > > > > > > > > > > > > > > > > > > > > > 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. > > > > > > > > > > > > > > > > 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 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' > > > > > > > > > > > > > > > > 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?' > > > > > > > > > > > > > > > > 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/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 > > > > > > > > > > > > > > What does "bug" refer to? Above you describe the current desi= gn not a bug. > > > > > > > > > > > > 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 ? > > > > > > > > > > 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 s= et in > > > > > low-level code to point at the DTB and there is a pre-defined fun= ction > > > > > 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 passed = in a > > > > > CPU register to U-Boot then CONFIG_OF_PRIOR_STAGE is probably eas= ier > > > > > 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 less > > > > 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 the > > main user of CONFIG_OF_PRIOR_STAGE at this point? >=20 > Bin, Rick? >=20 > 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. --=20 Tom --j3olVFx0FsM75XyV Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQGzBAABCgAdFiEEGjx/cOCPqxcHgJu/FHw5/5Y0tywFAmFF5xgACgkQFHw5/5Y0 tywTWQwAoWWhzoSJuq9YrdT2ZF7TlAVNoCC00nqMa7zHI1Y2IW61abPzIKjF0LTA CkgThjBINHB/MmF9n5eEAzRCAxN1I56S3ZFc5fuNETIaQuU/e9i6cQ4uzN4NLzs8 0rYmd/4LLmIhb5LLlL+oJ54v9G6KPjE+hh6zsumyJLDD6uc0uftXbuphjXEkBzQO HeLi9Q56caZt+LF0mhVst57IxhImNDpA3HNJwMtECgamtDggM77pULoIuOgvgUzD rZ3YOfoSN937+lKsMswQgGb/R+BCcJnrJBDSYkosZYpX1xJvgFKlJORxyHL1BBDB CC+6gikbN3l9ee4yRYUJ3n3XIXmu7nghWT/Uf+LHx7DtOgSwB8tzkze3ANjXzf5P gcr0uccx6rOVzkP30RnvFfjgpGBKvmV6xhLTj42MZDJfMZBFiSC9+zocp4+6DTPo 9O41Mk35oyMzqaFUe40q7HSFQ+IuqjLjLmt49i5xfgqKbxayaMIX+0Nt4KSbFBQI d8Usvvyh =K34x -----END PGP SIGNATURE----- --j3olVFx0FsM75XyV--