xref: /openbmc/u-boot/doc/README.kconfig (revision c21fc7e223ebad72735b9d02bcbd8878ae026fef)
16933b5c9SMasahiro YamadaKconfig in U-Boot
26933b5c9SMasahiro Yamada=================
36933b5c9SMasahiro Yamada
46933b5c9SMasahiro YamadaThis document describes the configuration infrastructure of U-Boot.
56933b5c9SMasahiro Yamada
66933b5c9SMasahiro YamadaThe conventional configuration was replaced by Kconfig at v2014.10-rc1 release.
76933b5c9SMasahiro Yamada
86933b5c9SMasahiro Yamada
96933b5c9SMasahiro YamadaLanguage Specification
106933b5c9SMasahiro Yamada----------------------
116933b5c9SMasahiro Yamada
126933b5c9SMasahiro YamadaKconfig originates in Linux Kernel.
136933b5c9SMasahiro YamadaSee the file "Documentation/kbuild/kconfig*.txt" in your Linux Kernel
146933b5c9SMasahiro Yamadasource directory for a basic specification of Kconfig.
156933b5c9SMasahiro Yamada
166933b5c9SMasahiro Yamada
176933b5c9SMasahiro YamadaDifference from Linux's Kconfig
186933b5c9SMasahiro Yamada-------------------------------
196933b5c9SMasahiro Yamada
20e02ee254SMasahiro YamadaHere are some worth-mentioning configuration targets.
216933b5c9SMasahiro Yamada
226933b5c9SMasahiro Yamada- silentoldconfig
236933b5c9SMasahiro Yamada
246933b5c9SMasahiro Yamada  This target updates .config, include/generated/autoconf.h and
25*c21fc7e2SMasahiro Yamada  include/configs/* as in Linux.  In U-Boot, it also does the following
26e02ee254SMasahiro Yamada  for the compatibility with the old configuration system:
276933b5c9SMasahiro Yamada
28e02ee254SMasahiro Yamada   * create a symbolic link "arch/${ARCH}/include/asm/arch" pointing to
29e02ee254SMasahiro Yamada     the SoC/CPU specific header directory
30e02ee254SMasahiro Yamada   * create include/config.h
31e02ee254SMasahiro Yamada   * create include/autoconf.mk
32e02ee254SMasahiro Yamada   * create spl/include/autoconf.mk (SPL and TPL only)
33e02ee254SMasahiro Yamada   * create tpl/include/autoconf.mk (TPL only)
346933b5c9SMasahiro Yamada
35e02ee254SMasahiro Yamada   If we could completely switch to Kconfig in a long run
36e02ee254SMasahiro Yamada   (i.e. remove all the include/configs/*.h), those additional processings
37e02ee254SMasahiro Yamada   above would be removed.
386933b5c9SMasahiro Yamada
39e02ee254SMasahiro Yamada- defconfig
406933b5c9SMasahiro Yamada
41e02ee254SMasahiro Yamada  In U-Boot, "make defconfig" is a shorthand of "make sandbox_defconfig"
426933b5c9SMasahiro Yamada
43e02ee254SMasahiro Yamada- <board>_defconfig
446933b5c9SMasahiro Yamada
45e02ee254SMasahiro Yamada  Now it works as in Linux.
46e02ee254SMasahiro Yamada  The prefixes such as "+S:" in *_defconfig are deprecated.
47e02ee254SMasahiro Yamada  You can simply remove the prefixes.  Do not add them for new boards.
486933b5c9SMasahiro Yamada
49d1b60d34SMasahiro Yamada- <board>_config
50d1b60d34SMasahiro Yamada
51d1b60d34SMasahiro Yamada  This does not exist in Linux's Kconfig.
52e02ee254SMasahiro Yamada  "make <board>_config" works the same as "make <board>_defconfig".
53d1b60d34SMasahiro Yamada  Prior to Kconfig, in U-Boot, "make <board>_config" was used for the
54e02ee254SMasahiro Yamada  configuration.  It is still supported for backward compatibility, so
55e02ee254SMasahiro Yamada  we do not need to update the distro recipes.
56e02ee254SMasahiro Yamada
57e02ee254SMasahiro Yamada
58e02ee254SMasahiro YamadaThe other configuration targets work as in Linux Kernel.
59d1b60d34SMasahiro Yamada
606933b5c9SMasahiro Yamada
616933b5c9SMasahiro YamadaMigration steps to Kconfig
626933b5c9SMasahiro Yamada--------------------------
636933b5c9SMasahiro Yamada
646933b5c9SMasahiro YamadaPrior to Kconfig, the C preprocessor based board configuration had been used
656933b5c9SMasahiro Yamadain U-Boot.
666933b5c9SMasahiro Yamada
676933b5c9SMasahiro YamadaAlthough Kconfig was introduced and some configs have been moved to Kconfig,
686933b5c9SMasahiro Yamadamany of configs are still defined in C header files.  It will take a very
696933b5c9SMasahiro Yamadalong term to move all of them to Kconfig.  In the interim, the two different
706933b5c9SMasahiro Yamadaconfiguration infrastructures should coexist.
716933b5c9SMasahiro YamadaThe configuration files are generated by both Kconfig and the old preprocessor
726933b5c9SMasahiro Yamadabased configuration as follows:
736933b5c9SMasahiro Yamada
746933b5c9SMasahiro YamadaConfiguration files for use in C sources
756933b5c9SMasahiro Yamada  - include/generated/autoconf.h     (generated by Kconfig for Normal)
766933b5c9SMasahiro Yamada  - include/configs/<board>.h        (exists for all boards)
776933b5c9SMasahiro Yamada
786933b5c9SMasahiro YamadaConfiguration file for use in makefiles
79e02ee254SMasahiro Yamada  - include/config/auto.conf         (generated by Kconfig)
806933b5c9SMasahiro Yamada  - include/autoconf.mk              (generated by the old config for Normal)
816933b5c9SMasahiro Yamada  - spl/include/autoconfig.mk        (generated by the old config for SPL)
826933b5c9SMasahiro Yamada  - tpl/include/autoconfig.mk        (generated by the old config for TPL)
836933b5c9SMasahiro Yamada
846933b5c9SMasahiro YamadaWhen adding a new CONFIG macro, it is highly recommended to add it to Kconfig
856933b5c9SMasahiro Yamadarather than to a header file.
866933b5c9SMasahiro Yamada
876933b5c9SMasahiro Yamada
886933b5c9SMasahiro YamadaConversion from boards.cfg to Kconfig
896933b5c9SMasahiro Yamada-------------------------------------
906933b5c9SMasahiro Yamada
916933b5c9SMasahiro YamadaPrior to Kconfig, boards.cfg was a primary database that contained Arch, CPU,
926933b5c9SMasahiro YamadaSoC, etc. of all the supported boards.  It was deleted when switching to
936933b5c9SMasahiro YamadaKconfig.  Each field of boards.cfg was converted as follows:
946933b5c9SMasahiro Yamada
956933b5c9SMasahiro Yamada Status      ->  "S:" entry of MAINTAINERS
966933b5c9SMasahiro Yamada Arch        ->  CONFIG_SYS_ARCH defined by Kconfig
976933b5c9SMasahiro Yamada CPU         ->  CONFIG_SYS_CPU defined by Kconfig
986933b5c9SMasahiro Yamada SoC         ->  CONFIG_SYS_SOC defined by Kconfig
996933b5c9SMasahiro Yamada Vendor      ->  CONFIG_SYS_VENDOR defined by Kconfig
1006933b5c9SMasahiro Yamada Board       ->  CONFIG_SYS_BOARD defined by Kconfig
1016933b5c9SMasahiro Yamada Target      ->  File name of defconfig (configs/<target>_defconfig)
1026933b5c9SMasahiro Yamada Options     ->  CONFIG_SYS_EXTRA_OPTIONS defined by Kconfig
1036933b5c9SMasahiro Yamada Maintainers ->  "M:" entry of MAINTAINERS
1046933b5c9SMasahiro Yamada
1056933b5c9SMasahiro Yamada
1066933b5c9SMasahiro YamadaTips to add/remove boards
1076933b5c9SMasahiro Yamada-------------------------
1086933b5c9SMasahiro Yamada
1096933b5c9SMasahiro YamadaWhen adding a new board, the following steps are generally needed:
1106933b5c9SMasahiro Yamada
1116933b5c9SMasahiro Yamada [1] Add a header file include/configs/<target>.h
1126933b5c9SMasahiro Yamada [2] Make sure to define necessary CONFIG_SYS_* in Kconfig:
1136933b5c9SMasahiro Yamada       Define CONFIG_SYS_CPU="cpu" to compile arch/<arch>/cpu/<cpu>
1146933b5c9SMasahiro Yamada       Define CONFIG_SYS_SOC="soc" to compile arch/<arch>/cpu/<cpu>/<soc>
1156933b5c9SMasahiro Yamada       Define CONFIG_SYS_VENDOR="vendor" to compile board/<vendor>/common/*
1166933b5c9SMasahiro Yamada         and board/<vendor>/<board>/*
1176933b5c9SMasahiro Yamada       Define CONFIG_SYS_BOARD="board" to compile board/<board>/*
1186933b5c9SMasahiro Yamada         (or board/<vendor>/<board>/* if CONFIG_SYS_VENDOR is defined)
1196933b5c9SMasahiro Yamada       Define CONFIG_SYS_CONFIG_NAME="target" to include
1206933b5c9SMasahiro Yamada         include/configs/<target>.h
1216933b5c9SMasahiro Yamada [3] Add a new entry to the board select menu in Kconfig.
1226933b5c9SMasahiro Yamada     The board select menu is located in arch/<arch>/Kconfig or
1236933b5c9SMasahiro Yamada     arch/<arch>/*/Kconfig.
1246933b5c9SMasahiro Yamada [4] Add a MAINTAINERS file
1256933b5c9SMasahiro Yamada     It is generally placed at board/<board>/MAINTAINERS or
1266933b5c9SMasahiro Yamada     board/<vendor>/<board>/MAINTAINERS
1276933b5c9SMasahiro Yamada [5] Add configs/<target>_defconfig
1286933b5c9SMasahiro Yamada
1296933b5c9SMasahiro YamadaWhen removing an obsolete board, the following steps are generally needed:
1306933b5c9SMasahiro Yamada
1316933b5c9SMasahiro Yamada [1] Remove configs/<target>_defconfig
1326933b5c9SMasahiro Yamada [2] Remove include/configs/<target>.h if it is not used by any other boards
1336933b5c9SMasahiro Yamada [3] Remove board/<vendor>/<board>/* or board/<board>/* if it is not used
1346933b5c9SMasahiro Yamada     by any other boards
1356933b5c9SMasahiro Yamada [4] Update MAINTAINERS if necessary
1366933b5c9SMasahiro Yamada [5] Remove the unused entry from the board select menu in Kconfig
1376933b5c9SMasahiro Yamada [6] Add an entry to doc/README.scrapyard
1386933b5c9SMasahiro Yamada
1396933b5c9SMasahiro Yamada
1406933b5c9SMasahiro YamadaTODO
1416933b5c9SMasahiro Yamada----
1426933b5c9SMasahiro Yamada
1436933b5c9SMasahiro Yamada- The option field of boards.cfg, which was used for the pre-Kconfig
1446933b5c9SMasahiro Yamada  configuration, moved to CONFIG_SYS_EXTRA_OPTIONS verbatim now.
1456933b5c9SMasahiro Yamada  Board maintainers are expected to implement proper Kconfig options
1466933b5c9SMasahiro Yamada  and switch over to them.  Eventually CONFIG_SYS_EXTRA_OPTIONS will go away.
1476933b5c9SMasahiro Yamada  CONFIG_SYS_EXTRA_OPTIONS should not be used for new boards.
1486933b5c9SMasahiro Yamada
1496933b5c9SMasahiro Yamada- In the pre-Kconfig, a single board had multiple entries in the boards.cfg
150e02ee254SMasahiro Yamada  file with differences in the option fields.  The corresponding defconfig
151e02ee254SMasahiro Yamada  files were auto-generated when switching to Kconfig.  Now we have too many
1526933b5c9SMasahiro Yamada  defconfig files compared with the number of the supported boards.  It is
1536933b5c9SMasahiro Yamada  recommended to have only one defconfig per board and allow users to select
1546933b5c9SMasahiro Yamada  the config options.
1556933b5c9SMasahiro Yamada
1566933b5c9SMasahiro Yamada- Move the config macros in header files to Kconfig.  When we move at least
1576933b5c9SMasahiro Yamada  macros used in makefiles, we can drop include/autoconfig.mk, which makes
1586933b5c9SMasahiro Yamada  the build scripts much simpler.
159