Install Canoeboot Free BIOS/UEFI boot firmware

Return to previous index

Migrating from other coreboot distros

Please read the safety guide. Please also read that guide more generally, if installing Canoeboot, as there are several safety pitfalls that you must avoid when flashing this firmware.

libre BIOS/UEFI boot firmware

ALWAYS remember to make a backup of the current flash, when overwriting it, regardless of what firmware you currently have and what firmware you’re re-flashing it with; this includes updates between Canoeboot releases. Use the -r option in flashprog instead -w, to read from the flash.

These documents will teach you how to install Canoeboot, on these devices/motherboards. Canoeboot is a Free Software project that replaces proprietary BIOS/UEFI firmware.

Trouble?

Inquiries can be done via Canoeboot IRC and other channels.

PCI-E rebar

The EDK2-based images work with modern graphics cards, which often lack VGA ROMs these days. Canoeboot recommends use of integrated graphics, where VGA and GOP ROMs are not required.

EDK2 does GOP ROM execution by default, in Canoeboot, when you use a graphics card; it will find the ROM on your card, and execute it. This ROM is non-free, and we’ll have more to say about mitigating that in a little while.

However, we do not enable re-locatable BAR by default. This is required for higher-end modern cards with large amounts of video RAM. Please read the documentation for this.

If in doubt, please just follow the link and enable rebar if you’re using a graphics card.

Now, mitigations:

You can turn on rebar, and avoid use of GOP ROMs on some cards. Refer to the extras page; it contains guidance about use of the Intel GPU (with libgfxinit) for framebuffer, offloading rendering to a graphics card. In some cases, you can do this with the GOP ROM loaded in memory without executing it. Most people will probably just run the GOP ROM via normal EDK2 configuration, as is the default. You are warned about this.

Canoeboot recommends avoiding use of graphics cards entirely. Use integrated graphics, where native (libre) framebuffer initialisation is provided by Canoeboot. The policy here, in Canoeboot, is: respect the user’s choice, while warning them of the consequences. With this paragraph, the user has now been warned quite thoroughly.

SMMSTORE settings

Canoeboot always uses 256KB SMMSTORE, but other coreboot distros can sometimes use 512KB; please overwrite the entire BIOS region / relevant flash section when switching to Canoeboot; do not attempt to retain SMMSTORE. These other projects will, most likely, use completely different flash layouts.

Modern Canoeboot releases provides EDK2 with SMMSTORE on certain boards, but please only follow the notes below if updating from one Canoeboot release to another, otherwise please omit --fmap -i COREBOOT as shown below.

If you’re installing for first time, please also flash the whole image.

If updating from an existing stable Canoeboot release with EDK2, note that you can avoid overwriting your EFI setup config by doing this:

flashprog -p internal --fmap -i COREBOOT -w whatever.rom

This avoids flashing the SMMSTORE section, where your settings are. This is because the EDK2 payload writes settings to that section in the flash.

Conversely, you may reset it thus:

flashprog -p internal --fmap -i SMMSTORE -w whatever.rom

Be very careful with this. Note that fmap exists inside the BIOS region on IFD-based systems.

Laptops

Intel

4th Gen.

3rd -> 2nd Gen.

(Socketed processors are fully compatible with motherboards from different generations)

Core 2

Arm

Chromebooks with U-Boot payload

Games consoles

Servers (x86_64 with ECC support)

Intel

AMD

Opteron 6300

Opteron 4300/4200

Opteron 2000/8000

Desktops/WorkStations (x86/_64)

4th Gen. (Core + Xeon v3)

(5th gen cpus are compatible with some the 4gen boards; C222/4/6 and H/Z97 chipsets https://en.wikipedia.org/wiki/LGA_1150#Haswell_chipsets )

3rd -> 2nd Gen. (Core + Xeon v1-2)

(Processors are fully compatible with motherboards from different generations)

Core 2

Bonnel (Atom) - Intel D945GCLF (Moderate, DDR2) - Intel D510MO and D410PT motherboards (Moderate, DDR2)

Emulation

More information about the Canoeboot build system can be found in the cbmk maintenance manual, and information about porting new systems in the porting manual.

ROM image file names

Modern Canoeboot standardises on EDK2 these days, not SeaBIOS/GRUB which are provided inside EDK2 for backward compatibility but recommended only for legacy use. Please use the edk2_ images provided by modern Canoeboot, where possible as this is much more compatible with modern operating systems.

Canoeboot ROM images are named like this: payload_board_inittype_displaytype_keymap.rom

The payload option can be EDK2, SeaBIOS, GRUB or U-Boot. U-Boot on ARM64 and EDK2 on x86; GRUB and SeaBIOS EFI builds provided for backward compatibility with older releases, inside of the EDK2 build.

Inittype can be libgfxinit, vgarom or normal. The libgfxinit option means coreboot provides native video initialisation, for onboard graphics. The vgarom option means coreboot executes a VGA option ROM for video initialisation. The normal option means coreboot provides no video initialisation, via VGA ROM or native code.

Displaytype can be txtmode or corebootfb - if inittype is normal, this is ignored because txtmode is assumed.

NOTE: modern releases also support fspgop which, semantics aside, works essentially just like libgfxinit_corebootfb.

If payload is seabios instead of seagrub, no keymaps are inserted into flash and only US QWERTY is assumed, otherwise the keymap refers to what is used in GRUB on seagrub payload setups.

If you use a libgfxinit image on a desktop machine, you can still insert a graphics card and it’ll work just fine; its own VGA option ROM will be executed instead, if the primary payload is SeaBIOS, whether that be pure SeaBIOS or a SeaGRUB setup.

Flash lockdown / boot security

This is referred to informally as Secure canoeBoot.

Full flash lockdown is possible, with cryptographic verification of your your operating system kernel that may or may not have come directly from the website, kernel.org, and other files, using special features in the GRUB payload.

See: GRUB hardening / Secure canoeBoot

If you already did this, it’s possible that you may no longer be able to flash internally. If that is the case, you must flash externally.

ThinkPad X200/T400/T500/W500/R400/R500

If you’re running one of these with Lenovo BIOS, you must externally flash Canoeboot, because the original firmware restricts writes to the flash.

There machines all use SOIC8/SOIC16 flash ICs. Refer to pages specifically for each machine:

NOTE: T400S, X200S and X200 Tablet require different steps, because these have WSON8 flash ICs on them, which will require some soldering. Please read the external flashing guide in the section pertaining to WSON.

You can find WSON8 probes online, that are similar to a SOIC8/SOIC16 clip. Your mileage may very, but WSON8 has the same pinout as SOIC8 so you might have some luck with that.

Hot-swap the flash IC with another one while it’s running, and flash it internally.

ThinkPad X220/X220T/T420/T420s/T520

T420/T520: T420 flash instructions

T420s/T520 are similar, in terms of assembly/disassembly.

Now, as for X220/X220 Tablet:

X220/X220 Tablet is essentially the same as the X230, but cannot be flashed internally; you must use an external flasher.

Otherwise, look at X230 disassembly. Note that the X220 has a single 8MB flash, instead of 8MB and 4MB.

ThinkPad X230/T430/T530/W530/X230T

Internal flashing from vendor BIOS to Canoeboot is possible, but not recommended. See: IvyBridge ThinkPad internal flashing.

External flashing recommended, but only documented for X230. See: ThinkPad X230 install guide.

Otherwise, refer to external SPI flashing.

ThinkPad T60/X60/X60Tablet/X60S

Only the Intel GPU is compatible. Do not flash the ATI GPU models.

External flashing guides:

These machines can also be flashed internally, by exploiting a bug in the original Lenovo BIOS. If there’s a BIOS password at boot, you should just flash externally.

Internal flashing instructions:

First, please ensure that your CR2032/CMOS battery is working. This is what powers the SRAM containing BIOS settings, and it powers the real-time clock. It also holds the BUC.TS value - this is what we need.

BUC (Backup Control) register contains a bit called Top Swap (TS). The 64KB bootblock at the top of flash is complemented by a backup Top Swap just above it. The one at the end can’t be flashed internally while Lenovo BIOS is running, but the rest of it can be flashed (everything above the main bootblock).

By setting the TS bit, you can make the machine boot from the backup bootblock.

Download the Canoeboot 20160907 utils archive, and in there you will find these binaries:

You’ll also find the bucts tool. Run it as root:

./bucts 1

Now run both of these as root:

./flashrom_i945_sst -p internal -w coreboot.rom
./flashrom_i945_mx -p internal -w coreboot.rom

You’ll see a lot of errors. This is normal. You should see something like:

Reading old flash chip contents... done.
Erasing and writing flash chip... spi_block_erase_20 failed during command execution at address 0x0
Reading current flash chip contents... done. Looking for another erase function.
spi_block_erase_52 failed during command execution at address 0x0
Reading current flash chip contents... done. Looking for another erase function.
Transaction error!
spi_block_erase_d8 failed during command execution at address 0x1f0000
Reading current flash chip contents... done. Looking for another erase function.
spi_chip_erase_60 failed during command execution
Reading current flash chip contents... done. Looking for another erase function.
spi_chip_erase_c7 failed during command execution
Looking for another erase function.
No usable erase functions left.
FAILED!
Uh oh. Erase/write failed. Checking if anything has changed.
Reading current flash chip contents... done.
Apparently at least some data has changed.
Your flash chip is in an unknown state.

If you see this, rejoice! It means that the flash was successful. Please do not panic. Shut down now, and wait a few seconds, then turn back on again.

The main bootblock still isn’t flashed, but you can shut down, wait a few seconds and boot up again. When you do, you’ll have Canoeboot. Please make sure to flash a second time, like so:

flashprog -p internal -w coreboot.rom

Canoeboot recommends flashprog now, which is a fork of flashrom, but we used flashrom in the 2016 release. The macronix/ssh flashrom binaries there are specifically patched; check the Canoeboot 20160907 source code for the actual patches. The patches modify some flash chip definitions in flashrom, to exploit the bug in Lenovo BIOS enabling internal flashing.

You must ensure that the second flash is performed, upon reboot, because otherwise if the CR2032 battery dies, bucts will be reset and it will no longer boot.

When you’ve done the second flash, which includes overwriting the main bootblock, set bucts back to zero:

./bucts 0

The second flash can be done by simply following the general internal flashing guide further down on this page.

ARM-based Chromebooks

See: Chromebook flashing instructions

NOTE: The generic flashing instructions (later on this page) apply only to the x86 machines, because the Chromebooks still use flashrom with the -p host argument instead of -p internal when flashing, and you typically need to flash externally, due to Google’s security model.

QEMU (arm64 and x86)

Canoeboot can be used on QEMU (virtual machine), which is useful for debugging payloads and generally trying out Canoeboot, without requiring real hardware.

See: Canoeboot QEMU guide

The Canoeboot version of this page is: https://canoeboot.org/docs/install/

Markdown file for this page: https://canoeboot.org/docs/install/index.md

Site map

This HTML page was generated by the Canoeboot Static Site Generator.

Canoeboot is discontinued. A new project was created: RBoot project, a fully free UEFI firmware distribution based on coreboot. RBoot is Canoeboot continued under a new name, with the same maintainer. The canoeboot website and release sources shall be preserved for historical purposes.