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>

Documentation/util/cbfstool/index.md

@@ -0,0 +1,5 @@
+# cbfstool
+
+Contents:
+
+* [Handling memory mapped boot media](mmap_windows.md)

Documentation/util/cbfstool/mmap_windows.md

@@ -0,0 +1,77 @@
+# cbfstool: Handling memory mapped boot media
+
+`cbfstool` is a utility used for managing coreboot file system (CBFS)
+components in a ROM image. x86 platforms are special since they have
+the SPI flash boot media memory mapped into host address space at
+runtime. This requires `cbfstool` to deal with two separate address
+spaces for any CBFS components that are eXecute-In-Place (XIP) - one
+is the SPI flash address space and other is the host address space
+where the SPI flash gets mapped.
+
+By default, all x86 platforms map a maximum of 16MiB of SPI flash at
+the top of 4G in host address space. If the flash is greater than
+16MiB, then only the top 16MiB of the flash is mapped in the host
+address space. If the flash is smaller than 16MiB, then the entire SPI
+flash is mapped at the top of 4G and the rest of the space remains
+unused.
+
+In more recent platforms like Tiger Lake (TGL), it is possible to map
+more than 16MiB of SPI flash. Since the host address space has legacy
+fixed device addresses mapped below `4G - 16M`, the SPI flash is split
+into separate windows when being mapped to the host address space.
+Default decode window of maximum 16MiB size still lives just below the
+4G boundary. The additional decode window is free to live in any
+available MMIO space that the SoC chooses.
+
+Following diagram shows different combinations of SPI flash being
+mapped into host address space when using multiple windows:
+
+![MMAP window combinations with different flash sizes][mmap_windows]
+
+*(a) SPI flash of size 16MiB (b) SPI flash smaller than 16MiB (c) SPI flash
+of size (16MiB+ext window size) (d) SPI flash smaller than (16MiB+ext
+window size)*
+
+The location of standard decode window is fixed in host address space
+`(4G - 16M) to 4G`. However, the platform is free to choose where the
+extended window lives in the host address space. Since `cbfstool`
+needs to know the exact location of the extended window, it allows the
+platform to pass in two parameters `ext-win-base` and `ext-win-size`
+that provide the base and the size of the extended window in host
+address space.
+
+`cbfstool` creates two memory map windows using the knowledge about the
+standard decode window and the information passed in by the platform
+about the extended decode window. These windows are useful in
+converting addresses from one space to another (flash space and host
+space) when dealing with XIP components.
+
+## Assumptions
+
+1. Top 16MiB is still decoded in the fixed decode window just below 4G
+   boundary.
+1. Rest of the SPI flash below the top 16MiB is mapped at the top of
+   the extended window. Even though the platform might support a
+   larger extended window, the SPI flash part used by the mainboard
+   might not be large enough to be mapped in the entire window. In
+   such cases, the mapping is assumed to be in the top part of the
+   extended window with the bottom part remaining unused.
+
+## Example
+
+If the platform supports extended window and the SPI flash size is
+greater, then `cbfstool` creates a mapping for the extended window as
+well.
+
+```
+ext_win_base = 0xF8000000
+ext_win_size = 32 * MiB
+ext_win_limit = ext_win_base + ext_win_size - 1 = 0xF9FFFFFF
+```
+
+If SPI flash is 32MiB, then top 16MiB is mapped from `0xFF000000 -
+0xFFFFFFFF` whereas the bottom 16MiB is mapped from `0xF9000000 -
+0xF9FFFFFF`. The extended window `0xF8000000 - 0xF8FFFFFF` remains
+unused.
+
+[mmap_windows]: mmap_windows.svg

Documentation/util/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.

Documentation/util/ifdtool/index.md

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

Documentation/util/ifdtool/layout.md

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