From cf5b9d6a31d898750dd31df12f0b6be9c5dce32e Mon Sep 17 00:00:00 2001 From: Francis Rowe Date: Sat, 14 Feb 2015 02:31:20 -0500 Subject: Documentation: improve the installation instructions --- (limited to 'docs/install') diff --git a/docs/install/bbb_setup.html b/docs/install/bbb_setup.html index d9251d5..70881a2 100644 --- a/docs/install/bbb_setup.html +++ b/docs/install/bbb_setup.html @@ -8,14 +8,14 @@ @import url('../css/main.css'); - Setup the BeagleBone Black as an SPI flashrom programmer + How to programme an SPI flash chip with the BeagleBone Black
-

Setup the BeagleBone Black as an SPI flashrom programmer

-

How to use the BBB as an external flashrom programmer, for reading/writing an SPI flash chip.

+

How to programme an SPI flash chip with the BeagleBone Black

+

This section documents how to use the BBB as an external flashrom programmer, for reading and writing an SPI flash chip.

Back to previous index

@@ -247,8 +247,8 @@ crw-rw---T 1 root spi 153, 0 Nov 19 21:07 /dev/spidev1.0 entry already exists.

- Get flashrom from libreboot_bin release archive, or build it from libreboot_src/git if you need to. - An ARM binary (statically compiled) for flashrom exists in libreboot_bin releases. + Get flashrom from libreboot_util release archive, or build it from libreboot_src/git if you need to. + An ARM binary (statically compiled) for flashrom exists in libreboot_util releases.

@@ -326,7 +326,7 @@ Note: flashrom can never write if the flash chip isn't found automatically.

- That's basically it. Now refer back to the documentation for how to use this on your board. + That's basically it. Now refer back to the installation page for how to use this on your board.

diff --git a/docs/install/index.html b/docs/install/index.html index 4ec7bdb..6f95068 100644 --- a/docs/install/index.html +++ b/docs/install/index.html @@ -26,27 +26,27 @@

- -

Setting up external programmers

+ -

Installing libreboot (software)

+

Software methods

-

Installing libreboot (hardware)

+

Hardware methods

@@ -56,15 +56,14 @@

List of ROM images in libreboot

- Use the list of archives below to know which archive is correct - for your device: + Libreboot supports the following (refer to the release page):

@@ -84,15 +83,11 @@

QEMU

- Coreboot supports QEMU. QEMU is useful for testing purposes. Libreboot - comes with ROM images built for QEMU, by default. -

-

- The following ROM image archives are available in libreboot: + Libreboot comes with ROM images built for QEMU, by default:

Examples of how to use libreboot in QEMU: @@ -114,43 +109,77 @@

- +
-

X60/X60S/X60T/T60: How to flash the ROMs onto your machine (if running Lenovo BIOS firmware).

+

How to install or update libreboot (if running libreboot or coreboot)

-

- Hover over the next paragraph to make it black. + If you are using libreboot_src or git, then make sure that you built the sources first (see ../git/index.html#build).

-

- Following this guide means simply flashing a libreboot ROM. This guide will not (directly) teach you how to make a backup (dump) of the original Lenovo BIOS - because to do so would be to explicitly endorse proprietary software. However, for the purposes of reverse engineering it can be useful - to have a backup. Each copy of the original Lenovo BIOS is tied to the specific machine that it came from; it will not run - on any other machine, even if it's the same type of machine as yours. What this means is that, effectively, you can back it up now (so that you can - re-flash it later if you want to run the original Lenovo BIOS again) or lose it forever. The X60/T60 installation - guide on the coreboot wiki will show you how to do this: - http://www.coreboot.org/Board:lenovo/x60/Installation.
- Do not make this decision lightly! This is your last and only chance. +

+ +

+ These instructions work for most targets, provided that they are already running libreboot or coreboot. +

+

+ Look at the list of ROM images to see which image is compatible with your device. +

+

+ X60/T60 users with Lenovo BIOS should refer to #flashrom_lenovobios instead. + Similary, MacBook2,1 users running Apple EFI should refer to #flashrom_macbook21. +

+

+ + ThinkPad T60 and X60 Tablet users: be sure to read ../hcl/index.html#supported_t60_list + or ../hcl/index.html#supported_t60_list. + +

+

+ X200/R400 users running Lenovo BIOS should refer to x200_external.html + or r400_external.html. These machines contain the hard coded + MAC address for the onboard ethernet chipset, directly inside the SPI flash; + ich9gen shows how to change it (the default + libreboot ROM images for these machines contain a generic MAC address). +

+

+ X200/R400 users should also note, that it is possible for the user to write-protect whole regions + of the SPI flash by using a modified descriptor. Locked regions must be flashed externally; + see x200_external.html or r400_external.html. + Libreboot unlocks all regions, by default. +

+
+

+ How to update the flash chip contents:
+ $ sudo ./flash update yourrom.rom

- +
+

- The following is for the libreboot image and *not* the factory bios dump: + Ocassionally, coreboot changes the name of a given board. If flashrom complains about a board mismatch, but + you are sure that you chose the correct ROM image, then run this alternative command:
+ $ sudo ./flash forceupdate yourrom.rom

+
+ +
+

- Check the last two 64K regions in your ROM file (libreboot.rom in this example):
- $ dd if=libreboot.rom of=top64k.bin bs=1 skip=$[$(stat -c %s libreboot.rom) - 0x10000] count=64k
- $ dd if=libreboot.rom of=lower64k.bin bs=1 skip=$[$(stat -c %s libreboot.rom) - 0x20000] count=64k
- $ sha512sum lower64k.bin top64k.bin
- Make *sure* that they match before you continue. The ROMs included pre-compiled in libreboot should already match. - If they don't match, then do this (based on those instructions from coreboot wiki):
- $ dd if=top64k.bin of=libreboot.rom bs=1 seek=$[$(stat -c %s libreboot.rom) - 0x20000] count=64k conv=notrunc
- After this, the ROM will be safe to flash. Explanation is provided in ../git/index.html#build_bucts. + You should see "Verifying flash... VERIFIED." written at the end of the flashrom output. Shut down + after you see this, and then boot up again after a few seconds.

+

Back to top of page

+ +
+ +
+ +

ThinkPad X60/T60: Initial installation guide (if running Lenovo BIOS firmware)

+

This is for the ThinkPad X60 and T60 while running Lenovo BIOS. If you already have coreboot or libreboot running, then go to #flashrom instead!

@@ -161,16 +190,25 @@ If you are using libreboot_src or git, then make sure that you built the sources first (see ../git/index.html#build).

- -

"YOURBOARD/YOURROM" should be replaced with what is correct as per #rom. Alternatively - you may be using your own custom ROM. Adapt.

- +

- Run the script:
- $ sudo ./flash i945lenovo_firstflash bin/YOURBOARD/YOURROM. + + Warning: this guide will not instruct the user how to backup the original Lenovo BIOS firmware. These backups + are tied to each machine, and will not work on any other. + For that, please refer to http://www.coreboot.org/Board:lenovo/x60/Installation. +

+ +

+ The first half of the procedure is as follows:
+ $ sudo ./flash i945lenovo_firstflash yourrom.rom. +

+ +
+ +

You should see within the output the following:
@@ -194,16 +232,12 @@

-

- - If you boot and you see nothing, try turning up the backlight (Fn+Home). - -

- -

- When you have booted up again:
- $ sudo ./flash i945lenovo_secondflash bin/YOURBOARD/YOURROM -

+
+

+ When you have booted up again, you must also do this:
+ $ sudo ./flash i945lenovo_secondflash yourrom.rom +

+
@@ -217,46 +251,20 @@ "Verifying flash... VERIFIED."

-

Shut down again, wait a few seconds, and then boot.

-
-

- Some thinkpads come with WWAN cards installed, along with sim cards. These use non-free firmware and should be removed. - You might also want to remove bluetooth. See ../security/x60_security.html and - ../security/t60_security.html. -

-

Back to top of page.

-

macbook21: How to flash your ROM (if running Apple EFI firmware)

+

MacBook2,1: Initial installation guide (if running Apple EFI firmware)

- Hover over the next paragraph to make it black. -

-

- Following this guide means simply flashing a libreboot ROM. This guide will not (directly) teach you how to make a backup (dump) of the original Apple EFI firmware - because to do so would be to explicitly endorse proprietary software. However, for the purposes of reverse engineering it can be useful - to have a backup. Each copy of the original Apple EFI is (believed, but unproven to be) tied to the specific machine that it came from; it will not (as is believed) run - on any other machine, even if it's the same type of machine as yours. What this means is that, effectively, you can back it up now (so that you can - re-flash it later if you want to run the original Apple EFI firmware again) or lose it forever. The macbook21 installation - guide on the coreboot wiki will show you how to do this: - http://www.coreboot.org/Board:apple/macbook21.
- Do not make this decision lightly! This is (very likely) your last and only chance. -

- -

- (this theory is untested at the time of writing) -

- -

- Note: If you have a MacBook1,1 then these instructions will not work. See ../hcl/index.html#macbook11 for MacBook1,1 flashing instructions. + If you have a MacBook1,1, refer to ../hcl/index.html#macbook11 for flashing instructions.

@@ -271,149 +279,45 @@

Be sure to read the information in ../hcl/index.html#macbook21.

- -
-

- If you are using libreboot_src or git, then make sure that you built the sources first (see ../git/index.html#build). -

-
- -

- Look at #rom to see which ROM is suitable for your machine. Alternatively you may be using your own - custom ROM. Adapt. -

- +

- Use this flashing script, to install libreboot:
- $ sudo ./flash i945apple_firstflash bin/YOURBOARD/YOURROM + + Warning: this guide will not instruct the user how to backup the original Apple EFI firmware. + For that, please refer to http://www.coreboot.org/Board:apple/macbook21. +

-

- You should also see within the output the following:
- "Verifying flash... VERIFIED." -

- -

- If you see that, great! Shut down now (power off). Wait a few seconds and then boot! -

- -

- - If you boot and you see nothing, try turning up the backlight (F2 for macbook21). - + If you are using libreboot_src or git, then make sure that you built the sources first (see ../git/index.html#build).

- -
-

Back to top of page.

- -
- -
- -

X60/X60S/X60T/T60/X200/R400/macbook21: How to flash the ROMs onto your machine (if running libreboot or coreboot already)

- -

- - These instructions work for the Lenovo ThinkPad X60/X60S/X60T/T60 and Apple MacBook2,1. - -

-

- - This assumes that you already have coreboot or libreboot running. - -

-

- - If you have Lenovo BIOS running (X60/X60S/X60T/T60), go to #flashrom_lenovobios instead. - -

-

- - If you have Lenovo BIOS running (X200), go to x200_external.html instead. - -

-

- - If you have Lenovo BIOS running (R400), go to r400_external.html instead. - -

-

- - If you have Apple EFI firmware running (macbook21), go to #flashrom_macbook21 instead. - -

-

- - If you are flashing a Lenovo ThinkPad T60, be sure to read ../hcl/index.html#supported_t60_list. - -

- - If you have an X200 or R400 with libreboot or coreboot already running, note that - the Gbe in the boot flash contains your MAC address. You will need to change the default - MAC address inside the ROM images before flashing a new libreboot image. See - ich9gen for details. - - Another important note about the X200/R400: even if you do already have libreboot or coreboot, - it is possible for the user to write-protect regions in the flash chip, by modifying - the flash descriptor. If you have locked regions, you will need an external flasher - (see x200_external.html or x200_external.html) - to re-flash those regions. By default, - the X200 and R400 ROM images in libreboot contain a descriptor+gbe with all regions unlocked. - -

-

- - If you are flashing an Apple MacBook2,1, be sure to read the information in ../hcl/index.html#macbook21. - + Look at the list of ROM images to see which image is compatible with your device.

+

- If you are using libreboot_src or git, then make sure that you built the sources first (see ../git/index.html#build). + Use this flashing script, to install libreboot:
+ $ sudo ./flash i945apple_firstflash yourrom.rom

-

- Look at #rom to see which ROM is suitable for your machine. Alternative you may be using your own - custom ROM. Adapt. -

-

- Flash the ROM:
- $ sudo ./flash update bin/YOURBOARD/YOURROM -

-

- If you are sure that you are flashing the correct image but you get the error - This coreboot image (LENOVO:ThinkPad X60) does not appear to be correct for the detected mainboard (Lenovo:ThinkPad X60 / X60s / X60t) or - similar (if it's a different board), then do: -
- $ sudo ./flash forceupdate bin/YOURBOARD/YOURROM -

- You should see "Verifying flash... VERIFIED." written at the end of the flashrom output. SHUT DOWN - after you see this, and then boot up again after a few seconds. + You should also see within the output the following:
+ "Verifying flash... VERIFIED."

- - If you boot and you see nothing, try turning up the backlight (Fn+Home for X60/X60S/X60T/T60/X200, F2 for macbook21). - + Shut down.

-

- Some thinkpads come with WWAN cards installed, along with sim cards. These use non-free firmware and should be removed. - You might also want to remove bluetooth. See ../security/x60_security.html and - ../security/t60_security.html. -

- -

Back to top of page

+

Back to top of page.

diff --git a/docs/install/r400_external.html b/docs/install/r400_external.html index 9d477a9..992d618 100644 --- a/docs/install/r400_external.html +++ b/docs/install/r400_external.html @@ -105,6 +105,10 @@ POMONA 5250 (correlate with the BBB guide) Then connect the 3.3v PSU wire (red one) and make sure that everything else is connected.

+ Flashrom binaries for ARM (tested on a BBB) are distributed in libreboot_util. Alternatively, + libreboot also distributes flashrom source code which can be built. +

+

I did (SSH'd into the BBB):
# ./flashrom -p linux_spi:dev=/dev/spidev1.0,spispeed=512
In my case, the output was: diff --git a/docs/install/t60_unbrick.html b/docs/install/t60_unbrick.html index a36f961..62089b1 100644 --- a/docs/install/t60_unbrick.html +++ b/docs/install/t60_unbrick.html @@ -8,14 +8,14 @@ @import url('../css/main.css'); - Libreboot documentation: Unbricking the ThinkPad T60 + ThinkPad T60: Recovery guide

-

Unbricking the ThinkPad T60

-

This guide will show you how to recover from a bad flash that prevents your ThinkPad T60 from booting.

+

ThinkPad T60: Recovery guide

+

This section documents how to recover from a bad flash that prevents your ThinkPad T60 from booting.

Back to previous index

@@ -187,6 +187,11 @@ POMONA 5250:

Connect the pomona from the BBB to the flash chip. No pics unfortunately. (use the text diagram above).

+ +

+ Flashrom binaries for ARM (tested on a BBB) are distributed in libreboot_util. Alternatively, + libreboot also distributes flashrom source code which can be built. +

SSH'd into the BBB:
diff --git a/docs/install/x200_external.html b/docs/install/x200_external.html index e0f2179..8c1df7e 100644 --- a/docs/install/x200_external.html +++ b/docs/install/x200_external.html @@ -132,6 +132,10 @@ chip on those pins? Then connect the 3.3v PSU wire (red one) and make sure that everything else is connected.

+ Flashrom binaries for ARM (tested on a BBB) are distributed in libreboot_util. Alternatively, + libreboot also distributes flashrom source code which can be built. +

+

I did (SSH'd into the BBB):
# ./flashrom -p linux_spi:dev=/dev/spidev1.0,spispeed=512
In my case, the output was: diff --git a/docs/install/x60_unbrick.html b/docs/install/x60_unbrick.html index 1b5056d..6bbe3c5 100644 --- a/docs/install/x60_unbrick.html +++ b/docs/install/x60_unbrick.html @@ -8,14 +8,14 @@ @import url('../css/main.css'); - Libreboot documentation: Unbricking the ThinkPad X60 + ThinkPad X60: Recovery guide

-

Unbricking the ThinkPad X60

-

This guide will show you how to recover from a bad flash that prevents your ThinkPad X60 from booting.

+

ThinkPad X60: Recovery guide

+

This section documents how to recover from a bad flash that prevents your ThinkPad X60 from booting.

Back to previous index

@@ -150,6 +150,11 @@ POMONA 5250: Connecting the BBB and pomona (in this image, an external 3.3v DC PSU was used):

+ +

+ Flashrom binaries for ARM (tested on a BBB) are distributed in libreboot_util. Alternatively, + libreboot also distributes flashrom source code which can be built. +

SSH'd into the BBB:
diff --git a/docs/install/x60tablet_unbrick.html b/docs/install/x60tablet_unbrick.html index 3623482..14339ae 100644 --- a/docs/install/x60tablet_unbrick.html +++ b/docs/install/x60tablet_unbrick.html @@ -8,14 +8,14 @@ @import url('../css/main.css'); - Unbricking the ThinkPad X60 Tablet + ThinkPad X60 Tablet: Recovery guide

-

Unbricking the ThinkPad X60 Tablet

-

This guide will show you how to recover from a bad flash that prevents your ThinkPad X60 Tablet from booting.

+

ThinkPad X60 Tablet: Recovery guide

+

This section documents how to recover from a bad flash that prevents your ThinkPad X60 Tablet from booting.

Back to previous index

@@ -142,7 +142,12 @@ POMONA 5250: Connecting the BBB and pomona (in this image, an external 3.3v DC PSU was used):

- + +

+ Flashrom binaries for ARM (tested on a BBB) are distributed in libreboot_util. Alternatively, + libreboot also distributes flashrom source code which can be built. +

+

SSH'd into the BBB:
# ./flashrom -p linux_spi:dev=/dev/spidev1.0,spispeed=512 -w yourrom.rom -- cgit v0.9.1