Skip to content
Merged
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
24 changes: 0 additions & 24 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -202,18 +202,6 @@ jobs:
}
subst mcpp.toml .spec
subst examples/hello/mcpp.toml ../../.spec
# THE PLATFORM, AS THE SPECIFICATION IS: its repository's branch of the same name, else its
# default branch, named by path in the example (the example states the released version).
- name: Point at the platform's working tree
run: |
set -euo pipefail
git clone --quiet https://github.com/mcpplibs/openkal-uefi-platform .platform
if git -C .platform rev-parse --verify --quiet "origin/$OPENKAL_BRANCH" > /dev/null; then
git -C .platform checkout --quiet "origin/$OPENKAL_BRANCH"
fi
f=examples/hello/mcpp.toml
sed "s|^platform = .*$|platform = { path = \"../../.platform\" }|" "$f" > "$f.next" && mv "$f.next" "$f"
grep -q 'path = "../../.platform"' "$f" || { echo "::error::$f was not substituted"; exit 1; }
- name: Install OVMF and qemu
run: sudo apt-get update && sudo apt-get install -y --no-install-recommends ovmf qemu-system-x86

Expand Down Expand Up @@ -476,18 +464,6 @@ jobs:
}
subst mcpp.toml .spec
subst examples/hello/mcpp.toml ../../.spec
# THE PLATFORM, AS THE SPECIFICATION IS: its repository's branch of the same name, else its
# default branch, named by path in the example (the example states the released version).
- name: Point at the platform's working tree
run: |
set -euo pipefail
git clone --quiet https://github.com/mcpplibs/openkal-uefi-platform .platform
if git -C .platform rev-parse --verify --quiet "origin/$OPENKAL_BRANCH" > /dev/null; then
git -C .platform checkout --quiet "origin/$OPENKAL_BRANCH"
fi
f=examples/hello/mcpp.toml
sed "s|^platform = .*$|platform = { path = \"../../.platform\" }|" "$f" > "$f.next" && mv "$f.next" "$f"
grep -q 'path = "../../.platform"' "$f" || { echo "::error::$f was not substituted"; exit 1; }
- name: The EFI application cross-builds
run: |
cd examples/hello
Expand Down
59 changes: 50 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,33 @@
An implementation of [openkal][kal] on UEFI Boot Services, for applications the
firmware loads before an operating system exists.

A program names the target and nothing else; the row `x86_64-uefi`, its compile
and link conventions and its runner are the platform package's
([openkal-uefi-platform][plat]), which selects this implementation:
A program names the target and nothing else. The row `x86_64-uefi`, its compile
and link conventions and its runner are the openkal platform's
([openkal-platform][plat] 0.28.0): the same C library and C++ run-time as on
every other system, openkal-musl and openkal-llvm-runtime, with this
implementation beneath them, so a UEFI application is written in C++23 with
`import std`:

```toml
[target.x86_64-uefi]
platform = "openkal-uefi-platform@0.1.0"
platform = "openkal-platform@0.28.0"
```

```sh
mcpp build --target x86_64-uefi # hello.efi: PE32+, subsystem EFI application
mcpp run --target x86_64-uefi # booted under QEMU with the edk2 firmware
mcpp run --target x86_64-uefi # booted by dirun under QEMU with xim's OVMF
```

## Two arrangements

| | entry | initialisers | `main` |
|---|---|---|---|
| beneath a C library (`standalone`, 0.10.0) | `efi_main` records the firmware's tables and the arguments | the C library's (`.ctors`, through `__libc_start_main`) | called by the C library |
| alone (no C library) | `efi_main` | read from the image's own `.ctors` and `.CRT` sections | called here |

openkal-musl selects `standalone` on `cfg(os = "uefi")`. A program that wants no
C library states `c-abi = false` for the row and calls openkal directly.

## What a program receives

The firmware calls `efi_main`; this implementation records its tables, turns off
Expand All @@ -28,7 +41,7 @@ spaces; firmware that gave none gives one empty name.
| openkal | UEFI |
|---|---|
| `stream` | `SIMPLE_TEXT_OUTPUT_PROTOCOL` (UCS-2, `\n` as CR LF); input reports its end |
| `memory` | `AllocatePool` / `FreePool`, over-allocated for a stricter alignment |
| `memory` | `AllocatePool` / `FreePool`, over-allocated for an alignment below a page; pages for a page or more, placed at the alignment from the memory map (0.10.0) |
| `env` | the load options; no variables, image, loader or system name (absent) |
| `time` | `GetTime` for the wall clock; the processor's counter, measured against `Stall`, for the monotonic one; `Stall` for a sleep |
| `abort` | `Exit` with the status as a warning code, so a starter reads the number |
Expand All @@ -43,22 +56,50 @@ clause 7.19) is what it will claim. The rest have no firmware service beneath th
A status leaves an application through `Exit`, to whoever started it. A board on
which it must leave the machine --- an emulator running it as a test --- defines
`okuefi_board_exit(int)` in its platform package, and `kal_exit` calls it first;
the definition here does nothing. openkal-uefi-platform's writes the status to
the definition here does nothing. openkal-platform's (board/qemu-exit.S) writes the status to
QEMU's debug-exit port, only when the processor names QEMU as its hypervisor.

Standard error is the firmware's `StdErr`. A board on which that console reaches
nothing a reader sees defines `okuefi_board_errors_to_console()` to return
nonzero, and standard error is then `ConOut` (0.10.0): under OVMF in QEMU,
`StdErr` writes nothing to the serial console a runner reads, and a program's
diagnostics and the message of an abort were lost. openkal-platform's board, and
this repository's (examples/board), define it.

## The table offsets are checked, not trusted

These structures are ABI. A field one slot out reads a neighbouring function
pointer, which calls something that exists with the wrong arguments. Every member
this implementation reaches is pinned by a `static_assert` on its offset.

## Interfaces (0.10.0)

`[kernel-abi] provides-interfaces` states `openkal.abort`, `openkal.env`,
`openkal.exec`, `openkal.memory`, `openkal.stream` and `openkal.time` (0.9.0
stated the list as a key of `[package]`, where the engine does not read it).
`openkal.exec` is pages of type `EfiLoaderCode`, protected through the memory
attribute protocol where the firmware offers it: what a loader of images (the
ok-image runner carried as a UEFI application) places code in. A file cannot be
mapped (no `openkal.fs`), so `kal_exec_map_part` answers not supported.

## Verified

`examples/hello`, built with mcpp 2026.11.12.1 and booted by dirun as
`EFI/BOOT/BOOTX64.EFI` under QEMU's q35 with the edk2 firmware (0.45 s, KVM):
a static initialiser ran, the arguments are counted, an over-aligned allocation,
a 20 ms sleep measured as such, the wall clock reads the present; status 42
returned through the board's exit.
returned through the board's exit. 0.10.0 adds an allocation aligned to 16 MiB,
which is pages placed at that alignment and no more than its size.

0.10.0 beneath openkal-musl 0.29.6 and openkal-llvm-runtime 0.20.3 (mcpp
2026.11.13.1, `--release`): a program of `import std` that prints with
`std::println` and sorts with `std::ranges::sort` is a 1.2 MB EFI application;
under OVMF it prints, counts one argument (the empty name) and returns 42 in
0.8 s. An ok image carried by such an application (openkal-platform's carrier,
the core runner placing it through `openkal.exec`) prints, writes to standard
error, throws and catches, and returns its status in 0.4 s with 1 GiB or more:
the carrier's allocator and the image's each place a 32 MiB arena at a 256 MiB
alignment.

[kal]: https://github.com/mcpplibs/openkal
[plat]: https://github.com/mcpplibs/openkal-uefi-platform
[plat]: https://github.com/mcpplibs/openkal-platform
38 changes: 38 additions & 0 deletions examples/board/board/qemu-exit.S
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
/* 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

/* THE BOARD'S ERROR CONSOLE: OVMF's StdErr writes nothing to the serial console the runner reads,
* so standard error is ConOut on this board (okuefi_board_errors_to_console, nonzero). */
.globl okuefi_board_errors_to_console
.def okuefi_board_errors_to_console; .scl 2; .type 32; .endef
okuefi_board_errors_to_console:
mov $1, %eax
ret
68 changes: 68 additions & 0 deletions examples/board/mcpp.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# The board of this repository's example and CI: the `x86_64-uefi' row with no C library above
# this implementation (its arrangement alone), QEMU's q35 with the edk2 firmware as its runner, and
# the board's exit (board/qemu-exit.S) that returns a status through the debug-exit port. A test
# fixture, not a published package: applications take the row from openkal-platform (0.28.0), over
# openkal-musl and openkal-llvm-runtime. It was openkal-uefi-platform 0.1.0, folded here and into
# openkal-platform; runtime/mem.S supplies the four memory functions a compiler calls, there being
# no C library.
[package]
namespace = "mcpplibs"
name = "uefi-board"
version = "0.1.0"
description = "The board of openkal-uefi's example: the x86_64-uefi row with no C library, QEMU with the edk2 firmware"
license = "Apache-2.0"
authors = ["mcpplibs"]
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.10.0"
"c-abi" = false
"c++-abi" = false
"compiler-runtime" = false
72 changes: 72 additions & 0 deletions examples/board/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
4 changes: 3 additions & 1 deletion examples/hello/mcpp.toml
Original file line number Diff line number Diff line change
Expand Up @@ -11,5 +11,7 @@ openkal = "^0.25.0"
# The implementation under change; the platform names openkal-uefi by version.
openkal-uefi = { path = "../..", override = true }

# The arrangement with no C library, on this repository's board (examples/board). An application
# with the C library and C++ run-time names openkal-platform instead (README).
[target.x86_64-uefi]
platform = "openkal-uefi-platform@0.1.0"
platform = { path = "../board" }
9 changes: 8 additions & 1 deletion examples/hello/src/main.cpp
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// 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.
// the arguments, the two clocks, two over-aligned allocations, and a status the board carries out.
import openkal.stream;
import openkal.abort;
import openkal.memory;
Expand Down Expand Up @@ -32,6 +32,13 @@ int main(int argc, char**, char**) {
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);
// An alignment of a page or more is pages placed at it (0.10.0), which over-allocating would
// have cost in backed memory (a C library's allocator states 256 MiB for an arena; 16 MiB here
// fits the 256 MiB machine this example boots in).
void* arena = kal_alloc(4u << 20, 16u << 20);
check(arena != nullptr && (reinterpret_cast<kal_uintptr>(arena) & ((16u << 20) - 1)) == 0,
"an allocation aligned to 16 MiB");
kal_free(arena, 4u << 20, 16u << 20);
const kal_duration t0 = kal_time_monotonic();
kal_time_sleep(20u * 1000u * 1000u);
const kal_duration t1 = kal_time_monotonic();
Expand Down
19 changes: 16 additions & 3 deletions mcpp.toml
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
[package]
namespace = "mcpplibs"
name = "openkal-uefi"
version = "0.9.0"
version = "0.10.0"
description = "An implementation of openkal on UEFI Boot Services, for applications the firmware loads before an operating system exists"
license = "Apache-2.0"

Expand All @@ -28,15 +28,28 @@ license = "Apache-2.0"
# package answers to; several packages answer to it and the engine knows none
# of them by name.
provides = ["mcpp:kernel-abi=openkal"]
# The interfaces this implementation provides, which `kal_interfaces()' answers too (src/version.cpp).
provides-interfaces = ["openkal.abort", "openkal.env", "openkal.memory", "openkal.stream", "openkal.time"]
authors = ["mcpplibs"]
repo = "https://github.com/mcpplibs/openkal-uefi"

# The interfaces this implementation provides, which `kal_interfaces()' answers too
# (src/version.cpp). 0.9.0 stated the list as a key of [package], where the engine does not read
# it, so a consumer bound every interface (openkal-run then referred to fifteen this
# implementation does not have); the list belongs to [kernel-abi].
[kernel-abi]
provides-interfaces = ["openkal.abort", "openkal.env", "openkal.exec", "openkal.memory", "openkal.stream", "openkal.time"]

[dependencies]
# Every patch release of the specification's minor version (openkal clause 8).
openkal = "^0.25.0"

# The program's entry belongs to this implementation in both arrangements. With
# no C library it runs the image's initialisers and calls `main`; `standalone`
# (0.10.0) is the arrangement beneath a C library written above openkal
# (openkal-musl names it so on `cfg(os = "uefi")`), whose `__libc_start_main`
# receives the program and does both.
[features]
standalone = { defines = ["OKUEFI_STANDALONE"] }

[build]
flags = [
{ glob = "src/**", cxxflags = ["-fno-exceptions", "-fno-rtti",
Expand Down
Loading
Loading