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
50 changes: 49 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,9 @@ name: CI
# refusals hold. An image at its base, anywhere and unplaced
# observes the same memory (0.4.0). Asked to end, okrun names the
# openkal call each task of an image waits in, then ends the
# program as the request would have (0.7.0).
# program as the request would have (0.7.0). Under a debugger
# continued to the end, the program ends as the image ends it
# (0.7.1).

on:
push:
Expand Down Expand Up @@ -98,6 +100,12 @@ jobs:
bash examples/build-image.sh "$arch" "out/$arch/fpstate.oke" examples/fpstate/app.c
# Tasks that wait when the program is asked to end (0.7.0).
bash examples/build-image.sh "$arch" "out/$arch/ending.oke" examples/ending/app.c
# An image that ends the program itself, through kal_exit (0.7.1).
bash examples/build-image.sh "$arch" "out/$arch/exits.oke" examples/exits/app.c
# An image that starts images, itself and exits.oke, each entered by
# the runner's loader, and a program of the system as given (0.7.1).
CPATH="${spec%/openkal/process.h}" bash examples/build-image.sh "$arch" "out/$arch/starts.oke" examples/starts/app.c
cp "out/$arch/starts.oke" "out/$arch/signed-starts.oke"
cp "out/$arch/hello.oke" "out/$arch/signed.oke"
# The library examples/bind binds for a program of each system.
bash examples/build-image.sh "$arch" "out/$arch/libmathlib.okso" examples/bind/mathlib/image/mathlib.c
Expand Down Expand Up @@ -147,6 +155,7 @@ jobs:
"$OKLD" keygen "$RUNNER_TEMP/seed" > out/key.hex
for arch in x86_64 aarch64; do
"$OKLD" sign "out/$arch/signed.oke" "$RUNNER_TEMP/seed"
"$OKLD" sign "out/$arch/signed-starts.oke" "$RUNNER_TEMP/seed"
"$OKLD" inspect "out/$arch/signed.oke"
# The signature is over the stored segments too: placed, then signed.
if "$OKLD" place "out/$arch/signed.oke" 2> signed-place.txt; then echo "::error::a signed image was placed"; exit 1; fi
Expand Down Expand Up @@ -301,6 +310,41 @@ jobs:
# requests over is named the same and ends by itself.
python=python3; [ "$RUNNER_OS" = Windows ] && python=python
"$python" tools/tests/end_request.py --okrun "$OKRUN" --image "out/${{ matrix.arch }}/ending.oke"
- name: Under a debugger, a program ends as its image ends it (0.7.1)
if: runner.os == 'Linux'
run: |
# GDB stopped before the end while the runner's task waits and then
# continued: the runner's task returns before the program ends, so
# each run ends normally, the image's main returning or calling kal_exit.
# The debugger is the index's static build (xim:gdb), the same on every
# Linux runner, not the distribution's the runner may or may not carry.
xlings install xim:gdb@18.1 -y -g
gdb --version | head -1
python3 tools/tests/debugger_end.py --okrun "$OKRUN" --images "out/${{ matrix.arch }}"
- name: An image starts images, each entered by the runner (0.7.1)
run: |
# An image file an image starts is entered through the loader the
# runner names, with the runner's signature requirements, and observes
# the vector its starter gave; a program of the system is started as
# given (openkal-image#42). Under 0.7.0 the image's start of itself
# ended by SIGSEGV on Linux.
# The program of the system is named in the system's spelling: the
# vector reaches it as given, and cmd.exe given its own name as
# `C:/Windows/System32/cmd.exe' answered `The syntax of the command
# is incorrect.' (run 44538697059). The image's lines are printed
# before they are judged.
a='${{ matrix.arch }}'
if [ "$RUNNER_OS" = Windows ]; then native=('C:\Windows\System32\cmd.exe' /c "exit 5"); else native=(/bin/sh -c "exit 5"); fi
out=$({ MSYS_NO_PATHCONV=1 "$OKRUN" "out/$a/starts.oke" "${native[@]}" || true; } | tr -d '\r')
echo "$out"
grep -qx "starts: ok" <<<"$out" || { echo "::error::an image's start of an image, or of a program of the system"; exit 1; }
# Signed, under a signature requirement: itself starts, and the
# unsigned exits.oke is refused by its reason, kal_err_permission (6).
out=$({ "$OKRUN" --require-signature --trust "$(cat out/key.hex)" "out/$a/signed-starts.oke" || true; } | tr -d '\r')
echo "$out"
grep -qx "starts: itself 7" <<<"$out" && grep -qx "starts: exits.oke -1006" <<<"$out" \
|| { echo "::error::the runner's signature requirements reach the image it starts"; exit 1; }
echo " ok an image starts images through the runner, and a program of the system as given"
- name: The same bytes
run: |
a='${{ matrix.arch }}'
Expand Down Expand Up @@ -525,6 +569,10 @@ jobs:
grep -q "library: twice(21) = 42, next_value() = 41, 42" lib.txt || { echo "::error::okrun_open_library"; exit 1; }
"$host" okb out/needed.okb | tr -d '\r' | grep -q "twice(21) = 42" || { echo "::error::okrun_run_okb_bytes"; exit 1; }
"$host" images "out/$a/needed.oke" "out/$a/liboktwice.okso" | tr -d '\r' | grep -q "twice(21) = 42" || { echo "::error::okrun_run_images"; exit 1; }
# A program that names no loader: the image's start of an image file is
# refused as kal_err_not_program, and nothing is started (0.7.1).
"$host" file "out/$a/starts.oke" refused | tr -d '\r' | grep -q "refused as not a program" \
|| { echo "::error::an image's start of an image file where no loader is named"; exit 1; }
# The archive a program that carries its images holds: no okb.json,
# the images at the root, zipalign's field and bytes between members.
python3 examples/package/stage.py staged out
Expand Down
7 changes: 4 additions & 3 deletions .github/workflows/release-binaries.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ on:
description: "The release tag the binaries are built from and attached to (e.g. 0.1.3)"
required: true
platform:
description: "The openkal-platform whose hosted arrangement builds the tools: the one whose version group holds the implementations the tag pins (0.1.5: 0.19.0; 0.1.6: 0.19.1; 0.1.7: 0.19.2; 0.1.8: 0.20.0; 0.1.9: 0.20.1; 0.3.0: 0.21.0; 0.3.1: 0.21.1; 0.4.2: 0.23.1; 0.4.3 and 0.4.4: 0.23.3; 0.7.0: 0.31.0)"
description: "The openkal-platform whose hosted arrangement builds the tools: the one whose version group holds the implementations the tag pins (0.1.5: 0.19.0; 0.1.6: 0.19.1; 0.1.7: 0.19.2; 0.1.8: 0.20.0; 0.1.9: 0.20.1; 0.3.0: 0.21.0; 0.3.1: 0.21.1; 0.4.2: 0.23.1; 0.4.3 and 0.4.4: 0.23.3; 0.7.0: 0.31.0; 0.7.1: 0.31.1)"
required: true
default: "0.21.0"
asset_revision:
Expand Down Expand Up @@ -48,10 +48,11 @@ env:
# platform is the one whose version group holds them (0.1.4: 0.18.0; 0.1.5:
# 0.19.0, openkal-linux 0.19.0; 0.1.6: 0.19.1; 0.1.7: 0.19.2; 0.1.8: 0.20.0; 0.1.9: 0.20.1;
# 0.3.0: 0.21.0; 0.3.1: 0.21.1; 0.4.2: 0.23.1; 0.4.3 and 0.4.4: 0.23.3;
# 0.7.0, the openkal 0.26 family: 0.31.0).
# 0.7.0, the openkal 0.26 family: 0.31.0; 0.7.1: 0.31.1, whose group holds
# openkal-macos 0.24.1 and this release).
# A published release builds over the platform named here, which a release
# that changes the pinned implementations updates in the same commit.
PLATFORM_VERSION: ${{ github.event.inputs.platform || '0.31.0' }}
PLATFORM_VERSION: ${{ github.event.inputs.platform || '0.31.1' }}
XLINGS_VERSION: v2026.10.26.1
XLINGS_NON_INTERACTIVE: '1'

Expand Down
60 changes: 59 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ architecture that has a runner.
|---|---|---|
| `openkal-ld` | `libokld` | The format's definition. A reader of bytes, a checker, a signer (Ed25519) and a loader. Freestanding: no C library, no exceptions. Its users are libokrun, `okld`, and a C library's `dlopen`. |
| `openkal-run` | `libokrun` | The runner's core. It binds an image's names to this process's one openkal implementation, in the image's calling convention, then enters the image. |
| `openkal-tools` | `okrun`, `okld`, `okprof` | `okrun [--require-signature] [--trust <key>] [--debugger] [--prof=<what>[:dir]] image\|okb args...` runs an image or an okb. `okld check \| note \| place \| touch \| debug-split \| sign \| keygen \| inspect \| note-source \| bundle \| bundle check` works on images and okbs on a build machine. `okprof record \| report \| diff` measures what an image did across openkal. The debugger scripts are in `tools/scripts`. |
| `openkal-tools` | `okrun`, `okld`, `okprof` | `okrun [--require-signature] [--trust <key>] [--debugger] [--prof=<what>[:dir]] [--argv0=<name>] image\|okb args...` runs an image or an okb. `okld check \| note \| place \| touch \| debug-split \| sign \| keygen \| inspect \| note-source \| bundle \| bundle check` works on images and okbs on a build machine. `okprof record \| report \| diff` measures what an image did across openkal. The debugger scripts are in `tools/scripts`. |
| `openkal-bind` | `mcpp.mcpplibs.openkal_bind` | A build plugin. A library published as an image (`.okso`) and a C header is called from a program of Linux, macOS or Windows through a binding generated from the header ([docs/bind.md](docs/bind.md)). |

`libokld` is the loader at run time and `okld` is the tool on the build machine. They share a
Expand Down Expand Up @@ -140,6 +140,24 @@ system, openkal-linux `^0.27.0`, openkal-macos `^0.24.0`, openkal-windows
from the specification's SURFACE.txt, as before. A release's programs are built
over openkal-platform 0.31.0, whose version group holds this family.

Version 0.7.1 enters an image file an image starts through the loader the
runner names, rather than handing it to the system, and states the image's name
absolute ([An image that starts a program](#an-image-that-starts-a-program)).
It takes the requests to end once the image is loaded, and the
runner's task that waits for them returns before the runner ends the program:
where the image's main returns and where the image calls `kal_exit`. The
program ends as the image ends it, with the image's tasks alone. Under GDB 15,
continued from a stop in a one-task image to its end, 0.7.0 stopped with
"Couldn't get registers: No such process" in 10 of 12 runs instead of the
program's end: GDB resumes each task in turn, and the program had ended before
it resumed the runner's. A start that is refused returns with the program's
requests as they were, which a program of the system that runs images through
libokrun keeps. A release's programs are built over openkal-platform 0.31.1,
whose group holds this release and openkal-macos 0.24.1: on macOS the runner's
task acts on a request, and 0.24.1 waits for the request's delivery before the
status a shell gives such an end (0.24.0 ended first, with 143, in one run of
two of `tools/tests/end_request.py`).

## An image

```sh
Expand Down Expand Up @@ -338,6 +356,42 @@ each task was waiting for. Where the implementation reports no request to end, o
started to wait for one, nothing is taken and a request ends the program as before; a
measurement's report states which (`requests`).

The requests are taken once the image is loaded: a start that is refused returns with them as
they were. Where the image's main returns, and where the image calls `kal_exit`, the runner asks
its task to return and joins it before it ends the program (0.7.1), so the program ends with the
image's tasks alone and with the image's status; a request that comes after that is not acted on.
A debugger that resumes each task in turn sees the program end as the image ended it.

## An image that starts a program

An image starts a program as any program of openkal does: `kal_process_spawn`, and the C library's
`posix_spawn`, `execve` and `system` above it. The system runs the bytes of a file it starts as a
program of its own, and an image is not one: under 0.7.0 an image file that an image started ended
by SIGSEGV on Linux, and on the other systems was no program at all (#42). From 0.7.1 the runner
answers the start (`run/build.mcpp`). A file that is an image (it carries the OPENKAL requirements
note, SPEC 12.4) or an okb (an archive with `okb.json`) is started through the loader the runner
names (`okrun_options::loader`; `okrun` names itself) as

```text
okrun [--require-signature] [--trust <key>]... --argv0=<argv[0]> -- <image> <argv[1]>...
```

The started image observes the vector its starter gave (openkal clause 7.6), and is held to the
runner's signature requirements. The runner asks of the file what the loader will ask before it
starts anything, so that a start that cannot happen is refused by its reason rather than seen as the
loader's status: `kal_err_not_program` for an image of another architecture, of a later format, or
requiring interfaces this system's openkal does not provide, and `kal_err_permission` for one a
signature requirement refuses. The handle is the loader's, and its status is the image's. Any
other file is started as given, once its first bytes and, for an ELF file, its notes are read. A
program that names no loader, one that carries its image among them, refuses the start of an
image file as `kal_err_not_program`; such a program starts itself by its own name, which is a
program of the system.

The image's name (`kal_env_image`) is absolute from 0.7.1, as a program's of the system is: the name
the implementation resolves the image's file to. An image that starts itself by that name starts the
same program again, wherever it then works. `/proc/self/exe` and the system's other names for the
running program name the runner, as they name any loader.

## A debugger

An image's instructions and read-only data are its file's pages, so a debugger finds the image
Expand Down Expand Up @@ -399,6 +453,10 @@ its header and calls it, on openkal and on every other system alike ([docs/bind.
- Asked to end, okrun names the openkal call each task of an image waits in, with the task's
identity, and the program ends as the request would have ended it; an image that took the
requests over is named the same and ends by itself, with its own status.
- An image starts itself and another image through the runner, each observing the vector its
starter gave, and a program of the system as given, on all four machines; under a signature
requirement the unsigned image it starts is refused as `kal_err_permission`, and a program that
names no loader refuses the start of an image file as `kal_err_not_program`.
- libokld's SHA-256, CRC-32, ZIP reader and writer (with ZIP64) and manifest reader hold
against their vectors and refusals.

Expand Down
2 changes: 1 addition & 1 deletion bind/mcpp.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
namespace = "mcpplibs"
name = "openkal-bind"
version = "0.7.0"
version = "0.7.1"
# `mcpp::xpkg_request', `mcpp::decision' (protocol 15).
mcpp = ">=2026.10.1.3"
description = "A build plugin: a library published as an ok image (.okso) and a C header is called from a program of any system, through a binding generated from the header and libokrun."
Expand Down
11 changes: 11 additions & 0 deletions examples/exits/app.c
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
/* An image that ends the program itself (0.7.1): its main calls kal_exit,
* which passes through the runner (`own_kal_exit'), rather than returning to
* it. The runner's task that waits for the requests to end returns before the
* program ends, as where an image's main returns (tools/tests/debugger_end.py).
*/
void kal_exit(int status);

__attribute__((visibility("default"))) int ok_main(void) {
kal_exit(0);
return 1;
}
10 changes: 9 additions & 1 deletion examples/host/src/main.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@
// program that carries its images holds one
// okrun-host images <needed.oke> <liboktwice.okso>
// a group of images run from memory
// okrun-host file <image> [arguments...] an image run from its file by a program that
// names no loader (0.7.1: the image's start of an
// image file is refused, examples/starts)
#include <okrun.h>
#include <cstdio>
#include <cstring>
Expand Down Expand Up @@ -35,7 +38,7 @@ std::vector<unsigned char> read(const char* path) {
} // namespace

int main(int argc, char** argv) {
if (argc < 3) { std::fprintf(stderr, "usage: okrun-host library <okso> | okb <file.okb> | archive <file.zip> <entry> | images <oke> <okso>\n"); return 2; }
if (argc < 3) { std::fprintf(stderr, "usage: okrun-host library <okso> | okb <file.okb> | archive <file.zip> <entry> | images <oke> <okso> | file <image>\n"); return 2; }
okrun_options options{};
char why[512];
if (std::strcmp(argv[1], "library") == 0) {
Expand Down Expand Up @@ -76,6 +79,11 @@ int main(int argc, char** argv) {
std::fprintf(stderr, "okrun-host: %s\n", why);
return 127;
}
if (std::strcmp(argv[1], "file") == 0) {
okrun_run_file(argv[2], argc - 2, const_cast<const char* const*>(argv + 2), &options, why, sizeof why);
std::fprintf(stderr, "okrun-host: %s\n", why);
return 127;
}
std::fprintf(stderr, "okrun-host: unknown mode %s\n", argv[1]);
return 2;
}
Loading
Loading