ownerboot/doc/build.md

Building Ownerboot

Ownerboot should work with any recent version of nixpkgs. A submodule reference to a known-good nixpkgs revision is included for demonstration purposes.

git submodule init
git submodule update --depth 1 nixpkgs
export NIX_PATH=$(pwd)

Then execute one of the following three lines, depending on which platform you want to build for:

nix build --option trusted-public-keys "" -L -f src kgpe.coreboot    # kgpe-d16 AMD opteron
nix build --option trusted-public-keys "" -L -f src am1i.coreboot    # am1-i AMD kabini
nix build --option trusted-public-keys "" -L -f src kevin.coreboot   # Samsung chromebook rk3399 arm64

The --option trusted-public-keys "" tells nix not to trust binaries signed by the people who run nixos.org. This is the simplest and most effective way to force nix to build everything from source (except nix itself and the compiler-which-compiles-your-compiler).

After a lot of compiling you should find a symbolic link result to a directory containing the following files:

coreboot.rom     # this is the flash image
flashrom.layout  # this is a copy of the flash image's "partition table"
config           # the Linux kernel .config
cmos.layout      # layout of RTC NVRAM values (amd64 only)
cmos.default     # default RTC NVRAM values (amd64 only)

First Flash

The first time you write ownerboot to your flash chip you don't have a "known good" image to fall back to. So you need to save a copy of your flash chip's contents, and make sure you know how to write it back to the chip without booting your machine first (generally this involves using an SPI clip or removing the flash chip from its socket).

Once you've done that, you can write the complete flash image (bootblock, normal image, and fallback image) with one of the following two commands.

# amd64
flashrom -p internal -w result/coreboot.rom

# rk3399-gru-kevin
flashrom -p linux_mtd -w result/coreboot.rom

Note that in both cases you will need to already have booted using a bootloader which allows you to write to the flash chip. None of the manufacturer bootloaders allow this, so if you aren't already using coreboot your first flashing will need to be done with an SPI clip or by removing the chip from its socket (if it is socketed).

If you're using an em100 to emulate a real flash chip, use the following command instead. This should execute in 2-3 seconds instead of the 20-30 seconds it takes to write to a flash chip:

nix-shell -p em100 --run \
  'em100 -v --stop -c GD25Q128C --download result/coreboot.rom --start'

Once you've done this, cross your fingers, hold your breath, and reboot.

Testing Upgrades

arm64

To overwrite only the normal-boot image on the kevin arm64 platform, use the following commands:

flashrom -p linux_mtd --fmap -i NORMAL -w coreboot.rom

The command above tells flashrom to read the "fmap descriptor" from the chip before writing. An "fmap descriptor" is basically the flash chip equivalent of a partition table. The -i NORMAL tells it to read the NORMAL partition out of the coreboot.rom image and write it to the NORMAL partition on your flash chip.

amd64

AMD platforms require a rather unusual fmap descriptor format, with nested partitions. This is needed for the AMD-supplied AEGSA code (which is open source, but fragile enough that issues like this tend to be worked around rather than fixed), which uses the outer partition for SMRAM protection (a critical security requirement). Unfortunately flashrom gets confused by these nested partition tables, so on that platform you need to pass the partition table to flashrom explicitly, in a format it understands, and with the outer partitions omitted. To do this, execute the following command:

flashrom -p internal --layout result/flashrom.layout -i NORMAL -w result/coreboot.rom

Accepting Upgrades

If all went well, you can write the now-known-good image to your FALLBACK partition by using the same commands above, but replacing NORMAL with FALLBACK.

Recovery

If you flash a bad NORMAL image, you can switch to the FALLBACK image several ways:

arm64

Eject the stylus pen from the laptop and pull it all the way out before powering on the device. There is an internal sensor that detects if the stylus is inserted or not; ownerboot checks this sensor very early in the boot process.

You can also use the watchdog reboot to select the FALLBACK image; ownerboot examines the "reboot reason" register early in the boot process and takes it into account when selecting an image:

cat > /dev/watchdog   # will block for a while, then hard reboot

amd64

Connect the two motherboard pins designated as the "recovery jumper" before powering the machine on. I have these pins wired to the power switch on the front of my servers' chassis so I can use the power button as a recovery button.

You can also use the RTC NVRAM to force a FALLBACK image boot. The first command below selects the Fallback image; the second command reads back the value written so you can confirm that it was stored correctly.

nvramtool -y result/cmos.layout -w boot_option=Fallback
nvramtool -y result/cmos.layout -r boot_option

Extracting the NORMAL/FALLBACK copy

If you want to extract one of the two copies of the bootloader, use cbfstool:

cbfstool result/coreboot.rom read -r NORMAL   -f primary.region.out
cbfstool result/coreboot.rom read -r FALLBACK -f fallback.region.out