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

Single-block relocation: RELOCATE-BLOCK, resolve_lbn(), persisted exception table

Browse Source 
Implements the full design from the prior commit in one pass. resolve_lbn()
is the single choke point threaded through the ten public LBN-consuming
entry points (blk_get_buffer, blk_update, blk_flush, blk_is_allocated,
blk_mark_allocated, blk_mark_free, blk_is_valid, blk_get_meta, blk_set_meta,
plus blk_get_empty_buffer covered via delegation) -- an LBN->LBN redirect,
not a new storage allocator, since the LBN space is already unified across
every attached blkio_dev backend. VM window cache staleness across a
relocation reuses the existing blk_vm_check_epoch() mechanism from
Milestone 2h's hot-detach fix for free -- g.epoch bumps on relocation too.

Persistence lands in the same pass: two new uint32_t fields
(reloc_start/reloc_devblocks) appended after hdr_crc in blk_volume_meta_t,
carved from existing padding without moving any earlier field's byte
offset -- an old formatted volume's zeroed padding reads back as
reloc_devblocks=0 ("no reloc capacity"), gracefully, not a format-breaking
change. compute_totals_from_B() generalized to account for the new
reserved region. reloc_flush_to_disk()/reloc_load_from_disk() mirror the
BAM I/O functions' own absolute-devblock-addressing shape; the persisted
copy's owner is first_disk_slot() (already existed, already used for this
exact "which device is canonical" question by blk_get_volume_meta()).
blk_subsys_relocate_block() is a mechanical primitive only -- copies
content (staged through a local buffer, since obtaining the target's
blk_get_buffer() result can evict and invalidate the source's cache
pointer if they share a device), frees the source BAM entry, appends the
exception entry, bumps the epoch, flushes to disk. RELOCATE-BLOCK exposes
it to FORTH, no policy of its own (ACL's job, per this session's direction).

A first live-test attempt gave a false negative against disk/artemis.img
(predates reloc capacity, so relocation only ever existed in memory that
boot) -- traced to the test's own setup before being mistaken for a bug,
then re-verified correctly against a fresh volume (new fixture,
disk/artemis-reloc-test.img): relocated a RAMDRIVE block to the fresh
disk, confirmed live resolution through the redirect, then confirmed both
the redirect and the relocated content survived an abrupt QEMU kill and
full reboot. Also fixed three lingering "glibc" doc-comment
misattributions from Milestone 2h (the actual allocator is this kernel's
own kmalloc) that survived an earlier FABRIC-2.md-only correction. All
three architectures re-verified clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
This commit is contained in:
Robert Allan James
2026-08-25 19:14:01 -04:00
co-authored by Claude Sonnet 5
parent 073dae4f56
commit 36d832ff47
22 changed files with 63612 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/block_subsystem.c
+192 -5
View File
@@ -71,6 +71,20 @@
#define META_PER_BLOCK (META_REGION_SIZE / BLK_PACK_RATIO)
#define DISK_CACHE_SLOTS 8
/* Single-block relocation (Milestone 2h+). One reserved 4 KiB devblock:
* a 4-byte count prefix plus up to BLK_RELOC_MAX_ENTRIES 8-byte
* {home_lbn, actual_lbn} pairs (500*8+4 = 4004 <= 4096). Relocations are
* expected rare, not routine -- see FABRIC-2.md's own design writeup --
* so a linear-scanned fixed array is deliberate, matching this file's
* existing tolerance for small bounded scans (DISK_CACHE_SLOTS above,
* BLK_VM_SLOTS in block_words.c are the same shape). */
#define BLK_RELOC_MAX_ENTRIES 500u
typedef struct {
uint32_t home_lbn;
uint32_t actual_lbn;
} blk_reloc_entry_t;
static inline size_t minzu(size_t a, size_t b) { return a < b ? a : b; }
static inline uint32_t udiv_floor(uint32_t a, uint32_t b) { return a / b; }
@@ -154,9 +168,10 @@ static struct {
/* Bumped on every attach/detach (Milestone 2h). Freeing a slot then
* immediately allocating a new one for a same-LBN re-attach can hand
* back the *same* heap address (confirmed live: glibc's allocator does
* exactly this for a free() followed immediately by a same-size
* calloc(), with nothing else allocated in between) -- so a raw
* back the *same* heap address (confirmed live: this kernel's own
* first-fit kmalloc, src/starkernel/memory/kmalloc.c, does exactly
* this for a free() followed immediately by a same-size calloc(),
* with nothing else allocated in between) -- so a raw
* pointer comparison against a cached blk_get_buffer() result cannot
* reliably detect "this LBN's device changed underneath a caller
* holding a stale cached pointer." A monotonic epoch can't be fooled
@@ -165,9 +180,32 @@ static struct {
* caches a blk_get_buffer() result across calls). */
uint64_t epoch;
/* Single-block relocation exception table (Milestone 2h+, in-memory
* mirror of whichever attached disk's own on-disk copy is canonical
* -- see reloc_flush_to_disk()/reloc_load_from_disk() below).
* Subsystem-global, not per-device: an LBN can be relocated to any
* other LBN regardless of which devices happen to be involved. */
blk_reloc_entry_t reloc[BLK_RELOC_MAX_ENTRIES];
uint32_t reloc_count;
int initialized;
} g = {0};
/* Redirect lbn through the relocation table if it's been moved elsewhere.
* The single choke point every public LBN-consuming entry point below
* calls first -- see FABRIC-2.md's design writeup for why this is an
* LBN->LBN redirect rather than a new storage-allocation mechanism, and
* why it's safe for every downstream function (BAM offset math, cache
* lookup, lbn_to_slot() itself) to stay completely unaware a substitution
* happened. Linear scan -- see BLK_RELOC_MAX_ENTRIES's own doc comment
* for why that's the right tradeoff here. */
static uint32_t resolve_lbn(uint32_t lbn) {
for (uint32_t i = 0; i < g.reloc_count; i++) {
if (g.reloc[i].home_lbn == lbn) return g.reloc[i].actual_lbn;
}
return lbn;
}
/* ===== slot routing ===== */
static blk_dev_slot_t *lbn_to_slot(uint32_t lbn) {
blk_dev_slot_t *s = g.head;
@@ -323,8 +361,9 @@ static uint32_t choose_B(uint64_t total_devblocks_4k) {
static void compute_totals_from_B(blk_volume_meta_t *m) {
uint64_t B = m->bam_devblocks;
uint64_t R = m->reloc_devblocks; /* reserved relocation-table region, see blk_volume_meta_t's own doc comment */
m->tracked_blocks = 32768ULL * B;
uint64_t payload4k = (m->total_devblocks > (1+B)) ? (m->total_devblocks - 1 - B) : 0;
uint64_t payload4k = (m->total_devblocks > (1+B+R)) ? (m->total_devblocks - 1 - B - R) : 0;
uint64_t storable = 3ULL * payload4k;
m->total_blocks = (m->tracked_blocks < storable) ? m->tracked_blocks : storable;
uint64_t reserved = (uint64_t) BLK_DISK_SYS_RESERVED;
@@ -409,6 +448,58 @@ static int bam_flush_to_disk(blk_dev_slot_t *slot) {
return BLK_OK;
}
/* ===== relocation-exception table I/O (Milestone 2h+, mirrors the BAM I/O
* functions' own absolute-devblock-addressing shape above) =====
*
* Wire format: raw byte layout of the in-memory g.reloc[]/g.reloc_count
* state -- a 4-byte count prefix, then that many packed {uint32_t home_lbn;
* uint32_t actual_lbn;} pairs, all within one 4 KiB devblock (only the
* first is ever read/written -- blk_compute_fresh_geometry() always
* reserves exactly one; a volume with reloc_devblocks > 1 isn't produced
* by this driver today, so the rest would silently go unused, matching
* "won't migrate too much" scale). slot is the relocation-table owner
* (first_disk_slot(), see blk_subsys_attach_device()) -- both functions
* are no-ops (not errors) when there's no owner yet, or the owner
* predates reloc capacity (reloc_devblocks == 0, e.g. disk/artemis.img's
* existing fixture, formatted before this feature existed). */
static int reloc_load_from_disk(blk_dev_slot_t *slot) {
if (!slot || !slot->dev) return BLK_EINVAL;
blk_volume_meta_t *m = &slot->vol_meta;
if (m->reloc_devblocks == 0) { g.reloc_count = 0; return BLK_OK; }
uint8_t buf4k[4096];
uint32_t base1k = m->reloc_start * 4u;
for (uint32_t k = 0; k < 4; k++) {
if (blkio_read(slot->dev, base1k + k, buf4k + k*1024u) != BLKIO_OK)
memset(buf4k + k*1024u, 0, 1024u);
}
uint32_t count;
memcpy(&count, buf4k, sizeof(count));
if (count > BLK_RELOC_MAX_ENTRIES) count = 0; /* corrupt/foreign data guard */
memcpy(g.reloc, buf4k + sizeof(count), (size_t) count * sizeof(blk_reloc_entry_t));
g.reloc_count = count;
return BLK_OK;
}
static int reloc_flush_to_disk(blk_dev_slot_t *slot) {
if (!slot || !slot->dev) return BLK_OK; /* no owner yet -- nothing to persist to */
blk_volume_meta_t *m = &slot->vol_meta;
if (m->reloc_devblocks == 0) return BLK_OK; /* this device predates reloc capacity */
uint8_t buf4k[4096] = {0};
memcpy(buf4k, &g.reloc_count, sizeof(g.reloc_count));
memcpy(buf4k + sizeof(g.reloc_count), g.reloc,
(size_t) g.reloc_count * sizeof(blk_reloc_entry_t));
uint32_t base1k = m->reloc_start * 4u;
for (uint32_t k = 0; k < 4; k++) {
if (blkio_write(slot->dev, base1k + k, buf4k + k*1024u) != BLKIO_OK) return BLK_EIO;
}
blkio_flush(slot->dev);
return BLK_OK;
}
/* ===== volume format / load (per disk slot) ===== */
/* Compute fresh volume geometry in memory only. Pure function of device
@@ -426,7 +517,15 @@ static void blk_compute_fresh_geometry(blk_dev_slot_t *slot) {
slot->vol_meta.total_devblocks = (uint64_t) udiv_floor(slot->total_blkio_blocks_1k, 4);
slot->vol_meta.bam_start = 1;
slot->vol_meta.bam_devblocks = choose_B(slot->vol_meta.total_devblocks);
slot->vol_meta.devblock_base = slot->vol_meta.bam_start + slot->vol_meta.bam_devblocks;
slot->vol_meta.reloc_start = slot->vol_meta.bam_start + slot->vol_meta.bam_devblocks;
/* One devblock (4 KiB): a 4-byte count prefix + up to BLK_RELOC_MAX_ENTRIES
* 8-byte {home_lbn, actual_lbn} pairs -- see this file's own doc comment
* on BLK_RELOC_MAX_ENTRIES. Reserved unconditionally on every fresh
* format, not sized to demand -- relocations are rare, but knowing in
* advance whether a volume *can* ever receive one is simpler than a
* variable-size region that might need to grow later. */
slot->vol_meta.reloc_devblocks = 1;
slot->vol_meta.devblock_base = slot->vol_meta.reloc_start + slot->vol_meta.reloc_devblocks;
compute_totals_from_B(&slot->vol_meta);
if (sf_has_rtc()) slot->vol_meta.created_time = sf_realtime_ns();
@@ -452,6 +551,12 @@ static int blk_commit_format(blk_dev_slot_t *slot) {
uint32_t base1k = (slot->vol_meta.bam_start + i) * 4u;
for (uint32_t k = 0; k < 4; k++) (void) blkio_write(slot->dev, base1k + k, z);
}
/* Zero the reloc region too -- a zeroed 4-byte count prefix reads back
* as "0 entries", the correct empty-table default. */
for (uint32_t i = 0; i < slot->vol_meta.reloc_devblocks; i++) {
uint32_t base1k = (slot->vol_meta.reloc_start + i) * 4u;
for (uint32_t k = 0; k < 4; k++) (void) blkio_write(slot->dev, base1k + k, z);
}
uint8_t hdr[BLK_DEVICE_SECTOR];
volmeta_to_buf(&slot->vol_meta, hdr);
(void) write_header_4k(slot, hdr);
@@ -553,6 +658,9 @@ int blk_subsys_add_raw_device(uint8_t *buf, uint32_t nblocks) {
return BLK_OK;
}
static blk_dev_slot_t *first_disk_slot(void); /* defined below; used here to identify the
* relocation-table owner right after attach */
int blk_subsys_attach_device(struct blkio_dev *dev) {
if (!g.initialized) return BLK_ENODEV;
if (!dev) return BLK_EINVAL;
@@ -578,6 +686,19 @@ int blk_subsys_attach_device(struct blkio_dev *dev) {
g.total_user_lbn += slot->user_blocks;
g.epoch++;
/* Milestone 2h+: load the relocation-exception table from whichever
* disk-backed device is now the canonical owner (first_disk_slot(),
* the same "which device is canonical" answer blk_get_volume_meta()/
* blk_set_volume_meta() already use) -- but only the first time that
* device becomes the owner. A later-attached second disk-backed
* device (e.g. a USB drive attaching after Artemis's own disk) must
* NOT overwrite the already-loaded table with its own (likely empty)
* one. See FABRIC-2.md's design writeup for why "first attached wins"
* is a pragmatic default, not a general multi-primary-device answer. */
if (slot->dev && first_disk_slot() == slot) {
(void) reloc_load_from_disk(slot);
}
log_message(LOG_INFO,
"blk: disk '%s' v2 LBN %u..%u (%u user blocks); "
"devblocks=%llu bam=%u base=%u total=%llu free=%llu",
@@ -636,6 +757,63 @@ int blk_subsys_detach_device(struct blkio_dev *dev) {
return BLK_OK;
}
/* Milestone 2h+ single-block relocation -- see FABRIC-2.md's design
* writeup for the full reasoning. Mechanical primitive only: this
* function does not decide *whether* a relocation should happen (ACL's
* job) or validate that target_lbn is genuinely owned by whoever is
* asking (also ACL's job) -- it just executes one, correctly, once told
* to. */
int blk_subsys_relocate_block(uint32_t home_lbn, uint32_t target_lbn) {
if (!g.initialized) return BLK_ENODEV;
if (home_lbn == target_lbn) return BLK_EINVAL;
/* Refuse re-relocating an already-relocated home_lbn, or relocating
* onto an LBN that's itself someone else's relocation source --
* both would need chain-following this function deliberately doesn't
* support; call blk_subsys_unrelocate()-style bookkeeping (not yet
* needed, not yet built) first if that's ever required. */
for (uint32_t i = 0; i < g.reloc_count; i++) {
if (g.reloc[i].home_lbn == home_lbn || g.reloc[i].home_lbn == target_lbn)
return BLK_EINVAL;
}
if (g.reloc_count >= BLK_RELOC_MAX_ENTRIES) return BLK_ENOMEM;
if (!blk_is_valid(home_lbn) || !blk_is_valid(target_lbn)) return BLK_ERANGE;
/* Stage through a local buffer rather than copying directly from one
* blk_get_buffer() result to another -- obtaining the target buffer
* can trigger a cache eviction (cache_get_slot()'s FIFO shift) that
* silently invalidates a pointer already held into the *same*
* device's cache array, if home_lbn and target_lbn happen to share a
* device. Not a hypothetical: this is exactly the class of stale
* pointer this file's own blk_vm_evict() comment already warns about. */
uint8_t *src = blk_get_buffer(home_lbn, 0);
if (!src) return BLK_EIO;
uint8_t staged[BLK_FORTH_SIZE];
memcpy(staged, src, BLK_FORTH_SIZE);
uint8_t *dst = blk_get_buffer(target_lbn, 1);
if (!dst) return BLK_EIO;
memcpy(dst, staged, BLK_FORTH_SIZE);
if (blk_update(target_lbn) != BLK_OK) return BLK_EIO;
/* Free home_lbn's original backing block -- must happen before the
* redirect is inserted below, while resolve_lbn(home_lbn) still
* resolves to itself; inserting the redirect first would make this
* call free target_lbn instead. */
(void) blk_mark_free(home_lbn);
g.reloc[g.reloc_count].home_lbn = home_lbn;
g.reloc[g.reloc_count].actual_lbn = target_lbn;
g.reloc_count++;
g.epoch++;
(void) reloc_flush_to_disk(first_disk_slot());
log_message(LOG_INFO, "blk: relocated LBN %u -> %u", home_lbn, target_lbn);
return BLK_OK;
}
uint64_t blk_subsys_epoch(void) {
return g.epoch;
}
@@ -685,6 +863,7 @@ int blk_subsys_confirm_format(uint32_t lbn) {
uint8_t *blk_get_buffer(uint32_t block_num, int writable) {
if (!g.initialized) return NULL;
block_num = resolve_lbn(block_num);
/* RAM */
if (block_num < g.ram_user) {
@@ -727,6 +906,7 @@ uint8_t *blk_get_empty_buffer(uint32_t block_num) {
int blk_update(uint32_t block_num) {
if (!g.initialized) return BLK_ENODEV;
block_num = resolve_lbn(block_num);
/* RAM */
if (block_num < g.ram_user) {
@@ -775,6 +955,7 @@ int blk_update(uint32_t block_num) {
int blk_flush(uint32_t block_num) {
if (!g.initialized) return BLK_ENODEV;
if (block_num > 0) block_num = resolve_lbn(block_num); /* 0 is the "flush all" sentinel */
if (block_num > 0) {
if (block_num < g.ram_user) {
@@ -829,6 +1010,7 @@ int blk_flush(uint32_t block_num) {
int blk_is_allocated(uint32_t block_num) {
if (!g.initialized) return BLK_ENODEV;
block_num = resolve_lbn(block_num);
if (block_num < g.ram_user) return BLK_EINVAL;
blk_dev_slot_t *slot = lbn_to_slot(block_num);
if (!slot) return 0;
@@ -837,6 +1019,7 @@ int blk_is_allocated(uint32_t block_num) {
int blk_mark_allocated(uint32_t block_num) {
if (!g.initialized) return BLK_ENODEV;
block_num = resolve_lbn(block_num);
if (block_num < g.ram_user) return BLK_EINVAL;
blk_dev_slot_t *slot = lbn_to_slot(block_num);
if (!slot) return BLK_ERANGE;
@@ -855,6 +1038,7 @@ int blk_mark_allocated(uint32_t block_num) {
int blk_mark_free(uint32_t block_num) {
if (!g.initialized) return BLK_ENODEV;
block_num = resolve_lbn(block_num);
if (block_num < g.ram_user) return BLK_EINVAL;
blk_dev_slot_t *slot = lbn_to_slot(block_num);
if (!slot) return BLK_ERANGE;
@@ -933,6 +1117,7 @@ int blk_set_volume_meta(const blk_volume_meta_t *meta) {
int blk_is_valid(uint32_t block_num) {
if (!g.initialized) return 0;
block_num = resolve_lbn(block_num);
if (block_num < g.ram_user) return 1;
return lbn_to_slot(block_num) ? 1 : 0;
}
@@ -945,6 +1130,7 @@ uint32_t blk_get_total_blocks(void) {
int blk_get_meta(uint32_t block_num, blk_meta_t *meta) {
if (!meta) return BLK_EINVAL;
if (!g.initialized) return BLK_ENODEV;
block_num = resolve_lbn(block_num);
if (block_num < g.ram_user) {
memset(meta, 0, sizeof(*meta));
meta->magic = 0x424C4B5F5354524BULL;
@@ -967,6 +1153,7 @@ int blk_get_meta(uint32_t block_num, blk_meta_t *meta) {
int blk_set_meta(uint32_t block_num, const blk_meta_t *meta) {
if (!meta) return BLK_EINVAL;
if (!g.initialized) return BLK_ENODEV;
block_num = resolve_lbn(block_num);
if (block_num < g.ram_user) return BLK_OK;
blk_dev_slot_t *slot = lbn_to_slot(block_num);
if (!slot) return BLK_ERANGE;