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
> 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
to weigh, not yet chosen: matching the hosted/StarForth ladder'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.
*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
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