feat: 补上 time 与 env —— 而 time 缺席的那条理由是错的

kal.cpp 与 README 都写着 time 是「刻意缺席」,并给了理由:

  SBI 可以armed一个定时器中断,那是内核的机制,不是程序能读的时钟。

前半句对,后半句不从它推出来。这个架构**另外**把 `rdtime` 直接暴露给程序 ——
`time` CSR,由 Zicntr 定义,固件让低特权级可读 —— 它和 SBI 的定时器扩展是两个
不同的设施,第一个不存在说明不了第二个。

实测(2026-08-23,OpenSBI + QEMU virt,S 模式,底下没有内核):

  t0=333572 t1=381292  ADVANCES

⭐ 结论会被复查,写在它旁边的理由不会。那条理由在注释里待了多久,推翻它所需的
两分钟就一直可用多久。

## time

单调计数、精确粒度、以及在同一个计数器上自旋的 sleep —— 在一台只有一个执行
上下文、没有调度器可让的机器上,自旋**就是**睡眠而不是它的模拟,所以
KAL_TIME_PROP_SLEEP_PRECISE 是照实设的。

⚠️ 没有墙钟。SBI 不定义任何取墙钟的设施,而 6.2 把「有没有墙钟」定成属性而不是
接口 —— 所以 kal_time_wall 在场并返回 0,KAL_TIME_PROP_WALL_AVAILABLE 清零。

⚠️ 一处新的板级事实:rdtime 的频率架构不固定,写在设备树里,而入口约定不转发
设备树指针。所以它是构建输入 OPENKAL_OPENSBI_TIMEBASE_HZ,和已有的堆大小同一
先例 —— 属于机器的数字由知道是哪台机器的工程声明,而不是由不知道的包假设。

## env

每个答案都是空的,而这是实现不是桩。6.2 禁止的是「在场但总是失败」;这里没有
失败可报:固件把 hart 号和设备树交给镜像,两者都不是命令行,所以这个环境**有**
环境,只是里面没有东西。枚举零个东西的调用者不需要任何特例,这正是它与 6.2
禁止的那种运行期拒绝的区别。

## 判据

例子里加两条断言,并且都验证过会红:
- clock ok —— 两次读数中间 sleep 一毫秒,后者必须大于前者。把
  kal_time_monotonic 改成返回常量重跑,打印 clock stuck。**读得出来和会走
  是两件事,只有这条断言能分开它们。**
- env empty —— 「返回 0」和「根本没链进来」不问就分不出。

Author: speak-agent

.github/workflows/ci.yml

@@ -78,6 +78,13 @@ jobs:
           mcpp run 2>&1 | tee run.log
           grep -q "hello from openkal over SBI" run.log
           grep -q "heap ok" run.log
+          # ⚠️ `clock ok` is the line that distinguishes a counter that reads
+          # from a counter that MOVES. The example takes two readings with a
+          # sleep between them; a stuck clock reads fine and prints
+          # `clock stuck`. Verified to print it, by returning a constant from
+          # `kal_time_monotonic` and rerunning.
+          grep -q "clock ok" run.log
+          grep -q "env empty" run.log
 
   # ---------------------------------------------------------------------------
   # The cross-compilation is performed FROM three systems, not only from Linux.

README.md

@@ -23,16 +23,45 @@ requires firmware beneath it, a board backend does not.
 
 ## What is implemented
 
-`abort`, `stream` and `memory` — openkal's core set. An implementation provides
-an interface in whole or not at all, so the absence of `fs`, `process`, `task`,
-`env` and `time` is not a deviation; `import openkal.task;` simply does not
-resolve.
-
-⚠️ **`time` is absent deliberately, and SBI does have a timer.** SBI can arm a
-timer interrupt, which is a mechanism for a kernel rather than a clock a program
-can read. Reporting a clock that does not advance would make every timed wait
-silently wrong — the specification's own example of a simulation that
-disqualifies an interface from being provided at all.
+`abort`, `stream` and `memory` — openkal's core set — plus `time` and `env`. An
+implementation provides an interface in whole or not at all, so the absence of
+`fs`, `process` and `task` is not a deviation; `import openkal.task;` simply
+does not resolve. This machine has no storage, no second image to start and no
+scheduler, and clause 6.2 says the remedy for an operation that cannot be
+provided is that its absence be expressed by its absence rather than by a
+run-time refusal.
+
+⚠️ **`time` used to be on that list, with a reason, and the reason was wrong.**
+
+It read: SBI can arm a timer interrupt, which is a mechanism for a kernel rather
+than a clock a program can read. The first half is true. The second does not
+follow from it — this architecture also exposes `rdtime` directly to the
+program, through the `time` CSR, independently of SBI's timer extension. Two
+different facilities, and the absence of the first says nothing about the
+second.
+
+Measured 2026-08-23 under OpenSBI on QEMU's `virt`, from supervisor mode with no
+kernel beneath:
+
+```
+t0=333572 t1=381292  ADVANCES
+```
+
+⭐ The conclusion got rechecked and the reason beside it did not. The two
+minutes that refuted it had been available for as long as the file existed.
+
+`time` is therefore provided: a monotonic count, an exact granularity, and a
+sleep that spins on the same counter — which on a machine with one execution
+context and nothing to yield to is what sleeping *is*, so
+`KAL_TIME_PROP_SLEEP_PRECISE` is set truthfully. **Not** a wall clock: SBI
+defines no facility for one, `KAL_TIME_PROP_WALL_AVAILABLE` is clear, and clause
+6.2 makes that a property rather than a missing interface.
+
+`env` is provided and every answer is empty. That is an implementation, not a
+stub: firmware enters the image with a hart identifier and a device tree, and
+neither is a command line, so this environment *has* an environment and it has
+nothing in it. A caller enumerating zero things needs no special case, which is
+exactly what distinguishes this from the run-time refusal clause 6.2 forbids.
 
 ## The heap is a bump allocator, and that is a bound rather than an omission
 

examples/hello/src/main.cpp

@@ -7,6 +7,8 @@
 import openkal.stream;
 import openkal.abort;
 import openkal.memory;
+import openkal.time;
+import openkal.env;
 
 namespace {
 
@@ -25,9 +27,30 @@ extern "C" void kmain() {
     say(p ? "heap ok\n" : "heap exhausted\n");
     kal_free(p, 64, 16);
 
+    // ⚠️ THE ASSERTION IS THAT IT MOVES, NOT THAT IT READS.
+    //
+    // A clock that returns a constant reads perfectly well and is worthless,
+    // and it is the exact failure the comment this interface replaced was
+    // afraid of. So the sleep is between two readings and the second must
+    // exceed the first: a stuck counter fails here, and only here.
+    //
+    // The figure is a millisecond because it has to be long enough to exceed
+    // one tick of a granularity this package does not fix, and short enough
+    // that a spin of it does not matter to anyone.
+    const kal_duration t0 = kal_time_monotonic();
+    kal_time_sleep(1000000);
+    const kal_duration t1 = kal_time_monotonic();
+    say(t1 > t0 ? "clock ok\n" : "clock stuck\n");
+
+    // Empty, and that is the answer rather than a refusal — src/env.cpp records
+    // why the two are different. Asserted because "returns zero" and "was never
+    // linked" are indistinguishable without asking.
+    say(kal_env_arg_count() == 0 && kal_env_var_count() == 0
+            ? "env empty\n" : "env unexpected\n");
+
     // Reaches the host as QEMU's exit status, because SRST is a real shutdown
     // rather than a spin.
-    kal_exit(p ? 0 : 1);
+    kal_exit(p && t1 > t0 ? 0 : 1);
 }
 
 asm(".section .text.entry\n.globl _start\n_start:\n"

mcpp.toml

@@ -36,9 +36,18 @@ flags = [
                                  "-fno-asynchronous-unwind-tables"] },
 ]
 
-# ⚠️ The heap size is a build input because SBI provides no allocator and the
+# ⚠️ TWO FIGURES THAT BELONG TO THE MACHINE, DECLARED RATHER THAN ASSUMED.
+#
+# The heap size is a build input because SBI provides no allocator and the
 # region therefore has to come from somewhere. 64 KiB is enough for the
 # allocating half of the freestanding standard library on a small program and
 # small enough not to matter in an image; a project that needs another figure
 # overrides the define rather than editing this package.
-defines = ["OPENKAL_OPENSBI_HEAP_BYTES=65536"]
+#
+# The timebase is a build input because `rdtime` counts at a rate the
+# architecture does not fix. It is published in the device tree, which the entry
+# contract does not forward, so a project that runs on other hardware states it
+# here. The default is QEMU's `virt`. src/time.cpp records why this is an input
+# and what a project that leaves it wrong gets.
+defines = ["OPENKAL_OPENSBI_HEAP_BYTES=65536",
+           "OPENKAL_OPENSBI_TIMEBASE_HZ=10000000"]

src/env.cpp

@@ -0,0 +1,60 @@
+// openkal.env on the RISC-V Supervisor Binary Interface.
+//
+// ⚠️ EVERY ANSWER HERE IS EMPTY, AND THAT IS AN IMPLEMENTATION RATHER THAN A
+// STUB. THE DIFFERENCE IS THE ONE CLAUSE 6.2 TURNS ON.
+//
+// Clause 6.2 forbids the arrangement this file could be mistaken for: "an
+// operation that is present and always fails is a defect; the remedy is that
+// its absence be expressed by its absence". So the question that has to be
+// answered before writing any of it is whether an image started by firmware
+// HAS an environment, and the answer is that it has one and it is empty.
+//
+// Those are not the same situation, and the distinction is visible in what a
+// caller sees. An implementation that refused would have to report a failure,
+// and a caller would have to distinguish "this machine cannot tell me" from
+// "there are none". Here there is nothing to distinguish: the count is zero,
+// and every enumeration of zero things ends immediately. A hosted
+// implementation asked for the fourth of three arguments returns exactly what
+// this one returns for the first of none, by the same rule, and no caller needs
+// a special case for either.
+//
+// ⚠️ WHY IT IS EMPTY, WHICH IS A FACT ABOUT THE ENTRY CONTRACT AND NOT ABOUT SBI
+//
+// Firmware enters the image at its load address with a hart identifier and a
+// device tree in registers. Neither is a command line. A device tree CAN carry
+// one --- `/chosen/bootargs` --- and this package does not read the device
+// tree, for the reason time.cpp records: the entry sequence belongs to the
+// consumer, and the pointer is gone by the time anything here runs.
+//
+// So "no arguments" describes this arrangement accurately today. If the entry
+// contract later forwards the device tree, this file is where `bootargs` would
+// be split, and the interface does not change --- which is the point of
+// answering the question rather than declining it.
+
+#include <openkal/env.h>
+
+extern "C" {
+
+kal_uintptr kal_env_arg_count(void) { return 0; }
+
+const char* kal_env_arg(kal_uintptr, kal_uintptr* len) {
+    if (len) *len = 0;
+    return nullptr;
+}
+
+kal_uintptr kal_env_var_count(void) { return 0; }
+
+const char* kal_env_var(const char*, kal_uintptr, kal_uintptr* value_len) {
+    if (value_len) *value_len = 0;
+    return nullptr;
+}
+
+const char* kal_env_var_at(kal_uintptr, kal_uintptr* name_len,
+                           const char** value, kal_uintptr* value_len) {
+    if (name_len)  *name_len  = 0;
+    if (value)     *value     = nullptr;
+    if (value_len) *value_len = 0;
+    return nullptr;
+}
+
+}  // extern "C"

src/kal.cpp

@@ -15,13 +15,20 @@
 //
 // WHAT IS IMPLEMENTED
 //
-// abort, stream and memory: openkal's core set. An implementation provides an
-// interface in whole or not at all, so the absence of fs, process, task, env
-// and time is not a deviation. `time` is deliberately absent even though SBI
-// has a timer extension: SBI can arm a timer interrupt, which is a mechanism
-// for a kernel rather than a clock a program can read, and reporting a clock
-// that does not advance would make every timed wait silently wrong — the
-// specification's own example of a simulation that disqualifies an interface.
+// This file: abort, stream and memory — openkal's core set. Beside it,
+// time.cpp and env.cpp. An implementation provides an interface in whole or not
+// at all, so the absence of fs, process and task is not a deviation: this
+// machine has no storage, no second image to start, and no scheduler, and
+// clause 6.2 says the remedy for an operation that cannot be provided is that
+// its absence be expressed by its absence rather than by a run-time refusal.
+//
+// ⚠️ `time` USED TO BE ON THAT LIST, WITH A REASON, AND THE REASON WAS WRONG.
+//
+// It read: SBI can arm a timer interrupt, which is a mechanism for a kernel
+// rather than a clock a program can read. The first half is true; the second
+// does not follow, because this architecture exposes `rdtime` to the program
+// independently of SBI. Measured under OpenSBI on QEMU's `virt` and it
+// advances. time.cpp records the measurement and what it cost to not take it.
 
 #include <openkal/abort.h>
 #include <openkal/memory.h>

src/time.cpp

@@ -0,0 +1,129 @@
+// openkal.time on the RISC-V Supervisor Binary Interface.
+//
+// ⚠️ THIS FILE EXISTS BECAUSE THE REASON RECORDED FOR ITS ABSENCE WAS WRONG.
+//
+// kal.cpp said, and said it as a design decision rather than as a note:
+//
+//     `time` is deliberately absent even though SBI has a timer extension:
+//     SBI can arm a timer interrupt, which is a mechanism for a kernel rather
+//     than a clock a program can read, and reporting a clock that does not
+//     advance would make every timed wait silently wrong.
+//
+// The first half is true and the second does not follow from it. SBI's timer
+// extension does arm an interrupt, and it is indeed a kernel's mechanism. But
+// this architecture ALSO exposes a counter directly to the program: `rdtime`
+// reads the `time` CSR, which the Zicntr extension defines and which firmware
+// makes readable below its own privilege level. Those are two different
+// facilities, and the absence of the first says nothing about the second.
+//
+// Measured 2026-08-23 under OpenSBI on QEMU's `virt`, from a program in
+// supervisor mode with no kernel beneath it:
+//
+//     t0=333572 t1=381292  ADVANCES
+//
+// ⭐ The lesson is the one the repository keeps relearning: a conclusion gets
+// rechecked and the reason written beside it does not. The reason above sat in
+// a comment for as long as the file existed, and the two minutes that refuted
+// it were available the whole time.
+//
+// WHAT IS AND IS NOT AVAILABLE HERE
+//
+// A monotonic count, precisely; a granularity, exactly; a sleep, by spinning on
+// the same counter, which on a machine with one execution context and no
+// scheduler is what sleeping is rather than a simulation of it.
+//
+// ⚠️ NOT a wall clock. SBI defines no facility for one, and no board fact would
+// supply it either --- a real-time clock is a device, and reading it is what a
+// board backend does. `KAL_TIME_PROP_WALL_AVAILABLE` is left clear, which is
+// the specification's own way of saying so: clause 6.2 makes availability of a
+// wall clock a PROPERTY rather than an interface, so `kal_time_wall` is present
+// and reports zero, and a program reads the word before it reads the clock.
+
+#include <openkal/time.h>
+
+#include "sbi.h"
+
+namespace {
+
+// ⚠️ THE ONE BOARD FACT THIS PACKAGE TAKES, AND IT TAKES IT AS AN INPUT.
+//
+// `rdtime` counts at a rate the architecture does not fix. The rate is
+// published in the device tree as `/cpus/timebase-frequency`, and this package
+// does not read one: the device tree is handed to the image in a register at
+// entry, the entry sequence belongs to the consumer rather than to this
+// package, and requiring every consumer to forward it would change a contract
+// that today is "jump here with a stack".
+//
+// So the rate is a build input, exactly as the heap size already is, and for
+// the same reason --- a figure that belongs to the machine is declared by the
+// project that knows which machine, rather than assumed by a package that does
+// not. The default is QEMU's `virt`, which is what the example runs on.
+//
+// ⚠️ A project on other hardware that leaves the default in place gets a clock
+// that advances at the wrong rate. That is a stated bound and not a hidden one:
+// the figure has a name, the name appears in the manifest, and this comment is
+// what a reader finds when they look for it.
+#ifndef OPENKAL_OPENSBI_TIMEBASE_HZ
+#  define OPENKAL_OPENSBI_TIMEBASE_HZ 10000000
+#endif
+
+constexpr kal_u64 kHz  = OPENKAL_OPENSBI_TIMEBASE_HZ;
+constexpr kal_u64 kNano = 1000000000ULL;
+
+inline kal_u64 ticks() {
+    kal_u64 v;
+    __asm__ __volatile__("rdtime %0" : "=r"(v));
+    return v;
+}
+
+// Split rather than `t * kNano / kHz`, which overflows a 64-bit product after
+// about eighteen seconds at ten megahertz. The split form is exact for every
+// value the counter can hold.
+inline kal_u64 to_ns(kal_u64 t) {
+    return (t / kHz) * kNano + (t % kHz) * kNano / kHz;
+}
+
+inline kal_u64 to_ticks(kal_u64 ns) {
+    return (ns / kNano) * kHz + (ns % kNano) * kHz / kNano;
+}
+
+}  // namespace
+
+extern "C" {
+
+kal_duration kal_time_monotonic(void) { return to_ns(ticks()); }
+
+// Present and reporting zero, which clause 6.2 provides for: the availability
+// of a wall clock is a property of the implementation, the property word says
+// this one has none, and a program that reads the word does not reach here.
+kal_duration kal_time_wall(void) { return 0; }
+
+// One tick, in nanoseconds, rounded up so that the figure is never reported as
+// finer than it is. At ten megahertz this is 100.
+kal_duration kal_time_monotonic_granularity(void) {
+    const kal_u64 g = kNano / kHz;
+    return g ? g : 1;
+}
+
+// ⚠️ Spinning, and that is the accurate implementation rather than a stand-in.
+//
+// Sleeping means giving the machine to something else until a time arrives. On
+// a machine with one execution context and nothing to give it to, the time
+// still has to arrive, and waiting for it on the same counter the caller would
+// read is precise to a tick. `KAL_TIME_PROP_SLEEP_PRECISE` is therefore set,
+// and it is set truthfully: there is no scheduler to overshoot.
+//
+// A `wfi` between polls would lower power, and it is not used, because it
+// requires an interrupt to be pending to wake from --- which requires SBI's
+// timer extension, which requires a trap handler, which this arrangement does
+// not have. The comment kal.cpp got wrong was about that extension; this is
+// where it would have been right.
+void kal_time_sleep(kal_duration ns) {
+    if (ns == 0) return;
+    const kal_u64 deadline = ticks() + to_ticks(ns);
+    while (ticks() < deadline) {}
+}
+
+const kal_uintptr kal_time_props = KAL_TIME_PROP_SLEEP_PRECISE;
+
+}  // extern "C"