From c5c3cc6580870da8b0550bbeb419e34f7260c515 Mon Sep 17 00:00:00 2001 From: Leah Rowe Date: Sun, 19 Jan 2025 18:02:33 +0000 Subject: [PATCH] general audit / cleanup Signed-off-by: Leah Rowe --- site/about.md | 16 +- site/contact.de.md | 14 +- site/contact.it.md | 21 +- site/contact.md | 16 +- site/contact.uk.md | 16 +- site/contrib.md | 1 - site/docs/bsd/index.md | 176 +++++++++++++-- site/docs/build/index.md | 56 +++-- site/docs/build/index.uk.md | 50 ++--- site/docs/grub/index.md | 12 +- site/docs/index.md | 18 +- site/docs/index.uk.md | 13 +- site/docs/index.zh-cn.md | 19 +- site/docs/install/c201.md | 26 ++- site/docs/install/chromebooks.md | 47 ++-- site/docs/install/d945gclf.md | 22 +- site/docs/install/dell780.md | 38 ++-- site/docs/install/devmem.md | 10 +- site/docs/install/ga-g41m-es2l.md | 20 +- site/docs/install/ich9utils.md | 15 +- site/docs/install/index.md | 110 ++++----- site/docs/install/kcma-d8.md | 30 +-- site/docs/install/kfsn4-dre.md | 28 ++- site/docs/install/kgpe-d16.md | 25 ++- site/docs/install/latitude.md | 46 ++-- site/docs/install/mac_address.md | 46 ++-- site/docs/install/macbook21.md | 44 ++-- site/docs/install/nvmutil.md | 106 +++++---- site/docs/install/playstation.md | 36 ++- site/docs/install/r400.md | 55 ++--- site/docs/install/spi.md | 274 ++++++++++++++++------- site/docs/install/spi.zh-cn.md | 116 ++++------ site/docs/install/spi_generic.md | 19 +- site/docs/install/t400.md | 60 ++--- site/docs/install/t500.md | 60 ++--- site/docs/install/t60_unbrick.md | 11 +- site/docs/install/x200.md | 58 ++--- site/docs/install/x200.uk.md | 33 ++- site/docs/install/x60_unbrick.md | 9 +- site/docs/install/x60tablet_unbrick.md | 9 +- site/docs/linux/grub_boot_installer.md | 42 +++- site/docs/linux/grub_cbfs.md | 43 ++-- site/docs/linux/grub_hardening.md | 97 +++++--- site/docs/linux/index.md | 103 +++++---- site/docs/maintain/index.md | 259 +++++++++------------ site/docs/maintain/style.md | 57 ++--- site/docs/maintain/testing.md | 12 +- site/docs/maintain/testing.uk.md | 18 +- site/docs/misc/codenames.md | 8 +- site/docs/misc/emulation.md | 8 +- site/docs/misc/index.md | 13 +- site/docs/uboot/index.md | 21 +- site/docs/uboot/uboot-archlinux.md | 31 ++- site/docs/uboot/uboot-debian-bookworm.md | 11 +- site/docs/uboot/uboot-openbsd.md | 6 +- site/docs/uboot/uboot-x86.md | 32 ++- site/download.md | 2 +- site/faq.md | 172 ++++++++------ site/faq.uk.md | 212 ++++++++++-------- site/git.de.md | 77 +++++-- site/git.md | 67 ++++-- site/git.uk.md | 25 +-- site/index.md | 14 +- site/news/audit1.md | 26 +-- site/news/audit2.md | 4 +- site/news/canoeboot20231026.md | 50 ++--- site/news/canoeboot20231101.md | 23 +- site/news/canoeboot20231103.md | 18 +- site/news/canoeboot20231107.md | 26 +-- site/news/canoeboot20240504.md | 32 ++- site/news/canoeboot20240510.md | 13 +- site/news/canoeboot20240612.md | 32 ++- site/news/canoeboot20241102.md | 43 ++-- site/news/canoeboot20241207.md | 23 +- site/news/canoeboot20250107.md | 26 +-- site/news/policy.md | 10 +- site/other.md | 28 +-- site/template.de.include | 2 +- site/template.include | 2 +- site/template.it.include | 2 +- site/template.uk.include | 2 +- site/template.zh-cn.include | 2 +- 82 files changed, 1908 insertions(+), 1567 deletions(-) diff --git a/site/about.md b/site/about.md index 49610a5..8a8e083 100644 --- a/site/about.md +++ b/site/about.md @@ -6,8 +6,8 @@ x-toc-enable: true 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. -What is Canoeboot? -=================== +Open source BIOS/UEFI firmware +------------------ Canoeboot is free/libre boot firmware based on [Libreboot](https://libreboot.org/) (which is in turn based on coreboot), replacing proprietary BIOS/UEFI firmware on select x86/ARM @@ -25,8 +25,7 @@ same way that *Debian* is a 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. -How does Canoeboot compare to Libreboot? -------------------- +### How does Canoeboot compare to Libreboot? More specifically, Canoeboot is a *fork* of Libreboot, maintained in parallel as per each Libreboot release; Canoeboot maintains @@ -105,8 +104,7 @@ 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. -Who? ------- +### Who? 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. @@ -116,8 +114,7 @@ a handful of mainboards from coreboot, and sometimes several [mitigations](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) may be required to stabilise certain functionalities under these conditions. -Release schedule --------------- +### Release schedule 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 @@ -128,8 +125,7 @@ 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 *not* ported over to Canoeboot. -How releases are engineered ------------------ +### How releases are engineered It's actually very simple. Here is the method by which Canoeboot releases are created: diff --git a/site/contact.de.md b/site/contact.de.md index 45c91b7..a185918 100644 --- a/site/contact.de.md +++ b/site/contact.de.md @@ -4,13 +4,13 @@ x-toc-enable: true ... User support -============ +------------ IRC oder Reddit werden bevorzugt, sofern Du eine Support Anfrage hast (IRC empfohlen). Für Informationen bzgl. IRC and Reddit siehe unten. Entwicklungs Diskussion -====================== +--------------------- Eine Mailing Liste ist für die Zukunft in Planung. Bis dahin, siehe unter [der Git Seite](git.md) für Informationen wie Du dich an der Entwicklung beteiligen kannst. @@ -18,7 +18,7 @@ Eine Mailing Liste ist für die Zukunft in Planung. Bis dahin, siehe unter Hier finden sich ebenso Anleitungen zum Senden von Patches (via Pull-Requests). IRC Chatraum -============ +------------- IRC ist hauptsächlich der Weg um Kontakt Canoeboot Projekt aufzunehmen. `#canoeboot` auf Libera IRC. @@ -49,12 +49,11 @@ Website erläutern wie dies funktioniert: Grundsätzlich solltest Du die Dokumentation der von Dir verwendeten IRC Software konsultieren. Soziale Medien -============ +----------------- Canoeboot existiert offiziell an vielen Orten. -Mastodon --------- +### Mastodon Gründerin und Haupt-Entwicklerin, Leah Rowe, ist auf Mastodon: @@ -63,8 +62,7 @@ Gründerin und Haupt-Entwicklerin, Leah Rowe, ist auf Mastodon: Leah kann zudem unter dieser eMail kontaktiert werden: [leah@libreboot.org](mailto:leah@libreboot.org) -Reddit ------- +### Reddit Hauptsächlich verwendet als Support Kanal und für Veröffentlichung von Neuigkeiten: diff --git a/site/contact.it.md b/site/contact.it.md index c902546..41814af 100644 --- a/site/contact.it.md +++ b/site/contact.it.md @@ -4,19 +4,19 @@ x-toc-enable: true ... Supporto utenti -=============== +--------------- IRC o Reddit sono consigliati, sebbene preferiamo che usi il canale IRC per avere o per offrire supporto tecnico. Continua a leggere per avere ulteriori informazioni. Mailing list -============ +------------ No mailing lists at present. Discussione sullo sviluppo -========================== +-------------------------- Per ora dai un occhiata sulla [pagina Git](git.md) per avere maggiori informazioni su come puoi @@ -26,7 +26,7 @@ Su quella stessa pagina puoi trovare informazioni su come inviare correzioni (patches) tramite pull requests. Canale IRC -========== +---------- IRC e' il modo principale per contattare chi collabora con il progetto Canoeboot. Il canale ufficiale e' `#canoeboot` su Libera IRC. @@ -56,19 +56,22 @@ di Libera spiegano come: Comunque dovresti sempre controllare la documentazione del tuo client IRC preferito. Reti sociali online -=================== +------------------- Canoeboot esiste ufficialmente in molte piattaforme. -Mastodon --------- +### Mastodon Il fondatore e sviluppatore principale, Leah Rowe, e' su Mastodon: * -Posta elettronica ------------------ +### Posta elettronica Leah puo' essere contattata anche via email a questo indirizzo: [leah@libreboot.org](mailto:leah@libreboot.org) + +### Reddit + +Usato principalmente come canale di supporto e per annunciare notizie: + diff --git a/site/contact.md b/site/contact.md index 6304789..2a94bb8 100644 --- a/site/contact.md +++ b/site/contact.md @@ -3,16 +3,14 @@ title: Contact x-toc-enable: true ... -**TODO: mailing lists, mastodon server and peertube account.** - User support -============ +------------- IRC or Reddit are recommended, if you wish to ask for support (IRC recommended). See below for information about IRC and Reddit. Development discussion -====================== +-------------------- Mailing lists are planned for the future. For now, see notes on [the Git page](git.md) for information about how to assist with development. @@ -20,7 +18,7 @@ on [the Git page](git.md) for information about how to assist with development. Instructions are also on that page for sending patches (via pull requests). IRC chatroom -============ +------------- IRC is the main way to contact the Canoeboot project. `#canoeboot` on Libera IRC. @@ -51,12 +49,11 @@ website tells you how: In general, you should check the documentation provided by your IRC software. Social media -============ +------------- Canoeboot exists officially on many places. -Mastodon --------- +### Mastodon The founder and lead developer, Leah Rowe, is on Mastodon: @@ -65,8 +62,7 @@ The founder and lead developer, Leah Rowe, is on Mastodon: Leah can also be contacted by this email address: [leah@libreboot.org](mailto:leah@libreboot.org) -Reddit ------- +### Reddit Mostly used as a support channel, and also for news announcements: diff --git a/site/contact.uk.md b/site/contact.uk.md index 0e2f1e3..48e498d 100644 --- a/site/contact.uk.md +++ b/site/contact.uk.md @@ -3,16 +3,14 @@ title: Зв'язок x-toc-enable: true ... -**TODO: списки розсилки, сервер mastodon та обліковий запис peertube.** - Підтримка користувачів -============ +---------------------- IRC або Reddit рекомендовані, якщо ви бажаєте попросити про допомогу (найкраще IRC). Дивіться інформацію нижче щодо IRC та Reddit. Обговорення розробки -====================== +-------------------- Списки розсилки плануються на майбутнє. Зараз, подивіться нотатки на [сторінці Git](git.md) для інформації щодо допомоги з розробкою. @@ -20,7 +18,7 @@ IRC або Reddit рекомендовані, якщо ви бажаєте по На цій сторінці також знаходяться інструкції по відправці патчів (через pull request'и). Кімната IRC -============ +----------- IRC це головний спосіб зв'язку з проектом Canoeboot. `#canoeboot` на Libera IRC. @@ -51,12 +49,11 @@ Libera є однією з найбільших мереж IRC, використ Взагалі, вам варто перевірити документацію, яка передбачена вашою програмою IRC. Соціальні мережі -============ +---------------- Canoeboot офіційно існує в багатьох місцях. -Mastodon --------------------- +### Mastodon Засновник та головний розробник, Лія Роу, є в Mastodon: @@ -65,8 +62,7 @@ Mastodon Також можливо зв'язатися з Лією за ії електронною адресою: [leah@libreboot.org](mailto:leah@libreboot.org) -Reddit ------- +### Reddit Найбільше використовується як канал підтримки, та також для оголошення новин: diff --git a/site/contrib.md b/site/contrib.md index abe9e86..72151da 100644 --- a/site/contrib.md +++ b/site/contrib.md @@ -9,4 +9,3 @@ and lead developer for *both* projects; Leah maintains both Canoeboot *and* Libreboot. If you have a patch, or beef, talk to Leah. - diff --git a/site/docs/bsd/index.md b/site/docs/bsd/index.md index 20204f8..eb80b15 100644 --- a/site/docs/bsd/index.md +++ b/site/docs/bsd/index.md @@ -1,26 +1,120 @@ --- -title: BSD operating systems +title: Install a BSD operating system on Canoeboot x-toc-enable: true ... -Guide last updated on 16 November 2022. +It is assumed here that you are using the *SeaBIOS* payload, *not* the GRUB +payload; the U-Boot payload may also work, but that is not covered here. The +SeaBIOS payload must ideally run in text mode (`txtmode` images from Canoeboot +releases). -NOTE: This guide pertains to x86 hosts, and does not cover supported CrOS/ARM -chromebooks. For ARM targets, you should refer to u-boot documentation. +This guide pertains to x86 hosts, and does not cover supported CrOS/ARM +chromebooks. For ARM targets, you should refer to [u-boot +documentation](../uboot/) - and [U-Boot x86](../uboot/uboot-x86.md) is also +available. The U-Boot x86 payload is interesting, because it can in fact boot +OpenBSD via UEFI method (U-Boot provides a lightweight UEFI implementation +independently of, say, EDK2). -Canoeboot is capable of booting many BSD systems. This section mostly documents -the peculiarities of Canoeboot as it pertains to BSD; you can otherwise refer to -the official documentation for whatever BSD system you would like to use. +What is BSD? +------------ -Kernel Mode Setting -=================== +In our context, we are referring to those descendents of 4.4BSD-Lite starting +in the early 1990s. On balance, they are about equal to Linux in many ways, +and some would argue that they are *better* (higher code quality). It can be +said that the BSDs are the closest we have to *true* open source Unix systems, +since they ultimately descend from that code lineage. For example, the +FreeBSD project briefly covers its own history in the Hand Book: + + +Chief among them are: + +* [FreeBSD](https://www.freebsd.org/) (HardenedBSD probably also works) +* [NetBSD](https://netbsd.org/) +* [OpenBSD](https://www.openbsd.org/) +* [DragonFlyBSD](https://www.dragonflybsd.org/) (UNTESTED) + +**TODO: DragonFlyBSD is untested, as of January 2025. It ought to be tested.** + +Many other BSD systems exist, that are largely derived from these. + +Why use BSD (instead of Linux)? +------------------------------- + +BSD operating systems are in wide use today, powering much of the world's +most critical infrastructure, and they're quite competent laptop/desktop or +workstation systems. Some of them have unique features that you can't find +anywhere else (e.g. FreeBSD jails, OpenBSD's numerous security enhancements, +NetBSD's rump kernel design and clean code quality). + +BSD systems are superfically similar to Linux systems, but they are very +different under the hood (different kernel designs, different userspace +implementations, and so on). However, almost all of the Linux userspace programs +that you enjoy using are probably available in the various BSD *ports trees*, +or they can be compiled with little to no modification. This is because, despite +the actual differences under the hood, the BSDs and various Linux distros all +adhere to the same basic standards (e.g. Single Unix Specification). + +If you want to enjoy using a high quality operating system, with many unique +features, BSD systems can be quite fun to use, and quite challenging. They tend +to have a much more conservative take on implementations, compared to Linux +distros, instead opting for technical correctness and minimalism; this is a +good thing, because lots of Linux distros these days are extremely bloated. +Using a BSD system feels like Linux did in the year 2005, just with much better +hardware support, and that's a *good thing*; the reason why is that BSD systems +simply have fewer users, and a higher concentration of *technical* users, and +this *shows* when you use it. Linux is *much* more mass market and has to cater +to all sorts of people, and these days Linux distros have to *Just Work*. + +You can look at the documentation of each BSD system and try each one out, to +see which one is right for you. Be warned, BSD systems *are* typically harder +to use than Linux systems. Even the most seasoned Linux user will often have a +hard time with any BSD, if it's their first time using a BSD system. This is +mitigated by excellent documentation, which is one of the things that the BSDs +excel at, but you are expected to *read* the documentation; many Linux distros +try to hold your hand ("it Just Works"), but the BSDs generally don't do that. + +If you're already a power user on Linux, and comfortable with the more hands-on +distros like Arch Linux or Gentoo Linux, you'll have a much easier time +learning a BSD. FreeBSD for example comes completely barebones by default, and +you add packages to it, configuring it to your liking, much like Arch Linux; if +you're wily enough, you might also use the CURRENT tree and install all packages +by building them from *ports* (akin to how Gentoo Linux is used). + +BSD systems also have much more relaxed licensing than Linux systems, by and +large; most of the software in the base system, on any BSD project, will use +a permissive license instead of copyleft. They can be regarded as Free Software, +but it's a very different ideology than, say, GNU. Some might argue that this +is better, because licensing conflicts are common among copyleft licenses, even +among different versions of the GPL. A BSD-style license permits *anyone* to +use the code, *without* requiring modified versions to ship source code, so it +can be said that the BSD license model contains [far fewer +restrictions](https://docs.freebsd.org/en/articles/bsdl-gpl/). One might say +that the BSD systems are *more free* than GNU/Linux systems. + +Basically, your choice to use BSD will likely be based on a combination of +technical and/or ideological preferences. But don't say we didn't warn you. +BSD is hard. On the flip side of that coin, BSD is *easy*, because it forces +you to really learn how your system works; when you become proficient with +BSD, you'll learn everything else much easier, and you may find yourself doing +things more efficiently *in Linux* as well! + +That's enough BSD fanaticism. Please read the following sections, *before* +you embark on your BSD Canoeboot journey: + +Common issues with BSD+Canoeboot +-------------------------------- + +This page will not tell you how to install BSD systems; that is best left to +the documentation for your BSD system. Instead, these next sections cover only +the idiosyncrasies of Canoeboot as they relate to BSD: + +### Kernel Mode Setting Your BSD system *must* support Kernel Mode Setting for your graphics device (most of them do nowadays). The reasons will become apparent, as you read this article. -Boot BSD, using SeaBIOS -======================= +### Boot BSD, using SeaBIOS On x86 platforms, Canoeboot provides the choice of GRUB and/or SeaBIOS payload. GRUB can technically boot BSD kernels, but the code is @@ -37,8 +131,18 @@ If you don't plan to set up Xorg/Wayland, then that's all you really need to do. For example, you might want to run a headless server, in which case you probably don't mind running in text mode all the time. -OpenBSD and corebootfb ----------------------- +#### GRUB payload + +GRUB *can* directly boot many BSD systems, but this is ill advisable. You are +advised to use either SeaBIOS, and boot a BIOS-based BSD bootloader, or use +Canoeboot's [U-Boot payload](../uboot/) and use it to boot via UEFI; U-Boot's +bootflow menu can achieve this. + +The U-Boot coreboot payload is still experimental, on ARM64 *and* x86/x86\_64, +so you should probably use SeaBIOS for now (on x86). U-Boot is the *only* +coreboot payload for Canoeboot on ARM64 motherboards. + +### OpenBSD and corebootfb It's still recommended to use SeaBIOS in text mode, but OpenBSD specifically can work with SeaBIOS booting in a coreboot framebuffer, with SeaVGABIOS. In @@ -46,19 +150,22 @@ Canoeboot ROM images, this would be SeaBIOS images with `corebootfb` in the file name. Make sure to select MBR-style partitioning on the installer, and it will -Just Work. +Just Work. **GPT partitioning won't work in OpenBSD, if you use the SeaBIOS +payload, but will work if you boot/install it via UEFI boot method with +Canoeboot's [U-Boot UEFI payload](../uboot/uboot-x86.md) instead.** If you're using the GRUB payload but SeaBIOS is available in the boot menu, you can just select SeaBIOS at said menu, and OpenBSD will work fine. -FreeBSD and corebootfb ----------------------- +### FreeBSD and corebootfb Assumed broken, so please ensure that you boot with SeaBIOS payload in text mode (cbmk ROM images with `txtmode` in the file name, not `corebootfb`). -Warnings for X11 users ----------------------- +Please boot in *text mode*. FreeBSD can be configured to use KMS, if you need +Xorg or wayland. + +### Warnings for X11 users One important peculiarity of most Canoeboot systems is: VGA mode support exists, if booting with corebootfb (coreboot's own framebuffer) and @@ -169,3 +276,36 @@ extremely expensive computationally speaking. This is why modern kernels You can learn more about INT10H text/VGA modes here: + +If you use the *U-Boot* payload, INT10H is irrelevant because you will rely on +an EFI framebuffer instead, which U-Boot does provide (piggybacking off of the +coreboot framebuffer where one is available). + +Regardless of whether you have an EFI framebuffer or INT10H VGA interrupts, +the various BSD systems all support KMS so you should be able to use Xorg or +Wayland just fine. + +ALWAYS READ THE MANUAL +---------------------- + +All of the BSDs have *excellent* documentation; it's one of the defining +characteristics, versus typical Linux distros. This is precisely *because* +the BSDs develop everything in-house, so the various components of a BSD +system are much more heavily integrated, and this means that they can provide +much more reliable documentation; reliable from both the user's perspective +and from the perspective of technical correctness. + +Aside from these and other quirks when installing BSD *on Canoeboot*, the BSDs +otherwise work in exactly the same way as you would expect, and you can +follow along to their official documentation without much fuss. + +No specific or detailed guides will be provided here, because SeaBIOS is +fairly self-explanatory; you can otherwise refer to the SeaBIOS +documentation. + +DO NOT USE ROM IMAGES WITH `seabios_grubfirst` IN THE FILE NAME! These were +present in older Canoeboot releases, and supported in previous revisions +of the build system, but they did not work for the intended purpose. More +info is written on the [Canoeboot installation guide](../install/). ROM +images with `seabios_grubfirst` in the filename will NOT be included in +future Canoeboot releases. diff --git a/site/docs/build/index.md b/site/docs/build/index.md index 51ee47b..bbecdc2 100644 --- a/site/docs/build/index.md +++ b/site/docs/build/index.md @@ -1,19 +1,12 @@ --- -title: Build from source +title: Compile Canoeboot from source x-toc-enable: true ... -WARNING: eCryptfs file name limits -================================= +If you need to build Canoeboot from source, this guide is for you. -Do not run the build system on a eCryptfs file system, because it has -very short file name limits and Canoeboot's build system deals with very -long file names. We commonly get reports from this by Linux Mint users -who encrypt their home directory with eCryptfs; regular LUKS encryption will -do nicely. - -Introduction -============ +Open source BIOS/UEFI firmware +------------ Canoeboot's build system is named `cbmk`, short for `CanoeBoot MaKe`, and this document describes how to use it. With this guide, you can know how to compile @@ -22,8 +15,16 @@ canoeboot from the available source code. The following document describes how `cbmk` works, and how you can make changes to it: [canoeboot maintenance manual](../maintain/) +### WARNING: eCryptfs file name limits + +Do not run the build system on a eCryptfs file system, because it has +very short file name limits and Canoeboot's build system deals with very +long file names. We commonly get reports from this by Linux Mint users +who encrypt their home directory with eCryptfs; regular LUKS encryption will +do nicely. + System requirements -=================== +------------------- You must ensure that you have the correct operating system, CPU, RAM, disk space and so on. @@ -32,7 +33,7 @@ System requirements are documented in the [cbmk maintenance manual](../maintain/#system-requirements). Multi-threaded builds -===================== +--------------------- Canoeboot's build system defaults to a single build thread, but you can change it by doing e.g. @@ -46,7 +47,7 @@ is passed, where THREADS is the number of threads. This is also set when running xz commands for compression, using the `-t` option. Environmental variables -======================= +----------------------- Please read about environmental variables in [the build instructions](../maintain/), before running cbmk. You should set @@ -54,14 +55,14 @@ your variables accordingly, though you do not technically need to; some of them may be useful, e.g. `XBMK_THREADS` (sets the number of build threads). Sources -======= +------- This version, if hosted live on canoeboot.org, assumes that you are using the `cbmk` git repository, which you can download using the instructions on [the code review page](../../git.md). Git -=== +--- Canoeboot's build system uses Git, extensively. You should perform the steps below, *even if you're using a release archive*. @@ -81,21 +82,18 @@ You may also want to follow more of the steps here: How to compile Canoeboot -======================== Actual development/testing is always done using cbmk directly, and this includes when building from source. Here are some instructions to get you started: -Zero..st, check time/date -------------------------- +### Zero..st, check time/date Make sure date/hwclock report the correct time and date on your system, because parts of the build process download from HTTPS servers and wrong time or date can cause connections to be dropped during negotiation. -First, install build dependencies ---------------------------------- +### First, install build dependencies Check `config/dependencies/` for list of supported distros. @@ -131,8 +129,7 @@ Technically, any Linux distribution can be used to build canoeboot. However, you will have to write your own script for installing build dependencies. -Debian Trixie/Sid ------------------ +### Debian Trixie/Sid Debian Trixie, the testing release as of 3 January 2025, and Debian Sid, provide `gnat` and `gcc` as you expect, but `gnat` resolves to `gnat-13` and @@ -169,8 +166,7 @@ When we tested with this configuration, the KGPE-D16 images also compiled. NOTE: Ubuntu 24.10 also has the issue described above. Some other distros may also have it, if they're based on Debian Testing/Sid or Ubuntu 24.10. -MIPS cross compiler -------------------- +### MIPS cross compiler Canoeboot has support for the Sony PlayStation (PS1/PSX), based on the PCSX-Redux Open BIOS. If you're doing a full release build, and/or @@ -185,8 +181,7 @@ If your distro doesn't have the MIPS compiler available, the [PlayStation](../install/playstation.md) page provides instructions for manual installation; please do this in addition to the normal dependencies. -Next, build ROM images ----------------------- +### Next, build ROM images Canoeboot MaKe (cbmk) automatically runs all necessary commands; for example, `./mk -b coreboot` will automatically build the required payloads @@ -205,8 +200,7 @@ or get a list of supported build targets: ./mk -b coreboot list -Or maybe just build payloads? ------------------------------ +### Or maybe just build payloads? If you wish to build payloads, you can also do that. For example: @@ -232,8 +226,8 @@ example want to modify a config, e.g.: Or perhaps add a new board! The maintenance manual will teach you how the Canoeboot build system (cbmk) works! -Post-compilation steps -====================== +A note about documentation (and this page) +------------------------------- So you compiled your Canoeboot image? Congratulations! diff --git a/site/docs/build/index.uk.md b/site/docs/build/index.uk.md index 949f396..c7ba0fb 100644 --- a/site/docs/build/index.uk.md +++ b/site/docs/build/index.uk.md @@ -7,17 +7,8 @@ x-toc-enable: true still in English, and there may be some differences aside from translation, versus the English version.** -WARNING: eCryptfs file name limits -================================= - -Do not run the build system on a eCryptfs file system, because it has -very short file name limits and Canoeboot's build system deals with very -long file names. We commonly get reports from this by Linux Mint users -who encrypt their home directory with eCryptfs; regular LUKS encryption will -do nicely. - -Introduction -============ +Open source BIOS/UEFI firmware +------------ Система побудови canoeboot, називається `cbmk`, скорочення від `CanoeBoot MaKe`, і цей документ описує те, як використовувати її. З цим керівництвом ви можете узнати те, як побудувати @@ -34,8 +25,16 @@ canoeboot з доступного джерельного коду. Наступний документ описує те, як працює `cbmk`, і як ви можете робити зміни до нього: [керівництво обслуговування canoeboot](../maintain/) +### WARNING: eCryptfs file name limits + +Do not run the build system on a eCryptfs file system, because it has +very short file name limits and Canoeboot's build system deals with very +long file names. We commonly get reports from this by Linux Mint users +who encrypt their home directory with eCryptfs; regular LUKS encryption will +do nicely. + System requirements -=================== +------------------- You must ensure that you have the correct operating system, CPU, RAM, disk space and so on. @@ -44,7 +43,7 @@ System requirements are documented in the [cbmk maintenance manual](../maintain/#system-requirements). Multi-threaded builds -===================== +--------------------- Canoeboot's build system defaults to a single build thread, but you can change it by doing e.g. @@ -58,15 +57,15 @@ is passed, where THREADS is the number of threads. This is also set when running xz commands for compression, using the `-t` option. Environmental variables -======================= +----------------------- Please read about environmental variables in [the build instructions](../maintain/), before running cbmk. You should set your variables accordingly, though you do not technically need to; some of them may be useful, e.g. `XBMK_THREADS` (sets the number of build threads). -Introduction -============ +Environmental variables +----------------------- Please read about environmental variables in [the build instructions](../maintain/), before running cbmk. You should set @@ -74,7 +73,7 @@ your variables accordingly, though you do not technically need to; some of them may be useful, e.g. `XBMK_THREADS` (sets the number of build threads). Git -=== +--- Система побудови Canoeboot використовує Git, обширно. Ви маєте виконати кроки знизу, *навіть, якщо ви використовуєте архів випуску*. @@ -94,17 +93,15 @@ Git Build -===== +----- -Zero..st, check time/date -------------------------- +### Zero..st, check time/date Make sure date/hwclock report the correct time and date on your system, because parts of the build process download from HTTPS servers and wrong time or date can cause connections to be dropped during negotiation. -Побудова з джерельного коду -============================ +### Побудова з джерельного коду Фактична розробка/тестування завжди виконується безпосередньо за допомогою `cbmk`, і це також стосується збирання з джерельного коду. Ось кілька інструкцій, щоб @@ -129,8 +126,7 @@ Check: `config/dependencies/` for list of supported distros. Однак, вам потрібно буде написано свій власний сценарій для встановлення залежностей побудови. -Debian Trixie/Sid ------------------ +### Debian Trixie/Sid Debian Trixie, the testing release as of 3 January 2025, and Debian Sid, provide `gnat` and `gcc` as you expect, but `gnat` resolves to `gnat-13` and @@ -167,8 +163,7 @@ When we tested with this configuration, the KGPE-D16 images also compiled. NOTE: Ubuntu 24.10 also has the issue described above. Some other distros may also have it, if they're based on Debian Testing/Sid or Ubuntu 24.10. -MIPS cross compiler -------------------- +### MIPS cross compiler Canoeboot has support for the Sony PlayStation (PS1/PSX), based on the PCSX-Redux Open BIOS. If you're doing a full release build, and/or @@ -183,8 +178,7 @@ If your distro doesn't have the MIPS compiler available, the [PlayStation](../install/playstation.md) page provides instructions for manual installation; please do this in addition to the normal dependencies. -Next, build ROM images ----------------------- +### Next, build ROM images В якості результату, ви тепер можете (після встановлення правильних залежностей побудови) виконати лише одну команду, з свіжого Git clone, для побудови образів ROM: diff --git a/site/docs/grub/index.md b/site/docs/grub/index.md index d5cb085..53c042a 100644 --- a/site/docs/grub/index.md +++ b/site/docs/grub/index.md @@ -8,17 +8,19 @@ documentation, but there are aspects of Canoeboot that deserve special treatment. Canoeboot provides the option to boot GRUB directly, running on bare metal (instead of using BIOS or UEFI services). -[The Linux section](../linux/) also has canoeboot-specific guides for +Boot Linux from GRUB +-------------------- + +[The Linux section](../linux/) also has Canoeboot-specific guides for dealing with Linux distributions when using GRUB directly, in this setup. [A similar section exists for BSD operating systems](../bsd/) GRUB keyboard layouts -===================== +--------------------- It is possible to use *any* keymap in GRUB. -Custom keyboard layout ----------------------- +### Custom keyboard layout Keymaps are stored in `config/grub/keymap/` @@ -30,7 +32,7 @@ files: When you build GRUB from source, you can use the `grub-mklayout` program to create a special keymap file for GRUB. [Learn how to build GRUB](../build/) -To compile GRUB, in lbmk, do this: +To compile GRUB, in cbmk, do this: ./mk -b grub default diff --git a/site/docs/index.md b/site/docs/index.md index b2c7c59..06dcae4 100644 --- a/site/docs/index.md +++ b/site/docs/index.md @@ -1,5 +1,5 @@ --- -title: Documentation +title: Canoeboot documentation ... Always check the Canoeboot website for the latest updates to @@ -8,22 +8,24 @@ the [main news section](../news/). [Answers to Frequently Asked Questions about Canoeboot](../faq.md). -What is Canoeboot? An article is available for that; please read the -article titled [What is Canoeboot?](../about.md). +Need help? +---------- + +Help is available on [Canoeboot IRC](../contact.md) and other channels. Installing Canoeboot -==================== +-------------------- - [How to install Canoeboot](install/) -Documentation related to operating systems -============================ +Installing operating systems +---------------------------- - [How to install BSD operating systems](bsd/) - [How to install Linux](linux/) Information for developers -========================== +-------------------------- - [How to compile the Canoeboot source code](build/) - [Build system developer documentation](maintain/) @@ -31,7 +33,7 @@ Information for developers - [U-Boot payload](uboot/) Other information -================= +----------------- - [Miscellaneous](misc/) - [List of codenames](misc/codenames.md) diff --git a/site/docs/index.uk.md b/site/docs/index.uk.md index a250422..335d9f6 100644 --- a/site/docs/index.uk.md +++ b/site/docs/index.uk.md @@ -8,22 +8,23 @@ Canoeboot. Новини, включаючи оголошення про випу [Відповіді на поширені запитання про Canoeboot](../faq.md). -What is Canoeboot? An article is available for that; please read the -article titled [What is Canoeboot?](../about.md). +Need help? +---------- + +Help is available on [Canoeboot IRC](../contact.md) and other channels. Встановлення Canoeboot -==================== - [Як встановити Canoeboot](install/) Документація, яка має відношення до операційних систем -============================ +----------------------------------------------------- - [Як встановити BSD на x86 хостову систему](bsd/) - [Керівництва Linux](linux/) Інформація для розробників -========================== +-------------------------- - [Як зібрати джерельний код Canoeboot](build/) - [Документація розробника системи побудови](maintain/) @@ -31,7 +32,7 @@ article titled [What is Canoeboot?](../about.md). - [Корисне навантаження U-Boot](uboot/) Інша інформація -================= +--------------- - [Різне](misc/) - [Список кодових назв](misc/codenames.md) diff --git a/site/docs/index.zh-cn.md b/site/docs/index.zh-cn.md index 6a5e48e..b8fd614 100644 --- a/site/docs/index.zh-cn.md +++ b/site/docs/index.zh-cn.md @@ -2,26 +2,31 @@ title: 文档 ... -canoeboot 的最新更新，可以在 [canoeboot.org](https://canoeboot.org) 上找到。新闻，包括新版发布公告，可以在[新闻主页](../news/)中找到。 +Canoeboot 的最新更新，可以在 [canoeboot.org](https://canoeboot.org) 上找到。新闻，包括新版发布公告，可以在[新闻主页](../news/)中找到。 -[canoeboot 常见问题解答](../faq.md). +[Canoeboot 常见问题解答](../faq.md). What is Canoeboot? An article is available for that; please read the article titled [What is Canoeboot?](../about.md). -安装 canoeboot -==================== +Need help? +---------- + +Help is available on [Canoeboot IRC](../contact.md) and other channels. + +安装 Canoeboot +-------------- - [如何安装 Canoeboot](install/) 操作系统相关文档 -============================ +---------------- - [如何在 x86 机器上安装 BSD](bsd/) - [Linux 指南](linux/) 开发者信息 -========================== +---------- - [如何编译 canoeboot 源代码](build/) - [构建系统开发者文档](maintain/) @@ -29,7 +34,7 @@ article titled [What is Canoeboot?](../about.md). - [U-Boot payload](uboot/) 其它信息 -================= +-------- - [杂项](misc/) - [代号列表](misc/codenames.md) diff --git a/site/docs/install/c201.md b/site/docs/install/c201.md index 9af2b50..05ff5ac 100644 --- a/site/docs/install/c201.md +++ b/site/docs/install/c201.md @@ -1,8 +1,15 @@ --- -title: ASUS Chromebook C201 installation guide +title: Install Canoeboot ASUS Chromebook C201 x-toc-enable: true ... +Open source BIOS/UEFI firmware +------------------------------ + +This document will teach you how to install Canoeboot, on your +ASUS Chromebook C201 motherboard. Canoeboot replaces proprietary +BIOS/UEFI firmware. + WARNING: This board is known to have non-functioning video init at the time of writing, 19 February 2023. It is as yet unsolved. @@ -10,14 +17,13 @@ See: (NOTE: Libreboot issue page not Canoeboot) Introduction -=========== +------------ This page contains information about assembly and disassembly, for flashing the ASUS Chromebook C201 externally. It will also link to internal flashing instructions, and information about U-Boot. -Flashrom --------- +### Flashrom A special fork of flashrom, maintained by Google, is required for flashing. More information about this is present in the generic [chromebook flashing @@ -27,8 +33,7 @@ NOTE: Canoeboot standardises on [flashprog](https://flashprog.org/wiki/Flashprog now, as of 3 May 2024, which is a fork of flashrom, but the chromium fork is another fork of flashrom, and you should use that on chromebooks. -Depthcharge payload (obsolete) ------------------------------- +### Depthcharge payload (obsolete) This board was also supported in Libreboot 20160907, with the Depthcharge payload. Support was dropped in later releases, and then re-added in the @@ -41,7 +46,7 @@ instructions pertaining to Depthcharge: * U-boot payload -============== +-------------- U-Boot was ported to coreboot CrOS devices, courtesy of Alper Nebi Yasak on behalf of the Libreboot project, upon which Canoeboot is based. @@ -51,7 +56,7 @@ Read the section pertaining to U-boot payload: [u-boot payload documentation for Canoeboot](../uboot/) Internal flashing -================= +------------------ External flashing is possible, but only necessary in the event of a *brick*. If you're flashing good firmware, and the machine boots properly, you can @@ -63,8 +68,7 @@ the information has moved. See: [chromebook flashing instructions](chromebooks.md) -Write-protect screw -------------------- +### Write-protect screw The chromebook flashing instructions, linked above, refer to a *screw* that can be turned, to disable flash protection. This is necessary, for internally @@ -87,7 +91,7 @@ The write protect screw can be put back in place later, when the device is known to be in a working state. External flashing -================= +----------------- If the machine is no longer booting, due to bad firmware, you can unbrick it externally. Refer to [external flash instructions](spi.md). diff --git a/site/docs/install/chromebooks.md b/site/docs/install/chromebooks.md index 6487c63..ff8b926 100644 --- a/site/docs/install/chromebooks.md +++ b/site/docs/install/chromebooks.md @@ -1,14 +1,30 @@ --- -title: Chromebook flashing instructions +title: Install Canoeboot on a Chromebook x-toc-enable: true ... +Open source BIOS/UEFI firmware +------------------------------ + +This document will teach you how to install Canoeboot, on various ARM64-based +Chromebook laptops. Canoeboot replaces proprietary BIOS/UEFI firmware, though +it should be noted that Google already ships coreboot and their own payload +called Depthcharge, which is all free software; the difference with Canoeboot +is that it replaces Depthcharge with *U-Boot* (as a coreboot payload), which +provides a lightweight UEFI boot implementation that can boot regular Linux and +BSD systems more easily than Depthcharge. + +NOTE: daisy, peach and veyron boards were temporarily removed from +cbmk. They should be re-added to Canoeboot at a later date. The reasons +are written on the hardware compatibility page. For now, Canoeboot only +officially supports the `nyan` and `gru` chromebooks. + This page attempts to give a brief, general overview of how to flash custom firmware on ChromeOS devices. This guide usually refers to all of them as "Chromebook"s since it's the most common form factor. Flashrom -======== +-------- A special fork of flashrom, maintained by Google, is required for flashing these Chromebook devices. See: @@ -18,7 +34,7 @@ these Chromebook devices. See: You must then compile this from source, and run it. Enable ChromeOS "Developer Mode" -================================ +-------------------------------- Chromebooks are locked-down by default to only run ChromeOS. Most things you will want to do on these require you unlock it by enabling their @@ -39,7 +55,7 @@ where you can run programs. Most of the root file system is read-only, except for `/usr/local` and any mounted drives under `/media/removable`. Identify your device -==================== +-------------------- It's more common to refer to ChromeOS boards by their codenames, and many compatible devices can share a single codename. Canoeboot ROM @@ -51,7 +67,7 @@ device's. There are a number of ways to find it, some are: - Run `crossystem hwid` or `crossystem fwid` in a terminal Back up stock firmware -====================== +---------------------- The stock firmware on your device comes with some irreplaceable data that is unique to your device. This can include the serial number and @@ -73,7 +89,7 @@ If you can already boot a conventional Linux distro on your Chromebook, you may be able to use `flashrom -p linux_mtd` on that system instead. Check external flashability -=========================== +--------------------------- If a ROM image you flash is broken, you may need to restore the stock firmware to fix the board to get internal flashing working. Refer to the @@ -88,7 +104,7 @@ mechanism that lets you flash externally using a special USB debugging cable. However, most boards that Canoeboot supports do not have this. Disable write protection -======================== +------------------------ Chromebooks have the SPI flash chip partially write-protected by default, but thankfully this protection can be disabled by the device @@ -123,7 +139,7 @@ compile and use that flashrom fork to disable write-protection. There is no `cbmk` support yet for automatically building it. Prepare the ROM image -===================== +--------------------- Canoeboot ROM image layouts are currently incompatible with the regions that should be carried over from the stock firmware. However, the @@ -138,7 +154,7 @@ keep backups of the original firmware. TODO: Instructions to preserve vital data when FMAPs are compatible. Flash the ROM image -=================== +------------------- WARNING: Although none are supported yet, make sure not to flash ROM images on x86 Chromebooks without injecting non-redistributable blobs @@ -158,7 +174,7 @@ If you can already boot a conventional Linux distro on your Chromebook, you may be able to use `flashrom -p linux_mtd` on that system instead. Install an operating system (experimental research) -=========================== +------------------------------------------------ In general, ARM-compatible distros targeting U-boot can be used. There are three general methods for installing that vary depending on the distribution: @@ -168,25 +184,22 @@ three general methods for installing that vary depending on the distribution: 3. extlinux.conf - a newer flat, bootloader-spec text file that typically lives in /boot/extlinux/extlinux.conf -Successful installations: -------------------------- +### Successful installations: * [ArchLinuxARM on RK3399-based Chromebooks](../uboot/uboot-archlinux.md). * [Debian Bookworm on Samsung Chromebook Plus XE513C24](../uboot/uboot-debian-bookworm.md). * [Debian on Asus Chromebook C201](https://wiki.debian.org/InstallingDebianOn/Asus/C201). -Unsuccessful installations: ---------------------------- +### Unsuccessful installations: * [OpenBSD on Samsung Chromebook Plus XE513C24](../uboot/uboot-openbsd.md). -Other promising ARM-compatible distros: ---------------------------------------- +### Other promising ARM-compatible distros: * [Armbian](https://www.armbian.com/uefi-arm64/). See also -======== +-------- * [ChromiumOS Documentation](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/) * [ChromiumOS Firmware Test Manual](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/firmware_test_manual.md) diff --git a/site/docs/install/d945gclf.md b/site/docs/install/d945gclf.md index 4d95c7e..00766e2 100644 --- a/site/docs/install/d945gclf.md +++ b/site/docs/install/d945gclf.md @@ -1,5 +1,5 @@ --- -title: Intel D945GCLF desktop board +title: Install Canoeboot on Intel D945GCLF and/or D945GCLF2 x-toc-enable: true ... @@ -21,7 +21,7 @@ motherboard while they still have the original BIOS present. | **Graphics** | ? | | **Display** | None. | | **Memory** | Up to 2GB | -| **Architecture** | x86_64 | +| **Architecture** | x86\_64 | | **Original boot firmware** | Intel BIOS | | **Intel ME/AMD PSP** | Not present. | | **Flash chip** | SOIC-8 512KiB | @@ -50,13 +50,21 @@ P*: Partially works with vendor firmware | **SeaBIOS** | Works | | **SeaBIOS with GRUB** | Doesn't work | + +Open source BIOS/UEFI firmware +------------------------------ + +This document will teach you how to install Canoeboot, on your +Intel D945GCLF and/or D945GCLF2 desktop motherboard. Canoeboot replaces +proprietary BIOS/UEFI firmware. + If you just want flashing instructions, go to [../install/d945gclf.md](../install/d945gclf.md) D945GCLF2D also reported working by a user. Introduction -============ +------------ This board is a mini-itx desktop board for 2008. It uses an atom 230, which is a singe core CPU but it is hyperthreaded so it appears to have @@ -79,8 +87,7 @@ hyperthreaded). Since the board is almost identical (and coreboot code seem to indicate that it works, since MAX\_CPU=4 is set), it is believed that it should also work but this is untested. -Remarks about vendor bios: --------------------------- +### Remarks about vendor bios: - Without Canoeboot or Libreboot this board is completely useless, since the vendor bios is very bad. It cannot boot from any HDD whether it is @@ -99,15 +106,14 @@ And SPI SOIC8 flash chip\ ![](https://av.canoeboot.org/d945gclf/20160923_141550.jpg){width="50%" height="50%"} Flashing instructions {#clip} -===================== +----------------------------- Refer to [spi.md](spi.md) for how to re-flash externally. Here is an image of the flash chip:\ ![](https://av.canoeboot.org/d945gclf/d945gclf_spi.jpg) -How to replace thermal paste and fan ------------------------------------- +### How to replace thermal paste and fan This board comes with very crappy disposable loud fan, that one has no bearings, which can not be repaired or oiled properly, do not waste your diff --git a/site/docs/install/dell780.md b/site/docs/install/dell780.md index 377c013..33b4951 100644 --- a/site/docs/install/dell780.md +++ b/site/docs/install/dell780.md @@ -1,5 +1,5 @@ --- -title: Dell OptiPlex 780 MT/USFF +title: Install Canoeboot on Dell OptiPlex 780 MT/USFF x-toc-enable: true ... @@ -52,14 +52,18 @@ P*: Partially works with vendor firmware | **SeaBIOS** | Works | | **SeaBIOS with GRUB** | Works | -Introduction -============ + +Open source BIOS/UEFI firmware +------------------------- + +This document will teach you how to install Canoeboot, on your +Dell OptiPlex 780 desktop motherboard. Canoeboot replaces proprietary +BIOS/UEFI firmware. Official information about the computer can be found here: -Build ROM image from source ---------------------------- +### Build ROM image from source The build target, when building from source, is thus: @@ -72,25 +76,27 @@ The `_truncate` image is needed if you're flashing Canoeboot internally from the original Dell firmware. Otherwise, you only need the regular images that lack `_truncate` in the file name. -100% FREE -========= +Alternatively, you can use release images instead of compiling from source. + +### 100% FREE / OPEN SOURCE! This mainboard is entirely free software in the main boot flash. It is using the Intel X4X / ICH10 platform, same as on the already supported Gigabyte GA-G41M-ES2L mainboard. -Installation -============ +Install Canoeboot +----------------- -Set MAC address ---------------- +These next sections will teach you how to install Canoeboot, on your +Dell OptiPlex 780 motherboard. + +### Set MAC address This platform uses an Intel Flash Descriptor, and defines an Intel GbE NVM region. As such, release/build ROMs will contain the same MAC address. To change the MAC address, please read [nvmutil documentation](../install/nvmutil.md). -WARNING about CPU/GPU compatibility -------------------------------- +### WARNING about CPU/GPU compatibility Coreboot has libre initialisation code for Intel graphics, but libre initialisation code is not available for most graphics cards. This machine can @@ -99,8 +105,7 @@ used, SeaBIOS executes its VGA ROM which provides video init, instead of coreboot's native Intel video init. GRUB piggybacks off of what SeaBIOS did, so the GRUB payload will also work. -Flash a ROM image (software) ------------------ +### Flash a ROM image (software) **Always make sure to dump a copy of the current flash first. ALSO: [make sure /dev/mem protection is disabled](devmem.md) for the flashing to work!** @@ -149,8 +154,7 @@ the full image; the one without `_truncate` in the file name uses all of the flash, with the BIOS region ending at the 8MB limit, so the BIOS region is therefore 2MB larger on those images. -Flash a ROM image (hardware) ------------------ +### Flash a ROM image (hardware) For general information, please refer to [25xx NOR flash instructions](../install/spi.md) - that page refers to use of socketed flash. diff --git a/site/docs/install/devmem.md b/site/docs/install/devmem.md index cdcbf16..fd2e21e 100644 --- a/site/docs/install/devmem.md +++ b/site/docs/install/devmem.md @@ -12,7 +12,7 @@ access once you no longer need it, as this is a useful security layer against any wrongful operations that you may later inadvertently run as root. Also disable SecureBoot -======================= +----------------------- If you're using a UEFI setup, it's probably because you're using a latter Intel platform and want to flash Canoeboot internally, from @@ -23,7 +23,7 @@ using the factory firmware, please ensure that *SecureBoot* is disabled, because it will interfere with lower memory accesses if left enabled. FLASH ERRORS (and workarounds) -======================= +------------------------------ **NOTE: Canoeboot standardises on [flashprog](https://flashprog.org/wiki/Flashprog) now, which is a fork of flashrom.** @@ -33,8 +33,7 @@ This section relates to installing Canoeboot on supported targets. Right out of the gate, some users may experience errors with flashprog when using the internal programmer. They are: -/dev/mem access error ---------------------- +### /dev/mem access error NOTE: if running `flashprog -p internal` for software based flashing, and you get an error related to `/dev/mem` access, you should reboot with @@ -46,8 +45,7 @@ is `kernel.securelevel=-1`; see [NetBSD securelevel manual](https://wiki.netbsd.org/tutorials/kernel_secure_levels/) and [OpenBSD securelevel manual](https://man.openbsd.org/securelevel). -ERROR: Could not get I/O privileges ------------------------------------- +### ERROR: Could not get I/O privileges Error message: `ERROR: Could not get I/O privileges (Function not implemented)` diff --git a/site/docs/install/ga-g41m-es2l.md b/site/docs/install/ga-g41m-es2l.md index c732697..06e135e 100644 --- a/site/docs/install/ga-g41m-es2l.md +++ b/site/docs/install/ga-g41m-es2l.md @@ -1,5 +1,5 @@ --- -title: Gigabyte GA-G41M-ES2L desktop board +title: Install Canoeboot on Gigabyte GA-G41M-ES2L ...
@@ -18,7 +18,7 @@ GA-G41M-ES2L | **Graphics** | Integrated | | **Display** | None. | | **Memory** | Up to 8GB (2x4GB DDR2-800) | -| **Architecture** | x86_64 | +| **Architecture** | x86\_64 | | **Original boot firmware** | AWARD BIOS | | **Intel ME/AMD PSP** | Present. Can be disabled | | **Flash chip** | 2x8Mbit | @@ -48,8 +48,12 @@ P*: Partially works with vendor firmware | **SeaBIOS with GRUB** | Works |
-Introduction -============ +Open source BIOS/UEFI firmware +------------------------------ + +This document will teach you how to install Canoeboot, on your +Gigabyte GA-G41M-ES2L desktop motherboard. Canoeboot replaces proprietary +BIOS/UEFI firmware. This is a desktop board using intel hardware (circa \~2009, ICH7 southbridge, similar performance-wise to the ThinkPad X200. It can make @@ -85,7 +89,7 @@ You can learn more about using the build system, cbmk, here:\ [Canoeboot build instructions](../build/) RAM -=== +--- **This board is very picky with RAM. If it doesn't boot, try an EHCI debug dongle, serial usb adapter and null modem cable, or spkmodem, to get a @@ -101,7 +105,7 @@ Many other modules will probably work just fine, but raminit is very picky on this board. Your mileage *will* fluctuate, wildly. MAC ADDRESS -=========== +----------- NOTE: due to a bug in the hardware, the MAC address is hardcoded in coreboot. Therefore, you must set your own MAC address in your @@ -112,14 +116,14 @@ distro, to set a valid MAC address. By doing this, your NIC should work nicely. Flash chip size {#flashchips} -=============== +--------------------- Use this to find out: flashprog -p internal Flashing instructions {#clip} -===================== +-------------------------- Refer to [spi.md](spi.md) for how to set up an SPI programmer for external flashing. *You can only externally reprogram one of the chips diff --git a/site/docs/install/ich9utils.md b/site/docs/install/ich9utils.md index cc0053f..496bdb5 100644 --- a/site/docs/install/ich9utils.md +++ b/site/docs/install/ich9utils.md @@ -25,7 +25,7 @@ scrapped. Anyway, ich9utils documentation: Introduction -============ +------------ The `ich9utils` utility from Canoeboot is used to manipulate Intel Flash Descriptors for ICH9M on laptops such as ThinkPad X200 or T400. Specifically, @@ -73,7 +73,7 @@ More information about the ME can be found at Another project: ich9utils -========= +--------- You can find `ich9utils` on the [Libreboot Git page](https://libreboot.org/git.html) or you can download `lbmk` from the same page at an under revision (around Libreboot 20230625 or @@ -90,7 +90,7 @@ Go in there and type `make` to get the binaries: `ich9deblob`, `ich9gen` and `ich9show`. ICH9 show utility {#ich9show} -================ +--------------------------- The *ich9show* utility outputs the entire contents of the descriptor and GbE regions in a given ROM image as supplied by the user. Output is in Markdown @@ -98,7 +98,7 @@ format (Pandoc variant) so that it can be converted easily into various formats. It could even be piped *directly* into pandoc! ICH9 gen utility {#ich9gen} -================ +--------------------------- When you simply run `ich9gen` without any arguments, it generates descriptor+GbE images with a default MAC address in the GbE region. If you wish @@ -190,8 +190,7 @@ Your canoeboot.rom image is now ready to be flashed on the system. Refer back to [../install/\#flashprog](../install/#flashprog) for how to flash it. -Write-protecting the flash chip -------------------------------- +### Write-protecting the flash chip The `ich9gen` utility (see below) generates two types of descriptor+GbE setup: @@ -205,7 +204,7 @@ the contents of flash). For ease of use, Canoeboot provides ROMs that are read-write by default. ICH9 deblob utility {#ich9deblob} -=================== +----------------------------------- This was the tool originally used to disable the ME on X200 (later adapted for other systems that use the GM45 chipset). @@ -284,7 +283,7 @@ back to [index.md/\#gm45](index.md/#gm45) for how to flash it. demefactory utility {#demefactory} -=================== +---------------------------------- This utility has never been tested, officially, but it *should* work. diff --git a/site/docs/install/index.md b/site/docs/install/index.md index 487343f..7174489 100644 --- a/site/docs/install/index.md +++ b/site/docs/install/index.md @@ -1,10 +1,14 @@ --- -title: Canoeboot installation guides +title: Install Canoeboot x-toc-enable: true ... +Open source BIOS/UEFI firmware +------------------------------ + This article will teach you how to install Canoeboot, on any of the supported -laptop, desktop and server motherboards. +laptop, desktop and server motherboards of Intel/AMD x86/x86\_64 and ARM64 +platform. Canoeboot replaces proprietary BIOS/UEFI firmware. **ALWAYS remember to make a backup of the current flash, when overwriting it, regardless of what firmware you currently have and what firmware you're @@ -12,7 +16,7 @@ re-flashing it with; this includes updates between Canoeboot releases. Use the `-r` option in flashprog instead `-w`, to read from the flash.** Install Canoeboot via external flashing -================= +--------------------------------------- Refer to the following article:\ [Externally rewrite 25xx NOR flash via SPI protocol](spi.md) @@ -23,10 +27,13 @@ a backup of the current flash contents, prior to flashing, whether you dump externally or internally - if only external flashing is available, then it's usually the case that only external dumping is available too. -This section relates to installing canoeboot on supported targets. +Need help? +---------- + +Help is available on [Canoeboot IRC](../../contact.md) and other channels. Which systems are supported by Canoeboot? -======================================== +----------------------------------------- Before actually reading the installation guides, please ensure that your system is fully supported by Canoeboot. More information about the Canoeboot @@ -37,19 +44,16 @@ systems, you can use the U-Boot payload (coreboot still initialises hardware). Canoeboot currently supports the following systems: -Games consoles --------------- +### Games consoles - [Sony Playstation](playstation.md) (PS1/PSX) -Servers (AMD, x86) ------------------- +### Servers (AMD, x86) - [ASUS KFSN4-DRE motherboard](kfsn4-dre.md) - [ASUS KGPE-D16 motherboard](kgpe-d16.md) -Desktops (AMD, Intel, x86) --------------------------- +### Desktops (AMD, Intel, x86) - [Acer G43T-AM3](acer_g43t-am3.md) - Apple iMac 5,2 @@ -59,8 +63,7 @@ Desktops (AMD, Intel, x86) - Intel D510MO and D410PT motherboards - [Intel D945GCLF](d945gclf.md) -Laptops (Intel, x86) --------------------- +### Laptops (Intel, x86) - [Apple MacBook1,1 and MacBook2,1](macbook21.md) - [Dell Latitude E4300, E6400, E6400 XFR and E6400 ATG](latitude.md) @@ -71,19 +74,17 @@ Laptops (Intel, x86) - Lenovo ThinkPad T60, X60, X60S, X60 Tablet (with Intel GPU) - [Lenovo ThinkPad X200 / X200S / X200 Tablet](x200.md) -Laptops (ARM, with U-Boot payload) ----------------------------------- +### Laptops (ARM, with U-Boot payload) - [ASUS Chromebook Flip C101 (gru-bob)](chromebooks.md) - [Samsung Chromebook Plus (v1) (gru-kevin)](chromebooks.md) -Emulation ---------- +### Emulation - [Qemu x86 and arm64](../misc/emulation.md) -**Disable security before flashing** -================================ +Disable security before flashing +-------------------------------- **Before internal flashing, you must first disable `/dev/mem` protections. Make sure to re-enable them after you're finished.** @@ -91,7 +92,7 @@ sure to re-enable them after you're finished.** **See: [Disabling /dev/mem protection](devmem.md)** ROM image file names -==================== +-------------------- Canoeboot ROM images are named like this: `payload_board_inittype_displaytype_keymap.rom` @@ -121,7 +122,7 @@ executed instead, if the primary payload is SeaBIOS, whether that be pure SeaBIOS or a SeaGRUB setup. EC firmware updates -=================== +------------------- Obviously, free EC firmware would be preferable, but it is not the case on all machine. We would like to have free EC firmware on more machines, but for @@ -142,23 +143,21 @@ It is recommended that you update to the latest EC firmware version. The Updating the EC can sometimes provide benefit depending on the vendor. For example, they might fix power issues that could then enhance battery life. -ThinkPads ---------- +### ThinkPads See: Otherwise, check the Lenovo website to find the update utility for your mainboard. -Other ------ +### Other The same wisdom applies to other laptop vendors. Non-laptops typically do not have embedded controllers in them. Canoeboot installation instructions -=================================== +----------------------------------- In general, if Canoeboot is already running, you can skip towards the final section on this page, which provides general internal @@ -172,8 +171,7 @@ Therefore, before following generic guides, make sure to check first whether your board has special instructions, otherwise use the generic guide at the end of this article. -Intel GbE MAC address (IFD-based systems) ---------------------------------------- +### Intel GbE MAC address (IFD-based systems) On all Intel platforms except X4X (e.g. Gigabyte GA-G41M-ES2L) and i945 ones (e.g. ThinkPad X60, ThinkPad T60, MacBook2,1), an Intel Flash Descriptor is @@ -183,10 +181,9 @@ flash, and can (must) be changed prior to installation. You can use [nvmutil](nvmutil.md) to change the MAC address. You will perform this modification to the ROM image, before flashing it. -Flash lockdown / boot security -------------------- +### Flash lockdown / boot security -This is referred to informally as *Secure libreBoot*. +This is referred to informally as *Secure canoeBoot*. Full flash lockdown is possible, with cryptographic verification of your Linux kernel and other files, using special features in the GRUB payload. @@ -205,8 +202,7 @@ See: [GRUB hardening / Secure canoeBoot](../linux/grub_hardening.md) If you already did this, it's possible that you may no longer be able to flash internally. If that is the case, you must [flash externally](spi.md). -Updating an existing installation ---------------------------------- +### Updating an existing installation Unless otherwise stated, in sections pertaining to each mainboard below, an existing Canoeboot installation can be updated via internal flashing, @@ -223,16 +219,14 @@ special steps required that differ from updating an existing installation. The next sections will pertain to specific mainboards, where indicated, followed by general internal flashing instructions where applicable. -Dell Latitude laptops (vendor BIOS) ---------------------- +### Dell Latitude laptops (vendor BIOS) See: [Dell Latitude flashing guide](latitude.md) This applies to all supported Dell Latitude models. Remember to [update the MAC address with nvmutil](nvmutil.md), before flashing. -ThinkPad X200/T400/T500/W500/R400/R500 --------------------------------------- +### ThinkPad X200/T400/T500/W500/R400/R500 If you're running one of these with Lenovo BIOS, you must externally flash Canoeboot, because the original firmware restricts writes to the flash. @@ -253,35 +247,30 @@ You can find WSON8 probes online, that are similar to a SOIC8/SOIC16 clip. Your mileage may very, but WSON8 has the same pinout as SOIC8 so you might have some luck with that. -Intel D510MO/D410PT (vendor BIOS) ------------------------ +### Intel D510MO/D410PT (vendor BIOS) See: [External flashing guide](spi.md) - both boards are compatible with the same image. -Gigabyte GA-G41M-ES2L (vendor BIOS) ---------------------- +### Gigabyte GA-G41M-ES2L (vendor BIOS) Internal flashing is possible, from factory BIOS to Canoeboot, but special steps are required. See: [Gigabyte GA-G41M-ES2L installation guide](ga-g41m-es2l.md) -Acer G43T-AM3 (vendor BIOS) --------------------- +### Acer G43T-AM3 (vendor BIOS) See: [Acer G43T-AM3](acer_g43t-am3.md) -MacBook 1,1 / 2,1 / iMac 5,2 (vendor BIOS) -------------------------- +### MacBook 1,1 / 2,1 / iMac 5,2 (vendor BIOS) MacBook *1,1* requires [external flashing](spi.md). MacBook *2,1* can always be flashed internally. iMac 5,2 can be flashed internally. Also check the [Macbook2,1 hardware page](macbook21.md) -ASUS KCMA-D8 / KGPE-D16 (vendor BIOS) --------------------------- +### ASUS KCMA-D8 / KGPE-D16 (vendor BIOS) [You must flash it externally](spi.md) (DIP-8 section) - also look at the [KGPE-D16 hardware page](kgpe-d16.md). @@ -291,8 +280,7 @@ Further information is available on the [KCMA-D8 page](kcma-d8.md). KGPE-D16 installation is essentially the same, with the same type of flash IC (DIP-8). Refer to the external flashing guide. -ASUS KFSN4-DRE (vendor BIOS) -------------------------- +### ASUS KFSN4-DRE (vendor BIOS) This board uses LPC flash in a PLCC32 socket. This coreboot page shows an example of the push pin as a proof of concept: @@ -303,13 +291,11 @@ See: [ASUS KFSN4-DRE guide](kfsn4-dre.md) Hot-swap the flash IC with another one while it's running, and flash it internally. -Intel D945GCLF (vendor BIOS) ---------------------------------- +### Intel D945GCLF (vendor BIOS) See: [Intel D945GCLF flashing guide](d945gclf.md) -ThinkPad T60/X60/X60Tablet/X60S -------------------------------- +### ThinkPad T60/X60/X60Tablet/X60S Only the Intel GPU is compatible. Do not flash the ATI GPU models. @@ -402,8 +388,7 @@ bootblock, set bucts back to zero: The second flash can be done by simply following the general internal flashing guide further down on this page. -ARM-based Chromebooks ---------------------- +### ARM-based Chromebooks See: [Chromebook flashing instructions](chromebooks.md) @@ -412,8 +397,7 @@ the x86 machines, because the Chromebooks still use flashrom with the `-p host` argument instead of `-p internal` when flashing, and you typically need to flash externally, due to Google's security model. -QEMU (arm64 and x86) --------------------- +### QEMU (arm64 and x86) Canoeboot can be used on QEMU (virtual machine), which is useful for debugging payloads and generally trying out Canoeboot, without requiring real hardware. @@ -421,7 +405,7 @@ payloads and generally trying out Canoeboot, without requiring real hardware. See: [Canoeboot QEMU guide](../misc/emulation.md) Install via host CPU (internal flashing) -======================================== +---------------------------------------- NOTE: This mainly applies to the x86 machines. @@ -435,10 +419,9 @@ directly. Internal flashing is often unavailable with the factory firmware, but it is usually possible when Canoeboot is running (barring special circumstances). -Run flashprog on host CPU ------------------------- +### Run flashprog on host CPU -### Flash chip size +#### Flash chip size Use this to find out: @@ -446,7 +429,7 @@ Use this to find out: In the output will be information pertaining to your boot flash. -### Howto: read/write/erase the boot flash +#### Howto: read/write/erase the boot flash How to read the current chip contents: @@ -471,6 +454,3 @@ There is nothing to worry about. If successful, it will either say `VERIFIED` or it will say that the chip contents are identical to the requested image. - -NOTE: there are exceptions where the above is not possible. Read about them in -the sections below: diff --git a/site/docs/install/kcma-d8.md b/site/docs/install/kcma-d8.md index 902f8b4..216fb5d 100644 --- a/site/docs/install/kcma-d8.md +++ b/site/docs/install/kcma-d8.md @@ -1,12 +1,16 @@ --- -title: ASUS KCMA-D8 desktop/workstation board +title: Install Canoeboot on ASUS KCMA-D8 x-toc-enable: true ... TODO: this page is OLD. check that the info is still valid. -Introduction -============ +Open source BIOS/UEFI firmware +------------------------------ + +This document will teach you how to install Canoeboot, on your +ASUS KCMA-D8 server/workstation motherboard. Canoeboot replaces proprietary +BIOS/UEFI firmware. Specifications available here: @@ -36,7 +40,7 @@ If you currently have the ASUS firmware, please ignore the above link and instead refer to the section below: Flashing -======== +-------- The default ASUS firmware write-protects the flash, so you have to remove the chip and re-flash it using external hardware. @@ -56,7 +60,7 @@ Refer to the following guide:\ [Externally rewrite 25xx NOR flash via SPI protocol](../install/spi.md) PCI option ROMs -=============== +--------------- Unlike Libreboot 20160907, Canoeboot in newer releases now supports finding and loading PCI option ROMs automatically, both in GRUB and SeaBIOS on this machine. @@ -66,21 +70,21 @@ So for example, if you wish to use an add-on graphics card, you can! It's no problem, and should work just fine. CPU coolers -=========== +----------- With some creativity, standard AM3+ coolers will work fine. 2 x Socket C32 (LGA1207) available, so you can use 2 CPUs. (up to 32GiB per CPU) CPU compatibility -================= +----------------- - Opteron 4100 series: Incompatible - Opteron 4200 series: Compatible - Opteron 4300 series: Compatible Board status (compatibility) {#boardstatus} -============================ +------------------------------------- There are two ways to identify a supported KCMA-D8 board: @@ -99,14 +103,14 @@ For more detailed information regarding the coreboot port, see Form factor {#formfactor} -=========== +----------------------- This board is ATX form factor. While the [ATX standard, version 2.2](https://web.archive.org/web/20120725150314/http://www.formfactors.org/developer/specs/atx2_2.pdf) specifies board dimensions 305mm x 244mm, this board measures 305mm x 253mm; please ensure that your case supports this extra ~cm in width. IPMI iKVM module add-on {#ipmi} -======================= +---------------------------- Don't use it. It uses proprietary firmware and adds a backdoor (remote out-of-band management chip, similar to the [Intel Management @@ -116,7 +120,7 @@ mainboard since it's on the add-on module, which you don't have to install. Flash chips {#flashchips} -=========== +----------------------- 2MiB flash chips are included by default, on these boards. It's on a P-DIP 8 slot (SPI chip). The flash chip can be upgraded to higher sizes: @@ -133,7 +137,7 @@ Ideally, you should not hot-swap. Only remove the IC when the system is powered down and disconnected from mains. Native graphics initialization {#graphics} -============================== +----------------------------------------- Only text-mode is known to work, but linux(kernel) can initialize the framebuffer display (if it has KMS - kernel mode setting). @@ -147,7 +151,7 @@ because the Nouveau driver can't increase the GPU clock (it doesn't know how, as of 18 March 2021). Current issues {#issues} -============== +---------------------- - Opteron 4100 series CPUs are currently incompatible - LRDIMM memory modules are currently incompatible diff --git a/site/docs/install/kfsn4-dre.md b/site/docs/install/kfsn4-dre.md index bda2759..684df56 100644 --- a/site/docs/install/kfsn4-dre.md +++ b/site/docs/install/kfsn4-dre.md @@ -1,5 +1,5 @@ --- -title: ASUS KFSN4-DRE server/workstation board +title: Install Canoeboot on ASUS KFSN4-DRE x-toc-enable: true ... @@ -18,7 +18,7 @@ x-toc-enable: true | **Graphics** | XGI Z9s VGA Controller | | **Display** | None. | | **Memory** | 512MB, 1GB, 2GB, 4GB | -| **Architecture** | x86_64 | +| **Architecture** | x86\_64 | | **Original boot firmware** | AMIBIOS | | **Intel ME/AMD PSP** | Not present. | | **Flash chip** | PLCC 1MiB (Upgradable to 2MiB) | @@ -46,6 +46,13 @@ P+: Partially works; | **SeaBIOS with GRUB** | Partially works | +Open source BIOS/UEFI firmware +------------------------------ + +This document will teach you how to install Canoeboot, on your +ASUS KFSN4-DRE server/workstation motherboard. Canoeboot replaces proprietary +BIOS/UEFI firmware. + This is a server board using AMD hardware (Fam10h). It can also be used for building a high-powered workstation. Powered by Canoeboot. @@ -56,14 +63,14 @@ NOTE: Canoeboot standardises on [flashprog](https://flashprog.org/wiki/Flashprog now, as of 3 May 2024, which is a fork of flashrom. Form factor {#formfactor} -=========== +--------------------- These boards use the SSI EEB 3.61 form factor; make sure that your case supports this. This form factor is similar to E-ATX in that the size is identical, but the position of the screws are different. Flash chips {#flashchips} -=========== +----------------------- These boards use LPC flash (not SPI), in a PLCC socket. The default flash size 1MiB (8Mbits), and can be upgraded to 2MiB (16Mbits). @@ -76,18 +83,18 @@ extractor. These can be found online. See * Native graphics initialization {#graphics} -============================== +--------------------------------------- Native graphics initialization exists (XGI Z9s) for this board. Framebuffer- and text-mode both work. A serial port is also available. Memory -====== +------- DDR2 533/667 Registered ECC. 16 slots. Total capacity up to 64GiB. Hex-core CPUs {#hexcore} -============= +--------------------- PCB revision 1.05G is the latest version of this board and the best one (the revision number is be printed on the board), if you want to use @@ -101,7 +108,8 @@ To be sure your board supports a CPU check the official ASUS website here: If you are running a Hex-Core CPU on any board version, please contact us. Board configurations {#configurations} -============== +---------------------------------------- + There are 7 different configurations of this board: "standard", 2S, iKVM, iKVM/IST, SAS, SAS/iKVM and SAS/iKVM/IST. @@ -120,7 +128,7 @@ The IST versions with PCB revision 1.05G are the ones who are believed to support the six core Opteron Istanbul processors (2400 and 8400 series). Current issues {#issues} -============== +----------------------- - There seems to be a 30 second bootblock delay (observed by tpearson); the system otherwise boots and works as expected. See @@ -147,7 +155,7 @@ Current issues {#issues} the USB booting doesn't work. Other information -================= +------------------ [specifications](https://web.archive.org/web/20181212180051/http://ftp.tekwind.co.jp/pub/asustw/mb/Socket%20F/KFSN4-DRE/Manual/e3335_kfsn4-dre.pdf) diff --git a/site/docs/install/kgpe-d16.md b/site/docs/install/kgpe-d16.md index 85a359e..fb36c65 100644 --- a/site/docs/install/kgpe-d16.md +++ b/site/docs/install/kgpe-d16.md @@ -3,10 +3,17 @@ title: ASUS KGPE-D16 server/workstation board x-toc-enable: true ... +Open source BIOS/UEFI firmware +------------------------------ + +This document will teach you how to install Canoeboot, on your +ASUS KGPE-D16 server/workstation motherboard. Libreboot replaces proprietary +BIOS/UEFI firmware. + TODO: OLD page. TODO: check that all the info is still valid. -Introduction -============ +Free your BIOS today! +--------------------- This is a server board using AMD hardware (Fam10h *and Fam15h* CPUs available). It can also be used for building a high-powered workstation. @@ -26,24 +33,24 @@ possible to re-flash using software running in Linux on the KGPE-D16, without using external hardware. CPU compatibility -================= +----------------- Opteron 62xx and 63xx CPUs work just fine. Board status (compatibility) {#boardstatus} -============================ +--------------------- See . Form factor {#formfactor} -=========== +---------------------- These boards use the SSI EEB 3.61 form factor; make sure that your case supports this. This form factor is similar to E-ATX in that the size is identical, but the position of the screws are different. IPMI iKVM module add-on {#ipmi} -======================= +-------------------------- Don't use it. It uses proprietary firmware and adds a backdoor (remote out-of-band management chip, similar to the [Intel Management @@ -53,7 +60,7 @@ mainboard since it's on the add-on module, which you don't have to install. Flash chips {#flashchips} -=========== +-------------------------- 2MiB flash chips are included by default, on these boards. It's on a P-DIP 8 slot (SPI chip). The flash chip can be upgraded to higher sizes: @@ -72,13 +79,13 @@ This guide shows how to flash the chip:\ [25xx NOR flashing guide](../install/spi.md) Native graphics initialization {#graphics} -============================== +---------------------------------- Only text-mode is known to work, but linux(kernel) can initialize the framebuffer display (if it has KMS - kernel mode setting). Current issues {#issues} -============== +---------------------------------- - LRDIMM memory modules are currently incompatible (IT MAY WORK NOWADAYS, TODO TEST) diff --git a/site/docs/install/latitude.md b/site/docs/install/latitude.md index 166b6dc..3602b43 100644 --- a/site/docs/install/latitude.md +++ b/site/docs/install/latitude.md @@ -1,14 +1,26 @@ --- -title: Flashing Canoeboot on Dell Latitude laptops +title: Install Canoeboot on Dell Latitude laptops x-toc-enable: true ... +Open source BIOS/UEFI firmware +------------------------------ + +This document will teach you how to install Canoeboot, on various models of +Dell Latitude laptop motherboard, namely Dell Latitude E4300, E6400, E6400 XFR, +E6400 ATG; you must only install Canoeboot on models with *Intel graphics*. +Canoeboot replaces proprietary BIOS/UEFI firmware. + +In case any models are unlisted in the above paragraph, you should also check +the full list of supported Dell Latitude models on the [Canoeboot hardware +compatibility](./#which-systems-are-supported-by-canoeboot) page. + All of the Dell Latitude models can be flashed internally, which means that you do not need to disassemble them. You can do it from Linux or BSD, using the instructions on this page. Disable security before flashing -================================ +-------------------------------- Please also [disable /dev/mem protection](devmem.md), otherwise flashprog and dell-flash-unlock won't work. You can re-enable the protections after @@ -19,13 +31,13 @@ Note that Canoeboot does not currently implement UEFI on x86 platforms, but you can set up [Secure canoeBoot](../linux/grub_hardening.md) after flashing. MAC address -=========== +----------- Make sure to set your own MAC address in the ROM image before flashing. Please read the [nvmutil manual](nvmutil.md) which says how to do this. Thermal safety -============== +-------------- **Thermal safety**: this machine shuts down very quickly, when the machine exceeds 80c CPU temperature, which is far more conservative than on most @@ -34,17 +46,23 @@ excellent. More info available [here](../install/dell_thermal.md). This is a known bug, but otherwise the machine will be mostly stable. Machine-specific notes -====================== +---------------------- -dGPU variants -------------- +### Latitude E6400 + +Vendor files not required for Dell Latitude E6400 if you have the Intel GPU. + +If you have the Nvidia model, please use the `e6400nvidia_4mb` target, and +make sure to run the [inject script](ivy_has_common.md) prior to flashing. + +### dGPU variants Only the models with Intel graphics are supported in Canoeboot, since these can be booted with free graphics initialisation, whereas the discrete GPUs require binary blobs which are not allowed in Canoeboot. Internal flashing -================= +----------------- You can simply boot Linux or BSD, on the Dell Latitude you wish to flash, and run `flashprog` from there, for Canoeboot installation. Certain other steps @@ -105,12 +123,11 @@ successful. If you don't see that, or you're unsure, please [contact the Canoeboot project via IRC](../../contact.md). External flashing -================= +----------------- -General guidance ----------------- +### General guidance -Machine-specific disassembly instructions not provided, but you can find +Machine-specific disassembly instructions are not provided, but you can find the hardware maintenance manual for your Latitude module online. Just search for it. The flash chips(s) is/are usually under the keyboard/palmrest. Near to the PCH/southbridge. @@ -128,10 +145,9 @@ Please read the [external SPI flash guide](spi.md) External flashing is usually not required, on these machines. -Chip size guidance ------------------- +### Chip size guidance -SOme Dell Latitudes use a single flash chip, so you can +Some Dell Latitudes use a single flash chip, so you can just use the ROM images as-is. If there are two flash chips, you must split the ROM images. Check the silk diff --git a/site/docs/install/mac_address.md b/site/docs/install/mac_address.md index d213d2f..06d5d82 100644 --- a/site/docs/install/mac_address.md +++ b/site/docs/install/mac_address.md @@ -4,7 +4,7 @@ x-toc-enable: true ... Introduction (GM45+e1000) -========================= +------------------------- This section is applicable to all supported laptops with the mobile 4 series chipset (as shown in `$ lspci`) @@ -17,15 +17,11 @@ for the built-in gigabit ethernet controller is stored inside the flash chip, along with Canoeboot and other configuration data. Therefore, installing Canoeboot will overwrite it. -Thus, for these laptops, prebuilt Canoeboot already contains a generic -MAC address in the configuration section. This address is `00:f5:f0:40:71:fe -in builds before 2018-01-16 and `00:4c:69:62:72:65` (see the ascii character -set) afterwards. +Thus, for these laptops, prebuilt Canoeboot images already contain a generic +MAC address in the GbE region. Unless you change it, your computer will boot and use it. This can lead to network problems if you have more than one Canoeboot computer on -the same layer2 network (e.g. on the same network switch). The switch -(postman) will simply not know who to deliver to as the MAC (house) addresses -will be the same. +the same layer2 network (e.g. on the same network switch). To prevent these address clashes, you can either modify prebuilt Canoeboot to use an address of your own choosing or you can change the address in your @@ -35,7 +31,7 @@ In either case, it is a good idea to write down the address that your computer originally had. Obtaining the existing MAC address -================================== +---------------------------------- The existing MAC address may be obtained by the following methods: @@ -65,7 +61,7 @@ The existing MAC address may be obtained by the following methods: updated. Changing the MAC address in the operating system -================================================ +------------------------------------------------ There are three portable ways of doing so: @@ -90,8 +86,8 @@ init scripts or you can use your operating system's own networking configuration. Refer to your operating system's documentation for how to do this. -Changing the MAC address on X200/T400/T500/W500 -=============================================== +Changing the MAC address on X200/T400/T500/W500 (OBSOLETE) +----------------------------------------------- On GM45 laptops with ICH9M southbridge and Intel PHY module, the MAC address is hardcoded in boot flash, which means it can be changed if you re-flash. @@ -101,8 +97,26 @@ See [ich9utils documentation](../install/ich9utils.md) If *all* you want to do is change the MAC address, you might try `nvmutil` instead. See notes below: -Also see [nvmutil documentation](../install/nvmutil.md) +Changing the MAC address via nvmutil +----------------------------------------------------------------- -The nvmutil utility is yet another utility provided by Canoeboot, for -changing your MAC address. It is a standalone utility, that operates -only on pre-assembled GbE files. +Nowadays, nvmutil is the preferred way to do it, instead of ich9gen. + +See [nvmutil documentation](../install/nvmutil.md) + +This tool was originally written for changing the MAC address on Intel +Sandybridge, Ivybridge and Haswell platforms, but it can be used on any +platform with a valid GbE region in flash, where an Intel Flash Descriptor +is used; this includes older GM45+ICH9M machines supported by Canoeboot. + +The `ich9utils` program is more useful in an cbmk context, because it +generates an entire Intel Flash Descriptor and GbE region from scratch; +coreboot has a similar method in its build system, using its own utility +called bincfg, but this tool is unused in cbmk. + +No tool like ich9utils exists for these boards yet, but cbmk includes the IFD +and GbE files in-tree. + +You can use `nvmutil` to change the existing MAC address in a GbE region. This +sets the "hardcoded" MAC address, typically a globally assigned one set by +the vendor, but you can use local addresses, and you can use randomised MACs. diff --git a/site/docs/install/macbook21.md b/site/docs/install/macbook21.md index 3aae60a..3a043cd 100644 --- a/site/docs/install/macbook21.md +++ b/site/docs/install/macbook21.md @@ -1,5 +1,5 @@ --- -title: MacBook2,1 and MacBook1,1 +title: Install Canoeboot on MacBook2,1 and MacBook1,1 x-toc-enable: true ... @@ -20,7 +20,7 @@ x-toc-enable: true | **Graphics** | Intel GMA 950 | | **Display** | 1280x800 TFT | | **Memory** | 512MB, 1GB (upgradable to 4GB with 3GB usable) | -| **Architecture** | x86_64 | +| **Architecture** | x86\_64 | | **EC** | Proprietary | | **Original boot firmware** | Apple EFI | | **Intel ME/AMD PSP** | Not present. | @@ -48,6 +48,14 @@ P+: Partially works; | **SeaBIOS** | Works | | **SeaBIOS with GRUB** | Works | + +Open source BIOS/UEFI firmware +------------------------- + +This document will teach you how to install Canoeboot, on your +Apple MacBook 2,1 2005-2007 laptop motherboard. Canoeboot replaces proprietary +BIOS/UEFI firmware. + The MacBook1,1 and MacBook2,1 are very similar to the ThinkPad X60. It shares some hardware with the X60 such as the chipset. @@ -61,15 +69,14 @@ uses Core Duo processors (supports 32-bit OS but not 64-bit), and it is believed that this is the only difference. Compatibility -============= +------------- The following pages list many models of MacBook1,1 and MacBook2,1: * * -Models ------- +### Models Specifically (Order No. / Model No. / CPU) for the MacBook1,1: @@ -97,7 +104,7 @@ then don't forget to [send a patch](../../git.md), confirming that it actually works! Internal flashing -================= +----------------- MacBook2,1 can always be flashed internally, even if running Apple firmware: @@ -110,7 +117,7 @@ The MacBook1,1 can't be flashed internally if running the Apple EFI firmware. You must flash externally. External flashing -================= +----------------- MacBook1,1 requires external flashing, if running the default Apple firmware. MacBook2,1 can be flashed internally, regardless. @@ -130,7 +137,7 @@ Refer to the following guide:\ [Externally rewrite 25xx NOR flash via SPI protocol](../install/spi.md) OSes using Linux on Apple EFI firmware -====================================== +-------------------------------------- You have 2 choices for booting up OSes using Linux as their kernel on the MacBook: @@ -139,8 +146,7 @@ on the MacBook: * Boot via a CD or DVD. -Boot via a CD or DVD --------------------- +### Boot via a CD or DVD The Apple EFI firmware contains a PC BIOS emulation layer for booting Microsoft Windows on CDs and DVDs. That emulation layer **only** works @@ -170,8 +176,7 @@ should boot up properly automatically. to it using GRUB, despite the fact that it does sometimes show up. You also won't be able to boot it up when using Canoeboot.* -Boot via USB ------------- +### Boot via USB This method is harder than booting from a CD/DVD and may soft-brick your MacBook but it's the only way to boot up successfully from a USB. @@ -209,14 +214,14 @@ the CMOS/PRAM battery, wait a few minutes, and put it back in. to reconfigure GRUB2 correctly, else your system won't boot.* Coreboot wiki page -================== +------------------ The following page has some information: * Issues and solutions/workarounds -================================ +-------------------------------- There is one mouse button only, however multiple finger tapping works. The Apple logo on the @@ -227,8 +232,7 @@ should [cover it up](http://cweiske.de/tagebuch/tuxbook.htm). software. Webcams are a privacy and security risk; cover it up! Or remove it.* -Make it overheat less ---------------------- +### Make it overheat less NOTE: in Canoeboot, this section is less relevant, because C3 states are now; the issue pertained to much older releases of [Libreboot](https://libreboot.org/), @@ -269,8 +273,7 @@ PLATFORM_PROFILE_ON_BAT=low-power The MacBook will still overheat, just less. -Enable AltGr ------------- +### Enable AltGr The keyboard has a keypad enter instead of an AltGr. The first key on the right side of the spacebar is the Apple "command" key. On its @@ -294,12 +297,11 @@ line: to the file /etc/vconsole.conf and then restart the computer. -Make touchpad more responsive ------------------------------ +### Make touchpad more responsive Linux kernels of version 3.15 or lower might make the touchpad extremely sluggish. A user reported that they could get better -response from the touchpad with the following in their xorg.conf: +response from the touchpad with the following in their `xorg.conf`: ``` Section "InputClass" diff --git a/site/docs/install/nvmutil.md b/site/docs/install/nvmutil.md index ae71e31..2872bea 100644 --- a/site/docs/install/nvmutil.md +++ b/site/docs/install/nvmutil.md @@ -1,45 +1,35 @@ --- -title: nvmutil manual +title: nvmutil usage instructions x-toc-enable: true ... With this software, you can change the MAC address inside GbE regions -on any system that uses an Intel Flash Descriptor. +on any system that uses an Intel Flash Descriptor. This software works well +on most/all of the major Linux or BSD operating systems. You can use the documentation below, if you wish to use `nvmutil` manually. Continue reading... -Introduction -============ +Change the Intel GbE MAC address +-------------------------------- -This is the manual for `nvmutil`, included in the Canoeboot, -build system (cbmk) under `util/nvmutil/`. This program lets you modify -the MAC address, correct/verify/invalidate checksums, -swap/copy and dump regions on Intel PHY NVM images, -which are small binary configuration files that go -in flash, for Gigabit (ethernet) Intel NICs. +This is the manual for `nvmutil`, included within the [Canoeboot build +system](../maintain/) (cbmk) under `util/nvmutil/`. This program lets you modify +the MAC address, correct/verify/invalidate checksums, swap/copy and dump regions +on Intel PHY NVM images, which are small binary configuration files that go in +flash, for Gigabit (ethernet) Intel NICs. **Please [install build dependencies](../build/) before you do this.** -This software is largely targeted at coreboot users, -but it can be used on most modern Intel systems, or -most systems from about 2008/2009 onwards. +This software is largely targeted at coreboot users, but it can be used on most +modern Intel systems, or most systems from about 2008/2009 onwards, regardless +of which boot firmware they have. -NOTE: Canoeboot X200/X200T/X200S/T400/T400S/T500/W500/R400 -users should know that this software does *not* -replace `ich9gen`, because that program generates entire -ICH9M IFD+GbE regions, in addition to letting you set the -MAC address. *This* program, `nvmutil`, can *also* set -the MAC address on those machines, but it operates on a -single GbE dump that is already created. - -This program is operated on dumps of the GbE NVM image, -which normally goes in the boot flash (alongside BIOS/UEFI -or coreboot, IFD and other regions in the flash). The first -half of this README is dedicated to precisely this, telling -you how to dump or otherwise acquire that file; the second -half of this README then tells you how to operate on it, -using `nvmutil`. +This program is operated on dumps of the GbE NVM image, which normally goes in +the boot flash (alongside BIOS/UEFI or coreboot, IFD and other regions in +the flash). The first half of this README is dedicated to precisely this, +telling you how to dump or otherwise acquire that file; the second half of this +README then tells you how to operate on it, using `nvmutil`. Automatic MAC address changer ----------------------------- @@ -70,7 +60,13 @@ is provided without argument, or no argument is given, the MAC address is randomised. Otherwise, you can specify an arbitrary address. The `?` character is random, and you can specify that any of them be random, -while setting others (or all of them) arbitrarily. +while setting others (or all of them) arbitrarily. On the corresponding nibble, +the bit for unicast/multicast and global/local are set accordingly, so that +randomly generated addresses are *always* unicast and *local*, unless the +corresponding nibble is set arbitrarily; if the latter, then an error is thrown +if the arbitrary nibble corresponds to a multicast MAC address (and when errors +are thrown, the file shall remain unchanged). More information about error +handling is provided, later in this document. The `restore` option restores the original one. The command works by using a reference GbE image file present in Canoeboot's build system, for the given @@ -80,7 +76,7 @@ The Canoeboot version is designed to throw an error, if you run it on a Libreboo tarball. How to download newer versions -============================== +------------------------------ Simply pull down the latest changes in `cbmk.git`. The `nvmutil` software is part of our Canoeboot build system, which we called `cbmk`, @@ -91,7 +87,7 @@ More info about git: * Context -======= +------- On many Intel systems with an IFD (Intel Flash Descriptor), the Intel PHY (Gigabit Ethernet) stores its configuration, binary @@ -122,8 +118,7 @@ This 4KB region is then repeated, to make an 8KB region in flash, known as the *GbE region*. In `nvmutil`, the first part is referred to as *part 0* and the second part as *part 1*. -Known compatible PHYs ---------------------- +### Known compatible PHYs TODO: write a full list her ofe what actual PHYs are known to work. @@ -136,7 +131,7 @@ files; it is assumed that intel would later change the file size and/or checksum value and/or checksum location. How to obtain the GbE file -========================== +-------------------------- The chip containing your BIOS/UEFI firmware (or coreboot) has it, if you have an Intel PHY for gigabit ethernet. @@ -146,8 +141,7 @@ containing your NIC's configuration. This is the part that many people will struggle with, so we will dedicated an entire next section to it: -Use flashprog ------------- +### Use flashprog NOTE: Canoeboot standardises on [flashprog](https://flashprog.org/wiki/Flashprog) now, as of 3 May 2024, which is a fork of flashrom. @@ -194,8 +188,7 @@ option should be changed accordingly. Read flashprog documentation, and make sure you have everything properly configured. -Use ifdtool ------------ +### Use ifdtool NOTE: This has only been tested on systems that use IFDv1 (Intel Flash Descriptor, version 1). This distinction, between @@ -308,7 +301,7 @@ SPI1. You should adjust the above parameters, according to your configuration. How to compile source code -========================== +-------------------------- The nvmutil source code is located under `util/nvmutil/` in the cbmk repository. A makefile is included there, for you to build an @@ -333,8 +326,7 @@ The `nvmutil` software has been build-tested on `Clang`, `GCC` and `tcc`. Only standard library functions (plus `err.h`) are used, so you don't need any extra libraries. -How to compile it ------------------ +### How to compile nvmutil First, ensure that the current working directory is your copy of the nvmutil source code! @@ -350,7 +342,7 @@ whatever is in your `$PATH` for userspace programs). TODO: Add `make install` to the Makefile, portably. How to use nvmutil -================== +------------------ You run it, passing as argument the path to a file, and you run commands on that file. This section will tell you how to @@ -362,8 +354,7 @@ done that, you could still run it in cwd for instance: ./nvm bla bla bla -Exit status ------------ +### Exit status The `nvmutil` program uses `errno` extensively. The best error handling is done this way, the Unix way. Error handling is extremely @@ -389,8 +380,7 @@ of size *8KB*. Additional rules regarding exit status shall apply, depending on what command you use. Commands are documented in the following sections: -Change MAC address ------------------- +### Change MAC address The `nvm` program lets you change the MAC address. It sets a valid checksum, after changing the MAC address. This program @@ -455,8 +445,7 @@ corrected if you use the `setchecksum` command in `nvmutil`. It is common for vendor gbe files to contain one valid part and one invalid part, per checksum rules. -Verify checksums (and show MAC addresses) ------------------------------------------ +### Verify checksums (and show MAC addresses) This command *only* requires *read* access on files. @@ -472,8 +461,7 @@ NOTE: This will exit with zero status if at least one part contains a valid checksum. If both parts are invalid, nvmutil will exit with non-zero status. -Copy part ---------- +### Copy part This command requires read *and* write access on files. @@ -493,8 +481,7 @@ will be performed, and nvmutil will exit with non-zero status. Otherwise, it will (if all other conditions are met) exit with zero status. -Swap parts ----------- +### Swap parts This command requires read *and* write access on files. @@ -513,8 +500,7 @@ If *at least one* part is valid, nvmutil will return with zero exit status. If both parts are invalid, it will return non-zero. -Set valid checksum ------------------- +### Set valid checksum This command requires read *and* write access on files. @@ -534,8 +520,7 @@ set the checksum. There is no feasible way to guard against use on the wrong file, unlike with the other commands. Please make SURE you're running this on the correct file!* -Set invalid checksum --------------------- +### Set invalid checksum This command requires read *and* write access on files. @@ -563,3 +548,12 @@ run `brick` before running `setmac` (or run it afterwards). The Linux kernel's `e1000` driver will refuse to initialise Intel gigabit NICs that don't have a valid checksum. This is software-defined, and not enforced by the hardware. + +TODO +---- + +* Support higher block sizes e.g. 8KB blocks for GbE part sections +* Adapt this into a manpage (useful for Linux package repositories / BSD ports) +* Send nvmutil upstream to coreboot, for inclusion under `util/` +* In addition to the manpage, when sending to coreboot, also adapt this page + for inclusion into doc.coreboot.org diff --git a/site/docs/install/playstation.md b/site/docs/install/playstation.md index 4930114..b4a5f0b 100644 --- a/site/docs/install/playstation.md +++ b/site/docs/install/playstation.md @@ -27,16 +27,16 @@ if you want it to, and you can! | **Original boot firmware** | Sony PS1 BIOS (USA/JPN/EU) | | **Flash chip** | 512KB Mask ROM | -Introduction -============ + +Open source playstation (PS1/PSX) BIOS +--------------------------------- This uses the free/opensource BIOS developed by the PCSX-Redux team, which you can learn more about here: -Build from source ------------------ +### Build from source Canoeboot's build system provides automation for this. Please use the latest cbmk revision [from Git](../../git.md). @@ -65,7 +65,7 @@ This commonly only builds the BIOS part. If you want to build all of PCSX-Redux, you can, but cbmk does not provide automation for this. Installation -============ +------------ If all went well, you should see `openbios.bin` located under the `bin/playstation/` (within cbmk). Alternatively, you may be using @@ -73,8 +73,7 @@ a release *after* Canoeboot 20240612 that has it pre-built. Either way is fine. The `openbios.bin` file is your new BIOS build. -Emulators ---------- +### Emulators Most PlayStation emulators rely on low-level emulation to execute the real BIOS. The Open BIOS by PCSX-Redux (as distributed by Canoeboot) can also be used, and @@ -89,8 +88,7 @@ provided with your chosen PlayStation emulator. You can even freely redistribute this BIOS, because it's free software (released under MIT license), which is a major advantage over Sony's original BIOS. -Hardware --------- +### Hardware Not yet tested by the Canoeboot project, but the PCSX-Redux developers have stated that it will work on the real console. *It should be noted that the Open @@ -114,7 +112,7 @@ BIOS much more polished, but a number of games have been tested and it's more or less fully reliable in most cases. Game compatibility -================== +------------------ The upstream maintains a compatibility list, here: @@ -124,7 +122,7 @@ NOTE: Google Docs, but an option exists on there to export it for LibreOffice Calc. The list is provided as a spreadsheet. Remarks about hardware -==================== +---------------------- Modern NOR flash can be used. You specifically want a TSOP-32 SMD/SMT type device, one that operates at 3.3v (tolerance 2.7 to 3.6v), organised into 512KB blocks, @@ -144,10 +142,9 @@ We do not yet provide instructions for how to install this on real hardware, in the Canoeboot project, but this can be done at a future date. Other mods (hardware) -=============== +--------------------- -Video timings -------------- +### Video timings The Open BIOS will not implement any DRM, so it's possible that you might boot out of region games. In an emulator, this is no problem, but it can prove @@ -197,8 +194,7 @@ By fixing the timings in this way, your region-free console will also have correct timings, thus maximum game compatibility, and colours will always be correct no matter what video cable you're using. -Modchips --------- +### Modchips If using hardware, you will probably still want a modchip. Many proprietary modchip firmwares exist, such as Old crow, MultiMode3 and Mayumi; these run on @@ -226,8 +222,7 @@ not yet been confirmed by the Canoeboot project. More hardware testing is planned, but the Open BIOS works perfectly in emulators. Give it a try! -Boot games on SD cards ------------------------ +### Boot games on SD cards The [PicoStation](https://github.com/paulocode/picostation) project provides free firmware for RP2040 devices, which you can solder into a modboard which @@ -238,8 +233,7 @@ real playstation (the picostation replaces your CD drive). Not only is this useful in a development context, but it can also be used when your CD drive has worn out and no longer reads discs properly. -Final remarks -------------- +### Final remarks Combined with PsNee and PicoStation, the Open BIOS from PCSX-Redux team will turn your 90s PlayStation into a very hackable machine. There is @@ -251,7 +245,7 @@ simply computers, fully reprogrammable and as such, Canoeboot is happy to provid this support, for the Sony PlayStation Credit -====== +------ Thanks go to the PCSX-Redux team for their excellent work reverse engineering the Sony PS1 BIOS. diff --git a/site/docs/install/r400.md b/site/docs/install/r400.md index 8bae747..2991bba 100644 --- a/site/docs/install/r400.md +++ b/site/docs/install/r400.md @@ -1,5 +1,5 @@ --- -title: Flashing the ThinkPad R400 +title: Install Canoeboot on Lenovo ThinkPad R400 x-toc-enable: true ... @@ -21,7 +21,7 @@ x-toc-enable: true GeForce 9300M on some models) | | **Display** | 1280x800/1440x900 TFT | | **Memory** | Up to 8GB | -| **Architecture** | x86_64 | +| **Architecture** | x86\_64 | | **EC** | Proprietary | | **Original boot firmware** | LenovoBIOS | | **Intel ME/AMD PSP** | Present. Can be completly disabled. | @@ -52,16 +52,12 @@ P*: Partially works with vendor firmware | **SeaBIOS with GRUB** | Works | -Dell Latitude E6400 -=================== +Open source BIOS/UEFI firmware +------------------------- -**If you haven't bought an R400 yet: the [Dell Latitude -E6400](../install/latitude.md) is much easier to flash; no disassembly required, -it can be flashed entirely in software from Dell BIOS to Canoeboot. It is the -same hardware generation (GM45), with same CPUs, video processor, etc.** - -Introduction -============ +This document will teach you how to install Canoeboot, on your +Lenovo ThinkPad R400 laptop motherboard. Canoeboot replaces proprietary +BIOS/UEFI firmware. It is believed that all or most R400 laptops are compatible. See notes about [CPU @@ -85,8 +81,16 @@ now, as of 27 January 2024, which is a fork of flashrom. The reason why was explained, in the [Libreboot 20240225 release](https://libreboot.org/news/libreboot20240225.html)** +Dell Latitude E6400 +------------------- + +**If you haven't bought an R400 yet: the [Dell Latitude +E6400](../install/latitude.md) is much easier to flash; no disassembly required, +it can be flashed entirely in software from Dell BIOS to Canoeboot. It is the +same hardware generation (GM45), with same CPUs, video processor, etc.** + EC update {#ecupdate} -========= +-------------------- It is recommended that you update to the latest EC firmware version. The [EC firmware](../../faq.md#ec-embedded-controller-firmware) is separate from @@ -111,7 +115,7 @@ TODO: put hardware register logs here like on the [X200](x200.md) and [T400](t400.md) page. Installation notes -================== +------------------ [External flashing](spi.md) required, if Lenovo BIOS is running. @@ -131,15 +135,14 @@ ROM properly first. Although ROM images are provided pre-built in Canoeboot, there are some modifications that you need to make to the one you chose before flashing. (instructions referenced later in this guide) -Serial port {#serial_port} ------------ +### Serial port {#serial_port} EHCI debug might not be needed. It has been reported that the docking station for this laptop has a serial port, so it might be possible to use that instead. A note about CPUs -================= +----------------- [ThinkWiki](http://www.thinkwiki.org/wiki/Category:R400) has a list of CPUs for this system. The Core 2 Duo P8400 and P8600 are believed to @@ -147,13 +150,12 @@ work in Canoeboot. The Core 2 Duo T9600 was confirmed to work, so the T9400 probably also works. *The Core 2 Duo T5870/5670 and Celeron M 575/585 are untested!* -Quad-core CPUs --------------- +### Quad-core CPUs Incompatible. Do not use. A note about GPUs -================= +----------------- Some models have an Intel GPU, while others have both an ATI and an Intel GPU; this is referred to as "Dual Graphics" (previously @@ -167,12 +169,12 @@ Intel GPU is used and the ATI GPU is disabled, so native graphics initialization works all the same. CPU paste required -================== +------------------ See [\#paste](#paste). Flash chip size {#flashchips} -=============== +----------------------------- Use this to find out: @@ -182,17 +184,16 @@ NOTE: Canoeboot standardises on [flashprog](https://flashprog.org/wiki/Flashprog now, as of 3 May 2024, which is a fork of flashrom. MAC address {#macaddress} -=========== +------------------------- Refer to [mac\_address.md](../install/mac_address.md). External flashing -================= +----------------- Refer to [spi.md](spi.md) as a guide for external re-flashing. -Disassembly ------------ +### Disassembly Remove all screws:\ ![](https://av.canoeboot.org/r400/0000.jpg)\ @@ -278,7 +279,7 @@ Read [this article](spi.md) to learn how you may flash the chip, which is near to the RAM. Thermal paste (IMPORTANT) -========================= +------------------------- Because part of this procedure involved removing the heatsink, you will need to apply new paste. Arctic MX-4 is ok. You will also need isopropyl @@ -295,7 +296,7 @@ show how to properly apply the thermal paste. Other guides online detail the proper application procedure. Memory -====== +------ In DDR3 machines with Cantiga (GM45/GS45/PM45), northbridge requires sticks that will work as PC3-8500 (faster PC3/PC3L sticks can work as PC3-8500). diff --git a/site/docs/install/spi.md b/site/docs/install/spi.md index 34d5122..341f718 100644 --- a/site/docs/install/spi.md +++ b/site/docs/install/spi.md @@ -3,8 +3,51 @@ title: Read/write 25XX NOR flash via SPI protocol x-toc-enable: true ... -NOTE: Canoeboot standardises on [flashprog](https://flashprog.org/wiki/Flashprog) -now, as of 3 May 2024, which is a fork of flashrom. +Need help? +---------- + +Help is available on [Canoeboot IRC](../../contact.md) and other channels. + +Install open source BIOS/UEFI firmware +-------------------------------------- + +This guide is predominantly about *installing Canoeboot* (flashing it) onto +your motherboard's main system flash. You can also adapt this guide for dumping, +erasing and verifying firmware images; this guide shows you how to use +the [flashprog](https://flashprog.org/) software with various external +25XX NOR flash programmers. This guide is written for *Linux* users, but BSD +operating systems are also compatible with flashprog; Windows might be feasible, +ditto Apple's MacOS, as flashprog can also run on those, but they are not +officially supported by Canoeboot, and *we recommend* that you use Linux/BSD. + +Although this documentation is written *for the Canoeboot project*, it can be +used on any compatible 25xx NOR flash, on any number of devices, such as home +routers and even certain videogame systems. If you're a refurbisher, and not +a Canoeboot-based one, but just a regular refurbisher e.g. on eBay, dealing +with proprietary UEFI firmware (and perhaps Windows installations), it may be +that on some of them, SMM-based flash writes are performed to store UEFI firmware +configurations (instead of the old NVRAM/CMOS memory); you could adapt this +guide (and read flashprog documentation) to erase/flash custom configurations, +for example when unlocking boot passwords on the computers that you sell. This +is the power of [Free Software](https://writefreesoftware.org/learn); flashprog +is a Free Software project. The use-case scenario of the humble eBay seller is +real; several of them have in fact used this guide in the past. + +So keep that in mind; this is part of the Canoeboot installation instructions, +but it can be used for *any* flashing operation on *any* 25xx NOR flash, with +all sorts of firmware; you could also use this to *reverse* a Canoeboot +installation, re-flashing the original vendor firmware if you made a dump of it, +**and we definitely recommend backing that up prior to Canoeboot installation**. + +**Please ensure that your programmer's voltage matches that of the flash IC, +and read this guide carefully to account for proper electrical safety. In +general, these programmers operate at 3.3v, so you'll need a logic level +adapter and e.g. buck converter, if you're dealing with a 1.8V flash IC.** + +**[PLEASE READ THESE INSTRUCTIONS BEFORE INSTALLING](ivy_has_common.md), OR +YOU MAY BRICK YOUR MACHINE!! - Please click the link and follow the instructions +there, before flashing. For posterity, +[here is the link again](ivy_has_common.md).** This guide will teach you how to use various tools for externally reprogramming a 25xx NOR flash via SPI protocol. This is the most common type of flash IC for @@ -42,10 +85,9 @@ from Linux, with flashprog. is called *external* because it's not the *internal* one on your mainboard. Raspberry Pi Pico -================= +----------------- -RP2040/RP2530 both supported ----------------------------- +### RP2040/RP2530 both supported **Pico 2 and other RP2530 dongles also supported, on Canoeboot 20250107 or higher. Releases before this only supported the original Pico, and other @@ -63,8 +105,7 @@ Additionally, all the software running on it is free, down to the full versions (Pico W & Pico WH) need vendor firmware to use the Wi-Fi chip, but that is not needed for following this guide. -Download serprog firmware pre-compiled -------------------------- +### Download serprog firmware pre-compiled Download the pico serprog tarball from Canoeboot releases. For example, the Canoeboot 20250107 one would be @@ -72,8 +113,9 @@ named: `canoeboot-20250107_pico_serprog.tar.xz` - it's available under the `roms/` directory in each release. With these binaries, you can easily get started. -Build serprog firmware from source ----------------------------------- +### Build serprog firmware from source (OPTIONAL) + +**Pre-compiled binaries are also available, in Canoeboot releases.** You can alternatively download the serprog firmware here:\ \ @@ -96,8 +138,7 @@ at `bin/serprog_pico/serprog_pico.uf2` and `bin/serprog_pico/serprog_pico_w.uf2` - images with `pico2` in the file name are for the Pico 2, and they can also be used. -Install the serprog firmware ----------------------------- +### Install the serprog firmware First, connect just the Pico to your computer with a micro-USB cable. Mount it like any other USB flash drive. If it isn't detected, you might need @@ -113,8 +154,7 @@ release tarball. **NOTE: Other RP2040/2530 devices will also work. You just have to match the right pins and use the correct firmware file!** -Logic levels ------------- +### Logic levels A Pico has proper 3.3V logic levels, unlike a ch341a. Which means it won't destroy your board by sending 5V to it. If you have a 1.8V flash chip, @@ -122,8 +162,7 @@ you need to add a logic level converter. **Please ensure that you have matched the voltage of your programmer to the voltage of your chip; both the data lines and power lines to the chip must match.** -Wiring ------- +### Wiring Disconnect the Pico and proceed to wire it to your [flash chip](/docs/install/spi.html#identify-which-flash-type-you-have). @@ -159,11 +198,16 @@ not worth it. The 12Mbps USB port is limiting the actual speed here. Higher speeds might work nicely, on Pico 2. -Do not use CH341A! -================== +Do not buy CH341A! +------------------ + +This section was heavily expanded, on 19 January 2025, because we see many +people online still talking about the CH341a. Therefore, the hatred has been +amplified. Please read this section carefully, to know why we advise against +use of this particular programmer. NOR flashes on Canoeboot systems run on 3.3V DC or 1.8V DC, and this includes -data lines. CH341A has 5V logic levels on data lines, which will damage your +data lines. CH341A can have 5V logic levels on data lines, which can damage your SPI flash and also the southbridge that it's connected to, plus anything else that it's connected to. @@ -223,8 +267,80 @@ resistors) performed, on the black CH341A:\ The green version (not shown above) may come with 3.3v logic already wired, but still needs to have pull-up resistors placed for WP/HOLD. +Disclaimer: A few (not many, but wily) people have criticised this section of the +documentation, due to a misconception about what it really means and also because +this section was previously very poorly written. So to be clear: + +Yes, we are quite well aware that the CH341A can in fact operate at 3.3v, +even unmodified black models; the VCC line is 3.3v, and if when you either +directly wire VCC to WP/HOLD pins yourself, or a pull-up resistor on the +motherboard you're flashing pulls these high at 3.3v, then the logic levels +on the data lines do in fact switch to 3V *during an erase, read or write cycle*. +When no flashing operation is underway, the data lines are outputting at almost +negligable current, so the actual amount of heat generated will be negligable, +and therefore damage is unlikely. However, as stated above and as we will state +again: + +* This is bad electrical design. The CH341A can switch flexibly between 3V + and 5V operation, but most flashes today are 1.8V or 5V anyway, and there are + all kinds of scenarios (such as over-current or surge event) where this 5V + idle logic level could still be applied. Modifying your CH341a to 3.3v + only, as defined in the datasheet (and by this page) is highly recommended. +* The drive level is extremely poor anyway, on CH341a, making ISP-based + flashing ill advisable in many cases, such as where the PCH (Intel platforms) + is partly active and the data lines have lower resistance, because some + boards have 0ohms or very low resistance on these lines. +* No pull-ups on the WP/hold lines, when flashing in the socket; they are high + via 0ohm trace to VCC, whereas you are advised to use a pull-up resistor to + mitigate over-current events. +* Crap LDO on the board, and no ESD/overcurrent protection; the CH341a probably + can't provide much current on the VCC line, especially for ISP-based flashing + where the flash shares a common power rail with many other components. + +CH341a is cheap junk. Get yourself a Raspberry Pi Pico instead; it's about the +same price, but of much higher quality from an electrical design perspective, +supports much higher (12mA!) drive levels on data lines, can control multiple +chip selects at once; it's just better, in every way. And the Raspberry Pi is +completely reprogrammable, so you can use it for something else when you're +done, e.g. UART dongle, or if you're wily enough, [PlayStation 1 Optical Disc +Emulator](https://github.com/paulocode/picostation) - the Pico is simply a +highly versatile tool, much better value for money than the piece of junk +CH341a. + +There is only one instance where the CH341a is *good*, and that is when you're +actually flashing a loose (not soldered) chip, in the ZIF socket on the CH341a +board. It's a DIP-8 socket, and you can also buy WSON-8 and SOIC-8 or SOIC-16 +adapters for it; you can also plug a special adapter board into it that converts +the voltages (VCC and data lines) to 1.8V, for 1.8V flashes (you could also +use that same 1.8V adapter circuit in a breadboard wired to your Pico). On +socket-based flashing, *which is specifically what the CH341a was designed +for*, you don't have to worry about weak drive level because there is nothing +contending with it on the flash IC's data pins. + +The *socket-based* flashing operation is what we recommend this programmer +for, *only if you already have one*. We still recommend fixing the issue with +the WP/HOLD pins as described above; if you're doing this, note that there are +also newer models that have a voltage switch and logic level shifter already +on the board, which can be very useful. *Clip-based* flashing (ISP / in-system +programming) is, specifically, what we advise against using the CH341a for. + +Even if you *are* doing socket-based flashing, we still suggest buying the Pico +instead, though the Pico doesn't come with a ZIF socket; you can wire the Pico +to a breadboard instead, if you want to use a socket for flashing. Then you +will also have a good ISP device, and the overall cost covering both use-case +scenarios is *lower* (cheaper part cost) than buying a CH341a *and* Pico; and +the Pico can also emulate the PlayStation Optical Disc Drive in your +playstation to boot from SD card instead of your dead CD drive, or could even +be a [JTAG adapter](https://hackaday.com/2022/04/11/need-a-jtag-adapter-use-your-pico/) - +again, the Pico is a reprogrammable device! Whereas, the CH341a is a fixed-function +device (and performs poorly). + +Why pay $10 for a CH341a when you can pay $10 for a Raspberry Pi Pico which is +electrically and functionally superior in every way? And the Pico is completely +open source, right down to the boot rom. + Identify which flash type you have -================================== +---------------------------------- In all of them, a dot or marking shows pin 1 (in the case of WSON8, pad 1). @@ -232,8 +348,7 @@ Use the following photos and then look at your board. When you've figured out what type of chip you have, use that knowledge and the rest of this guide, to accomplish your goal, which is to read from and/or write to the boot flash. -SOIC8 ------ +### SOIC8 ![](https://av.canoeboot.org/chip/soic8.jpg) @@ -248,8 +363,7 @@ SOIC8 | 7 | HOLD | | 8 | VCC | -SOIC16 ------- +### SOIC16 ![](https://av.canoeboot.org/chip/soic16.jpg) @@ -266,8 +380,7 @@ SOIC16 SOIC8 and SOIC16 are the most common types, but there are others: -WSON8 ------ +### WSON8 It will be like this on an X200S or X200 Tablet:\ @@ -278,15 +391,13 @@ On T400S, it is in this location near the RAM:\ ![](https://av.canoeboot.org/t400s/soic8.jpg)\ NOTE: in this photo, the chip has been replaced with SOIC8 -DIP8 ----- +### DIP8 ![](https://av.canoeboot.org/dip8/dip8.jpg) Pinout is the same as SOIC8 above. -Supply Voltage --------------- +### Supply Voltage Historically, all boards that Canoeboot supports happened to have SPI NOR chips which work at 3.3V DC. With the recent addition of Chromebooks whose chips are @@ -299,18 +410,16 @@ connect it to the chip through an adapter or logic level converter, never directly. Software configuration -====================== +---------------------- -General/Le potato ------------------ +### General/Le potato The [generic guide](spi_generic.md) is intended to help those looking to use an SBC which is not listed in this guide. The guide will, however, use the libre computer 'Le Potato' as a reference board. If you have that board, you should refer to the [generic guide.](spi_generic.md) -BeagleBone Black (BBB) ----------------------- +### BeagleBone Black (BBB) SSH into your BeagleBone Black. It is assumed that you are running Debian 9 on your BBB. You will run `flashprog` from your BBB. @@ -372,8 +481,7 @@ Note: flashprog can never write if the flash chip isn't found automatically. This means that it's working (the clip isn't connected to any flash chip, so the error is fine). -Caution about BBB ------------------ +### Caution about BBB BeagleBone Black is not recommended, because it's very slow and unstable for SPI flashing, and nowadays much better options exist. We used to mainly @@ -382,8 +490,7 @@ Software on it, but nowadays there are superior options. TODO: document other SPI flashers -Rasberry Pi (RPi) ------------------ +### Rasberry Pi (RPi) SSH into your Raspberry Pi. You will run `flashprog` from your Raspberry Pi. @@ -402,9 +509,9 @@ Under the Interface section, you can enable SPI. The device for communicating via SPI as at `/dev/spidev0.0` -RPi Drive Strength ------------------- -Flashrom on the RPi may not be able to detect the SPI flash chip on some +### RPi Drive Strength + +Flashprog on the RPi may not be able to detect the SPI flash chip on some systems, even if your wiring and clip are set up perfectly. This may be due to the drive strength of the Raspberry Pi GPIOs, which is 8mA by default. Drive strength is essentially the maximum current the pin can output while also @@ -460,8 +567,7 @@ See for more information about the drive strength control on the Pi. -Caution about RPi ------------------ +### Caution about RPi Basically, the Raspbian project, now called Raspberry Pi OS, put in their repo an update that added a new "trusted" repository, which just so happened to be @@ -481,8 +587,7 @@ They then removed it, after a public backlash, via the following commits: * * -Libre firmware on RPi ---------------------- +### Libre firmware on RPi The boot firmware on older Raspberry Pi models can be replaced, with entirely libre firmware. This may be a useful additional step, for some users. See: @@ -493,12 +598,11 @@ Website: -Install flashprog ----------------- +### Install flashprog If you're using a BBB or RPi, you will do this while SSH'd into those. -Flashrom is the software that you will use, for dumping, erasing and rewriting +Flashprog is the software that you will use, for dumping, erasing and rewriting the contents of your NOR flash. In the Canoeboot build system, from the Git repository, you can download and @@ -544,13 +648,12 @@ Example usage: ./elf/flashprog/flashprog -p PROGRAMMER --workaround-mx How to use flashprog -=================== +-------------------- Read past these sections, further down this page, to learn about specific chip types and how to wire them. -Reading -------- +### Reading Before flashing a new ROM image, it is highly advisable that you dump the current chip contents to a file. @@ -596,8 +699,21 @@ they should all be the same length (VCC and GND wires can be longer). This advice is *especially* applicable to the BBB, which is highly unreliable. -Writing -------- +For boards with more than one flash chip you will need to read from both chips +and combine them into a single file. +Most of the time, a two chip setup includes one 8mb 'bottom' chip and one 4mb +'top' chip. +The setup just described applies to the x230, t430, t530, and t440p. +For other boards, make sure you know which chip contains the lower and upper +portions of the rom. +You can combine both flashes together with `cat` for example: + + cat bottom_8mb.rom top_4mb.rom > full_12mb.rom + +Note that you will need this combined rom if you intend to manually extract vendor +files, which is a method not officially supported by Canoeboot's build system. + +### Writing Next, run this command (RPi): @@ -624,14 +740,22 @@ Verifying flash... VERIFIED. If it says "VERIFIED" or says that the chip contents are identical to the requested image, then the chip is properly flashed. +If the board you are writing to has two chips you'll need to split the rom into +two sections. +For example, to split a rom for the 12MB flash setups: + + dd if=canoeboot_12mb.rom bs=1M of=bottom.rom count=8 + dd if=canoeboot_12mb.rom bs=1M of=top.rom skip=8 + +Flash the resulting roms to each of their respective chips according to the above instructions. + Hardware configuration -====================== +---------------------- Refer to the above guidance about software configuration. The following advice will teach you how to wire each type of flash chip. -WARNINGS --------- +### WARNINGS Do not connect the power source until your chip is otherwise properly wired. For instance, do not connect a test clip that has power attached. @@ -656,16 +780,14 @@ DO NOT connect more than 1 DC power source to your flash chip either! Mixing voltages like that can easily cause damage to your equipment, and to your chip/mainboard. -MISO/MOSI/CS/CLK lines ----------------------- +### MISO/MOSI/CS/CLK lines You may want to add 47ohm series resistors on these lines, when flashing the chips. Only do it on those lines (NOT the VCC or GND lines). This provides some protection from over-current. On Intel platforms, the SPI flash is usually connected via such resistors, directly to the Southbridge chipset. -ISP programming and VCC diode ------------------------------ +### ISP programming and VCC diode ISP means in-system programming. It's when you flash a chip that is already mounted to the mainboard of your computer that you wish to install Canoeboot @@ -705,8 +827,7 @@ the flash into a breadboard when flashing. TODO: Make a page on canoeboot.org, showing how to do this on all mainboards supported by canoeboot. -GPIO pins on BeagleBone Black (BBB) ------------------------------------ +### GPIO pins on BeagleBone Black (BBB) Use this image for reference when connecting the pomona to the BBB: (D0 = MISO or connects @@ -715,8 +836,7 @@ to MISO). On that page, look at the *P9 header*. It is what you will use to wire up your chip for flashing. -GPIO pins on Raspberry Pi (RPi) 40 Pin --------------------------------------- +### GPIO pins on Raspberry Pi (RPi) 40 Pin This diagram shows the pinout for most modern Pi's and Pi derivatives. The diagram shows the pins of an RPi on the left and the two SOIC clips @@ -724,8 +844,7 @@ on the left. ![](https://av.canoeboot.org/rpi/wiring.webp) -GPIO pins on Raspberry Pi (RPi) 26 Pin -------------------------------- +### GPIO pins on Raspberry Pi (RPi) 26 Pin Diagram of the 26 GPIO Pins of the Raspberry Pi Model B (for the Model B+ with 40 pins, start counting from the right and leave 14 pins): @@ -734,8 +853,7 @@ B+ with 40 pins, start counting from the right and leave 14 pins): Use this as a reference for the other sections in this page, seen below: -SOIC8/DIP8/WSON8 wiring diagram -------------------------------- +### SOIC8/DIP8/WSON8 wiring diagram Refer to this diagram: @@ -762,8 +880,7 @@ will provide a stable 3.3V voltage, with adequate current levels. On those laptops, this is necessary because the flash shares a common 3.3V DC rail with many other ICs that all draw quite a lot of current. -SOIC16 wiring diagram (Raspberry Pi) ------------------------------------- +### SOIC16 wiring diagram (Raspberry Pi) RPi GPIO header:\ ![](https://av.canoeboot.org/rpi/0009.png) @@ -801,8 +918,7 @@ NOTE: pins 1 and 9 are WP/HOLD pins. If flashing a chip on a breadboard, please use pull-up resistors on those (see notes below), and decoupling capacitor on pin 2 (VCC). -Pull-up resistors and decoupling capacitors -------------------------------------------- +### Pull-up resistors and decoupling capacitors **Do this for chips mounted to a breadboard. Ignore this section if you're flashing a chip that is already soldered to a mainboard.** @@ -850,8 +966,7 @@ WP/HOLD are not pin 3/7 like above, but instead pins 1 and 9, so wire your pull-up resistors on those. VCC on SOIC16 is pin 2, so wire your decoupling capacitors up on that. -SOIC8/WSON8/DIP8/SOIC16 not mounted to a mainboard --------------------------------------------------- +### SOIC8/WSON8/DIP8/SOIC16 not mounted to a mainboard If your system has lower capacity SPI flash, you can upgrade. On *most* systems, SPI flash is memory mapped and the maximum (in practise) that you can use is a @@ -923,8 +1038,7 @@ and good 60/40 or 63/37 leaded solder (don't use lead-free): ![](https://av.canoeboot.org/dip8/adapter.jpg) ![](https://av.canoeboot.org/dip8/sop8todip8.jpg) -SOIC8/SOIC16 soldered to a mainboard ------------------------------------- +### SOIC8/SOIC16 soldered to a mainboard This is an example of *in-system programming* or *ISP* for short. @@ -949,8 +1063,7 @@ Here is an example of a test clip connected for SOIC16:\ And here is an example photo for SOIC8:\ ![](https://av.canoeboot.org/x60/th_bbb_flashing.jpg) -DIP8 soldered to the mainboard ------------------------------- +### DIP8 soldered to the mainboard It is extremely cursed for DIP8 to be soldered directly to the mainboard. It is usually mounted to a socket. @@ -965,8 +1078,7 @@ directly soldered. It is almost always mounted in a socket. Your DIP8 IC has the same pinout as a SOIC8 IC. -Replace WSON8 IC with SOIC8 ---------------------------- +### Replace WSON8 IC with SOIC8 **NOTE: You can alternatively purchase WSON8 probes from a site like Aliexpress. They look similar to SOIC8 clips, and they work similarly.** @@ -1081,7 +1193,7 @@ evaporates quickly and it does not leave a corrosive residue. ------------------------------------------------------------------------------- LICENSING -========= +--------- This page is released under different copyright terms than most other pages on this website. diff --git a/site/docs/install/spi.zh-cn.md b/site/docs/install/spi.zh-cn.md index a47b1f6..ec34b35 100644 --- a/site/docs/install/spi.zh-cn.md +++ b/site/docs/install/spi.zh-cn.md @@ -23,10 +23,9 @@ canoeboot 目前记录了这些 SPI 编程器的使用方法： 你在读的*这个*教程，使用的是*外部*编程器。之所以叫*外部*，是因为用的不是主板上的*内部*编程器。 Raspberry Pi Pico -================= +----------------- -RP2040/RP2530 both supported ----------------------------- +### RP2040/RP2530 both supported **Pico 2 and other RP2530 dongles also supported, on Canoeboot 20250107 or higher. Releases before this only supported the original Pico, and other @@ -44,8 +43,7 @@ Additionally, all the software running on it is free, down to the full versions (Pico W & Pico WH) need vendor firmware to use the Wi-Fi chip, but that is not needed for following this guide. -Download serprog firmware pre-compiled -------------------------- +### Download serprog firmware pre-compiled Download the pico serprog tarball from Canoeboot releases. For example, the Canoeboot 20250107 one would be @@ -53,8 +51,7 @@ named: `canoeboot-20250107_pico_serprog.tar.xz` - it's available under the `roms/` directory in each release. With these binaries, you can easily get started. -Build serprog firmware from source ----------------------------------- +### Build serprog firmware from source You can alternatively download the serprog firmware here:\ \ @@ -77,8 +74,7 @@ at `bin/serprog_pico/serprog_pico.uf2` and `bin/serprog_pico/serprog_pico_w.uf2` - images with `pico2` in the file name are for the Pico 2, and they can also be used. -Install the serprog firmware ----------------------------- +### Install the serprog firmware First, connect just the Pico to your computer with a micro-USB cable. Mount it like any other USB flash drive. If it isn't detected, you might need @@ -94,8 +90,7 @@ release tarball. **NOTE: Other RP2040/2530 devices will also work. You just have to match the right pins and use the correct firmware file!** -Logic levels ------------- +### Logic levels A Pico has proper 3.3V logic levels, unlike a ch341a. Which means it won't destroy your board by sending 5V to it. If you have a 1.8V flash chip, @@ -103,8 +98,7 @@ you need to add a logic level converter. **Please ensure that you have matched the voltage of your programmer to the voltage of your chip; both the data lines and power lines to the chip must match.** -Wiring ------- +### Wiring Disconnect the Pico and proceed to wire it to your [flash chip](/docs/install/spi.html#identify-which-flash-type-you-have). @@ -141,7 +135,7 @@ not worth it. The 12Mbps USB port is limiting the actual speed here. Higher speeds might work nicely, on Pico 2. 不要使用 CH341A！ -================== +---------------- canoeboot 支持的机器，NOR flash 使用的是 3.3V DC 或 1.8V DC，这也包括了数据线路。CH341A 在数据线路上有 5V 逻辑电平，这会损伤 SPI flash 和它连接的南桥，以及它连接的其它任何东西。 @@ -172,26 +166,23 @@ canoeboot 支持的机器，NOR flash 使用的是 3.3V DC 或 1.8V DC，这也 绿色版本（上面未展示）可能已经连接了 3.3v 逻辑电平，但仍然需要为 WP/HOLD 增加上拉电阻。 识别你的 flash 类型 -================================== +------------------- 每一个 flash，都会有一个点或者标记，表明这是第 1 引脚（如 WSON8 的第 1 焊盘）。 参考下面的图片，再看看你的主板。搞清楚你的芯片类型之后，根据你了解的情况及本教程剩下的部分，来实现你的目标，即对你的引导 flash 进行读/写。 -SOIC8 ------ +### SOIC8 ![](https://av.canoeboot.org/chip/soic8.jpg) -SOIC16 ------- +### SOIC16 ![](https://av.canoeboot.org/chip/soic16.jpg) SOIC8 和 SOIC16 是最常见的类型，但也有其他的类型： -WSON8 ------ +### WSON8 X200S 或 X200 Tablet 上是像这样的：\ ![](https://av.canoeboot.org/x200t_flash/X200T-flashchip-location.jpg) @@ -200,28 +191,24 @@ T400S 上，是在 RAM 附近的这个位置：\ ![](https://av.canoeboot.org/t400s/soic8.jpg)\ 注意: 本照片中的芯片换成了 SOIC8 -DIP8 ----- +### DIP8 ![](https://av.canoeboot.org/dip8/dip8.jpg) -电源电压 --------------- +### 电源电压 之前，Canoeboot 支持的所有主板，刚好都有在 3.3V DC 下工作的 SPI NOR 芯片。因为最近添加了额定 1.8V DC 芯片的 Chromebook，所以就不再是这么回事了。 检查主板上芯片的元件型号，再查找一下它的数据表。找出它需要的电源电压并记下来。如果它和你外部刷写硬件的输出电压不匹配，那你只能通过适配器或者逻辑电平转换器，把它连至芯片，而绝不能直接连接。 软件配置 -====================== +-------- -通用/Le potato ------------------ +### 通用/Le potato [通用指南](spi_generic.md)可以帮助你使用本指南未列出的 SBC（单板电脑）。不过，那份指南会使用 libre computer 'Le Potato' 作为参考板。如果你有那块板子，你应该参考 [通用指南](spi_generic.md)。 -BeagleBone Black（BBB） ----------------------- +### BeagleBone Black（BBB） SSH 连接到你的 BeagleBone Black。假定你在 BBB 上用的是 Debian 9。你将在 BBB 上运行 `flashprog`。 @@ -278,15 +265,13 @@ Note: flashprog can never write if the flash chip isn't found automatically. 这表示正常工作了（夹子没连接任何 flash 芯片，所以出错是正常的）。 -BBB 注意事项 ------------------ +### BBB 注意事项 不建议使用 BeagleBone Black，因为拿它来进行 SPI 刷写，速度很慢而且不稳定，并且现在有更好的选择了。我们以前建议使用 BBB，因为它可以完全运行自由软件，但现在有了更佳的选择。 计划：讲解其他 SPI 刷写工具 -Rasberry Pi（RPi） ------------------ +### Rasberry Pi（RPi） SSH 连接到树莓派。你将在树莓派上运行 `flashprog`。 @@ -303,8 +288,7 @@ SSH 连接到树莓派。你将在树莓派上运行 `flashprog`。 用于 SPI 通讯的设备位于 `/dev/spidev0.0`。 -RPi 驱动强度（Drive Strength） ------------------- +### RPi 驱动强度（Drive Strength） RPi 的 flashprog 可能无法检测到一些系统的 SPI flash，即使你已经完美地连好了线并夹住了芯片。这可能是因为树莓派 GPIO 的驱动强度，它默认是 8mA。驱动强度本质上就是，在保持高电平最低电压的同时，引脚最高能输出的电流。对树莓派而言，这个电压是 3.0 V。 @@ -334,8 +318,7 @@ RPi 的 flashprog 可能无法检测到一些系统的 SPI flash，即使你已 见 了解树莓派上的驱动强度控制。 -RPi 注意事项 ------------------ +### RPi 注意事项 基本上，Raspbian 项目，即现在的 Raspberry Pi OS，对其仓库进行了更新，增加了一个新的“受信任”仓库，这刚好是一个微软软件仓库。他们这么做，似乎是为了 VS Code，但问题在于，这可以让微软自由地控制他们喜欢的依赖（根据 apt-get 规则）。每当你更新，你都会对微软的服务器发送请求。不觉得这很奇怪吗？ @@ -348,8 +331,7 @@ RPi 注意事项 * * -RPi 的自由固件 ---------------------- +### RPi 的自由固件 旧款树莓派的引导固件可以替换成完全自由的固件。对有些用户而言，这额外的一步可能很有用。参见： @@ -359,8 +341,7 @@ RPi 的自由固件 -安装 flashprog ----------------- +### 安装 flashprog 如果你在使用 BBB 或者 RPi，你需要在 SSH 进去之后再这么做。 @@ -388,12 +369,11 @@ Flashprog 是用来读出、擦除、重写 NOR flash 内容的软件。 如果你直接下载了 flashprog 源代码，你可以进入目录并直接运行 `make`。在 canoeboot 构建系统中，`config/dependencies/` 处的脚本写明了构建依赖，你可以直接使用 `apt-get` 软件安装。 如何使用 flashprog -=================== +------------------ 请先阅读本页更下方的部分，了解特定的芯片类型及其接线方法。 -读出 -------- +### 读出 刷入新的 ROM 镜像之前，强烈建议你将当前芯片的内容读出到一个文件。 @@ -433,8 +413,7 @@ BBB 的话，这样： 注意，如果你要手动提取 blob，那你就需要这个组合而成的 rom。 -写入 -------- +### 写入 接下来，运行这个命令（RPi）： @@ -459,12 +438,11 @@ Verifying flash... VERIFIED. 如果它显示“VERIFIED”了，或者芯片的内容和请求的镜像一致，那芯片就刷写成功了。 硬件配置 -====================== +-------- 软件配置请参考上面的教程。下面的建议会教你如何为每种 flash 芯片接线。 -警告 --------- +### 警告 在芯片还没有正确接好线时，先不要连接电源。例如，不要连接到接通电源的测试夹。 @@ -476,13 +454,11 @@ Verifying flash... VERIFIED. 也不要给你的 flash 芯片连接超过 1 个 DC 电源！那样混合电压的话，很容易损伤你的设备及芯片/主板。 -MISO/MOSI/CS/CLK 接线 ----------------------- +### MISO/MOSI/CS/CLK 接线 在刷写这些芯片的时候，你可能也想增加 47 欧姆的串联电阻（不是加在 VCC 或 GND 线上）。这可以提供一些过流保护。在 Intel 平台上，SPI flash 直接连接到南桥芯片组时，通常会通过这样的电阻。 -ISP 编程及 VCC 二极管 ------------------------------ +### ISP 编程及 VCC 二极管 ISP 即系统内编程（in-system programming）。它指的是，一块芯片已经装在了你想安装 canoeboot 的电脑的主板上，而你要对这块芯片进行刷写。 @@ -498,22 +474,19 @@ ISP 即系统内编程（in-system programming）。它指的是，一块芯片 计划：在 canoeboot.org 创建一个页面，讲怎么在 canoeboot 支持的所有主板这么做。 -BeagleBone Black（BBB）上的 GPIO 引脚 ------------------------------------ +### BeagleBone Black（BBB）上的 GPIO 引脚 把 pomona 夹子连接到 BBB 时，参考这张图片： （D0 = MISO 或连接到 MISO）。 如果你要用 *P9 排针*来连接芯片刷写的话，请看那个页面的那个部分。 -40 引脚树莓派（RPi）的 GPIO 引脚 --------------------------------------- +### 40 引脚树莓派（RPi）的 GPIO 引脚 下图展示了大多数现代树莓派及其衍生版的引脚分配。图中右边是 RPi 的引脚，左边是两个 SOIC 夹。 ![](https://av.canoeboot.org/rpi/wiring.webp) -26 引脚树莓派（RPi）的 GPIO 引脚 -------------------------------- +### 26 引脚树莓派（RPi）的 GPIO 引脚 树莓派 B 款 26 GPIO 引脚图（对 40 引脚的 B+ 款而言，从右边开始数，剩下 14 个引脚）： @@ -521,8 +494,7 @@ BeagleBone Black（BBB）上的 GPIO 引脚 此处的信息，也请在阅读以下其他部分时参考： -SOIC8/DIP8/WSON8 接线图 -------------------------------- +### SOIC8/DIP8/WSON8 接线图 参考此表： @@ -543,8 +515,7 @@ SOIC8/DIP8/WSON8 接线图 注意：在 X60/T60 thinkpad 上，不要连接第 8 引脚。而是将你的 PSU 接在主板供电口上，但不要启动主板。这会提供稳定的 3.3V 电压及足够的电流。在这些笔记本上，这是必要的，因为 flash 和其他许多 IC 共用一路 3.3V DC 电源，这些 IC 都会分走很多电流。 -SOIC16 接线图（树莓派） ------------------------------------- +### SOIC16 接线图（树莓派） RPi GPIO 排针：\ ![](https://av.canoeboot.org/rpi/0009.webp) @@ -580,8 +551,7 @@ BBB P9 排针：\ 注意：第 1 和第 9 引脚是 WP/HOLD 引脚。在面包板上刷写芯片时，请对它们使用上拉电阻（见上面的注记），并在第 2 引脚（VCC）使用去耦电容。 -上拉电阻和去耦电容 -------------------------------------------- +### 上拉电阻和去耦电容 **如果芯片是装在面包板上的，那请遵循这里的步骤。如果你要刷写的芯片已经焊接在了主板上，那请忽略这一部分。** @@ -602,8 +572,7 @@ SOIC8/WSON8/DIP8：如果芯片在主板上，那第 8 引脚，即 VCC，就已 SOIC16：同上，但在面包板上使用 SOIC16 socket。在 SOIC16 上，WP/HOLD 不同于上面的第 3/7 引脚，而是第 1 和第 9 引脚，所以要把上拉电阻接到那里。SOIC16 上的 VCC 是第 2 引脚，所以要把去耦电容接到那里。 -SOIC8/WSON8/DIP8/SOIC16 未安装在主板上 --------------------------------------------------- +### SOIC8/WSON8/DIP8/SOIC16 未安装在主板上 如果你的机器的 SPI flash 容量较低，那你可以升级。在*大多数*机器上，SPI flash 是经过映射的内存，而（实际上）你最大可以使用 16MiB 的芯片。例如，canoeboot 的 KGPE-D16 和 KCMA-D8 主板默认有 2MiB flash，但你可以对它们轻松升级。另一个例子是 ThinkPad X200S、X200 Tablet 和 T400S，它们都有 WSON8，而最佳的方案就是将它替换为 SOIC8 flash 芯片。 @@ -640,8 +609,7 @@ SOIC8/WSON8/DIP8/SOIC16 未安装在主板上 ![](https://av.canoeboot.org/dip8/adapter.jpg) ![](https://av.canoeboot.org/dip8/sop8todip8.jpg) -SOIC8/SOIC16 焊接在主板上 ------------------------------------- +### SOIC8/SOIC16 焊接在主板上 这是*系统内编程*或 *ISP* 的一个简短例子。 @@ -657,8 +625,7 @@ Pomona 5252 是一个 SOIC16 测试夹。也有其他的可以用，但这个是 SOIC8 例子的照片如下：\ ![](https://av.canoeboot.org/x60/th_bbb_flashing.jpg) -DIP8 焊接在主板上 ------------------------------- +### DIP8 焊接在主板上 把 DIP8 直接焊接在主板上怪异至极。它通常是安装在芯片座上的。 @@ -668,8 +635,7 @@ DIP8 焊接在主板上 DIP8 IC 的引脚分配和 SOIC8 IC 一样。 -使用 SOIC8 替换 WSON8 IC ---------------------------- +### 使用 SOIC8 替换 WSON8 IC **NOTE: You can alternatively purchase WSON8 probes from a site like Aliexpress. They look similar to SOIC8 clips, and they work similarly.** @@ -735,7 +701,7 @@ WSON8 IC：\ ------------------------------------------------------------------------------- 许可证 -========= +------ 本页面发布所使用的版权条款，不同于本网站上大多数其他页面。 diff --git a/site/docs/install/spi_generic.md b/site/docs/install/spi_generic.md index b7c8623..c96fa40 100644 --- a/site/docs/install/spi_generic.md +++ b/site/docs/install/spi_generic.md @@ -6,7 +6,10 @@ x-toc-enable: true NOTE: Canoeboot standardises on [flashprog](https://flashprog.org/wiki/Flashprog) now, as of 3 May 2024, which is a fork of flashrom. -There are a plethora of single board computers with which you can flash canoeboot to a SOIC chip. +Background information +---------------------- + +There are a plethora of single board computers with which you can flash Canoeboot to a SOIC chip. Some users might be daunted by the price of a raspberry pi. This guide is intended to help users looking to use a programmer which is not listed in the [main guide.](spi.md) As an example, this guide will use the [libre computer 'le potato.'](https://libre.computer/products/aml-s905x-cc/) @@ -22,7 +25,7 @@ All of this means that you should try to find a board that is *known* to support It is *not* enough to know that the board itself supports SPI. Selecting an Operating System -============================= +----------------------------- In theory, any linux based operating system will do. In practice, many distros are highly limited when it comes to single-board-computers. @@ -36,7 +39,7 @@ If your SBC supports [Raspbian](https://www.raspberrypi.com/software/) then usin As a bonus, you may refer to the [main guide](spi.md) if the SBC you have supports raspbian, should you get confused with this guide. Connecting to your Programmer -============================= +----------------------------- Many SBC operating systems enable ssh by default. If the OS you chose does not enable ssh on first boot, try checking the distro documentation and looking for terms such as 'headless install.' @@ -54,10 +57,10 @@ SSH to your programmer using the default credentials as specified in your distro The IP address is the one determined in the earlier step. For example: -`ssh root@192.168.0.167` + ssh root@192.168.0.167 Finding GPIO Pins -================= +----------------- If you have determined that a board supports SPI then the only step left is to determine the correct location of the SPI pins. @@ -69,7 +72,7 @@ Match each of the categories in the 'signal' column with those in the 'pin' colu Using this method, you can theoretically use any single board computer with SPI support. Enabling SPI -============ +------------ The modules needed and methods to enable SPI vary based on the SBC you choose. You should always make sure there is a well documented method for enabling SPI on your SBC before purchasing. @@ -80,8 +83,8 @@ sudo ldto enable spicc spicc-spidev sudo ldto merge spicc spicc-spidev ``` -Using Flashprog -============== +Using flashprog +-------------- Some Linux distros will provide flashprog in their default repositories. diff --git a/site/docs/install/t400.md b/site/docs/install/t400.md index 7fc5134..0f8828a 100644 --- a/site/docs/install/t400.md +++ b/site/docs/install/t400.md @@ -1,5 +1,5 @@ --- -title: Flashing the ThinkPad T400 externally +title: Install Canoeboot on Lenovo ThinkPad T400 x-toc-enable: true ... @@ -20,7 +20,7 @@ x-toc-enable: true 3650 on some models) | | **Display** | 1280x800/1440x900 TFT | | **Memory** | 2 or 4GB (Upgradable to 8GB) | -| **Architecture** | x86_64 | +| **Architecture** | x86\_64 | | **EC** | Proprietary | | **Original boot firmware** | LenovoBIOS | | **Intel ME/AMD PSP** | Present. Can be completly disabled. | @@ -51,16 +51,12 @@ P*: Partially works with vendor firmware | **SeaBIOS with GRUB** | Works | -Dell Latitude E6400 -=================== +Open source BIOS/UEFI firmware +------------------------- -**If you haven't bought an T400 yet: the [Dell Latitude -E6400](../install/latitude.md) is much easier to flash; no disassembly required, -it can be flashed entirely in software from Dell BIOS to Canoeboot. It is the -same hardware generation (GM45), with same CPUs, video processor, etc.** - -Introduction -============ +This document will teach you how to install Canoeboot, on your +Lenovo ThinkPad T400 laptop motherboard. Canoeboot replaces proprietary +BIOS/UEFI firmware. It is believed that all or most laptops of the model T400 are compatible. See notes about [CPU @@ -79,12 +75,20 @@ modified descriptor: see [../install/ich9utils.md](../install/ich9utils.md)* Flashing instructions can be found at [../install/\#flashprog](../install/#flashprog) +Dell Latitude E6400 +------------------- + +**If you haven't bought an T400 yet: the [Dell Latitude +E6400](../install/latitude.md) is much easier to flash; no disassembly required, +it can be flashed entirely in software from Dell BIOS to Canoeboot. It is the +same hardware generation (GM45), with same CPUs, video processor, etc.** + EC update {#ecupdate} -========= +--------------------- It is recommended that you update to the latest EC firmware version. The [EC firmware](../../faq.md#ec-embedded-controller-firmware) is separate from -libreboot, so we don't actually provide that, but if you still have +Canoeboot, so we don't actually provide that, but if you still have Lenovo BIOS then you can just run the Lenovo BIOS update utility, which will update both the BIOS and EC version. See: @@ -92,7 +96,7 @@ will update both the BIOS and EC version. See: - NOTE: this can only be done when you are using Lenovo BIOS. How to -update the EC firmware while running libreboot is unknown. libreboot +update the EC firmware while running Canoeboot is unknown. Canoeboot only replaces the BIOS firmware, not EC. Updated EC firmware has several advantages e.g. bettery battery @@ -102,7 +106,7 @@ The T400 is almost identical to the X200, code-wise. See [x200.md](x200.md). Installation notes -============ +------------------ [External flashing](spi.md) required, if Lenovo BIOS is running. @@ -118,15 +122,14 @@ the screws on page 114 (with title "1130 Keyboard bezel") are swapped and if you follow the HMM you will punch a hole through the bezel in the upper right corner. -Serial port {#serial_port} ------------ +### Serial port {#serial_port} EHCI debug might not be needed. It has been reported that the docking station for this laptop has a serial port, so it might be possible to use that instead. A note about CPUs -================= +----------------- [ThinkWiki](http://www.thinkwiki.org/wiki/Category:T400) has a list of CPUs for this system. The Core 2 Duo P8400, P8600 and P8700 are believed @@ -134,8 +137,7 @@ to work with Canoeboot. T9600, T9500, T9550 and T9900 are all compatible, as reported by users. -Quad-core CPUs --------------- +### Quad-core CPUs Very likely to be compatible, but requires hardware modification. Based on info from German forum post about installing Core Quad CPU on T500 found in coreboot mailing list. Currently work in progress and no guide available. @@ -143,9 +145,8 @@ Based on info from German forum post about installing Core Quad CPU on T500 foun - [Coreboot mailing list post](https://mail.coreboot.org/pipermail/coreboot/2016-November/082463.html) - [German forum post about install Core Quad on T500](https://thinkpad-forum.de/threads/199129) - A note about GPUs -================= +----------------- Some models have an Intel GPU, while others have both an ATI and an Intel GPU; this is referred to as "switchable graphics". In the *BIOS @@ -158,29 +159,28 @@ Intel GPU is used and the ATI GPU is disabled, so native graphics initialization works all the same. CPU paste required -================== +------------------ See [\#paste](#paste). Flash chip size {#flashchips} -=============== +--------------------------- Use this to find out: flashprog -p internal MAC address {#macaddress} -=========== +------------------------ Refer to [mac\_address.md](mac_address.md). How to flash externally -========================= +----------------------- Refer to [spi.md](spi.md) as a guide for external re-flashing. -The procedure -------------- +### The procedure Remove *all* screws, placing them in the order that you removed them:\ ![](https://av.canoeboot.org/t400/0001.jpg) ![](https://av.canoeboot.org/t400/0002.jpg) @@ -278,7 +278,7 @@ Refer to the external flashing instructions [here](spi.md), and when you're done, re-assemble your laptop. Thermal paste (IMPORTANT) -========================= +------------------------- Because part of this procedure involved removing the heatsink, you will need to apply new paste. Arctic MX-4 is ok. You will also need isopropyl @@ -295,7 +295,7 @@ show how to properly apply the thermal paste. Other guides online detail the proper application procedure. Memory -====== +------ In DDR3 machines with Cantiga (GM45/GS45/PM45), northbridge requires sticks that will work as PC3-8500 (faster PC3/PC3L sticks can work as PC3-8500). diff --git a/site/docs/install/t500.md b/site/docs/install/t500.md index 6a582ff..176d873 100644 --- a/site/docs/install/t500.md +++ b/site/docs/install/t500.md @@ -1,5 +1,5 @@ --- -title: ThinkPad T500 external flashing +title: Install Canoeboot on Lenovo ThinkPad T500 and/or W500 x-toc-enable: true ... @@ -20,7 +20,7 @@ x-toc-enable: true 3650 on some models) | | **Display** | 1280x800/1680x1050/1920x1200 TFT | | **Memory** | 2 or 4GB (Upgradable to 8GB) | -| **Architecture** | x86_64 | +| **Architecture** | x86\_64 | | **EC** | Proprietary | | **Original boot firmware** | LenovoBIOS | | **Intel ME/AMD PSP** | Present. Can be completly disabled. | @@ -51,16 +51,12 @@ P*: Partially works with vendor firmware | **SeaBIOS with GRUB** | Works | -Dell Latitude E6400 -=================== +Open source BIOS/UEFI firmware +------------------------- -**If you haven't bought an T500 yet: the [Dell Latitude -E6400](../install/latitude.md) is much easier to flash; no disassembly required, -it can be flashed entirely in software from Dell BIOS to Canoeboot. It is the -same hardware generation (GM45), with same CPUs, video processor, etc.** - -Introduction -============ +This document will teach you how to install Canoeboot, on your +Lenovo ThinkPad T500 or ThinkPad W500 laptop motherboard. Canoeboot replaces +proprietary BIOS/UEFI firmware. It is believed that all or most T500 laptops are compatible. See notes about [CPU @@ -81,8 +77,16 @@ modified descriptor: see [../install/ich9utils.md](../install/ich9utils.md)* Flashing instructions can be found at [../install/\#flashprog](../install/#flashprog) +Dell Latitude E6400 +------------------- + +**If you haven't bought an T500 yet: the [Dell Latitude +E6400](../install/latitude.md) is much easier to flash; no disassembly required, +it can be flashed entirely in software from Dell BIOS to Canoeboot. It is the +same hardware generation (GM45), with same CPUs, video processor, etc.** + EC update {#ecupdate} -========= +------------------- It is recommended that you update to the latest EC firmware version. The [EC firmware](../../faq.md#ec-embedded-controller-firmware) is separate from @@ -104,7 +108,7 @@ The T500 is almost identical to the X200, code-wise. See [x200.md](x200.md). Installation notes -================== +------------------ [External flashing](spi.md) required, if Lenovo BIOS is running. @@ -114,15 +118,14 @@ followed (adapted) if you brick your T500, to know how to recover. W500 is also mostly compatible with this guide. -Serial port {#serial_port} ------------ +### Serial port {#serial_port} EHCI debug might not be needed. It has been reported that the docking station for this laptop has a serial port, so it might be possible to use that instead. A note about CPUs -================= +----------------- [ThinkWiki](http://www.thinkwiki.org/wiki/Category:T500) has a list of CPUs for this system. The Core 2 Duo P8400, P8600 and P8700 are believed @@ -132,8 +135,8 @@ confirmed working. T9550 and T9900 was tested by a user, and is compatible as reported in the IRC channel. T9500 and T9400 may also work, but YMMV. -Quad-core CPUs --------------- +### Quad-core CPUs + Very likely to be compatible, but requires hardware modification. Based on info from German forum post about installing Core Quad CPU on T500 found in coreboot mailing list. Currently work in progress and no guide available. @@ -149,7 +152,7 @@ everything nicely: A note about GPUs -================= +----------------- Some models have an Intel GPU, while others have both an ATI and an Intel GPU; this is referred to as "switchable graphics". In the *BIOS @@ -162,29 +165,28 @@ Intel GPU is used and the ATI GPU is disabled, so native graphics initialization works all the same. CPU paste required -================== +------------------ See [\#paste](#paste). Flash chip size {#flashchips} -=============== +----------------------------- Use this to find out: flashprog -p internal MAC address {#macaddress} -=========== +------------------------ Refer to [mac\_address.md](mac_address.md). Clip wiring -=========== +----------- Refer to [spi.md](spi.md) as a guide for external re-flashing. -The procedure -------------- +### The procedure Remove all screws:\ ![](https://av.canoeboot.org/t500/0000.jpg)\ @@ -287,7 +289,7 @@ Connect your programmer, then connect GND and 3.3V\ Now flash Canoeboot. Thermal paste (IMPORTANT) -========================= +------------------------- Because part of this procedure involved removing the heatsink, you will need to apply new paste. Arctic MX-4 is ok. You will also need isopropyl @@ -304,7 +306,7 @@ show how to properly apply the thermal paste. Other guides online detail the proper application procedure. Wifi -==== +---- It is recommended that you install a new wifi chipset. This can only be done after installing Canoeboot, because the original firmware has a @@ -316,7 +318,7 @@ the Intel chip that this T500 came with:\ ![](https://av.canoeboot.org/t400/0012.jpg) ![](https://av.canoeboot.org/t400/ar5b95.jpg) WWAN -==== +---- If you have a WWAN/3G card and/or sim card reader, remove them permanently. The WWAN-3G card has DMA, and proprietary firmware inside; @@ -326,7 +328,7 @@ also track your movements. Not to be confused with wifi (wifi is fine). Memory -====== +------ In DDR3 machines with Cantiga (GM45/GS45/PM45), northbridge requires sticks that will work as PC3-8500 (faster PC3/PC3L sticks can work as PC3-8500). diff --git a/site/docs/install/t60_unbrick.md b/site/docs/install/t60_unbrick.md index c85526c..a873a89 100644 --- a/site/docs/install/t60_unbrick.md +++ b/site/docs/install/t60_unbrick.md @@ -1,10 +1,15 @@ --- -title: ThinkPad T60 Recovery guide +title: Install Canoeboot on Lenovo ThinkPad T60 x-toc-enable: true ... -NOTE: Canoeboot standardises on [flashprog](https://flashprog.org/wiki/Flashprog) -now, as of 3 May 2024, which is a fork of flashrom. +Open source BIOS/UEFI firmware +------------------------------ + +This document will teach you how to install Canoeboot, on your +Lenovo Thinkpad T60 motherboard. Canoeboot replaces proprietary +BIOS/UEFI firmware. *This* version of the guide shows you how to +flash using external hardware, which can be useful for un-bricking. "Unbricking" means flashing a known-good (working) ROM. The problem: you can't boot the system, making this difficult. In this situation, diff --git a/site/docs/install/x200.md b/site/docs/install/x200.md index 8b1aeac..193778b 100644 --- a/site/docs/install/x200.md +++ b/site/docs/install/x200.md @@ -1,5 +1,5 @@ --- -title: First-time ThinkPad X200 flashing +title: Install Canoeboot on Lenovo ThinkPad X200 / X200s / X200 Tablet x-toc-enable: true ... @@ -18,7 +18,7 @@ x-toc-enable: true | **Graphics** | Intel GMA X4500MHD | | **Display** | 1280x800/1440x900 TFT | | **Memory** | 1,2,3 or 4GB (Upgradable to 8GB, unofficially) | -| **Architecture** | x86_64 | +| **Architecture** | x86\_64 | | **EC** | Proprietary | | **Original boot firmware** | LenovoBIOS | | **Intel ME/AMD PSP** | Present. Can be completly disabled. | @@ -47,16 +47,12 @@ P+: Partially works; | **SeaBIOS with GRUB** | Works | -Dell Latitude E6400 -=================== +Open source BIOS/UEFI firmware +------------------------- -**If you haven't bought an X200 yet: the [Dell Latitude -E6400](../install/latitude.md) is much easier to flash; no disassembly required, -it can be flashed entirely in software from Dell BIOS to Canoeboot. It is the -same hardware generation (GM45), with same CPUs, video processor, etc.** - -Introduction -============ +This document will teach you how to install Canoeboot, on your +Lenovo ThinkPad X200, X200s or X200 Tablet laptop motherboard. Canoeboot +replaces proprietary BIOS/UEFI firmware. It is believed that all X200 laptops are compatible. X200S and X200 Tablet will also work, [depending on the configuration](#x200s). @@ -80,8 +76,16 @@ Flashing instructions can be found at NOTE: Canoeboot standardises on [flashprog](https://flashprog.org/wiki/Flashprog) now, as of 3 May 2024, which is a fork of flashrom. +Dell Latitude E6400 +------------------- + +**If you haven't bought an X200 yet: the [Dell Latitude +E6400](../install/latitude.md) is much easier to flash; no disassembly required, +it can be flashed entirely in software from Dell BIOS to Canoeboot. It is the +same hardware generation (GM45), with same CPUs, video processor, etc.** + EC update {#ecupdate} -========= +--------------------- It is recommended that you update to the latest EC firmware version. The [EC firmware](../../faq.md#ec-embedded-controller-firmware) is separate from @@ -102,7 +106,7 @@ Updated EC firmware has several advantages e.g. better battery handling. Battery Recall {#batteryrecall} -============== +------------------------------ [On 21 April 2015, Lenovo expanded a recall on Lenovo batteries found in some ThinkPad models, which includes the X200 and X200S.](https://pcsupport.lenovo.com/cr/en/solutions/hf004122) To find out if you are affected, use [this Lenovo tool.](https://lenovobattery2014.orderz.com/) @@ -161,14 +165,13 @@ Sources: Mod](http://forum.thinkpads.com/viewtopic.php?p=660662#p660662) - [ThinkWiki.de - X200 Displayumbau](http://thinkwiki.de/X200_Displayumbau) -### X200S +#### X200S explains that the X200S screens/assemblies are thinner. You need to replace the whole lid with one from a normal X200/X201. -How to tell if it has an LED or CCFL? {#led_howtotell} -------------------------------------- +### How to tell if it has an LED or CCFL? {#led_howtotell} Some X200s have a CCFL backlight and some have an LED backlight, in their LCD panel. This also means that the inverters will vary, so you must be careful if @@ -182,11 +185,11 @@ a lamp which contains mercury; dispose according to local, state or federal laws"* (one with an LED backlit panel will say something different). Installation notes -================== +------------------ [External flashing](spi.md) required, if running Lenovo BIOS. -This guide is for those who want libreboot on their ThinkPad X200 while +This guide is for those who want Canoeboot on their ThinkPad X200 while they still have the original Lenovo BIOS present. This guide can also be followed (adapted) if you brick your X200, to know how to recover. @@ -196,22 +199,19 @@ underneath the palm rest. You will then connect an external SPI programmer, to re-flash the chip externally while it is powered off with the battery removed. NOTE: This guide only applies to the regular X200. For X200S and X200 Tablet -flashing, please read other guides available on libreboot.org. +flashing, please read other guides available on canoeboot.org. -Flash chip size -=============== +### Flash chip size Run this command on x200 to find out flash chip model and its size: flashprog -p internal -MAC address -=========== +### MAC address Refer to [mac\_address.md](mac_address.md). -The procedure -------------- +### The procedure This section is for the X200. This does not apply to the X200S or X200 Tablet (for those systems, you have to remove the motherboard @@ -246,7 +246,7 @@ When you're done, put the system back together. If it doesn't boot, try other RAM modules because raminit is very unreliable on this platform (in coreboot). Memory -====== +------ In DDR3 machines with Cantiga (GM45/GS45/PM45), northbridge requires sticks that will work as PC3-8500 (faster PC3/PC3L sticks can work as PC3-8500). @@ -272,8 +272,10 @@ You should see something like this: Now [install Linux](../linux/). -X200S and X200 Tablet users: GPIO33 trick will not work. --------------------------------------------------------- +Errata +------ + +### X200S and X200 Tablet users: GPIO33 trick will not work. sgsit found out about a pin called GPIO33, which can be grounded to disable the flashing protections by the descriptor and stop the ME from diff --git a/site/docs/install/x200.uk.md b/site/docs/install/x200.uk.md index 3cc87f9..578a75a 100644 --- a/site/docs/install/x200.uk.md +++ b/site/docs/install/x200.uk.md @@ -18,7 +18,7 @@ x-toc-enable: true | **Графіка** | Intel GMA X4500MHD | | **Дісплей** | 1280x800/1440x900 TFT | | **Пам'ять** | 1,2,3 or 4GB (оновлюється до 8GB, неофіційно) | -| **Архітектура** | x86_64 | +| **Архітектура** | x86\_64 | | **EC** | Пропрієтарний | | **Оригінальна прошивка** | LenovoBIOS | | **Intel ME/AMD PSP** | Наявний. Можна повністю вимкнути. | @@ -48,7 +48,7 @@ P+: Частково працює; Вступ -============ +----- Вважається що всі ноутбуки X200 сумісні. X200S та X200 Tablet також працюватимуть, [залежно від конфігурації](#x200s). @@ -73,7 +73,7 @@ NOTE: Canoeboot standardises on [flashprog](https://flashprog.org/wiki/Flashprog now, as of 3 May 2024, which is a fork of flashrom. Оновлення EC {#ecupdate} -========= +------------------------ Рекомендується оновити мікропрограму EC до останньої версії. [Прошивка EC](../../faq.md#ec-embedded-controller-firmware) є окремою від @@ -94,7 +94,7 @@ Lenovo BIOS, ви можете просто запустити утиліту о з акумулятором. Відкликання батареї {#batteryrecall} -============== +------------------------------------ [21 квітня 2015 року, Lenovo розширила відкликання акумуляторів Lenovo, які були встановлені в деяких моделях Thinkpad, зокрема X200 та X200S.](https://pcsupport.lenovo.com/cr/en/solutions/hf004122) Щоб дізнатися, чи вас це стосується, використовуйте [цей інструмент Lenovo.](https://lenovobattery2014.orderz.com/) @@ -103,8 +103,7 @@ Lenovo радить власникам відкликаних моделей "в Після перевірки батареї, Lenovo безкоштовно замінить відкликані батареї. Інструкції щодо заміни батареї для X200/X200s [можна знайти на цій сторінці.](https://pcsupport.lenovo.com/cr/en/parts/pd003507/) -Список сумісності LCD {#lcd_supported_list} ----------------------- +### Список сумісності LCD {#lcd_supported_list} Список РК-панелей (там перераховані панелі X200): @@ -153,14 +152,13 @@ Lenovo радить власникам відкликаних моделей "в Mod](http://forum.thinkpads.com/viewtopic.php?p=660662#p660662) - [ThinkWiki.de - X200 Displayumbau](http://thinkwiki.de/X200_Displayumbau) -### X200S +#### X200S пояснює, що екрани/блоки X200S тонші. Вам потрібно замінити всю кришку на одну від звичайного X200/X201. -Як визначити, чи у нього LED, чи CCFL? {#led_howtotell} -------------------------------------- +### Як визначити, чи у нього LED, чи CCFL? {#led_howtotell} Деякі X200 мають підсвічування CCFL, а деякі - світлодіодне підсвічування на РК-панелі. Це також означає, що інвертори відрізнятимуться, тому ви повинні бути обережними, @@ -174,7 +172,7 @@ CCFL містять меркурій. На X200 з CCFL підсвіткою (я законів"* (на тому, що має світлодіодне підсвічування, буде написано щось інше). Installation notes -================== +------------------ [External flashing](spi.md) required, if running Lenovo BIOS. @@ -191,19 +189,18 @@ Installation notes будь-ласка прочитайте інші посібники, доступні на libreboot.org. Розмір флеш-чіпа -=============== +---------------- Виконайте цю команду на x200, щоб дізнатися модель флеш-чіпа та його розмір: flashprog -p internal MAC адреса -=========== +---------- Зверніться до [mac\_address.md](mac_address.md). -Процедура -------------- +### Процедура Цей розділ стосується X200. Цей не стосується X200S або X200 Tablet (для цих систем потрібно повністю видалити материнську плату, @@ -238,7 +235,7 @@ Tablet (для цих систем потрібно повністю видал модулі оперативної пам'яті, тому що raminit дуже ненадійний на цій платформі (в coreboot). Пам'ять -====== +------- У машинах DDR3 з Cantiga (GM45/GS45/PM45), північний міст потребує стіків, які працюватимуть як PC3-8500 (швидші стіки PC3/PC3L можуть працювати як PC3-8500). @@ -255,8 +252,7 @@ Tablet (для цих систем потрібно повністю видал ![](https://av.libreboot.org/x200/disassembly/0018.jpg) -Завантажуйтесь! --------- +### Завантажуйтесь! Ви маєте побачити щось подібне цьому: @@ -264,8 +260,7 @@ Tablet (для цих систем потрібно повністю видал Тепер [встановлюйте Linux](../linux/). -Користувачі X200S та X200 Tablet: трюк GPIO33 не спрацює. --------------------------------------------------------- +### Користувачі X200S та X200 Tablet: трюк GPIO33 не спрацює. sgsit дізнався про контакт під назвою GPIO33, який можна заземлити, щоб вимкнути захист прошивки за допомогою дескриптора та зупинити ME від diff --git a/site/docs/install/x60_unbrick.md b/site/docs/install/x60_unbrick.md index 235f4fc..94722ba 100644 --- a/site/docs/install/x60_unbrick.md +++ b/site/docs/install/x60_unbrick.md @@ -1,8 +1,15 @@ --- -title: ThinkPad X60 Recovery guide +title: Install Canoeboot on Lenovo ThinkPad X60 x-toc-enable: true ... +Open source BIOS/UEFI firmware +------------------------------ + +This document will teach you how to install Canoeboot, on your +Lenovo ThinkPad X60 laptop motherboard. Canoeboot replaces proprietary +BIOS/UEFI firmware. + "Unbricking" means flashing a known-good (working) ROM. The problem: you can't boot the system, making this difficult. In this situation, external hardware is needed which can flash the SPI chip (where Canoeboot diff --git a/site/docs/install/x60tablet_unbrick.md b/site/docs/install/x60tablet_unbrick.md index d72c1e4..2bc68e5 100644 --- a/site/docs/install/x60tablet_unbrick.md +++ b/site/docs/install/x60tablet_unbrick.md @@ -1,8 +1,15 @@ --- -title: ThinkPad X60 Tablet Recovery guide +title: Install Canoeboot on Lenovo ThinkPad X60 Tablet x-toc-enable: true ... +Open source BIOS/UEFI firmware +------------------------------ + +This document will teach you how to install Canoeboot, on your +Lenovo Thinkpad X60 Tablet laptop motherboard. Canoeboot replaces proprietary +BIOS/UEFI firmware. + "Unbricking" means flashing a known-good (working) ROM. The problem: you can't boot the system, making this difficult. In this situation, external hardware is needed which can flash the SPI chip (where Canoeboot diff --git a/site/docs/linux/grub_boot_installer.md b/site/docs/linux/grub_boot_installer.md index ef2e654..f09f409 100644 --- a/site/docs/linux/grub_boot_installer.md +++ b/site/docs/linux/grub_boot_installer.md @@ -1,9 +1,10 @@ --- -title: Installing Linux +title: Boot Linux distro installers on Canoeboot x-toc-enable: true ... -# Introduction +GRUB payload assumed +-------------------- This guide assumes that you are using the GRUB bootloader directly. If you're using SeaBIOS, it's quite intuitive and works similarly to other BIOS @@ -17,7 +18,9 @@ Linux distributions, by default). These instructions are intended to be generic, applicable to just about any Linux distribution. -## Prepare the USB Drive in Linux +Prepare the USB Drive in Linux +------------------------------ + If you downloaded your ISO while on an existing Linux system, here is how to create the bootable Linux USB drive: @@ -40,19 +43,25 @@ folder, this is the command we would run: That's it! You should now be able to boot the installer from your USB drive (the instructions for doing so will be given later). -## Prepare the USB drive in NetBSD +Prepare the USB drive in NetBSD +------------------------------- + [This page](https://wiki.netbsd.org/tutorials/how_to_install_netbsd_from_an_usb_memory_stick/) on the NetBSD website shows how to create a NetBSD bootable USB drive, from within NetBSD itself. You should the `dd` method documented there. This will work with any Linux ISO image. -## Prepare the USB drive in FreeBSD +Prepare the USB drive in FreeBSD +-------------------------------- + [This page](https://www.freebsd.org/doc/handbook/bsdinstall-pre.html) on the FreeBSD website shows how to create a bootable USB drive for installing FreeBSD. Use the `dd` method documented. This will work with any Linux ISO image. -## Prepare the USB drive in LibertyBSD or OpenBSD +Prepare the USB drive in OpenBSD +-------------------------------- + If you downloaded your ISO on a LibertyBSD or OpenBSD system, here is how to create the bootable Linux USB drive: @@ -78,12 +87,14 @@ the OpenBSD installer to it with `dd`. Here's an example: That's it! You should now be able to boot the installer from your USB drive (the instructions for doing so will be given later). -## GRUB2 config on external media +GRUB2 config on external media +------------------------------- If the distro installer image has a `grub.cfg` file inside, this menuentry is scripted to find it. This works well for many distros. -## Debian or Devuan net install +Debian or Devuan net installation +--------------------------------- Download the Debian or Devuan net installer. You can download the Debian ISO from [the Debian homepage](https://www.debian.org/), or the Devuan ISO from @@ -96,12 +107,16 @@ You can select the option, in the Canoeboot GRUB menu, to load GRUB config from external media, and that should work just fine. Alternatively, pick one of the ISOLINUX-related menu options. -## Booting ISOLINUX Images (Automatic Method) +Booting ISOLINUX Images (Automatic Method) +------------------------------------------ + Boot it in GRUB using the `Parse ISOLINUX config (USB)` option. A new menu should appear in GRUB, showing the boot options for that distro; this is a GRUB menu, converted from the usual ISOLINUX menu provided by that distro. -## Booting ISOLINUX Images (Manual Method) +Booting ISOLINUX Images (Manual Method) +--------------------------------------- + These are generic instructions. They may or may not be correct for your distribution. You must adapt them appropriately, for whatever Linux distribution it is that you are trying to install. @@ -151,7 +166,11 @@ to see a list of USB devices/partitions. Of course, this will vary from distro to distro. If you did all of that correctly, then it should now be booting your USB drive in the way that you specified. -## Troubleshooting +Troubleshooting +--------------- + +### Display modes + Most of these issues occur when using Canoeboot with coreboot's `text-mode` with libgfxinit for video initialization. This mode is useful for text mode payloads, like `MemTest86+`, which expect `text-mode`, but for Linux @@ -161,6 +180,7 @@ do Kernel Mode Setting, so they are able to initialize a frame buffer in bare metal regardless of whatever coreboot is doing). ### debian-installer Graphical Corruption in Text-Mode (Debian and Devuan) + When using the ROM images that use Coreboot's `text mode`, instead of the coreboot framebuffer, while using libgfxinit, booting the Debian or Devuan net installer results in graphical corruption, because it is trying to switch to a diff --git a/site/docs/linux/grub_cbfs.md b/site/docs/linux/grub_cbfs.md index e7087a5..5dea4f6 100644 --- a/site/docs/linux/grub_cbfs.md +++ b/site/docs/linux/grub_cbfs.md @@ -3,12 +3,21 @@ title: Modifying grub.cfg in CBFS x-toc-enable: true ... +Configure boot order and so on +------------------------------ + Read [Canoeboot flashing guides](../install/) before continuing, and make sure to back up the current flash contents before you consider following this guide. Before you follow this guide, it is advisable that you have the ability to [flash externally](../install/spi.md), just in case something goes wrong. +Canoeboot's *GRUB* payload is much more flexible than most other types of boot +payload, but can sometimes require hands-on configuration depending on what you +want to do. + +### Why modify the configuration? + Canoeboot's own GRUB configuration automatically scans for one provided by your distro, and this automation will usually work. Sometimes, you might wish to override it with your own custom menuentry or additional logic in the GRUB @@ -16,11 +25,12 @@ config. You can configure GRUB however you like, and this topic is vast so what to actually *put in the config* will not be covered here. This guide will simply teach you how to modify the config, but not what to put, -whereas the [GRUB hardening](grub_hardening.md) guide specifically -says what to modify; cross reference that page and this page. +whereas the [GRUB hardening](../linux/grub_hardening.md) guide specifically +says what to modify; cross reference that page and this page, if you want to +follow the GRUB hardening guide. Otherwise, this page contains generic guidance. **Disable security before continuing** -================================ +-------------------------------------- **Before internal flashing, you must first disable `/dev/mem` protections. Make sure to re-enable them after you're finished.** @@ -32,12 +42,11 @@ flashing, from an existing installation. If you're externally flashing the machine, you can ignore this advice. Build dependencies -================== +------------------ **Please first [install build dependencies](../build/).** -Coreboot utilities ------------------- +### Coreboot utilities You need `cbfstool` from coreboot. For whatever board you have, check which coreboot tree it uses in Canoeboot's build system, cbmk. For example, let's @@ -59,8 +68,7 @@ This will result in the following binary: `elf/cbfstool/default/cbfstool` We won't assume the path to cbfstool, in the remainder of this guide, so adapt accordingly. -GRUB utilities --------------- +### GRUB utilities Again, let's assume the coreboot board is `x200_8mb`. Check the file `config/coreboot/x200_8mb/target.cfg` for `grubtree` - if it's not set, @@ -72,8 +80,7 @@ This will compile GRUB for the given tree. If you need to use any of the GRUB utilities, this command will build them and in this example, they will be available under `src/grub/default/`. -Flashprog ---------- +### Flashprog Compile flashprog like so: @@ -82,7 +89,7 @@ Compile flashprog like so: A binary will appear at `elf/flashprog/flashprog`. Default GRUB config -=================== +------------------- The coreboot image has its own filesystem, CBFS, and within CBFS is the GRUB binary, and within the GRUB binary is another filesystem called memdisk, where @@ -91,10 +98,9 @@ the default GRUB configuration is located. You can override it by inserting your own GRUB config within CBFS. Acquiring a GRUB config -======================= +----------------------- -Dump the boot flash -------------------- +### Dump the boot flash This is only useful if you already inserted a GRUB config in CBFS. Otherwise, you can grab it from Canoeboot's build system, cbmk. @@ -105,8 +111,7 @@ look at the [main flashing guide](../install/). Those guides show how to dump the flash contents, which you are advised to do. -Default GRUB config location ----------------------------- +### Default GRUB config location We'll assume that your GRUB tree is `default`, so the file `config/grub/default/config/payload` is your GRUB config; this will be the @@ -116,7 +121,7 @@ Modify *that* file, or the one you extracted if you already inserted a custom one before, and you will re-insert it when you're done. Insert grubtest.cfg -=================== +------------------- Before reading the next section, please note: if you only have the fallback GRUB config in memdisk, and no configs in CBFS, you can test the modified @@ -128,7 +133,7 @@ Canoeboot will not automatically load it, but it will be available from the default GRUB menu. This can be useful for test purposes, hence the name. Insert new grub.cfg -=================== +------------------- If you already have a `grub.cfg` in cbfstool, you can extract and modify that one, e.g.: @@ -155,7 +160,7 @@ test config from the default menu, before deciding whether to make it the main config, as `grub.cfg`, overriding the one in GRUB memdisk. Flash the modified ROM image -============================ +---------------------------- Check the [Canoeboot flashing guide](../install/) which says how to flash the new image. diff --git a/site/docs/linux/grub_hardening.md b/site/docs/linux/grub_hardening.md index d4fbd24..c280ae6 100644 --- a/site/docs/linux/grub_hardening.md +++ b/site/docs/linux/grub_hardening.md @@ -1,18 +1,47 @@ --- -title: Hardening GRUB +title: Hardening GRUB (i.e. Secure canoeBoot) x-toc-enable: true ... +What is Secure canoeBoot? +------------------------- + +Canoeboot provides open source BIOS/UEFI firmware, replacing proprietary +BIOS/UEFI firmware, and that precisely is Canoeboot primary mission; Canoeboot +is a [Free Software](https://writefreesoftware.org/learn) project, *first*. +Our *next* priority is to provide you with *highly secure* boot firmware, free +from backdoors and with well-audited code. *This* document does just that, by +telling you how to *harden* your Canoeboot installation against various physical +access attacks. + +### Not UEFI SecureBoot! + +UEFI SecureBoot was invented by Microsoft for booting Microsoft Windows. We +don't use UEFI SecureBoot in the Canoeboot project, because UEFI SecureBoot +is *completely inferior* to Canoeboot's security model. We call our own +security model *Secure canoeBoot* and we use neither BIOS nor UEFI; we use GRUB! + +*Strong encryption* is the name of the game. You will use the *GRUB payload*. GRUB supports various security mechanisms that are not enabled by default. This page will tell you how to enable them, for the purpose of boot security, both detecting and attempting to prevent certain types of attack. +Please also expect to brick your machine at least once, because many of these +changes are highly invasive and may even require you to *modify source code*. **Make sure you have an [external SPI programmer](../install/spi.md), for recovery purposes, just in case you brick your machine. The modifications -documented here are highly invasive and it would be easy to make mistakes.** +documented here are highly invasive. An external SPI programmer can be used +to restore the previous working state, should a brick occur.** + +Canoeboot's design philosophy is that the most non-technical user must be +catered to first, which means that certain security hardening steps are skipped +by default. With the steps documented here, you will be able to thwart many +types of physical attack on your machine. Many of the types of configurations +documented here are *unique*, and available only in Canoeboot! (or otherwise +only *practical* in Canoeboot) Full disk encryption -==================== +-------------------- [Encrypted /boot with LUKS2 on argon2 key derivation is now possible](../../news/argon2.md) - the work is based on that done by @@ -34,7 +63,7 @@ You are advised to do this *first*, because steps below depend on certain configuration changes to be made on your installed Linux distro. **Dependencies (do this first)** -============================= +-------------------------------- **Please read this: [Modifying GRUB in CBFS](grub_cbfs.md)** @@ -43,15 +72,14 @@ which tells you what modifications to actually perform, whereas the guide linked above tells you how to apply your modifications for flashing.** Flash write protection -====================== +---------------------- Although not strictly related to GRUB, flash protection will prevent anyone except you from overwriting the flash without permission. This is important, because you don't want some malicious software running as root from overwriting your flash, thus removing any of the above protections. -Build-time write protect ---------------------------- +### Build-time write protect Let's assume your board is `x200_8mb`, do: @@ -83,8 +111,7 @@ Anyway, when you're done, save the config and then build it from source in cbmk. See: [build from source](../build/) -IFD-based flash protection --------------------------- +### IFD-based flash protection **NOTE: This CAN cause bricks on a lot of machines. You should use this with care. The FLILL and/or PRx based methods are more reliable - also SMM methods. @@ -104,8 +131,7 @@ version matching the coreboot tree for your mainboard. Note that this only works for Intel-based systems that use an Intel Flash Descriptor, which is actually most Intel systems that Canoeboot supports. -Other facts ------------ +### Other facts Strapping `HDA_SDO` or `HDA_DOCK_EN` requires physical access, because you have to short a pin on the HDA chip on the motherboard, or there will be a header @@ -122,8 +148,7 @@ Enable `CONFIG_STRICT_DEVMEM` in your Linux kernel, or set `securelevel` above zero on your BSD setup (but BSD cannot be booted with GRUB very easily so it's a moot point). -FLILL ------ +### FLILL On Intel Flash Descriptor, you can insert up to four (4) commands on a list within, called *FLILL*; not yet documented, but any SPI command listed here @@ -131,14 +156,13 @@ would no longer work during internal flash operations. For example, you could use it to disable certain erase/write commands. You could also use it to disable *reads*. -PRx registers -------------- +### PRx registers Protected Range registers are available on Intel platforms, to disable flash writes. This is not yet documented, and it varies per platform. -GRUB Password -============= +GRUB password +------------- The security of this setup depends on a good GRUB password as GPG signature checking can be disabled through the GRUB console with this command: @@ -176,7 +200,7 @@ GRUB will also ask for a username in addition to the password; the "root" user is specified above, but you can cahnge it to whatever you want. Unset superusers -================ +---------------- Find this line in `grub.cfg`: @@ -191,7 +215,7 @@ because `unset superusers` in fact disables passwordh authentication, so it's very important that you comment out this line. Disable the SeaBIOS menu -==================== +------------------------ **Very important. Make sure you read this carefully.** @@ -219,8 +243,7 @@ Release images with `seagrub` in the name already have this bootorder file, so you only need to disable the menu on these images. If you have the image with `seabios` in the name (instead of `seagrub`), you must do both. -SeaBIOS option ROMs -------------------- +### SeaBIOS option ROMs SeaBIOS will also still execute PCI option ROMs. Depending on your preference, you may wish to disable this, but please note that this will break certain @@ -230,8 +253,7 @@ things like graphics cards. More information is available here: If you're using a graphics card, you *need* VGA option ROMs at least. -GRUBSEA -------- +### GRUBSEA Another option is to make it so that GRUB is the primary payload on your board. In this setup, SeaBIOS and U-Boot are still available. @@ -251,7 +273,7 @@ and disable the SeaBIOS menu, making SeaBIOS load only GRUB; SeaGRUB is useful because GRUB will piggyback off of the VGA setup done by SeaBIOS first. GPG keys -======== +-------- First, generate a GPG keypair to use for signing. Option RSA (sign only) is ok. @@ -293,7 +315,7 @@ into CBFS, using instructions already provided on the GRUB CBFS guide linked above, earlier on in this guide. Enforce GPG check in GRUB -========================= +------------------------- The following must be present in `grub.cfg`, but please note that the background image used by GRUB is in the memdisk by default, not CBFS, so you @@ -312,7 +334,7 @@ the GRUB CBFS guide that was also linked above, earlier on in the article you're currently reading. Install the new image -===================== +--------------------- Now simply flash the new image, using the [flashing instructions](../install/). @@ -323,8 +345,29 @@ and the system is now unbootable, that's OK because you can use an external flasher; please read [external flashing instructions](../install/spi.md) +Linux kernel hardening +---------------------- + +You may also wish to compile your own kernel, because distro kernels will always +have code in the same place, so attackers are more easily able to know exactly +where to attack your kernel (ROP-based attacks). + +The Whonix/KickSecure Linux projects have guidance about Linux kernel +hardening: + +* +* +* + +There's info there about userspace too, but start with kernel first. Canoeboot +is a boot firmware project, so Linux kernel hardening is beyond the scope of +the Canoeboot project documentation, **for now**. + +(for now, because Canoeboot may in fact provide a Linux distro in the flash +at some point, and this page will definitely be updated when that happens) + References -========== +---------- * [GRUB manual](https://www.gnu.org/software/grub/manual/html_node/Security.html#Security) * [GRUB info pages](http://git.savannah.gnu.org/cgit/grub.git/tree/docs/grub.texi) diff --git a/site/docs/linux/index.md b/site/docs/linux/index.md index c1eadcb..25799b0 100644 --- a/site/docs/linux/index.md +++ b/site/docs/linux/index.md @@ -1,10 +1,15 @@ --- -title: Linux guides +title: Install Linux on a Canoeboot system x-toc-enable: true ... +Booting Linux from GRUB payload +------------------------------- + NOTE: This guide pertains to x86 hosts, and does not cover supported CrOS/ARM -chromebooks. For ARM targets, you should refer to u-boot documentation. +chromebooks. For ARM targets, you should refer +to [u-boot documentation](../uboot/) - separate [U-Boot x86 +documentation](../uboot/uboot-x86.md) is also available. GRUB -------- @@ -17,51 +22,19 @@ on Linux is generally assumed, especially for Canoeboot development, but Canoeboot also works quite nicely with [BSD systems](../bsd/). -Useful links -============ +### Useful links -Refer to the following pages: +Refer to these pages, hosted by the Canoeboot project: * [How to Prepare and Boot a USB Installer in Canoeboot Systems](grub_boot_installer.md) * [Modifying the GRUB Configuration in Canoeboot Systems](grub_cbfs.md) * [How to Harden Your GRUB Configuration, for Security](grub_hardening.md) -NOTE ABOUT VGA MODES and GRUB -============================= - -Canoeboot does not support switching VGA modes, when coreboot's libgfxinit is -used on Intel GPUs. Many distros will install GRUB, which Canoeboot then finds -and executes, if running SeaBIOS payload; if using GRUB, just the distro's -grub.cfg file is loaded instead, by Canoeboot's own GRUB in flash. - -Canoeboot GRUB boots in text mode or uses the coreboot framebuffer. Anyway, -set `GRUB_TERMINAL=console` in GRUB and you should be fine. This avoids GRUB, -the one provided by your distro, switching video modes. - -In Debian for example (steps largely the same on other distros): - -Edit `/etc/default/grub` as root, and uncomment or add the line: - - GRUB_TERMINAL=console - -Then still as root, do these commands: - - export PATH="$PATH:/sbin" - update-grub - -NOTE: `update-grub` is very much Debian-centric. Not all distros will have it. -On Arch-based distros for instance, you might do: - - grub-mkconfig -o /boot/grub/grub.cfg - -The `update-grub` command is provided on Debian for user convenience, but on -all distros, you may want to just use `grub-mkconfig`. Use what works for you. - -Now your distro's GRUB menu should work, when your distro's GRUB bootloader is -executed from Canoeboot's SeaBIOS payload. +They will provide specific information; the information below pertains mostly +to troubleshooting, and there are some notes about Full Disk Encryption: Encrypted /boot via LUKS2 with argon2 -======================================= +------------------------------------- Full encryption for basic LUKS2 (with PBKDF or argon2 key derivation) is supported in Canoeboot. Legacy LUKS1 is also supported. On *most* other @@ -109,8 +82,7 @@ At the time of the Canoeboot 20231026 release, the GRUB upstream (on gnu.org) did not have these argon2 patches in its source tree, but Canoeboot merges and maintains them out of tree. -argon2id --------- +### argon2id You should *specifically* use argon2id. Please ensure this, because some older LUKS2 setups defaulted to the weaker *argon2i*. This post by Matthew @@ -118,10 +90,46 @@ Garret contains information about that: +Canoeboot's GRUB Argon2id implementation was created by Patrick Steinhardt, +who adapted PHC's Argon2 implementation for use in GRUB; Ax33l later added it +to Arch Linux AUR for GRUB 2.06, and Nicholas Johnson rebased *that* for +GRUB 2.12 so that Canoeboot could use it; Canoeboot later inherited it. + NOTE: You should also read the instructions about about `GRUB_TERMINAL`. +NOTE ABOUT VGA MODES and GRUB +----------------------------- + +Canoeboot does not support switching VGA modes, when coreboot's libgfxinit is +used on Intel GPUs. Many distros will install GRUB, which Canoeboot then finds +and executes, if running SeaBIOS payload; if using GRUB, just the distro's +grub.cfg file is loaded instead, by Canoeboot's own GRUB in flash. + +Canoeboot GRUB boots in text mode or uses the coreboot framebuffer. Anyway, +set `GRUB_TERMINAL=console` in GRUB and you should be fine. This avoids GRUB, +the one provided by your distro, switching video modes. + +In Debian for example (steps largely the same on other distros): + +Edit `/etc/default/grub` as root, and uncomment or add the line: + + GRUB_TERMINAL=console + +Then still as root, do these commands: + + export PATH="$PATH:/sbin" + update-grub + +NOTE: `update-grub` is very much Debian-centric. Not all distros will have it. +On Arch-based distros for instance, you might do: + + grub-mkconfig -o /boot/grub/grub.cfg + +Now your distro's GRUB menu should work, when your distro's GRUB bootloader is +executed from Canoeboot's SeaBIOS payload. + Rebooting system in case of freeze -=================================== +---------------------------------- Linux kernel has a feature to do actions to the system any time, even with it freezes, this is called a @@ -139,13 +147,12 @@ command line paramter. So append `sysrq_always_enabled=1` to your You can also run `# sysctl kernel.sysrq=1` to enable them. Fedora won't boot? -================== +------------------ This may also apply to CentOS or Redhat. Chroot guide can be found on [fedora website](https://docs.fedoraproject.org/en-US/quick-docs/bootloading-with-grub2/#restoring-bootloader-using-live-disk) -linux16 issue -------------- +### linux16 issue Canoeboot's default GRUB config sources fedora's grub config `grub.cfg` (in `/boot/grub2/grub.cfg`), fedora by default makes use of the @@ -159,8 +166,7 @@ Set the `sixteenbit` variable to an empty string, then run: grub2-mkconfig -o /boot/grub2/grub.cfg -BLS issue ---------- +### BLS issue With [newer versions of fedora](https://fedoraproject.org/wiki/Changes/BootLoaderSpecByDefault), scripts from grub package default to generating [BLS](https://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/) @@ -172,3 +178,6 @@ to `/etc/default/grub` (or modify existing one if it already exists): Then generate `grub.cfg` with: grub2-mkconfig -o /boot/grub2/grub.cfg + +These idiosyncrasies aside, Fedora is a great distro. It's well-tested with the +Canoeboot build system, and it boots up just fine. diff --git a/site/docs/maintain/index.md b/site/docs/maintain/index.md index a1f2391..7cd138b 100644 --- a/site/docs/maintain/index.md +++ b/site/docs/maintain/index.md @@ -1,10 +1,16 @@ --- -title: cbmk maintenance manual +title: CanoeBoot MaKe (cbmk) build system design and maintenance manual x-toc-enable: true ... -NOTE: Canoeboot standardises on [flashprog](https://flashprog.org/wiki/Flashprog) -now, as of 3 May 2024, which is a fork of flashrom. +Open source BIOS/UEFI firmware +------------------------------ + +Canoeboot is a [Free Software](https://writefreesoftware.org/learn) project, +replacing proprietary BIOS/UEFI firmware. It provides coreboot and a number +of *payloads* such as GRUB, U-Boot or SeaBIOS, which boot your operating system. +This document describes the very essence of Canoeboot's design, how the project +functions and how releases are made. In addition to this manual, you should also refer to [porting.md](porting.md) and [testing.md](testing.md). @@ -19,7 +25,7 @@ are kept in sync. You should therefore also read Libreboot's own about the porting process is written on the [about](../../about.md) page. Automated coreboot build system -=============================== +------------------------------- This document describes the entire Canoeboot build system, its design philosophy and how it's used to prepare Canoeboot releases; it is provided as a *reference* @@ -45,7 +51,7 @@ first, it will do so automatically. Therefore, you can run any part of cbmk on its own, and the entire design is modular. Best practises for learning cbmk -================================ +-------------------------------- The follow sections will cover subdirectories, within cbmk. Contrary to what some may otherwise assume, it's best to learn about everything *except* scripts @@ -63,8 +69,7 @@ bottom-up; most documents take the latter approach, in other projects, but most people naturally want to learn how a specific thing works first, hence the approach taken here. -Don't be deceived by simplicity -------------------------------- +### Don't be deceived by simplicity Canoeboot's build system is powerful, and highly configurable, yet deceptively simple at the same time. Remember this rule, a rule that applies to *all* @@ -75,12 +80,11 @@ Many people will be shocked by how *small* Canoeboot is, at its core. You will be surprised by just how much can be done with so little. Continue reading! System requirements -=================== +------------------- This concerns system requirements when *building* Canoeboot. -Operating system ----------------- +### Operating system Any sensible Linux distribution will do. Canoeboot's build system is regularly testing on all the major distros. Please do report bugs if you encounter @@ -97,18 +101,16 @@ Alpine, though we currently do not have an automated way to install build dependencies for these distros. NOTE: **Linux** is assumed. BSD systems may work, for parts of the build system, -but BSD systems are currently not well-tested with lbmk. +but BSD systems are currently not well-tested with cbmk. -**Dependencies** ----------------- +### **Dependencies** **Make sure you have dependencies installed!** **The [main build guide](../build) will tell you how to install dependencies, such as GNU toolchains and various libraries.** -Host CPU --------- +### Host CPU At least an Intel Core 2 Duo, though we recommend much faster CPUs if building entire release archives, e.g. quad-core Haswell CPU or better. @@ -123,8 +125,7 @@ NOTE3: *32-bit* x86 (i686) machines can be used to compile Canoeboot, but MemTest86\+ is only compiled for 64-bit, and not cross compiled, so builds are disabled when cbmk detects a 32-bit host CPU. -Memory ------- +### Memory At least 2GB per CPU core, ideally 4GB; for example, 16GB RAM is recommended if you're compiling an a quad-core CPU. @@ -135,8 +136,7 @@ For example, when you're building on a quad-core, do this prior to building: export XBMK_THREADS=4 -Disk space ----------- +### Disk space About 20GB bare minimum, if only compiling for 1 board. The sources take up a lot of space. However, Canoeboot is always expanding as it's developed. @@ -149,10 +149,9 @@ major bottleneck, so any HDD or SSD will do, but we obviously recommend a fast NVMe (PCI-E) SSD if you can. Environmental variables -======================= +----------------------- -XBMK\_THREADS -------------- +### XBMK\_THREADS For example: @@ -163,8 +162,7 @@ This would build on two threads, when running cbmk. It defaults to 1. Previous revisions of cbmk used `nproc` by default, but this was set to 1 instead, because nproc is not available on every operating system. -XBMK\_RELEASE -------------- +### XBMK\_RELEASE If set to `y`, it signals to `script/roms` that a release is being built, and it will honour `release="n"` in target.cfg files. You could also set this @@ -174,7 +172,7 @@ behaves running it in release mode. Do this if you want to: export XBMK_RELEASE=y Projects/files downloaded/generated by cbmk -=========================================== +-------------------------------------------- The following sections will describe files and directories that are not included in `cbmk.git`, but *are* created by running various cbmk commands; @@ -183,8 +181,7 @@ many of these will also be provided, pre-generated, under release archives. Some of these are *downloaded* by Canoeboot's build system, automatically, while others are created during the build process based on these downloaded programs. -bin/ ---------------- +### bin/ This directory is created when running any of the following commands, with the right arguments: @@ -208,14 +205,12 @@ now only puts coreboot images in `bin/`, with payloads included. If you still have `elf/` coreboot images in your cbmk tree, please do not use them (and you may aswell delete them). -cache/ ---------------- +### cache/ Certain files are cached here automatically, by cbmk. The user need not touch these files. -cache/file/ --------------- +### cache/file/ Files that are downloaded are hashed, and the cached version of the file is stored there, named as the SHA512 checksum. This is used for submodule Git @@ -229,8 +224,7 @@ files relative to the directory locations for those repositories, but subfiles are not downloaded to the *cached git repository*, only the work directory used for building in cbmk. -cache/hash ---------------- +### cache/hash/ When cbmk is handling any project, it sorts a list of files under `config/` including `config/project` (or `config/project/TREE`) and `config/data/project`. @@ -243,14 +237,12 @@ If the currently stored hash differs from what's calculated, it means that the project has changed, and the source directories plus builds are deleted. The project source is then re-prepared and re-build. -cache/repo --------------- +### cache/repo/ Git repositories are cached here. This avoids wasting bandwidth, when downloading multiple repositories. **Git submodules are also cached here!** -elf/ ---------------- +### elf/ **DO NOT flash coreboot ROM images contained under `elf/`. Please use ROM images under `bin/` instead! - In modern cbmk, only the ones under `bin/` are ever @@ -285,8 +277,7 @@ As of Canoeboot 20240612, the `elf/` directory must be used by default for all builds, in an effort to make exclusive use of *out-of-source builds*. As such, the `cbutils` directory is no longer used. -release/ ---------------- +### release/ The script at `build` create tarballs in here, which constitute regular Canoeboot releases. It is meticulously maintained, as per @@ -315,13 +306,11 @@ Or with a custom directory: The build system expects there to be a *git tag*, so make sure there is one. This is used to create the version number for a given release. -src/ ----- +### src/ Third-party source trees are downloaded into this directory, by cbmk. -src/coreboot/ ---------------- +### src/coreboot/ Please also visit: @@ -340,8 +329,7 @@ This may be less efficient on disk usage, but it simplifies the logic greatly. Coreboot also uses its own toolchain called *crossgcc*, and crossgcc is in fact compiled *per tree* in Canoeboot. -src/flashprog/ ---------------- +### src/flashprog/ Please also visit: @@ -350,8 +338,7 @@ convenience of users, and this is copied to release archives. Flashprog is the program that you will use to read, erase and write the flash, containing coreboot firmware. -src/gpio-scripts ----------------- +### src/gpio-scripts This is a fork of the original gpio-scripts. The fork is maintained by Riku Viitanen, based on code written by Angel Pons (author of the Haswell native @@ -362,8 +349,7 @@ machines, when porting new boards to coreboot. NOTE: Not included in Canoeboot yet, but `intelp2m` is used instead for this purpose, on much newer Intel systems (from around Skylake era or later). -src/grub/TREE ---------------- +### src/grub/TREE Please also visit: @@ -396,25 +382,19 @@ tree contains NVMe SSD support but not xHCI support. The `default` tree contains no NVMe or xHCI support. All trees otherwise have the same fixes on top of upstream GRUB, e.g. fix for Dell Latitude keyboard controllers. -src/int/ --------- +### src/int/ Riku Viitanen wrote this tool for debugging, when implementing MXM option ROM support in coreboot and SeaBIOS, for the HP EliteBook 8560w. -NOTE: The EliteBook 8560w isn't actually supported in Canoeboot yet, but this -could be used for other boards in the future. - -src/memtest86plus/ ---------------- +### src/memtest86plus/ Please also visit: This is provided inside ROM images, as a payload executed from main GRUB or SeaBIOS payload. It checks for corrupted memory. -src/mxmdump/ ------------- +### src/mxmdump/ Riku Viitanen wrote this utility, for dumping the MXM config on graphics cards that use it. The HP EliteBook 8560w uses these cards, and normally you would @@ -430,8 +410,7 @@ this fact, but such hacks are no longer required because of Riku's tool. NOTE: The EliteBook 8560w isn't supported in Canoeboot yet, but this tool could be used for other machines in the future. -src/seabios/ ---------------- +### src/seabios/ Please also visit: @@ -443,8 +422,7 @@ particular, the BSD bootloaders can be executed from SeaBIOS. This is provided as a coreboot payload, either as first payload or it can be executed from GRUB (if GRUB is the main payload, on a given target). -src/u-boot/ ---------------- +### src/u-boot/ Please also visit: @@ -461,8 +439,7 @@ More information can be found on the [U-Boot x86 page](../install/uboot-x86.md); it is available as an alternative to the traditional SeaBIOS and GRUB payloads, and it can successfully boot UEFI applications on x86 Canoeboot systems. -src/pcsx-redux ----------------- +### src/pcsx-redux/ PCSX-Redux is a Sony Playstation (PS1/PSX) emulator, but Canoeboot only uses one part from it: the Open BIOS. This is used by Canoeboot to provide an @@ -473,8 +450,7 @@ More information available on the [PlayStation page](../install/playstation.md). This is automatically compiled by the main build script, and the resulting BIOS image is provided in Canoeboot release archives. -src/pico-serprog ---------------------------- +### src/pico-serprog/ Used by cbmk, to build firmware for serprog-based SPI flashers with RP2040 SoC. Alongside this, `util-fw/rp2040/pico-sdk` is imported which is required for @@ -485,8 +461,7 @@ Please visit these pages: * * -src/stm32-vserprog ----------------------- +### src/stm32-vserprog/ Used by cbmk, to build firmware for serprog-based SPI flashers with STM32 MCU. Alongside this, `libopencm3` is imported which is required for building it. @@ -501,8 +476,7 @@ Before moving onto configurations, we will now cover *utilities* provided by Canoeboot itself (included within cbmk, rather than being downloaded like the third party projects listed above): -tmp/ ---------------- +### tmp/ The `TMPDIR` environmental variable is set by cbmk, to a location under `/tmp`, but some users may have `/tmp` mounted as a *tmpfs* (file system in RAM), and @@ -512,7 +486,7 @@ Where large files (or a large number of files) are handled by cbmk on a temporary basis, this `tmp/` directory is created and then used. util/ -=============== +----- If a codebase is not frequently used by Canoeboot, is actively developed (making it not viable to maintain in Canoeboot) or the codebase is very large, we would @@ -522,8 +496,7 @@ where the intention is that `cbmk.git` itself should be small and efficient. Where appropriate, and where the code is small enough, or it is otherwise deemed desirable, `cbmk.git` provides a few utilities as part of itself, namely: -util/dell-flash-unlock/ ---------------- +### util/dell-flash-unlock/ This program, written by Nicholas Chin, unlocks the boot flash on Dell Latitude E6400; it permits internal flashing, from factory firmware to Canoeboot, so that @@ -532,8 +505,7 @@ the user need not disassemble and flash externally. It also supports several other Dell laptops, with similar ECs. Check the README file included in this directory, for more information. -util/nvmutil/ ---------------- +### util/nvmutil/ The `nvmutil` software allows you to set the MAC address on Intel GbE NVM files. It also allows you to set *random* MAC addresses, in addition to @@ -544,8 +516,7 @@ about here: [nvmutil manual](../install/nvmutil.md) -util/spkmodem\_recv/ ---------------- +### util/spkmodem\_recv/ Canoeboot imported this from coreboot, who is turn imported it from GRUB with little to no modification. @@ -582,13 +553,12 @@ do this. Other improvemnts include: by cbmk: config/ -======= +------- This directory contains configuration files, used by the Canoeboot build system. These next sections will cover specific configuration files. -config/PROJECT\*/nuke.list --------------------------- +### config/PROJECT\*/nuke.list The script `include/git.sh` handles deletion of certain files, for downloaded projects, based on a `nuke.list` file that can (for single-tree projects) be @@ -606,10 +576,9 @@ foo/bar.txt Ditto `src/flashprog/`, if you wanted to delete a file from in there, as one other example. Deletions occur when the source tree is created. -config/coreboot ---------------- +### config/coreboot/ -### config/coreboot/BOARDNAME/ +#### config/coreboot/BOARDNAME/ Each target name (e.g. `x200_8mb`) has its own directory under here. Targets that do not define defconfigs also exist here; for example, the `default` @@ -621,14 +590,14 @@ for example, be `default`. In other words, they can refer to other trees. The coreboot downloads are based on scanning of these directories, and ROM images are also built based on them. -### config/coreboot/BOARDNAME/patches/ +#### config/coreboot/BOARDNAME/patches/ For any given coreboot tree, patches with the `patch` file extension are placed here, alphanumerically in the order that they should be applied. These patches are then so applied, when cbmk downloads the given source tree. -### config/coreboot/BOARDNAME/target.cfg +#### config/coreboot/BOARDNAME/target.cfg This file can contain several configuration lines, each being a string, such as: @@ -738,7 +707,7 @@ by this variable, to also be present. The `grubtree` option specifies which GRUB tree to use. If unset, it defers to the `default` GRUB tree. -### config/coreboot/BOARDNAME/config/ +#### config/coreboot/BOARDNAME/config/ Files in this directory are *coreboot* configuration files. @@ -816,8 +785,7 @@ Even if your board doesn't actually use `libgfxinit`, the config for it should still be named as such. From a user's perspective, it really makes no difference. -config/dependencies/ ---------------- +### config/dependencies/ Files here are so named, and called like so: e.g. the `debian` file would be referenced when running: @@ -828,8 +796,7 @@ These files define a list of packages, and the correct package manager command to use on a given distro. This can be used to install build dependencies, which are required for compiling Canoeboot from source code. -config/git/ ---------------- +### config/git/ Configuration related to third-party Git repositories, that Canoeboot makes use of. @@ -844,8 +811,7 @@ of their own; for example, `config/grub/` exists. Multiple files exist here, and they are *concatenated* in a temporary file by cbmk, which is then scanned to find information about projects. -config/data/PROJECT/mkhelper.cfg --------------------------------- +### config/data/PROJECT/mkhelper.cfg These `mkhelper.cfg` files define common configuration that can be supplied for any single- or multi-tree project. Arguments available are as follows: @@ -890,18 +856,17 @@ In the simplest of terms, you may regard mkhelpers as *plugins*, of a sort. They simply extend the core functionality of the build system, in a way that can differ flexibly between projects. -GRUB config ---------------- +### GRUB config -### config/data/grub/background +#### config/data/grub/background/ Splash screen images applied duing startup when using the GRUB payload. -### config/data/grub/background/background1024x768.png +#### config/data/grub/background/background1024x768.png Used on ThinkPad X60 and T60. -### config/data/grub/background/background1280x800.png +#### config/data/grub/background/background1280x800.png Used on all other machines, besides X60 and T60 thinkpads. @@ -911,23 +876,23 @@ example, `config/coreboot/x60/target.cfg` specifies this: grub_background="background1024x768.png" -### config/data/grub/background/COPYING +#### config/data/grub/background/COPYING Licensing info for GRUB bootsplash images. -### config/grub/TREE/config/ +#### config/grub/TREE/config/ GRUB configuration files. -### config/grub/config/AUTHORS +#### config/grub/config/AUTHORS Author info for GRUB configuration files. -### config/grub/config/COPYING +#### config/grub/config/COPYING Licensing info for GRUB configuration files. -### config/grub/TREE/config/payload +#### config/grub/TREE/config/payload This is a configuration file. It is used to program GRUB's shell. @@ -941,7 +906,7 @@ A `grubtest.cfg` can be inserted into CBFS, but it will not override the default `grub.cfg` (either in CBFS or on memdisk); however, the one in memdisk will provide a menuentry for switching to this, if available. -### config/data/grub/memdisk.cfg +#### config/data/grub/memdisk.cfg This GRUB configuration checks whether `grub.cfg` exists in CBFS and switches to that first (not provided by default) or, if one is not available in CBFS, @@ -951,12 +916,12 @@ The GRUB memdisk is a file system within `grub.elf`, itself stored within the coreboot file system named *CBFS*, which is part of the coreboot ROM image on every coreboot target. -### config/data/grub/keymap/ +#### config/data/grub/keymap/ Keymap files used by GRUB. They can alter the character set corresponding to inputted scancodes. -### config/data/grub/keymap/\*.gkb +#### config/data/grub/keymap/\*.gkb The keymap files themselves. These are inserted into the GRUB memdisk, and the `grub.cfg` file can specify which one is to be used. @@ -965,7 +930,7 @@ These files are binary-encoded, defining which characters correspond to which scancodes. It is handled by `grub-core/commands/keylayouts.c` in the GRUB source code. -### config/data/grub/module/TREE +#### config/data/grub/module/TREE This defines which modules are inserted into `grub.elf`. These modules can be anything from file systems, small applications/utilities, launchers (e.g. @@ -979,7 +944,7 @@ This list is used by cbmk when it runs `grub-mkstandalone`, which is the utility from GRUB that generates `grub.elf` files (to be compressed inside CBFS and then executed as a coreboot payload). -### config/grub/TREE/patches/ +#### config/grub/TREE/patches/ For a given GRUB revision, patches with the `patch` file extension are placed here, alphanumerically in the order that they should be applied. For example, @@ -988,69 +953,66 @@ partitions to be decrypted by GRUB. These patches are then so applied, when cbmk downloads the given source tree. -config/ifd/\* ---------------- +### config/ifd/\* Intel Flash Descriptors and GbE NVM images, which are binary-encoded configuration files. These files are referenced in coreboot defconfigs, used by cbmk to build coreboot ROM images. -config/seabios/ ---------------- +### config/seabios/ -### config/data/seabios/build.list +#### config/data/seabios/build.list When a given SeaBIOS tree is compiled, for a given target, this file defines which files to copy from the `seabios/` directory, which are then copied to a location under `elf/seabios`. -### config/seabios/default/ +#### config/seabios/default/ Currently the only tree in use, this defines what SeaBIOS revision is to be used, when the SeaBIOS payload is enabled on a given coreboot target. -### config/seabios/default/config/ +#### config/seabios/default/config/ Configuration files go in here. -### config/seabios/default/config/libgfxinit +#### config/seabios/default/config/libgfxinit Configuration file for when native video initialisation is available in coreboot. -### config/seabios/default/config/normal +#### config/seabios/default/config/normal Configuration file for when native video initialisation is unavailable in coreboot, and VGA ROM initialisation is also not provided by coreboot (in this configuration, the usual setup will be that *SeaBIOS* finds and executes them, instead of coreboot). -### config/seabios/default/config/vgarom +#### config/seabios/default/config/vgarom Configuration file for when native video initialisation is unavailable in coreboot, and VGA ROM initialisation is provided by coreboot; in this setup, SeaBIOS should not execute VGA ROMs. -### config/seabios/default/target.cfg +#### config/seabios/default/target.cfg Similar concept to `target.cfg` files provided by coreboot. This specifies which SeaBIOS revision (from Git) is to be used, when compiling SeaBIOS images. -config/u-boot/ ---------------- +### config/u-boot/ This directory contains configuration, patches and so on, for each mainboard that can use U-Boot as a payload in the `cbmk` build system. U-Boot doesn't yet have reliable generic configurations that can work across all coreboot boards (per-architecture), so these are used to build it per-board. -### config/data/u-boot/build.list +#### config/data/u-boot/build.list When a given U-Boot tree is compiled, for a given target, this file defines which files to copy from the U-Boot source build, which are then copied to a location under `elf/u-boot/`. -### config/u-boot/TREENAME/ +#### config/u-boot/TREENAME/ Each `TREENAME` directory defines configuration for a corresponding mainboard. It doesn't actually have to be for a board; it can also be used to just define @@ -1058,14 +1020,14 @@ a U-Boot revision, with patches and so on. To enable use as a payload in ROM images, this must have the same name as its `config/coreboot/TREENAME/` counterpart. -### config/u-boot/TREENAME/patches/ +#### config/u-boot/TREENAME/patches/ For any given U-Boot tree, patches with the `patch` file extension are placed here, alphanumerically in the order that they should be applied. These patches are then so applied, when cbmk downloads the given source tree. -### config/u-boot/TREENAME/target.cfg +#### config/u-boot/TREENAME/target.cfg This file can contain several configuration lines, each being a string, such as: @@ -1101,7 +1063,7 @@ to a non-native arch means that necessary crossgcc-arch will be compiled and be available when building roms, but not necessarily built or discovered when individual scripts are called manually.* -### config/u-boot/TREENAME/config/ +#### config/u-boot/TREENAME/config/ Files in this directory are *U-Boot* configuration files. Configuration file names can be anything, but for now `default` is the only one used. @@ -1131,8 +1093,7 @@ Another interesting config option is `CONFIG_POSITION_INDEPENDENT` for ARM boards, which has been so far enabled in the ones `cbmk` supports, just to be safe. -config/submodule ----------------- +### config/submodule/ In here you can find submodule configurations for projects. It works for both single- and multi-tree projects. Use the existing examples as reference. @@ -1175,14 +1136,12 @@ because files are not extracted, only placed at their configured destination). The destination path in `module.list` is relative to the location of the main Git repository under which it is placed. -config/data/PROJECT -------------------- +### config/data/PROJECT/ Random configuration data provided on a per-project basis. Complements the `config/PROJECT` directory. -U-Boot build system -------------------- +### U-Boot build system If you wish to know about U-Boot, refer here:\ @@ -1214,28 +1173,24 @@ configs, but not for adding them. Adding them is to be done manually, based on the above guidance. Config files in cbmk root directory -=================================== +----------------------------------- -projectsite -------------- +### projectsite Domain name linking to the project home page (e.g. canoeboot.org). -projectname ---------------- +### projectname This is a text file, containing a single line that says `canoeboot`. This string is used by the build system, when naming releases alongside the version number. -version ---------------- +### version Updated each time cbmk runs, based on either `git describe` or, on release archives, this file is static and never changes. It says what Canoeboot revision is currently in use (or was in use, if cbmk isn't running). -versiondate ---------------- +### versiondate Updated each time cbmk runs, based on either `git describe` or, on release archives, this file is static and never changes. It says the *time* of @@ -1245,10 +1200,9 @@ At last, you will now learn about the *scripts* (exclusively written as posix shell scripts) that constitute the entire Canoeboot build system, cbmk: Scripts in root directory of cbmk -================================= +--------------------------------- -build ---------------- +### build This is the main build script. @@ -1271,14 +1225,13 @@ You can also know what build system revision you have by running: This script is the beating heart of Canoeboot. Break it and you break Canoeboot. include/ -=============== +-------- This directory contains *helper scripts*, to be included by main scripts using the `.` command (called the `source` command in `bash`, but we rely upon posix `sh` only). -include/git.sh --------------- +### include/git.sh These functions in here previously existed as independent scripts, but they were unified here, and they are used when you pass the `-f` argument @@ -1288,8 +1241,7 @@ These functions deal with git cloning, submodule updates, revision resets and the application of patch files via `git am`. *Every* git repository downloaded by cbmk is handled by the functions in this file. -include/lib.sh ---------------- +### include/lib.sh Several other parts of cbmk also use this file. It is added to as little as possible, and contains miscallaneous functions that don't belong anywhere else. @@ -1314,8 +1266,7 @@ so if for example you say `mk coreboot`, it would build every coreboot target. This is useful for the release build logic, because now it can much more simply build all of Canoeboot, while still being flexible about it. -include/rom.sh ------------ +### include/rom.sh This builds coreboot ROM images. Specifically, this contains mkhelper functions. It also builds serprog images, and it could be used to provide functions for @@ -1386,8 +1337,7 @@ CCACHE is automatically used, when building coreboot, but not currently for other projects. This is done by cooking coreboot configs at build time, enabling coreboot's build option for it. -Serprog images: --------------- +### Serprog images: Build firmware images for serprog-based SPI programmers, where they use an STM32 MCU. It also builds for RP2040-based programmers like Raspberry Pi Pico. @@ -1405,10 +1355,9 @@ include/inject.sh Functions for modifying the intel GbE MAC address on IFD-based Intel systems. script/ -======= +------- -script/trees ------------- +### script/trees *This* is the other beating heart of Canoeboot. Used heavily by Canoeboot, this script is what handles defconfig files for SeaBIOS, U-Boot *and* coreboot; it diff --git a/site/docs/maintain/style.md b/site/docs/maintain/style.md index 48053d7..829a3ff 100644 --- a/site/docs/maintain/style.md +++ b/site/docs/maintain/style.md @@ -13,7 +13,7 @@ and several practises may persist in spite of it; nonetheless, this article shall serve as a reference for cbmk development. NO BASHISMS -=========== +----------- Canoeboot's build system, cbmk (CanoeBoot MaKe) is written entirely in POSIX shell (sh) scripts. This is thanks to the work done by Ferass El Hafidi on @@ -28,15 +28,14 @@ and an even more excellent introduction: (seriously, it's good. Read it!) Design -====== +------ Canoeboot's build system design is very simple: put as much as possible under `config/`, and keep actual logic to a minimum. You can read about that design in the [cbmk maintenance manual](index.md). -No Makefiles ------------- +### No Makefiles We have Makefiles in some C programs, under `util/`, and projects that we import may use Makefiles, but cbmk itself does not contain any Makefiles. Instead, we @@ -47,7 +46,7 @@ code is more readable. It's easier to implement a cleaner coding style, which the next sections will cover. Coding style -============ +------------ Read and go read a few userland program source trees in OpenBSD's main CVS tree. This is the style that inspires the cbmk @@ -61,19 +60,17 @@ Canoeboot scripts, and also C programs like `nvmutil`, are heavily inspired by this style. We insist on its use, because this style is extremely readable and forces you to write better code. -main on top ------------ +### main on top In every cbmk script, it is our intention that there be a `main()` function. All logic should be inside a function, and `main()` should be the function that executes first; at the bottom of each script, insert this line: - main $@ + main "$@" This will execute `main()`, passing any arguments (from the user's shell) to it. -Top-down logic --------------- +### Top-down logic *Every* function called from main should always be *below* the calling function. Therefore, if multiple functions call a given function, that function should be @@ -119,11 +116,10 @@ complicated_function() do_some_complicated_stuff || return 1 } -main $@ +main "$@" ``` -PWD is always root of cbmk --------------------------- +### PWD is always root of cbmk In any script executed by cbmk, under `script/`, the work directory is relative to the main `cbmk` script. In other words, all scripts under `script/` also @@ -132,8 +128,7 @@ assume this. This is actually one of the reasons for that design, as also alluded to in the main [cbmk maintenance manual](index.md). -main should only be a simple skeleton -------------------------------------- +### main should only be a simple skeleton The `main()` function should not implement much logic itself. Each script in cbmk is its own program. The `main()` function should contain the overall @@ -145,7 +140,7 @@ be below a function that builds ROM images with SeaBIOS payloads inside them, when building coreboot ROM images. One task, one script -==================== +-------------------- Not literally *one task*, but one theme, one *kind* of overall task. For example, `script/build/roms` builds final ROM images of coreboot, @@ -156,7 +151,7 @@ another program that does another thing very well; programs communicate with each other via the universal method, namely text. Error handling -============== +-------------- Where feasible, a script should do: @@ -184,8 +179,7 @@ For example: $err "function_name: this shit doesn't work. fix it." -Do not directly exit --------------------- +### Do not directly exit Please try to use `err` for all error exits. @@ -197,8 +191,7 @@ A script should either return zero status, or call `err()`. An individual function may, in some cases, return 1 or 0 itself, which would then be handled accordingly by the calling function. -How to handle errors --------------------- +### How to handle errors There are some instances where errors should be *ignored*, in which case you might do: @@ -212,7 +205,7 @@ command succeeded, then do this. Never mix `&&` and `||` If/else blocks -============== +-------------- Keep these simple, and where possible, maybe don't use them at all! For example: @@ -237,8 +230,7 @@ or do something ``` -Warnings --------- +### Warnings In C, the `stderr` file is 2 as represented by `int fd` style. In shell scripts, it's the same: 1 for standard output, 2 for errors/warnings. The `err` function @@ -250,25 +242,24 @@ should not yield an exit, you should do something like this: printf "function_name: this is dodgy stuff. fix it maybe?\n" 1>&2 Avoid passing arguments excessively -=================================== +----------------------------------- In functions, use of arguments passed to them can be useful, but in general, they should be avoided; use global variables when feasible. Do not exceed 80 characters per line -==================================== +------------------------------------ See: RFC 3676 Excessively long code lines are really annoying to read. Use tab-based indendation -========================= +------------------------- A new line should begin with tab indentation, in a function. -Multi-line commands -------------------- +### Multi-line commands Use \\ at the end, as you would, but use *four spaces* to indent on the follow-up line. For example: @@ -282,14 +273,14 @@ function_name() ``` Use printf! -=========== +----------- Don't use `echo` unless there's some compelling reason to do so. The `printf` functionality is more standard, across various sh implementations. env -=== +--- Don't do: @@ -302,7 +293,7 @@ Do: This is more portable, between various Unix systems. Be portable! -============ +------------ In addition to not using bashisms, commands that cbmk uses must also be portable; where possible, third party projects should be tweaked. @@ -317,7 +308,7 @@ Work+testing is sorely needed, in this area. It would be nice if Canoeboot could be built on BSD systems, for example. Do as little as possible -======================== +------------------------ Don't over-engineer anything. Write as simply as you can, to perform a single task. This is basically the same as what has been written elsewhere, but it's diff --git a/site/docs/maintain/testing.md b/site/docs/maintain/testing.md index 15ef88d..4a1fef7 100644 --- a/site/docs/maintain/testing.md +++ b/site/docs/maintain/testing.md @@ -35,7 +35,7 @@ provide testing for the same mainboard if that's what you have. The more the merrier! Be Contactable -============== +-------------- You should monitor whatever email you provide in your application. There is no specific time-frame for how long it should take after @@ -45,7 +45,7 @@ If you are the *only* maintainer for your board then please take into consideration that your input is especially vital. Have External Flashing Equipment -================================ +-------------------------------- The roms you test will of course be untested. To avoid having a bricked machine, you need to have external flashing @@ -57,7 +57,7 @@ Refer to [Coreboot's documentation](https://doc.coreboot.org/) or ask on IRC if you are unsure. Testing Procedure -================= +----------------- You will receive an email when roms are ready for testing. The email will link to an open issue on our [current git hosting platform.](/git.html#cbmk-canoeboot-make) @@ -78,6 +78,6 @@ note: [insert any notes if relevant] For example, a board status comment might look like this: - board: t440p_12mb - status: fail - note: GRUB throws error 'something_is_b0rked' + board: t440p_12mb + status: fail + note: GRUB throws error 'something_is_b0rked' diff --git a/site/docs/maintain/testing.uk.md b/site/docs/maintain/testing.uk.md index c81055a..07d4844 100644 --- a/site/docs/maintain/testing.uk.md +++ b/site/docs/maintain/testing.uk.md @@ -32,7 +32,7 @@ Canoeboot намагається зробити Coreboot доступним дл краще! Будьте доступними для зв'язку -============== +-------------------------- Вам варто відслідковувати будь-яку електронну пошту, що ви вкажете в вашому поданні. Немає конкретного часового проміжку для того, скільки має пройти часу після того, як @@ -42,27 +42,27 @@ Canoeboot намагається зробити Coreboot доступним дл врахуйте, що ваш внесок є особливо значущим. Майте обладнання для зовнішньої прошивки -================================ +------------------------------------- Образи rom, які ви випробуєте, будуть звісно невипробуваними. Задля уникнення отримання непрацездатної машини, вам потрібно мати обладнання для зовнішньої прошивки в наявності для відновлення вашої плати з поламаного rom. -В більшості випадків ви можете посилатися на [керівництво SPI.](../install/spi.html) +В більшості випадків ви можете посилатися на [керівництво SPI](../install/spi.md). В менш частих випадках -таких як, деякі ARM chromebook- ваша плата може бути прошита іншим чином. Посилайтесь на [документацію Coreboot](https://doc.coreboot.org/) або спитайте в IRC, якщо не впевнені. Процедура випробування -================= +--------------------- Ви отримаєте лист електронною поштою, коли образи rom будуть готовими для випробування. -Лист електронною поштою буде посилатися на відкритий issue на нашій [поточній платформі розміщення git.](/git.html#cbmk-canoeboot-make) +Лист електронною поштою буде посилатися на відкритий issue на нашій [поточній платформі розміщення git.](../../git.md#cbmk-canoeboot-make) Чи ви отримаєте лист електронною поштою через поштовий домен canoeboot.org, або один з email розробників, вам варто перевірити (для вашої власної безпеки), -що завантажені rom підписано з [офіційним ключем.](/download.html#gpg-signing-key) +що завантажені rom підписано з [офіційним ключем.](../../download.md#gpg-signing-key) Коли ваше випробування закінчено, прокоментуйте в issue, на яке наведено посилання в вашому відправленому листі електронною поштою, таким чином: @@ -75,6 +75,6 @@ note: [вставьте будь-які приміткі, якщо релева Наприклад, відгук про статус плати міг би виглядати подібним чином: - board: t440p_12mb - status: fail - note: GRUB throws error 'something_is_b0rked' + board: t440p_12mb + status: fail + note: GRUB throws error 'something_is_b0rked' diff --git a/site/docs/misc/codenames.md b/site/docs/misc/codenames.md index f6a15d2..f0cd5d3 100644 --- a/site/docs/misc/codenames.md +++ b/site/docs/misc/codenames.md @@ -6,7 +6,7 @@ x-toc-enable: true TODO: this page could do with an update. More info, about more boards Introduction -============ +------------ This document lists product codenames for some hardware. Please note that just because a certain device is listed here does NOT mean @@ -28,7 +28,7 @@ of reliability): they will appear silver. List of models and codenames -============================ +---------------------------- ### Codenames @@ -101,6 +101,7 @@ under RAM sticks. - Port Replicator II - Seville-lite ### Miscellaneous + - [Calistoga](https://ark.intel.com/products/codename/5950/Calistoga): 945GM/945PM chipset family name - Napa: calistoga based platform @@ -118,7 +119,8 @@ GM45/GS45/PM45 chipset family name. of it fully describes its operation. See also -======== +-------- + - Many more Intel codenames can be found at [Wikipedia](https://en.wikipedia.org/wiki/List_of_Intel_codenames). - For ThinkPads see [Documentation/thinkpad/codenames.csv @ Coreboot] diff --git a/site/docs/misc/emulation.md b/site/docs/misc/emulation.md index 7f4820f..bc87ce5 100644 --- a/site/docs/misc/emulation.md +++ b/site/docs/misc/emulation.md @@ -3,8 +3,8 @@ title: Building Canoeboot for Emulation x-toc-enable: true ... -Introduction -============ +Canoeboot on QEMU +----------------- Canoeboot supports building for qemu as a target board. The resulting rom can then be tested using qemu. @@ -13,7 +13,7 @@ The qemu board is mostly intended to speed up development by removing the need t Qemu may also be useful for end users who intend to make changes to their Canoeboot rom without having to flash and reboot their machine. Building and Testing -==================== +-------------------- Canoeboot can be built for qemu just like any other board. @@ -57,7 +57,7 @@ qemu-system-aarch64 \ ``` Use Cases -========= +--------- While development is the primary motivation for qemu support, the board makes it easy to test minor changes to release roms. For example one can use *cbfstool* from coreboot to edit the background image in a Canoeboot rom as follows: diff --git a/site/docs/misc/index.md b/site/docs/misc/index.md index c84a069..0155141 100644 --- a/site/docs/misc/index.md +++ b/site/docs/misc/index.md @@ -11,7 +11,7 @@ You should assume that these instructions no longer work. Otherwise, if you wish to test them and send changes, patches are very much welcome! High Pitched Whining Noise on Idle in Arch-based distros -============================================================== +-------------------------------------------------------- **NOTE: VERY OLD advice (years old), it may not be relevant for modern Arch.** @@ -69,7 +69,6 @@ using [this guide](../linux/grub_cbfs.md). X60/T60: Serial port - how to use (for dock owners) [Note: using a grsec enabled kernel will disable the powertop function. ](https://en.wikibooks.org/wiki/Grsecurity/Appendix/Grsecurity_and_PaX_Configuration_Options) -=================================================== For the Thinkpad X60 you can use the "UltraBase X6" dock (for the X60 Tablet it is called X6 Tablet UltraBase). For the ThinkPad T60, you @@ -103,8 +102,8 @@ Note: part of the tutorial above requires changing your grub.cfg. Just change the `linux` line to add instructions for enabling getty. See [../linux/grub\_cbfs.md](../linux/grub_cbfs.md). -Finetune backlight control on intel gpu's -========================================= +Finetune backlight control on intel GPUs +---------------------------------------- Sometimes the backlight control value (BLC\_PWM\_CTL) set by Canoeboot is not ideal. The result is either flicker, which could cause nausea or @@ -196,7 +195,7 @@ on page 94. More research needs to be done on this target so proceed with care. Power Management Beeps on Thinkpads -=================================== +----------------------------------- When disconnecting or connecting the charger, a beep occurs. When the battery goes to a critically low charge level, a beep occurs. Nvramtool @@ -231,7 +230,7 @@ Finally, you need to flash the rom with this new image. See here for a detailed explanation. Get EDID: Find out the name (model) of your LCD panel -===================================================== +----------------------------------------------------- Get the panel name: @@ -254,7 +253,7 @@ removing the LCD panel is an option. Usually, there will be information printed on the back. e1000e driver trouble shooting (Intel NICs) -=========================================== +------------------------------------------- Example error, ¿may happen on weird and complex routing schemes(citation needed for cause): diff --git a/site/docs/uboot/index.md b/site/docs/uboot/index.md index e438603..72816c8 100644 --- a/site/docs/uboot/index.md +++ b/site/docs/uboot/index.md @@ -6,30 +6,20 @@ x-toc-enable: true **NOTE: This documentation refers only to ARM64. For AMD64/i386 (Intel/AMD) U-Boot setups, please read [uboot-x86.md](uboot-x86.md).** -Canoeboot has experimental support for using U-Boot as a coreboot -payload since the the project was launched, and on x86 since late 2024. - -U-Boot integration in Canoeboot is currently at a proof-of-concept -stage, with most boards completely untested and most likely not working. ROM images for them are mostly intended for further testing and development. If you have one of these machines and want to help fix things, you can ping `alpernebbi` on Libera IRC, who ported these boards to Canoeboot. -Make sure you have the latest `cbmk` from the Git repository, -and the build dependencies are installed like so, from `cbmk/` as root: - - ./mk dependencies debian - -This installs everything needed for `./mk -b coreboot`, and part of the -build process makes use of coreboot's own cross-compile toolchain. +Emulation +--------- [QEMU x86/ARM64 virtual machines](../misc/emulation.md) are also supported, which should be easy targets to start tinkering on if you want to contribute. Usage -===== +----- When your board is powered on, U-Boot will ideally turn on the display and start printing console messages there. After a countdown of a few @@ -63,7 +53,7 @@ table, unexpected parts of the SPI ROM image, or do something else entirely. Known issues -============ +------------ U-Boot integration in Canoeboot is incomplete. Here is a list of known issues that affect all boards: @@ -81,7 +71,8 @@ issues that affect all boards: - UEFI support is incomplete See also -======== +-------- + - [U-Boot documentation](https://u-boot.readthedocs.io/en/latest/) - [U-Boot documentation (unmigrated files)](https://source.denx.de/u-boot/u-boot/-/tree/master/doc) - [U-Boot and generic distro boot](https://marcin.juszkiewicz.com.pl/2021/03/14/u-boot-and-generic-distro-boot/) diff --git a/site/docs/uboot/uboot-archlinux.md b/site/docs/uboot/uboot-archlinux.md index d4d9375..0b23def 100644 --- a/site/docs/uboot/uboot-archlinux.md +++ b/site/docs/uboot/uboot-archlinux.md @@ -4,7 +4,7 @@ x-toc-enable: true ... Background -========== +---------- The following process should theoretically be applicable to other U-Boot devices and Linux distributions, but the focus here is specifically on ArchLinuxARM. @@ -16,7 +16,7 @@ And the the instructions from the ArchLinuxARM wiki [here](https://archlinuxarm. The purpose of this guide is to instruct users on how to install an ArchLinuxARM on an external disk that will boot on a gru_bob chromebook, and optionally on the internal eMMC. Many concepts covered in this guide may be familiar to prospective and veteran Canoeboot users, with the scope being comprehensive. Boot Method -=========== +----------- There are (at least) three methods that can be used to boot into a Linux distribution from u-boot: 1) EFI - common, modern boot method for amd64 architecture machines. This is not distribution-specific, so if you intend to make a portable drive that is compatible across multiple systems, you may have a use case. @@ -34,7 +34,7 @@ For more information about what actually goes into a boot.scr script, check [thi Since extlinux.conf is supported by multiple bootloaders, making your system more portable, is natively supported by u-boot, and requires no binary blobs or extra software, it seems to be the best choice for a chromebook. Creating extlinux.conf -====================== +---------------------- Here is an example template of extlinux.conf, [similar examples are found in the u-boot docs](https://u-boot.readthedocs.io/en/latest/develop/distro.html): @@ -44,7 +44,6 @@ menu title Libre-U-Boot menu prompt 0 timeout 50 - label arch menu label Arch Linux ARM linux /Image @@ -61,7 +60,7 @@ label archfallback ``` Formatting and Partitioning Your External Media -=============================================== +----------------------------------------------- Now it's time partition the boot disk. During testing, a microSD card was used in the microSD card slot of the gru-bob chromebook. The Canoeboot configuration will boot the microSD card above the onboard eMMC if both are present and bootable. This is useful because it means no knowledge or use of the u-boot console is required. @@ -73,10 +72,12 @@ Find your device with my favourite command, `lsblk` and open it with `fdisk` ``` fdisk /dev/sdX ``` + For users creating a bootable SD card, your device may show up as `/dev/mmcblkX` - if this is the case, make sure to change the commands in this guide to contain that path instead of `/dev/sdX`. In the fdisk tui, create two partitions on a Master Boot Record: + - create a new MBR label - create boot partition of approx. 200MB or greater - set bootable flag on this partition @@ -86,27 +87,32 @@ In the fdisk tui, create two partitions on a Master Boot Record: You will find the appropriate options by typing `m` when using the fdisk tui on Linux distros. Now make the filesystems: + ``` mkfs.vfat /dev/sdX1 mkfs.ext4 /dev/sdX2 - ``` It's now time to get the PARTUUID of `/dev/sdX2`: + ``` sudo blkid | grep "/dev/sdX2" ``` + make sure to note down the PARTUUID of your second partition; not your boot partition. paste this into your extlinux.conf file in the `append` section, e.g.: + ``` append console=ttyS0,115200 console=tty1 rw root=PARTUUID=fc0d0284-ca84-4194-bf8a-4b9da8d66908 ``` + in the template provided above, replace `$PARTUUID` with your own. It's possible to specify root in other ways - check the u-boot docs for more examples. Boot-Disk Creation -================== +------------------ Now that we've got an extlinux.conf file, copy it to your /tmp directory, and we'll begin. + ``` cd /tmp curl -LO http://os.archlinuxarm.org/os/ArchLinuxARM-aarch64-latest.tar.gz @@ -123,6 +129,7 @@ sync umount boot umount root ``` + Note the use of ArchLinuxARM-aarch64-latest.tar.gz and not ArchLinuxARM-gru-latest.tar.gz The current gru build only supports a depthcharge payload and, of course, we're not using depthcharge are we? @@ -133,7 +140,7 @@ Extensive testing with ArchLinuxARM-latest release, showed that booting the fall If you create an extlinux.conf file with paths to both images - like in the template above - you can select either by number at boot. Going Live - Necessary Tweaks -============================= +----------------------------- Once you're at the login prompt, the fun isn't over! Login & password for root are both `root` by default. Most Arch users will likely try to update their system now - don't update just yet. @@ -142,10 +149,12 @@ Run `lsblk` and you'll see that the boot partition is not mounted by default. Updating with `pacman -Syu` at this stage will cause driver problems if you update without your boot partition mounted, likely meaning you cannot connect to the internet with a USB peripheral. To prevent this becoming a problem: + ``` mkdir /boot mount /dev/sdX1 /boot ``` + With that out of the way, yes, you may now update. It's worth creating a basic filesystem table to automate mounting at boot - it's blank by default so here's another template: @@ -160,18 +169,22 @@ UUID=$UUID1 / ext4 rw,relatime 0 1 # /dev/mmcblk1p1 boot UUID=$UUID0 /boot vfat rw,relatime 0 2 ``` + It should go without saying that you'll replace `$UUID0` and `UUID1` with your boot and root filesystem UUID. To get the right information in there: + ``` lsblk -o NAME,UUID,FSTYPE,SIZE ``` + `NAME` and `SIZE` are not necessary, but they will help you tell which partition is which. Final Steps -=========== +----------- At this stage, you now have a fully functional ArchLinuxARM system on an external disk, and are ready to configure your system. If you intend to install onto the eMMC module, you can make your changes permanent with: + ``` dd if=/dev/mmcblk0 of=/dev/mmcblk1 bs=4M status=progress ``` diff --git a/site/docs/uboot/uboot-debian-bookworm.md b/site/docs/uboot/uboot-debian-bookworm.md index 6c06500..7541b9b 100644 --- a/site/docs/uboot/uboot-debian-bookworm.md +++ b/site/docs/uboot/uboot-debian-bookworm.md @@ -4,7 +4,7 @@ x-toc-enable: true ... System Configuration -==================== +-------------------- Hardware: Samsung Chromebook Plus XE513C24 (gru\_kevin) @@ -15,7 +15,7 @@ Operating System: Debian Bookworm RC2 [https://wiki.debian.org/Firmware](https://wiki.debian.org/Firmware) Install Media Preparation -========================= +------------------------- Follow the Debian installation instructions in the link below: @@ -26,16 +26,17 @@ page and I selected the DVD image to have all the packages available when offline (3.7 gigabyte iso). See the notes below about alternately using the netinst version. -[https://cdimage.debian.org/cdimage/bookworm_di_rc2/arm64/iso-dvd/](https://cdimage.debian.org/cdimage/bookworm_di_rc2/arm64/iso-dvd/) +[https://cdimage.debian.org/cdimage/bookworm\_di\_rc2/arm64/iso-dvd/](https://cdimage.debian.org/cdimage/bookworm_di_rc2/arm64/iso-dvd/) Write the iso file to a micro sdcard. Replace `sdcard_device` below with the appropriate device path on your system. + ``` # dd if=debian-bookworm-DI-rc2-arm64-DVD-1.img of=/dev/sdcard_device bs=1M status=progress; sync ``` Installation -============ +------------ 1. Insert the micro sdcard into the slot on the Chromebook. 2. Power on the Chromebook. @@ -149,7 +150,7 @@ internal emmc. ![](https://av.canoeboot.org/xe513c24/debbook-firefox.jpg) System Functionality -==================== +-------------------- Things that work: diff --git a/site/docs/uboot/uboot-openbsd.md b/site/docs/uboot/uboot-openbsd.md index 6d74bc2..3f2ddb9 100644 --- a/site/docs/uboot/uboot-openbsd.md +++ b/site/docs/uboot/uboot-openbsd.md @@ -4,7 +4,7 @@ x-toc-enable: true ... System Configuration -==================== +-------------------- Hardware: Samsung Chromebook Plus XE513C24 (gru\_kevin) @@ -13,7 +13,7 @@ Tested on [Libreboot 20230423](https://libreboot.org/news/libreboot20230423.html Operating System: OpenBSD 7.3 Install Media Preparation -========================= +------------------------- Follow the OpenBSD arm64 installation instructions in the link below: @@ -26,7 +26,7 @@ with the appropriate device path on your system. ``` Installation Attempt -==================== +-------------------- 1. Insert the micro sdcard into the slot on the Chromebook. 2. Power on the Chromebook. diff --git a/site/docs/uboot/uboot-x86.md b/site/docs/uboot/uboot-x86.md index e2a57d5..3a075d3 100644 --- a/site/docs/uboot/uboot-x86.md +++ b/site/docs/uboot/uboot-x86.md @@ -3,8 +3,8 @@ title: U-Boot payload (x86 specific) x-toc-enable: true ... -Introduction -============ +U-Boot UEFI on x86 +------------------ @@ -25,8 +25,7 @@ payload. It has several boot methods but the most interesting (in an x86 context) is UEFI. U-Boot provides a very sensible UEFI implementation that can reliably boot many Linux and BSD systems. -Availability ------------- +### Availability @@ -52,8 +51,7 @@ Here is an example of what it looks like on the boot menu: -Errors ------- +### Errors If you see error `-25` in the bootflow menu, it's because there's nothing installed that i t can use e.g. EFI bootloader such as GRUB. @@ -62,8 +60,7 @@ If you see error `-2` it's likely that you have tried to boot a USB drive automatically; sometimes you have to do it manually (see the section below about using the bootflow command manually, via `bootflow select`). -Boot Linux or BSD installer (USB) ---------------------------- +### Boot Linux/BSD installer (USB) Just stick your formatted USB stick in. U-Boot should detect it. Sometimes some USB flash drives are broken, because many of them violate specifications and @@ -84,8 +81,7 @@ After selecting the device, you can do: bootflow boot -Booting installed system ------------------------- +### Booting installed system It should just work. If all is well, it'll show the bootflow menu. Simply select your device. If you see error, perhaps try: @@ -93,10 +89,9 @@ select your device. If you see error, perhaps try: bootefi bootmgr Tested operating systems -======================== +------------------------ -Linux/BSD ---------- +### Linux/BSD Arch Linux, Debian Linux and OpenBSD have been tested. @@ -110,8 +105,7 @@ bootloader in the installed system). EFI-based GRUB menus like in the Debian installer seemed to work just fine, that is: setups that use the EFI framebuffer instead of a text console. -Windows -------- +### Windows Windows was tested, and doesn't work yet. Simon Glass maintains the x86 coreboot payload, and has informed me that he still has some work to do @@ -120,7 +114,7 @@ there. Obviously using Windows would be extremely unGNU, so we advise against it. SecureBoot -========== +---------- Supported by U-Boot, though U-Boot does not currently have a robust way of storing EFI variables, and Canoeboot disables SecureBoot by default. However, @@ -135,7 +129,7 @@ sense to Canoeboot's GRUB hardening setup, though the latter is more flexible, albeit not widely used by the mainstream, but it does work (I use it myself!). ThinkPad X60/T60 -================ +---------------- The 32-bit U-Boot payload is only useful for 32-bit setups, and 32-bit UEFI isn't really that common on x86; the 64-bit U-Boot payload is much more useful, @@ -172,7 +166,7 @@ interesting in the future, as more distros stop supporting BIOS-based methods, or where the latter may become untested in the future. Bugs -==== +---- Limited testing, at least as of 5 December 2024, but some issues that appeared included: @@ -192,7 +186,7 @@ but some don't very well; the GM45 machines work well, e.g. a ThinkPad X200 was tested. Mitigating instability -======================= +---------------------- U-Boot is not a primary payload on any board where it's enabled. It's instead chainloaded from SeaBIOS on 64-bit x86, and from GRUB on 32-bit x86. You select diff --git a/site/download.md b/site/download.md index 138d956..a345df8 100644 --- a/site/download.md +++ b/site/download.md @@ -1,5 +1,5 @@ --- -title: Downloads +title: Download Canoeboot x-toc-enable: true ... diff --git a/site/faq.md b/site/faq.md index 363ce07..1377dba 100644 --- a/site/faq.md +++ b/site/faq.md @@ -6,7 +6,7 @@ x-toc-enable: true AKA Frequently Questioned Answers Disable security before flashing -================================ +-------------------------------- Before internal flashing, you must first disable `/dev/mem` protections. Make sure to re-enable them after you're finished. @@ -14,20 +14,17 @@ sure to re-enable them after you're finished. See: [Disabling /dev/mem protection](docs/install/devmem.md) Important issues -================ +---------------- -How to compile Canoeboot from source ------------------------------------- +### How to compile Canoeboot from source Refer to the [cbmk build instructions](docs/build/). -How does the build system work? -------------------------------- +### How does the build system work? Refer to the [cbmk maintenance manual](docs/maintain/). -Do not use CH341A! ------------------- +### Do not use CH341A! This SPI flasher will damage your chip, and the mainboard that it is connected to. @@ -35,8 +32,7 @@ to. Read the notes about CH341A on [docs/install/spi.md](docs/install/spi.md) to learn more. -How Can I Help --------------- +### How Can I Help If you have a board supported in Canoeboot then please consider becoming a tester. @@ -44,8 +40,7 @@ Testing involves minimal effort and really helps out the project. See the [board maintainers documentation](/docs/maintain/testing.md) if you are interested in testing roms before they are released. -Uneven backlight on GM45 ThinkPads ----------------------------------- +### Uneven backlight on GM45 ThinkPads We don't know how to detect the correct PWM value to use in coreboot, so we just use the default one in coreboot which has @@ -54,8 +49,7 @@ this issue on some CCFL panels, but not LED panels. You can work around this in your distribution, by following the notes at [docs: backlight control](../docs/misc/#finetune-backlight-control-on-intel-gpus). -Dead ethernet port on X200/T400/X60/T60 ---------------------------------------- +### GM45 thinkpad ethernet port doesn't autoconnect This was observed on some systems using network-manager. This happens both on the original BIOS and in Canoeboot. It's a quirk in the @@ -71,8 +65,7 @@ On systemd-based distros, you might try: (the service name might be different for you, depending on your configuration) -KCMA-D8/KGPE-D16: doesn't boot with PIKE2008 ---------------------------------------- +### PIKE2008 module hangs KGPE-D16 / KCMA-D8 Loading the option ROM from the PIKE2008 module on either ASUS KCMA-D8 or KGPE-D16 causes the system to hang at boot. It's possible to use @@ -81,8 +74,7 @@ or to boot (with SeaGRUB and/or SeaBIOS) from regular SATA and then use it in Linux. The Linux kernel is capable of using the PIKE2008 module without loading the option ROM. -How to save kernel panic logs on thinkpad laptops? --------------------------------------------------- +### How to save kernel panic logs on thinkpad laptops? The easiest method of doing so is by using the kernel's netconsole and reproducing the panic. Netconsole requires two machines, the one that is @@ -147,23 +139,21 @@ the target (`target$`): 7. Try to reproduce the kernel panic. Hardware compatibility -====================== +---------------------- -What systems are compatible with Canoeboot? ------------------------------------------------------------------------------------ +### What systems are compatible with Canoeboot? Any system can easily be added, so *compatibility* merely refers to whatever boards are integrated in the `cbmk` build system, which Canoeboot uses. The [installation page](docs/install/) lists compatible machines. -Freedom pitfalls with modern Intel hardware {#intel} ----------------------------------------------------- +### Freedom pitfalls with modern Intel hardware {#intel} Coreboot is nominally Free Software, but requires binary blobs on most x86 targets that it supports, on both Intel and AMD. -### Intel Management Engine (ME) {#intelme} +#### Intel Management Engine (ME) {#intelme} NOTE: The information below is slightly out of date. Nowadays, Intel ME does not run on an ARC coprocessor, but instead runs on a modified Intel 486 based @@ -328,7 +318,11 @@ The book ***[Platform Embedded Security Technology Revealed](https://www.apress.com/9781430265719)*** describes in great detail the ME's hardware architecture and firmware application modules. -### Firmware Support Package (FSP) {#fsp} +If you're stuck with the ME (non-canoeboot system), you might find this +interesting: + + +#### Firmware Support Package (FSP) {#fsp} On all recent Intel systems, coreboot support has revolved around integrating a blob (for each system) called the *FSP* (firmware support @@ -342,7 +336,7 @@ Since the FSP is responsible for the early hardware initialization, that means it also handles SMM (System Management Mode). This is a special mode that operates below the operating system level. -### CPU microcode updates {#microcode} +#### CPU microcode updates {#microcode} The microcode configures logic gates in your CPU, to implement an instruction set architecture. Your CPU will already contain them, but it also supplies a @@ -365,8 +359,7 @@ The git repository for that project is here: Both the video and the repository give some further insight about CPU microcode. The way it works on AMD will be very similar to Intel. -Freedom pitfalls to consider on AMD hardware {#amd} ----------------------------------------------------------------------------- +### Freedom pitfalls to consider on AMD hardware {#amd} NOTE: Nowadays there's openSIL - it's AMD's attempt to provide some source code again, that projects like coreboot @@ -376,7 +369,7 @@ be "neutered" (nothing like `me_cleaner`, or *psp\_cleaner*) exists yet. AMD has more or less the same problem as Intel, when it comes to software freedom. -### AMD Platform Security Processor (PSP) +#### AMD Platform Security Processor (PSP) This is basically AMD's own version of the [Intel Management Engine](#intelme). It has all of the same basic security and freedom @@ -419,13 +412,13 @@ anecdotal reports indicate that AMD's boot guard counterpart will be used on most OEM hardware, disabled only on so-called "enthusiast" CPUs. -### AMD IMC firmware +#### AMD IMC firmware Read . NOTE: This section is oudated, and it is in need of cleanup. -### AMD SMU firmware +#### AMD SMU firmware NOTE: This section may be outdated, and it is in need of cleanup. @@ -443,7 +436,7 @@ and based on this work, Damien Zammit (another coreboot hacker) firmware, but on the relevant system (ASUS F2A85-M) there were still other such files present (Video BIOS, and others). -### AMD AGESA firmware +#### AMD AGESA firmware NOTE: More needs to be written about this, to reflect the current reality. The situation with AMD has evolved in recent years. The information on this FAQ @@ -455,29 +448,26 @@ project, releasing this as source code under a free license. In 2014, they stopped releasing source code and started releasing AGESA as binary blobs instead. This makes AGESA now equivalent to [Intel FSP](#fsp). -### AMD CPU microcode updates +#### AMD CPU microcode updates Read the Intel section practically the same, though it was found with much later hardware in AMD that you could run without microcode updates. It's unknown whether the updates are needed on all AMD boards (depends on CPU). -Hi, I have <insert random system here>, is it supported? --------------------------------------------------------------------------------------------------------- +### Hi, I have <insert random system here>, is it supported? If coreboot lacks support for your hardware, you must add support for it. Please consult the coreboot project for guidance. General questions -================= +----------------- -How do I install Canoeboot? -------------------------------------------------------- +### How do I install Canoeboot? See [installation guide](docs/install/) -How do I program an SPI flash chip? ---------------------------------------------------------------------------------- +### How do I program an SPI flash chip? Refer to:\ [Externally rewrite 25xx NOR flash via SPI protocol](docs/install/spi.md) @@ -485,8 +475,7 @@ Refer to:\ It's possible to use a 16-pin SOIC test clip on an 8-pin SOIC chip, if you align the pins properly. The connection is generally more sturdy. -How do I write-protect the flash chip? ----------------------------------------------------------------------------- +### How do I write-protect the flash chip? By default, there is no write-protection on a Canoeboot system. This is for usability reasons, because most people do not have easy access to an @@ -506,8 +495,7 @@ welcome to submit patches adding these instructions. TODO: Document PRx based flash protection on Intel platforms, and investigate other methods on AMD systems. -How do I change the BIOS settings? ------------------------------------------------------------------------- +### How do I change the BIOS settings? Most Canoeboot setups actually use the [GRUB payload](http://www.coreboot.org/GRUB2). More information about payloads @@ -541,8 +529,7 @@ To get a full list of available options, do this: This will change the default inside that ROM image, and then you can re-flash it. -How do I pad a ROM before flashing? --------------------------------------- +### How do I pad a ROM before flashing? It is advisable to simply use a larger ROM image. This section was written mostly for ASUS KCMA-D8 and KGPE-D16 mainboards, where previously we only @@ -581,8 +568,7 @@ padded 16MiB image do the following: With padding removed cbfstool will be able to operate on the image as usual. -Do I need a bootloader in my distro? ---------------------------------------------------------------------------------------------------- +### Do I need to install a bootloader when installing a distribution? Most Canoeboot setups integrate the GRUB bootloader already, as a *[payload](http://www.coreboot.org/Payloads)*. This means that the GRUB @@ -600,8 +586,7 @@ Nowadays, other payloads are also provided. If you're using the SeaBIOS payload, then the normal MBR bootsector is used on your HDD or SSD, like you would expect. So the above paragraphs only apply to the GRUB payload. -Do I need to re-flash when I re-install a distribution? -------------------------------------------------------------------------------------------- +### Do I need to re-flash when I re-install a distribution? Not anymore. Recent versions of Canoeboot (using the GRUB payload) will automatically switch to a GRUB configuration on the HDD or SSD, if it @@ -613,14 +598,38 @@ more information, see If you're using the SeaBIOS payload, it's even easier. It works just like you would expect. SeaBIOS implements a normal x86 BIOS interface. -What does a flash chip look like? ------------------------------------------------------------------ +### What does a flash chip look like? You can find photos of various chip types on the following page:\ [External 25xx NOR flashing guide](docs/install/spi.md) +### tlp + +You can install the `tlp` package and start that service. For example, on +Debian: + +``` +apt-get install tlp tlp-rdw +systemctl enable tlp +systemctl start tlp +``` + +Now read the manual: + +``` +man tlp-stat +``` + +As root, you can do: + +``` +tlp-stat -b +``` + +This will provide information about the battery. + What other firmware exists outside of Canoeboot? -================================================== +------------------------------------------------ ### External GPUs @@ -830,10 +839,9 @@ Use of ethernet or wifi is recommended, as opposed to mobile networks, as these are generally much safer. Operating Systems -================= +----------------- -Can I use Linux? --------------------------------------------------- +### Can I use Linux? Absolutely! It is well-tested in Canoeboot, and highly recommended. See [installing Linux](../docs/linux/grub_boot_installer.md) and @@ -842,15 +850,13 @@ Absolutely! It is well-tested in Canoeboot, and highly recommended. See Any recent distribution should work, as long as it uses KMS (kernel mode setting) for the graphics. -Fedora won't boot? (maybe Redhat/CentOS) ------------------------------------------------------------ +### Fedora won't boot? (may also be applicable to Redhat/CentOS) On Fedora, by default the grub.cfg tries to boot linux in 16-bit mode. You just have to modify Fedora's GRUB configuration. Refer to [the Linux page](docs/linux/). -Can I use BSD? ----------------------------------- +### Can I use BSD? Absolutely! The Canoeboot firmware has good support for FreeBSD, NetBSD and OpenBSD. Other systems are untested, but should work just fine. @@ -858,13 +864,49 @@ OpenBSD. Other systems are untested, but should work just fine. See: [docs/bsd/](docs/bsd/) -Are other operating systems compatible? -------------------------------------------------------------------- +### Windows?? + +Yes, you can use Windows 10 and 11. They are not officially supported and the +Canoeboot project recommends that you *avoid* this choice, because Windows is +proprietary software. What this means is that you do *not* have the freedom +to use, study, adapt and share the software in any reasonable way. You are +entirely at the mercy of Microsoft, whose motive is profit, as opposed to the +general advancement of computer science and the welfare of everyone. + +See: [What is Free Software?](https://writefreesoftware.org/learn) + +In addition to being proprietary software, Windows is known to be full of bugs, +including *backdoors*. When you *use* Windows, it will send information about +you to third parties, used for a variety of purposes such as advertising, but +it's quite possible that three-letter agencies may also receive your data if +you use Windows. + +For the sake of your freedom, you should never, ever use Windows. Use Linux or +BSD systems, which are well-supported. Anyway: + +[Video of Windows 10 booting up](https://yewtu.be/watch?v=BWq6XnWKQnM) + +[Video of Windows 11 booting up](https://yewtu.be/watch?v=OFHiMfVNNeA) + +Of note: Windows 11 officially requires at least TPM 1.2 to be supported, and +it requires use of UEFI SecureBoot. To bypass this requirement, MajorGeeks has +a guide, see: + +The person who tested this also stated that they were unable to perform an +in-place upgrade from 10 to 11, so they had to wipe the drive and perform a +clean (note: not clean, because Windows is full of NSA spyware) installation. + +In both cases, as shown above, the Windows operating system was booting from +SeaBIOS, with the coreboot framebuffer initialised at startup, on an Intel GPU +initialised via coreboot's *libgfxinit*, on November 2023 versions of Canoeboot. +We do not yet support booting with UEFI on x86 machines. + +### Are other operating systems compatible? Unknown. Perhaps so, but it's impossible to say without further testing. -What level of freedom does Canoeboot give me? -=================================================== +What level of software freedom does Canoeboot give me? +-------------------------------------------------- Canoeboot firmware provides host hardware initialisation inside ROM files, that can be written to NOR flash, but on many systems there exist @@ -908,7 +950,7 @@ exist, for example, the work done by Sam Zeloof and the Libre Silicon project: (Sam literally makes CPUs in his garage) Where can I learn more about electronics -========================================== +---------------------------------------- * Basics of soldering and rework by PACE Both series of videos are mandatory regardless of your soldering skill. diff --git a/site/faq.uk.md b/site/faq.uk.md index d9a0df7..226dc74 100644 --- a/site/faq.uk.md +++ b/site/faq.uk.md @@ -6,20 +6,17 @@ x-toc-enable: true Також відомо як Відповіді на часті питання Важливі питання -================ +--------------- -Як скомпілювати Canoeboot з джерельного коду ------------------------------------- +### Як скомпілювати Canoeboot з джерельного коду Зверніться до [інструкцій зі збірки cbmk](docs/build/). -Як працює система збірки? -------------------------------- +### Як працює система збірки? Зверніться до [посібника з обслуговування cbmk](docs/maintain/). -Не використовуйте CH341A! ------------------- +### Не використовуйте CH341A! Цей програматор SPI пошкодить ваш чіп і материнську плату, до якої він підключений. @@ -27,8 +24,7 @@ x-toc-enable: true Прочитайте примітки щодо CH341A на [docs/install/spi.md](docs/install/spi.md), щоб вивчити більше. -Flashprog скаржиться на доступ DEVMEM --------------------------------------- +### Flashprog скаржиться на доступ DEVMEM Якщо запущено `flashprog -p internal` для програмної перепрошивки та ви отримуєте помилку, пов'язану з доступом до /dev/mem, вам слід перезавантажити систему з @@ -48,8 +44,7 @@ Error accessing DMI Table, 0x1000 bytes at 0x000000007fb27000 /dev/mem mmap failed: Operation not permitted ``` -Підсвічування в лівій частині екрана стає темнішим ---------------------------------------------------------------------------------------------------------------- +### Підсвічування в лівій частині екрана стає темнішим Ми не знаємо, як визначити правильне значення ШІМ для використання в coreboot, тому ми просто використовуємо стандартне в coreboot, який має @@ -58,8 +53,7 @@ coreboot, тому ми просто використовуємо стандар Ви можете вирішити цю проблему у своєму дистрибутиві, дотримуючись приміток на [документація: контроль підсвічуванням](../docs/misc/#finetune-backlight-control-on-intel-gpus). -Ethernet не працює на моєму X200/T400/X60/T60, коли я його підключаю -------------------------------------------------------------------- +### Ethernet не працює на моєму X200/T400/X60/T60, коли я його підключаю Це спостерігалося в деяких системах, які використовують network-manager. Таке буває як в оригінальному BIOS, так і в Canoeboot. Це примха в @@ -75,8 +69,7 @@ Ethernet не працює на моєму X200/T400/X60/T60, коли я йог (назва служби може відрізнятися для вас, залежно від вашої конфігурації) -які слід враховувати на апаратному забезпеченні AMD ---------------------------------------------------- +### Мій KCMA-D8 або KGPE-D16 не завантажується з встановленим модулем PIKE2008 Завантаження Option ROM з модуля PIKE2008 на ASUS KCMA-D8 або KGPE-D16 викликає зависання системи під час завантаження. Можна використовувати @@ -85,8 +78,7 @@ Ethernet не працює на моєму X200/T400/X60/T60, коли я йог це в Linux. Ядро Linux здатне використовувати PIKE2008 модуль без завантаження Option ROM. -Як зберегти журнали паніки ядра на ноутбуках Thinkpad? --------------------------------------------------- +### Як зберегти журнали паніки ядра на ноутбуках Thinkpad? Найпростіший спосіб зробити це за допомогою netconsole ядра і відтворення паніки. Netconsole вимагає двох машин, тієї, що є @@ -151,23 +143,21 @@ Ethernet не працює на моєму X200/T400/X60/T60, коли я йог 7. Спробуйте відтворити паніку ядра. Апаратна сумісність -====================== +------------------- -Які системи сумісні з Canoeboot? ------------------------------------------------------------------------------------ +### Які системи сумісні з Canoeboot? Будь-яку систему можна легко додати, тому *сумісність* посилається до будь-якої інтегрованої до системи побудови `cbmk` плати, яку Canoeboot використовує. The [installation page](docs/install/) lists compatible machines. -Пастки свободи з сучасним обладнанням Intel {#intel} ----------------------------------------------------- +### Пастки свободи з сучасним обладнанням Intel {#intel} Coreboot номінально є вільним програмним забезпеченням, але для більшості x86 цілей, які він підтримує, потрібні двійкові блоби, як на Intel, так і на AMD. -### Intel Management Engine (ME) {#intelme} +#### Intel Management Engine (ME) {#intelme} ПРИМІТКА: Інформація нижче трохи застаріла. Зараз Intel ME не працює на співпроцесорі ARC, а працює на архітектурі модифікованого процесора Intel 486, @@ -328,7 +318,7 @@ wiki](http://www.coreboot.org/Intel_Management_Engine), та Revealed (Розкрито вбудовану технологію безпеки платформи)](https://www.apress.com/9781430265719)*** чудово описує в значних подробицях архітектуру апаратного забезпечення ME та прикладні модулі мікропрограми. -### Firmware Support Package (FSP) {#fsp} +#### Firmware Support Package (FSP) {#fsp} У всіх останніх системах Intel, підтримка coreboot обертається навколо інтеграції блоба (для кожної системи) під назвою *FSP* (Firmware Support Package, пакет підтримки @@ -347,7 +337,7 @@ Revealed (Розкрито вбудовану технологію безпек руткітів SMM було продемонстровано в природі (використайте пошукову систему, щоб знайти їх). -### Оновлення мікрокода ЦП {#microcode} +#### Оновлення мікрокода ЦП {#microcode} Мікрокод налаштовує логічні вентилі у вашому ЦП, щоб реалізувати архітектуру набору інструкцій. Ваш ЦП уже містить їх, але він також надає спосіб оновлення @@ -366,34 +356,12 @@ Revealed (Розкрито вбудовану технологію безпек І відео, і репозиторій дають деяку додаткову інформацію про мікрокод ЦП. Те, як це працює на AMD, буде дуже схожим на Intel. -### Intel не співпрацює - -Роками coreboot бореться з Intel. Виявилося, що Intel загалом -вкрай відмовляється від співпраці. Багато розробників coreboot -і компаній намагалися залучити Intel до співпраці; а саме, -випуск джерельного коду для компонентів мікропрограми. Навіть Google, що -продає мільйони *хромбуків* (з попередньо встановленим coreboot) не змогла їх -переконати. - -Навіть коли Intel співпрацює, вони все одно не надають джерельний код. -Вони можуть надавати обмежену інформацію (таблиці даних) відповідно до суворої -корпоративної NDA (угоди про нерозголошення), але навіть це не -гарантується. Навіть ODM та IBV не можуть отримати джерельний код від Intel, в -більшості випадків (вони просто інтегрують блоки, надані Intel). - -Новіші графічні чіпсети Intel [вимагають блобів -прошивки](https://01.org/linuxgraphics/intel-linux-graphics-firmwares?langredirect=1). - -Проект Canoeboot *надає* деяку підтримку для новіших платформ Intel, але -вам варто знати про ці проблемні питання, якщо ви вибираєте використовувати ці машини. - -Підводні камені свободи, які слід враховувати на апаратному забезпеченні AMD {#amd} ----------------------------------------------------------------------------- +### Підводні камені свободи, які слід враховувати на апаратному забезпеченні AMD {#amd} AMD має більш-менш ту саму проблему, що й Intel, коли справа стосується свободи програмного забезпечення. -### AMD Platform Security Processor (PSP) +#### AMD Platform Security Processor (PSP) По суті, це власна версія [Intel Management Engine](#intelme) від AMD. Він має ті самі базові проблеми безпеки та свободи, @@ -436,13 +404,13 @@ Management Engine), PSP від AMD також може діяти як тира на більшості апаратного забезпечення OEM, відключений лише на так званих процесорах "ентузіастів". -### Прошивка AMD IMC +#### Прошивка AMD IMC Прочитайте . ПРИМІТКА: Ця секція є застарілою, та потребує очищення. -### Прошивка AMD SMU +#### Прошивка AMD SMU ПРИМІТКА: Ця секція є застарілою, та потребує очищення. @@ -460,7 +428,7 @@ Management Engine), PSP від AMD також може діяти як тира прошивкою, але у відповідній системі (ASUS F2A85-M) все ще були присутні інші блоби (Відео BIOS та інші). -### Прошивка AMD AGESA +#### Прошивка AMD AGESA ПРИМІТКА: Більше має бути написано про це, щоб відобразити сучасну реальність. Ситуація з AMD в останні роки змінилась. Інформація на цій сторінці поширених @@ -472,14 +440,18 @@ Management Engine), PSP від AMD також може діяти як тира вони припинили випускати джерельний код і замість цього почали випускати AGESA у вигляді бінарних блобів. Це робить AGESA еквівалентом [Intel FSP](#fsp). -### Оновлення мікрокоду ЦП AMD +#### Оновлення мікрокоду ЦП AMD Прочитайте розділ Intel практично так само, хоча було виявлено, що з набагато пізнішим апаратним забезпеченням AMD можна працювати без оновлень мікрокоду. Невідомо, чи потрібні оновлення на всіх платах AMD (залежить від ЦП). -### AMD не співпрацює +Проект Canoeboot не розцінює оновлення мікрокоду проблемою, і він +вмикає їх за замовчуванням на всьому апаратному забезпеченні, +яке підтримується. + +#### AMD не співпрацює Здавалося, що AMD була на правильному шляху в 2011 році, коли вони почала співпрацювати та випускати джерельний код для кількох критичних @@ -506,22 +478,19 @@ Family 15h (на стороні AMD) або будь-яке інше, випущ Це також стосується викривачів або будь-кого, кому потрібна справжня конфіденційність та безпека. -<вставте сюди випадкову систему>, чи підтримується вона? --------------------------------------------------------------------------------------------------------- +### Привіт, у мене <вставте сюди випадкову систему>, чи підтримується вона? Якщо в coreboot бракує підтримки для вашого апаратного забезпечення, ви мусите додати підтримку для нього. Будь-ласка, проконсультуйтесь з проектом coreboot для наставництва. Загальні питання -================= +---------------- -Як встановити Canoeboot? -------------------------------------------------------- +### Як встановити Canoeboot? Подивіться [посібник з встановлення](docs/install/) -Як запрограмувати флеш-чіп SPI? ---------------------------------------------------------------------------------- +### Як запрограмувати флеш-чіп SPI? Зверніться до:\ [Зовнішній перезапис 25xx NOR flash через протокол SPI](docs/install/spi.md) @@ -529,8 +498,7 @@ Family 15h (на стороні AMD) або будь-яке інше, випущ Можна використовувати 16-контактний затискач SOIC на 8-контактній мікросхемі SOIC, якщо правильно впорядкувати контакти. Як правило, з'єднання більш міцне. -Як захистити флеш-чіп від запису? ----------------------------------------------------------------------------- +### Як захистити флеш-чіп від запису? За замовчуванням немає захисту від запису на системі Canoeboot. Це з міркувань зручності використання, оскільки більшість людей не мають легкого доступу до зовнішнього @@ -550,8 +518,7 @@ Family 15h (на стороні AMD) або будь-яке інше, випущ ЗРОБИТИ: Задокументувати захист флеш-пам'яті на основі PRx на платформах Intel і дослідити інші методи на системах AMD. -Як змінити налаштування BIOS? ------------------------------------------------------------------------- +### Як змінити налаштування BIOS? Більшість налаштувань Canoeboot насправді використовує [корисне навантаження GRUB](http://www.coreboot.org/GRUB2). Більше інформації про корисні навантаження @@ -585,8 +552,7 @@ coreboot вікі для більшої інформації. Це змінить за замовчуванням всередині образа ROM, і потім ви можете перепрошити його. -Як заповнити ROM перед перепрошивкою? --------------------------------------- +### Як заповнити ROM перед перепрошивкою? Бажано просто використовувати більший образ ROM. Цей розділ був написаний здебільшого для материнських плат ASUS KCMA-D8 та KGPE-D16, де раніше ми надавали @@ -625,8 +591,7 @@ ROM та флеш-чіпом. Випадок вище, наприклад: Після видалення заповнення cbfstool зможе працювати із образом як зазвичай. -Чи потрібно встановлювати завантажувач під час встановлення дистрибутива? ---------------------------------------------------------------------------------------------------- +### Чи потрібно встановлювати завантажувач під час встановлення дистрибутива? Більшість налаштувань Canoeboot уже інтегрують завантажувач GRUB як *[корисне навантаження](http://www.coreboot.org/Payloads)*. Це означає, що завантажувач GRUB @@ -644,8 +609,7 @@ HDD або SSD під час встановлення нового дистри тоді на вашому HDD або SSD використовується звичайний завантажувальний сектор MBR, як і слід було очікувати. Отже, наведені вище параграфи стосуються лише корисного навантаження GRUB. -Чи потрібно мені перепрошивати, коли я перевстановлю дистрибутив? -------------------------------------------------------------------------------------------- +### Чи потрібно мені перепрошивати, коли я перевстановлю дистрибутив? Більше ні. Останні версії Canoeboot (з використанням корисного навантаження GRUB) автоматично переключатимуться на конфігурацію GRUB на HDD або SSD, якщо @@ -657,16 +621,40 @@ GRUB (наприклад, флеш-накопичувач USB). Для Якщо ви використовуєте корисне навантаження SeaBIOS, це ще простіше. Це працює так, як ви очікували. SeaBIOS реалізує звичайний інтерфейс x86 BIOS. -Як виглядає флеш-чіп? ------------------------------------------------------------------ +### Як виглядає флеш-чіп? Ви можете знайти фотографії різних видів чипів на наступній сторінці:\ [Керівництво зовнішньої прошивки 25xx NOR](docs/install/spi.md) -Яке ще мікропрограмне забезпечення існує за межами Canoeboot? -================================================== +### tlp -### Зовнішні графічні карти +Ви можете встановити пакет `tlp` та розпочати той сервіс. Наприклад, на +Debian: + +``` +apt-get install tlp tlp-rdw +systemctl enable tlp +systemctl start tlp +``` + +Тепер прочитайте документацію: + +``` +man tlp-stat +``` + +Від імені root, ви можете зробити: + +``` +tlp-stat -b +``` + +Це надасть інформацію про батарею. + +Яке ще мікропрограмне забезпечення існує за межами Canoeboot? +------------------------------------------------------ + +#### Зовнішні графічні карти Відео BIOS наявний на більшості графічних карт. Для інтегрованої графіки VBIOS (спеціальний вид OptionROM) зазвичай вбудовано @@ -682,7 +670,7 @@ Canoeboot буде використовувати цей код, коли він В конфігураціях, де SeaBIOS і власна ініціалізація GPU використовуються разом, додається спеціальна прокладка VBIOS, яка використовує лінійний кадровий буфер coreboot. -### Прошивка EC (вбудований контролер) +#### Прошивка EC (вбудований контролер) Це є у більшості (всіх?) ноутбуків. EC (вбудований контролер) - це невеликий, окремий процесор, який в основному обробляє вхідні/вихідні дані, характерні @@ -702,7 +690,7 @@ Canoeboot буде використовувати цей код, коли він EC присутній ледь не на всіх ноутбуках. Інші пристрої використовують, залежно від складності, або EC, або варіант із прошивкою в Mask ROM - SuperIO. -### Прошивка HDD/SSD +#### Прошивка HDD/SSD Жорсткі диски та твердотільні накопичувачі містять вбудоване програмне забезпечення, призначене для обробки внутрішньої роботи пристрою, водночас відкриваючи простий, стандартний інтерфейс (наприклад, @@ -797,7 +785,6 @@ SATA через USB, і проект Canoeboot здатний завантажу звичайним чином. Проконсультуйтесь з документацією для вашої операційної системи Linux/BSD, щоб знати те, як встановити їх з *повнодисковим шифруванням*: - Поточна теорія (недоведена) полягає в тому, що це принаймні запобіжить зловмисним дискам неправильно маніпулювати даними, які зчитуються з диска або записуються на диск, оскільки він не може отримати доступ до вашого ключа LUKS, @@ -807,7 +794,7 @@ SATA через USB, і проект Canoeboot здатний завантажу **Сприймайте сказане в цьому абзаці з дрібкою солі. Це все ще обговорюється і нічого з цього не доведено.** -### NIC (контролер ethernet) +#### NIC (контролер ethernet) Мережеві карти Ethernet зазвичай запускають вбудоване програмне забезпечення, яке відповідає за внутрішню ініціалізацію пристрою. Теоретично його можна налаштувати @@ -816,19 +803,19 @@ SATA через USB, і проект Canoeboot здатний завантажу З належним IOMMU можна було би пом'якшити проблеми, пов'язані з DMA. Також можна використовувати мережевий адаптер USB, який не має DMA. -### Мікрокод процесора +#### Мікрокод процесора Мікрокод налаштовує масиви логічних вентилів у мікропроцесорі для реалізації архітектури набору інструкцій. Спеціальні *декодери* в мікропроцесорі налаштують схему на основі цього мікрокоду. -### Звукова карта +#### Звукова карта Звукове обладнання (інтегроване чи дискретне) зазвичай має вбудоване програмне забезпечення (DSP) для обробки введення/виведення. Знову ж таки, USB DAC є хорошим обхідним шляхом. -### Веб-камера +#### Веб-камера Веб-камери мають вбудоване програмне забезпечення, яке обробляє зображення, що вводиться в камеру; налаштування фокуса, балансу білого тощо. Можна використовувати апаратне забезпечення @@ -836,12 +823,12 @@ SATA через USB, і проект Canoeboot здатний завантажу (наприклад, на ноутбуках) не рекомендовані проектом Canoeboot з міркувань безпеки. -### Хост-контролер USB +#### Хост-контролер USB Хост-контролери USB потребують мікропрограми. Іноді це потрібно надати самому coreboot. -### Прошивка WWAN +#### Прошивка WWAN Деякі ноутбуки можуть мати пристрій для зчитування SIM-карт із карткою для роботи з WWAN, підключення до мережі 3g/4g (наприклад, GSM). Це та @@ -868,10 +855,9 @@ WWAN, підключення до мережі 3g/4g (наприклад, GSM). оскільки вони, як правило, набагато безпечніші. Операційні системи -================= +------------------ -Чи я можу використовувати Linux? --------------------------------------------------- +### Чи я можу використовувати Linux? Абсолютно! Він добре перевірений в Canoeboot, та дуже рекомендований. Подивіться [встановлення Linux](../docs/linux/grub_boot_installer.md) та @@ -880,15 +866,13 @@ WWAN, підключення до мережі 3g/4g (наприклад, GSM). Будь-який сучасний дистрибутив має працювати, допоки він використовує KMS (kernel mode setting) для графіки. -Fedora не завантажується? (також може бути застосовано до Redhat/CentOS) ------------------------------------------------------------ +### Fedora не завантажується? (також може бути застосовано до Redhat/CentOS) У Fedora типово grub.cfg намагається завантажити linux в 16-розрядному режимі. Вам просто потрібно змінити конфігурацію GRUB Fedora. Зверніться до [сторінки Linux](docs/linux/). -Чи я можу використовувати BSD? ----------------------------------- +### Чи я можу використовувати BSD? Абсолютно! Прошивка Canoeboot має добру підтримку для FreeBSD, NetBSD та OpenBSD. Інші системи не перевірені, але мають працювти нормально. @@ -896,13 +880,49 @@ OpenBSD. Інші системи не перевірені, але мають п Дивіться: [docs/bsd/](docs/bsd/index.uk.md) -Чи підтримуються інші операційні системи? -------------------------------------------------------------------- +### Windows?? + +Yes, you can use Windows 10 and 11. They are not officially supported and the +Canoeboot project recommends that you *avoid* this choice, because Windows is +proprietary software. What this means is that you do *not* have the freedom +to use, study, adapt and share the software in any reasonable way. You are +entirely at the mercy of Microsoft, whose motive is profit, as opposed to the +general advancement of computer science and the welfare of everyone. + +See: [What is Free Software?](https://writefreesoftware.org/learn) + +In addition to being proprietary software, Windows is known to be full of bugs, +including *backdoors*. When you *use* Windows, it will send information about +you to third parties, used for a variety of purposes such as advertising, but +it's quite possible that three-letter agencies may also receive your data if +you use Windows. + +For the sake of your freedom, you should never, ever use Windows. Use Linux or +BSD systems, which are well-supported. Anyway: + +[Video of Windows 10 booting up](https://yewtu.be/watch?v=BWq6XnWKQnM) + +[Video of Windows 11 booting up](https://yewtu.be/watch?v=OFHiMfVNNeA) + +Of note: Windows 11 officially requires at least TPM 1.2 to be supported, and +it requires use of UEFI SecureBoot. To bypass this requirement, MajorGeeks has +a guide, see: + +The person who tested this also stated that they were unable to perform an +in-place upgrade from 10 to 11, so they had to wipe the drive and perform a +clean (note: not clean, because Windows is full of NSA spyware) installation. + +In both cases, as shown above, the Windows operating system was booting from +SeaBIOS, with the coreboot framebuffer initialised at startup, on an Intel GPU +initialised via coreboot's *libgfxinit*, on November 2023 versions of Canoeboot. +We do not yet support booting with UEFI on x86 machines. + +### Чи підтримуються інші операційні системи? Невідомо. Можливо, але неможливо сказати без подальшого випробовування. Який рівень програмної свободи дає мені Canoeboot? -=================================================== +-------------------------------------------------- Прошивка Canoeboot надає ініціалізацію апаратного забезпечення хоста всередині файлів ROM, що може бути записано на флеш NOR, але на багатьох системах існує @@ -946,7 +966,7 @@ OpenBSD. Інші системи не перевірені, але мають п (Сем буквально робить процесори в своєму гаражі) Де я можу вивчати більше про електроніку -========================================== +---------------------------------------- * Основи пайки та переробки від PACE Обидві серії відео є обов'язковими незалежно від ваших навичок паяння. diff --git a/site/git.de.md b/site/git.de.md index cabc1d1..cb9b870 100644 --- a/site/git.de.md +++ b/site/git.de.md @@ -3,11 +3,8 @@ title: Code review x-toc-enable: true ... -If you wish to submit patches, you can. Submit them, using the instructions -provided in the following sections: - Canoeboot Repositories -=================== +--------------------- Informationen darüber wer an Canoeboot arbeitet und wer das Projekt betreibt sind unter [who.de.md](who.de.md) zu finden. @@ -22,8 +19,23 @@ Die Entwicklung von Canoeboot findet mithilfe der Versionskontrolle von Git statt. Sieh in der [offiziellen Git Dokumentation](https://git-scm.com/doc) nach, sofern Du nicht weisst wie man Git verwendet. -cbmk (canoeboot-make) ---------------------- +Das `bucts` Repository wird auch vom Canoeboot Projekt gehostet, da das +Original Repository auf `stuge.se` nicht mehr verfügbar ist, seit wie dies +zuletzt geprüft haben. Das `bucts` Programm wurde von Peter Stuge geschrieben. +Du benötigst `bucts` sofern Du ein Canoeboot ROM intern auf ein Thinkpad X60 +oder T60 flashen möchtest, welches (derzeit) noch ein nicht-freies Lenovo +BIOS verwendet. Anleitungen hierfür findest Du hier:\ +[Canoeboot Installations Anleitungen](docs/install/) + +Das `ich9utils` Repository wird erheblich vom `cbmk` build system verwendet. +Du kannst `ich9utils` allerdings auch separat herunterladen und verwenden. +Es erzeugt ICH9M descriptor+GbE Images für GM45 ThinkPads welche die ICH9M +Southbridge verwenden. Es könnte auch für andere Systeme funktionieren, +welche dieselbe Platform bzw. denselben Chipsatz verwenden. +Dokumentation für `ich9utils` ist hier verfügbar:\ +[ich9utils Dokumentation](docs/install/ich9utils.md) + +### cbmk (canoeboot-make) Dies ist das zentrale build system in Canoeboot. Man könnte auch sagen `cbmk` *ist* Canoeboot! Das Git repository herunterladen: @@ -42,8 +54,7 @@ Für Anleitungen bzgl. `cbmk` build, siehe [build Anleitungen](docs/build/). Informationen über das build system selbst und wie es funktioniert, sind verfügbar unter dem [cbmk maintenance guide](docs/maintain/). -cbwww and cbwww-img -------------------- +### cbwww and cbwww-img Die *gesamte* Canoeboot Website sowie Dokumentation befindet sich in einem Git Repository. @@ -112,8 +123,7 @@ Repository dorthin. Konfiguriere deinen lokalen HTTP Server entsprechend. Nochmal, Anleitungen hierfür findest Du auf der Untitled Webseite. -Name nicht erforderlich ------------------ +### Name nicht erforderlich Beiträge die Du hinzufügst, werden in einem für jeden zugänglichen Git Repository öffentlich aufgezeichnet. Dies betrifft ebenso den Namen sowie @@ -141,8 +151,37 @@ Commits/Patches verwendest dann solltest Du anonym sein. Verwende und [git show](https://git-scm.com/docs/git-show) um dies zu überprüfen bevor Du einem öffentlichen Git Repository Änderungen hinzufügst. -Patches senden ------------- +### Lizenzen (für Mitwirkende) + +Stelle sicher, dass deine Beiträge mit einer libre Lizenz frei lizensiert +sind. Canoeboot schreibt nicht mehr vor, welche Lizenzen akzeptiert werden, +und es existieren einige Lizenzen. Wir werden deinen Beitrag prüfen und +dir mitteilen sofern es ein Problem damit gibt (z.B. keine Lizenz). + +Gib *immer* eine Lizenz an für deine Arbeit! Keine Lizenz anzugeben bedeutet +das deine Arbeit unter die Standard Urheberrechte fällt, was deine Arbeit +proprietär macht und somit von denselben Einschränkungen betroffen ist. + +Die MIT Lizenz ist ein guter Start, und sie ist die bevorzugte Lizenz +für sämtliche Arbeit an Canoeboot, aber wir sind nicht pingelig. Canoeboot +hat in der Vergangenheit GNU Lizenzen so wie GPL verwendet; vieles davon +besteht nach wie vor und wird auch weiterhin bestehen. +Es ist deine Arbeit; sofern deine Arbeit auf der Arbeit eines anderen basiert, +ist es aufgrund der Lizenz-Kompatibilität ggfs. naheliegend diesselbe Lizenz zu +verwenden. + +[Hier](https://opensource.org/licenses) findest Du übliche Beispiele für Lizenzen. + +*Wenn* deine Arbeit auf bestehender Arbeit basiert, dann ist es wichtig +(für deinen Beitrag) das die Lizenz deiner Arbeit kompatibel ist mit der +Lizenz der Arbeit auf der sie beruht. Die MIT Lizenz ist hierfür gut geeignet, +weil sie mit vielen anderen Lizenen kompatibel ist, und Freiheit zulässt +(wie zum Beispiel die Freiheit einer SubLizenz) was bei vielen anderen +Lizenzen nicht der Fall ist: + + + +### Patches senden Erstelle einen Account unter und navigiere (während Du eingeloggt bist) zu dem Repository das Du bearbeiten möchtest. Klicke @@ -173,9 +212,6 @@ Ein weiterer Weg Patches zu senden ist Leah Rowe direkt eine email zu senden: Um den Prozess der Quelltext Überprüfung transparent zu gestalten, wird jedoch empfohlen künftig Codeberg zu verwenden. -Git mirrors -=========== - Mirrors für cbmk.git -------------------- @@ -193,8 +229,12 @@ angeklickt werden, um Änderungen in deinem Web Browser anzusehen): * * -cbwww.git Mirror ----------------- +Mirrors fur pico-serprog.git +---------------------------- + +* + +### cbwww.git Mirror Das `cbwww` Repository enthält Markdown Dateien (Pandoc Variant), für die Verwendung mit dem [Untitled Static Site Generator](https://untitled.vimuser.org/); @@ -215,9 +255,6 @@ anklicken um Änderungen in deinem Web Browser anzusehen). Siehe: cbwww-img.git Mirror ---------------- -Du kannst `git clone` für diese Links ausführen und/oder die Links -anklicken um Änderungen in deinem Web Browser anzusehen). Siehe: - * * * diff --git a/site/git.md b/site/git.md index 0bb3c24..f31853a 100644 --- a/site/git.md +++ b/site/git.md @@ -3,11 +3,8 @@ title: Code review x-toc-enable: true ... -If you wish to submit patches, you can. Submit them, using the instructions -provided in the following sections: - Canoeboot repositories -=================== +---------------------- Information about who works on canoeboot and who runs the project can be found on [who.md](who.md) @@ -22,8 +19,14 @@ Development of canoeboot is done using the Git version control system. Refer to the [official Git documentation](https://git-scm.com/doc) if you don't know how to use Git. -cbmk (canoeboot-make) ---------------------- +The `bucts` repository is hosted by the Canoeboot project, because the original +repository on `stuge.se` is no longer available, last time we checked. The +`bucts` program was written by Peter Stuge. You need `bucts` if you're flashing +internally an Canoeboot ROM onto a ThinkPad X60 or T60 that is currently running +the original Lenovo BIOS. Instructions for that are available here:\ +[Canoeboot installation guides](docs/install/) + +### cbmk (canoeboot-make) This is the core build system in canoeboot. You could say that `cbmk` *is* canoeboot! Download the Git repository: @@ -41,8 +44,7 @@ build `cbmk`, refer to the [build instructions](docs/build/). Information about the build system itself, and how it works, is available in the [cbmk maintenance guide](docs/maintain/). -cbwww and cbwww-img -------------------- +### cbwww and cbwww-img The *entire* canoeboot website and documentation is hosted in a Git repository. Download it like so: @@ -107,8 +109,7 @@ repository there. Configure your local HTTP server accordingly. Again, instructions are available on the Untitled website for this purpose. -Name not required ------------------ +### Name not required Contributions that you make are publicly recorded, in a Git repository which everyone can access. This includes the name and email address of the @@ -133,8 +134,36 @@ should be fairly anonymous. Use and [git show](https://git-scm.com/docs/git-show) to confirm that before you push changes to a public Git repository. -Send patches ------------- +### Licenses (for contributors) + +Make sure to freely license your work, under a libre license. Canoeboot no +longer sets arbitrary restrictions on what licenses are accepted, and many +licenses out there already exist. We will audit your contribution and tell +you if there are problems with it (e.g. no license). + +*Always* declare a license on your work! Not declaring a license means that +the default, restrictive copyright laws apply, which would make your work +proprietary, subject to all of the same restrictions. + +The MIT license is a good one to start with, and it is the preferred license +for all new works in Canoeboot, but we're not picky. Canoeboot has historically +used mostly GPL licensing; much of that remains, and is likely to remain. +It's your work; obviously, if you're deriving from an existing work, +it may make sense to use the same license on your contribution, for license +compatibility. + +You can find common examples of licenses +[here](https://opensource.org/licenses). + +If you *are* deriving from an existing work, it's important that your license +(for your contribution) be compatible with the licensing of the work from which +yours was derived. The MIT license is good because it's widely compatible +with many other licenses, and permits many freedoms (such as the freedom to +sublicense) that other licenses do not: + + + +### Send patches Make an account on and navigate (while logged in) to the repository that you wish to work on. Click *Fork* and in your account, @@ -160,9 +189,6 @@ Another way to submit patches is to email Leah Rowe directly: However, for transparency of the code review process, it's recommended that you use Codeberg, for the time being. -Git mirrors -=========== - Mirrors of cbmk.git ------------------- @@ -180,8 +206,12 @@ to view changes in your Web browser): * * -cbwww.git mirror ----------------- +Mirrors of pico-serprog.git +-------------------------- + +* + +### cbwww.git mirror The `cbwww` repository contains Markdown files (pandoc variant), for use with the [Untitled Static Site Generator](https://untitled.vimuser.org/); this @@ -202,9 +232,6 @@ Web browser. See: cbwww-img.git mirror ---------------- -You can run `git clone` on these links, and/or click to view changes in your -Web browser. See: - * * * diff --git a/site/git.uk.md b/site/git.uk.md index 7d5aea9..fac5d89 100644 --- a/site/git.uk.md +++ b/site/git.uk.md @@ -7,7 +7,7 @@ If you wish to submit patches, you can. Submit them, using the instructions provided in the following sections: репозиторії Canoeboot -=================== +-------------------- Інформацію про те, хто працює над canoeboot і хто керує проектом, можна знайти на [who.uk.md](who.uk.md) @@ -22,8 +22,7 @@ provided in the following sections: Зверніться до [офіційної документації Git](https://git-scm.com/doc), якщо ви не знаєте, як користуватися Git. -cbmk (canoeboot-make) ---------------------- +### cbmk (canoeboot-make) Це основна система збирання в canoeboot. Можна сказати, що `cbmk` *це* canoeboot! Завантажте репозиторій Git: @@ -41,8 +40,7 @@ canoeboot! Завантажте репозиторій Git: Інформація про саму систему збірки та про те, як вона працює, доступна в [посібнику обслуговування cbmk](docs/maintain/). -cbwww та cbwww-img -------------------- +### cbwww та cbwww-img *Весь* веб-сайт і документація canoeboot розміщені в репозиторії Git. Завантажте так: @@ -107,8 +105,7 @@ Untitled. Знову ж таки, інструкції для цього доступні на веб-сайті Untitled. -Ім'я не вимагається ------------------ +#### Ім'я не вимагається Внески, які ви робите, реєструються публічно в репозиторії Git, доступ до якого мають всі. Це включає ім'я та електронну адресу @@ -133,8 +130,7 @@ Untitled. та [git show](https://git-scm.com/docs/git-show), щоб підтвердити це перед тим, як ви надсилаєте зміни до загальнодоступного сховища Git. -Надсилайте виправлення ------------- +### Надсилайте виправлення Створіть обліковий запис на і перейдіть (увійшовши в систему) до репозиторію, над яким ви хочете працювати. Натисніть *Fork*, і у вашому обліковому записі, @@ -161,10 +157,9 @@ IRC-канал canoeboot і повідомити канал, які виправ використовувати Codeberg. Дзеркала Git -============ +------------ -Дзеркала cbmk.git ----------------- +### Дзеркала cbmk.git Репозиторій `cbmk` містить автоматизовану систему побудови Canoeboot, що створює випуски Canoeboot (включаючи зібрані образи ROM). @@ -180,8 +175,7 @@ IRC-канал canoeboot і повідомити канал, які виправ * * -дзеркало cbwww.git ----------------- +### дзеркало cbwww.git Репозиторій `cbwww` містить файли Markdown (варіант pandoc), для використання з [генератором статичних сайтів Untitled](https://untitled.vimuser.org/); це те, @@ -199,8 +193,7 @@ IRC-канал canoeboot і повідомити канал, які виправ * * -дзеркало cbwww-img.git ----------------- +### дзеркало cbwww-img.git Ви можете виконати `git clone` на цих посиланнях, та/або натиснути для перегляду змін в вашому веб-браузері. Дивіться: diff --git a/site/index.md b/site/index.md index 5f2aba1..6b88be4 100644 --- a/site/index.md +++ b/site/index.md @@ -42,7 +42,7 @@ you continue to use your hardware, with continued firmware updates. All of this is *why* Canoeboot exists. Overview of Canoeboot design -============================ +---------------------------- @@ -70,7 +70,7 @@ Canoeboot, coreboot would be inaccessible for most users; you can also still [reconfigure](docs/maintain/) Canoeboot however you wish. Why use Canoeboot? -================== +------------------ @@ -84,7 +84,7 @@ whereas Canoeboot is specifically crafted for end users. In other words, the purpose of Canoeboot is to *Just Work*. Direct configuration and installation of coreboot is also possible, but Canoeboot makes it *much* easier. -Canoeboot gives you [freedoms](https://writefreesoftware.org/) that +Canoeboot gives you [Free Software](https://writefreesoftware.org/) that you otherwise can't get with most other boot firmware, plus faster boot speeds and [better security](docs/linux/grub_hardening.md). It's extremely powerful and [configurable](docs/maintain/) for many use cases. If you're unhappy with @@ -119,7 +119,7 @@ over your own property (your computer), and so, we make it our mission to help you [wrest](https://trmm.net/TOCTOU/) back such control. Canoeboot is not a fork of coreboot -=================================== +----------------------------------- @@ -146,8 +146,7 @@ knowledge or skill except the ability to follow [simplified instructions, written for non-technical users](docs/install/). -How to help Canoeboot -===================== +### How to help Canoeboot The [Libreboot tasks page](https://libreboot.org/tasks/) lists tasks that could (will) be worked on. It will be updated over time as more tasks are @@ -212,8 +211,7 @@ you can send patches. Any and all development discussion and user support are all done on the IRC channel. More information is on the [contact page](contact.md). -Translations needed, for canoeboot.org --------------------------------------- +### Translations needed, for canoeboot.org If you want to help with translations, you can translate pages, update existing translations and submit your translated versions. For instructions, please diff --git a/site/news/audit1.md b/site/news/audit1.md index 9d2e16c..02977a5 100644 --- a/site/news/audit1.md +++ b/site/news/audit1.md @@ -10,7 +10,7 @@ published on 12 June 2024; nonetheless, the article date is set to June 9th. For changes up to June 12th, please read the Canoeboot 20240612 announcement. Introduction -============ +------------ Canoeboot is a free/libre boot firmware project. It replaces your proprietary BIOS/UEFI firmware, on supported x86 and ARM computers. It does @@ -51,8 +51,7 @@ one as the *first* official Canoeboot Build System Audit, or *audit 1*. ALSO: Canoeboot 20240510 was released *during* the audit; this changelog is in reference to Canoeboot 20240504, *not* 20240510. -Modest code size reduction --------------------------- +### Modest code size reduction There are 1054 lines of shell script in the build system, versus 1208 in the Canoeboot 20240504 release. Canoeboot's build system is written purely in @@ -62,12 +61,11 @@ This is a difference of 154 lines, or a 13% reduction. Despite the reduction, numerous features have been added and a large number of bugs were fixed. Summarised list of changes -========================== +-------------------------- Changes are in order per category, from newest to oldest: -Feature changes ---------------- +### Feature changes * **Download crossgcc tarballs as dependencies, when cloning coreboot.** We previously relied on the coreboot build system, which automatically fetches @@ -191,8 +189,7 @@ Feature changes * Removed all status checks from script/roms (formerly script/build/roms), because it's better to document this instead, and rely on testing regardless. -Bug fixes ---------- +### Bug fixes Some of these changes fix actual issues that were found in testing, while others were fixed *before* being triggered/reported and are thus *preventative @@ -405,8 +402,7 @@ The changes are, from newest to earliest: * Main build script: exit (with error status) if not running directly from the root of the cbmk work directory. -General code cleanup --------------------- +### General code cleanup In addition to *general* very sweeping code cleanup, condensing code lines where possible and so on: @@ -523,13 +519,12 @@ where possible and so on: * script/build/roms: split up `main()` into multiple smaller functions Revision updates -================ +---------------- Some revisions were updated as part of standard routine, but happened to be done during this audit. Those updates are as follows: -SeaBIOS -------- +### SeaBIOS Bump SeaBIOS to revision `e5f2e4c69643bc3cd385306a9e5d29e11578148c`, which has these changes relative to the old one: @@ -559,8 +554,7 @@ these changes relative to the old one: * a6ed6b70 limit address space used for pci devices. ``` -Flashprog ---------- +### Flashprog Updated to revision 5b4fdd1 from 2 May 2024, rebasing the MX workaround patch. @@ -631,7 +625,7 @@ Flashrom, lead by Nico Huber after a dispute with the new leadership of Flashrom, and it was felt that Flashprog is a better choice for Canoeboot. Git log -======= +------- This entire set of changelogs is based on the precise Git history in cbmk, relative to Canoeboot 20240504 which is from where the audit began. diff --git a/site/news/audit2.md b/site/news/audit2.md index c08722b..5d821fd 100644 --- a/site/news/audit2.md +++ b/site/news/audit2.md @@ -5,8 +5,8 @@ Heavy amount of code reduction in this audit, and general cleanup. A new Canoeboot release is planned, for the early days of August 2024. -Introduction -============ +Free as in freedom! +-------------------- Canoeboot is a free/opensource boot firmware project. It replaces your proprietary BIOS/UEFI firmware, on supported x86 and ARM computers. It does diff --git a/site/news/canoeboot20231026.md b/site/news/canoeboot20231026.md index b6fecd0..e0f7a50 100644 --- a/site/news/canoeboot20231026.md +++ b/site/news/canoeboot20231026.md @@ -7,8 +7,8 @@ a de-blobbed configuration on *fewer mainboards*; Libreboot supports more hardware, and much newer hardware. More information can be found on Canoeboot's [about](../about.html) page and by reading Libreboot's [Binary Blob Reduction Policy](https://libreboot.org/news/policy.html). -Introduction -============ +Open source BIOS/UEFI firmware +----------------------------- *This* new release, Canoeboot 20231026, released today 26 October 2023, is based on [Libreboot 20231021](https://libreboot.org/news/libreboot20231021.html). @@ -44,7 +44,7 @@ Libreboot supports *a lot more hardware*, but Canoeboot is provided for the purists out there who are OK using slightly older hardware as a result. Work done since last release -============================ +---------------------------- Canoeboot is a *special fork* of Libreboot, maintained in parallel by the Canoeboot [removes all binary blobs](policy.md) from coreboot, unlike @@ -60,8 +60,7 @@ things like memory controller initialisation. Canoeboot is provided for purists who only want free software; it even removes CPU microcode updates, regardless of the negative impact this has on system stability. -GRUB LUKS2 now supported (with argon2 key derivation) ---------------------------------------------------- +### GRUB LUKS2 now supported (with argon2 key derivation) *This* new Canoeboot release imports the [PHC argon2 implementation](https://github.com/P-H-C/phc-winner-argon2) into GRUB, @@ -84,15 +83,13 @@ 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! -Simplified commands (build system) -------------------------- +### Simplified commands (build system) You can find information about *using* the build system in the [Canoeboot build instructions](../docs/build/) and in the [cbmk maintenance manual](../docs/maintain/). -TWO massive audits. 50% code size reduction in cbmk. --------------------------------------------- +### TWO massive audits. 50% code size reduction in cbmk. Canoeboot's build system, cbmk, is written entirely in shell scripts. It is an automatic build system that downloads, patches, configures and compiles @@ -109,8 +106,7 @@ 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. -Serprog firmware building (RP2040 and STM32) ------------------------------------ +### Serprog firmware building (RP2040 and STM32) In addition to coreboot firmware, the Canoeboot build system (cbmk) can now build *serprog* firmware, specifically `pico-serprog` and `stm32-vserprog`, on @@ -124,8 +120,7 @@ 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. -Updated U-Boot revision (2023.10) ----------------------------- +### Updated U-Boot revision (2023.10) Alper Nebi Yasak submitted patches that update the U-Boot revision in Libreboot, on `gru_bob` and `gru_kevin` chromebooks. Additionally, the `cros` @@ -152,8 +147,7 @@ reading these diffs: All of these patches have been ported to this Canoeboot release. -Coreboot, GRUB, U-Boot and SeaBIOS revisions ------------------------------------- +### Coreboot, GRUB, U-Boot and SeaBIOS revisions In Canoeboot 20231026 (*this release*): @@ -165,10 +159,9 @@ In Canoeboot 20231026 (*this release*): * U-Boot: commit ID `4459ed60cb1e0562bc5b40405e2b4b9bbf766d57`, 2 October 2023 Build system tweaks -=================== +------------------- -resources/ now config/ ----------------------- +### resources/ now config/ The `resources/scripts/` directory is now `script/`, and what was `resources/` now only contains configuration data plus code patches for various projects, @@ -181,8 +174,7 @@ 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. -Full list of changes (detail) --------------------- +### Full list of changes (detail) These changes have been ported from the Libreboot 20231021 release, which are mostly the results of the two audits (mentioned above): @@ -443,7 +435,7 @@ mostly the results of the two audits (mentioned above): not cleanly handle `/tmp` at all, but now it's pretty reliable. Hardware supported in this release -================================== +---------------------------------- All of the following are believed to *boot*, but if you have any issues, please contact the Canoeboot project. They are: @@ -453,8 +445,7 @@ please contact the Canoeboot project. They are: - [ASUS KFSN4-DRE motherboard](../docs/hardware/kfsn4-dre.md) - [ASUS KGPE-D16 motherboard](../docs/hardware/kgpe-d16.md) -Desktops (AMD, Intel, x86) ------------------------ +### Desktops (AMD, Intel, x86) - [Gigabyte GA-G41M-ES2L motherboard](../docs/hardware/ga-g41m-es2l.md) - [Acer G43T-AM3](../docs/hardware/acer_g43t-am3.md) @@ -483,14 +474,14 @@ Desktops (AMD, Intel, x86) - [Samsung Chromebook Plus (v1) (gru-kevin)](../docs/install/chromebooks.md) Downloads -========= +--------- 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. Special changes -=============== +--------------- Besides deblobbing, there are two critical differences in how Canoeboot's build system works in this release, versus the Libreboot 20231021 build system: @@ -515,7 +506,7 @@ with). The build system in Canoeboot 20231026 is *[extremely efficient](../docs/maintain/)*. Backports -========= +-------- In addition to the Libreboot 20231021 changes, the following Libreboot patches were backported into this Canoeboot release, from Libreboot revisions pushed @@ -532,7 +523,7 @@ after the Libreboot 20231021 release came out: * Excluded mainboards -=================== +------------------- The following boards are *missing* in Canoeboot 20231026, but are supported in the Libreboot 20231021 release: @@ -558,7 +549,7 @@ the Libreboot 20231021 release: * Lenovo ThinkPad X230/X230T Post-release errata -=================== +------------------- The following binary blobs were overlooked, and are still present in the release archive for Canoeboot 20231101 and 20231026; this mistake was @@ -598,8 +589,7 @@ people know of the above issue. You are advised, therefore, to use the [Canoeboot 20231103 release](canoeboot20231103.md). -Update on 12 November 2023: ---------------------------- +### Update on 12 November 2023: This file was also overlooked, and is still present in the release tarball: diff --git a/site/news/canoeboot20231101.md b/site/news/canoeboot20231101.md index 0dd4dad..ddd236b 100644 --- a/site/news/canoeboot20231101.md +++ b/site/news/canoeboot20231101.md @@ -7,8 +7,8 @@ a de-blobbed configuration on *fewer mainboards*; Libreboot supports more hardware, and much newer hardware. More information can be found on Canoeboot's [about](../about.html) page and by reading Libreboot's [Binary Blob Reduction Policy](https://libreboot.org/news/policy.html). -Introduction -============ +Open source BIOS/UEFI firmware +--------------------------- *This* new release, Canoeboot 20231101, released today 1 November 2023, is based on the [Libreboot 20231101](https://libreboot.org/news/libreboot20231101.html) release, porting changes in it on top of @@ -46,15 +46,14 @@ Libreboot supports *a lot more hardware*, but Canoeboot is provided for the purists out there who are OK using slightly older hardware as a result. Work done since last release -============================ +--------------------------- This changelog is based on the Libreboot 20231101 changelog; changes from Libreboot 20231101 that are suitable for Canoeboot have been included in this release, and so, this changelog has been modified (based on the Libreboot one): -Coreboot, GRUB, U-Boot and SeaBIOS revisions ------------------------------------- +### Coreboot, GRUB, U-Boot and SeaBIOS revisions Canoeboot 20231026 and 20231101 are both based on these revisions: @@ -69,7 +68,7 @@ of these, that fix certain bugs or improve certain functionalities. More information is available elsewhere in this page. Build system tweaks -=================== +------------------ These changes were made: @@ -105,7 +104,7 @@ This is only about 1 week's worth of changes; this Canoeboot release is largely a bugfix release. Hardware supported in this release -================================== +--------------------------------- All of the following are believed to *boot*, but if you have any issues, please contact the Canoeboot project. They are: @@ -115,8 +114,7 @@ please contact the Canoeboot project. They are: - [ASUS KFSN4-DRE motherboard](../docs/hardware/kfsn4-dre.md) - [ASUS KGPE-D16 motherboard](../docs/hardware/kgpe-d16.md) -Desktops (AMD, Intel, x86) ------------------------ +### Desktops (AMD, Intel, x86) - [Gigabyte GA-G41M-ES2L motherboard](../docs/hardware/ga-g41m-es2l.md) - [Acer G43T-AM3](../docs/hardware/acer_g43t-am3.md) @@ -146,14 +144,14 @@ Desktops (AMD, Intel, x86) - [Samsung Chromebook Plus (v1) (gru-kevin)](../docs/install/chromebooks.md) Downloads -========= +--------- 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. Post-release errata -=================== +------------------- The following binary blobs were overlooked, and are still present in the release archive for Canoeboot 20231101 and 20231026; this mistake was @@ -193,8 +191,7 @@ people know of the above issue. You are advised, therefore, to use the [Canoeboot 20231103 release](canoeboot20231103.md). -Update on 12 November 2023: ---------------------------- +### Update on 12 November 2023: This file was also overlooked, and is still present in the release tarball: diff --git a/site/news/canoeboot20231103.md b/site/news/canoeboot20231103.md index 3bfee55..1d42d2d 100644 --- a/site/news/canoeboot20231103.md +++ b/site/news/canoeboot20231103.md @@ -7,8 +7,8 @@ a de-blobbed configuration on *fewer mainboards*; Libreboot supports more hardware, and much newer hardware. More information can be found on Canoeboot's [about](../about.html) page and by reading Libreboot's [Binary Blob Reduction Policy](https://libreboot.org/news/policy.html). -Introduction -============ +Open source BIOS/UEFI firmware +---------------------------- *This* new release, Canoeboot 20231103, released today 3 November 2023, is based on the [Canoeboot 20231101](https://canoeboot.org/news/canoeboot20231101.html) @@ -47,7 +47,7 @@ Libreboot supports *a lot more hardware*, but Canoeboot is provided for the purists out there who are OK using slightly older hardware as a result. Work done since last release -============================ +---------------------------- There have been no code changes whatsoever, on any of the current builds, but a major oversight has been corrected. @@ -89,7 +89,7 @@ people know of the above issue. Those files, listed above, have been removed in today's release. Hardware supported in this release -================================== +------------------------------------ All of the following are believed to *boot*, but if you have any issues, please contact the Canoeboot project. They are: @@ -99,8 +99,7 @@ please contact the Canoeboot project. They are: - [ASUS KFSN4-DRE motherboard](../docs/hardware/kfsn4-dre.md) - [ASUS KGPE-D16 motherboard](../docs/hardware/kgpe-d16.md) -Desktops (AMD, Intel, x86) ------------------------ +### Desktops (AMD, Intel, x86) - [Gigabyte GA-G41M-ES2L motherboard](../docs/hardware/ga-g41m-es2l.md) - [Acer G43T-AM3](../docs/hardware/acer_g43t-am3.md) @@ -130,17 +129,16 @@ Desktops (AMD, Intel, x86) - [Samsung Chromebook Plus (v1) (gru-kevin)](../docs/install/chromebooks.md) Downloads -========= +--------- 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. Errata -====== +------ -Update on 12 November 2023: ---------------------------- +### Update on 12 November 2023: This file was also overlooked, and is still present in the release tarball: diff --git a/site/news/canoeboot20231107.md b/site/news/canoeboot20231107.md index 92f9162..cf5ff37 100644 --- a/site/news/canoeboot20231107.md +++ b/site/news/canoeboot20231107.md @@ -7,8 +7,8 @@ a de-blobbed configuration on *fewer mainboards*; Libreboot supports more hardware, and much newer hardware. More information can be found on Canoeboot's [about](../about.html) page and by reading Libreboot's [Binary Blob Reduction Policy](https://libreboot.org/news/policy.html). -Introduction -============ +Open source BIOS/UEFI firmware +------------------------------ *This* new release, Canoeboot 20231107, released today 7 November 2023, is based on the recent [Libreboot 20231106](https://libreboot.org/news/libreboot20231106.html) release. @@ -41,13 +41,12 @@ firmware, but not Canoeboot! Booting Linux/BSD is also [well](../docs/linux/) [supported](../docs/bsd/). Work done since last release -============================ +--------------------------- This is largely a bugfix release. Most notably, boot issues on GM45 thinkpads present in the 20231103 release have been resolved. -Dell E6400 on its own tree ------------------------------ +### Dell E6400 on its own tree Canoeboot contains a DDR2 raminit patch for Dell Latitude E6400, that increases reliability on coldboot, but it negatively affects other GM45 machines that use @@ -65,8 +64,7 @@ from those release archives). Today's Canoeboot release solves that problem, so these machines can be used reliably once again (and ROM images are provided, in this Canoeboot 20231107 release). -Coreboot, GRUB, U-Boot and SeaBIOS revisions ------------------------------------- +### Coreboot, GRUB, U-Boot and SeaBIOS revisions Canoeboot 20231107 and 20231103 are both based on these revisions: @@ -82,7 +80,7 @@ Several other fixes and tweaks have been made, in addition to this and the E6400 patch mentioned above. Build system tweaks -=================== +---------------- These changes were made: @@ -126,7 +124,7 @@ f12f5c3a nvmutil: fix makefile This is a very conservative changelog, because this is largely a bugfix release. Hardware supported in this release -================================== +-------------------------------- All of the following are believed to *boot*, but if you have any issues, please contact the Canoeboot project. They are: @@ -136,8 +134,7 @@ please contact the Canoeboot project. They are: - [ASUS KFSN4-DRE motherboard](../docs/hardware/kfsn4-dre.md) - [ASUS KGPE-D16 motherboard](../docs/hardware/kgpe-d16.md) -Desktops (AMD, Intel, x86) ------------------------ +### Desktops (AMD, Intel, x86) - [Gigabyte GA-G41M-ES2L motherboard](../docs/hardware/ga-g41m-es2l.md) - [Acer G43T-AM3](../docs/hardware/acer_g43t-am3.md) @@ -167,17 +164,16 @@ Desktops (AMD, Intel, x86) - [Samsung Chromebook Plus (v1) (gru-kevin)](../docs/install/chromebooks.md) Downloads -========= +--------- 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. Errata -====== +------ -Update on 12 November 2023: ---------------------------- +### Update on 12 November 2023: This file was also overlooked, and is still present in the release tarball: diff --git a/site/news/canoeboot20240504.md b/site/news/canoeboot20240504.md index fb53d71..f899dfa 100644 --- a/site/news/canoeboot20240504.md +++ b/site/news/canoeboot20240504.md @@ -10,8 +10,8 @@ hardware, and much newer hardware. More information can be found on Canoeboot's **Do not use the Canoeboot 20240504 release, because it had problems with it. Please use the [Canoeboot 20240612 release](canoeboot20240612.md) instead.** -Introduction -============ +Free software BIOS/UEFI +------------------------ Canoeboot is a free/libre BIOS/UEFI replacement on x86 and ARM, providing boot firmware that initialises the hardware in your computer, to then load an @@ -67,7 +67,7 @@ Your computer is *your property* to use as you wish. Free Software protects you, by ensuring that you always have control of the machine. Hardware supported in this release -================================== +--------------------------------- This release supports the following hardware: @@ -105,17 +105,15 @@ This release supports the following hardware: - [Samsung Chromebook Plus (v1) (gru-kevin)](../docs/install/chromebooks.md) Highlights -========== +----------- -S3 fixed on GM45 thinkpads ------------------------ +### S3 fixed on GM45 thinkpads This was broken in the previous Canoeboot release, but now it works again. S3 suspend/resume (when you put the laptop to sleep and later wake it up). -Modest code size reduction --------------------------- +### Modest code size reduction See: [Libreboot build system audit 4](https://libreboot.org/news/audit4.html) @@ -138,15 +136,13 @@ things like memory controller initialisation. Canoeboot is provided for purists who only want free software; it even removes CPU microcode updates, regardless of the negative impact this has on system stability. -GRUB 2.12 revision now used ---------------------------- +### GRUB 2.12 revision now used The previous Canoeboot release used a revision from GRUB 2.12-rc1, but now it uses the GRUB 2.12 released during December 2023, with some additional revisions and patches on top of that. -GRUB support for EFI System Partition -------------------------------------- +### GRUB support for EFI System Partition We don't use UEFI on x86, but the GRUB config in Canoeboot's GRUB payload has now been modified, to also scan `grub.cfg` from `EFI/` directories. @@ -160,8 +156,7 @@ installers (e.g. USB media). Syslinux/Extlinux/GRUB config scanning has been merged together there, so now a lot more distro installers should boot automatically, without manual tweaking/intervention from the user. -U-Boot release script ---------------------- +### U-Boot release script The script at `script/update/release` now supports generating standalone U-Boot source archives, like so: @@ -173,8 +168,7 @@ than `release/`. Canoeboot still provides U-Boot embedded within the larger source release archive, and does not yet actually provide U-Boot as a standalone project, but some people may find this useful. -Flashprog now used, not flashrom ---------------------------- +### Flashprog now used, not flashrom Essentially, flashprog has better leadership and is more stable than flashrom; flashrom has had new leadership for a while now, and in my view they are not @@ -190,7 +184,7 @@ stable. Canoeboot will use flashprog from now on, not flashrom. Work done since Canoeboot 20231107 -============================ +--------------------------- The following log will now acount for changes since Canoeboot 20231107, from most recent descending to very earliest commits. The most interesting changes @@ -476,7 +470,7 @@ are highlighted in bold: properly formatted to include `nvmutil.c`, when running make-all. Disabled boards -=============== +------------- Canoeboot's build system can be configured to exclude certain boards in release archives, while still permitting them to be re-built. @@ -488,7 +482,7 @@ D510MO and D945GCLF images not included either, due to lack of testing. *All other boards have ROM images in this release.* Errata -====== +---- See: diff --git a/site/news/canoeboot20240510.md b/site/news/canoeboot20240510.md index ac36dd8..a4802a2 100644 --- a/site/news/canoeboot20240510.md +++ b/site/news/canoeboot20240510.md @@ -10,8 +10,8 @@ hardware, and much newer hardware. More information can be found on Canoeboot's **Do not use the Canoeboot 20240510 release, because it had problems with it. Please use the [Canoeboot 20240612 release](canoeboot20240612.md) instead.** -Introduction -============ +Free software BIOS/UEFI +---------------------- Canoeboot is a [free/libre](https://writefreesoftware.org/) BIOS/UEFI replacement on x86 and ARM, providing @@ -55,7 +55,7 @@ changes; if you already installed Canoeboot 20240504, you probably don't need to update, but the *SeaBIOS* revision was updated, and has some fixes. Changes in this release -======================= +---------------------- *Extensive* changes have been made to the documentation and website! @@ -63,8 +63,7 @@ Very large and sweeping changes. ALSO: -Build system changes -------------------- +### Build system changes The following improvements have been made, most of them not affecting the final build (the actual code that goes in-flash): @@ -113,7 +112,7 @@ to update to today's release. If you *didn't* install 20240504, then you may aswell update to today's release (Canoeboot 20240510). Hardware supported in this release -================================== +-------------------------- This release supports the following hardware: @@ -156,7 +155,7 @@ the last Canoeboot release, so I decided to another quick one. That is all. Errata -====== +----- See: diff --git a/site/news/canoeboot20240612.md b/site/news/canoeboot20240612.md index 30d38c3..9ab5889 100644 --- a/site/news/canoeboot20240612.md +++ b/site/news/canoeboot20240612.md @@ -7,8 +7,8 @@ a de-blobbed configuration on *fewer mainboards*; Libreboot supports more hardware, and much newer hardware. More information can be found on Canoeboot's [about](../about.html) page and by reading Libreboot's [Binary Blob Reduction Policy](https://libreboot.org/news/policy.html). -Introduction -============ +Open source BIOS/UEFI firmware +----------------------------- Canoeboot is a free/libre BIOS/UEFI replacement on x86 and ARM, providing boot firmware that initialises the hardware in your computer, to then load an @@ -46,7 +46,7 @@ announcement for Canoeboot 20240612 is in reference to 20240504, *not* 20240510, so it also includes changes from the 20240510 release, with fixes made after it. Changes since Audit 1 -===================== +-------------------- Audit 1 was only recent, and forms most of the changes in this release, so look further down for a list of those changes or read [the audit 1 page](audit1.md). @@ -72,13 +72,12 @@ precisely to avoid any potential issues if a board doesn't need it. The NVMe patch has been extensively tested, on all of the boards that actually have it. Audit 1 changes -=============== +--------------- Since the recent audit 1 changes are included in this release, the changelog of that audit has simply been copied for sake of efficiency. Firstly: -Modest code size reduction --------------------------- +### Modest code size reduction There are 1054 lines of shell script in the build system, versus 1208 in the Canoeboot 20240504 release. Canoeboot's build system is written purely in @@ -88,12 +87,11 @@ This is a difference of 154 lines, or a 13% reduction. Despite the reduction, numerous features have been added and a large number of bugs were fixed. Summarised list of changes -========================== +-------------------------- Changes are in order per category, from newest to oldest: -Feature changes ---------------- +### Feature changes * **Download crossgcc tarballs as dependencies, when cloning coreboot.** We previously relied on the coreboot build system, which automatically fetches @@ -217,8 +215,7 @@ Feature changes * Removed all status checks from script/roms (formerly script/build/roms), because it's better to document this instead, and rely on testing regardless. -Bug fixes ---------- +### Bug fixes Some of these changes fix actual issues that were found in testing, while others were fixed *before* being triggered/reported and are thus *preventative @@ -431,8 +428,7 @@ The changes are, from newest to earliest: * Main build script: exit (with error status) if not running directly from the root of the cbmk work directory. -General code cleanup --------------------- +### General code cleanup In addition to *general* very sweeping code cleanup, condensing code lines where possible and so on: @@ -549,13 +545,12 @@ where possible and so on: * script/build/roms: split up `main()` into multiple smaller functions Revision updates -================ +---------------- Some revisions were updated as part of standard routine, but happened to be done during this audit. Those updates are as follows: -SeaBIOS -------- +### SeaBIOS Bump SeaBIOS to revision `e5f2e4c69643bc3cd385306a9e5d29e11578148c`, which has these changes relative to the old one: @@ -585,8 +580,7 @@ these changes relative to the old one: * a6ed6b70 limit address space used for pci devices. ``` -Flashprog ---------- +### Flashprog Updated to revision 5b4fdd1 from 2 May 2024, rebasing the MX workaround patch. @@ -657,7 +651,7 @@ Flashrom, lead by Nico Huber after a dispute with the new leadership of Flashrom, and it was felt that Flashprog is a better choice for Canoeboot. Git log -======= +------ This entire set of changelogs is based on the precise Git history in cbmk, relative to Canoeboot 20240504 which is from where the audit began. diff --git a/site/news/canoeboot20241102.md b/site/news/canoeboot20241102.md index 19cec60..7217307 100644 --- a/site/news/canoeboot20241102.md +++ b/site/news/canoeboot20241102.md @@ -7,8 +7,8 @@ a de-blobbed configuration on *fewer mainboards*; Libreboot supports more hardware, and much newer hardware. More information can be found on Canoeboot's [about](../about.html) page and by reading Libreboot's [Binary Blob Reduction Policy](https://libreboot.org/news/policy.html). -Introduction -============ +Open source BIOS/UEFI firmware +-------------------------- Canoeboot is a free/libre BIOS/UEFI replacement on x86 and ARM, providing boot firmware that initialises the hardware in your computer, to then load an @@ -26,12 +26,11 @@ or [GRUB](https://www.gnu.org/software/grub/) to boot your operating system; on ARM(chromebooks), we provide *U-Boot* (as a coreboot payload). Summarised list of changes -========================== +-------------------------- Changes are in order per category, from newest to oldest: -Board support -------------- +### Board support The following boards have been added since the Canoeboot 20240612 release: @@ -46,8 +45,7 @@ modified Intel Flash Descriptors similar to that seen on ThinkPad X200/T400. E4300 has the same installation procedure as the E6400. -About the PlayStation BIOS --------------------------- +### About the PlayStation BIOS This is *not* coreboot, but it is a fully free/opensource BIOS with source code under MIT license, provided by @@ -63,8 +61,7 @@ other modifications, it basically becomes a very hackable classic 90s computer, that also happens to play games. More info is on the Libreboot page about it, linked above. -Feature changes ---------------- +### Feature changes Some unused features have been removed, and yet more added. The overall focus of Audit 2 has been to remove legacy cruft from cbmk, and in general to simplify @@ -263,8 +260,7 @@ The changes are as follows: avoiding such configurations. NOTE: This issue never affected *Canoeboot*, but Canoeboot keeps in sync with Libreboot where possible. -Configuration changes ---------------------- +### Configuration changes This pertains to anything under `config/`, for any changes that are of note, but it does not pertain to *revisions* for specific projects, nor does it @@ -323,8 +319,7 @@ The changes are as follows: which is loaded per-project on multi-tree projects, before each target file. It allows easier configuration tree-wide on multi-tree projects. -Bug fixes ---------- +### Bug fixes There are fewer *acute* bug fixes in Audit 2, because bugfixes was the primary focus of *Audit 1*. The word *acute* is used, referring to triggered bugs, because @@ -501,8 +496,7 @@ The changes are as follows: could create situations where the user can longer run cbmk without intervention such as changing permission on certain files. Avoid the issue entirely. -General code cleanup --------------------- +### General code cleanup Extensive code cleanup has been performed, as was the main purpose of Audit 2. @@ -778,10 +772,9 @@ The changes are as follows: * `script/roms`: shorter variable names, condensed several functions. Revision updates -================ +---------------- -Coreboot --------- +### Coreboot The `default` tree was updated to commit ID `97bc693ab` from 29 July 2024. Several patches were merged upstream and therefore no longer needed in cbmk. @@ -798,8 +791,7 @@ a single `fam15h` tree. This contains the ASUS KGPE-D16 and KCMA-D8 ports, based on coreboot's `4.11_branch` tree, with Canoeboot's special build fixes that make it compile on modern distros, such as Debian Sid or Arch. -U-Boot ------- +### U-Boot Alper Nebi Yasak is the maintainer of U-Boot, within *Libreboot*, and a Libreboot patch of his updated U-Boot to v2024.07, on the `gru_bob` and `gru_kevin` @@ -813,20 +805,17 @@ boards, but revision updates will be done *immediately after* Audit 2 is announced, as a priority for further work that is to be completed for the next Canoeboot release, ETA August 2024. -GRUB ----- +### GRUB Updated the revision to commit ID b53ec06a1 from 17 June 2024. This fixes several bugs in the LUKS implementation. Several virtual memory fixes, and numerous fixes to file system drivers in the GRUB kernel. -Flashprog ---------- +### Flashprog Updated the revision to commit ID `639d563` from 2 August 2024. -PCSX Redux ----------- +### PCSX Redux This was added git commit ID `6ec5348058413619b290b069adbdae68180ce8c0`. It is a *Sony PlayStation* emulator, but we only need one part of it: the BIOS. @@ -838,7 +827,7 @@ the open BIOS image, which is compatible with every PlayStation emulator and also real PlayStations (soldering required). Git log -======= +-------- This git log covers all changes in this audit, relative to Canoeboot 20240612. diff --git a/site/news/canoeboot20241207.md b/site/news/canoeboot20241207.md index 98a9057..f4b19cc 100644 --- a/site/news/canoeboot20241207.md +++ b/site/news/canoeboot20241207.md @@ -14,8 +14,8 @@ Therefore, this can be considered a stable release of Canoeboot. This page lists all changes since Canoeboot 20241102. -Introduction -============ +Open source BIOS/UEFI firmware +------------------------------ @@ -34,8 +34,7 @@ and then a payload such as [SeaBIOS](https://www.seabios.org/SeaBIOS) or [GRUB](https://www.gnu.org/software/grub/) to boot your operating system; on ARM(chromebooks), we provide *U-Boot* (as a coreboot payload). -U-Boot UEFI payload on x86\_64 ------------------------------- +### U-Boot UEFI payload on x86\_64 For Canoeboot 20241207, today's release, U-Boot is *also* provided as an optional coreboot payload on x86 machines. This provides a sensible UEFI @@ -51,14 +50,13 @@ Since this is based on a stable release, not much has changed; the focus has been on bug fixes. However, the U-Boot x86 payload is a notable new feature. Summarised list of changes -========================== +------------------------- Changes are in order per category, from newest to oldest: -Feature changes ---------------- +### Feature changes * U-Boot support, for both x86 and x86\_64, provided as a coreboot payload. This complements the existing ARM64 U-Boot support present in Canoeboot. @@ -66,16 +64,14 @@ Feature changes timeout for the first selected entry on the bootflow menu (upstream does not currently support this feature, at the time of this Canoeboot release). -Configuration changes ---------------------- +### Configuration changes * Enabled the serial console by default, on these machines: Thinkpad X60, T60. * U-Boot x86 enabled on almost every x86 board, chainloaded from SeaBIOS. The `seauboot` images boot directly into U-Boot first, from SeaBIOS, but U-Boot can be bypassed by using the ESC menu in SeaBIOS. -Bug fixes ---------- +### Bug fixes * `script/trees`: reset `PATH` per target, to avoid it being wrong in the next target, because we manipulate this when enabling cross compilation (by using @@ -100,8 +96,7 @@ Bug fixes payload. * Added `arm-none-eabi-gcc-cs-c++` to Fedora dependencies. -Revision updates -================ +### Revision updates * Updated U-Boot to v2024.10, on both ARM64 and x86 boards. * Bumped coreboot/next to the latest coreboot revision, from several days @@ -109,7 +104,7 @@ Revision updates OptiPlex 780 ports. Git log -======= +------- This git log covers all changes in this audit, relative to Canoeboot 20241102. diff --git a/site/news/canoeboot20250107.md b/site/news/canoeboot20250107.md index 46652c3..626a85b 100644 --- a/site/news/canoeboot20250107.md +++ b/site/news/canoeboot20250107.md @@ -14,8 +14,8 @@ January 2025. Therefore, this can be considered a stable release of Canoeboot. This page lists all changes since Canoeboot 20241207. -Introduction -============ +Open source BIOS/UEFI firmware +------------------------ @@ -36,10 +36,9 @@ system; on ARM(chromebooks), we provide *U-Boot* (as a coreboot payload). Experimental x86 U-Boot support is also available. Summarised list of changes -========================== +-------------------- -Board support -------------- +### Board support RP2530 devices now supported in `pico-serprog`, e.g. Raspberry Pi Pico 2. @@ -50,8 +49,7 @@ The documentation has been updated, to reflect this improvement. Canoeboot also now imports `picotool` which is now used to compile the UF2 binaries for installation, when building them from `pico-sdk`. -Revision updates ----------------- +### Revision updates In descending order from latest changes to earliest changes: @@ -66,8 +64,7 @@ In descending order from latest changes to earliest changes: * Bumped flashprog to revision eb2c041 (14 Nov 2024). This brings in several important fixes from upstream. -Feature changes ---------------- +### Feature changes In descending order from latest changes to earliest changes: @@ -89,16 +86,14 @@ In descending order from latest changes to earliest changes: on any boards, nor will it be, on release images, but the user can do it themselves when compiling from source. -Configuration changes ---------------------- +### Configuration changes In descending order from the latest changes to the earliest changes: None of note; some other entries in this release log could be considered configuration changes. -Bug fixes ---------- +### Bug fixes Several fixes were made to prevent build errors on the latest Debian Sid and Arch, as of 6 January 2025. Fedora 41 was also tested, fixing @@ -178,8 +173,7 @@ changes to the earliest changes): because otherwise GRUB prefers the memdisk one and adding one in CBFS didn't change the background image, when users attempted this. -General code cleanup --------------------- +### General code cleanup In descending order from the latest changes to the earliest changes: @@ -189,7 +183,7 @@ In descending order from the latest changes to the earliest changes: improvement). Git log -======= +------- This log is relative to Canoeboot 20241207: diff --git a/site/news/policy.md b/site/news/policy.md index ca9d4dd..4ad5fff 100644 --- a/site/news/policy.md +++ b/site/news/policy.md @@ -26,8 +26,8 @@ Policy* on 17 November 2022, but Libreboot has existed since December 2013. Canoeboot started in October 2023, because of a minority of users that still demanded such a project exist as the old Libreboot did. -Introduction -============ +Free as in freedom! +----------------- Canoeboot intentionally *de-blobs* coreboot, which is to say that it does not include binary blobs. The coreboot software otherwise requires binary blobs on @@ -43,7 +43,7 @@ they are removed. You can also read more about the de-blobbing process on the [about](../about.md) page. Background information -====================== +---------------------- Canoeboot concerns itself only with what goes in the main boot flash IC, but there are other pieces of firmware to take into consideration, as covered @@ -62,7 +62,7 @@ supports a handful of machines from coreboot. For information about Intel Management Engine and AMD PSP, refer to the FAQ. So what *is* Canoeboot's policy? -================================ +------------------------- Canoeboot follows a very conservative and *light touch* approach, when it comes to deblobbing coreboot. @@ -108,7 +108,7 @@ not with free software. Other examples of firmware outside of the main boot flash is covered in the Canoeboot FAQ. More detailed insight about microcode -===================================== +--------------------------------- To be clear: it is preferable that microcode be free. The microcode on Intel and AMD systems *are* non-free. Facts and feelings rarely coincide; the diff --git a/site/other.md b/site/other.md index 388ca1a..6715442 100644 --- a/site/other.md +++ b/site/other.md @@ -3,8 +3,8 @@ title: Other coreboot distributions x-toc-enable: true ... -Introduction -============ +What is a coreboot distro? +-------------------------- Canoeboot is a *coreboot distribution* or *coreboot distro*, in the same way that Debian is a *Linux distro*. Its purpose is to provide free/opensource boot @@ -28,13 +28,12 @@ It's thanks to the various coreboot distros that many people use coreboot today; without them, many otherwise non-technical users might not use coreboot at all. List of coreboot distros -======================== +------------------------ Not all distros are listed; only those of high quality or otherwise of interest; quality, not quantity. In alphabetical order: -Dasharo -------- +### Dasharo Website: @@ -52,8 +51,7 @@ the Dasharo project, and later upstreamed into the regular coreboot project. Dasharo has a special emphasis on commercial application, providing tailored coreboot images for each supported mainboard, with an emphasis on stability. -Heads ------ +### Heads Website: @@ -77,8 +75,7 @@ ROM hashes on every build; for this purpose, it also auto-downloads vendor files such as Intel ME at build time, instead of requiring you to dump from the original boot firmware. -Libreboot ---------- +### Libreboot Website: @@ -117,8 +114,7 @@ are in fact advised to use *Libreboot*, not Canoeboot. Canoeboot is meant only as a proof of concept, and/or for purists who absolutely wish to have the purest free software experience possible, regardless of these facts. -MrChromeBox ------------ +### MrChromeBox Website: @@ -154,8 +150,7 @@ the interview: Libreboot largely avoids supporting Chromebooks, precisely because MrChromebox is a perfectly viable option on these machines. -Skulls ------- +### Skulls Git repositories: @@ -171,8 +166,7 @@ aims to provide ease of use while also providing great power and flexibility. So Libreboot is aimed specifically at power users, while also trying to accomodate non-technical users; Skulls largely targets the latter. -System76 Open Firmware ----------------------- +### System76 Open Firmware Git repository: @@ -187,7 +181,7 @@ System76 provides the coreboot firmware, along with EDK2 UEFI payload. It can boot Linux distros, BSD systems and even Windows perfectly. Is your distro unlisted? -======================== +------------------------ Please get in touch! We'd love to link your project here. @@ -203,7 +197,7 @@ firmware, which was the primary motivation behind this page, in promoting the various projects. Non-coreboot free firmware -========================== +-------------------------- Several other projects besides coreboot provide free hardware initialisation, such as [U-Boot](https://www.u-boot.org/) (as own firmware, distinct from U-Boot diff --git a/site/template.de.include b/site/template.de.include index 5e45851..e6be047 100644 --- a/site/template.de.include +++ b/site/template.de.include @@ -93,7 +93,7 @@ $return$ $endif$ $if(toc)$ $endif$ diff --git a/site/template.include b/site/template.include index a93e37b..4c79a99 100644 --- a/site/template.include +++ b/site/template.include @@ -93,7 +93,7 @@ $return$ $endif$ $if(toc)$ $endif$ diff --git a/site/template.it.include b/site/template.it.include index e70887e..9cdc7d9 100644 --- a/site/template.it.include +++ b/site/template.it.include @@ -93,7 +93,7 @@ $return$ $endif$ $if(toc)$ $endif$ diff --git a/site/template.uk.include b/site/template.uk.include index 9ae4b93..025d054 100644 --- a/site/template.uk.include +++ b/site/template.uk.include @@ -93,7 +93,7 @@ $return$ $endif$ $if(toc)$ $endif$ diff --git a/site/template.zh-cn.include b/site/template.zh-cn.include index 50db517..72fe93f 100644 --- a/site/template.zh-cn.include +++ b/site/template.zh-cn.include @@ -93,7 +93,7 @@ $return$ $endif$ $if(toc)$ $endif$