6 files changed, 167 insertions, 9 deletions
diff --git a/doc/develop/environment.rst b/doc/develop/environment.rst
index e1783462bb0..e46cd39d601 100644
--- a/doc/develop/environment.rst
+++ b/doc/develop/environment.rst
@@ -18,8 +18,8 @@ The callbacks are named and associated with a function using the
 U_BOOT_ENV_CALLBACK macro in your board or driver code.
 
 These callbacks are associated with variables in one of two ways.  The
-static list can be added to by defining CFG_ENV_CALLBACK_LIST_STATIC
-in the board configuration to a string that defines a list of
+static list can be added to by defining CONFIG_ENV_CALLBACK_LIST_STATIC
+in the board defconfig via menuconfig to a string that defines a list of
 associations.  The list must be in the following format::
 
     entry = variable_name[:callback_name]
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..227074dc497
--- /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.
diff --git a/doc/develop/release_cycle.rst b/doc/develop/release_cycle.rst
index 1548d2634ff..449d0375a1b 100644
--- a/doc/develop/release_cycle.rst
+++ b/doc/develop/release_cycle.rst
@@ -71,13 +71,13 @@ For the next scheduled release, release candidates were made on::
 
 * U-Boot v2025.01-rc2 was released on Mon 11 November 2024.
 
-.. * U-Boot v2025.01-rc3 was released on Mon 25 November 2024.
+* U-Boot v2025.01-rc3 was released on Mon 25 November 2024.
 
-.. * U-Boot v2025.01-rc4 was released on Mon 09 December 2024.
+* U-Boot v2025.01-rc4 was released on Mon 09 December 2024.
 
-.. * U-Boot v2025.01-rc5 was released on Mon 23 December 2024.
+* U-Boot v2025.01-rc5 was released on Mon 23 December 2024.
 
-.. * U-Boot v2025.01-rc6 was released on Mon 30 December 2024.
+* U-Boot v2025.01-rc6 was released on Mon 30 December 2024.
 
 Please note that the following dates are planned only and may be deviated from
 as needed.
diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst
index e22b5e3e244..ee6e34089b5 100644
--- a/doc/develop/sending_patches.rst
+++ b/doc/develop/sending_patches.rst
@@ -377,7 +377,7 @@ The following are a "rule of thumb" as to how the states are used in patchwork
 today. Not all states are used by all custodians.
 
 * New: Patch has been submitted to the list, and none of the maintainers has
-  changed it's state since.
+  changed its state since.
 
 * Under Review: A custodian is reviewing the patch currently.
 
diff --git a/doc/develop/uefi/fwu_updates.rst b/doc/develop/uefi/fwu_updates.rst
index 51e8a28efe1..84713581459 100644
--- a/doc/develop/uefi/fwu_updates.rst
+++ b/doc/develop/uefi/fwu_updates.rst
@@ -170,7 +170,7 @@ build the tool, enable::
 
     CONFIG_TOOLS_MKEFICAPSULE=y
 
-Run the following commands to generate the accept/revert capsules::
+Run the following commands to generate the accept/revert capsules:
 
 .. code-block:: bash
 
@@ -180,7 +180,7 @@ Run the following commands to generate the accept/revert capsules::
       <capsule_file_name>
 
 Some examples of using the mkeficapsule tool for generation of the
-empty capsule would be::
+empty capsule would be:
 
 .. code-block:: bash