diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.kconfig | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/doc/README.kconfig b/doc/README.kconfig new file mode 100644 index 0000000..cd549a8 --- /dev/null +++ b/doc/README.kconfig @@ -0,0 +1,219 @@ +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 are prefixed + with "spl/", for example "make 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, + if supported by the target board. Depending on whether CONFIG_SPL and + CONFIG_TPL are defined, "make silentoldconfig" iterates three times at most + changing the work directory. + + 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 as in Linux. + From the example defconfig shown 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 like "savedefconfig" + in Linux Kernel: creates the minimal set of config based on the .config + and saves 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 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) + - spl/include/generated/autoconf.h (generated by Kconfig for SPL) + - tpl/include/generated/autoconf.h (generated by Kconfig for TPL) + - include/configs/<board>.h (exists for all boards) + +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 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) + Options -> CONFIG_SYS_EXTRA_OPTIONS defined by Kconfig + 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 +---- + +- 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 will go 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 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. |