Re-adding legacy payloads to Libreboot


Return to index

Please note: non-FAT32 ESP is possible in our EDK2 version. Look at the main EDK2 UEFI guide. We support also: EXT2/3/4, NTFS, ExFAT, ZFS, XFS, F2FS, btrfs, UFS 1, UFS 1 (Big Endian) and UFS2. This covers nearly all Linux and BSD file systems that people use these days. You can place an ESP (EFI System Directory) structure on existing partitions without having to reformat for a FAT32 ESP, although the latter is standard in UEFI. These extra file systems were added to EDK2 to make migration easier. It also makes generally running EFI applications much easier. Thank you Pete Batard for your wonderful EfiFs project, which we are using for this purpose, re-purposing the GNU GRUB filesystem drivers for use in EDK2.

This page pertains to EDK2 UEFI - please refer to that documentation first. This guide will teach you how to add back legacy payloads to EDK2 on modern Libreboot releasse, so that you can use e.g. GRUB payload, SeaBIOS for legacy operating system, etc. Context also provided here.

Libreboot has patched its EDK2 sources so that the size of the EDK2 binary can be a maximum of 32MB. With compression, this is quite big and could even fit a Linux UKI, if you then had enough flash space in CBFS to fit EDK2 with Linux in it.

UEFI-only!!!

Libreboot 26.11 only has EDK2 and iPXE(booting from EDK2) on most Intel/AMD hardware. This is to simplify maintenance of the project, as we then no longer have to provide sources of several large and complicated projects, some of which can be quite buggy. The payloads removed were:

It is strongly recommended that you convert your existing OS setup to UEFI, but some users may still want the legacy payloads. This page will tell you how to add them back.

Install dependencies

If you’re building the legacy payloads (see below) from source, you need build dependencies. Check the build guide which tells you how to install build dependencies - it is assumed that you will build everything on a Linux system.

As on that page, Libreboot tells you how to automatically install build dependencies, using configs provided by Libreboot, for various distros. These include legacy dependencies, as they were not removed since removing these legacy payloads in the build system.

Quick start

Copy e.g. grub.efi to a USB stick, FAT32 formatted, and in EDK2 shell from the boot menu, do:

fs0:
grub.efi

before running grub.efi, type ls to make sure you’re on the right volume. Otherwise try e.g. fs1, fs2, etc. Same for other payloads e.g. rebios.

Or put the given binary inside ESP; consult upstream documentation for what you’re inserting into ESP. Note that you can do this with any EFI application, not just the ones covered here.

Prepare binaries for lbmk

Do this inside the lbmk root, or the root of the Libreboot src archive from 26.11 onward:

mkdir -p efi/

You can have any combination of these files:

You can get these EFI binaries from upstreams, or by building them from source. We will now cover how to do just that, for each project:

SeaBIOS

We will use ReBIOS, which emulates a real BIOS; it uses SeaBIOS, and its own custom VGA emulation, which is full emulation; it can run legacy operating systems perfectly. For example, ReactOS and Windows XP will work perfectly. This is a huge upgrade over traditional coreboot SeaBIOS, which has a much buggier implementation - it would be nice to port their VGA emulation there, for 32-bit targets in Libreboot that use the coreboot payload of SeaBIOS, piggybacking off of the libgfxinit linear framebuffer.

ALSO:

WARNING: Intel VT-d or equivalent on AMD required (IOMMU), because ReBIOS works by running the BIOS emulation inside a hypervisor, with hardware passthrough such that the legacy OS can use the hardware normally. If your hardware doesn’t have an IOMMU, you can’t run ReBIOS.

Now, build it:

Clone https://github.com/ReBIOS-Project/ReBIOS in Git and build it using the instructions in their README, or get a release build provided by that project, here: https://github.com/ReBIOS-Project/ReBIOS/releases

If using the release binary, they literally have it as rebios.efi - you can just use their build (recommended), but some people might want to build from source. It’s fine either way.

Save the binary to location from lbmk root: efi/rebios.efi

MemTest86plus

Clone https://github.com/memtest86plus/memtest86plus.git and build it in that repository using their supplied README. Build the EFI x64 (Intel/AMD) version. Alternatively, you can find a binary in their releases, if you go to https://www.memtest.org/ - either way, make sure you run file on the binary, and check that it says EFI Intel/AMD64 x86_64.

Save the binary to location from lbmk root: efi/mt86plus.efi

GRUB

This section pertains to EFI GRUB, not the coreboot-payload version of GRUB.

GRUB releases very rarely, and the master branch often contains critical security fixes. Distros will often backport these into their versions. It is advised to keep GRUB up to date on master, rather than using releases, for this reason. Upstream does semi-regular audit sweeps, e.g. fuzzing, fixing use after frees, bounds checks, etc.

Yes:

Classic Libreboot. The old coreboot payload was replaced by an EFI GRUB payload mimicking the old coreboot one, in Libreboot 26.10. This section will tell you how to build a GRUB EFI payload functionally equivalent to that.

Download the latest GRUB:

git clone https://gitlab.freedesktop.org/gnu-grub/grub.git
cd grub

Now, do these commands in the grub directory:

./bootstrap
./autogen.sh
./configure --target=x86_64 --with-platform=efi --disable-werror
make -j$(nproc)

NOTE: -j$(nproc) optional, but it makes GRUB build with the number of threads available for your CPU. Otherwise, without it, GRUB will build on just a single thread most likely.

NOTE: This won’t build the actual GRUB payload. This will be done next, with a utility that make just compiled called grub-mkstandalone, but first, I repeat the warning: this is the EFI GRUB target. This is not a coreboot payload! It is a generic GRUB EFI payload, and we will make it mimick the original coreboot payload, as in the Libreboot 26.10 release - GRUB was removed entirely, since Libreboot 26.11.

Now, here is a simple GRUB config that you will use inside the GRUB payload. Make a note of this for later, and save it locally (inside your GRUB src) to a file. I will assume you save this to a file named grub.cfg inside your GRUB clone:

set prefix=(memdisk)/boot/grub

insmod regexp

gfxpayload=keep
terminal_output console
terminal_input console

for dt in cbfsdisk memdisk; do
	for it in png jpg; do
		if [ -f (${dt})/background.${it} ]; then
			insmod ${it}
			background_image (${dt})/background.${it}
		fi
	done
done

set default="0"
set timeout=8

function try_user_config {
	if [ "${1}" = "(proc)" ]; then
		return 0
	fi
	if [ "${1}" = "(cbfsdisk)" ]; then
		return 0
	fi
	if [ "${1}" = "(memdisk)" ]; then
		return 0
	fi

	set root="${1}"

	# The @/... entries are for cases where the BTRFS filesystem is being used
	for dir in '' /@ /grub /boot/grub /@/grub /@/boot/grub /grub2 /boot/grub2 /@/grub2 /@/boot/grub2 /boot /@/boot /EFI /EFI/* /@*; do
		if [ -f "${dir}/grub.cfg" ]; then
			unset superusers
			configfile "${dir}/grub.cfg"
		elif [ -f "${dir}/isolinux/isolinux.cfg" ]; then
			syslinux_configfile -i "${dir}/isolinux/isolinux.cfg"
		elif [ -f "${dir}/syslinux/syslinux.cfg" ]; then
			syslinux_configfile -s "${dir}/syslinux/syslinux.cfg"
		elif [ -f "${dir}/syslinux/extlinux.conf" ]; then
			syslinux_configfile -s "${dir}/syslinux/extlinux.conf"
		elif [ -f "${dir}/extlinux/extlinux.conf" ]; then
			syslinux_configfile -s "${dir}/extlinux/extlinux.conf"
		fi
	done
}

menuentry 'Attempt to auto-boot Linux (USB attempted first)  [o]' --hotkey='o' {

	for vol in (cd*) (*); do
		try_user_config "${vol}"
		echo
	done

	set pager=0
	echo -n "Attempting to unlock encrypted volumes"
	echo
	cryptomount -a
	set pager=1
	echo

	# trying again will find decrypted volumes.
	for vol in (*); do
		try_user_config "${vol}"
		echo
	done

	true # Prevent pager requiring to accept each line instead of whole screen
}

if [ -f (cbfsdisk)/img/memtest ]; then
menuentry 'Load MemTest86+  [m]' --hotkey='m' {
	set root='cbfsdisk'
	chainloader /img/memtest
}
fi

menuentry 'Poweroff  [p]' --hotkey='p' {
	halt
}

menuentry 'Reboot  [r]' --hotkey='r' {
	reboot
}

menuentry 'EFI setup  [q]' --hotkey='q' {
	fwsetup
}

This config, as above, is based on what was present in the Libreboot 26.10 release. It can be extended of course, if you want to modify it, but the above config should work for most legacy Libreboot setups, that booted Linux distros with GRUB. As you can see in the config, it’s basically just bruteforcing every partition on your system to try to find another GRUB config supplied by your distro. This isn’t very sophisticated; it’s better to just use your distro’s provided GRUB EFI build these days, and load it directly from EDK2. Conversion to full UEFI is recommended.

Please note: when booting a distro using GRUB EFI, you’re just booting in EFI mode while bypassing the ESP; distros won’t detect this. They might just assume you’re on UEFI anyway, and set up an EFI-based system, which would then boot in normal EDK2. This legacy GRUB setup is intended for people who booted distros before, on the old coreboot-payload version of GRUB.

Now, still inside the GRUB clone directory, building the payload is fairl simple:

./grub-mkstandalone \
    --grub-mkimage="grub-mkimage" \
    -O x86_64-efi -o "grub.efi" -d "grub-core" \
    --fonts= --themes= --locales= \
    --modules="$(find grub-core/ -type f -name "*.mod")" \
    --install-modules= \
    "/boot/grub/grub.cfg=grub.cfg"

You should now have a grub.efi file. Copy this into the efi/ directory on the root of your Libreboot git clone or (26.11 or later) Libreboot src archive.

Build the Libreboot image

Refer to build instructions - if your board uses EDK2, and you placed the payload binaries for EDK2 correctly inside efi/, then you should flash the firmware. If you then check the boot menu in EDK2, you’ll most likely see the payloads.

Canoeboot, a former fork of Libreboot (now Canoeboot is RBoot), was archived since being forked into RBoot. RBoot has this same EFI-only policy in releases.

If you’re booting Linux distros/installers with the GRUB EFI payload, you can refer to the old documentation which is archived here:

The GRUB setup won’t be changed further, so these docs should be valid forever. Users are advised to otherwise convert fully to UEFI instead of relying on these legacy setups.

You don’t need the BSD instructions from the old docs, because the ReBIOS setup actually emulates full VGA; the old BSD docs were for a version of SeaBIOS that was very buggy, so it had the user booting only in text mode and then switching to Kernel Mode Setting. With ReBIOS, you can just do normal VGA-based mode setting, though KMS is still recommended. Consult your BSD docs.

It should go without saying: these legacy setups are only intended for existing OS installs. New OS installs should be done purely with EDK2, in an EFI setup, with full ESP.

MemTest86plus is memtest86plus. Not much to explain there.

BONUS:

ReactOS was tested with ReBIOS and it worked perfectly, on my ThinkPad X220. Which just so happened to have VT-d on it. This is the first time ReactOS ever actually booted on a Libreboot machine! Since Libreboot 26.11 - and for example, older versions of Windows will work. E.g. Windows XP, Windows 7. Ditto older BSD systems - if you want to run OpenBSD from 2012 (long before it had KMS, and definitely relied on VGA interrupts), you absolutely can.

And finally:

Why were these payloads removed?

Bloat. UEFI is the future. More seriously:

SeaBIOS:

Memtest: pointless to include.

It’s better that most people use EDK2 itself. By only including it by default in new builds, we ensure that most new users will do just that. Support was added though for re-adding these payloads, as alluded to above. That way, the diehards who refuse to upgrade still have choices. Yes, and please note:

The build system will automatically re-build a given ROM image for your board, when you add and remove those payloads in efi/ or when changing them. So, you could just keep lbmk locally and keep those files. When updating lbmk or when changing those files, just re-build again, and you will get a new ROM with updated builds.

Basically, maintenance of these legacy payloads has been shifted onto the user, but Libreboot’s automation makes it so easy even still, that most users will probably be happy. Win-win for everyone. This design change was part of a massive, dare I even say revolutionary, drive to completely modernise everything from the ground up, inside the Libreboot project. We actually had EDK2 many years ago, briefly, in the erstwhile OSBoot project, but it was removed prior to merging with Libreboot. EDK2 wasn’t as mature back in those days, at least not any open source versions. It’s pretty much nearly all the way there nowadays and will work with whatever you throw at it.

Regarding GRUB patches

This section pertains to EFI GRUB, not coreboot GRUB.

Please note: the GRUB setup, as above, is just standard upstream code, without Libreboot’s prior patching. This should be OK in a UEFI context, but please note: if setting terminal_output to gfxterm insead of console as it is shown above, you’ll get quite messed up looking borders. Just ignore it. It’s a limitation in unifont, and Libreboot used to patch it by simply removing the border. In console mode, the border fonts look fine, so the above reference config uses console mode by default.

The other patching Libreboot last had for GRUB was:

It was initially decided that builds of GRUB would be provided out of tree, for people to add using this guide, but the new leadership in GRUB seems to be doing a good job, and most users should be happy with the fairly conservative GRUB setup as described above.

Please consult Libreboot IRC if you get stuck.

Native legacy coreboot payloads

DO NOT follow the next guides unless you want a brick. They’ll probably be fine, but these next sections are for restoring the coreboot payloads of SeaBIOS and GRUB. These are no longer maintained since Libreboot 26.11, but some users may want to add them. Some general guidance is provided, thus:

SeaBIOS

In your board’s configuration, e.g. for ThinkPad T480 it is: config/module/coreboot/lenovo_thinkpad_t480_16mb/ modify target.cfg, e.g. modify config/module/coreboot/lenovo_thinkpad_t480_16mb/target.cfg and add these lines to the end of it:

payload_edk2=""
payload_seabios="y"
build_depend="seabios/build"

This disables use of EDK2 UEFI payload, and gives you back the original coreboot payload build for SeaBIOS. Then just build your board, as indicated elsewhere in this guide. Please note that when you do this, the payloads under efi/ will no longer be added, even if present. They are only added for targets that use EDK2 UEFI payload.

Use of bare SeaBIOS is not recommended. The code is quite solid, and never changes much, so the risk of regression is low, but it has several shortcomings compare to ReBIOS CSM module:

EDK2 is recommended, but SeaBIOS is left supported in the build system for some legacy 32-bit hardware, and 64-bit setups that don’t yet have a proper linear framebuffer at startup that EDK2 needs in our configuration.

GRUB (coreboot payload)

This section pertains to the GRUB coreboot payload, not the EFI version of GRUB that runs in EDK2.

Please note: the coreboot-payload version of GRUB is incredibly unstable. The native drivers that it has to implement there can be buggy. It was always unreliable and a maintenance burden for Libreboot, which is why it was removed in favour of EDK2. You are advised to use the EDK2 version of GRUB, as it is generally much more stable. Please build the EFI version of GRUB. This documentation about the coreboot version is provided only for completeness, post-removal.

You can re-add this to the ROM. It could be run as a standalone coreboot payload, but you are advised to run it from SeaBIOS. The instructions are similar to the EFI build, and they are:

Download the latest GRUB:

git clone https://gitlab.freedesktop.org/gnu-grub/grub.git
cd grub

You almost certainly need to patch GRUB. You can find patching for GRUB in the Libreboot 26.10 branch. In lbmk, do this on a copy of lbmk so you don’t lose what you did above:

git checkout 26.10_branch

Then look in config/module/grub/ for patches.

In Libreboot 26.10 branch you see, and I will now tell you which ones are relevant to you (assuming some of them haven’t been merged):

Disable ugly border when using unifont:
0001-mitigate-grub-s-missing-characters-for-borders-arrow.patch

Libreboot special sauce
0002-say-the-name-libreboot-in-the-grub-menu.patch

Keyboard patches recommended highly:
0003-at_keyboard-coreboot-force-scancodes2-translate.patch
0004-keylayouts-don-t-print-Unknown-key-message.patch

Optional
0005-don-t-print-missing-prefix-errors-on-the-screen.patch
0006-don-t-print-error-if-module-not-found.patch
0007-don-t-print-empty-error-messages.patch

xHCI patches if you need them. Keep an eye on it,
because GRUB might actually merge these if they are re-submitted later:
0008-grub-core-bus-usb-Parse-SuperSpeed-companion-descrip.patch
0009-usb-Add-enum-for-xHCI.patch
0010-usbtrans-Set-default-maximum-packet-size.patch
0011-grub-core-bus-usb-Add-function-pointer-for-attach-de.patch
0012-grub-core-bus-usb-usbhub-Add-new-private-fields-for-.patch
0013-grub-core-bus-usb-Add-xhci-support.patch
0014-grub-core-bus-usb-usbhub-Add-xHCI-non-root-hub-suppo.patch
0015-xHCI-also-accept-SBRN-0x31-and-0x32.patch
0016-xhci-fix-port-indexing.patch
0017-xhci-configure-TT-for-non-root-hubs.patch
0018-Fix-compilation-on-x86_64.patch

REQUIRED for coreboot (payload version), GRUB never merged it
0019-kern-coreboot-mmap-Map-to-reserved.patch

Skip (lbmk handled PO files. you should let GRUB handle them)
0020-bootstrap-Don-t-download-po-files.patch

Probably skip
0021-force-disable-werror.patch

Skip these (use 0022 on old Linux distros if you need to - not recommended)
0022-don-t-use-image-base-in-configure-ac.patch
0023-indicate-use-of-ESC-to-cycle-boot-devices.patch

Now, do these commands in the grub directory:

./bootstrap
./autogen.sh
./configure --with-platform=coreboot --disable-werror
make -j$(nproc)

Sample GRUB config, based on the Libreboot 26.10 version:

set prefix=(memdisk)/boot/grub

insmod at_keyboard
insmod usb_keyboard
insmod nativedisk
insmod xhci
insmod ehci
insmod ohci
insmod uhci
insmod usb
insmod usbms
insmod regexp

gfxpayload=keep

terminal_output gfxterm

terminal_input --append at_keyboard
terminal_input --append usb_keyboard

for dt in cbfsdisk memdisk; do
	for it in png jpg; do
		if [ -f (${dt})/background.${it} ]; then
			insmod ${it}
			background_image (${dt})/background.${it}
		fi
	done
done

set default="0"
set timeout=8

# find it in config/data/grub/keymap/ in 26.10,
# and add to cbfs as keymap.gkb. e.g. ukdvorak.gkb
if [ -f (cbfsdisk)/keymap.gkb ]; then
	keymap (cbfsdisk)/keymap.gkb
fi

function try_user_config {
	if [ "${1}" = "(proc)" ]; then
		return 0
	fi
	if [ "${1}" = "(cbfsdisk)" ]; then
		return 0
	fi
	if [ "${1}" = "(memdisk)" ]; then
		return 0
	fi

	set root="${1}"

	# The @/... entries are for cases where the BTRFS filesystem is being used
	for dir in '' /@ /grub /boot/grub /@/grub /@/boot/grub /grub2 /boot/grub2 /@/grub2 /@/boot/grub2 /boot /@/boot /EFI /EFI/* /@*; do
		if [ -f "${dir}/grub.cfg" ]; then
			unset superusers
			configfile "${dir}/grub.cfg"
		elif [ -f "${dir}/isolinux/isolinux.cfg" ]; then
			syslinux_configfile -i "${dir}/isolinux/isolinux.cfg"
		elif [ -f "${dir}/syslinux/syslinux.cfg" ]; then
			syslinux_configfile -s "${dir}/syslinux/syslinux.cfg"
		elif [ -f "${dir}/syslinux/extlinux.conf" ]; then
			syslinux_configfile -s "${dir}/syslinux/extlinux.conf"
		elif [ -f "${dir}/extlinux/extlinux.conf" ]; then
			syslinux_configfile -s "${dir}/extlinux/extlinux.conf"
		fi
	done
}

menuentry 'Attempt to auto-boot Linux (USB attempted first)  [o]' --hotkey='o' {

	for vol in (usb*) (*); do
		try_user_config "${vol}"
		echo
	done

	set pager=0
	echo -n "Attempting to unlock encrypted volumes"
	echo
	cryptomount -a
	set pager=1
	echo

	# trying again will find decrypted volumes.
	for vol in (*); do
		try_user_config "${vol}"
		echo
	done

	true # Prevent pager requiring to accept each line instead of whole screen
}

if [ -f (cbfsdisk)/img/memtest ]; then
menuentry 'Load MemTest86+  [m]' --hotkey='m' {
	set root='cbfsdisk'
	chainloader /img/memtest
}
fi

menuentry 'Return to SeaBIOS  [q]' --hotkey='q' {
	set root='cbfsdisk'
	chainloader /fallback/payload
}

menuentry 'Poweroff  [p]' --hotkey='p' {
	halt
}

menuentry 'Reboot  [r]' --hotkey='r' {
	reboot
}

Save that as grub.cfg and then do:

./grub-mkstandalone \
    --grub-mkimage="grub-mkimage" \
    -O i386-coreboot -o "grub.elf" -d "grub-core" \
    --fonts= --themes= --locales= \
    --modules="$(find grub-core/ -type f -name "*.mod")" \
    --install-modules= \
    "/boot/grub/grub.cfg=grub.cfg"

The resulting grub.elf can be added to the coreboot image thus:

cbfstool your.rom add-payload -f grub.elf -n img/grub2 -c lzma

You may find cbfstool under elf/coreboot/TREE, where TREE corresponds to what is in target.cfg for your board (see SeaBIOS section above). For example, it might be under elf/coreboot/default/ as cbfstool. Always use the one for your tree.

You can build cbfstool for the tree like this:

./mk -d coreboot TREE

When you flash the ROM, you can press ESC in SeaBIOS to access GRUB from the menu. Alternatively, you might do this for your board:

./mk -m coreboot board_name_goes_here

Please note: if this is because you want GRUB to load automatically, you could just insert it to load from SeaBIOS, and add a bootorder file:

/rom@img/grub2

Place that in the bootorder file in CBFS.

In there, you could specify to add a custom payload, linking to your grub.elf - this would give you standalone GRUB, without SeaBIOS, when building, and the ROM will have custom_ at the start of the filename under bin/ when building in lbmk as the payload logic in lbmk gets skipped when defining payloads in the coreboot config. This is NOT RECOMMENDED, as GRUB can sometimes be quite unstable depending on the revision, so when we built GRUB, we had it booting from SeaBIOS which is usually stable.

You can also add the background in config/data/grub to CBFS if you want, as background.png.

Markdown file for this page: https://libreboot.org/docs/install/legacy.md

Site map

This HTML page was generated by the Libreboot Static Site Generator.