[coreboot-gerrit] Change in coreboot[master]: documentation: Add flashing instructions This commit adds flashing in...

[Renze Nicolai (Code Review)]

Renze Nicolai has uploaded this change for review. ( https://review.coreboot.org/23028


Change subject: documentation: Add flashing instructions This commit adds flashing instructions to the documentation directory
......................................................................

documentation: Add flashing instructions
This commit adds flashing instructions to the documentation directory

Change-Id: Ieb072c3cf78d70880c04369789d84994ef9a9040
Signed-off-by: Renze Nicolai <renze at rnplus.nl>
---
A Documentation/flashing.md
1 file changed, 123 insertions(+), 0 deletions(-)



  git pull ssh://review.coreboot.org:29418/coreboot refs/changes/28/23028/1

diff --git a/Documentation/flashing.md b/Documentation/flashing.md
new file mode 100644
index 0000000..566acea6
--- /dev/null
+++ b/Documentation/flashing.md
@@ -0,0 +1,123 @@
+# Flashing coreboot
+The BIOS of your computer is stored on a flash chip connected through SPI or LPC.
+
+In some cases it is possible to read from and write to this flash chip from the OS running on the computer the chip is in. In other cases this is not possible and an external flash programmer needs to be used.
+
+When flashing the bios of the computer from within the OS running on it is the easiest way to get Coreboot installed. It does however come with the risk that when you make a mistake your computer won't boot again until the flash is reprogrammed using an external programmer. Flashing without an external programmer available is therefore not recommended.
+
+Externally reading from or writing to the flash chip allows you to recover from a bricked machine and to create backups that are sure to be complete.
+
+## Preparation
+This guide assumes that the ```flashrom``` utility is used to read and write flash chips. Please make sure you have this utility installed on your computer. Also install it on a second computer, which will be used to preform flashing using an external programmer.
+
+### Determining the kind of flash chip
+The flash chip in your computer can be in multiple packages. The flash chip might be contained in a ```SOIC-8```, ```SOIC-16```, ```DIP```, ```PLCC``` or ```WSON``` package.
+
+Depending on the kind of package you will need tools to connect your programmer to your flash chip. For ```SOIC-8``` and ```SOIC-16``` style packages special clips can be bought which allow you to connect a programmer without soldering to your board. The same goes for ```DIP``` style chips, but if you're lucky the ```DIP``` style chip might be placed in a socket, allowing for easy removal and replacement.
+
+When the flash chip on your board is socketed we recommend you to buy an identical flash chip. This will allow you to use the original chip as a backup in case something goes wrong.
+
+Packages like ```PLCC``` and ```WSON``` might prove to be more complex as connecting to these kinds of chips can be a challenge.
+
+Note that in some cases there will be connector available on your board to connect a programmer to. If available we recommend you to use this connector instead of a clip.
+
+To determine the protocol (```SPI``` or ```LPC```) that your flash chip uses please read the first page of the datasheet of your flash chip, which can probably be found easily by searching for the type indication printed on top of the chip.
+
+### Programming a flash chip in-circuit
+Often the flash chip on a board can't easily be removed. When flashing the flash chip of a computer while it is still attached to the mainboard please remove all power sources (AC adapters, batteries) from the board before attempting to program the flash chip.
+
+Since the flash chip needs to be powered in order to be able to program this means that powering the flash chip could cause other parts of the mainboard to be powered from the programmer as well. It is possible that powering the flash chip will cause damage to your board. Always check with other users of your board before attempting to power the flash chip in circuit.
+
+### Multiple flash chips
+Some boards contain multiple (SPI) flash chips, which are combined in software. If your board has multiple flash chips keep in mind that you will have to connect the "chip select" pins of both flash chips. Pulling the chip select pin of a flash chip up to the supply voltage will cause the flash chip to stay idle while. This makes sure that the flash chip you do not wish to target stays idle while you're communicating with the other flash chip.
+
+### Supported programmers
+Flashrom supports many different programmers, a full list of programmers can be found on the [Flashrom website](https://www.flashrom.org/Supported_programmers).
+
+## Flashing internally
+Flashing from within the OS itself is easy, but there are some cavecats:
+
+* Most modern Intel motherboards have the [flash descriptor]() configured in such a way that the OS running on the machine can not read or write certain regions of the flash. This can cause backups to be incomplete and it can cause writing to the BIOS region using this method to be impossible.
+* The Linux kernel by default does not allow reading and writing the flash chip, make sure to add ```iomem=relaxed``` to the cmdline before attempting to flash internally.
+* Laptops, notebooks and netbooks are difficult to support as the embedded controller
+(EC) in these machines often interacts badly with flashing. More details can be found [here](https://flashrom.org/Laptops). If flash is shared with the EC, erase is guaranteed to brick your laptop and write may brick your laptop.
+Read and probe may irritate your EC and cause fan failure, backlight failure and sudden poweroff.
+You have been warned.
+
+Using flashrom to read the flash chip of your computer can be done using the ```-r``` flag:
+
+```
+sudo flashrom -p internal -r backup.rom
+```
+
+We recommend you to read the flash at least two times. Make sure both backups are identical before continuing.
+
+On laptops Flashrom might interfere with the embedded controller. If you still want to continue you will need to run flashrom as follows:
+
+```
+sudo flashrom -p internal:laptop=force_I_want_a_brick -r backup.rom
+```
+
+As explained earlier reading the flash might fail because of the security parameters configured in the Intel flash descriptor, or simply because your board isn't supported (yet). If this is the case you will have to flash using an external programmer.
+
+Writing the flash can be done using the ```-w``` flag:
+
+```
+sudo flashrom -p internal -w build/coreboot.rom
+```
+
+Should writing to the flash chip fail then you might just have corrupted the contents of your flash chip. If this happens to you make sure you DO NOT TURN OFF YOUR COMPUTER. Contact us in the #flashrom channel on Freenode for help, note that it might take a few hours for someone to answer your questions, be patient.
+
+## Flashing Externally
+
+The process of flashing using an external programmer depends on the kind of programmer you're using. We will give a few examples of how to configure Flashrom for certain kinds of programmers. More programmer specific details can be found on the [Flashrom wiki](https://www.flashrom.org/Supported_programmers).
+
+As we've explained earlier programming a flash chip in-circuit is not without danger. Since the flash chip needs to be powered in order to be able to program this means that powering the flash chip could cause other parts of the mainboard to be powered from the programmer as well. It is possible that powering the flash chip will cause damage to your board. Always check with other users of your board before attempting to power the flash chip in circuit.
+
+### Programming SPI flash using a Pickit 2 programmer
+
+Connecting the programmer:
+
+| Pin on the Pickit | Pin on the flash chip |
+|-------------------|-----------------------|
+| 1 - VPP/MCLR      | CS (Chip-select)      |
+| 2 - Vdd           | Vdd / Vcc             |
+| 3 - GND           | GND / Vss             |
+| 4 - PGD           | MISO                  |
+| 5 - PGC           | SCLK                  |
+| 6 - AUX           | MOSI                  |
+
+First check if Flashrom detects your flash chip by running Flashrom without any parameters except for the type of programmer:
+
+```
+flashrom -p pickit2_spi
+```
+
+In some cases you might need to supply the type of chip that is connected by using the ```-c``` flag.
+
+Reading from and writing to the flash chip can be done using the ```-r``` and ```-w``` flags respectively.
+
+### Programming SPI flash using an FTDI FT2232H or FT4232H based board
+
+Connecting the programmer (On port A):
+
+| Pin on the FTDI chip | Pin on the flash chip |
+|----------------------|-----------------------|
+| 16 - ADBUS0          | SCLK                  |
+| 17 - ADBUS1          | MOSI                  |
+| 18 - ADBUS2          | MISO                  |
+| 19 - ADBUS3          | CS (Chip-select)      |
+
+The FT2232H has two separate ports which can be used independently of each other. You will have to tell Flashrom to which of the two ports you connected the flash chip. This is done by adding the one of the ```port=A``` or ```port=B``` parameters to the ```-p ft2232_spi:type=2232H``` flag.
+
+Using an FT4232H based programmer is also supported. Since this chip has four ports the port parameter can be ```A```, ```B```, ```C``` or ```D```. The type parameter should in this case be set to ```type=4232H```.
+
+First check if Flashrom detects your flash chip by running Flashrom without any parameters except for the type of programmer and the port used:
+
+```
+flashrom -p ft2232_spi:type=2232H,port=A
+```
+
+In some cases you might need to supply the type of chip that is connected by using the ```-c``` flag.
+
+Reading from and writing to the flash chip can be done using the ```-r``` and ```-w``` flags respectively.

-- 
To view, visit https://review.coreboot.org/23028
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings

Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ieb072c3cf78d70880c04369789d84994ef9a9040
Gerrit-Change-Number: 23028
Gerrit-PatchSet: 1
Gerrit-Owner: Renze Nicolai <renze at rnplus.nl>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.coreboot.org/pipermail/coreboot-gerrit/attachments/20171228/c0866686/attachment-0001.html>