Documentation/util/ifdtool/layout.md

   1 # IFD Layout
   2
   3 A coreboot image for an Intel SoC contains two separate definitions of the
   4 layout of the flash. The Intel Flash Descriptor (IFD) which defines offsets and
   5 sizes of various regions of flash and the [coreboot FMAP](../../lib/flashmap.md).
   6
   7 The FMAP should define all of the of the regions defined by the IFD to ensure
   8 that those regions are accounted for by coreboot and will not be accidentally
   9 modified.
  10
  11 ## IFD mapping
  12
  13 The names of the IFD regions in the FMAP should follow the convention of
  14 starting with the prefix `SI_` which stands for `silicon initialization` as a
  15 way to categorize anything required by the SoC but not provided by coreboot.
  16
  17 ```eval_rst
  18 +------------+------------------+-----------+-------------------------------------------+
  19 | IFD Region | IFD Region name  | FMAP Name | Notes                                     |
  20 | index      |                  |           |                                           |
  21 +============+==================+===========+===========================================+
  22 | 0          | Flash Descriptor | SI_DESC   | Always the top 4 KiB of flash             |
  23 +------------+------------------+-----------+-------------------------------------------+
  24 | 1          | BIOS             | SI_BIOS   | This is the region that contains coreboot |
  25 +------------+------------------+-----------+-------------------------------------------+
  26 | 2          | Intel ME         | SI_ME     |                                           |
  27 +------------+------------------+-----------+-------------------------------------------+
  28 | 3          | Gigabit Ethernet | SI_GBE    |                                           |
  29 +------------+------------------+-----------+-------------------------------------------+
  30 | 4          | Platform Data    | SI_PDR    |                                           |
  31 +------------+------------------+-----------+-------------------------------------------+
  32 | 8          | EC Firmware      | SI_EC     | Most ChromeOS devices do not use this     |
  33 |            |                  |           | region; EC firmware is stored in BIOS     |
  34 |            |                  |           | region of flash                           |
  35 +------------+------------------+-----------+-------------------------------------------+
  36 ```
  37
  38 ## Validation
  39
  40 The ifdtool can be used to manipulate a firmware image with a IFD. This tool
  41 will not take into account the FMAP while modifying the image which can lead to
  42 unexpected and hard to debug issues with the firmware image. For example if the
  43 ME region is defined at 6 MiB in the IFD but the FMAP only allocates 4 MiB for
  44 the ME, then when the ME is added by the ifdtool 6 MiB will be written which
  45 could overwrite 2 MiB of the BIOS.
  46
  47 In order to validate that the FMAP and the IFD are compatible the ifdtool
  48 provides --validate (-t) option. `ifdtool -t` will read both the IFD and the
  49 FMAP in the image and for every non empty region in the IFD if that region is
  50 defined in the FMAP but the offset or size is different then the tool will
  51 return an error.
  52
  53 Example:
  54
  55 ```console
  56 foo@bar:~$ ifdtool -t bad_image.bin
  57 Region mismatch between bios and SI_BIOS
  58  Descriptor region bios:
  59   offset: 0x00400000
  60   length: 0x01c00000
  61  FMAP area SI_BIOS:
  62   offset: 0x00800000
  63   length: 0x01800000
  64 Region mismatch between me and SI_ME
  65  Descriptor region me:
  66   offset: 0x00103000
  67   length: 0x002f9000
  68  FMAP area SI_ME:
  69   offset: 0x00103000
  70   length: 0x006f9000
  71 Region mismatch between pd and SI_PDR
  72  Descriptor region pd:
  73   offset: 0x003fc000
  74   length: 0x00004000
  75  FMAP area SI_PDR:
  76   offset: 0x007fc000
  77   length: 0x00004000
  78 ```