admin/LithosAnanake
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

boards: the amd64 target is PC -- a generic x86-64 UEFI PC, not the SER5

Browse Source 
Captain Bob, 2026-10-14: "change to PC, not SER5. it's not supposed to be
specific, but PC generic."  boards/ser5 -> boards/pc, TARGET=PC,
lithos-pc.img; the image was never specific to one machine (the generic
UEFI/ACPI path, FABRIC-3 III).  The Beelink SER5 stays named where the text
means the unit on the bench (its Secure Boot, BIOS, serial header) and in
the records.  Built: lithos-pc.img, system=v4, with its SBOM.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
2026-10-14 17:22:32 -04:00
co-authored by Claude Opus 5.5
parent 1ce8576b76
commit 3b49cb15a2
10 changed files with 55 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Makefile
+3 -3
View File
@@ -8,7 +8,7 @@
# docs/book/Makefile -- the single LaTeX book (build/docs/*.pdf)
# Every sub-make runs from this directory, so paths are always repo-relative.
#
# TARGET is either a board (SER5 RASPI MILKV ZYNQ7020), a hosted v3 profile
# TARGET is either a board (PC RASPI MILKV ZYNQ7020), a hosted v3 profile
# (standard fast fastest turbo asan ...), or empty:
#
# make [all] every board that has a kernel port, the
@@ -34,11 +34,11 @@
# ==============================================================================
# Board name (as typed on the command line) -> boards/ directory.
BOARD_DIR_SER5 := ser5
BOARD_DIR_PC := pc
BOARD_DIR_RASPI := raspi
BOARD_DIR_MILKV := milkv
BOARD_DIR_ZYNQ7020 := zynq7020
BOARDS := SER5 RASPI MILKV ZYNQ7020
BOARDS := PC RASPI MILKV ZYNQ7020
empty :=
space := $(empty) $(empty)
README.md
+4 -4
View File
@@ -35,7 +35,7 @@ chooses (see below).
| M7.1 | Capsule birth · Mama FORTH vocabulary · the Tripod fleet · kernel-Hermes · word-level ACL | ✅ Live |
| M8 | Keyboard input to the REPL — PS/2, virtio and **USB** keyboards (a full keyboard: Caps/Num Lock, keypad) | ✅ In QEMU, all three ISAs |
| M9 | Block storage — Artemis's disk on virtio-blk; identity thumbdrives on USB mass storage | ✅ In QEMU · real disks: no driver yet (`boards/BRINGUP.md` A4) |
| Bare metal | SER5 (amd64), Raspberry Pi 5 (aarch64), Milk-V Mars (riscv64); Zynq-7020 (ARMv7) not yet ported | Images build; first boots on the bench — `boards/BRINGUP.md` |
| Bare metal | a generic PC (amd64; first on the bench: a Beelink SER5), Raspberry Pi 5 (aarch64), Milk-V Mars (riscv64); Zynq-7020 (ARMv7) not yet ported | Images build; first boots on the bench — `boards/BRINGUP.md` |
**v4 is the default build, and v3 is being retired**: every kernel boots v4 unless its boot
arguments say `system=v3`. POST at boot, on all three ISAs: v4 — **538 tests**,
@@ -70,14 +70,14 @@ arguments say `system=v3`. POST at boot, on all three ISAs: v4 — **538 tests**
```bash
# One boot image per physical target (output: build/boards/<board>/)
make boot_image TARGET=SER5 # Beelink SER5 -- GPT/ESP, BOOTX64.EFI
make boot_image TARGET=PC # any x86-64 UEFI PC -- GPT/ESP, BOOTX64.EFI
make boot_image TARGET=RASPI # Raspberry Pi 5 -- FAT, config.txt + kernel_2712.img + DTB
make boot_image TARGET=MILKV # Milk-V Mars -- GPT/ESP, BOOTRISCV64.EFI (U-Boot bootefi)
make boards # list boards (the Zynq-7020 has no ARMv7 port yet)
# Each image carries v4 and v3. As built it boots v4; to boot v3, change the one word
# system=v4 -> system=v3
# in starforth.cfg on the SER5's stick or the Mars's card, or cmdline.txt on the Pi 5's card.
# in starforth.cfg on the PC's stick or the Mars's card, or cmdline.txt on the Pi 5's card.
# The same TARGET drives all, docs and clean (make help)
make # every board with a kernel port + hosted v3 + the book
@@ -125,7 +125,7 @@ which to believe. Among them:
|---|---|
| [The FABRIC record](docs/fabric/) | Every design decision and the work as it happened (`FABRIC-3.md` is the living one) |
| [StarForth v4](docs/v4.0.0/) | The F18-derived engine |
| [Board bring-up](boards/BRINGUP.md) | Getting onto the SER5, the Pi 5 and the Mars |
| [Board bring-up](boards/BRINGUP.md) | Getting onto a PC, the Pi 5 and the Mars |
| [Roadmap and versioning](docs/reference/ROADMAP.md) | Milestone plan and release-versioning policy |
| [Capsule System — M7.1](docs/reference/M7.1.md) | Capsule birth protocol |
| [Word-level ACL](docs/reference/word-acl/DESIGN.md) | The access-control design |
boards/BRINGUP.md
+6 -6
View File
@@ -8,7 +8,7 @@ on the date above; where it comes from a document instead, the document is named
has been booted, its results go in `docs/fabric/FABRIC-3.md` (sections III, IV, V) and its
`README.md` here, and this file is corrected.
The four boards: `SER5` (amd64), `RASPI` (Pi 5, aarch64), `MILKV` (Mars, riscv64), `ZYNQ7020`
The four boards: `PC` (amd64, any x86-64 UEFI PC; the one on the bench is a Beelink SER5 -- the target was named `SER5` until 2026-10-14), `RASPI` (Pi 5, aarch64), `MILKV` (Mars, riscv64), `ZYNQ7020`
(ARMv7, no port yet). See `boards/README.md` for what each image is.
---
@@ -30,7 +30,7 @@ None has been fixed: each needs your word.
| A5 | **Entropy:** RDRAND on amd64 only. aarch64 and riscv64 have virtio-rng alone. | `kernel/src/rng/rng.c` | Pi 5 and Mars print the "no entropy backend available" warning; anything that needs random bytes is refused. Minting needs them. |
| A6 | **Fixed 2026-10-14.** Every board image carries both systems, v3 and v4, and the boot arguments choose: `system=v4` (as built: v4 is the default) or `system=v3` -- one word in `starforth.cfg` on the SER5's and the Mars's stick or card, in `cmdline.txt` on the Pi 5's card. No rebuild to switch. | root `Makefile`, `kernel/Makefile`, `kernel/src/kernel_main.c`, `kernel/src/boot/cmdline.c`; `FABRIC-3.md` XLIII | The SER5 image itself, booted under OVMF: v3 as built, v4 after the one-word edit. The boot says which system runs and why ("System: ..."). |
### 1.2 SER5
### 1.2 PC (the SER5 on the bench)
| # | What | Where | Effect |
|---|---|---|---|
@@ -127,7 +127,7 @@ In this order, each as a design for approval first:
### 3.1 Build
```
make boot_image TARGET=SER5 EMERGENCY_CONSOLE_ENABLED=1
make boot_image TARGET=PC EMERGENCY_CONSOLE_ENABLED=1
make boot_image TARGET=RASPI EMERGENCY_CONSOLE_ENABLED=1
make boot_image TARGET=MILKV EMERGENCY_CONSOLE_ENABLED=1
```
@@ -136,7 +136,7 @@ make boot_image TARGET=MILKV EMERGENCY_CONSOLE_ENABLED=1
objects itself (2026-10-14): make does not see a change of compile flags, and an image
built over old objects booted headless (2026-10-13) or would have lacked v4.
- [ ] The images boot v4. To boot v3 instead: change `system=v4` to `system=v3` in
`starforth.cfg` (SER5, Mars) or `cmdline.txt` (Pi 5) on the medium. The boot prints "System: ..." with the choice.
`starforth.cfg` (PC, Mars) or `cmdline.txt` (Pi 5) on the medium. The boot prints "System: ..." with the choice.
- [ ] Each ends with its image in `build/boards/<board>/`. Record `sha256sum` of each.
- [ ] Confirm the switch took: the image booted in QEMU (3.2) shows a prompt with no
thumbdrive attached. After a clean build it does (tried on `MILKV`).
@@ -149,7 +149,7 @@ make boot_image TARGET=MILKV EMERGENCY_CONSOLE_ENABLED=1
One QEMU at a time. Use a copy of the image: the kernel writes to its disk.
- [ ] **SER5:** q35 with OVMF, the image as the only disk, no `-cdrom`, no virtio disk, no
- [ ] **PC:** q35 with OVMF, the image as the only disk, no `-cdrom`, no virtio disk, no
thumbdrive. This is the machine the README's "booted in QEMU" refers to.
- [ ] **MILKV:** the command in `boards/milkv/README.md` (OpenSBI, U-Boot, `bootefi`).
- [ ] **RASPI:** there is no QEMU model of the Pi 5, but its native path -- raw image, entry
@@ -182,7 +182,7 @@ the one QEMU exercises most closely, and the Pi 5's can be rehearsed only in par
- [ ] `sudo dd if=build/boards/<board>/<image> of=/dev/sdX bs=4M conv=fsync status=progress`
- [ ] Read it back and compare: `sudo cmp -n $(stat -c %s <image>) <image> /dev/sdX`.
### 4.2 SER5
### 4.2 PC (the SER5)
- [ ] Serial, if there is a header: 115200 8N1, logged to a file from before power-on.
- [ ] HDMI and keyboard connected. Stick in a rear port.
boards/README.md
+3 -2
View File
@@ -6,7 +6,7 @@ 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` |
| `PC` | `pc/` | amd64 | UEFI firmware, removable-media path -- any x86-64 PC | 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` |
@@ -24,6 +24,7 @@ devices. `KERNEL_ARGS="..."` is written as `starforth.cfg` (UEFI boards) or `cmd
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
PC image has been booted in QEMU (q35 + OVMF, from its own disk) through POST. (`PC` was named
`SER5` until 2026-10-14, after the first PC on the bench; the image was never specific to it.) The Pi 5
native path (`raspi/README.md`) and the JH7110 peripherals have still only been checked by
compiling.
boards/pc/README.md
+20
View File
@@ -0,0 +1,20 @@
# PC boot media (generic x86-64, UEFI)
`make boot_image TARGET=PC` builds `build/boards/pc/lithos-pc.img`: a GPT disk with one FAT32
EFI System Partition, for any x86-64 PC whose UEFI firmware boots a removable medium. 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`: the boot arguments -- `system=v4` as built; change the word to `system=v3` to
boot v3 (and `KERNEL_ARGS="..."` adds to it).
Beside the image, `lithos-pc.spdx` / `.spdx.json`: its SBOM, every file on it with its SHA-256.
Nothing in the image is specific to one machine: it follows the generic UEFI/ACPI path in
FABRIC-3.md §III. Until 2026-10-14 this target was named `SER5`, after the first PC to be brought
up -- a Beelink SER5 (AMD Ryzen), which is still the one on the bench (`boards/BRINGUP.md`).
Status: booted in QEMU (q35 + OVMF, from this image as its own disk): v4 as built, v3 with
`system=v3`. Not yet booted on real hardware.
boards/pc/board.mk
+12
View File
@@ -0,0 +1,12 @@
# boards/pc/board.mk -- a generic PC: x86-64, UEFI firmware, ACPI.
#
# Not one machine: the standards-compliant UEFI path (FABRIC-3.md §III), so
# any x86-64 PC whose firmware boots a UEFI removable medium. (The first to be
# brought up on the bench is a Beelink SER5, an AMD Ryzen mini-PC -- see
# boards/BRINGUP.md.) 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 := Generic PC (x86-64, UEFI, ACPI)
BOARD_ARCH := amd64
BOARD_BOOT := uefi-esp
BOARD_IMAGE := lithos-pc.img
boards/ser5/README.md
-14
View File
@@ -1,14 +0,0 @@
# 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.
boards/ser5/board.mk
-10
View File
@@ -1,10 +0,0 @@
# 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
docs/INDEX.md
+4 -4
View File
@@ -2,8 +2,8 @@
Generated 2026-10-14 by the docs triage (docs/CLAUDE.md, Phase 1), from the tracked tree
after the reorganisation. Start at **[README.md](README.md)** for the map; abandoned ideas and
revised claims are in **[DEAD-AND-REVISED.md](DEAD-AND-REVISED.md)**; the duplicates deleted
2026-10-14 are recorded in **[DELETE-CANDIDATES.md](DELETE-CANDIDATES.md)**. Logs (`logs/`) and DoE run
revised claims are in **[DEAD-AND-REVISED.md](DEAD-AND-REVISED.md)**; files awaiting a delete
ruling are in **[DELETE-CANDIDATES.md](DELETE-CANDIDATES.md)**. Logs (`logs/`) and DoE run
CSVs are not listed. Bulk data folders, and the formal LaTeX tree (governed by
`docs/formal/CLAUDE.md`), are listed one row per folder.
@@ -38,7 +38,7 @@ CSVs are not listed. Bulk data folders, and the formal LaTeX tree (governed by
| CODE_OF_CONDUCT.md | Contributor Covenant Code of Conduct | CURRENT | |
| CONTRIBUTING.md | Contributing to StarForth | CURRENT | |
| NOTICE.md | NOTICE.md | CURRENT | |
| README.md | LithosAnanke v2.0.1 | CURRENT | |
| README.md | LithosAnanke v2.1.0 | CURRENT | |
## boards
@@ -47,9 +47,9 @@ CSVs are not listed. Bulk data folders, and the formal LaTeX tree (governed by
| boards/BRINGUP.md | Board bring-up checklist | WORKING | Bare-metal bring-up checklist and blockers. |
| boards/README.md | boards/ | CURRENT | |
| boards/milkv/README.md | Milk-V Mars boot media | CURRENT | |
| boards/pc/README.md | PC boot media (generic x86-64, UEFI) | CURRENT | |
| boards/raspi/README.md | Raspberry Pi 5 native boot media | CURRENT | |
| boards/raspi/config.txt | LithosAnanke native (non-UEFI) boot config for Raspberry Pi 5 (BCM2712). | CURRENT | |
| boards/ser5/README.md | Beelink SER5 boot media | CURRENT | |
| boards/zynq7020/README.md | Xilinx Zynq-7020 boot media | CURRENT | |
## capsules
kernel/Makefile
+3 -3
View File
@@ -189,7 +189,7 @@ CAPSULE_GENERATED_KOBJ = $(KERNEL_OBJ_DIR)/capsule_generated.o
# ==============================================================================
# BOARD (boot_image)
# ==============================================================================
# BOARD names a directory under boards/ (ser5, raspi, milkv, ...). Its
# BOARD names a directory under boards/ (pc, raspi, milkv, ...). Its
# board.mk sets BOARD_ARCH, BOARD_BOOT (how the firmware finds us) and
# BOARD_IMAGE (the single file written to the boot medium). The root
# Makefile's `make boot_image TARGET=<NAME>` maps NAME to BOARD and passes
@@ -1197,7 +1197,7 @@ thumbdrive: all
# ==============================================================================
# boot_image -- the single file written to a board's boot medium. Driven by
# BOARD (boards/<board>/board.mk); normally invoked from the repo root as
# make boot_image TARGET=SER5|RASPI|MILKV|ZYNQ7020
# make boot_image TARGET=PC|RASPI|MILKV|ZYNQ7020
# Output: build/boards/<board>/$(BOARD_IMAGE).
#
# BOARD_BOOT selects the recipe:
@@ -1285,7 +1285,7 @@ rpi5-rehearsal:
ifeq ($(strip $(BOARD)),)
boot_image:
@echo "boot_image needs a board. From the repo root:"
@echo " make boot_image TARGET=SER5|RASPI|MILKV|ZYNQ7020"
@echo " make boot_image TARGET=PC|RASPI|MILKV|ZYNQ7020"
@exit 1
else ifeq ($(BOARD_BOOT),uefi-esp)
boot_image: all