% Canoeboot 20231026 released! % Leah Rowe in GNU Leah Mode™ % 26 October 2023
This new release, Canoeboot 20231026, released today 26 October 2023, is based on Libreboot 20231021.
Canoeboot provides boot firmware for supported x86/ARM machines, starting a bootloader that then loads your operating system. It replaces proprietary BIOS/UEFI firmware on x86 machines, and provides an improved configuration on ARM-based chromebooks supported (U-Boot bootloader, instead of Google's depthcharge bootloader). On x86 machines, the GRUB and SeaBIOS coreboot payloads are officially supported, provided in varying configurations per machine. It provides an automated build system for the configuration and installation of coreboot ROM images, making coreboot easier to use for non-technical people. You can find the list of supported hardware in Canoeboot documentation.
Canoeboot's main benefit is higher boot speed, better security and more customisation options compared to most proprietary firmware. As a libre software project, the code can be audited, and coreboot does regularly audit code. The other main benefit is freedom to study, adapt and share the code, a freedom denied by most boot firmware, but not Canoeboot! Booting Linux/BSD is also well supported.
Canoeboot is maintained in parallel with Libreboot, and by the same developer, Leah Rowe, who maintains both projects; Canoeboot implements the GNU Free System Distribution Guideline as policy, ensuring that all of the software provided by it is free software.
The following mainboards added in Libreboot 20231021 have been excluded in this Canoeboot release, due to the GNU FSDG policy: HP EliteBook 2170p, HP EliteBook 8470p, Dell Precision T1650 and Dell Latitude E6430. Other non-FSDG compliant boards are also excluded, such as newer ThinkPads that require Intel ME.
Canoeboot complies strictly with GNU Free System Distribution Guidelines, which means it does not contain binary blobs; as a result, it supports only a very restricted subset of hardware from Libreboot upon which it is based (Canoeboot is a GNU-friendly fork of Libreboot).
This new Canoeboot release imports the PHC argon2 implementation into GRUB, courtesy of Axel who initially ported the code to run under GRUB 2.06, but this Canoeboot release uses GRUB 2.12 (an RC revision from git, at present).
Axel's code was published to this AUR repository which Nicholas Johnson then rebased on top of GRUB 2.12, and I then imported the work into Libreboot, with Johnson's blessing; Canoeboot has inherited this work in full.
These libreboot patches added argon2 support, and have been ported to Canoeboot in this 20231026 release:
This means that you can now boot from encrypted /boot
partitions. I'm very
grateful to everyone who made this possible!
You can find information about using the build system in the Canoeboot build instructions and in the cbmk maintenance manual.
Canoeboot's build system, cbmk, is written entirely in shell scripts. It is an automatic build system that downloads, patches, configures and compiles source trees such as coreboot and various payloads, to build complete ROM images that are easier to install.
The primary focus of Libreboot 20231021 cultiminated in two audits, namely Libreboot Build System Audit 2 and then Libreboot Build System Audit 3.
The changes in those audits have been ported to this Canoeboot release.
Changes include things like vastly reduced code complexity (while not sacrificing functionality), greater speed (at compiling, and boot speeds are higher when you use the GRUB payload), many bug fixes and more.
In addition to coreboot firmware, the Canoeboot build system (cbmk) can now
build serprog firmware, specifically pico-serprog
and stm32-vserprog
, on
all devices that these projects support.
The serprog protocol is supported by flashrom, to provide SPI flashing. It can be used to set up an external SPI flasher, for flashing Canoeboot externally. This too has been ported from Libreboot.
Pre-compiled firmware images are available, for many of these devices, under
the roms/
directory in this Canoeboot 20231026 release! Riku Viitanen is the
one who added this capability to Libreboot, which was then ported to Canoeboot.
Alper Nebi Yasak submitted patches that update the U-Boot revision in
Libreboot, on gru_bob
and gru_kevin
chromebooks. Additionally, the cros
coreboot tree has merged there with the default
tree instead (and the default
tree has been updated to coreboot from 12 October 2023).
Many improvements were made to these boards, which you can learn about by reading these diffs:
All of these patches have been ported to this Canoeboot release.
In Canoeboot 20231026 (this release):
d862695f5f432b5c78dada5f16c293a4c3f9fce6
, 12 October 2023coreboot/default
(see above)1c13f8d85c7306213cd525308ee8973e5663a3f8
, 16 June 2021e58b870ff926415e23fc386af41ff81b2f588763
, 3 October 20231e1da7a963007d03a4e0e9a9e0ff17990bb1608d
, 24 August 20234459ed60cb1e0562bc5b40405e2b4b9bbf766d57
, 2 October 2023The resources/scripts/
directory is now script/
, and what was resources/
now only contains configuration data plus code patches for various projects,
so it has been renamed to config/
- I considered splitting patches
into patch/
, but the current directory structure for patches is not a problem
so I left it alone.
Also, the IFD/GbE files have been moved here, under config/ifd/
. These can
always be ge-generated if the user wants to, using ich9gen, or using a
combination of bincfg and ifdtool from coreboot, and nvmutil (to change the
mac address) from Canoeboot or Libreboot.
These changes have been ported from the Libreboot 20231021 release, which are mostly the results of the two audits (mentioned above):
config/git/
--mtime
and option options in GNU Tar (if it is actually GNU Tar), when
creating Tar archives. This results in partially reproducible source archives,
and consistent hashes were seen in testing, but not between distros..git
within cbmk, for the build system itself, if
Git history was removed as in releases. This work around some build systems
like coreboot that use Git extensively, and are error-prone without it.-k
grub.cfg
, because it causes trouble in some
non-interactive setups where the user sees an errant message on the screen
and has to press enter. This fixes boot interruptions in some cases, allowing
normal use of the machine. The pager was initially enabled many years ago,
to make use of cat a bit easier in the GRUB shell, but the user can just
enable the pager themselves if they really want to.include/
, and main scripts in script/
,
called by the main build
scriptsetvars
function defined under include/err.sh
config/git
are now
concatenated, traversing recursively through the target directory; files first,
then directories in order, and for each directory, follow the same pattern
until all files are concatenated. This same logic is also used for patches.
This now enables use of subdirectories, in some config/patch directories.util/nvmutil
cp
to copy links.err
, or just something that belongs on the error
output (instead of standard output).-B
option in make commands./tmp
, because it might be a tmpfs with
little memory available; clone into tmp/gitclone
instead, within cbmk,
and mv
it to avoid unnecessary additional writes (mv
is much more efficient
than cp
, for this purpose).resources/scripts/
is now script/
,
and resources/
was renamed to config/
; ifd and gbe files were also moved
to config/ifd/
. Commands are now 1-argument instead of 2, for example
the ./build boot roms
command is now ./build roms
.read
command that is built into sh
, reading each line.
This is more efficient, and provides more robust handling on lines with
spaces in them.config/git
have
had certain depend
items removed, if a given project already defines it
under .gitmodules
(within its repository).target.cfg
files in multi-tree projects coreboot,
SeaBIOS and U-Boot. Unified to all such projects, under one script, and
with improved error handling../build dependencies x
commands still work
as root (they're the only commands available as root).list
command has been mostly unified, making it easier to tell (from
cbmk) what commands are available, without having to manually poke around
under script/
.-T0
flag is now used, universally, on xz commands. This makes xz
run
on multiple threads, greatly speeding up the creation of large tar archives.-j
in make commands, for multi-threading, but it relies
on nproc
to get thread count, so this only works if you have nproc
(you
probably don't, if you run BSD; BSD porting is still on TODO for Canoeboot).gitcheck
; now, a global git name/email config is always required.
The only behaviour (setting local config, and unsetting) was quite error-prone
under fault conditions, where cleanup may not have been provided, or when
execution was interrupted, resulting sometimes in accidentally committing
to cbmk.git
as author named cbmkplaceholder
.x_
or err
is used to provide such behaviour. This results in all
exits from cbmk being consolidated to err
, under fault conditions. - zero
exits are also consolidated, going only through the main script, which has its
own exit function called cbmk_exit
that provides TMPDIR
cleanup.err
function (and functions
that use it) inside include/err.sh
; there is also x_
which can be used
to run a command and exit automatically with non-zero status, useful because
it provides more verbose output than if you just relied on set -e
, and it
still works when a script does not use set -e
- however, it is not used
on all functions, because it works by executing $@
directly, which can break
depending on arguments. Therefore, some scripts just default to || err
for
providing breakage in scripts.elf/
vs bin/
, when it comes to
flashing coreboot ROM images; it tells them to use bin/
because those
images do contain payloads, whereas the ones under elf/
do not.elf/
, as are payloads, then they are joined separately by
the usual ROMs build script, and these cached ROMs contain many changes in
them that were previously handled by moverom
in the main ROM build script.
Under the new design, repetitive steps are avoided; payloads are inserted into
a copy of the cached ROMs under TMPDIR
, before being copied for keymaps
and small files; this eliminates delays caused by slow compression (LZMA is
always used, when inserting payloads). After crossgcc and the payloads are
compiled, the ROM with coreboot builds in under a minute, whereas it would
have previously taken several minutes on most Canoeboot-supported hardware.include/
and its functions are called by the main build script, which
provides a stub for this.script/
, inheriting the TMPDIR
variable set (and exported) by cbmk./tmp
handling; a universal TMPDIR
is set (environmental
variable) and exported to all child processes running cbmk scripts. On exit,
the main tmp directory is purged, cleaning all tmp directories under it.-e
option in sh
was
heavily relied upon to catch errors, but now errors are handled much more
verbosely. Many fault conditions previously did not make cbmk exit at all,
let alone with non-zero status, and zero status was sometimes being returned
under some edge cases that were tested. Error handling is more robust now.util/ich9utils
(containing ich9gen
) was removed, thus eliminating about
3000 source lines (of C code) from cbmk. The nvmutil
program, also provided
by and originating from the Canoeboot project, can already change GbE MAC
addresses. Coreboot's bincfg can generate ich9m descriptors, and ifdtool can
manipulate them; so the features provided by ich9utils were superfluous, since
they are available in other projects that we ship. We now ship pre-built
ifd/gbe configs on these machines, which can be modified or re-assembled
manually if you want to. This eliminates a moving part from Canoeboot, and
speeds up the build a little bit.elf
directory contains these, and
the existing bin
directory still holds the full ROM images (containing
payloads) when compiled.build/boot/roms_helper
script - the new style is much cleaner,
mandating that logic be top-down, with a main()
function defined; it's
basically inspired by the OpenBSD coding style for C programs, adapted to
shell scripts.grub.elf
is now used on all ROM
images. The grub.cfg
goes in GRUB memdisk now, but can be overridden by
inserting a grub.cfg
in CBFS; many behaviours are also controlled this way,
for example to change keymaps and other behaviours. This results in much
faster builds, because a different GRUB payload doesn't have to be added to
each new ROM image; such takes time, due to time-expensive LZMA compression.
This, plus the optimised set of GRUB modules, also makes GRUB itself load
much faster. All of the fat has been trimmed, though still quite a lot more
than a Crumb./tmp
at all, but now it's pretty reliable.All of the following are believed to boot, but if you have any issues, please contact the Canoeboot project. They are:
You can find this release on the downloads page. At the time of this announcement, some of the rsync mirrors may not have it yet, so please check another one if your favourite one doesn't have it.
Besides deblobbing, there are two critical differences in how Canoeboot's build system works in this release, versus the Libreboot 20231021 build system:
config/git/
because
many of those entries were defined as submodules by each given project; in
some serprog-related repositories, proprietary drivers get downloaded that are
never actually compiled or executed in any way. Rather than deblob these in
Canoeboot, the Canoeboot build system simply skips downloading those
repositories altogether.config/git/
for Canoeboot 20231026, that do
not exist under Libreboot 20231021.This quirk is only a minor difference. Severals scripts that handled dependencies for building non-FSDG-compliant boards (such as blob download scripts) have been excluded in this Canoeboot release, because they are not needed.
As a result, the Canoeboot build system is about 1250 sloc when counting shell scripts of the build system; considerably smaller than older revisions, accounting for an approximate 50% reduction in the amount of code.
That ~1250 sloc in Canoeboot is with all the extra features such as serprog integration and U-Boot support (on actual mainboards, that you can flash it with). The build system in Canoeboot 20231026 is extremely efficient.
In addition to the Libreboot 20231021 changes, the following Libreboot patches were backported into this Canoeboot release, from Libreboot revisions pushed after the Libreboot 20231021 release came out:
The following boards are missing in Canoeboot 20231026, but are supported in the Libreboot 20231021 release; this is because they do not comply with GNU FSDG policy:
The following binary blobs were overlooked, and are still present in the release archive for Canoeboot 20231101 and 20231026; this mistake was corrected, in the Canoeboot 20231103 release, so you should use that if you don't want these files. They are, thus:
src/coreboot/default/3rdparty/stm/Test/FrmPkg/Core/Init/Dmar.h
src/coreboot/fam15h_rdimm/src/vendorcode/intel/fsp1_0/baytrail/absf/minnowmax_1gb.absf
src/coreboot/fam15h_rdimm/src/vendorcode/intel/fsp1_0/baytrail/absf/minnowmax_2gb.absf
src/coreboot/fam15h_udimm/src/vendorcode/intel/fsp1_0/baytrail/absf/minnowmax_1gb.absf
src/coreboot/fam15h_udimm/src/vendorcode/intel/fsp1_0/baytrail/absf/minnowmax_2gb.absf
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/ble.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/ble_err.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/ble_gap.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/ble_gatt.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/ble_gattc.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/ble_gatts.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/ble_hci.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/ble_l2cap.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/ble_ranges.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/ble_types.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/nrf_error.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/nrf_error_sdm.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/nrf_error_soc.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/nrf_nvic.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/nrf_sdm.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/nrf_soc.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/nrf_svc.h
src/pico-sdk/lib/tinyusb/hw/mcu/nordic/nrf5x/s140_nrf52_6.1.1_API/include/nrf52/nrf_mbr.h
Thanks go to Craig Topham, who is the Copyright and Licensing Associate at the Free Software Foundation; you can find his entry on the FSF staff page. Craig is the one who reported these.
The Canoeboot 20231026 and 20231101 release tarballs will not be altered, but errata has now been added to the announcement pages for those releases, to let people know of the above issue.
You are advised, therefore, to use the Canoeboot 20231103 release.
This file was also overlooked, and is still present in the release tarball:
src/vendorcode/amd/agesa/f12/Proc/GNB/Nb/Family/LN/F12NbSmuFirmware.h
This has now been removed, in the Canoeboot git repository (cbmk.git
), and
this file will absent, in the next release after Canoeboot 20231107. Thanks go
to Denis Carikli who reported this. The patch to fix it is here:
https://codeberg.org/canoeboot/cbmk/commit/70d0dbec733c5552f8cd6fb711809935c8f3d2f3