misc: Add KCONFIG.md file which talks about Kconfig files.

There are some minor aspects about how Kconfig files are used in gem5
which are a little different from how they are documented online or are
used in other projects. Document that in this file.

Change-Id: Ib981d1e265cf466d453071b33820d6baa24e17d4
Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5/+/58634
Reviewed-by: Jason Lowe-Power <power.jg@gmail.com>
Maintainer: Jason Lowe-Power <power.jg@gmail.com>
Tested-by: kokoro <noreply+kokoro@google.com>

KCONFIG.md

@@ -0,0 +1,114 @@
+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*:
+
+ * Describe how kconfig works generally. This is well documented elsewhere, for
+    instance [here](
+    https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html):
+ * The settings in gem5's kconfig files. These should be documented with help
+   text within the kconfig files, and in the code where these options are
+   consumed.
+ * The various tools which can manipulate a given configuration. These are
+   documented in gem5's SCons help text.
+
+# kconfiglib
+
+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.
+
+# The 'CONF' dict in the SCons environment
+
+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.
+
+# Automatic/measured configuration values.
+
+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.
+
+# Accessing 'CONF' values in Kconfig files.
+
+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.
+
+# Structure of the Kconfig hierarchy
+
+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.
+
+# EXTRAS directories.
+
+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.