From c7ddc999fc076bf6871e3b5e641c07f17b0b1746 Mon Sep 17 00:00:00 2001 From: Mathew King Date: Thu, 8 Aug 2019 14:59:25 -0600 Subject: 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 Change-Id: Idebf105dee1b8f829d54bd65c82867af7aa4aded Reviewed-on: https://review.coreboot.org/c/coreboot/+/34802 Tested-by: build bot (Jenkins) Reviewed-by: Stefan Reinauer --- Documentation/Binary_Extraction.md | 68 ------------------------------ Documentation/ifdtool/binary_extraction.md | 68 ++++++++++++++++++++++++++++++ Documentation/ifdtool/index.md | 5 +++ Documentation/ifdtool/layout.md | 66 +++++++++++++++++++++++++++++ Documentation/index.md | 1 - Documentation/util.md | 2 +- 6 files changed, 140 insertions(+), 70 deletions(-) delete mode 100644 Documentation/Binary_Extraction.md create mode 100644 Documentation/ifdtool/binary_extraction.md create mode 100644 Documentation/ifdtool/index.md create mode 100644 Documentation/ifdtool/layout.md (limited to 'Documentation') diff --git a/Documentation/Binary_Extraction.md b/Documentation/Binary_Extraction.md deleted file mode 100644 index fe8c25ca4e..0000000000 --- a/Documentation/Binary_Extraction.md +++ /dev/null @@ -1,68 +0,0 @@ -# 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. \ No newline at end of file diff --git a/Documentation/ifdtool/binary_extraction.md b/Documentation/ifdtool/binary_extraction.md new file mode 100644 index 0000000000..fe8c25ca4e --- /dev/null +++ b/Documentation/ifdtool/binary_extraction.md @@ -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. \ No newline at end of file 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` -- cgit v1.2.3