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
@@ -0,0 +1,29 @@
|
||||
# boards/
|
||||
|
||||
One directory per physical target. `make boot_image TARGET=<NAME>` (repo root) maps the
|
||||
name to a directory here, reads its `board.mk`, and builds the single file that goes on
|
||||
that board's boot medium into `build/boards/<board>/`.
|
||||
|
||||
| TARGET | Directory | ISA | Boot path | Image |
|
||||
|---|---|---|---|---|
|
||||
| `SER5` | `ser5/` | amd64 | UEFI firmware, removable-media path | GPT + FAT32 ESP: `EFI/BOOT/BOOTX64.EFI` |
|
||||
| `RASPI` | `raspi/` | aarch64 | Pi 5 EEPROM firmware, native | MBR + FAT32: `config.txt`, `kernel_2712.img`, `bcm2712-rpi-5-b.dtb` |
|
||||
| `MILKV` | `milkv/` | riscv64 | SPI-flash U-Boot + OpenSBI, `bootefi` | GPT + FAT32 ESP: `EFI/BOOT/BOOTRISCV64.EFI` |
|
||||
| `ZYNQ7020` | `zynq7020/` | armv7 | BootROM, `BOOT.BIN`, U-Boot | not yet: needs `kernel/src/arch/armv7` |
|
||||
|
||||
`board.mk` sets:
|
||||
|
||||
- `BOARD_DESC`: one-line description (`make boards`)
|
||||
- `BOARD_ARCH`: kernel ISA (`kernel/src/arch/<arch>`)
|
||||
- `BOARD_BOOT`: image recipe in `kernel/Makefile` (`uefi-esp`, `rpi-native`, ...)
|
||||
- `BOARD_IMAGE`: output file name
|
||||
|
||||
Disk images are assembled by `scripts/mkdiskimage.sh`, which needs no root access and no loop
|
||||
devices. `KERNEL_ARGS="..."` is written as `starforth.cfg` (UEFI boards) or `cmdline.txt`
|
||||
(Pi 5, where the firmware copies it into `/chosen/bootargs`). `BOOT_IMAGE_SIZE_MIB` sets the
|
||||
image size; the default is 128.
|
||||
|
||||
Hardware status: none of these images has been booted on real silicon from this build. The
|
||||
SER5 image has been booted in QEMU (q35 + OVMF, from its own disk) through POST. The Pi 5
|
||||
native path (`raspi/README.md`) and the JH7110 peripherals have still only been checked by
|
||||
compiling.
|
||||
@@ -0,0 +1,30 @@
|
||||
# Milk-V Mars boot media
|
||||
|
||||
`make boot_image TARGET=MILKV` builds `build/boards/milkv/lithos-milkv.img`: a GPT disk with one
|
||||
FAT32 EFI System Partition. Write it to an SD card with `dd`. The partition holds:
|
||||
|
||||
- `EFI/BOOT/BOOTRISCV64.EFI`: the riscv64 monolithic loader, the same one QEMU boots.
|
||||
- `startup.nsh`: for a UEFI shell, if one is used.
|
||||
- `starforth.cfg`: only present when `KERNEL_ARGS="..."` is given.
|
||||
|
||||
The board's own SPI-flash U-Boot, with OpenSBI underneath, finds the loader through its standard
|
||||
`bootefi` scan of the removable-media path. U-Boot passes its devicetree to the loader through the
|
||||
EFI configuration table.
|
||||
|
||||
Status: booted in QEMU through the same chain the board uses: OpenSBI, then U-Boot
|
||||
`qemu-riscv64_smode`, then `bootefi` from this image's ESP, then the loader and the kernel. POST
|
||||
passed, Stadium conservation was exact (resident 43691 + reservoir 21845 = 65536 = `Q48_ONE`), and
|
||||
Hestia and Artemis came up. Not yet booted on the Mars itself. The JH7110 peripherals
|
||||
(framebuffer, RNG) have only been checked by compiling.
|
||||
|
||||
To repeat the QEMU boot (`qemu-system-riscv64` is in Ubuntu 26.04's `qemu-system-riscv` package;
|
||||
OpenSBI and U-Boot come from `opensbi` and `u-boot-qemu`). Use a copy, because the kernel writes
|
||||
to its disk:
|
||||
|
||||
```
|
||||
cp build/boards/milkv/lithos-milkv.img /tmp/mv.img
|
||||
qemu-system-riscv64 -machine virt -cpu rv64 -m 2048 -nographic \
|
||||
-bios /usr/lib/riscv64-linux-gnu/opensbi/generic/fw_dynamic.bin \
|
||||
-kernel /usr/lib/u-boot/qemu-riscv64_smode/u-boot.bin \
|
||||
-drive if=none,format=raw,file=/tmp/mv.img,id=d0 -device virtio-blk-device,drive=d0
|
||||
```
|
||||
@@ -0,0 +1,11 @@
|
||||
# boards/milkv/board.mk -- Milk-V Mars (StarFive JH7110, SiFive U74, RV64GC).
|
||||
#
|
||||
# The board's own SPI-flash U-Boot (OpenSBI underneath) runs the EFI
|
||||
# application through its standard distro/bootefi scan: the SD card is a GPT
|
||||
# disk with one FAT32 EFI System Partition holding EFI/BOOT/BOOTRISCV64.EFI,
|
||||
# the same riscv64 monolithic loader QEMU boots. U-Boot passes its own
|
||||
# devicetree through the EFI configuration table.
|
||||
BOARD_DESC := Milk-V Mars (StarFive JH7110, RV64GC, U-Boot bootefi)
|
||||
BOARD_ARCH := riscv64
|
||||
BOARD_BOOT := uefi-esp
|
||||
BOARD_IMAGE := lithos-milkv.img
|
||||
@@ -0,0 +1,20 @@
|
||||
# Raspberry Pi 5 native boot media
|
||||
|
||||
`make boot_image TARGET=RASPI` builds `build/boards/raspi/lithos-raspi.img`: an MBR disk
|
||||
with one FAT32 (LBA) partition. Write it to an SD card with `dd`. The partition holds:
|
||||
|
||||
- `config.txt`: checked in here (FABRIC-3.md §IV.3 item 6). It pins `kernel_address=0x80000`
|
||||
because Pi 5 firmware loads `kernel_2712.img` at 0x200000 by default.
|
||||
- `kernel_2712.img`: the aarch64 kernel objects relinked at 0x80000 by
|
||||
`kernel/linker/starkernel-native-rpi5.ld`, entered at `rpi5_native_start`
|
||||
(`kernel/src/arch/aarch64/native_rpi5_entry.S`, which zeroes `.bss` first), and flattened
|
||||
with `objcopy -O binary`.
|
||||
- `bcm2712-rpi-5-b.dtb`: the Raspberry Pi firmware's own stock DTB. It is not built by this
|
||||
project; it is fetched once from the firmware release pinned in `board.mk`
|
||||
(`RPI_FIRMWARE_TAG`) into `build/cache/`. To use a local copy, pass `RPI5_DTB=/path/to/dtb`.
|
||||
- `cmdline.txt`: only present when `KERNEL_ARGS="..."` is given. The firmware copies it into
|
||||
`/chosen/bootargs`, which `rpi5_native_boot()` parses.
|
||||
|
||||
Not yet verified on hardware. The native path still assumes everything `kernel_main()`
|
||||
needs after a UEFI handoff. The firmware enters at EL2 with the MMU off, which is not what
|
||||
UEFI hands over, and that difference has not been exercised.
|
||||
@@ -0,0 +1,18 @@
|
||||
# boards/raspi/board.mk -- Raspberry Pi 5 (BCM2712, Cortex-A76, aarch64).
|
||||
#
|
||||
# Native firmware boot, no UEFI (FABRIC-3.md §IV): the Pi 5 bootloader
|
||||
# lives in EEPROM and reads config.txt, kernel_2712.img and the board DTB
|
||||
# from the first FAT partition of the SD card. kernel_2712.img is the
|
||||
# aarch64 kernel relinked at 0x80000 (kernel/linker/starkernel-native-rpi5.ld)
|
||||
# and flattened to a raw binary.
|
||||
#
|
||||
# The DTB is the Raspberry Pi firmware's own stock file, not built here. It
|
||||
# is fetched once from the pinned firmware release below into build/cache/
|
||||
# unless RPI5_DTB points at a local copy.
|
||||
BOARD_DESC := Raspberry Pi 5 (BCM2712, Cortex-A76, native firmware boot)
|
||||
BOARD_ARCH := aarch64
|
||||
BOARD_BOOT := rpi-native
|
||||
BOARD_IMAGE := lithos-raspi.img
|
||||
RPI_FIRMWARE_TAG ?= 1.20260915
|
||||
RPI5_DTB_URL ?= https://raw.githubusercontent.com/raspberrypi/firmware/$(RPI_FIRMWARE_TAG)/boot/bcm2712-rpi-5-b.dtb
|
||||
RPI5_DTB ?= build/cache/raspi-$(RPI_FIRMWARE_TAG)/bcm2712-rpi-5-b.dtb
|
||||
@@ -0,0 +1,69 @@
|
||||
# LithosAnanke native (non-UEFI) boot config for Raspberry Pi 5 (BCM2712).
|
||||
# FABRIC-3.md §IV.3 item 6 -- see that section's own doc comment for the
|
||||
# research trail behind each line (confirmed against raspberrypi.com's
|
||||
# current config.txt reference and a real, working Pi 5 bare-metal
|
||||
# project's own checked-in config.txt, not assumed from general Pi
|
||||
# knowledge).
|
||||
|
||||
# Load our own kernel image directly -- no UEFI, no Linux. kernel_2712.img
|
||||
# is the real filename Pi 5/500/CM5 firmware looks for first (its own
|
||||
# 16K-page-size build); naming our own image this exactly, rather than
|
||||
# falling back to kernel8.img, removes any ambiguity about which file the
|
||||
# firmware picks up.
|
||||
kernel=kernel_2712.img
|
||||
|
||||
# Pin the load address to the one the image is linked at
|
||||
# (kernel/linker/starkernel-native-rpi5.ld). Pi 5 firmware's own default
|
||||
# for kernel_2712.img is 0x200000, not the classic 0x80000 -- leaving it
|
||||
# implicit would load a 0x80000-linked flat image 1.5 MiB away from where
|
||||
# every absolute address in it points.
|
||||
kernel_address=0x80000
|
||||
|
||||
# Disable the firmware's Linux-compatible-image sanity check. Without
|
||||
# this, official docs describe it as checking for "a compatible Device
|
||||
# Tree file before attempting to boot" and warn that "older non-compatible
|
||||
# kernels would be loaded and then hang" -- documented specifically as the
|
||||
# bare-metal-development escape hatch. One real working Pi 5 bare-metal
|
||||
# project's own config.txt does NOT set this and still boots, so it may
|
||||
# not be strictly required for every non-Linux image; kept here anyway
|
||||
# since the official doc names this exact use case and there is no
|
||||
# hardware in hand yet to verify which behavior is actually gated.
|
||||
os_check=0
|
||||
|
||||
# Pin the exact devicetree explicitly rather than relying on the
|
||||
# firmware's own board-revision auto-selection (which would also resolve
|
||||
# to this file on real Pi 5 hardware, per general config.txt convention --
|
||||
# explicit is certain, not just probably-correct).
|
||||
device_tree=bcm2712-rpi-5-b.dtb
|
||||
|
||||
# Enable the dedicated debug UART (Pi 5's own JST connector, not the GPIO
|
||||
# 14/15 header pins). Not because serial capture hardware is set up for
|
||||
# this bring-up (that decision is HDMI-only, FABRIC-3.md §IV) -- this is
|
||||
# a firmware-side switch that costs nothing when nothing is listening, and
|
||||
# it is the only diagnostic channel that survives a framebuffer failure.
|
||||
# rpi5_uart_base() (rpi5_dtb.c) already exists and is currently uncalled;
|
||||
# this is the hook a UART-based fallback console would use if the mailbox
|
||||
# framebuffer driver's two documented unverified details turn out wrong on
|
||||
# real hardware.
|
||||
enable_uart=1
|
||||
|
||||
# Deliberately NOT set, researched but not included this pass:
|
||||
# dtoverlay=uart0 -- GPIO 14/15 header UART; needs a USB-serial
|
||||
# adapter this bring-up doesn't have (HDMI-only
|
||||
# decision). enable_uart=1 above covers the JST
|
||||
# debug UART instead, which needs no extra cable.
|
||||
# dtparam=pciex1 -- one real Pi 5 bare-metal project's own config.txt
|
||||
# comments this as "Required for RP1 access", which
|
||||
# would be surprising (RP1 is always-on in stock Pi
|
||||
# 5 boots) and is community-reported, not confirmed
|
||||
# against official docs. Not needed for this boot
|
||||
# (no RP1 access yet -- FABRIC-3.md §IV.3 item 5 is
|
||||
# still re-scoped, not implemented). Revisit if that
|
||||
# item's own real Broadcom-indirect PCIe work needs
|
||||
# it.
|
||||
# arm_64bit=1 -- researched and dropped: official docs state
|
||||
# "Models that only support a 64-bit kernel ignore
|
||||
# this flag" -- inert on Pi 5, not wrong to include,
|
||||
# just meaningless. The original item 6 wording
|
||||
# named this; corrected here rather than carried
|
||||
# forward.
|
||||
@@ -0,0 +1,14 @@
|
||||
# Beelink SER5 boot media
|
||||
|
||||
`make boot_image TARGET=SER5` builds `build/boards/ser5/lithos-ser5.img`: a GPT disk with one
|
||||
FAT32 EFI System Partition. Write it to a USB stick with `dd`. The partition holds:
|
||||
|
||||
- `EFI/BOOT/BOOTX64.EFI`: the amd64 monolithic loader, with the whole kernel embedded. Firmware
|
||||
finds it through the UEFI removable-media path, so no boot entry has to be created.
|
||||
- `startup.nsh`: runs the loader if the firmware drops into the UEFI shell.
|
||||
- `starforth.cfg`: only present when `KERNEL_ARGS="..."` is given.
|
||||
|
||||
Nothing in the image is SER5-specific. It follows the generic UEFI/ACPI path in FABRIC-3.md §III.
|
||||
|
||||
Status: booted in QEMU (q35 + OVMF, from this image as its own disk) through POST, with Stadium
|
||||
conservation exact (sum 65536 = `Q48_ONE`). Not yet booted on the SER5 itself.
|
||||
@@ -0,0 +1,10 @@
|
||||
# boards/ser5/board.mk -- Beelink SER5 (AMD Ryzen, x86-64, UEFI/ACPI).
|
||||
#
|
||||
# Generic standards-compliant UEFI path (FABRIC-3.md §III): nothing in the
|
||||
# image is SER5-specific. The monolithic loader embeds the whole kernel, so
|
||||
# the image is a GPT disk with one FAT32 EFI System Partition holding
|
||||
# EFI/BOOT/BOOTX64.EFI. Write it to a USB stick with dd.
|
||||
BOARD_DESC := Beelink SER5 (AMD Ryzen, x86-64, UEFI)
|
||||
BOARD_ARCH := amd64
|
||||
BOARD_BOOT := uefi-esp
|
||||
BOARD_IMAGE := lithos-ser5.img
|
||||
@@ -0,0 +1,17 @@
|
||||
# Xilinx Zynq-7020 boot media
|
||||
|
||||
The Zynq-7020's processing system is a dual Cortex-A9: ARMv7-A, 32-bit. It is the host for the
|
||||
StarForth v4 mesh (`docs/v4.0.0/JUSTIFICATION.md` §5, §8).
|
||||
|
||||
Boot chain: BootROM, then `BOOT.BIN` (U-Boot SPL with the board's `ps7_init` DDR and clock setup),
|
||||
then U-Boot, then LithosAnanke. Everything is read from the SD card's FAT partition.
|
||||
|
||||
Status: no image yet. `make boot_image TARGET=ZYNQ7020` stops with an error, because there is no
|
||||
ARMv7 kernel port (`kernel/src/arch/armv7`: entry code, MMU, GIC, private timer). A trial
|
||||
compile for Cortex-A9 built 147 of the 151 kernel and engine sources. The four that failed use
|
||||
`__int128` or have no ARMv7 branch: `kernel/src/crypto/fe25519.c`,
|
||||
`kernel/src/crypto/scalar25519.c`, `kernel/src/hal/hal.c` and
|
||||
`v3/src/word_source/mixed_arithmetic_words.c`.
|
||||
|
||||
`BOOT.BIN` depends on the exact board (Zybo Z7-20, PYNQ-Z2, Arty Z7-20, ZedBoard, ...), because
|
||||
`ps7_init` holds that board's DDR timing. The board has not been chosen yet.
|
||||
@@ -0,0 +1,11 @@
|
||||
# boards/zynq7020/board.mk -- Xilinx Zynq-7020 (dual Cortex-A9, ARMv7-A, 32-bit).
|
||||
#
|
||||
# Boot chain: BootROM -> BOOT.BIN (U-Boot SPL with the board's ps7_init DDR/
|
||||
# clock setup) -> U-Boot -> LithosAnanke, all from the SD card's FAT
|
||||
# partition. Needs the ARMv7 kernel port (kernel/src/arch/armv7), which is
|
||||
# in progress: until it exists, boot_image stops with an explicit error
|
||||
# rather than producing an image that cannot run.
|
||||
BOARD_DESC := Xilinx Zynq-7020 (Cortex-A9, ARMv7-A, BOOT.BIN) -- ARMv7 port in progress
|
||||
BOARD_ARCH := armv7
|
||||
BOARD_BOOT := zynq-bootbin
|
||||
BOARD_IMAGE := lithos-zynq7020.img
|
||||
Reference in New Issue
Block a user