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

[Tom Rini]

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?

-- 
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/20220728/d6c24085/attachment.sig>