Coreboot

Coreboot Firmware on Purism Librem Devices

What is Coreboot

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 payload (such as SeaBIOS) to boot a modern operating system (such as PureOS) 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 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. (Building PureBoot from source is also possible, but not yet integrated into the main coreboot update script.)

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:

  • 1) Update firmware using pre-built image
  • 2) Build firmware update from source
  • 3) Modify default boot order
  • 4) Set device serial number
Coreboot Utility

We’ll cover the first two here, since those are the ones of interest to the majority of users, and the latter two are fairly self-explanatory 🙂

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/RevisionMinimum coreboot/SeaBIOSMinimum PureBoot
Librem 13 v14.7-Purism-1--
Librem 15 v24.7-Purism-5--
Librem 13 v24.7-Purism-1Beta 2
Librem 13 v34.7-Purism-4Beta 2
Librem 15 v34.7-Purism-1Beta 2
Librem 13 v44.8.1-Purism-4Beta 2
Librem 15 v44.8.1-Purism-4Beta 2
Librem Mini v14.12-Purism-2Beta 13
Librem L1UM v24.19-Purism-2Release 26
Librem Mini v24.12-Purism-4Release 15
Librem 14 v1-014.13-Purism-1Release 17
Librem 14 v1-024.21-Purism-3Release 28.2
Librem 114.21-Purism-2Release 28.1

Updating Your Firmware Using a Pre-Built Image

When selecting this option, the script will prompt you to select/confirm your Librem device model:

Coreboot utility device

After selecting/verifying your Librem model, the script will give you the option between the “standard” coreboot/SeaBIOS firmware and the PureBoot (coreboot/Heads) firmware.

Note: Librem 13v1 and 15v2 do not offer PureBoot due to limited flash space. The coreboot utility selects coreboot/SeaBIOS automatically.

Coreboot utility file type

The script will prompt to confirm or enter the device serial number. This is also skipped for Librem 13v1 and 15v2. If run from a Librem running coreboot firmware, the default option will be the device’s current serial number:

Serial number

The script will download and validate the appropriate firmware image. For coreboot/SeaBIOS, the script will prompt to set the default boot order. If your Librem has multiple internal storage drives, you will need to ensure your boot device has the higher priority between the two. You may also wish to prioritize external/USB devices when attached (by default, external devices have the lowest priority).

Selecting a device moves it to the top of the list. When you are happy with the ordering, simply press enter to continue. You can always override the default by pressing ESC during the boot splash to select a boot device.

Bootloader

Lastly, if running coreboot/SeaBIOS firmware, the script will prompt you to flash the update. If running PureBoot firmware, the script will prompt you to copy the update to USB and to update via the Heads menu option.

Flash complete

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.

Building the Firmware Update from Source

Currently this function only supports building our standard coreboot/SeaBIOS firmware. We plan on adding support to build the PureBoot firmware soon. Until then, instructions to do so can be found in the main PureBoot documentation.

As with using a pre-built image, the option for building the coreboot/SeaBIOS firmware from source starts with device selection/confirmation, followed by serial number confirmation/entry, and setting the default boot order:

Coreboot device Utility serial Bootloader

Next, the script will clone Purism’s coreboot repository using git. Once that is completed, the script will inform the user that it is ready to build coreboot, and that it may take some time (due to needing to compile coreboot’s toolchain first).

Coreboot

After you hit enter, the build process will kick off, validating/building coreboot’s toolchain, then building coreboot itself for the selected device. Once it has completed, the contents of the firmware will be printed, and the hash of the compiled image will be compared against the expected/known good hash.

If the hash matches the expected value, the script will prompt you to flash the update.

Coreboot hash

If the hash does not match, the script will recommend you not flash the image, and you should not do it manually either, as it could brick the machine

If you have any questions, or if you just want to know more about the coreboot utility/update script, you may also want to check out the main forum thread for it.

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

2. Change to the cbmem tool directory

cd coreboot/util/cbmem

3. Build cbmem

make

4. Run cbmem to confirm coreboot booted

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

5. 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)
...

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 Arch Linux’s wiki or AskUbuntu question #360543.

Purism

3D renders are artist renderings, for illustration purposes. Images and specifications are subject to change depending on manufacturing requirements.

Unless otherwise noted, contents created by the Purism team on this website are copyleft with a CC-by-SA 4.0 license.