Edit this page -- Back to previous index
This guide assumes that you use the GNU GRUB bootloader as your default payload. In this configuration, GNU 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. Retroboot’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, Retroboot’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.
There are mainly three methods for obtaining a Retroboot ROM image:
In either case, you will use the
cbfstool supplied by the coreboot project. This can be found under
coreboot/*/util/cbfstool/ as source code, where
* can be any coreboot source code directory for a given mainboard.
For the time being, no stable Retroboot release exists and there are no archives available with pre-compiled binaries. Therefore, we will download the source code and compile it.
Since no stable release schedule is yet established for Retroboot, you may also wish to compile the Retroboot ROM yourself. The guide linked above will tell you how to do that.
Install the build dependencies. For Ubuntu 20.04 and similar, you can run the following command in the Retroboot build system, from the root directory of the Retroboot Git repository.
./build dependencies ubuntu2004
Then, download coreboot:
Finally, compile the
./build module cbutils
Among other things, this will produce a
cbfstool executable under any of the subdirectories in
coreboot/ under `util/cbfstool/cbfstool
For example: coreboot/x230_4mb/util/cbfstool/cbfstool
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, Retroboot inherits this technology.
You will also want to build
flashrom which Retroboot recommends for reading from and/or writing to the boot flash. In the Retroboot build system, you can build it by running this command:
./build module flashrom
An executable will be available at
flashrom/flashrom after you have done this.
If you wish to modify your existing Retroboot ROM, which was installed on your computer, you can use
flashrom to acquire it.
Simply run the following, after using Retroboot’s build system to compile flashrom:
sudo ./flashrom/flashrom -p internal -r dump.bin
If flashrom complains about multiple flash chip definitions, do what it says to rectify your command and run it again.
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.
At other sites, you may need to connect an SPI programmer externally (with the machine powered down) and read the contents of the boot flash. At present, the only SPI flasher documented by Retroboot is the Raspberry Pi which you can learn how to use (for this purpose) by reading the following guide: How to program an SPI flash chip with the Raspberry Pi
You can simply put a custom
/boot/grub/ on your installed GNU+Linux system, if you’re using GNU+Linux. Retroboot also provides instructions for systems running BSD with GNU GRUB payload in Retroboot, on these articles: ../bsd/
Retroboot images that use the GNU GRUB bootloader will have two configuration files in CBFS:
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 Retroboot ROM image that you compiled or otherwise acquired).
Show the contents of CBFS, in your ROM:
cbfstool dump.bin print
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
dump.bin or other modified Retroboot ROM can then be re-flashed using:
sudo ./flashrom -p internal -w dump.bin
-c option is required, use it and specify a flash chip name. This is only useful when
flashrom complains about multiple flash chips being detected.
If you need to use external flashing equipment, see the link above to the Raspberry Pi page.
Edit this page – License – Template – Authors – Conduct Guidelines – Governance – Donate – Buy preinstalled
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License Version 1.3 or any later version published by the Free Software Foundation with no Invariant Sections, no Front Cover Texts, and no Back Cover Texts. A copy of this license is found in /docs/fdl-1.3.html