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
22 changes: 18 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,20 @@ the mtest library; each CI run reports them together.
in the repository's store, and a program handed to a runner (`node` on the Web)
was named relative to the wrong directory.

## Version 0.26

A start is bounded by the environment alone: an implementation keeps no bound of
its own upon the number or size of the arguments and variables it is given, and
the environment's refusal for size is `kal_err_no_space` (clause 7.6, entry 64).
A unit's reference names the start of the system and the process space it was
made in. A reference from an earlier start, and an identifier since given to a
program of another birth, are `empty`; a reference from another space is refused
by `kal_process_job_open` with `kal_err_not_supported`, an answer that does not
change by waiting; and `KAL_PROCESS_PROP_JOB_OBSERVE` is claimed only where a
reference can be made (clause 7.18, entry 65). No declaration changes. Both are
requirements upon every implementation, so the minor version advances (clause
8), and the suite observes each.

## How a program uses openkal

A program declares two dependencies. The first fixes the version of the contract
Expand All @@ -112,16 +126,16 @@ conditional on the target.

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

[target.'cfg(os = "linux")'.dependencies]
openkal-linux = "0.26.3"
openkal-linux = "0.27.0"

[target.'cfg(os = "macos")'.dependencies]
openkal-macos = "0.23.2"
openkal-macos = "0.24.0"

[target.'cfg(windows)'.dependencies]
openkal-windows = "0.21.2"
openkal-windows = "0.23.0"
```

The program imports the interface and names no implementation.
Expand Down
65 changes: 64 additions & 1 deletion SPEC.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# openkal Specification, version 0.25.3
# openkal Specification, version 0.26.0

## 1. Scope

Expand Down Expand Up @@ -886,6 +886,16 @@ and the others joined after it by single spaces, unaltered; an implementation
claims it with `KAL_PROCESS_PROP_ONE_STRING`, and one whose environment gives a
program a vector reports `kal_err_not_supported` (version 0.17.1).

The vector and the environment are bounded by the environment alone. An
implementation shall keep no bound of its own, upon the number of elements of
either or upon their size, below what its environment admits. A start that the
environment refuses for the size of what it was given shall be reported as
`kal_err_no_space`: the request did not fit, which a caller acts upon by giving
less, and which neither `kal_err_no_memory` nor `kal_err_io` states. Which
environment admits how much is not specified, and a caller that must stay
within every environment's bound gives a program its arguments in a file.
Clause 11, entry 64.

This rule was absent from version 0.3, and both implementations existing at the
time prepended the path. They agreed only because they shared an author; a third
implementer had nothing to consult. The defect was found by writing one program
Expand Down Expand Up @@ -1145,6 +1155,32 @@ continuation yields `unknown`. Retirement conveys no admission or termination
authority over the continuation's unit and never reopens the original unit.
The caller may remain alive to finish its own bookkeeping. Clause 11, entry 58.

A reference names where it was made: the start of the system, and, where an
environment divides its programs into spaces of which one cannot enumerate
another's, the space. An implementation shall identify a space by something the
environment gives to no later space, and shall not answer a reference from the
programs of a space other than the reference's own. From this the answers
follow (version 0.26):

| the reference | answer |
| --- | --- |
| was made under an earlier start of the system | `empty`: every program of that start has ended |
| names a unit whose identifier a program of another birth now holds, where the environment withholds a unit's identifier while a member remains | `empty` |
| was made in another space of this start | `kal_process_job_open` reports `kal_err_not_supported`, to this caller always |
| names a unit whose native identity the environment did not keep once its last holder was lost | the same: the loss is not evidence that the members have ended, and the unit cannot be opened again |
| cannot be decided now and may be later | `unknown` |

`unknown` is thereby a condition that may pass, and a caller may wait upon it;
`kal_err_not_supported` from `kal_process_job_open` is one that does not, and a
caller that waits upon it waits for nothing.

An implementation claims `KAL_PROCESS_PROP_JOB_OBSERVE` only where it can make a
reference: where the start of the system, the space and a program's birth can
all be read. Where one cannot, it does not claim the property, and
`kal_process_job_create` reports `kal_err_not_supported`; a caller learns it
from `kal_process_props` before it starts anything (clause 6.1). Clause 11,
entry 65.

### 7.19 A started program that runs to its end first

Some environments have one task: a firmware's boot services, a disk operating
Expand Down Expand Up @@ -2231,6 +2267,33 @@ The following are recorded so that they are not mistaken for oversights.
the implementation holds. The suite now reaches every name without
requiring it, so a defined name is kept and an absent one is null.

64. **A start bounded by the environment alone.** **Specified in 0.26**, in
clause 7.6. Two implementations refused a start whose vector or environment
had more than 512 elements and reported `kal_err_no_memory`; neither
constant guarded a fixed buffer, and the specification authorised neither.
A build tool passes a compiler one argument for each include directory and
each definition, and an environment prepared by a development tool holds
several hundred variables, so the bound was met by ordinary programs and
its report named a cause that was not the cause. The environment's own
refusal reached a caller as `kal_err_io`. An implementation now keeps no
bound below its environment's, and the environment's refusal is
`kal_err_no_space`. No declaration changes; the requirement is upon every
implementation, so the minor version advances (clause 8).

65. **What an observation answers, and where a unit is claimed.** **Specified
in 0.26**, in clause 7.18. An observer had two outcomes, `empty` and
`unknown`, for three facts: a unit that is empty, one that is occupied or
not yet decidable, and one that cannot be observed from where the observer
is. The third does not change by waiting, and a caller that waited upon it
refused for ever a build interrupted in another process space. Two cases
answered `unknown` that can be established as `empty`: a reference from an
earlier start of the system, and an identifier since given to a program of
another birth. One implementation identified a process space by a number
its kernel gives again to a later space, so a reference could be answered
from the programs of an unrelated space. The reference now names its space
exactly, the answers are those of the table in 7.18, and the property is
claimed only where a reference can be made. No declaration changes.

## 12. Images

A program written against this specification is built for an environment: its
Expand Down
2 changes: 1 addition & 1 deletion SURFACE.txt
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# The C surface of openkal 0.25.0, one name per line.
# The C surface of openkal 0.26.0, one name per line.
#
# This file is normative and is the single source consulted by clause 9. A
# conforming implementation exports the names of the interfaces it provides
Expand Down
12 changes: 6 additions & 6 deletions examples/portable/mcpp.toml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ name = "portable"
version = "0.1.0"

[dependencies]
openkal = "0.25.3"
openkal = "0.26.0"

# AND THE VERSIONS HAVE TO FOLLOW THE SOURCE, which is the reason this example
# is a criterion rather than an assumption.
Expand All @@ -25,13 +25,13 @@ openkal = "0.25.3"
# so no repository's continuous integration compiled it. The platform legs
# below exist so that it cannot go stale silently again.
[target.'cfg(os = "linux")'.dependencies]
openkal-linux = "0.26.3"
openkal-linux = "0.27.0"

[target.'cfg(os = "macos")'.dependencies]
openkal-macos = "0.23.2"
openkal-macos = "0.24.0"

[target.'cfg(windows)'.dependencies]
openkal-windows = "0.21.2"
openkal-windows = "0.23.0"

# ANDROID IS NOT A LINE HERE, AND THAT IS THE POINT.
#
Expand All @@ -57,7 +57,7 @@ openkal-windows = "0.21.2"
# All three iOS rows match: the device and both simulator arches carry
# `os = "ios"`.
[target.'cfg(os = "ios")'.dependencies]
openkal-macos = "0.23.2"
openkal-macos = "0.24.0"

# THE WEB IS THE ONE PLATFORM THAT NEEDED NEW SOFTWARE.
#
Expand All @@ -82,4 +82,4 @@ openkal-macos = "0.23.2"
# error would have produced a program that links, runs, and fails where a
# reader cannot connect it to a missing facility. See the README.
[target.'cfg(os = "emscripten")'.dependencies]
openkal-emscripten = "0.14.2"
openkal-emscripten = "0.15.0"
23 changes: 21 additions & 2 deletions include/openkal/process.h
Original file line number Diff line number Diff line change
Expand Up @@ -322,6 +322,11 @@ extern "C" {
* Everything that varies between one start and another is in `kal_spawn', which
* is why this is one declaration and not a family --- see the comment there.
*
* THE VECTOR AND THE ENVIRONMENT ARE BOUNDED BY THE ENVIRONMENT ALONE (version
* 0.26, clause 7.6): an implementation keeps no bound of its own upon the
* number of elements or their size, and a start the environment refuses for
* the size of what it was given is kal_err_no_space.
*
* EACH ENVIRONMENT ENTRY IS `NAME=value', and an entry that holds no `=', or
* whose name is empty, is kal_err_invalid and starts nothing. Version 0.17
* states it: one implementation refused such an entry and another passed it to
Expand Down Expand Up @@ -647,8 +652,10 @@ void kal_process_job_close(struct kal_job);
* a caller. `open' obtains an observation reference to the original unit;
* closing it ends nothing. An environment that cannot retain a native unit
* identity after its last observer is lost shall not report name absence as
* emptiness. It reports UNKNOWN. Neither a dead leader nor a stale reference
* proves that the unit's other programs have ended.
* emptiness: `open' refuses such a reference with kal_err_not_supported
* (version 0.26), as it does any reference the caller can never observe.
* Neither a dead leader nor a stale reference proves that the unit's other
* programs have ended.
*
* A job obtained by `open' shall be passed only to `observe' and `close',
* never to spawn, enter, terminate, limit or another control operation. This
Expand All @@ -661,6 +668,18 @@ void kal_process_job_close(struct kal_job);
* ambiguity, an inaccessible unit or an expired native reference is UNKNOWN,
* never EMPTY. A positively empty unit has no remaining active member.
*
* WHAT A REFERENCE'S ORIGIN ESTABLISHES (version 0.26, clause 7.18). A
* reference names the start of the system and the process space it was made
* in, the space by something the environment gives to no later space. One
* made under an earlier start is EMPTY: every program of that start has ended.
* Where the environment withholds a unit's identifier while a member remains,
* an identifier a program of another birth now holds is EMPTY. One made in
* another space of this start, and one whose native identity was not kept
* once its last holder was lost, cannot be observed from here, and waiting
* does not change that: `open' reports kal_err_not_supported, to this caller
* always, where UNKNOWN is a condition that may pass. JOB_OBSERVE is claimed
* only where a reference can be made.
*
* The job returned by `create' is the job supplied to the EXISTING spawn:
* one start, with the declared unit stated by its caller. Before `retire',
* the caller shall cease all admission into that unit, including its own
Expand Down
4 changes: 2 additions & 2 deletions include/openkal/version.h
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,8 @@
* for the reason tools/check-readme-versions.sh exists --- the one fact a
* consumer actually asks for was checked by nobody. */
#define KAL_VERSION_MAJOR 0u
#define KAL_VERSION_MINOR 25u
#define KAL_VERSION_PATCH 3u
#define KAL_VERSION_MINOR 26u
#define KAL_VERSION_PATCH 0u

#define KAL_VERSION_MAKE(major, minor, patch) \
(((kal_u64)(major) << 32) | ((kal_u64)(minor) << 16) | \
Expand Down
4 changes: 2 additions & 2 deletions kit/mcpp.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
namespace = "mcpplibs"
name = "openkal-kit"
version = "0.3.1"
version = "0.3.2"
description = "Facilities composed from openkal's interfaces. Not part of the specification, and structurally incapable of being mistaken for it."
license = "Apache-2.0"
authors = ["mcpplibs"]
Expand Down Expand Up @@ -67,7 +67,7 @@ kind = "lib"
# published packages, which is the only place this could be observed: no
# continuous integration in this ecosystem resolves a published package,
# because they all substitute working trees by design.
openkal = "0.25.0"
openkal = "0.26.0"

# NO `include_dirs` HERE EITHER. It named `../include`, which reaches out of
# this package into whatever happens to sit above it. With the specification
Expand Down
2 changes: 1 addition & 1 deletion mcpp.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
namespace = "mcpplibs"
name = "openkal"
version = "0.25.3"
version = "0.26.0"
description = "openkal: a portable kernel ABI specification. This package carries the normative declarations; implementations are separate packages."
license = "Apache-2.0"
authors = ["mcpplibs"]
Expand Down
4 changes: 2 additions & 2 deletions tests/cts/mcpp.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
namespace = "mcpplibs"
name = "openkal-conformance"
version = "0.10.1"
version = "0.11.0"
description = "The behavioural half of clause 9: a suite an implementation of openkal runs against itself, selectable to the interfaces it provides."
license = "Apache-2.0"
authors = ["mcpplibs"]
Expand All @@ -18,7 +18,7 @@ repo = "https://github.com/mcpplibs/openkal"
# What it depends upon is therefore openkal and the language. The formatting in
# okc.report is the price of that, and it is sixty lines.
[dependencies]
openkal = "0.25.3"
openkal = "0.26.0"

# The implementation under examination is not named here.
#
Expand Down
2 changes: 1 addition & 1 deletion tests/cts/src/protocol.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ bool begin() {

line e;
e.raw("{\"e\":\"program\",\"protocol\":1,\"level\":2,\"framework\":\"openkal-conformance\","
"\"version\":\"0.10.1\",\"isolation\":[\"process\"]}");
"\"version\":\"0.11.0\",\"isolation\":[\"process\"]}");
e.send();
return true;
#else
Expand Down
2 changes: 1 addition & 1 deletion tests/cts/src/report.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ int failed_count() { return g_failed; }
int unobserved_count() { return g_unobserved; }

void write_inventory() {
line("openkal conformance suite, version 0.10.1");
line("openkal conformance suite, version 0.11.0");
line("");
line("interface provision examined select with");
for (const auto& row : inventory) {
Expand Down
60 changes: 60 additions & 0 deletions tests/cts/src/sections/child.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ const char* argument_for(errand e) {
case errand::report_resources: return "--child-report-resources";
case errand::fault: return "--child-fault";
case errand::write_in_first_grant: return "--child-write-in-first-grant";
case errand::count_vectors: return "--child-count-vectors";
case errand::declare_unit: return "--child-declare-unit";
case errand::none: break;
}
return "";
Expand Down Expand Up @@ -74,6 +76,11 @@ errand child_errand() {
if (same(a, len, argument_for(errand::report_resources))) return errand::report_resources;
if (same(a, len, argument_for(errand::fault))) return errand::fault;
if (same(a, len, argument_for(errand::write_in_first_grant))) return errand::write_in_first_grant;
if (same(a, len, argument_for(errand::count_vectors))) return errand::count_vectors;
if (same(a, len, argument_for(errand::declare_unit))) return errand::declare_unit;
// The errand is the second element; what follows it under
// `count_vectors' is two thousand elements that name none.
break;
}
#endif
return errand::none;
Expand Down Expand Up @@ -292,6 +299,41 @@ after g_after;
}
#endif
kal_exit(72);
case errand::count_vectors:
#ifdef MCPP_FEATURE_ENV
{
// The lengths are asked with no buffer, so the copy holds
// neither vector: what it reports is what it was given.
int status = 100;
const kal_uintptr args = kal_env_arg_count();
if (args == 2 + vector_count) status += 1;
kal_uintptr named = 0;
const kal_uintptr prefix = sizeof vector_name - 1;
for (kal_uintptr i = 0; i < kal_env_var_count(); ++i) {
char name[64];
const kal_intptr n = kal_env_var_at(i, name, sizeof name);
if (n < static_cast<kal_intptr>(prefix) || static_cast<kal_uintptr>(n) >= sizeof name) continue;
if (!same(name, prefix, vector_name)) continue;
if (kal_env_var(name, static_cast<kal_uintptr>(n), nullptr, 0)
== static_cast<kal_intptr>(vector_value)) ++named;
}
if (named == vector_count) status += 2;
for (kal_uintptr i = 2; i < args; ++i)
if (kal_env_arg(i, nullptr, 0) == static_cast<kal_intptr>(vector_long)) { status += 4; break; }
kal_exit(status);
}
#endif
kal_exit(99);
case errand::declare_unit:
#ifdef MCPP_FEATURE_PROCESS
{
kal_job unit{}; char reference[512]; kal_uintptr used = 0;
const int e = kal_process_job_create(&unit, reference, sizeof reference, &used);
if (e == kal_ok) kal_exit(used != 0 ? 80 : 82);
kal_exit(e == kal_err_not_supported ? 81 : 82);
}
#endif
kal_exit(82);
case errand::hold_memory:
case errand::grow_memory:
// Memory written through, so that every environment charges it ---
Expand Down Expand Up @@ -473,6 +515,22 @@ bool start_copy_granting_with(const char* errand_argument, const kal_preopen* gr
return e == kal_ok;
}

bool start_copy_given(const char** argv, const kal_uintptr* lens, kal_uintptr count,
const char** env, const kal_uintptr* env_lens, kal_uintptr env_count,
int& spawned, int& status, int& terminated) {
kal_dir base{}; const char* rel = nullptr; kal_uintptr rel_len = 0;
if (!locate_self(base, rel, rel_len)) return false;
const kal_spawn_streams streams{ 0, 0, 0 };
const kal_spawn how{ base, kal::fs::working(), nullptr, nullptr, 0, 0 };
kal_process child{};
spawned = kal_process_spawn(&how, rel, rel_len, argv, lens, count, env, env_lens, env_count,
&streams, &child);
if (spawned != kal_ok) return true;
const int e = kal_process_wait(child, &status, &terminated);
kal_process_close(child);
return e == kal_ok;
}

bool start_copy_with(const char* errand_argument, kal_uintptr flags,
const kal_spawn_streams& streams, int& spawned,
int& status, int& terminated) {
Expand All @@ -498,6 +556,8 @@ bool start_copy_running(const char*, const char*, kal_process&) { return false;
bool start_copy_in_unit(const char*, kal_job&, kal_process&) { return false; }
bool start_copy_granting(const char*, const kal_preopen*, kal_uintptr, int&, int&) { return false; }
bool start_copy_with(const char*, kal_uintptr, const kal_spawn_streams&, int&, int&, int&) { return false; }
bool start_copy_given(const char**, const kal_uintptr*, kal_uintptr, const char**,
const kal_uintptr*, kal_uintptr, int&, int&, int&) { return false; }
bool start_copy_granting_with(const char*, const kal_preopen*, kal_uintptr, kal_uintptr,
const kal_spawn_streams&, int&, int&, int&) { return false; }

Expand Down
Loading
Loading