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 7AD4AC432BE for ; Sun, 29 Aug 2021 14:47:28 +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 C94F160F39 for ; Sun, 29 Aug 2021 14:47:27 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org C94F160F39 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 E0884832CB; Sun, 29 Aug 2021 16:47:25 +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="BTJuQU/6"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 191D383319; Sun, 29 Aug 2021 16:47:24 +0200 (CEST) Received: from mail-qt1-x82e.google.com (mail-qt1-x82e.google.com [IPv6:2607:f8b0:4864:20::82e]) (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 236D682EB9 for ; Sun, 29 Aug 2021 16:47:19 +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-x82e.google.com with SMTP id r21so9581026qtw.11 for ; Sun, 29 Aug 2021 07:47:19 -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=nCs70FCa1jKoSd7LU6HHOdi3eh0yhurf+0N3jg+1aLA=; b=BTJuQU/6j2oyPbE1imki27XBh5XFyP/xPlbVPkNz2NZeB9Mi8HyMuWMPtvCSG2sgw2 9TlOPEk/VzkYZi7AR2ePeFmmlMcw9OfEaPecYQd6CM6HtmP3tmTIDI08OWtl/GO8LKiR G0vsiLdkzdwc+gnDDoJI9nGLav99CPVm1su9w= 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=nCs70FCa1jKoSd7LU6HHOdi3eh0yhurf+0N3jg+1aLA=; b=ezSIZKZvrWmYz997o264XSiNaXk2BUlL2rbpe+mGqeOtgERra474cVEA/v+YLd6U4e g5HV+atv013mIFhn3vCNOk7T7j/rFbhV1/phGMSWhzV+5QvH9AKns3zE/BZrh6vJpoTO OR3R5D4VJE8h8+HwLrYqmhBCWrf3ebwdgprKwjr7GLR/2Per3LcbvHiR6LR2QGDmdPwc dZzhrIT9XvlrJy5DhXYqnNvEgV+oc/0lR9GLFjnKv15YhaeiilYdS7Fnd7r2Ct5E8PiU zlIv2WDcBuxBb0qFZnMwZx3HPvGhNZIqRJhGx4i6nyqGW+TSnP766CL39ipJylHhN7S5 49eA== X-Gm-Message-State: AOAM532ZoX3Nleoe701d3fsQbJ04ffbocViFVHmauSNDX2hcO1ERu9hm U8MYZeVg058YwTsnPXu+rvW93Q== X-Google-Smtp-Source: ABdhPJwM+kZvAp7cgqCjr5O5oGENiQANfOdobZonniMswZpkNeL7Og0hCdzeNzDUnpTYD0oAFAsQIg== X-Received: by 2002:ac8:7483:: with SMTP id v3mr16564144qtq.113.1630248437782; Sun, 29 Aug 2021 07:47:17 -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 c17sm7269427qtq.42.2021.08.29.07.47.16 (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Sun, 29 Aug 2021 07:47:17 -0700 (PDT) Date: Sun, 29 Aug 2021 10:47:15 -0400 From: Tom Rini To: Bin Meng Cc: Simon Glass , Mark Kettenis , U-Boot Mailing List , Heinrich Schuchardt , Sean Anderson Subject: Re: [PATCH] doc: Add documentation about devicetree usage Message-ID: <20210829144715.GE858@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="eWbA4KkXHy33HJL0" 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 --eWbA4KkXHy33HJL0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sun, Aug 29, 2021 at 09:43:12PM +0800, Bin Meng wrote: > Hi Simon, >=20 > On Sun, Aug 29, 2021 at 9:03 PM Simon Glass wrote: > > > > Hi Mark, > > > > On Sun, 29 Aug 2021 at 02:19, Mark Kettenis w= rote: > > > > > > > From: Simon Glass > > > > Date: Sat, 28 Aug 2021 20:07:27 -0600 > > > > > > > > Hi Bin, > > > > > > > > On Sat, 28 Aug 2021 at 19:29, Bin Meng wrote: > > > > > > > > > > Hi Simon, > > > > > > > > > > On Sun, Aug 29, 2021 at 12:45 AM Simon Glass w= rote: > > > > > > > > > > > > Hi Bin, > > > > > > > > > > > > On Sat, 28 Aug 2021 at 07:15, Bin Meng wro= te: > > > > > > > > > > > > > > Hi Simon, > > > > > > > > > > > > > > On Sat, Aug 28, 2021 at 11:23 AM 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 > > > > > > > > --- > > > > > > > > > > > > > > > > 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/devel= op/package/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 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. Spe= cifically: > > > > > > > > + > > > > > > > > +- `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. > > > > > > > > + > > > > > > > > +Once this bug is fixed, CONFIG_OF_BOARD and CONFIG_OF_PRIO= R_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 wil= l become 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= using > > > > > > > CONFIG_OF_PRIOR_STAGE? > > > > > > > > > > > > To be clear, I am not planning to remove this option. It will s= till 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 th= e fly > > > > > based on different command-line options, so the DTB is dynamic an= d we > > > > > can't hardcode one in the U-Boot tree. > > > > > > > > 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. > > > > > > > > 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.). > > > > > > 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. > > > > Well I believe it does and actually I think CI currently checks > > this.The config node is certainly optional. But it would not support > > booting signed images, for example, without the public key. > > > > > > > > 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. > > > > Yes that is true and I suppose is how things are able to work at presen= t. > > > > But I do see QMU for RISC-V with an SPL boot, although it is only > > mentioned in the docs, so perhaps it is not in the CI yet. If there > > are few enough devices and enough memory (and you don't care about > > boot speed) then the u-boot,dm-xxx tags are not strictly necessary. > > But then we are using QEMU in a somewhat unrealistic state. > > >=20 > RISC-V SPL is in CI testing. See qemu_riscv{32,64}_spl targets in the > u-boot/master and the recent patches for SiFive Unleashed. The qemu cases are so that we have the SPL flow in CI, right? --=20 Tom --eWbA4KkXHy33HJL0 Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQGzBAABCgAdFiEEGjx/cOCPqxcHgJu/FHw5/5Y0tywFAmErnfMACgkQFHw5/5Y0 tyxLvAv/f1RAIW7tcX+IRqkkfZJSJcpCVx5uCdsWxUw2YrCTnuBY/pGbeXtz6t3b F3wTjgYjS3JTF3AFyCSyVe30VlnGowziqYCz7O7Dd3g6srBVAT/V0Ahit/8dlMRA pvNBMCTpwnRR1ldQNgiHNztqQAQHWn+I9PYfc3cslVfnF/GhibQsGlbWuN/04UiA DecIAvZU5ANnJgNEx6MmdjdgIkNG4CCcEs8C6U9+cT4Q4Nu8LDUEzPNFeKMlIwtB qbJuyXj+0kcaE0fI9MxMb2JBO9s1jyhHYICmbAHdP7heIRtcAfvMIX5hXJFcunZa HiWSmKLBKvlEOJhGv4tdSqIi3e/64t3mq/3DWHOnePtgqwkR5Dyf9C/YkULYfBw+ g3WhV8bJlu2sipbzO4NCQOeZ9aMmjU+Ae9vHJzIyFxKEZch3E/QGnyLMj601sAeK gOPIKlkx/H+Ucw7Dfe5mZPNlyfy/YcQ6Ba0F046l9sjEg1igrP2+Rwx4KGH5nYuQ bCGCR48P =Fm0/ -----END PGP SIGNATURE----- --eWbA4KkXHy33HJL0--