[RFCv1] doc: develop: Describe using CONFIG vs CFG for values

[Heinrich Schuchardt]

Am 28. Juli 2022 15:20:46 MESZ schrieb Tom Rini <trini at konsulko.com>:
>Document how and when to use CONFIG or CFG namespace for options.  There
>are times where Kconfig is not a great fit for our needs, so we want to
>use the CFG namespace instead.
>
>Signed-off-by: Tom Rini <trini at konsulko.com>
>---
>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?
>---
> doc/develop/build_configuration.rst | 36 +++++++++++++++++++++++++++++
> doc/develop/index.rst               |  1 +
> 2 files changed, 37 insertions(+)
> create mode 100644 doc/develop/build_configuration.rst
>
>diff --git a/doc/develop/build_configuration.rst b/doc/develop/build_configuration.rst
>new file mode 100644
>index 000000000000..541ce528b36a
>--- /dev/null
>+++ b/doc/develop/build_configuration.rst
>@@ -0,0 +1,36 @@
>+.. SPDX-License-Identifier: GPL-2.0+
>+
>+Using CONFIG or CFG to configure the build
>+==========================================
>+
>+There are two namespaces used to control the build-time configuration of
>+U-Boot, ``CONFIG`` and ``CFG``. 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 first of these, ``CONFIG``` is managed in the `Kconfig language
>+<https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html>`_ that is
>+most commonly associated with the Linux kernel and the Kconfig files found
>+throughout our sources. Adding options to this namespace 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 second of these, ``CFG`` is implemented directly as C preprocessor values or
>+macros, depending on what they are in turn describing. The nature of U-Boot
>+means that 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 :doc:`device tree
>+<devicetree/control>`. 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. As this information tends
>+to be specific to a given SoC (or family of SoCs) or if board specific something
>+that is mandated by the physical design rather than truly user configurable, it
>+is acceptable to ``#define`` these values in the ``CFG`` namespace. It is
>+strongly encouraged to place these in the architecture header files, if they are
>+generic to a given SoC, or under the board directory if board specific. Placing
>+them under the board.h file in the *include/configs/* directory should be seen
>+as a last resort.

I would prefer to have numbered list of priorities:

Get property
1) by runtime probing if the U-Boot binary supports multiple boards
2) from Kconfig CONFIG value
3) from DT at runtime
4) from SoC specific CFG constant value
5) from board specific CFG constant value

I am not sure about the sequence of 2 and 3. We don't want to replace defconfig by DT. But we wouldn't want register addresses in Kconfig either. So this needs mire elaboration.

Best regards

Heinrich 

>diff --git a/doc/develop/index.rst b/doc/develop/index.rst
>index 73741ceb6a2f..c8ec7c210d35 100644
>--- a/doc/develop/index.rst
>+++ b/doc/develop/index.rst
>@@ -9,6 +9,7 @@ General
> .. toctree::
>    :maxdepth: 1
> 
>+   build_configuration
>    codingstyle
>    designprinciples
>    process