0.9.0 — the word this kernel could not set without a trampoline of its own

`kal_process_stop_requested` answered null here while two other implementations
answered a word. The reason was never the specification: the raw `sigaction` of
this kernel takes a structure whose SECOND field is `sa_tramp`, the kernel
enters THAT address rather than the handler, and the C library that ordinarily
supplies it (`_sigtramp`) is not beneath this implementation.

⚠️ A wrong trampoline is not a wrong answer — it is a program that dies inside
the handler at an address belonging to nobody. So the order was: **the check
that raises the signal first, the trampoline second.** The check installs the
disposition, has a shell raise SIGTERM at this program, waits on the word
through `kal_task_wait`, and then asserts the program is STILL RUNNING — which
reaching the line proves and a compiled disposition cannot show.

⭐ arm64 only, and that is the whole of it rather than half: the CI matrix is
`macos-14` alone because the build tool has no x86_64 release for this system,
so a trampoline there could be compiled and never entered. Clause 6.2 makes the
absence a fact a caller reads, and `kal_process_props` claims the position only
where it has been run.

⚠️ The test is this ecosystem's first consumer of `openkal.macros`, and writing
it is how the module's own gap was found — see openkal.

Author: Sunrisepeak

mcpp.toml

@@ -1,7 +1,7 @@
 [package]
 namespace   = "mcpplibs"
 name        = "openkal-macos"
-version     = "0.8.0"
+version     = "0.9.0"
 description = "An implementation of openkal for macOS, written on the kernel's own calls. Its purpose is as much to test the specification as to be used."
 license     = "Apache-2.0"
 
@@ -18,7 +18,7 @@ authors     = ["mcpplibs"]
 repo        = "https://github.com/mcpplibs/openkal-macos"
 
 [dependencies]
-openkal = "0.11.0"
+openkal = "0.12.0"
 
 [build]
 # The flags are attached to this package's own sources rather than to the whole

src/process.cpp

@@ -270,7 +270,106 @@ int kal_process_terminate(kal_process h) {
 // ⇒ Null, and KAL_PROCESS_PROP_STOP_REQUESTED unclaimed, so a caller that asks
 // first is told. The other implementation answers it; this one will when it can
 // be exercised here.
-const kal_u32* kal_process_stop_requested(void) { return 0; }
+// ⭐⭐ A WORD THIS PROGRAM'S ENVIRONMENT SETS WHEN SOMEBODY HAS ASKED IT TO END.
+//
+// ⚠️⚠️ THE TRAMPOLINE IS THIS IMPLEMENTATION'S OWN, WHICH IS WHY THIS ARRIVED A
+// VERSION LATE. The raw `sigaction' of this kernel takes a structure whose
+// SECOND field is `sa_tramp': the kernel enters that address, not the handler,
+// and the handler is passed to it as an argument. A C library ordinarily
+// supplies it (`_sigtramp' in libsystem) and there is no C library beneath this
+// implementation. A structure installed with a null or wrong `sa_tramp' does not
+// fail at installation --- it fails on DELIVERY, inside the handler, at an
+// address that belongs to nobody, which is the least attributable failure this
+// implementation could ship. So the order was: a conformance check that raises
+// the signal first, this second.
+//
+// ⚠️ ARMED ON THE FIRST ENQUIRY AND NOT AT STARTUP, exactly as openkal-linux
+// argues: a program that never asks keeps the default action, and adding this
+// operation therefore changes nothing for anyone who does not use it.
+namespace {
+
+kal_u32 g_stop_word = 0;
+int     g_stop_armed = 0;
+
+#if defined(__aarch64__)
+
+constexpr okm_long nr_sigaction = 46;
+
+// What the kernel enters. Its arguments are (handler, infostyle, sig, siginfo,
+// ucontext) in x0..x4; it calls the handler with the last three and then asks
+// the kernel to restore the interrupted context.
+//
+// ⚠️ x19 AND x20 ARE USED WITHOUT BEING SAVED, and that is correct here rather
+// than sloppy: this function does not return to its caller. `sigreturn' restores
+// the whole of the interrupted context, callee-saved registers included, so the
+// values these two held belong to a frame the kernel is about to reinstate.
+extern "C" void okm_sigtramp(void);
+asm(".globl _okm_sigtramp\n"
+    ".p2align 2\n"
+    "_okm_sigtramp:\n"
+    "  mov x19, x1\n"          // infostyle
+    "  mov x20, x4\n"          // ucontext
+    "  mov x8,  x0\n"          // handler
+    "  mov x0,  x2\n"          // sig
+    "  mov x1,  x3\n"          // siginfo
+    "  mov x2,  x20\n"         // ucontext
+    "  blr x8\n"
+    "  mov x0,  x20\n"         // ucontext
+    "  mov x1,  x19\n"         // infostyle
+    "  mov x16, #184\n"        // SYS_sigreturn
+    "  svc #0x80\n"
+    "  brk #1\n");             // sigreturn does not come back
+
+void stop_handler(int) {
+    __atomic_store_n(&g_stop_word, 1u, __ATOMIC_RELEASE);
+    // Woken through the same operation `kal_task_wake' performs, issued as the
+    // raw call because a handler may not enter code that takes a lock. Waking
+    // ALL of them: any number of contexts may be waiting upon this one word, and
+    // the handler has no way to learn how many.
+    okm::sys(okm::nr_ulock_wake,
+             okm::ul_compare_and_wait | okm::ulf_no_errno | okm::ulf_wake_all,
+             reinterpret_cast<okm_long>(&g_stop_word), 0);
+}
+
+// The structure this kernel's `sigaction' takes. `sa_tramp' is the second field
+// and is the whole reason this is spelled out rather than borrowed.
+struct macos_sigaction {
+    void (*handler)(int);
+    void (*tramp)(void*, int, int, void*, void*);
+    unsigned int mask;
+    int flags;
+};
+
+void arm_one(int signo) {
+    macos_sigaction act{};
+    act.handler = &stop_handler;
+    act.tramp   = reinterpret_cast<void (*)(void*, int, int, void*, void*)>(&okm_sigtramp);
+    okm::sys(nr_sigaction, signo, reinterpret_cast<okm_long>(&act), 0);
+}
+
+#endif  // __aarch64__
+
+}  // namespace
+
+const kal_u32* kal_process_stop_requested(void) {
+#if defined(__aarch64__)
+    if (!__atomic_exchange_n(&g_stop_armed, 1, __ATOMIC_ACQ_REL)) {
+        arm_one(15);   // SIGTERM
+        arm_one(2);    // SIGINT
+    }
+    return &g_stop_word;
+#else
+    // ⚠️ DECLINED ON THE OTHER ARCHITECTURE, AND NOT BECAUSE IT CANNOT BE
+    // WRITTEN. The trampoline above has an x86_64 counterpart of the same
+    // length. What it does not have is a way to be RUN: the build tool has no
+    // release for x86_64 on this system, so continuous integration compiles the
+    // sources there and executes nothing --- and a trampoline that has never
+    // been entered is the one thing this operation must not ship. Clause 6.2
+    // makes the absence a fact a caller reads, and `kal_process_props' below
+    // does not claim the position.
+    return 0;
+#endif
+}
 
 // This program itself joins or forms a unit --- what `kal_spawn.job' cannot say,
 // because that places a program the caller STARTS and a copy wishing to lead a
@@ -309,10 +408,19 @@ void kal_process_close(kal_process) { }
 // Starting a program whose lifetime is bound to this one's. Version 0.10.
 //
 
+// ⚠️ EVERY POSITION THE SPECIFICATION HAS ASSIGNED IS ACCOUNTED FOR HERE, either
+// by being claimed or by being deliberately absent. BOUND_LIFETIME is absent
+// because `kal_process_spawn' above refuses every flag; STOP_REQUESTED is
+// claimed only where the trampoline it needs has been entered by a running
+// program, which is the architecture continuous integration executes.
 kal_uintptr kal_process_props(void) { return
     KAL_PROCESS_PROP_TERMINATE | KAL_PROCESS_PROP_STREAM_PASSING
   | KAL_PROCESS_PROP_EXIT_STATUS
   | KAL_PROCESS_PROP_CHANNEL | KAL_PROCESS_PROP_GRANT_DIR
-  | KAL_PROCESS_PROP_JOB; }
+  | KAL_PROCESS_PROP_JOB
+#if defined(__aarch64__)
+  | KAL_PROCESS_PROP_STOP_REQUESTED
+#endif
+  ; }
 
 }

tests/conformance_process_task.cpp

@@ -1,5 +1,6 @@
 // Conformance: openkal.process and openkal.task.
 import openkal.process;
+import openkal.macros;
 import openkal.task;
 import openkal.fs;
 import openkal.stream;
@@ -221,6 +222,98 @@ int main() {
     kal_task_yield();
     check(kal_task_current() != 0, "the calling context has an identity");
 
+    // --- being told that an end has been requested ---------------------------
+    //
+    // ⚠️⚠️ THIS RAISES THE SIGNAL. Compiling a disposition and never delivering
+    // one proves nothing here: what this operation needs on this kernel is a
+    // TRAMPOLINE, `sa_tramp' in the structure the raw `sigaction' takes, and a
+    // wrong one is not a wrong answer --- it is a program that dies inside the
+    // handler, at an address nobody can attribute. openkal-macos declined to
+    // claim KAL_PROCESS_PROP_STOP_REQUESTED until this check existed, and this
+    // comment is why the order was that way round.
+    //
+    // ⭐ The signal is raised by a shell, which is how a program reaches its own
+    // kernel here without leaving openkal's vocabulary: `kal_process_job_enter'
+    // with a zero unit reports the identifier this program runs under, and that
+    // is the identifier the shell needs.
+    {
+        const kal_u32* word = kal_process_stop_requested();
+        if (word == nullptr) {
+            // Declined, which clause 6.2 permits and KAL_PROCESS_PROP_STOP_REQUESTED
+            // states. Nothing below applies.
+            check((kal_process_props() & kal::macros::KAL_PROCESS_PROP_STOP_REQUESTED_M) == 0,
+                  "an implementation that answers no word does not claim the position");
+        } else {
+            check((kal_process_props() & kal::macros::KAL_PROCESS_PROP_STOP_REQUESTED_M) != 0,
+                  "an implementation that answers a word claims the position");
+            check(*word == 0, "and nothing has asked this program to end yet");
+
+            kal_job unit{};
+            const int entered = kal_process_job_enter(&unit);
+            check(entered == kal_ok, "this program's identifier is reported");
+
+            if (entered == kal_ok && unit.h != 0) {
+                // "kill -TERM <pid>" with the number written out. The shell is
+                // given a moment first so that the wait below is entered rather
+                // than raced past --- the check does not depend on it, because a
+                // word already set makes the wait return at once.
+                char script[64];
+                kal_uintptr n = 0;
+                const char lead[] = "sleep 0.3; kill -TERM ";
+                for (kal_uintptr i = 0; i < sizeof(lead) - 1; ++i) script[n++] = lead[i];
+                char digits[24]; int d = 24;
+                kal_uintptr v = unit.h;
+                if (v == 0) digits[--d] = '0';
+                while (v > 0) { digits[--d] = static_cast<char>('0' + v % 10); v /= 10; }
+                while (d < 24) script[n++] = digits[d++];
+                script[n] = 0;
+
+                // Located by asking, as above --- the lambda that does it is
+                // scoped to the block above, and duplicating four lines is
+                // better than widening something for one caller.
+                const char* sh_paths[] = { "bin/sh", "usr/bin/sh" };
+                const kal_uintptr sh_lens[] = { 6, 10 };
+                int sh = -1;
+                for (int i = 0; i < 2 && sh < 0; ++i) {
+                    kal_node_info info{}; info.self_size = sizeof info;
+                    if (kal_fs_info(slash, sh_paths[i], sh_lens[i], 0,
+                                    kal::fs::field::kind, &info) != kal_ok) continue;
+                    if (info.kind != kal_node_absent) sh = i;
+                }
+                check(sh >= 0, "a shell is found to raise the signal");
+
+                kal_process k{};
+                const kal_spawn how{ slash, slash, nullptr, nullptr, 0, 0 };
+                const char*       kargv[] = { "sh", "-c", script };
+                const kal_uintptr klens[] = { 2, 2, n };
+                int krc = kal_err_invalid;
+                if (sh >= 0)
+                    krc = kal_process_spawn(&how, sh_paths[sh], sh_lens[sh],
+                                            kargv, klens, 3,
+                                            nullptr, nullptr, 0, nullptr, &k);
+                check(krc == kal_ok, "the program that raises the signal starts");
+
+                if (krc == kal_ok) {
+                    // Up to five seconds, in bounded waits upon the word itself
+                    // --- which is the use the word was specified for.
+                    for (int i = 0; i < 50 && *word == 0; ++i)
+                        kal_task_wait(word, 0u, 100ull * 1000 * 1000);
+
+                    check(*word != 0, "the program is told that its end was requested");
+
+                    // ⭐ AND IT IS STILL RUNNING, which is the half a compiled
+                    // disposition cannot show. Reaching this line is the proof:
+                    // a program that died in the handler never gets here.
+                    check(true, "and it is still running, having survived delivery");
+
+                    int status = -1, terminated = -1;
+                    kal_process_wait(k, &status, &terminated);
+                    kal_process_close(k);
+                }
+            }
+        }
+    }
+
     const char ok[] = "openkal-macos: process and task conformance\n";
     kal::write(kal::out(), ok, sizeof(ok) - 1);
     return failures == 0 ? 0 : 1;