<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<style type="text/css">
@import url('../css/main.css');
</style>
<title>Installing libreboot</title>
</head>
<body>
<div class="section">
<h1 id="pagetop">Installing libreboot</h1>
<p>
This section relates to installing libreboot on supported targets.
</p>
<p>
<a href="../index.html">Back to previous index</a>
</p>
</div>
<div class="section">
<ul>
</ul>
<h2>Software methods</h2>
<ul>
<li><a href="#rom">List of ROM images in libreboot</a></li>
<li><a href="#flashrom">How to update libreboot (if you are already running libreboot or coreboot)</a></li>
<li><a href="#flashrom_lenovobios">ThinkPad X60/T60: Initial installation guide (if running the proprietary firmware)</a></li>
<li><a href="#flashrom_macbook21">MacBook2,1: Initial installation guide (if running the proprietary firmware)</a></li>
</ul>
<h2>Hardware methods</h2>
<ul>
<li><a href="bbb_setup.html">How to programme an SPI flash chip with the BeagleBone Black</a></li>
<li><a href="x60_unbrick.html">ThinkPad X60: Recovery guide</a></li>
<li><a href="x60tablet_unbrick.html">ThinkPad X60 Tablet: Recovery guide</a></li>
<li><a href="t60_unbrick.html">ThinkPad T60: Recovery guide</a></li>
<li><a href="x200_external.html">ThinkPad X200/X200S/X200T (needed if running the proprietary firmware, or to unbrick)</a></li>
<li><a href="r400_external.html">ThinkPad R400 (needed if running the proprietary firmware, or to unbrick)</a></li>
<li><a href="t400_external.html">ThinkPad T400 (needed if running the proprietary firmware, or to unbrick)</a></li>
<li><a href="t500_external.html">ThinkPad T500 (needed if running the proprietary firmware, or to unbrick)</a></li>
</ul>
</div>
<div class="section">
<h1 id="rom">List of ROM images in libreboot</h1>
<p>
Libreboot supports the following (refer to the <a href="../release.html">release</a> page):
</p>
<ul>
<li>Apple MacBook1,1 and MacBook2,1: download <b>libreboot_macbook21.tar.xz</b></li>
<li>ThinkPad X60, X60s and X60 Tablet: download <b>libreboot_x60.tar.xz</b></li>
<li>ThinkPad T60: download <b>libreboot_t60.tar.xz</b> (see <a href="../hcl/index.html#supported_t60_list">../hcl/index.html#supported_t60_list</a>)</li>
<li>ThinkPad X200: download <b>libreboot_x200_8mb.tar.xz</b> (8MiB flash chip) or <b>libreboot_x200_4mb.tar.xz</b> (4MiB flash chip) (see <a href="../hcl/x200.html">../hcl/x200.html</a>)</li>
<li>ThinkPad R400: download <b>libreboot_r400_8mb.tar.xz</b> (8MiB flash chip) or <b>libreboot_r400_4mb.tar.xz</b> (4MiB flash chip) (see <a href="../hcl/r400.html">../hcl/r400.html</a>)</li>
<li>ThinkPad T400: download <b>libreboot_t400_8mb.tar.xz</b> (8MiB flash chip) or <b>libreboot_t400_4mb.tar.xz</b> (4MiB flash chip) (see <a href="../hcl/t400.html">../hcl/t400.html</a>)</li>
<li>ThinkPad T500: download <b>libreboot_t500_8mb.tar.xz</b> (8MiB flash chip) or <b>libreboot_t500_4mb.tar.xz</b> (4MiB flash chip) (see <a href="../hcl/t500.html">../hcl/t500.html</a>)</li>
</ul>
<p>
The ROM images in each archive use the following naming convention: <b>boardname_keymap_mode.rom</b>
</p>
<p>
Available <i>modes</i>: <b>vesafb</b> or <b>txtmode</b>. The <i>vesafb</i> ROM images are recommended, in most cases;
<i>txtmode</i> ROM images come with MemTest86+, which requires text-mode instead of the usual framebuffer used
by coreboot native graphics initialization.
</p>
<p>
Keymaps are named appropriate/y according to each keyboard layout
support in GRUB. To learn how these keymaps are created, see
<a href="../grub/index.html#grub_keyboard">../grub/index.html#grub_keyboard</a>
</p>
<h2 id="qemu">QEMU</h2>
<p>
Libreboot comes with ROM images built for QEMU, by default:
</p>
<ul>
<li><b>libreboot_qemu_q35_ich9.tar.xz</b></li>
<li><b>libreboot_qemu_i440fx_piix4.tar.xz</b></li>
</ul>
<p>
Examples of how to use libreboot in QEMU:
</p>
<ul>
<li>$ <b>qemu-system-i386 -M q35 -m 512 -bios qemu_q35_ich9_keymap_mode.rom</b></li>
<li>$ <b>qemu-system-i386 -M pc -m 512 -bios qemu_i440fx_piix4_keymap_mode.rom</b></li>
</ul>
<p>
You can optionally specify the <b>-serial stdio</b> argument, so that QEMU will emulate
a serial terminal on the standard input/output (most likely your terminal emulator or TTY).
</p>
<p>
Other arguments are available for QEMU. The manual will contain more information.
</p>
<p>
On GM45 hardware (with libreboot), make sure that the <i>kvm</i> and <i>kvm_intel</i> kernel modules
are not loaded, when using QEMU.
</p>
<p>
<a href="#pagetop">Back to top of page.</a>
</p>
</div>
<div class="section">
<h1 id="flashrom">How to update libreboot (if you are already running libreboot or coreboot)</h1>
<p>
On all current targets, updating libreboot can be accomplished without disassembly and,
therefore, without having to externally re-flash using any dedicated hardware. In other words,
you can do everything entirely in software, directly from the OS that is running on your libreboot
system.
</p>
<div class="important">
<p>
<b>If you are using libreboot_src or git, then make sure that you built the sources first (see <a href="../git/index.html#build">../git/index.html#build</a>).</b>
</p>
</div>
<p>
Look at the <a href="#rom">list of ROM images</a> to see which image is compatible with your device.
</p>
<h2>Are you currently running the original, proprietary firmware?</h2>
<p>
If you are currently running the proprietary firmware (not libreboot or coreboot),
then the flashing instructions for your system are going to be different.
</p>
<p>
X60/T60 users running the proprietary firmware should refer to <a href="#flashrom_lenovobios">#flashrom_lenovobios</a>.
MacBook2,1 users running Apple EFI should refer to <a href="#flashrom_macbook21">#flashrom_macbook21</a>
</p>
<p>
X200 users, refer to <a href="x200_external.html">x200_external.html</a>,
R400 users refer to <a href="r400_external.html">r400_external.html</a>,
T400 users refer to <a href="t400_external.html">t400_external.html</a>,
T500 users refer to <a href="t500_external.html">t500_external.html</a>
</p>
<h2>Are you currently running libreboot (or coreboot)?</h2>
<p>
X60/T60 users should be fine with this guide. If you write-protected the flash chip, please refer to
<a href="x60_unbrick.html">x60_unbrick.html</a>, <a href="x60tablet_unbrick.html">x60tablet_unbrick.html</a>
or <a href="t60_unbrick.html">t60_unbrick.html</a>. <i>This probably does not apply to you. Most people
do not write-protect the flash chip, so you probably didn't either.</i>
</p>
<p>
Similarly, it is possible to write-protect the flash chip in coreboot or libreboot on GM45 laptops
(X200/R400/T400/T500). If you did this, then you will need to use the links above for flashing,
treating your laptop as though it currently has the proprietary firmware (because write-protected SPI flash
requires external re-flashing, as is also the case when running the proprietary firmware).
</p>
<p>
If you did not write-protect the flash chip, or it came to you without any write-protection
(<b><i>libreboot does not write-protect the flash chip by default, so this probably applies to you</i></b>),
read on!
</p>
<h2>MAC address on GM45 (X200/R400/T400/T500)</h2>
<p>
<b>Users of the X200/R400/T400/T500 take note:</b> The MAC address for the onboard ethernet chipset
is located inside the flash chip. Libreboot ROM images for these laptops contain a generic MAC
address by default (00:F5:F0:40:71:FE), but this is not what you want.
<i>Make sure to change the MAC address inside the ROM image, before flashing it.
The instructions on <a href="../hcl/gm45_remove_me.html#ich9gen">../hcl/gm45_remove_me.html#ich9gen</a>
show how to do this.</i>
</p>
<p>
It is important that you change the default MAC address, before flashing. It will be printed on a sticker
at the bottom of the laptop, or it will be printed on a sticker next to or underneath the RAM. Alternatively,
and assuming that your current firmware has the correct MAC address in it, you can get it from your OS.
</p>
<h2>All good?</h2>
<p>Excellent! Moving on...</p>
<p>
Download the <i>libreboot_util.tar.xz</i> archive, and extract it. Inside, you will find
a directory called <i>flashrom</i>. This contains statically compiled executable files of
the <i>flashrom</i> utility, which you will use to re-flash your libreboot system.
</p>
<p>
Simply use <i>cd</i> on your terminal, to switch to the <i>libreboot_util</i> directory. Inside,
there is a script called <i>flash</i>, which will detect what CPU architecture you have
(e.g. i686, x86_64) and use the appropriate executable. It is also possible for you to
build these executables from the libreboot source code archives.
</p>
<div class="important">
<p>
How to update the flash chip contents:<br/>
$ <b>sudo ./flash update <a href="#rom">yourrom.rom</a></b>
</p>
</div>
<div class="important">
<p>
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:<br/>
$ <b>sudo ./flash forceupdate <a href="#rom">yourrom.rom</a></b>
</p>
</div>
<div class="important">
<p>
You should see <b>"Verifying flash... VERIFIED."</b> written at the end of the flashrom output. <b>Shut down</b>
after you see this, and then boot up again after a few seconds.
</p>
</div>
<p><a href="#pagetop">Back to top of page</a></p>
</div>
<div class="section">
<h1 id="flashrom_lenovobios">ThinkPad X60/T60: Initial installation guide (if running the proprietary firmware)</h1>
<p><b>This is for the ThinkPad X60 and T60 while running Lenovo BIOS. If you already have coreboot or libreboot running,
then go to <a href="#flashrom">#flashrom</a> instead!</b></p>
<p><b>If you are flashing a Lenovo ThinkPad T60, be sure to read <a href="../hcl/index.html#supported_t60_list">../hcl/index.html#supported_t60_list</a></b></p>
<div class="important">
<p>
<b>If you are using libreboot_src or git, then make sure that you built the sources first (see <a href="../git/index.html#build">../git/index.html#build</a>).</b>
</p>
</div>
<p>
<b>
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 <a href="http://www.coreboot.org/Board:lenovo/x60/Installation">http://www.coreboot.org/Board:lenovo/x60/Installation</a>.
</b>
</p>
<div class="important">
<p>
The first half of the procedure is as follows:<br/>
$ <b>sudo ./flash i945lenovo_firstflash <a href="#rom">yourrom.rom</a>.</b>
</p>
</div>
<div class="important">
<p>
You should see within the output the following:<br/>
<b>"Updated BUC.TS=1 - 64kb address ranges at 0xFFFE0000 and 0xFFFF0000 are swapped"</b>.
</p>
<p>
You should also see within the output the following:<br/>
<b>"Flash chip is in an unknown state"</b>, <b>"FAILED"</b> and <b>"DO NOT SHUTDOWN OR REBOOT"</b><br/>
Seeing this means that the operation was a <b>resounding</b> success! <b>DON'T PANIC</b>.
</p>
<p>
See this link for more details:
<a href="http://thread.gmane.org/gmane.linux.bios.flashrom/575">http://thread.gmane.org/gmane.linux.bios.flashrom/575</a>.
</p>
<p>
If the above is what you see, then <b>SHUT DOWN</b>. Wait a few seconds, and then boot; libreboot is running, but there is a 2nd procedure <b>*needed*</b> (see below).
</p>
</div>
<div class="important">
<p>
When you have booted up again, you must also do this:<br/>
$ <b>sudo ./flash i945lenovo_secondflash <a href="#rom">yourrom.rom</a></b>
</p>
</div>
<div class="important">
<p>
You should see within the output the following:<br/>
<b>"Updated BUC.TS=0 - 128kb address range 0xFFFE0000-0xFFFFFFFF is untranslated"</b>
</p>
<p>
You should also see within the output the following:<br/>
<b>"Verifying flash... VERIFIED."</b>
</p>
</div>
<p><a href="#pagetop">Back to top of page.</a></p>
</div>
<div class="section">
<h1 id="flashrom_macbook21">MacBook2,1: Initial installation guide (if running the proprietary firmware)</h1>
<div class="important">
<p>
<b>If you have a MacBook1,1, refer to <a href="../hcl/index.html#macbook11">../hcl/index.html#macbook11</a> for flashing instructions.</b>
</p>
</div>
<p>
<b>
This is for the MacBook2,1 while running Apple EFI firmware. If you already have
coreboot or libreboot running, then go to <a href="#flashrom">#flashrom</a> instead!
</b>
</p>
<p>
Be sure to read the information in <a href="../hcl/index.html#macbook21">../hcl/index.html#macbook21</a>.
</p>
<p>
<b>
Warning: this guide will not instruct the user how to backup the original Apple EFI firmware.
For that, please refer to <a href="http://www.coreboot.org/Board:apple/macbook21">http://www.coreboot.org/Board:apple/macbook21</a>.
</b>
</p>
<div class="important">
<p>
<b>If you are using libreboot_src or git, then make sure that you built the sources first (see <a href="../git/index.html#build">../git/index.html#build</a>).</b>
</p>
</div>
<p>
Look at the <a href="#rom">list of ROM images</a> to see which image is compatible with your device.
</p>
<div class="important">
<p>
Use this flashing script, to install libreboot:<br/>
$ <b>sudo ./flash i945apple_firstflash <a href="#rom">yourrom.rom</a></b>
</p>
</div>
<div class="important">
<p>
You should also see within the output the following:<br/>
<b>"Verifying flash... VERIFIED."</b>
</p>
<p>
Shut down.
</p>
</div>
<p><a href="#pagetop">Back to top of page.</a></p>
</div>
<div class="section">
<p>
Copyright © 2014, 2015 Francis Rowe <info@gluglug.org.uk><br/>
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 <a href="../cc-by-sa-4.txt">../cc-by-sa-4.txt</a>.
</p>
<p>
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 <a href="../cc-by-sa-4.txt">../cc-by-sa-4.txt</a> for more information.
</p>
</div>
</body>
</html>