title: Retroboot installation manual ...

This section relates to installing Retroboot on supported targets. NOTE: This only applies to the Git repository. Efforts are made to keep these instructions compatible with release archives, BUT: if you are using a release archive instead of the Git repository, please instead refer to the documentation included in that release archive! This applies to all documentation on Retroboot's website, for the most part, but especially the install guides! Retroboot is a very young project and, as such, it is constantly evolving.

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

Flashing via software methods, on system:

ThinkPad X200/X200S/X200T if already running Retroboot/Libreboot
ThinkPad X220/T420/T420S if already running Retroboot with Neutered ME and ifdtool-unlocked regions
ThinkPad X230/X230T if already running Retroboot with Neutered ME and ifdtool-unlocked regions
ThinkPad X60/X60S/X60T/T60 with Mobility Radeon X1400 (if already running Retroboot/coreboot)
ThinkPad X60/X60S/X60T/T60 with Mobility Radeon X1400 (if running Lenovo BIOS)

Setting up programmers, for external SPI flashing

Raspberry Pi Setup (ISP - In System Programming)

Flashing via hardware methods, on system:

Installing Retroboot onto ThinkPad X200S or X200 Tablet {#x200st}

Flash the same ROM image for X200 on your X200S or X200 Tablet. They are the same boards.

These laptops use WSON8 form factory for the NOR flash. It must be de-soldered, and replaced with a SO8/SOIC8 NOR flash.

X200S/X200Tablet not yet fully documented on Retroboot for external flash, but Leah Rowe has videos on her YouTube channel showing how to have Libreboot on these. First, watch this video:

https://www.youtube.com/watch?v=tguch_iPBZQ

Then watch this video:

https://www.youtube.com/watch?v=MxMKJsg5IEU

Use youtube-dl to download these video, if you wish to avoid non-free JavaScript on youtube.com. The Retroboot project is currently setting up a video hosting site, which will run GNU MediaGoblin. However, this website is not yet available to the public.

The plan is to, over time, host all Retroboot related videos there. A separate virtual host is also being configured an that server, for Libreboot videos linked on libreboot.org.

When you have installed Retroboot on your X200S or X200 Tablet, using these instructions, internal flashing is possible (unless you flash a ROM with Intel Flash Descriptor that sets flash regions read-only, in which case external flashing is needed again but at that point, a regular SOIC8 test clip can be used rather than having to solder anything).

Most people who flash X200S or X200 Tablet solder 30awg kynar wires directly to the original WSON8, flash it and then de-solder them, and then boot up. This is NOT recommended by the Retroboot project and can in fact ruin your machine. The reason is simple: the WSON8 is a QFN type IC, and is therefore not designed to have modwires on it. You run the risk of causing discontinuity with the QFN/pads and where they lead to on the mainboard, and it means that you are mixing old solder with new solder. Mixing solder chemistries is never a good idea and can lead to cold joints.

Therefore, the Retroboot project recommends that you do it properly, using the instructions in the videos linked above. You will remove the original WSON using a hot air jet, then install the new SOIC8 using regular knife tip.

Use lots of flux! Use quality 60/40 leaded solder (none of that Rohs rubbish).

CPU microcode on Libreboot-compatible targets {#microcode}

Targets from Libreboot (such as X200/T400) contain CPU microcode updates when built using the Retroboot build system. To remove these, use cbfstool e.g.:

cbfstool x200.retroboot.rom remove -n cpu_microcode_blob.bin

Then re-flash. When you do this, and the ROM has libgfxinit in the file name (rather than vgarom), it will be a ROM containing only 100% Free Software, like Libreboot.

Unlike Libreboot, Retroboot does not prohibit binary blobs in its build system. The CPU microcode updates are useful, because they fix bugs in the CPU. For example, power/thermal management is greatly improved on i945 laptops (X60/T60) and virtualization is enabled on GM45 laptops (X200/T400) not to mention, general system stability is greatly increased.

This has other benefits. For instance, Opteron 6300 CPUs are now fully stable on D16 when flashed with a Retroboot ROM, as opposed to Libreboot.

The only binary blobs added, in Retroboot, to systems that come from Libreboot, are:

CPU microcode updates
Vendor-supplied Video BIOS option ROM (on separate ROM images with vgarom in the filename. ROMs with libgfxinit in the file name use native video initialization from coreboot, exactly like Libreboot does)

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

You do not have to build ROM images from the source code. In addition to that, you can also download one of the releases on the download page where pre-compiled ROM images are available. These ROM images are built using the exact same steps as defined in the link above.

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. The entire build system is documented in the Retroboot maintenance manual

General rules about ROM file names:

vesafb means that coreboot starts with a high resolution VESA frame buffer (useful with Tianocore payload or libgfxinit especially when using SeaBIOS with SeaVGABIOS option ROM). When using libgfxinit, this is the most compatible option if you wish to use GNU+Linux or BSD operating systems on Retroboot.
txtmode means that coreboot starts in legacy VGA text mode (useful for legacy OS and text mode applications like memtest86+). This configuration is only recommended in combination with the Video BIOS option ROM (vgarom config mentioned below) but can be used with libgfxinit if you wish to run memtest86+ and FreeDOS will work (but only if you run text mode DOS programs)
vgarom means that a Video BIOS option ROM will be used, supplied by the manufacturer of the target video chipset. In this configuration, libgfxinit in coreboot is disabled. The VBIOS option ROM is usually non-free. This is the most compatible option (recommended with SeaBIOS payload in txtmode configuration, or Tianocore with vesafb configuration); it has full INT10H and mode switching support, so even legacy DOS games will work, and it will enable the use of legacy operating systems (e.g. old Windows versions)
libgfxinit means that native video initialization is used in coreboot. On many targets nowadays, coreboot has native video support and creates a frame buffer. The SeaVGABIOS option ROM (part of SeaBIOS) can use this, to emulate a Video BIOS (but lacks proper INT10H and video mode switching)

Beyond this, the file name of your ROM will contain the name of the machine and the default coreboot payload (GRUB, SeaBIOS, Tianocore etc) in use.

Read the Retroboot maintenance manual

ThinkPad X200/X200S/X200T if already running Retroboot/Libreboot {#gm45}

For X200/X200S/X200T the ROM is the same. The only difference is which ROM you select based on the size of your boot flash (4MiB and 8MiB are most common, or 16MiB is typical if you are replacing the flash because that's the maximum size supported on this machine).

Just use flashrom -p internal on a ROM supplied by the Retroboot project, or a ROM that you built using the Retroboot build system.

Use the -w argument. You can also specify a custom MAC address in the GbE region, by overwriting the default descriptor+GbE region using ich9gen and dd.

For instructions on changing your MAC address and on the ICH9 descriptors in general, refer to the ich9utils page.

Example:

flashrom -p internal -w x200.retroboot.rom

NOTE: This won't work if you flashed with an Intel Flash Descriptor that set the regions read-only in your boot flash.

X60/X60S/X60T/T60: How to update or install retroboot (if you are already running retroboot or coreboot) {#i945}

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.

You can find flashrom under the flashrom/ directory in the Retroboot source code release archives. Build it (from source) using the Retroboot build instructions page.

Updating/changing the X220/T420/T420S ROM if Retroboot already flashed {#x220t420}

This assumes that you unlocked the regions using ifdtool, and ran me_cleaner, when installing Retroboot the first time. Retroboot currently does not provide pre-compiled utilities, but you can download the source code archive of Retroboot from the download page and build these utilities using the instructions at Retroboot build instructions page.

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

For flashing the BIOS region, a custom flash layout file is included at:

resources/coreboot/x220/flash.layout

Retroboot includes 8MiB ROM images for X220, but only the upper 3MiB of it should be flashed, to the upper 3MiB of the flash chip. The low 5MiB of the ROM is all 0xFF which you should not flash; the lower 5MiB on the actual chip contains your Intel Flash Descriptor, GbE and Intel ME regions and it's very important that these do not get overwritten.

Assuming that you compiled flashrom (from Retroboot build system), you can use the followang command to flash your ROM:

sudo ./flashrom/flashrom -l resources/coreboot/x220/flash.layout -i coreboot -w retroboot.rom -p internal

NOTE: X220, T420 and T420S all have the same default region layout, so even though the above specifies a flash layout for X220, the actual flash layout included for T420/T420S are exactly the same in Retroboot. However, please make sure that you are flashing the correct ROM image!

In the above example, retroboot.rom is your 8MiB ROM image. The -i coreboot option specifies that only the coreboot part should be flashed, and the -l argument specifying the flash layout defines that coreboot region as the upper 3MiB of the flash.

If your machine currently has Lenovo BIOS, OR has the default unmodified 5MiB 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

The linked guide instructs you

That's only if you want to also flash the descriptor, ME and/or GbE region. If coreboot/retroboot is already running, you can re-flash internally if using a layout file specifying to flash only the upper 3MiB BIOS region but in that situation if ME is not neutered and/or ME/descriptor region is set read-only you must pass the following parameter as an argument in flashrom: --noverify-all

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}

Retroboot provides separate ROM images for X230 and X230 Tablet. The instructions are the same for both, with the only difference being which ROM you use.

NOTE: Retroboot includes ROMs with 4mb in the file name, but these are for external flashing, for flashing just SPI2 (the 4MiB chip). If you're doing internal flashing (flashrom on OS running on the X230), use the 7mb ROM. The ROM says 7mb in the file name, but the actual file size is 12MiB. This is because the ROM is compiled for the 12MiB of boot flash on your X230, but with CBFS size set to 7MiB. You will flash only the upper 7MiB of that ROM, to the upper 7MiB of the 12MiB boot flash on your X230.

Your X230 has two flash chips: 8MiB for the lower part and 4MiB for the upper part. Combined, this creates 12MiB of flash and this is what flashrom sees when using -p internal.

This guide that you unlocked the regions using ifdtool, and ran me_cleaner, when installing Retroboot the first time. Retroboot currently does not provide pre-compiled utilities, but you can download the source code archive of Retroboot from the download page and build these utilities using the instructions at Retroboot build instructions page.

For X230/X230T you will want to use a layout file in flashrom and only flash the BIOS region, which is the upper 7MiB region on the default descriptor configuration (unless you modified it to change region sizes and or move them); Retroboot provides the option to flash a 4MiB ROM (CBFS size 4MiB) with 3MiB lower section of the BIOS region unused, or a full 7MiB ROM (CBFS size 7MiB) with all of the BIOS region available to you in cbfstool.

The 4MiB ROM files are provided for external flashing, for flashing Retroboot the first time, to make things a little bit simpler (just dump the whole 8MiB NOR flash, run it through me_cleaner and ifdtool --unlock, flash it back, and then flash the 4MiB ROM to the 4MiB NOR flash).

The 7MiB ROM files are provided for internal flashing, after you flashed the first time using the 4MiB ROM externally. You can flash the 7MiB file externally but you have to split the lower 3MiB of the upper of the ROM image, and flash it (using a layout file) to the upper 3MiB of the 8MiB NOR flash. Then you flash the upper 4MiB of that 7MiB ROM, to the 4MiB NOR flash. It's much simpler to just flash the 4MiB ROM to the 4MiB NOR flash, then boot and OS and run flashrom -p internal, with layout file, to flash the 7MiB file since the two flash chips are seen as one big 12MiB "chip" in your operating system.

Seriously. Just use the full 12MiB images marked 7mb and use the included layout file. Instructions are below.

For X230 if flashing a 4MiB ROM (4MiB CBFS size), a custom flash layout file is included here in the Git repository / archive, for internal flashing:

resources/coreboot/x230_4mb/flash.layout

NOTE: you will need to pad the ROM if you wish to flash the 4MiB one. Just flash the 7MiB one please (ROM is actually 12MiB, with first 5MiB being padding).

For X230 if flashing a 7MiB ROM (7MiB CBFS size), a custom flash layout file is included here in the Git repository / archive, for internal flashing:

resources/coreboot/x230_7mb/flash.layout

These layout files, when used, specify that flashrom must only flash a certain region. When using flashrom -p internal running on e.g. GNU+Linux, the 8MiB and 4MiB NOR flash (on the X230 mainboard) are detected as a single, continuous 12MiB of flash, with the 8MiB flash being the lower section and 4MiB NOR flash being in the upper section of what it sees.

Flash the ROM with 7mb in the file name, and use the layout file included in Retroboot to flash just the upper 7MiB of that ROM to the upper 7MiB of the 12MiB boot flash:

sudo ./flashrom/flashrom -l resources/coreboot/x230_7mb/flash.layout -i coreboot -w retroboot.rom -p internal

The -l parameter in flashrom specifies a layout file. In that layout file is specified an arbitrary set of regions. These regions can be within any boundaries you like.

The 7MiB layout file (for ROMs with 7mb in the file name) looks like this, inside:

00000000:004fffff intelstuff
00500000:00bfffff coreboot

These are boundaries in bytes, specified in hexademical.

The -i parameter in flashrom specifies which region (as per the layout file) should be flashed. NOTE: region, in this context, refers to flashrom layout file structure, not regions as defined in the Intel Flash Descriptor. So, -i coreboot specifies that only those boundaries in that ROM are to be flashed within those boundaries of the NOR flash.

BE SURE to flash ONLY the coreboot region, where the contents of the Retroboot ROM is what ends up being flashed there. If you mess this up, you could brick your machine (make it unbootable). The lower 5MiB of your boot flash is the Intel Flash Descriptor, Gbe and ME regions which should NOT be overwritten!

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

ThinkPad X60/X60S/X60T/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.

index.md 22 KB Permalink History Raw