44 KiB
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 namedpci1000,0072.rom
andpci1000,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
: theich9gen
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, X3018MiB 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 reasonich9gen
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) ROMs16MiB ICH9 IFD NOGBE NOR flash
: Same as above, but for 16MB (128Mbit) ROMsi945 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 settingbucts
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/build/release/u-boot-libre
This builds a release of u-boot-libre. Once released officially, the files produced by the command below are then expected to be used by FSDG distributions packages.
While this isn't useful as-is for Libreboot, it enables to share the deblobbing code between various FSDG distributions and also enables Libreboot to reuse that deblobbing process to support boards with u-boot in the future.
Command: ./build release u-boot-libre
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