Documentation: Move cbfstool & ifdtool dirs under util\

Change-Id: If1b263345baf321cde75058f310c96d89a95d62d
Signed-off-by: Martin Roth <gaumless@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/64577
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Felix Singer <felixsinger@posteo.net>
This commit is contained in:
Martin Roth
2022-05-22 18:20:02 -06:00
committed by Martin L Roth
parent 13c8dc5d23
commit d5ada6d781
7 changed files with 5 additions and 4 deletions

View File

@@ -0,0 +1,68 @@
# Intel IFD Binary Extraction Tutorial
## Part 1: Extracting Binaries
To begin extracting the binaries, first create a directory labeled "binaries"
in the coreboot directory (i.e. /path/to/coreboot/binaries/).
Now, execute the following commands to extract the binaries from a ROM image.
**Note:** Make sure you are in the root coreboot directory.
cd /path/to/coreboot/util/ifdtool
./ifdtool COREBOOT_IMAGE
./ifdtool -d COREBOOT_IMAGE
./ifdtool -x COREBOOT_IMAGE
In the above steps, COREBOOT_IMAGE is the name of the ROM image to extract the
binaries from, including the file path (ex. /build/coreboot.rom).
Copy the extracted .bin files to the binaries directory you created previously.
**Note:** You may want to rename your various .bin files to more clearly
indicate what they are and their purpose.
To extract the mrc.bin, move to the /coreboot/build directory and run the
following command:
cd /path/to/coreboot/build/
./cbfstool COREBOOT_IMAGE extract -n mrc.bin -f /path/to/destination/filename
where COREBOOT_IMAGE is the filepath to the ROM image (same image as above),
/path/to/destination is the filepath to the destination directory and filename
is the output filename. An example command is given below:
./cbfstool coreboot.rom extract -n mrc.bin -f /path/to/coreboot/binaries/mrc.bin
## Part 2: Using extract_blobs.sh
To simplify some of the steps above, there is a script in the
/path/to/coreboot/util/chromeos/ directory called extract_blobs.sh what will
extract the flashdescriptor.bin and intel_me.bin files.
To run this script, switch to the /path/to/coreboot/util/chromeos/ directory
and execute the script providing a coreboot image as an argument.
cd /path/to/coreboot/util/chromeos/
./extract_blobs.sh COREBOOT_IMAGE
Executing those commands will result in two binary blobs to appear in the
/path/to/coreboot/util/chromeos/ directory under the names
'flashdescriptor.bin' and 'me.bin'.
## Part 3: Changing the coreboot configuration settings
To begin using the binaries extracted above, enable the use of binary
repositories in the menuconfig. From the main coreboot directory, run
'make menuconfig'. Select "General Setup", then select "Allow use of
binary-only repository", then exit to the main menu.
To configure the ROM image for a specific board, select "Mainboard". Select
"Mainboard vendor" and scroll to the correct vendor. Then select "Mainboard
model" and select the name of the board model. Exit back to the main menu.
To add the binaries you extracted, select "Chipset". Scroll and select "Add a
System Agent Binary" and set the filepath to your mrc.bin file's filepath.
Scroll and select "Add Intel descriptor.bin file" and type the filepath for
your descriptor.bin file. Scroll down and select "Add Intel ME/TXE firmware
file" and type the filepath for your ME file. Exit to the main menu.
Select "Exit", and select "Yes" when prompted to save your configuration.

View File

@@ -0,0 +1,6 @@
# ifdtool
Contents:
* [Intel IFD Binary Extraction](binary_extraction.md)
* [IFD Layout](layout.md)

View File

@@ -0,0 +1,78 @@
# 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.
```eval_rst
+------------+------------------+-----------+-------------------------------------------+
| IFD Region | IFD Region name | FMAP Name | Notes |
| index | | | |
+============+==================+===========+===========================================+
| 0 | Flash Descriptor | SI_DESC | Always the top 4 KiB 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 in 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 MiB in the IFD but the FMAP only allocates 4 MiB for
the ME, then when the ME is added by the ifdtool 6 MiB will be written which
could overwrite 2 MiB 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
```