Cat that kicks an exclamation mark. Rainbow Colors
The Zerocat Label
True Free-Design Hardware. Transparent. No Tricks.

Coreboot Machines

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

ZC-X230t with Zerocat Boot Menu

ZC-X230t with Zerocat Boot Menu

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.md.

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 (AHCI)” should reliably bring up your system. In case that fails, you might try the “Search Kernel Linux (AHCI)” Options. 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 Headers and Decrypt (AHCI)” 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.

Menu Entry: “Search LUKS Headers and Decrypt (AHCI)”

Menu Entry: “Search LUKS Headers and Decrypt (AHCI)”

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 (AHCI)” should reliably bring up your system, the 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.

GNU Guix System – Startup

GNU Guix System – Startup

GNU Guix System – Login with Slim Display Manager (Xfce4-Session ahead)

GNU Guix System – Login with Slim Display Manager (Xfce4-Session ahead)

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=/mnt/swapfile bs=1MiB count=10240
$ sudo chmod 0600 /mnt/swapfile
$ sudo mkswap /mnt/swapfile
$ nano my-os-config.scm

;; This is an operating system configuration with encrypted SWAP space
(use-modules ... )
(use-service-modules ... )
(operating-system
  ;; ...
  (mapped-devices ... )
  (file-systems ... )
  (swap-devices (list "/mnt/swapfile")))

$ 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 /mnt/swapfile 0" /dev/mapper/cryptroot |& sed -r -e '$!d;' - \
    )"

Please compare this information to webpages Page1 and Page2.

Unfortunately, this resume from hibernation configuration does not work, the kernel is unable to find the swap-space signature. Why, what’s wrong??

For the time being, let’s use 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)))

Xfce4 – Logout without Hibernation Options

Xfce4 – Logout without Hibernation Options

Toolchain Scripts

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

Example invocation of “setup-toolbox.sh --usage” (Version v0.12.0)

Example invocation of “setup-toolbox.sh --usage” (Version v0.12.0)

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

This project comes with a Sleeve How-to to show how you might sew a typical Zerocat Sleeve once you have successfully flashed your laptop:

Zerocat Sleeves

Zerocat Sleeves

Sources and Documentation