This file explains how to work with gem5‘s implementation of the kconfig configuration system, very similar to what’s used by the linux kernel. It talks about how to work with the Kconfig files themselves which define what user adjustable configuration parameters there are, and how they work and interoperate.
This file does not:
gem5 uses the kconfiglib python library for consuming and manipulating kconfig configurations. It is very similar to the kconfig implementation used by the linux kernel, but is slightly different and has some small extensions added to it. Almost all kconfig documentation written for the kernel's implementation should apply here as well, but it may occasionally be necessary to refer to the kconfiglib documentation.
Also, because gem5‘s build system is more modular than kconfig’s design supports out of the box, particularly for “choice” blocks, we have extended kconfiglib and added a “cont_choice” keyword. This keyword is very similar to “choice”, except “cont_choice” blocks can be re-opened and extended with more options further into the config.
This can be used to set up a central point where the user can choose between mutually exclusive options, and still allow new Kconfig files to add new options without modifying the original source.
Having to choose between mutually exclusive options should be avoided in general, but is unavoidable in a few key places in gem5 at the moment. Once those areas have been addressed, this keyword may be removed in the future.
In “env” SCons environment in SConscript files, or the “main” environment in SConsopts files, can hold many variables which help SCons operate generally, like setting what include paths to use, what the compiler command line is, etc. These environments each have a ‘CONF’ sub-dict which holds all the variables which are actually used to configure gem5, and not to configure SCons and the build process itself.
All variables in this dict are automatically available to include in c++. To access the value of env[‘CONF’][‘FOO’], you would #include “config/foo.hh”. Because these variables are in a shared namespace, their names should be unique and distinctive.
These values are available in config scripts through the m5.defines.buildEnv dict.
Some configuration values are not set by the user, and are measured from the host environment. These could reflect the availability of a header file, library or tool, whether the compiler supports a particular option or language feature, etc.
These values should be measured in SConsopts files, and stored in the ‘CONF’ dict described above. Like any other variable in ‘CONF’, they are then available to C++ through generated header files, to config scripts through buildEnv, etc. They are also available in the kconfig files themselves through a mechanism discussed below.
When the gem5 Kconfig files are processed to either manipulate a configuration through a tool, or to apply a configuration to the gem5 build, all the values in ‘CONF’ are temporarily put into environment variables. In the Kconfig files themselves, these environment variables can be accessed using $(FOO) syntax, which is described in kconfiglib's documentation.
Note that this is slightly different from the kernel's Kconfig syntax, where the environment variables would have to be imported in using other keywords first.
This is generally used to make automatic/measured settings which were determined in SConsopts files available in Kconfig files. They can then be used to compute dependencies, or to set default values, etc.
Unlike SConscript files, gem5 does not find Kconfig files automatically, and they are only used if they are included explicitly in other Kconfig files.
Kconfig options should be defined as close as possible to where they are used. This makes them easier to find, keeps related functionality grouped together in the source tree, and minimizes conflicts from modifying the same few, central files when changing unrelated parts of gem5.
When including a Kconfig file in another, you should use the “rsource” keyword which is a kconfiglib extension. This lets you include the other file using a path which is relative to the current file, and also helps make the kconfig files more modular and self contained.
The EXTRAS variable can be set to a list of directories which hold additional source that should be built into gem5. Because there's no way to know what (if any) paths will be in EXTRAS ahead of time, it is not possible to explicitly include kconfig files in those directories from a static file.
Instead, gem5‘s real root Kconfig file, which includes the one in src, is automatically generated as part of the build. It uses the kconfiglib extension “osource” to optionally source a file called Kconfig in the base of each EXTRAS directory after it has sourced gem5’s main Kconfig. If you want to add Kconfig options to your EXTRAS directory, you can create that file, and then rsource any additional internal Kconfig files as needed.