FABRIC.md: scope item 4.6 into 4.6a-4.6f -- audit, fix, decide flags, build, verify, retry 4.4g

Scoping only, per Captain Bob's explicit instruction -- nothing implemented.
Breaks the -O0-kernel finding into six sequential, individually-committable
items matching this document's §25.0 rule-1 discipline (same treatment 4.4
itself got before 4.4a onward):

4.6a full ISR-global volatile audit (investigation only), 4.6b fix whatever
4.6a finds (starting from the one already-confirmed TimeTrustState.ticks
hazard), 4.6c decide the actual -O flags and record the reasoning before
touching the Makefile, 4.6d apply them and get a clean three-arch build,
4.6e the real three-arch acceptance boot (a kernel that has only ever run
at -O0 has no track record at any other level), 4.6f retry 4.4g's reorder
now that optimization exists to make it viable.

Also flagged, not scoped: the ACL-RWT DoE campaign's overhead numbers were
all measured at -O0; nobody has asked whether they still hold once the
kernel builds differently.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-11 09:48:20 -04:00
co-authored by Claude Sonnet 5
parent b42308762b
commit 2e22303ef1
+75 -10
View File
@@ -5388,18 +5388,83 @@ document and committing that amendment as its own item.*
is shared. This is a real, specific, isolated bug (one field, not a sprawling unknown), not
a hypothetical one — but it is unaudited, and enabling `-O2` before fixing it would ship a
live regression.
**Scope, not yet started.** Two things needed before optimization can be turned on: (1) fix
`TimeTrustState.ticks` specifically (mark `volatile`, or move it into the existing
`g_pending_counter`-style handoff), and (2) do a fuller sweep for any other
ISR-written/mainline-read state that isn't already `volatile` — the one confirmed instance
came from investigating a single busy-wait loop found by accident (4.4g), not from an
exhaustive audit, so absence of further evidence here is not evidence of absence. Then
three-arch re-verification of the whole boot sequence at whatever `-O` level is chosen,
since a kernel that has only ever been built and accepted at `-O0` has no track record at
any other optimization level. Not started; report per CLAUDE.md's "identify, don't fix
unprompted" rule until Captain Bob scopes and authorizes the actual work.
**Not scheduled as one item — broken out below (4.6a4.6f) per §25.0 rule 1, same treatment
as 4.4's own design-only lock before 4.4a onward.** Nothing below is started; this is
scoping only, per Captain Bob's explicit instruction 2026-08-11.
*Refs:* discovered via 4.4g; independent of Console work.
- [ ] **4.6a — Full ISR/interrupt-context global-state audit, all three architectures.**
Investigation only, no code change. For each architecture, enumerate every vector actually
wired to a handler (amd64: IDT/APIC vectors in `arch/amd64/interrupts.c`; aarch64: GIC
vectors in `arch/aarch64/interrupts.c`; riscv64: PLIC/trap causes in
`arch/riscv64/interrupts.c`), list every global or `static` variable each handler touches
either directly or through a called function (e.g. `heartbeat_tick()`
`TimeTrustState.ticks`), and check each one's declaration for `volatile`. The one confirmed
hazard (`TimeTrustState.ticks`, `timer.h:90`) came from investigating a single busy-wait
loop found by accident while working 4.4g — not from an exhaustive pass — so this item
exists precisely because absence of further evidence so far is not evidence of absence.
*Done when:* a written inventory exists here (or in a linked scratch doc) covering every
handler on all three architectures, with every non-`volatile` ISR-touched global listed by
file:line, or an explicit "none found" recorded per architecture.
*Refs:* 4.6.
- [ ] **4.6b — Fix every hazard 4.6a found.** Depends on 4.6a. Code fix, no optimization
flags touched yet. `TimeTrustState.ticks` is the one already-confirmed instance — mark it
`volatile`, or fold it into the existing `g_pending_counter`/`g_pending_valid`-style
ISR→mainline handoff pattern already used elsewhere in `heartbeat.c`, whichever fits the
finding better once 4.6a's full inventory is in hand. Any further hazards 4.6a surfaces get
fixed here too, not deferred.
*Done when:* every hazard from 4.6a's inventory is fixed; three-arch boot still clean at
the unchanged `-O0` (this item changes correctness under future optimization, not present
behavior, so a clean boot here proves no regression was introduced, not that optimization
is now safe).
*Refs:* 4.6, 4.6a.
- [ ] **4.6c — Decide and record the target optimization flags.** Design-only, no code.
Depends on 4.6b (deciding flags before the known hazard is fixed is premature). Candidates
to weigh, not yet chosen: matching the hosted/StarForth ladder's
`-O2 -flto=auto -fuse-linker-plugin -DNDEBUG` (this repo's own `Makefile`'s
`TARGET_CFLAGS_standard`, and CLAUDE.md already documents that plain `-flto` without
`-fuse-linker-plugin` causes "ELF section name out of range" errors on a codebase this
size — the same risk applies here if LTO is chosen) versus a more conservative `-O1` or
`-Og` for kernel debuggability versus plain `-O2` without LTO as a lower-risk first step.
Also decide whether `-DNDEBUG` is appropriate here — check whether the kernel build path
actually uses `assert()` anywhere before copying that flag by habit from the hosted ladder.
*Done when:* an exact flag set is chosen and written down here with the reasoning, before
any Makefile edit.
*Refs:* 4.6, CLAUDE.md "Important: Linker Configuration".
- [ ] **4.6d — Apply the chosen flags to `Makefile.starkernel`; build all three
architectures.** Depends on 4.6b (hazard fixed) and 4.6c (flags decided). Code change:
add the flags to `COMMON_CFLAGS` (shared across all three `ARCH_CFLAGS` blocks, so this is
one change, not three). Optimization can surface warnings `-O0` never triggers (e.g.
`-Wmaybe-uninitialized`) under the existing `-Wall -Werror -Wextra` standard — budget time
to fix those, not to weaken the warning set.
*Done when:* all three architectures build with zero warnings under the existing
`-Wall -Werror -Wextra` standard.
*Refs:* 4.6, 4.6c.
- [ ] **4.6e — Three-arch acceptance boot with optimization enabled.** Depends on 4.6d. This
is the actual gate, per CLAUDE.md's non-negotiable acceptance criteria — a kernel that has
only ever been built and accepted at `-O0` has no track record at any other optimization
level, so this is a full fresh verification, not a formality.
*Done when:* all three architectures boot clean to `ok>`/`zuse)ok>`, POST's dictionary-hash
parity check still passes, logs captured in `logs/` per CLAUDE.md.
*Refs:* 4.6, CLAUDE.md acceptance criteria.
- [ ] **4.6f — Retry the 4.4g `console_fb_init()` reorder now that optimization is live.**
Depends on 4.6e. This is the original motivating case: both attempts this session (bare,
and with the `fb_scroll_rows()` volatile fix alone) stalled boot indefinitely at `-O0`.
*Done when:* the reorder from 4.4g completes in a reasonable time (no multi-minute stall)
on a three-arch boot, and an amd64 screendump shows the fuller boot transcript that was
4.4g's whole point.
*Refs:* 4.4g, 4.6.
> **Aside, not a task:** the ACL-RWT DoE campaign's overhead numbers (CLAUDE.md, "measured
> overhead +0.0054%+0.0088%") were all measured at `-O0`. Nobody has asked whether those
> numbers still hold, or even remain comparable, once the kernel is built at a different
> optimization level. Not scoped here — flagging so it isn't lost if 4.6 ever lands.
---
## 25.6 Phase 5 — Verification and measurement