From 4d091d0271cf6925cb9d0576d08bd3bb5acc8881 Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Fri, 13 Nov 2026 13:54:18 +0900 Subject: [PATCH 1/2] 0.1.0: x86_64-uefi, its conventions, the board's exit and the block-memory functions, QEMU with the edk2 firmware as the runner --- README.md | 2 +- board/qemu-exit.S | 30 ++++++++++++++++++++ mcpp.toml | 68 ++++++++++++++++++++++++++++++++++++++++++++ runtime/mem.S | 72 +++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 171 insertions(+), 1 deletion(-) create mode 100644 board/qemu-exit.S create mode 100644 mcpp.toml create mode 100644 runtime/mem.S diff --git a/README.md b/README.md index c728aa1..20e250c 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/board/qemu-exit.S b/board/qemu-exit.S new file mode 100644 index 0000000..f237ddf --- /dev/null +++ b/board/qemu-exit.S @@ -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 diff --git a/mcpp.toml b/mcpp.toml new file mode 100644 index 0000000..65c2beb --- /dev/null +++ b/mcpp.toml @@ -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.0", "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 diff --git a/runtime/mem.S b/runtime/mem.S new file mode 100644 index 0000000..9129c8c --- /dev/null +++ b/runtime/mem.S @@ -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 From 68a57322f231b007d310ecd64cf3e9a03db6a91c Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Fri, 13 Nov 2026 16:41:42 +0900 Subject: [PATCH 2/2] examples/hello and CI: a UEFI application above openkal, built and run on each host; the runner requires dirun 0.3.1 examples/hello is written against openkal alone (a static initialiser, the arguments, the two clocks, an over-aligned allocation) and returns 42. CI builds it on Linux, macOS and Windows, checks the PE32+ EFI-application header, and runs it through the platform's runner. --- .github/workflows/ci.yml | 97 +++++++++++++++++++++++++++++++++++++ .gitignore | 2 + examples/hello/mcpp.lock | 25 ++++++++++ examples/hello/mcpp.toml | 13 +++++ examples/hello/src/main.cpp | 42 ++++++++++++++++ mcpp.toml | 2 +- 6 files changed, 180 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/ci.yml create mode 100644 .gitignore create mode 100644 examples/hello/mcpp.lock create mode 100644 examples/hello/mcpp.toml create mode 100644 examples/hello/src/main.cpp diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..978451c --- /dev/null +++ b/.github/workflows/ci.yml @@ -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("= 1 && kal_env_arg_count() == static_cast(argc), "the arguments are counted alike"); + void* p = kal_alloc(4096, 64); + check(p != nullptr && (reinterpret_cast(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; +} diff --git a/mcpp.toml b/mcpp.toml index 65c2beb..efbad3c 100644 --- a/mcpp.toml +++ b/mcpp.toml @@ -35,7 +35,7 @@ cmd = ["dirun", "--payload", "{}", "--arch", "x86_64", "--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.0", "xim:qemu-x86@9.2.4-1", "xim:ovmf@9.2.4"] +requires = ["xim:dirun@0.3.1", "xim:qemu-x86@9.2.4-1", "xim:ovmf@9.2.4"] [[platform.define]] triple = "x86_64-uefi"