Re-adding legacy payloads to Libreboot

Return to index

This page pertains to EDK2 UEFI - please refer to that documentation first.

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:

• GRUB: both the coreboot payload and the EFI GRUB build
• CSMWrap - initially in Libreboot 26.10 but later removed under revision (a CSM wrapper for SeaBIOS)
• Memtest86plus: nice to have, but not essential for booting.

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.

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.

Note that, whether you build from source, or get binaries from upstreams, you can easily run these payloads from standard EDK2 payload in Libreboot, without re-building. The guidance below tells you how to re-build from source to add these legacy payloads back, but for example:

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

fs0:
grub.elf

before running grub.elf, 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.

Alternatively, if you already have an ESP on your system, you could install these to ESP. Refer to upstream documentation for GRUB, ReBIOS and Memtest86plus for how to do that. When doing it to ESP, it’ll appear in the boot menu and you could make it auto-boot via boot order, for example if you wanted ReBIOS to boot first.

The next sections will tell you how to build or otherwise find builds for the legacy payloads, and it will then focus on telling you how to re-compile Libreboot, adding these to PE32 sections inside EDK2 itself, but you don’t have to do that.

You can add any combination of SeaBIOS(ReBIOS), GRUB and MemTest86plus to your EDK2 UEFI firmware. Make the directory efi/ in Libreboot 26.11 src directory or in the latest lbmk.git, thus:

mkdir -p efi/

You can have any combination of these files:

• efi/mt86plus.efi
• efi/grub.elf
• efi/rebios.elf (SeaBIOS CSM payload)

You could for example have just mt86plus, or just rebios, or just GRUB, or GRUB and ReBIOS, or ReBIOS and Memtest… you get the idea.

Now, build your ROM from source (Libreboot firmware). If your board uses EDK2, and one or more of these files exists, they will be placed automatically inside the EDK2 firmware.

To change the build, you can modify these files by replacing them with other builds, or you can remove them, or re-add them here. When you do that, and you re-build your Libreboot image, the EDK2 binary is automatically re-compiled.

Libreboot removed support for building these since release 26.11, to simplify maintenance of the project as pure EDK2 is the recommended default these days, and it is expected that most people will prefer to use this anyway. Those users who do want the old setups, please continue reading as you will now be told how to compile these payloads, or how to get builds for them:

Unlike CSMWrap, the ReBIOS payload actually implements a full VGA BIOS via emulation. This allows you to run a lot of legacy operating systems, with proper VGA; old DOS games will even work!

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

You should find, either in (probably) the bin/ directory when compiling, or in their release archives, a file called rebios.efi - copy this into efi/ under the Libreboot lbmk Git clone. So:

mkdir -p efi/`

Place the binary in elf/ (lbmk) as rebios.efi - NOTE: IOMMU required because it runs a hypervisor for hardware passthrough, emulating BIOS inside the hypervisor. You cannot run this unless you have e.g. Intel VT-d or equivalent on AMD.

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.

Place the binary in elf/ as mt86plus.efi.

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

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.

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.

GRUB is useful, because a lot of people used GRUB in older versions of Libreboot. Many existing Linux setups depend on it. Conversion to EFI is recommended, but not everyone wants to do that.

Canoeboot, a former fork of Libreboot (now Canoeboot is RBoot), was archived since being discontinued. The old docs for SeaBIOS and GRUB can be found there:

• https://canoeboot.org/docs/linux/

The BSD docs were removed from that page, but please note: unlike in the old bare SeaBIOS payload from older releases, or the CSMWrap payload, the ReBIOS payload actually implements full emulation of the classic VGA BIOS. Therefore, BIOS-compatible BSD systems will pretty much just work as you’d expect, so you can just use that. Otherwise, check this on the Wayback Machine:

• https://canoeboot.org/docs/bsd/

Libreboot removed these notes in its version. Since these payloads won’t be maintained anymore, the docs as they were (precisely) before being removed should still be valid, for use with these legacy payloads.

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:

Bloat. UEFI is the future. More seriously:

• GRUB’s build system is extremely buggy, doesn’t do many error checks.
• GRUB drivers are buggy.
• GRUB is generally a maintainence nightmare.

SeaBIOS:

• UEFI is superior in every way.

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.

Please consult Libreboot IRC if you get stuck.

SPDX-License-Identifier: GFDL-1.3-or-later

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.