[coreboot-gerrit] Change in coreboot[master]: Documentation/ifdtool: modify IFD regions

[Marcello Sylvester Bauer (Code Review)]

Marcello Sylvester Bauer has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/38832 )

Change subject: Documentation/ifdtool: modify IFD regions
......................................................................

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 
---
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
+```