canoeboot
/
cbwww
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

make grub_cbfs.md a bit clearer 

a lot of the instructions are really old

make it relevant to the way canoeboot currently works

Signed-off-by: Leah Rowe <info@minifree.org>
master
Leah Rowe 2024-08-26 22:36:21 +01:00
parent fb80442611
commit 9fe5e0a8d2
1 changed files with 64 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

171
site/docs/gnulinux/grub_cbfs.md
View File

@ -9,26 +9,13 @@ now, as of 3 May 2024, which is a fork of flashrom.
Before you follow this guide, it is advisable that you have the ability to Before you follow this guide, it is advisable that you have the ability to
flash externally, just in case something goes wrong. flash externally, just in case something goes wrong.
This guide assumes that you use the GRUB bootloader as your default Canoeboot's own GRUB configuration automatically scans for one provided by
payload. In this configuration, GRUB is flashed alongside coreboot and runs your distro, and this automation will usually work. Sometimes, you might wish
on *bare metal* as a native coreboot payload and does *not* use BIOS or UEFI to override it with your own custom menuentry or additional logic in the GRUB
services (but it *can* load and execute SeaBIOS, in addition to any other config. You can configure GRUB however you like, and this topic is vast so what
coreboot payload, by chainloading it). to actually *put in the config* will not be covered here.
In most circumstances, this guide will not benefit you. Canoeboot's default This guide will simply teach you how to modify the config, but not what to put.
GRUB configuration file contains scripting logic within it that intelligently
searches for GRUB partitions installed onto a partition on your SSD, HDD or
USB drive installed on your computer. If such a file is found, Canoeboot's
default GRUB configuration is configured to switch automatically to that
configuration. While not perfect, the logic *does* work with most
configurations.
Therefore, you should only follow *this* guide if the automation (described
above) does not work. It goes without saying that modifying the default GRUB
configuration is risky, because a misconfiguration could create what's called
a *soft brick* where your machine is effectively useless and, in that scenario,
may or may not require external flashing equipment for restoring the machine to
a known state.
Compile flashprog and cbfstool Compile flashprog and cbfstool
============================= =============================
@ -55,20 +42,28 @@ This can be found under `coreboot/*/util/cbfstool/` as source code,
where `*` can be any coreboot source code directory for a given mainboard. where `*` can be any coreboot source code directory for a given mainboard.
The directory named `default` should suffice. The directory named `default` should suffice.
Install the build dependencies. For Ubuntu 20.04 and similar, you can run Install the build dependencies. For Debian and similar, you can run
the following command in the Canoeboot build system, from the root directory the following command in the Canoeboot build system, from the root directory
of the Canoeboot Git repository. of the Canoeboot Git repository.
./mk dependencies ubuntu2004 ./mk dependencies debian
Then, download coreboot: Determine what coreboot tree you need for your board. For example, if building
for `x200_8mb`, check `config/coreboot/x200_8mb/target.cfg` and it might
say `tree="default"` - in this case, the coreboot tree is named `default`.
./mk -f coreboot Then, download coreboot (we'll assume the `default` tree is correct):
./mk -f coreboot default
Finally, compile the `cbutils` module: Finally, compile the `cbutils` module:
./mk -b grub ./mk -b grub
GRUB is multi-tree, but for GRUB utilities that's fine because we don't patch
those in any tree; we only patch the GRUB kernel to add various drivers and
extra crypto such as argon2.
Among other things, this will produce a `cbfstool` executable under any of the Among other things, this will produce a `cbfstool` executable under any of the
subdirectories in `src/coreboot/` under `util/cbfstool/cbfstool subdirectories in `src/coreboot/` under `util/cbfstool/cbfstool
@ -78,8 +73,15 @@ The `cbfstool` utility is what you shall use. It is used to manipulate CBFS
(coreboot file system) which is a file system contained within the coreboot (coreboot file system) which is a file system contained within the coreboot
ROM image; as a *coreboot distribution*, Canoeboot inherits this technology. ROM image; as a *coreboot distribution*, Canoeboot inherits this technology.
You will also want to build `flashprog` which canoeboot recommends for reading You can compile cbfstool and ifdtool for the given coreboot tree, e.g.:
from and/or writing to the boot flash. In the canoeboot build system, you can
./mk -d coreboot default
This will create `elf/cbfstool/default/cbfbstool`
and `elf/ifdtool/default/ifdtool`.
You will also want to build `flashprog` which Canoeboot recommends for reading
from and/or writing to the boot flash. In the Canoeboot build system, you can
build it by running this command: build it by running this command:
./mk -b flashprog ./mk -b flashprog
@ -90,98 +92,53 @@ this.
Dump the boot flash Dump the boot flash
=================== ===================
If you wish to modify your *existing* canoeboot ROM, which was installed on [Learn how to externally reprogram these chips](../install/spi.md) and use
your computer, you can use `flashprog` to acquire it. the `-r` option in flashprog; alternatively, for internal flash access,
look at the [main flashing guide](../install/).
Simply run the following, after using canoeboot's build system to compile Those guides show how to dump the flash contents, which you are advised to do.
flashprog:
sudo ./elf/flashprog/flashprog -p internal -r dump.bin
If flashprog complains about multiple flash chip definitions, do what it says to
rectify your command and run it again.
You may want to use the following, instead of `-p internal`:
`-p internal:laptop=force_I_want_a_brick,boardmismatch=force`
Do not let the word *brick* fools you. This merely disables the safety checks
in flashprog, which is sometimes necessary depending on what ROM was already
flashed, versus the new ROM image.
The `internal` option assumes that internal read/write is possible; this is
when you read from and/or write to the boot flash from an operating systems
(usually GNU+Linux) that is *running on* the target system.
In other cases, you may need to connect an SPI programmer externally (with the
machine powered down) and read the contents of the boot flash.
[Learn how to externally reprogram these chips](../install/spi.md)
Extract grub.cfg
================
Canoeboot 20231026 or newer
-----------------------------------
Releases or or after Canoeboot 20231026 contain `grub.cfg` inside GRUB memdisk,
inaccessible directly from CBFS, but the memdisk is inside `grub.elf` which
gets put inside CBFS.
An override is possible, on new Canoeboot revisions. If `grub.cfg` is present
in CBFS, Canoeboot's GRUB will use *that* and not the memdisk one; it will not
auto-switch to `grubtest.cfg`, but the test config will be available in the
menu to switch to, if present. This contrasts behaviour in older revisions.
You can find `grub.cfg` under cbmk (for this purpose, it's best to use the
cbmk one, not the release one - unless you're using a release image).
Find it at path (in current cbmk): `config/grub/config/grub.cfg`.
So, you can *add* `grubtest.cfg` as normal, test that, and
then *add* `grub.cfg` once you're happy, and it will override the default.
In older revisions of Canoeboot, GRUB memdisk always loaded the config from
CBFS, which you would have to replace; this meant it was possible to brick
your GRUB installation if you accidentally flashed without `grub.cfg`. In
Canoeboot 20231026 and higher, such error is impossible; this behaviour is
also present in Libreboot 20231021, upon which Canoeboot 20231026 is based.
This new behaviour is therefore much safer, under user error. However, it's
still possible to flash a bad `grub.cfg` by misconfiguring it, which is why
you should add `grubtest.cfg` first; when present, it will be available in
the default menu, for testing, but the GRUB memdisk config will always be used
first if no `grub.cfg` (as opposed to `grubtest.cfg`) exists in CBFS.
Insert new grub.cfg Insert new grub.cfg
=================== ===================
You can find the default config under `config/grub/config/grub.cfg` in the If you already have a `grub.cfg` in cbfstool, you can extract and modify that
Canoeboot build system, one, e.g.:
Remove the old `grub.cfg` (substitute with `grubtest.cfg` as desired): cbfstool canoeboot.rom extract -n grub.cfg -f grub.cfg
cbfstool dump.bin remove -n grub.cfg Now remove it:
Add your modified `grub.cfg` (substitute with `grubtest.cfg` as desired): cbfstool canoeboot.rom remove -n grub.cfg
cbfstool dump.bin add -f grub.cfg -n grub.cfg -t raw It's important that you re-add `grub.cfg` before flashing:
cbfstool canoeboot.rom add -f grub.cfg -n grub.cfg
Repeat this for `grubtest.cfg` if you wish.
If you're using a default Canoeboot image, there *is no `grub.cfg` in flash*.
This is because there is also a default one embedded inside the GRUB binary,
which is inside CBFS. So:
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
the default GRUB configuration is located.
You can insert a `grub.cfg` into CBFS and it will override the one in memdisk.
Check your board, e.g. `x200_8mb`, look at the file: `config/coreboot/x200_8mb/target.cfg`
and check for `grubtree` - if it's not sot, then it's `default`, otherwise check
what it's set to.
We'll assume it's `default`, so the
file `config/grub/default/config/payload` is your GRUB config; this will be the
same as what yo uhave in memdisk.
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.
Flash the modified ROM image Flash the modified ROM image
============================ ============================
Your modified `dump.bin` or other modified Canoeboot ROM can then be re-flashed Check the [Canoeboot flashing guide](../install/) which says how to flash the
using: new image.
sudo ./flashprog -p internal -w dump.bin
If a `-c` option is required, use it and specify a flash chip name. This is
only useful when `flashprog` complains about multiple flash chips being
detected.
If flashprog complains about wrong chip/board, make sure that your ROM is for
the correct system. If you're sure, you can disable the safety checks by running
this instead:
sudo ./flashprog -p internal:laptop=force_I_want_a_brick,boardmismatch=force -w dump.bin
If you need to use external flashing equipment, see the link above to the
Raspberry Pi page.