Coreboot Machines

2024-Nov-07: Attention, this is outdated information, kept for reference!

This project will help to you to create your own Zerocat Laptop, a Coreboot-driven machine that uses GRUB2 as its primary payload. Install GNU Guix System in conjunction with full disk encryption, and you will end up with very satisfying free-software devices, the ZC-X200t or ZC-X230t for instance:

Tuned Firmware Descriptor

This project tunes the Intel Firmware Descriptor to put more flash space under user control, see section “Region”. It deletes (ZC-X200t etc.) or radically truncates (ZC-X230t etc.) the Intel ME firmware and disables the ME controller via bits MeDisable or AltMeDisable. Region Access Permissions are carefully reviewed.

ZC-X230t Firmware Layout

$ diff -y ifd.factory ifd.zerocat

[...]

Found Region Section                                            Found Region Section
FLREG0:    0x00000000                                           FLREG0:    0x00000000
  Flash Region 0 (Flash Descriptor): 00000000 - 00000fff        Flash Region 0 (Flash Descriptor): 00000000 - 00000fff
FLREG1:    0x0bff0500                                         | FLREG1:    0x0bff0197
  Flash Region 1 (BIOS): 00500000 - 00bfffff                  | Flash Region 1 (BIOS): 00018000 - 00bfffff
FLREG2:    0x04ff0003                                         | FLREG2:    0x01960003
  Flash Region 2 (Intel ME): 00003000 - 004fffff              | Flash Region 2 (Intel ME): 00003000 - 00017fff
FLREG3:    0x00020001                                           FLREG3:    0x00020001
  Flash Region 3 (GbE): 00001000 - 00002fff                     Flash Region 3 (GbE): 00001000 - 00002fff
FLREG4:    0x00001fff                                           FLREG4:    0x00001fff
  Flash Region 4 (Platform Data): 00fff000 - 00000fff (unused   Flash Region 4 (Platform Data): 00fff000 - 00000fff (unused

[...]

Configurable LAN-on-Motherboard

The onboard Gigabit Ethernet controller is configurable through dedicated “Spec Setter Files”. It usually comes enabled, with a custom MAC Address, disabled PXE Boot Agent, and disabled MACsec feature. It can be disabled upon request.

(This project ships its own Spec Setter File for the 82579LM Intel GbE Controller interfacing the Intel 6 Series Express Chipsets, thus supporting the ZC-X230t and similar machines. Coreboot ships that kind of file since August 2020 and with version “4.13”, but uses a different namespace and some different values.)

GRUB2 Payload Configuration

GRUB2’s configuration files and the boot menu have been carefully reviewed, such that Trisquel, Debian and GNU Guix System should be bootable straight away. See Supported Distros.

GNU Guix System can even be used in conjunction with full disk encryption, what makes it the default system candidate for Zerocat Products. To ease further configuration after installation, GNU Guix System Declaration Templates are provided.

Boot Menu in Action

Option “Search GRUB2 Configuration File” should reliably bring up your system. In case that fails, you might try the “Search Kernel Linux” Option. As a last fallback, you might consider to use SeaBIOS, which uses a 16bit boot path.

In case you are using disk encryption, please unlock the root device with entry “Search LUKS Header, Decrypt, Mount CRYPTO Volume” before using search entries. Note GRUB2 runs a single thread only, thus decryption routines take some more time than specified via cryptsetup’s default iteration time. Another explication for the delay might be that entropy data is not yet available to GRUB2, but has to be collected.

GRUB2 offers a very flexible console in case your selected OS cannot be started with the predefined entries of the Boot Menu. See the GRUB2 Manual to learn about the available command set.

Starting GNU Guix System

Option “Search GRUB2 Configuration File” should reliably bring up your system, GNU Guix System for instance. If set up to start from encrypted disk partitions, keys must be entered again to enable kernel’s access to the root and home partitions.

Note that the GRUB Bootloader is running as a Coreboot Payload, there is no need to install it on disk:

(operating-system
  ;; ...
  (bootloader
    (bootloader-configuration
      (bootloader grub-bootloader)
;      (targets '("/dev/sda"))                   ;install bootloader?
      (keyboard-layout keyboard-layout)
      (timeout 5))))

Encrypted SWAP Space

At the time of writing, GNU Guix System does not support encrypted SWAP partitions, but swap files within an encrypted root partition are supported. The Guix Documentation offers snippets that explain how to set up that swapfile. Basically, these steps are required:

$ sudo dd if=/dev/zero of=/swapfile bs=1MiB count=10240
$ sudo chmod 0600 /swapfile
$ sudo mkswap /swapfile

$ nano my-os-config.scm
------------------------------------------------------------------------
;; This is an operating system configuration with encrypted SWAP space
(operating-system
  ;; ...
  (swap-devices 
    (list
      (swap-space
        (target "/swapfile")
        (dependencies mapped-devices)
        (priority #f)
        (discard? #t)   ;if supported, use #t to enable TRIM operation on SSD
      ) ;end of swap-space
    ) ;end of list
  ) ;end of swap-devices

$ sudo guix system reconfigure my-os-config.scm
$ sudo reboot

Unfortunately, resume from hibernation is not configured properly with Guix’ default GRUB2 boot entry, all hibernation data stored in that swap space will be lost. The space won't be recognized and has to be activated back again, manually via swapon.

In case you would use an unencrypted swap partition as swap space, you might edit the kernel boot options and add resume=/dev/sdaX before boot, or within your configuration file:

(use-modules
  ;; ...
  (gnu packages linux))
(operating-system
  ;; ...
  (kernel linux-libre)
  (kernel-arguments
    (cons*
      "resume=/dev/sdaX"
      %default-kernel-arguments)))

However, in case of using a swap file on an encrypted partition, you are to provide the file offset in respect to the start of that partition and keep that offset up to date:

(use-modules
  ;; ...
  (gnu packages linux))
(operating-system
  ;; ...
  (kernel linux-libre)
  (kernel-arguments
    (cons*
      "resume=/dev/mapper/cryptroot"
      "resume_offset=<offset_number>"
      %default-kernel-arguments)))

The <offset_number> can be retrieved via:

echo\
  "resume_offset=$(\
    sudo debugfs -R "bmap /swapfile 0" /dev/mapper/cryptroot\
    |& sed -r -e '$!d;' -\
  )"

Please compare this information to webpages Page1 and Page2.

This resume from hibernation configuration has been tested successfully on a Zerocat X200 (no CPU microcode update blob) and on a Zerocat X230t (with CPU microcode blob), using GNU with Linux-Libre 6.0.12 (guix channel 8125c22ea2). However, it once happend that the system resumed fine but was then stuck with the fan spinning at full speed. Use with care!

As a security measure, consider to disable hibernation with hibernate=no in order to avoid loss of data:

(use-modules
  ;; ...
  (gnu packages linux))
(operating-system
  ;; ...
  (kernel linux-libre)
  (kernel-arguments
    (cons*
      "hibernate=no"
      %default-kernel-arguments)))

Toolchain Scripts

The toolchain scripts use fairly recent project versions, such like coreboot@4.14, grub@grub-2.06 and seabios@rel-1.14.0. The scripts themselves require to be run on Trisquel GNU/Linux-libre – support for GNU Guix System is still experimental.

If you type ‘yes’, usage information will be displayed and some examples should give you a fast approach towards your use case.

Equipment

When it comes to write the generated ROM file to the flash chip of your device, please consider to use the RYF-Certified Chipflasher.

Sleeve How-To

See our Sleeve How-to if interested in a nice sleeve for your laptop.

Sources and Documentation

• Git repository: git://zerocat.org/zerocat/projects/coreboot-machines
• Prebuilt documentation: Zerocat Coreboot Machines
• See #../doc/CHANGES.md to see the change log.