Reorganize source tree: kernel/, v3/, v4/ split and board infrastructure
Source tree reorganization: - Move StarForth v3 engine to v3/ (src/, include/, Makefile) - Move kernel to kernel/ (src/, include/, linker/, Makefile) - Create v4/ skeleton for F18-ISA golden model (DECOMPOSITION.md, JUSTIFICATION.md) - Move FABRIC-0..4.md to docs/fabric/ - Move ONTOLOGY.md and ROADMAP.md to docs/ Board infrastructure: - Add boards/ser5/, boards/raspi/, boards/milkv/, boards/zynq7020/ - Each board has board.mk (ISA, CPU flags, boot recipe) and README.md - Root Makefile becomes thin dispatcher: boot_image, all, clean, docs take TARGET - make boot_image TARGET=SER5|RASPI|MILKV builds one GPT/MBR image per board - ZYNQ7020 target exists but stops with clear error (ARMv7 port not built yet) - scripts/mkdiskimage.sh builds disk images for all boards Docs pipeline: - docs/book/ with LaTeX master (main.tex) and Makefile - pandoc converts Markdown to LaTeX at build time - Two Lua filters: table-widths.lua (wide tables wrap), code-breaks.lua (inline code breaks) - make docs builds single PDF (754 pages, 0 missing characters) - make docs TARGET=<board> adds board appendix - build/docs/<book|board>/meta.tex stamps git commit into PDF Bug fixes: - 42 include paths that only worked by accident now use correct relative paths - clang-18 hardcode replaced with configurable CC variable (fixed aarch64 build) - Pi 5: kernel_2712.img linked at 0x80000, .bss zeroed, memory reserved - Doxyfile, .clang-tidy, README.md, Kconfig paths updated Verified: - Hosted v3 build passes 1012 tests, 0 failures - SER5 image boots in QEMU (OVMF), POST passes, K exact (65536 = Q48_ONE) - Milk-V image boots in QEMU (OpenSBI + U-Boot + bootefi), POST passes - make clean TARGET=<board> removes only that board and its ISA objects - make all builds all boards, hosted v3, and docs in one run Co-authored-by: Junie <junie@jetbrains.com>
This commit is contained in:
rajames
+20
-20
@@ -224,43 +224,43 @@ changes with any new C word registration).
|
||||
|
||||
```bash
|
||||
# Build kernel for a given architecture (amd64 default)
|
||||
make -f Makefile.starkernel ARCH=amd64
|
||||
make -f Makefile.starkernel ARCH=aarch64
|
||||
make -f Makefile.starkernel ARCH=riscv64
|
||||
make -f kernel/Makefile ARCH=amd64
|
||||
make -f kernel/Makefile ARCH=aarch64
|
||||
make -f kernel/Makefile ARCH=riscv64
|
||||
|
||||
# Run in QEMU with OVMF
|
||||
make -f Makefile.starkernel qemu
|
||||
make -f Makefile.starkernel ARCH=aarch64 qemu
|
||||
make -f Makefile.starkernel ARCH=riscv64 qemu
|
||||
make -f kernel/Makefile qemu
|
||||
make -f kernel/Makefile ARCH=aarch64 qemu
|
||||
make -f kernel/Makefile ARCH=riscv64 qemu
|
||||
|
||||
# Clean
|
||||
make -f Makefile.starkernel clean
|
||||
make -f kernel/Makefile clean
|
||||
```
|
||||
|
||||
Output: `build/<arch>/kernel/starkernel_loader.efi` + `build/<arch>/kernel/starkernel_kernel.elf`.
|
||||
|
||||
Two independently tracked version strings flow into the generated `include/version.h`:
|
||||
`VERSION` (`Makefile.starkernel` — the embedded StarForth engine version, currently `3.1.0`;
|
||||
`VERSION` (`kernel/Makefile` — the embedded StarForth engine version, currently `3.1.0`;
|
||||
note this does **not** auto-sync with the standalone StarForth repo's own version) and
|
||||
`LITHOS_VERSION` (`Makefile.starkernel` — the kernel version, currently **`2.0.0`**;
|
||||
`LITHOS_VERSION` (`kernel/Makefile` — the kernel version, currently **`2.0.0`**;
|
||||
corrected 2026-09-19 — this file said `2.0.1`, but `FABRIC-3.md` §I.2 rolled it back to
|
||||
`2.0.0` on 2026-09-04 because `2.0.1` names the SER5 hardware-track line and claims hardware
|
||||
progress not yet verified. The versioning policy is **semantic, not sequential** — see the
|
||||
roadmap table in `Makefile.starkernel` before choosing any version).
|
||||
roadmap table in `kernel/Makefile` before choosing any version).
|
||||
|
||||
### Build configuration (Kconfig — real, wired, not vestigial)
|
||||
|
||||
Every kernel-only knob (`STARFORTH_ENABLE_VM`, `PARITY_MODE`, the shared physics/heartbeat
|
||||
family, etc.) is an optional Kconfig symbol defined across `Kconfig`, `Kconfig.arch`,
|
||||
`Kconfig.heartbeat`, `Kconfig.kernel`, `Kconfig.physics`, `Kconfig.variant` (~40 symbols
|
||||
total). `Makefile.starkernel` pulls its defaults from this system via a `kconfig_bool(...)`
|
||||
total). `kernel/Makefile` pulls its defaults from this system via a `kconfig_bool(...)`
|
||||
mechanism — e.g. `STARFORTH_ENABLE_VM` defaults to **1** (confirmed at
|
||||
`Makefile.starkernel:61`), meaning a plain `make -f Makefile.starkernel` already builds with
|
||||
`kernel/Makefile:61`), meaning a plain `make -f kernel/Makefile` already builds with
|
||||
VM + capsule-birth + ACL active. A bare invocation uses the defaults it always has:
|
||||
|
||||
```bash
|
||||
make -f Makefile.starkernel ARCH=amd64 menuconfig
|
||||
make -f Makefile.starkernel ARCH=amd64 kernel_amd64_defconfig
|
||||
make -f kernel/Makefile ARCH=amd64 menuconfig
|
||||
make -f kernel/Makefile ARCH=amd64 kernel_amd64_defconfig
|
||||
```
|
||||
|
||||
### Hosted VM (vendored, for local sanity only)
|
||||
@@ -277,7 +277,7 @@ StarForth repo) were removed 2026-08-15 — they referenced
|
||||
in the actual generated `include/version.h` (which only has `STARFORTH_VERSION`,
|
||||
`STARFORTH_ARCH`, `STARFORTH_TARGET`, `STARFORTH_TIMESTAMP`, `STARFORTH_VERSION_FULL`,
|
||||
`LITHOS_VERSION`, `LITHOS_VERSION_STR`), so they could never have worked. Bump versions by hand-editing the `VERSION`/
|
||||
`LITHOS_VERSION` variables in `Makefile.starkernel` instead. Report the broken targets if
|
||||
`LITHOS_VERSION` variables in `kernel/Makefile` instead. Report the broken targets if
|
||||
asked, don't silently fix them.
|
||||
|
||||
### Important: Linker Configuration
|
||||
@@ -298,9 +298,9 @@ The vendored hosted `make` build (above) is NEVER used to validate kernel change
|
||||
|
||||
```bash
|
||||
# Run in this exact order for every kernel change:
|
||||
make -f Makefile.starkernel ARCH=amd64 clean qemu
|
||||
make -f Makefile.starkernel ARCH=aarch64 clean qemu
|
||||
make -f Makefile.starkernel ARCH=riscv64 clean qemu
|
||||
make -f kernel/Makefile ARCH=amd64 clean qemu
|
||||
make -f kernel/Makefile ARCH=aarch64 clean qemu
|
||||
make -f kernel/Makefile ARCH=riscv64 clean qemu
|
||||
```
|
||||
|
||||
**QEMU rule — non-negotiable:** Only ONE QEMU instance may run at a time, always in the
|
||||
@@ -475,7 +475,7 @@ listed in `proof/ROOT` (corrected 2026-09-19; this file said 23, and `proof/COVE
|
||||
said 52 all along). **Read `proof/COVERAGE.md` first**: its stated goal is not a green build but
|
||||
"identify precisely what cannot be proven and why — the boundary between 'formally verified'
|
||||
and 'not, for this specific reason'." Run `isabelle build -D proof/`
|
||||
directly; neither `Makefile` nor `Makefile.starkernel` in this repo defines an
|
||||
directly; neither `Makefile` nor `kernel/Makefile` in this repo defines an
|
||||
`isabelle-build`/`isabelle-check` target (unlike the standalone StarForth repo, which has a
|
||||
broken one — this repo simply doesn't have the target at all, so there's nothing to
|
||||
mistakenly invoke).
|
||||
@@ -495,7 +495,7 @@ status for kernel work.
|
||||
|
||||
- **Strict ANSI C99** — No GNU extensions, no C++ features
|
||||
- **Zero warnings target, with four explicit exceptions — corrected 2026-08-18, previous
|
||||
claim was wrong.** Build with `-Wall -Wextra -Werror`, but `Makefile.starkernel` carries
|
||||
claim was wrong.** Build with `-Wall -Wextra -Werror`, but `kernel/Makefile` carries
|
||||
`-Wno-error=unused-parameter -Wno-error=shift-negative-value -Wno-error=sign-compare
|
||||
-Wno-error=missing-field-initializers` — those four classes are enabled (still visible as
|
||||
warnings) but deliberately downgraded from fatal, everything else is. The previous version
|
||||
|
||||
Reference in New Issue
Block a user