summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPatrick Georgi <pgeorgi@google.com>2021-03-16 21:45:25 +0100
committerPatrick Georgi <pgeorgi@google.com>2021-03-17 23:07:07 +0000
commita763e8f92b9faeb70f63304f974551479ac3859b (patch)
tree116b9cff55c750f53e76e7a7f5c89b2885defc30
parenta9b44f4c79078210fe9966daf2412cc222c2d0a9 (diff)
downloadcoreboot-a763e8f92b9faeb70f63304f974551479ac3859b.tar.xz
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>
-rw-r--r--Documentation/tutorial/index.md1
-rw-r--r--Documentation/tutorial/managing_local_additions.md43
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.