Module storage_controller_rtl 

storage_controller — the deterministic NAND storage controller (the storage analog of super::dram).

The memory controller proves that timing can be guaranteed: DRAM timing is deterministic by spec, so the compiler schedules a command stream, an independent checker proves it legal, and a device model delivers exactly the promised beat cycles — zero jitter, refresh co-scheduled and never a surprise. Storage looks impossible at first because a commodity SSD’s FTL runs garbage-collection / wear-leveling / erase reactively and hidden (that is SSD tail latency). The fix is the SAME move as DRAM refresh: make every reactive background event a SCHEDULED event the compiler owns. That requires HOST-MANAGED flash (NVMe ZNS / open-channel): append-only zones (no device-side GC surprise) and an exposed channel×die geometry (schedulable parallelism), so a host-scheduled block erase is the flash analog of REFpb.

This module makes that a checked, executable fact:

• FlashTimings — a ZNS-TLC-class timing table (one struct of DATA, so the flash architect’s corrections drop in as numbers, not code); • schedule_zoned — the compile-time command scheduler: zone/gather/reset descriptors → a fully TIMED NAND command stream, die-interleaved and channel- striped, with block erases placed into idle die windows (never displacing a read); • check_legal_flash — an INDEPENDENT per-command legality checker (per-die busy serialization, per-channel data-bus occupancy, tR / tPROG / tBERS) — the scheduler never grades its own homework; • FlashDeviceModel — a die/channel-state device that EXECUTES a timed stream and reports every read’s completion cycle: the zero-jitter fact is planned == executed; • execute_with_suspend / black_box_execute — the Tier-B (bounded, erase- suspend) and Tier-C (black-box reactive FTL) executors that prove the determinism ladder: bounded jitter under a budgeted suspend, and the IMPOSSIBILITY of any static guarantee once reclamation timing is not host-owned.

Everything is a pure function of its inputs — deterministic by construction, like the rest of the stack, and the certified-SAT tR / erase-collision obligations live in the test battery beside the executor RTL.

Structs

FlashCmd

One timed NAND command. chan is the shared data-bus this die hangs off; die is the global die index (its own serializing resource).

FlashDeviceModel

Tier A — a die-state DEVICE that SIMULATES the plan and reports each read’s actual completion cycle. It does not trust the plan’s promise: it replays each command against a per-die busy timeline and STALLS a command whose die is not yet free (a read issued into a mid-erase die waits out the erase). So on a legal plan the simulated beats equal planned_read_beats EXACTLY (zero jitter, cross-checked against the promise), and on an illegal plan they DIVERGE — the device is an independent collision detector, not an echo.

FlashTimings

ZNS-TLC-class NAND timing + geometry, in CONTROLLER CLOCK CYCLES. Engineering-realistic ratios (read : program : erase ≈ 1 : 10 : 100); the table is DATA for the flash architect to correct, and every measurement re-derives from it.

Gather

The random tail: explicit page reads (a pointer-chase / index lookup).

Placement

A zone’s DIE WINDOW. Real ZNS zones occupy a subset of the dies, so reads on one zone and a reset on a DISJOINT zone can run CONCURRENTLY without ever colliding — the system-level form of “GC is free”. Placement::full is the classic all-dies stripe.

TimedCmd

A command with its planned issue cycle. The PLAN is the artifact: the certified SAT proves windows of it timing-legal, and the executor RTL runs it in order.

Utilization

The measured outcome of a plan.

ZoneDesc

A compile-time transfer descriptor — the vocabulary the static schedule hands to the storage edge: count consecutive pages from global page base_page, read or programmed.

ZoneReset

A host-scheduled zone reset: erase every die’s block backing the zone — the reclamation event, placed into idle windows by the scheduler (the REFpb analog).

Enums

FlashOp

One NAND operation on a die.

VisitOrder

How the access list is ordered into the plan.

Functions

black_box_execute

Tier C — the black-box SSD: a HIDDEN FTL fires an un-suspendable erase on victim_die just before the victim_read-th read (0-based, over reads only), so that read stalls behind the full tBERS. Returns each read’s completion cycle. This models what a commodity drive does; the point is that a read now BLOWS its latency bound — proving no static guarantee survives once reclamation timing is not host-owned.

check_legal_flash

The INDEPENDENT legality checker — a total function over the plan, sharing no code with the scheduler. Verifies per-die serialization (a die runs one op at a time, so a read is never issued while its die is mid-erase — the collision the whole design avoids) and per-channel data-bus disjointness. A die’s ops arrive in issue order, so a running watermark is exact; a read’s data-out is DELAYED by tR (sense first), so its bus window need not align with issue order — the channel is checked by interval disjointness, not a watermark. First violation as Err(description).

delta_encode

Encode a timed plan as executor words: [delta:24][op:3][chan:5][die:8][pad:24]. delta = cycles after the PREVIOUS command (first word: cycles after reset). op: 0=Read 1=Program 2=Erase.

emit_storage_controller_testbench

A self-checking testbench: a ROM of REAL plan words (from delta_encode) drives the executor; the bench asserts every issue arrives IN ORDER with the exact op/chan/die of its word, AND that the hardware honors the compiled TIMING — the clk-cycle gap between two consecutive issues exceeds the command’s own delta by a FIXED pipeline overhead (so every compiled inter-command interval is reproduced exactly, not just the order). Prints PASS/FAIL.

emit_storage_controller_verilog

The dumb in-order executor: a countdown FSM. It loads the next word, waits exactly delta cycles, strobes the command pins, and acks the word — in arrival order, by construction (there is no other datapath). cmd_ack pulses on CONSUME (load), so the producer’s read index advances immediately (the classic handshake-latency trap avoided, exactly as in dram_executor).

execute_with_suspend

Tier B — an executor that lets a read PREEMPT an in-progress erase on its die, paying a bounded suspend_window instead of the full tBERS, then resuming the erase. Returns each read’s completion cycle; every read stays within FlashTimings::read_latency_bound.

gather_delivery_order

For a pure read gather, the order in which the requested pages’ data arrives — indices into pages, sorted by delivery beat (ties broken by issue order). Near-storage compute consumes beats in THIS order, so a reduction fed at the storage edge (merge-on-ingest, scan, hash) must be SOUND under it: the die-interleave that saturates the bus reorders the stream, so only order-invariant reductions (a CRDT join, a commutative fold) are safe here.

map_page

Global page → (channel, die): consecutive pages rotate across ALL dies so a sequential stream interleaves — one die senses while the next streams data, and idle dies are free to erase. A compile-time-known mapping the schedule depends on.

measure

planned_read_beats

Planned read-completion cycles straight from the plan (what the compiler promises).

schedule_placed

Placement-aware scheduler: each read/program stream and each reset targets a die WINDOW (Placement). A reset on a window DISJOINT from the read window runs concurrently with the reads and provably cannot collide with them — concurrent, zero-jitter reclamation.

schedule_zoned

The compile-time scheduler (full-stripe placement): read/program streams laid down die- interleaved and channel-striped, then reset erases placed into each die’s trailing idle window. Returns the timed plan, time-sorted.

standard_report

The standard measurement scenarios — kernel-shaped storage traffic, each checked legal and measured. Returns a stable JSON document (pure function of the timing table) — the benchmarks/results/storage_sim.json artifact the handout cites.