summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorMathew King <mathewk@chromium.org>2019-08-08 14:59:25 -0600
committerPatrick Georgi <pgeorgi@google.com>2019-10-03 15:28:15 +0000
commitc7ddc999fc076bf6871e3b5e641c07f17b0b1746 (patch)
treea7dfb7aec7bade6ddf74f23d1f1f6bdb26f62ccd /Documentation
parent006eb9d8c8550ce0e8d01d37cceb88e7c1e12a5e (diff)
downloadcoreboot-c7ddc999fc076bf6871e3b5e641c07f17b0b1746.tar.xz
ifdtool: Add validate option to ifdtool
Add an option to ifdtool which validates that the flash regions defined in the descriptor match the coresponding areas in the FMAP. BUG=chromium:992215 TEST=Ran 'ifdtool -t' with a good bios image and verify no issues run 'ifdtool -t' with a bad bios image and verify expected issues Signed-off-by: Mathew King <mathewk@chromium.org> Change-Id: Idebf105dee1b8f829d54bd65c82867af7aa4aded Reviewed-on: https://review.coreboot.org/c/coreboot/+/34802 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/ifdtool/binary_extraction.md (renamed from Documentation/Binary_Extraction.md)0
-rw-r--r--Documentation/ifdtool/index.md5
-rw-r--r--Documentation/ifdtool/layout.md66
-rw-r--r--Documentation/index.md1
-rw-r--r--Documentation/util.md2
5 files changed, 72 insertions, 2 deletions
diff --git a/Documentation/Binary_Extraction.md b/Documentation/ifdtool/binary_extraction.md
index fe8c25ca4e..fe8c25ca4e 100644
--- a/Documentation/Binary_Extraction.md
+++ b/Documentation/ifdtool/binary_extraction.md
diff --git a/Documentation/ifdtool/index.md b/Documentation/ifdtool/index.md
new file mode 100644
index 0000000000..e6e6057a74
--- /dev/null
+++ b/Documentation/ifdtool/index.md
@@ -0,0 +1,5 @@
+
+Contents:
+
+* [Intel IFD Binary Extraction](binary_extraction.md)
+* [IFD Layout](layout.md) \ No newline at end of file
diff --git a/Documentation/ifdtool/layout.md b/Documentation/ifdtool/layout.md
new file mode 100644
index 0000000000..950db6f7ff
--- /dev/null
+++ b/Documentation/ifdtool/layout.md
@@ -0,0 +1,66 @@
+# IFD Layout
+
+A coreboot image for an Intel SoC contains two separate definitions of the
+layout of the flash. The Intel Flash Descriptor (IFD) which defines offsets and
+sizes of various regions of flash and the [coreboot FMAP](../lib/flashmap.md).
+
+The FMAP should define all of the of the regions defined by the IFD to ensure
+that those regions are accounted for by coreboot and will not be accidentally
+modified.
+
+## IFD mapping
+
+The names of the IFD regions in the FMAP should follow the convention of
+starting with the prefix `SI_` which stands for `silicon initialization` as a
+way to categorize anything required by the SoC but not provided by coreboot.
+
+|IFD Region index|IFD Region name|FMAP Name|Notes|
+|---|---|---|---|
+|0|Flash Descriptor|SI_DESC|Always the top 4KB of flash|
+|1|BIOS|SI_BIOS|This is the region that contains coreboot|
+|2|Intel ME|SI_ME||
+|3|Gigabit Ethernet|SI_GBE||
+|4|Platform Data|SI_PDR||
+|8|EC Firmware|SI_EC|Most Chrome OS devices do not use this region; EC firmware is stored BIOS region of flash|
+
+## Validation
+
+The ifdtool can be used to manipulate a firmware image with a IFD. This tool
+will not take into account the FMAP while modifying the image which can lead to
+unexpected and hard to debug issues with the firmware image. For example if the
+ME region is defined at 6 MB in the IFD but the FMAP only allocates 4 MB for the
+ME, then when the ME is added by the ifdtool 6 MB will be written which could
+overwrite 2 MB of the BIOS.
+
+In order to validate that the FMAP and the IFD are compatible the ifdtool
+provides --validate (-t) option. `ifdtool -t` will read both the IFD and the
+FMAP in the image and for every non empty region in the IFD if that region is
+defined in the FMAP but the offset or size is different then the tool will
+return an error.
+
+Example:
+
+```console
+foo@bar:~$ ifdtool -t bad_image.bin
+Region mismatch between bios and SI_BIOS
+ Descriptor region bios:
+ offset: 0x00400000
+ length: 0x01c00000
+ FMAP area SI_BIOS:
+ offset: 0x00800000
+ length: 0x01800000
+Region mismatch between me and SI_ME
+ Descriptor region me:
+ offset: 0x00103000
+ length: 0x002f9000
+ FMAP area SI_ME:
+ offset: 0x00103000
+ length: 0x006f9000
+Region mismatch between pd and SI_PDR
+ Descriptor region pd:
+ offset: 0x003fc000
+ length: 0x00004000
+ FMAP area SI_PDR:
+ offset: 0x007fc000
+ length: 0x00004000
+``` \ No newline at end of file
diff --git a/Documentation/index.md b/Documentation/index.md
index b880c1c4d5..39c8d11f9a 100644
--- a/Documentation/index.md
+++ b/Documentation/index.md
@@ -169,7 +169,6 @@ Contents:
* [coreboot at conferences](community/conferences.md)
* [Payloads](payloads.md)
* [Distributions](distributions.md)
-* [Intel IFD Binary Extraction](Binary_Extraction.md)
* [Dealing with Untrusted Input in SMM](technotes/2017-02-dealing-with-untrusted-input-in-smm.md)
* [GPIO toggling in ACPI AML](acpi/gpio.md)
* [Adding devices to a device tree](acpi/devicetree.md)
diff --git a/Documentation/util.md b/Documentation/util.md
index f8fabc1ec3..3a09b00101 100644
--- a/Documentation/util.md
+++ b/Documentation/util.md
@@ -47,7 +47,7 @@ Controller (EC). `C`
* __genprof__ - Format function tracing logs `Bash` `C`
* __gitconfig__ - Initialize git repository submodules install git
hooks `Bash`
-* __ifdtool__ - Extract and dump Intel Firmware Descriptor information
+* [__ifdtool__](ifdtool/index.md) - Extract and dump Intel Firmware Descriptor information
`C`
* __intelmetool__ - Dump interesting things about Management Engine
even if hidden `C`