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:
co-authored by
Claude Sonnet 5
parent
b42308762b
commit
2e22303ef1
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user