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. > > > > Signed-off-by: Tom Rini <tr...@konsulko.com> > > --- > > 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. > > > > 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 static > > configuration. > > > > 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 them > > 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 clear > > 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 > > > > diff --git a/README b/README > > index 2c4bde0b3297..623f35907217 100644 > > --- a/README > > +++ b/README > > @@ -166,27 +166,6 @@ Directory Hierarchy: > > Software Configuration: > > ======================= > > > > -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: > > --------------------------------------------------- > > > > 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 > > > > 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 > > +==================== > > + > > +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 > > aspects of > > +the world can be configured at run time and others must be done at build > > time. > > +In general run time configuration is preferred over build time > > configuration. > > +But when making these decisions, we also need to consider if we're talking > > about > > +a feature that could be useful to virtually every platform or something > > specific > > +to a single hardware platform. The resulting image size is also another > > +important consideration. Finally, run time configuration has additional > > overhead > > +both in terms of resource requirements and wall clock time. All of this > > means > > +that care must be taken when writing new code to select the most > > appropriate > > +configuration mechanism. > > + > > +When adding new features to U-Boot, be they a new subsystem or SoC support > > or > > +new platform for an existing supported SoC, the preferred configuration > > order > > +is: > > + > > +#. Hardware based run time configuration. Examples of this include reading > > + processor specific registers, or a set of board specific GPIOs or an > > EEPROM > > + with a known format to it. These are the cases where we either cannot 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 > > enable or > > + disable some sort of feature, such as the SoC or network support. The > > + ``CONFIG`` prefix for C preprocessor macros is strictly reserved for > > Kconfig > > + usage only. > > + > > +#. Making use of the :doc:`device tree <devicetree/control>` to determine > > at > > + run time how to configure a feature that we have enabled via Kconfig. > > 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 > > macros that > > + have the ``CFG`` prefix. While the ``CFG`` prefix is reserved for this > > build > > + time configuration mechanism, the usage is ad hoc. This is to be used > > when the > > + previously mentioned mechanisms are not possible, or for legacy code > > 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 model > > +<driver-model/index>` 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 either > > not > > +possible or not practical to make a run time determination about some > > +functionality of the hardware or a required software feature or similar. > > Each of > > +these has their own places where they are better suited than the other for > > use. > > + > > +The `Kconfig language > > +<https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html>`_ is > > well > > +documented and used in a number of projects, including the Linux kernel. We > > +implement this with the Kconfig files found throughout our sources. This > > +mechanism is the preferred way of exposing new configuration options as > > there > > +are a number of ways for both users and system integrators to manage and > > change > > +these options. Some common examples here are to enable a specific command > > within > > +U-Boot or even a whole subsystem such as NAND flash or network > > connectivity. > > + > > +The ``CFG`` mechanism is implemented directly as C preprocessor values or > > +macros, depending on what they are in turn describing. While we have some > > +functionality that is very reasonable to expose to the end user to enable > > 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 > > should be > > +getting these values from the device tree. However, there are cases where > > this > > +is either not practical due to when we need the information and may not > > 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 > > %s/namespace/mechanism/ > > I will adjust this when merging. > > Reviewed-by: Heinrich Schuchardt <xypron.g...@gmx.de>
Thanks! -- Tom
signature.asc
Description: PGP signature