0.16.0 --- the region a context stands on, measured rather than inferred

`kal_task_stack` reports the stack of the CALLING context. Every context this
implementation creates runs on a region it allocated, so the pair is recorded
when the context begins and returned as it stands; the context the program was
started on has no such record, and its region is measured.

RLIMIT_STACK ALONE IS NOT THE ANSWER, AND BELIEVING IT WAS WOULD BE THE DEFECT
THIS EXISTS TO REMOVE. The limit is a policy, and the floor the kernel enforces
is `mapping_end - RLIMIT_STACK` --- the end of the MAPPING, which is not the
address the program's first instruction sees. `setup_arg_pages` places the
arguments at the top of the mapping and moves the mapping's start down by a
random shift, so a bound computed from a stack pointer begins below the real
floor. Below the real floor is where this system puts the program's own
libraries, so the range would contain another mapping: a caller that laid a
guard at its base, or measured the room above it, would be measuring a region
the kernel will not grow the stack into.

So the mapping is measured with `mincore` --- an exponential-then-bisection
search outward from a local of the caller --- and the floor is the higher of the
two bounds the kernel itself applies: `mapping_end - RLIMIT_STACK`, read with
`prlimit64`, and one guard gap above the nearest mapping below.

BOTH BOUNDS WERE MEASURED ON 6.8.0 BEFORE BEING WRITTEN DOWN. A descending write
stopped at exactly `mapping_end - RLIMIT_STACK`, with one page below it
unwritable and one page above it writable; with one page mapped by the test
itself inside the reservation, the same write stopped at exactly that page's end
plus 256 pages.

THE GUARD GAP IS A KERNEL GLOBAL THIS IMPLEMENTATION CANNOT READ, and the
default is therefore what is applied. A kernel booted with a larger gap stops
the stack above the base reported here --- the region is reported larger than
the kernel will grow it, which is the direction a caller must not be wrong in,
and the reason the default is applied rather than a smaller number. A kernel
booted with a smaller gap is reported a region smaller than it could have, which
is the harmless direction. Both are stated at the code.

An environment that will not answer --- `mincore` refused by a filter, say ---
is reported as the kernel's condition rather than as a range, because a range
derived from a refusal is a range derived from nothing. It is not reported as
"unsupported": clause 6.1 forbids a provided interface to answer that way.

Where the program carries a runtime of its own, that runtime owns the stacks and
is asked instead (`pthread_getattr_np`), which is the same answer a program
above openkal would get for itself. That is the one arrangement in which this
implementation may take a C library's name, and the file says so.

The conformance suite observes containment --- the reported region contains a
local of the context that asked, for the first context and for a started one,
and the answer does not change while the context runs --- and this package's own
tests observe the same property, because it is the one both of the wrong answers
mcpplibs/openkal-musl#49 removed had violated.

Author: Sunrisepeak

README.md

@@ -5,10 +5,10 @@ for Linux, written on the kernel's own system-call interface.
 
 ```toml
 [dependencies]
-openkal = "0.14.1"
+openkal = "0.15.0"
 
 [target.'cfg(os = "linux")'.dependencies]
-openkal-linux = "0.15.1"
+openkal-linux = "0.16.0"
 ```
 
 ## Why it does not use a C library
@@ -45,6 +45,46 @@ second and third.
 All eight. `tools/check-surface.sh --complete` in the specification package
 compares the exported names against `SURFACE.txt`.
 
+## The region a context stands on
+
+`kal_task_stack` reports the stack of the calling context, and this
+implementation answers it from two different sources because the two
+arrangements are told apart by who chose the stack.
+
+Where this implementation creates the context it also allocates the region, so
+the pair is recorded when the context begins and returned as it stands. That is
+exact and costs nothing.
+
+The context the program was started on has no such record, and its region is
+measured. `RLIMIT_STACK` alone is not the answer: the limit is a policy and the
+floor the kernel enforces is `mapping_end - RLIMIT_STACK`, where the mapping's
+end is not the address the program's first instruction sees --- the kernel
+places the arguments at the top of the mapping and moves the mapping's start
+down by a random shift. A region computed from a stack pointer alone therefore
+begins below the real floor, and below the real floor is where this system puts
+the program's own libraries.
+
+So the mapping is found by asking the kernel which pages are mapped, and the
+floor is the higher of the two bounds the kernel itself applies: the limit
+above, and one guard gap above the nearest mapping below, because the kernel
+refuses to grow the stack to within `stack_guard_gap` of another mapping.
+
+The gap is a kernel global this implementation cannot read, and the default of
+256 pages is what is applied. A kernel booted with a larger gap stops the stack
+above the base reported here, which is the direction a caller must not be wrong
+in; a kernel booted with a smaller one is reported a region smaller than it
+could have, which is the harmless direction.
+
+Both bounds were measured rather than derived, on 6.8.0: a descending write
+stopped at exactly `mapping_end - RLIMIT_STACK`, with one page below it
+unwritable and one page above it writable; and with a page mapped by the test
+itself inside the reservation, the same write stopped at exactly that page's end
+plus 256 pages.
+
+A program that carries a runtime of its own answers from that runtime instead
+(`pthread_getattr_np`), because in that arrangement the runtime is what owns the
+stacks and is what a program above openkal would ask for itself.
+
 ## Conformance
 
 The suite lives in the specification package and is the same suite every

mcpp.toml

@@ -1,7 +1,7 @@
 [package]
 namespace   = "mcpplibs"
 name        = "openkal-linux"
-version     = "0.15.1"
+version     = "0.16.0"
 description = "The reference implementation of openkal for Linux, written on the kernel's own system-call interface so that it can be placed beneath a C library as well as above one."
 license     = "Apache-2.0"
 
@@ -63,7 +63,7 @@ provides-interfaces = [
 ]
 
 [dependencies]
-openkal = "0.14.1"
+openkal = { git = "https://github.com/mcpplibs/openkal.git", branch = "openkal-0.15.0" }
 
 # The package contributes definitions and no modules. The interface it
 # implements is declared by the specification package, which this package

src/sys.h

@@ -100,6 +100,10 @@ enum : okl_long {
     nr_close_range = 436, nr_prlimit64 = 302,
     nr_dup2 = 33, nr_utimensat = 280, nr_symlinkat = 266, nr_fstatfs = 138,
     nr_getrandom = 318,
+    // openkal 0.15: the region a context stands on is measured by asking the
+    // kernel which pages are mapped. The floor comes from the limit the kernel
+    // itself enforces, which `nr_prlimit64' above already names.
+    nr_mincore = 27,
     // openkal 0.13: whether a node may be started
     nr_fchmodat = 268,
     // openkal 0.11: the directory a started program runs in, and the unit it joins
@@ -189,6 +193,12 @@ enum : okl_long {
     nr_prctl = 167, nr_sched_getaffinity = 123, nr_getppid = 173,
     nr_arch_prctl = -1, nr_utimensat = 88, nr_symlinkat = 36, nr_fstatfs = 44,
     nr_getrandom = 278,
+    // openkal 0.15: the region a context stands on is measured by asking the
+    // kernel which pages are mapped. The floor comes from the limit the kernel
+    // itself enforces, which `nr_prlimit64' above already names --- and the two
+    // numbers differ from the other architecture's because this one takes the
+    // architecture-independent table for everything it can.
+    nr_mincore = 232,
     // openkal 0.13: whether a node may be started
     nr_fchmodat = 53,
     // openkal 0.11: the directory a started program runs in, and the unit it joins