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,274 @@
|
||||
/*
|
||||
StarForth — Steady-State Virtual Machine Runtime
|
||||
|
||||
Copyright (c) 2023–2025 Robert A. James
|
||||
All rights reserved.
|
||||
|
||||
This file is part of the StarForth project.
|
||||
|
||||
Licensed under the StarForth License, Version 1.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
|
||||
You may obtain a copy of the License at:
|
||||
https://github.com/star.4th@proton.me/StarForth/LICENSE.txt
|
||||
|
||||
This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
express or implied, including but not limited to the warranties of
|
||||
merchantability, fitness for a particular purpose, and noninfringement.
|
||||
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
*/
|
||||
|
||||
/**
|
||||
* artemis_sig.h - Artemis disk signature format (FABRIC-3.md §XXVI follow-on,
|
||||
* 2026-09-13)
|
||||
*
|
||||
* Identifies Artemis's own disk, distinct from an identity thumbdrive's
|
||||
* homeblocks_sig_t -- needed once Artemis's disk stops being found by a
|
||||
* hardcoded PCI virtio-blk vendor/device ID scan (QEMU-only; real hardware
|
||||
* has no reason to expose a virtio-blk PCI device at all, since virtio is a
|
||||
* paravirtualization standard, not something a physical storage controller
|
||||
* speaks) and starts being discovered generically instead, the same way
|
||||
* WIREBIND already discovers identity thumbdrives -- by content signature,
|
||||
* not by which bus happened to present the device. Without a distinct
|
||||
* signature, generic discovery on real hardware (where an identity
|
||||
* thumbdrive and Artemis's own disk could both be attached as USB-MSC
|
||||
* devices simultaneously) would have no way to tell them apart.
|
||||
*
|
||||
* Mirrors homeblocks_sig_t's own structural convention (magic + version +
|
||||
* CRC, one 4KiB header) -- a sibling format, not a field bolted onto
|
||||
* homeblocks_sig_t itself: homeblocks_sig_t's own header comment already
|
||||
* states it's "deliberately narrow in scope" (identity-drive fields only,
|
||||
* no spare room), and Artemis's disk is conceptually a different kind of
|
||||
* thing (one dedicated fleet-owned device, not one of many candidate
|
||||
* identity drives), not a variant of the same one.
|
||||
*
|
||||
* CORRECTION, same day: the first version of this format placed the header
|
||||
* at a fixed bottom-of-device forth-block (4, i.e. devblock 1), copying
|
||||
* homeblocks_sig_t's own devblock-1 convention. That convention is safe for
|
||||
* an identity thumbdrive (raw, dedicated storage -- capsule_mint.c writes
|
||||
* directly, no block-subsystem format involved), but Artemis's disk is
|
||||
* block_subsystem.c's own STFR/v2-formatted volume: devblock 0 holds that
|
||||
* format's header (read_header_4k()/write_header_4k(), block_subsystem.c)
|
||||
* and devblock 1 is the FIRST DEVBLOCK OF THE LIVE BAM
|
||||
* (blk_compute_fresh_geometry(): bam_start = 1). Writing artemis_sig_t
|
||||
* there would have overwritten Artemis's own live allocation map on the
|
||||
* very first real boot this ran against -- caught (via `git status`/`grep`
|
||||
* cross-reference against block_subsystem.c, not against a live disk)
|
||||
* before the genesis-stamp call site ever executed against the real image.
|
||||
*
|
||||
* The header now lives at a fixed offset from the END of the device
|
||||
* instead (ARTEMIS_SIG_DEVBLOCK_FROM_TOP, see below) -- the same
|
||||
* "top-of-device, outside the user-addressable LBN pool" region
|
||||
* block_subsystem.c's own meta_fence_blocks reservation (128 devblocks by
|
||||
* default, BLK_META_FENCE_INIT) already carves out for exactly this kind
|
||||
* of system metadata, and where Zuse's own genesis marker/eligibility list
|
||||
* already live (blk_meta_zone_read()/write(), devblock_from_top 0 and 1+
|
||||
* respectively). This format deliberately does NOT go through
|
||||
* blk_meta_zone_*, though: that accessor requires the device to already be
|
||||
* blk_subsys_attach_device()'d and format-detected (first_disk_slot()) --
|
||||
* exactly the state generic pre-attach discovery (repl.c's idle-loop
|
||||
* USB-MSC scan) doesn't have yet, which is the entire reason this format
|
||||
* exists. artemis_sig_check()/artemis_sig_genesis_stamp() instead compute
|
||||
* the same top-of-device arithmetic independently via blkio_info(), so
|
||||
* they work on a raw, not-yet-attached device exactly like
|
||||
* homeblocks_sig_check() already does. ARTEMIS_SIG_DEVBLOCK_FROM_TOP is
|
||||
* fixed well clear of Zuse's two tenants (0 and 1+, open-ended but
|
||||
* realistically small -- 127 pubkeys per chained devblock) so the two
|
||||
* subsystems' independent top-of-device math can never collide, without
|
||||
* this format needing to know how far the eligibility chain has actually
|
||||
* grown on any given boot.
|
||||
*
|
||||
* Reserves offset/size pointers to the growable per-VM log-persistence
|
||||
* region (FABRIC-3.md §XXVI follow-on's own log-record work), the same way
|
||||
* homeblocks_sig_t reserves pointers to where the cert and identity source
|
||||
* attach -- this format doesn't need revisiting when that region's own
|
||||
* internal layout is designed.
|
||||
*/
|
||||
|
||||
#ifndef STARKERNEL_ARTEMIS_SIG_H
|
||||
#define STARKERNEL_ARTEMIS_SIG_H
|
||||
|
||||
#include <stdint.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/*===========================================================================
|
||||
* Magic Field Packing -- same bit layout convention as HOMEBLOCKS_SIG_PACK
|
||||
*
|
||||
* bits 0..31 : 'ARTM' (0x4D545241 little-endian) -- distinct from
|
||||
* homeblocks_sig_t's 'LAHB', so a generic scan can tell an
|
||||
* Artemis disk apart from an identity thumbdrive by content
|
||||
* alone, regardless of which bus either was found on.
|
||||
* bits 32..39 : version (0 for v0)
|
||||
* bits 40..63 : reserved (zero)
|
||||
*===========================================================================*/
|
||||
|
||||
#define ARTEMIS_SIG_MAGIC 0x4D545241ULL /* 'ARTM' */
|
||||
#define ARTEMIS_SIG_VERSION_0 0
|
||||
|
||||
#define ARTEMIS_SIG_PACK(ver) \
|
||||
(ARTEMIS_SIG_MAGIC | ((uint64_t)(ver) << 32))
|
||||
|
||||
#define ARTEMIS_SIG_GET_MAGIC(m) ((uint32_t)((m) & 0xFFFFFFFFULL))
|
||||
#define ARTEMIS_SIG_GET_VERSION(m) ((uint8_t)(((m) >> 32) & 0xFF))
|
||||
|
||||
/* Fence-relative top-of-device index -- see this header's own CORRECTION
|
||||
* comment above for why this replaced a fixed bottom-of-device forth-block.
|
||||
* Same "distance from the very last physical devblock" convention
|
||||
* block_subsystem.c's blk_meta_zone_read()/write() use internally (0 =
|
||||
* last devblock, 1 = second-to-last, ...), computed independently here via
|
||||
* blkio_info() rather than through that accessor (which needs an already-
|
||||
* attached, format-detected slot this code runs before). Fixed well past
|
||||
* Zuse's genesis marker (devblock_from_top 0) and eligibility list
|
||||
* (devblock_from_top 1, chained upward as needed) -- see
|
||||
* zuse_eligibility_list.h -- so the two subsystems' independent top-of-
|
||||
* device math can never collide regardless of how large the eligibility
|
||||
* chain grows in practice. Well inside BLK_META_FENCE_INIT (128 devblocks,
|
||||
* block_subsystem.h) on any real Artemis disk. */
|
||||
#define ARTEMIS_SIG_DEVBLOCK_FROM_TOP 64u
|
||||
|
||||
/*===========================================================================
|
||||
* artemis_sig_t - Artemis disk signature header (exactly one 4KiB devblock)
|
||||
*===========================================================================*/
|
||||
|
||||
typedef struct {
|
||||
uint64_t magic; /* ARTEMIS_SIG_PACK(...) */
|
||||
uint8_t disk_uuid[16]; /* Mirrors homeblocks_sig_t's drive_uuid --
|
||||
* one Artemis disk exists today, but costs
|
||||
* nothing to future-proof the same way. */
|
||||
uint64_t genesis_time_ns; /* Monotonic timestamp when this signature
|
||||
* was first stamped (the one-time genesis
|
||||
* step, not every boot). */
|
||||
uint64_t metadata_devblocks; /* Size of the metadata region at the start
|
||||
* of this raw device (sig header + log
|
||||
* region), in 4KiB devblocks -- everything
|
||||
* past this is Artemis's own general
|
||||
* block-storage pool, same "no partition
|
||||
* boundary" convention homeblocks_sig_t
|
||||
* uses for an identity's own pool. */
|
||||
|
||||
uint32_t log_region_offset; /* CORRECTION, Step 4 (log_region.h,
|
||||
* 2026-09-13): stays 0 -- informational
|
||||
* field only, never written or read by
|
||||
* the real implementation. The log
|
||||
* region ended up at a fixed, compile-
|
||||
* time devblock_from_top constant
|
||||
* (LOG_REGION_DEVBLOCK_FROM_TOP_BASE,
|
||||
* log_region.h) reached through
|
||||
* blk_meta_zone_*(), whose own control
|
||||
* header (log_region_ctrl_t) is the one
|
||||
* authoritative source of the region's
|
||||
* live offset/size/head/tail -- a second
|
||||
* writer of the same fact here would be
|
||||
* unnecessary drift risk, not a useful
|
||||
* summary. Left at 0/reserved rather
|
||||
* than deleted, in case a real second
|
||||
* reader (a host-side offline tool that
|
||||
* can't run blk_meta_zone_*() at all)
|
||||
* ever needs it. */
|
||||
uint32_t log_region_devblocks; /* See log_region_offset above -- same
|
||||
* reasoning, stays 0. */
|
||||
|
||||
uint64_t hdr_crc; /* Computed over every field above this
|
||||
* one, same boundary/discipline as
|
||||
* homeblocks_sig_compute_crc(). */
|
||||
|
||||
/* Padding to keep the header exactly one 4KiB devblock. */
|
||||
uint8_t _pad[4096 - (
|
||||
8 + /* magic */
|
||||
16 + /* disk_uuid */
|
||||
8 + /* genesis_time_ns */
|
||||
8 + /* metadata_devblocks */
|
||||
4 + 4 + /* log_region_offset, log_region_devblocks */
|
||||
8 /* hdr_crc */
|
||||
)];
|
||||
} artemis_sig_t;
|
||||
|
||||
/* C99-portable compile-time size assertion (no _Static_assert -- that's
|
||||
* C11), same discipline homeblocks_sig.h's own check uses. */
|
||||
typedef char artemis_sig_size_check[(sizeof(artemis_sig_t) == 4096) ? 1 : -1];
|
||||
|
||||
/*===========================================================================
|
||||
* Signature check (mirrors homeblocks_sig_result_t exactly)
|
||||
*===========================================================================*/
|
||||
|
||||
typedef enum {
|
||||
ARTEMIS_SIG_OK = 0, /* magic, version, and crc all check out */
|
||||
ARTEMIS_SIG_BLANK, /* magic does not match -- blank, foreign, or
|
||||
* an identity thumbdrive (different magic) */
|
||||
ARTEMIS_SIG_BAD_VERSION, /* magic matches, version unrecognized */
|
||||
ARTEMIS_SIG_BAD_CRC, /* magic+version match, crc fails -- corrupt
|
||||
* or tampered */
|
||||
ARTEMIS_SIG_READ_ERROR /* could not read from the device at all */
|
||||
} artemis_sig_result_t;
|
||||
|
||||
/* Forward-declared, not included here -- same reasoning as
|
||||
* homeblocks_sig.h's own forward declaration of struct blkio_dev. */
|
||||
struct blkio_dev;
|
||||
|
||||
/*
|
||||
* artemis_sig_check - Read and verify the Artemis disk signature header, at
|
||||
* the fixed ARTEMIS_SIG_DEVBLOCK_FROM_TOP offset from whatever `dev`
|
||||
* reports as its own total size (blkio_info()) -- no attach or format
|
||||
* detection required, same "works on a raw, not-yet-attached device"
|
||||
* contract homeblocks_sig_check() already has.
|
||||
*
|
||||
* @param dev Open block device to read from.
|
||||
* @param out_sig On ARTEMIS_SIG_OK, populated with the verified
|
||||
* header. Left unspecified on any other result.
|
||||
* @return ARTEMIS_SIG_OK, or the specific reason for refusal.
|
||||
*/
|
||||
artemis_sig_result_t artemis_sig_check(struct blkio_dev *dev,
|
||||
artemis_sig_t *out_sig);
|
||||
|
||||
/*
|
||||
* artemis_sig_compute_crc - CRC-64 over every field of `sig` up to but not
|
||||
* including hdr_crc itself and the trailing padding. Exposed publicly for
|
||||
* the same reason homeblocks_sig_compute_crc() is: both the check and the
|
||||
* future genesis-stamping step need the identical computation.
|
||||
*
|
||||
* @param sig Header to checksum. hdr_crc and _pad are not read.
|
||||
* @return The CRC-64 value that hdr_crc should hold for `sig` to verify.
|
||||
*/
|
||||
uint64_t artemis_sig_compute_crc(const artemis_sig_t *sig);
|
||||
|
||||
/*
|
||||
* artemis_sig_genesis_stamp - One-time write of a fresh artemis_sig_t onto
|
||||
* a disk already confirmed to be Artemis's own (never called speculatively
|
||||
* on an unidentified/blank device -- see the call site in kernel_main.c for
|
||||
* why that's always safe there: virtio_blk_find_artemis() only ever
|
||||
* succeeds against the one dedicated PCI device, so a BLANK read at this
|
||||
* fblock unambiguously means "this disk has never been stamped," not
|
||||
* "this might be some other blank drive"). log_region_offset/devblocks are
|
||||
* written as 0 (not yet allocated) -- step 4's own log-persistence design
|
||||
* allocates them later via a normal artemis_sig_t rewrite, same one-header
|
||||
* location.
|
||||
*
|
||||
* disk_uuid is drawn from rng_get_bytes(), same entropy source
|
||||
* capsule_mint.c already uses for an identity thumbdrive's drive_uuid.
|
||||
* genesis_time_ns is written as 0 -- no monotonic-ns source exists
|
||||
* anywhere in this codebase yet, same open item homeblocks_sig_t's own
|
||||
* minted_time_ns field already carries.
|
||||
*
|
||||
* Idempotent by construction: a caller must check artemis_sig_check()
|
||||
* returns ARTEMIS_SIG_BLANK first (this function does not re-check, to
|
||||
* avoid a second redundant read the caller already just performed).
|
||||
*
|
||||
* @param dev Open block device to write to. Must already be confirmed as
|
||||
* Artemis's own disk.
|
||||
* @return 0 on success (including read-back verification), -1 on any
|
||||
* entropy, write, or verify failure -- the disk is left however
|
||||
* the failed write left it, same as capsule_mint.c's own
|
||||
* write-then-verify discipline.
|
||||
*/
|
||||
int artemis_sig_genesis_stamp(struct blkio_dev *dev);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* STARKERNEL_ARTEMIS_SIG_H */
|
||||
Reference in New Issue
Block a user