Return to index

The main purpose of this article is to describe how the Canoeboot project operates, why it exists and what it does. Who, what, why and when.

Canoeboot is free/opensource boot firmware based on Libreboot (which is in turn based on coreboot), replacing proprietary BIOS/UEFI firmware on select x86/ARM laptops, desktops and server mainboards. It provides an automated build system for compiling coreboot ROM images, that are easy to install for non-technical users. The emphasis is placed upon ease of use, and optional security features.

Users take this automation for granted today, but Libreboot was the first such project to implement this. It, like Canoeboot, is a coreboot distro in the same way that Debian is a Linux distro (that uses the GNU C Library and coreutils, among other things). Similar projects now exist, today, inspired by Libreboot’s example. Coreboot is notoriously difficult to configure and install for most non-technical users, but Libreboot and Canoeboot make it easier.

More specifically, Canoeboot is a fork of Libreboot, maintained in parallel as per each Libreboot release. Canoeboot adheres to the GNU Free System Distribution Guidelines, instead of Libreboot’s more pragmatic Binary Blob Reduction Policy - and such adherence (to GNU FSDG) is the main purpose of Canoeboot. It consequently supports far less hardware than Libreboot, providing a proof of concept showing what Libreboot would be like if it didn’t implement such a policy (in opposition to the GNU one that Canoeboot implements). Libreboot previously adhered to the GNU FSDG policy, but adopted the Binary Blob Reduction Policy in November 2022, in an effort to increase the number of mainboards that can be supported from coreboot.

Thus, Canoeboot is a representation of the old Libreboot project. Coreboot is nominally free software, but requires binary blobs for certain initialisation on certain boards; only very few mainboards can boot without them. You can read about how Libreboot handles this (in contrast to Canoeboot which bans all binary blobs), by reading the Libreboot Freedom Status page: https://libreboot.org/freedom-status.html

Canoeboot was created because there are still a few people who want this sort of thing, but there weren’t any modern, or otherwise high quality implementations. Thus, I decided to revive the old Libreboot project myself, forking from my very own project (Libreboot) and calling the new fork Canoeboot. I forked my own project.

Canoeboot is maintained by the same founder, Leah Rowe, who is the founder and lead developer of both the Libreboot project and the Canoeboot project. Maintaining a project like Canoeboot is both challenging and fun; Canoeboot does not permit any binary blobs from coreboot, which means that it can only support a handful of mainboards from coreboot, and sometimes several mitigations may be required to stabilise certain functionalities under these conditions.

The Canoeboot schedule is: whenever a Libreboot release is ready, produce a new Canoeboot release based on it, when there are enough changes to warrant a new release.

It’s actually very simple. Here is the method by which Canoeboot releases are created:

• Take an archive of Libreboot’s git repositories (build system, website and images), at the version that the current Canoeboot release is based on.
• Take the new Libreboot release, that is the target for Canoeboot-ising.
• Diff the two revisions in bulk (as-is), by re-initialising Git history in the old Libreboot revision; then copy .git/ to the directory containing the new revision.
• In the directory containing the new revision, commit all of the changes.
• In the directory containing the new revision, run this command: git format-patch -n1
• The resulting .patch file will then show all of the changes.

The resulting patch file is then opened up in Vim.

In the Canoeboot repository, these changes are then copied over. This is done by scrolling through the patch file, deciding which changes are worthy. The policy is to include all changes, except those that are not suitable under FSDG.

Then the following is done, for coreboot and u-boot trees per tree:

• Take the old revision of a given tree (e.g. coreboot/default), and diff it with the entire source tree on the same tree (e.g. coreboot/default) but on the new revision; then from the diff, get the list of all files that have been added and all of the files that have been modified (ignore files that have been deleted; also keep track of files that have renamed). This can be done very automatically with Git.
• Based on that, a list of files for scanning is now available. Next, the deblob-check script is executed within that source tree, using that list as input. For example: ./deblob-check $(cat /path/to/list) > sus.list
• The resulting sus.list file contains all results, and this new list of files can then be checked. This is checked manually, but usually doesn’t take very long (it’s never more than a couple hundred files, and it’s easy to see within like 5 seconds whether it’s a blob: 500 seconds if it’s 100 files).
• Any false positives are ignored, while actual blobs are then added to the correct file, e.g. config/coreboot/default/blobs.list.
• Next, documentation is scanned. The same process is used (track new files, moved files and changed files), but there is no automation for this. Every changed/moved/added file must be checked manually. This is to check for any documentation that recommends or endorses any proprietary code. Whole files can be deleted in this way; a normal diff can be provided to clean up other files, under e.g. config/coreboot/default/patches/ if necessary.
• There may also be cases where a given bit of code is not a blob, but still proprietary, e.g. source code provided with restrictions on usage, modification or distribution.

Libreboot often contains hundreds of changes per release, so it would be quite inefficient to cherry-pick individual patches. Therefore, all development is done in Libreboot exclusively, and Canoeboot is the by-product of that development, updating every now and then.

The above steps are a general guide, but specific tweaks may also be required in the build system, for a new release; minor edge cases here and there, that are different for every release, but they are usually very minor.

The deblob-check script is from linux-libre, a GNU fork of Linux that is de-blobbed, but the same script works on any source tree, except it will flag all of the false positives on non-Linux source trees; it scans heuristically for binary blobs.

This is how Canoeboot can provide releases so quickly, based upon each release of Libreboot. Extensive testing is performed on ROM images compiled under the Libreboot build system, so the Canoeboot images are also easy to verify, since a Canoeboot release will always be closely based on a Libreboot release.

This is actually the benefit of Canoeboot, over all other FSDG-derived coreboot distros, because the other projects do not have as good infrastructure or the level of resources or technical knowledge that Libreboot has. Libreboot provides high quality releases which are then filtered by order of the protocol described above, to provide Canoeboot releases.

Prior to 16 November 2022, another project existed called the osboot project, which was also created by Leah. Osboot started as a fork of Libreboot, starting in early December 2020, with the exact policies and goals of Libreboot as of 16 November 2022. On 16 November 2022, osboot was shut down and all code differences merged back into Libreboot, thus creating the osboot/libreboot merger of 16 November 2022. The osboot project was thus the blueprint for modern Libreboot.

Prior to the merger, during those almost-2-years, osboot and Libreboot were kept in sync, but it was much harder; Libreboot was the main project, but under the old policy, whereas osboot was adding new boards and new logic to the build system. Then later, osboot became main; however, Libreboot was still the bigger project. At the time osboot started, Libreboot had not seen any releases in five years; osboot forked the old Libreboot build system from 2016 because of a failed re-write of it since 2017; osboot was used in early 2021 to revive the Libreboot project, scrapping the re-write and modernising the classic design that later became lbmk (the Canoeboot version is cbmk and the osboot version was called osbmk).

Removing code is easier than adding it each time, when syncing one project based on another, but doing it this way was impossible then, so osboot and Libreboot were maintained in parallel on a per-patch basis; the same logic would be implemented per-patch between the two projects, but this started becoming much harder to manage over time.

So if osboot was to become the de facto main project, I decided that it should be osboot that has the most recognition. Therefore, I merged osboot into Libreboot. I originally intended to then maintain an fsdg branch within Libreboot, which would have been equivalent to today’s Canoeboot in terms of policy. However, this too would have become impractical.

So the situation before was: FSDG-only Libreboot, and no osboot. Then it was Osboot and Libreboot. Then libreboot-only again, but under the Binary Blob Reduction Policy. Now, today, it is libreboot under the Binary Blob Reduction Policy and Canoeboot under Libreboot’s old Binary Blob Extermination Policy adhering to GNU FSDG. You can read the actual old Libreboot policy (the FSDG one) in this link: https://web.archive.org/web/20221107235850/https://libreboot.org/news/policy.html

tl;dr - it’s basically this.

Markdown file for this page: https://canoeboot.org/about.md

Subscribe to RSS for this site

Site map

This HTML page was generated by the Untitled Static Site Generator.