FABRIC.md: item 4.5c complete -- decided -O2, no LTO, no -DNDEBUG

-O2 over -O1/-Og: no optimization level has a verified track record here,
so pick the one that actually solves the motivating problem (4.4g's
fb_scroll_rows() stall needs real loop batching -Og doesn't reliably do)
and matches what both sibling Makefiles already default to.

No LTO yet: deliberately deferred, not rejected -- stacking a second risky
change (LTO, which CLAUDE.md already documents has broken this exact
codebase before) on top of a first-ever optimization pass would make any
4.5e failure ambiguous between two causes. Isolate them.

No -DNDEBUG: checked, not assumed. Zero runtime assert() calls exist
anywhere in the kernel build -- the two "assert(" hits found are a
_Static_assert pair (compile-time, ungated regardless) and a comment. The
freestanding assert.h shim is itself unconditional and ignores NDEBUG too.
Nothing for the flag to affect; copying it by habit would have been exactly
the cargo-culting this item warned against.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-11 10:12:36 -04:00
co-authored by Claude Sonnet 5
parent bc126c5a91
commit c5d46858fb
+34 -1
View File
@@ -5478,7 +5478,7 @@ document and committing that amendment as its own item.*
> `[Hera] ok>`. This proves no regression, not that optimization is safe yet — that's > `[Hera] ok>`. This proves no regression, not that optimization is safe yet — that's
> 4.5e's job once 4.5c/4.5d actually turn it on. > 4.5e's job once 4.5c/4.5d actually turn it on.
- [ ] **4.5c — Decide and record the target optimization flags.** Design-only, no code. - [x] **4.5c — Decide and record the target optimization flags.** Design-only, no code.
Depends on 4.5b (deciding flags before the known hazard is fixed is premature). Candidates Depends on 4.5b (deciding flags before the known hazard is fixed is premature). Candidates
to weigh, not yet chosen: matching the hosted/StarForth ladder's to weigh, not yet chosen: matching the hosted/StarForth ladder's
`-O2 -flto=auto -fuse-linker-plugin -DNDEBUG` (this repo's own `Makefile`'s `-O2 -flto=auto -fuse-linker-plugin -DNDEBUG` (this repo's own `Makefile`'s
@@ -5492,6 +5492,39 @@ document and committing that amendment as its own item.*
any Makefile edit. any Makefile edit.
*Refs:* 4.5, CLAUDE.md "Important: Linker Configuration". *Refs:* 4.5, CLAUDE.md "Important: Linker Configuration".
> **Decided 2026-08-11: `-O2`, no LTO, no `-DNDEBUG`.**
>
> **`-O2`, not `-O1`/`-Og`.** The kernel has no verified track record at any optimization
> level, so this is inherently a first attempt regardless of which level is picked — there's
> no "safer" level that avoids needing full re-verification. Given that, pick the level that
> actually solves the motivating problem: `-Og` is tuned for debuggability and does not
> reliably batch/vectorize loops the way `-O2` does, and the concrete case that started this
> (4.4g's `fb_scroll_rows()` stall) specifically needs real loop optimization, not just
> "some optimization." `-O2` is also what both sibling Makefiles (this repo's own vendored
> hosted `Makefile` and the standalone StarForth repo's) already use as their default
> `standard` target — precedented in this codebase, not a novel choice.
>
> **No LTO (`-flto`/`-fuse-linker-plugin`) yet.** Deliberately deferred, not rejected. LTO is
> a second, independent source of risk on top of a first-ever optimization pass, and
> CLAUDE.md already documents that this exact codebase has hit "ELF section name out of
> range" from plain `-flto` before (hence the hosted ladder's `-fuse-linker-plugin`
> workaround). Stacking both changes at once would make any 4.5e boot failure ambiguous
> between "-O2 semantics exposed a bug" and "LTO-specific linker issue" — isolate the two.
> If `-O2` alone verifies clean on all three architectures, LTO becomes its own
> follow-up item, not assumed here.
>
> **No `-DNDEBUG`.** Checked, not assumed: `grep -rn "assert(" src/starkernel/
> include/starkernel/` turns up exactly two files. `uefi_loader.c`'s two hits are
> `_Static_assert` (compile-time, layout checks on `BootInfo` offsets — unaffected by
> `NDEBUG` regardless, since `_Static_assert` isn't gated by it). `shim.c`'s one hit is a
> comment mentioning "assert()", not a call. There are zero runtime `assert()` call sites
> anywhere in the kernel build — `include/starkernel/freestanding/assert.h`'s shim
> (`#define assert(expr) ((void)(expr))`, itself unconditional and not gated on `NDEBUG`
> either) exists but has nothing to affect. Copying `-DNDEBUG` from the hosted ladder would
> be exactly the cargo-culting this item's own text warned against.
>
> **Chosen flags: `-O2`.** Added to `COMMON_CFLAGS` in 4.5d; no other new flags.
- [ ] **4.5d — Apply the chosen flags to `Makefile.starkernel`; build all three - [ ] **4.5d — Apply the chosen flags to `Makefile.starkernel`; build all three
architectures.** Depends on 4.5b (hazard fixed) and 4.5c (flags decided). Code change: architectures.** Depends on 4.5b (hazard fixed) and 4.5c (flags decided). Code change:
add the flags to `COMMON_CFLAGS` (shared across all three `ARCH_CFLAGS` blocks, so this is add the flags to `COMMON_CFLAGS` (shared across all three `ARCH_CFLAGS` blocks, so this is