diff --git a/FABRIC.md b/FABRIC.md index acd6e6a..ceae69e 100644 --- a/FABRIC.md +++ b/FABRIC.md @@ -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.6a–4.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