--- title: Re-adding legacy payloads to Libreboot x-toc-enable: true ... This page pertains to [EDK2 UEFI](edk2.md) - please refer to that documentation first. 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: * 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. Install dependencies ----------------- If you're building the legacy payloads (see below) from source, you need build dependencies. Check [the build guide](../build/) 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 ----------- 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. Add SeaBIOS CSM ---------------- 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](../build/) (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! SeaBIOS ----- Clone in Git and build it using the instructions in their README, or get a release build provided by that project, here: 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.** MemTest86plus ------------ Clone 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 - 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`. GRUB ---- 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. Build the Libreboot image ----------------- Refer to [build instructions](../build/) - 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: * 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: * 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: Why were these payloads removed? ----------- 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"