Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org 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 smtp.lore.kernel.org (Postfix) with ESMTPS id 6463FC00144 for ; Fri, 29 Jul 2022 17:08:13 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id ABE7083FC5; Fri, 29 Jul 2022 19:08:11 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (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="PEUCYAwl"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id B0D7583FD0; Fri, 29 Jul 2022 19:08:10 +0200 (CEST) Received: from mail-qt1-x82d.google.com (mail-qt1-x82d.google.com [IPv6:2607:f8b0:4864:20::82d]) (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 29C8983FA2 for ; Fri, 29 Jul 2022 19:08:07 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=konsulko.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=trini@konsulko.com Received: by mail-qt1-x82d.google.com with SMTP id h22so3757642qta.3 for ; Fri, 29 Jul 2022 10:08:07 -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; bh=mNUkdYbdfa60x2dXkBZeetdDmYeGsI+zO9tg9kH1uQk=; b=PEUCYAwlL57FIcCrJYFaY23HPWR7DMv/PhhY57eb83XspDmS40dFTokNwYecllvpHr 6HtEIwgbTAw7j71pHf9F80xmCog00yl4JRKfarvkLvZrrcco8r6OJ8snXKah9Sx2tnTy 9CoEQ0ZB0CfmXSD5Jjk3aauZ9s4MFFXOSZuYE= 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; bh=mNUkdYbdfa60x2dXkBZeetdDmYeGsI+zO9tg9kH1uQk=; b=DrNLtcgjaT08xUeswp0ZmzvoWIYa2QDtXcRK/yMz+FLVOBduO4GHdxVss6Xtgs7y1t bN49FfS/x1Qjk6AE3dRDgh+y5wy7hg/H6NttK9UMdFJNiFGwSrlt30qhJpQdkd1Kh+HZ V+3ja6M9UsNaKIktCCjBASwp6z87KryitmlkAas9R13S4CccPZx2HGWyPFPop9D6Xzqn AErW+XCm3dXX+DlbwqN/gmb4dyxEM5FMlTm1J4r6fpRR0DjscabGeXDQvKjimN/oyWrQ 30Id0AhtcejwEX5mIL+JkYJXRAvjgUGdmdKQZmkasVeBBk5MzU1uoBKneBbV2vi7BMXs YSjw== X-Gm-Message-State: AJIora9yv6SbTJYdYHIHnnWIk1L2tL77eBxcJ2Tclh3D3ufHdDwUpv6i LkiLiqf19rHXHZdtYnMxQPRU1w== X-Google-Smtp-Source: AGRyM1tlf30NJMkomCdGu7iMh9NXFbtmrk0qH8YSm/wCLmf0HNJh2HYZ4Ybjy1kBYNU1PIt0ZRTuyA== X-Received: by 2002:ac8:5f4c:0:b0:320:795c:b414 with SMTP id y12-20020ac85f4c000000b00320795cb414mr4325513qta.302.1659114485772; Fri, 29 Jul 2022 10:08:05 -0700 (PDT) Received: from bill-the-cat (cpe-65-184-195-139.ec.res.rr.com. [65.184.195.139]) by smtp.gmail.com with ESMTPSA id u5-20020a05620a430500b006b5988b2ca8sm3031982qko.40.2022.07.29.10.08.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 29 Jul 2022 10:08:04 -0700 (PDT) Date: Fri, 29 Jul 2022 13:08:03 -0400 From: Tom Rini To: Heinrich Schuchardt Cc: Pali =?iso-8859-1?Q?Roh=E1r?= , Simon Glass , u-boot@lists.denx.de Subject: Re: [v3] doc: develop: Describe system configuration Message-ID: <20220729170803.GT1146598@bill-the-cat> References: <20220729160738.1235524-1-trini@konsulko.com> <711b363a-a7f1-f3b8-6125-b0ad4294125c@gmx.de> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="7HVArpy0IqoV80ek" Content-Disposition: inline In-Reply-To: <711b363a-a7f1-f3b8-6125-b0ad4294125c@gmx.de> X-Clacks-Overhead: GNU Terry Pratchett X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 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.6 at phobos.denx.de X-Virus-Status: Clean --7HVArpy0IqoV80ek Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Fri, Jul 29, 2022 at 06:51:50PM +0200, Heinrich Schuchardt wrote: > On 7/29/22 18:07, Tom Rini wrote: > > Start by describing in general the best practices for how to implement > > configuration of some aspect of U-Boot. This generally means finding > > the right choices for when something should be static or dynamically > > configured and enabled. Then further document when to use CONFIG or CFG > > namespaces for static configuration. > >=20 > > Signed-off-by: Tom Rini > > --- > > Changes in v3: > > - Drop RFC prefix. > > - Incorporate most of the specific wording changes Heinrich requested > > against v2. > > - Heinrich disliked the "namespace" wording in v2, and that in turn was > > a hold over from when this talked only about CONFIG vs CFG. Remove > > that word entirely and instead talk about configuration mechanisms. > > Reword a number of sections and examples so that they read better or > > hopefully more clearly now that we talk about different mechanisms. > > - Expand on when to use each configuration mechanism. Generally don't > > refer to CONFIG but instead Kconfig. > >=20 > > RFCv2: > > - Based on Pali's feedback, remove the README section and start a new > > section in this document to cover when to use each namespace. Try and > > be clear about when to use "hidden" Kconfig options rather than CFG = as > > well. > > - Based on Heinrich's feedback, rename this to system_configuration.rst > > and include some introductory remarks on when to use some dynamic or > > static configuration. Link to the driver model code for dynamic > > configuration and then explain the CONFIG vs CFG namespaces for stat= ic > > configuration. > >=20 > > RFCv1: > > - This is essentially my idea on how to better handle the problem of > > CONFIG values that just don't fit in Kconfig because it makes much > > more sense to define them statically for a given SoC or calculate th= em > > from other values, and so on. One example here would be to revert > > c7fad78ec0ee ("Convert CONFIG_SYS_BR0_PRELIM et al to Kconfig") and > > re-name these to CFG_SYS_.. instead. Another big example here would = be > > a global search-and-replace of 's/CONFIG_HPS_/CFG_HPS_/g' as that's > > all tool-generated. Not all CONFIG_SYS_ options would get this as > > boolean choices are well handled in Kconfig, and that may not be cle= ar > > enough in what I wrote here? > > --- > > README | 21 ----- > > doc/develop/index.rst | 1 + > > doc/develop/system_configuration.rst | 132 +++++++++++++++++++++++++++ > > 3 files changed, 133 insertions(+), 21 deletions(-) > > create mode 100644 doc/develop/system_configuration.rst > >=20 > > diff --git a/README b/README > > index 2c4bde0b3297..623f35907217 100644 > > --- a/README > > +++ b/README > > @@ -166,27 +166,6 @@ Directory Hierarchy: > > Software Configuration: > > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > >=20 > > -Configuration is usually done using C preprocessor defines; the > > -rationale behind that is to avoid dead code whenever possible. > > - > > -There are two classes of configuration variables: > > - > > -* Configuration _OPTIONS_: > > - These are selectable by the user and have names beginning with > > - "CONFIG_". > > - > > -* Configuration _SETTINGS_: > > - These depend on the hardware etc. and should not be meddled with if > > - you don't know what you're doing; they have names beginning with > > - "CONFIG_SYS_". > > - > > -Previously, all configuration was done by hand, which involved creating > > -symbolic links and editing configuration files manually. More recently, > > -U-Boot has added the Kbuild infrastructure used by the Linux kernel, > > -allowing you to use the "make menuconfig" command to configure your > > -build. > > - > > - > > Selection of Processor Architecture and Board Type: > > --------------------------------------------------- > >=20 > > diff --git a/doc/develop/index.rst b/doc/develop/index.rst > > index 73741ceb6a2f..7c41e3f1b6e5 100644 > > --- a/doc/develop/index.rst > > +++ b/doc/develop/index.rst > > @@ -13,6 +13,7 @@ General > > designprinciples > > process > > release_cycle > > + system_configuration > >=20 > > Implementation > > -------------- > > diff --git a/doc/develop/system_configuration.rst b/doc/develop/system_= configuration.rst > > new file mode 100644 > > index 000000000000..1279d12cb7ae > > --- /dev/null > > +++ b/doc/develop/system_configuration.rst > > @@ -0,0 +1,132 @@ > > +.. SPDX-License-Identifier: GPL-2.0+ > > + > > +System configuration > > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > + > > +There are a number of different aspects to configuring U-Boot to build= and then > > +run on a given platform or set of platforms. Broadly speaking, some as= pects of > > +the world can be configured at run time and others must be done at bui= ld time. > > +In general run time configuration is preferred over build time configu= ration. > > +But when making these decisions, we also need to consider if we're tal= king about > > +a feature that could be useful to virtually every platform or somethin= g specific > > +to a single hardware platform. The resulting image size is also another > > +important consideration. Finally, run time configuration has additiona= l overhead > > +both in terms of resource requirements and wall clock time. All of thi= s means > > +that care must be taken when writing new code to select the most appro= priate > > +configuration mechanism. > > + > > +When adding new features to U-Boot, be they a new subsystem or SoC sup= port or > > +new platform for an existing supported SoC, the preferred configuratio= n order > > +is: > > + > > +#. Hardware based run time configuration. Examples of this include rea= ding > > + processor specific registers, or a set of board specific GPIOs or a= n EEPROM > > + with a known format to it. These are the cases where we either cann= ot or > > + should not be relying on device tree checks. We use this for cases = such as > > + optimized boot time or starting with a generic device tree and then= enabling > > + or disabling features as we boot. > > + > > +#. Making use of our Kconfig infrastructure and C preprocessor macros = that have > > + the prefix ``CONFIG``. This is the primary method of build time > > + configuration. This is generally the best fit for when we want to e= nable or > > + disable some sort of feature, such as the SoC or network support. T= he > > + ``CONFIG`` prefix for C preprocessor macros is strictly reserved fo= r Kconfig > > + usage only. > > + > > +#. Making use of the :doc:`device tree ` to determ= ine at > > + run time how to configure a feature that we have enabled via Kconfi= g. For > > + example, we would use Kconfig to enable an i2c chip driver, but use= the device > > + tree to know where the i2c chip resides in memory and other details= we need > > + in order to configure the bus. > > + > > +#. Making use of C header files directly and defining C preprocessor m= acros that > > + have the ``CFG`` prefix. While the ``CFG`` prefix is reserved for t= his build > > + time configuration mechanism, the usage is ad hoc. This is to be us= ed when the > > + previously mentioned mechanisms are not possible, or for legacy cod= e that has > > + not been converted. > > + > > +Dynamic run time configuration methods. > > +--------------------------------------- > > + > > +Details of hardware specific run time configuration methods are found = within the > > +documentation for a given processor family or board. > > + > > +Details of how to use run time configuration based on :doc:`driver mod= el > > +` are covered in that documentation section. > > + > > +Static build time configuration methods > > +--------------------------------------- > > + > > +There are two mechanisms used to control the build time configuration = of U-Boot. > > +One is utilizing Kconfig and ``CONFIG`` prefixed macros and the other = is ad hoc > > +usage of ``CFG`` prefixed macros. Both of these are used when it is ei= ther not > > +possible or not practical to make a run time determination about some > > +functionality of the hardware or a required software feature or simila= r. Each of > > +these has their own places where they are better suited than the other= for use. > > + > > +The `Kconfig language > > +`= _ is well > > +documented and used in a number of projects, including the Linux kerne= l. We > > +implement this with the Kconfig files found throughout our sources. Th= is > > +mechanism is the preferred way of exposing new configuration options a= s there > > +are a number of ways for both users and system integrators to manage a= nd change > > +these options. Some common examples here are to enable a specific comm= and within > > +U-Boot or even a whole subsystem such as NAND flash or network connect= ivity. > > + > > +The ``CFG`` mechanism is implemented directly as C preprocessor values= or > > +macros, depending on what they are in turn describing. While we have s= ome > > +functionality that is very reasonable to expose to the end user to ena= ble or > > +disable we have other places where we need to describe things such as = register > > +locations or values, memory map ranges and so on. When practical, we s= hould be > > +getting these values from the device tree. However, there are cases wh= ere this > > +is either not practical due to when we need the information and may no= t have a > > +device tree yet or due to legacy reasons code has not been rewritten. > > + > > +When to use each mechanism > > +^^^^^^^^^^^^^^^^^^^^^^^^^^ > > + > > +While there are some cases where it should be fairly obvious where to = use each > > +namespace, as for example a command would done via Kconfig, a new i2c = driver >=20 > %s/namespace/mechanism/ >=20 > I will adjust this when merging. >=20 > Reviewed-by: Heinrich Schuchardt Thanks! --=20 Tom --7HVArpy0IqoV80ek Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQGzBAABCgAdFiEEGjx/cOCPqxcHgJu/FHw5/5Y0tywFAmLkE+8ACgkQFHw5/5Y0 tywpWQv+P1dcnOy6EKtyyiYqonIvrEJqrtxXVqC5IcBMWqtHiLYqy4xiaOkQkfU8 EsaHu7U6Br3yesR3pF/mMH6n2yDUOPQZTU+cSwIuxJ0JgKvpXmBTumwi8E/5bhxA qr4275elOOcIK/VE1beAhdjc0sarvrLEdXe/YTv73oVbXOU6QXeMUlqsM58gojgX 0K+7m5pDbuJeaIsWcuItwnLmoQcOxGrwrW3VEswWlkS5fuyIDVZDs5xL2JdLcS5i aSxLOWAJhKT07voPjVVdD58W0KYQ2Xp9tSTvCYoVMf3DShnQhUltfgkNf0uNO+LB h92cwIVgE3LTA0WPzAOHac1izg/8Jkr7YWN4QGJdn7JI0/rUX95XJKhlRGAPQbQg NIijuVSTpoxoKDR0xSB7qoTKmIazzH1zQMVWkwDTZ0uH3Q7H5MXeHy9kKU/PRsHI h8HWdWTtdtM7NMHu8ZoEXuRXgmQclOTklWvPxNJeLA1pwubvvwTO1qKIWfVWvSel s2xnQuyI =UVpz -----END PGP SIGNATURE----- --7HVArpy0IqoV80ek--