[PATCH 1/1] doc: move README.kconfig to HTML documentation
Heinrich Schuchardt
heinrich.schuchardt at canonical.com
Mon Nov 11 10:05:39 CET 2024
* format according to Sphinx style
* add link to Linux Kconfig documentation
* sort table alphabetically in 'Conversion from boards.cfg to Kconfig'
Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
---
doc/README.kconfig | 151 --------------------------------------
doc/develop/index.rst | 1 +
doc/develop/kconfig.rst | 157 ++++++++++++++++++++++++++++++++++++++++
3 files changed, 158 insertions(+), 151 deletions(-)
delete mode 100644 doc/README.kconfig
create mode 100644 doc/develop/kconfig.rst
diff --git a/doc/README.kconfig b/doc/README.kconfig
deleted file mode 100644
index 808cf56e59c..00000000000
--- a/doc/README.kconfig
+++ /dev/null
@@ -1,151 +0,0 @@
-Kconfig in U-Boot
-=================
-
-This document describes the configuration infrastructure of U-Boot.
-
-The conventional configuration was replaced by Kconfig at v2014.10-rc1 release.
-
-
-Language Specification
-----------------------
-
-Kconfig originates in Linux Kernel.
-See the file "Documentation/kbuild/kconfig*.txt" in your Linux Kernel
-source directory for a basic specification of Kconfig.
-
-
-Difference from Linux's Kconfig
--------------------------------
-
-Here are some worth-mentioning configuration targets.
-
-- silentoldconfig
-
- This target updates .config, include/generated/autoconf.h and
- include/configs/* as in Linux. In U-Boot, it also does the following
- for the compatibility with the old configuration system:
-
- * create a symbolic link "arch/${ARCH}/include/asm/arch" pointing to
- the SoC/CPU specific header directory
- * create include/config.h
- * create include/autoconf.mk
- * create spl/include/autoconf.mk (SPL and TPL only)
- * create tpl/include/autoconf.mk (TPL only)
-
- If we could completely switch to Kconfig in a long run
- (i.e. remove all the include/configs/*.h), those additional processings
- above would be removed.
-
-- defconfig
-
- In U-Boot, "make defconfig" is a shorthand of "make sandbox_defconfig"
-
-- <board>_defconfig
-
- Now it works as in Linux.
- The prefixes such as "+S:" in *_defconfig are deprecated.
- You can simply remove the prefixes. Do not add them for new boards.
-
-- <board>_config
-
- This does not exist in Linux's Kconfig.
- "make <board>_config" works the same as "make <board>_defconfig".
- Prior to Kconfig, in U-Boot, "make <board>_config" was used for the
- configuration. It is still supported for backward compatibility, so
- we do not need to update the distro recipes.
-
-
-The other configuration targets work as in Linux Kernel.
-
-
-Migration steps to Kconfig
---------------------------
-
-Prior to Kconfig, the C preprocessor based board configuration had been used
-in U-Boot.
-
-Although Kconfig was introduced and some configs have been moved to Kconfig,
-many of configs are still defined in C header files. It will take a very
-long term to move all of them to Kconfig. In the interim, the two different
-configuration infrastructures should coexist.
-The configuration files are generated by both Kconfig and the old preprocessor
-based configuration as follows:
-
-Configuration files for use in C sources
- - include/generated/autoconf.h (generated by Kconfig for Normal)
- - include/configs/<board>.h (exists for all boards)
-
-Configuration file for use in makefiles
- - include/config/auto.conf (generated by Kconfig)
- - include/autoconf.mk (generated by the old config for Normal)
- - spl/include/autoconfig.mk (generated by the old config for SPL)
- - tpl/include/autoconfig.mk (generated by the old config for TPL)
-
-When adding a new CONFIG macro, it is highly recommended to add it to Kconfig
-rather than to a header file.
-
-
-Conversion from boards.cfg to Kconfig
--------------------------------------
-
-Prior to Kconfig, boards.cfg was a primary database that contained Arch, CPU,
-SoC, etc. of all the supported boards. It was deleted when switching to
-Kconfig. Each field of boards.cfg was converted as follows:
-
- Status -> "S:" entry of MAINTAINERS
- Arch -> CONFIG_SYS_ARCH defined by Kconfig
- CPU -> CONFIG_SYS_CPU defined by Kconfig
- SoC -> CONFIG_SYS_SOC defined by Kconfig
- Vendor -> CONFIG_SYS_VENDOR defined by Kconfig
- Board -> CONFIG_SYS_BOARD defined by Kconfig
- Target -> File name of defconfig (configs/<target>_defconfig)
- Maintainers -> "M:" entry of MAINTAINERS
-
-
-Tips to add/remove boards
--------------------------
-
-When adding a new board, the following steps are generally needed:
-
- [1] Add a header file include/configs/<target>.h
- [2] Make sure to define necessary CONFIG_SYS_* in Kconfig:
- Define CONFIG_SYS_CPU="cpu" to compile arch/<arch>/cpu/<cpu>
- Define CONFIG_SYS_SOC="soc" to compile arch/<arch>/cpu/<cpu>/<soc>
- Define CONFIG_SYS_VENDOR="vendor" to compile board/<vendor>/common/*
- and board/<vendor>/<board>/*
- Define CONFIG_SYS_BOARD="board" to compile board/<board>/*
- (or board/<vendor>/<board>/* if CONFIG_SYS_VENDOR is defined)
- Define CONFIG_SYS_CONFIG_NAME="target" to include
- include/configs/<target>.h
- [3] Add a new entry to the board select menu in Kconfig.
- The board select menu is located in arch/<arch>/Kconfig or
- arch/<arch>/*/Kconfig.
- [4] Add a MAINTAINERS file
- It is generally placed at board/<board>/MAINTAINERS or
- board/<vendor>/<board>/MAINTAINERS
- [5] Add configs/<target>_defconfig
-
-When removing an obsolete board, the following steps are generally needed:
-
- [1] Remove configs/<target>_defconfig
- [2] Remove include/configs/<target>.h if it is not used by any other boards
- [3] Remove board/<vendor>/<board>/* or board/<board>/* if it is not used
- by any other boards
- [4] Update MAINTAINERS if necessary
- [5] Remove the unused entry from the board select menu in Kconfig
- [6] Add an entry to doc/README.scrapyard
-
-
-TODO
-----
-
-- In the pre-Kconfig, a single board had multiple entries in the boards.cfg
- file with differences in the option fields. The corresponding defconfig
- files were auto-generated when switching to Kconfig. Now we have too many
- defconfig files compared with the number of the supported boards. It is
- recommended to have only one defconfig per board and allow users to select
- the config options.
-
-- Move the config macros in header files to Kconfig. When we move at least
- macros used in makefiles, we can drop include/autoconfig.mk, which makes
- the build scripts much simpler.
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index 30f7fdb8847..d9f2a838207 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -13,6 +13,7 @@ General
codingstyle
designprinciples
docstyle
+ kconfig
memory
patman
process
diff --git a/doc/develop/kconfig.rst b/doc/develop/kconfig.rst
new file mode 100644
index 00000000000..3a2be54e117
--- /dev/null
+++ b/doc/develop/kconfig.rst
@@ -0,0 +1,157 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Kconfig in U-Boot
+=================
+
+This document describes the configuration infrastructure of U-Boot.
+
+The conventional configuration was replaced by Kconfig at v2014.10-rc1 release.
+
+Language Specification
+----------------------
+
+The Kconfig configuration language originates in Linux kernel.
+See the Linux document
+`Kconfig Language <https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html>`_
+for a description of Kconfig.
+
+Difference from Linux's Kconfig
+-------------------------------
+
+Here are some worth-mentioning configuration targets.
+
+silentoldconfig
+ This target updates .config, include/generated/autoconf.h and
+ include/configs/* as in Linux. In U-Boot, it also does the following
+ for the compatibility with the old configuration system:
+
+ * create a symbolic link "arch/${ARCH}/include/asm/arch" pointing to
+ the SoC/CPU specific header directory
+ * create include/config.h
+ * create include/autoconf.mk
+ * create spl/include/autoconf.mk (SPL and TPL only)
+ * create tpl/include/autoconf.mk (TPL only)
+
+ If we could completely switch to Kconfig in a long run
+ (i.e. remove all the include/configs/\*.h), those additional processings
+ above would be removed.
+
+defconfig
+ In U-Boot, "make defconfig" is a shorthand of "make sandbox_defconfig"
+
+<board>_defconfig
+ Now it works as in Linux.
+ The prefixes such as "+S:" in \*_defconfig are deprecated.
+ You can simply remove the prefixes. Do not add them for new boards.
+
+<board>_config
+ This does not exist in Linux's Kconfig.
+ "make <board>_config" works the same as "make <board>_defconfig".
+ Prior to Kconfig, in U-Boot, "make <board>_config" was used for the
+ configuration. It is still supported for backward compatibility, so
+ we do not need to update the distro recipes.
+
+The other configuration targets work as in Linux Kernel.
+
+Migration steps to Kconfig
+--------------------------
+
+Prior to Kconfig, the C preprocessor based board configuration had been used
+in U-Boot.
+
+Although Kconfig was introduced and some configs have been moved to Kconfig,
+many of configs are still defined in C header files. It will take a very
+long term to move all of them to Kconfig. In the interim, the two different
+configuration infrastructures should coexist.
+The configuration files are generated by both Kconfig and the old preprocessor
+based configuration as follows:
+
+Configuration files for use in C sources
+ - include/generated/autoconf.h (generated by Kconfig for Normal)
+ - include/configs/<board>.h (exists for all boards)
+
+Configuration file for use in makefiles
+ - include/config/auto.conf (generated by Kconfig)
+ - include/autoconf.mk (generated by the old config for Normal)
+ - spl/include/autoconfig.mk (generated by the old config for SPL)
+ - tpl/include/autoconfig.mk (generated by the old config for TPL)
+
+When adding a new CONFIG macro, it is highly recommended to add it to Kconfig
+rather than to a header file.
+
+Conversion from boards.cfg to Kconfig
+-------------------------------------
+
+Prior to Kconfig, boards.cfg was a primary database that contained Arch, CPU,
+SoC, etc. of all the supported boards. It was deleted when switching to
+Kconfig. Each field of boards.cfg was converted as follows:
+
+=========== ====================================================
+From To
+=========== ====================================================
+Arch CONFIG_SYS_ARCH defined by Kconfig
+Board CONFIG_SYS_BOARD defined by Kconfig
+CPU CONFIG_SYS_CPU defined by Kconfig
+Maintainers "M:" entry of MAINTAINERS
+SoC CONFIG_SYS_SOC defined by Kconfig
+Status "S:" entry of MAINTAINERS
+Target File name of defconfig (configs/<target>\_defconfig)
+Vendor CONFIG_SYS_VENDOR defined by Kconfig
+=========== ====================================================
+
+Tips to add/remove boards
+-------------------------
+
+When adding a new board, the following steps are generally needed:
+
+1. Add a header file include/configs/<target>.h
+
+2. Make sure to define necessary CONFIG_SYS_* in Kconfig:
+
+ * Define CONFIG_SYS_CPU="cpu" to compile arch/<arch>/cpu/<cpu>
+ * Define CONFIG_SYS_SOC="soc" to compile arch/<arch>/cpu/<cpu>/<soc>
+ * Define CONFIG_SYS_VENDOR="vendor" to compile board/<vendor>/common/\*
+ and board/<vendor>/<board>/\*
+ * Define CONFIG_SYS_BOARD="board" to compile board/<board>/\*
+ (or board/<vendor>/<board>/* if CONFIG_SYS_VENDOR is defined)
+ Define CONFIG_SYS_CONFIG_NAME="target" to include
+ include/configs/<target>.h
+
+3. Add a new entry to the board select menu in Kconfig.
+ The board select menu is located in arch/<arch>/Kconfig or
+ arch/<arch>/\*/Kconfig.
+
+4. Add a MAINTAINERS file
+ It is generally placed at board/<board>/MAINTAINERS or
+ board/<vendor>/<board>/MAINTAINERS
+
+5. Add configs/<target>_defconfig
+
+When removing an obsolete board, the following steps are generally needed:
+
+1. Remove configs/<target>_defconfig
+
+2. Remove include/configs/<target>.h if it is not used by any other boards
+
+3. Remove board/<vendor>/<board>/\* or board/<board>/\* if it is not used
+ by any other boards
+
+4. Update MAINTAINERS if necessary
+
+5. Remove the unused entry from the board select menu in Kconfig
+
+6. Add an entry to doc/README.scrapyard
+
+TODO
+----
+
+* In the pre-Kconfig, a single board had multiple entries in the boards.cfg
+ file with differences in the option fields. The corresponding defconfig
+ files were auto-generated when switching to Kconfig. Now we have too many
+ defconfig files compared with the number of the supported boards. It is
+ recommended to have only one defconfig per board and allow users to select
+ the config options.
+
+* Move the config macros in header files to Kconfig. When we move at least
+ macros used in makefiles, we can drop include/autoconfig.mk, which makes
+ the build scripts much simpler.
--
2.45.2
More information about the U-Boot
mailing list