commit 2c77a938603088abd0c636df6758674e9a10e723
parent b11597609109b3ac2f2416582aaf1a2cdf9b4caf
Author: Ryan Sepassi <rsepassi@gmail.com>
Date: Tue, 16 Jun 2026 15:59:09 -0700
KERNEL.md: close out the remaining-work checklist
Phases 1-5 plus the adversarial-review fixes are landed. Mark every remaining
item done; record the --format elf delegation-to-objcopy/strip decision.
Diffstat:
| M | doc/plan/KERNEL.md | | | 108 | ++++++++++++++++++++++++++++++++++++++++--------------------------------------- |
1 file changed, 55 insertions(+), 53 deletions(-)
diff --git a/doc/plan/KERNEL.md b/doc/plan/KERNEL.md
@@ -374,68 +374,70 @@ The validation suite should stay targeted:
## Remaining work
-Phases 1-4 are substantially landed (flag parity, undefined-symbol policy,
-`--map`/`--symbols`, the linker-script parse surface, and `kit image
---format bin` / `objcopy -O binary`). The items below remain. Each is scoped to
-be picked up independently; file pointers name the most likely starting point.
+Phases 1-5 are landed. Phases 1-4 (flag parity, undefined-symbol policy,
+`--map`/`--symbols`, the linker-script parse surface, `kit image --format bin` /
+`objcopy -O binary`) plus all of the items below shipped; an adversarial review
+of the integrated diff found and fixed a further set of correctness bugs
+(coalesced-PT_LOAD bss/perms, `--defsym` ordering, exact `--section-start`
+addressing, NOLOAD relocations, memory-usage accounting, `--cref` imports, image
+metadata accuracy, and cc/ld report parity). The checklist below is closed out.
### Image formats beyond `bin` (Phase 5)
-- [ ] `--format rom`: fixed-size flat binary; require an explicit size or
- `--pad-to`, deterministic fill, fail when payload exceeds the size. Extend
- `src/obj/image.c` (the `KIT_IMAGE_FORMAT_*` switch is stubbed to `bin` only)
- and `driver/cmd/image.c`.
-- [ ] `--format sections`: concatenate `--section NAME` (repeatable) in declared
- order, reject missing sections, make address metadata explicit. Needs a
- section-iteration path alongside the existing segment path in `src/obj/image.c`.
-- [ ] `--format elf`: copy / normalize / strip / split-debug an existing linked
- ELF (only if cleaner than routing through `objcopy` + `strip`).
-- [ ] `--metadata FILE`: deterministic JSON sidecar (target, object format,
- entry, build id, selected segments/sections, source/output ranges, policy,
- warnings). `KitImageReport` already carries most facts.
-- [ ] Image selection/validation flags: `--only-section` / `--remove-section` /
- `--section`; `--strip-debug` / `--split-debug` / `--keep-symbols`;
- `--require-entry` / `--require-symbol` / `--require-section` / `--no-dynamic`.
-
-### Linker-script layout (parsed but not yet honored)
-
-These constructs parse today (`src/link/link_script.c`) but are silently dropped
-at layout (`src/link/link_layout.c`) — fixing each is a correctness item.
-
-- [ ] `NOLOAD` with PROGBITS content (force no file bytes / NOBITS segment;
- `sec.noload` is set but never read).
-- [ ] Inter-section `.` assignments (a `. = ALIGN(...)` written between output
- sections must apply at its textual position, not in the pre-section pass).
-- [ ] Multi-byte fills (`=0x12345678` / `FILL(...)` truncate to the low byte).
-- [ ] Multiple sections sharing one `:phdr`, and a section listing several
- phdrs (only `os->phdrs[0]` is honored; each section makes its own segment).
-- [ ] Recursion-depth guard in script expression parse/eval (deep `(((...)))`).
+- [x] `--format rom`: fixed-size flat binary; requires `--pad-to`, deterministic
+ fill, fails when payload exceeds the size.
+- [x] `--format sections`: concatenate `--section NAME` (repeatable) in declared
+ order, reject missing sections, address metadata made explicit (new
+ section-iteration path in `src/obj/image.c`).
+- [x] `--format elf`: evaluated and **deliberately delegated** to `objcopy` +
+ `strip` — a standalone implementation would duplicate the object-rewrite /
+ strip / split-debug machinery 1:1. The emitter returns a clear diagnostic
+ pointing to those tools rather than half-building a parallel path.
+- [x] `--metadata FILE`: deterministic JSON sidecar (target, object format,
+ entry, build id, selection, source/output ranges, policy, warnings); the
+ `selection` field mirrors the emitter's actual segment policy.
+- [x] Image selection/validation flags: `--only-section` / `--remove-section` /
+ `--section`; `--strip-debug` / `--split-debug` / `--keep-symbols` (gated to
+ `--format elf`); `--require-entry` / `--require-symbol` / `--require-section` /
+ `--no-dynamic`.
+
+### Linker-script layout (now honored at layout)
+
+- [x] `NOLOAD` with PROGBITS content (forces NOBITS / no file bytes; relocations
+ into a NOLOAD section are skipped, not written through a null buffer).
+- [x] Inter-section `.` assignments apply at their textual position (sequence-
+ stamped assignments interleaved with the section walk).
+- [x] Multi-byte fills (`=0x12345678` / `FILL(...)`) lay a repeating big-endian
+ pattern.
+- [x] Multiple sections sharing one `:phdr` coalesce into one PT_LOAD; a section
+ listing several phdrs appears under each (with R/W/X perms union).
+- [x] Recursion-depth guard in script expression parse and eval.
### Linker flags and policy
-- [ ] `--defsym name=expr` and `--section-start=.name=addr`.
-- [ ] `-Tdata` / `-Tbss` through `build-exe` and `ld` (currently rejected).
-- [ ] `--orphan-handling=place|warn|error|discard` and `--fatal-warnings`.
-- [ ] `--cref FILE` and `--print-memory-usage` (the latter once `MEMORY`
- regions feed it).
-- [ ] Map completeness: add LMA, discarded sections, and unresolved symbols to
- `--map` (`src/api/link.c`); normalize input paths to avoid absolute paths
- leaking into the map and breaking byte-identity.
+- [x] `--defsym name=expr` (can now satisfy an otherwise-undefined reference) and
+ `--section-start=.name=addr` (lands at the exact requested vaddr).
+- [x] `-Tdata` / `-Tbss` through `build-exe` and `ld`.
+- [x] `--orphan-handling=place|warn|error|discard` and `--fatal-warnings`.
+- [x] `--cref FILE` (includes imported/undefined symbols) and
+ `--print-memory-usage` (per-`MEMORY`-region usage, overflow-safe for high-half
+ regions).
+- [x] Map completeness: LMA, discarded sections, and unresolved symbols in
+ `--map`; input paths normalized to basenames (no absolute-path leak).
### Freestanding strict validation (Phase 2 gap)
-DSO-input rejection exists in `ld` only. Extend strict-by-default freestanding
-diagnostics to cover the rest, in both `ld` and `build-exe`:
-
-- [ ] Reject dynamic-interpreter paths, dynamic sections, and PLT/GOT imports.
-- [ ] Reject cross-input target / object-format mismatches.
-- [ ] Surface the policy through `build-exe`, not just `ld`.
+- [x] Reject dynamic-interpreter paths, dynamic sections, and PLT/GOT imports.
+- [x] Reject cross-input target / object-format mismatches.
+- [x] Policy surfaced through `build-exe`, not just `ld` (both honor the same
+ `freestanding_strict` trigger).
### Tests and fixtures
-- [ ] Per-arch kernel-link fixtures for `aarch64-none-elf`, `riscv64-none-elf`,
- and `riscv32-none-elf` (coverage is x64-centric today).
-- [ ] Byte-golden `--map` / `--symbols` fixtures (current checks are
- `grep`-assertions in `test/buildcmds/run.sh`, not reproducibility goldens).
-- [ ] Negative tests: region overflow, discarded sections, dynamic artifacts,
- and a `NOLOAD`-with-PROGBITS layout case.
+- [x] Per-arch kernel-link fixtures for `x86_64-none-elf`, `aarch64-none-elf`,
+ `riscv64-none-elf`, and `riscv32-none-elf` (build → map/symbols → image →
+ validate, reproducible).
+- [x] Byte-golden `--map` / `--symbols` fixtures (deterministic, committed
+ goldens for a pinned link).
+- [x] Negative tests: region overflow, discarded sections, dynamic artifacts,
+ NOLOAD-with-PROGBITS, and cross-arch freestanding rejection.
