# Installing libreboot

This section relates to installing libreboot on supported targets.

Back to previous index

## Setting up external programmers

- Setup the BeagleBone Black as an SPI flashrom programmer

## Installing libreboot (software)

- QEMU
- Recommended ROMs to flash
- X60/X60S/X60T/T60: How to flash your ROM (if running Lenovo BIOS firmware)
- macbook21: How to flash your ROM (if running Apple EFI firmware)
- X60/X60S/X60T/T60/X200/macbook21: How to flash your ROM (if running libreboot or coreboot already)

## Installing libreboot (hardware)

- ThinkPad X60/X60S: How to unbrick
- ThinkPad X60 Tablet: How to unbrick
- ThinkPad T60: How to unbrick
- ThinkPad X200: How to unbrick (also the initial installation guide for this machine)

# QEMU

You don't really do anything here, just run (example):
$ qemu-system-i386 -M pc -m 512 -bios bin/qemu_i440fx_piix4/qemu_i440fx_piix4_ukdvorak_vesafb.rom -serial stdio
$ qemu-system-i386 -M q35 -m 512 -bios bin/qemu_q35_ich9/qemu_q35_ich9_ukdvorak_vesafb.rom -serial stdio

Back to top of page.

# Recommended ROMs to flash

List of directories corresponding to each board:

- ThinkPad X60, X60s and X60 Tablet: bin/x60/
- ThinkPad T60: bin/t60/ (note, see ../hcl/index.html#supported_t60_list)
- ThinkPad X200: bin/x200_8mb/ (8MiB flash chip) or bin/x200_4mb (4MiB flash chip) (see ../hcl/x200.html)
- Apple MacBook2,1: bin/macbook21/
- Apple MacBook1,1: bin/macbook21/ (it's not a typo; the same ROMs work)

These images use coreboot text-mode graphics:

- US Qwerty keyboard: boardname_usqwerty_txtmode.rom
- UK Qwerty keyboard: boardname_ukqwerty_txtmode.rom
- US Dvorak keyboard: boardname_usdvorak_txtmode.rom
- UK Dvorak keyboard: boardname_ukdvorak_txtmode.rom
- French Azerty keyboard: boardname_frazerty_txtmode.rom
- French Dvorak (BEPO): boardname_frdvbepo_txtmode.rom
- Italian Qwerty keyboard: boardname_itqwerty_txtmode.rom
- Swedish Qwerty keyboard: boardname_svenska_txtmode.rom

These images use coreboot framebuffer graphics:

- US Qwerty keyboard: boardname_usqwerty_vesafb.rom
- UK Qwerty keyboard: boardname_ukqwerty_vesafb.rom
- US Dvorak keyboard: boardname_usdvorak_vesafb.rom
- UK Dvorak keyboard: boardname_ukdvorak_vesafb.rom
- French Azerty keyboard: boardname_frazerty_vesafb.rom
- French Dvorak (BEPO): boardname_frdvbepo_vesafb.rom
- Italian Qwerty keyboard: boardname_itqwerty_vesafb.rom
- Swedish Qwerty keyboard: boardname_svenska_vesafb.rom

The boards for boardname in the examples above can be found by the names of the directories in ./bin/ or ./resources/libreboot/config/.

_txtmode images come with a working MemTest86+ and GRUB Invaders, both of which require text-mode. _vesafb images are recommended in most cases.

This will give you your native keyboard layout inside GRUB. The preferences in your OS are not affected, it just makes using the GRUB command line easier (if you ever need to do that). ../grub/index.html#grub_keyboard shows you how this was done. If your native keyboard layout differs, you can adapt those notes and hack the 'build' script for your needs.

Back to top of page.

# X60/X60S/X60T/T60: How to flash the ROMs onto your machine (if running Lenovo BIOS 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 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.

The following is for the libreboot image and *not* the factory bios dump:

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.

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!

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

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 ./lenovobios_firstflash bin/YOURBOARD/YOURROM.

You should see within the output the following:
"Updated BUC.TS=1 - 64kb address ranges at 0xFFFE0000 and 0xFFFF0000 are swapped".

You should also see within the output the following:
"Flash chip is in an unknown state", "FAILED" and "DO NOT SHUTDOWN OR REBOOT"
Seeing this means that the operation was a resounding success! DON'T PANIC.

See this link for more details: http://thread.gmane.org/gmane.linux.bios.flashrom/575.

If the above is what you see, then SHUT DOWN. Wait a few seconds, and then boot; libreboot is running, but there is a 2nd procedure *needed* (see below).

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

When you have booted up again:
$ sudo ./lenovobios_secondflash bin/YOURBOARD/YOURROM

You should see within the output the following:
"Updated BUC.TS=0 - 128kb address range 0xFFFE0000-0xFFFFFFFF is untranslated"

You should also see within the output the following:
"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)

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.

This is for the MacBook2,1 while running Apple EFI firmware. If you already have coreboot or libreboot running, then go to #flashrom instead!

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.

Flashing is actually easy (compared to X60/T60).
$ sudo flashrom -p internal:laptop=force_I_want_a_brick -w bin/YOURBOARD/YOURROM

Alternatively, a script is provided which does the same thing:
$ sudo ./macbook21_firstflash bin/YOURBOARD/YOURROM

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).

Back to top of page.

# X60/X60S/X60T/T60/X200/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 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 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: 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) to re-flash those regions. By default, the X200 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.

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. Alternative you may be using your own custom ROM. Adapt.

Flash the ROM:
$ sudo ./flash 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 ./forceflash 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.

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

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

Copyright © 2014, 2015 Francis Rowe <info@gluglug.org.uk>
This document is released under the Creative Commons Attribution-ShareAlike 4.0 International Public License and all future versions. A copy of the license can be found at ../license.txt.

This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See ../license.txt for more information.