commit c3b3b5777cd40a0ec300f0674e31c5e843be1b1a
parent 6d58111015601dfee004536777e545c663079046
Author: Ryan Sepassi <rsepassi@gmail.com>
Date: Tue, 16 Jun 2026 14:02:05 -0700
KERNEL.md: add farmable checklist of remaining work
Record what's left after the first-pass landing (image formats beyond bin,
unhonored linker-script layout constructs, remaining linker flags, the
freestanding strict-validation gap, and missing per-arch/golden tests) as
independently-scoped checklist items with starting-point file pointers.
Diffstat:
| M | doc/plan/KERNEL.md | | | 68 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 68 insertions(+), 0 deletions(-)
diff --git a/doc/plan/KERNEL.md b/doc/plan/KERNEL.md
@@ -371,3 +371,71 @@ The validation suite should stay targeted:
- one image-conversion fixture per image format and hole policy,
- negative tests for unresolved symbols, region overflow, dynamic artifacts, and
overlapping image ranges.
+
+## 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.
+
+### 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 `(((...)))`).
+
+### 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.
+
+### 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`.
+
+### 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.
