cbwww/site/docs/maintain/index.md

If you wish to know about coreboot, refer here:
https://doc.coreboot.org/tutorial/part1.html

This and other documents from coreboot shall help you to understand coreboot.

You create a config, for resources/coreboot/BOARDNAME/configs, by running the make menuconfig command in the coreboot build system. You should do this after running ./download coreboot in lbmk.

You can simply clone coreboot upstream, add whatever patches you want, and then you can make your config. It will appear afterwards in a file named .config which is your config for inside resources/coreboot/BOARDNAME/.

You can then use git format-patch -nX where X is however many patches you added to that coreboot tree. You can put them in the patches directory under resources/coreboot/BOARDNAME.

The base revision, upon which any custom patches you wrote are applied, shall be the cbrevision entry.

REMINDER: Do not enable a payload in coreboot's build system. Set it to none, and enable whatever payload you want in lbmk.

If a payload is not supported in lbmk, patches are very much welcome! It is the policy of libreboot, to only ever use the coreboot build system inside coreboot, but not use any of coreboot's own integration for payloads. It is far more flexible and robust to handle payloads externally, relative to the coreboot build system.

Scripts exist in lbmk for automating the modification/updating of existing configs, but not for adding them. Adding them is to be done manually, based on the above guidance.

ALSO:

If the option exists, for a given board, please configure coreboot to clear all DRAM upon boot. This is for security reasons. An exception is made when such functionality is not available, on the specific board/revision that you're configuring in coreboot.

resources/coreboot/BOARDNAME/patches/*

In cases where cbrevision is specified, where the given directory under resources/coreboot/ does in fact define a version of coreboot to download, you can add custom patches on top of that revision. When you run the command ./download coreboot, those patches will be applied chronologically in alphanumerical order as per patch file names.

The patch files should be named with .patch file extensions. All other files will be ignored. By having lbmk do it this way, you could add a README file for instance, and lbmk will not erroneously try to apply README as though it were a patch file. This might be useful if you have a lot of patches, and you want to provide some explanations about specific files.

resources/git/revisions

This defines git repositories and commit IDs (revisions) to reset to, for various projects used by Libreboot. This file is used, for projects that are relatively simple to handle when downloading (coreboot is not defined here).

In the past, Libreboot had bespoke logic for each program, to download it. This was repetitive, so much of the download logic was centralised with the use of the gitclone script, which references this file.

resources/grub/background/

Splash screen images applied duing startup when using the GRUB payload.

resources/grub/config/grub.cfg

This is a configuration file. It is used to program GRUB's shell.

This is inserted (as grub.cfg) into the root of CBFS, in the ROM image. It contains a lot of logic in it, for booting various system configurations, when the GRUB payload is in use.

resources/grub/config/grub_memdisk.cfg

This is a configuration file. It is used to program GRUB's shell.

This file is inserted (as grub.cfg) into the GRUB memdisk, when building the GRUB payload (for coreboot), using GRUB's grub-mkstandalone utility. It simply loads the grub.cfg file from CBFS (see above).

resources/grub/keymap/

This directory contains keymaps for GRUB. They allow for different keyboard layouts to be used. The lbmk build system uses these to produce ROM images with various keyboard layouts used by default, when the GRUB payload is to be used.

They are stored here, directly in GRUB's own .gkb file format, which is a binary format defining which scancodes correspond to which character input.

This binary format is documented by GRUB; the code for it is easy to understand. Please read grub-core/commands/keylayouts.c in the GRUB source code.

resources/grub/modules.list

This file defines all modules that are to be included in builds of GRUB. They are standalone builds, created using the grub-mkstandalone utility.

resources/grub/patches/

This directory contains custom patches for GRUB.

resources/me_cleaner/patches

Patches applied to me_cleaner when downloading it.

resources/memtest86plus/patches/

Patches applied to Memtest86+ when downloading it. Libreboot includes memtest86+ as a secondary payload, loaded from SeaBIOS or GRUB when booted via int10h text mode on x86 hosts.

(using it with corebootfb mode is also possible, if your machine has a viable serial output on it with memtest86+ configured accordingly, and this was done on some older Libreboot releases in the past, but current Libreboot releases only provide memtest86+ in text mode, for use directly on the machine)

resources/scripts/

These scripts implement the core logic of Libreboot's automated build system, to produce coreboot ROM images with payloads.

resources/scripts/build/

This directory contains shell scripts for compiling various binaries from available sources.

resources/scripts/build/boot/

This directory contains shell scripts for compiling ROM images. Many other scripts in lbmk are called by these scripts; for example, GRUB payload scripts.

resources/scripts/build/boot/roms

This script builds coreboot ROM images. It is largely a shim, which calls the roms_helper script, which does most of the legwork.

Command: ./build boot roms

Additional parameters can be provided. This lists all boards available:

./build boot roms list

Pass several board names if you wish to build only for specific targets. For example:

./build boot roms x60 x200_8mb

Since November 2022, this script can build images for x86 and ARM targets. The ARM targets are ChromeOS devices (chromebooks and such); Libreboot uses the U-Boot payload, rather than Google's depthcharge bootloader. In this setup, U-Boot is running on the bare metal, as enabled by coreboot.

For x86 targets, these scripts build with the GRUB and/or SeaBIOS payloads inserted into the ROM images; secondary payloads like Memtest86+ are also handled and inserted here.

resources/scripts/build/boot/roms_helper

This script builds coreboot ROM images. It is not to be executed directory; user interaction must be done via the main roms script.

It heavily makes use of the board.cfg file, for a given board. This script will only operate on a single target, from a directory in resources/coreboot/.

If grub_scan_disk is set, it sets that in the grub.cfg file that is to be inserted into a ROM image, when payload_grub is turned on.

It automatically detects if crossgcc is to be compiled, on a given coreboot tree (in cases where it has not yet been compiled), and compiles it for a target based on the arch entry in board.cfg.

It creates ROM images with GRUB, SeaBIOS, U-Boot, optionally with Memtest86+ also included, in various separate configurations in many different ROM images for user installation.

The romtype entry in board.cfg tells this script what to do with the ROM, after it has been built. Currently, it operates based on these possible values for romtype:

• d8d16sas will cause fake (empty) files named pci1000,0072.rom and pci1000,3050.rom to be inserted in CBFS. This prevents SeaBIOS from loading or executing the option ROM stored on PIKE2008 modules, present on certain configurations with the ASUS KCMA-D8 or KGPE-D16 mainboards. Those option ROMs cause the system to hang, so they should never be executed (this means however that booting Linux kernels from SAS devices is impossible on those boards, unless a Linux payload is used; Linux can use those SAS drives, without relying on the PIKE2008 option ROMs). When SeaBIOS runs, it will default to loading the corresponding option ROM from CBFS, if it exists, for a given PCI device, overriding whatever option ROM is present on the device itself, but if the option ROM is invalid/empty, SeaBIOS will not attempt to load another one, until the empty/invalid one (in CBFS) is deleted.
• 4MiB ICH9 IFD NOR flash: the ich9gen program will be used to insert an Intel Flash Descriptor and Gigabit Ethernet Non-volatile memory file into the ROM image. This is used on GM45/ICH9M based laptops, such as: ThinkPad X200, T400, T500, W500, X200 Tablet, X200S, T400S, X301
• 8MiB ICH9 IFD NOR flash: Same as the 4MB one as described above, but for ROM images with 8MB (64Mbit) of boot flash. The one above is for systems with 4MB (32Mbit) of flash.
• 16MiB ICH9 IFD NOR flash: ditto, but for 16MB (128Mbit) flash. In this and the other two cases as described above, the first 4KB is the Intel Flash Descriptor, the next 8KB is GbE NVM and the rest is BIOS (for the coreboot part). In all cases, the default ME (Intel Management Engine) region is disabled, as is the ME itself, based on bits set to disable it in the Intel Flash Descriptor. The descriptor is used in such a setup, because on all such boards in libreboot, GbE NVM is needed to get gigabit ethernet working correctly; it is the sole reason ich9gen was written, because it is otherwise possible to boot these machines in a descriptorless setup, where ICH9M behaves similarly to ICH7: all one region of flash, for the boot firmware (coreboot), but it results in a non-functional gigabit enternet device.
• 4MiB ICH9 IFD NOGBE NOR flash: Intel Flash Descriptor on its own, without ME or GbE NVM. Just IFD and BIOS. This is used on the ThinkPad R500.
• 8MiB ICH9 IFD NOGBE NOR flash: Same as above, but for 8MB (64Mbit) ROMs
• 16MiB ICH9 IFD NOGBE NOR flash: Same as above, but for 16MB (128Mbit) ROMs
• i945 laptop: in this configuration, the upper 64KB section of the ROM is copied into the 64KB section below that. This results in there being two bootblocks in the ROM, and you can decide which one is used by setting bucts

If no payload is defined in board.cfg, the roms_helper script will exit with error status.

If SeaBIOS is to be used, on libgfxinit setups, SeaVGABIOS will also be inserted. This provides a minimal VGA compatibility layer on top of the coreboot framebuffer, but does not allow for switching the VGA mode. It is currently most useful for directly executing ISOLINUX/SYSLINUX bootloaders, and certain OS software (some Windows setups might work, poorly, depending on the board configuration, but don't hold your breath; it is far from complete).

If SeaBIOS is to be used, in vgarom setups or normal setups, SeaVGABIOS is not inserted and you rely on either coreboot and/or SeaBIOS to execute VGA option ROMs.

In all cases, this script automatically inserts several SeaBIOS runtime configurations, such as: etc/ps2-keyboard-spinup set to 3000 (PS/2 spinup wait time), etc/pci-optionrom-exec set to 2 (despite that already being the default anyway) to enable all option ROMs, unless vgarom setups are used, in which case the option is set to 0 (disabled) because coreboot is then expected to handle option ROMs, and SeaBIOS should not do it.

This script handles U-Boot separately, for ARM-based chromeos devices.

Essentially, the roms_helper script makes use of each and every part of lbmk. It is the heart of libreboot.

When the ROM is finished compiling, it will appear under a directory in bin/

resources/scripts/build/clean/cbutils

This simply runs make clean on various utilities from coreboot, which lbmk makes use of.

Command: ./build clean cbutils

resources/scripts/build/clean/crossgcc

This runs make crossgcc-clean on all of the coreboot revisions present in lbmk.

Command: ./build clean crossgcc

resources/scripts/build/clean/flashrom

This runs make clean in the flashrom/ directory.

Command: ./build clean flashrom

resources/scripts/build/clean/grub

This runs make clean in the grub/ directory.

It does not delete anything in payload/grub/.

Command: ./build clean grub

resources/scripts/build/clean/ich9utils

This runs make clean in the ich9utils/ directory.

Command: ./build clean ich9utils

resources/scripts/build/clean/memtest86plus

This runs make clean in the memtest86plus/ directory.

Command: ./build clean memtest86plus

resources/scripts/build/clean/payloads

This deletes the payload/ directory.

Command: ./build clean payloads

resources/scripts/build/clean/rom_images

This deletes the bin/ directory, containing compiled coreboot ROM images.

Command: ./build clean rom_images

resources/scripts/build/clean/seabios

This runs make clean in the seabios/ directory.

Command: ./build clean seabios

resources/scripts/build/clean/u-boot

This runs make distclean and git clean -fdx on all of the U-Boot revisions present in lbmk.

Command: ./build clean u-boot

resources/scripts/build/dependencies/arch

Using pacman, this installs build dependencies in Arch. It may also work on similar distros like Manjaro or Artix.

Command: ./build dependencies arch

resources/scripts/build/dependencies/debian

Using apt-get, this installs build dependencies in Debian. It may work on other apt-get distros.

Command: ./build dependencies debian

resources/scripts/build/dependencies/fedora35

Using dnf, this installs build dependencies in Fedora 35.

Command: ./build dependencies fedora35

resources/scripts/build/dependencies/ubuntu2004

Using apt-get, this installs build dependencies for Ubuntu 20.04 (for later versions, you might use the Debian script).

Command: ./build dependencies ubuntu2004

resources/scripts/build/dependencies/void

Using xbps, this installs build dependencies for Void.

Command: ./build dependencies void

resources/scripts/build/descriptors/ich9m

This runs ich9gen to generate descriptors for ICH9M platforms. These are then stored in descriptors/ich9m/

Command: ./build descriptors ich9m

resources/scripts/build/module/cbutils

This compiles various coreboot utilities (such as cbfstool).

Command: ./build module cbutils

resources/scripts/build/module/flashrom

This compiles flashrom.

Command ./build module flashrom

resources/scripts/build/module/grub

This compiles GRUB utilities. It does not build the actual payloads.

Command: ./build module grub

resources/scripts/build/module/ich9utils

This compiles ich9utils, which includes the ich9gen utility.

Command: ./build module ich9utils

resources/scripts/build/module/memtest86plus

This compiles Memtest86+.

Command: ./build module memtest86plus

resources/scripts/build/payload/grub

This builds the GRUB payloads.

Command: ./build payload grub

resources/scripts/build/payload/seabios

This builds the SeaBIOS payloads.

Command: ./build payload seabios

resources/scripts/build/payload/u-boot

This builds the U-Boot payloads. Usually a target board and a cross-compiler appropriate for the board must be specified for it to work, because trying to build for all boards of varying architectures using only the host compiler will not work.

Command: CROSS_COMPILE=aarch64-gnu-linux- ./build payload u-boot qemu_arm64_12mb

resources/scripts/build/release/roms

This builds release archives, containing ROM images. You must only run this after you've built all of the ROM images that you wish to release.

Command: ./build release roms

resources/scripts/build/release/src

This builds source archives. You must only run this after compiling crossgcc on all coreboot source trees.

Command: ./build release src

resources/scripts/download/coreboot

This downloads, and patches coreboot, as per board.cfg files in resources/coreboot/.

Command: ./download coreboot

NOTE: This version of the script also performs the full git checkout in each coreboot tree, like so:

git submodule update --init

NOTE: --checkout is excluded, because such exclusion skips a lot of blobs during submodule update. This saves work for the project.

resources/scripts/download/flashrom

This downloads and patches flashrom.

Command: ./download flashrom

resources/scripts/download/grub

This downloads and patches GRUB.

Command: ./download grub

resources/scripts/download/memtest86plus

This downloads and patches Memtest86+.

Command: ./download memtest86plus

resources/scripts/download/seabios

This downloads and patches SeaBIOS.

Command: ./download seabios

resources/scripts/download/u-boot

This downloads, and patches U-Boot, as per board.cfg files in resources/u-boot/.

Command: ./download u-boot

resources/scripts/misc/versioncheck

This updates the text file containing version information. It is used by many other build scripts. It also updates the files containing the version date.

You need not run this yourself, directly.

resources/scripts/modify/coreboot/configs

Loads coreboot configs into coreboot trees, and runs make menuconfig, so that you can easily modify them in an ncurses interface. Additional parameters are accepted, for example:

./modify coreboot configs x60 x200_8mb

With no additional parameters given, it simply cycles through all configs under resources/coreboot/.

Command: ./modify coreboot configs

resources/scripts/modify/seabios/configs

This lets you modify SeaBIOS configs.

Command: ./modify seabios configs

resources/scripts/modify/u-boot/configs

Loads U-Boot configs into U-Boot trees, and runs make menuconfig, so that you can easily modify them in an ncurses interface. Additional parameters are accepted, for example:

./modify u-boot configs gru_kevin gru_bob

With no additional parameters given, it simply cycles through all configs under resources/u-boot/.

Command: ./modify u-boot configs

resources/scripts/update/coreboot/configs

This runs make oldconfig on coreboot configs under resources/coreboot/. It is most useful when updating a coreboot revision, per board.cfg. It allows additional parameters, for example:

./update coreboot configs x60 x200_8mb

With no additional parameters given, it simply cycles through all configs under resources/coreboot/.

Command: ./update coreboot configs

resources/scripts/update/seabios/configs

This runs make oldconfig on SeaBIOS configs. It is most useful when updating the version of SeaBIOS used by lbmk.

Command: ./update seabios configs

resources/scripts/update/u-boot/configs

This runs make oldconfig on U-Boot configs under resources/u-boot/. It is most useful when updating a U-Boot revision, per board.cfg. It allows additional parameters, for example:

./update u-boot configs gru_kevin gru_bob

With no additional parameters given, it simply cycles through all configs under resources/u-boot/.

However, using make oldconfig is not optimal for U-Boot, as their Kconfig dependencies/defaults are not as well specified as coreboot's is. When updating configs for an upstream board, it's usually better (but not automated) to:

• Turn lbmk config into a defconfig in the old version
• Compare it with the old version's upstream defconfig
• Apply the difference to the new version's upstream defconfig
• Create an updated config in the new version

Command: ./update u-boot configs

resources/seabios/config/libgfxinit

SeaBIOS configuration file, when libgfxinit is to be used. It enables the coreboot linear framebuffer option in the SeaBIOS make menuconfig configuration interface.

resources/seabios/config/vgarom

This version is for normal SeaBIOS configurations, where libgfxinit is not to be used; coreboot itself handles VGA ROM initialisation.

resources/seabios/config/normal

This version is for normal SeaBIOS configurations, where libgfxinit is not to be used; coreboot itself does not handle VGA ROM initialisation, and it is assumed that SeaBIOS payload will be used in text mode. In this setup, SeaBIOS executes VGA ROMs.

resources/seabios/patches/

This directory contains patch files, automatically applied to SeaBIOS after downloading it.

update

This can be used to update SeaBIOS, coreboot and U-Boot configs. It calls scripts in resources/scripts/update/, for example:

./update coreboot configs

This runs:

./resources/scripts/update/coreboot/configs

Additional parameters can be given, for example:

./update coreboot configs x200_8mb x60

This would run:

./resources/scripts/update/coreboot/configs x200_8mb x60

resources/u-boot/

This directory contains configuration, patches and so on, for each mainboard that can use U-Boot as a payload in the lbmk build system. U-Boot doesn't yet have reliable generic configurations that can work across all coreboot boards (per-architecture), so these are used to build it per-board.

resources/u-boot/BOARDNAME/

Each BOARDNAME directory defines configuration for a corresponding mainboard. It doesn't actually have to be for a board; it can also be used to just define a U-Boot revision, with patches and so on. To enable use as a payload in ROM images, this must have the same name as its resources/coreboot/BOARDNAME/ counterpart.

resources/u-boot/BOARDNAME/board.cfg

This file can contain several configuration lines, each being a string, such as:

• ubtree="default" (example entry)
• ubrevision="4debc57a3da6c3f4d3f89a637e99206f4cea0a96" (example entry)
• arch="AArch64" (example entry)

These are similar in meaning to their coreboot counterparts.

The ubtree entry is actually a link, where its value is a directory name under resources/u-boot. For example, ubtree="default" would refer to resources/u-boot/default and the corresponding U-Boot source tree created (when running ./download u-boot, which makes use of board.cfg) would be u-boot/default/. In other words: a board.cfg file in resources/u-boot/foo might refer to resources/u-boot/bar by specifying ubtree="bar", and the created u-boot source tree would be u-boot/bar/. ALSO:

FUN FACT: such references are infinitely checked until resolved. For example, foo can refer to bar and bar can refer to baz but if there is an infinite loop, this is detected and handled by lbmk. For example, if bar refers to foo which refers back to bar, this is not permitted and will throw an error in lbmk.

The ubrevision entry defines which U-Boot revision to use, from the U-Boot Git repository. At present, lbmk only supports use of the official repository from the upstream U-Boot project.

The arch entry specifies which CPU architecture is to be used: currently recognized entries are x86_32, x86_64, ARMv7 and AArch64. Setting it to a non-native arch means that necessary crossgcc-arch will be compiled and be available when building roms, but not necessarily built or discovered when individual scripts are called manually.

resources/u-boot/BOARDNAME/config/*

Files in this directory are U-Boot configuration files. Configuration file names can be anything, but for now default is the only one used.

In lbmk, a board-specific directory under resources/u-boot/ should never specify a U-Boot revision. Rather, a directory without U-Boot configs should be created, specifying a U-Boot revision. For example, the directory resources/u-boot/default/ specifies a U-Boot revision. In the board-specific directory, your board.cfg could then specify ubtree="default" but without specifying a U-Boot revision (this is specified by resources/u-boot/default/board.cfg).

Normally, the U-Boot build process results in the U-Boot executable and a device-tree file for the target board, which must further be packaged together to make things work. When you create a U-Boot configuration, you should enable CONFIG_REMAKE_ELF or CONFIG_OF_EMBED that handles this. The former option enables creation of a u-boot.elf that bundles them together after the build, and the latter option embeds it into the u-boot executable.

When making a U-Boot configuration, you should also pay special attention to the CONFIG_SYS_TEXT_BASE (CONFIG_TEXT_BASE in later versions), whose defaults may cause it to overlap coreboot, in which case it won't boot. Normally, the upstream coreboot build system checks for this when given CONFIG_PAYLOAD_ELF, but lbmk injects the payload itself and doesn't check for this yet.

Another interesting config option is CONFIG_POSITION_INDEPENDENT for ARM boards, which has been so far enabled in the ones lbmk supports, just to be safe.

U-Boot build system

If you wish to know about U-Boot, refer here:
https://u-boot.readthedocs.io/en/latest/

This and other documents from U-Boot shall help you to understand U-Boot.

You create a config, for resources/u-boot/BOARDNAME/configs, by finding the corresponding board name in the upstream U-Boot configs directory, and running make BOARDNAME_defconfig and make menuconfig commands in the U-Boot build system. You should do this after running ./download u-boot in lbmk.

You might want to consider basing your config on the upstream coreboot boards when possible, but such a board is not available upstream for ARM yet.

You can simply clone U-Boot upstream, add whatever patches you want, and then you can make your config. It will appear afterwards in a file named .config which is your config for inside resources/u-boot/BOARDNAME/.

You can then use git format-patch -nX where X is however many patches you added to that U-Boot tree. You can put them in the patches directory under resources/u-boot/BOARDNAME.

The base revision, upon which any custom patches you wrote are applied, shall be the ubrevision entry.

Scripts exist in lbmk for automating the modification/updating of existing configs, but not for adding them. Adding them is to be done manually, based on the above guidance.

resources/u-boot/BOARDNAME/patches/*

In cases where ubrevision is specified, where the given directory under resources/u-boot/ does in fact define a version of U-Boot to download, you can add custom patches on top of that revision. When you run the command ./download u-boot, those patches will be applied chronologically in alphanumerical order as per patch file names.

The patch files should be named with .patch file extensions. All other files will be ignored. By having lbmk do it this way, you could add a README file for instance, and lbmk will not erroneously try to apply README as though it were a patch file. This might be useful if you have a lot of patches, and you want to provide some explanations about specific files.

util/

This directory contains utilities that lbmk makes use of.

util/nvmutil/

The nvmutil software allows you to set the MAC address on Intel GbE NVM files. It also allows you to set random MAC addresses, in addition to arbitrary ones.

This directory contains the source code for nvmutil, which you can read about here:

nvmutil manual

util/ich9utils/

The ich9utils utilities handle ICH9M Flash Descriptors, and GbE NVM configs for Intel Gigabit Ethernet chipsets used on certain laptops of Intel GM45 platform, combined with ICH9M southbridge.

This directory contains the source code for ich9utils, which you can read about here:

ich9utils manual

This source code also pertains to ich9gen, which is what GM45 laptops in Libreboot use in order to generate a config that excludes Intel ME firmware.

Patches welcome.

If you read this manual from start to finish, you've been assimilated. Welcome to the team!