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
165 changes: 165 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
name: CI

on:
push:
branches: [main]
pull_request:
workflow_dispatch:
inputs:
mcpp_ref:
description: "build mcpp from this branch or tag of mcpp-community/mcpp"
required: false
default: ""

env:
# THE ENGINE THAT KNOWS THE TARGET. `x86_64-freebsd' is a row of mcpp
# 2026.11.10.1. A run given `mcpp_ref' builds the engine from that branch or
# tag, with the released one as the compiler of that build.
MCPP_VERSION: 2026.11.10.1
MCPP_SOURCE_REF: ${{ github.event.inputs.mcpp_ref || '' }}
XLINGS_VERSION: v2026.10.26.1
XLINGS_NON_INTERACTIVE: '1'

jobs:
# THE CONFORMANCE SUITE ON FREEBSD. Built on Linux for `x86_64-freebsd' above
# FreeBSD's own C library (the base system's sysroot, ci/freebsd-platform),
# and run in a FreeBSD virtual machine, as the system a user runs it on. The
# three-way check of the manifest, kal_interfaces() and the exported names is
# made on both sides: the exported names when the suite is built, the other
# two by the suite when it runs.
#
# BOTH ARCHITECTURES. arm64 runs in an emulated machine (vmactions'
# `arch: aarch64', without hardware assistance), which is why its job is
# given longer.
# THE STANDALONE ARRANGEMENT is run the same way: openkal-musl over this
# implementation with the feature `standalone', built for
# `<arch>-freebsd-musl' from the working trees (tools/run-conformance-standalone.sh),
# its C++ runtime openkal-llvm-runtime, each at its branch of the same name when
# it has one.
conformance:
name: conformance (freebsd ${{ matrix.arch }}, ${{ matrix.arrangement }})
runs-on: ubuntu-24.04
timeout-minutes: ${{ matrix.minutes }}
strategy:
fail-fast: false
matrix:
include:
- { arch: x86_64, arrangement: hosted, minutes: 90 }
- { arch: aarch64, arrangement: hosted, minutes: 240 }
- { arch: x86_64, arrangement: standalone, minutes: 90 }
- { arch: aarch64, arrangement: standalone, minutes: 240 }
steps:
- uses: actions/checkout@v4

- name: The committed manifest names no local directory
run: |
set -euo pipefail
bad=$(grep -nE '^[a-z-]+ = \{[^}]*path = "(/|[A-Za-z]:)' mcpp.toml || true)
if [ -n "$bad" ]; then
echo "::error::the committed manifest names an absolute path"; printf '%s\n' "$bad"; exit 1
fi

- name: The specification
run: |
git clone --quiet https://github.com/mcpplibs/openkal.git .spec
branch='${{ github.head_ref || github.ref_name }}'
if git -C .spec rev-parse --verify --quiet "origin/$branch" > /dev/null; then
git -C .spec checkout --quiet "origin/$branch"
echo "the specification is at $branch"
else
echo "the specification has no $branch; its default branch is used"
fi

- name: Install xlings
run: |
curl -fsSL 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 mcpp
run: |
set -euo pipefail
xlings update
xlings install "mcpp@$MCPP_VERSION" -y -g
mcpp self config --mirror GLOBAL
if [ -n "${MCPP_SOURCE_REF:-}" ]; then
src="$RUNNER_TEMP/mcpp-src"
git clone --quiet --depth 1 --branch "$MCPP_SOURCE_REF" https://github.com/mcpp-community/mcpp.git "$src"
rm -f "$src/.xlings.json"
( cd "$src" && mcpp build --release )
built=$(find "$src/target" -type f -name mcpp | head -1)
[ -n "$built" ] || { echo "::error::mcpp did not build from $MCPP_SOURCE_REF"; exit 1; }
echo "$(cd "$(dirname "$built")" && pwd)" >> "$GITHUB_PATH"
echo "under review: $("$built" --version) (from $MCPP_SOURCE_REF)"
fi

- name: The suite, built for FreeBSD
env:
OPENKAL_CONFORMANCE_RUNNER: ${{ github.workspace }}/tools/defer-runner
OKF_DEFERRED: ${{ github.workspace }}/.deferred
run: |
set -euo pipefail
mcpp --version
features=full,exec,random,terminal,timeout,map,region
if [ '${{ matrix.arrangement }}' = standalone ]; then
branch='${{ github.head_ref || github.ref_name }}'
# openkal-musl and openkal-llvm-runtime (the suite's C and C++
# runtimes) at their branch of the same name, else their default
# branch.
for repo in openkal-musl openkal-llvm-runtime; do
git clone --quiet "https://github.com/mcpplibs/$repo.git" ".$repo"
if git -C ".$repo" rev-parse --verify --quiet "origin/$branch" > /dev/null; then
git -C ".$repo" checkout --quiet "origin/$branch"; echo "$repo is at $branch"
fi
done
bash tools/run-conformance-standalone.sh .spec .openkal-musl '${{ matrix.arch }}' "$features" .openkal-llvm-runtime
else
bash .spec/tools/run-conformance.sh openkal-freebsd . "$features" \
--target '${{ matrix.arch }}-freebsd' --platform "path:$GITHUB_WORKSPACE/ci/freebsd-platform"
fi
file .deferred/openkal-conformance

- name: The suite, run in FreeBSD
uses: vmactions/freebsd-vm@v1
with:
arch: ${{ matrix.arch }}
usesh: true
run: |
set -e
uname -a
./.deferred/run.sh > .deferred/run.log 2>&1 || echo "status $?" >> .deferred/run.log
cat .deferred/run.log

- name: The verdict
run: |
set -euo pipefail
log=.deferred/run.log
{ echo '### openkal-freebsd conformance on FreeBSD (${{ matrix.arch }}, ${{ matrix.arrangement }})'; echo '```'; grep -E '^observations|DID NOT HOLD|^the implementation' "$log" | sort -u; echo '```'; } >> "$GITHUB_STEP_SUMMARY"
! grep -q '^status ' "$log" || { echo "::error::the suite did not finish with status 0"; grep '^status ' "$log"; exit 1; }
grep -qE '^observations: [0-9]+ held, 0 did not hold' "$log" || { echo "::error::an observation did not hold"; exit 1; }

# THE STANDALONE ARRANGEMENT, COMPILED FOR BOTH ARCHITECTURES from this
# package's sources and openkal's headers alone (tools/check-standalone.sh):
# no system header, no C library, and the objects carry the FreeBSD brand.
standalone:
name: standalone (compiled for x86_64 and aarch64)
runs-on: ubuntu-24.04
timeout-minutes: 30
steps:
- uses: actions/checkout@v4
- name: The specification
run: git clone --quiet --depth 1 https://github.com/mcpplibs/openkal.git .spec
- name: Install xlings and mcpp
run: |
curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh \
| bash -s "$XLINGS_VERSION"
export PATH="$HOME/.xlings/subos/current/bin:$PATH"
xlings update
xlings install "mcpp@$MCPP_VERSION" -y -g
mcpp toolchain install llvm 23.1.3
- name: Every source, for both architectures
run: |
set -euo pipefail
cxx=$(find "$HOME/.mcpp" -path '*xim-x-llvm/23.1.3/bin/clang++' | head -1)
[ -n "$cxx" ] || { echo "::error::clang++ 23.1.3 was not found"; exit 1; }
bash tools/check-standalone.sh "$cxx" .spec/include
117 changes: 117 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
# openkal-freebsd

An implementation of [openkal](https://github.com/mcpplibs/openkal) for FreeBSD,
written on the kernel's own system-call interface.

```toml
[target.'cfg(os = "freebsd")'.dependencies]
openkal-freebsd = "0.1.0"
```

## What it is

FreeBSD's kernel interface is stable: a program built for FreeBSD 14 runs on
every later 14.x and, through `COMPAT_FREEBSD14`, on 15. This implementation
issues that interface directly, on amd64 and arm64, and reads no header of a C
library. `src/sys.h` states FreeBSD 14's system-call numbers, flags and
structure layouts. They were read from the base system's headers by compiling
them for both architectures, where they are identical, and each structure's
size is asserted. The kernel reports a failure with the carry flag and the
error number in the first result register; `okf::call6` folds the two into one
value, the result or the error number negated, as openkal-linux's system calls
answer.

## Two arrangements

**Hosted (the default).** The program carries a runtime that has received
control: FreeBSD's own C library and `libthr`, as in a program built for
`x86_64-freebsd` or `aarch64-freebsd`. This implementation borrows what that
runtime already does, as openkal-linux does above a C library:

- the program's arguments and environment, from the `(argc, argv, envp)` that
FreeBSD's run-time linker passes to every `.init_array` function;
- a context, which is the runtime's thread (`pthread_create`), and its stack,
which the runtime states (`pthread_attr_get_np`).

`-lthr` is named only on those rows.

**Standalone (feature `standalone`).** Nothing in the program has received
control: either it supplies its own runtime, or it is built above a C library
written on openkal (openkal-musl, the rows `x86_64-freebsd-musl` and
`aarch64-freebsd-musl`). This implementation then:

- begins the program with `_start`, which takes the argument block from `%rdi`
or `x0`, and the auxiliary vector after it;
- carries the `.note.tag` ABI brand by which the kernel recognises a FreeBSD
image;
- lays out the image's `PT_TLS` block and sets the thread pointer
(`sysarch(AMD64_SET_FSBASE)` on amd64, `tpidr_el0` on arm64);
- hands over to a linked C library's `__libc_start_main`, or else runs the
initialisers and calls `main`;
- creates contexts with `thr_new` on stacks it maps with a guard, and joins
them on the word `thr_exit` sets;
- states the first stack from `AT_USRSTACKBASE` and `AT_USRSTACKLIM`.

In both arrangements everything else is a system call:

| interface | how |
|---|---|
| `openkal.abort` | `exit`; SIGABRT at its default disposition |
| `openkal.stream` | `read`, `write`; a terminal is what answers `TIOCGETA` |
| `openkal.memory` | size classes carved from `mmap`ed chunks; `hw.physmem` and the free and inactive page counts from `sysctl` |
| `openkal.env` | the recorded vectors; `kern.proc.pathname` for the image's name |
| `openkal.time` | `clock_gettime`, `clock_getres`, `nanosleep` |
| `openkal.random` | `getrandom` |
| `openkal.fs` | the `*at` calls relative to directory descriptors; `getdirentries`; `flock` for a lock on a whole file; two preopens, the working directory (`__getcwd`) and the root |
| `openkal.process` | `pdfork` (`PD_DAEMON`; the descriptor is held while the handle is) and `fexecve`; `wait6`; process groups as units; SIGINT, SIGTERM and SIGHUP taken over with `sigaction` |
| `openkal.task` | a word waited upon and woken with `_umtx_op` (`UMTX_OP_WAIT_UINT_PRIVATE`, `UMTX_OP_WAKE_PRIVATE`) |
| `openkal.exec` | `mmap`, `mprotect`, never writable and executable at once; a region at an address is `MAP_FIXED \| MAP_EXCL` |
| `openkal.terminal` | `TIOCGETA`, `TIOCSETAF`, `TIOCGWINSZ` |
| `openkal.timeout` | `ppoll`; a program awaited with a bound |
| `openkal.map` | `mmap` of a descriptor |
| `openkal.region` | reserved `PROT_NONE` mappings backed by `mprotect` |

Absent in 0.1, neither stated nor defined: `openkal.space`, `openkal.net`,
`openkal.datagram`, `openkal.prof` and `openkal.debug`. Within the stated
interfaces, the property words do not claim the following, and the operations
answer `kal_err_not_supported` as clause 6.2 requires:

- confinement, a bound lifetime and a one-string command line for a started
program;
- the observable units of 0.24, and a unit's usage and limits;
- a rename that does not replace (FreeBSD has none);
- the timeout forms of `accept` and `recv_from`, whose resources belong to the
absent network interfaces.

The stop word is counted and never zero again (openkal 0.25). The handler wakes
the word's waiters itself, because a wake is a system call, which a handler may
make.

## How it is examined

**Hosted.** openkal's conformance suite is built on Linux for `x86_64-freebsd`
and `aarch64-freebsd` above FreeBSD's C library, using the base-system sysroots
`xim:<arch>-freebsd-sysroot@14.5` named by `ci/freebsd-platform`. It is then run
in a FreeBSD virtual machine (vmactions/freebsd-vm; the arm64 machine is
emulated). On FreeBSD 14.5 amd64 it reports 334 observations held, none
failed, and 12 not observed (interfaces not provided, properties not claimed).
The suite's three-way check holds: the manifest's `provides-interfaces`,
`kal_interfaces()` and the exported names state the same fourteen interfaces.

**Standalone.** Every source compiles for both architectures from openkal's
headers alone, `-ffreestanding` and without a system header, and the objects
carry the brand (`tools/check-standalone.sh`). The suite in this arrangement
runs above openkal-musl on the `*-freebsd-musl` rows.

- `tools/defer-runner` puts the suite and the variables it is run with in a
directory, where CI runs it inside a FreeBSD VM.
- `tools/vm-run.py` runs a program in a local FreeBSD VM image for development
(`OKF_VM_IMAGE`, `tools/vm-runner`). It forwards `OPENKAL_*`, `KAL_*` and the
mtest protocol's variables, so the suite can report through mtest once the
runner's listing pass honours `--run-under` (mtest 0.6.0).

The targets need mcpp 2026.11.10.1 or later.

## License

Apache-2.0.
29 changes: 29 additions & 0 deletions ci/freebsd-platform/mcpp.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# The FreeBSD target as this repository's CI builds it: the system's own C
# library and runtimes from the FreeBSD base sysroots (xim:<arch>-freebsd-sysroot,
# FreeBSD 14.5's base.txz), compiled by LLVM. openkal-freebsd is the kernel-abi
# layer above them; the platform names none.
[package]
name = "openkal-freebsd-ci-platform"
version = "0.1.0"

[platform]
toolchain = "llvm@23.1.3"

[[platform.provider]]
serves = ["x86_64-freebsd"]
sysroot = "xim:x86_64-freebsd-sysroot@14.5"
hosted = true

[[platform.provider]]
serves = ["aarch64-freebsd"]
sysroot = "xim:aarch64-freebsd-sysroot@14.5"
hosted = true

[platform.link]
driver = "compiler"

[platform.layers]
"kernel-abi" = false
"c-abi" = false
"c++-abi" = false
"compiler-runtime" = false
72 changes: 72 additions & 0 deletions mcpp.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
[package]
namespace = "mcpplibs"
name = "openkal-freebsd"
version = "0.1.0"
description = "An implementation of openkal for FreeBSD, written on the kernel's own system-call interface."
license = "Apache-2.0"
authors = ["mcpplibs"]
repo = "https://github.com/mcpplibs/openkal-freebsd"

provides = ["mcpp:kernel-abi=openkal"]

# WHICH INTERFACES THIS IMPLEMENTATION PROVIDES, AND NO OTHER. An interface it
# does not provide is absent: it is not in this list, not in kal_interfaces(),
# and none of its names is defined (SPEC.md clause 6.1). The conformance
# suite's three-way check compares this list with kal_interfaces() and with the
# names the artefact exports.
#
# Absent in 0.1: openkal.space, openkal.net, openkal.datagram, openkal.prof and
# openkal.debug.
[kernel-abi]
provides-interfaces = [
"openkal.abort",
"openkal.stream",
"openkal.memory",
"openkal.env",
"openkal.time",
"openkal.random",
"openkal.fs",
"openkal.process",
"openkal.task",
"openkal.exec",
"openkal.terminal",
"openkal.timeout",
"openkal.map",
"openkal.region",
]

[dependencies]
openkal = "0.25.0"

[build]
sources = ["src/*.cpp"]
# No exception propagates out of a C entry point, and nothing here is
# identified at run time. The flags are attached to this package's sources;
# the conformance tests are consumers.
flags = [
{ glob = "src/**", cxxflags = ["-fno-exceptions", "-fno-rtti"] },
]

# THE THREADS OF THE PROGRAM'S RUNTIME, which a context is in the hosted
# arrangement (src/task.cpp): FreeBSD's own C library's rows. A row whose C
# library is written above openkal (`*-freebsd-musl') has no libthr, and this
# implementation is then standalone.
[target.'cfg(all(os = "freebsd", not(env = "musl")))'.build]
ldflags = ["-lthr"]

[features]
default = []

# Whether this implementation is the whole of the program's environment.
#
# Ordinarily the program carries a runtime that has already received control
# and creates its contexts --- FreeBSD's C library and libthr --- and this
# implementation borrows both. That is the default.
#
# Where nothing in the program has received control --- the program supplies
# its own runtime, or it is a C library written above openkal (openkal-musl) ---
# this implementation does both: it begins the program (`_start', the image's
# .note.tag brand, the thread pointer through sysarch) and creates contexts with
# thr_new. That is what `standalone' selects, a statement about the program
# that the consumer which knows it makes.
standalone = { defines = ["OKF_STANDALONE"] }
Loading
Loading