Nelua

Core · the boot manager

neboot

A UEFI boot menu written in Nelua. It starts Cascadia with Theseus Init or OpenRC recovery from the same kernel and initramfs. A third entry starts another EFI application.

Time through the Core boot menu

On 21 November 2026, four QEMU TCG boots of the Core EFI image reached the menu in a median 3.99 s. With the first entry selected immediately, kernel loading through the StartImage handoff took 0.26 s. The next 12.37 s elapsed before the serial shell reported the Theseus PID 1 executable.

Boot in QEMU

In the neboot checkout (repository access required), put the Nelua fork, necc and nelinker on your PATH. If you installed the necc SDK outside its default location, set NECC_SYSROOT to the SDK directory.

Stage an x86-64 EFI-stub kernel and its matching Cascadia initramfs. Replace the example paths with your local files.

make stage KERNEL=/path/to/vmlinuz INITRD=/path/to/initramfs
Starting from a Cascadia ISO

With xorriso installed, this command extracts both boot files from the same verified local ISO and stages them in build/esp.

make stage-iso ISO=/path/to/cascadia-native-x86_64.iso

Open the serial menu. The script uses Python 3, sfdisk and mtools to prepare a temporary disk, then boots it with QEMU and x86-64 OVMF.

python3 tests/smoke-ovmf.py --esp build/esp --interactive
  • 1 boots Cascadia with Theseus Init as PID 1.
  • 2 boots Cascadia with OpenRC as PID 1 for recovery.
  • 3 runs the second EFI application. Control returns to the menu when it exits or the file is missing.
  • Q returns to firmware.

To exit QEMU from the menu or a running guest, press Ctrl+A, then X.

Select a firmware pair or use software emulation

If the script cannot find your firmware, set OVMF_CODE and OVMF_VARS to a matching x86-64 OVMF pair with Secure Boot disabled. The test copies the variables file for each boot. QEMU uses KVM when your account can access /dev/kvm and software emulation otherwise. Set QEMU_ACCEL=tcg to select software emulation explicitly.

Repeat the two-boot test

With the boot files staged, run the automated check from the same checkout. It tests the child application, repeats with the child missing, and checks PID 1 after each Linux boot. The Theseus guest also makes an HTTPS request to example.com.

python3 tests/smoke-ovmf.py --esp build/esp --logs build/logs --check-internet

Compare the PASS lines with the recorded OVMF results. The serial transcripts are saved in build/logs/theseus-chainload.log and build/logs/openrc-missing.log.

If HTTPS fails, the test reports the guest’s curl exit code, HTTP status and serial log path.

From Nelua to BOOTX64.EFI

  1. The Nelua fork emits freestanding C. Nelua records describe the firmware tables. Both the exported entry point and the function types stored in protocol records carry ms_abi, so the convention survives an indirect call through a record field.
  2. necc compiles the generated C to x86-64 ELF objects using its native backend. The SDK supplies TinyCC for preprocessing and assembly.
  3. nelinker reads those objects and writes a PE32+ EFI application. Its base relocation table tells the firmware which absolute addresses to adjust if the image moves.

For example, the console’s write function has type function<ms_abi>(pointer, *uint16): usize. Calling it passes the console and a pointer to UTF-16 text back to firmware.

Both Linux entries start the EFI stub in /boot/vmlinuz on the EFI System Partition and pass /boot/initramfs in the kernel’s load options. The chainload entry starts /EFI/TOOLS/second.efi from the same partition.

What ran under OVMF

On , x86-64 QEMU with KVM and OVMF booted the image with Secure Boot disabled. The loader requested base 0x100000000. On the first host, firmware placed it at 0x3e2fb000 for both menu entries. A fresh build on a second host produced the same EFI binary. There, OVMF placed it at 0x3e10c000. The test compares the observed address to the preferred base on each boot.

  • With the child application present, it printed a message and returned to the menu. Selecting Theseus then booted Linux with theseus-init as PID 1. An HTTPS request from the guest returned 200.
  • With the child file missing, the menu reported EFI_NOT_FOUND and appeared again. Selecting OpenRC recovery booted Linux with openrc-init as PID 1.

A separate calling-convention test used a GCC-built firmware shim to call the Nelua entry point. The entry point called the shim’s console function through a protocol pointer and returned 42 to the caller.

Read the console and ABI test excerpts (plain text)