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 B297CC4320A for ; Sun, 29 Aug 2021 14:45:01 +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 C7C1460F25 for ; Sun, 29 Aug 2021 14:45:00 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org C7C1460F25 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 58B3E82EB9; Sun, 29 Aug 2021 16:44:58 +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="RUaPFDNg"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 6D451832CB; Sun, 29 Aug 2021 16:44:55 +0200 (CEST) Received: from mail-qk1-x730.google.com (mail-qk1-x730.google.com [IPv6:2607:f8b0:4864:20::730]) (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 C472881BDA for ; Sun, 29 Aug 2021 16:44:50 +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-x730.google.com with SMTP id p4so6484117qki.3 for ; Sun, 29 Aug 2021 07:44:50 -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=ZavHV+mLeOJHac53O9Au3o9v4i2/2NtwGTBs+oVpug0=; b=RUaPFDNgzrl1T/Cs9DjXDM1HnEj0mFrrTmEzZaREnzI60X07QGR2VAGgaq7UProLEB O0sOS6EE+ZdjMGrydG73s0JSkdYFxJnX4g2l0GdzJWlSIda9CzF8EpNfrI9TV4D72HJf yacyL8NNt1BYFJWRKmbJZ9OSOpynmaehyUAy8= 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=ZavHV+mLeOJHac53O9Au3o9v4i2/2NtwGTBs+oVpug0=; b=YxFW1iKXqv/wffXw0Ko3o0j3OI6Kr7N2e38ISoZEWrCqOKk1E665wd1y2USvy4T8IW V4BhsRHjB6QHeGvrwxgLXi1w/+m0aSUSFb50RHLopvOALfBgctpShmpuYD/LtBXqowuk zDH6WEf7tP8RX4rqtBD/46KHAfRpe98raFv2uDXQzFUm5HA7HC9Z/N4nIpH7Xw0GD9MJ VfHuJ/tUERDEyTAy2P58uUQCPK8VcJixG6a8Us8lJzC6BzN1OffR8nV07C5J/X/QpNnr wRSiKhqTIUONpFpY6eOvr0ArGpASY3BgS3dFTGm2mGDVBNwjXxuDqSiu8evKDfH37d2q ZfCw== X-Gm-Message-State: AOAM531XBzenVqAFYrqtXZiryXkuymyOttYyElvNiTefux1CiMLWp2vY P8aoI96y69atA4xgGiijwanjWA== X-Google-Smtp-Source: ABdhPJw9034ftNmVg201teXgxIZTPnio7vJ0dwNycioUADxm+zFVllVEFU7/NnXMSZQnWNLHz2Sy/A== X-Received: by 2002:a37:a905:: with SMTP id s5mr17828063qke.63.1630248289284; Sun, 29 Aug 2021 07:44:49 -0700 (PDT) Received: from bill-the-cat (2603-6081-7b01-cbda-8054-417e-d97b-7576.res6.spectrum.com. [2603:6081:7b01:cbda:8054:417e:d97b:7576]) by smtp.gmail.com with ESMTPSA id i16sm6965791qtw.15.2021.08.29.07.44.47 (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Sun, 29 Aug 2021 07:44:47 -0700 (PDT) Date: Sun, 29 Aug 2021 10:44:45 -0400 From: Tom Rini To: Mark Kettenis Cc: Simon Glass , bmeng.cn@gmail.com, u-boot@lists.denx.de, xypron.glpk@gmx.de, seanga2@gmail.com Subject: Re: [PATCH] doc: Add documentation about devicetree usage Message-ID: <20210829144445.GC858@bill-the-cat> References: <20210828032348.4570-1-sjg@chromium.org> <5614245d41c45ae2@bloch.sibelius.xs4all.nl> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="f35OJ//TcTYGpEDr" Content-Disposition: inline In-Reply-To: <5614245d41c45ae2@bloch.sibelius.xs4all.nl> 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 --f35OJ//TcTYGpEDr Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sun, Aug 29, 2021 at 10:19:53AM +0200, Mark Kettenis wrote: > > From: Simon Glass > > Date: Sat, 28 Aug 2021 20:07:27 -0600 > >=20 > > Hi Bin, > >=20 > > On Sat, 28 Aug 2021 at 19:29, Bin Meng wrote: > > > > > > Hi Simon, > > > > > > On Sun, Aug 29, 2021 at 12:45 AM Simon Glass wrote: > > > > > > > > Hi Bin, > > > > > > > > On Sat, 28 Aug 2021 at 07:15, Bin Meng wrote: > > > > > > > > > > Hi Simon, > > > > > > > > > > On Sat, Aug 28, 2021 at 11:23 AM Simon Glass w= rote: > > > > > > > > > > > > At present some of the ideas and techniques behind devicetree i= n 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. > > > > > > > > > > > > Signed-off-by: Simon Glass > > > > > > --- > > > > > > > > > > > > doc/develop/index.rst | 1 + > > > > > > doc/develop/package/devicetree.rst | 315 +++++++++++++++++++++= ++++++++ > > > > > > doc/develop/package/index.rst | 1 + > > > > > > 3 files changed, 317 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/p= ackage/devicetree.rst > > > > > > new file mode 100644 > > > > > > index 00000000000..fccbb182f3e > > > > > > --- /dev/null > > > > > > +++ b/doc/develop/package/devicetree.rst > > > > > > @@ -0,0 +1,315 @@ > > > > > > +.. 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 r= equired blobs or > > > > > > +any other information it needs to operate. It is possible to u= pdate the > > > > > > +devicetree separately from actually building U-Boot. This prov= ides a good degree > > > > > > +of control and flexibility for firmware that uses U-Boot in co= njunction with > > > > > > +other project. > > > > > > + > > > > > > +There are many reasons why it is useful to modify the devicetr= ee 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 vidc= onsole) > > > > > > + > > > > > > +This section describes how to work with devicetree to accompli= sh your goals. > > > > > > + > > > > > > +See also :doc:`../devicetree/control` for a basic summary of t= he 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 specif= ied using the > > > > > > +`CONFIG DEFAULT_DEVICE_TREE` option. > > > > > > + > > > > > > + > > > > > > +Current situation (August 2021) > > > > > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > > > > > + > > > > > > +As an aside, at present U-Boot allows `CONFIG_DEFAULT_DEVICE_T= REE` 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. Specifi= cally: > > > > > > + > > > > > > +- `CONFIG_OF_BOARD` was added in rpi_patch_ for Raspberry Pi, = which 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= 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 use= d by RISC-V qemu > > > > > > + boards. > > > > > > + > > > > > > +Once this bug is fixed, CONFIG_OF_BOARD and CONFIG_OF_PRIOR_ST= AGE will override > > > > > > +(at runtime) the devicetree suppled with U-Boot, but will othe= rwise use > > > > > > +CONFIG_OF_SEPARATE for the in-tree build. So these two will be= come options, > > > > > > +moving out of the 'choice' in `dts/Kconfig` > > > > > > + > > > > > > +Offending boards are: > > > > > > + > > > > > > +- bcm7260 > > > > > > +- bcm7445 > > > > > > +- qemu_arm64 > > > > > > +- qemu_arm > > > > > > +- qemu-ppce500 > > > > > > +- qemu-riscv32 > > > > > > +- qemu-riscv32_smode > > > > > > +- qemu-riscv64 > > > > > > +- qemu-riscv64_smode > > > > > > + > > > > > > +All of these need to have a devicetree added in-tree. This is = targeted to be > > > > > > +fixed in the 2022.01 release. > > > > > > > > > > Do you have some idea of how to support the QEMU case, if not usi= ng > > > > > CONFIG_OF_PRIOR_STAGE? > > > > > > > > To be clear, I am not planning to remove this option. It will still= work. > > > > > > > > But I do want to have an in-tree devicetree for all boards, and > > > > someone will need to update qemu to support adding U-Boot > > > > nodes/properties. It always has an array of options controlling what > > > > it presents to BIOS/UEFI, for example, so this should not be too > > > > controversial. > > > > > > I think there is some misunderstanding. > > > > > > Adding U-Boot nodes/properties is not a problem for QEMU, but the > > > thing is that these QEMU targets don't require U-Boot specific > > > nodes/properties. It's just that QEMU will generate the DTB on the fly > > > based on different command-line options, so the DTB is dynamic and we > > > can't hardcode one in the U-Boot tree. > >=20 > > That's fine, but I do want some sort of sample in the tree, like we > > have for qemu-x86 and others. For some reason ARM and RISC-V don't > > have one. > >=20 > > Also, QEMU needs a way to add properties and nodes that are specific > > to U-Boot, since at present there is no way at all to pass these > > through (/config node, u-boot,dm-xxx tags, etc.). >=20 > I suppose some of the /config stuff could be nice and that the device > tree is indeed the most appropriate way to pass runtime options from > QEMU to U-Boot. But I'd say U-Boot should still work (with reasonable > defaults) if no U-Boot specific options are present in the device > tree. >=20 > My understanding is that the u-boot,dm-xxx tags are for SPL. It seems > that for most scenarios having where there is some prior firmware that > passes a device tree, SPL isn't used. That certainly is the case for > QEMU, Raspberry Pi and my Apple M1 work. This is key, for moving forward. We need to be able to function wholly and correctly with a device tree we are given by whatever stars "us" off. When we talk about QEMU, we need to keep in mind what QEMU is being used for, as the use cases. I feel like QEMU-as-QEMU really is to enable CI and perhaps enable debug/development workflows. QEMU-as-hardware (SiFive from Bin's recent patch, sabrelite that QEMU 6.1.0 supports, integrator, malta like we do today, and so on) should be "let us act like it's the real hardware". So if we're expecting a device tree to have X in it, we need to work with whatever the relevant upstreams are to have it. --=20 Tom --f35OJ//TcTYGpEDr Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQGzBAABCgAdFiEEGjx/cOCPqxcHgJu/FHw5/5Y0tywFAmErnVoACgkQFHw5/5Y0 tywDSAv+KSKVQtAM7M/MPauo2ATgXbpziIgV2tZQc0Ou6+aTKP6zg79hg00d3is0 Nzl4dYl+f0bhwd7gAwMD3PUwKZQHev7mmeNM6yDzLBoeyJGsizAomofcoraQ/pu7 TvJRuWtnDO3t4Bq7cjRBwlQMcwwVMp3LK8KEemtpaorbK58kuk2lzQTEFB4N1eSz wdTZJdAzzPoetc37IlwdqxBt4l999Dz5yfyjX/+v+xok/a5JmZCZgbOtl/tsYlto 52WBmMI56CYZtP4klT629EJuAmHkPha384qjcBQAsquK4A/nd50C60a9ISS2n4gy t2a7PXiKQKdjZg8K+cdBD9Uh0swlLIjIAtqCT4uq/7WFQfNDtwI+HdkMpZjU7xPn 0JOI+INdrHhSi3ivXqBwEgfF/OcH1iFNLA7rqNsL3foc+lNwafaq1+sxp+ltS+R4 fn6bveicVgHCJmZHmjCEsmxRgstsFdB3u1I7KTBD2YbgiS+fYQ690B/KbiQ+GH6O 3eeVi7Q9 =qIMs -----END PGP SIGNATURE----- --f35OJ//TcTYGpEDr--