Documentation/tutorial/flashing_firmware/index.md

   1 # Flashing firmware tutorial
   2
   3 Updating the firmware is possible using the **internal method**, where the updates
   4 happen from a running system, or using the **external method**, where the system
   5 is in a shut down state and an external programmer is attached to write into the
   6 flash IC.
   7
   8 ## Contents
   9
  10 ```{toctree}
  11 :maxdepth: 1
  12
  13 Flashing internally <int_flashrom.md>
  14 Flashing firmware standalone <ext_standalone.md>
  15 Flashing firmware externally supplying direct power <ext_power.md>
  16 Flashing firmware externally without supplying direct power <no_ext_power.md>
  17 ```
  18
  19 ## General advice
  20
  21 * It's recommended to only flash the BIOS region.
  22 * Always verify the firmware image.
  23 * If you flash externally and have transmission errors:
  24   * Use short wires
  25   * Reduce clock frequency
  26   * Check power supply
  27   * Make sure that there are no other bus masters (EC, ME, SoC, ...)
  28
  29 ## Internal method
  30
  31 This method using [flashrom] is available on many platforms, as long as they
  32 aren't locked down.
  33
  34 There are various protection schemes that make it impossible to modify or
  35 replace a firmware from a running system. coreboot allows to disable these
  36 mechanisms, making it possible to overwrite (or update) the firmware from a
  37 running system.
  38
  39 Usually you must use the **external method** once to install a retrofitted
  40 coreboot and then you can use the **internal method** for future updates.
  41
  42 There are multiple ways to update the firmware:
  43 * Using flashrom's *internal* programmer to directly write into the firmware
  44   flash IC, running on the target machine itself
  45 * A proprietary software to update the firmware, running on the target machine
  46   itself
  47 * A UEFI firmware update capsule
  48
  49 More details on flashrom's
  50 ```{toctree}
  51 :maxdepth: 1
  52
  53 internal programmer <int_flashrom.md>
  54 ```
  55
  56 ## External method
  57
  58 External flashing is possible on many platforms, but requires disassembling
  59 the target hardware. You need to buy a flash programmer, that
  60 exposes the same interface as your flash IC (likely SPI).
  61
  62 Please also have a look at the mainboard-specific documentation for details.
  63
  64 After exposing the firmware flash IC, read the schematics and use one of the
  65 possible methods:
  66
  67 ```{toctree}
  68 :maxdepth: 1
  69
  70 Flashing firmware standalone <ext_standalone.md>
  71 Flashing firmware externally supplying direct power <ext_power.md>
  72 Flashing firmware externally without supplying direct power <no_ext_power.md>
  73 ```
  74
  75 **WARNING:** Using the wrong method or accidentally using the wrong pinout might
  76   permanently damage your hardware!
  77
  78 **WARNING:** Do not rely on dots *painted* on flash ICs to orient the pins!
  79 Any dots painted on flash ICs may only indicate if they've been tested.  Dots
  80 that appear in datasheets to indicate pin 1 correspond to some kind of physical
  81 marker, such as a drilled hole, or one side being more flat than the other.
  82
  83 ## Using a layout file
  84 On platforms where the flash IC is shared with other components you might want
  85 to write only a part of the flash IC. On Intel for example there are IFD, ME and
  86 GBE which don't need to be updated to install coreboot.
  87 To make [flashrom] only write the *bios* region, leaving Intel ME and Intel IFD
  88 untouched, you can use a layout file, which can be created with ifdtool and a backup
  89 of the original firmware.
  90
  91 ```bash
  92 ifdtool -f rom.layout backup.rom
  93 ```
  94
  95 and looks similar to:
  96
  97 ```
  98 00000000:00000fff fd
  99 00500000:00bfffff bios
 100 00003000:004fffff me
 101 00001000:00002fff gbe
 102 ```
 103
 104 By specifying *-l* and *-i* [flashrom] writes a single region:
 105 ```bash
 106 flashrom -l rom.layout -i bios -w coreboot.rom -p <programmer>
 107 ```
 108
 109 ## Using an IFD to determine the layout
 110 flashrom version 1.0 supports reading the layout from the IFD (first 4KiB of
 111 the ROM). You don't need to manually specify a layout it, but it only works
 112 under the following conditions:
 113
 114 * Only available on Intel ICH7+
 115 * There's only one flash IC when flashing externally
 116
 117 ```bash
 118 flashrom --ifd -i bios -w coreboot.rom -p <programmer>
 119 ```
 120
 121 **TODO** explain FMAP regions, normal/fallback mechanism, flash lock mechanisms
 122
 123 [flashrom]: https://www.flashrom.org/Flashrom