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 Here are some worth-mentioning configuration targets.
  21
  22 - silentoldconfig
  23
  24   This target updates .config, include/generated/autoconf.h and
  25   include/configs/* as in Linux.  In U-Boot, it also does the followings
  26   for the compatibility with the old configuration system:
  27
  28    * create a symbolic link "arch/${ARCH}/include/asm/arch" pointing to
  29      the SoC/CPU specific header directory
  30    * create include/config.h
  31    * create include/autoconf.mk
  32    * create spl/include/autoconf.mk (SPL and TPL only)
  33    * create tpl/include/autoconf.mk (TPL only)
  34
  35    If we could completely switch to Kconfig in a long run
  36    (i.e. remove all the include/configs/*.h), those additional processings
  37    above would be removed.
  38
  39 - defconfig
  40
  41   In U-Boot, "make defconfig" is a shorthand of "make sandbox_defconfig"
  42
  43 - <board>_defconfig
  44
  45   Now it works as in Linux.
  46   The prefixes such as "+S:" in *_defconfig are deprecated.
  47   You can simply remove the prefixes.  Do not add them for new boards.
  48
  49 - <board>_config
  50
  51   This does not exist in Linux's Kconfig.
  52   "make <board>_config" works the same as "make <board>_defconfig".
  53   Prior to Kconfig, in U-Boot, "make <board>_config" was used for the
  54   configuration.  It is still supported for backward compatibility, so
  55   we do not need to update the distro recipes.
  56
  57
  58 The other configuration targets work as in Linux Kernel.
  59
  60
  61 Migration steps to Kconfig
  62 --------------------------
  63
  64 Prior to Kconfig, the C preprocessor based board configuration had been used
  65 in U-Boot.
  66
  67 Although Kconfig was introduced and some configs have been moved to Kconfig,
  68 many of configs are still defined in C header files.  It will take a very
  69 long term to move all of them to Kconfig.  In the interim, the two different
  70 configuration infrastructures should coexist.
  71 The configuration files are generated by both Kconfig and the old preprocessor
  72 based configuration as follows:
  73
  74 Configuration files for use in C sources
  75   - include/generated/autoconf.h     (generated by Kconfig for Normal)
  76   - include/configs/<board>.h        (exists for all boards)
  77
  78 Configuration file for use in makefiles
  79   - include/config/auto.conf         (generated by Kconfig)
  80   - include/autoconf.mk              (generated by the old config for Normal)
  81   - spl/include/autoconfig.mk        (generated by the old config for SPL)
  82   - tpl/include/autoconfig.mk        (generated by the old config for TPL)
  83
  84 When adding a new CONFIG macro, it is highly recommended to add it to Kconfig
  85 rather than to a header file.
  86
  87
  88 Conversion from boards.cfg to Kconfig
  89 -------------------------------------
  90
  91 Prior to Kconfig, boards.cfg was a primary database that contained Arch, CPU,
  92 SoC, etc. of all the supported boards.  It was deleted when switching to
  93 Kconfig.  Each field of boards.cfg was converted as follows:
  94
  95  Status      ->  "S:" entry of MAINTAINERS
  96  Arch        ->  CONFIG_SYS_ARCH defined by Kconfig
  97  CPU         ->  CONFIG_SYS_CPU defined by Kconfig
  98  SoC         ->  CONFIG_SYS_SOC defined by Kconfig
  99  Vendor      ->  CONFIG_SYS_VENDOR defined by Kconfig
 100  Board       ->  CONFIG_SYS_BOARD defined by Kconfig
 101  Target      ->  File name of defconfig (configs/<target>_defconfig)
 102  Options     ->  CONFIG_SYS_EXTRA_OPTIONS defined by Kconfig
 103  Maintainers ->  "M:" entry of MAINTAINERS
 104
 105
 106 Tips to add/remove boards
 107 -------------------------
 108
 109 When adding a new board, the following steps are generally needed:
 110
 111  [1] Add a header file include/configs/<target>.h
 112  [2] Make sure to define necessary CONFIG_SYS_* in Kconfig:
 113        Define CONFIG_SYS_CPU="cpu" to compile arch/<arch>/cpu/<cpu>
 114        Define CONFIG_SYS_SOC="soc" to compile arch/<arch>/cpu/<cpu>/<soc>
 115        Define CONFIG_SYS_VENDOR="vendor" to compile board/<vendor>/common/*
 116          and board/<vendor>/<board>/*
 117        Define CONFIG_SYS_BOARD="board" to compile board/<board>/*
 118          (or board/<vendor>/<board>/* if CONFIG_SYS_VENDOR is defined)
 119        Define CONFIG_SYS_CONFIG_NAME="target" to include
 120          include/configs/<target>.h
 121  [3] Add a new entry to the board select menu in Kconfig.
 122      The board select menu is located in arch/<arch>/Kconfig or
 123      arch/<arch>/*/Kconfig.
 124  [4] Add a MAINTAINERS file
 125      It is generally placed at board/<board>/MAINTAINERS or
 126      board/<vendor>/<board>/MAINTAINERS
 127  [5] Add configs/<target>_defconfig
 128
 129 When removing an obsolete board, the following steps are generally needed:
 130
 131  [1] Remove configs/<target>_defconfig
 132  [2] Remove include/configs/<target>.h if it is not used by any other boards
 133  [3] Remove board/<vendor>/<board>/* or board/<board>/* if it is not used
 134      by any other boards
 135  [4] Update MAINTAINERS if necessary
 136  [5] Remove the unused entry from the board select menu in Kconfig
 137  [6] Add an entry to doc/README.scrapyard
 138
 139
 140 TODO
 141 ----
 142
 143 - The option field of boards.cfg, which was used for the pre-Kconfig
 144   configuration, moved to CONFIG_SYS_EXTRA_OPTIONS verbatim now.
 145   Board maintainers are expected to implement proper Kconfig options
 146   and switch over to them.  Eventually CONFIG_SYS_EXTRA_OPTIONS will go away.
 147   CONFIG_SYS_EXTRA_OPTIONS should not be used for new boards.
 148
 149 - In the pre-Kconfig, a single board had multiple entries in the boards.cfg
 150   file with differences in the option fields.  The corresponding defconfig
 151   files were auto-generated when switching to Kconfig.  Now we have too many
 152   defconfig files compared with the number of the supported boards.  It is
 153   recommended to have only one defconfig per board and allow users to select
 154   the config options.
 155
 156 - Move the config macros in header files to Kconfig.  When we move at least
 157   macros used in makefiles, we can drop include/autoconfig.mk, which makes
 158   the build scripts much simpler.