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

[Heinrich Schuchardt]

Am 28. Juli 2022 19:53:34 MESZ schrieb Tom Rini <trini at konsulko.com>:
>On Thu, Jul 28, 2022 at 06:44:56PM +0200, Heinrich Schuchardt wrote:
>> 
>> 
>> 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.
>
>I've rewritten things a bit so far to try and be clearer on CONFIG vs
>CFG.  Maybe I should rename it to system_configuration.rst and try and
>talk more about when to get something at run-time?

Such a broadened scope would be helpful for future developers.

Best regards

Heinrich