coreboot

coreboot logo

What is coreboot?

coreboot is a free software BIOS we use on our laptops. For PureBoot, Heads is loaded as the coreboot payload. We also offer coreboot/SeaBIOS, which provides a traditional BIOS boot environment using SeaBIOS. This document provides information about updating using our coreboot utility and build instructions.

coreboot is a modern, lightweight, open-source replacement for the proprietary (usually UEFI) system firmware shipped on most PCs/laptops today. It is designed to perform only the minimum number of tasks necessary to initialize the hardware, and pairs with a coreboot payload (such as SeaBIOS) to boot a modern operating system such as PureOS (see the PureOS home page) as quickly as possible. It brings increased performance and security, avoiding widespread security issues (see What the CIA Vault 7 documents mean, follow-up posts #1, #2, #3, etc.), and provides the foundation for our new PureBoot firmware, which offers a tamper-resistant boot process via Heads and a Librem Key.

Since the summer of 2017, Purism has shipped coreboot firmware (featuring SeaBIOS as the payload) on all Librem laptops. We also offer an easy to use coreboot update/flashing script for all Librem models, including those older models which didn’t ship with coreboot. This script allows you to update the firmware on your Librem, using either a pre-built binary firmware update image or compiling from source. Pre-built images for our PureBoot firmware are available as well. The script uses only files available from public Purism repositories, and performs numerous checks to ensure the integrity of the downloaded/compiled firmware update all the way through the flashing process.

Since coreboot initializes the bare metal hardware, it must be tailored specifically to every chipset and motherboard — and so each Librem model has its own unique build. You can track our progress through our contributions to coreboot, our coreboot timeline of long-term involvement with the coreboot project, and our Freedom roadmap. And remember to keep things in perspective!

Note

If you have an older model Librem which shipped with proprietary AMI firmware, and your OS was installed in UEFI mode, you will need to reinstall it after, or migrate it before flashing our coreboot image (see “Migrating a UEFI-based install” below).

Using the Coreboot Utility/Update Script

Purism offers an easy-to-use coreboot update script, which provides precompiled images of coreboot/SeaBIOS and PureBoot and can build coreboot/SeaBIOS from source.

A few preliminary notes:

  • coreboot/SeaBIOS users should run the coreboot utility script on the Librem being updated. PureBoot users can run the script anywhere to download the update, including in a container or VM, and then apply the update from PureBoot.

  • On some chipsets, you may need to add iomem=relaxed to the grub kernel boot parameters for flashrom to read/write the firmware

  • Before flashing the firmware, make sure your battery is charged, and connect AC power if possible. Do not interrupt the process – do not suspend or shut down the machine, do not close the lid, do not close the terminal. Otherwise, you risk bricking the device

Full documentation for the coreboot utility script can be found in the README at https://source.puri.sm/firmware/utility, but here’s the TL;DR: simply open a terminal and run the following commands:

mkdir ~/updates
cd ~/updates
wget https://source.puri.sm/firmware/utility/raw/master/coreboot_util.sh -O coreboot_util.sh
sudo bash ./coreboot_util.sh

The script will check for basic dependencies (which are documented in above README), then present a menu with several options:

################################################
##       Purism Librem coreboot Utility
################################################
#    Device: Librem 14
#    Serial: 123456789
#  Firmware: Standard (coreboot+SeaBIOS)
#   Version: 24.02.01-Purism-1 (05/14/2024)
################################################
#
#  1) Update firmware
#  2) Switch to a different firmware
#  3) Prepare firmware for manual flash
#  4) Configure serial number
#  5) Configure boot order
#
################################################

Enter your choice (1-5) or Q to quit:

If you downgrade for any reason, please note the earliest versions supporting each board revision. For later board revisions like Librem 14 v1-02, do not downgrade below the minimum version supporting that revision.

Model/Revision

Minimum coreboot/SeaBIOS

Minimum PureBoot

Librem 13 v1

4.7-Purism-1

–

Librem 15 v2

4.7-Purism-5

–

Librem 13 v2

4.7-Purism-1

Beta 2

Librem 13 v3

4.7-Purism-4

Beta 2

Librem 15 v3

4.7-Purism-1

Beta 2

Librem 13 v4

4.8.1-Purism-4

Beta 2

Librem 15 v4

4.8.1-Purism-4

Beta 2

Librem Mini v1

4.12-Purism-2

Beta 13

Librem L1UM v2

4.19-Purism-2

Release 26

Librem Mini v2

4.12-Purism-4

Release 15

Librem 14 v1-01

4.13-Purism-1

Release 17

Librem 14 v1-02

4.21-Purism-3

Release 28.2

Librem 11

4.21-Purism-2

Release 28.1

Update Firmware

This function updates the firmware on your device using the same firmware type and configuration.

For coreboot/SeaBIOS, you can either download a pre-built ROM or build the update from source:

How would you like to obtain the update?

1 - Download precompiled build
2 - Build from source

Enter your choice (default 1):

Both selections will result in the same update. Building from source takes longer but allows you to reproduce the same ROM from source code.

For coreboot/SeaBIOS firmware, the script will prompt you to flash the update. For PureBoot firmware, the script will prompt you to copy the update to USB and to update via the PureBoot menu.

Flashing: [##################################################-] (100%)
Verifying flash contents. Please wait...
The flash contents were verified and the image was flashed correctly.


You must reboot for the coreboot update to take effect.

Reboot now? (y/N) ?

When flashing, the script will check for a compatible version of flashrom, download/compile from source if needed, and then flash the update. You will be prompted to reboot when it has completed (~2 mins) and should do so.

Switch to a different firmware

This function changes the firmware type or configuration on your device.

You can select either Standard (coreboot/SeaBIOS) or PureBoot (coreboot/Heads) firmware:

Which firmware type would you like to flash?

1 - Standard (coreboot/SeaBIOS) [v24.02.01-Purism-1]
2 - PureBoot (coreboot/Heads)   [Release-29]

Enter your choice:

(Librem 13v1 and 15v2 do not support PureBoot, on these devices coreboot/SeaBIOS is selected automatically.)

If the selected firmware has configuration options, you can select the desired configuration. For PureBoot, these options can also be changed later from the PureBoot menu.

Which configuration would you like?

1 - Default
2 - Basic mode [basic]

Enter your choice (default 1):

Specify your device serial number:

Set the device serial number:

1 - Extracted from your local system (123456789)
2 - Enter serial number manually
3 - Do not set a serial number

Enter your choice (default: 1):

(Librem 13v1 and 15v2 do not have firmware serial numbers, this step is skipped. On any device, you can choose not to set a serial number if you don’t want to or don’t know it.)

For coreboot/SeaBIOS, you can configure the boot order:

Adjust the default order in which devices will attempt booting.
Selecting an item will move it to the top of the list.
Press [Enter] to continue when done.

1 - NVMe SSD
2 - 2.5" SATA SSD/HDD
3 - External/USB drives

** Note: regardless of the default order set here, you can always
** select a different boot device by pressing 'ESC' at boot time.

Enter your choice:

Selecting a device moves it to the top of the list. When the boot order is correct, press Enter to continue.

For coreboot/SeaBIOS, you can either download a pre-built ROM or build the update from source:

How would you like to obtain the update?

1 - Download precompiled build
2 - Build from source

Enter your choice (default 1):

Both selections will result in the same update. Building from source takes longer but allows you to reproduce the same ROM from source code.

Finally, the script will prompt you to flash the update.

Flashing: [##################################################-] (100%)
Verifying flash contents. Please wait...
The flash contents were verified and the image was flashed correctly.


You must reboot for the coreboot update to take effect.

Reboot now? (y/N) ?

When flashing, the script will check for a compatible version of flashrom, download/compile from source if needed, and then flash the update. You will be prompted to reboot when it has completed (~2 mins) and should do so.

Prepare firmware for manual flash

This function prepares a firmware file for another system. Use this to prepare a firmware update for an offline system, or when preparing an update within a VM, container, or Qube.

When preparing a PureBoot update, you can apply the update from the PureBoot menu. For a coreboot/SeaBIOS update, flash the update with flashrom.

First, select the device:

Which Librem device do you have?

# Broadwell/5th-Gen
1 - Librem 13 v1
2 - Librem 15 v2
# Skylake/6th-Gen
3 - Librem 13 v2/v3
4 - Librem 15 v3
# Kaby Lake/7th-Gen
5 - Librem 13 v4
6 - Librem 15 v4
# Whiskey Lake/8th-Gen
7 - Librem Mini
# Coffee Lake/9th-Gen
8 - Librem L1UM v2
# Comet Lake/10th-Gen
9 - Librem Mini v2
10 - Librem 14
# Jasper Lake/Atom
11 - Librem 11

Detected device: Librem 14

Enter your choice (default 10):

Then, make the remaining firmware selections as in the Switch to a different firmware section.

Confirming the Presence of the Correct Coreboot Image

If you want to feel warm and fuzzy by confirming you have coreboot installed properly after you see the cool Purism logo during boot, here is an easy to confirm coreboot booted and was installed properly.

  1. Grab coreboot source (or better yet, simply use the source checked out as part of the update script above)

git clone --depth=1 https://review.coreboot.org/coreboot.git

  1. Change to the cbmem tool directory

cd coreboot/util/cbmem

  1. Build cbmem

make

  1. Run cbmem to confirm coreboot booted

sudo ./cbmem -c | egrep -i "coreboot-|purism|librem"

  1. Verify output looks similar to:

coreboot-4.8.1-10-gade55f0fa4-4.8.1-Purism-4 Sun Jan 20 19:24:19 UTC 2019 bootblock starting...
coreboot-4.8.1-10-gade55f0fa4-4.8.1-Purism-4 Sun Jan 20 19:24:19 UTC 2019 romstage starting...
coreboot-4.8.1-10-gade55f0fa4-4.8.1-Purism-4 Sun Jan 20 19:24:19 UTC 2019 postcar starting...
coreboot-4.8.1-10-gade55f0fa4-4.8.1-Purism-4 Sun Jan 20 19:24:19 UTC 2019 ramstage starting...
Root Device (Purism Librem 13 v2)
Found mainboard Purism Librem 13 v2

Verifying the Intel ME is Neutralized

You can confirm the ME condition by utilizing the same cbmem utility as above:

coreboot/util/cbmem$ sudo ./cbmem -c | grep ^ME

the most important lines are the 7 that match these output:

for Librem 13v1/15v2

ME: FW Partition Table : OK
ME: Bringup Loader Failure : NO
ME: Firmware Init Complete : NO
ME: Manufacturing Mode : YES
ME: Boot Options Present : NO
ME: Update In Progress : NO
ME: Current Working State : Initializing
...

for Librem 13v2/15v3 and newer

ME: Host Firmware Status Register 1 : 0xFFFFFFFF
ME: Host Firmware Status Register 2 : 0xFFFFFFFF
ME: Host Firmware Status Register 3 : 0xFFFFFFFF
ME: Host Firmware Status Register 4 : 0xFFFFFFFF
ME: Host Firmware Status Register 5 : 0xFFFFFFFF
ME: Host Firmware Status Register 6 : 0xFFFFFFFF
ME: FW Partition Table      : BAD
ME: Bringup Loader Failure  : YES
ME: Firmware Init Complete  : YES
ME: Manufacturing Mode      : YES
ME: Boot Options Present    : YES
ME: Update In Progress      : YES
ME: D3 Support              : YES
ME: D0i3 Support            : YES
ME: Low Power State Enabled : YES
ME: CPU Replaced            : YES
ME: CPU Replacement Valid   : YES
ME: Current Working State   : Unknown (15)
...

Note

Disclaimer: ME neutralization and disablement is an ongoing and repeated effort requiring tailored work across different models and chipsets (for example, we once found the ME cleaner tool to cause problems with Wi-Fi on Skylake, and had to solve that first).

Migrating a UEFI-based Install

If you have an older Librem which shipped with proprietary AMI firmware, and your existing operating system was installed in UEFI mode, you will not be able to boot it after flashing coreboot on your Librem, because the SeaBIOS payload used in conjunction with coreboot provides support for Legacy BIOS boot mode, rather than UEFI. Additionally, UEFI installations typically use a GPT partition layout, and if you were to simply switch to the older MBR layout, everything on the disk would be lost — so don’t do that! Please follow the instructions below instead, which modifies the GPT/UEFI partition layout to one which allows grub to boot from a GPT layout disk in legacy BIOS mode (using a special 1 MB partition at the start of the disk). Here are the steps:

  1. Back up your data. (disclaimer: the steps below have had only limited testing so far, exercise caution)

  2. Using gparted, prepare the new target partition with one of these two approaches: Shrinking your EFI partition 1 MiB smaller, then creating a new partition in the newly freed 1 MiB space, or; Reformating your EFI partition

  3. Using gparted, apply the “bios_grub” flag to the new target partition.

  4. Remove the old EFI partition from /etc/fstab

  5. Reinstall GRUB with one of these two commands, where X is the physical storage device’s identifier:

If your OS is installed on a NVMe m.2 SSD:

sudo grub-install /dev/nvmeX
(most likely /dev/nvme0n1)

If your OS is installed on a SATA drive (either m.2 or in the 2.5” slot):

sudo grub-install /dev/sdX
(most likely /dev/sda)

You can find more advanced techniques or explanations in the GRUB documentation on the Arch Linux wiki or AskUbuntu question #360543.