michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: kconfig: Put all documentation on setting symbols on a new page

Browse source 
Add a new 'Setting Kconfig configuration values' page in the new Kconfig
section in 'User and Developer Guides'. Move all the information on
setting Kconfig symbols from 'Application Development' and the board
porting guide into it. The same page now covers both configuration files
and Kconfig.defconfig files.

Add links to the new page in various places to make it easy to find.
Also add some more references to the top-level Kconfig page and other
Kconfig pages.

A lot of stuff was rewritten while moving it over (the CONF_FILE
documentation has been cleaned up in particular). Some new information
has been added as well, like a tip re. minimal configurations being
helpful when making Kconfig settings permanent, and a warning re.
dependencies being ORed rather than ANDed when defining a symbol in
multiple locations.

Fixes: #20915

Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
This commit is contained in:
Ulf Magnusson 2019-12-04 11:13:12 +01:00 • committed by Carles Cufí
commit e32686d0d6
7 changed files with 375 additions and 340 deletions
Download patch file Download diff file Expand all files Collapse all files

162
doc/application/index.rst
View file

@ -48,13 +48,12 @@ These contents are:
debug compiled binaries on real or emulated hardware, and more. debug compiled binaries on real or emulated hardware, and more.
* **Kernel configuration files**: An application typically provides a * **Kernel configuration files**: An application typically provides a
configuration file (usually called :file:`prj.conf`) that specifies Kconfig configuration file (usually called :file:`prj.conf`) that specifies
application-specific values for one or more kernel configuration options. application-specific values for one or more kernel configuration options.
These application settings are merged with board-specific settings to produce These application settings are merged with board-specific settings to produce
a kernel configuration. a kernel configuration.
The :ref:`application_kconfig` section below goes over application See :ref:`application-kconfig` below for more information.
configuration in detail.
* **Application source code files**: An application typically provides one * **Application source code files**: An application typically provides one
or more application-specific files, written in C or assembly language. These or more application-specific files, written in C or assembly language. These
@ -87,6 +86,9 @@ At the top of the tree there are several files that are of importance:
The top-level Kconfig file, which refers to the file :file:`Kconfig.zephyr` The top-level Kconfig file, which refers to the file :file:`Kconfig.zephyr`
also found at the top-level directory. also found at the top-level directory.
See :ref:`the Kconfig section of the manual <kconfig>` for detailed Kconfig
documentation.
:file:`west.yml` :file:`west.yml`
The :ref:`west` manifest, listing the external repositories managed by The :ref:`west` manifest, listing the external repositories managed by
the west command-line tool. the west command-line tool.
@ -221,15 +223,7 @@ Follow these steps to create a new application directory. (Refer to
:file:`boilerplate.cmake`. The most recent of the two :file:`boilerplate.cmake`. The most recent of the two
versions will be enforced by CMake. versions will be enforced by CMake.
#. Set any Kconfig values needed by your application. Zephyr uses the same #. Set Kconfig configuration options. See :ref:`application-kconfig`.
Kconfig system as the Linux kernel, but with its own database of
configuration options.
For example, create a file named :file:`prj.conf` in the :file:`app`
directory, and enable or disable Kconfig features as needed. You can use
existing :ref:`samples-and-demos` to get started with Kconfig variables you
are interested in. See :ref:`application_kconfig` for more details, and
:ref:`configuration_options` for a complete list of available options.
#. Optionally, you can also configure any devicetree overlays needed by your #. Optionally, you can also configure any devicetree overlays needed by your
application. See :ref:`application_dt` below for details. application. See :ref:`application_dt` below for details.
@ -272,6 +266,8 @@ should know about.
semicolons. Each file includes Kconfig configuration values that override semicolons. Each file includes Kconfig configuration values that override
the default configuration values. the default configuration values.
See :ref:`initial-conf` for more information.
* :makevar:`DTC_OVERLAY_FILE`: Indicates the name of one or more devicetree * :makevar:`DTC_OVERLAY_FILE`: Indicates the name of one or more devicetree
overlay files. Multiple filenames can be separated with either spaces or overlay files. Multiple filenames can be separated with either spaces or
semicolons. Each file includes devicetree values that override the default semicolons. Each file includes devicetree values that override the default
@ -1087,7 +1083,7 @@ Make sure to follow these steps in order.
set(CONF_FILE "fragment_file1.conf") set(CONF_FILE "fragment_file1.conf")
list(APPEND CONF_FILE "fragment_file2.conf") list(APPEND CONF_FILE "fragment_file2.conf")
More details are available below in :ref:`application_kconfig`. See :ref:`initial-conf` for more information.
#. If your application uses a devicetree overlay file or files other than #. If your application uses a devicetree overlay file or files other than
the usual :file:`<board>.overlay`, add lines setting the the usual :file:`<board>.overlay`, add lines setting the
@ -1099,6 +1095,9 @@ Make sure to follow these steps in order.
create a :file:`Kconfig` file in the same directory as your create a :file:`Kconfig` file in the same directory as your
application's :file:`CMakeLists.txt`. application's :file:`CMakeLists.txt`.
See :ref:`the Kconfig section of the manual <kconfig>` for detailed
Kconfig documentation.
An (unlikely) advanced use case would be if your application has its own An (unlikely) advanced use case would be if your application has its own
unique configuration **options** that are set differently depending on the unique configuration **options** that are set differently depending on the
build configuration. build configuration.
@ -1112,8 +1111,8 @@ Make sure to follow these steps in order.
.. note:: .. note::
Environment variables in ``source`` statements are expanded directly, Environment variables in ``source`` statements are expanded directly, so
so you do not need to define an ``option env="ZEPHYR_BASE"`` Kconfig you do not need to define an ``option env="ZEPHYR_BASE"`` Kconfig
"bounce" symbol. If you use such a symbol, it must have the same name as "bounce" symbol. If you use such a symbol, it must have the same name as
the environment variable. the environment variable.
@ -1177,138 +1176,33 @@ documentation `runningcmake`_ .
.. _runningcmake: http://cmake.org/runningcmake/ .. _runningcmake: http://cmake.org/runningcmake/
.. _application_configuration:
Application Configuration Application Configuration
************************* *************************
.. _application_kconfig: .. _application-kconfig:
Kconfig Configuration Kconfig Configuration
===================== =====================
Use the ``menuconfig`` and ``guiconfig`` interfaces to test out different Application configuration options are usually set in :file:`prj.conf` in the
configurations during development. See :ref:`menuconfig` for more information. application directory. For example, C++ support could be enabled with this
assignment:
The Initial Kconfig Configuration
---------------------------------
The initial configuration for an application is produced by merging
configuration settings from three sources:
1. A :makevar:`BOARD`-specific configuration file, stored in
:file:`boards/ARCHITECTURE/BOARD/BOARD_defconfig` in the Zephyr base
directory.
2. Any CMakeCache entries that are prefixed with :makevar:`CONFIG_`.
3. One or more application-specific configuration files.
The application-specific configuration file(s) can be specified in any of the
following ways. The simplest option is to just have a single :file:`prj.conf`
file.
1. If :makevar:`CONF_FILE` is set in :file:`CMakeLists.txt` (**before including
the boilerplate.cmake file**), or is present in the CMake variable cache,
or is specified via the ``-DCONF_FILE=<conf file(s)>`` when invoking CMake
(either directly or via ``west``) the configuration files specified in it
are merged and used as the application-specific settings.
2. Otherwise (if (1.) does not apply), if a file :file:`prj_BOARD.conf` exists
in the application directory, where :makevar:`BOARD` is the BOARD value set
earlier, the settings in it are used.
3. Otherwise (if (2.) does not apply), if a file :file:`boards/BOARD.conf` exists
in the application directory, where :makevar:`BOARD` is the BOARD value set
earlier, the settings in it are merged with :file:`prj.conf` and used.
4. Otherwise, if a file :file:`prj.conf` exists in the application directory,
the settings in it are used.
Configuration settings that have not been specified fall back on their
default value, as given in the :file:`Kconfig` files.
The merged configuration is saved in :file:`zephyr/.config` in the build
directory.
As long as :file:`zephyr/.config` exists and is up-to-date (is newer than the
:makevar:`BOARD` and application configuration files), it will be used in
preference to producing a new merged configuration. This can be used to test
out configurations during development, as described in :ref:`menuconfig`.
For more information on Zephyr's Kconfig configuration scheme, see the
:ref:`setting_configuration_values` section in the :ref:`board_porting_guide`.
For some tips and general recommendations when writing Kconfig files, see the
:ref:`kconfig_tips_and_tricks` page.
For information on available kernel configuration options, including
inter-dependencies between options, see the :ref:`configuration_options`.
.. note::
Dependencies between options can also be viewed in the :ref:`interactive
configuration interfaces <menuconfig>`. They will show the most up-to-date
dependencies, and also show which dependencies are currently unsatisfied.
To view the dependencies of an option in e.g. ``menuconfig``, jump to it
with :kbd:`/` and press :kbd:`?`. For each unsatisfied dependency, jump to
it in turn to check its dependencies.
.. _application_set_conf:
Making Kconfig Configuration Settings Permanent
-----------------------------------------------
This section describes how to edit Zephyr configuration (:file:`.conf`) files
to make configuration settings permanent.
- Add each configuration entry on a new line.
- Enable or disable a boolean option by setting its value to ``y`` or ``n``:
.. code-block:: none .. code-block:: none
CONFIG_SOME_BOOL=y CONFIG_CPLUSPLUS=y
CONFIG_SOME_OTHER_BOOL=n
.. note:: Looking at :ref:`existing samples <samples-and-demos>` is a good way to get
started.
Another way to set a boolean symbol to ``n`` is with a comment with the See :ref:`setting_configuration_values` for detailed documentation on setting
following format: Kconfig configuration values. The :ref:`initial-conf` section on the same page
explains how the initial configuration is derived. See
.. code-block:: none :ref:`configuration_options` for a complete list of configuration options.
# CONFIG_SOME_OTHER_BOOL is not set
This style is accepted for a technical reason: Kconfig configuration files
can be parsed as makefiles (though Zephyr doesn't use this). Having
``n``-valued symbols correspond to unset variables simplifies tests in
Make.
- You can set integer and string options as well, like this:
.. code-block:: none
CONFIG_SOME_INT=42
CONFIG_SOME_STRING="the best value ever"
- Ensure that each entry setting an option contains no spaces
(including on either side of the = sign).
- Use a # followed by a space to comment a line:
.. code-block:: none
# This is a comment.
The example below shows a comment line and an override setting
:option:`CONFIG_PRINTK` to ``y``:
.. code-block:: c
# Enable printk for debugging
CONFIG_PRINTK=y
The other pages in the :ref:`Kconfig section of the manual <kconfig>` are also
worth going through, especially if you planning to add new configuration
options.
.. _application_dt: .. _application_dt:

3
doc/guides/kconfig/index.rst
View file

@ -1,3 +1,5 @@
.. _kconfig:
Kconfig Kconfig
####### #######
@ -5,6 +7,7 @@ Kconfig
:maxdepth: 1 :maxdepth: 1
menuconfig.rst menuconfig.rst
setting.rst
tips.rst tips.rst
preprocessor-functions.rst preprocessor-functions.rst
extensions.rst extensions.rst

2
doc/guides/kconfig/menuconfig.rst
View file

@ -20,7 +20,7 @@ terminal, while ``guiconfig`` is a graphical configuration interface.
re-configuring. re-configuring.
To make a setting permanent, you should set it in a :file:`*.conf` file, as To make a setting permanent, you should set it in a :file:`*.conf` file, as
described in :ref:`application_set_conf`. described in :ref:`setting_configuration_values`.
.. tip:: .. tip::

326
doc/guides/kconfig/setting.rst Normal file
View file

@ -0,0 +1,326 @@
.. _setting_configuration_values:
Setting Kconfig configuration values
####################################
The :ref:`menuconfig and guiconfig interfaces <menuconfig>` can be used to test
out configurations during application development. This page explains how to
make settings permanent.
An auto-generated list of all Kconfig options can be found in the :ref:`Kconfig
symbol reference <configuration_options>`.
.. note::
Before making changes to Kconfig files, it's a good idea to also go through
the :ref:`kconfig_tips_and_tricks` page.
Visible and invisible Kconfig symbols
*************************************
When making Kconfig changes, it's important to understand the difference
between *visible* and *invisible* symbols.
- A visible symbol is a symbol defined with a prompt. Visible symbols show
up in the interactive configuration interfaces (hence *visible*), and can be
set in configuration files.
Here's an example of a visible symbol:
.. code-block:: none
config FLOAT
bool "Support floating point operations"
depends on HAS_FPU
The symbol is shown like this in ``menuconfig``, where it can be toggled:
.. code-block:: none
[ ] Support floating point operations
- An *invisible* symbol is a symbol without a prompt. Invisible symbols are
not shown in the interactive configuration interfaces, and users have no
direct control over their value. They instead get their value from defaults
or from other symbols.
Here's an example or an invisible symbol:
.. code-block:: none
config CPU_HAS_FPU
bool
help
This symbol is y if the CPU has a hardware floating point unit.
In this case, ``CPU_HAS_FPU`` is enabled through other symbols having
``select CPU_HAS_FPU``.
Setting symbols in configuration files
**************************************
Visible symbols can be configured by setting them in configuration files. The
initial configuration is produced by merging a :file:`*_defconfig` file for the
board with application settings, usually from :file:`prj.conf`. See
:ref:`initial-conf` below for more details.
Assignments in configuration files use this syntax:
.. code-block:: none
CONFIG_<symbol name>=<value>
There should be no spaces around the equals sign.
``bool`` symbols can be enabled or disabled by setting them to ``y`` or ``n``,
respectively. The ``FLOAT`` symbol from the example above could be enabled like
this:
.. code-block:: none
CONFIG_FLOAT=y
.. note::
A boolean symbol can also be set to ``n`` with a comment formatted like
this:
.. code-block:: none
# CONFIG_SOME_OTHER_BOOL is not set
This is the format you will see in the merged configuration in
:file:`zephyr/.config`.
This style is accepted for historical reasons: Kconfig configuration files
can be parsed as makefiles (though Zephyr doesn't use this). Having
``n``-valued symbols correspond to unset variables simplifies tests in Make.
Other symbol types are assigned like this:
.. code-block:: none
CONFIG_SOME_STRING="cool value"
CONFIG_SOME_INT=123
Comments use a #:
.. code-block:: none
# This is a comment
Assignments in configuration files are only respected if the dependencies for
the symbol are satisfied. A warning is printed otherwise. To figure out what
the dependencies of a symbol are, use one of the :ref:`interactive
configuration interfaces <menuconfig>` (you can jump directly to a symbol with
:kbd:`/`), or look up the symbol in the :ref:`Kconfig symbol reference
<configuration_options>`.
.. _initial-conf:
The Initial Configuration
*************************
The initial configuration for an application comes from merging configuration
settings from three sources:
1. A ``BOARD``-specific configuration file stored in
:file:`boards/<architecture>/<BOARD>/<BOARD>_defconfig`
2. Any CMake cache entries prefix with ``CONFIG_``
3. The application configuration
The application configuration can come from the sources below. By default,
:file:`prj.conf` is used.
1. If ``CONF_FILE`` is set, the configuration file(s) specified in it are
merged and used as the application configuration. ``CONF_FILE`` can be set
in various ways:
1. In :file:`CMakeLists.txt`, before including :file:`boilerplate.cmake`
2. By passing ``-DCONF_FILE=<conf file(s)>``, either directly or via ``west``
3. From the CMake variable cache
2. Otherwise, :file:`prj_<BOARD>.conf` is used if it exists in the application
directory.
3. Otherwise, if :file:`boards/<BOARD>.conf` exists in the application
directory, the result of merging it with :file:`prj.conf` is used.
4. Otherwise, :file:`prj.conf` is used if it exists in the application
directory
If a symbol is assigned both in :file:`<BOARD>_defconfig` and in the
application configuration, the value set in the application configuration takes
precedence.
The merged configuration is saved to :file:`zephyr/.config` in the build
directory.
As long as :file:`zephyr/.config` exists and is up-to-date (is newer than any
``BOARD`` and application configuration files), it will be used in preference
to producing a new merged configuration. :file:`zephyr/.config` is also the
configuration that gets modified when making changes in the :ref:`interactive
configuration interfaces <menuconfig>`.
Configuring invisible Kconfig symbols
*************************************
When making changes to the default configuration for a board, you might have to
configure invisible symbols. This is done in
:file:`boards/<architecture>/<BOARD>/Kconfig.defconfig`, which is a regular
:file:`Kconfig` file.
.. note::
Assignments in :file:`.config` files have no effect on invisible symbols,
so this scheme is not just an organizational issue.
Assigning values in :file:`Kconfig.defconfig` relies on defining 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. Only giving the
type once at the "base" definition of the symbol is a good idea for reasons
explained in :ref:`kconfig_shorthands`.
``default`` values in :file:`Kconfig.defconfig` files have priority over
``default`` values given on the "base" definition of a symbol. Internally, this
is implemented by including the :file:`Kconfig.defconfig` files first. Kconfig
uses the first ``default`` with a satisfied condition, where an empty condition
corresponds to ``if y`` (is always satisfied).
Note that conditions from surrounding top-level ``if``\ s are propagated to
symbol properties, so the above ``default`` is equivalent to
``default 32 if BOARD_MY_BOARD``.
.. warning::
When defining a symbol in multiple locations, dependencies are ORed together
rather than ANDed together. It is not possible to make the dependencies of a
symbol more restrictive by defining it in multiple locations.
For example, the direct dependencies of the symbol below becomes
``DEP1 || DEP2``:
.. code-block:: none
config FOO
...
depends on DEP1
config FOO
...
depends on DEP2
When making changes to :file:`Kconfig.defconfig` files, always check the
symbol's direct dependencies in one of the :ref:`interactive configuration
interfaces <menuconfig>` afterwards. It is often necessary to repeat
dependencies from the base definition of the symbol to avoid weakening a
symbol's dependencies.
Motivation for Kconfig.defconfig files
--------------------------------------
One motivation for this configuration scheme is to avoid making fixed
``BOARD``-specific settings configurable in the interactive configuration
interfaces. If all board configuration were done via :file:`<BOARD>_defconfig`,
all symbols would have to be visible, as values given in
:file:`<BOARD>_defconfig` have no effect on invisible symbols.
Having fixed settings be user-configurable would clutter up the configuration
interfaces and make them harder to understand, and would make it easier to
accidentally create broken configurations.
When dealing with fixed board-specific settings, also consider whether they
could be handled via :ref:`devicetree <device-tree>` instead.
Configuring choices
-------------------
There are two ways to configure a Kconfig ``choice``:
1. By setting one of the choice symbols to ``y`` in a configuration file.
Setting one choice symbol to ``y`` automatically gives all other choice
symbols the value ``n``.
If multiple choice symbols are set to ``y``, only the last one set to ``y``
will be honored (the rest will get the value ``n``). This allows a choice
selection from a board :file:`defconfig` file to be overridden from an
application :file:`prj.conf` file.
2. By changing the ``default`` of the choice in :file:`Kconfig.defconfig`.
As with symbols, changing the default for a choice is done by defining the
choice in multiple locations. For this to work, the choice must have a name.
As an example, assume that a choice has the following base definition (here,
the name of the choice is ``FOO``):
.. code-block:: none
choice FOO
bool "Foo choice"
default B
config A
bool "A"
config B
bool "B"
endchoice
To change the default symbol of ``FOO`` to ``A``, you would add the
following definition to :file:`Kconfig.defconfig`:
.. code-block:: none
choice FOO
default A
endchoice
The :file:`Kconfig.defconfig` method should be used when the dependencies of
the choice might not be satisfied. In that case, you're setting the default
selection whenever the user makes the choice visible.
More Kconfig resources
======================
The :ref:`kconfig_tips_and_tricks` page has some tips for writing Kconfig
files.
The :zephyr_file:`kconfiglib.py <scripts/kconfig/kconfiglib.py>` docstring
docstring (at the top of the file) goes over how symbol values are calculated
in detail.

6
doc/guides/kconfig/tips.rst
View file

@ -589,8 +589,10 @@ with the C Kconfig tools, though an implicit 0 default might be less likely to
be what was intended compared to other symbol types as well. be what was intended compared to other symbol types as well.
Common shorthands .. _kconfig_shorthands:
=================
Common Kconfig shorthands
=========================
Kconfig has two shorthands that deal with prompts and defaults. Kconfig has two shorthands that deal with prompts and defaults.

8
doc/guides/porting/arch.rst
View file

@ -13,11 +13,9 @@ The following are examples of ISAs and ABIs that Zephyr supports:
* ARMv7-M ISA with Thumb2 instruction set and ARM Embedded ABI (aeabi) * ARMv7-M ISA with Thumb2 instruction set and ARM Embedded ABI (aeabi)
* ARCv2 ISA * ARCv2 ISA
For information on Kconfig configuration, see the For information on Kconfig configuration, see
:ref:`setting_configuration_values` section in the :ref:`board_porting_guide`. :ref:`setting_configuration_values`. Architectures use a Kconfig configuration
Architectures use a similar Kconfig configuration scheme. The scheme similar to boards.
:ref:`kconfig_tips_and_tricks` page has some general recommendations and tips
for writing Kconfig files as well.
An architecture port can be divided in several parts; most are required and An architecture port can be divided in several parts; most are required and
some are optional: some are optional:

200
doc/guides/porting/board_porting.rst
View file

@ -125,7 +125,7 @@ A board port on Zephyr typically consists of two parts:
- A hardware description (usually done by device tree), which specifies embedded - A hardware description (usually done by device tree), which specifies embedded
SoC reference, connectors and any other hardware components such as LEDs, SoC reference, connectors and any other hardware components such as LEDs,
buttons, sensors or communication peripherals (USB, BLE controller, ..). buttons, sensors or communication peripherals (USB, BLE controller, ...).
- A software configuration (done using Kconfig) of features and peripheral - A software configuration (done using Kconfig) of features and peripheral
drivers. This default board configuration is subordinated to features drivers. This default board configuration is subordinated to features
@ -143,10 +143,11 @@ When porting Zephyr to a board, you must provide the board's default
Kconfig configuration, which is used in application builds unless explicitly Kconfig configuration, which is used in application builds unless explicitly
overridden. overridden.
.. note:: Setting Kconfig configuration values is documented in detail in
:ref:`setting_configuration_values`, which you should go through. Note that the
See the :ref:`kconfig_tips_and_tricks` page for some best practices and tips default board configuration might involve both :file:`<BOARD>_defconfig` and
when writing Kconfig files. :file:`Kconfig.defconfig` files. The rest of this section contains some
board-specific guidelines.
In order to provide consistency across the various boards and ease the work of In order to provide consistency across the various boards and ease the work of
users providing applications that are not board specific, the following users providing applications that are not board specific, the following
@ -172,192 +173,3 @@ peripherals should be disabled by default.
- Enable all GPIO ports. - Enable all GPIO ports.
- If available, enable pinmux and interrupt controller drivers. - If available, enable pinmux and interrupt controller drivers.
.. _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
string
prompt "Foo value"
config VISIBLE_2
# Shorthand for giving a type and a prompt at the same time. This is
# the preferred style in Zephyr.
bool "Enable stuff"
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.
.. note::
Assignments in :file:`.config` files have no effect on invisible symbols,
so this scheme is not just an organizational issue.
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`` values in :file:`Kconfig.defconfig` files have priority over
``default`` values given on the "base" definition of a symbol. Internally, this
is implemented by including the :file:`Kconfig.defconfig` files first. Kconfig
uses the first ``default`` with a satisfied condition, where an empty condition
works like ``if y`` (is always satisfied).
.. note::
``range`` properties on ``int`` and ``hex`` symbols work the same way, and
can also be added or overridden in :file:`Kconfig.defconfig` files.
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.
Configuring choices
-------------------
There are two ways to configure a Kconfig ``choice``:
1. By setting one of the choice symbols to ``y`` in :file:`BOARD_defconfig`.
.. note::
Setting one choice symbol to ``y`` automatically gives all other choice
symbols the value ``n``.
If multiple choice symbols are set to ``y``, only the last one set to
``y`` will be honored (and the rest will get the value ``n``). This
allows a choice selection from a board :file:`defconfig` file to be
overridden from an application :file:`prj.conf` file.
2. By changing the ``default`` of the choice in :file:`Kconfig.defconfig`.
As with symbols, changing the default for a choice is done by defining the
choice in multiple locations. For this to work, the choice must have a name.
As an example, assume that a choice has the following base definition (here,
the name of the choice is ``FOO``):
.. code-block:: none
choice FOO
bool "Foo choice"
default B
config A
bool "A"
config B
bool "B"
endchoice
To change the default symbol of ``FOO`` to ``A``, you would add the
following definition to :file:`Kconfig.defconfig`:
.. code-block:: none
choice FOO
default A
endchoice
The :file:`Kconfig.defconfig` method should be used when the dependencies of
the choice might not be satisfied. In that case, you're setting the default
selection whenever the user makes the choice visible.
Motivation
----------
One motivation for this configuration scheme is to avoid making fixed
``BOARD``-specific settings configurable in the ``menuconfig`` interface. If
all configuration were done via :file:`BOARD_defconfig`, all symbols would have
to be visible, as values given in :file:`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.
More Kconfig resources
======================
The official documentation for Kconfig is `kconfig-language.txt
<https://raw.githubusercontent.com/torvalds/linux/master/Documentation/kbuild/kconfig-language.txt>`_
and `kconfig-macro-language.txt
<https://raw.githubusercontent.com/torvalds/linux/master/Documentation/kbuild/kconfig-macro-language.txt>`_.
The :ref:`kconfig_tips_and_tricks` page has some best practices and
tips for writing Kconfig files.
The `kconfiglib.py
<https://raw.githubusercontent.com/zephyrproject-rtos/zephyr/master/scripts/kconfig/kconfiglib.py>`_
docstring (at the top of the file) goes over how symbol values are calculated
in detail.