doc: Document Zephyr's Kconfig configuration scheme

In particular, try to demystify Kconfig.defconfig files, and provide
guidelines on whether configuration settings should go in
BOARD_defconfig or Kconfig.defconfig.

The board porting section seems to be the most relevant one here, so put
the documentation there, with some "see also" links from elsewhere.
Things could be reorganized later if needed.

Give a general overview of visible and invisible Kconfig symbols as
well, as that ties in with the configuration scheme.

This is reverse-engineering on my part. The configuration scheme doesn't
seem to be documented anywhere prior.

Fixes: zephyrproject-rtos#7159

Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>

doc/application/application.rst

@@ -880,6 +880,9 @@ As long as :file:`zephyr/.config` exists and is up-to-date (is newer than the
 preference to producing a new merged configuration. This can be used during
 development, as described below in :ref:`override_kernel_conf`.
 
+For more information on Zephyr's Kconfig configuration scheme, see the
+:ref:`setting_configuration_values` section in the :ref:`board_porting_guide`.
+
 For information on available kernel configuration options, including
 inter-dependencies between options, see the :ref:`configuration`.
 

doc/porting/arch.rst

@@ -14,6 +14,10 @@ The following are examples of ISAs and ABIs that Zephyr supports:
 * ARMv7-M ISA with Thumb2 instruction set and ARM Embedded ABI (aeabi)
 * ARCv2 ISA
 
+For information on Kconfig configuration, see the
+:ref:`setting_configuration_values` section in the :ref:`board_porting_guide`.
+Architectures use a similar Kconfig configuration scheme.
+
 An architecture port can be divided in several parts; most are required and
 some are optional:
 

doc/porting/board_porting.rst

@@ -147,3 +147,114 @@ guidelines should be followed when porting a board:
 - Propose and configure a default network interface.
 
 - Enable all GPIO ports.
+
+.. _setting_configuration_values:
+
+Setting configuration values
+============================
+
+Kconfig symbols can be set to their ``BOARD``-specific values in one of two
+ways. The right method to use depends on whether the symbol is *visible* or
+not.
+
+
+Visible and invisible Kconfig symbols
+-------------------------------------
+
+Kconfig symbols come in two varieties:
+
+- A Kconfig symbol defined with a prompt is *visible*, and can be configured from
+  the ``menuconfig`` configuration interface.
+
+- A Kconfig symbol defined without a prompt is *invisible*. The user has no
+  direct control over its value.
+
+Here are some examples of visible and invisible symbols:
+
+.. code-block:: none
+
+    config NOT_VISIBLE
+    	bool
+    	default FOO
+
+    config VISIBLE_1
+    	bool "Enable stuff"
+
+    config VISIBLE_2
+    	string
+    	prompt "Foo value"
+
+
+Configuring visible Kconfig symbols
+-----------------------------------
+
+Default ``BOARD``-specific configuration values for visible Kconfig symbols
+*should* be given in :file:`boards/ARCHITECTURE/BOARD/BOARD_defconfig`, which
+uses the standard Kconfig :file:`.config` file syntax.
+
+
+Configuring invisible Kconfig symbols
+-------------------------------------
+
+``BOARD``-specific configuration values for invisible Kconfig symbols *must* be
+given in :file:`boards/ARCHITECTURE/BOARD/Kconfig.defconfig`, which uses
+Kconfig syntax.
+
+Assigning values in :file:`Kconfig.defconfig` relies on being able to define a
+Kconfig symbol in multiple locations. As an example, say we want to set
+``FOO_WIDTH`` below to 32:
+
+.. code-block:: none
+
+    config FOO_WIDTH
+    	int
+
+To do this, we extend the definition of ``FOO_WIDTH`` as follows, in
+:file:`Kconfig.defconfig`:
+
+.. code-block:: none
+
+    if BOARD_MY_BOARD
+
+    config FOO_WIDTH
+    	default 32
+
+    endif
+
+.. note::
+
+    Since the type of the symbol (``int``) has already been given at the first
+    definition location, it does not need to be repeated here.
+
+``default`` properties from :file:`Kconfig.defconfig` files override
+``default`` properties given on the "base" definition of the symbol. Zephyr
+uses a custom Kconfig patch that makes Kconfig prefer later defaults, and
+includes the :file:`Kconfig.defconfig` files last.
+
+.. note::
+
+    Assignments in :file:`.config` files have no effect on invisible symbols,
+    so this scheme is not just an organizational issue.
+
+If you want a symbol to only be user-configurable on some boards, make its base
+definition have no prompt, and then add a prompt to it in the
+:file:`Kconfig.defconfig` files of the boards where it should be configurable.
+
+.. note::
+
+    Prompts added in :file:`Kconfig.defconfig` files show up at the location of
+    the :file:`Kconfig.defconfig` file in the ``menuconfig`` interface, rather
+    than at the location of the base definition of the symbol.
+
+Motivation
+----------
+
+One motivation for this scheme is to avoid making fixed ``BOARD``-specific
+settings configurable in the ``menuconfig`` interface. If all
+configuration were done via :file:`boards/ARCHITECTURE/BOARD/BOARD_defconfig`,
+all symbols would have to be visible, as values given in
+:file:`boards/ARCHITECTURE/BOARD/BOARD_defconfig` have no effect on invisible
+symbols.
+
+Having fixed settings be user-configurable might be confusing, and would allow
+the user to create broken configurations.