Documentation: Update index.md and move files

* Add more subdirectories and index.mds.
* Move "getting started" and "lessons" into sub-directories.
* Move "NativeRaminit" into northbridge/intel/sandybridge folder.
* Move "MultiProcessorInit" into soc/intel/icelake folder.
* Reference new files

Change-Id: I78c3ec0e8bcc342686277ae141a88d0486680978
Signed-off-by: Philipp Deppenwiese <zaolin@das-labor.org>
Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com>
Reviewed-on: https://review.coreboot.org/26262
Reviewed-by: Patrick Georgi <pgeorgi@google.com>
Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>

5 files changed, 1650 insertions, 0 deletions

diff --git a/Documentation/getting_started/build_system.md b/Documentation/getting_started/build_system.md
new file mode 100644
index 0000000000..787c833d2b
--- /dev/null
+++ b/Documentation/getting_started/build_system.md
@@ -0,0 +1,86 @@
+# The coreboot build system
+(this document is still incomplete and will be filled in over time)
+
+## General operation
+The coreboot build system is based on GNU make but extends it significantly
+to the point of providing its own custom language.
+The overhead of learning this new syntax is (hopefully) offset by its lower
+complexity.
+
+The build system is defined in the toplevel `Makefile` and `toolchain.inc`
+and is supposed to be generic (and is in fact used with a number of other
+projects).  Project specific configuration should reside in files called
+`Makefile.inc`.
+
+In general, the build system provides a number of "classes" that describe
+various parts of the build. These cover the various build targets in coreboot
+such as the stages, subdirectories with more source code, and the general
+addition of files.
+
+Each class has a name (eg. `romstage`, `subdirs`, `cbfs-files`) and is used
+by filling in a variable of that name followed by `-y` (eg. `romstage-y`,
+`subdirs-y`, `cbfs-files-y`).
+The `-y` suffix allows a simple interaction with our Kconfig build
+configuration system: Kconfig options are available as variables starting
+with a `CONFIG_` prefix and boolean options contain `y`, `n` or are empty.
+
+This allows `class-$(CONFIG_FOO) += bar` to conditionally add `bar` to
+`class` depending on the choice for `FOO`.
+
+## classes
+Classes can be defined as required. `subdirs` is handled internally since
+it's parsed per subdirectory to add further directories to the rule set.
+
+TODO: explain how to create new classes and how to evaluate them.
+
+### subdirs
+`subdirs` contains subdirectories (relative to the current directory) that
+should also be handled by the build system. The build system expects these
+directories to contain a file called `Makefile.inc`.
+
+Subdirectories are not read at the point where the `subdirs` statement
+resides but later, after the current directory is handled (and potentially
+others, too).
+
+### cbfs-files
+This class is used to add files to the final CBFS image. Since several more
+options need to be maintained than can comfortably fit in that single
+variable, additional variables are used.
+
+`cbfs-files-y` contains the file name used in the CBFS image (called `foo`
+here). Additional options are added in `foo-$(option)` variables. The
+supported options are:
+
+*  `file`: The on-disk file to add as `foo` (required)
+*  `type`: The file type. Can be `raw`, `stage`, `payload`, and `flat-binary`
+   (required)
+*  `compression`: Can be `none` or `lzma` (default: none)
+*  `position`: An absolute position constraint for the placement of the file
+   (default: none)
+*  `align`: Minimum alignment for the file (default: none)
+*  `options`: Additional cbfstool options (default: none)
+
+`position` and `align` are mutually exclusive.
+
+#### FMAP region support
+With the addition of FMAP flash partitioning support to coreboot, there was a
+need to extend the specification of files to provide more precise control
+which regions should contain which files, and even change some flags based on
+the region.
+
+Since FMAP policies depend on features using FMAP, that's kept separate from
+the cbfs-files class.
+
+The `position` and `align` options for file `foo` can be overwritten for a
+region `REGION` using `foo-REGION-position` and `foo-REGION-align`.
+
+The regions that each file should end in can be defined by overriding a
+function called `regions-for-file` that's called as
+`$(call regions-for-file,$(filename))` and should return a comma-separated
+list of regions, such as `REGION1,REGION2,REGION3`.
+
+The default implementation just returns `COREBOOT` (the default region) for
+all files.
+
+vboot provides its own implementation of `regions-for-file` that can be used
+as reference in `src/vboot/Makefile.inc`.
diff --git a/Documentation/getting_started/gerrit_guidelines.md b/Documentation/getting_started/gerrit_guidelines.md
new file mode 100644
index 0000000000..cf7d5e8c5a
--- /dev/null
+++ b/Documentation/getting_started/gerrit_guidelines.md
@@ -0,0 +1,277 @@
+coreboot Gerrit Etiquette and Guidelines
+========================================
+
+The following rules are the requirements for behavior in the coreboot
+codebase in gerrit. These have mainly been unwritten rules up to this
+point, and should be familiar to most users who have been active in
+coreboot for a period of time. Following these rules will help reduce
+friction in the community.
+
+Note that as with many rules, there are exceptions. Some have been noted
+in the 'More Detail' section. If you feel there is an exception not listed
+here, please discuss it in the mailing list to get this document  updated.
+Don't just assume that it's okay, even if someone on IRC says it is.
+
+
+Summary:
+--------
+These are the expectations for committing, reviewing, and submitting code
+into coreboot git and gerrit. While breaking individual rules may not have
+immediate consequences, the coreboot leadership may act on repeated or
+flagrant violations with or without notice.
+
+* Don't violate the licenses.
+* Let non-trivial patches sit in a review state for at least 24 hours
+before submission.
+* Try to coordinate with platform maintainers when making changes to
+platforms.
+* If you give a patch a -2, you are responsible for giving concrete
+recommendations for what could be changed to resolve the issue the patch
+addresses.
+* Don't modify other people's patches without their consent.
+* Be respectful to others when commenting.
+* Don’t submit patches that you know will break other platforms.
+
+
+More detail:
+------------
+* Don't violate the licenses. If you're submitting code that you didn't
+write yourself, make sure the license is compatible with the license of the
+project you're submitting the changes to. If you’re submitting code that
+you wrote that might be owned by your employer, make sure that your
+employer is aware and you are authorized to submit the code. For
+clarification, see the Developer's Certificate of Origin in the coreboot
+[Signed-off-by policy](https://www.coreboot.org/Development_Guidelines#Sign-off_Procedure).
+
+* Let non-trivial patches sit in a review state for at least 24 hours
+before submission. Remember that there are coreboot developers in timezones
+all over the world, and everyone should have a chance to contribute.
+Trivial patches would be things like whitespace changes or spelling fixes.
+In general, small changes that don’t impact the final binary output. The
+24-hour period would start at submission, and would be restarted at any
+update which significantly changes any part of the patch. Patches can be
+'Fast-tracked' and submitted in under this 24 hour with the agreement of at
+least 3 +2 votes.
+
+* Do not +2 patches that you authored or own, even for something as trivial
+as whitespace fixes. When working on your own patches, it’s easy to
+overlook something like accidentally updating file permissions or git
+submodule commit IDs. Let someone else review the patch. An exception to
+this would be if two people worked in the patch together. If both +2 the
+patch, that is acceptable, as each is giving a +2 to the other's work.
+
+* Try to coordinate with platform maintainers and other significant
+contributors to the code when making changes to platforms. The platform
+maintainers are the users who initially pushed the code for that platform,
+as well as users who have made significant changes to a platform. To find
+out who maintains a piece of code, please use util/scripts/maintainers.go
+or refer to the original author of the code in git log.
+
+* If you give a patch a -2, you are responsible for giving concrete
+recommendations for what could be changed to resolve the issue the patch
+addresses. If you feel strongly that a patch should NEVER be merged, you
+are responsible for defending your position and listening to other points
+of view. Giving a -2 and walking away is not acceptable, and may cause your
+ -2 to be removed by the coreboot leadership after no less than a week. A
+ notification that the -2 will be removed unless there is a response will
+ be sent out at least 2 days before it is removed.
+
+* Don't modify other people's patches unless you have coordinated this with
+the owner of that patch. Not only is this considered rude, but your changes
+could be unintentionally lost. An exception to this would be for patches
+that have not been updated for more than 90 days. In that case, the patch
+can be taken over if the original author does not respond to requests for
+updates. Alternatively, a new patch can be pushed with the original
+content, and both patches should be updated to reference the other.
+
+* Be respectful to others when commenting on patches. Comments should
+be kept to the code, and should be kept in a polite tone. We are a
+worldwide community and English is a difficult language. Assume your
+colleagues are intelligent and do not intend disrespect. Resist the urge to
+retaliate against perceived verbal misconduct, such behavior is not
+conducive to getting patches merged.
+
+* Don’t submit code that you know will break other platforms. If your patch
+affects code that is used by other platforms, it should be compatible with
+those platforms. While it would be nice to update any other platforms, you
+must at least provide a path that will allow other platforms to continue
+working.
+
+
+Recommendations for gerrit activity:
+------------------------------------
+These guidelines are less strict than the ones listed above. These are more
+of the “good idea” variety. You are requested to follow the below
+guidelines, but there will probably be no actual consequences if they’re
+not followed. That said, following the recommendations below will speed up
+review of your patches, and make the members of the community do less work.
+
+* Each patch should be kept to one logical change, which should be
+described in the title of the patch. Unrelated changes should be split out
+into separate patches. Fixing whitespace on a line you’re editing is
+reasonable. Fixing whitespace around the code you’re working on should be a
+separate ‘cleanup’ patch. Larger patches that touch several areas are fine,
+so long as they are one logical change. Adding new chips and doing code
+cleanup over wide areas are two examples of this.
+
+* Test your patches before submitting them to gerrit. It's also appreciated
+if you add a line to the commit message describing how the patch was
+tested. This prevents people from having to ask whether and how the patch
+was tested. Examples of this sort of comment would be ‘TEST=Built
+platform’ or ‘Tested by building and booting platform’.  Stating that the
+patch was not tested is also fine, although you might be asked to do some
+testing in cases where that would be reasonable.
+
+* Take advantage of the lint tools to make sure your patches don’t contain
+trivial mistakes. By running ‘make gitconfig’, the lint-stable tools are
+automatically put in place and will test your patches before they are
+committed. As a violation of these tools will cause the jenkins build test
+to fail, it’s to your advantage to test this before pushing to gerrit.
+
+* Don't submit patch trains longer than around 20 patches unless you
+understand how to manage long patch trains. Long patch trains can become
+difficult to handle and tie up the build servers for long periods of time
+if not managed well. Rebasing a patch train over and over as you fix
+earlier patches in the train can hide comments, and make people review the
+code multiple times to see if anything has changed between revisions. When
+pushing long patch trains, it is recommended to only push the full patch
+train once - the initial time, and only to rebase three or four patches at
+a time.
+
+* Run 'make what-jenkins-does' locally on patch trains before submitting.
+This helps verify that the patch train won’t tie up the jenkins builders
+for no reason if there are failing patches in the train. For running
+parallel builds, you can specify the number of cores to use by setting the
+the CPUS environment variable. Example:
+        make what-jenkins-does CPUS=8
+
+* Use a topic when pushing a train of patches. This groups the commits
+together so people can easily see the connection at the top level of
+gerrit. Topics can be set for individual patches in gerrit by going into
+the patch and clicking on the icon next to the topic line. Topics can also
+be set when you push the patches into gerrit. For example, to push a set of
+commits with the the i915-kernel-x60 set, use the command:
+        git push origin HEAD:refs/for/master/i915-kernel-x60
+
+* If one of your patches isn't ready to be merged, make sure it's obvious
+that you don't feel it's ready for merge yet. The preferred way to show
+this is by marking in the commit message that it’s not ready until X. The
+commit message can be updated easily when it’s ready to be pushed.
+Examples of this are "WIP: title" or "[NEEDS_TEST]: title".  Another way to
+mark the patch as not ready would be to give it a -1 or -2 review, but
+isn't as obvious as the commit message. These patches can also be pushed as
+drafts as shown in the next guideline.
+
+* When pushing patches that are not for submission, these should be marked
+as such. This can be done in the title ‘[DONOTSUBMIT]’, or can be pushed as
+draft commits, so that only explicitly added reviewers will see them. These
+sorts of patches are frequently posted as ideas or RFCs for the community
+to look at. To push a draft, use the command:
+        git push origin HEAD:refs/drafts/master
+
+* Respond to anyone who has taken the time to review your patches, even if
+it's just to say that you disagree. While it may seem annoying to address a
+request to fix spelling or 'trivial' issues, it’s generally easy to handle
+in gerrit’s built-in editor. If you do use the built-in editor, remember to
+get that change to your local copy before re-pushing. It's also acceptable
+to add fixes for these sorts of comments to another patch, but it's
+recommended that that patch be pushed to gerrit before the initial patch
+gets submitted.
+
+* Consider breaking up large individual patches into smaller patches
+grouped by areas. This makes the patches easier to review, but increases
+the number of patches. The way you want to handle this is a personal
+decision, as long as each patch is still one logical change.
+
+* If you have an interest in a particular area or mainboard, set yourself
+up as a ‘maintainer’ of that area by adding yourself to the MAINTAINERS
+file in the coreboot root directory. Eventually, this should automatically
+add you as a reviewer when an area that you’re listed as a maintainer is
+changed.
+
+* Submit mainboards that you’re working on to the board-status repo. This
+helps others and shows that these mainboards are currently being
+maintained. At some point, boards that are not up to date in the
+board-status repo will probably end up getting removed from the coreboot
+master branch.
+
+* Abandon patches that are no longer useful, or that you don’t intend to
+keep working on to get submitted.
+
+* Bring attention to patches that you would like reviewed. Add reviewers,
+ask for reviewers on IRC or even just rebase it against the current
+codebase to bring it to the top of the gerrit list. If you’re not sure who
+would be a good reviewer, look in the MAINTAINERS file or git history of
+the files that you’ve changed, and add those people.
+
+* Familiarize yourself with the coreboot [commit message
+guidelines](https://www.coreboot.org/Git#Commit_messages), before pushing
+patches. This will help to keep annoying requests to fix your commit
+message to a minimum.
+
+* If there have been comments or discussion on a patch, verify that the
+comments have been addressed before giving a +2. If you feel that a comment
+is invalid, please respond to that comment instead of just ignoring it.
+
+* Be conscientious when reviewing patches. As a reviewer who approves (+2)
+a patch, you are responsible for the patch and the effect it has on the
+codebase. In the event that the patch breaks things, you are expected to
+be actively involved in the cleanup effort. This means you shouldn’t +2 a
+patch just because you trust the author of a patch - Make sure you
+understand what the implications of a patch might be, or leave the review
+to others. Partial reviews, reviewing code style, for example, can be given
+a +1 instead of a +2. This also applies if you think the patch looks good,
+but may not have the experience to know if there may be unintended
+consequences.
+
+* If there is still ongoing discussion to a patch, try to wait for a
+conclusion to the discussion before submitting it to the tree. If you feel
+that someone is just bikeshedding, maybe just state that and give a time
+that the patch will be submitted if no new objections are raised.
+
+* When working with patch trains, for minor requests it’s acceptable to
+create a fix addressing a comment in another patch at the end of the patch
+train. This minimizes rebases of the patch train while still addressing the
+request. For major problems where the change doesn’t work as intended or
+breaks other platforms, the change really needs to go into the original
+patch.
+
+* When bringing in a patch from another git repo, update the original
+git/gerrit tags by prepending the lines with 'Original-'.  Marking
+the original text this way makes it much easier to tell what changes
+happened in which repository. This applies to these lines, not the actual
+commit message itself:
+        Commit-Id:
+        Change-Id:
+        Signed-off-by:
+        Reviewed-on:
+        Tested-by:
+        Reviewed-by:
+The script 'util/gitconfig/rebase.sh' can be used to help automate this.
+Other tags such as 'Commit-Queue' can simply be removed.
+
+
+Expectations contributors should have:
+--------------------------------------
+* Don't expect that people will review your patch unless you ask them to.
+Adding other people as reviewers is the easiest way. Asking for reviews for
+individual patches in the IRC channel, or by sending a direct request to an
+individual through your favorite messenger is usually the best way to get a
+patch reviewed quickly.
+
+* Don't expect that your patch will be submitted immediately after getting
+a +2. As stated previously, non-trivial patches should wait at least 24
+hours before being submitted. That said, if you feel that your patch or
+series of patches has been sitting longer than needed, you can ask for it
+to be submitted on IRC, or comment that it's ready for submission in the
+patch. This will move it to the top of the list where it's more likely to
+be noticed and acted upon.
+
+* Reviews are about the code. It's easy to take it personally when someone
+is criticising your code, but the whole idea is to get better code into our
+codebase. Again, this also applies in the other direction: review code,
+criticize code, but don’t make it personal.
+
+
+Requests for clarification and suggestions for updates to these guidelines
+should be sent to the coreboot mailing list at <coreboot@coreboot.org>.
diff --git a/Documentation/getting_started/index.md b/Documentation/getting_started/index.md
new file mode 100644
index 0000000000..b23e89d701
--- /dev/null
+++ b/Documentation/getting_started/index.md
@@ -0,0 +1,6 @@
+# Getting Started
+
+* [Build System](build_system.md)
+* [Submodules](submodules.md)
+* [Kconfig](kconfig.md)
+* [Gerrit Guidelines](gerrit_guidelines.md)
diff --git a/Documentation/getting_started/kconfig.md b/Documentation/getting_started/kconfig.md
new file mode 100644
index 0000000000..7b436ce80a
--- /dev/null
+++ b/Documentation/getting_started/kconfig.md
@@ -0,0 +1,1235 @@
+# Kconfig in coreboot
+
+## Overview
+Kconfig is a tool used in coreboot, Linux, and many other projects as the main
+configuration mechanism.  In coreboot, it allows a developer both to select
+which platform to build and to modify various features within the platform. The
+Kconfig language was developed as a way to configure the Linux kernel, and is
+still maintained as a part of the Linux kernel tree. Starting in Linux 2.5.45,
+the ncurses based menuconfig was added, which is still used as the main
+configuration front end in coreboot today.
+
+The official Kconfig source and documentation is kept at kernel.org:
+
+- [Kconfig source](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/scripts/kconfig)
+- [Kconfig Language Documentation](https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt)
+
+The advantage to using Kconfig is that it allows users to easily select the
+high level features of the project to be enabled or disabled at build time.
+Ultimately the Kconfig tool generates a list of values which are used by the
+source code and Makefiles of the project.  This allows the source files to
+select features, and allows the build to determine which files should be
+compiled and linked to the rom.
+
+
+## Kconfig targets in Make
+The Kconfig program in coreboot is built from source in util/kconfig. There are
+various targets in the makefile to build Kconfig in different ways. These give
+the user control over how to build the platform
+
+
+### Front end configuration targets
+These are the make targets that would be used to update the configuration of
+the platform.
+- config - Text mode configuration tool, asks each configuration option in turn.
+  This does actually run in coreboot, but it is recommended that this not be
+  used as there is no way to save a partial config.
+- gconfig - Graphical configuration tool based on GTK+ 2.0.
+- menuconfig - Text mode, menu driven configuration tool.
+- nconfig - Text mode, menu driven configuration tool.
+- xconfig - Graphical front end based on QT.
+
+
+### Targets that update config files
+These options are used to update the coreboot config files, typically .config.
+The target file can be changed with variables in the environment or on the make
+command line.
+
+- defconfig - This generates a config based on another config file.  Use the
+  environment variable KBUILD_DEFCONFIG to specify the base config file.
+- oldconfig - Displays the answers to all configuration questions as it
+  generates the config.h file.  If an interactive question is found that does
+  not have an answer yet, it stops and queries the user for the desired value.
+- olddefconfig - Generates a config, using the default value for any symbols not
+  listed in the .config file.
+- savedefconfig - Creates a ‘mini-config’ file, stripping out all of the symbols
+  that were left as default values.  This is very useful for debugging, and is
+  how config files should be saved.
+- silentoldconfig - This evaluates the .config file the same way that the
+  oldconfig target does, but does not print out each question as it is
+  evaluated.  It still stops to query the user if an option with no answer in
+  the .config file is found.
+
+
+### Targets not typically used in coreboot
+- localmodconfig, localnoconfig, randconfig, allyesconfig, allnoconfig - These
+  are all used to generate various Kconfig files for testing.
+
+
+### Environment Variables that affect Kconfig
+These variables are typically set in the makefiles or on the make command line.
+
+#### Variables added to the coreboot Kconfig source
+These variables were added to Kconfig specifically for coreboot and are not
+included in the Linux version.
+
+- COREBOOT_BUILD_DIR=path for temporary files.   This is used by coreboot’s
+  abuild tool.
+
+- KCONFIG_STRICT=value. Define to enable warnings as errors.   This is enabled
+  in coreboot, and should not be changed.
+
+- KCONFIG_NEGATIVES=value. Define to show negative values in the autoconf.h file
+  (build/config.h). This is enabled in coreboot, and should not be changed.
+
+
+#### Variables used to control the input and output config files
+- KBUILD_DEFCONFIG=inputname of the defconfig file.  This defaults to
+  ‘configs/defconfig’ and is used by the ‘defconfig’ target.
+
+- DEFCONFIG=output name of the defconfig file.  This defaults to ‘defconfig’
+  and is used by ‘savedefconfig’ target as the output filename.
+
+- DOTCONFIG=name of the .config file.  This defaults to '.config' and is used
+  by most config type targets.
+
+
+#### Variables used by the makefiles for controlling Kconfig
+- Kconfig=root Kconfig file.  This is set to 'src/Kconfig' in the coreboot
+  makefile.
+
+- KCONFIG_CONFIG=input config file.  coreboot sets this to $(DOTCONFIG).
+
+- KCONFIG_AUTOHEADER=path and filename of autoconf.h file. coreboot sets this
+  to $(obj)/config.h.
+
+- KCONFIG_DEPENDENCIES=”kbuild dependency file".  This defaults to
+  auto.conf.cmd and outputs the name of all of the Kconfig files used.
+
+- KCONFIG_SPLITCONFIG=”directory name for individual SYMBOL.h files”.
+  coreboot sets this to $(obj)/config.
+
+#### Used only for ‘make menuconfig’
+- MENUCONFIG_MODE=single_menu.  Set to "single_menu" to enable.  All other
+  values disable the option.  This makes submenus appear below the menu option
+  instead of opening a new screen.
+
+- MENUCONFIG_COLOR=&lt;theme&gt;.  This sets the color theme for the menu from
+  these options:
+
+   -  mono       =&gt; selects colors suitable for monochrome displays.
+   -  blackbg    =&gt; selects a color scheme with black background.
+   -  classic    =&gt; theme with blue background. The classic look.
+   -  bluetitle  =&gt; an LCD friendly version of classic. (default).
+
+
+#### Used only for ‘make nconfig’
+
+- NCONFIG_MODE=single_menu
+
+   Submenus appear below the menu option instead of opening a new screen.
+
+
+#### Unused in coreboot
+
+Although these variables are not used by coreboot, their values should be left
+at the default values.  Other values may have unexpected effects on the
+codebase.
+
+- KCONFIG_SEED=randconfig seed value.
+- KCONFIG_PROBABILITY=randconfig percent to set to y.
+- KCONFIG_NOSILENTUPDATE=value.  Define to prevent silent updates to .config
+  file.
+- KCONFIG_OVERWRITECONFIG=value. Define to prevent breaking a .config symlink.
+- KCONFIG_TRISTATE=filename of tristate.conf file.
+- SRCTREE=path to src directory.
+- KCONFIG_AUTOCONFIG=path and filename of the auto.conf file.
+
+    coreboot sets this to $(obj)/auto.conf.  Although this value is actually
+    set by coreboot, the resulting file is not used.
+
+- CONFIG_=prefix for Kconfig output symbols.
+
+   coreboot expects this to *NOT* be set.
+
+
+
+## Kconfig Language
+
+The Kconfig language has about 30 keywords, some overloaded, and some with the
+same meaning.  Whitespace may have specific meaning, for example in the 'help'
+keyword.  There are 8 logical operators for use in expressions, which allow
+values to be set based on other values.
+
+
+### Terminology
+
+- Symbols - There are two types of symbols, "constant" and “non-constant”.
+    - Constant symbols are alphanumeric values used in expressions for
+      comparison. The Kconfig language specification says that these must be
+      surrounded by single or double quotes.
+    - Non-constant symbols are the 'config' values that are output into the
+      saved .config, auto.conf and config.h files. Non-constant symbols are
+      typically defined with the 'config' keyword, although they can also be
+      defined with the 'choice' keyword. These symbols may be used in a file's
+      expressions before they are defined. Valid characters for non-constant
+      symbols are any combination of alphanumeric characters, underscore.
+      Although “1234” is accepted as a symbol name, as is “o_o”, convention is
+      to use all uppercase words that are descriptive of the symbol's use so
+      they make sense when turned into CONFIG_NAME #defines.
+
+- Expressions - An expression is a logical evaluation. It can be as simple as
+  a static 'y' or 'n', or can be a symbol. Alternatively, expressions can be
+  complex evaluations of multiple symbols using the various logical operators.
+  The Kconfig language allows these logical evaluations in several places. The
+  most common use for complex expressions is following 'if' or ‘depends on’
+  keywords, but they can also be used to set the value for a prompt or default
+  values.
+
+- Types - Each Kconfig symbol is one of the following types: bool, hex, int,
+  string, or tristate. The tristate type is not used for coreboot, leaving just
+  four types. As noted in the keyword summaries, a symbol must have a consistent
+  type anywhere it is defined. Also, Kconfig will simply not display a symbol
+  that has no type defined. A warning will be displayed in the terminal where
+  menuconfig was run if this happens:
+  _src/Kconfig:25:warning: config symbol defined without type_.
+
+- Prompts - Input prompts are the text associated with the symbols which shown
+  to the user. The Kconfig language definition does not require surrounding the
+  prompt’s text with quotes, however it is recommended that quotes be used for
+  maximum compatibility.
+
+- Menu Entries - These keyword blocks create the symbols and questions that are
+  visible in the front end.
+
+
+## Keywords
+
+### bool
+
+The 'bool' keyword assigns a boolean type to a symbol. The allowable values for
+a boolean type are 'n' or 'y'. The keyword can be followed by an optional prompt
+string which makes the symbol editable in one of the configuration front ends.
+
+
+##### Usage:
+bool \[prompt\] \[if &lt;expr&gt;\]
+
+
+##### Example:
+    config ANY_TOOLCHAIN
+        bool "Allow building with any toolchain"
+        default n
+        depends on COMPILER_GCC
+
+
+##### Notes:
+- Putting the prompt after the 'bool' keyword is the same as using a 'prompt'
+  keyword later. See the 'prompt' keyword for more notes.
+- Only the first type definition for each symbol is valid. Further matching
+  definitions are fine, although unnecessary. Conflicting type definitions will
+  be ignored, and a warning will be presented on the console where the
+  configuration front end was run:
+  _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_.
+- Boolean symbols do not need a default and will default to ‘n’.
+
+
+##### Restrictions:
+
+- This keyword must be within a symbol definition block, started by the
+  'config' keyword.
+
+--------------------------------------------------------------------------------
+
+### choice
+
+This creates a selection list of one or more boolean symbols. For bools, only
+one of the symbols can be selected, and one will be be forced to be selected,
+either by a ‘default’ statement, or by selecting the first config option if
+there is no default value listed.
+
+##### Usage:
+choice \[symbol\]
+- \[prompt\]
+- \[default\]
+
+
+##### Example:
+    choice TESTCHOICE
+        prompt "Test choice"
+        default TESTCHOICE2 if TESTCHOICE_DEFAULT_2
+        default TESTCHOICE3
+
+    config TESTCHOICE1
+        bool "Choice 1"
+    config TESTCHOICE2
+        bool "Choice 2"
+    config TESTCHOICE3
+        bool "Choice 3"
+    config TESTCHOICE4
+        bool "Choice 4" if TESTCHOICE_SHOW_4
+    endchoice
+
+    config TESTCHOICE_DEFAULT_2
+        def_bool y
+
+    config TESTCHOICE_SHOW_4
+        def_bool n
+
+    config TESTSTRING
+        string
+        default “String #1” if TESTCHOICE1
+        default “String #2” if TESTCHOICE2
+        default “String #4” if TESTCHOICE3
+        default “String #4” if TESTCHOICE4
+        default “”
+
+
+##### Notes:
+- If no symbol is associated with a choice, then you can not have multiple
+  definitions of that choice. If a symbol is associated to the choice, then
+  you may define the same choice (ie. with the same entries) in another place.
+  Any selection in either location will update both choice menu selections. In
+  coreboot, the value of the symbol is always 1.
+- As shown in the example above, the choice between bools can be used to set
+  the default for a non-bool type.  This works best when the non-bool type
+  does not have an input prompt.
+
+
+##### Restrictions:
+- Symbols used for 'choice' entries must have input prompts defined using the
+  'prompt' keyword.
+- Symbols used in 'choice' entries may not be enabled with a 'select'
+  statement, they can be defaulted using a second Kconfig symbol however.
+
+--------------------------------------------------------------------------------
+
+### comment
+
+This keyword defines a line of text that is displayed to the user in the
+configuration frontend and is additionally written to the output files.
+
+
+##### Usage:
+comment &lt;prompt&gt;
+- \[depends on\]
+
+
+##### Example:
+
+    if CONSOLE_SERIAL
+        comment "I/O mapped, 8250-compatible"
+        depends on DRIVERS_UART_8250IO
+    endif
+
+
+##### Notes:
+- Comments are only valid outside of config blocks, but can be within menu and
+  if blocks.
+
+--------------------------------------------------------------------------------
+
+### config
+
+This is the keyword that starts a block defining a Kconfig symbol. The symbol
+modifiers follow the 'config' statement.
+
+##### Usage:
+config &lt;symbol&gt;
+
+-  \[bool | def_bool | int | hex | string\]
+- \[depends on\]
+- \[prompt\]
+- \[help\]
+- \[range\]
+- \[select\]
+
+
+##### Example:
+    config SEABIOS_PS2_TIMEOUT
+        prompt "PS/2 keyboard timeout" if PAYLOAD_SEABIOS
+        default 0
+        depends on PAYLOAD_SEABIOS
+        int
+        help
+          Some PS/2 keyboard controllers don't respond to commands
+          immediately after powering on. This specifies how long
+          SeaBIOS will wait for the keyboard controller to become
+          ready before giving up.
+
+
+##### Notes:
+- Non-coreboot projects also use the 'tristate' and 'def_tristate' types.
+- Ends at the next Kconfig keyword that is not valid inside the config block:
+
+    menu | endmenu | if | endif | choice | config | source | comment
+
+--------------------------------------------------------------------------------
+
+### default
+
+The ‘default’ keyword assigns a value to a symbol in the case where no preset
+value exists, i.e. the symbol is not present and assigned in .config.  If there
+is no preset value, and no ‘default’ keyword, the user will be asked to enter a
+valid value when building coreboot.
+
+
+##### Usage:
+default &lt;expr&gt; \[if &lt;expr&gt;\]
+
+
+##### Example:
+    config GENERATE_MP_TABLE
+        prompt "Generate an MP table" if HAVE_MP_TABLE || DRIVERS_GENERIC_IOAPIC
+        bool
+        default HAVE_MP_TABLE || DRIVERS_GENERIC_IOAPIC
+        help
+          Generate an MP table (conforming to the Intel
+          MultiProcessor specification 1.4) for this board.
+
+
+##### Notes:
+- Kconfig defaults for symbols without a prompt *NEVER* affect existing legal
+  symbol definitions in a .config file. The default only affects the symbol if
+  there is no valid definition in a config file.  This is a frequent source of
+  confusion.  It’s covered again in the Tips section below.
+- The first valid 'default' entry for a symbol is always used. Any further
+  'default' statements for a symbol are ignored.  This means that the order of
+  Kconfig files is very important as the earlier files get to set the defaults
+  first.  They should be sourced in the order from most specific (mainboard
+  Kconfig files) to the most generic (architecture-specific Kconfig files).
+- If there is no 'default' entry for a symbol, it gets set to 'n', 0, 0x0, or
+  “” depending on the type, however the 'bool' type is the only type that
+  should be left without a default value.
+
+--------------------------------------------------------------------------------
+
+### def_bool
+
+‘def_bool’ is similar to the 'bool' keyword in that it sets a symbol’s type to
+boolean. It lets you set the type and default value at the same time, instead
+of setting the type and the prompt at the same time. It's typically used for
+symbols that don't have prompts.
+
+
+##### Usage:
+def_bool &lt;expr&gt; \[if &lt;expr&gt;\]
+
+
+##### Example:
+    config EC_GOOGLE_CHROMEEC_LPC
+        depends on EC_GOOGLE_CHROMEEC && ARCH_X86
+        def_bool y
+        select SERIRQ_CONTINUOUS_MODE
+        help
+          Google Chrome EC via LPC bus.
+
+
+##### Notes:
+- Only the first type definition for each symbol is valid. Further matching
+  definitions are fine, although unnecessary. Conflicting type definitions will
+  be ignored, and a warning will be presented on the console where the
+  configuration front end was run:
+  _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_.
+
+##### Restrictions:
+- This keyword must be within a symbol definition block, started by the
+  'config' keyword.
+
+--------------------------------------------------------------------------------
+
+### depends on
+
+This defines a dependency for a menu entry, including symbols and comments.  It
+behaves the same as surrounding the menu entry with an if/endif block.  If the
+‘depends on’ expression evaluates to false, the 'prompt' value will not be
+printed, and defaults will not be set based on this block.
+
+
+##### Usage:
+depends on &lt;expr&gt;
+
+
+##### Example:
+    config COMMON_CBFS_SPI_WRAPPER
+        bool
+        default n
+        depends on SPI_FLASH
+        depends on !ARCH_X86
+        help
+          Use common wrapper to interface CBFS to SPI bootrom.
+
+
+##### Notes:
+- Symbols that have multiple ‘depends on’ sections as above are equivalent to a
+  single ‘depends on’ statement with sections joined by &&.  So the above is
+  the same as “depends on SPI_FLASH && ! ARCH_X86”.
+
+--------------------------------------------------------------------------------
+
+### endchoice
+
+This ends a choice block. See the 'choice' keyword for more information and an
+example.
+
+--------------------------------------------------------------------------------
+
+### endif
+
+This ends a block started by the 'if' keyword. See the 'if' keyword for more
+information and an example.
+
+--------------------------------------------------------------------------------
+
+### endmenu
+
+This ends a menu block. See the 'menu' keyword for more information and an
+example.
+
+--------------------------------------------------------------------------------
+
+### help
+
+The 'help' keyword defines the subsequent block of text as help for a config or
+choice block. The help block is started by the 'help' keyword on a line by
+itself, and the indentation level of the next line controls the end of the help
+block. The help ends on the next non-blank line that has an indentation level
+less than the indentation level of the first line following the 'help' keyword.
+
+##### Usage:
+help &lt;help text&gt;
+
+
+##### Example:
+    config COMPILER_GCC
+        bool "GCC"
+        help
+          Use the GNU Compiler Collection (GCC) to build coreboot.  For details
+          see http://gcc.gnu.org.
+
+
+##### Notes:
+- Identical to the '---help---' keyword which isn’t used in coreboot.
+- Other keywords are allowed inside the help block, and are not recognized as
+  keywords so long as the indentation rules are followed, even if they start a
+  line.
+
+
+##### Restrictions:
+- Only used for 'config' and 'choice' keywords.
+
+--------------------------------------------------------------------------------
+
+### hex
+
+This is another symbol type specifier, specifying an unsigned integer value
+formatted as hexadecimal.
+
+##### Usage:
+hex &lt;expr&gt; \[if &lt;expr&gt;\]
+
+
+##### Example:
+    config INTEL_PCH_UART_CONSOLE_NUMBER
+        hex "Serial IO UART number to use for console"
+        default 0x0
+        depends on INTEL_PCH_UART_CONSOLE
+
+
+##### Notes:
+- Kconfig doesn’t complain if you don’t start the default value for a hex
+  symbol with ‘0x’, but not doing so will lead to issues.  It will update 10
+  to 0x10 without warning the user.
+- Putting the prompt text after the 'hex' keyword is the same as using a
+  'prompt' keyword later. See the 'prompt' keyword for more notes.
+- Only the first type definition for each symbol is valid. Further matching
+  definitions are fine, although unnecessary. Conflicting type definitions will
+  be ignored, and a warning will be presented on the console where the
+  configuration front end was run:
+  _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_.
+
+
+##### Restrictions:
+- This keyword must be within a symbol definition block, started by the
+  'config' keyword.
+- 'hex' type symbols must have a 'default' entry set.
+
+--------------------------------------------------------------------------------
+
+### if
+
+The 'if' keyword is overloaded, used in two different ways. The first definition
+enables and disables various other keywords, and follows the other keyword
+definition. This usage is shown in each of the other keywords' usage listings.
+
+The second usage of the 'if' keyword is part of an if/endif block. Most items
+within an if/endif block are not evaluated, while others, such as the 'source'
+keyword, ignore the existence of the if/endif block completely. Symbols defined
+within an if/endif block are still created, although their default values are
+ignored - all values are set to 'n'.
+
+
+##### Usage:
+if &lt;expr&gt;
+
+- \[config\]
+- \[choice\]
+- \[comment\]
+- \[menu\]
+
+endif
+
+
+##### Example:
+    if ARCH_X86
+
+    config SMP
+        bool
+        default y if MAX_CPUS != 1
+        default n
+        help
+          This option is used to enable certain functions to make
+          coreboot work correctly on symmetric multi processor (SMP) systems.
+    endif
+
+##### Restrictions:
+- Corresponding ‘if’ and ‘endif’ statements must exist in the same file.
+
+--------------------------------------------------------------------------------
+
+### int
+
+A type setting keyword, defines a symbol as an integer, accepting only signed
+numeric values.  The values can be further restricted with the ‘range’ keyword.
+
+
+##### Usage:
+int &lt;expr&gt; \[if &lt;expr&gt;\]
+
+
+##### Example:
+    config PRE_GRAPHICS_DELAY
+        int "Graphics initialization delay in ms"
+        default 0
+        help
+          On some systems, coreboot boots so fast that connected
+          monitors (mostly TVs) won't be able to wake up fast enough
+          to talk to the VBIOS. On those systems we need to wait for a
+          bit before executing the VBIOS.
+
+
+##### Notes:
+- Only the first type definition for each symbol is valid. Further matching
+  definitions are fine, although unnecessary. Conflicting type definitions will
+  be ignored, and a warning will be presented on the console where the
+  configuration front end was run:
+  _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_.
+
+
+##### Restrictions:
+- This keyword must be within a symbol definition block, started by the 'config'
+  keyword.
+- 'int' type symbols must have a default value set.
+
+--------------------------------------------------------------------------------
+
+### mainmenu
+
+The 'mainmenu' keyword sets the title or title bar of the configuration front
+  end, depending on how the configuration program decides to use it. It can only
+  be specified once and at the very beginning of the top level Kconfig file,
+  before any other statements.
+
+
+##### Usage:
+mainmenu &lt;prompt&gt;
+
+##### Example:
+mainmenu "coreboot configuration"
+
+##### Restrictions:
+- Must be the first statement in the top level Kconfig.
+- Must only be used once in the entire Kconfig tree.
+
+--------------------------------------------------------------------------------
+
+### menu
+
+The 'menu' and 'endmenu' keywords tell the configuration front end that the
+enclosed statements are part of a group of related pieces.
+
+
+##### Usage:
+menu &lt;prompt&gt;
+
+- \[choice\]
+- \[config\]
+- \[menu\]
+- \[if/endif\]
+
+endmenu
+
+
+##### Example:
+    menu "On-Chip Device Power Down Control"
+    config TEMP_POWERDOWN
+        bool "Temperature sensor power-down"
+
+    config SATA_POWERDOWN
+        bool "SATA power-down"
+
+    config ADC_POWERDOWN
+        bool "ADC power-down"
+
+    config PCIE0_POWERDOWN
+        bool "PCIE0 power-down"
+
+    config MAC_POWERDOWN
+        bool "MAC power-down"
+
+    config USB1_POWERDOWN
+        bool "USB2.0 Host Controller 1 power-down"
+
+    config IDE_POWERDOWN
+        bool "IDE power-down"
+
+    endmenu
+
+##### Restrictions:
+- Must be closed by a corresponding ‘endmenu’ keyword in the same file.
+
+--------------------------------------------------------------------------------
+
+### prompt
+
+The 'prompt' keyword sets the text displayed for a config symbol or choice in
+configuration front end.
+
+
+##### Usage:
+prompt &lt;prompt&gt; \[if &lt;expr&gt;\]
+
+
+##### Example:
+    config REALMODE_DEBUG
+        prompt "Enable debug messages for option ROM execution"
+        bool
+        default n
+        depends on PCI_OPTION_ROM_RUN_REALMODE
+        depends on DEFAULT_CONSOLE_LOGLEVEL_7 || DEFAULT_CONSOLE_LOGLEVEL_8
+        help
+          This option enables additional x86emu related debug
+          messages.  Note: This option will increase the time to emulate a ROM.
+
+          If unsure, say N.
+
+
+##### Notes:
+- The same rules apply for menu entries defined by the 'prompt' keyword and
+  other prompt types such as those defined by the 'int' or 'string' keywords.
+- Redefining the prompt text in multiple instances of config symbols is allowed.
+  Only the current prompt statement for a particular entry will be displayed by
+  the front end in any given location.  This means that multiple mainboards can
+  set different prompt values for a symbol, and it would appear differently in
+  each mainboard’s menu.  The symbol can even have multiple entries in the same
+  menu with different prompts if desired. For example, both of these would get
+  printed, and changing either entry would change the other.
+
+        config PROMPT_TEST
+            string "Prompt value 1"
+
+        config PROMPT_TEST
+            prompt "Prompt value 2"
+
+- Although not required, it's recommended that you use quotes around prompt
+  statements.
+* If the prompt is redefined inside the SAME config entry, you will get a
+  warning:
+  _warning: prompt redefined_.
+  For example, this is not allowed:
+
+        config PROMPT_TEST
+            string "Prompt value 1"
+            prompt "Prompt value 2"
+--------------------------------------------------------------------------------
+
+### range
+
+This sets the allowable minimum and maximum entries for hex or int type config
+symbols.
+
+
+##### Usage:
+range &lt;symbol&gt; &lt;symbol&gt; \[if &lt;expr&gt;\]
+
+
+##### Example:
+    config TEST1
+        hex "test 1"
+        range 0x0 0x10
+
+
+##### Notes:
+- Only the first definition of a range is used for any symbol. Further
+  definitions will be ignored without warning.
+
+--------------------------------------------------------------------------------
+
+### select
+
+The ‘select’ keyword is used within a bool type config block.  In coreboot (and
+other projects that don't use modules), the 'select' keyword can force an
+unassociated bool type symbol to 'y'.  When the symbol for the config block is
+‘y’, the ‘select’ action is taken.  Otherwise the bool is unaffected.
+
+
+##### Usage:
+select &lt;symbol&gt; \[if &lt;expr&gt;\]
+
+
+##### Example:
+    config TPM
+        bool
+        default n
+        select LPC_TPM if ARCH_X86
+        select I2C_TPM if ARCH_ARM
+        select I2C_TPM if ARCH_ARM64
+        help
+          Enable this option to enable TPM support in coreboot.
+          If unsure, say N.
+
+##### Notes:
+- Using the 'select' keyword can create logical contradictions in Kconfig, which
+  will create warnings and fail to save the .config.  Following is an example of
+  an obviously invalid configuration, where selecting BOOLTEST violates the
+  ‘depends on’ of BOOLTEST2:
+
+        config BOOLTEST
+            bool "bool Test"
+            select BOOLTEST2
+
+        config BOOLTEST2
+            bool "Bool Test 2"
+            depends on !BOOLTEST
+
+##### Restrictions:
+- The ‘select’ keyword only works on bool type symbols.
+- Symbols created inside of choice blocks cannot be selected, and should be
+  enabled by using default values instead.
+
+--------------------------------------------------------------------------------
+
+### source
+
+The 'source' keyword functions much the same as an 'include' statement in c.
+This pulls one or more files into Kconfig at the location of the 'source'
+command. This statement is always parsed - there is no way to conditionally
+source a file. coreboot has modified the source statement slightly to handle
+directory globbing. The '*' character will match with any directory.
+
+
+##### Usage:
+source &lt;prompt&gt;
+
+
+##### Example:
+
+    choice
+        prompt "Mainboard vendor"
+        default VENDOR_EMULATION
+
+        source "src/mainboard/*/Kconfig.name"
+
+    endchoice
+
+    source "src/mainboard/*/Kconfig"
+
+
+##### Notes:
+- As with all prompt values, the 'source' prompt may be enclosed in single or
+  double quotes, or left without any quotes.  Using quotes is highly recommended
+  however.
+- The 'source' keyword loads files relative to the working directory where the
+  Kconfig command was run. For coreboot, this is the root coreboot directory, so
+  all source commands in the src directory need to start with ‘src/’.
+- In coreboot's Kconfig, if a sourced file does not exist, the statement is
+  simply ignored. This is different than other versions of Kconfig.
+- 'source' pulls a file into the Kconfig tree at the location of the keyword.
+  This allows for files containing small bits of the Kconfig tree to be pulled
+  into a larger construct.  A restriction on this is that the starting/ending
+  keyword pairs must be within the same file - ‘endif’ cannot appear in a
+  different file than the ‘if’ statement that it ends. The same is true of
+  menu/endmenu and choice/endchoice pairs.
+
+The coreboot Kconfig structure uses this along with globbing to build up the
+mainboard directory.  Each mainboard’s Kconfig.name file contains just two
+statements that generate a list of all the platform names:
+
+    config BOARD_AMD_NORWICH
+         bool "Norwich"
+
+
+##### Restrictions:
+- 'source' keywords always load in the specified file or files. There is no way
+  to optionally pull in a file. Putting an if/endif block around a source
+  command does not affect the source command, although it does affect the
+  content.  To avoid confusion, use if/endif blocks inside sourced files to
+  remove their content if necessary.
+
+--------------------------------------------------------------------------------
+
+### string
+
+The last of the symbol type assignment keywords. 'string' allows a text value to
+be entered.
+
+
+##### Usage:
+string &lt;expr&gt; \[if &lt;expr&gt;\]
+
+
+##### Example:
+    config BOOTBLOCK_SOUTHBRIDGE_INIT
+        string
+        default "southbridge/amd/pi/hudson/bootblock.c"
+
+    config HUDSON_GEC_FWM_FILE
+        string "GEC firmware path and filename"
+        depends on HUDSON_GEC_FWM
+
+
+##### Notes:
+- Putting the prompt after the 'string' keyword is the same as using a 'prompt'
+keyword later. See the prompt keyword for more notes.
+- Only the first type definition for each symbol is valid. Further matching
+  definitions are fine, although unnecessary. Conflicting type definitions will
+  be ignored, and a warning will be presented on the console where the
+  configuration front end was run:
+  _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'string'_.
+- Some characters may not get interpreted correctly when inside a string entry
+  depending on how they are used - inside a C file, inside a Makefile, passed
+  through a Makefile to a C file, or something else.  It may be necessary to
+  escape the characters at times.  Because this is very dependent upon how the
+  symbol is actually used, a definitive guide cannot be given here.
+- 'string' type variables do NOT need a default, and will default to the
+  value “”.
+
+
+##### Restrictions:
+- This keyword must be within a symbol definition block, started by the 'config'
+  keyword.
+
+--------------------------------------------------------------------------------
+
+
+
+
+## Keywords not used in coreboot at the time of writing:
+
+- allnoconfig_y:
+- defconfig_list
+- def_tristate
+- env
+- ---help---
+- menuconfig
+- modules
+- optional
+- option
+- tristate
+- visible if
+
+
+## Build files generated by Kconfig
+
+### build/config.h
+
+The config.h file is a very basic header file made up of a list of #define
+statements:
+
+    #define SYMBOL NAME XXX
+
+
+##### Symbol types:
+- bool, int, and hex types -  Every symbol of one of these types created in the
+  Kconfig tree is defined.  It doesn’t matter whether they’re in an if/endif
+  block, or have a ‘depends on’ statement - they ALL end up being defined in
+  this file.
+- String - Only string types that actually have a value associated with them
+  are defined.
+
+The config.h file uses 0 and 1 to represent Kconfig's 'n' and 'y' values
+respectively. String values are placed inside double quotes.
+
+The name of the file is controlled by the $KCONFIG_AUTOHEADER environment
+variable, which is set to $(obj)/config.h by the coreboot makefiles.
+
+The prefix used for the symbols is controlled by the $CONFIG_ environment
+variable.  This is not set in coreboot, which uses the default CONFIG_ prefix
+for all of its symbols.
+
+The coreboot makefile forces the config.h file to be included into all coreboot
+C files. This is done in Makefile.inc on the compiler command line using the
+“-include $(obj)/config.h” command line option.
+
+Example of various symbol types in the config.h file:
+
+    #define CONFIG_BOOTBLOCK_SOURCE "bootblock_simple.c" # String
+    #define CONFIG_CBFS_SIZE 0x00300000                  # Hex
+    #define CONFIG_TTYS0_BAUD 115200                     # Int
+    #define CONFIG_HAVE_ACPI_TABLES 1                    # Bool enabled
+    #define CONFIG_EXPERT 0                              # Bool disabled
+    #define CONFIG_NORTHBRIDGE_INTEL_I440LX 0            # Bool excluded
+
+
+### .config
+
+The .config file in the root directory is used as the input file, but also by
+the makefiles to set variable values. The main difference is that it does not
+contain all of the symbols. It excludes symbols defined in an if/endif block
+whose expression evaluated as false. Note that the symbol
+CONFIG_NORTHBRIDGE_INTEL_I440LX shown in the config.h example above is not
+present in the .config file.
+
+In addition, the .config file below contains the 'comment' prompt text from the
+Kconfig, separating the blocks.
+
+    ## General setup ##
+    CONFIG_BOOTBLOCK_SOURCE="bootblock_simple.c" # String
+    CONFIG_CBFS_SIZE=0x00300000                  # Hex
+    CONFIG_TTYS0_BAUD=115200                     # Int
+    CONFIG_HAVE_ACPI_TABLES=y                    # Bool enabled
+    # CONFIG_EXPERT is not set                   # Bool disabled
+
+This file is included directly by the makefile, and sets the CONFIG symbols so
+that they are available during the build process.
+
+
+### build/auto.conf
+
+Although the controlling variable for the auto.conf filename,
+KCONFIG_AUTOCONFIG, is set in the coreboot makefiles, the auto.conf file itself
+is not used by coreboot.  This file has the same syntax and structure as the
+.config file, but contains all symbols in the Kconfig tree, including those that
+are not enabled, or are excluded by if/endif blocks, or the 'depends on'
+keyword.  The kconfig tool could be updated to not generate this file, but since
+it's not hurting anything, it's still being generated.
+
+
+
+## Defconfig or Miniconfig files
+
+Miniconfig files are the standard .config files with all of the symbols which
+are set to their default values stripped out.  These files are very useful for
+debugging your config, as well as being the best way to store your .config file.
+If you store your config as a full config file, it will be much harder to
+maintain.  Any Kconfig symbols with updated default values will retain their old
+values,  and any symbols which have been removed will still remain in the file.
+Storing full config files just generally leads to a lot more maintenance than
+storing miniconfig files.
+
+The easiest way to generate the miniconfig file is by running
+
+    make savedefconfig DOTCONFIG=.config DEFCONFIG=[output file]
+
+DEFCONFIG defaults to ‘defconfig’, DOTCONFIG defaults to ‘.config’.
+
+
+To turn the miniconfig back into a full config file, use one of the two targets:
+
+    make olddefconfig DOTCONFIG=[input/output file]
+
+or
+
+    make defconfig KBUILD_DEFCONFIG=[input file] DOTCONFIG=[output file]
+
+In both of these cases, DOTCONFIG defaults to .config.
+
+
+
+## Editing and updating saved .config files
+
+
+### Don’t save full config files
+
+Save miniconfig files, as mentioned in the previous section.
+
+
+### Disable values with ‘# CONFIG_SYMBOL is not set’
+
+A common mistake when trying to disable a value is to edit the .config file and
+change it from ‘CONFIG_SYMBOL=y’ to ‘CONFIG_SYMBOL=n’, but this doesn’t
+correctly disable the symbol.  If the default value for the symbol is ‘n’ to
+begin with, this isn’t an issue - the symbol just gets ignored, and the default
+value is used.  The problem is where the default for the symbol is ‘y’.  When
+the bad entry in the .config file gets ignored, the value is set back to ‘y’,
+leading to much frustration.
+
+Always disable the Kconfig symbols in the .config file with the syntax:
+
+    # CONFIG_SYMBOL is not set
+
+### Only the LAST instance of a symbol is used
+
+When reading a saved .config file, Kconfig uses the LAST instance of a symbol
+that it comes across, and ignores any previous instances. This can be used to
+override symbols in a saved .config file by appending the new value to a config
+file.
+
+For example:
+
+A .config file that contains these two lines:
+
+    # CONFIG_BOOLTEST is not set
+    CONFIG_BOOLTEST=y
+
+After running ‘make olddefconfig’, ends up with the value:
+
+    CONFIG_BOOLTEST=y
+
+A case where this can be used is by a making a script to create two versions of
+a coreboot rom for a single platform. The first ROM could be built with serial
+console disabled, and the second ROM, built as a debug version, could have
+serial console enabled by overriding the "CONFIG_CONSOLE_SERIAL" symbol, and
+setting it to enabled.
+
+## General Kconfig Tips and Notes
+
+### Default values for config options
+
+The FIRST valid default that the Kconfig parser comes across will be used for
+each symbol. This means that the organization of the tree is very important.
+The structure should go from most specific at the top of the Kconfig tree to the
+most general later in the tree.  In coreboot, the mainboard directories get
+loaded first, as they are sourced very early in the src/Kconfig file.  Chipset
+Kconfig files get sourced later, and the architecture specific Kconfig files get
+sourced even later.  This allows the mainboards to set their defaults early,
+overriding the default values set in chipset or architecture.
+
+Due to this mechanism, a default defined early cannot be changed by a default
+set in a later Kconfig file. There are ways around this, involving 'depends on'
+statements, but they add additional variables which are generally just used
+internal to Kconfig.
+
+
+### Select statement usage
+
+The 'select' keyword forces the value of a symbol with a bool type to 'y'. It
+overrides any dependencies of the symbol, so using it carelessly can lead to
+unpredictable results.
+
+
+
+### All bool, int, and hex Kconfig symbols are ALWAYS defined in the C code
+
+All bool, int, and hex Kconfig symbols are ALWAYS defined in the C code if they
+are in a sourced Kconfig - do NOT use #ifdef CONFIG_SYMBOL
+
+String symbols are the exception.  All others (int, hex, etc.) are always
+defined in config.h.  Never use an #ifdef statement for a Kconfig symbol other
+than strings in C to determine whether the symbol is enabled or disabled. So
+long as the symbol is in ANY sourced Kconfig file, it will be defined. Even if
+the symbol is only inside of an if/endif block where the if expression evaluates
+as false, the symbol STILL gets defined in the config.h file (though not in the
+.config file).
+
+Use \#if IS_ENABLED(CONFIG_*) to be sure (it returns false for undefined symbols
+and defined-to-0 symbols alike).
+
+
+
+### Symbols with prompts use defaults *ONLY* when initially created or enabled.
+
+Symbols with a prompt which may be user-modified are NOT updated to default
+values when changing between platforms or modifying other symbols. There are
+only two times the default values are used:
+1. When a config is initially created.
+2. When a dependency which had previously kept the symbol from being active
+   changes to allowing it to be active.
+
+Because of this, starting with a saved .config for one platform and updating it
+for another platform can lead to very different results than creating a platform
+from scratch.
+
+
+
+### Symbols with no prompt will be the default value (unless 'select' is used).
+
+Symbols that do not have a prompt will always use the first valid default value
+specified in Kconfig. They cannot be updated, even if they are modified in a
+saved .config file. As always, a 'select' statement overrides any specified
+'default' or 'depends on' statement.
+
+
+## Differences between coreboot's Kconfig and other Kconfig implementations.
+
+- coreboot has added the glob operator '*' for the 'source' keyword.
+- coreboot’s Kconfig always defines variables except for strings. In other
+  Kconfig implementations, bools set to false/0/no are not defined.
+- IS_ENABLED() is ‘false’ for undefined variables and ‘0’ variables. In Linux
+  (where the macro comes from) it’s ‘true’ as soon as the variable is defined.
+- coreboot’s version of Kconfig adds the KCONFIG_STRICT environment variable to
+  error out if there are any issues in the Kconfig files.  In the Linux kernel,
+  Kconfig will generate a warning, but will still output an updated .config or
+  config.h file.
+
+
+## Kconfig Editor Highlighting
+
+#### vim:
+
+vim has syntax highlighting for Kconfig built in (or at least as a part of
+vim-common), but most editors do not.
+
+
+#### ultraedit:
+
+https://github.com/martinlroth/wordfiles/blob/master/kconfig.uew
+
+
+
+#### atom:
+
+https://github.com/martinlroth/language-kconfig
+
+
+## Syntax Checking:
+
+The Kconfig utility does some basic syntax checking on the Kconfig tree.
+Running "make silentoldconfig" will show any errors that the Kconfig utility
+sees.
+
+### util/kconfig_lint
+
+Because the Kconfig utility is relatively forgiving, and ignores issues that a
+developer might be interested in, kconfig_lint, another Kconfig checker has been
+written.
+
+The file kconfig_lint and its associated readme can be found in the coreboot
+utils/lint directory.  It is useful for parsing the Kconfig tree, and for
+showing warnings, errors, and notes about coreboot’s Kconfig files.
+
+
+    kconfig_lint <options>
+       -o|--output=file         Set output filename
+       -p|--print               Print full output
+       -e|--errors_off          Don't print warnings or errors
+       -w|--warnings_off        Don't print warnings
+       -n|--notes               Show minor notes
+       --path=dir               Path to top level kconfig
+       -c|--config=file         Filename of config file to load
+       -G|--no_git_grep         Use standard grep tools instead of git grep
+
+
+The -p option is very useful for debugging Kconfig issues, because it reads all
+of the Kconfig files in the order that the Kconfig tools would read them, and
+prints it out, along with where each line came from and which menu it appears
+in.
+
+## License:
+This work is licensed under the Creative Commons Attribution 4.0 International
+License. To view a copy of this license, visit
+https://creativecommons.org/licenses/by/4.0/ or send a letter to Creative
+Commons, PO Box 1866, Mountain View, CA 94042, USA.
+
+Code examples snippets are licensed under GPLv2, and are used here under fair
+use laws.
diff --git a/Documentation/getting_started/submodules.md b/Documentation/getting_started/submodules.md
new file mode 100644
index 0000000000..631e351303
--- /dev/null
+++ b/Documentation/getting_started/submodules.md
@@ -0,0 +1,46 @@
+Use of git submodules in coreboot
+=================================
+coreboot uses git submodules to keep certain parts of the tree separate,
+with two major use cases:
+
+First, we use a vendor tool by NVIDIA for systems based on their SoC
+and since they publish it through git, we can just import it into our
+tree using submodules.
+
+Second, lots of boards these days require binaries and we want to keep
+them separate from coreboot proper to clearly delineate shiny Open Source
+from ugly blobs.
+Since we don't want to impose blobs on users who really don't need them,
+that repository is only downloaded and checked out on explicit request.
+
+Handling submodules
+-------------------
+For the most part, submodules should be automatically checked out on the
+first execution of the coreboot Makefile.
+
+To manually fetch all repositories (eg. when you want to prepare the tree
+for archiving, or to use it without network access), run
+
+    $ git submodule update --init --checkout
+
+This also checks out the binaries below `3rdparty/`
+
+Mirroring coreboot
+------------------
+When running a coreboot mirror to checkout from, for full operation, you
+should also mirror the blobs and nvidia-cbootimage repository, and place
+them in the same directory as the coreboot repository mirror.
+
+That is, when residing in coreboot's repository, `cd ../blobs.git`
+should move you to the blobs repository.
+
+With that, no matter what the URL of your coreboot repository is, the
+git client (of a sufficiently new version) is able to pick up the other
+repositories transparently.
+
+Minimum requirements
+--------------------
+git needs to be able to handle relative paths to submodule repositories,
+and it needs to know about non-automatic submodules.
+
+For these features, we require git version 1.7.6.1 or newer.