/* 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. */ /** * doe_region.c - Growable per-trial DoE-campaign-summary ring on Artemis's * disk. See starkernel/doe_region.h for the format/interface design. * * Mirrors log_region.c's own read/write/grow/evict shape exactly (same * blk_meta_zone_read()/write() accessor, same control-header CRC * discipline), minus the priority-eviction logic that doesn't apply here * (no level concept for a trial summary -- plain FIFO eviction only). */ #include "starkernel/doe_region.h" #include #include #include "block_subsystem.h" /* blk_meta_zone_read/write, compute_crc64 */ static uint64_t doe_region_ctrl_compute_crc(const doe_region_ctrl_t *ctrl) { size_t crc_span = offsetof(doe_region_ctrl_t, hdr_crc); return compute_crc64((const uint8_t *)ctrl, crc_span); } /* Reads the control header; returns 0 and *out populated only if magic, * version, and CRC all check out. Any other result (blank, foreign, * corrupt, or a read failure) is treated identically by the caller: "not * yet initialized," matching log_region_ctrl_read()'s own discipline. */ static int doe_region_ctrl_read(doe_region_ctrl_t *out) { if (blk_meta_zone_read(DOE_REGION_DEVBLOCK_FROM_TOP_BASE, (uint8_t *)out) != 0) return -1; if (DOE_REGION_GET_MAGIC(out->magic) != (uint32_t)(DOE_REGION_MAGIC & 0xFFFFFFFFull)) return -1; if (DOE_REGION_GET_VERSION(out->magic) != DOE_REGION_VERSION_0) return -1; uint64_t want_crc = doe_region_ctrl_compute_crc(out); if (want_crc != out->hdr_crc) return -1; return 0; } static int doe_region_ctrl_write(doe_region_ctrl_t *ctrl) { ctrl->hdr_crc = doe_region_ctrl_compute_crc(ctrl); return blk_meta_zone_write(DOE_REGION_DEVBLOCK_FROM_TOP_BASE, (const uint8_t *)ctrl) == 0 ? 0 : -1; } static void doe_region_ctrl_init_fresh(doe_region_ctrl_t *ctrl) { memset(ctrl, 0, sizeof(*ctrl)); ctrl->magic = DOE_REGION_PACK(DOE_REGION_VERSION_0); ctrl->devblocks = DOE_REGION_INITIAL_DEVBLOCKS; ctrl->head_slot = 0; ctrl->tail_slot = 0; ctrl->record_count = 0; } /* Reads/writes the devblock holding slot_index (DOE_SLOTS_PER_DEVBLOCK * slots per devblock), one devblock_from_top past the control header for * every DOE_SLOTS_PER_DEVBLOCK slots. */ static uint32_t doe_region_slot_devblock_from_top(uint32_t slot_index) { return DOE_REGION_DEVBLOCK_FROM_TOP_BASE + 1u + (slot_index / DOE_SLOTS_PER_DEVBLOCK); } static int doe_region_write_slot(uint32_t slot_index, const doe_trial_slot_t *slot) { uint8_t devblock_buf[4096]; uint32_t dft = doe_region_slot_devblock_from_top(slot_index); uint32_t slot_in_devblock = slot_index % DOE_SLOTS_PER_DEVBLOCK; /* Read-modify-write: blk_meta_zone_*() only operates at whole-devblock * granularity, and a devblock holds DOE_SLOTS_PER_DEVBLOCK slots, so a * single-slot write must preserve its siblings. A read failure on a * never-yet-written devblock (blank fence content) is not fatal here -- * proceed with a zeroed buffer, matching log_region_write_slot()'s own * discipline. */ if (blk_meta_zone_read(dft, devblock_buf) != 0) { memset(devblock_buf, 0, sizeof(devblock_buf)); } memcpy(devblock_buf + (size_t)slot_in_devblock * DOE_SLOT_SIZE, slot, sizeof(*slot)); return blk_meta_zone_write(dft, devblock_buf) == 0 ? 0 : -1; } int doe_region_append(uint32_t run_id, uint32_t cfg, uint32_t rep, uint32_t nw, uint32_t mode, uint32_t fail_count, uint64_t fleet_k_q48, uint32_t fleet_conserved, uint64_t switch_count_cumulative, const char *isa, uint32_t isa_len) { doe_region_ctrl_t ctrl; if (doe_region_ctrl_read(&ctrl) != 0) { doe_region_ctrl_init_fresh(&ctrl); } uint32_t total_slots = ctrl.devblocks * DOE_SLOTS_PER_DEVBLOCK; if (ctrl.record_count >= total_slots) { if (ctrl.devblocks < DOE_REGION_MAX_DEVBLOCKS) { /* Grow: new slots appear at indices [old_total_slots .. * new_total_slots-1], nothing already written moves -- safe * at any point in the ring's lifecycle (see log_region.c's * own identical reasoning). */ ctrl.devblocks += DOE_REGION_GROWTH_INCREMENT; if (ctrl.devblocks > DOE_REGION_MAX_DEVBLOCKS) ctrl.devblocks = DOE_REGION_MAX_DEVBLOCKS; total_slots = ctrl.devblocks * DOE_SLOTS_PER_DEVBLOCK; } if (ctrl.record_count >= total_slots) { /* Still full (growth ceiling already reached) -- plain FIFO * eviction, no priority concept for a trial summary. */ ctrl.head_slot = (ctrl.head_slot + 1u) % total_slots; ctrl.record_count--; } } doe_trial_slot_t slot; memset(&slot, 0, sizeof(slot)); slot.fleet_k_q48 = fleet_k_q48; slot.switch_count_cumulative = switch_count_cumulative; slot.run_id = run_id; slot.cfg = cfg; slot.rep = rep; slot.nw = nw; slot.mode = mode; slot.fail_count = fail_count; slot.fleet_conserved = fleet_conserved; uint32_t isa_n = isa_len; if (isa_n > DOE_SLOT_ISA_MAX) isa_n = DOE_SLOT_ISA_MAX; if (isa && isa_n) memcpy(slot.isa, isa, isa_n); if (doe_region_write_slot(ctrl.tail_slot, &slot) != 0) return -1; ctrl.tail_slot = (ctrl.tail_slot + 1u) % total_slots; if (ctrl.record_count < total_slots) ctrl.record_count++; return doe_region_ctrl_write(&ctrl) == 0 ? 0 : -1; }