cbmk

Canoeboot

Find canoeboot documentation at https://canoeboot.org/

The canoeboot project provides libre boot firmware that initializes the hardware (e.g. memory controller, CPU, peripherals) on specific Intel/AMD x86 and ARM targets, which then starts a bootloader for your operating system. Linux/BSD are well-supported. It replaces proprietary BIOS/UEFI firmware. Help is available via #canoeboot IRC on Libera IRC.

Why use Canoeboot?

Why should you use canoeboot?

Canoeboot gives you freedoms that you otherwise can't get with most other boot firmware. It's extremely powerful and configurable for many use cases.

You have rights. The right to privacy, freedom of thought, freedom of speech and the right to read. In this context, Canoeboot gives you these rights. Your freedom matters. Right to repair matters. Many people use proprietary (non-libre) boot firmware, even if they use a libre OS. Proprietary firmware often contains backdoors (more info on the FAQ), and it and can be buggy. The canoeboot project was founded in October 2023, with the express purpose of making coreboot firmware accessible for non-technical users.

The canoeboot project uses coreboot for hardware initialisation. Coreboot is notoriously difficult to install for most non-technical users; it handles only basic initialization and jumps to a separate payload program (e.g. GRUB, Tianocore), which must also be configured. The canoeboot software solves this problem; it is a coreboot distribution with an automated build system (named cbmk) that builds complete ROM images, for more robust installation. Documentation is provided.

How does Canoeboot differ from coreboot?

In the same way that Debian is a GNU+Linux distribution, canoeboot is a coreboot distribution. If you want to build a ROM image from scratch, you otherwise have to perform expert-level configuration of coreboot, GRUB and whatever other software you need, to prepare the ROM image. With canoeboot, you can literally download from Git or a source archive, and run make, and it will build entire ROM images. An automated build system, named cbmk (Canoeboot MaKe), builds these ROM images automatically, without any user input or intervention required. Configuration has already been performed in advance.

If you were to build regular coreboot, without using canoeboot's automated build system, it would require a lot more intervention and decent technical knowledge to produce a working configuration.

Regular binary releases of canoeboot provide these ROM images pre-compiled, and you can simply install them, with no special knowledge or skill except the ability to follow installation instructions and run commands BSD/Linux.

Canoeboot vs Libreboot

Libreboot and Canoeboot are both lead by the same founder, Leah Rowe, kept in sync whenever feasible; for each Libreboot release, a Canoeboot release follows.

Canoeboot is a fork of Libreboot, provided as a proof of concept demonstrating Libreboot in its current state per release, while removing any and all parts that do not comply with the GNU Free System Distribution Guideline (GNU FSDG). GNU FSDG is the policy that Libreboot used to be based on, but Libreboot adopted a more pragmatic Binary Blob Reduction Policy in November 2022, resulting in greater hardware support.

Canoeboot supports fewer mainboards than Libreboot, because it takes a hardline approach by limiting itself only to those mainboards which can be booted entirely without binary blob code in the main boot flash. The distinction of in the main boot flash is extremely important, because many examples exist where coreboot interacts with certain proprietary software; for example, the EC (Embedded Controller) firmware on some ThinkPads that both Libreboot and Canoeboot support. GNU FSDG is full of contradictions like this; for example, the HP Elitebooks supported by Libreboot 20231021 use proprietary EC firmware too, but it's in the main boot flash, whereas on many other machines it would be on a separate chip, and not the main boot flash.

Coreboot can boot with Free Software exclusively on many boards, but quite a few more mainboards exist where that is not the case. For example, a given mainboard may require a blob to configure the memory controller. Libreboot provides as few binary blobs as possible while allowing any mainboard to be supported, whereas Canoeboot provides no binary blobs and thus can only support a limited subset of what coreboot supports.

Libreboot started with the no-blob policy, in December 2013. In December 2020, another project lead by Leah Rowe was created, named osboot. The osboot project had the same policy as current Libreboot, and was later merged into Libreboot, during November 2022. Thus, Libreboot became osboot, and it has improved substantially since then. This was done, in an effort to bring coreboot to more people, since Libreboot was much better established at that point. Since then, the decision has proven to be quite successful, with many more users.

While the no-blob approach may seem noble, it stifles the adopt of Free Software, in this case coreboot, by alienating those users who like the idea of free software but do not have such "pure" hardware. The FSF's definition of purity (in this context) is deeply flawed, as it contains many contradictions.

Binary blobs are bad. Free software is good, and everyone deserves to have freedom in their computing. The irony is that there are some who would denounce the current Libreboot project, under the logic that it is enabling proprietary software, but this is not so; Libreboot is removing proprietary software, when you install it.

Therefore, the nuance in the type of thinking behind Libreboot policy is that while proprietary software is bad, and should be avoided, that choice may not always be available; in such cases then, it can be used but with the stipulation that it be replaced (with free software) at a future date, and that strong education is given about it in the meantime. Indeed, many projects out there, for example many Linux and/or GNU-based systems, will include such proprietary software (such as wifi firmware blobs) and not tell you about it, or not clearly document its existence. Libreboot very clearly documents what and where these blobs are, in this document: https://libreboot.org/freedom-status.html

The mentality behind Libreboot policy is that some software freedom is better than none. For example, if you're running a ThinkPad X230 or T440p, both of these can boot entirely without binary blobs in coreboot, but you do still need the neutered Intel ME image outside of that (in the ME region of the flash, whereas coreboot goes in the BIOS region). More information about that is available, on the Freedom Status page of the Libreboot project: https://libreboot.org/freedom-status.html

Libreboot still supports all of the same mainboards that Canoeboot supports, and provides the exact same configuration as options in each release. In other words, the no-blob configuration is still possible in Libreboot, and that will always be true, when possible on a given mainboard. Libreboot's preference is precisely to promote Free Software, hence the Binary Blob Reduction Policy. Again for posterity, here is a link to the text of that policy: https://libreboot.org/news/policy.html

By contrast, many projects (that handle blobs) do not have such a stipulation. They either have no policy, a loosely defined policy, or they actively encourage the use of blobs. Libreboot does not encourage use of binary blobs, unless absolutely necessary on a given mainboard; whereas, a project like Debian will provide the nouveau driver for nvidia graphics cards, while also providing the binary drivers from Nvidia (which is proprietary); if Libreboot were to become a Debian, it would only recommend the nouveau driver if that works well enough. And now an example closer to home: in Libreboot, let's say you have a board with Intel graphics. Libreboot provides free initialisation of the framebuffer (using coreboot's libgfxinit), which has some limitations but does work well with Linux/BSD, and you could add Tianocore for an efi framebuffer if you wanted; an alternative to this is the proprietary VGA Option ROM from intel, which can provide full VGA mode setting as a BIOS callback, which would enable more operating systems (e.g. ReactOS, games in FreeDOS, etc). Libreboot does not provide the Intel VGA ROM, because it is not needed. Linux and BSD are fine, you you can play DOS games in dosbox if you really want to. You do not need to boot DOOM on FreeDOS.

To summarise the above point: if Libreboot had a policy like the Debian one, it would provide that VGA ROM. Libreboot is not Debian. But it does not follow GNU's hardline approach either. Both approaches are bad. Libreboot policy is based on FSF ideology, but without dogma. So, the difference with Canoeboot is that it also implements the dogma. The FSF and GNU dogma is that proprietary software must always be avoided, under all circumstances. Libreboot does not implement such dogma.

The purpose of Canoeboot is therefore to demonstrate what can be done under such dogma, while providing criticism of it in favour of Libreboot policy. The Libreboot policy is correct because it provides more software freedom overall to more people. In any software community, a certain fixed percentage of people will become programmers, and so bringing coreboot to more people will inevitably lead to more people becoming coreboot developers; this may then encourage more people to reverse engineer the blobs to produce free source code.

To put the above point another way: the GNU FSDG policy, dictated by the FSF, is causing active harm to the adoption of Free Software. For example, if a Windows user is introduced to Linux for the first time, but they are introduced to an FSDG-compliant distro like Trisquel, they may find that certain hardware doesn't work. They aren't master hackers, they are clueless novices, and everything needs to work or they are going to ditch Linux and keep using Windows. That is just a fact, with most people, even principled people who believe in the ideals. When someone is just starting out, they need the experience to be as smooth as possible.

That novice user could one day reverse engineer graphics drivers and bring about the next revolution in software freedom, but a bad early experience will deter them early on, and thus stifle future development of free software. This is the argument put forward by Libreboot, as of November 2022 with the merging of osboot.

tl;dr just imagine a universe where osboot never existed, and know that Canoeboot is essentially what Libreboot might have been at this point in time. It is a representation of what was, and what could have been. Canoeboot is one possible answer to that what if, although the actual universe where osboot didn't exist may not have produced exactly the same result as Canoeboot today; it could be slightly different. Libreboot butterflies...

Libreboot today is far superior to Canoeboot, and it's what you should use, but there are a few who prefer the old Libreboot policy, who absolutely do not want any proprietary software even to be present, let alone installed and/or executed. Thus, canoeboot was born.

Canoeboot provides the same level of automation that Libreboot does in the downloading, patching and building of coreboot ROM images, but it excludes any binary blobs that may otherwise be present in upstream projects. Canoeboot will also remove non-blobs that are still proprietary software; there are some cases where software may be provided by a vendor with source code, but under some license that puts restrictions on its use or distribution. Canoeboot will only knowingly provide software that adheres to the GNU Free Software Definition, in compliance with the GNU Free System Distribution Guidelines.

Project goals

• Support as much hardware as possible! (within the restrictions imposed by GNU FSDG policy)
• Make coreboot easy to use. Coreboot is notoriously difficult to install, due to an overall lack of user-focused documentation and support. Most people will simply give up before attempting to install coreboot. Canoeboot's automated build system and user-friendly installation instructions solves this problem.

Canoeboot attempts to bridge this divide by providing a build system automating much of the coreboot image creation and customization. Secondly, the project produces documentation aimed at non-technical users. Thirdly, the project attempts to provide excellent user support via IRC.

Canoeboot already comes with a payload (GRUB), flashrom and other needed parts. Everything is fully integrated, in a way where most of the complicated steps that are otherwise required, are instead done for the user in advance.

You can download ROM images for your canoeboot system and install them without having to build anything from source. If, however, you are interested in building your own image, the build system makes it relatively easy to do so.

Not a coreboot fork!

Canoeboot is not a fork of coreboot. Every so often, the project re-bases on the latest version of coreboot, with the number of custom patches in use minimized. Tested, stable (static) releases are then provided in Canoeboot, based on specific coreboot revisions.

LICENSE FOR THIS README

It's just a README file. This README file is released under the terms of the Creative Commons Zero license, version 1.0 of the license, which you can read here:

https://creativecommons.org/publicdomain/zero/1.0/legalcode.txt

The documentation in Canoeboot will use a mix of other licenses, so you should check that for more information.