Skip to content
Open
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
35 changes: 33 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@ written on the kernel's own calls.

```toml
[dependencies]
openkal = "0.25.0"
openkal = "0.26.0"

[target.'cfg(os = "macos")'.dependencies]
openkal-macos = "0.23.5"
openkal-macos = "0.24.1"
```

Its purpose is as much to test the specification as to be used. A specification
Expand All @@ -23,6 +23,21 @@ References retain the original process identity, birth and boot session.
Retirement checks the live continuation before and after membership migration;
ambiguity reports `unknown`. No process registry is installed.

**What an observation answers (0.24.0, openkal 0.26, clause 7.18).** This kernel
has one process space, so a reference names its boot session and nothing else.
A reference of another boot session is `empty`, where `kal_process_job_open`
refused it; one whose number a program of another start now holds is `empty`,
where it was `unknown`: a number is given again only once no program holds it as
its group. `KAL_PROCESS_PROP_JOB_OBSERVE` is claimed only where the boot session
and the caller's start can be read. `tests/a_unit_reference_names_its_boot_session.cpp`.

**A start is bounded by the kernel alone (0.24.0, openkal 0.26, clause 7.6).** An
argument vector or an environment of more than 512 entries was refused and
reported as `kal_err_no_memory`; the constant guarded no buffer. It is removed:
the kernel bounds the bytes of both together (`ARG_MAX`), and its refusal
(`E2BIG`) is reported as `kal_err_no_space`, where it was `kal_err_io`.
`tests/a_start_is_bounded_by_the_kernel_alone.cpp`.

**The confinement rules are as long as the grants make them (0.22.1).** The
sandbox profile names each grant in the write rule and in the read rule. Its
buffer was a fixed 16 KiB, and sixteen grants with names near `MAXPATHLEN`
Expand Down Expand Up @@ -183,6 +198,22 @@ same image parses as fast on Linux arm64. Since 0.17.1 it is the same kernel ide
this system's library keeps for each thread (`pthread_threadid_np`, a name no C
library in this ecosystem defines).

## What 0.24.1 corrects

**A request acted on by another context ends the program as the request.**
`kal_process_end_as_requested` restores the request's default treatment, unblocks
it and sends it to the program again; a program still there a moment later ends
with the status a shell gives one so ended. The kernel gives a signal sent to the
program to the first of its contexts that does not block it, which need not be
the caller, and the moment was not waited for: called from a context other than
the first, `kill` returned before the signal was delivered and the exit ended the
program first, so its starter saw the status 143 where the request's own end was
`SIGTERM` (measured: okrun 0.7.0, whose own context acts on the request, on the
macos-15 arm64 runners). The call now waits up to a tenth of a second for the
delivery, as openkal-linux does, before that exit.
`tests/stop_word_and_sigpipe.cpp` runs twenty copies whose second context acts on
the request while the first waits for it; each ends by `SIGTERM`.

## What 0.23.5 corrects

**A part of `fork` the library does not export is not called.** Starting a context
Expand Down
4 changes: 2 additions & 2 deletions mcpp.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
namespace = "mcpplibs"
name = "openkal-macos"
version = "0.23.5"
version = "0.24.1"
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"

Expand Down Expand Up @@ -62,7 +62,7 @@ provides-interfaces = [

[dependencies]
# Every patch release of the specification's minor version (openkal clause 8).
openkal = "^0.25.0"
openkal = "^0.26.0"

[build]
# The flags are attached to this package's own sources rather than to the whole
Expand Down
59 changes: 48 additions & 11 deletions src/process.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,9 @@ namespace okm { extern bool g_pipe_ignored_here; }

namespace {

constexpr kal_uintptr kMaxEntries = 512;
bool units_observable(); // defined beside the unit's reference (clause 7.18)



// --- confinement (0.23): this system's sandbox ---------------------------------
//
Expand Down Expand Up @@ -218,7 +220,6 @@ struct vector {
bool ok = true;

bool build(const char** items, const kal_uintptr* lens, kal_uintptr n) {
if (n > kMaxEntries) { ok = false; return false; }
okm_uptr total = 0;
for (kal_uintptr i = 0; i < n; ++i) total += lens[i] + 1;
slots_bytes = (n + 1) * sizeof(char*);
Expand Down Expand Up @@ -262,7 +263,6 @@ struct vector {

bool build_env(const char** items, const kal_uintptr* lens, kal_uintptr n,
const kal_preopen* grants, kal_uintptr g, const conveyance& c) {
if (n > kMaxEntries) { ok = false; return false; }
auto left_out = [&](const char* s, kal_uintptr l) {
return names_preopens(s, l) || starts_with(s, l, kRights, kRightsLen)
|| starts_with(s, l, kResources, kResourcesLen);
Expand Down Expand Up @@ -1326,9 +1326,16 @@ int kal_process_end_as_requested(void) {
okm::sys(nr_sigaction, signo, reinterpret_cast<okm_long>(&act), 0);
unsigned int set = 1u << (signo - 1);
okm::sys(okm::nr_sigprocmask, 2 /* SIG_UNBLOCK */, reinterpret_cast<okm_long>(&set), 0);
// A signal a program sends itself, unblocked, is delivered before the call
// returns; the exit below is reached only if it was not.
okm::sys(okm::nr_kill, okm::sys(okm::nr_getpid), signo);
// THE MOMENT IS WAITED FOR (0.24.1). The kernel gives a signal sent to the
// program to the first of its contexts that does not block it, which need
// not be the caller: called from another context, `kill' returned before
// the signal was delivered, and the exit below ended the program first, so
// its starter saw 143 where the request's own end was SIGTERM (measured:
// okrun 0.7.0, whose own context acts on the request, on macos-15 arm64).
// As openkal-linux, a tenth of a second; the exit is reached only if the
// signal was not delivered in it.
for (int i = 0; i < 100; ++i) kal_time_sleep(1000000ull);
okm::sys(okm::nr_exit, 128 + signo);
#endif
for (;;) { }
Expand Down Expand Up @@ -1424,7 +1431,9 @@ void kal_process_close(kal_process h) {
// 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_JOB_OBSERVE |
// JOB_OBSERVE is claimed where a reference can be made (clause 7.18, 0.26):
// where the boot session's name and this program's start can be read.
kal_uintptr kal_process_props(void) { return (units_observable() ? KAL_PROCESS_PROP_JOB_OBSERVE : 0u) |
KAL_PROCESS_PROP_TERMINATE | KAL_PROCESS_PROP_STREAM_PASSING
| KAL_PROCESS_PROP_EXIT_STATUS
| KAL_PROCESS_PROP_CHANNEL | KAL_PROCESS_PROP_GRANT_DIR
Expand All @@ -1448,6 +1457,18 @@ kal_uintptr kal_process_props(void) { return KAL_PROCESS_PROP_JOB_OBSERVE |

// Observable units (openkal 0.24). The unit stays the kernel's own group;
// identity validation does not create a registry or infer quiet from a leader.
//
// WHAT AN OBSERVATION CAN ESTABLISH (openkal 0.26, clause 7.18). This kernel
// has one process space, so a reference names its boot session and nothing
// else:
// another boot session every program of it has ended EMPTY
// no such group the kernel holds none EMPTY
// the number is another program's
// a number is given again only once no program
// holds it as its group, so the unit ended EMPTY
// the group OCCUPIED
// Where the boot session cannot be read nothing is established: `open'
// refuses, and the property is not claimed.
#include "unit_reference.h"
namespace {
struct unit_identity {
Expand Down Expand Up @@ -1479,9 +1500,23 @@ bool unit_parse(const char* p, kal_uintptr n, unit_identity& u) {
&& r.number(u.birth) && u.birth != 0
&& r.token(u.boot,sizeof u.boot) && r.at == n;
}
bool unit_same_origin(const unit_identity& u) {
enum class origin { here, another_boot, unreadable };
origin unit_origin_of(const unit_identity& u) {
char boot[64]{}, space[64]{};
return unit_origin(boot,space) && unit_reference::same(u.boot,boot);
if (!unit_origin(boot,space)) return origin::unreadable;
return unit_reference::same(u.boot,boot) ? origin::here : origin::another_boot;
}
bool unit_same_origin(const unit_identity& u) { return unit_origin_of(u) == origin::here; }
// Read once: the answer is a property of where the program runs.
bool units_observable() {
static int known = -1;
int k = __atomic_load_n(&known, __ATOMIC_ACQUIRE);
if (k < 0) {
char boot[64]{}, space[64]{}; kal_u64 own = 0;
k = unit_origin(boot,space) && unit_birth(0,own) && own != 0 ? 1 : 0;
__atomic_store_n(&known, k, __ATOMIC_RELEASE);
}
return k == 1;
}
}
extern "C" {
Expand All @@ -1501,18 +1536,20 @@ int kal_process_job_create(kal_job* out, char* reference, kal_uintptr capacity,
int kal_process_job_open(const char* reference, kal_uintptr length, kal_job* out) {
if (!out) return kal_err_invalid;
unit_identity u; if (!unit_parse(reference,length,u)) return kal_err_invalid;
if (!unit_same_origin(u)) return kal_err_not_supported;
if (unit_origin_of(u) == origin::unreadable) return kal_err_not_supported;
out->h = static_cast<kal_uintptr>(u.group); return kal_ok;
}
int kal_process_job_observe(kal_job job, const char* reference, kal_uintptr length, kal_u32* state) {
if (!state) return kal_err_invalid; *state = KAL_JOB_UNKNOWN;
unit_identity u; if (!unit_parse(reference,length,u) || job.h != u.group) return kal_err_invalid;
if (!unit_same_origin(u)) return kal_ok;
const origin from = unit_origin_of(u);
if (from == origin::another_boot) { *state = KAL_JOB_EMPTY; return kal_ok; }
if (from != origin::here) return kal_ok;
const auto status = okm::sys(okm::nr_kill,-static_cast<okm_long>(u.group),0);
if (status == -3 /* ESRCH */) { *state = KAL_JOB_EMPTY; return kal_ok; }
if (okm::failed(status)) return kal_ok;
kal_u64 birth = 0;
if (unit_birth(static_cast<okm_long>(u.group),birth) && birth != u.birth) return kal_ok;
if (unit_birth(static_cast<okm_long>(u.group),birth) && birth != u.birth) { *state = KAL_JOB_EMPTY; return kal_ok; }
*state = KAL_JOB_OCCUPIED; return kal_ok;
}
int kal_process_job_retire(kal_job job, const char* reference, kal_uintptr length,
Expand Down
6 changes: 4 additions & 2 deletions src/sys.h
Original file line number Diff line number Diff line change
Expand Up @@ -270,7 +270,7 @@ struct kpollfd { int fd; short events; short revents; };

// --- error values, as this kernel returns them -------------------------------
enum : int {
e_perm = 1, e_noent = 2, e_intr = 4, e_io = 5, e_noexec = 8, e_badf = 9,
e_perm = 1, e_noent = 2, e_intr = 4, e_io = 5, e_2big = 7, e_noexec = 8, e_badf = 9,
e_child = 10,
e_again = 35, e_nomem = 12, e_acces = 13, e_fault = 14, e_busy = 16,
e_exist = 17, e_xdev = 18, e_nodev = 19, e_notdir = 20, e_isdir = 21,
Expand Down Expand Up @@ -360,7 +360,9 @@ inline int translate(okm_long r) {
case e_loop: case e_spipe: return 1; // invalid
case e_again: return 2; // again
case e_nomem: return 4; // no memory
case e_nospc: case e_fbig: case e_dquot: return 5; // no space
// e_2big: a start whose arguments and environment exceed ARG_MAX
// (openkal 0.26, clause 7.6).
case e_nospc: case e_fbig: case e_dquot: case e_2big: return 5; // no space
case e_acces: case e_perm: case e_rofs: return 6; // permission
case e_nosys: case e_opnotsupp: case e_notsup: return 7; // unsupported
case e_pipe: case e_connreset: return 8; // closed
Expand Down
88 changes: 88 additions & 0 deletions tests/a_start_is_bounded_by_the_kernel_alone.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
// A start takes the vectors its caller gives (SPEC.md clause 7.6, version 0.26).
//
// Until 0.24.0 this implementation refused an argument vector or an environment
// of more than 512 entries and reported it as memory exhausted. Neither vector
// has a fixed buffer, and the kernel bounds the bytes of both together
// (ARG_MAX, one mebibyte), not their entries. A build tool reached the bound
// with a compile command of 520 definitions, and a development environment's
// build phase with 546 variables; both read as a machine out of memory.
//
// Each case has a shell report what it received, since the claim is about the
// started program.
#include <cstdio>
#include <cstring>
#include <string>
#include <vector>
import openkal.fs;
import openkal.types;
import openkal.process;
import mcpplibs.mtest;

using namespace mcpplibs::mtest;

namespace {

kal_dir root() {
for (kal_uintptr i = 0; i < kal_fs_preopen_count(); ++i) {
kal_dir d{}; char n[8]; kal_uintptr l = 0;
if (kal_fs_preopen(i, &d, n, sizeof n, &l) == kal_ok && l == 1 && n[0] == '/') return d;
}
return kal_dir{};
}

// Starts /bin/sh with the vectors given; the answer of the start, and the
// status where it started.
int start_shell(const std::vector<std::string>& args, const std::vector<std::string>& env, int& status) {
std::vector<const char*> argv, envp;
std::vector<kal_uintptr> alens, elens;
for (auto const& a : args) { argv.push_back(a.c_str()); alens.push_back(a.size()); }
for (auto const& e : env) { envp.push_back(e.c_str()); elens.push_back(e.size()); }
const kal_spawn how{ root(), kal::fs::working(), nullptr, nullptr, 0, 0 };
kal_process p{};
int rc = kal_err_invalid;
for (const char* path : { "bin/sh", "usr/bin/sh" }) {
rc = kal_process_spawn(&how, path, std::strlen(path), argv.data(), alens.data(), argv.size(),
envp.data(), elens.data(), envp.size(), nullptr, &p);
if (rc != kal_err_not_found) break;
}
if (rc != kal_ok) return rc;
int terminated = -1;
kal_process_wait(p, &status, &terminated);
kal_process_close(p);
if (terminated != 0) status = -1;
return kal_ok;
}

} // namespace

UTest a_start_is_bounded_by_the_kernel_alone_test{"a_start_is_bounded_by_the_kernel_alone", [] {
// 2,000 arguments after the script: the shell counts them. 2000 mod 256 is 208.
{
std::vector<std::string> args{ "sh", "-c", "exit $(($# % 256))", "sh" };
for (int i = 0; i < 2000; ++i) args.push_back("a");
int status = -1;
const int rc = start_shell(args, {}, status);
expect(rc == kal_ok) << "a vector of 2,004 elements starts (answer " << rc << ")";
expect(status == 208) << "the started program counts 2,000 arguments (status " << status << ")";
}
// 2,000 variables, about 200 KiB: the shell reads the first and the last.
{
std::vector<std::string> env;
const std::string value(90, 'v');
for (int i = 0; i < 2000; ++i) env.push_back("OKV" + std::to_string(i) + "=" + value + std::to_string(i));
const std::vector<std::string> args{ "sh", "-c",
"[ \"${OKV0%0}\" = \"" + value + "\" ] && [ \"${OKV1999%1999}\" = \"" + value + "\" ] && exit 77; exit 1" };
int status = -1;
const int rc = start_shell(args, env, status);
expect(rc == kal_ok) << "an environment of 2,000 variables starts (answer " << rc << ")";
expect(status == 77) << "the started program reads the first and the last variable (status " << status << ")";
}
// More than the kernel takes for both vectors together (ARG_MAX): the
// request does not fit, which is not a machine without memory.
{
const std::vector<std::string> args{ "sh", "-c", "exit 0", "sh", std::string(2 * 1024 * 1024, 'x') };
int status = -1;
const int rc = start_shell(args, {}, status);
expect(rc == kal_err_no_space) << "a start the kernel refuses for its size is no space (answer " << rc << ")";
}
}};
88 changes: 88 additions & 0 deletions tests/a_unit_reference_names_its_boot_session.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
// What an observation of a unit answers (SPEC.md clause 7.18, version 0.26).
//
// A unit here is a process group, and its reference names the boot session it
// was made in; this kernel has one process space. The cases alter a real
// reference one field at a time, which is how a reference from elsewhere reads
// to this program.
#include <cstdio>
#include <cstring>
#include <string>
#include <vector>
#include <csignal>
#include <unistd.h>
#include <sys/wait.h>
import openkal.types;
import openkal.process;
import mcpplibs.mtest;

using namespace mcpplibs::mtest;

namespace {

std::vector<std::string> fields(const std::string& r) {
std::vector<std::string> out(1);
for (char c : r) { if (c == ';') out.emplace_back(); else out.back() += c; }
return out;
}
std::string joined(const std::vector<std::string>& f) {
std::string out;
for (std::size_t i = 0; i < f.size(); ++i) { if (i) out += ';'; out += f[i]; }
return out;
}

// What `open' answers, and the state an observation gives where it opens.
struct answer { int open = 0; kal_u32 state = kal::process::job_state::unknown; };
answer ask(const std::string& reference) {
answer a; kal_job job{};
a.open = kal_process_job_open(reference.data(), reference.size(), &job);
if (a.open == kal_ok) kal_process_job_observe(job, reference.data(), reference.size(), &a.state);
return a;
}

} // namespace

UTest a_unit_reference_names_its_boot_session_test{"a_unit_reference_names_its_boot_session", [] {
expect(fatal(kal::process::has(kal::process::job_observe)))
<< "this environment lets a reference be made, so observation is claimed";

// A child declares a unit, reports its reference and stays until told.
int to_parent[2], to_child[2];
expect(fatal(pipe(to_parent) == 0 && pipe(to_child) == 0)) << "pipes";
const pid_t child = fork();
if (child == 0) {
close(to_parent[0]); close(to_child[1]);
kal_job job{}; char reference[256]; kal_uintptr used = 0;
const int rc = kal_process_job_create(&job, reference, sizeof reference, &used);
if (rc != kal_ok) used = 0;
(void)!write(to_parent[1], reference, used);
close(to_parent[1]);
char c; (void)!read(to_child[0], &c, 1);
_exit(0);
}
close(to_parent[1]); close(to_child[0]);
std::string reference(256, '\0');
const ssize_t n = read(to_parent[0], reference.data(), reference.size());
reference.resize(n > 0 ? static_cast<std::size_t>(n) : 0);
auto f = fields(reference);
expect(fatal(f.size() == 4 && f[0] == "M2")) << "the reference is `M2;group;birth;boot': " << reference;

expect(ask(reference).open == kal_ok && ask(reference).state == kal::process::job_state::occupied)
<< "a unit with a running member is occupied";

{ // Another boot session: every program of it has ended.
auto g = f; g[3] = "00000000-0000-0000-0000-000000000000";
const auto a = ask(joined(g));
expect(a.open == kal_ok && a.state == kal::process::job_state::empty) << "a reference of another boot session is empty (open " << a.open << ", state " << a.state << ")";
}
{ // The number is another program's: the kernel gave it again, which it
// does only once no program holds it as its group.
auto g = f; g[2] = std::to_string(std::stoull(f[2]) + 1);
const auto a = ask(joined(g));
expect(a.open == kal_ok && a.state == kal::process::job_state::empty) << "a unit whose number now names a program of another start is empty (state " << a.state << ")";
}

close(to_child[1]);
int status = 0; waitpid(child, &status, 0);
const auto after = ask(reference);
expect(after.open == kal_ok && after.state == kal::process::job_state::empty) << "a unit whose members have ended is empty (state " << after.state << ")";
}};
Loading
Loading