From c5d46858fbc4271a9b833e97243bce427a4eadce Mon Sep 17 00:00:00 2001 From: Robert Allan James Date: Tue, 11 Aug 2026 10:12:36 -0400 Subject: [PATCH] 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 --- FABRIC.md | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/FABRIC.md b/FABRIC.md index 12cdbb2..af2005e 100644 --- a/FABRIC.md +++ b/FABRIC.md @@ -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