/* 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 #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 */