Documentation: Move firmware flashing tutorial to tutorial section

There is no need that the tutorial for flashing firmware has its own
point in the main menu. Thus, move it to the tutorial section.

Change-Id: Ife6d97254af4c006fe01480a78c76303f9cb34bb
Signed-off-by: Felix Singer <felixsinger@posteo.net>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/62424
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Thomas Heijligen <src@posteo.de>

8 files changed, 320 insertions, 0 deletions

diff --git a/Documentation/tutorial/flashing_firmware/ext_power.md b/Documentation/tutorial/flashing_firmware/ext_power.md
new file mode 100644
index 000000000000..542ccfd934f0
--- /dev/null
+++ b/Documentation/tutorial/flashing_firmware/ext_power.md
@@ -0,0 +1,28 @@
+# Flashing firmware externally supplying direct power
+
+**WARNING:** Never use a high current rated power supply, like PC ATX power
+             supply. It'll literally melt your PCB traces on short circuit.
+
+On some mainboards the flash IC Vcc pin is connected to a diode, which prevents
+powering the rest of the board.
+
+![][flash_ic_diode]
+
+Please have a look at the mainboard specific documentation for details.
+
+On those boards it's safe to use a programmer and supply power externally.
+
+**WARNING:** Verify that you apply the correct voltage!
+
+## USB programmer
+USB programmers are usually current limited by the host USB hub. On USB 2.0
+ports the limit is 500mA, which is sufficient to power the flash. Those are
+the best choice as they are stateless and have a fast power on reset cycle.
+
+## Single board computers (like BeagleBone Black / RPi)
+Be careful when connecting a flash chip, especially when using a Pomona
+test-clip. A short circuit or overcurrent (250mA) causes a brown-out reset,
+resulting in a reboot of the running operating system (and possible loss of
+remote shell).
+
+[flash_ic_diode]: flash_ic_diode.svg
diff --git a/Documentation/tutorial/flashing_firmware/ext_standalone.md b/Documentation/tutorial/flashing_firmware/ext_standalone.md
new file mode 100644
index 000000000000..3a676ce47ca4
--- /dev/null
+++ b/Documentation/tutorial/flashing_firmware/ext_standalone.md
@@ -0,0 +1,23 @@
+# Flashing firmware standalone
+
+If none of the other methods work, there are three possibilities:
+
+## Desolder
+You must remove or desolder the flash IC before you can flash it.
+It's recommended to solder a socket in place of the flash IC.
+
+When flashing the IC, always connect all input pins.
+If in doubt, pull /WP, /HOLD, /RESET and alike up towards Vcc.
+
+## SPI flash emulator
+If you are a developer, you might want to use an [EM100Pro] instead, which sets
+the onboard flash on hold, and allows to run custom firmware.
+It provides a very fast development cycle without actually writing to flash.
+
+## SPI flash overwrite
+It is possible to set the onboard flash on hold and use another flash chip.
+Connect all lines one-to-one, except /HOLD. Pull /HOLD of the soldered flash IC
+low, and /HOLD of your replacement flash IC high.
+
+
+[EM100Pro]: https://www.dediprog.com/product/EM100Pro
diff --git a/Documentation/tutorial/flashing_firmware/flash_ic_diode.svg b/Documentation/tutorial/flashing_firmware/flash_ic_diode.svg
new file mode 100644
index 000000000000..22cd87277fad
--- /dev/null
+++ b/Documentation/tutorial/flashing_firmware/flash_ic_diode.svg
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="4cm" height="3cm" viewBox="311 435 68 45" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <g>
+    <g>
+      <rect style="fill: #ffffff" x="322.125" y="451.034" width="37.75" height="26.6444"/>
+      <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="322.125" y="451.034" width="37.75" height="26.6444"/>
+      <text font-size="4.51549" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="341" y="465.734">
+        <tspan x="341" y="465.734"></tspan>
+      </text>
+    </g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="359.875" y1="456.784" x2="368.527" y2="456.784"/>
+    <text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="348.75" y="457.909">
+      <tspan x="348.75" y="457.909">VCC</tspan>
+    </text>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="359.763" y1="461.772" x2="368.652" y2="461.784"/>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="360.138" y1="466.872" x2="368.527" y2="466.909"/>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="360.277" y1="471.534" x2="368.402" y2="471.534"/>
+    <text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="345.752" y="463.247">
+      <tspan x="345.752" y="463.247">HOLD</tspan>
+    </text>
+    <line style="fill: none; fill-opacity:0; stroke-width: 0.2; stroke: #000000" x1="346.652" y1="459.159" x2="358.402" y2="459.159"/>
+    <text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="349.752" y="468.247">
+      <tspan x="349.752" y="468.247">CLK</tspan>
+    </text>
+    <text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="353.502" y="472.997">
+      <tspan x="353.502" y="472.997">DI</tspan>
+    </text>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.49" y1="456.922" x2="322.143" y2="456.922"/>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.378" y1="461.909" x2="322.268" y2="461.922"/>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.753" y1="467.009" x2="322.143" y2="467.047"/>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.893" y1="471.672" x2="322.018" y2="471.672"/>
+    <text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="323.752" y="458.372">
+      <tspan x="323.752" y="458.372">CS</tspan>
+    </text>
+    <text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="324.127" y="468.497">
+      <tspan x="324.127" y="468.497">WP</tspan>
+    </text>
+    <text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="323.752" y="472.997">
+      <tspan x="323.752" y="472.997">GND</tspan>
+    </text>
+    <text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="324.127" y="463.497">
+      <tspan x="324.127" y="463.497">DO</tspan>
+    </text>
+    <line style="fill: none; fill-opacity:0; stroke-width: 0.2; stroke: #000000" x1="330.852" y1="454.397" x2="323.902" y2="454.409"/>
+    <line style="fill: none; fill-opacity:0; stroke-width: 0.2; stroke: #000000" x1="330.802" y1="464.397" x2="323.852" y2="464.409"/>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="368.252" y1="456.797" x2="373.902" y2="456.784"/>
+  <g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="374.027" y1="456.784" x2="374.027" y2="438.895"/>
+    <polyline style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" points="375.027,439.777 374.027,437.777 373.027,439.777 "/>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="314.277" y1="471.784" x2="314.277" y2="479.659"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="317.027" y1="479.659" x2="311.502" y2="479.672"/>
+  <g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1.2; stroke: #000000" x1="374.027" y1="443.284" x2="374.027" y2="447.434"/>
+    <polygon style="fill: #000000" points="372.027,447.434 374.027,451.434 376.027,447.434 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 1.2; stroke: #000000" points="372.027,447.434 374.027,451.434 376.027,447.434 "/>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1.2; stroke: #000000" x1="370.402" y1="452.032" x2="377.527" y2="452.032"/>
+</svg>
diff --git a/Documentation/tutorial/flashing_firmware/flash_ic_no_diode.svg b/Documentation/tutorial/flashing_firmware/flash_ic_no_diode.svg
new file mode 100644
index 000000000000..543c9262df53
--- /dev/null
+++ b/Documentation/tutorial/flashing_firmware/flash_ic_no_diode.svg
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="4cm" height="3cm" viewBox="311 435 65 45" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <g>
+    <g>
+      <rect style="fill: #ffffff" x="322.124" y="451.034" width="37.75" height="26.6444"/>
+      <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="322.124" y="451.034" width="37.75" height="26.6444"/>
+      <text font-size="4.51556" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="340.999" y="465.734">
+        <tspan x="340.999" y="465.734"></tspan>
+      </text>
+    </g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="359.874" y1="456.784" x2="368.528" y2="456.784"/>
+    <text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="348.75" y="457.91">
+      <tspan x="348.75" y="457.91">VCC</tspan>
+    </text>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="359.762" y1="461.772" x2="368.652" y2="461.784"/>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="360.138" y1="466.872" x2="368.528" y2="466.91"/>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="360.278" y1="471.534" x2="368.402" y2="471.534"/>
+    <text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="345.752" y="463.246">
+      <tspan x="345.752" y="463.246">HOLD</tspan>
+    </text>
+    <line style="fill: none; fill-opacity:0; stroke-width: 0.2; stroke: #000000" x1="346.652" y1="459.16" x2="358.402" y2="459.16"/>
+    <text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="349.752" y="468.246">
+      <tspan x="349.752" y="468.246">CLK</tspan>
+    </text>
+    <text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="353.502" y="472.996">
+      <tspan x="353.502" y="472.996">DI</tspan>
+    </text>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.49" y1="456.922" x2="322.142" y2="456.922"/>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.378" y1="461.91" x2="322.268" y2="461.922"/>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.752" y1="467.01" x2="322.142" y2="467.046"/>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.892" y1="471.672" x2="322.018" y2="471.672"/>
+    <text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="323.752" y="458.372">
+      <tspan x="323.752" y="458.372">CS</tspan>
+    </text>
+    <text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="324.128" y="468.496">
+      <tspan x="324.128" y="468.496">WP</tspan>
+    </text>
+    <text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="323.752" y="472.996">
+      <tspan x="323.752" y="472.996">GND</tspan>
+    </text>
+    <text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="324.128" y="463.496">
+      <tspan x="324.128" y="463.496">DO</tspan>
+    </text>
+    <line style="fill: none; fill-opacity:0; stroke-width: 0.2; stroke: #000000" x1="330.852" y1="454.396" x2="323.902" y2="454.41"/>
+    <line style="fill: none; fill-opacity:0; stroke-width: 0.2; stroke: #000000" x1="330.802" y1="464.396" x2="323.852" y2="464.41"/>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="368.252" y1="456.796" x2="373.902" y2="456.784"/>
+  <g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="374.028" y1="456.784" x2="374.028" y2="438.896"/>
+    <polyline style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" points="375.028,439.778 374.028,437.778 373.028,439.778 "/>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="314.278" y1="471.784" x2="314.278" y2="479.66"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="317.028" y1="479.66" x2="311.502" y2="479.672"/>
+</svg>
diff --git a/Documentation/tutorial/flashing_firmware/index.md b/Documentation/tutorial/flashing_firmware/index.md
new file mode 100644
index 000000000000..da3d7f098ff8
--- /dev/null
+++ b/Documentation/tutorial/flashing_firmware/index.md
@@ -0,0 +1,111 @@
+# Flashing firmware tutorial
+
+Updating the firmware is possible using the **internal method**, where the updates
+happen from a running system, or using the **external method**, where the system
+is in a shut down state and an external programmer is attached to write into the
+flash IC.
+
+## Contents
+
+* [Flashing internally](int_flashrom.md)
+* [Flashing firmware standalone](ext_standalone.md)
+* [Flashing firmware externally supplying direct power](ext_power.md)
+* [Flashing firmware externally without supplying direct power](no_ext_power.md)
+
+## General advice
+
+* It's recommended to only flash the BIOS region.
+* Always verify the firmware image.
+* If you flash externally and have transmission errors:
+  * Use short wires
+  * Reduce clock frequency
+  * Check power supply
+  * Make sure that there are no other bus masters (EC, ME, SoC, ...)
+
+## Internal method
+
+This method using [flashrom] is available on many platforms, as long as they
+aren't locked down.
+
+There are various protection schemes that make it impossible to modify or
+replace a firmware from a running system. coreboot allows to disable these
+mechanisms, making it possible to overwrite (or update) the firmware from a
+running system.
+
+Usually you must use the **external method** once to install a retrofitted
+coreboot and then you can use the **internal method** for future updates.
+
+There are multiple ways to update the firmware:
+* Using flashrom's *internal* programmer to directly write into the firmware
+  flash IC, running on the target machine itself
+* A proprietary software to update the firmware, running on the target machine
+  itself
+* A UEFI firmware update capsule
+
+More details on flashrom's
+* [internal programmer](int_flashrom.md)
+
+## External method
+
+External flashing is possible on many platforms, but requires disassembling
+the target hardware. You need to buy a flash programmer, that
+exposes the same interface as your flash IC (likely SPI).
+
+Please also have a look at the mainboard-specific documentation for details.
+
+After exposing the firmware flash IC, read the schematics and use one of the
+possible methods:
+
+* [Flashing firmware standalone](ext_standalone.md)
+* [Flashing firmware externally supplying direct power](ext_power.md)
+* [Flashing firmware externally without supplying direct power](no_ext_power.md)
+
+**WARNING:** Using the wrong method or accidentally using the wrong pinout might
+  permanently damage your hardware!
+
+**WARNING:** Do not rely on dots *painted* on flash ICs to orient the pins!
+Any dots painted on flash ICs may only indicate if they've been tested.  Dots
+that appear in datasheets to indicate pin 1 correspond to some kind of physical
+marker, such as a drilled hole, or one side being more flat than the other.
+
+## Using a layout file
+On platforms where the flash IC is shared with other components you might want
+to write only a part of the flash IC. On Intel for example there are IFD, ME and
+GBE which don't need to be updated to install coreboot.
+To make [flashrom] only write the *bios* region, leaving Intel ME and Intel IFD
+untouched, you can use a layout file, which can be created with ifdtool and a backup
+of the original firmware.
+
+```bash
+ifdtool -f rom.layout backup.rom
+```
+
+and looks similar to:
+
+```
+00000000:00000fff fd
+00500000:00bfffff bios
+00003000:004fffff me
+00001000:00002fff gbe
+```
+
+By specifying *-l* and *-i* [flashrom] writes a single region:
+```bash
+flashrom -l rom.layout -i bios -w coreboot.rom -p <programmer>
+```
+
+## Using an IFD to determine the layout
+flashrom version 1.0 supports reading the layout from the IFD (first 4KiB of
+the ROM). You don't need to manually specify a layout it, but it only works
+under the following conditions:
+
+* Only available on Intel ICH7+
+* There's only one flash IC when flashing externally
+
+```bash
+flashrom --ifd -i bios -w coreboot.rom -p <programmer>
+```
+
+**TODO** explain FMAP regions, normal/fallback mechanism, flash lock mechanisms
+
+[flashrom]: https://www.flashrom.org/Flashrom
diff --git a/Documentation/tutorial/flashing_firmware/int_flashrom.md b/Documentation/tutorial/flashing_firmware/int_flashrom.md
new file mode 100644
index 000000000000..982aca287d2a
--- /dev/null
+++ b/Documentation/tutorial/flashing_firmware/int_flashrom.md
@@ -0,0 +1,19 @@
+# Flashing firmware internally
+
+**WARNING:** If you flash a broken firmware and have no recovery mechanism, you
+             must use the **external method** to flash a working firmware again.
+
+## Using flashrom
+This method does only work on Linux, if it isn't locked down.
+You may also need to boot with `iomem=relaxed` in the kernel command
+line if CONFIG_IO_STRICT_DEVMEM is set.
+
+
+For more details please also check [flashrom's wiki].
+Use the programmer *internal* to flash *coreboot.rom* internally:
+
+```bash
+flashrom -p internal -w coreboot.rom
+```
+
+[flashrom's wiki]: https://www.flashrom.org/Flashrom
diff --git a/Documentation/tutorial/flashing_firmware/no_ext_power.md b/Documentation/tutorial/flashing_firmware/no_ext_power.md
new file mode 100644
index 000000000000..b97ba4cc7a1f
--- /dev/null
+++ b/Documentation/tutorial/flashing_firmware/no_ext_power.md
@@ -0,0 +1,22 @@
+# Flashing firmware externally supplying no power
+
+On some mainboards the flash IC's Vcc pin is connected to the internal
+power-rail, powering the entire board if the flash IC is powered externally.
+Likely it powers other chips which access the flash IC, preventing the external
+programmer from reading/writing the chip. It also violates the components'
+power sequence, bringing the ICs into an undefined state.
+
+![][flash_ic_no_diode]
+
+Please have a look at the mainboard specific documentation for details.
+
+On those boards it's recommended to use a programmer without supplying power
+externally.
+
+The key to read and write the flash IC is to put the machine into *S3* sleep-
+state or *S5* sleep-state *maybe* with Wake-On-LAN enabled.
+Another option that sometimes works is to keep the device in reset. This method requires
+knowledge of the board schematics and might require hardware modifications.
+Use a multimeter to make sure the flash IC is powered in those sleep states.
+
+[flash_ic_no_diode]: flash_ic_no_diode.svg
diff --git a/Documentation/tutorial/index.md b/Documentation/tutorial/index.md
index 8b3d88aaba45..384f84084e59 100644
--- a/Documentation/tutorial/index.md
+++ b/Documentation/tutorial/index.md
@@ -4,3 +4,4 @@
 * [Part 2: Submitting a patch to coreboot.org](part2.md)
 * [Part 3: Writing unit tests](part3.md)
 * [Managing local additions](managing_local_additions.md)
+* [Flashing firmware](flashing_firmware/index.md)