Documentation: Describe the site-local hook in our config/build system

Change-Id: Ia682b784540fa82e1f216f76d87d59a4f0b94486
Signed-off-by: Patrick Georgi <pgeorgi@google.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/51546
Reviewed-by: Furquan Shaikh <furquan@google.com>
Reviewed-by: Tim Wawrzynczak <twawrzynczak@chromium.org>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>

2 files changed, 44 insertions, 0 deletions

diff --git a/Documentation/tutorial/index.md b/Documentation/tutorial/index.md
index b8fb82737d..8b3d88aaba 100644
--- a/Documentation/tutorial/index.md
+++ b/Documentation/tutorial/index.md
@@ -3,3 +3,4 @@
 * [Part 1: Starting from scratch](part1.md)
 * [Part 2: Submitting a patch to coreboot.org](part2.md)
 * [Part 3: Writing unit tests](part3.md)
+* [Managing local additions](managing_local_additions.md)
diff --git a/Documentation/tutorial/managing_local_additions.md b/Documentation/tutorial/managing_local_additions.md
new file mode 100644
index 0000000000..6ca5971164
--- /dev/null
+++ b/Documentation/tutorial/managing_local_additions.md
@@ -0,0 +1,43 @@
+Managing local additions
+========================
+
+This section describes the site-local mechanism, what it is good for and
+how it can be used.
+
+What is site-local?
+-------------------
+site-local is the name of a directory that won't ever appear in the
+upstream coreboot repository but is referred to in several key places of its
+configuration and build system. The intent is provide a single location to
+store local modifications.
+
+By keeping local additions to builds in this place, it can be versioned
+independently from upstream (e.g. controlled by git in another repository)
+and any changes made there won't ever conflict with upstream changes.
+
+This optional directory is searched for in the top-level of the coreboot
+repo and is called `site-local`.
+
+Integration into the configuration system
+-----------------------------------------
+Kconfig includes `site-local/Kconfig` relatively early, so it can be used
+to pre-define some configuration before coreboot's regular ruleset sets
+up defaults.
+
+Integration into the build system
+---------------------------------
+The build system includes, if present, `site-local/Makefile.inc`. The main
+purpose so far has been to add additional files to a CBFS image. A single
+Makefile.inc can serve multiple boards, for example:
+
+    cbfs-files-$(CONFIG_BOARD_INTEL_D945GCLF) += pci8086,2772.rom
+    pci8086,2772.rom-file := intel_d945gclf/pci8086,2772.rom
+    pci8086,2772.rom-type := optionrom
+
+    cbfs-files-$(CONFIG_BOARD_KONTRON_986LCD_M) += pci8086,27a2.rom
+    pci8086,27a2.rom-file := kontron_986lcd-m/pci8086,27a2.rom
+    pci8086,27a2.rom-type := optionrom
+
+This adds the correct Option ROM binary (which are non-redistributable and
+therefore can't become part of the coreboot.org repos) to coreboot.rom when
+built for intel/d945gclf or kontron/986lcd-m.