From 44d2d383d6b0fd285192a6381d0f6e2835654668 Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Fri, 13 Nov 2026 21:37:35 +0900 Subject: [PATCH 1/3] 0.10.0: standalone beneath a C library, openkal.exec, the interfaces under [kernel-abi]; the example's board folded in --- .github/workflows/ci.yml | 24 ------- README.md | 43 ++++++++++--- examples/board/board/qemu-exit.S | 30 +++++++++ examples/board/mcpp.toml | 68 ++++++++++++++++++++ examples/board/runtime/mem.S | 72 +++++++++++++++++++++ examples/hello/mcpp.toml | 4 +- mcpp.toml | 19 +++++- src/exec.cpp | 104 +++++++++++++++++++++++++++++++ src/start.cpp | 20 +++++- src/uefi.h | 36 ++++++++++- src/version.cpp | 6 +- 11 files changed, 384 insertions(+), 42 deletions(-) create mode 100644 examples/board/board/qemu-exit.S create mode 100644 examples/board/mcpp.toml create mode 100644 examples/board/runtime/mem.S create mode 100644 src/exec.cpp diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fa175b0..fb27d37 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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 @@ -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 diff --git a/README.md b/README.md index 8e592b3..b2a193f 100644 --- a/README.md +++ b/README.md @@ -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 @@ -43,7 +56,7 @@ 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. ## The table offsets are checked, not trusted @@ -52,6 +65,16 @@ 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 @@ -60,5 +83,11 @@ 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. +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. + [kal]: https://github.com/mcpplibs/openkal -[plat]: https://github.com/mcpplibs/openkal-uefi-platform +[plat]: https://github.com/mcpplibs/openkal-platform diff --git a/examples/board/board/qemu-exit.S b/examples/board/board/qemu-exit.S new file mode 100644 index 0000000..f237ddf --- /dev/null +++ b/examples/board/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/examples/board/mcpp.toml b/examples/board/mcpp.toml new file mode 100644 index 0000000..ab952a4 --- /dev/null +++ b/examples/board/mcpp.toml @@ -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 diff --git a/examples/board/runtime/mem.S b/examples/board/runtime/mem.S new file mode 100644 index 0000000..9129c8c --- /dev/null +++ b/examples/board/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 diff --git a/examples/hello/mcpp.toml b/examples/hello/mcpp.toml index 7c8727f..872c4fb 100644 --- a/examples/hello/mcpp.toml +++ b/examples/hello/mcpp.toml @@ -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" } diff --git a/mcpp.toml b/mcpp.toml index 3b5a2a5..b755101 100644 --- a/mcpp.toml +++ b/mcpp.toml @@ -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" @@ -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", diff --git a/src/exec.cpp b/src/exec.cpp new file mode 100644 index 0000000..e624bc6 --- /dev/null +++ b/src/exec.cpp @@ -0,0 +1,104 @@ +// openkal.exec on UEFI Boot Services: memory a program may execute, which a loader of images needs +// (the ok-image runner, carried as a UEFI application, places an image's code here). +// +// A region is pages of type EfiLoaderCode, the type the firmware gives an image it loads, zeroed. +// Firmware that enforces "never writable and executable at once" offers the memory attribute +// protocol (UEFI 2.10): a region is then made not executable when it is reserved, and publishing +// a part makes it read-only and executable; sealing a part makes it read-only and not executable. +// Firmware that offers no such protocol maps every page writable and executable, and has nothing to +// change: publishing is then a statement the caller makes, as the interface allows. +// +// A file cannot be mapped (there is no openkal.fs here), so kal_exec_map_part answers +// kal_err_not_supported, a property of the environment. +#include +#include + +#include "uefi.h" +#include "state.h" + +namespace { + +constexpr kal_uintptr kPage = 4096; + +efi_memory_attribute_protocol* attributes() { + static bool asked = false; + static efi_memory_attribute_protocol* protocol = nullptr; + if (!asked) { + asked = true; + void* p = nullptr; + auto* bs = okuefi::self().st->boot_services; + if (bs->locate_protocol(&kMemoryAttributeProtocol, nullptr, &p) == EFI_SUCCESS) + protocol = static_cast(p); + } + return protocol; +} + +kal_uintptr pages_of(kal_uintptr size) { return (size + kPage - 1) / kPage; } + +void* reserve(int how, unsigned long long at, kal_uintptr size) { + if (size == 0) return nullptr; + unsigned long long address = at; + const kal_uintptr pages = pages_of(size); + if (okuefi::self().st->boot_services->allocate_pages(how, EfiLoaderCode, pages, &address) != EFI_SUCCESS) + return nullptr; + auto* p = reinterpret_cast(address); + for (kal_uintptr i = 0; i < pages * kPage; ++i) p[i] = 0; + if (auto* a = attributes()) + a->set_memory_attributes(a, address, pages * kPage, EFI_MEMORY_XP); + return p; +} + +int protect(void* region, kal_uintptr offset, kal_uintptr size, bool execute) { + if (!region || size == 0 || offset % kPage || size % kPage) return kal_err_invalid; + auto* a = attributes(); + if (!a) return kal_ok; + const auto base = reinterpret_cast(region) + offset; + if (a->set_memory_attributes(a, base, size, EFI_MEMORY_RO) != EFI_SUCCESS) return kal_err_io; + const efi_status s = execute ? a->clear_memory_attributes(a, base, size, EFI_MEMORY_XP) + : a->set_memory_attributes(a, base, size, EFI_MEMORY_XP); + return s == EFI_SUCCESS ? kal_ok : kal_err_io; +} + +} // namespace + +extern "C" { + +void* kal_exec_alloc(kal_uintptr size) { return reserve(AllocateAnyPages, 0, size); } + +void* kal_exec_alloc_at(void* at, kal_uintptr size) { + const auto address = reinterpret_cast(at); + if (!at || size == 0 || address % kPage) return nullptr; + return reserve(AllocateAddress, address, size); +} + +int kal_exec_publish(void* p, kal_uintptr size) { + return protect(p, 0, pages_of(size) * kPage, true); +} + +int kal_exec_publish_part(void* region, kal_uintptr offset, kal_uintptr size) { + return protect(region, offset, size, true); +} + +int kal_exec_seal_part(void* region, kal_uintptr offset, kal_uintptr size, kal_uintptr flags) { + if (flags & ~KAL_EXEC_SEAL_FOREVER) return kal_err_invalid; + return protect(region, offset, size, false); +} + +kal_uintptr kal_exec_granularity(void) { return kPage; } + +int kal_exec_map_part(void*, kal_uintptr, kal_uintptr, struct kal_file, kal_u64, kal_uintptr) { + return kal_err_not_supported; +} + +void kal_exec_free(void* p, kal_uintptr size) { + if (!p || size == 0) return; + if (auto* a = attributes()) + a->clear_memory_attributes(a, reinterpret_cast(p), pages_of(size) * kPage, + EFI_MEMORY_RO | EFI_MEMORY_XP); + okuefi::self().st->boot_services->free_pages(reinterpret_cast(p), pages_of(size)); +} + +// Placement at a chosen address is offered (AllocateAddress); publishing again is not. +kal_uintptr kal_exec_props(void) { return KAL_EXEC_PROP_AVAILABLE | KAL_EXEC_PROP_PLACE; } + +} // extern "C" diff --git a/src/start.cpp b/src/start.cpp index 69230e6..bb03d32 100644 --- a/src/start.cpp +++ b/src/start.cpp @@ -11,6 +11,15 @@ extern "C" int main(int, char**, char**); +#ifdef OKUEFI_STANDALONE +// THE STANDALONE ARRANGEMENT (0.10.0): a C library above this implementation (openkal-musl) +// receives the program at the name every C library's hand-over has. It obtains the arguments +// through openkal.env and runs the initialisers itself, so this entry records the firmware's +// tables and the arguments and hands over; the image's sections are not walked here. +extern "C" int __libc_start_main(int (*)(int, char**, char**), int, char**, + void (*)(), void (*)(), void (*)()); +#endif + namespace { // THE STATIC INITIALISERS are found in this image's own section table. A compiler for this target @@ -121,12 +130,17 @@ extern "C" efi_status efi_main(efi_handle image, efi_system_table* st) { if (st->boot_services->handle_protocol(image, &kLoadedImageProtocol, reinterpret_cast(&li)) != EFI_SUCCESS) li = nullptr; record_arguments(li); - run_initialisers(li ? li->image_base : nullptr); // Position zero is the name the program was started by; firmware that gave none gives an empty - // name rather than none (openkal.env). + // name rather than none (openkal.env), in both arrangements. static char name[] = ""; static char* unnamed[] = {name, nullptr}; - static char* no_environment[] = {nullptr}; if (s.argc == 0) { s.argc = 1; s.argv = unnamed; } +#ifdef OKUEFI_STANDALONE + __libc_start_main(main, 0, nullptr, nullptr, nullptr, nullptr); + kal_exit(127); +#else + run_initialisers(li ? li->image_base : nullptr); + static char* no_environment[] = {nullptr}; kal_exit(main(s.argc, s.argv, no_environment)); +#endif } diff --git a/src/uefi.h b/src/uefi.h index d8ade89..8fbb19e 100644 --- a/src/uefi.h +++ b/src/uefi.h @@ -73,8 +73,9 @@ struct efi_boot_services { efi_table_header hdr; /* 0 */ void* raise_tpl; /* 24 */ void* restore_tpl; /* 32 */ - void* allocate_pages; /* 40 */ - void* free_pages; /* 48 */ + efi_status (*allocate_pages)(int type, int memory_type, efi_uintn pages, + unsigned long long* memory); /* 40 */ + efi_status (*free_pages)(unsigned long long memory, efi_uintn pages); /* 48 */ void* get_memory_map; /* 56 */ efi_status (*allocate_pool)(int type, efi_uintn size, void** buf); /* 64 */ efi_status (*free_pool)(void* buf); /* 72 */ @@ -103,6 +104,14 @@ struct efi_boot_services { efi_status (*stall)(efi_uintn microseconds); /* 248 */ efi_status (*set_watchdog_timer)(efi_uintn seconds, unsigned long long code, efi_uintn data_size, efi_char16* data); /* 256 */ + void* connect_controller; /* 264 */ + void* disconnect_controller; /* 272 */ + void* open_protocol; /* 280 */ + void* close_protocol; /* 288 */ + void* open_protocol_information; /* 296 */ + void* protocols_per_handle; /* 304 */ + void* locate_handle_buffer; /* 312 */ + efi_status (*locate_protocol)(const struct efi_guid*, void* registration, void** iface); /* 320 */ }; static_assert(__builtin_offsetof(efi_boot_services, allocate_pool) == 64, @@ -114,6 +123,13 @@ static_assert(__builtin_offsetof(efi_boot_services, exit_boot_services) == 232); static_assert(__builtin_offsetof(efi_boot_services, handle_protocol) == 152); static_assert(__builtin_offsetof(efi_boot_services, stall) == 248); static_assert(__builtin_offsetof(efi_boot_services, set_watchdog_timer) == 256); +static_assert(__builtin_offsetof(efi_boot_services, allocate_pages) == 40); +static_assert(__builtin_offsetof(efi_boot_services, free_pages) == 48); +static_assert(__builtin_offsetof(efi_boot_services, locate_protocol) == 320); + +/* EFI_ALLOCATE_TYPE and EFI_MEMORY_TYPE: the two this implementation asks for. */ +enum { AllocateAnyPages = 0, AllocateAddress = 2 }; +enum { EfiLoaderCode = 1 }; struct efi_guid { efi_u32 a; efi_u16 b, c; efi_u8 d[8]; }; @@ -176,4 +192,20 @@ static_assert(__builtin_offsetof(efi_system_table, std_err) == 80); static_assert(__builtin_offsetof(efi_system_table, boot_services) == 96, "EFI_SYSTEM_TABLE.BootServices follows RuntimeServices"); +/* EFI_MEMORY_ATTRIBUTE_PROTOCOL (UEFI 2.10): the protection of a range of memory. Firmware that + * enforces "no page both writable and executable" offers it; older firmware maps every page both, + * and has nothing to ask. */ +struct efi_memory_attribute_protocol { + efi_status (*get_memory_attributes)(efi_memory_attribute_protocol*, unsigned long long base, + unsigned long long length, unsigned long long* attributes); + efi_status (*set_memory_attributes)(efi_memory_attribute_protocol*, unsigned long long base, + unsigned long long length, unsigned long long attributes); + efi_status (*clear_memory_attributes)(efi_memory_attribute_protocol*, unsigned long long base, + unsigned long long length, unsigned long long attributes); +}; +inline constexpr efi_guid kMemoryAttributeProtocol = { + 0xf4560cf6, 0x40ec, 0x4b4a, {0xa1, 0x92, 0xbf, 0x1d, 0x57, 0xd0, 0xb1, 0x89}}; +inline constexpr unsigned long long EFI_MEMORY_XP = 0x0000000000004000ull; +inline constexpr unsigned long long EFI_MEMORY_RO = 0x0000000000020000ull; + #endif /* OPENKAL_UEFI_H */ diff --git a/src/version.cpp b/src/version.cpp index d48f0c8..b92c484 100644 --- a/src/version.cpp +++ b/src/version.cpp @@ -6,11 +6,13 @@ extern "C" { kal_u64 kal_version(void) { return KAL_VERSION; } -// Firmware supplies a console, a pool, a clock and the options an image was started with. +// Firmware supplies a console, a pool, a clock, the options an image was started with, and pages +// of code (openkal.exec, 0.10.0: what a loader of images places their code in). // `openkal.process' waits for `openkal.fs' (a program is named through a directory handle); // the rest have no firmware service beneath them here. kal_u64 kal_interfaces(void) { - return KAL_IFACE_ABORT | KAL_IFACE_STREAM | KAL_IFACE_MEMORY | KAL_IFACE_ENV | KAL_IFACE_TIME; + return KAL_IFACE_ABORT | KAL_IFACE_STREAM | KAL_IFACE_MEMORY | KAL_IFACE_ENV | KAL_IFACE_TIME | + KAL_IFACE_EXEC; } } From ab6e950dbe84ed863642cfbe06cdf9b3d89ae3ad Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Fri, 13 Nov 2026 22:32:14 +0900 Subject: [PATCH 2/3] 0.10.0: page-or-more alignments are placed pages; a board may make standard error the console kal_alloc over-allocated every stricter alignment from the pool, so the 256 MiB a C library's allocator states for an arena cost 256 MiB of backed memory beyond the arena. An alignment of a page or more is now pages at an aligned address read from the memory map (AllocateAddress), the highest first; kal_free returns them as pages. OVMF's StdErr writes nothing to the serial console a runner reads, so diagnostics and abort messages were lost. A board defines okuefi_board_errors_to_console() to send standard error to ConOut; the example board does. The example checks a 256 MiB-aligned allocation. --- README.md | 18 +++++-- examples/board/board/qemu-exit.S | 8 +++ examples/hello/src/main.cpp | 8 ++- src/kal.cpp | 91 ++++++++++++++++++++++++++++++-- src/uefi.h | 17 +++++- 5 files changed, 132 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index b2a193f..88d0b39 100644 --- a/README.md +++ b/README.md @@ -41,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 | @@ -59,6 +59,13 @@ which it must leave the machine --- an emulator running it as a test --- defines 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 @@ -81,13 +88,18 @@ mapped (no `openkal.fs`), so `kal_exec_map_part` answers not supported. `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 256 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. +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-platform diff --git a/examples/board/board/qemu-exit.S b/examples/board/board/qemu-exit.S index f237ddf..f7b6581 100644 --- a/examples/board/board/qemu-exit.S +++ b/examples/board/board/qemu-exit.S @@ -28,3 +28,11 @@ okuefi_board_exit: 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 diff --git a/examples/hello/src/main.cpp b/examples/hello/src/main.cpp index ca5ccd8..56d0759 100644 --- a/examples/hello/src/main.cpp +++ b/examples/hello/src/main.cpp @@ -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; @@ -32,6 +32,12 @@ int main(int argc, char**, char**) { void* p = kal_alloc(4096, 64); check(p != nullptr && (reinterpret_cast(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): the 256 MiB a C library's + // allocator states for an arena, which over-allocating would have cost in backed memory. + void* arena = kal_alloc(32u << 20, 256u << 20); + check(arena != nullptr && (reinterpret_cast(arena) & ((256u << 20) - 1)) == 0, + "an allocation aligned to 256 MiB"); + kal_free(arena, 32u << 20, 256u << 20); const kal_duration t0 = kal_time_monotonic(); kal_time_sleep(20u * 1000u * 1000u); const kal_duration t1 = kal_time_monotonic(); diff --git a/src/kal.cpp b/src/kal.cpp index ba6554e..711c65d 100644 --- a/src/kal.cpp +++ b/src/kal.cpp @@ -86,13 +86,30 @@ extern "C" { // there before Exit is called. The definition here is the default, and does nothing. [[gnu::weak]] void okuefi_board_exit(int) {} +// THE BOARD'S ERROR CONSOLE (0.10.0). Standard error is the firmware's StdErr, the console its +// ErrOut variable names. A board on which that console reaches nothing the program's reader sees +// defines this function to return nonzero, and standard error is then ConOut: measured under OVMF +// in QEMU, StdErr wrote nothing to the serial console a runner reads, so a program's diagnostics, +// and the message of an abort, were lost. The definition here is the default, and keeps StdErr. +[[gnu::weak]] int okuefi_board_errors_to_console(void) { return 0; } + +} // extern "C" + +namespace { +efi_simple_text_output_protocol* error_console() { + if (g_st->std_err && !okuefi_board_errors_to_console()) return g_st->std_err; + return g_st->con_out; +} +} // namespace + +extern "C" { + KAL_NORETURN void kal_abort(const char* msg, kal_uintptr len) { if (g_st && msg && len) - write_to(g_st->std_err ? g_st->std_err : g_st->con_out, - reinterpret_cast(msg), len); + write_to(error_console(), reinterpret_cast(msg), len); if (g_st) { const unsigned char nl = '\n'; - write_to(g_st->std_err ? g_st->std_err : g_st->con_out, &nl, 1); + write_to(error_console(), &nl, 1); g_st->boot_services->exit(g_image, EFI_ABORTED, 0, nullptr); } for (;;) {} @@ -116,7 +133,7 @@ kal_intptr kal_stream_write(kal_stream s, const void* buf, kal_uintptr n) { if (!g_st) return -kal_err_io; efi_simple_text_output_protocol* out = s.h == kStdout ? g_st->con_out - : s.h == kStderr ? (g_st->std_err ? g_st->std_err : g_st->con_out) + : s.h == kStderr ? error_console() : nullptr; if (!out) return -kal_err_invalid; return write_to(out, static_cast(buf), n); @@ -153,6 +170,15 @@ kal_uintptr kal_stream_props(kal_stream s) { // a stricter alignment is satisfied by over-allocating and storing the original // pointer immediately before the aligned address — the same technique a C // library uses for `aligned_alloc` where the platform lacks one. +// +// AN ALIGNMENT OF A PAGE OR MORE IS PAGES (0.10.0). Over-allocating costs the +// alignment in memory that is backed, and the allocator of a C library above +// this one asks for its arenas at 256 MiB: measured under OVMF with 512 MiB, +// a 32 MiB arena became a 288 MiB request and failed. Pages are placed at an +// aligned address instead: the memory map is read for free memory that holds +// an aligned range of the size, and the pages there are allocated +// (AllocateAddress), the highest such range first, where the firmware's own +// allocations would otherwise go. Nothing beyond the size is taken. // The quantum this environment allocates and protects memory in. // // Firmware hands out memory in pages of four kilobytes --- that is the unit of @@ -168,9 +194,60 @@ int kal_memory_info(kal_memory_status* out) { return kal_ok; } +namespace { + +constexpr kal_uintptr kPage = 4096; + +kal_uintptr pages_of(kal_uintptr size) { return (size + kPage - 1) / kPage; } + +// The highest address, aligned to `align', at which `pages' free pages lie; zero where none do. +unsigned long long aligned_free_range(kal_uintptr pages, kal_uintptr align) { + auto* bs = g_st->boot_services; + efi_uintn size = 0, key = 0, step = 0; + unsigned int version = 0; + if (bs->get_memory_map(&size, nullptr, &key, &step, &version) != EFI_BUFFER_TOO_SMALL || step == 0) + return 0; + // The pool allocation below may add entries to the map it is to hold. + size += 4 * step; + void* buffer = nullptr; + if (bs->allocate_pool(EfiLoaderData, size, &buffer) != EFI_SUCCESS) return 0; + unsigned long long best = 0; + if (bs->get_memory_map(&size, static_cast(buffer), &key, &step, &version) + == EFI_SUCCESS) { + const unsigned long long want = static_cast(pages) * kPage; + for (efi_uintn at = 0; at + step <= size; at += step) { + const auto* d = reinterpret_cast( + static_cast(buffer) + at); + if (d->type != EfiConventionalMemory || d->pages * kPage < want) continue; + const unsigned long long start = d->physical_start; + const unsigned long long end = start + d->pages * kPage; + const unsigned long long top = (end - want) & ~(static_cast(align) - 1); + if (top >= start && top != 0 && top > best) best = top; + } + } + bs->free_pool(buffer); + return best; +} + +void* aligned_pages(kal_uintptr size, kal_uintptr align) { + auto* bs = g_st->boot_services; + const kal_uintptr pages = pages_of(size); + unsigned long long address = 0; + if (align <= kPage) + return bs->allocate_pages(AllocateAnyPages, EfiLoaderData, pages, &address) == EFI_SUCCESS + ? reinterpret_cast(address) : nullptr; + address = aligned_free_range(pages, align); + if (address == 0) return nullptr; + return bs->allocate_pages(AllocateAddress, EfiLoaderData, pages, &address) == EFI_SUCCESS + ? reinterpret_cast(address) : nullptr; +} + +} // namespace + void* kal_alloc(kal_uintptr size, kal_uintptr align) { if (!g_st) return nullptr; if (size == 0) size = 1; + if (align >= kPage && (align & (align - 1)) == 0) return aligned_pages(size, align); if (align <= 8) { void* p = nullptr; if (g_st->boot_services->allocate_pool(EfiLoaderData, size, &p) != EFI_SUCCESS) @@ -187,8 +264,12 @@ void* kal_alloc(kal_uintptr size, kal_uintptr align) { return reinterpret_cast(aligned); } -void kal_free(void* p, kal_uintptr, kal_uintptr align) { +void kal_free(void* p, kal_uintptr size, kal_uintptr align) { if (!p || !g_st) return; + if (align >= kPage && (align & (align - 1)) == 0) { + g_st->boot_services->free_pages(reinterpret_cast(p), pages_of(size ? size : 1)); + return; + } void* raw = align <= 8 ? p : reinterpret_cast(p)[-1]; g_st->boot_services->free_pool(raw); } diff --git a/src/uefi.h b/src/uefi.h index 8fbb19e..3d2d2c7 100644 --- a/src/uefi.h +++ b/src/uefi.h @@ -67,6 +67,19 @@ struct efi_simple_text_input_protocol { void* wait_for_key; }; +/* One entry of the memory map (EFI_MEMORY_DESCRIPTOR). Entries are `descriptor_size' bytes apart, + * which may exceed this structure; a reader steps by that size and never by sizeof. */ +struct efi_memory_descriptor { + unsigned int type; + unsigned int pad; + unsigned long long physical_start; + unsigned long long virtual_start; + unsigned long long pages; + unsigned long long attribute; +}; +inline constexpr unsigned int EfiConventionalMemory = 7; +inline constexpr efi_status EFI_BUFFER_TOO_SMALL = 0x8000000000000005ULL; + /* Only as far as `exit`, with every intervening slot named so that the offsets * are computed rather than counted by hand. */ struct efi_boot_services { @@ -76,7 +89,8 @@ struct efi_boot_services { efi_status (*allocate_pages)(int type, int memory_type, efi_uintn pages, unsigned long long* memory); /* 40 */ efi_status (*free_pages)(unsigned long long memory, efi_uintn pages); /* 48 */ - void* get_memory_map; /* 56 */ + efi_status (*get_memory_map)(efi_uintn* size, struct efi_memory_descriptor* map, efi_uintn* key, + efi_uintn* descriptor_size, unsigned int* version); /* 56 */ efi_status (*allocate_pool)(int type, efi_uintn size, void** buf); /* 64 */ efi_status (*free_pool)(void* buf); /* 72 */ void* create_event; /* 80 */ @@ -125,6 +139,7 @@ static_assert(__builtin_offsetof(efi_boot_services, stall) == 248); static_assert(__builtin_offsetof(efi_boot_services, set_watchdog_timer) == 256); static_assert(__builtin_offsetof(efi_boot_services, allocate_pages) == 40); static_assert(__builtin_offsetof(efi_boot_services, free_pages) == 48); +static_assert(__builtin_offsetof(efi_boot_services, get_memory_map) == 56); static_assert(__builtin_offsetof(efi_boot_services, locate_protocol) == 320); /* EFI_ALLOCATE_TYPE and EFI_MEMORY_TYPE: the two this implementation asks for. */ From 365925b5b8707d845e22e61592cfe8baada6fc69 Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Fri, 13 Nov 2026 22:41:33 +0900 Subject: [PATCH 3/3] example: the page-placed allocation at 16 MiB, which the 256 MiB machine of CI holds --- README.md | 2 +- examples/hello/src/main.cpp | 13 +++++++------ 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 88d0b39..3a9075a 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,7 @@ mapped (no `openkal.fs`), so `kal_exec_map_part` answers not supported. `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. 0.10.0 adds an allocation aligned to 256 MiB, +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 diff --git a/examples/hello/src/main.cpp b/examples/hello/src/main.cpp index 56d0759..0be1183 100644 --- a/examples/hello/src/main.cpp +++ b/examples/hello/src/main.cpp @@ -32,12 +32,13 @@ int main(int argc, char**, char**) { void* p = kal_alloc(4096, 64); check(p != nullptr && (reinterpret_cast(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): the 256 MiB a C library's - // allocator states for an arena, which over-allocating would have cost in backed memory. - void* arena = kal_alloc(32u << 20, 256u << 20); - check(arena != nullptr && (reinterpret_cast(arena) & ((256u << 20) - 1)) == 0, - "an allocation aligned to 256 MiB"); - kal_free(arena, 32u << 20, 256u << 20); + // 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(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();