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