From 9fe5e0a8d297ea9b0df8e403a33d3cd63dbc6b42 Mon Sep 17 00:00:00 2001 From: Leah Rowe Date: Mon, 26 Aug 2024 22:36:21 +0100 Subject: [PATCH] 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 --- site/docs/gnulinux/grub_cbfs.md | 171 ++++++++++++-------------------- 1 file changed, 64 insertions(+), 107 deletions(-) diff --git a/site/docs/gnulinux/grub_cbfs.md b/site/docs/gnulinux/grub_cbfs.md index 9f4d26a..06f9da3 100644 --- a/site/docs/gnulinux/grub_cbfs.md +++ b/site/docs/gnulinux/grub_cbfs.md @@ -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 flash externally, just in case something goes wrong. -This guide assumes that you use the GRUB bootloader as your default -payload. In this configuration, GRUB is flashed alongside coreboot and runs -on *bare metal* as a native coreboot payload and does *not* use BIOS or UEFI -services (but it *can* load and execute SeaBIOS, in addition to any other -coreboot payload, by chainloading it). +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 +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. -In most circumstances, this guide will not benefit you. Canoeboot's default -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. +This guide will simply teach you how to modify the config, but not what to put. 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. 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 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: ./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 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 ROM image; as a *coreboot distribution*, Canoeboot inherits this technology. -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 +You can compile cbfstool and ifdtool for the given coreboot tree, e.g.: + + ./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: ./mk -b flashprog @@ -90,98 +92,53 @@ this. Dump the boot flash =================== -If you wish to modify your *existing* canoeboot ROM, which was installed on -your computer, you can use `flashprog` to acquire it. +[Learn how to externally reprogram these chips](../install/spi.md) and use +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 -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. +Those guides show how to dump the flash contents, which you are advised to do. Insert new grub.cfg =================== -You can find the default config under `config/grub/config/grub.cfg` in the -Canoeboot build system, +If you already have a `grub.cfg` in cbfstool, you can extract and modify that +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 ============================ -Your modified `dump.bin` or other modified Canoeboot ROM can then be re-flashed -using: - - 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. +Check the [Canoeboot flashing guide](../install/) which says how to flash the +new image.