Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 97 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
name: CI

# What this workflow asserts about openkal-uefi-platform: on each host its runner states, mcpp builds
# examples/hello for x86_64-uefi (a PE32+ EFI application above openkal-uefi), and `mcpp run` boots it
# under QEMU's q35 with the edk2 firmware through dirun, the three installed by the run itself, and
# returns its status (42).

on:
push:
branches: [main]
pull_request:
workflow_dispatch:

concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

env:
MCPP_VERSION: 2026.11.12.1
XLINGS_VERSION: v2026.10.26.1
XLINGS_NON_INTERACTIVE: '1'

jobs:
uefi:
name: x86_64-uefi (${{ matrix.os }})
runs-on: ${{ matrix.os }}
timeout-minutes: 60
strategy:
fail-fast: false
matrix:
os: [ubuntu-24.04, macos-15, windows-2025]
defaults:
run:
shell: bash
steps:
- uses: actions/checkout@v4

- name: Install xlings (Unix)
if: runner.os != 'Windows'
run: |
curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 \
https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh \
| bash -s "$XLINGS_VERSION"
echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
- name: Install xlings (Windows)
if: runner.os == 'Windows'
shell: pwsh
run: |
irm https://d2learn.org/xlings-install.ps1.txt | iex
"$env:USERPROFILE\.xlings\subos\current\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append

- name: Install mcpp
run: |
set -euo pipefail
xlings config --mirror GLOBAL 2>/dev/null || true
for attempt in 1 2 3 4 5; do
xlings update > /dev/null 2>&1 || true
if xlings install "xim:mcpp@$MCPP_VERSION" -y -g; then break; fi
[ "$attempt" = 5 ] && { echo "::error::mcpp@$MCPP_VERSION could not be installed"; exit 1; }
sleep 30
done
mcpp self config --mirror GLOBAL
mcpp --version

- name: Enable KVM (Linux)
if: runner.os == 'Linux'
run: |
if [ -e /dev/kvm ]; then
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm.rules
sudo udevadm control --reload-rules && sudo udevadm trigger --name-match=kvm
fi

- name: A UEFI application, built and run
working-directory: examples/hello
run: |
set -euo pipefail
mcpp build --target x86_64-uefi
app=$(find target/x86_64-uefi -path '*bin/hello.efi' -type f | head -1)
[ -n "$app" ] || { echo "::error::no hello.efi"; exit 1; }
python3 - "$app" <<'PY'
import struct, sys
data = open(sys.argv[1], "rb").read()
pe = struct.unpack_from("<I", data, 0x3c)[0]
assert data[pe:pe + 4] == b"PE\0\0", "not a PE image"
machine = struct.unpack_from("<H", data, pe + 4)[0]
magic, = struct.unpack_from("<H", data, pe + 24)
subsystem, = struct.unpack_from("<H", data, pe + 24 + 68)
assert (machine, magic, subsystem) == (0x8664, 0x20b, 10), (hex(machine), hex(magic), subsystem)
print("PE32+ x86-64, subsystem EFI application")
PY
set +e
mcpp run --target x86_64-uefi | tee run.log
status=${PIPESTATUS[0]}
set -e
grep -q "hello from openkal over UEFI" run.log && grep -q "all held" run.log \
|| { echo "::error::the application's output"; exit 1; }
[ "$status" = 42 ] || { echo "::error::the status is $status, not 42"; exit 1; }
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
target/
*.log
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ mcpp run --target x86_64-uefi # booted by dirun under QEMU; the status com
| freestanding, no red zone, UCS-2 `wchar_t`, entry `efi_main` | `[platform.build]` |
| the block-memory functions a compiler calls (no C library) | `runtime/mem.S` |
| the board's exit: the status to QEMU's debug-exit port, only under QEMU | `board/qemu-exit.S` |
| the runner: dirun boots the application as `EFI/BOOT/BOOTX64.EFI` | `[platform.runner]` |
| the runner: dirun boots the application as `EFI/BOOT/BOOTX64.EFI` under qemu-x86's emulator with ovmf's code image, the three installed by the first run on Linux, macOS and Windows | `[platform.runner]` |

The engine knows no UEFI: everything above is this package's (design P15).

Expand Down
30 changes: 30 additions & 0 deletions board/qemu-exit.S
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
/* THE BOARD'S EXIT: a status leaves the machine through QEMU's `isa-debug-exit' device (port 0xf4),
* whose write ends the emulator with (status << 1) | 1. openkal-uefi calls this before Exit
* (okuefi_board_exit); its own definition does nothing.
*
* Only under QEMU. The processor states a hypervisor in CPUID leaf 1 (ECX bit 31) and names it in
* leaf 0x40000000 ("TCGTCGTCGTCG" for QEMU's translator, "KVMKVMKVM" under KVM); on a machine
* that is neither, nothing is written and the status leaves through Exit alone. The Microsoft x64
* convention: the status arrives in ECX. */
.text
.globl okuefi_board_exit
.def okuefi_board_exit; .scl 2; .type 32; .endef
okuefi_board_exit:
push %rbx
mov %ecx, %r8d
mov $1, %eax
cpuid
bt $31, %ecx
jnc 1f
mov $0x40000000, %eax
cpuid
cmp $0x54474354, %ebx /* "TCGT" */
je 2f
cmp $0x4b4d564b, %ebx /* "KVMK" */
jne 1f
2: mov %r8d, %eax
and $0xff, %eax
mov $0xf4, %dx
out %eax, %dx
1: pop %rbx
ret
25 changes: 25 additions & 0 deletions examples/hello/mcpp.lock
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Auto-generated by mcpp. Do not edit by hand.
# Records what this build resolved. It does not yet pin future builds:
# index dependencies are re-resolved from their constraints each time.
# dev-dependencies are excluded: only `mcpp test` resolves them, and this
# file must not change depending on which command ran last.
version = 2

[target."x86_64-uefi"]
identity = "x86_64-uefi"

[package."openkal"]
namespace = "mcpplibs"
version = "0.25.1"
source = "index+mcpplibs@0.25.1"
hash = "fnv1a:68ef4b0777428faf"
targets = ["x86_64-uefi"]

[package."openkal-uefi"]
namespace = "mcpplibs"
version = "0.9.0"
source = "index+mcpplibs@0.9.0"
hash = "fnv1a:aabd72ca63b5e36e"
origin = "platform"
targets = ["x86_64-uefi"]

13 changes: 13 additions & 0 deletions examples/hello/mcpp.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
[package]
name = "hello"
version = "0.1.0"

[targets.hello]
kind = "bin"
main = "src/main.cpp"

[dependencies]
openkal = "^0.25.0"

[target.x86_64-uefi]
platform = { path = "../.." }
42 changes: 42 additions & 0 deletions examples/hello/src/main.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
// A UEFI application written against openkal, with no UEFI type in sight: a static initialiser,
// the arguments, the two clocks, an over-aligned allocation, and a status the board carries out.
import openkal.stream;
import openkal.abort;
import openkal.memory;
import openkal.env;
import openkal.time;

namespace {
void say(const char* s) {
kal_uintptr n = 0;
while (s[n]) ++n;
kal_stream_write(kal_stdout(), s, n);
}
int failures = 0;
void check(bool ok, const char* what) {
say(ok ? " ok " : " FAIL ");
say(what);
say("\n");
if (!ok) ++failures;
}
struct initialised {
int value = 7;
initialised() { value = 42; }
} g_initialised;
} // namespace

int main(int argc, char**, char**) {
say("hello from openkal over UEFI\n");
check(g_initialised.value == 42, "a static initialiser ran before main");
check(argc >= 1 && kal_env_arg_count() == static_cast<kal_uintptr>(argc), "the arguments are counted alike");
void* p = kal_alloc(4096, 64);
check(p != nullptr && (reinterpret_cast<kal_uintptr>(p) & 63) == 0, "an over-aligned allocation");
kal_free(p, 4096, 64);
const kal_duration t0 = kal_time_monotonic();
kal_time_sleep(20u * 1000u * 1000u);
const kal_duration t1 = kal_time_monotonic();
check(t1 - t0 >= 19u * 1000u * 1000u && t1 - t0 < 2000u * 1000u * 1000u, "a sleep of 20 ms is measured as such");
check(kal_time_wall() > 1700000000ull * 1000000000ull, "the wall clock reads the present");
say(failures ? "FAILED\n" : "all held\n");
return failures ? 1 : 42;
}
68 changes: 68 additions & 0 deletions mcpp.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# openkal-uefi-platform: UEFI applications for x86_64 (openkal on Boot Services), as a platform
# package (mcpp SPEC-013). The row is data here, not in the engine: an application is PE32+ with
# the EFI_APPLICATION subsystem, entered at `efi_main' in the Microsoft x64 convention, which the
# `x86_64-unknown-uefi' compiler target uses. The board is QEMU's q35 with the edk2 firmware: its
# runner boots the application as the firmware's default boot file and reads the status the board
# exit (board/qemu-exit.S) writes to the debug-exit port.
[package]
namespace = "mcpplibs"
name = "openkal-uefi-platform"
version = "0.1.0"
description = "UEFI applications for x86_64 above openkal-uefi: the x86_64-uefi row, its compile and link conventions, and QEMU's board with the edk2 firmware as its runner"
license = "Apache-2.0"
authors = ["mcpplibs"]
repo = "https://github.com/mcpplibs/openkal-uefi-platform"
mcpp = ">=2026.11.12.1"

[platform]
targets = ["x86_64-uefi"]
toolchain = "llvm@23.1.3"


# The board's runner: dirun boots the application as the firmware's default boot file and reads the
# status the board exit writes to the debug-exit port. The emulator is qemu-x86's program, named by
# path (a package's program is not on PATH; the package is built for each host below), and the
# firmware is ovmf's code image (edk2's x86_64 firmware), the same file on every host. The code image
# is a flash device (as `-bios' QEMU refuses it); the application's directory is a read-only virtio
# disk (q35's own controller refuses a read-only drive, and a writable FAT image needs a temporary
# file QEMU makes outside the run's directory). Measured: 0.43 s to the status under KVM.
[platform.runner]
cmd = ["dirun", "--payload", "{}", "--arch", "x86_64",
"--emulator", "{pkg:qemu-x86}/bin/qemu-system-x86_64", "--machine", "q35",
"--emulator-arg", "-drive", "--emulator-arg", "if=pflash,format=raw,readonly=on,file={pkg:ovmf}/share/edk2/edk2-x86_64-code.fd",
"--emulator-arg", "-drive", "--emulator-arg", "if=virtio,format=raw,readonly=on,file=fat:{dir}",
"--emulator-arg", "-device", "--emulator-arg", "isa-debug-exit,iobase=0xf4,iosize=0x04",
"--place", "EFI/BOOT/BOOTX64.EFI", "--status", "debug-exit",
"--after", "BdsDxe: starting [^\\n]*\\n"]
hosts = ["linux-x86_64", "linux-aarch64", "macos-aarch64", "windows-x86_64"]
requires = ["xim:dirun@0.3.1", "xim:qemu-x86@9.2.4-1", "xim:ovmf@9.2.4"]

[[platform.define]]
triple = "x86_64-uefi"
clang-triple = "x86_64-unknown-uefi"
object-format = "pe"
execution = "uefi"
exe-suffix = ".efi"

[[platform.provider]]
serves = ["x86_64-uefi"]

# Freestanding: no C library, no red zone (firmware interrupts run on the application's stack),
# 16-bit wide characters (UEFI's text is UCS-2), no stack probe calls (no runtime to supply
# `__chkstk').
[platform.build]
ldflags = ["-nostdlib", "-Wl,-entry:efi_main", "-Wl,-subsystem:efi_application"]
cflags = ["-ffreestanding", "-fshort-wchar", "-mno-red-zone", "-mno-stack-arg-probe"]
cxxflags = ["-ffreestanding", "-fshort-wchar", "-mno-red-zone", "-mno-stack-arg-probe",
"-fno-exceptions", "-fno-rtti"]

# The board's exit, and the block-memory functions a compiler calls (no C library here).
[platform.link]
driver = "compiler"
inputs = [{ file = "board/qemu-exit.S" }, { file = "runtime/mem.S" }]

[platform.layers]
"kernel-abi" = "openkal-uefi@0.9.0"
"c-abi" = false
"c++-abi" = false
"compiler-runtime" = false
72 changes: 72 additions & 0 deletions runtime/mem.S
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
/* The four functions a compiler calls for a block of memory (memcpy, memmove, memset, memcmp),
* which a freestanding implementation may require of the C library (openkal-linux states the
* same exception). This platform has no C library, so it supplies them. The Microsoft x64
* convention: arguments in RCX, RDX, R8; RDI and RSI are the callee's to preserve. */
.text

.globl memset
.def memset; .scl 2; .type 32; .endef
memset: /* (dst, c, n) -> dst */
push %rdi
mov %rcx, %r9
mov %rcx, %rdi
mov %edx, %eax
mov %r8, %rcx
rep stosb
mov %r9, %rax
pop %rdi
ret

.globl memcpy
.def memcpy; .scl 2; .type 32; .endef
memcpy: /* (dst, src, n) -> dst */
push %rdi
push %rsi
mov %rcx, %r9
mov %rcx, %rdi
mov %rdx, %rsi
mov %r8, %rcx
rep movsb
mov %r9, %rax
pop %rsi
pop %rdi
ret

.globl memmove
.def memmove; .scl 2; .type 32; .endef
memmove: /* (dst, src, n) -> dst; the blocks may overlap */
push %rdi
push %rsi
mov %rcx, %r9
mov %rcx, %rdi
mov %rdx, %rsi
mov %r8, %rcx
cmp %rsi, %rdi
jbe 1f /* the destination is below: forwards */
lea -1(%rsi,%rcx), %rsi /* otherwise backwards, from the last byte */
lea -1(%rdi,%rcx), %rdi
std
rep movsb
cld
jmp 2f
1: rep movsb
2: mov %r9, %rax
pop %rsi
pop %rdi
ret

.globl memcmp
.def memcmp; .scl 2; .type 32; .endef
memcmp: /* (a, b, n) -> <0, 0, >0 */
xor %eax, %eax
test %r8, %r8
jz 2f
1: movzbl (%rcx), %eax
movzbl (%rdx), %r9d
sub %r9d, %eax
jnz 2f
inc %rcx
inc %rdx
dec %r8
jnz 1b
2: ret
Loading