[v3] doc: develop: Describe system configuration
Tom Rini
trini at konsulko.com
Fri Jul 29 19:08:03 CEST 2022
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 <trini at 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.glpk at gmx.de>
Thanks!
--
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 659 bytes
Desc: not available
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20220729/f1456a40/attachment.sig>
More information about the U-Boot
mailing list