rajamesandJunie
a8b70e88d3
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>
StarForth / LithosAnanke Documentation
This is the lithosananke branch: the bare-metal StarKernel side of the project
(contrast master, which is the hosted-VM-only side). Documentation follows the
two-tier model described in docs/CLAUDE.md: formal/ is the polished,
citable LaTeX tier; working/ is living design notes and drafts that feed it.
Everything else in this directory is branch- or subsystem-specific material that
doesn't fit either tier.
Layout
- formal/ — Three-volume LaTeX documentation set (research volumes,
practitioner books, standalone reports) plus the
scraps/fragment library it's assembled from. Audience: patent counsel, SSRN reviewers, licensees, hobbyists with hardware in hand. Seeformal/CLAUDE.mdfor authoring conventions. - working/ — Living documents: architecture design notes, DoE
experiment logs, hardware/platform notes, draft specs, academic-paper source
material, and an archive of superseded docs. Source material for
formal/. - 03-architecture/ — Tripod VM architecture constraints (Hera/Hermes/Artemis) and the word-level ACL system design.
- lithosananke/ — LithosAnanke kernel branch documentation: milestone roadmap, system architecture, HAL reference, kernel command-line argument design, and the amd64 APIC-timer ISR postmortem.
- birthing/ — VM birthing plan and status for the Hera-spawns- Hermes/Artemis constellation, plus three-architecture QEMU acceptance logs.
- patent/ — Provisional patent application source. Legal hold — ask Bob before touching anything in this directory.
- api/ — Generated Doxygen tag file and warnings log (gitignored; not part of the tracked doc tree).
- pptx/ — Elevator-pitch and deep-dive slide decks for different audiences (technical, non-technical, academic, PhD-level).
Current Active Work
- LithosAnanke M7/M7.1 — VM parity validation and init capsule architecture.
See
lithosananke/README.mdandlithosananke/M7.1.md. - Word-level ACL system — Phase 6 complete on
master; Phase 7 (LithosAnanke parity) is the next step. See03-architecture/word-acl/README.md. - Tripod VMs — Hera (governor), Hermes (messenger), Artemis (memory/block
storage). See
03-architecture/tripod/README.mdandbirthing/.
Contributing
- Place new material in
working/first; promote toformal/only when it's ready to be cited (seeformal/CLAUDE.mdfor promotion criteria). - Never touch
patent/,formal/patent/,formal/scraps/legal/, orworking/legal/without Bob's explicit instruction. - Add a
README.mdto any new category-level subdirectory, following the format used throughout this tree: orientation paragraph + bullet list of real files with one-line descriptions.