lbwww/site/docs/maintain/index.md

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

In addition to this manual, you should also refer to [porting.md](porting.md)
and [testing.md](testing.md).

Please also read about the [lbmk coding style and design](style.md).

Automated coreboot build system
===============================

This document describes the entire Libreboot build system, its design philosophy
and how it's used to prepare Libreboot releases; it is provided as a *reference*
for *Libreboot development*, pertaining to the current development branch of
Libreboot's build system (called *lbmk*).

The homepage of Libreboot says that Libreboot is a *coreboot distro*, providing
the necessary integration of coreboot, payloads and utilities so as to provide
releases, much like Linux distros do for your operating system, but here we are
concerned about the *boot firmware* instead. Libreboot is to coreboot, what
Debian is to Linux. It provides easier, more automated configuration and
installation.

The build system, lbmk, *is* that coreboot distro, at its very core. You can
basically think of it as a package manager; it is even a *source-based* package
manager. If you simply want to build ROM images, refer instead to the [basic
build instructions](../build/).

This build system, lbmk, is completely automated in every way. It is designed
to take care of itself; so long as build dependencies are installed, it will
check itself when running *any* command; if another command had to be executed
first, it will do so automatically. Therefore, you can run any part of lbmk
on its own, and the entire design is modular.

Best practises for learning lbmk
================================

The follow sections will cover subdirectories, within lbmk. Contrary to what
some may otherwise assume, it's best to learn about everything *except* scripts
or code within Libreboot, first. No, you should first learn about config files
used in the Libreboot build system, and *then* learn about the logic. By doing
it in this order, you will have greater context later when reading about those
scripts. Learning about each upstream project (such as coreboot) will also be
useful; check documentation provided by each project.

After learning about configuration, you will then read about files and
directories generated by the build system; only *then* will this document
describe each script or program that forms part of the build system. In other
words, this document adopts a *top-down* approach to education, rather than
bottom-up; most documents take the latter approach, in other projects, but
most people naturally want to learn how a specific thing works first, hence
the approach taken here.

Don't be deceived by simplicity
-------------------------------

Libreboot's build system is powerful, and highly configurable, yet deceptively
simple at the same time. Remember this rule, a rule that applies to *all*
software projects: code equals bugs, so smaller codebases will yield fewer bugs.
Libreboot is [regularly](../../news/audit.md) [audited](../../news/audit2.md).

Many people will be shocked by how *small* Libreboot is, at its core. You will
be surprised by just how much can be done with so little. Continue reading!

libreboot blob reduction policy
============================

The coreboot software is nominally free, but it requires additional binary
blobs on many supported systems. These *blobs* lack source code, and the
coreboot project does not control them, but they can be used to perform
specific initialization tasks.

The libreboot project *allows* binary blobs from coreboot, but there is *still* a
lot of nuance to precisely what is allowed. It is important that you understand
these nuances, when working on *libreboot*.

[Please read the blob reduction guidelines](../../news/policy.md) and also
the [freedom status page](../../freedom-status.md).

Before *configuration* info, you will first be shown a brief overview of every
project that Libreboot imports, such as coreboot.

Projects/files downloaded/generated by lbmk
===========================================

The following sections will describe files and directories that are not
included in `lbmk.git`, but *are* created by running various lbmk commands;
many of these will also be provided, pre-generated, under release archives.

Some of these are *downloaded* by Libreboot's build system, automatically, while
others are created during the build process based on these downloaded programs.

bin/
---------------

This directory is created when running any of the following commands, with the
right arguments:

	./build fw coreboot ARGUMENTS_HERE
	./build fw serprog stm32
	./build fw serprog rp2040

Simply speaking, `bin/` shall contain finished ROM images or firmware, that
can then be installed (flashed) to the target device.

The files under `bin/` are provided in regular Libreboot releases.

bios\_extract/
---------------

Used by the blob handler scripts. The upstream that we use is here:
<https://review.coreboot.org/bios_extract>

Specifically: the pfs extract utility from this is used on Dell vendor updates,
to extract SCH5545 EC (Environment Control) firmware.

biosutilities/
---------------

Used by the blob handler scripts. The upstream that we use is here:
<https://github.com/platomav/BIOSUtilities>

The `dell_inspiron_1100_unpacker.py` script is used here, to extract from Dell
BIOS updates, to get at the VGA ROM for Nvidia GPU on certain models of Dell
Latitude E6400.

blobs/
---------------

Used by the blob handler scripts, referenced in certain coreboot configs.

Certain binary blobs such as Intel ME or SCH5545 EC firmware are downloaded
here; not all blobs are downloaded here however, as some are handled under
separate directories.

cbutils/
---------------

The build system compiles `cbfstool` and `ifdtool`, from coreboot, and then
places the executables here for use on coreboot ROM images.

coreboot/
---------------

Please also visit: <https://coreboot.org/>

Coreboot is the main boot firmware, providing hardware initialisation. Libreboot
makes extensive use of coreboot, on supported mainboards.

Coreboot trees go here. Libreboot's build system does not simply use one tree,
or multiple branches in the same tree; entirely separate directories are
created, for each revision of coreboot used, each able to have its own patches.
These can then be re-use appropriately, per mainboard. For example:

* `src/coreboot/default` is used by most mainboards.
* `src/coreboot/cros` is used by cros devices.

This may be less efficient on disk usage, but it simplifies the logic greatly.
Coreboot also uses its own toolchain called *crossgcc*, and crossgcc is in fact
compiled *per tree* in Libreboot.

ec/
---------------

KBC1126 EC firmware goes here, required on HP EliteBook laptops. These images
are inserted into those coreboot images, under `elf/` *and* `bin/`.

elf/
---------------

Compiled binaries (compiled by lbmk) go here, but they are not the final
binaries; coreboot ROM images are compiled without payloads, then cached here
under `elf/coreboot` as one example; ditto GRUB and SeaBIOS which go
under `elf/grub` and `elf/seabios` respectively - `elf/u-boot` is another
example.

Binaries under `elf/` are compiled first, which lbmk then uses to generate
the files under `bin/`; the latter files under `bin/` are intended for
installation by the user.

It is technically possible to re-use these files elsewhere. For example, you
may wish to only compile GRUB with lbmk, and then use the `grub.elf` file from
lbmk in your own custom coreboot ROM (that you didn't build with lbmk).

This is only used by the build system, but these images are *not* provided in
releases (only the images under `bin/` are provided).

flashrom/
---------------

Please also visit: <https://flashrom.org/>

Although currently unused by any part of lbmk, we provide flashrom for the
convenience of users, and this is copied to release archives. Flashrom is the
program that you will use to read, erase and write the flash, containing
coreboot firmware.

grub/
---------------

Please also visit: <https://www.gnu.org/software/grub/>

The GNU GRUB bootloader, a reference multiboot implementation with its own
small kernel/OS and drivers (e.g. file systems, cryptography). This is the
default recommended [coreboot payload](https://doc.coreboot.org/payloads.html)
on x86-based Libreboot systems. GRUB will load and execute your Linux kernel,
which then runs on the bare metal.

The *utilities* for GRUB are compiled here, and used from here; specifically,
the `grub-mkstandalone` utility is executed from here to create the final
GRUB image under `elf/grub/`.

NOTE: This is *only* provided for x86 machines, in Libreboot. For ARM, we ship
U-Boot instead.

me\_cleaner/
---------------

Please also visit: <https://github.com/corna/me_cleaner/>

This is used by Libreboot, to *neuter* Intel ME images. The intel ME images
are auto-downloaded from the vendor during each build process, cached on
disk and processed by `me_cleaner`. It removes almost all code from Intel ME,
leaving only the basic bringup code (analogous to running coreboot without a
payload). More information available at these pages:

* <https://github.com/corna/me_cleaner/>
* Libreboot [freedom status page](../../freedom-status.md)

The *blob* scripts are what handle this, specifically the download script
located at `script/update/blobs/download`.

memtest86plus/
---------------

Please also visit: <https://www.memtest.org/>

This is provided inside ROM images, as a payload executed from main GRUB or
SeaBIOS payload. It checks for corrupted memory.

mrc/
---------------

Please also
visit: <https://doc.coreboot.org/northbridge/intel/haswell/mrc.bin.html> - the
handling of this, in Libreboot, is based largely on the information there.

This contains the Intel MRC blob, auto-downloaded during build
by `script/update/blobs/mrc`, called by the user directly or
by `script/update/blobs/download`. This provides raminit and peripheral
init on certain Haswell and Broadwell platforms.

In some cases, libre MRC firmware is also available, and provided
by Libreboot as an alternative choice.

pciroms/
---------------

PCI Option ROMs, currently used only for the VGA ROM on models of Dell Latitude
E6400 containing an Nvidia GPU; it provides video initialisation, where coreboot
currently only initialises Intel GPUs natively, on Libreboot systems.

release/
---------------

The scripts under `script/build/release/` create tar archives in here, which
constitute regular Libreboot releases. It is meticulously maintained, as per
current lbmk behaviour, and executed so as to provide Libreboot release
archives.

This provides source tarballs, and ROM images for example; however, ROM images
containing non-redistributable blobs are *scrubbed* such that those blobs must,
in regular releases, be [re-added manually](../install/ivy_has_common.md) by
the user.

seabios/
---------------

Please also visit: <https://www.seabios.org/SeaBIOS>

This is the PC BIOS implementation used by Libreboot, on x86 machines (not all
of them). A BIOS/UEFI implementation is not required, because Linux and BSD
kernels can execute on bare metal, but it can nonetheless still be useful; in
particular, the BSD bootloaders can be executed from SeaBIOS.

This is provided as a coreboot payload, either as first payload or it can be
executed from GRUB (if GRUB is the main payload, on a given target).

tmp/
---------------

The `TMPDIR` environmental variable is set by lbmk, to a location under `/tmp`,
but some users may have `/tmp` mounted as a *tmpfs* (file system in RAM), and
may not have much RAM.

Where large files (or a large number of files) are handled by lbmk on a
temporary basis, this `tmp/` directory is created and then used.

u-boot/
---------------

Please also visit: <https://www.denx.de/project/u-boot/>

This is a bootloader provided on ARM chromebooks, within Libreboot. It also
provides UEFI. Information about that can be found on these resources:

* [U-Boot documentation](../u-boot/)
* [Chromebook documentation](../install/chromebooks.md)

This is currently the only payload on *ARM* systems, within Libreboot.

uefitool/
---------------

Please also visit: <https://github.com/LongSoft/UEFITool>

This is compiled, so as to provide `UEFIExtract`. Currently used by the
blob download script at `script/update/blobs/download`, to download SCH5545 EC
firmware (used for fan control on Dell Precision T1650).

util-fw/rp2040/pico-serprog
---------------------------

Used by lbmk, to build firmware for serprog-based SPI flashers with RP2040 SoC.
Alongside this, `util-fw/rp2040/pico-sdk` is imported which is required for
building it.

Please visit these pages:

* <https://github.com/raspberrypi/pico-sdk>
* <https://codeberg.org/libreboot/pico-serprog>

util-fw/stm32-vserprog
----------------------

Used by lbmk, to build firmware for serprog-based SPI flashers with STM32 MCU.
Alongside this, `libopencm3` is imported which is required for building it.

* <https://codeberg.org/libreboot/stm32-vserprog>
* <https://github.com/libopencm3/libopencm3>

These serprog programmers are quite desirable, owing to their low cost and ease
of use. You can learn more on the [SPI flashing guide](../install/spi.md).

Before moving onto configurations, we will now cover *utilities* provided by
Libreboot itself (included within lbmk, rather than being downloaded like the
third party projects listed above):

util/
===============

Not to be confused with `util-fw/`!

If a codebase is not frequently used by Libreboot, is actively developed (making
it not viable to maintain in Libreboot) or the codebase is very large, we would
import that as a third party module in lbmk - this rule exists for all projects,
where the intention is that `lbmk.git` itself should be small and efficient.

Where appropriate, and where the code is small enough, or it is otherwise deemed
desirable, `lbmk.git` provides a few utilities as part of itself, namely:

util/e6400-flash-unlock/
---------------

This program, written by Nicholas Chin, unlocks the boot flash on Dell Latitude
E6400; it permits internal flashing, from factory firmware to Libreboot, so that
the user need not disassemble and flash externally.

util/me7\_update\_parser/
---------------

This is a special fork of `me_cleaner`, specifically for parsing and neutering
Intel ME images provided by Lenovo for ThinkPad X220 and other Lenovo
ThinkPads of Intel SandyBridge platform. You can find information about this
on the original repository:

<https://github.com/Thrilleratplay/me7_update_parser>

ME7 Update Parser was originally written for *Heads*, another coreboot distro
very similar to Libreboot that provides coreboot build automation with Linux
based payload configurations. *Their* build system auto-downloads and
auto-neuters Intel ME images, during build, so that the user does not have to
manually extract such images from dumps of the original vendor firmware (in
the flash) on a given machine.

Such logic was ported to Libreboot, courtesy of `shmalebx9` as mentioned
on the [who page](../../who.md) - Caleb is a core developer in the Libreboot
project.

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](../install/nvmutil.md)

util/spkmodem\_recv/
---------------

FSF has original copyright on this; it was imported from coreboot, who in turn
imported it from GRUB with very little modification. Therefore, this code is
canonically based on what is provided in GNU GRUB.

This is a receiving client for spkmodem, which is a method of providing serial
consoles via pulses on the PC speaker. The `spkmodem_recv` client will *decode*
these pulses. Coreboot has a driver for generating these pulses, as does
GRUB; this client code was imported from GRUB, and has in fact been provided
by every Libreboot release since the start of the project (look inside the GRUB
or coreboot source code and you'll find it).

However, the original code from GRUB was of quite poor quality and this code
is often used. For fun, it was decided that this utility would be imported
directly into `lbmk.git`, and thoroughly cleaned. The lbmk version has been
more or less re-written, using the original logic as a base; variables are
more clearly named. A top-down, OpenBSD-inspired coding style is used,
replacing the GNU coding style implemented in the original code. The [OpenBSD
coding style][https://man.openbsd.org/style.9] is much easier to read.

This code has been modified to make use of the `pledge()` system call, when used
on [OpenBSD](https://www.openbsd.org/); the original version from GRUB did not
do this. Other improvemnts include:

* Superior error handling (the program actually exits with non-zero status now,
  under fault conditions, whereas the original code did *not* handle errors).
* Debug mode is now handled via `getopt()` by passing the `-d` flag at run time,
  whereas the original code only enabled it if a DEBUG build-time flag was used.
* The code has been translated into English (e.g. references to "trames" in
  the code, now say "frames" in the Libreboot version).
* Certain magic numbers, and certain equations in code, are now labelled as
  either variables or as `#define` values, thus increasing code legibility.

*Now* in the next sections, you will learn about configuration files provided
by lbmk:

config/
=======

This directory contains configuration files, used by the Libreboot build
system. These next sections will cover specific configuration files.

config/blobs/
---------------

### config/blobs/sources

URLs and hashes for vendor files containing Intel ME images within them. Where
feasible, backup URLs are also provided. SHA1 checksums are defined, so that
lbmk can verify the integrity of downloaded files.

When building for sandybridge, ivybridge and haswell machines, Libreboot's
bulid system automatically downloads such updates from the vendor, to extract
the Intel ME image and neuter it with `me_cleaner` or `me7_update_parser.py`.

Such auto-download logic was ported from the *Heads* build system, to be used
in the *Libreboot* build system. It is the bee's knees, because it prevents
the need for manual extraction of Intel ME images from vendor dumps. It means
that you can just *build Libreboot* (from `lbmk`) and then just flash the
resulting image, without having to worry.

Of course, backing up the original firmware is still a good idea, before
installing Libreboot or any other spin of coreboot.

This file is also used to define the VGA ROM, on Nvidia models of Dell Latitude
E6400.

config/coreboot
---------------

### config/coreboot/build.list

When a given coreboot tree is compiled, for a given target, this file defines
which files to copy from the coreboot directory, which are then copied to
a location under `elf/coreboot`.

### config/coreboot/BOARDNAME/

Each target name (e.g. `x200_8mb`) has its own directory under here. Targets
that do not define defconfigs also exist here; for example, the `default`
directory defines a coreboot revision and patches.

Targets under `config/coreboot` can specify `tree=TREE` where `TREE` could,
for example, be `default`. In other words, they can refer to other trees.

The coreboot downloads are based on scanning of these directories, and ROM
images are also built based on them; coreboot defconfigs are also used by
the blob scripts, for adding or removing certain binary blobs (for example,
a config will define where `me.bin` is located, and if it doesn't exist, the
blob scripts will look up that file and download/process it with `me_cleaner`).

### config/coreboot/BOARDNAME/patches/

For any given coreboot tree, patches with the `patch` file extension are placed
here, alphanumerically in the order that they should be applied.

These patches are then so applied, when lbmk downloads the given source tree.

### config/coreboot/BOARDNAME/target.cfg

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

* `tree="default"` (example entry)
* `romtype="normal"` (example entry)
* `rev="ad983eeec76ecdb2aff4fb47baeee95ade012225"` (example entry)
* `arch="x86_64"` (example entry)
* `payload_grub="y"` (example entry)
* `payload_grub_withseabios="y"` (example entry)
* `payload_seabios="y"` (example entry)
* `payload_memtest="y"` (example entry)
* `payload_uboot="y"` (example entry)
* `payload_seabios_withgrub="y"` (example entry)
* `grub_scan_disk="ata"`
* `uboot_config=default` (specify which U-Boot tree to use)
* `blobs_required="n"`
* `microcode_required="y"`

The `tree` value refers to `config/coreboot/TREE`; in other words, a given
target could specify a name other than its own as the tree; it would then
re-use code from that tree, rather than providing its own.

The `romtype` entry is used during the building of ROM images, to define
special steps; for example, d8d16sas` would tell lbmk that a fake PIKE2008
ROM must be inserted into CBFS (prevents hanging on SeaBIOS).

The `rev` entry defines which coreboot revision to use, from the
coreboot Git repository. *At present, lbmk only supports use of the official
repository from the upstream coreboot 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.*

The `payload_grub` entry specifies whether or not GRUB is to be included in
ROM images.

The `payload_grub_withseabios` entry specifies whether or not SeaBIOS is to
be included *with* GRUB, in ROM images. Turning this on also turns
on `payload_seabios_withgrub`, unless that option is explicitly turned off.

The `payload_seabios` entry specifies whether or not SeaBIOS is to be included
in ROM images. This option is *automatically* enabled
if `payload_grub_withseabios` and/or `payload_seabios_withgrub` are also turned
on.

The `payload_memtest` entry specifies whether or not MemTest86+ is to be
included in ROM images; it will only be included in ROM images for *text mode*
startup, on x86 machines.

The `payload_uboot` entry specifies whether or not U-Boot is to be included in
ROM images.

The `uboot_config` option specifies which U-Boot board configuration file
variant should be used. It currently doesn't make sense for this to be anything
other than `default`, which is the default if the option is missing.

The `grub_scan_disk` option specifies can be `ahci`, `ata` or `both`, and it
determines which types of disks are to be scanned, when the `grub.cfg` file in
GRUB payloads tries to automatically find other `grub.cfg` files supplied by
your Linux distribution. On some machines, setting it to `ata` or `ahci`
can improve boot speed by reducing delays; for example, trying to scan `ata0`
on a ThinkPad X60 with the optical drive may cause GRUB to hang, so on that
machine it is advisable to set this option to `ahci` (becuse the default HDD
slot is AHCI).

The `blobs_required` entry doesn't affect anything in code, except that
the `noblobs` string will be appended to ROM image file names, on releases;
ditto `nomicrocode` but in that case, the behaviour is: if no microcode to
begin with, only `nomicrocode` images will be named, otherwise ROM images with
and without microcode updates will be provided in releases (CPU microcode
updates).

### config/coreboot/BOARDNAME/config/

Files in this directory are *coreboot* configuration files. 

Configuration file names can be as follows:

* `libgfxinit_corebootfb`
* `libgfxinit_txtmode`
* `vgarom_vesafb`
* `vgarom_txtmode`
* `normal`

Information pertaining to this can be found on
the [installation manual](../install/)

In `lbmk`, a board-specific directory under `config/coreboot/` should never
specify a coreboot revision. Rather, a directory *without* coreboot configs
should be created, specifying a coreboot revision. For example, the
directory `config/coreboot/default/` specifies a coreboot revision. In the
board-specific directory, your `board.cfg` could then
specify `cbtree="default"` but without specifying a coreboot revision (this
is specified by `config/coreboot/default/board.cfg`).

When you create a coreboot configuration, you should set the payload to *none*
because `lbmk` itself will assume that is the case, and insert payloads itself.

Configurations with `libgfxinit` will use coreboot's native graphics init code
if available on that board. If the file name has `txtmode` in it, coreboot
will be configured to start in *text mode*, when setting up the display. If
the file name has `corebootfb` in it, coreboot will be configured to set up a
high resolution *frame buffer*, when initializing the display.

NOTE: If the configuration file is `libgfxinit_txtmode`, the SeaBIOS payload
can still run *external* VGA option ROMs on graphics cards, and this is the
recommended setup (SeaBIOS in text mode) if you have a board with both onboard
and an add-on graphics card (e.g. PCI express slot) installed.

Configuration files with `vgarom` in the name have coreboot itself configured
to run VGA option ROMs (and perhaps other option ROMs). *This* setup is not
strictly recommended for *SeaBIOS*, and it is recommended that you only run
GRUB in this setup. As such, if you wish for a board to have coreboot initialize
the VGA ROM (on an add-on graphics card, as opposed to onboard chipset), you
should have a *separate* directory just for that, under `config/coreboot/`;
another directory for that board will have configs with `libgfxinit`. HOWEVER:

It *is* supported in lbmk to have SeaBIOS used, on either setup. In the
directory `config/seabios/` there are SeaBIOS configs for both; the vgarom
one sets VGA hardware type to *none* while the libgfxinit one sets it
to *coreboot linear framebuffer*. However, if you use SeaBIOS on a setup with
coreboot also doing option ROM initialization, such initialization is being
performed *twice*. As such, if you want to use an add-on graphics card in
SeaBIOS, but the board has libgfxinit, it is recommended that you do it from
a `libgfxinit` ROM.

HOWEVER: there's no hard and fast rule. For example, you could make a vgarom
configuration, on a board in lbmk, but in its coreboot configuration, don't
enable native init *or* oproms, and do SeaBIOS-only on that board.

On `vgarom` setups, coreboot can be configured to start with a high resolution
VESA frame buffer (NOT to be confused with the coreboot frame buffer), or just
normal text mode. Text mode startup is always recommended, and in that setup,
GRUB (including coreboot GRUB, but also PC GRUB) can use VGA modes.

The name `libgfxinit` is simply what `./build boot roms` uses, but it may be
that a board uses the old-school native video init code written in C. On some
platforms, coreboot implemented a 3rd party library called `libgfxinit`, which
is written in Ada and handles video initialization. In this setup, coreboot
*itself* should *never* be configured to run any option ROMs, whether you
start in text mode or with the coreboot framebuffer initialization.

The `normal` config type is for desktop boards that lack onboard graphics
chipsets, where you would always use an add-on graphics card (or *no* graphics
card, which would be perfectly OK on servers).

Even if your board doesn't actually use `libgfxinit`, the config for it should
still be named as such. From a user's perspective, it really makes no
difference.

config/dependencies/
---------------

Files here are so named, and called like so: e.g. the `debian` file would be
referenced when running:

	./build dependencies debian

These files define a list of packages, and the correct package manager command
to use on a given distro. This can be used to install build dependencies, which
are required for compiling Libreboot from source code.

config/git/
---------------

Configuration related to third-party Git repositories, that Libreboot makes
use of.

### config/git/revisions

This file defines third party codebases, with repository links, revision IDs,
and dependencies (referring to other modules defined in this file).

Almost every third party codebase that lbmk downloads is based on the handling
of *this* file. Some of the codebases defined here will also have a directory
of their own; for example, `config/grub/` exists.

config/grub/
---------------

### config/grub/background

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

### config/grub/background/background1024x768.png

Used on ThinkPad X60 and T60.

### config/grub/background/background1280x800.png

Used on all other machines, besides X60 and T60 thinkpads.

NOTE: the `grub_background` option can be set under `target.cfg` in the
relevant coreboot directory, under `config/coreboot/`; for
example, `config/coreboot/x60/target.cfg` specifies this:

	grub_background="background1024x768.png"

### config/grub/background/COPYING

Licensing info for GRUB bootsplash images.

### config/grub/config/

GRUB configuration files.

### config/grub/config/AUTHORS

Author info for GRUB configuration files.

### config/grub/config/COPYING

Licensing info for GRUB configuration files.

### config/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 GRUB memdisk, in the ROM image. It
contains a lot of logic in it, for booting various system configurations, when
the GRUB payload is in use.

It can be overridden by inserting `grub.cfg` into coreboot's main CBFS root.

A `grubtest.cfg` can be inserted into CBFS, but it will not override the
default `grub.cfg` (either in CBFS or on memdisk); however, the one in memdisk
will provide a menuentry for switching to this, if available.

### config/grub/config/grub\_memdisk.cfg

This GRUB configuration checks whether `grub.cfg` exists in CBFS and switches
to that first (not provided by default) or, if one is not available in CBFS,
it will load the `grub.cfg` stored inside GRUB memdisk.

The GRUB memdisk is a file system within `grub.elf`, itself stored within the
coreboot file system named *CBFS*, which is part of the coreboot ROM image on
every coreboot target.

### config/grub/keymap/

Keymap files used by GRUB. They can alter the character set corresponding to
inputted scancodes.

### config/grub/keymap/\*.gkb

The keymap files themselves. These are inserted into the GRUB memdisk, and
the `grub.cfg` file can specify which one is to be used.

These files are binary-encoded, defining which characters correspond to which
scancodes. It is handled by `grub-core/commands/keylayouts.c` in the GRUB source
code.

### config/grub/modules.list

This defines which modules are inserted into `grub.elf`. These modules can be
anything from file systems, small applications/utilities, launchers (e.g.
the `linux` command will execute a Linux kernel), you name it.

Libreboot defines only a very conservative set of modules here, so as to reduce
the amount of space used in the main boot flash. (GRUB payloads are also
compressed when they are inserted into coreboot images)

This list is used by lbmk when it runs `grub-mkstandalone`, which is the utility
from GRUB that generates `grub.elf` files (to be compressed inside CBFS and then
executed as a coreboot payload).

### config/grub/patches/

For a given GRUB revision, patches with the `patch` file extension are placed
here, alphanumerically in the order that they should be applied. For example,
Libreboot provides argon2 key derivation support out of tree, allowing LUKS2
partitions to be decrypted by GRUB.

These patches are then so applied, when lbmk downloads the given source tree.

config/ifd/\*
---------------

Intel Flash Descriptors and GbE NVM images, which are binary-encoded
configuration files. These files are referenced in coreboot defconfigs, used
by lbmk to build coreboot ROM images.

config/seabios/
---------------

### config/seabios/build.list

When a given SeaBIOS tree is compiled, for a given target, this file defines
which files to copy from the `seabios/` directory, which are then copied to
a location under `elf/seabios`.

### config/seabios/default/

Currently the only tree in use, this defines what SeaBIOS revision is to be
used, when the SeaBIOS payload is enabled on a given coreboot target.

### config/seabios/default/config/

Configuration files go in here.

### config/seabios/default/config/libgfxinit

Configuration file for when native video initialisation is available in
coreboot.

### config/seabios/default/config/normal

Configuration file for when native video initialisation is unavailable in
coreboot, and VGA ROM initialisation is also not provided by coreboot (in
this configuration, the usual setup will be that *SeaBIOS* finds and
executes them, instead of coreboot).

### config/seabios/default/config/vgarom

Configuration file for when native video initialisation is unavailable in
coreboot, and VGA ROM initialisation is provided by coreboot; in this setup,
SeaBIOS should not execute VGA ROMs.

### config/seabios/default/target.cfg

Similar concept to `target.cfg` files provided by coreboot. This specifies
which SeaBIOS revision (from Git) is to be used, when compiling SeaBIOS images.

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

### config/u-boot/build.list

When a given U-Boot tree is compiled, for a given target, this file defines
which files to copy from the `u-boot/` directory, which are then copied to
a location under `elf/u-boot/`.

### config/u-boot/TREENAME/

Each `TREENAME` 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 `config/coreboot/TREENAME/`
counterpart.

### config/u-boot/TREENAME/patches/

For any given U-Boot tree, patches with the `patch` file extension are placed
here, alphanumerically in the order that they should be applied.

These patches are then so applied, when lbmk downloads the given source tree.

### config/u-boot/TREENAME/target.cfg

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

* `tree="default"` (example entry)
* `rev="4debc57a3da6c3f4d3f89a637e99206f4cea0a96"` (example entry)
* `arch="AArch64"` (example entry)

These are similar in meaning to their coreboot counterparts.

The tree` entry is actually a link, where its value is a directory name
under `config/u-boot`. For example, `tree="default"` would refer to
`config/u-boot/default` and the corresponding U-Boot source tree created
(when running `./update project trees u-boot`, which makes use of `target.cfg`)
would be `u-boot/default/`. In other words: a `target.cfg` file
in `config/u-boot/foo` might refer to `config/u-boot/bar` by
specifying `tree="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 `rev` 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.*

### config/u-boot/TREENAME/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 `config/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
`config/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
`config/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 `config/u-boot/TREENAME/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 `./update project trees 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 `config/u-boot/TREENAME/`.

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 `config/u-boot/BOARDNAME`.

The *base* revision, upon which any custom patches you wrote are applied,
shall be the `rev` 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.

Config files in lbmk root directory
===================================

projectname
---------------

This is a text file, containing a single line that says `libreboot`. This string
is used by the build system, when naming releases alongside the version number.

version
---------------

Updated each time lbmk runs, based on either `git describe` or, on release
archives, this file is static and never changes. It says what Libreboot revision
is currently in use (or was in use, if lbmk isn't running).

versiondate
---------------

Updated each time lbmk runs, based on either `git describe` or, on release
archives, this file is static and never changes. It says the *time* of
whichever Libreboot revision is currently in use (time of commit).

At least, you will now learn about the *scripts* (exclusively written as
posix shell scripts) that constitute the entire Libreboot build system, lbmk:

Scripts in root directory of lbmk
=================================

build
---------------

Symbolic link, pointing to the `lbmk` script. This is executed by the user, or
by lbmk, referencing scripts under `script/build/*/`.

checkgit
---------------

This is executed by the `lbmk` script when it runs, returning non-zero status
and exit if global git name/email configuration does not exist; lbmk makes
extensive use of git, and coreboot requires this to be set.

checkversion
---------------

If lbmk is in git, this uses `git describe` to get a version number based on
revision and/or git tag, then writing that to a file called `version` and a
corresponding date (as unix timestamp) to `versiondate`; if this script is
executed from a release archive, the value stored in those files (included by
default in release archives, but auto-generated in `lbmk.git`) will be used
as-is.

The result of this is then used in many things. For example, `lscoreboot` on
the GRUB terminal will yield this revision number and date.

handle
---------------

Symbolic link, pointing to the `lbmk` script. This is executed by the user, or
by lbmk, referencing scripts under `script/handle/*/`.

lbmk
---------------

This is the main script in lbmk, Libreboot's build system. It is what executes
all other parts of the Libreboot build system. The rules are as follows:

* `lbmk` cannot be called directly; symlinks such as `build`, `update`
  or `handle` will point to it, and you will execute those.
* Argument zero, representing the name of the symlink, will be used to
  execute `script/LINKNAME/mode/option` - for example: `./build boot roms all`
  would execute `script/build/boot/roms all` in `sh`.
* `TMPDIR` is exclicitly set, providing a constant location where temporary
  files and directories can be made. `TMPDIR` is exported by the parent to
  all children; for example, `./build boot roms all` would export it
  to `script/build/boot/roms`, and then anything called by *that* will also
  inherit it - the main parent process running `lbmk` will then clean up this
  `TMPDIR` directory upon any exit.
* All exits from lbmk are handled by this script. *All* exits, zero or non-zero,
  are engineered such that *this* script, in the parent process (the very first
  instance) is what ultimately exits.
* This script is programmed to *exit* with non-zero status, when run as root,
  unless the `./build dependencies *` commands are used,
  referencing files under `config/dependencies/`
* Under fault conditions, each child process shall output to stderr, and the
  main parent process running `lbmk` will output the final error message.

tl;dr break this script and you *break Libreboot*.

update
---------------

Symbolic link, pointing to the `lbmk` script. This is executed by the user, or
by lbmk, referencing scripts under `script/update/*/`.

include/
===============

This directory contains *helper scripts*, to be included
by main scripts using the `.` command (called the `source`
command in `bash`, but we rely upon posix `sh` only).

include/blobutil.sh
---------------

Common variables, used by all scripts under `script/update/blobs/`.

include/defconfig.sh
---------------

Functions used by scripts under `script/update/blobs/`, for checking defconfig
files. These files are checked because the scripts need to know whether a given
blob is used; if it is, a path is then specified in defconfig, telling the blob
script either where it is, or where it should be downloaded to.

include/err.sh
---------------

Generic error handling, used by all lbmk scripts.

include/export.sh
---------------

Used by the main script named `lbmk`, this provides initialisation of
the `TMPDIR` environmental variable, allowing unified handling of `/tmp` within
lbmk.

script/
=======

*All* scripts under `script/` are executed only by the main `lbmk` script,
conforming to the standard `buildpath/mode/option` e.g. `build/boot/roms` - so,
running `./build boot roms` would run `script/build/boot/roms`.

script/build/
---------------

These are highly specialised build scripts, written for specific tasks, almost
entirely in the context of building firmware images themselves, but some utils
are also handled.

The scripts that create release archives are also located under this directory.

### script/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 targetname`

The `targetname` argument must be specified, chosen from this output:

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

To build *all* targets, specify:

	./build boot roms all

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.

### script/build/boot/roms\_helper

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

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

If `grub_scan_disk` is set, it sets that in the `scan.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 `target.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 `target.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.
* `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 declaration is made, or a declaration is made contrary to the above,
  no special modifications will be made.

If no payload is defined in `target.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 beating heart of libreboot. Break it and you break Libreboot.

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

### script/build/command/options

It basically just does `ls -1` but in a more fault-tolerant way. This is used
in certain circumstances, such as `./build boot roms all` where a script needs
to know what build targets are available.

Command: `./build command options DIRECTORY`

### script/build/coreboot/utils

This builds coreboot utilities `ifdtool` and `cbfstool`, placing them
under `cbutils/` for use by other parts of lbmk.

Command: `./build coreboot utils`

### script/build/grub/payload

This builds the `grub.elf` file and keymap configuration files, placing these
under `elf/grub/` for use by `script/build/boot/roms_helper`.

Command: `./build grub payload`

### script/build/grub/utils

This builds the `grub-mkstandalone` utility under `grub/`, which is then used
by `script/build/boot/roms_helper` to insert GRUB payloads inside coreboot ROM
images.

Command: `./build grub utils`

### script/build/release/roms

This builds release archives, containing ROM images for coreboot and/or serprog
programmers. You must *only* run this *after* you've build all of the ROM images
that you wish to release.

Command: `./build release roms`

NOTE: This script *scrubs* certain binary blobs from release ROMs, such as
Intel ME or MRC firmware. The release ROMs shall then exclude these blobs
within them, requiring manual insertion by the user post-release. See:

[Insert binary blobs
on Sandybridge/Ivybridge/Haswell](../install/ivy_has_common.md)

### script/build/release/src

This builds source archives. You must only run this after compiling crossgcc
on all coreboot source trees, and after building the ROM images that you wish
to release; in other words, it is recommended that you
run `./build release roms` first.

Command: `./build release src`

### script/build/serprog/rp2040

Build firmware images for serprog-based SPI programmers, where they use an
RP2040 MCU.

Example command: `./build serprog rp2040`

The `list` argument is available:

	./build serprog rp2040 list

Without arguments, all targets would be compiled, but you can specify a short
list of targets instead, based on the output of `list`.

### script/build/serprog/stm32

Build firmware images for serprog-based SPI programmers, where they use an
STM32 MCU.

Example command: `./build serprog stm32`

The `list` argument is available:

	./build serprog stm32 list

Without arguments, all targets would be compiled, but you can specify a short
list of targets instead, based on the output of `list`.

script/handle/
--------------

The `handle` scripts deal with Kconfig infrastructure across various projects
used by lbmk. It also handles the compilation of *crossgcc*, coreboot's cross
compiling toolchain collection which is used for compiling coreboot itself and
also U-Boot (but *SeaBIOS* is currently built using the *host* toolchain).

### script/handle/make/config

*This* is the other beating heart of Libreboot. Used heavily by Libreboot, this
script is what handles defconfig files for SeaBIOS, U-Boot *and* coreboot; it
used to be separate scripts, but the logic was unified under this single script.

It handles the following files (PROJECT can be `coreboot`, `seabios`
or `u-boot`):

* `config/PROJECT/build.list` (defines what files to copy, after building for
  the target)
* `config/PROJECT/*/target.cfg` (lbmk build parameters, project project/target)
* `config/PROJECT/*/config/*` (defconfig files)

Basic command: `./handle make config FLAG projectname`

FLAG values are (only *one* to be used at a time):

* `-b` builds an image for the target, based on defconfig.
* `-u` runs `make oldconfig` on the target's corresponding source tree, using
  its defconfig (useful for automatically updating configs, when updating trees
  like when adding patches or switching git revisions)
* `-m` runs `make menuconfig` on the target's corresponding source tree, using
  its defconfig (useful for modifying configs, e.g. changing CBFS size on
  a coreboot image)
* `-c` tries `make distclean`, deferring to `make clean` under fault
  conditions and from that, non-zero exit under fault conditions. This is done
  on the target's corresponding source tree.
* `-x` tries 'make crossgcc-clean`. This only works on coreboot trees, but no
  error status will be returned on exit if you try it on other project trees; no
  action will be performed.

As for *projectname", this can either be `coreboot`, `u-boot` or `seabios`.

Example commands:

	./handle make config -b coreboot
	./handle make config -b coreboot x200_8mb
	./handle make config -b coreboot x230_12mb x220_8mb t1650_12mb
	./handle make config -x coreboot default
	./handle make config -u seabios
	./handle make config -m u-boot gru_bob

NOTE: the `-x` and `-c` options will cause an exit with zero status, when
the target's corresponding source tree is unavailable; a non-zero status is
only return under fault conditions when said source tree is *available*. ALL
other flags will cause the very same source tree to be downloaded and prepared,
if unavailable and *that* too will return with non-zero status under fault
conditions.

NOTE: "target" can indeed be the tree name, under some circumstances. For
example, `./handle make config -m seabios default`

After `projectname`, a target can be specified, but if no target is specified,
then *all* targets will be operated on. For
example, `./handle make config -b coreboot` will attempt to build *all*
coreboot ROM images.

NOTE: the `coreboot` projectname here shall cause the ROM images to go
under `elf/` - this is the no-payload ROM images, which are later used
separately by `script/build/boot/roms_helper` to provide full images, with
payloads inserted. It is an intentional design choice of Libreboot, to split
it up this way and *not* use coreboot's own build system to handle payloads.

In lbmk, there are *two* types of git download: *simple* downloads where only
a single revision would ever be used, or *multi* downloads where different
revisions are used depending on target.

All such downloads are *simple* downloads, except for coreboot, U-Boot and
SeaBIOS which are *multi* downloads. The *other* requirement is that defconfigs
be used, though this could be worked around in the future if a *multi* setup is
needed on a project that *does not use defconfigs* (this is not yet the case in
lbmk).

All of this used to about 20 different scripts, all with much-duplicated logic.
Now it is unified, efficiently, under a single script.

Remember: code equals bugs, so less code equals fewer bugs.

### script/handle/make/file

Generic handling of Makefiles, and also cmake on some projects. This is used
on projects with non-Kconfig-based build systems, where the step for compiling
is basically `cd projectdir/ && make`.

Example commands:

	./handle make file -b memtest86plus
	./handle make file -c memtest86plus

The `-b` option runs `make all`. The `-c` option tries `make clean` first,
and then `make distclean`.

script/update/
---------------

These scripts pertain mostly to *downloads*, of either Git repositories or,
where required on given mainboards, binary blobs.

### script/update/blobs/download

This downloads binary blobs when needed, on a given coreboot target. It does
this by scanning the defconfig files of that board, to know where the blobs
are (or where they should be) within lbmk.

These blobs are then inserted at build time by the coreboot build system (as
defined by defconfigs), or post-release by running the `inject` script.

More information is available [here](../install/ivy_has_common.md).

### script/update/blobs/extract

NOTE: Currently broken on some setups. This script is not recommended, but
it can extract some binary blobs from vendor dumps. Use of it is ill advised,
because it's not complete, and there's no guarantee what you'll get from it.

More information is available [here](../install/ivy_has_common.md).

### script/update/blobs/inject

This is not used during the build process, but it can be run by the user on
release ROMs (which do not contain non-redistributable blobs handled by these
blob scripts, but those blobs are required). This script inserts those blobs
into the coreboot ROM image; if you're building from source, using lbmk, you
do not need to run the inject script at all.

More information is available [here](../install/ivy_has_common.md).

### script/update/blobs/mrc

This is called by the main blob download script, and downloads Intel MRC images
for raminit and peripherals. Libre MRC setups are also provided in Libreboot,
as an alternative.

Command: `./update blobs mrc`

More information is available [here](../install/ivy_has_common.md).

### script/update/project/repo

Where Kconfig-based infrastructure is not used, and a project only has one
revision in use by lbmk, this script is used. It downloads third party
software (such as memtest86+), based on entries defined
in `config/git/revisions` and then applies patches, if they exist.

Example command: `./update project repo memtest86plus`

### script/update/project/trees

Similar to the above, and in fact it does use `script/update/project/repo`, but
then the downloaded tree is copied to multiple directories based on target name.
This is used for coreboot, U-Boot and SeaBIOS, to create multiple source trees.

The `config/git/revisions` file does not specify a revision for these projects;
it literally says `HEAD`, nor are patches applied under this paradigm.

Instead, it looks for patches in `config/projectname/target/patches`
where `projectname` could be coreboot for example, and `target` could
be `default` on `cros` for example; those are tree names, but you could also
specify a build target such as `x200_8mb` if it points to a tree name.

It also updates git submodules, where available. The `target.cfg` file is used,
to know what revision is needed on a given target tree.

Example commands:

	./update project trees coreboot
	./update project trees seabios
	./update project trees u-boot

With no additional arguments provided, it will download *all* trees for the
given project. If you only want to download a specific tree, you can declare
either the tree name itself or the target name (pointing to the tree name). For
example:

	./update project trees coreboot default
	./update project trees coreboot x200_8mb

In the above example, `x200_8mb` is a build target and its `target.cfg` points
to `default` as tree name, so the practical result of both commands will be
exactly the same.

Downloaded source trees are *only* created for actual tree names; they are
not duplicated for targets, where those targets refer to a tree. This saves
time, and disk space.

This *used to be* separate scripts for coreboot and U-Boot, where SeaBIOS was
treated as a *simple* clone (using logic similar to `script/update/project/repo`
but the logic was unified into this one script, greatly simplifying lbmk.