summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-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 b8fb82737d8b..8b3d88aaba45 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 000000000000..6ca5971164ad
--- /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.