[U-Boot] [PATCH] README.kconfig: add initial version of Kconfig document

[Masahiro Yamada]

Signed-off-by: Masahiro Yamada <yamada.m at jp.panasonic.com>
---

Please point out if my English is strange, there is something unclear,
or something important is missing.


 doc/README.kconfig | 163 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 163 insertions(+)
 create mode 100644 doc/README.kconfig

diff --git a/doc/README.kconfig b/doc/README.kconfig
new file mode 100644
index 0000000..6a3b80f
--- /dev/null
+++ b/doc/README.kconfig
@@ -0,0 +1,163 @@
+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
+-------------------------------
+
+The biggest difference between Linux Kernel and U-Boot in terms of the
+configuration is that U-Boot has to configure multiple boot images per board:
+Normal, SPL, TPL.
+Kconfig functions need to be expanded for U-Boot to handle multiple images.
+The files scripts/kconfig/* were imported from Linux Kernel and adjusted
+for that purpose.
+
+See below for how each configuration target works in U-Boot:
+
+- config, nconfig, menuconfig, xconfig, gconfig
+
+  These targets are used to configure Normal and create (or modify) the .config
+  file.  For SPL configuration, the configutation targets must be prefixed
+  with "spl/", for example "male spl/config", "make spl/menuconfig", etc.
+  Those targets create or modify the spl/.config file.  Likewise, run
+  "make tpl/config", "make tpl/menuconfig", etc. for TPL.
+
+- silentoldconfig
+
+  This target updates .config, include/generated/autoconf.h and
+  include/configs/*.  In U-Boot, the same thing is done for SPL, TPL
+  for boards supporting them.  Depending on whether CONFIG_SPL and CONFIG_TPL
+  are defined, "make silentoldconfig" iterates three times at most.
+
+  To sum up, "make silentoldconfig" possibly updates:
+  - .config, include/generated/autoconf.h, include/config/*
+  - spl/.config, spl/include/generated/autoconf.h, spl/include/config/*
+    (in case CONFIG_SPL=y)
+  - tpl/.config, tpl/include/generated/autoconf.h, tpl/include/config/*
+    (in case CONFIG_TPL=y)
+
+- defconfig, <board>_defconfig
+
+  The target "<board>_defconfig" is used to create the .config based on the
+  file configs/<board>_defconfig.  The "defconfig" target is the same
+  except it checks for a file specified with KBUILD_DEFCONFIG environment.
+
+  Note:
+  The defconfig files are placed under the "configs" directory,
+  not "arch/$(ARCH)/configs".  This is because "ARCH" is not necessarily
+  given from the command line for the U-Boot configuration and build.
+
+  The defconfig file format in U-Boot has the special syntax; each line has
+  "<condition>:" prefix to show which image(s) the line is valid for.
+  For example,
+
+  CONFIG_FOO=100
+  S:CONFIG_FOO=200
+  T:CONFIG_FOO=300
+  ST:CONFIG_BAR=y
+  +S:CONFIG_BAZ=y
+  +T:CONFIG_QUX=y
+  +ST:CONFIG_QUUX=y
+
+  Here, the "<condition>:" prefix is one of:
+  None  - the line is valid only for Normal image
+  S:    - the line is valid only for SPL image
+  T:    - the line is valid only for TPL image
+  ST:   - the line is valid for SPL and TPL images
+  +S:   - the line is valid for Normal and SPL images
+  +T:   - the line is valid for Normal and TPL images
+  +ST:  - the line is valid for Normal, SPL and SPL images
+
+  So, if neither CONFIG_SPL nor CONFIG_TPL is defined, the defconfig file
+  has no "<condition>:" part and therefore has the same form of that of
+  Linux Kernel.
+  From the example defconfig above, three separete configuration sets are
+  generated and used for creating .config, spl/.config and tpl/.config.
+
+  - Input for the default configuration of Normal
+     CONFIG_FOO=100
+     CONFIG_BAZ=y
+     CONFIG_QUX=y
+     CONFIG_QUUX=y
+
+  - Input for the default configuration of SPL
+     CONFIG_FOO=200
+     CONFIG_BAR=y
+     CONFIG_BAZ=y
+     CONFIG_QUUX=y
+
+  - Input for the default configuration of TPL
+     CONFIG_FOO=300
+     CONFIG_BAR=y
+     CONFIG_QUX=y
+     CONFIG_QUUX=y
+
+- savedefconfig
+
+  This is the reverse operation of "make defconfig".  If neither CONFIG_SPL
+  nor CONFIG_TPL is defined in the .config file, it works as "savedefconfig"
+  in Linux Kernel: creates the minimal set of config based on the .config
+  and save it into the "defconfig" file.  If CONFIG_SPL (and CONFIG_TPL) is
+  defined, the common lines among .config, spl/.config and tpl/.config are
+  coalesced together with "<condition:>" prefix for each line as shown above.
+  This file can be used as an input of "defconfig" target.
+
+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 were 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)
+  - spl/include/generated/autoconf.h (generated by Kconfig for SPL)
+  - tpl/include/generated/autoconf.h (generated by Kconfig for TPL)
+  - include/configs/<board>.h        (generated by the old config)
+
+Configuration file for use in makefiles
+  - include/config/auto.conf         (generated by Kconfig for Normal)
+  - spl/include/config/auto.conf     (generated by Kconfig for SPL)
+  - tpl/include/config/auto.conf     (generated by Kconfig for TPL)
+  - 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 a header file.
+
+TODO
+----
+
+- The option field of boards.cfg, which was used for the pre-Kconfig
+  configuration, moved to CONFIG_SYS_EXTRA_OPTIONS verbatim now.
+  Board maintainers are expected to implement proper Kconfig options
+  and switch over to them.  Eventually CONFIG_SYS_EXTRA_OPTIONS goes away.
+  CONFIG_SYS_EXTRA_OPTIONS should not be used for new boards.
+
+- In the pre-Kconfig, a single board had multiple entries in the boards.cfg
+  file with differences in the option fields.  The correspoing defconfig files
+  were auto-generated when switching to Kconfig.  Now we have too many
+  defconfig files comared 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.
-- 
1.9.1