lbwww/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/DEFAULT/blobs.list

For directories in resources/coreboot/ that specify cbrevision, a blobs.list file can be included. When running ./download coreboot, lbmk will delete whatever files are listed in blobs.list for that coreboot tree.

When downloading coreboot, lbmk checks out coreboot 3rdparty submodules, but only does git submodule update --init; on coreboot's side, it is set up so that this doesn't download most of the non-free software that coreboot distributes (for that, you run git submodule --init --checkout (you'll note that the --checkout option is included).

However, some binary blobs still remain even when only doing --init. These are discovered, whenever a new coreboot revision is added to lbmk, by running the linux-libre deblob script on the coreboot source tree, after doing the git submodule update --init command.

See deblob-check from the fsfla website:
https://www.fsfla.org/ikiwiki/selibre/linux-libre/

The deblob-check script in fact does work quite well on the coreboot source tree! However, coreboot is far simpler than the Linux kernel, and much more conservative in its general scope, that the script was never actually forked specifically for Libreboot. Simply speaking, the way deblobbing is handled in Libreboot is as follows:

• Copy the blobs.list from the last deblobbed coreboot revision
• Run deblob-check on the new coreboot revision
• Run deblob-check on the last deblobbed coreboot revision
• Diff the results
• Any file that was deleted on coreboot side, remove from the new blobs.list
• Any new files get added to the new blobs.list

Doing it manually, and in such a crude fashion as this, is perfectly acceptable because coreboot makes a good habit of always separating binary code blobs into completely separate files.

There is some nuance in exactly how Libreboot handles binary blobs. As far as Libreboot is concerned, only software is deleted if a blob. Non-software blobs are retained, so long as they are in a well-understood format or are otherwise trivial. Of course, such data must not be under a non-free license! On the other hand, blobs such as CPU microcode are always to be deleted.

For example: DDR training data is retained. These are data patterns used for memory controller initialization, specifically during training (bruteforcing the precise timings required at boot time).

More nuance: lbmk does not disable any code for loading blobs, but rather, it only deletes the actual blobs. For example, you can still add CPU microcode updates to Libreboot ROM images, and libreboot's version of coreboot will still use them, if present. This has always been the case. Libreboot will never try to prevent you from running blobs; it merely does not include them. This is for the sake of efficiency, because deblobbing is actually only a very minor aspect of what Libreboot is, and time is better spent on other areas of development. Deblobbing is done in the most low-effort way possible, just so as to comply with the GNU Free System Distribution Guidelines.

Of course, deleting blobs from coreboot breaks coreboot, in situations where you actually want to build for a board where those blobs are used, but since those boards are not to be supported in lbmk anyway, it's moot (the boards that lbmk does support will all boot just fine, because all of the required files exist, and are free).

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.

FUN FACT: If you run NODELETE= ./download coreboot, lbmk will skip deleting blobs, and also skip deleting the .git files and directories in those coreboot clones. By default, the Git history is deleted, because it contains blobs. However, you may want to make changes and then create a patch using git format-patch, and you can do just that! Afterwards, you would simply delete the blobs manually and delete the Git history (or you could just run ./download coreboot again, without NODELETE).

resources/grub/background/

Splash screen images applied duing startup when using the GNU 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 GNU GRUB. They are standalone builds, created using the grub-mkstandalone utility.

resources/grub/patches/

This directory contains custom patches for GNU GRUB.

resources/memtest86plus/patch/

This directory contains custom patches for Memtest86+.

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

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 and/or SeaBIOS, 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:

• 4MiB IFD BIOS region will cause only the upper 4MB section of the ROM to be included in a release. This option is largely deprecated, a hangover from osboot, which also no longer uses this option on any boards, and it is thus subject for removal.
• 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.

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.

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/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).

This script should also work with Trisquel 9 and 10.

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/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, patches and deblobs coreboot, as per board.cfg files in resources/coreboot/.

Command: ./download coreboot

resources/scripts/download/flashrom

This downloads and patches flashrom.

Command: ./download flashrom

resources/scripts/download/grub

This downloads and patches GNU GRUB.

Command: ./download grub

resources/scripts/download/ich9utils

This downloads ich9utils, which includes ich9gen.

Command: ./download ich9utils

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/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/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/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.

update

This can be used to update SeaBIOS and coreboot 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