CINXE.COM

<!DOCTYPE html> <html lang="en" dir="ltr"> <head> <meta charset="utf-8"> <meta name="description" content=""> <meta name="keywords" content="libreboot, coreboot, canoeboot, opensource, libre, free software, bios, uefi"> <meta name="generator" content="pandoc"> <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes"> <link rel="icon" type="image/x-icon" href="/favicon.ico"> <link rel="canonical" href="https://canoeboot.org/about.html" />  <meta property="og:title" content="Canoeboot – What is Canoeboot?"> <meta property="og:type" content="article" /> <meta property="og:image" content="https://av.canoeboot.org/t60logo.jpg"> <meta property="og:url" content="https://canoeboot.org/about.html"> <meta name="twitter:card" content="summary_large_image"> <meta property="og:description" content="Canoeboot – What is Canoeboot?"> <meta property="og:site_name" content="Canoeboot – What is Canoeboot?"> <meta name="twitter:image:alt" content="Canoeboot – What is Canoeboot?"> <title>Canoeboot – What is Canoeboot?</title> <link rel="stylesheet" href="/global.css"> <link rel="stylesheet" href=""> <link rel="alternate" type="application/rss+xml" title="RSS Feed" href="/feed.xml"/> </head> <body> <div class="page"> <header> <div class="title" onclick="location.href='/';"> <p class="title-logo"> <a href="/"><img loading="lazy" class="title-logo" alt="Canoeboot logo" src="/favicon.ico" /></a> </p> <h1 class="title">What is Canoeboot?</h1> </div> <ul> <li><a href="/">Home</a></li> <li><a href="/about.html">About</a></li> <li><a href="/faq.html">FAQ</a></li> <li style="font-size:1.3em;"><strong><a href="/download.html">Download</a></strong></li> <li><a href="/git.html">Git</a></li> <li style="font-size:1.3em;"><strong><a href="/docs/install/">Install</a></strong></li> <li><a href="/docs/">Docs</a></li> <li><a href="/news/">News</a></li> <li><a href="https://codeberg.org/canoeboot/cbmk/issues">Bugs</a></li> <li><a href="/contact.html">Contact</a></li> <li><a href="/other.html">Other coreboot distros</a></li> </ul> <hr/> </header> <nav id="TOC"> <h2>Navigate this page:</h2> <ul> <li><a href="#open-source-biosuefi-firmware">Open source BIOS/UEFI firmware</a> <ul> <li><a href="#how-does-canoeboot-compare-to-libreboot">How does Canoeboot compare to Libreboot?</a></li> <li><a href="#who">Who?</a></li> <li><a href="#release-schedule">Release schedule</a></li> <li><a href="#how-releases-are-engineered">How releases are engineered</a></li> </ul></li> </ul> </nav> <div class="pagetext"> <p><a href="./">Return to index</a></p> <p>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.</p> <div class="h"><h2 id="open-source-biosuefi-firmware">Open source BIOS/UEFI firmware</h2><a aria-hidden="true" href="#open-source-biosuefi-firmware">[link]</a></div> <p>Canoeboot is free/libre boot firmware based on <a href="https://libreboot.org/">Libreboot</a> (which is in turn based on coreboot), replacing proprietary BIOS/UEFI firmware on select x86/ARM laptops, desktops and server motherboards. It provides an <a href="docs/maintain/">automated build system</a> for <a href="docs/build/">compiling coreboot ROM images</a>, that are <a href="docs/install/">easy to install</a> for non-technical users. The emphasis is placed upon ease of use, and optional <a href="docs/linux/grub_hardening.html">security features</a>.</p> <p>Users take this automation for granted today, but Libreboot was the first such project to implement this. It, like Canoeboot, is a <em><a href="docs/maintain/">coreboot distro</a></em> in the same way that <em>Parabola</em> is a GNU/Linux distro. 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.</p> <div class="h"><h3 id="how-does-canoeboot-compare-to-libreboot">How does Canoeboot compare to Libreboot?</h3><a aria-hidden="true" href="#how-does-canoeboot-compare-to-libreboot">[link]</a></div> <p>More specifically, Canoeboot is a <em>fork</em> of Libreboot, maintained in parallel as per each Libreboot release; Canoeboot maintains a <a href="news/policy.html">zero-blob policy</a>, adhering to the <a href="https://www.gnu.org/distros/free-system-distribution-guidelines.en.html">GNU Free System Distribution Guidelines</a>, in contrast to Libreboot’s <em><a href="https://libreboot.org/news/policy.html">Binary Blob Reduction Policy</a></em>. Canoeboot consequently supports far less hardware than Libreboot. Canoeboot even <em>excludes CPU microcode updates</em>, regardless of the negative impact this can have on system stability. The purpose of Canoeboot is simply to provide free boot firmware that is <em>fully</em> <a href="https://writefreesoftware.org/learn">Free Software</a> for the purists out there, whereas Libreboot <em>does</em> permit blobs under strict circumstances.</p> <p>The result is that Canoeboot fully complies with the <a href="https://www.gnu.org/distros/free-system-distribution-guidelines.en.html">GNU Free System Distribution Guidelines</a>, and that is the entire purpose of Canoeboot. This means that an organisation such as the <em>Free Software Foundation</em> shall continue to have a viable project which they can use on all of their computers.</p> <p>The approach taken by Canoeboot is the same one that Libreboot used to take, from it’s founding in 2013, right up until November 2022. On 17 November 2022, Libreboot switched to the <a href="https://libreboot.org/news/policy.html">Binary Blob Reduction Policy</a>, which is still quite strict; it still prohibits binary blobs from being included, including them only when absolutely required, because some boards from coreboot still require certain code from the vendor (e.g. raminit may not be implemented on some newer boards, so code from the vendor is used in such cases, e.g. Intel MRC/FSP).</p> <p>However, this move made a bunch of FSF people very angry. Canoeboot was later created, to provide a spiritual successor to the <em>old</em> Libreboot project, from before it changed. Despite Libreboot’s principles, they are now at odds with the much stricter policies set by the GNU FSDG, so Canoeboot was created to continue providing a viable coreboot distribution under <em>its</em> terms.</p> <p>In practise, Libreboot <em>also</em> provides fully free firmware on a lot of newer boards, depending on your point of view. For example, on Intel platforms up to Haswell, free raminit is available and the only code needed from the vendor is Intel ME, which is configured via <code>me_cleaner</code> on Libreboot releases, disabling the ME after early bringup. See: <a href="https://github.com/corna/me_cleaner" class="uri">https://github.com/corna/me_cleaner</a> - use of <code>me_cleaner</code> can be considered <em>de-blobbing</em>, since it is removing almost all of the code from the ME, but on most newer platforms, a small rump of ME code is still required for power management as one example.</p> <p>More information about precisely how <em>Libreboot</em> differs from Canoeboot, and therefore how Canoeboot differs from Libreboot, can be gleaned by looking at the following resources:</p> <ul> <li><a href="https://libreboot.org/news/policy.html">Libreboot Binary Blob Reduction Policy</a></li> <li><a href="news/policy.html">Canoeboot Binary Blob Extermination Policy</a> (adhering to GNU FSDG)</li> <li><a href="https://libreboot.org/freedom-status.html">Libreboot Freedom Status</a></li> </ul> <p>And check the hardware compatibility list of both projects:</p> <ul> <li><a href="https://libreboot.org/docs/install/#which-systems-are-supported-by-libreboot">Libreboot supported hardware</a></li> <li><a href="docs/install/#which-systems-are-supported-by-canoeboot">Canoeboot supported hardware</a></li> </ul> <p>I’m writing in the first person. Who’s this <em>I</em> you’re reading about? It’s me, Leah Rowe; I am the founder and lead developer of Libreboot, <em>and also</em> the founder and lead developer of Canoeboot! I maintain both projects, keeping them in relative sync between releases, often performing same-day simultaneous Canoeboot and Libreboot releases.</p> <p>So why is Canoeboot even maintained, if it’s inferior to Libreboot? Why maintain two projects? The answer is simple: Canoeboot is a fun technical challenge to see what can be done under such noble yet highly restrictive policies. Maintaining it is also not that hard, because the design is mostly kept in sync with Libreboot, on a per-commit basis, so the amount of development overhead is actually quite minimal.</p> <p>For example, both build systems both use the exact same design. See:</p> <ul> <li><a href="https://libreboot.org/docs/maintain/">Libreboot build system design</a></li> <li><a href="docs/maintain/">Canoeboot build system design</a></li> </ul> <p>With few exceptions, Canoeboot generally keeps in sync with Libreboot at all times, usually making releases on the exact same day. When a Libreboot release comes out, Canoeboot usually also does a corresponding release on the same day, or the day after.</p> <div class="h"><h3 id="who">Who?</h3><a aria-hidden="true" href="#who">[link]</a></div> <p>Canoeboot is maintained by the same founder, Leah Rowe, who is the founder and lead developer of both the Libreboot project <em>and</em> 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 motherboards from coreboot, and sometimes several <a href="https://browse.libreboot.org/lbmk.git/plain/resources/coreboot/default/patches/0012-fix-speedstep-on-x200-t400-Revert-cpu-intel-model_10.patch?id=9938fa14b1bf54db37c0c18bdfec051cae41448e">mitigations</a> may be required to stabilise certain functionalities under these conditions.</p> <div class="h"><h3 id="release-schedule">Release schedule</h3><a aria-hidden="true" href="#release-schedule">[link]</a></div> <p>Please also read <a href="news/schedule.html">this article</a>.</p> <p>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.</p> <p>The intention, moving forward, is that Canoeboot will track <em>stable</em> releases of Libreboot. Development is done mainly on Libreboot, and ported over to Canoeboot periodically; any work that isn’t suitable for Canoeboot (such as scripts for handling binary blobs) are <em>not</em> ported over to Canoeboot.</p> <div class="h"><h3 id="how-releases-are-engineered">How releases are engineered</h3><a aria-hidden="true" href="#how-releases-are-engineered">[link]</a></div> <p>It’s actually very simple. Here is the method by which Canoeboot releases are created:</p> <ul> <li>Take an archive of Libreboot’s git repositories (build system, website and images), at the version that the current Canoeboot release is based on.</li> <li>Take the <em>new</em> Libreboot release, that is the target for Canoeboot-ising.</li> <li>Diff the two revisions in bulk (as-is), by re-initialising Git history in the old Libreboot revision; then copy <code>.git/</code> to the directory containing the new revision.</li> <li>In the directory containing the new revision, commit all of the changes.</li> <li>In the directory containing the new revision, run this command: <code>git format-patch -n1</code></li> <li>The resulting <code>.patch</code> file will then show all of the changes.</li> </ul> <p>The resulting patch file is then opened up in <em>Vim</em>.</p> <p>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 <em>all</em> changes, except those that are not suitable under Canoeboot’s <a href="news/policy.html">policy</a>.</p> <p><em>Then</em> the following is done, for coreboot and u-boot trees <em>per tree</em>:</p> <ul> <li>Take the old revision of a given tree (e.g. <code>coreboot/default</code>), and diff it with the entire source tree on the same tree (e.g. <code>coreboot/default</code>) but on the new revision; then from the diff, get the list of all files that have been <em>added</em> and all of the files that have been <em>modified</em> (ignore files that have been deleted; also keep track of files that have renamed). This can be done very automatically with Git.</li> <li>Based on that, a list of files for scanning is now available. Next, the <code>deblob-check</code> script is executed within that source tree, using that list as input. For example: <code>./deblob-check $(cat /path/to/list) > sus.list</code></li> <li>The resulting <code>sus.list</code> file contains all results, and this new list of files can then be checked. This is checked <em>manually</em>, 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).</li> <li>Any false positives are ignored, while actual blobs are then added to the correct file, e.g. <code>config/coreboot/default/blobs.list</code>.</li> <li>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. <code>config/coreboot/default/patches/</code> if necessary.</li> <li>There may also be cases where a given bit of code is <em>not a blob</em>, but still proprietary, e.g. source code provided with restrictions on usage, modification or distribution.</li> </ul> <p>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.</p> <p>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.</p> <p>Upstream sources are rigorously checked, comparing files that have changed between releases. This takes time, but the process is largely automated.</p> <p>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.</p> <div id="footer"> <hr /> <ul> <li><a href="/git.html">Edit this page</a></li> <li><a href="/news/policy.html">Binary Blob Extermination Policy</a></li> <li><a href="/who.html">Who develops Canoeboot?</a></li> <li><a href="/license.html">License</a></li> <li><a href="/template-license.html">Template</a></li> <li><a href="/contrib.html">Authors</a></li> </ul> <hr /> </div> <p>Markdown file for this page: <a href="https://canoeboot.org/about.md" class="uri">https://canoeboot.org/about.md</a></p> <p><a href="/feed.xml">Subscribe to RSS for this site</a></p> <p><a href="/sitemap.html">Site map</a></p> <p>This HTML page was generated by the <a href="https://libreboot.org/docs/sitegen/">Libreboot Static Site Generator</a>.</p> </div> </div> </body> </html>