---
title: Retroboot installation manual
...

This section relates to installing Retroboot on supported targets.

NOTE: if running `flashrom -p internal` for software based flashing, and you
get an error related to `/dev/mem` access, you should reboot with
`iomem=relaxed` kernel parameter before running flashrom, or use a kernel that
has `CONFIG_STRICT_DEVMEM` not enabled.

General information
-------------------

-   [What systems are compatible with Retroboot?](../hardware/)
-   [Information about Retroboot ROM images](#rom)

Flashing via software methods, on system:
-----------------------------------------

-   [ThinkPad X220 if already running Retroboot with Neutered ME and ifdtool-unlocked regions](#x220)
-   [ThinkPad X230/X230T if already running Retroboot with Neutered ME and ifdtool-unlocked regions](#x230)
-   [ThinkPad T60 with Mobility Radeon X1400 (if already running Retroboot/coreboot)](#t60)
-   [ThinkPad T60 with Mobility Radeon X1400 (if running Lenovo BIOS)](#flashrom_lenovobios)

Setting up programmers, for external SPI flashing 
-------------------------------------------------

-   [Raspberry Pi Setup](rpi_setup.md) (ISP - In System Programming)

Flashing via hardware methods, on system:
-----------------------------------------

-   [ThinkPad T60 with Mobility Radeon X1400 PCI ID 1002:7145](t60_unbrick.md)
-   [ThinkPad X220](x220_external.md)
-   [ThinkPad X230/X230T](x230_external.md)

Information about Retroboot ROM images {#rom}
======================================

When ROM images are provided, by the Retroboot build system, they appear under
the `bin/` directory.

[How to compile Retroboot ROM images](../git/)

When releases are made available, it will not be necessary to compile from
source. Instead, the Retroboot project will provide release archives containing
pre-compiled ROM images, utilities and, for GNU GPL compliance, source code
(though we recommend working on the Git repository, where the source code
release archives are mainly intended as a *reference* corresponding to the
released binaries).

If you wish to help with Retroboot development (for instance, adding a board
to Retroboot that you have, which has coreboot support, and maintaining support
for it in Retroboot), you should first familiarize yourself with the Retroboot
build system.

[Read the Retroboot maintenance manual](../maintain/)

How to update or install retroboot (if you are already running retroboot or coreboot) {#t60}
=================================================================================================

Just use `flashrom -p internal` when flashing T60 if you already have
a Retroboot/Libreboot/Coreboot ROM with the upper 64KiB bootblock flashed
(either externally, or as a result of using the Libreboot 20160907 install
scripts for *first flash* and *second flash* (see below on this page).

Example:

    flashrom -p internal -w t60.retroboot.rom

If flashrom complains about multiple chips detected, just do what it says
and use the `-c` option to pick a chip. If it fails, pick another one.

Updating/changing the X220 ROM if Retroboot already flashed {#x220}
=========================================================================

This assumes that you unlocked the regions using ifdtool, and ran me\_cleaner,
when installing Retroboot the first time.

For X220 you will want to use a layout file in flashrom and only flash the
BIOS region, which is the upper 2MiB region on the default descriptor
configuration (unless you modified it to change region sizes and or move them).

For X220, a custom flash layout file in included at:

    resources/coreboot/x220/flash.layout

You need to pad the 2MiB X220 ROMs provided by Retroboot to 8MiB in size, with
the contents of the 2MiB Retroboot ROM at the end of the file. If you have your
6MiB neutered+unlocked dump of the descriptor+GbE+ME region (neutered using
the `me_cleaner` utility and regions unlocked using `ifdtool --unlock` as in
the original X230 install guide when you flashed externally) you could do:

    cat 6mb.dump 2mb.retroboot.rom > 8mb.descriptor.me.gbe.bios

In this example, `6mb.dump` is the neutered+unlocked dump of your original ME,
descriptor and GbE region. 2mb.retroboot.rom is the Retroboot ROM that you wish
to flash. 8mb.descriptor.me.gbe.bios will be a file containing both, joined in
to a single 8MiB file.

Alternatively, you could just create the 8mb file by doing:

    dd if=/dev/zero bs=6M count=1 of=6mb.zero

Flash your ROM like like so (if you were in the Retroboot Git repository):

    sudo ./flashrom/flashrom -l resources/coreboot/x220/flash.layout -i coreboot -w 8mb.descriptor.me.gbe.bios -p internal

(use the flash.layout file at `resources/coreboot/x220/flash.layout` for the
above command)

BE SURE to flash ONLY the 2MiB region, where the contents of the 2MiB Retroboot
ROM is what ends up being flashed there. If you mess this up, you could brick
your machine (make it unbootable).

The above flashrom command for X220 will flash *only* the BIOS region.
The file `newretrobootrom.rom` could be a new Retroboot ROM, if you're updating
to a new version, or it could be that you are switching to a different ROM
configuration on the same version of retroboot. So long as its a coreboot image
with flash size set to 8MiB, CBFS size set to 2MiB or lower and the 2MiB
coreboot part spliced out after coreboot was built (e.g. using dd the way
the Retroboot build system does it when building ROMs. See ROM building scripts
under `resources/scripts/build/roms/` for how Retroboot does it: it builds
8MiB coreboot ROMs but everything below the upper 2MiB is 0xFF and the upper
2MiB is the coreboot ROM with CBFS size to 2MiB size, on Retroboot ROMs).

If your X220 currently has Lenovo BIOS, OR has the default unmodified 6MiB
descriptor+gbe+me in the 8MiB flash chip then you will need to re-flash
externally using this guide:

[How to flash ThinkPad X220 externally](x220_external.md)

However you decided to flash, flashrom will say `VERIFIED` if it was a
successful flash. After you flash, and it says VERIFIED, turn off the system,
wait a few seconds and then boot up again. If it didn't say VERIFIED, unless
othewise stated by this documentation, you should NOT turn off your system and
seek immediate help, for it may brick if you turn it off, so it may need to be
fixed. (unless flashrom didn't actually do anything because you typo'd the
command or something, like specifying a non-existing ROM on your file system)


Updating/changing the X230/X230T ROM if Retroboot already flashed {#x230}
=========================================================================

This assumes that you unlocked the regions using ifdtool, and ran me\_cleaner,
when installing Retroboot the first time.

For X230/X230T you will want to use a layout file in flashrom and only flash the
BIOS region, which is the upper 4MiB region on the default descriptor
configuration (unless you modified it to change region sizes and or move them).

For X230, a custom flash layout file in included at:

    resources/coreboot/x230/flash.layout

You need to pad the 4MiB X230 ROMs provided by Retroboot to 12MiB in size, with
the contents of the 4MiB Retroboot ROM at the end of the file. If you have your
8MiB neutered+unlocked dump of the descriptor+GbE+ME region (neutered using
the `me_cleaner` utility and regions unlocked using `ifdtool --unlock` as in
the original X230 install guide when you flashed externally) you could do:

    cat 8mb.dump 4mb.retroboot.rom > 12mb.descriptor.me.gbe.bios

In this example, `8mb.dump` is the neutered+unlocked dump of your original ME,
descriptor and GbE region. 4mb.retroboot.rom is the Retroboot ROM that you wish
to flash. 12mb.descriptor.me.gbe.bios will be a file containing both, joined in
to a single 12MiB file.

Alternatively, you could just create the 8mb file by doing:

    dd if=/dev/zero bs=8M count=1 of=8mb.zero

Flash your ROM like like so (if you were in the Retroboot Git repository):

    sudo ./flashrom/flashrom -l resources/coreboot/x230/flash.layout -i coreboot -w 12mb.descriptor.me.gbe.bios -p internal

(use the flash.layout file at `resources/coreboot/x230/flash.layout` for the
above command)

BE SURE to flash ONLY the 4MiB region, where the contents of the 4MiB Retroboot
ROM is what ends up being flashed there. If you mess this up, you could brick
your machine (make it unbootable).

The above flashrom command for X230 will flash *only* the BIOS region.
The file `newretrobootrom.rom` could be a new Retroboot ROM, if you're updating
to a new version, or it could be that you are switching to a different ROM
configuration on the same version of retroboot. So long as its a coreboot image
with flash size set to 12MiB, CBFS size set to 4MiB or lower and the 4MiB
coreboot part spliced out after coreboot was built (e.g. using dd the way
the Retroboot build system does it when building ROMs. See ROM building scripts
under `resources/scripts/build/roms/` for how Retroboot does it: it builds
12MiB coreboot ROMs but everything below the upper 4MiB is 0xFF and the upper
4MiB is the coreboot ROM with CBFS size to 4MiB size, on Retroboot ROMs).

If your X230 currently has Lenovo BIOS, OR has the default unmodified 8MiB
descriptor+gbe+me in SPI1 (8MiB flash chip) you will need to re-flash
externally using this guide:

[How to flash ThinkPad X230 externally](x230_external.md)

However you decided to flash, flashrom will say `VERIFIED` if it was a
successful flash. After you flash, and it says VERIFIED, turn off the system,
wait a few seconds and then boot up again. If it didn't say VERIFIED, unless
othewise stated by this documentation, you should NOT turn off your system and
seek immediate help, for it may brick if you turn it off, so it may need to be
fixed. (unless flashrom didn't actually do anything because you typo'd the
command or something, like specifying a non-existing ROM on your file system)

ThinkPad X60/T60: Initial installation guide (if running the proprietary firmware) {#flashrom_lenovobios}
==================================================================================

For now, no integration exists in Retroboot for the first and second flash
(you need to flash twice, when flashing from LenovoBIOS to Retroboot). Go
and download the Libreboot 20160907 util release archive from
<https://libreboot.org/> and follow the instructions on the Libreboot website:

<https://libreboot.org/docs/install/#flashrom_lenovobios>

NOTE: The libreboot website doesn't tell you to back up your Lenovo BIOS, but
you *should*. Do it using this flashrom command:

    sudo flashrom -p internal -r factory.bin

A 2MiB file named `factory.bin` will have been created. If flashrom complained
about multiple flash chips detected, just do what it says and pick one using
the `-c` option.

Libreboot supports T60/X60 that has Intel GPU, whereas Retroboot supports T60
that has ATI GPU.

However, the procedure for flashing Retroboot on your T60 when you have ATI
GPU and you're running Lenovo BIOS, is exactly the same as when you have an
Intel T60 and flashing Libreboot from Lenovo BIOS.

Imagine that you're flashing Libreboot on a T60 that has Intel GPU, and follow
the instructions on that libreboot page, *but* use the T60 ROM that you compiled
in the Retroboot build system. That T60 ROM has an ATOMBIOS VGA option ROM
for the ATI Mobility Radeon X1400 GPU, and uses the SeaBIOS payload.

MacBook2,1: Initial installation guide (if running the proprietary firmware) {#flashrom_macbook21}
============================================================================

*If you have a MacBook1,1, refer to
[../hardware/\#information-about-the-macbook11](../hardware/#information-about-the-macbook11) for flashing instructions.*

*This is for the MacBook2,1 while running Apple EFI firmware. If you
already have coreboot or retroboot running, then go to
[\#flashrom](#flashrom) instead!*

Be sure to read the information in
[../hardware/\#information-about-the-macbook21](../hardware/#information-about-the-macbook21).

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

*If you are using retroboot\_src or git, then make sure that you built
the sources first (see [../git/\#build](../git/#build)).*

Look at the [list of ROM images](#rom) to see which image is compatible
with your device.

Use this flashing script, to install retroboot:

`$ sudo ./flash i945apple_firstflash `[`yourrom.rom`](#rom)

You should also see within the output the following:

    Verifying flash... VERIFIED.

Shut down.

Copyright © 2014, 2015, 2016 Leah Rowe <info@minifree.org>\

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License Version 1.3 or any later
version published by the Free Software Foundation
with no Invariant Sections, no Front Cover Texts, and no Back Cover Texts.
A copy of this license is found in [../fdl-1.3.md](../fdl-1.3.md)
