From 15d840558480536ddaca71bc1876254d59fca7fe Mon Sep 17 00:00:00 2001 From: Patrick Rudolph Date: Sat, 4 Aug 2018 10:04:45 +0200 Subject: Documentation: Add basic flashing tutorial for Lenovo * Add basic flashing tutorial ** Describe internal and external flashing ** Describe flash supply diode protection ** Gives general advices on flashing ** Describe how to use flashrom --ifd * Describe basic flashing on Lenovo T4xx devices ** Describe how to disassemble and access the flash IC on T4xx ** Describe flash layout on Sandy Bridge and Ivy Bridge series. Change-Id: Ia833e27f4e7d89ee32be9bed21a0c021839facec Signed-off-by: Patrick Rudolph Reviewed-on: https://review.coreboot.org/27852 Tested-by: build bot (Jenkins) Reviewed-by: Philipp Deppenwiese --- 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 | 105 +++++++++++++++++++++ Documentation/flash_tutorial/int_flashrom.md | 19 ++++ Documentation/flash_tutorial/no_ext_power.md | 22 +++++ 7 files changed, 313 insertions(+) create mode 100644 Documentation/flash_tutorial/ext_power.md create mode 100644 Documentation/flash_tutorial/ext_standalone.md create mode 100644 Documentation/flash_tutorial/flash_ic_diode.svg create mode 100644 Documentation/flash_tutorial/flash_ic_no_diode.svg create mode 100644 Documentation/flash_tutorial/index.md create mode 100644 Documentation/flash_tutorial/int_flashrom.md create mode 100644 Documentation/flash_tutorial/no_ext_power.md (limited to 'Documentation/flash_tutorial') diff --git a/Documentation/flash_tutorial/ext_power.md b/Documentation/flash_tutorial/ext_power.md new file mode 100644 index 0000000000..542ccfd934 --- /dev/null +++ b/Documentation/flash_tutorial/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/flash_tutorial/ext_standalone.md b/Documentation/flash_tutorial/ext_standalone.md new file mode 100644 index 0000000000..3a676ce47c --- /dev/null +++ b/Documentation/flash_tutorial/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/flash_tutorial/flash_ic_diode.svg b/Documentation/flash_tutorial/flash_ic_diode.svg new file mode 100644 index 0000000000..22cd87277f --- /dev/null +++ b/Documentation/flash_tutorial/flash_ic_diode.svg @@ -0,0 +1,61 @@ + + + + + + + + + + + + + + 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 new file mode 100644 index 0000000000..543c9262df --- /dev/null +++ b/Documentation/flash_tutorial/flash_ic_no_diode.svg @@ -0,0 +1,55 @@ + + + + + + + + + + + + + + VCC + + + + + + HOLD + + + + CLK + + + DI + + + + + + + CS + + + WP + + + GND + + + DO + + + + + + + + + + + + diff --git a/Documentation/flash_tutorial/index.md b/Documentation/flash_tutorial/index.md new file mode 100644 index 0000000000..1a291372a6 --- /dev/null +++ b/Documentation/flash_tutorial/index.md @@ -0,0 +1,105 @@ +# 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 internaly](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! + +## 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 using ifdtool + +```bash +ifdtool -f rom.layout coreboot.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 new file mode 100644 index 0000000000..28b534b003 --- /dev/null +++ b/Documentation/flash_tutorial/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/flash_tutorial/no_ext_power.md b/Documentation/flash_tutorial/no_ext_power.md new file mode 100644 index 0000000000..b97ba4cc7a --- /dev/null +++ b/Documentation/flash_tutorial/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 -- cgit v1.2.3