Marcello Sylvester Bauer has uploaded this change for review.

View Change

Documentation/ifdtool: modify IFD regions

Add documentation about using ifdtool to modify the region rangers,
with examples.

Change-Id: I862bd851fc68365ca11aa0477ae4e4002f1eeea7
Signed-off-by: Marcello Sylvester Bauer <sylv@sylv.io>
---
M Documentation/ifdtool/layout.md
1 file changed, 53 insertions(+), 3 deletions(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/32/38832/1
diff --git a/Documentation/ifdtool/layout.md b/Documentation/ifdtool/layout.md
index 950db6f..c09cfaa 100644
--- a/Documentation/ifdtool/layout.md
+++ b/Documentation/ifdtool/layout.md
@@ -4,7 +4,7 @@
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
+The FMAP should define all offsets of the regions defined by the IFD to ensure
that those regions are accounted for by coreboot and will not be accidentally
modified.

@@ -23,7 +23,7 @@
|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
+## Modification

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
@@ -32,6 +32,56 @@
ME, then when the ME is added by the ifdtool 6 MB will be written which could
overwrite 2 MB of the BIOS.

+### Manual Modification
+
+It is possible to adjust the IFD regions on a firmware image or on a Flash Descriptor file directly.
+In the case of modifying a complete firmware image, it will also move the data content of each region.
+
+The process consists of three steps:
+ 1) dump the ifd layout file out of the firmware/descriptor image
+ 2) modify the ifd region defined on the layout file
+ 3) update the firmware/descriptor image using the new layout
+
+#### Example - Reduce the ME Region size
+
+##### Step 1 - Dump IFD regions into a flashrom layout file
+ $ ifdtool -f ifd_old.layout descriptor.bin
+ Wrote layout to ifd-old.layout
+
+ $ cat ifd_old.layout
+ 00000000:00000fff fd
+ 00500000:007fffff bios
+ 00003000:004fffff me
+ 00001000:00002fff gbe
+
+##### Step 2 - Modify the layout file
+ $ diff ifd_old.layout ifd_new.layout
+ 2,3c2,3
+ < 00500000:007fffff bios
+ < 00003000:004fffff me
+ ---
+ > 00020000:007fffff bios
+ > 00003000:0001ffff me
+
+##### Step 3 - Update the IFD regions
+ $ ifdtool -n ifd_new.layout descriptor.bin
+ [...]
+ Writing new image to descriptor.bin.new
+
+### build-time Modification
+
+Instead of using the the ifdtool directly, it is possible to define a flashrom layout file in the
+coreboot configuration, so that it will be modified at build-time.
+
+ $ make menuconfig
+ Chipset --->
+ [*] Add Intel descriptor.bin file
+ (path/to/descriptor.bin) Path and filename of the descriptor.bin file
+ [*] update regions using a flashrom layout file
+ (path/to/ifd.layout) Path and filename flashrom layout file
+
+## Validation
+
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
@@ -63,4 +113,4 @@
FMAP area SI_PDR:
offset: 0x007fc000
length: 0x00004000
-```
\ No newline at end of file
+```

To view, visit change 38832. To unsubscribe, or for help writing mail filters, visit settings.

Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-Change-Id: I862bd851fc68365ca11aa0477ae4e4002f1eeea7
Gerrit-Change-Number: 38832
Gerrit-PatchSet: 1
Gerrit-Owner: Marcello Sylvester Bauer <sylv@sylv.io>
Gerrit-MessageType: newchange