From d55fa332d8849b8794b5b8386b73679b71fb6f59 Mon Sep 17 00:00:00 2001 From: Felix Singer Date: Sun, 27 Feb 2022 22:27:17 +0100 Subject: 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 Reviewed-on: https://review.coreboot.org/c/coreboot/+/62424 Tested-by: build bot (Jenkins) Reviewed-by: Thomas Heijligen --- Documentation/contributing/gsoc.md | 2 +- Documentation/flash_tutorial/ext_power.md | 28 ------ Documentation/flash_tutorial/ext_standalone.md | 23 ----- Documentation/flash_tutorial/flash_ic_diode.svg | 61 ----------- Documentation/flash_tutorial/flash_ic_no_diode.svg | 55 ---------- Documentation/flash_tutorial/index.md | 111 --------------------- Documentation/flash_tutorial/int_flashrom.md | 19 ---- Documentation/flash_tutorial/no_ext_power.md | 22 ---- Documentation/index.md | 1 - Documentation/mainboard/acer/g43t-am3.md | 2 +- Documentation/mainboard/asrock/h110m-dvs.md | 2 +- Documentation/mainboard/asrock/h77pro4-m.md | 2 +- Documentation/mainboard/asus/p5q.md | 2 +- Documentation/mainboard/gigabyte/ga-g41m-es2l.md | 2 +- Documentation/mainboard/hp/2560p.md | 2 +- .../mainboard/lenovo/Ivy_Bridge_series.md | 4 +- .../mainboard/lenovo/Sandy_Bridge_series.md | 4 +- .../mainboard/lenovo/ivb_internal_flashing.md | 2 +- Documentation/mainboard/lenovo/t410.md | 2 +- Documentation/mainboard/lenovo/t420.md | 2 +- Documentation/mainboard/lenovo/t430.md | 2 +- Documentation/mainboard/lenovo/w530.md | 2 +- Documentation/mainboard/lenovo/x1.md | 2 +- Documentation/mainboard/lenovo/x230s.md | 2 +- Documentation/mainboard/lenovo/x301.md | 2 +- Documentation/mainboard/msi/ms7707/ms7707.md | 2 +- Documentation/mainboard/prodrive/hermes.md | 2 +- Documentation/mainboard/supermicro/x10slm-f.md | 2 +- .../x11-lga1151-series/x11-lga1151-series.md | 2 +- Documentation/mainboard/supermicro/x9sae.md | 2 +- .../northbridge/intel/sandybridge/me_cleaner.md | 2 +- .../tutorial/flashing_firmware/ext_power.md | 28 ++++++ .../tutorial/flashing_firmware/ext_standalone.md | 23 +++++ .../tutorial/flashing_firmware/flash_ic_diode.svg | 61 +++++++++++ .../flashing_firmware/flash_ic_no_diode.svg | 55 ++++++++++ Documentation/tutorial/flashing_firmware/index.md | 111 +++++++++++++++++++++ .../tutorial/flashing_firmware/int_flashrom.md | 19 ++++ .../tutorial/flashing_firmware/no_ext_power.md | 22 ++++ Documentation/tutorial/index.md | 1 + 39 files changed, 345 insertions(+), 345 deletions(-) delete mode 100644 Documentation/flash_tutorial/ext_power.md delete mode 100644 Documentation/flash_tutorial/ext_standalone.md delete mode 100644 Documentation/flash_tutorial/flash_ic_diode.svg delete mode 100644 Documentation/flash_tutorial/flash_ic_no_diode.svg delete mode 100644 Documentation/flash_tutorial/index.md delete mode 100644 Documentation/flash_tutorial/int_flashrom.md delete mode 100644 Documentation/flash_tutorial/no_ext_power.md create mode 100644 Documentation/tutorial/flashing_firmware/ext_power.md create mode 100644 Documentation/tutorial/flashing_firmware/ext_standalone.md create mode 100644 Documentation/tutorial/flashing_firmware/flash_ic_diode.svg create mode 100644 Documentation/tutorial/flashing_firmware/flash_ic_no_diode.svg create mode 100644 Documentation/tutorial/flashing_firmware/index.md create mode 100644 Documentation/tutorial/flashing_firmware/int_flashrom.md create mode 100644 Documentation/tutorial/flashing_firmware/no_ext_power.md (limited to 'Documentation') diff --git a/Documentation/contributing/gsoc.md b/Documentation/contributing/gsoc.md index ba94f20616..4f854268a8 100644 --- a/Documentation/contributing/gsoc.md +++ b/Documentation/contributing/gsoc.md @@ -260,7 +260,7 @@ questions. [mailing list]: https://mail.coreboot.org/postorius/lists/coreboot.coreboot.org [Getting started]: ../getting_started/index.md [Tutorial]: ../tutorial/index.md -[Flashing firmware tutorial]: ../flash_tutorial/index.md +[Flashing firmware tutorial]: ../tutorial/flashing_firmware/index.md [Coding style]: coding_style.md [Code of Conduct]: ../community/code_of_conduct.md [Language style]: ../community/language_style.md diff --git a/Documentation/flash_tutorial/ext_power.md b/Documentation/flash_tutorial/ext_power.md deleted file mode 100644 index 542ccfd934..0000000000 --- a/Documentation/flash_tutorial/ext_power.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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/flash_tutorial/ext_standalone.md b/Documentation/flash_tutorial/ext_standalone.md deleted file mode 100644 index 3a676ce47c..0000000000 --- a/Documentation/flash_tutorial/ext_standalone.md +++ /dev/null @@ -1,23 +0,0 @@ -# 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/flash_tutorial/flash_ic_diode.svg b/Documentation/flash_tutorial/flash_ic_diode.svg deleted file mode 100644 index 22cd87277f..0000000000 --- a/Documentation/flash_tutorial/flash_ic_diode.svg +++ /dev/null @@ -1,61 +0,0 @@ - - - - - - - - - - - - - - VCC - - - - - - HOLD - - - - CLK - - - DI - - - - - - - CS - - - WP - - - GND - - - DO - - - - - - - - - - - - - - - - - - diff --git a/Documentation/flash_tutorial/flash_ic_no_diode.svg b/Documentation/flash_tutorial/flash_ic_no_diode.svg deleted file mode 100644 index 543c9262df..0000000000 --- a/Documentation/flash_tutorial/flash_ic_no_diode.svg +++ /dev/null @@ -1,55 +0,0 @@ - - - - - - - - - - - - - - VCC - - - - - - HOLD - - - - CLK - - - DI - - - - - - - CS - - - WP - - - GND - - - DO - - - - - - - - - - - - diff --git a/Documentation/flash_tutorial/index.md b/Documentation/flash_tutorial/index.md deleted file mode 100644 index da3d7f098f..0000000000 --- a/Documentation/flash_tutorial/index.md +++ /dev/null @@ -1,111 +0,0 @@ -# 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 -``` - -## 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 -``` - -**TODO** explain FMAP regions, normal/fallback mechanism, flash lock mechanisms - -[flashrom]: https://www.flashrom.org/Flashrom diff --git a/Documentation/flash_tutorial/int_flashrom.md b/Documentation/flash_tutorial/int_flashrom.md deleted file mode 100644 index 982aca287d..0000000000 --- a/Documentation/flash_tutorial/int_flashrom.md +++ /dev/null @@ -1,19 +0,0 @@ -# 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/flash_tutorial/no_ext_power.md b/Documentation/flash_tutorial/no_ext_power.md deleted file mode 100644 index b97ba4cc7a..0000000000 --- a/Documentation/flash_tutorial/no_ext_power.md +++ /dev/null @@ -1,22 +0,0 @@ -# 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/index.md b/Documentation/index.md index aecea356df..16997ed409 100644 --- a/Documentation/index.md +++ b/Documentation/index.md @@ -190,4 +190,3 @@ Contents: * [Utilities](util.md) * [coreboot infrastructure](infrastructure/index.md) * [Release notes](releases/index.md) -* [Flashing firmware tutorial](flash_tutorial/index.md) diff --git a/Documentation/mainboard/acer/g43t-am3.md b/Documentation/mainboard/acer/g43t-am3.md index 2e9b8d658c..e57009c4de 100644 --- a/Documentation/mainboard/acer/g43t-am3.md +++ b/Documentation/mainboard/acer/g43t-am3.md @@ -124,7 +124,7 @@ $ sudo flashrom \ ```eval_rst In addition to the information here, please see the -:doc:`../../flash_tutorial/index`. +:doc:`../../tutorial/flashing_firmware/index`. ``` ### External flashing diff --git a/Documentation/mainboard/asrock/h110m-dvs.md b/Documentation/mainboard/asrock/h110m-dvs.md index 4d26cfd0f8..4a20bb66b5 100644 --- a/Documentation/mainboard/asrock/h110m-dvs.md +++ b/Documentation/mainboard/asrock/h110m-dvs.md @@ -58,7 +58,7 @@ The main SPI flash can be accessed using [flashrom]. By default, only the BIOS region of the flash is writable. If you wish to change any other region, such as the Management Engine or firmware descriptor, then an external programmer is required (unless you find a clever way around -the flash protection). More information about this [here](../../flash_tutorial/index.md). +the flash protection). More information about this [here](../../tutorial/flashing_firmware/index.md). ### External programming diff --git a/Documentation/mainboard/asrock/h77pro4-m.md b/Documentation/mainboard/asrock/h77pro4-m.md index 45c603d7a3..7b4487dbe2 100644 --- a/Documentation/mainboard/asrock/h77pro4-m.md +++ b/Documentation/mainboard/asrock/h77pro4-m.md @@ -115,7 +115,7 @@ region is not readable even by the host. ```eval_rst In addition to the information here, please see the -:doc:`../../flash_tutorial/index`. +:doc:`../../tutorial/flashing_firmware/index`. ``` ## Hardware monitoring and fan control diff --git a/Documentation/mainboard/asus/p5q.md b/Documentation/mainboard/asus/p5q.md index 39a859155f..ec208876a0 100644 --- a/Documentation/mainboard/asus/p5q.md +++ b/Documentation/mainboard/asus/p5q.md @@ -130,5 +130,5 @@ You can also control the CPU fan with similar rules: echo 2000 >/sys/class/hwmon/hwmon2/pwm1_tolerance [ASUS P5Q]: https://www.asus.com/Motherboards/P5Q -[this guide]: ../../flash_tutorial/int_flashrom.md +[this guide]: ../../tutorial/flashing_firmware/int_flashrom.md [kernel docs]: https://www.kernel.org/doc/Documentation/hwmon/w83627ehf.rst diff --git a/Documentation/mainboard/gigabyte/ga-g41m-es2l.md b/Documentation/mainboard/gigabyte/ga-g41m-es2l.md index 6c17f4cc3f..57c4945686 100644 --- a/Documentation/mainboard/gigabyte/ga-g41m-es2l.md +++ b/Documentation/mainboard/gigabyte/ga-g41m-es2l.md @@ -142,7 +142,7 @@ Built gigabyte/ga-g41m-es2l (GA-G41M-ES2L) ```eval_rst In addition to the information here, please see the -:doc:`../../flash_tutorial/index`. +:doc:`../../tutorial/flashing_firmware/index`. ``` ### Do backup diff --git a/Documentation/mainboard/hp/2560p.md b/Documentation/mainboard/hp/2560p.md index 0b51a89e38..65a87d1068 100644 --- a/Documentation/mainboard/hp/2560p.md +++ b/Documentation/mainboard/hp/2560p.md @@ -94,6 +94,6 @@ Schematic of this laptop can be found on [Lab One]. [HP EliteBook 2560p]: https://support.hp.com/us-en/product/hp-elitebook-2560p-notebook-pc/5071201 [Maintenance and Service Guide]: http://h10032.www1.hp.com/ctg/Manual/c03011618 -[flashing tutorial]: ../../flash_tutorial/ext_power.md +[flashing tutorial]: ../../tutorial/flashing_firmware/ext_power.md [Lab One]: https://www.laboneinside.com/hp-elitebook-2560p-schematic-diagram/ [bug #141]: https://ticket.coreboot.org/issues/141 diff --git a/Documentation/mainboard/lenovo/Ivy_Bridge_series.md b/Documentation/mainboard/lenovo/Ivy_Bridge_series.md index ca02b3c69a..bf49f5d5fd 100644 --- a/Documentation/mainboard/lenovo/Ivy_Bridge_series.md +++ b/Documentation/mainboard/lenovo/Ivy_Bridge_series.md @@ -38,7 +38,7 @@ This information is valid for all supported models, except T430s, [T431s](t431s. * ROM chip size should be set to 12MiB. ```eval_rst -Please also have a look at :doc:`../../flash_tutorial/index`. +Please also have a look at :doc:`../../tutorial/flashing_firmware/index`. ``` ## Splitting the coreboot.rom @@ -90,4 +90,4 @@ Tests on Lenovo W530 showed no issues with a stripped and shrunken ME firmware. [me_cleaner]: ../../northbridge/intel/sandybridge/me_cleaner.md -[external programmer]: ../../flash_tutorial/index.md +[external programmer]: ../../tutorial/flashing_firmware/index.md diff --git a/Documentation/mainboard/lenovo/Sandy_Bridge_series.md b/Documentation/mainboard/lenovo/Sandy_Bridge_series.md index e1d9c77501..2a53df3b8c 100644 --- a/Documentation/mainboard/lenovo/Sandy_Bridge_series.md +++ b/Documentation/mainboard/lenovo/Sandy_Bridge_series.md @@ -70,5 +70,5 @@ the remaining space for the `bios` partition. [me_cleaner]: ../../northbridge/intel/sandybridge/me_cleaner.md -[external programmer]: ../../flash_tutorial/index.md -[flashing tutorial]: ../../flash_tutorial/index.md +[external programmer]: ../../tutorial/flashing_firmware/index.md +[flashing tutorial]: ../../tutorial/flashing_firmware/index.md diff --git a/Documentation/mainboard/lenovo/ivb_internal_flashing.md b/Documentation/mainboard/lenovo/ivb_internal_flashing.md index 1aeea8b06c..40afd6fc07 100644 --- a/Documentation/mainboard/lenovo/ivb_internal_flashing.md +++ b/Documentation/mainboard/lenovo/ivb_internal_flashing.md @@ -361,4 +361,4 @@ Note that you should have an external SPI programmer as a backup method. It will help you recover if you flash non-working ROM by mistake. -[flash internally]: ../../flash_tutorial/int_flashrom.md +[flash internally]: ../../tutorial/flashing_firmware/int_flashrom.md diff --git a/Documentation/mainboard/lenovo/t410.md b/Documentation/mainboard/lenovo/t410.md index 980c9590a9..80d54f83eb 100644 --- a/Documentation/mainboard/lenovo/t410.md +++ b/Documentation/mainboard/lenovo/t410.md @@ -37,7 +37,7 @@ The chip will either be a Macronix MX25L6405D or a Winbond W25Q64CVSIG. Do not rely on dots painted in the corner of the chip (such as the blue dot pictured) to orient the pins! -[Flashing tutorial](../../flash_tutorial/no_ext_power.md) +[Flashing tutorial](../../tutorial/flashing_firmware/no_ext_power.md) Steps to access the flash IC are described here [T4xx series]. diff --git a/Documentation/mainboard/lenovo/t420.md b/Documentation/mainboard/lenovo/t420.md index 189649b6e2..726dbd89a3 100644 --- a/Documentation/mainboard/lenovo/t420.md +++ b/Documentation/mainboard/lenovo/t420.md @@ -53,5 +53,5 @@ Steps to access the flash IC are described here [T4xx series]. * Suspend (Windows 10) [T4xx series]: t4xx_series.md -[flashing tutorial]: ../../flash_tutorial/ext_power.md +[flashing tutorial]: ../../tutorial/flashing_firmware/ext_power.md [T420 / T520 / X220 / T420s / W520 common]: Sandy_Bridge_series.md diff --git a/Documentation/mainboard/lenovo/t430.md b/Documentation/mainboard/lenovo/t430.md index c2cddca053..87eedba2a6 100644 --- a/Documentation/mainboard/lenovo/t430.md +++ b/Documentation/mainboard/lenovo/t430.md @@ -9,6 +9,6 @@ the general [flashing tutorial]. Steps to access the flash IC are described here [T4xx series]. -[flashing tutorial]: ../../flash_tutorial/ext_power.md +[flashing tutorial]: ../../tutorial/flashing_firmware/ext_power.md [T4xx series]: t4xx_series.md [T430 / T530 / X230 / T430s / W530 common]: Ivy_Bridge_series.md diff --git a/Documentation/mainboard/lenovo/w530.md b/Documentation/mainboard/lenovo/w530.md index e3fe6b8d4f..c9dcd50146 100644 --- a/Documentation/mainboard/lenovo/w530.md +++ b/Documentation/mainboard/lenovo/w530.md @@ -22,5 +22,5 @@ the general [flashing tutorial]. [w530-2]: w530-2.jpg -[flashing tutorial]: ../../flash_tutorial/ext_power.md +[flashing tutorial]: ../../tutorial/flashing_firmware/ext_power.md [T430 / T530 / X230 / T430s / W530 common]: Ivy_Bridge_series.md diff --git a/Documentation/mainboard/lenovo/x1.md b/Documentation/mainboard/lenovo/x1.md index 9f915bc07f..5e8ec29b10 100644 --- a/Documentation/mainboard/lenovo/x1.md +++ b/Documentation/mainboard/lenovo/x1.md @@ -18,5 +18,5 @@ the general [flashing tutorial]. Steps to access the flash IC are described here [X2xx series]. [X2xx series]: x2xx_series.md -[flashing tutorial]: ../../flash_tutorial/ext_power.md +[flashing tutorial]: ../../tutorial/flashing_firmware/ext_power.md [T420 / T520 / X220 / T420s / W520 common]: Sandy_Bridge_series.md diff --git a/Documentation/mainboard/lenovo/x230s.md b/Documentation/mainboard/lenovo/x230s.md index 845410e17b..eedc5f4196 100644 --- a/Documentation/mainboard/lenovo/x230s.md +++ b/Documentation/mainboard/lenovo/x230s.md @@ -16,4 +16,4 @@ is located at the circled place. Unlike [most Ivy Bridge ThinkPads](Ivy_Bridge_series.md), X230s has a single 16MiB SPI flash chip. -The general [flashing tutorial](../../flash_tutorial/index.md) has more details. +The general [flashing tutorial](../../tutorial/flashing_firmware/index.md) has more details. diff --git a/Documentation/mainboard/lenovo/x301.md b/Documentation/mainboard/lenovo/x301.md index b273fc5a33..4166b3ff68 100644 --- a/Documentation/mainboard/lenovo/x301.md +++ b/Documentation/mainboard/lenovo/x301.md @@ -43,5 +43,5 @@ Tested: Linux payload (Heads) and SeaBIOS. -[flashing tutorial]: ../../flash_tutorial/ext_power.md +[flashing tutorial]: ../../tutorial/flashing_firmware/ext_power.md diff --git a/Documentation/mainboard/msi/ms7707/ms7707.md b/Documentation/mainboard/msi/ms7707/ms7707.md index 9309596b64..c92e674270 100644 --- a/Documentation/mainboard/msi/ms7707/ms7707.md +++ b/Documentation/mainboard/msi/ms7707/ms7707.md @@ -110,4 +110,4 @@ needed (internally re-routed already). [Winbond 25Q32BV datasheet]: https://www.winbond.com/resource-files/w25q32bv_revi_100413_wo_automotive.pdf [Fintek F71808A datasheet]: https://www.alldatasheet.com/datasheet-pdf/pdf/459069/FINTEK/F71808A.html [flashlayout]: flashlayout.svg -[flashing methods]: ../../../flash_tutorial/index.md +[flashing methods]: ../../../tutorial/flashing_firmware/index.md diff --git a/Documentation/mainboard/prodrive/hermes.md b/Documentation/mainboard/prodrive/hermes.md index 6a12c3ab66..3b73ee0ed1 100644 --- a/Documentation/mainboard/prodrive/hermes.md +++ b/Documentation/mainboard/prodrive/hermes.md @@ -49,6 +49,6 @@ The board features: ## Extra links [flashrom]: https://flashrom.org/Flashrom -[flashing tutorial]: ../../../../flash_tutorial/ext_power.md +[flashing tutorial]: ../../../../tutorial/flashing_firmware/ext_power.md [Intel FSP2.0]: ../../../../soc/intel/fsp/index.md [AST2500]: https://www.aspeedtech.com/products.php?fPath=20&rId=440 diff --git a/Documentation/mainboard/supermicro/x10slm-f.md b/Documentation/mainboard/supermicro/x10slm-f.md index 703608028a..97c78d6c3b 100644 --- a/Documentation/mainboard/supermicro/x10slm-f.md +++ b/Documentation/mainboard/supermicro/x10slm-f.md @@ -42,7 +42,7 @@ Now, run `make` to build the coreboot image. ```eval_rst In addition to the information here, please see the -:doc:`../../flash_tutorial/index`. +:doc:`../../tutorial/flashing_firmware/index`. ``` ### Internal programming diff --git a/Documentation/mainboard/supermicro/x11-lga1151-series/x11-lga1151-series.md b/Documentation/mainboard/supermicro/x11-lga1151-series/x11-lga1151-series.md index 692e5e377c..394e0a982d 100644 --- a/Documentation/mainboard/supermicro/x11-lga1151-series/x11-lga1151-series.md +++ b/Documentation/mainboard/supermicro/x11-lga1151-series/x11-lga1151-series.md @@ -56,6 +56,6 @@ These issues apply to all boards. Have a look at the board-specific issues, too. [Supermicro X11 LGA1151 series]: https://www.supermicro.com/products/motherboard/Xeon3000/#1151 [OpenBMC]: https://www.openbmc.org/ [flashrom]: https://flashrom.org/Flashrom -[flashing tutorial]: ../../../../flash_tutorial/ext_power.md +[flashing tutorial]: ../../../../tutorial/flashing_firmware/ext_power.md [Intel FSP2.0]: ../../../../soc/intel/fsp/index.md [AST2400]: https://www.aspeedtech.com/products.php?fPath=20&rId=376 diff --git a/Documentation/mainboard/supermicro/x9sae.md b/Documentation/mainboard/supermicro/x9sae.md index b66ae92748..406785dcf2 100644 --- a/Documentation/mainboard/supermicro/x9sae.md +++ b/Documentation/mainboard/supermicro/x9sae.md @@ -105,4 +105,4 @@ seems that it shall not appear on X9SAE even if it is defined. [X9SAE-V]: https://www.supermicro.com/products/motherboard/xeon/c216/x9sae-v.cfm [W25Q128FVSG]: https://static.chipdip.ru/lib/093/DOC001093213.pdf [flashrom]: https://flashrom.org/Flashrom -[flash internally]: ../../flash_tutorial/int_flashrom.md +[flash internally]: ../../tutorial/flashing_firmware/int_flashrom.md diff --git a/Documentation/northbridge/intel/sandybridge/me_cleaner.md b/Documentation/northbridge/intel/sandybridge/me_cleaner.md index b457dcdd3c..c888d58cec 100644 --- a/Documentation/northbridge/intel/sandybridge/me_cleaner.md +++ b/Documentation/northbridge/intel/sandybridge/me_cleaner.md @@ -81,4 +81,4 @@ Make sure to include all partitions into the ROM: * ME * BIOS -[external programmer]: ../../../flash_tutorial/index.md +[external programmer]: ../../../tutorial/flashing_firmware/index.md diff --git a/Documentation/tutorial/flashing_firmware/ext_power.md b/Documentation/tutorial/flashing_firmware/ext_power.md new file mode 100644 index 0000000000..542ccfd934 --- /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 0000000000..3a676ce47c --- /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 0000000000..22cd87277f --- /dev/null +++ b/Documentation/tutorial/flashing_firmware/flash_ic_diode.svg @@ -0,0 +1,61 @@ + + + + + + + + + + + + + + VCC + + + + + + HOLD + + + + CLK + + + DI + + + + + + + CS + + + WP + + + GND + + + DO + + + + + + + + + + + + + + + + + + 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 0000000000..543c9262df --- /dev/null +++ b/Documentation/tutorial/flashing_firmware/flash_ic_no_diode.svg @@ -0,0 +1,55 @@ + + + + + + + + + + + + + + VCC + + + + + + HOLD + + + + CLK + + + DI + + + + + + + CS + + + WP + + + GND + + + DO + + + + + + + + + + + + diff --git a/Documentation/tutorial/flashing_firmware/index.md b/Documentation/tutorial/flashing_firmware/index.md new file mode 100644 index 0000000000..da3d7f098f --- /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 +``` + +## 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 +``` + +**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 0000000000..982aca287d --- /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 0000000000..b97ba4cc7a --- /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 8b3d88aaba..384f84084e 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) -- cgit v1.2.3