riscv64: finish SBI timer verification and clean up stale timer docs

Punch list §25 item 0.3 complete.

The functional work (FDT reader, `time` CSR switch, SBI TIME extension
arm/re-arm, sie.STIE) was committed separately by Captain Bob as accd79f,
honestly labeled "NOT complete." This finishes it: stale documentation
cleanup, then rigorous verification against the item's literal acceptance
text, which the prior commit had not yet done.

Doc cleanup: every remaining reference to `rdcycle` / "assumed 1 GHz" in
riscv64/timer.c and riscv64/apic.c rewritten to describe the actual `time`
CSR / SBI-armed behavior. Caught and corrected my own arithmetic error in
the process: a draft claimed the ns-overflow bound improved to "~58 years"
under the new counter; direct computation shows the bound is actually
~3.26 days (2^48 ns) and is *frequency-independent* -- s_ns_per_tick and
tick rate scale inversely and cancel. Verified with a script before
writing the final comment, not asserted.

Verification, since "boots to prompt" was not sufficient for this item's
acceptance ("heartbeat_ticks() advances ... within measurement noise"):

- No FORTH word exposes heartbeat_ticks() to the REPL, and adding one would
  be a new primitive outside this item's scope. GDB-over-QEMU-stub reads of
  the static counter failed ("Cannot access memory"), likely a virtual-vs-
  runtime address mismatch; abandoned rather than debugged further, since a
  better instrument was available.
- QEMU's own `-d int` trap tracing (independent of all guest code) shows
  2,797 `cause:5 desc=s_timer` interrupts delivered by the time boot reaches
  the prompt, and the interleaved `desc=supervisor_ecall` entries are exactly
  the SBI set_timer calls from riscv64_timer_rearm(), confirming the full
  interrupt -> handler -> re-arm -> SBI loop.
- Measured rate over a real 10.127 s window: 1,013 further interrupts,
  100.028 Hz observed against 100 Hz configured -- 0.03% deviation. The
  sustained, non-decaying rate is itself proof the one-shot re-arm succeeds
  on every cycle, not just the first.
- Confirmed regression-free on amd64 and aarch64 too: uefi_loader.c, uefi.h,
  boot_info_offsets.h and the new fdt.c/fdt.h are shared across all three
  builds (amd64 also consumes the offset constants via kernel_entry.S), so
  all three were rebuilt and booted. Identical dict_hash
  0x3d4e1daf289da94f on all three, matching the item 0.1/0.2 baseline.

Reported, not fixed, per rule 3:
- DOE_INJECT=1's EXEC-DOE now fails as "UNKNOWN WORD" against the pruned
  Hera-alone capsule -- doe.4th was never loaded by init.4th even before
  item 0.1's prune, so this is a pre-existing gap the prune surfaced, not a
  new defect. Discovered while chasing why a 200-rep injected DoE run
  produced no new CSV rows after 25 minutes; it had failed in the first
  millisecond, not run the whole time.
- repl.c's own comment claims a "Heartbeat: N ticks" diagnostic prints to
  the serial log; no such print exists anywhere in the tree.
- riscv64/arch.c's arch_read_timestamp() still uses rdcycle with a stale
  1 GHz comment, but it has zero callers on this architecture -- dead code,
  left alone.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-03 18:23:37 -04:00
co-authored by Claude Sonnet 5
parent accd79fc70
commit 5784d8a1a8
10 changed files with 31347 additions and 42 deletions
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff