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
18 changes: 15 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,9 @@ name: CI
# program of the system calls an image's library through libokrun
# and through the binding openkal-bind generates, and the binding's
# refusals hold. An image at its base, anywhere and unplaced
# observes the same memory (0.4.0).
# 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).

on:
push:
Expand Down Expand Up @@ -79,8 +81,8 @@ jobs:
bash examples/build-image.sh "$arch" "out/$arch/hello.oke" examples/hello/app.c
# The declarations are compiled from the public specification the
# tools resolved: any patch of its minor version (openkal clause 8),
# which is 0.25.1 since that patch was published.
spec=$(find "$HOME/.mcpp" -path '*openkal*0.25.*/include/openkal/process.h' -type f | sort -V | tail -1)
# 0.26 since 0.7.0.
spec=$(find "$HOME/.mcpp" -path '*openkal*0.26.*/include/openkal/process.h' -type f | sort -V | tail -1)
test -n "$spec"
CPATH="${spec%/openkal/process.h}" bash examples/build-image.sh "$arch" "out/$arch/process-unit.oke" examples/process-unit/app.c
bash examples/build-image.sh "$arch" "out/$arch/liboktwice.okso" examples/needed/lib.c
Expand All @@ -94,6 +96,8 @@ jobs:
bash examples/build-image.sh "$arch" "out/$arch/stack.oke" examples/stack/app.c
# The convention's floating-point state at the entry and in a context (0.5.3).
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
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 @@ -289,6 +293,14 @@ jobs:
run: |
python=python3; [ "$RUNNER_OS" = Windows ] && python=python
"$python" tools/tests/record_env.py --okprof "$OKPROF"
- name: A request to end names the call each task waits in (0.7.0)
run: |
# Asked to end (SIGTERM; a console's CTRL_BREAK_EVENT on Windows),
# okrun writes the openkal call each task of the image waits in, then
# ends the program as the request would have; an image that took the
# 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: The same bytes
run: |
a='${{ matrix.arch }}'
Expand Down
12 changes: 7 additions & 5 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)"
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)"
required: true
default: "0.21.0"
asset_revision:
Expand All @@ -40,16 +40,18 @@ env:
# 2026.11.10.1: openkal-run binds the interfaces its implementation provides.
# mcpp_ref supplies the candidate until this release is installable.
# 2026.11.15.1: openkal-platform 0.28.0, the default platform below, requires
# 2026.11.14.1 or later.
MCPP_VERSION: 2026.11.15.1
# 2026.11.14.1 or later. 2026.11.18.1 (0.7.0): openkal-platform 0.31.0
# requires 2026.11.17.1 or later, and its CI runs 2026.11.18.1.
MCPP_VERSION: 2026.11.18.1
# The platform whose hosted arrangement the programs are built over, named by
# the dispatch beside the tag: a tag's tools pin exact implementations, and the
# 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.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).
# 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.28.0' }}
PLATFORM_VERSION: ${{ github.event.inputs.platform || '0.31.0' }}
XLINGS_VERSION: v2026.10.26.1
XLINGS_NON_INTERACTIVE: '1'

Expand Down
42 changes: 42 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,15 @@ release carries its binaries (0.6.3 was published without them), and it adds
FreeBSD x86_64 and aarch64: static programs of the platform's hosted musl
identity, built on Linux and run in a FreeBSD machine before they are attached.

Version 0.7.0 writes, when the program is asked to end, the openkal call each
task of the image waits in, with the task's identity, and then acts on the
request as before ([When the program is asked to end](#when-the-program-is-asked-to-end)).
The package follows openkal 0.26: openkal `^0.26.0` and, as the defaults per
system, openkal-linux `^0.27.0`, openkal-macos `^0.24.0`, openkal-windows
`^0.23.0` and openkal-freebsd `^0.2.0`. The names the runner binds are generated
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.

## An image

```sh
Expand Down Expand Up @@ -299,6 +308,36 @@ identity, length and modification time. A later start of the same file admits th
shape alone; a file replaced or changed is compared again. A language server that starts a
worker per module no longer reads its 146 MB okb at each start.

## When the program is asked to end

A task of an image that never returns is waiting in a call of openkal or running its own code, and
a program ended by force leaves nothing to say which. Where the image is entered, the runner takes
the program's requests to end (`kal_process_stop_requested`: SIGTERM, SIGINT and SIGHUP on Linux,
macOS and FreeBSD; a console's control events on Windows) and waits for them on a task of its own
(0.7.0). Each task of the image has a line: its identity (`kal_task_current`) and the call that
waits it is in. The calls that wait are those that return only when another party acts or a time
passes (`run/build.mcpp`): the operations `openkal.timeout` bounds and its own forms of them,
`kal_task_wait`, `kal_task_join`, `kal_time_sleep`, `kal_stream_flush`, `kal_fs_open`,
`kal_fs_lock`, `kal_net_connect`, `kal_net_connect_at` and `kal_datagram_send_to`. A request
writes the lines to the runner's error stream, within a second where the implementation bounds a
write:

```text
okrun: asked to end; the openkal call each task of the image waits in:
okrun: task 2548376 (main): kal_task_join
okrun: task 2548380: kal_task_wait
```

and is then acted on as it was before the runner took it: the program ends as the request would
have ended it (`kal_process_end_as_requested`), so its starter observes the same end. An image that
takes the requests over itself is given a word that the runner counts once the record is written,
and acts on each request as it always did; each request writes the record. A task in none of the
calls that wait is `in no call that waits`: it runs its own code, or a call that returns by itself.
A harness that asks a program to end and waits a moment before it ends it by force so learns what
each task was waiting for. Where the implementation reports no request to end, or no task can be
started to wait for one, nothing is taken and a request ends the program as before; a
measurement's report states which (`requests`).

## 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 @@ -357,6 +396,9 @@ its header and calls it, on openkal and on every other system alike ([docs/bind.
nothing to the runner's cache; `okrun cache` lists and removes what it keeps.
- An okb states its images' chunk digests, which okrun verifies on several contexts and
`okld bundle check` beside the whole digest; a changed byte is refused by either.
- 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.
- 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.6.4"
version = "0.7.0"
# `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
84 changes: 84 additions & 0 deletions examples/ending/app.c
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
/* An image asked to end while its tasks wait (openkal-image 0.7.0). Its main
* task starts another, which waits upon a word nobody changes, and joins it;
* once the other has begun, the image says which task is which. okrun, asked to
* end, writes the call each task waits in --- the main task kal_task_join, the
* other kal_task_wait --- and ends the program as the request would have ended
* it.
*
* With the argument `takes', the image first takes the requests to end over
* (kal_process_stop_requested): the other task sleeps, the main task waits upon
* the request word, and once asked the image says so and returns 7. okrun
* writes the record --- kal_task_wait and kal_time_sleep --- and leaves the
* request to the image. tools/tests/end_request.py asks and reads both. */
typedef unsigned long kal_uintptr;
typedef long kal_intptr;
typedef unsigned int kal_u32;
typedef unsigned long long kal_u64;
struct kal_stream { kal_uintptr h; };
struct kal_task { kal_uintptr h; };

struct kal_stream kal_stdout(void);
kal_intptr kal_stream_write(struct kal_stream, const void*, kal_uintptr);
kal_uintptr kal_env_arg_count(void);
kal_intptr kal_env_arg(kal_uintptr, char*, kal_uintptr);
int kal_task_start(void (*entry)(void*), void* arg, struct kal_task* out);
int kal_task_join(struct kal_task);
kal_uintptr kal_task_current(void);
int kal_task_wait(const kal_u32* word, kal_u32 expected, kal_u64 timeout_ns);
int kal_task_wake(const kal_u32* word, kal_uintptr count, kal_uintptr* woken);
void kal_time_sleep(kal_u64 ns);
const kal_u32* kal_process_stop_requested(void);

static void put(const char* s) {
unsigned long n = 0; while (s[n]) ++n;
kal_stream_write(kal_stdout(), s, n);
}
static void put_num(kal_uintptr v) {
char b[24]; int i = 23; b[i] = 0;
do { b[--i] = (char)('0' + v % 10); v /= 10; } while (v);
put(b + i);
}

static kal_uintptr g_other;
static kal_u32 g_begun;
static kal_u32 g_never;

static void begun(void) {
g_other = kal_task_current();
__atomic_store_n(&g_begun, 1, __ATOMIC_RELEASE);
kal_task_wake(&g_begun, 1, 0);
}
static void waits(void* arg) {
(void)arg;
begun();
for (;;) kal_task_wait(&g_never, 0, 0);
}
static void sleeps(void* arg) {
(void)arg;
begun();
for (;;) kal_time_sleep(3600ull * 1000000000ull);
}

static int takes(void) {
char a[8];
if (kal_env_arg_count() < 2) return 0;
const kal_intptr n = kal_env_arg(1, a, sizeof a);
return n == 5 && a[0] == 't' && a[1] == 'a' && a[2] == 'k' && a[3] == 'e' && a[4] == 's';
}

__attribute__((visibility("default"))) int ok_main(void) {
const int taken = takes();
const kal_u32* stop = 0;
if (taken && !(stop = kal_process_stop_requested())) { put("ending: no request reaches this program\n"); return 3; }
struct kal_task other;
if (kal_task_start(taken ? sleeps : waits, 0, &other) != 0) { put("ending: no task\n"); return 3; }
while (__atomic_load_n(&g_begun, __ATOMIC_ACQUIRE) == 0) kal_task_wait(&g_begun, 0, 0);
put("ending: main "); put_num(kal_task_current()); put(", other "); put_num(g_other); put("\n");
if (!taken) {
kal_task_join(other);
return 0;
}
while (__atomic_load_n(stop, __ATOMIC_ACQUIRE) == 0) kal_task_wait(stop, 0, 0);
put("ending: asked to end, and the image ends by itself\n");
return 7;
}
2 changes: 1 addition & 1 deletion ld/mcpp.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
namespace = "mcpplibs"
name = "openkal-ld"
version = "0.6.4"
version = "0.7.0"
description = "libokld: the ok format (openkal image format) --- its definition, a reader of bytes, a checker, a signer, and a loader. Freestanding: no C library, no exceptions."
license = "Apache-2.0"
authors = ["mcpplibs"]
Expand Down
50 changes: 43 additions & 7 deletions run/build.mcpp
Original file line number Diff line number Diff line change
Expand Up @@ -39,10 +39,30 @@ int main() {
// box; every other name is the implementation's. Since 0.2 the runner
// also answers openkal.prof and openkal.debug, which are a loader's (SPEC
// 12.3), the word of interfaces (the implementation's and those two), and
// the program's end (where a measurement records what it measured).
// the program's end (where a measurement records what it measured). Since
// 0.7 the runner also answers the requests to end, which it took before the
// image could: an image that asks for them takes them over.
std::set<std::string> own{ "kal_env_arg_count", "kal_env_arg", "kal_env_image", "kal_env_loader",
"kal_interfaces", "kal_exit", "kal_abort" };
"kal_interfaces", "kal_exit", "kal_abort", "kal_process_stop_requested" };
const std::set<std::string> callbacks{ "kal_task_start", "kal_task_start_sized" };
// THE CALLS THAT WAIT (0.7): each returns only when another party acts ---
// a task, a program, a peer --- or a time passes, so a task that does not end
// is found in one of them. openkal.timeout names the operations that would
// otherwise wait without end, and its own forms of them wait up to a bound;
// the others wait by what they are (a context joined or a word waited upon,
// a lock another holds, a named pipe opened before its other end). Each is
// entered through a record of the call on the calling task's line, which a
// request to end writes (src/waits.cpp). An operation upon a file waits for
// a device, as every operation does, and is not among them.
const std::set<std::string> waits{
"kal_stream_read", "kal_stream_write", "kal_stream_flush", "kal_time_sleep",
"kal_fs_open", "kal_fs_lock", "kal_process_wait", "kal_task_join", "kal_task_wait",
"kal_net_accept", "kal_net_connect", "kal_net_connect_at",
"kal_datagram_recv_from", "kal_datagram_send_to",
"kal_timeout_read", "kal_timeout_write", "kal_timeout_accept", "kal_timeout_recv_from",
"kal_timeout_wait_process" };
// The interfaces a loader answers itself, whatever the implementation provides (SPEC 12.3).
const std::set<std::string> loaders{ "openkal.prof", "openkal.debug" };
std::vector<std::string> main_names, space_names, groups;
std::map<std::string, std::string> group_of;
std::string group, line;
Expand All @@ -58,6 +78,18 @@ int main() {
group_of[line] = group;
(group == "openkal.space" ? space_names : main_names).push_back(line);
}
// A name this runner treats as its own, as a callback or as a call that waits
// is one the specification has: a name it dropped or renamed would be bound
// as any other, without the treatment, and nothing would say so.
auto known = [&](const std::set<std::string>& names) {
for (const auto& n : names) {
if (group_of.contains(n)) continue;
std::printf("mcpp:warning=%s is not a name of %s\n", n.c_str(), surface.string().c_str());
return false;
}
return true;
};
if (!known(own) || !known(callbacks) || !known(waits)) return 1;

// The interfaces the implementation provides; none stated is every one.
std::set<std::string> provided;
Expand All @@ -82,11 +114,15 @@ int main() {
// of the calls an image makes (okprof, 0.2) keeps its counts.
for (std::size_t i = 0; i < names.size(); ++i) {
const auto& n = names[i];
// A callback of an interface the implementation does not provide is absent, as
// its other names are (0.6.3: a context cannot be started where there are none).
o << (own.contains(n) ? "OKRUN_OWN(" :
!provided.contains(group_of[n]) ? "OKRUN_ABSENT(" :
callbacks.contains(n) ? "OKRUN_CALLBACK(" : "OKRUN_BIND(")
// A name of an interface the implementation does not provide is absent, a
// callback's (0.6.3: a context cannot be started where there are none) and a
// name the runner answers (0.7: no request to end where there are no programs)
// as well, except the loader's own interfaces, which it answers everywhere.
const std::string& g = group_of[n];
o << (!provided.contains(g) && !loaders.contains(g) ? "OKRUN_ABSENT(" :
own.contains(n) ? "OKRUN_OWN(" :
callbacks.contains(n) ? "OKRUN_CALLBACK(" :
waits.contains(n) ? "OKRUN_WAIT(" : "OKRUN_BIND(")
<< n << ", " << i << ")\n";
}
};
Expand Down
14 changes: 7 additions & 7 deletions run/mcpp.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
namespace = "mcpplibs"
name = "openkal-run"
version = "0.6.4"
version = "0.7.0"
description = "libokrun: the runner's core --- an ok image's names bound to this process's one openkal implementation, in the image's calling convention, and its entry entered."
license = "Apache-2.0"
authors = ["mcpplibs"]
Expand All @@ -19,14 +19,14 @@ requires = ["mcpp:kernel-abi=openkal"]
kind = "lib"

[dependencies]
openkal = "^0.25.0"
openkal = "^0.26.0"
openkal-ld = { path = "../ld" }

[defaults."mcpp:kernel-abi=openkal"]
linux = "openkal-linux@^0.26.0"
macos = "openkal-macos@^0.23.0"
windows = "openkal-windows@^0.21.0"
'cfg(os = "freebsd")' = "openkal-freebsd@^0.1.0"
linux = "openkal-linux@^0.27.0"
macos = "openkal-macos@^0.24.0"
windows = "openkal-windows@^0.23.0"
'cfg(os = "freebsd")' = "openkal-freebsd@^0.2.0"

# THE INTERFACES THE RUNNER ITSELF CALLS (0.6; 0.6.3 the core runner): an implementation that does
# not provide one of them is refused when the graph is resolved. Every other interface is bound
Expand All @@ -39,7 +39,7 @@ requires-interfaces = [
]

[build]
sources = ["src/okrun.cppm", "src/bindings.cpp", "src/adapters.cpp"]
sources = ["src/okrun.cppm", "src/bindings.cpp", "src/adapters.cpp", "src/waits.cpp"]
include_dirs = ["include"]
flags = [
{ glob = "src/*.cpp", cxxflags = ["-fno-exceptions", "-fno-rtti"] },
Expand Down
Loading
Loading