doc/README.kconfig

   1 Kconfig in U-Boot
   2 =================
   3
   4 This document describes the configuration infrastructure of U-Boot.
   5
   6 The conventional configuration was replaced by Kconfig at v2014.10-rc1 release.
   7
   8
   9 Language Specification
  10 ----------------------
  11
  12 Kconfig originates in Linux Kernel.
  13 See the file "Documentation/kbuild/kconfig*.txt" in your Linux Kernel
  14 source directory for a basic specification of Kconfig.
  15
  16
  17 Difference from Linux's Kconfig
  18 -------------------------------
  19
  20 The biggest difference between Linux Kernel and U-Boot in terms of the
  21 configuration is that U-Boot has to configure multiple boot images per board:
  22 Normal, SPL, TPL.
  23 Kconfig functions need to be expanded for U-Boot to handle multiple images.
  24 The files scripts/kconfig/* were imported from Linux Kernel and adjusted
  25 for that purpose.
  26
  27 See below for how each configuration target works in U-Boot:
  28
  29 - config, nconfig, menuconfig, xconfig, gconfig
  30
  31   These targets are used to configure Normal and create (or modify) the
  32   .config file.  For SPL configuration, the configutation targets are prefixed
  33   with "spl/", for example "make spl/config", "make spl/menuconfig", etc.
  34   Those targets create or modify the spl/.config file.  Likewise, run
  35   "make tpl/config", "make tpl/menuconfig", etc. for TPL.
  36
  37 - silentoldconfig
  38
  39   This target updates .config, include/generated/autoconf.h and
  40   include/configs/*.  In U-Boot, the same thing is done for SPL, TPL,
  41   if supported by the target board.  Depending on whether CONFIG_SPL and
  42   CONFIG_TPL are defined, "make silentoldconfig" iterates three times at most
  43   changing the work directory.
  44
  45   To sum up, "make silentoldconfig" possibly updates:
  46   - .config, include/generated/autoconf.h, include/config/*
  47   - spl/.config, spl/include/generated/autoconf.h, spl/include/config/*
  48     (in case CONFIG_SPL=y)
  49   - tpl/.config, tpl/include/generated/autoconf.h, tpl/include/config/*
  50     (in case CONFIG_TPL=y)
  51
  52 - defconfig, <board>_defconfig
  53
  54   The target "<board>_defconfig" is used to create the .config based on the
  55   file configs/<board>_defconfig.  The "defconfig" target is the same
  56   except it checks for a file specified with KBUILD_DEFCONFIG environment.
  57
  58   Note:
  59   The defconfig files are placed under the "configs" directory,
  60   not "arch/$(ARCH)/configs".  This is because "ARCH" is not necessarily
  61   given from the command line for the U-Boot configuration and build.
  62
  63   The defconfig file format in U-Boot has the special syntax; each line has
  64   "<condition>:" prefix to show which image(s) the line is valid for.
  65   For example,
  66
  67   CONFIG_FOO=100
  68   S:CONFIG_FOO=200
  69   T:CONFIG_FOO=300
  70   ST:CONFIG_BAR=y
  71   +S:CONFIG_BAZ=y
  72   +T:CONFIG_QUX=y
  73   +ST:CONFIG_QUUX=y
  74
  75   Here, the "<condition>:" prefix is one of:
  76   None  - the line is valid only for Normal image
  77   S:    - the line is valid only for SPL image
  78   T:    - the line is valid only for TPL image
  79   ST:   - the line is valid for SPL and TPL images
  80   +S:   - the line is valid for Normal and SPL images
  81   +T:   - the line is valid for Normal and TPL images
  82   +ST:  - the line is valid for Normal, SPL and SPL images
  83
  84   So, if neither CONFIG_SPL nor CONFIG_TPL is defined, the defconfig file
  85   has no "<condition>:" part and therefore has the same form as in Linux.
  86   From the example defconfig shown above, three separete configuration sets
  87   are generated and used for creating .config, spl/.config and tpl/.config.
  88
  89   - Input for the default configuration of Normal
  90      CONFIG_FOO=100
  91      CONFIG_BAZ=y
  92      CONFIG_QUX=y
  93      CONFIG_QUUX=y
  94
  95   - Input for the default configuration of SPL
  96      CONFIG_FOO=200
  97      CONFIG_BAR=y
  98      CONFIG_BAZ=y
  99      CONFIG_QUUX=y
 100
 101   - Input for the default configuration of TPL
 102      CONFIG_FOO=300
 103      CONFIG_BAR=y
 104      CONFIG_QUX=y
 105      CONFIG_QUUX=y
 106
 107 - savedefconfig
 108
 109   This is the reverse operation of "make defconfig".  If neither CONFIG_SPL
 110   nor CONFIG_TPL is defined in the .config file, it works like "savedefconfig"
 111   in Linux Kernel: creates the minimal set of config based on the .config
 112   and saves it into the "defconfig" file.  If CONFIG_SPL (and CONFIG_TPL) is
 113   defined, the common lines among .config, spl/.config (and tpl/.config) are
 114   coalesced together with "<condition:>" prefix for each line as shown above.
 115   This file can be used as an input of "defconfig" target.
 116
 117 - <board>_config
 118
 119   This does not exist in Linux's Kconfig.
 120   Prior to Kconfig, in U-Boot, "make <board>_config" was used for the
 121   configuration.  It is still supported for backward compatibility and
 122   its behavior is the same as "make <board>_defconfig".
 123
 124
 125 Migration steps to Kconfig
 126 --------------------------
 127
 128 Prior to Kconfig, the C preprocessor based board configuration had been used
 129 in U-Boot.
 130
 131 Although Kconfig was introduced and some configs have been moved to Kconfig,
 132 many of configs are still defined in C header files.  It will take a very
 133 long term to move all of them to Kconfig.  In the interim, the two different
 134 configuration infrastructures should coexist.
 135 The configuration files are generated by both Kconfig and the old preprocessor
 136 based configuration as follows:
 137
 138 Configuration files for use in C sources
 139   - include/generated/autoconf.h     (generated by Kconfig for Normal)
 140   - spl/include/generated/autoconf.h (generated by Kconfig for SPL)
 141   - tpl/include/generated/autoconf.h (generated by Kconfig for TPL)
 142   - include/configs/<board>.h        (exists for all boards)
 143
 144 Configuration file for use in makefiles
 145   - include/config/auto.conf         (generated by Kconfig for Normal)
 146   - spl/include/config/auto.conf     (generated by Kconfig for SPL)
 147   - tpl/include/config/auto.conf     (generated by Kconfig for TPL)
 148   - include/autoconf.mk              (generated by the old config for Normal)
 149   - spl/include/autoconfig.mk        (generated by the old config for SPL)
 150   - tpl/include/autoconfig.mk        (generated by the old config for TPL)
 151
 152 When adding a new CONFIG macro, it is highly recommended to add it to Kconfig
 153 rather than to a header file.
 154
 155
 156 Conversion from boards.cfg to Kconfig
 157 -------------------------------------
 158
 159 Prior to Kconfig, boards.cfg was a primary database that contained Arch, CPU,
 160 SoC, etc. of all the supported boards.  It was deleted when switching to
 161 Kconfig.  Each field of boards.cfg was converted as follows:
 162
 163  Status      ->  "S:" entry of MAINTAINERS
 164  Arch        ->  CONFIG_SYS_ARCH defined by Kconfig
 165  CPU         ->  CONFIG_SYS_CPU defined by Kconfig
 166  SoC         ->  CONFIG_SYS_SOC defined by Kconfig
 167  Vendor      ->  CONFIG_SYS_VENDOR defined by Kconfig
 168  Board       ->  CONFIG_SYS_BOARD defined by Kconfig
 169  Target      ->  File name of defconfig (configs/<target>_defconfig)
 170  Options     ->  CONFIG_SYS_EXTRA_OPTIONS defined by Kconfig
 171  Maintainers ->  "M:" entry of MAINTAINERS
 172
 173
 174 Tips to add/remove boards
 175 -------------------------
 176
 177 When adding a new board, the following steps are generally needed:
 178
 179  [1] Add a header file include/configs/<target>.h
 180  [2] Make sure to define necessary CONFIG_SYS_* in Kconfig:
 181        Define CONFIG_SYS_CPU="cpu" to compile arch/<arch>/cpu/<cpu>
 182        Define CONFIG_SYS_SOC="soc" to compile arch/<arch>/cpu/<cpu>/<soc>
 183        Define CONFIG_SYS_VENDOR="vendor" to compile board/<vendor>/common/*
 184          and board/<vendor>/<board>/*
 185        Define CONFIG_SYS_BOARD="board" to compile board/<board>/*
 186          (or board/<vendor>/<board>/* if CONFIG_SYS_VENDOR is defined)
 187        Define CONFIG_SYS_CONFIG_NAME="target" to include
 188          include/configs/<target>.h
 189  [3] Add a new entry to the board select menu in Kconfig.
 190      The board select menu is located in arch/<arch>/Kconfig or
 191      arch/<arch>/*/Kconfig.
 192  [4] Add a MAINTAINERS file
 193      It is generally placed at board/<board>/MAINTAINERS or
 194      board/<vendor>/<board>/MAINTAINERS
 195  [5] Add configs/<target>_defconfig
 196
 197 When removing an obsolete board, the following steps are generally needed:
 198
 199  [1] Remove configs/<target>_defconfig
 200  [2] Remove include/configs/<target>.h if it is not used by any other boards
 201  [3] Remove board/<vendor>/<board>/* or board/<board>/* if it is not used
 202      by any other boards
 203  [4] Update MAINTAINERS if necessary
 204  [5] Remove the unused entry from the board select menu in Kconfig
 205  [6] Add an entry to doc/README.scrapyard
 206
 207
 208 TODO
 209 ----
 210
 211 - The option field of boards.cfg, which was used for the pre-Kconfig
 212   configuration, moved to CONFIG_SYS_EXTRA_OPTIONS verbatim now.
 213   Board maintainers are expected to implement proper Kconfig options
 214   and switch over to them.  Eventually CONFIG_SYS_EXTRA_OPTIONS will go away.
 215   CONFIG_SYS_EXTRA_OPTIONS should not be used for new boards.
 216
 217 - In the pre-Kconfig, a single board had multiple entries in the boards.cfg
 218   file with differences in the option fields.  The correspoing defconfig files
 219   were auto-generated when switching to Kconfig.  Now we have too many
 220   defconfig files compared with the number of the supported boards.  It is
 221   recommended to have only one defconfig per board and allow users to select
 222   the config options.
 223
 224 - Move the config macros in header files to Kconfig.  When we move at least
 225   macros used in makefiles, we can drop include/autoconfig.mk, which makes
 226   the build scripts much simpler.