doc: kconfig: Put all documentation on setting symbols on a new page
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:
parent
acc829c3ee
commit
e32686d0d6
7 changed files with 375 additions and 340 deletions
|
@ -48,13 +48,12 @@ These contents are:
|
|||
debug compiled binaries on real or emulated hardware, and more.
|
||||
|
||||
* **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.
|
||||
These application settings are merged with board-specific settings to produce
|
||||
a kernel configuration.
|
||||
|
||||
The :ref:`application_kconfig` section below goes over application
|
||||
configuration in detail.
|
||||
See :ref:`application-kconfig` below for more information.
|
||||
|
||||
* **Application source code files**: An application typically provides one
|
||||
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`
|
||||
also found at the top-level directory.
|
||||
|
||||
See :ref:`the Kconfig section of the manual <kconfig>` for detailed Kconfig
|
||||
documentation.
|
||||
|
||||
:file:`west.yml`
|
||||
The :ref:`west` manifest, listing the external repositories managed by
|
||||
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
|
||||
versions will be enforced by CMake.
|
||||
|
||||
#. Set any Kconfig values needed by your application. Zephyr uses the same
|
||||
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.
|
||||
#. Set Kconfig configuration options. See :ref:`application-kconfig`.
|
||||
|
||||
#. Optionally, you can also configure any devicetree overlays needed by your
|
||||
application. See :ref:`application_dt` below for details.
|
||||
|
@ -272,6 +266,8 @@ should know about.
|
|||
semicolons. Each file includes Kconfig configuration values that override
|
||||
the default configuration values.
|
||||
|
||||
See :ref:`initial-conf` for more information.
|
||||
|
||||
* :makevar:`DTC_OVERLAY_FILE`: Indicates the name of one or more devicetree
|
||||
overlay files. Multiple filenames can be separated with either spaces or
|
||||
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")
|
||||
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
|
||||
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
|
||||
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
|
||||
unique configuration **options** that are set differently depending on the
|
||||
build configuration.
|
||||
|
@ -1112,12 +1111,12 @@ Make sure to follow these steps in order.
|
|||
|
||||
.. note::
|
||||
|
||||
Environment variables in ``source`` statements are expanded directly,
|
||||
so 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
|
||||
the environment variable.
|
||||
Environment variables in ``source`` statements are expanded directly, so
|
||||
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
|
||||
the environment variable.
|
||||
|
||||
See :ref:`kconfig_extensions` for more information.
|
||||
See :ref:`kconfig_extensions` for more information.
|
||||
|
||||
The :file:`Kconfig` file is automatically detected when placed in
|
||||
the application directory, but it is also possible for it to be
|
||||
|
@ -1177,138 +1176,33 @@ documentation `runningcmake`_ .
|
|||
|
||||
.. _runningcmake: http://cmake.org/runningcmake/
|
||||
|
||||
.. _application_configuration:
|
||||
|
||||
Application Configuration
|
||||
*************************
|
||||
|
||||
.. _application_kconfig:
|
||||
.. _application-kconfig:
|
||||
|
||||
Kconfig Configuration
|
||||
=====================
|
||||
|
||||
Use the ``menuconfig`` and ``guiconfig`` interfaces to test out different
|
||||
configurations during development. See :ref:`menuconfig` for more information.
|
||||
Application configuration options are usually set in :file:`prj.conf` in the
|
||||
application directory. For example, C++ support could be enabled with this
|
||||
assignment:
|
||||
|
||||
The Initial Kconfig Configuration
|
||||
---------------------------------
|
||||
.. code-block:: none
|
||||
|
||||
The initial configuration for an application is produced by merging
|
||||
configuration settings from three sources:
|
||||
CONFIG_CPLUSPLUS=y
|
||||
|
||||
1. A :makevar:`BOARD`-specific configuration file, stored in
|
||||
:file:`boards/ARCHITECTURE/BOARD/BOARD_defconfig` in the Zephyr base
|
||||
directory.
|
||||
Looking at :ref:`existing samples <samples-and-demos>` is a good way to get
|
||||
started.
|
||||
|
||||
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
|
||||
|
||||
CONFIG_SOME_BOOL=y
|
||||
CONFIG_SOME_OTHER_BOOL=n
|
||||
|
||||
.. note::
|
||||
|
||||
Another way to set a boolean symbol to ``n`` is with a comment with the
|
||||
following format:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# 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
|
||||
See :ref:`setting_configuration_values` for detailed documentation on setting
|
||||
Kconfig configuration values. The :ref:`initial-conf` section on the same page
|
||||
explains how the initial configuration is derived. See
|
||||
:ref:`configuration_options` for a complete list of configuration options.
|
||||
|
||||
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:
|
||||
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
.. _kconfig:
|
||||
|
||||
Kconfig
|
||||
#######
|
||||
|
||||
|
@ -5,6 +7,7 @@ Kconfig
|
|||
:maxdepth: 1
|
||||
|
||||
menuconfig.rst
|
||||
setting.rst
|
||||
tips.rst
|
||||
preprocessor-functions.rst
|
||||
extensions.rst
|
||||
|
|
|
@ -20,7 +20,7 @@ terminal, while ``guiconfig`` is a graphical configuration interface.
|
|||
re-configuring.
|
||||
|
||||
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::
|
||||
|
||||
|
|
326
doc/guides/kconfig/setting.rst
Normal file
326
doc/guides/kconfig/setting.rst
Normal 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.
|
|
@ -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.
|
||||
|
||||
|
||||
Common shorthands
|
||||
=================
|
||||
.. _kconfig_shorthands:
|
||||
|
||||
Common Kconfig shorthands
|
||||
=========================
|
||||
|
||||
Kconfig has two shorthands that deal with prompts and defaults.
|
||||
|
||||
|
|
|
@ -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)
|
||||
* 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. The
|
||||
:ref:`kconfig_tips_and_tricks` page has some general recommendations and tips
|
||||
for writing Kconfig files as well.
|
||||
For information on Kconfig configuration, see
|
||||
:ref:`setting_configuration_values`. Architectures use a Kconfig configuration
|
||||
scheme similar to boards.
|
||||
|
||||
An architecture port can be divided in several parts; most are required and
|
||||
some are optional:
|
||||
|
|
|
@ -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
|
||||
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
|
||||
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
|
||||
overridden.
|
||||
|
||||
.. note::
|
||||
|
||||
See the :ref:`kconfig_tips_and_tricks` page for some best practices and tips
|
||||
when writing Kconfig files.
|
||||
Setting Kconfig configuration values is documented in detail in
|
||||
:ref:`setting_configuration_values`, which you should go through. Note that the
|
||||
default board configuration might involve both :file:`<BOARD>_defconfig` and
|
||||
: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
|
||||
users providing applications that are not board specific, the following
|
||||
|
@ -172,192 +173,3 @@ peripherals should be disabled by default.
|
|||
- Enable all GPIO ports.
|
||||
|
||||
- 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.
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue