retroboot/docs/maintain/index.md

---

title: Retroboot maintenance manual x-toc-enable: true ...

This document describes how to maintain rbmk (Retroboot Make). If you just want to build it, refer to this document instead: How to build Retroboot from source

Retroboot's build system is named rbmk, short for Retroboot Make, and this document describes every aspect of how it works. You can use this document as a reference for modifying rbmk. This document assumes that you are using the Retroboot git repository, which you can download here: https://notabug.org/retroboot/retroboot

If you're using a release archive of Retroboot, please refer to the documentation included with that release. It will be an older version of the document that you're now reading. For development, we prefer that you modify rbmk in the Git repository and read this document as a reference.

If you've made changes to Retroboot and you wish to submit them for review, you can! Refer to the following document: Sending patches for review

Use the Git repository!

An overview of Retroboot:

As of 5 January 2021, any command in the build system can run and, if required pre-requisite steps are not performed, the build system will run the necessary commands. For example, if you run ./build module grub but a GRUB directory is not present, the build system will automatically run ./download grub. This also means that you can now, from a fresh Git clone of Retroboot, simply run ./build retroboot roms and it will work!

In the git repository, Retroboot does not actually host projects such as coreboot, GRUB or SeaBIOS. Retroboot is, in a nutshell, a series of scripts that define how to:

• Download all of the required software components
• Patch all of the required software components, where necessary
• Build all of the required software components
• Build ROM images

Basically, Retroboot is mostly "metadata" defining where to grab everything and how to put it all together, from start to finish. No actual development on upstream projects (coreboot, GRUB, SeaBIOS etc) is done directly within Retroboot; development is done upstream, when development is done.

Another way of thinking about it is this: Retroboot is a recipe for building coreboot ROM images, much like a recipe for cake tells you how to prepare and bake a cake.

Retroboot doesn't just contain such scripts. It also contains:

• config files (for board configs, payloads, etc)
• option ROMs (e.g. for VGA initialization on boards without libgfxinit support)
• 3rd party submodules from coreboot. This is available under 3rdparty/ under each coreboot directory, for each board

You can also think of it as a "package manager". Development within Retroboot is done purely on the build scripts that download, patch, build and integrate everything, which then results in tested ROM images at known good versions of each and every software component.

This document assumes that you have downloaded Retroboot from the Git repository. If you are using a source code release archive, you can skip the download commands.

It is strongly recommended that you always build from Git, not the release archives. Technically, you can do whatever you want, but the releases are considered reference level, with source code included simply for GNU GPLv2/3 compliance and such. For actual development, you should use the Git repository.

In some cases, if you don't intend to develop Retroboot upstream but you simply want to make a quick modification to the version you're using, then working on the source code release archives would make sense. However, such a use-case scenario is not covered in this document. This page (at least the one hosted on retroboot.org) is geared towards the Git repository.

Let's begin!

Build dependencies

Before you begin, you should install all of the pre-requisite build dependencies so that you can compile Retroboot. These can be installed by running the following command in the build system (tested on Ubuntu 20.04):

./build dependencies ubuntu2004

Simply speaking, this runs a script that automatically installs all of the build dependencies in apt-get.

How to build Retroboot from source

Before you begin working on the build system, and reading the information on this page, it can help to get a high level view of how the build system is used. We already provide such documentation:

Learn how to compile Retroboot from source

Main build scripts

Retroboot's build system is highly centralized: all build commands revolve around two scripts:

• ./download (runs scripts under resources/scripts/download/)
• ./build (runs scripts under resources/scripts/build/)

The download script downloads modules.

The build script builds them.

A meclean script is also included. This runs the me_cleaner utility. It's not required for building anything in Retroboot, but the download script can download me_cleaner. The meclean script lets you run me_cleaner on a batch of ROM images.

Retroboot's build system is highly modular. For the most part, individual scripts within Retroboot are not tied to each other, and can be replaced or modified very easily, without affecting other parts of the build system too much, if at all. It is designed specifically to be easily adaptable, in this manner.

Everything used by the main build scripts (download and build) uses resources under the resources/ directory from the root of the Git repository or source code archive.

Resources directory

Everything in the Retroboot build system exists under the resources/ directory. The only exception to this is the docs/ and www/ directory, which are their own directory relative to the root of the main directory in the Git repository or Retroboot source code archive.

resources/util/

This directory contains utilities that are included as part of Retroboot, and not downloaded as modules like many parts of Retroboot are.

resources/util/ich9utils/

This is the ich9utils directory for source code of the following programs:

• ich9gen
• ich9deblob
• ich9show
• demefactory

Assuming you have basic dependencies such as GCC installed, simply type make in this directory to compile these utilities. Related commands in the Libreboot build system:

./build module ich9utils
./build descriptors ich9m

These utilities have everything to do with manipulating ICH9M based Intel Flash Descriptors on GM45 laptops such as ThinkPad X200 or T400. These were adapted from Libreboot.

More documentation about ICH9M and ich9utils is littered throughout the Retroboot documentation.

resources/blobs/pciroms/

This directory is intended for PCI Option ROM files, for instance Video BIOS ROM images. These can be loaded and executed by coreboot, or by SeaBIOS.

The file must be named with following convention: pciVVVV,DDDD.rom

VVVV is the vendor ID and DDDD is the device ID. These numbers can be obtained by running lspci -nn in GNU+Linux. You will see it listed as VVVV:DDDD. For example, an option ROM from PCI ID 1002:7145 would be pci1002,7145.rom.

NOTE: SeaVGABIOS option ROM is not stored here. It is stored under the directory payload/seabios/ as seavgabios.bin when running the command ./build payload seabios in the Retroboot build system. SeaVGABIOS is a free option ROM built from SeaBIOS source code, which makes use of libgfxinit in coreboot when using native video initialization in coreboot (as opposed to the vendor VBIOS Option ROM) on systems that have native video support in coreboot. Using coreboot's framebuffer as a base, SeaVGABIOS emulates a Video BIOS for legacy VGA support.

resources/coreboot/

This directory contains individual subdirectories for each board supported in Retroboot (whether it's a laptop, desktop or server mainboard). It contains config files, patches, information about coreboot/3rdparty commit IDs and so on. It reproducibly downloads and patches coreboot, for several mainboards that are supported in the Retroboot build system.

Inside each is the following:

resources/coreboot/BOARD_NAME/romtype

This file is optional.

Put a single line of text here, which can be anything. Specific lines of text can be used to instruct the ROM build script. Those are:

• 4MiB IFD BIOS region (if specified, the 4MiB BIOS region will be extracted which is actually just 4MiB CBFS size. For instance, x230_4mb ROMs are provided in Retroboot because X230 splits its 12MiB NOR flash into 8MiB and 4MiB chips, with upper 3MiB of the 8MiB flash being first part of the default BIOS region unless IFD is modified, with the 4MiB chip containing the final upper 4MiB part of the BIOS region. These 4MiB ROMs are useful when flashing, to flash just that 4MiB chip)
• 4MiB ICH9 IFD NOR flash (instructs the ROM script to insert ICH9M flash descriptor with disabled ME, on GM45/ICH9 boards such as ThinkPad X200/T400. This one is for 4MiB NOR flash)
• 8MiB ICH9 IFD NOR flash (same as above but for 8MiB NOR flash)
• 16MiB ICH9 IFD NOR flash (same as above but for 16MiB NOR flash)
• i945 laptop (if this is specified, the upper 64KiB bootblock will be copied to the space for the lower 64KiB bootblock, in the resulting coreboot ROM. This is useful for BUC.TS purposes on machines such as ThinkPad X60/T60)

As of 5 January 2021, no other strings are specified in the build system, so anything else (or the romtype file being absent) will result in default behaviour: just copy the ROM but don't modify it in any way.

In this configuration, the descriptor specifies regions based on 16MiB NOR flash.

resources/coreboot/BOARD_NAME/x86_32

This file is optional. If present, Tianocore will not be included at all when building ROM images.

Only the 64-bit version of Tianocore is built in Retroboot's build system. Some machines are 32-bit only, and in practise those older machines are typically quite useless with Tianocore.

Tianocore is only really useful on 64-bit machines, in most use-case scenarios, so Retroboot only builds the 64-bit version.

resources/coreboot/BOARD_NAME/config/

The following files (at least one, or all) can be included:

• libgfxinit_txtmode
• libgfxinit_vesafb
• vgarom_txtmode
• vgarom_vesafb

Configs with vgarom in the name must specify a PCI option ROM file name under format pciVVVV,DDDD.rom where VVVV is the vendor ID and DDDD is the device ID. This option ROM will be under resources/blobs/pciroms/ and the config: 1) disables VBT in coreboot, 2) Disables libgfxinit if present and 3) Enables loading and executing of PCI option ROM (Video BIOS) for that video chipset, with the exact PCI ID specified in the coreboot config.

Configs with libgfxinit in the name must specify that libgfxinit is to be used, with a VBT (Video BIOS Table) supplied by coreboot. Loading of PCI option ROMs must not be enabled in this setup (but on desktops, where libgfxinit is used for the built-in GPU, an add-on GPU can still be used if you use the SeaBIOS payload, because SeaBIOS will automatically load the Video BIOS from your graphics card).

Regardless of whether you use vgarom or libgfxinit setup:

• txtmode specifies that coreboot must start in legacy VGA text mode. This is useful for textmode applications such as MemTest86+ or operating systems such as FreeDOS
• vesafb specifies that coreboot must start in a VESA framebuffer. This option is most useful combined with libgfxinit when dealing with GNU+Linux or BSD operating systems in the GNU GRUB payload, or in SeaBIOS with SeaVGABIOS. This mode is also implied when using Tianocore, and Retroboot's build system does not provide Tianocore ROMs with txtmode startup.

These are specific coreboot configs for that board. These configs do not specify a payload, but enable PS/2 keyboard initialization in case SeaBIOS and GRUB are used (other payloads such as linuxboot and tianocore can do keyboard initialization on their own).

Each of these are coreboot configurations, for that board.

The rules (for Retroboot purposes) are as follows:

• Payload must be set to None. The Retroboot build system builds payloads externally, instead of using the coreboot build system.
• VGA ROM must be included, if required, and set in coreboot config such that coreboot itself is loading and executing the ROM.
• The config must not make coreboot's build system grab anything from external sources, except the 3rdparty repositories hosted by the coreboot project. The Retroboot build system provides the chance to specify exactly which 3rdparty submodule revisions are used. 3rdparty modules are downloaded after setting the coreboot revision, to ensure a consistent set of 3rdparty modules, and then resets the revisions of each submodule based on what is written in the Retroboot build system
• NOTE: exception to above rule is VGA ROMs, and other PCI option ROMs, which the user may want to include. However, only VGA option ROMs are really useful in most cases. Normally for other options ROMs, the user would want to have the SeaBIOS payload

General rules/principles for configuring a board in make menuconfig on the coreboot build system:

• General -> Use CMOS for configuration values (ENABLE)
• General -> Load default configuration values into CMOS on each boot (ENABLE)
• Hardcode your own desired CMOS config in src/mainboard/manufacturer_name/mainboard_name/cmos.default
• It's possible to change the CMOS config in nvramtool, directly on the ROM image. Simply dump it, change the value you want, then re-flash. Hardcoded config is desired, for consistent functionality on all systems where a given ROM image is used. This makes Retroboot behave more consistently at startup.
• Select what mainboard you want under Mainboard
• If it's a system with Intel Flash Descriptor, set the CBFS size to exactly the size of the BIOS region (as per Intel Flash Descriptor). For example, on X230, coreboot sets 1MiB CBFS size by default but the default BIOS region is 4MiB, so:
  • Mainboard -> Size of CBFS filesystem in ROM = 0x400000 (this is 4MiB specified in bytes as a hexadecimal value)
• Chipset -> Include CPU microcode in CBFS = Generate from tree (REQUIRED. If microcode updates are available, you should include them because they fix bugs and security issues that exist in the default burned in microcode on the CPU. However, some non-x86 machines such as Rockchip ARM SoCs might not use microcode at all)
• Chipset -> Bootblock behaviour = Always load fallback Based on a setting in CMOS memory, coreboot's bootblock can load either the fallback or normal payload. You can also put different ramstage and romstage in cbfs. This is useful for development, but not really useful for end users that Retroboot is targeting. (the Retroboot build system currently does not support use of fallback+normal but this could change in the future. Coreboot provides a mechanism where you put a setting in CMOS config that makes fallback/normal be used depending on that setting. If the RTC battery is pulled, then the other payload will be used. This other payload can be anything. This is useful for development purposes, like when developing a payload. You can have a known working payload, and the one you're working on, to prevent soft bricks and speed up development. Retroboot is geared towards end users, so just always use the fallback, and only include a fallback payload as fallback/payload in CBFS. This is the default behaviour of the Retroboot build system. This is OK because we verify each setup before releasing it.
• Devices -> Graphics initialization = Use libgfxinit
  • If you use this option, also do:
  • Add a Video BIOS Table (VBT) binary to CBFS (NEW) = ENABLED
  • Display -> Framebuffer mode = whatever you want
  • txtmode in the config name if setting legacy VGA framebuffer
  • vesafb in the config name if setting vesa framebuffer with a higher resolution
• Devices -> Graphics initialization = Run VGA Option ROMs
  • If you use this option, also do:
  • Display -> Leave it alone if you just want text mode (legacy VGA mode)
  • Display -> Select a resolution and set Framebuffer mode to VESA framebuffer if you want a high resolution framebuffer at startup
  • Add a VGA BIOS image = ENABLED
  • Include the PCI option ROM from resources/blobs/pciroms/ (see below) and in in coreboot menuconfig specify the filename as pciVVVV,DDDD.rom where VVVV is the vendor ID and DDDD is the device ID. You can find this information by running lspci -nn under GNU+Linux, and you can check that the option ROM is for your specific VGA adapter by running romheaders utility on the ROM. Check build date and other information of the VGA ROM by running strings pciVVVV,DDDD.rom | head
  • Example entry for path to VGA ROM in coreboot menuconfig: ../../resources/blobs/pciroms/pciVVVV,DDDD.rom
  • Add a Video BIOS Table (VBT) binary to CBFS = DISABLE (it's VERY important to disable this option, because the VGA ROM itself will handle VBT stuff and you don't want to conflict anything at start up)
• Generic Drivers -> PS/2 keyboard init = DISABLE
  • Only enable if necessary, like if you actually need to have PS/2 keyboard support, otherwise USB keyboard support will usually Just Work. GRUB, SeaBIOS and Tianocore all provide PS/2 keyboard init.
  • Tianocore (UEFI) payload does not require this option to be enabled. It handles PS/2 keyboard initialization by itself
  • Don't enable "PS/2 keyboard delay" in coreboot menuconfig. The Retroboot build system adds this externally, using a cbfstool command
• Security -> Memory initialization -> Always clear all DRAM on regular boot = ENABLE
  • This helps to reduce the threat posed by Cold Boot attacks
  • Other security features here you can choose to enable or disable depending on your preferences
• Console -> Default console log level = 0
  • Retroboot is intended for end users, who want a faster boot speed
  • The extra debug options slow down the boot process
• Payload -> Add a payload = NONE
  • Retroboot's build system compiles payloads externally, and adds them during the build process using cbfstool

resources/coreboot/BOARD_NAME/patches/

NOTE: This directory is ignored when you include a symlink file (see below)

You can make modifications to coreboot, on the upstream coreboot repository, reset to whatever coreboot commit ID you want to base your patches on.

For however many custom patches you've applied, run the following command:

git format-patch -nX

X is the number of patches. This might be applied in the master branch, or you might be working on another branch. If you're working in another branch, the commit ID is from whatever commit that branch forks from.

Retroboot's build system does not remove .git resources from coreboot, when downloading it for each board. Therefore, even if you've already applied patches (using the build system from Retroboot), you can then make further modifications on top of coreboot and include your patch.

The patches must be in ascending alpanumerical order from the first patch to be applied.

For example:

• 0001-first.patch
• 0002-second.patch
• 0003-third.patch
• ...and so on

NOTE: If you're using a symlink file (see below), do not put the patches here. In that situation, the patch directory should be empty (but the directory should still be present). For example, let's say X220 uses the same coreboot revision as X230, with X220 having a symlink file pointing to the X230 directory.

If symlink file present, put your patches in the patch/ directory of the board that is being linked to instead.

resources/coreboot/BOARD_NAME/revision/

NOTE: This directory is ignored when you include a symlink file (see below)

This directory contains files with single lines in them, specifying the exact commit ID of each coreboot submodule that go inside the 3rdparty/ directory of the coreboot Git repository.

Download coreboot and reset it to the revision you wish to use. Then you can download the submodules using this command:

git submodule update --init --checkout

Check the .gitmodules file in your coreboot directory. It specifies where all of the 3rdparty submodules will be downloaded to. Most of them will be downloaded into the 3rdparty/ directory.

For the ones in 3rdparty/ you should put a file with the same name as the corresponding directory under 3rdparty/ with that file containing just a single line specifying the commit ID you wish to use.

Generally, you should always set the 3rdparty revisions to the same ones used when you first downloaded the 3rdparty submodules in that version of coreboot, when that commit ID was the newest one in coreboot. This is because the submodule commit IDs will always be the latest ones in that repository, even when resetting to an older coreboot revision (Retroboot resets to the coreboot revision specified in cbrevision, see below).

If you are retroactively selecting an older coreboot revision, you should set the 3rdparty submodule revisions to ones that are either the exact same commit date as the date of the coreboot commit or, if none are that exact date, the latest date(s) before the date of the coreboot commit, not after. This will be verified when you submit a pull request anyway.

NOTE: Not all 3rdparty submodules are downloaded into 3rdparty/, and those ones will not automatically be reset to a specific revision by the Retroboot build system. For these, you should reset the commit using the extra.sh script (see below).

resources/coreboot/BOARD_NAME/cbrevision

NOTE: This file is ignored when you include a symlink file (see below).

This file must contain a single line, with no whitespace, just specifying the commit ID of the coreboot revision you intend to use (as per the coreboot Git repository).

resources/coreboot/BOARD_NAME/extra.sh (optional)

Technically, this script is optional but if you are not specifying a symlink via symlink file (see below) you should always, at the very least, reset submodule revisions of coreboot in this script, for those submodules that are not downloaded into the 3rdparty/ subdirectory of coreboot.

This is useful if you want to extend the default functionality of the build in Retroboot, for the particular board you're working on.

For example, if coreboot is downloading some submodules to a directory other than 3rdparty/ in the coreboot Git repository, you should script something in here to reset the revision of that submodule.

Another example of how this extra.sh script can be used is to apply custom patches to submodules in coreboot, or any other such functionality that is not yet implemented by the main build system in Retroboot. In other words, extra.sh can be used to extend the Retroboot build system functionality! That's why it's called extra.sh!

However, Retroboot's build system is released under a free license and you're free to extend it anyway. However! Sometimes, you will want to implement specific functionality that only benefits one specific mainboard in Retroboot. You could also make the extra.sh script symlink to another extra.sh script.

resources/coreboot/BOARD_NAME/symlink (optional)

When you run the ./download coreboot command, or coreboot is downloaded when running the ./download all command, coreboot is only downloaded (via git clone) once, and then copied (using cp -R) for each board specified as per directory names under resources/coreboot/.

A separate coreboot directory for each board is therefore created. For example, X230's coreboot directory would be coreboot/x230_4mb/. Coreboot's own crossgcc toolchain, utilities and other modules are compiled separately, for each directory. This means that different coreboot revisions can be used for different boards.

However, in practise we often use the same coreboot revision for most boards, or at most 2-3 coreboot revisions are used and each revision has a few boards using it in the Retroboot build system. It would be a waste to create a separate coreboot directory for multiple boards that all use the same coreboot revision.

Therefore, Retroboot's build system supports linking to another board, thus skipping the creation of a new coreboot directory.

The symlink file is not actually a symlink, but instead should contain the board name, per directory name of that board under resources/coreboot/.

The build system goes into the coreboot/ directory and creates a relative symlink. For example, if X220 contained a symlink pointing to X230, in the coreboot/ directory there would be a symlink x220 -> x230_4mb.

resources/grub/

This directory contains the GRUB configuration files (for the target systems that Retroboot's build system contains GRUB ROMs for), GRUB fonts, keymap files and a file specifying which modules are to be included in the GRUB payload.

resources/grub/config/

GRUB configs. There is not a full GRUB config here, because the build system mixed different snippets together to create various full GRUB configs, for various setups.

To understand how these files are used, read the following script:

• resources/scripts/build/payload/grub

resources/grub/font/

Fonts go in here. Currently, only the Dejavu Sans Mono is provided, as a font used in GRUB (but only is VESA mode, not text mode).

resources/grub/keymap/

Keymap configurations are included here, for various keyboard layouts. Retroboot's build system provides multiple ROM images with the GRUB payload, each with a different default payload. Even Dvorak (US, UK and French variants) are supported! This is one reason why Retroboot is so great.

I, Leah Rowe, created the UK Dvorak keymap file by hand, many years ago, by manually modifying the scan codes in the US Dvorak file. This is because there was no UK Dvorak keymap file available, and automatically generating it caused problems when actually using it. I did this many years ago, for Libreboot, because I'm a long time Dvorak user.

If you wish to add new keymaps, you can do so using the instructions here:

Adding new keymap files to GRUB

resources/grub/modules.list

This file contains a list of modules to be used in the GRUB payload. It is important to not use too many, because of limited storage capacity in the main boot flash on most systems that Retroboot has support for.

resources/memtest86plus/patch/

Patches for Memtest86+, which is included as a payload on certain Retroboot configurations. It is used to test your RAM, and it will tell you if your RAM is faulty.

resources/scripts/build/

This directory contains all of the scripts used that make up the entire Retroboot build system.

resources/scripts/build/clean/

Basically, these scripts do the equivalent of make clean or make distclean on various modules thet are a part of Retroboot.

resources/scripts/build/clean/ich9utils

This runs make clean on the ich9utils directory at resources/util/ich9utils/

This also deletes the descriptors generated at descriptors/ich9m/

resources/scripts/build/clean/cbutils

This runs make clean on the following coreboot utilities, in each coreboot directory for each board, on the following directories in coreboot:

• util/cbfstool/
• util/ifdtool/
• util/nvramtool/
• util/cbmem/

It also runs make distclean on payloads/libpayload/ in each coreboot directory.

These directories were created when running ./download coreboot in the Retroboot build system.

resources/scripts/build/clean/crossgcc

In each coreboot directory, for each board, this script does make distclean on util/crossgcc/ which is the cross-compiler toolchain that comes with coreboot.

The crossgcc binaries were compiled when running ./build module crossgcc in the Retroboot build system, which in turn runs make crossgcc in each and every coreboot directory created when running ./download coreboot in the Retroboot build system.

resources/scripts/build/clean/flashrom

This runs make clean on the flashrom/ directory, which was created when running ./download flashrom in the Retroboot build system.

resources/scripts/build/clean/grub

This runs make distclean on the grub/ directory, which was downloaded when running ./download grub in the Retroboot build system.

However, it does not delete the payload executables in the payload/ directory, which were created when running ./build payload grub, ./build payload seabios or ./build payload all in the Retroboot build system.

The files under payload/ are cleaned out when running the ./build clean payloads command.

resources/scripts/build/clean/memtest86plus

This runs make clean on the memtest86plus/ directory, which was created when running ./download memtest86plus in the Retroboot build system.

resources/scripts/build/clean/payloads

This literally just deletes the payload/ directory, which was created when running ./build payload grub or ./build payload seabios or ./build payload all in the Retroboot build system.

resources/scripts/build/clean/rom_images

This literally just deletes the bin/ directory, which was created when running the following command in the Retroboot build system:

./build retroboot roms

The bin/ directory contains coreboot ROM images, which were built when running one of the above commands.

resources/scripts/build/clean/seabios

This runs make distclean on the seabios/ directory, which was created when running ./download seabios in the Retroboot build system.

resources/scripts/build/dependencies/

resources/scripts/build/dependencies/ubuntu2004

Using the apt-get software, this script downloads and installs the required build dependencies on Ubuntu 20.04, which is a GNU+Linux distribution.

In Libreboot 20160907, which Retroboot was originally forked from (on December 11th, 2020), there was also a script for Parabola GNU+Linux. However, the Parabola script was deleted in Retroboot due to lack of testing. Libreboot 20160907 contained a script for Trisquel 7.0, which was updated for Ubuntu 20.04.

resources/scripts/build/descriptors/

Various commands to do with Intel Flash Descriptors

resources/scripts/build/descriptors/ich9m

This is executed when running ./build descriptors ich9m

This simply runs ich9gen located at resources/util/ich9utils/

Descriptors are made available at descriptors/ich9m/

resources/scripts/build/module/

These scripts compile the required modules, as a pre-requisite for then compiling payloads, which in turn is a pre-requisite for compiling coreboot ROM images for the end user to install (flash) on their machine.

resources/scripts/build/module/ich9utils

This runs make on ich9utils included at resources/util/ich9utils/.

This makes the following utilities available in that directory:

• ich9gen
• ich9show
• ich9deblob
• demefactory

More information about ich9utils is littered throughout the Retroboot documentation.

resources/scripts/build/module/cbutils

This runs make on the following coreboot utilities:

• util/cbfstool
• util/ifdtool
• util/nvramtool
• util/cbmem

The cbfstool utility is used extensively by the Retroboot build system, when building coreboot ROM images. It is used to:

• Insert payloads into the ROM images (Retroboot does not rely on the coreboot build system to insert payloads. They are compiled externally, and the ROM images are compiled with payloads. Cbfstool is then used, to insert the payloads after the coreboot ROM images are compiled)
• Insert GRUB configurations into the ROM images
• ...and more

The ifdtool utility is not currently used by the Retroboot build system, but it is provided for people who use Intel platforms that have an Intel Flash Descriptor in the boot flash. For example, X230's Intel Flash Descriptor sets some of the flash regions read-only by default, and ifdtool can be used to set these regions read-write by modifying the Intel Flash Descriptor in a dump of it, which can then be re-flashed to enable internal re-flashing.

The nvramtool utility is not currently used by the Retroboot build system, but it is recommended for changing CMOS settings in the coreboot ROM image. Retroboot hardcodes these settings, but you can dump the ROM and use nvramtool to change the defaults specified in the ROM; this modified ROM can then be re-flashed. The reason these settings are hardcoded is to ensure consistent behaviour of a given Retroboot ROM image, on a given system (unless the end user changes the default behaviour, and this is documented on the Retroboot website).

The cbmem utility is not currently used by the Retroboot build system, but it is useful for debugging purposes. End users can usually ignore this one.

resources/scripts/build/module/crossgcc

For each and every coreboot directory created by running ./download coreboot in the Retroboot build system, this script goes into said directory and runs the following command:

make crossgcc-i386

This is required for building coreboot ROM images in the Retroboot build system. Coreboot has its own cross-compiler toolchain, which it calls crossgcc and it is compiled by running the above command (in the coreboot build system).

resources/scripts/build/module/flashrom

This script runs make in the flashrom/ directory, which was created when running ./download flashrom in the Retroboot build system.

resources/scripts/build/module/grub

This does not build the actual GRUB payload, which is inserted into coreboot ROM images for configurations that use GNU GRUB bootloader as default payload.

Rather, this script builds the required GRUB utilities when are then executed by running ./build payload grub in the Retroboot build system, to create the GNU GRUB payloads (there are several different GRUB payload configurations, which Retroboot uses for different machine configurations).

GNU GRUB can be compiled for several different systems. On x86, the most common configuration is for BIOS or UEFI and is referred to generically as PC GRUB.

Retroboot compiles GNU GRUB with the following command in GRUB's build system:

./configure --with-platform=coreboot

This is a special build-time configuration. When this configuration is used, GNU GRUB runs on bare metal as a coreboot payload, and does not make use of BIOS or UEFI based services. Several features are present in this version of GRUB, that are not present in other versions. For example, the lscoreboot command becomes available on the GNU GRUB terminal, which displays information about the version of coreboot that is currently running on the end user's machine.

resources/scripts/build/module/memtest86plus

This script runs make in the memtest86plus/ directory, which was created when running ./download memtest86plus in the Retroboot build system.

resources/scripts/build/payload/

These scripts build the payloads (ELF executables) that are inserted into the coreboot ROM images, when built using the Retroboot build system.

resources/scripts/build/payload/grub

This script, using utilities compiled when running ./build module grub in the Retroboot build system, builds several GRUB payloads (ELF executables) and configuration files (for the GRUB payload) and places these files in the payload/grub/ directory.

These files are inserted into coreboot ROM images, when running ./build retroboot roms in the Retroboot build system, if GRUB payload is specified on that platform.

Essentially, there are 2 GRUB configurations per keymap (keyboard layout) supported in the Retroboot build system:

• Config for high resolution VESA framebuffer startup in coreboot
• Config for legacy VGA text mode startup in coreboot

The grub/grub-mkstandalone utility is used, which was built when running ./build module grub in the Retroboot build system. The grub-mkstandalone utility is what creates the ELF executable to then be used in coreboot, as a payload.

It uses the following resources for this:

• GRUB config files in resources/grub/config/
• GRUB keymap layout files in resources/grub/keymap/
• GRUB modules specified in resources/grub/modules.list

Because these files are created seperately, in this manner, you could also use these compiled ELF files in any coreboot ROM, not just ones compiled by the Retroboot build system, in the situation where you built coreboot without inserting a payload. Run the following cbfstool commands. Like so:

NOTE: the build system in Retroboot already does these commands, when building ROM images. The commands below are only examples, for if you built your own coreboot ROM by hand, and wanted to include some payloads in the ROM

For fallback payload in coreboot:

cbfstool coreboot.rom add-payload -f payload/grub/filename.elf -n fallback/payload -c lzma

For normal payload in coreboot:

cbfstool coreboot.rom add-payload -f payload/grub/filename.elf -n normal/payload -c lzma

For normal or fallback payload in coreboot, also do:

cbfstool coreboot.rom add -f payload/grub/filename.cfg -n grub.cfg -t raw

cbfstool coreboot.rom add -f payload/grub/filename_test.cfg -n grubtest.cfg -t raw

The .elf and .cfg must match! E.g. ELF+config for DE Qwertz keymap with legacy VGA text mode startup.

resources/scripts/build/payload/seabios

This script compiles two separate SeaBIOS payloads (ELF executables), using the configuration files stored in resources/seabios/config/:

• resources/seabios/config/libgfxinit
• resources/seabios/config/vgarom

The libgfxinit config specifies that SeaBIOS must use the video initialization in coreboot, which provides a framebuffer interface. For this purpose, SeaBIOS will also compile its own option ROM called SeaVGABIOS, which emulates a Video BIOS for providing legacy VGA support (however, it currently does not support switching between different video modes and INT 10H interrupt services are not completely functional when using this). SeaVGABIOS is useful for several things:

• SYSLINUX/ISOLINUX bootloaders, displayed on a native coreboot framebuffer
• BSD bootloaders, displayed on a native coreboot framebuffer
• Similar use case scenarios versus the above

The vgarom config specifies that SeaBIOS must not build its own Video BIOS option ROM, nor should it provide any video initialization. In this configuration, coreboot itself is loading and execution a Video BIOS option ROM supplied by the manufacturer (e.g. Intel/AMD/Nvidia).

Both configs support all of the standard BIOS functions, which is useful for legacy operating systems. However, INT 10H video interrupt services and especially mode switching are not fully functional when using SeaVGABIOS. They both load and execute PCI option ROMs, load and execute MBR based bootsectors and in general provide a legacy BIOS interface that legacy operating systems can use, such as DOS or old versions of Windows.

If you use the vgarom config, it is assumed that you will inserted a Video BIOS option ROM supplied by the manufacturer of your video chipset, into the coreboot ROM. For example: Intel, Nvidia or AMD/ATI option ROM.

Everything else (besides video initialization) is the same, in both SeaBIOS configs. Which one you use is based on your own needs/preferences.

resources/scripts/build/payload/tianocore

This script is executed when running ./build payload tianocore in the Retroboot build system.

This builds Tianocore UEFI payload. Currently it only builds the x86-64 setup, so this will not currently work on 32-bit only machines such as most T60 thinkpads.

Retroboot does not directly build Tianocore. It uses a dummy coreboot config, and uses the coreboot build system to download Tianocore. The coreboot build system always downloads Tianocore every time you want to build it, but this behaviour is disabled in Retroboot by a custom coreboot patch. Similarly, coreboot always re-builds Tianocore from scratch every time; this behaviour is also disabled.

Retroboot simply uses the Tianocore build script in the coreboot build system, and then the Tianocore payload is available at payload/tianocore/tianocore.elf in the Retroboot build system.

Coreboot's own download function for Tianocore is disabled. Retroboot downloads Tianocore itself, using the coreboot_fb branch from MrChromebox's fork of Tianocore (modified for better compatibility as a coreboot payload).

Planned: build SeaBIOS as CSM for Tianocore. This means that SeaBIOS will run as a UEFI app. The benefit to this setup is that Tianocore provides the option for INT10H video bios interrupt services to work in this setup, when using legacy operating systems (e.g. old Windows versions). Currently, Retroboot only provides a pure Tianocore setup or pure SeaBIOS setup, standalone, but does not provide both at the same time.

resources/scripts/build/retroboot/

resources/scripts/build/retroboot/roms

This script is called when running ./build retroboot roms in the Retroboot build system.

This script builds all ROM images, for all payloads. In earlier versions of Retroboot, separate coreboot configs were specified for each payload but now they are universal. This one script builds every ROM for every payload. In older versions, there were separate scripts for each payload config.

If no argument is given, this script will build ROM images for every board, for every payload. However, you can specify whatever boards you want and it will only build for that (with every payload). For example:

./build retroboot roms x230_4mb x220

If no special argument is given, this script will simply build all ROM images as defined by configuration files in resources/coreboot/*/config/

No actual instructions are contained within this script, for building anything. Instead, this script makes use of a helper script named roms_helper which you can read about in the next section.

Each coreboot image with GRUB payload will appear under the directory at location bin/grub_boardname/ (SeaBIOS and Tianocore are also available to select in the default GRUB menu).

At present, Retroboot only builds withs GNU GRUB as the default payload, with SeaBIOS and Tianocore as an option in the menu (SeaBIOS not yet included as CSM in Tianocore, but rather it is a standalone SeaBIOS setup).

resources/scripts/build/retroboot/roms_helper

This script is not intended to be used directly, but it is called by the script named roms under resources/scripts/build/retroboot/

This script builds ROM images for a single specified board. For example, the script named roms may give x230_4mb as an argument. For the purpose of explaining how this script works, we will assume that x230_4mb is the given argument, where roms runs ./build retroboot roms x230_4mb

This script makes use of the following resources:

• Coreboot source code directory at coreboot/board_name/ where in this example, board_name is x230_4mb.
• Utility cbfstool under coreboot/board_name/util/cbfstool/
• SeaBIOS payload (plus SeaVGABIOS) under payload/seabios/ (the coreboot images are compiled with GNU GRUB bootloader as the main payload, but SeaBIOS is also added and provided as an option in the GNU GRUB boot menu, as a menu option). When used as a coreboot payload, GNU GRUB can boot any other coreboot payload by using the chainloader command. GRUB has many advanced security features, unknown to most people but fully documented on the Retroboot website and we strongly recommend its use as default payload for your setup.
• Tianocore payload under payload/tianocore/
• Coreboot configuration(s) provided for a given board, located at resources/coreboot/board_name/config/
• keymap (keyboard layout) files located at resources/grub/keymap/original/ to know which keymaps are supported and, for each one, this script compiles a coreboot ROM image with its own version of GNU GRUB that uses the given keymap configuration.

The coreboot configuration under resource/coreboot/board_name/config/ can have one of the following file names:

• libgfxinit_txtmode
• libgfxinit_vesafb
• vgarom_txtmode
• vgarom_txtmode

It is not required to have all of these files present. You may choose which combination you would like, when adding new boards to Retroboot or modifying existing ones.

Configs with txtmode in the name are for setups where coreboot initializes the display in legacy VGA text mode, which is useful for legacy operating systems such as DOS, or text mode applications like MemTest86+. It is the most compatible option overall and, if your Video BIOS supports mode switching (which SeaVGABIOS does not, but most vendor option ROMs do), you can switch to higher resolution modes which means that more modern operating systems will show a video display. (NOTE: even with text mode startup, most GNU+Linux distributions and BSD operating systems will still show a video display, because their kernels support Kernel Mode Setting where the kernel itself is controlling video modes, without relying on Video BIOS services; this is standard practise on Intel video chipsets, for example). If you're using a vendor-supplied VGA ROM, it is recommended that you start in text mode as it will be the most compatible setup (in terms of operating system support, especially if you switch to SeaBIOS from the GNU GRUB menu).

Configs with vesafb in the name are for setups where coreboot initializes the display in a high resolution VESA frame buffer. This is useful in some situations, such as when using libgfxinit but if using text mode startup, it's not very important. If you are using SeaVGABIOS, it's recommended to use this setup as it will be the most compatible (with SYSLINUX/ISOLINUX bootloader menus and such).

The libgfxinit_txtmode config is for setups where libgfxinit is used. This is coreboot's own native video initialization, which coreboot provides on a lot of mainboards nowadays. In this setup, a PCI Option ROM for the Video BIOS is not needed because coreboot handles that functionality by itself. Not needed does not mean you won't use one; you may decide (at your own discretion) that you prefer to do so, if you wish. This setup is recommended when you wish to use text mode applications such as MemTest86+ or boot operating systems in text mode, such as FreeDOS (NOTE: FreeDOS will boot just fine on text mode setup with libgfxinit, but will only run text mode applications. Games and such will not work, because libgfxinit does not currently support mode switching)

The libgfxinit_vesafb config is for setups where libgfxinit is used, but you wish to start in a high-resolution VESA framebuffer. This setup is the most compatible, when dealing with GNU+Linux and BSD operating systems while booting the kernel of those operating systems directly from GRUB, without relying on SeaBIOS (which is provided in Retroboot's GRUB menu, an a menu option). It is also the best option for SeaBIOS+SeaVGABIOS, in terms of compatibility; most ISOLINUX/SYSLINUX boot menus will display correctly (loaded from SeaBIOS) in this setup, albeit at a higher resolution (compared to booting from text mode with the vendor VGA ROM, from SeaBIOS) so it might look weird to you at first if you're not used to ISOLINUX/SYSLINUX menus displaying at your monitor's native resolution. This also means that you can use SYSLINUX/ISOLINUX installed to the HDD/SSD on your system (though, this is largely pointless because GNU GRUB does the same things).

In addition, this build script inserts a file into CBFS (coreboot file system, which is a file system inside the coreboot ROM that is installed onto the end user's machine) that specifies a PS/2 keyboard delay; this makes SeaBIOS, when loaded, wait up to three seconds for the PS/2 keyboard to initialize, if present. This works around a potential race condition due to how fast coreboot is capable of booting, which would otherwise prevent the keyboard from being fully initialized, thus leaving you with a non-functioning keyboard (until booting an OS, which would presumably handle initialization on its own).

resources/scripts/download/

The scripts in this directory download the required components that are used in the Retroboot build system.

resources/scripts/download/coreboot

This script is executed when running the following command in the Retroboot build system:

./download coreboot

First, this script checks whether a coreboot/ directory exists. If it does not exist, it is created. If it does exist, it is deleted and then created (to clear what was previously there).

This coreboot/ directory does not actually contain the coreboot Git repository; rather, it is populated with multiple coreboot directories (one for each board, technically, and boards specify which coreboot revision is to be used, but boards in Retroboot can be configured to merely link to another board; this means that, potentially, a single coreboot source code directory could be used for multiple different mainboards so as to reduce waste of system resources during the build process).

For every board defined in resources/coreboot/ a coreboot directory is created from a git clone of the official coreboot Git repository hosted at https://review.coreboot.org/coreboot

If the script fails to download from the above link, it will default to the official backup repository hosted at https://github.com/coreboot/coreboot.git

If both downloads fail (usually this is because your internet is down or not connected), the script will produce an error message and exit with non-zero status.

For each board, a dedicated coreboot source code directory is created, with the .git files/directory from coreboot fully intact and:

• The commit ID is reset to a known coreboot revision, as per what is specified in resources/coreboot/boardname/cbrevision
• Coreboot submodules are downloaded by running git submodule update --init --checkout in the coreboot build system.
• For each submodule, specified in .gitmodules under the coreboot build system, the commit ID is reset to a known revision. This only applies to submodules that exist under 3rdparty/ in the coreboot build system, but a script named extra.sh can be supplied in resources/coreboot/boardname/extra.sh which you can make do whatever you want, including resetting commit IDs in other submodules not located at 3rdparty/ under the coreboot build system.
• For submodules that coreboot downloads into 3rdparty/, the revisions in Retroboot's build system are specified in resources/coreboot/boardname/revision/ by files whose file name matches the directory name of the submodule at 3rdparty/ (under the coreboot build system) and which contain a single line specifying the intended commit ID for use in the Git repository of that submodule (from the coreboot build system).
• Custom patches located in resources/coreboot/boardname/patches/ are applied on top of that coreboot revision. This is useful for patches that are not yet merged in coreboot, or patches that exist in newer versions that you wish to use in an older version.
• Custom patches are only applied (automatically, by the Retroboot build system) to coreboot itself, but you can handle this for coreboot submodules by writing instructions in the extra.sh script located at resources/coreboot/boardname/extra.sh
• The extra.sh script is mainly intended for custom functionality, as a plugin to the Retroboot build system, when you wish to add such functionality when it is not useful for other boards. In cases where such functionality will benefit other boards, it should be implemented in the main build system of Retroboot, rather than inside the extra.sh script.
• Optionally, you can include a file named symlink located at resources/coreboot/boardname/ containing a single line naming another Retroboot board (per directory name in resources/coreboot/). If this file is included, a separate coreboot directory will not be created for the given board that includes the given board. Instead, a symlink will be created under coreboot/ pointing to the actual coreboot directory at coreboot/otherboard where otherboard is the other board. In this setup, the following files are ignored in resources/coreboot/boardname/:
  • cbrevision (specify it in the cbrevision file for the other board)
  • anything under patches/ (place them in the patches/ directory for the other board instead, even if they aren't needed for that board)
  • anything under revision/ (place them in the revision/ directory for the other board instead)
  • extra.sh (write instructions in the extra.sh script for the other board instead, if you wish)

resources/scripts/download/flashrom

This script is executed when running the following command in the Retroboot build system:

./download flashrom

This downloads flashrom from the following Git repository: https://review.coreboot.org/flashrom.git

The commit ID is reset to a known revision, typically a tag for the latest stable release.

The repository is then available under flashrom/ in the Retroboot build system. Everything is self-contained in the script; typically, upstream flashrom is used and right now there are no custom patches in use, so nothing exists in resources/ for flashrom and such is not accounted for by the download script.

resources/scripts/download/grub

This script is executed when running the following command in the Retroboot build system:

./download grub

This downloads GNU GRUB from the following Git repository: git://git.savannah.gnu.org/grub.git

If that fails, the script defaults to this Git repository: http://git.savannah.gnu.org/r/grub.git

If the download fails for whatever reason, for both repository links, the script will produce an error message and exit with non-zero status.

The commit ID is then reset to a known revision. The resulting repository is available at grub/ in the Retroboot build system. Everything is self-contained in the script, and currently no patches are applied.

Since SeaBIOS is also included as an option in GRUB boot menus generated by Retroboot, this script also runs the following command:

./download seabios

resources/scripts/download/me_cleaner

This script is executed when running the following command in the Retroboot build system:

./download me_cleaner

The me_cleaner is downloaded from the official Git repository, hosted at https://github.com/corna/me_cleaner.git

The commit ID is reset to a known revision. Everything is self-contained in this download script.

This utility is not currently used in the Retroboot build system, but a script named meclean is included in the root of the Retroboot Git repository or source code release archive. The script allows you to specify, as argument, as many filenames as you would like and, then, the script will run me_cleaner on a batch of files specified.

The me_cleaner strips out AMT, networking support and many other functions in the Intel ME firmware, while also setting ME Alt Disable and a few other bits in the Intel Flash Descriptor, on a dumped ROM containing the Intel ME, GbE and Flash Descriptor.

The meclean script automatically places the neutered Intel ME firmware under bin/neutered/filename.neutered where filename was the original file name(s) of the ROM dump(s) provided as argument(s) to the meclean script.

Intel ME is, in its default state, a huge security threat and should never be used. In the past, there was no real solution on most platforms that have it. The Retroboot project strongly recommends that you use me_cleaner. It can also be used on systems for which no coreboot support exists, so long as the me_cleaner utility has support for the Intel ME version in use on that machine.

Basically, you dump (using SPI programmer device) the contents of boot flash on your system. You run the dump through me_cleaner and it will produce a heavily modified ROM. How heavily? A 6MiB Intel ME image is reduced to roughly 90KiB of code which merely handles initialization and power management on the target platform.

Read more about me_cleaner here: https://github.com/corna/me_cleaner

NOTE: On some older systems with Intel ME, the firmware can be removed entirely from the boot flash and a few bits can be set in the Intel Flash Descriptor to disable the Intel ME in its entirety. For example, Libreboot supports many GM45 based laptops such as the ThinkPad X200, X200T, T400 and so on; those systems have Intel ME, but can be re-configured to remove the Intel ME firmware and disable it (Libreboot does exactly that).

resources/scripts/download/memtest86plus

This script, using GNU Wget, downloads MemTest86+ and verifies the SHA512 checksum of the file. It then extracts the archive (MemTest86+ project does not host an official Git repository).

It applies custom patches provided in resources/memtest86plus/patch/

The resulting source code is available at memtest86plus/ in the Retroboot build system.

resources/scripts/download/tianocore

This script is executed when running ./download tianocore in the Retroboot build system.

This script downloads Tianocore. It checks out the coreboot_fb branch in MrChromebox's fork of Tianocore; this is a special fork with modifications that make Tianocore work much better as a coreboot payload (MrChromebox himself offers pre-compiled coreboot ROMs for several systems, using Tianocore, and thus his project competes with Retroboot; he's a really good guy btw :)

Tianocore is not downloaded to the main directory in the Retroboot build system. This script assumes that coreboot is already downloaded, using the ./download coreboot command in Retroboot's build system.

This script goes into payloads/external/tianocore/ on the coreboot build system. Coreboot's Makefile for Tianocore is heavily modified so that it:

• Does not automatically download Tianocore. Such functionality is moved to a specific command, called make download
• Does not re-build Tianocore every time

Planned: fully de-couple the coreboot scripts, out of the coreboot file system and, based on them, fully and properly integrate building and downloading of Tianocore in the Retroboot build system. This also implies that Retroboot will have its own toolchain (coreboot's crossgcc build scripts will be forked) because Tianocore's build system is extremely temperamental.

resources/scripts/download/seabios

This script downloads SeaBIOS from the following Git repository: https://git.seabios.org/seabios.git

If the download fails, the script produces an error message and exits with non-zero status.

The script resets SeaBIOS to a known revision, and does not currently apply custom patches on top of SeaBIOS.

resources/seabios/config/

resources/seabios/config/libgfxinit

This is the configuration used for SeaBIOS on coreboot configurations where libgfxinit is used. In this configuration, SeaBIOS also compiles SeaVGABIOS.

SeaVGABIOS is a special option ROM that emulates a Video BIOS, for legacy VGA support, but in fact uses the coreboot framebuffer, on configurations where coreboot does its own native video initialization.

At present, SeaVGABIOS does not fully support INT10H video interrupts and does not properly support mode switching. For example, DOS games (in FreeDOS) will not work. However, SeaVGABIOS supports just enough functionality that, when coreboot starts in high resolution VESA frame buffer mode, ISOLINUX and SYSLINUX bootloader menus will display properly (which makes dealing with GNU+Linux distributions much easier). BSD bootloader menus will probably also display correctly with this configuration.

resources/seabios/config/vgarom

This is the configuration used for SeaBIOS on coreboot configurations where a PCI Option ROM is included in the coreboot ROM, for VGA support. This is used in situations where native video initialization in coreboot is not used and/or unavailable. The PCI Option ROM is, in this configuration, usually supplied by the manufacturer of the video chipset; it is usually extracted from a dump of the original vendor firmware, before coreboot is installed.

Occasionally, this Video BIOS ROM is extracted from memory on a running system.

Occasionally, this Video BIOS ROM is extracted (dumped) from an add-on PCI/PCI-E video card. Normally, SeaBIOS will extract this at boot time but in some situations you will want coreboot to execute it, like when using another payload such as GNU GRUB.