215 lines
8.2 KiB
Markdown
215 lines
8.2 KiB
Markdown
---
|
|
title: Modifying grub.cfg in CBFS
|
|
x-toc-enable: true
|
|
...
|
|
|
|
NOTE: Libreboot standardises on [flashprog](https://flashprog.org/wiki/Flashprog)
|
|
now, as of 27 January 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).
|
|
|
|
In most circumstances, this guide will not benefit you. libreboot'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, libreboot'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
|
|
=============================
|
|
|
|
libreboot does not currently distribute utilities pre-compiled. It only
|
|
provides ROM images pre-compiled, where feasible. Therefore, you have to build
|
|
the utilities from source.
|
|
|
|
As for the ROM, there are mainly three methods for obtaining a libreboot ROM
|
|
image:
|
|
|
|
1. Dump the contents of the the main *boot flash* on your system, which already
|
|
has libreboot installed (with GRUB as the default payload). Extract the
|
|
GRUB configuration from *that* ROM image.
|
|
2. Extract it from a libreboot ROM image supplied by the libreboot project, on
|
|
the libreboot website or mirrors of the libreboot website.
|
|
3. Build the ROM yourself, using the libreboot build system. Instructions for
|
|
how to do this are covered in the following article:
|
|
[How to build libreboot from source](../build/)
|
|
|
|
In either case, you will use the `cbfstool` supplied in the libreboot build
|
|
system.
|
|
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
|
|
the following command in the libreboot build system, from the root directory
|
|
of the libreboot Git repository.
|
|
|
|
./build dependencies ubuntu2004
|
|
|
|
Then, download coreboot:
|
|
|
|
./update trees -f coreboot
|
|
|
|
Finally, compile the `cbutils` payload (and you will then have the utils):
|
|
|
|
./build grub
|
|
|
|
Among other things, this will produce a `cbfstool` executable under any of the
|
|
subdirectories in `src/coreboot/` under `util/cbfstool/cbfstool`.
|
|
|
|
For example: `src/coreboot/default/util/cbfstool/cbfstool`
|
|
|
|
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*, libreboot inherits this technology.
|
|
|
|
You will also want to build `flashprog` which libreboot recommends for reading
|
|
from and/or writing to the boot flash. In the libreboot build system, you can
|
|
build it by running this command:
|
|
|
|
./update trees -b flashprog
|
|
|
|
An executable will be available at `src/flashprog/flashprog` after you have done
|
|
this.
|
|
|
|
Dump the boot flash
|
|
===================
|
|
|
|
If you wish to modify your *existing* libreboot ROM, which was installed on
|
|
your computer, you can use `flashprog` to acquire it.
|
|
|
|
Simply run the following, after using libreboot's build system to compile
|
|
flashprog:
|
|
|
|
sudo ./src/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 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
|
|
================
|
|
|
|
Libreboot 20231021 or newer
|
|
-----------------------------------
|
|
|
|
Releases or or after 20231021 contain `grub.cfg` inside the GRUB memdisk,
|
|
inaccessible directly from CBFS, but the memdisk is inside `grub.elf` which
|
|
gets put inside CBFS.
|
|
|
|
An override is possible, on these Libreboot revisions. If `grub.cfg` is present
|
|
in CBFS, Libreboot'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.
|
|
|
|
You can find `grub.cfg` under lbmk (for this purpose, it's best to use the
|
|
lbmk one, not the release one - unless you're using a release image).
|
|
Find it at path (in current lbmk): `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.
|
|
|
|
Libreboot 20230625 or older
|
|
----------------------------
|
|
|
|
NOTE: This information will probably be deleted after a certain time has passed.
|
|
Libreboot changed a lot, as of release 20231021 in reference to 20230625, so it
|
|
may take a while before people adjust; therefore, this information is provided
|
|
for reference, but you should consider it to be deprecated:
|
|
|
|
libreboot images that use the GRUB bootloader will have *two* configuration
|
|
files in CBFS:
|
|
|
|
* `grub.cfg`
|
|
* `grubtest.cfg`
|
|
|
|
We recommend that you modify `grubtest.cfg` first, and boot. Select the boot
|
|
menu option for loading `grubtest.cfg` and verify that your new config works
|
|
correctly. If it doesn't, keep modifying `grubtest.cfg` until it does work.
|
|
When that it done, copy the changes over to `grub.cfg
|
|
|
|
You can use the following commands to modify the contents of CBFS, where
|
|
GRUB's configuration file is concerned (dump.bin is the ROM that you dumped,
|
|
or it could refer to the libreboot ROM image that you compiled or otherwise
|
|
acquired).
|
|
|
|
Show the contents of CBFS, in your ROM:
|
|
|
|
cbfstool dump.bin print
|
|
|
|
Extract `grub.cfg` (substitude with `grubtest.cfg` as desired):
|
|
|
|
cbfstool dump.bin extract -n grub.cfg -f grub.cfg
|
|
|
|
You will now have a file named `grub.cfg`.
|
|
|
|
Make your desired modifications. You should then delete the old `grub.cfg`
|
|
from your ROM image.
|
|
|
|
Insert new grub.cfg
|
|
===================
|
|
|
|
NOTE: As stated above, releases on or after Libreboot 20231021 only default to
|
|
the config in memdisk, and lack a CBFS config, so you can skip the *remove*
|
|
step below and just directly add the new `grub.cfg` - unless you already
|
|
added one before, in which case removal is required first.
|
|
|
|
Remove the old `grub.cfg` (substitute with `grubtest.cfg` as desired):
|
|
|
|
cbfstool dump.bin remove -n grub.cfg
|
|
|
|
Add your modified `grub.cfg` (substitute with `grubtest.cfg` as desired):
|
|
|
|
cbfstool dump.bin add -f grub.cfg -n grub.cfg -t raw
|
|
|
|
Flash the modified ROM image
|
|
============================
|
|
|
|
Your modified `dump.bin` or other modified libreboot 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.
|