# logicaffeine_compile > The LOGOS compiler: type checking, the optimizer, the interpreter and bytecode VM, and the Rust, C, WASM, RISC-V, CUDA and hardware backends Every public module and item of `logicaffeine_compile`, module by module, each with its one-line summary and its address. Item pages hold the full signature, documentation, trait implementations and a link to the source. - Crate page: [logicaffeine_compile](https://docs.logicaffeine.com/logicaffeine_compile/) - All items on one page: [logicaffeine_compile/all](https://docs.logicaffeine.com/logicaffeine_compile/all) - Source: [src/logicaffeine_compile/lib.rs](https://docs.logicaffeine.com/src/logicaffeine_compile/lib.rs) - Every crate: [llms.txt](https://docs.logicaffeine.com/llms.txt) ## logicaffeine_compile - [mod accel](https://docs.logicaffeine.com/logicaffeine_compile/accel/): The accelerator backends’ shared framework: the analog plane, the Plasticine PCU mesh and the SambaNova RDU all run a program the same way, as a host program with device regions. - [mod analysis](https://docs.logicaffeine.com/logicaffeine_compile/analysis/): Compile-time analysis passes for the LOGOS compilation pipeline. - [mod aot_unsupported](https://docs.logicaffeine.com/logicaffeine_compile/aot_unsupported/): The ops no single-device AOT backend can run — concurrency, virtual-time scheduling, and networking — classified once so the device tiers (Tenstorrent baby core, one CUDA kernel launch) cannot drift apart on their refusal set. - [mod arena](https://docs.logicaffeine.com/logicaffeine_compile/arena/) - [mod arena_ctx](https://docs.logicaffeine.com/logicaffeine_compile/arena_ctx/) - [mod ast](https://docs.logicaffeine.com/logicaffeine_compile/ast/): Abstract Syntax Tree types for both logical expressions and imperative statements. - [mod bringup](https://docs.logicaffeine.com/logicaffeine_compile/bringup/): Model bring-up: a checkpoint’s one program, lowered by every chip that runs it. - [mod codegen](https://docs.logicaffeine.com/logicaffeine_compile/codegen/): Code generation from LOGOS AST to Rust source code. - [mod codegen_ana](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/): LOGOS → analog spatial fabric (FPAA-style mixed-signal coprocessor) — the analog lane. - [mod codegen_c](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/) - [mod codegen_cuda](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/): LOGOS → CUDA AOT codegen tier. Emits ONE self-contained CUDA program — a `__global__` kernel that runs a whole LOGOS program on a single GPU thread, plus a host orchestrator — for the integer/bool scalar fragment of the language. - [mod codegen_dram](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/): codegen_dram — the DRAM compute-in-memory target (ComputeDRAM bulk bitwise + RowClone). - [mod codegen_mx](https://docs.logicaffeine.com/logicaffeine_compile/codegen_mx/): LOGOS → mixed-signal XPU — the unification of the digital whole-program engine (`crate::codegen_sva`’s wprog engine, exact ≡VM) and the analog plane (`crate::codegen_ana`, ε-certified floats / ½-grid-certified-exact integers). - [mod codegen_riscv](https://docs.logicaffeine.com/logicaffeine_compile/codegen_riscv/): LOGOS → RISC-V AOT codegen tier. Lowers the register bytecode `CompiledProgram` — the SAME IR the WASM backend and the Silicon ISA emitter consume — to RV64GC assembly text (SysV lp64d ABI, glibc), which a RISC-V GCC assembles+links and `qemu-user` runs, byte-for-byte identical to the VM. - [mod codegen_sass](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/): codegen_sass — the foundation of our OWN sm_86 SASS assembler (the MaxAs / turingas lever). - [mod codegen_sva](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/): SVA/PSL Code Generation for Hardware Verification - [mod codegen_tt](https://docs.logicaffeine.com/logicaffeine_compile/codegen_tt/): LOGOS → Tenstorrent (TT-Metalium) AOT codegen tier. Emits a complete single-Tensix-core TT-Metalium program — a host orchestrator plus a data-movement compute kernel that runs on one baby RISC-V core (`DataMovementProcessor::RISCV_0`) — for the scalar-compute fragment of the benchmark suite. - [mod compile](https://docs.logicaffeine.com/logicaffeine_compile/compile/): LOGOS Compilation Pipeline - [mod concurrency](https://docs.logicaffeine.com/logicaffeine_compile/concurrency/): Concurrency determinacy model + classifier. - [mod crypto_accel](https://docs.logicaffeine.com/logicaffeine_compile/crypto_accel/): Native SHA-256 / HMAC-SHA256 / PBKDF2-HMAC-SHA256, byte-identical to the pure-LOGOS reference in `assets/std/crypto.lg`. - [mod debug](https://docs.logicaffeine.com/logicaffeine_compile/debug/): The bytecode debugger bridge — drives the LOGOS VM one op at a time for the Studio debug drawer, with breakpoints, step-over / step-out, and time-travel (step backwards through executed ops). Single-task, bytecode tier (`tier: None`) so granularity is exactly one op and behaviour is identical to a normal run. - [mod debug_session](https://docs.logicaffeine.com/logicaffeine_compile/debug_session/): W11 — `DebugSession`: the one seam the DAP adapter and the Studio drawer both sit on. - [mod diagnostic](https://docs.logicaffeine.com/logicaffeine_compile/diagnostic/): Diagnostic bridge for translating Rust errors to LOGOS. - [mod drs](https://docs.logicaffeine.com/logicaffeine_compile/drs/): Discourse Representation Structure (DRS) for anaphora resolution and scope tracking. - [mod error](https://docs.logicaffeine.com/logicaffeine_compile/error/): Error types and display formatting for parse errors. - [mod extraction](https://docs.logicaffeine.com/logicaffeine_compile/extraction/): Program extraction from kernel terms to Rust. - [mod formatter](https://docs.logicaffeine.com/logicaffeine_compile/formatter/): Output formatters for logical expressions. - [mod frame_eval](https://docs.logicaffeine.com/logicaffeine_compile/frame_eval/): FrameEval — evaluate a LOGOS expression against a paused frame’s bindings. - [mod intern](https://docs.logicaffeine.com/logicaffeine_compile/intern/) - [mod interpreter](https://docs.logicaffeine.com/logicaffeine_compile/interpreter/): Tree-walking interpreter for LOGOS imperative code. - [mod lexer](https://docs.logicaffeine.com/logicaffeine_compile/lexer/): Two-stage lexer for LOGOS natural language input. - [mod loader](https://docs.logicaffeine.com/logicaffeine_compile/loader/): Module loader for multi-file LOGOS projects. - [mod model](https://docs.logicaffeine.com/logicaffeine_compile/model/): Models as data. A checkpoint’s own metadata describes its architecture (`spec`); this module reads it — a GGUF file (`gguf`), or a Hugging Face directory of safetensors shards in place (`hf`, `safetensors`) —, dequantizes its weights in every format a model ships in (`quant`), tokenizes text as the checkpoint’s vocabulary does (`tokenizer`), hashes Qwen3.8-Flash-Next’s n-gram embedding rows (`ngram_hash`), writes what it computes as a LOGOS program (`author`) whose weights it binds to the checkpoint’s tensors (`bind`) as the layout its arms read presents them (`layout`), names each cut of that one program every backend lowers (`program`), and evaluates that computation in `f64` as the oracle every lane is measured against (`reference`). - [mod monomorphize](https://docs.logicaffeine.com/logicaffeine_compile/monomorphize/): Monomorphization: a generic program rewritten into the concrete program it stands for, for the tiers with no generics of their own. - [mod mwe](https://docs.logicaffeine.com/logicaffeine_compile/mwe/): Multi-Word Expression (MWE) processing. - [mod observe](https://docs.logicaffeine.com/logicaffeine_compile/observe/): The observation channel’s emission buffer. When an observation statement (`Note`/`Warn`/`Record`) executes, it emits a structured `ObsEvent` to a per-run thread-local buffer, drained by sinks (the in-memory test sink today; console and wire in Wave 16). This is the SEPARATE observation channel (D0.1) — it never touches program output. - [mod optimization](https://docs.logicaffeine.com/logicaffeine_compile/optimization/): The registry of compiler optimization toggles. - [mod optimize](https://docs.logicaffeine.com/logicaffeine_compile/optimize/) - [mod page_host](https://docs.logicaffeine.com/logicaffeine_compile/page_host/): One driver, several page tiers. - [mod parser](https://docs.logicaffeine.com/logicaffeine_compile/parser/): Recursive descent parser for natural language to first-order logic. - [mod program_bindings](https://docs.logicaffeine.com/logicaffeine_compile/program_bindings/): Program bindings on the tiers that compile a program ahead of time. - [mod registry](https://docs.logicaffeine.com/logicaffeine_compile/registry/) - [mod repl](https://docs.logicaffeine.com/logicaffeine_compile/repl/): `ReplSession` — the replay-based interactive session behind `largo repl` (and any future notebook surface). - [mod replay](https://docs.logicaffeine.com/logicaffeine_compile/replay/): The `.replay` failure artifact. - [mod semantics](https://docs.logicaffeine.com/logicaffeine_compile/semantics/): The shared semantics kernel. - [mod sourcemap](https://docs.logicaffeine.com/logicaffeine_compile/sourcemap/): Source map for the diagnostic bridge. - [mod spatial](https://docs.logicaffeine.com/logicaffeine_compile/spatial/): The spatial IR — the one program every spatial backend lowers FROM. - [mod style](https://docs.logicaffeine.com/logicaffeine_compile/style/) - [mod tensor_graph](https://docs.logicaffeine.com/logicaffeine_compile/tensor_graph/): The tensor graph — programs as tensor ops, and the transforms over them. - [mod tensor_recognize](https://docs.logicaffeine.com/logicaffeine_compile/tensor_recognize/): Backend-neutral tensor-op recognition (LOGOS AST → typed specs), shared by every codegen backend. Backend-agnostic tensor-op recognition — LOGOS AST -> typed op specs, shared by every codegen backend. - [mod testrun](https://docs.logicaffeine.com/logicaffeine_compile/testrun/): The `largo test` runner core. - [mod token](https://docs.logicaffeine.com/logicaffeine_compile/token/): Token types for the LOGOS lexer and parser. - [mod ui_bridge](https://docs.logicaffeine.com/logicaffeine_compile/ui_bridge/): UI bridge for web interface integration. - [mod vm](https://docs.logicaffeine.com/logicaffeine_compile/vm/): Register bytecode VM. - [mod web_host](https://docs.logicaffeine.com/logicaffeine_compile/web_host/): The browser host for a LOGOS→WASM DOM app — shared by the CLI (`largo emit wasm-dom` / `largo serve`) and the web Studio’s live preview so both render a LOGOS app identically. It supplies the real DOM behind the `dom_*` imports, allocates host `Text` into linear memory, and fires event/fetch callbacks through the exported `__logos_call_closure` trampoline (the production analog of the test `MockDom`). It also carries the default theme, the favicon, and the build-error overlay so a fresh LOGOS web app is beautiful — and legible when it breaks — with zero CSS written. - [struct Arena](https://docs.logicaffeine.com/logicaffeine_compile/struct.Arena): An owning arena for stable references. - [struct AstContext](https://docs.logicaffeine.com/logicaffeine_compile/struct.AstContext): Collection of typed arenas for AST allocation during parsing. - [struct DiscoveryPass](https://docs.logicaffeine.com/logicaffeine_compile/struct.DiscoveryPass): Discovery pass that scans tokens before main parsing to build a TypeRegistry. - [struct Interner](https://docs.logicaffeine.com/logicaffeine_compile/struct.Interner): A string interner providing O(1) equality comparison via `Symbol` handles. - [struct Lexer](https://docs.logicaffeine.com/logicaffeine_compile/struct.Lexer) - [struct ParseError](https://docs.logicaffeine.com/logicaffeine_compile/struct.ParseError): A parse error with location information. - [struct Parser](https://docs.logicaffeine.com/logicaffeine_compile/struct.Parser) - [struct PolicyRegistry](https://docs.logicaffeine.com/logicaffeine_compile/struct.PolicyRegistry): Registry for security policies defined in `## Policy` blocks. - [struct Symbol](https://docs.logicaffeine.com/logicaffeine_compile/struct.Symbol): A lightweight handle to an interned string. - [struct SymbolRegistry](https://docs.logicaffeine.com/logicaffeine_compile/struct.SymbolRegistry): Registry for mapping words to FOL variable names. - [struct TypeRegistry](https://docs.logicaffeine.com/logicaffeine_compile/struct.TypeRegistry) - [enum PolicyCondition](https://docs.logicaffeine.com/logicaffeine_compile/enum.PolicyCondition): Condition in a policy definition. Represents the predicate logic for security rules. - [trait SymbolEq](https://docs.logicaffeine.com/logicaffeine_compile/trait.SymbolEq): Convenience trait for comparing a `Symbol` to a string literal. ## logicaffeine_compile::accel The accelerator backends’ shared framework: the analog plane, the Plasticine PCU mesh and the SambaNova RDU all run a program the same way, as a host program with device regions. - [mod c_model](https://docs.logicaffeine.com/logicaffeine_compile/accel/c_model/): The executable device model as C: what the host binary links and calls when it runs on a machine that has no accelerator. - [mod cells](https://docs.logicaffeine.com/logicaffeine_compile/accel/cells/): Each region cell as a lane routine: the fabric’s checked 64-bit semantics (`AluOp`/`FuncUnit`/`CmpKind::eval_checked`) realized at a device’s lane shape by the multi-word core and the softfloat. - [mod int64](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/): The VM’s 64-bit integer operations on narrow lanes: each is the checked semantics of `fabric_rtl::{AluOp, FuncUnit, CmpKind}::eval_checked`, built from the multi-word core. A result that leaves `i64`, a zero divisor or an exponent the VM refuses is reported in the fault word as the divergence’s code, never as a wrapped value. - [mod lane](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/): The lane machine: what a device’s integer datapath can actually do, at the width it actually has. - [mod multiword](https://docs.logicaffeine.com/logicaffeine_compile/accel/multiword/): The multi-word integer core: every wider-than-a-word integer operation, built once from lane operations and parameterized by the lane shape. - [mod region](https://docs.logicaffeine.com/logicaffeine_compile/accel/region/): Regions: the functions an accelerator runs, as control-flow graphs over checked cells. - [mod softfloat](https://docs.logicaffeine.com/logicaffeine_compile/accel/softfloat/): IEEE-754 binary64 on integer lanes: the VM’s `Float` arithmetic, exact to the bit, for devices whose silicon has no binary64 unit. ## logicaffeine_compile::accel::c_model The executable device model as C: what the host binary links and calls when it runs on a machine that has no accelerator. - [fn model_c](https://docs.logicaffeine.com/logicaffeine_compile/accel/c_model/fn.model_c): The model translation unit for `regions` (each with its host-side region number) on a device whose lanes are `shape`: every routine the regions use, every region, and the `logos_dev_call` driver with its accounting. `device` names the device in the accounting line. - [fn region_c](https://docs.logicaffeine.com/logicaffeine_compile/accel/c_model/fn.region_c): C for a region at `shape`: `static int (const int64_t *args, int64_t *out, uint32_t *fault)`, returning 1 with `*out` set, or 0 with `*fault` the divergence code. - [fn routine_c](https://docs.logicaffeine.com/logicaffeine_compile/accel/c_model/fn.routine_c): C for one lane routine: `static void (const uint32_t *in, uint32_t *out)`. Its register file is a local that starts at zero on every call, as the lane interpreter’s does, so a call depends on nothing but its inputs and the model is reentrant. - [fn routine_symbol](https://docs.logicaffeine.com/logicaffeine_compile/accel/c_model/fn.routine_symbol): The C symbol of `op`’s routine at `shape`. ## logicaffeine_compile::accel::cells Each region cell as a lane routine: the fabric’s checked 64-bit semantics (`AluOp`/`FuncUnit`/`CmpKind::eval_checked`) realized at a device’s lane shape by the multi-word core and the softfloat. - [enum CellOp](https://docs.logicaffeine.com/logicaffeine_compile/accel/cells/enum.CellOp): What a cell computes. - [fn all_ops](https://docs.logicaffeine.com/logicaffeine_compile/accel/cells/fn.all_ops): Every cell op, in a fixed order. - [fn build](https://docs.logicaffeine.com/logicaffeine_compile/accel/cells/fn.build): Build `op`’s routine at `shape`. - [fn routine](https://docs.logicaffeine.com/logicaffeine_compile/accel/cells/fn.routine): `op`’s routine at `shape`, built once per process. ## logicaffeine_compile::accel::int64 The VM’s 64-bit integer operations on narrow lanes: each is the checked semantics of `fabric_rtl::{AluOp, FuncUnit, CmpKind}::eval_checked`, built from the multi-word core. A result that leaves `i64`, a zero divisor or an exponent the VM refuses is reported in the fault word as the divergence’s code, never as a wrapped value. - [const FAULT_BITS](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/constant.FAULT_BITS): The bits of a routine’s fault word: 0, or a `Divergence` code. - [fn add](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.add): `a + b`, faulting where the VM promotes. - [fn bool64](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.bool64): A 0/1 predicate as a 64-bit value. - [fn div](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.div): `a / b` truncating, as the VM’s `Div` on two `Int`s. - [fn fault_when](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.fault_when): A fault word that is `d`’s code when `cond` is 1, else `otherwise`. - [fn floor_div](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.floor_div): `a // b` rounding toward negative infinity, as the VM’s `FloorDiv` on two `Int`s. - [fn magnitude](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.magnitude): `(|a|, sign)` of a two’s-complement value; `|MIN|` is `2^63`, exact in the unsigned width. - [fn mul](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.mul): `a × b`, faulting where the VM promotes. - [fn mul_checked](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.mul_checked): The signed product of two 64-bit values and 1 when it leaves `i64`. - [fn mul_hi_u](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.mul_hi_u): The high word of the unsigned 128-bit product. - [fn mul_ovf_s](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.mul_ovf_s): 1 when the signed product leaves `i64`, as a 64-bit value. - [fn n64](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.n64): The words of a 64-bit value on this builder’s lanes. - [fn nfault](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.nfault): The fault words of this builder’s lanes. - [fn no_fault](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.no_fault): No fault. - [fn popcount](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.popcount): The set bits of the 64-bit pattern, as a 64-bit value. - [fn pow](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.pow): `a ** b` by square-and-multiply over the exponent’s 32 bits, on magnitudes: a factor that overflowed counts only when a later set exponent bit multiplies it in, which is exactly when the VM’s exact power leaves `i64`. - [fn rem](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.rem): `a % b` taking the dividend’s sign, as the VM’s `Mod` on two `Int`s. - [fn shl](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.shl): `a.wrapping_shl(b as u32)`. - [fn shr](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.shr): `a.wrapping_shr(b as u32)` on the signed value (arithmetic). - [fn sub](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.sub): `a − b`, faulting where the VM promotes. - [fn ushr](https://docs.logicaffeine.com/logicaffeine_compile/accel/int64/fn.ushr): `(a as u64).wrapping_shr(b as u32)` (logical). ## logicaffeine_compile::accel::lane The lane machine: what a device’s integer datapath can actually do, at the width it actually has. - [struct ExactLanes](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/struct.ExactLanes): Exact digital lanes: the units a PCU or an RDU lane has, at their declared width. - [struct LInst](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/struct.LInst): An instruction: an operation and the register(s) it writes. `dst2` is the carry/borrow of `Add`/`Sub`. - [struct LaneCounts](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/struct.LaneCounts): How many of each kind of lane operation a run performed: the cost a device pays for a routine. - [struct LaneShape](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/struct.LaneShape): The integer datapath a device has: `word`-bit words (a power of two dividing 32), and a multiplier whose `mul`-bit operands give a product that fits one word (`2 × mul ≤ word`, `mul` dividing `word`). - [struct Routine](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/struct.Routine): A lane routine: its inputs and outputs as registers, its body, and the register file size. - [enum LOp](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/enum.LOp): One lane operation. Operands are registers; results are words, carries and predicates are 0 or 1. - [enum LStmt](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/enum.LStmt): A statement: an instruction, or a body repeated a fixed number of times (registers carry across trips). - [enum LaneFault](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/enum.LaneFault): Why a routine could not run: a builder bug the interpreter refuses to paper over. - [trait Lanes](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/trait.Lanes): A device’s datapath executing lane operations. The arithmetic ones are where devices differ (exact digital units, or the analog plane settling a column); the rest are the digital side of every device. - [fn join_u64](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/fn.join_u64): Join little-endian words back into a 64-bit value (words past bit 63 are ignored). - [fn join_u128](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/fn.join_u128): Join little-endian words into a 128-bit value. - [fn run](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/fn.run): Run `routine` on `lanes` with `inputs` (one word per input register); the output words, and what it cost. - [fn split_u64](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/fn.split_u64): Split a 64-bit value into `n` little-endian words of `shape.word` bits. - [fn split_u128](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/fn.split_u128): Split a 128-bit value into `n` little-endian words. - [type LReg](https://docs.logicaffeine.com/logicaffeine_compile/accel/lane/type.LReg): A lane register: one word of the device’s datapath. ## logicaffeine_compile::accel::multiword The multi-word integer core: every wider-than-a-word integer operation, built once from lane operations and parameterized by the lane shape. - [struct Builder](https://docs.logicaffeine.com/logicaffeine_compile/accel/multiword/struct.Builder): The routine under construction. - [struct Mw](https://docs.logicaffeine.com/logicaffeine_compile/accel/multiword/struct.Mw): A multi-word value: little-endian lane registers. ## logicaffeine_compile::accel::region Regions: the functions an accelerator runs, as control-flow graphs over checked cells. - [struct HostReason](https://docs.logicaffeine.com/logicaffeine_compile/accel/region/struct.HostReason): A function the region lowering keeps on the host, and why. - [struct RBlock](https://docs.logicaffeine.com/logicaffeine_compile/accel/region/struct.RBlock) - [struct RegionCfg](https://docs.logicaffeine.com/logicaffeine_compile/accel/region/struct.RegionCfg): A function as a region: its ports, its register file size, its blocks (block 0 is the entry). - [enum Discovered](https://docs.logicaffeine.com/logicaffeine_compile/accel/region/enum.Discovered): What discovery made of one function. - [enum Halt](https://docs.logicaffeine.com/logicaffeine_compile/accel/region/enum.Halt): Why a region run stopped short of a value. - [enum Kind](https://docs.logicaffeine.com/logicaffeine_compile/accel/region/enum.Kind): The value kinds a region carries across its boundary and between its cells. - [enum RStmt](https://docs.logicaffeine.com/logicaffeine_compile/accel/region/enum.RStmt): One statement of a region block. - [enum RTerm](https://docs.logicaffeine.com/logicaffeine_compile/accel/region/enum.RTerm): Where a block goes. - [fn discover](https://docs.logicaffeine.com/logicaffeine_compile/accel/region/fn.discover): Every function of `program`, each a region or a host reason; `names[i]` is function `i`’s name. - [fn lower](https://docs.logicaffeine.com/logicaffeine_compile/accel/region/fn.lower): Lower function `fi` of `program` to a region, or name why it stays on the host. - [type VReg](https://docs.logicaffeine.com/logicaffeine_compile/accel/region/type.VReg): A region register: one 64-bit value (an `Int`, a `Bool` as 0/1, a `Float` as its bit pattern). ## logicaffeine_compile::accel::softfloat IEEE-754 binary64 on integer lanes: the VM’s `Float` arithmetic, exact to the bit, for devices whose silicon has no binary64 unit. - [struct Unpacked](https://docs.logicaffeine.com/logicaffeine_compile/accel/softfloat/struct.Unpacked): A binary64 operand taken apart. - [const DEFAULT_NAN](https://docs.logicaffeine.com/logicaffeine_compile/accel/softfloat/constant.DEFAULT_NAN): The x86 default NaN an invalid operation produces. - [fn abs](https://docs.logicaffeine.com/logicaffeine_compile/accel/softfloat/fn.abs): `|x|`. - [fn add](https://docs.logicaffeine.com/logicaffeine_compile/accel/softfloat/fn.add): `a + b` (`negate_b` makes it `a − b`). - [fn approx_eq_ints](https://docs.logicaffeine.com/logicaffeine_compile/accel/softfloat/fn.approx_eq_ints): The VM’s `is approximately` on two integers: both converted to `f64`, equal, or apart by at most `max(1e-9 · max(|a|, |b|), 1e-12)`. - [fn compare](https://docs.logicaffeine.com/logicaffeine_compile/accel/softfloat/fn.compare): The IEEE comparisons as 0/1: `(a < b, a ≤ b, a == b)`. NaN compares false; `−0 == +0`. - [fn div](https://docs.logicaffeine.com/logicaffeine_compile/accel/softfloat/fn.div): `a ÷ b`. A zero divisor yields the IEEE result (∞, or NaN for `0 ÷ 0`); the VM’s failure there is the cell’s divergence, reported beside this value. - [fn floor_to_int](https://docs.logicaffeine.com/logicaffeine_compile/accel/softfloat/fn.floor_to_int): `f.floor() as i64`: NaN is 0, and the conversion saturates at the `i64` bounds. - [fn from_int](https://docs.logicaffeine.com/logicaffeine_compile/accel/softfloat/fn.from_int): `i64 as f64`, nearest-even. - [fn mul](https://docs.logicaffeine.com/logicaffeine_compile/accel/softfloat/fn.mul): `a × b`. - [fn round_pack](https://docs.logicaffeine.com/logicaffeine_compile/accel/softfloat/fn.round_pack): Round `sig × 2^(exp − 62)` to binary64, nearest-even, and pack it with `sign`. `sig` has its leading bit at 62 (a nonzero significand), with any lost low bits folded into bit 0 as a sticky bit. The one rounding every operation performs: normal results, gradual underflow to subnormals, and overflow to infinity. - [fn sqrt](https://docs.logicaffeine.com/logicaffeine_compile/accel/softfloat/fn.sqrt): `√a`. - [fn unpack](https://docs.logicaffeine.com/logicaffeine_compile/accel/softfloat/fn.unpack): Take `x` apart. Subnormals are normalized here, so every finite nonzero operand leaves with its leading significand bit at 52. ## logicaffeine_compile::analysis Compile-time analysis passes for the LOGOS compilation pipeline. - [mod assemble](https://docs.logicaffeine.com/logicaffeine_compile/analysis/assemble/): Source-level assembly of a multi-file / multi-directory LOGOS project. - [mod callgraph](https://docs.logicaffeine.com/logicaffeine_compile/analysis/callgraph/) - [mod check](https://docs.logicaffeine.com/logicaffeine_compile/analysis/check/): Bidirectional type checker for the LOGOS compilation pipeline. - [mod defined_real](https://docs.logicaffeine.com/logicaffeine_compile/analysis/defined_real/): Which functions may define a real number: `the real number whose digits in base 3 are f`, `the real number approximated by f`. - [mod dependencies](https://docs.logicaffeine.com/logicaffeine_compile/analysis/dependencies/) - [mod dimension_check](https://docs.logicaffeine.com/logicaffeine_compile/analysis/dimension_check/): Dimension-aware static analysis — rejects dimension-incoherent quantity arithmetic at COMPILE time, before any code is generated. `2 meters + 1 gram` is a type error, not a runtime panic: a length and a mass have no common dimension, so adding them cannot mean anything. - [mod escape](https://docs.logicaffeine.com/logicaffeine_compile/analysis/escape/): Escape analysis for zone safety. - [mod import_hygiene](https://docs.logicaffeine.com/logicaffeine_compile/analysis/import_hygiene/): Import-hygiene lints — the pit-of-success guardrails that keep a project’s import blocks honest. An UNRESOLVABLE import is already a hard error at assembly (with a “did you mean” suggestion from the loader); this pass finds the problems that ASSEMBLE FINE but are still mistakes: an import that is never used, the same module imported twice, and a module importing itself. - [mod known_calls](https://docs.logicaffeine.com/logicaffeine_compile/analysis/known_calls/): Definition-time resolution of CALLED NAMES — a call to a name that exists NOWHERE in the program is a check error, not a native-build E0425 or a runtime surprise. - [mod liveness](https://docs.logicaffeine.com/logicaffeine_compile/analysis/liveness/) - [mod ownership](https://docs.logicaffeine.com/logicaffeine_compile/analysis/ownership/): Native ownership analysis for use-after-move detection. - [mod pipes](https://docs.logicaffeine.com/logicaffeine_compile/analysis/pipes/): Which function parameters carry a pipe. - [mod policy](https://docs.logicaffeine.com/logicaffeine_compile/analysis/policy/) - [mod readonly](https://docs.logicaffeine.com/logicaffeine_compile/analysis/readonly/) - [mod registry](https://docs.logicaffeine.com/logicaffeine_compile/analysis/registry/) - [mod relay](https://docs.logicaffeine.com/logicaffeine_compile/analysis/relay/): Whether a program’s pages talk to the relay — and so whether the backend serving them answers `/_relay` itself. - [mod tower](https://docs.logicaffeine.com/logicaffeine_compile/analysis/tower/): Which values of a program the exact extension reaches: the bindings, function results and parameters that can hold an infinitesimal, a hyperreal, an infinite integer, an algebraic number, a computable real, an ordinal, a residue-dependent value or a provisional answer. - [mod types](https://docs.logicaffeine.com/logicaffeine_compile/analysis/types/): Type inference pass for the LOGOS compilation pipeline. - [mod unify](https://docs.logicaffeine.com/logicaffeine_compile/analysis/unify/): Unification engine for the bidirectional type checker. - [struct CapabilityDef](https://docs.logicaffeine.com/logicaffeine_compile/analysis/struct.CapabilityDef): A capability definition: `A User can publish the Document if...` - [struct Dependency](https://docs.logicaffeine.com/logicaffeine_compile/analysis/struct.Dependency): A dependency declaration found in the document’s abstract. - [struct DiscoveryPass](https://docs.logicaffeine.com/logicaffeine_compile/analysis/struct.DiscoveryPass): Discovery pass that scans tokens before main parsing to build a TypeRegistry. - [struct DiscoveryResult](https://docs.logicaffeine.com/logicaffeine_compile/analysis/struct.DiscoveryResult): Result of running the discovery pass - [struct FieldDef](https://docs.logicaffeine.com/logicaffeine_compile/analysis/struct.FieldDef): Field definition within a struct - [struct PolicyRegistry](https://docs.logicaffeine.com/logicaffeine_compile/analysis/struct.PolicyRegistry): Registry for security policies defined in `## Policy` blocks. - [struct PredicateDef](https://docs.logicaffeine.com/logicaffeine_compile/analysis/struct.PredicateDef): A predicate definition: `A User is admin if the user's role equals "admin".` - [struct TypeRegistry](https://docs.logicaffeine.com/logicaffeine_compile/analysis/struct.TypeRegistry) - [struct VariantDef](https://docs.logicaffeine.com/logicaffeine_compile/analysis/struct.VariantDef): Phase 33: Variant definition for sum types - [enum FieldType](https://docs.logicaffeine.com/logicaffeine_compile/analysis/enum.FieldType): Type reference for struct fields (avoids circular deps with ast::TypeExpr) - [enum PolicyCondition](https://docs.logicaffeine.com/logicaffeine_compile/analysis/enum.PolicyCondition): Condition in a policy definition. Represents the predicate logic for security rules. - [enum TypeDef](https://docs.logicaffeine.com/logicaffeine_compile/analysis/enum.TypeDef) - [fn discover_with_imports](https://docs.logicaffeine.com/logicaffeine_compile/analysis/fn.discover_with_imports): Recursive discovery with module imports. - [fn first_section_header](https://docs.logicaffeine.com/logicaffeine_compile/analysis/fn.first_section_header): A file’s first `## ` section header outside a ``` fence, as its 1-based line and its text: the line above which an `Import` must stand to import anything. - [fn misplaced_imports](https://docs.logicaffeine.com/logicaffeine_compile/analysis/fn.misplaced_imports): Every `Import` sentence below a file’s first `## ` header, each with its byte span. That is where `scan_dependencies` does not read, so such a sentence imports nothing: the module is never spliced and the program runs on without it. A caller refuses each at its own line. A line inside a - [fn scan_dependencies](https://docs.logicaffeine.com/logicaffeine_compile/analysis/fn.scan_dependencies): Scans the first paragraph (Abstract) of a LOGOS file for `[Alias](URI)` links. ## logicaffeine_compile::analysis::assemble Source-level assembly of a multi-file / multi-directory LOGOS project. - [struct AssembledProgram](https://docs.logicaffeine.com/logicaffeine_compile/analysis/assemble/struct.AssembledProgram): One assembled compilation unit: the combined source plus the metadata later passes need for qualified-name resolution, collision diagnostics, and cross-file error attribution. - [struct DefSite](https://docs.logicaffeine.com/logicaffeine_compile/analysis/assemble/struct.DefSite): A single definition site: which module (canonical path) declared a bare name, and the normalized content of the definition (its identity — two defs with the same normalized body are THE SAME definition). - [struct Located](https://docs.logicaffeine.com/logicaffeine_compile/analysis/assemble/struct.Located): A combined-source offset resolved back to its origin. - [struct Provenance](https://docs.logicaffeine.com/logicaffeine_compile/analysis/assemble/struct.Provenance): Bare-name → the modules that define it. A bare name owned by more than one distinct module is ambiguous: a bare reference to it is a hard error, and the qualified form disambiguates. - [struct ScopeInfo](https://docs.logicaffeine.com/logicaffeine_compile/analysis/assemble/struct.ScopeInfo): Per-file lexical scope for the whole project: what each file is allowed to reference. A file sees its own definitions and the exports of the modules it directly imports — never anything reached only transitively. - [struct Segment](https://docs.logicaffeine.com/logicaffeine_compile/analysis/assemble/struct.Segment): One contributed segment of the combined source: its `[start, end)` byte range in the combined string, the ORIGINAL file it came from, and — for a byte-intact segment — the offset in that file its `start` corresponds to. - [struct SourceMap](https://docs.logicaffeine.com/logicaffeine_compile/analysis/assemble/struct.SourceMap): File-level attribution: for each contributed segment of the combined source, its byte range, originating file, and (for byte-intact segments) the offset-within-file mapping — so a diagnostic on the combined blob is attributed to the user’s own file and line. - [enum DefKind](https://docs.logicaffeine.com/logicaffeine_compile/analysis/assemble/enum.DefKind): The kind of a top-level definition, for collision messages. - [fn assemble_project](https://docs.logicaffeine.com/logicaffeine_compile/analysis/assemble/fn.assemble_project): Assemble the whole project reachable from `entry_path` into one compilation unit. Returns an error only for unreadable/unresolvable imports; the combined source is then parsed by the normal pipeline. - [fn assemble_project_with_deps](https://docs.logicaffeine.com/logicaffeine_compile/analysis/assemble/fn.assemble_project_with_deps): `assemble_project`, additionally linking the declared dependency roots so a bare `Import .` resolves against a `path`/`git`-local package outside the project root. `dep_roots` empty is byte-for-byte identical to `assemble_project`, so a single-project build is unchanged. - [fn check_scopes](https://docs.logicaffeine.com/logicaffeine_compile/analysis/assemble/fn.check_scopes): Enforce per-file scoping over the assembled program: a reference to a name that is another user module’s export, from a file that neither defines nor imports it, is a hard error (no transitive leakage). Builtins, stdlib, and a file’s own/imported names are always fine, so a valid program never trips. ## logicaffeine_compile::analysis::callgraph - [struct CallGraph](https://docs.logicaffeine.com/logicaffeine_compile/analysis/callgraph/struct.CallGraph): Whole-program call graph for the LOGOS compilation pipeline. ## logicaffeine_compile::analysis::check Bidirectional type checker for the LOGOS compilation pipeline. - [struct CallInstance](https://docs.logicaffeine.com/logicaffeine_compile/analysis/check/struct.CallInstance): One call of a generic function, as the checker solved it. - [struct IndexedTypeError](https://docs.logicaffeine.com/logicaffeine_compile/analysis/check/struct.IndexedTypeError): One typechecker finding with the top-level statement it belongs to. - [struct Instantiations](https://docs.logicaffeine.com/logicaffeine_compile/analysis/check/struct.Instantiations): What the checker solved at every generic site of a program — the input to monomorphization. - [struct LocatedTypeError](https://docs.logicaffeine.com/logicaffeine_compile/analysis/check/struct.LocatedTypeError): A type error and the top-level function it was found in — `None` for a `## Main` statement. A checked program has no source spans left (lowering writes functions of its own), so the function is the location a report can give. - [enum Site](https://docs.logicaffeine.com/logicaffeine_compile/analysis/check/enum.Site): A node of the checked program, by address. The checker and a later pass over the SAME statements agree on it without the AST carrying ids. - [fn check_program](https://docs.logicaffeine.com/logicaffeine_compile/analysis/check/fn.check_program): Check a LOGOS program and return a typed `TypeEnv` for codegen. - [fn check_program_collect](https://docs.logicaffeine.com/logicaffeine_compile/analysis/check/fn.check_program_collect): Collect EVERY failing top-level statement instead of bailing at the first. - [fn check_program_located](https://docs.logicaffeine.com/logicaffeine_compile/analysis/check/fn.check_program_located): `check_program`, reporting which top-level function a failure is in. - [fn first_undeclared_type](https://docs.logicaffeine.com/logicaffeine_compile/analysis/check/fn.first_undeclared_type): The first type the program names that nothing supplies, with where it is named: the index of the top-level statement that names it, or `None` for a field of a declared record or variant (a declaration is not a statement). A name is supplied by the registry (a record, enum or alias the program declares or imports, a builtin, an intrinsic generic), by the language itself (`codegen::types::is_language_type_name`, and the dimension words `Quantity of ` takes, `Dimension::by_name`), or as a type parameter the declaration itself introduces. Run on the program the parser returned, whose top-level statements align with its statement spans, so a statement’s refusal is located. A written type counts wherever it stands: a construction, a collection’s element type, an annotation, a typed fetch, a function’s parameters and return type, a record’s or variant’s field types. - [fn infer_instantiations](https://docs.logicaffeine.com/logicaffeine_compile/analysis/check/fn.infer_instantiations): Check `stmts` as far as each statement goes — a failing statement does not stop the rest — and answer what every generic site was solved at. The input to monomorphization; a backend with no generics of its own reads which instance each call and construction needs from here. - [fn root_binding_types](https://docs.logicaffeine.com/logicaffeine_compile/analysis/check/fn.root_binding_types): The type of every binding the program’s ROOT declares, as the checker settled it once the whole program was read. Exact where `TypeEnv` is not: its variables are one flat map, so a function’s own `x` and the program’s `x` share an entry there. ## logicaffeine_compile::analysis::defined_real Which functions may define a real number: `the real number whose digits in base 3 are f`, `the real number approximated by f`. - [fn check](https://docs.logicaffeine.com/logicaffeine_compile/analysis/defined_real/fn.check): The first function the program defines a real number by that cannot define one, refused in words naming it; `Ok` when there is none. ## logicaffeine_compile::analysis::dependencies - [struct Dependency](https://docs.logicaffeine.com/logicaffeine_compile/analysis/dependencies/struct.Dependency): A dependency declaration found in the document’s abstract. - [struct SelectedName](https://docs.logicaffeine.com/logicaffeine_compile/analysis/dependencies/struct.SelectedName): One name selected by a per-name import (`Import double as dbl from Util.`). - [fn first_section_header](https://docs.logicaffeine.com/logicaffeine_compile/analysis/dependencies/fn.first_section_header): A file’s first `## ` section header outside a ``` fence, as its 1-based line and its text: the line above which an `Import` must stand to import anything. - [fn misplaced_imports](https://docs.logicaffeine.com/logicaffeine_compile/analysis/dependencies/fn.misplaced_imports): Every `Import` sentence below a file’s first `## ` header, each with its byte span. That is where `scan_dependencies` does not read, so such a sentence imports nothing: the module is never spliced and the program runs on without it. A caller refuses each at its own line. A line inside a - [fn scan_dependencies](https://docs.logicaffeine.com/logicaffeine_compile/analysis/dependencies/fn.scan_dependencies): Scans the first paragraph (Abstract) of a LOGOS file for `[Alias](URI)` links. ## logicaffeine_compile::analysis::dimension_check Dimension-aware static analysis — rejects dimension-incoherent quantity arithmetic at COMPILE time, before any code is generated. `2 meters + 1 gram` is a type error, not a runtime panic: a length and a mass have no common dimension, so adding them cannot mean anything. - [struct DimensionChecker](https://docs.logicaffeine.com/logicaffeine_compile/analysis/dimension_check/struct.DimensionChecker) - [struct DimensionError](https://docs.logicaffeine.com/logicaffeine_compile/analysis/dimension_check/struct.DimensionError): A dimension coherence error. `trail` names the statements it propagated out through, innermost first — the statement that holds the incoherent arithmetic, then each block statement around it — so a diagnostic can point at the sentence at fault. ## logicaffeine_compile::analysis::escape Escape analysis for zone safety. - [struct EscapeChecker](https://docs.logicaffeine.com/logicaffeine_compile/analysis/escape/struct.EscapeChecker) - [struct EscapeError](https://docs.logicaffeine.com/logicaffeine_compile/analysis/escape/struct.EscapeError): Error type for escape violations - [struct EscapeFinding](https://docs.logicaffeine.com/logicaffeine_compile/analysis/escape/struct.EscapeFinding): Tracks the “zone depth” of variables for escape analysis One escape finding: the top-level statement it belongs to (mapping onto `Parser::stmt_spans()`), and the erring statement with each one around it, innermost first (for `Parser::nested_stmt_spans()`). - [enum EscapeErrorKind](https://docs.logicaffeine.com/logicaffeine_compile/analysis/escape/enum.EscapeErrorKind) ## logicaffeine_compile::analysis::import_hygiene Import-hygiene lints — the pit-of-success guardrails that keep a project’s import blocks honest. An UNRESOLVABLE import is already a hard error at assembly (with a “did you mean” suggestion from the loader); this pass finds the problems that ASSEMBLE FINE but are still mistakes: an import that is never used, the same module imported twice, and a module importing itself. - [struct ImportLint](https://docs.logicaffeine.com/logicaffeine_compile/analysis/import_hygiene/struct.ImportLint): One import-hygiene finding. - [enum ImportLintKind](https://docs.logicaffeine.com/logicaffeine_compile/analysis/import_hygiene/enum.ImportLintKind): What kind of import-hygiene problem was found. - [enum LintSeverity](https://docs.logicaffeine.com/logicaffeine_compile/analysis/import_hygiene/enum.LintSeverity): The severity of an import lint. Warnings never block a build; errors do. - [fn lint_imports](https://docs.logicaffeine.com/logicaffeine_compile/analysis/import_hygiene/fn.lint_imports): Lint the entry file’s imports for unused / duplicate / self-import problems. Unresolvable imports are NOT reported here — the assembler already rejects those with a suggestion. Returns `Err` only if the entry can’t be read. - [fn lint_imports_with_deps](https://docs.logicaffeine.com/logicaffeine_compile/analysis/import_hygiene/fn.lint_imports_with_deps): `lint_imports`, resolving imports with the declared dependency roots so a `path`/`git`-local import is lint-checked too. `dep_roots` empty is identical to `lint_imports`. ## logicaffeine_compile::analysis::known_calls Definition-time resolution of CALLED NAMES — a call to a name that exists NOWHERE in the program is a check error, not a native-build E0425 or a runtime surprise. - [fn check_unknown_calls](https://docs.logicaffeine.com/logicaffeine_compile/analysis/known_calls/fn.check_unknown_calls): Reject the first call (in source order) to a name that exists nowhere in the post-prelude program. See the module docs for the KNOWN-name rule. - [fn check_unknown_calls_with_exports](https://docs.logicaffeine.com/logicaffeine_compile/analysis/known_calls/fn.check_unknown_calls_with_exports): `check_unknown_calls` for the mixed-document seam: `exports` is the callable surface of a bundled proven module (see `proven_module_exports`), whose names the imperative half calls by design (`use proven::*;`). - [fn proven_module_exports](https://docs.logicaffeine.com/logicaffeine_compile/analysis/known_calls/fn.proven_module_exports): The callable surface of a bundled proven module: every `pub fn` name. The Forge emits proven functions, `check_*` predicates, and non-nullary enum constructors all as `pub fn`s (a nullary constructor is a `pub const`, which is an identifier reference, not a call — outside this pass’s domain). - [fn refuse_retired_calls](https://docs.logicaffeine.com/logicaffeine_compile/analysis/known_calls/fn.refuse_retired_calls): The first call, in source order, to a builtin the language no longer has (`crate::semantics::builtins::retired_builtin`), refused in that builtin’s own sentence. A name the program defines or binds is its own and is called. Every tier’s front end runs this before the program runs, so each refuses the call in the same words, whether or not the call is ever reached. ## logicaffeine_compile::analysis::liveness - [struct FunctionLiveness](https://docs.logicaffeine.com/logicaffeine_compile/analysis/liveness/struct.FunctionLiveness): Per-function liveness table. - [struct LivenessResult](https://docs.logicaffeine.com/logicaffeine_compile/analysis/liveness/struct.LivenessResult): Liveness analysis result for a whole program. - [fn stmt_key](https://docs.logicaffeine.com/logicaffeine_compile/analysis/liveness/fn.stmt_key): The key a statement’s liveness is recorded under: its address in the arena the analysis walked. ## logicaffeine_compile::analysis::ownership Native ownership analysis for use-after-move detection. - [struct OwnershipChecker](https://docs.logicaffeine.com/logicaffeine_compile/analysis/ownership/struct.OwnershipChecker): Ownership checker - tracks variable states through control flow - [struct OwnershipError](https://docs.logicaffeine.com/logicaffeine_compile/analysis/ownership/struct.OwnershipError): Error type for ownership violations - [struct OwnershipFinding](https://docs.logicaffeine.com/logicaffeine_compile/analysis/ownership/struct.OwnershipFinding): One ownership finding with its statement coordinates: the top-level statement that ERRED, and (when known) the one that CAUSED it by moving the variable — both map 1:1 onto `Parser::stmt_spans()` — plus the exact statements, nested ones included, for `Parser::nested_stmt_spans()`: `trail` is the erring statement and each one around it, innermost first, and `cause` is the statement that gave the value away. - [enum MaybeGivenIn](https://docs.logicaffeine.com/logicaffeine_compile/analysis/ownership/enum.MaybeGivenIn): Where a value may have been given away: the construct whose paths disagree about it. - [enum OwnershipErrorKind](https://docs.logicaffeine.com/logicaffeine_compile/analysis/ownership/enum.OwnershipErrorKind) - [enum VarState](https://docs.logicaffeine.com/logicaffeine_compile/analysis/ownership/enum.VarState): Ownership state for a variable ## logicaffeine_compile::analysis::pipes Which function parameters carry a pipe. - [fn declare_pipe_params](https://docs.logicaffeine.com/logicaffeine_compile/analysis/pipes/fn.declare_pipe_params): The program with every pipe parameter declared as one: `ch: Real` a pipe parameter becomes `ch: Pipe of Real`, so each site that types a parameter by its declaration sees the pipe. - [fn pipe_params](https://docs.logicaffeine.com/logicaffeine_compile/analysis/pipes/fn.pipe_params): The positions of each function’s pipe parameters; a function with none is absent. ## logicaffeine_compile::analysis::policy - [struct CapabilityDef](https://docs.logicaffeine.com/logicaffeine_compile/analysis/policy/struct.CapabilityDef): A capability definition: `A User can publish the Document if...` - [struct PolicyRegistry](https://docs.logicaffeine.com/logicaffeine_compile/analysis/policy/struct.PolicyRegistry): Registry for security policies defined in `## Policy` blocks. - [struct PredicateDef](https://docs.logicaffeine.com/logicaffeine_compile/analysis/policy/struct.PredicateDef): A predicate definition: `A User is admin if the user's role equals "admin".` - [enum PolicyCondition](https://docs.logicaffeine.com/logicaffeine_compile/analysis/policy/enum.PolicyCondition): Condition in a policy definition. Represents the predicate logic for security rules. ## logicaffeine_compile::analysis::readonly - [struct MutableBorrowParams](https://docs.logicaffeine.com/logicaffeine_compile/analysis/readonly/struct.MutableBorrowParams): Mutable borrow parameter analysis result. - [struct ReadonlyParams](https://docs.logicaffeine.com/logicaffeine_compile/analysis/readonly/struct.ReadonlyParams): Readonly parameter analysis result. ## logicaffeine_compile::analysis::registry - [struct FieldDef](https://docs.logicaffeine.com/logicaffeine_compile/analysis/registry/struct.FieldDef): Field definition within a struct - [struct TypeRegistry](https://docs.logicaffeine.com/logicaffeine_compile/analysis/registry/struct.TypeRegistry) - [struct VariantDef](https://docs.logicaffeine.com/logicaffeine_compile/analysis/registry/struct.VariantDef): Phase 33: Variant definition for sum types - [enum FieldType](https://docs.logicaffeine.com/logicaffeine_compile/analysis/registry/enum.FieldType): Type reference for struct fields (avoids circular deps with ast::TypeExpr) - [enum TypeDef](https://docs.logicaffeine.com/logicaffeine_compile/analysis/registry/enum.TypeDef) - [const BUILTIN_STRUCT_NAMES](https://docs.logicaffeine.com/logicaffeine_compile/analysis/registry/constant.BUILTIN_STRUCT_NAMES): The structs the compiler hands to author code fully formed, rather than one an `## An X has:` declaration writes — the one list `TypeRegistry::with_primitives` registers them from and `TypeRegistry::is_builtin_struct` answers against, so a consumer never has to know their names itself. `crates/logicaffeine_compile/src/vm/wasm/kind.rs`’s `builtin_struct_types()` carries the same two shapes for the wasm backend’s own boundary-type resolution. - [fn builtin_generic_param_count](https://docs.logicaffeine.com/logicaffeine_compile/analysis/registry/fn.builtin_generic_param_count): How many type parameters a BUILT-IN generic takes — the one table the whole compiler asks. ## logicaffeine_compile::analysis::relay Whether a program’s pages talk to the relay — and so whether the backend serving them answers `/_relay` itself. - [fn component_uses_the_relay](https://docs.logicaffeine.com/logicaffeine_compile/analysis/relay/fn.component_uses_the_relay): Whether one declared page, component or store talks to the relay (see `pages_use_the_relay`). - [fn pages_use_the_relay](https://docs.logicaffeine.com/logicaffeine_compile/analysis/relay/fn.pages_use_the_relay): Whether any page, component or store this program declares talks to the relay: a `## Store … shared on`, a `When a message arrives on …` handler, or a `Publish … on …` in any action or handler, at any depth. - [fn source_uses_the_relay](https://docs.logicaffeine.com/logicaffeine_compile/analysis/relay/fn.source_uses_the_relay): `pages_use_the_relay` for a program’s source — a page file a site bundles. A source that does not parse uses nothing (its build refuses it on its own terms). ## logicaffeine_compile::analysis::tower Which values of a program the exact extension reaches: the bindings, function results and parameters that can hold an infinitesimal, a hyperreal, an infinite integer, an algebraic number, a computable real, an ordinal, a residue-dependent value or a provisional answer. - [struct TowerTypes](https://docs.logicaffeine.com/logicaffeine_compile/analysis/tower/struct.TowerTypes): The reached bindings, results and parameters of a program. - [type Scope](https://docs.logicaffeine.com/logicaffeine_compile/analysis/tower/type.Scope): Where a name lives: a function’s body, or the program’s root (`None`). ## logicaffeine_compile::analysis::types Type inference pass for the LOGOS compilation pipeline. - [struct FnSig](https://docs.logicaffeine.com/logicaffeine_compile/analysis/types/struct.FnSig): Function signature for tracked functions. - [struct RustNames](https://docs.logicaffeine.com/logicaffeine_compile/analysis/types/struct.RustNames): Centralized name resolution for Rust identifier output. - [struct TypeEnv](https://docs.logicaffeine.com/logicaffeine_compile/analysis/types/struct.TypeEnv): Type environment built by a forward pass over the AST. - [enum LogosType](https://docs.logicaffeine.com/logicaffeine_compile/analysis/types/enum.LogosType): Structured type representation for LOGOS values. ## logicaffeine_compile::analysis::unify Unification engine for the bidirectional type checker. - [struct TyVar](https://docs.logicaffeine.com/logicaffeine_compile/analysis/unify/struct.TyVar): A type variable used during inference. - [struct TypeScheme](https://docs.logicaffeine.com/logicaffeine_compile/analysis/unify/struct.TypeScheme): A quantified polymorphic type. - [struct TypeScope](https://docs.logicaffeine.com/logicaffeine_compile/analysis/unify/struct.TypeScope): Where the names in a written type are looked up while converting it: the program’s registry (so a user struct or enum is a `UserDefined`, not `Unknown`) and the type parameters in scope, each standing for the type it is currently bound to. - [struct UnificationTable](https://docs.logicaffeine.com/logicaffeine_compile/analysis/unify/struct.UnificationTable): Union-Find table implementing Robinson unification with occurs check. - [enum InferType](https://docs.logicaffeine.com/logicaffeine_compile/analysis/unify/enum.InferType): Inference-time type representation. - [enum TypeError](https://docs.logicaffeine.com/logicaffeine_compile/analysis/unify/enum.TypeError): A type error detected during unification or checking. - [fn infer_to_logos](https://docs.logicaffeine.com/logicaffeine_compile/analysis/unify/fn.infer_to_logos): Convert a zonked `InferType` to `LogosType`. - [fn unify_numeric](https://docs.logicaffeine.com/logicaffeine_compile/analysis/unify/fn.unify_numeric): Numeric promotion: Float wins; Int + Int = Int; Nat + Nat = Nat; Byte + Byte = Byte; Byte + Int (literal context) = Byte; otherwise error. ## logicaffeine_compile::aot_unsupported The ops no single-device AOT backend can run — concurrency, virtual-time scheduling, and networking — classified once so the device tiers (Tenstorrent baby core, one CUDA kernel launch) cannot drift apart on their refusal set. - [enum Offload](https://docs.logicaffeine.com/logicaffeine_compile/aot_unsupported/enum.Offload): The category of op that no single-device AOT backend can lower. Each tier maps a category to its own worded reason (a Tensix core vs. a CUDA kernel phrase it differently) but the SET is shared, so a concurrency/networking op can never be silently accepted by one tier and refused by another. - [fn classify](https://docs.logicaffeine.com/logicaffeine_compile/aot_unsupported/fn.classify): Classify a single op. `None` for every op that is not inherently off a single-device datapath (arithmetic, control flow, collections, …). - [fn first](https://docs.logicaffeine.com/logicaffeine_compile/aot_unsupported/fn.first): The first offload-unsupported op in `program`, classified — `None` if the whole program is on the single-device datapath. - [fn first_reachable](https://docs.logicaffeine.com/logicaffeine_compile/aot_unsupported/fn.first_reachable): The first unsupported op REACHABLE from the program’s entry — the honest question for a backend deciding whether it can build this program. ## logicaffeine_compile::arena - [struct Arena](https://docs.logicaffeine.com/logicaffeine_compile/arena/struct.Arena): An owning arena for stable references. ## logicaffeine_compile::arena_ctx - [struct AstContext](https://docs.logicaffeine.com/logicaffeine_compile/arena_ctx/struct.AstContext): Collection of typed arenas for AST allocation during parsing. ## logicaffeine_compile::ast Abstract Syntax Tree types for both logical expressions and imperative statements. - [mod axiom](https://docs.logicaffeine.com/logicaffeine_compile/ast/axiom/): AST nodes for the formal-logic vernacular: `## Axiom` and `## Theory` blocks. - [mod component](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/): The LGX component model — the first-class AST for a page, a component, a store, and the sections they own: `State:` (the record), `Actions:` (the only mutators, plus the English event sentences that trigger them), `View:` (the template, already parsed into the view IR), and `Style:` (the component’s CSS). - [mod definition](https://docs.logicaffeine.com/logicaffeine_compile/ast/definition/): `## Define` block AST — a vernacular-logic predicate definition (Rung 0a). - [mod logic](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/): Logic expression AST types for first-order logic with modal and event extensions. - [mod stmt](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/): Imperative statement AST types for the LOGOS language. - [mod theorem](https://docs.logicaffeine.com/logicaffeine_compile/ast/theorem/): Theorem and proof block AST types. - [mod view](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/): The LGX view IR — what a template PARSES INTO before anything is lowered. - [struct AxiomBlock](https://docs.logicaffeine.com/logicaffeine_compile/ast/struct.AxiomBlock): A `## Axiom` block: a named first-order axiom in formal notation. - [struct CaseTable](https://docs.logicaffeine.com/logicaffeine_compile/ast/struct.CaseTable): A table-driven test’s case fixture: `For each of these cases:` followed by a markdown pipe table. Columns bind names in the test body’s scope; each data row is a named sub-test. - [struct CategoricalData](https://docs.logicaffeine.com/logicaffeine_compile/ast/struct.CategoricalData): Aristotelian categorical proposition data. - [struct DefinitionBlock](https://docs.logicaffeine.com/logicaffeine_compile/ast/struct.DefinitionBlock): A `## Define` block: `(params) if and only if `. - [struct MatchArm](https://docs.logicaffeine.com/logicaffeine_compile/ast/struct.MatchArm): Match arm for pattern matching in Inspect statements. - [struct ModalVector](https://docs.logicaffeine.com/logicaffeine_compile/ast/struct.ModalVector): Modal operator parameters for Kripke semantics (Kratzer-style). - [struct NeoEventData](https://docs.logicaffeine.com/logicaffeine_compile/ast/struct.NeoEventData): Neo-Davidsonian event structure with thematic roles. - [struct NounPhrase](https://docs.logicaffeine.com/logicaffeine_compile/ast/struct.NounPhrase): Parsed noun phrase structure for compositional interpretation. - [struct RelationData](https://docs.logicaffeine.com/logicaffeine_compile/ast/struct.RelationData): Simple subject-verb-object relation data. - [struct SecurePad](https://docs.logicaffeine.com/logicaffeine_compile/ast/struct.SecurePad): The `with pad "" as ` binding on a `Connect`/`Listen` — activate the PNP one-time-pad session over the pad file at `pad`, with this peer taking `role`. - [struct StmtId](https://docs.logicaffeine.com/logicaffeine_compile/ast/struct.StmtId): A statement’s identity: where it lives. Stable for as long as the AST it was taken from is alive; a statement copied into a new block is a new identity. Diagnostics use it to name the exact statement a finding is about, nested ones included. - [struct TestCapabilities](https://docs.logicaffeine.com/logicaffeine_compile/ast/struct.TestCapabilities): Which sealed-world resources a `## Test` may really touch, granted by capability sentences (`This test may use the real filesystem.`). Everything defaults to sealed; a granted capability moves the test to the `--live` set. - [struct TheoremBlock](https://docs.logicaffeine.com/logicaffeine_compile/ast/struct.TheoremBlock): A theorem block containing premises, goal, and proof strategy. - [struct TheoryBlock](https://docs.logicaffeine.com/logicaffeine_compile/ast/struct.TheoryBlock): A `## Theory` block: a named development that groups the axioms and theorems that follow it (`## Theory Tarski`). Its body is the formal development text — a sequence of `Axiom …` and `Theorem …` declarations parsed downstream. - [enum AspectOperator](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.AspectOperator): Grammatical aspect operators for event structure. - [enum BinaryOpKind](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.BinaryOpKind): Binary operation kinds for imperative expressions. - [enum BinaryTemporalOp](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.BinaryTemporalOp): Binary temporal operators (LTL). - [enum ComparisonRelation](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.ComparisonRelation): Degree-comparison relation for `LogicExpr::Comparative`. - [enum CompressionCodec](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.CompressionCodec): The wire compression codec a `Send compressed [with ]` selects. The transpiler maps this to the runtime’s wire codec; bare `compressed` = `Deflate`. - [enum Dimension](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.Dimension): Physical dimension for degree semantics and unit tracking. - [enum ExpectedOutput](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.ExpectedOutput): Where an `Expect output:` snapshot lives: indented in the document, or in an external golden file (`Expect output as in "golden/report.txt".`). - [enum Expr](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.Expr): Shared expression type for pure computations (LOGOS §15.0.0). - [enum Literal](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.Literal): Literal values in LOGOS. - [enum LogicExpr](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.LogicExpr): First-order logic expression with modal, temporal, and event extensions. - [enum LogicalType](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.LogicalType): Montague semantic types for compositional interpretation. - [enum ModalDomain](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.ModalDomain): Modal logic domain classification. - [enum ModalFlavor](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.ModalFlavor): Modal flavor affecting scope interpretation. - [enum NumberKind](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.NumberKind): Numeric literal representation for degree semantics. - [enum ObsCategory](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.ObsCategory): The speech-act category of an observation statement: audience + retention, not a numeric level. - [enum ProofStrategy](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.ProofStrategy): Proof strategies for theorem verification. - [enum PropDomain](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.PropDomain): The domain a property quantifies over (`For all integers a and b:`). Generation draws from this; shrinking minimizes toward the domain’s zero. - [enum QuantifierKind](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.QuantifierKind): Quantifier types for first-order and generalized quantifiers. - [enum SecureRole](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.SecureRole): Imperative statement AST (LOGOS §15.0.0). - [enum SendLayout](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.SendLayout): The wire LAYOUT a `Send` modifier picks — the size↔speed dial the sender chooses for their link. The transpiler maps this to the runtime’s numeric codec. The sender knows their use case; this lets them express it in one word. - [enum Stmt](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.Stmt) - [enum TemporalOperator](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.TemporalOperator): Temporal logic operators. - [enum Term](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.Term): First-order logic term representing entities or values. - [enum ThematicRole](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.ThematicRole): Neo-Davidsonian thematic roles for event semantics. - [enum TypeExpr](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.TypeExpr): Type expression for explicit type annotations. - [enum UnaryOpKind](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.UnaryOpKind): Unary logical operators. - [enum VoiceOperator](https://docs.logicaffeine.com/logicaffeine_compile/ast/enum.VoiceOperator): Grammatical voice operators. - [type Block](https://docs.logicaffeine.com/logicaffeine_compile/ast/type.Block): Block is a sequence of statements. ## logicaffeine_compile::ast::axiom AST nodes for the formal-logic vernacular: `## Axiom` and `## Theory` blocks. - [struct AxiomBlock](https://docs.logicaffeine.com/logicaffeine_compile/ast/axiom/struct.AxiomBlock): A `## Axiom` block: a named first-order axiom in formal notation. - [struct TheoryBlock](https://docs.logicaffeine.com/logicaffeine_compile/ast/axiom/struct.TheoryBlock): A `## Theory` block: a named development that groups the axioms and theorems that follow it (`## Theory Tarski`). Its body is the formal development text — a sequence of `Axiom …` and `Theorem …` declarations parsed downstream. ## logicaffeine_compile::ast::component The LGX component model — the first-class AST for a page, a component, a store, and the sections they own: `State:` (the record), `Actions:` (the only mutators, plus the English event sentences that trigger them), `View:` (the template, already parsed into the view IR), and `Style:` (the component’s CSS). - [struct ActionDef](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/struct.ActionDef): `To name (params):` in `Actions:`. - [struct ComponentDef](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/struct.ComponentDef): One `## Page` / `## Component` / `## Store` / `## Error page` definition. - [struct EventHandler](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/struct.EventHandler) - [struct StateField](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/struct.StateField): `Let x be .` or `Let x always be .` (derived) in a `State:` section. - [struct StyleBlock](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/struct.StyleBlock): A `Style:` section: the dedented CSS text, the file offset of its first character, and the indentation stripped from each of its lines. - [enum ComponentKind](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/enum.ComponentKind) - [enum RouteBody](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/enum.RouteBody): A `## Route`’s body: ordinary statements, or a template for a `-> View` route. The template is boxed: a `ViewDef` inline would make every `Stmt` as wide as a view route. - [enum StoreMode](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/enum.StoreMode) - [enum Trigger](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/enum.Trigger): What an English `When …:` sentence in `Actions:` waits for. - [const RENDER_DEPTH_LIMIT](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/constant.RENDER_DEPTH_LIMIT): How deeply components may nest while one paint is drawn before the page is refused as one with no finite rendering (`render_depth_message`). - [const STORE_CASCADE_LIMIT](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/constant.STORE_CASCADE_LIMIT): How many rounds of `When 's changes:` may cascade — a watcher’s write waking a watcher, which wakes another — before the page is refused as one that never settles. Every tier counts the same rounds and says the same sentence (`store_cascade_message`). - [fn directive_failure_prefix](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/fn.directive_failure_prefix): What every tier puts in front of a trap inside a `## Directive`’s block (`removed`: its `When removed:` block): from the page’s side, the directive is what went wrong. - [fn render_depth_message](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/fn.render_depth_message): What every tier says when `component` is nested past `RENDER_DEPTH_LIMIT` while drawing. - [fn store_cascade_message](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/fn.store_cascade_message): What every tier says of a store-watcher cascade deeper than `STORE_CASCADE_LIMIT`. - [fn timer_period_not_positive](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/fn.timer_period_not_positive): What every tier says of a timer whose period, as its instance was drawn, is not positive. - [fn typed_fetch_refusal](https://docs.logicaffeine.com/logicaffeine_compile/ast/component/fn.typed_fetch_refusal): What every tier says of `Get … as ` when the derived JSON codec cannot read `ty`: a typed request decodes its answer through `fromJson_` for a declared record, `fromJsonSeq_` for a list of records or scalars, and takes Text verbatim — nothing else. ## logicaffeine_compile::ast::definition `## Define` block AST — a vernacular-logic predicate definition (Rung 0a). - [struct DefinitionBlock](https://docs.logicaffeine.com/logicaffeine_compile/ast/definition/struct.DefinitionBlock): A `## Define` block: `(params) if and only if `. ## logicaffeine_compile::ast::logic Logic expression AST types for first-order logic with modal and event extensions. - [struct CategoricalData](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/struct.CategoricalData): Aristotelian categorical proposition data. - [struct ModalVector](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/struct.ModalVector): Modal operator parameters for Kripke semantics (Kratzer-style). - [struct NeoEventData](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/struct.NeoEventData): Neo-Davidsonian event structure with thematic roles. - [struct NounPhrase](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/struct.NounPhrase): Parsed noun phrase structure for compositional interpretation. - [struct RelationData](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/struct.RelationData): Simple subject-verb-object relation data. - [enum AspectOperator](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.AspectOperator): Grammatical aspect operators for event structure. - [enum BinaryOpKind](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.BinaryOpKind): Binary logical connectives. - [enum BinaryTemporalOp](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.BinaryTemporalOp): Binary temporal operators (LTL). - [enum ComparisonRelation](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.ComparisonRelation): Degree-comparison relation for `LogicExpr::Comparative`. - [enum Dimension](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.Dimension): Physical dimension for degree semantics and unit tracking. - [enum LogicExpr](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.LogicExpr): First-order logic expression with modal, temporal, and event extensions. - [enum LogicalType](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.LogicalType): Montague semantic types for compositional interpretation. - [enum ModalDomain](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.ModalDomain): Modal logic domain classification. - [enum ModalFlavor](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.ModalFlavor): Modal flavor affecting scope interpretation. - [enum NumberKind](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.NumberKind): Numeric literal representation for degree semantics. - [enum QuantifierKind](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.QuantifierKind): Quantifier types for first-order and generalized quantifiers. - [enum TemporalOperator](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.TemporalOperator): Temporal logic operators. - [enum Term](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.Term): First-order logic term representing entities or values. - [enum ThematicRole](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.ThematicRole): Neo-Davidsonian thematic roles for event semantics. - [enum UnaryOpKind](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.UnaryOpKind): Unary logical operators. - [enum VoiceOperator](https://docs.logicaffeine.com/logicaffeine_compile/ast/logic/enum.VoiceOperator): Grammatical voice operators. ## logicaffeine_compile::ast::stmt Imperative statement AST types for the LOGOS language. - [struct CaseTable](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/struct.CaseTable): A table-driven test’s case fixture: `For each of these cases:` followed by a markdown pipe table. Columns bind names in the test body’s scope; each data row is a named sub-test. - [struct FailureSite](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/struct.FailureSite): One entry in `Parser::failure_sites` — everything a runtime failure needs to point BACK at the sentence a `Stmt::Site` marker stood in front of. - [struct MatchArm](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/struct.MatchArm): Match arm for pattern matching in Inspect statements. - [struct SecurePad](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/struct.SecurePad): The `with pad "" as ` binding on a `Connect`/`Listen` — activate the PNP one-time-pad session over the pad file at `pad`, with this peer taking `role`. - [struct StmtId](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/struct.StmtId): A statement’s identity: where it lives. Stable for as long as the AST it was taken from is alive; a statement copied into a new block is a new identity. Diagnostics use it to name the exact statement a finding is about, nested ones included. - [struct TestCapabilities](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/struct.TestCapabilities): Which sealed-world resources a `## Test` may really touch, granted by capability sentences (`This test may use the real filesystem.`). Everything defaults to sealed; a granted capability moves the test to the `--live` set. - [enum BinaryOpKind](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.BinaryOpKind): Binary operation kinds for imperative expressions. - [enum ClosureBody](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.ClosureBody): Body of a closure expression. - [enum CompressionCodec](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.CompressionCodec): The wire compression codec a `Send compressed [with ]` selects. The transpiler maps this to the runtime’s wire codec; bare `compressed` = `Deflate`. - [enum DomQuery](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.DomQuery): What `the of ` asks the page. - [enum ExpectedOutput](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.ExpectedOutput): Where an `Expect output:` snapshot lives: indented in the document, or in an external golden file (`Expect output as in "golden/report.txt".`). - [enum Expr](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.Expr): Shared expression type for pure computations (LOGOS §15.0.0). - [enum FetchMethod](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.FetchMethod): The HTTP method of a `Stmt::Fetch`. - [enum Literal](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.Literal): Literal values in LOGOS. - [enum ObsCategory](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.ObsCategory): The speech-act category of an observation statement: audience + retention, not a numeric level. - [enum Pattern](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.Pattern): Pattern for loop variable binding. Supports single identifiers and tuple destructuring for Map iteration. - [enum PropDomain](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.PropDomain): The domain a property quantifies over (`For all integers a and b:`). Generation draws from this; shrinking minimizes toward the domain’s zero. - [enum ReadSource](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.ReadSource): Source for Read statements. - [enum Role](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.Role): Which position a `UiStmt` may be written in — the partition `UiStmt::role` holds to, cross- checked against `action_verb_tier_lock`’s own census (which verbs compile inside `Actions:`) and `page_host::Drive` (which verbs carry a `## Main`/`## Test` statement to a page under test), so the two catalogues cannot silently drift apart. - [enum SecureRole](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.SecureRole): Imperative statement AST (LOGOS §15.0.0). - [enum SelectBranch](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.SelectBranch): A branch in a Select statement. - [enum SendLayout](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.SendLayout): The wire LAYOUT a `Send` modifier picks — the size↔speed dial the sender chooses for their link. The transpiler maps this to the runtime’s numeric codec. The sender knows their use case; this lets them express it in one word. - [enum Stmt](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.Stmt) - [enum StringPart](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.StringPart): A segment of an interpolated string. - [enum TypeExpr](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.TypeExpr): Type expression for explicit type annotations. - [enum UiStmt](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.UiStmt): What a component action can do to the page, the browser, storage or a store. Each is a sentence in the `Actions:` vocabulary; the selector forms take a selector TEXT or an `Element`. - [enum ZoneSource](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/enum.ZoneSource): Backing-file source for a memory-mapped zone (`… mapped from `). `Inside a zone called "D" mapped from "f.bin"` is `ZoneSource::Literal`; `… mapped from path` (a runtime `Text` variable) is `ZoneSource::Variable`. - [type Block](https://docs.logicaffeine.com/logicaffeine_compile/ast/stmt/type.Block): Block is a sequence of statements. ## logicaffeine_compile::ast::theorem Theorem and proof block AST types. - [struct TheoremBlock](https://docs.logicaffeine.com/logicaffeine_compile/ast/theorem/struct.TheoremBlock): A theorem block containing premises, goal, and proof strategy. - [enum ProofStrategy](https://docs.logicaffeine.com/logicaffeine_compile/ast/theorem/enum.ProofStrategy): Proof strategies for theorem verification. ## logicaffeine_compile::ast::view The LGX view IR — what a template PARSES INTO before anything is lowered. - [mod duplicate_keyed_loop_message_parts](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/duplicate_keyed_loop_message_parts/): The literal segments of `duplicate_keyed_loop_message`, PUBLIC so a compiled tier’s own lowering of `Each` can build the identical text out of runtime `Expr`s (string concatenation, `loop_desc` baked in as a literal since it is known at lowering time; `key`/the two positions are not) without a second, hand-copied version of the wording that could drift from this one. - [struct ViewArm](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/struct.ViewArm): One `{when Pattern:}` arm of a view `{inspect …:}`. - [struct ViewDef](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/struct.ViewDef): One complete view: a `Render:` block, a `Render into :` block, or a component’s `View:` — in source order they appear in `crate::parser::Parser::views`. - [enum Attr](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/enum.Attr): One attribute-position item of an element, in source order. - [enum BoundInput](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/enum.BoundInput): What a `bind={field}` on an element actually WRITES — the one place the whole language decides, so no two walks can disagree about a checkbox. - [enum ViewNode](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/enum.ViewNode): One node of a view tree. - [enum ViewRoot](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/enum.ViewRoot): The render target of a `ViewDef`. - [const LOOP_INDEX_BASE](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/constant.LOOP_INDEX_BASE): The position `{for each x in xs, at index i:}` gives the first item. - [fn bound_input_kind](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/fn.bound_input_kind): Decide, from an element’s TAG and attributes, what a `bind` on it writes. See `BoundInput`. - [fn duplicate_keyed_loop_message](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/fn.duplicate_keyed_loop_message): The message a `keyed by` loop whose siblings share a key fails with — the SAME wording on every tier, because the lowering of `Each` builds it at run time from the segments this function formats (`duplicate_keyed_loop_message_parts`). `loop_desc` names what is being iterated (`expr_shape` on the loop’s own `iterable`, e.g. `"todos"`); `key` is the colliding key’s own display value (its evaluated VALUE, not source text — two items collide on what a key IS, at runtime, never on how it was spelled). - [fn expr_shape](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/fn.expr_shape): A compact expression rendering for shapes: literals verbatim, identifiers by name, calls as `f(args)`, field access as `a's b`, interpolation with `{…}` holes; anything else prints as `_`. ## logicaffeine_compile::ast::view::duplicate_keyed_loop_message_parts The literal segments of `duplicate_keyed_loop_message`, PUBLIC so a compiled tier’s own lowering of `Each` can build the identical text out of runtime `Expr`s (string concatenation, `loop_desc` baked in as a literal since it is known at lowering time; `key`/the two positions are not) without a second, hand-copied version of the wording that could drift from this one. - [const AFTER_FIRST_POSITION](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/duplicate_keyed_loop_message_parts/constant.AFTER_FIRST_POSITION) - [const AFTER_LOOP_DESC](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/duplicate_keyed_loop_message_parts/constant.AFTER_LOOP_DESC) - [const AFTER_SECOND_POSITION](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/duplicate_keyed_loop_message_parts/constant.AFTER_SECOND_POSITION) - [const PREFIX](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/duplicate_keyed_loop_message_parts/constant.PREFIX) - [const SUFFIX](https://docs.logicaffeine.com/logicaffeine_compile/ast/view/duplicate_keyed_loop_message_parts/constant.SUFFIX) ## logicaffeine_compile::bringup Model bring-up: a checkpoint’s one program, lowered by every chip that runs it. - [struct Bringup](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.Bringup): A checkpoint brought up: its spec, the identity of its decode step (the program every backend’s cuts are cuts of), its text, and each backend asked for with what it made or why it refused. - [struct Brought](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.Brought): What a backend made of a model: the cut of the one program behind every artifact, and the files it wrote. - [struct C](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.C): The CPU through C (`crate::compile::compile_to_c`): the decode step as one C program; a run builds its generation program once, with no contraction of a product and a sum into one fused multiply-add, whose single rounding the VM’s arithmetic never takes, and runs it. - [struct Cuda](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.Cuda): The CUDA lane (`crate::codegen_cuda::lane`): the decode step and its prefill chunks as one fused CUDA program and the sidecar of computed constants it reads. - [struct D5005](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.D5005): The D5005 decode engine (`crate::spatial::decode_engine`): the step’s program for the engine’s sequencer, the checkpoint held to what the engine’s units read. - [struct Fabric](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.Fabric): The spatial fabric the compiler generates for an FPGA: it does not lower a model the author writes yet, and says so. - [struct Generated](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.Generated): What a chip generated for a run’s sequences: their tokens, a list a sequence in their order (ids from 0); the seconds the runs took, not the building of what ran them; what ran them — the chip itself, or the model of it this machine holds; and the program it ran — the generation program a CPU tier built, or the artifact the chip runs. - [struct Jit](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.Jit): The VM with its native tier: the same bytecode, the loops it runs hot compiled to machine code as it runs. - [struct Ran](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.Ran): A backend’s run of one sequence: the tokens it generated after the prompt (ids from 0), the seconds from the prompt to the last token, and what ran them — the chip itself, or the model of it this machine holds. - [struct Reference](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.Reference): What a run is judged against: the tokens it should generate, and where they come from. - [struct Refused](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.Refused): Why a backend does not run a model, by name. - [struct RiscvQemu](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.RiscvQemu): RISC-V through its AOT tier (`crate::compile::compile_to_riscv`): the decode step as RISC-V assembly; a run links its generation program with its runtime (`crate::codegen_riscv::runtime`) by `riscv64-linux-gnu-gcc` once and runs it under `qemu-riscv64`. - [struct Runs](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.Runs): The runs of a model brought up: the prompt, what they are judged against, and each backend that brought the model up with what it generated or why it did not run here. - [struct Rust](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.Rust): The CPU through Rust (`crate::compile::compile_to_rust`): the decode step as one Rust program; a run stages one project beside the artifacts (`crate::compile::compile_to_dir`) and builds its generation program into it in release, only its `src/main.rs` rewritten when the project is already staged, so the runtime crates build once a project. - [struct Sequence](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.Sequence): One sequence a run generates: its prompt (token ids from 0), and the tokens it is judged against — as many as it generates. - [struct SequenceRuns](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.SequenceRuns): The runs of several sequences: the sequences, and each backend that brought the model up with what it generated for them or why it did not run here. - [struct Sn50](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.Sn50): The SambaNova SN50 (`crate::spatial::rdu_chip`): the decode deployment as one certified program per layer kind, the embedding and the head, bound layer by layer by a manifest — SDK-gated, its placements MODELED. - [struct Vm](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.Vm): The bytecode VM (`crate::vm`): the decode step compiled to the bytecode it runs, as `largo run --interpret` compiles it (`vm_listing`). - [struct Wasm](https://docs.logicaffeine.com/logicaffeine_compile/bringup/struct.Wasm): WebAssembly (`crate::compile::compile_to_wasm`): the decode step as a module with the host shim `largo build --emit wasm` writes beside it (`crate::web_host::wasm_host_shim`); a run executes its generation program’s module under node. - [trait Backend](https://docs.logicaffeine.com/logicaffeine_compile/bringup/trait.Backend): A chip a model’s one program is lowered to. - [fn agreeing](https://docs.logicaffeine.com/logicaffeine_compile/bringup/fn.agreeing): How many of `ran`’s tokens agree with `reference`’s before the first that does not. - [fn backends](https://docs.logicaffeine.com/logicaffeine_compile/bringup/fn.backends): Every chip a model is brought up on, in the order the command line lists them: the CPU tiers, then the accelerators. - [fn bring_up](https://docs.logicaffeine.com/logicaffeine_compile/bringup/fn.bring_up): Bring the checkpoint at `checkpoint` — a GGUF file, or a Hugging Face directory (`config.json` beside its safetensors) — up on the backends named in `targets` (every one when empty), over caches of `ctx` positions, each backend’s artifacts under `out//` and the model’s program as `out/program.lg`: the spec read from the checkpoint’s own metadata (`bring_up_spec`). - [fn bring_up_spec](https://docs.logicaffeine.com/logicaffeine_compile/bringup/fn.bring_up_spec): `bring_up` for `spec`, whose weights the checkpoint at `checkpoint` holds. - [fn run](https://docs.logicaffeine.com/logicaffeine_compile/bringup/fn.run): Run the model `b` brought up on every backend that brought it up, `prompt` first, for as many tokens as `reference` holds, in the order the backends were asked for: `run_sequences` of the one sequence. - [fn run_sequences](https://docs.logicaffeine.com/logicaffeine_compile/bringup/fn.run_sequences): Run the model `b` brought up on every backend that brought it up, every one of `sequences` from an empty state, in the order the backends were asked for. ## logicaffeine_compile::codegen Code generation from LOGOS AST to Rust source code. - [struct RefinementContext](https://docs.logicaffeine.com/logicaffeine_compile/codegen/struct.RefinementContext): Tracks refinement type constraints across scopes for mutation enforcement. - [struct VariableCapabilities](https://docs.logicaffeine.com/logicaffeine_compile/codegen/struct.VariableCapabilities): Tracks which variables have Mount and/or Sync statements. - [fn codegen_assertion](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.codegen_assertion): Converts a LogicExpr to a Rust boolean expression for debug_assert!(). Uses RustFormatter to unify all logic-to-Rust translation. - [fn codegen_expr](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.codegen_expr) - [fn codegen_native_tier_export](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.codegen_native_tier_export): Emit the AOT-native export shim (HOTSWAP §Axis-3): a thin `#[no_mangle] extern "C"` calling-convention wrapper over the inner Rust fn that crosses our ACTUAL values — scalars BY VALUE — with NO `CString`/handle marshaling (unlike `codegen_c_export_with_marshaling`). The interpreter marshals VM `Value`s to these scalar args, calls the loaded symbol, and re-boxes the scalar result. - [fn codegen_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.codegen_program) - [fn codegen_program_mapped](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.codegen_program_mapped): Like `codegen_program`, but also builds the rustc→LOGOS `SourceMap`: every generated line maps to the top-level statement that produced it (`stmt_spans` is the parser’s side-table, 1:1 with `stmts`; zero-width spans mark prelude statements and are skipped), and variable origins carry ownership roles for the diagnostic bridge. This is the flycheck substrate. - [fn codegen_program_with_proven](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.codegen_program_with_proven): Like `codegen_program`, but bundles an extracted math/logic module into the output. `proven` is the body of a Rust module — functions, `check_*` property fns, a `World`/`holds` model-checker — produced by the Forge’s extraction with NO `fn main`. It is emitted as `pub mod { … }` right after the prelude (before `user_types`), followed by `use ::*;` so a bare call in the imperative program below — e.g. `double(21)` — resolves into it. Naming the module (rather than dumping items at crate root) keeps multiple proven modules reachable and avoids polluting the imperative namespace. When `proven` is `None`/blank the output is byte-identical to `codegen_program`. - [fn codegen_stmt](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.codegen_stmt) - [fn codegen_term](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.codegen_term) - [fn collect_async_functions](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.collect_async_functions): Phase 54: Collect function names that are async. Used by LaunchTask codegen to determine if .await is needed. - [fn collect_pipe_sender_params](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.collect_pipe_sender_params) - [fn collect_pipe_vars](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.collect_pipe_vars): Phase 54: Collect variables that are pipe declarations (created with CreatePipe). These have _tx/_rx suffixes, while pipe parameters don’t. - [fn embed_assets_enabled](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.embed_assets_enabled): Is the EMBEDDED-ASSETS `Serve` lowering active for this compile (B4)? When set, the emitted `Serve` closure consults `logos_assets::lookup(&path)` BEFORE calling the handler — an embedded page/static asset shadows a backend route, exactly the dev router’s precedence, so a `largo build` web binary serves the bundled site. Default OFF: a plain `Serve` program lowers byte-identically (the asset hook is inert), which the HTTP differential pins. - [fn empty_var_caps](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.empty_var_caps): Helper to create an empty VariableCapabilities map (for tests). - [fn force_disable_borrow_hoist_for_test](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.force_disable_borrow_hoist_for_test): Force borrow hoisting off (or back on) for the current thread only. Used by tests to verify the kill switch without the env-var data race. - [fn function_slice](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.function_slice): The statements needed to compile `target` standalone: the `target` function plus every function reachable from it through the call graph (transitively). `Main` and top-level functions unreachable from `target` are dropped; definition order is preserved. - [fn generate_c_header](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.generate_c_header): Generate the C header (.h) content for all C-exported functions. - [fn generate_python_bindings](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.generate_python_bindings): Generate Python ctypes bindings for all C-exported functions. - [fn generate_typescript_bindings](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.generate_typescript_bindings): Generate TypeScript type declarations (.d.ts) and FFI bindings (.js). - [fn observed_codegen_enabled](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.observed_codegen_enabled): Is the OBSERVED codegen profile active (Wave 13)? When set, observation is NOT elided at lowering and the AOT backend EMITS `logicaffeine_system::obs` calls for `Note`/`Warn`/`Record`/`During`. Default OFF — the release/elided profile, where observation is erased before codegen (byte-identical artifact, §0.7). - [fn release_panic_strategy](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.release_panic_strategy): The panic strategy of a generated program’s release build: `unwind` for one that opens with `UNWIND_PROFILE_HEADER`, `abort` for every other, whose failure hook reports and ends it. Every project writer takes it from here. - [fn with_deterministic_replay](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.with_deterministic_replay): Run `f` with the deterministic-replay lowering enabled, restoring the previous mode afterwards (panic-safe). Returns `f`’s result. - [fn with_embed_assets](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.with_embed_assets): Run `f` with the embedded-assets `Serve` lowering enabled (B4), restoring the previous mode afterwards (panic-safe). `largo build` wraps the web-project compile in this so the generated `Serve` consults `logos_assets`. - [fn with_observed_codegen](https://docs.logicaffeine.com/logicaffeine_compile/codegen/fn.with_observed_codegen): Run `f` with the OBSERVED codegen profile enabled, restoring the previous mode afterwards (panic-safe). Returns `f`’s result. ## logicaffeine_compile::codegen_ana LOGOS → analog spatial fabric (FPAA-style mixed-signal coprocessor) — the analog lane. - [mod calibrate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/calibrate/): Factory calibration — manufacturing ADJUSTABLE circuits, not impossibly perfect ones. - [mod cell](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/cell/): The analog tile netlist — `codegen_ana`’s SSA IR. - [mod control](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/control/): The digital control plane’s frame schedule — DAC/ADC strobing around the analog plane. - [mod dims](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/dims/): The ADL dimension census — every numeric field of the characterized descriptors (`AnalogTarget`, `NonIdealityModel`) declares its physical dimension, ONCE, here. - [mod dynamics](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/dynamics/): The relaxation lane — continuous-time state evolution as a compute primitive (`Solve A·x = b` by settling). - [mod effects](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/effects/): The physics-effect provenance grid. - [mod error_budget](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/error_budget/): The error budget — ε as a COMPILER OUTPUT, never a hand-tuned test tolerance. - [mod eval](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/eval/): Tier-1 behavioral evaluation of an analog netlist. - [mod gain](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/gain/): Gain scaling + the range-safety certificate — the compiler side of the analog trust story. - [mod int_lane](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/int_lane/): The certified-EXACT integer lane — small-range integer dataflow with the ADC as restorer. - [mod integrator](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/integrator/): The ZOH integrator lane — counted Euler loops as OTA-C integration. - [mod lower](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/lower/): Float-function → analog-netlist lowering — the analog lane’s Futamura moment. - [mod nonideal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/nonideal/): The non-ideality model — sourced physics, seeded instances, and the instance evaluator. - [mod ontology](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/): The typed ontology of analog circuits. - [mod place](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/place/): Non-ideality-aware placement — operand adjacency as a matching resource. - [mod reduction](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/reduction/): The streamed reduction — the flagship MAC lane. - [mod spice_emit](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/spice_emit/): Behavioral ngspice emission — the analog lane’s “iverilog tier”. - [mod stack](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack/): The constructive 2.5D/3D stack ADL. - [mod stack_place](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack_place/): 3D placement over composed analog tiers — vertical interconnect as a COUNTED, refusable resource, and the cross-tier Pelgrom category priced into the budget. - [mod target](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/target/): The `AnalogTarget` ADL — the analog lane’s described-fabric spine, shaped as a characterized analog PDK for the compiler, not a feature checklist. - [mod thermal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/thermal/): The certified thermal map — `G·ΔT = P` over exact ℚ, judged independently. - [mod wta](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/wta/): Winner-take-all — the O7 stretch: the MARGIN CERTIFICATE arrives before the tile does. - [mod xbar](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/xbar/): Crossbar canonicalization — folding a gain/sum tree into single Kirchhoff columns. - [struct AnalogArtifact](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/struct.AnalogArtifact): The mixed-signal compilation artifact: the lowered region, its physical schedule and placement, the certificates and the budget, and the behavioral SPICE netlist (emitted at the declared input box’s midpoint). - [struct AssumedLenRange](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/struct.AssumedLenRange): A declared COLLECTION-LENGTH range: `Assume length of xs is between A and B.` — the streamed lane’s frame bound (the control plane schedules `hi` frames; the runtime check enforces the contract on every tier, so a longer sequence fails loudly before the DAC ever fires). - [struct AssumedRange](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/struct.AssumedRange): A declared input range: `Assume x is between lo and hi.` (or the `Require that` spelling — the range IS the enforced `RuntimeAssert` shape, not the head keyword). The gain-scaling pass’s input: a variable whose runtime value is CONTRACT-bounded to `[lo, hi]` on every tier. - [enum AnaLowerError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/enum.AnaLowerError): Why the analog tier declines a program — a SOUND refusal, never wrong silicon. - [enum RegionLane](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/enum.RegionLane): Which certified lane a region compiled through. - [fn analog_artifact_from_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/fn.analog_artifact_from_source): The full DAG-lane pipeline for one region function on one target: lower → schedule/certify → place → budget (physical, with the sourced non-ideality model) → behavioral SPICE. - [fn analog_int_artifact_from_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/fn.analog_int_artifact_from_source): The INTEGER pipeline for one region function: lower through the int lane, schedule, place, take the CALIBRATED physical budget (the product configuration — trims burned at final test), and PROVE exactness through the ½-grid gate before any artifact exists. An integer artifact is therefore certified-exact by construction: its budget is the proof. - [fn analog_refusal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/fn.analog_refusal): The fail-closed refusal gate every analog compilation runs FIRST. `None` means the program clears the gate (an analog region exists, with declared ranges, inside the SoC model). - [fn assumed_len_ranges_in](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/fn.assumed_len_ranges_in): Recover every declared length range from parsed statements (the `between` desugar over a `length of ` operand, in an enforced `RuntimeAssert`). - [fn assumed_ranges](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/fn.assumed_ranges): Recover every declared range from a program’s source — the source-level surface of `assumed_ranges_in`, for callers outside the compile pipeline. - [fn assumed_ranges_in](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/fn.assumed_ranges_in): Recover every declared range from parsed statements: each enforced (`hard`) `RuntimeAssert` whose condition is the `between` desugar shape `lo <= x and x <= hi` with literal bounds. Walks function bodies and nested blocks — a contract is a contract wherever it is stated. - [fn contract_free_twin](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/fn.contract_free_twin): The contract-free twin of a source: the `Assume` range-check lines stripped. The checks belong to the CONTROL PLANE (the digital side validates each word before the DAC fires, and runs them as ordinary bytecode in the digital fallback), so the region DATAFLOW both lanes lower is this twin — exposed for the mixed-signal composition to build its fallback configs from the same text the analog lane extracts. - [fn exactness_gate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/fn.exactness_gate): The integer lane’s ½-grid exactness proof: integer inputs on a grid-preserving region read back EXACTLY through the rounding ADC iff the compiler’s own error budget stays under half a grid step. `Ok(())` is the exactness CERTIFICATE’S admission condition; the refusal carries the budget that broke so the diagnostic names the cost. - [fn try_region](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/fn.try_region): Try to compile ONE region function on `target`, deciding the lane from its parameter family: float params → the ε-certified pipeline; else the certified-exact integer pipeline. PANIC-SAFE: extraction shapes outside the supported family become a typed refusal, never a crash — this is the entry the mixed-signal partition (and `compile_to_analog`) dispatches through for arbitrary programs. - [fn unsupported_reason](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/fn.unsupported_reason): Returns `Some(reason)` if `program` uses an op with no home anywhere in the mixed-signal SoC model — concurrency (the analog control plane is a frame sequencer, not a thread pool) and networking (host-only IO). Everything else either maps to the plane, frames its boundary, or runs digitally VM-identical on the control side. ## logicaffeine_compile::codegen_ana::calibrate Factory calibration — manufacturing ADJUSTABLE circuits, not impossibly perfect ones. - [struct CalibrationTable](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/calibrate/struct.CalibrationTable): Per-die trim values, each ON the trim grid. - [struct TrimSpec](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/calibrate/struct.TrimSpec): The trim DAC resolution — a design parameter of the tile (finer than the weight grid, since trims correct errors, not values). - [fn apply_calibration](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/calibrate/fn.apply_calibration): The calibrated die: residual gain/offset errors (≤ half a trim step by construction), the noise realization untouched (noise is dynamic — no trim reaches it). - [fn calibrate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/calibrate/fn.calibrate): Factory calibration of one measured die: the quantized negation of every measured error. - [fn error_budget_calibrated](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/calibrate/fn.error_budget_calibrated): The CALIBRATED physical budget: gain and offset carry the residual half-step bound instead of the k·σ manufacturing envelope; noise keeps its envelope; the converter/quantization terms are unchanged. - [fn v1_trim](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/calibrate/fn.v1_trim): The V1 tile’s trim resolution: gain trim = a quarter unit element; offset trim = 0.5 mV steps (a 6-bit trim over ±16 mV). Design parameters of OUR tile, not silicon claims. ## logicaffeine_compile::codegen_ana::cell The analog tile netlist — `codegen_ana`’s SSA IR. - [struct AnalogNetlist](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/cell/struct.AnalogNetlist): A flat SSA analog netlist: the mapped region’s dataflow, output tapped at `out`. - [enum ASrc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/cell/enum.ASrc): An operand of an analog tile: a plane input (a DAC channel), a prior tile’s output net, or a compile-time constant (a programmed reference). - [enum AnalogCell](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/cell/enum.AnalogCell): One analog tile. Ideal (math-domain) semantics are given per variant; physical parameters (gm, C, rails) attach at the target/gain layers, not here. ## logicaffeine_compile::codegen_ana::control The digital control plane’s frame schedule — DAC/ADC strobing around the analog plane. - [struct ControlProgram](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/control/struct.ControlProgram): A frame-based control program: `frame` repeats `frames` times, then `epilogue` runs once. - [enum CtrlStep](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/control/enum.CtrlStep): One step of the control plane’s schedule. ## logicaffeine_compile::codegen_ana::dims The ADL dimension census — every numeric field of the characterized descriptors (`AnalogTarget`, `NonIdealityModel`) declares its physical dimension, ONCE, here. - [fn adl_dimensions](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/dims/fn.adl_dimensions): Every numeric field of the ADL, with its declared dimension. Names are `Type::field` — exactly one row per field, no field left out (the lock cross-checks against compile-guarded struct literals). ## logicaffeine_compile::codegen_ana::dynamics The relaxation lane — continuous-time state evolution as a compute primitive (`Solve A·x = b` by settling). - [struct DynSystem](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/dynamics/struct.DynSystem): A configured dynamical system: one force tile per state variable, built from the EXISTING tile vocabulary (`AnalogCell::Sum` — the tiles stop computing results and start generating the forces that move state). - [struct IsingOutcome](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/dynamics/struct.IsingOutcome): One Ising candidate: an attractor of the soft-spin flow, certified for WHAT IT IS — its exact energy and its exact 1-flip stability — and nothing more (the claim type has no optimality field to lie with). - [struct MinimizeOutcome](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/dynamics/struct.MinimizeOutcome): One settled, certified quadratic minimization. - [struct RelaxOutcome](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/dynamics/struct.RelaxOutcome): One settled, certified solve. - [struct SettleOpts](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/dynamics/struct.SettleOpts): The deterministic settle knobs. `eps_required` is the demanded certificate budget — the hard admission line for the emitted claim; `noise_amp`/`seed` inject a fixed-seed disturbance per step (the model’s stand-in for the physical noise floor, and R3’s future annealing ramp). - [fn gradient_flow_system](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/dynamics/fn.gradient_flow_system): Build the gradient-flow force network for `ẋ = b − A·x`. Purely structural — admission is `solve_by_settling`’s job. - [fn ising_by_soft_spin](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/dynamics/fn.ising_by_soft_spin): The R3 attempt: `minimize H(s) = −Σ J_ij·s_i·s_j − Σ h_i·s_i` by SOFT-SPIN relaxation (Hopfield 1984): continuous states `x ∈ [−1,1]ⁿ` follow `ẋ = −x + tanh(β·(J·x + h))` with the annealing schedule as a NOISE-AMPLITUDE RAMP (`opts.noise_amp` decaying linearly to zero — the noise floor as a resource) while β ramps up. The trajectory and the tanh live in the UNTRUSTED model tier; the readout `sign(x̂)` is certified digitally and exactly: recomputed energy and 1-flip stability, judged by `proof::relax_replay::check_ising_claim`. A candidate that is not even 1-flip stable is polished greedily (each flip strictly lowers H — a certified descent, not a search). - [fn minimize_by_settling](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/dynamics/fn.minimize_by_settling): `minimize ½xᵀQx + bᵀx` by settling `ẋ = −(Q·x + b)` — the SAME force network with the signs flipped (the tiles generate the negative gradient). The admission gate is R1’s; the CERTIFICATE is R2’s theorem: for spectrum ≥ μ > 0 (exact Gershgorin row bound over ℚ), `f(x̂) − f* ≤ ‖∇f(x̂)‖²/(2μ)` — a gradient residual becomes a distance-to-optimum bound. `Candidate` semantics: the bound is the claim; no optimality field exists to lie with. - [fn solve_by_settling](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/dynamics/fn.solve_by_settling): `Solve A·x = b` by settling the gradient-flow system, fail-closed end to end. - [fn with_penalty](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/dynamics/fn.with_penalty): Fold one soft equality constraint `gᵀx = c` into the quadratic as a virtual spring: `f(x) + λ(gᵀx − c)²` ⇒ `Q += 2λ·ggᵀ`, `b −= 2λc·g`. Stiffer springs pull the settled answer closer to the constraint surface — the quadratic-penalty form (primal-dual dynamics are the ledgered future). ## logicaffeine_compile::codegen_ana::effects The physics-effect provenance grid. - [struct EffectRow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/effects/struct.EffectRow): A total row: one slot per effect, by construction. - [enum BudgetTermClass](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/effects/enum.BudgetTermClass): What a budget term IS: physics of the die, or arithmetic of the bound itself. - [enum EffectSlot](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/effects/enum.EffectSlot): One provenance-classified cell of the grid. `params` names the `NonIdealityModel` fields this slot is the census home of (each field lives in exactly one slot, grid-wide); a slot mixing provenances takes the WEAKEST of its params’ statuses. - [enum PhysicsEffect](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/effects/enum.PhysicsEffect): Every physical effect the grid classifies, one slot each. Declaration order IS the row index (`ALL_EFFECTS[i] as usize == i`, pinned by the lock). - [const ALL_EFFECTS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/effects/constant.ALL_EFFECTS): The effect census, in declaration (= index) order. - [const EFFECT_COUNT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/effects/constant.EFFECT_COUNT) - [fn effect_of](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/effects/fn.effect_of): Total classification of every `ErrorSource` into the taxonomy — a budget term cannot exist outside it (no wildcard; a new variant breaks this match until classified). - [fn effect_row](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/effects/fn.effect_row): THE grid — exhaustive over every element, total over every effect. Elements not yet studied return the all-`Unknown` row (honest, ledgered); classified rows carry the dossier’s provenance. The `NonIdealityModel` fields live in the linear tile’s row — the model is tile-generic today and that row is its characterization home. ## logicaffeine_compile::codegen_ana::error_budget The error budget — ε as a COMPILER OUTPUT, never a hand-tuned test tolerance. - [struct ErrorTerm](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/error_budget/struct.ErrorTerm): One itemized contribution, in the MATH domain at the region output. - [struct OutputBudget](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/error_budget/struct.OutputBudget): The per-output budget: `eps_math` is the outward-rounded sum of `terms`, pinned by `recheck`. - [enum ErrorSource](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/error_budget/enum.ErrorSource): A named physical origin of error. The decomposition is user-facing spec: a refusal or a budget report says exactly which arrow of the architecture costs what. - [fn error_budget](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/error_budget/fn.error_budget): Compose the budget for a scheduled DAG netlist: one propagation pass with a lane per DAC input, the wq lane, and the cross lane; then the itemized terms. - [fn error_budget_chopped](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/error_budget/fn.error_budget_chopped): The CHOPPED physical budget: the schedule runs every frame twice around a `ChopSwap` and averages, so the frozen per-tile offset CANCELS EXACTLY — `TileOffset` is replaced by the modeled `ChopResidual` drift class, and the noise term is √2-averaged (two independent draws per result, bookkept outward). Everything else is the unchopped budget verbatim. - [fn error_budget_nonideal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/error_budget/fn.error_budget_nonideal): The PHYSICAL budget: the converter/quantization budget plus the non-ideality terms — per-leg gain error over the PLACED operand separations, per-tile offset, and the noise floor, each at the k·σ envelope and propagated through the dataflow. This is the ε the Monte-Carlo battery and (later) SPICE must live inside. ## logicaffeine_compile::codegen_ana::eval Tier-1 behavioral evaluation of an analog netlist. - [struct ConverterGrid](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/eval/struct.ConverterGrid): THE converter model — the single definition of the block scale and both converter grids every physical tier shares (the behavioral evaluators, the instance evaluator, the streamed and integrated steppers — and the mixed-signal SoC’s fixed-point surrogate, which must mirror these semantics bit-for-bit). - [fn eval_analog_dc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/eval/fn.eval_analog_dc): Ideal DC operating point: evaluate the SSA tiles in order and read the output tap. - [fn eval_analog_quantized](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/eval/fn.eval_analog_quantized): DC operating point through the CONVERTER path: each input is driven by the DAC (rounded to its LSB at the block scale), the plane settles in the VOLT domain (the `Mul` tile divides by its programmed `V_ref`, returning products to the block scale), and the output is read through the ADC (rounded to its LSB) and descaled exactly (power-of-two shift). ## logicaffeine_compile::codegen_ana::gain Gain scaling + the range-safety certificate — the compiler side of the analog trust story. - [struct GainSchedule](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/gain/struct.GainSchedule): The per-program gain schedule: one block scale for every net, the exact ADC descale, the REALIZABLE multiplier reference, and the weight-quantized twin of the netlist (weights snapped to the target’s unit elements — what the silicon actually programs). - [struct MathBound](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/gain/struct.MathBound): A directed-outward f64 interval — the same arithmetic the independent checker replays. - [struct NetBound](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/gain/struct.NetBound): One net’s certified bounds. - [struct RangeCertificate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/gain/struct.RangeCertificate): The range-safety certificate: per-net bounds + the physical envelope they were proven against. Independently judged by `logicaffeine_proof::interval_replay::check_range_claim` via `to_range_claim`; nothing here is trusted by the checker. - [fn scale_pass](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/gain/fn.scale_pass): Run the gain-scaling pass: propagate declared ranges, choose the block scale, gate realizable ratios, and emit the schedule + certificate. `ranges` is one `AssumedRange` per plane input, in input order (the caller resolves parameter names to input indices). - [fn to_range_claim](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/gain/fn.to_range_claim): Convert a netlist + schedule + certificate into the INDEPENDENT checker’s neutral vocabulary. The producer’s only role here is faithful translation; the judgment belongs to `logicaffeine_proof::interval_replay::check_range_claim`. ## logicaffeine_compile::codegen_ana::int_lane The certified-EXACT integer lane — small-range integer dataflow with the ADC as restorer. - [fn analog_int_netlist_from_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/int_lane/fn.analog_int_netlist_from_source): Lower an INTEGER function to an analog tile netlist realizable on `target`. The exactness claim itself is made downstream by `super::exactness_gate` over the scheduled budget. ## logicaffeine_compile::codegen_ana::integrator The ZOH integrator lane — counted Euler loops as OTA-C integration. - [struct AnalogIntegrator](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/integrator/struct.AnalogIntegrator): A lowered ZOH integrator. Tick-input convention: `In(s)` = held state `s`; `outs[s]` = the next value of state `s`; the declared result is `outs`-resolved `result_state`. - [enum InitSrc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/integrator/enum.InitSrc): A state’s initial value: a function parameter (DAC-driven at frame 0) or a constant. - [fn analog_integrator_from_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/integrator/fn.analog_integrator_from_source): Lower a counted Euler loop over float state(s) to a ZOH integrator on `target`. - [fn eval_analog_integrated](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/integrator/fn.eval_analog_integrated): Ideal trajectory: the VM’s Euler loop, frame by frame (bit-exact — same f64 ops in order). - [fn eval_analog_integrated_quantized](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/integrator/fn.eval_analog_integrated_quantized): The physical trajectory: initial states DAC-quantized once, the whole trajectory continuous in the S&H (weight-quantized tick), one ADC at the end. - [fn integrator_error_budget](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/integrator/fn.integrator_error_budget): The iterated integrator budget: the shared ε engine run once per frame over the held state vector — initial DAC errors on the parameter states carry through every frame, the weight-snap deviation injects per frame, one ADC half-LSB lands at the end. - [fn integrator_scale_pass](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/integrator/fn.integrator_scale_pass): Schedule + certify: iterate the interval trajectory over the declared frames, hull per net and per state, choose the block scale over everything, and emit the certificate. ## logicaffeine_compile::codegen_ana::lower Float-function → analog-netlist lowering — the analog lane’s Futamura moment. - [fn analog_netlist_from_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/lower/fn.analog_netlist_from_source): Lower `fn_name` in `src` to an analog tile netlist realizable on `target`. ## logicaffeine_compile::codegen_ana::nonideal The non-ideality model — sourced physics, seeded instances, and the instance evaluator. - [struct InstanceSample](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/nonideal/struct.InstanceSample): One manufactured die: per-cell per-leg fractional gain errors, per-cell output offsets (volts), and a frozen per-cell noise realization (volts). - [struct NonIdealityModel](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/nonideal/struct.NonIdealityModel): The characterized non-ideality figures a physical target carries. - [enum Separation](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/nonideal/enum.Separation): Physical separation of a tile from its operand — the Pelgrom law’s input. Same-tier separation is a distance (the gradient applies); separately manufactured tiers are a CATEGORY, not a distance. - [const KSIGMA](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/nonideal/constant.KSIGMA): The k·σ envelope every budget term and frozen draw uses. At k = 6 a fixed-seed battery is deterministically green forever (p(>6σ) ≈ 2e-9 per draw, evaluated once at authoring time). - [fn eval_analog_instance](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/nonideal/fn.eval_analog_instance): Evaluate one die: the volt-domain converter path over the QUANTIZED netlist with the instance’s gain errors, offsets, and frozen noise applied per tile. - [fn eval_analog_instance_chopped](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/nonideal/fn.eval_analog_instance_chopped): Evaluate one die CHOPPED: two frames — normal and polarity-swapped (each frozen offset enters negated) — with FRESH noise per frame (drawn from `frame_seed`), averaged by the digital side. The frozen offsets cancel EXACTLY; what survives is a deterministic intra-pair residual draw (the model’s `chop_residual_v` class) and √2-averaged noise. - [fn leg_sigma](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/nonideal/fn.leg_sigma): The per-leg 1σ gain-error class over a 2D placement — the shared law at `SameTier`. - [fn sample_instance](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/nonideal/fn.sample_instance): Draw one die. Deterministic in `seed`. - [fn separation_sigma](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/nonideal/fn.separation_sigma): THE shared separation law every budget composes with: programming accuracy plus the distance gradient in-tier; programming accuracy plus the flat categorical ceiling across tiers. 2D `leg_sigma` and the 3D stacked budget are both thin wrappers over this. - [fn sky130_nonideal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/nonideal/fn.sky130_nonideal): The SKY130-class model. ## logicaffeine_compile::codegen_ana::ontology The typed ontology of analog circuits. - [enum BjtRegion](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/enum.BjtRegion) - [enum ComputeOp](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/enum.ComputeOp): Layer 2: the compute vocabulary — the ops the ontology recognizes. The REALIZED subset is bijective with today’s tile IR; the rest are named-future (the `KNOWN_PLANNED` ledger). - [enum DiodeRegion](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/enum.DiodeRegion) - [enum Element](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/enum.Element): One element of the analog universe. - [enum ElementRole](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/enum.ElementRole): Layer 3: an element’s role — the total classification the ledgers pin. - [enum FunctionalMacro](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/enum.FunctionalMacro): Functional macros — the characterized, replicated blocks a chip is actually built from. - [enum MosRegion](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/enum.MosRegion) - [enum Passive](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/enum.Passive): Two-terminal and passive network elements. - [enum Semiconductor](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/enum.Semiconductor): Semiconductor primitives, by device × operating region (the region IS the mathematical law the element contributes — subthreshold is exp, saturation is square-law). - [enum SourceElement](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/enum.SourceElement): Independent and controlled sources — the linear-network vocabulary. - [enum SupportFunction](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/enum.SupportFunction): What a non-compute element does for the chip. - [const ALL_COMPUTE_OPS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/constant.ALL_COMPUTE_OPS) - [const ALL_ELEMENTS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/constant.ALL_ELEMENTS): Every element, exactly once, in canonical order — the census surface. - [const REALIZED_OPS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/constant.REALIZED_OPS): The ops whose tile kinds exist in the ADL today (`ALL_ANALOG_CELL_KINDS`) — the anchor of the realized/planned split. - [fn cell_kind_op](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/fn.cell_kind_op): Total injection of today’s tile IR into the vocabulary — no wildcard, so a new cell kind cannot escape the ontology. - [fn element_name](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/fn.element_name): The census device: a stable name per element — exhaustive by construction (delegates to the leaf enums’ `Debug`, which the census lock pins for duplicates and coverage). - [fn realizing_elements](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/fn.realizing_elements): Which elements realize each compute op — exhaustive, non-empty. For REALIZED ops every listed realizer is itself `ComputeMapped`/`Interface` (the lock proves it); for PLANNED ops the realizers are the elements whose lowering phase will promote them. - [fn role](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/ontology/fn.role): THE role classification — exhaustive over every leaf, no `_` arm anywhere. ## logicaffeine_compile::codegen_ana::place Non-ideality-aware placement — operand adjacency as a matching resource. - [struct AnalogPlacement](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/place/struct.AnalogPlacement): Per-cell site assignment on the target’s tile array. - [fn place_analog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/place/fn.place_analog): Greedy operand-adjacent placement: seat cells in SSA order, each at the free site with the smallest total pitch distance to its already-placed operands (row-major tie-break — deterministic, reproducible). - [fn place_blind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/place/fn.place_blind): The deliberate straw man: maximum-stride scatter (successive cells thrown to opposite corners), used by the anti-vacuity lock to prove aware placement pays. ## logicaffeine_compile::codegen_ana::reduction The streamed reduction — the flagship MAC lane. - [struct AnalogReduction](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/reduction/struct.AnalogReduction): A lowered streamed reduction. Tick-input convention: `In(0)` = the streamed element, `In(1)` = the held accumulator; `out` = the next accumulator value. - [fn analog_int_reduction_from_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/reduction/fn.analog_int_reduction_from_source): Lower a `Seq of Int` accumulator loop to a GRID-PRESERVING streamed reduction — the integer MAC. The exactness claim is made downstream by `super::exactness_gate` over the iterated budget. - [fn analog_reduction_from_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/reduction/fn.analog_reduction_from_source): Lower `fn_name` (a single-`Seq of Float`-parameter accumulator loop) to a streamed analog reduction realizable on `target`. - [fn eval_analog_sampled](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/reduction/fn.eval_analog_sampled): Ideal sampled evaluation: the VM’s loop trajectory, tick by tick (bit-exact — same f64 ops in the same order). - [fn eval_analog_sampled_quantized](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/reduction/fn.eval_analog_sampled_quantized): The physical sampled tier: each element DAC-quantized on entry, the accumulator CONTINUOUS across frames (it lives in the S&H), one ADC quantization at the end — over the weight-quantized tick. - [fn reduction_error_budget](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/reduction/fn.reduction_error_budget): The reduction budget: the shared ε engine ITERATED over the declared maximum frame count — the element’s DAC half-LSB enters every frame, the weight-snap deviation injects every frame, the accumulator’s lanes carry, and one ADC half-LSB lands at the end. - [fn reduction_scale_pass](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/reduction/fn.reduction_scale_pass): Schedule + certify the reduction: quantize the tick’s weights, ITERATE the interval propagation over the declared maximum frame count (hulling per net), choose the block scale over the whole trajectory, and emit the certificate the independent checker replays with the same iteration. ## logicaffeine_compile::codegen_ana::spice_emit Behavioral ngspice emission — the analog lane’s “iverilog tier”. - [const SPICE_ABSTOL](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/spice_emit/constant.SPICE_ABSTOL) - [const SPICE_RELTOL](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/spice_emit/constant.SPICE_RELTOL): The pinned simulator options — tests read these back from the emitted netlist to derive their simulator-discretization term. - [const SPICE_VNTOL](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/spice_emit/constant.SPICE_VNTOL) - [fn emit_spice_dc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/spice_emit/fn.emit_spice_dc): Emit a DC operating-point netlist for one input point: sources at the block scale, one behavioral element per tile, the output node written via `wrdata`. ## logicaffeine_compile::codegen_ana::stack The constructive 2.5D/3D stack ADL. - [struct CoolingBoundary](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack/struct.CoolingBoundary) - [struct DigitalTierPower](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack/struct.DigitalTierPower): The digital tier’s sourced power injection. - [struct Material](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack/struct.Material): A tier’s bulk material for lateral heat spreading. - [struct StackTarget](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack/struct.StackTarget): The composed stack — tiers bottom-up, gap `i` between tier `i` and tier `i+1`. - [struct Tier](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack/struct.Tier): One tier of the stack, bottom-up. - [struct VerticalClass](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack/struct.VerticalClass): A counted vertical interconnect class in one gap — SCARCE like `mul_tiles`. TSVs conduct heat: `g_w_per_k` is per-via thermal conductance, a placement-dependent cooling lever. - [enum CoolingClass](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack/enum.CoolingClass): How the stack sheds heat at its faces. S1 states the boundary; S5 makes the refusals. - [enum FigureStatus](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack/enum.FigureStatus): Provenance of a physical figure — the dossier discipline as a type. - [enum StackShapeError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack/enum.StackShapeError): A shape violation — a stack that cannot mean anything is refused with a name. - [enum TierFabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack/enum.TierFabric): What computes on a tier. - [enum VerticalKind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack/enum.VerticalKind) - [fn analog_artifact_on_stack](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack/fn.analog_artifact_on_stack): Compile an analog region ONTO a stack: resolve the analog tier and delegate to the 2D lane — the degenerate embed is bit-identical by construction (locked, not assumed). ## logicaffeine_compile::codegen_ana::stack_place 3D placement over composed analog tiers — vertical interconnect as a COUNTED, refusable resource, and the cross-tier Pelgrom category priced into the budget. - [struct StackPlacement](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack_place/struct.StackPlacement): Per-cell site assignment plus the per-gap via ledger. - [struct StackSite](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack_place/struct.StackSite): A physical site in the stack: which STACK tier, and where on its array. - [fn error_budget_nonideal_stacked](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack_place/fn.error_budget_nonideal_stacked): The stacked physical budget: the SAME composition engine as 2D, fed the full separation law — cross-tier legs pay the categorical ceiling, so hot scattering provably costs ε. - [fn error_budget_thermal_stacked](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack_place/fn.error_budget_thermal_stacked): The thermally-coupled stacked budget: the stacked budget PLUS the drift terms priced against the CERTIFIED thermal map — offset drifts with each tile’s absolute rise (`offset_tempco · ΔT`), gain with the tile-to-operand GRADIENT (`gain_tempco · |ΔT_cell − ΔT_operand|`) — matching cares about gradients. One Picard pass, deterministic: placement + power → temperature → ε; hot placement provably costs ε (`thermal_cooking_lock` measures it). The ℚ→f64 bridge rounds outward. - [fn place_stack](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack_place/fn.place_stack): Greedy operand-adjacent 3D placement: seat cells in SSA order at the FEASIBLE free site minimizing lateral-plus-hop cost to the placed operands (tier-major row-major tie-break — deterministic forever). A cell with no feasible site refuses on the blocking gap. - [fn place_stack_blind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/stack_place/fn.place_stack_blind): The deliberate straw man: max-stride scatter over the tier-major site list, adjacency- and hop-blind (it still refuses rather than overcommit a gap — legality is non-negotiable). ## logicaffeine_compile::codegen_ana::target The `AnalogTarget` ADL — the analog lane’s described-fabric spine, shaped as a characterized analog PDK for the compiler, not a feature checklist. - [struct AnalogTarget](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/target/struct.AnalogTarget): A described analog fabric. One lowering retargets across shapes by varying this descriptor; each demand is either realizable on it or refused with a typed `AnaUnplaceable`. - [enum AnaUnplaceable](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/target/enum.AnaUnplaceable): Why a netlist cannot be realized on a given analog target — a TYPED refusal, never a silently-wrong circuit. - [enum AnalogCapability](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/target/enum.AnalogCapability): A discrete capability a lowering demands of an analog target — the unit of typed refusal. Continuous demands (gain ratios, integrator rates, multiplier references) refuse through their own `AnaUnplaceable` variants, which carry the offending value. - [enum AnalogCellKind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/target/enum.AnalogCellKind): An analog tile kind the fabric can realize. - [const ALL_ANALOG_CELL_KINDS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/target/constant.ALL_ANALOG_CELL_KINDS): Every analog tile kind — the cell universe a superset target provides. ## logicaffeine_compile::codegen_ana::thermal The certified thermal map — `G·ΔT = P` over exact ℚ, judged independently. - [struct ThermalMap](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/thermal/struct.ThermalMap): A certified-solvable thermal map: the exact claim plus f64 conveniences for consumers. - [struct ThermalOpts](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/thermal/struct.ThermalOpts): The modeled-fidelity knobs. Every figure is a design parameter of OUR model, labeled in `THERMAL_MODEL_PROVENANCE` and anchored in `benchmarks/silicon/analog/thermal-constants.md`. - [const THERMAL_MODEL_PROVENANCE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/thermal/constant.THERMAL_MODEL_PROVENANCE): Provenance of the model’s figures — pinned by `thermal_provenance_lock`. - [fn check_cooling](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/thermal/fn.check_cooling): Judge the CERTIFIED map against the stack’s DECLARED cooling budget: every junction must sit under `t_junction_max_c` at the stated ambient. The refusal names the hottest node, its tier, both temperatures, and the cooling class — the same program may compile under a stronger class; that verdict belongs to the checker’s map, not the producer’s optimism. - [fn cooling_class_name](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/thermal/fn.cooling_class_name): The name of a cooling class, for refusal messages. - [fn film_coefficient_w_m2k](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/thermal/fn.film_coefficient_w_m2k): The carried film-coefficient point for a cooling class, W/(m²·K). - [fn thermal_default_opts](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/thermal/fn.thermal_default_opts): The V1 defaults. - [fn thermal_map](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/thermal/fn.thermal_map): Build and exactly solve the stack’s steady-state thermal network for one placed region. ## logicaffeine_compile::codegen_ana::wta Winner-take-all — the O7 stretch: the MARGIN CERTIFICATE arrives before the tile does. - [struct WtaOutcome](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/wta/struct.WtaOutcome): One judged winner-take-all readout. - [fn wta_winner](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/wta/fn.wta_winner): Judge an ideal value vector at block scale `s`: argmax, top-two margin, and whether the margin clears the offset resolution band. `None` for fewer than two competitors. ## logicaffeine_compile::codegen_ana::xbar Crossbar canonicalization — folding a gain/sum tree into single Kirchhoff columns. - [fn fold_crossbar](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/xbar/fn.fold_crossbar): Fold gain-into-sum and sum-into-sum to fixpoint, then prune dead tiles. Order-preserving: spliced addends keep their producer’s addend order at the consumer’s position, so the evaluation order stays deterministic. - [fn fold_crossbar_for](https://docs.logicaffeine.com/logicaffeine_compile/codegen_ana/xbar/fn.fold_crossbar_for): Fold to fixpoint, prune, then TREE the columns back down to the physical summing fan-in: a folded column wider than `max_fanin` splits into balanced sub-sums (weights ride on the leaves; the joining nodes take unit weights), because fan-in is a physical resource — the summing node’s loading, settling, and noise all grow with it. ## logicaffeine_compile::codegen_c - [mod concurrency](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/concurrency/): The concurrency-lowering knob for the C-family backends. - [mod cshake](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/cshake/): Structural reachability over an emitted C translation unit — split the runtime into top-level definition UNITS, then keep only those reachable (transitively) from a set of root symbols. - [mod from_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/from_program/): ★ Phase 1 — the `CompiledProgram → C` Op-walker (bytecode-IR-as-source-of-truth re-base) ★ - [mod value_runtime](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/value_runtime/): The value runtime a C program links when the exact extension reaches it: `logicaffeine-data`’s C ABI over the compiled value model (`logos_rt_value_*`, see `logicaffeine_data::abi`), built on demand as one static library, so both C backends compute with the compiler’s own values. A program the extension never reaches declares nothing and links nothing more than it did. - [enum TaskTier](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/enum.TaskTier): How a concurrent program’s tasks run: as coroutines on stacks of their own (`ucontext`, host C), or as resumable step functions over heap frames (the stepped tier: the host walker and the GPU). - [const CRDT_CORE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/constant.CRDT_CORE): The C family’s convergent collections: the data crate’s observed-remove set (add-wins and remove-wins) and its observed-remove map of last-writer values, ported once, in C every tier compiles — both C generators, the stepped tier and RISC-V. A tier defines its qualifiers and its allocator before this text (see the file’s header). - [const FILE_RUNTIME](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/constant.FILE_RUNTIME): The files a program reads, writes and mounts (`Read … from file`, `Write … to file`, `Mount`), resolved under the working directory as the native file system resolves them. Emitted only for a program that uses one. - [const SCHED_CORE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/constant.SCHED_CORE): The C family’s scheduler: `logicaffeine_runtime::Scheduler::process_step` ported once, in C every tier compiles — the host C and RISC-V coroutine runtimes, and the stepped tier’s frames CUDA and the bytecode walker run. A tier defines its qualifiers, its allocator and its own task fields before this text, and supplies only the yield (see the file’s header). - [const USER_CODE_SENTINEL](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/constant.USER_CODE_SENTINEL): Marks the boundary between the fixed runtime/type prelude and the program’s own code in a `codegen_program_c` translation unit. The CUDA AOT tier splits here to lift the user code onto the device; it is an ordinary C comment to gcc. - [fn codegen_monomorphic_program_c](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/fn.codegen_monomorphic_program_c): `codegen_program_c` for a monomorphized program: `instances` names the generic type each instance type applies, so its values show under the generic’s name. - [fn codegen_program_c](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/fn.codegen_program_c) - [fn refused_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/fn.refused_program): The C of a program every run of which fails before any output, `reason` on stderr: what a program the VM refuses before running it does. ## logicaffeine_compile::codegen_c::concurrency The concurrency-lowering knob for the C-family backends. - [struct ConcurrencyTradeoff](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/concurrency/struct.ConcurrencyTradeoff): One knob’s trade-off — the regime where the setting wins and where it loses (why it can’t be baked in unconditionally). Mirrors `crate::codegen_cuda::KnobTradeoff` but kept local so `codegen_c` does not depend on `codegen_cuda`. - [struct SchedulerConfig](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/concurrency/struct.SchedulerConfig): All scheduler knobs, bundled. Has a `Default` and fluent setters so it is easy to annotate while still having a sensible baseline. - [struct SchedulerKnobs](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/concurrency/struct.SchedulerKnobs): The knobs that parameterize the emitted deterministic scheduler. This is the SAME `SchedulerConfig` the oracle runtime (`logicaffeine_runtime`) runs — the ready-queue `policy` (FIFO / LIFO / round-robin / seeded-random / priority), the `clock` (virtual `Logical` vs `Wall`), the default channel capacity, and the M:N `workers` count (1 = cooperative single core, N = work-stealing) — plus the `seed` that drives the seeded chooser for the random-choice points (`TaskPick` under `Random`, `SelectWinner`, `TimerTieBreak`). Emitting C straight from a `SchedulerConfig` guarantees the AOT scheduler’s knobs are ONE-TO-ONE with the oracle’s, so a program run at `knobs` on the VM and the same `knobs` in AOT-C agree. - [enum CTarget](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/concurrency/enum.CTarget): A C-family lowering target, classified by whether it can express stackful coroutines. The concurrency knob is forced to `ConcurrencyLowering::Stackless` exactly when `ucontext` is absent. - [enum ClockMode](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/concurrency/enum.ClockMode): How the scheduler’s clock advances. - [enum ConcurrencyLowering](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/concurrency/enum.ConcurrencyLowering): How the C-family backend lowers a task’s suspend/resume. One point in the (one-dimensional) knob lattice; pick with `ConcurrencyLowering::for_target`. - [enum SchedulePolicy](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/concurrency/enum.SchedulePolicy): The ready-task selection discipline. Determinism holds under every policy: `Fifo`/`Lifo`/`RoundRobin`/`Priority` are deterministic by construction, and `Random` resolves its pick through the seeded `Chooser`, so it is reproducible under a fixed seed. ## logicaffeine_compile::codegen_c::cshake Structural reachability over an emitted C translation unit — split the runtime into top-level definition UNITS, then keep only those reachable (transitively) from a set of root symbols. - [struct CUnit](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/cshake/struct.CUnit): One top-level C construct: a typedef, a `static` function definition or forward declaration, or a file-scope global. `defined` is the symbol(s) it introduces; `references` is every identifier it mentions (an over-approximation of its dependencies); `text` is the exact source span (with any leading comment/blank lines attached, so units travel with their doc comment). - [enum UnitKind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/cshake/enum.UnitKind) - [fn c_identifiers](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/cshake/fn.c_identifiers): Collect every C identifier in `s`, skipping string/char literals and comments. - [fn macro_references](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/cshake/fn.macro_references): A `#define`’s macro name and the names its replacement mentions, its own parameters left out: a macro is expanded where it is named, so what it names is reached through it. `None` for any other directive. A preprocessor unit is its one directive behind whatever comments `parse_c_units` attached to it. - [fn parse_c_units](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/cshake/fn.parse_c_units): Split an emitted C translation unit into top-level `CUnit`s. Leading comments/blank lines attach to the unit that follows. `#…` preprocessor directives, backslash-continued lines included, are their own `UnitKind::Preproc` units. - [fn reachable_units](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/cshake/fn.reachable_units): Indices (in original order) of the units transitively reachable from `roots`. A unit is reached when any symbol it defines is in the frontier; reaching it adds every identifier it references. ## logicaffeine_compile::codegen_c::from_program ★ Phase 1 — the `CompiledProgram → C` Op-walker (bytecode-IR-as-source-of-truth re-base) ★ - [struct Offload](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/from_program/struct.Offload): A function whose calls a device may answer: its index in the program, the device region that answers it, and how each parameter and the result cross the boundary. - [struct OffloadedC](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/from_program/struct.OffloadedC): The walker’s C for a program with an offload table, and each offloaded function it keeps on the host with the reason. - [fn compile_program_to_c](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/from_program/fn.compile_program_to_c): Lower a whole `CompiledProgram` to a self-contained C translation unit. Returns a typed refusal (`Err`) for any op/const/kind not yet lowered — the caller falls back to the AST emitter. - [fn compile_program_to_c_offloaded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/from_program/fn.compile_program_to_c_offloaded): The Op-walker with an offload table. Each function the table names asks its device first, at its entry, so every caller’s call is offered: `logos_dev_call(region, args, &out)` with the parameters in their ports, whose DONE answer is the call’s result and whose DECLINED answer runs the body the walker emits for it anyway. A function a port cannot serve — a parameter or result whose settled kind the port does not carry — stays on the host, reported in `kept`. The driver’s definition is the caller’s to append. - [fn compile_program_to_c_with_offloads](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/from_program/fn.compile_program_to_c_with_offloads): The Op-walker with an offload table (`compile_program_to_c_offloaded`); an empty table is `compile_program_to_c_with_policy`. - [fn compile_program_to_c_with_policy](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/from_program/fn.compile_program_to_c_with_policy): The Op-walker with an optional policy context — the `(interner, PolicyRegistry)` a `CheckPolicy` op needs to resolve its predicate/capability name into a condition (the bytecode carries only the name, exactly as the VM consults its `policy_ctx`). A program with no `Check` statement passes `None` and emits byte-identical C to before. This is the seam `compile_to_c_via_bytecode` uses so runtime authorization lowers natively. ## logicaffeine_compile::codegen_c::value_runtime The value runtime a C program links when the exact extension reaches it: `logicaffeine-data`’s C ABI over the compiled value model (`logos_rt_value_*`, see `logicaffeine_data::abi`), built on demand as one static library, so both C backends compute with the compiler’s own values. A program the extension never reaches declares nothing and links nothing more than it did. - [struct Archive](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/value_runtime/struct.Archive): The built library. - [enum Target](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/value_runtime/enum.Target): The machine a library is built for. - [fn archive](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/value_runtime/fn.archive): The library for the host, built once per process. - [fn archive_for](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/value_runtime/fn.archive_for): The library for `target`, built once per process. - [fn archive_link_args](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/value_runtime/fn.archive_link_args): The archive built for `target` and the system libraries it calls, as a link line names them. - [fn link_args](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/value_runtime/fn.link_args): What `code` puts on its link line after its own source: the value runtime’s archive and the system libraries the archive calls, when the program links it; nothing otherwise. - [fn links](https://docs.logicaffeine.com/logicaffeine_compile/codegen_c/value_runtime/fn.links): Whether the emitted C program `code` links the value runtime. ## logicaffeine_compile::codegen_cuda LOGOS → CUDA AOT codegen tier. Emits ONE self-contained CUDA program — a `__global__` kernel that runs a whole LOGOS program on a single GPU thread, plus a host orchestrator — for the integer/bool scalar fragment of the language. - [mod chip](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/chip/): The GPU chip / family knob — which NVIDIA silicon the CUDA backend targets. - [mod forward_shim](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/forward_shim/): What the older compiled forward runs whole (`compile_to_cuda_forward*`): its answer to the shared optimizer. - [mod fused_row](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/fused_row/): The fused row-op CUDA emitter — the real one-block-per-row shared-memory reduction kernel. - [mod gdn](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gdn/): Gated DeltaNet lowered to CUDA — the mechanism behind 48 of Qwen3.8-27B’s 64 layers. - [mod gemm_tile](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/): The CUDA GEMM tiling lattice — the search space our optimizing compiler sweeps to climb from the naive one-thread-per-output DP4A kernel toward the cuBLAS ceiling. - [mod knobs](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/knobs/): The CUDA backend’s optimization knob lattice. - [mod lane](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/): The compiled generation lane: a model’s decode step, written in LOGOS from its `ModelSpec` and compiled to one CUDA program that loads the checkpoint, runs the prompt and generates. - [mod lane_link](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane_link/): The lane’s link: each op of the one IR, as the shared optimizer leaves it under the lane’s shim, to the launches the lane’s kernels run it with. - [mod lane_shim](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane_shim/): What the compiled generation lane runs whole: the CUDA lane’s answer to the shared optimizer. - [mod matrix](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/matrix/): The INT8 weight-stationary GEMM path of the CUDA tier — the workload a GPU (and an RDU) actually exists for: `O(M×N) = A(M×K) · W(K×N)` in int8, the shape every transformer projection and attention dot reduces to. - [mod provenance](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/provenance/): Where an emitted CUDA program came from, stated in its first line. Every whole-program emitter takes its header from `header`, so no program can claim a provenance it does not have — in particular, a hand-written lane cannot say it was compiled from a model’s `.lg`. - [mod qwen38](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/): Qwen3.8-27B authored in LOGOS. - [mod qwen38_batched](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38_batched/): ════════════════════════════════════════════════════════════════════════════════════════════════ ★ BATCHED Qwen3.8-27B DECODE ★ — where the bandwidth wall stops being the wall. - [mod qwen_batched](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_batched/): ════════════════════════════════════════════════════════════════════════════════════════════════ BATCHED Qwen3-30B decode — the lane where “beat llama” is a landslide, not a 4% wall. - [mod qwen_emit](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/): The whole-forward orchestrator — composing a multi-stage LOGOS tensor-op program into ONE CUDA program that chains genuine PARALLEL kernels through shared device buffers. - [mod solbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/solbench/): SOL-ExecBench harness bridge — turn a recognized LOGOS fused-row op into a submittable `solution.json` plus a torch-binding CUDA kernel that conforms to the benchmark’s ABI. - [struct CudaArtifact](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/struct.CudaArtifact): A complete single-file CUDA program emitted from a LOGOS program. - [enum CudaLowerError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/enum.CudaLowerError): An op / value outside the CUDA scalar fragment. The `&str` names what is not lifted. A refusal — the backend declines rather than emit wrong code (mirrors `crate::codegen_riscv::RiscVLowerError` / `crate::codegen_tt::TtLowerError`). - [const CUDA_MAKEFILE_TEMPLATE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/constant.CUDA_MAKEFILE_TEMPLATE): Makefile glue: builds the single-file CUDA program with `nvcc` for the Ampere (`sm_86`, the RTX 3060 class) target. `{KERNEL_FILE}` is substituted with the emitted source name. - [const CUDA_NET_OPS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/constant.CUDA_NET_OPS): The OFFLINE NETWORKING ops the device serves via the loopback transport (`codegen_c`’s `C_NET_RUNTIME`, device-lifted). `Connect`/`Listen`/`Sync` are no-ops, `MakePeer` is identity, `Send`/`Stream` enqueue a 64-bit message into a per-address FIFO, `Await` dequeues it — so a single-node `Send X to peer; Await …` round-trips ≡ the VM’s offline `NetInbox`. Every op here is also in `CUDA_SCALAR_OPS`; excluded from the offload refusal below (they are now device-served, not host-only). Bound by `cuda_aot_lock`. - [const CUDA_SCALAR_OPS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/constant.CUDA_SCALAR_OPS): The op names the CUDA scalar fragment lowers today — integer/bool arithmetic, comparisons, control flow, calls, globals, and `Show`. EXHAUSTIVELY enforced against the VM ISA by `cuda_aot_lock` (floor + shrink-only gaps), so this set can only grow. A scalar op whose value escapes to BigInt/Rational/Float/Text is still caught, by the device-cleanliness backstop — this list is necessary, not sufficient, for support. - [const KERNEL_FILE_NAME](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/constant.KERNEL_FILE_NAME): The single canonical name of the emitted CUDA source (referenced by the Makefile). - [const LOGOS_DEVICE_FLOAT_FMT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/constant.LOGOS_DEVICE_FLOAT_FMT): The device `__device__` C source for `logos_fmt_f64` (and its bignum helpers). Substituted for the host body when the CUDA device-lift reaches `logos_fmt_f64` (see `super::device_lift`). Self- contained: references only `malloc`/`memcpy`/`isnan`/`isinf` (all device-available). - [fn codegen_program_cuda](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/fn.codegen_program_cuda): Emit `program` as a single-file CUDA program. `oracle_c` is the self-contained C translation of the SAME program (from `crate::compile::compile_to_c_stepped`, which is `crate::compile::compile_to_c`’s C for a program with no tasks); its program-region compute is lifted onto the device. Returns `CudaLowerError::Unsupported` if the program leaves the scalar fragment (op-level or value-escape). - [fn unsupported_reason](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/fn.unsupported_reason): `Some(reason)` if `program` uses an op outside the CUDA scalar fragment. Host-only IO and the DOM get the shared single-device reason (`crate::aot_unsupported`); everything else that is not a scalar op is named directly. ## logicaffeine_compile::codegen_cuda::chip The GPU chip / family knob — which NVIDIA silicon the CUDA backend targets. - [struct CudaChip](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/chip/struct.CudaChip): A described CUDA target part — the hardware limits and realized numeric formats that make the fastest kernel chip-specific, plus the SM arch its kernels are compiled for. Construct with a named part (`CudaChip::rtx3060`, `CudaChip::b200`, …); the emitter reads it to pick the arch flag, the shared-memory budget, and which precisions are legal. - [enum GpuFamily](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/chip/enum.GpuFamily): An NVIDIA GPU architecture family — fixes the tensor-core generation and which numeric formats exist. ## logicaffeine_compile::codegen_cuda::forward_shim What the older compiled forward runs whole (`compile_to_cuda_forward*`): its answer to the shared optimizer. - [struct ForwardShim](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/forward_shim/struct.ForwardShim): The older forward under its numerics. - [fn kernel_refusal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/forward_shim/fn.kernel_refusal): Why the forward’s kernels do not compute a lifted op, or `None` when they do. The spec is the op’s meaning: a field of it the kernel does not implement is a refusal, never a field the kernel ignores. ## logicaffeine_compile::codegen_cuda::fused_row The fused row-op CUDA emitter — the real one-block-per-row shared-memory reduction kernel. - [fn emit_fused_row](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/fused_row/fn.emit_fused_row): Emit a self-contained CUDA program for a recognized fused row op: one `__global__` block per row doing a shared-memory tree reduction over `cols`, plus a host that fills `X` deterministically and prints `Σ Y`. `knobs.chip` stamps the provenance header (and drives the arch the caller compiles for). - [fn emit_swiglu](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/fused_row/fn.emit_swiglu): Emit a self-contained CUDA program for a recognized SwiGLU map — `y[i] = silu(gate[i]) * up[i]`, one thread per element, self-contained host (deterministic fills + `Σ Y` checksum). Chip-stamped like the fused-row. ## logicaffeine_compile::codegen_cuda::gdn Gated DeltaNet lowered to CUDA — the mechanism behind 48 of Qwen3.8-27B’s 64 layers. - [const GDN_KERNELS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gdn/constant.GDN_KERNELS): One block per `(value head, row)` computes that row’s `u`, `w` and the shared `k·q` in a single pass over the memory, then rewrites the row from the register it already holds. `o` lands in scratch; the gated RMSNorm needs the whole head, so it is a second (tiny) kernel. - [const QWEN38_KERNELS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gdn/constant.QWEN38_KERNELS): The rest of the Qwen3.8-specific device code: the pieces of a GDN layer that surround the recurrence, plus the two things gated attention needs that a plain transformer does not (a partial rotary and an output gate). Each is deliberately fused past what a per-operator graph could do — the conv carries silu, the gate kernel computes both gates from one launch, and the norm+rope stay one pass over the head. - [fn emit_gated_delta_forward](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gdn/fn.emit_gated_delta_forward): Emit a self-contained CUDA program for ONE Gated DeltaNet step with every input inlined, so the fused kernels above can be checked against the LOGOS `gated delta` op on the VM at small shapes on any GPU — the same shape of proof `emit_moe_forward` gives the MoE block. Prints `O` then the mutated memory `S`, because a desugar that ignored the memory would otherwise pass. ## logicaffeine_compile::codegen_cuda::gemm_tile The CUDA GEMM tiling lattice — the search space our optimizing compiler sweeps to climb from the naive one-thread-per-output DP4A kernel toward the cuBLAS ceiling. - [struct CudaTile](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/struct.CudaTile): A point in the GEMM tiling lattice. - [struct CutlassI8Gemm](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/struct.CutlassI8Gemm): A CUTLASS int8 tensorop-GEMM config. cuBLAS’s own int8 GEMM kernel IS a CUTLASS kernel — disassembly of `cublasGemmEx` (CUDA_R_8I, TN, 2048^3, sm_86) shows it dispatch `cutlass_80_tensorop_i16832gemm_s8_256x128_64x3_tn_align16`. Because CUTLASS is open source, our compiler can emit the same kernel and reach cuBLAS parity (measured 99.6-100.0% head-to-head), instead of approximating it with a hand-written kernel that tops out at ~90% (ptxas will not schedule our from-scratch source into the perfect pointer-increment addressing CUTLASS’s templates coax out of it). - [struct CutlassNvfp4Gemm](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/struct.CutlassNvfp4Gemm): A CUTLASS Blackwell (sm_100) NVFP4 block-scaled GEMM config — the GPU MODE `nvfp4_gemm` leaderboard target. Operands are FP4 (e2m1) with per-16-element FP8 (ue4m3) block scale factors; accumulate FP32; output FP16. cuBLAS/`torch._scaled_mm`’s own NVFP4 path is a CUTLASS kernel (as with int8), so our compiler emits the same CollectiveBuilder GEMM and then pulls ahead by consuming the pre-permuted GPU scale factors directly (the reference re-derives them from a CPU tensor inside the timed region — free speedup) + epilogue fusion. NOTE: sm_100 / NVFP4 requires CUTLASS >= 3.7 and a Blackwell GPU; validate on the leaderboard runner (`popcorn submit --mode test --gpu B200`), not on sm_86 hardware. - [struct GpuLimits](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/struct.GpuLimits): The per-block hardware budget the lattice is bounded by. - [struct WmmaTile](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/struct.WmmaTile): A pipelined-WMMA configuration: block tile `BM×BN`, K-stage `BK`, warp grid `WARPS_M×WARPS_N`. - [enum ComputePrimitive](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/enum.ComputePrimitive): Which compute hardware a GEMM kernel targets. - [enum CutlassEpilogue](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/enum.CutlassEpilogue): A fused pointwise epilogue our compiler folds INTO the GEMM — the thing cuBLAS cannot do in-kernel. cuBLAS must write the GEMM result to global memory and run a SECOND kernel for the activation (an extra full-output read+write); fusing it here removes that round-trip and BEATS a cuBLAS+elementwise baseline. - [enum GemmLayout](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/enum.GemmLayout): GEMM operand layout (BLAS transpose convention). The int8 tensor cores are fastest in `Tn`. - [enum HmmaKernel](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/enum.HmmaKernel): Which half-precision WMMA GEMM kernel is the FASTEST legal choice for a shape. - [enum MmaKind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/enum.MmaKind): The tensor-core (or CUDA-core) MMA family a GEMM lowers to, keyed on operand PRECISION. Int8 (`Dp4aI8` CUDA-core, `WmmaI8` IMMA) already exist; `HmmaBf16`/`HmmaF16` add the half-precision tensor-core path. (FP8/NVFP4 join later via the `mma.sync`/`tcgen05` PTX path on Hopper/Blackwell.) - [const AMPERE_SM_REGS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/constant.AMPERE_SM_REGS): SM-level register file on Ampere (sm_86): 65,536 32-bit registers per SM. A tile needs `regs_per_thread · threads ≤ this` to place at least one block per SM. - [fn cpasync_stages_fit](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.cpasync_stages_fit): A `stages`-deep pipeline fits iff `stages` shared buffers (each = the single-stage footprint) fit smem. - [fn cuda_tile_lattice](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.cuda_tile_lattice): Enumerate the legal tiling lattice for `gpu`: the divisor space of block tiles × K-stages × thread tiles. Only points that pass `CudaTile::is_legal` are returned, so every element is directly emittable. - [fn default_wmma_tile](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.default_wmma_tile): A sensible default rung-3 config: 128×128 block, BK=32, 8 warps (2×4), so each warp owns a 64×32 warp-tile = 4×2 = 8 fragments. This is the classic WMMA GEMM shape. - [fn emit_cutlass_i8_gemm](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_cutlass_i8_gemm): Plain GEMM (parity with cuBLAS) — the un-fused kernel. - [fn emit_cutlass_i8_gemm_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_cutlass_i8_gemm_bench): Full head-to-head parity program: our compiler-emitted CUTLASS kernel vs `cublasGemmEx`, same process, interleaved best-of-100, varied-fill oracle-checked. Prints `PARITY OURS CUBLAS `. - [fn emit_cutlass_i8_gemm_ep](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_cutlass_i8_gemm_ep): Emit the CUTLASS int8 TN GEMM kernel our compiler chooses — the same one cuBLAS runs (with an optional fused epilogue). Produces the `using Gemm = ...` instantiation + an `extern "C" run_gemm_k` launcher. Requires the CUTLASS headers on the include path (`-I /include`). - [fn emit_cutlass_i8_gemm_relu_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_cutlass_i8_gemm_relu_bench): Full head-to-head program: our FUSED GEMM+ReLU vs the baseline cuBLAS forces (GEMM then a SEPARATE relu kernel). Both are oracle-checked against `relu(A*B)` and against each other; prints `FUSED SPEEDUP x` (our_time vs cublas+relu_time). This is where we BEAT cuBLAS — via fusion. - [fn emit_cutlass_nvfp4_gemm](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_cutlass_nvfp4_gemm): Emit our compiler’s CUTLASS Blackwell NVFP4 block-scaled GEMM as a torch-extension launcher for `load_inline` on the Blackwell leaderboard runner. Consumes the pre-permuted FP8 block scales directly. - [fn emit_cutlass_nvfp4_group_gemm](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_cutlass_nvfp4_group_gemm): Emit our compiler’s CUTLASS Blackwell NVFP4 grouped GEMM (MoE) — all G experts in ONE kernel launch via CUTLASS `GroupProblemShape` + per-group pointer arrays. This is the fusion edge on the GPU MODE `nvfp4_group_gemm` leaderboard: the reference launches G separate GEMMs; we launch one grouped kernel over all experts (no per-expert launch overhead, one wave of tensor-core work). Validate on the B200 runner. - [fn emit_gemm_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_gemm_program): Emit a full runnable GEMM program, choosing the compute primitive from the problem + hardware. When the GPU has tensor cores and the shape is 16-aligned, this emits the WMMA (tensor-core) kernel; otherwise the tiled DP4A (CUDA-core) kernel driven by `tile`. Both paths are byte-exact vs the scalar oracle. - [fn emit_mma_tn_colb_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_colb_bench) - [fn emit_mma_tn_colb_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_colb_program) - [fn emit_mma_tn_cpasync_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_cpasync_bench) - [fn emit_mma_tn_cpasync_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_cpasync_program) - [fn emit_mma_tn_i8](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_i8) - [fn emit_mma_tn_i8_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_i8_bench) - [fn emit_mma_tn_i8_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_i8_program) - [fn emit_mma_tn_k32_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_k32_bench) - [fn emit_mma_tn_k32_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_k32_program) - [fn emit_mma_tn_k32db_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_k32db_bench) - [fn emit_mma_tn_k32db_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_k32db_program) - [fn emit_mma_tn_k32swz_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_k32swz_bench) - [fn emit_mma_tn_k32swz_kernel](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_k32swz_kernel): Emit JUST the swizzled-k32 kernel (no host main) — so the compiler can compile it to a cubin and analyze its SASS (register pressure, occupancy, tensor-core utilisation) via `codegen_sass::SassReport`. - [fn emit_mma_tn_k32swz_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_k32swz_program) - [fn emit_mma_tn_k64_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_k64_bench) - [fn emit_mma_tn_k64_kernel](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_k64_kernel): Emit JUST the BK=64 champion kernel (no host main) — for the head-to-head cuBLAS parity harness and SASS analysis. Renames the entry to the given symbol so it can be linked beside cublas in one program. - [fn emit_mma_tn_k64_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_k64_program) - [fn emit_mma_tn_ldm_cfg_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_ldm_cfg_bench): Emit the ldmatrix+mma.sync.s8 TN kernel for a specific config so the frontier can sweep block/warp/stage shapes on-device. `stages` shared buffers (cp.async N-stage). WN must be a multiple of 8, WM of 16. - [fn emit_mma_tn_ldm_swizzle_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_ldm_swizzle_bench) - [fn emit_mma_tn_ldm_swizzle_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_ldm_swizzle_program): The swizzled program (varied-fill oracle correctness). - [fn emit_mma_tn_ldmatrix_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_ldmatrix_bench) - [fn emit_mma_tn_ldmatrix_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_mma_tn_ldmatrix_program) - [fn emit_tiled_dp4a](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_tiled_dp4a): Emit a shared-memory + register-blocked tiled DP4A GEMM kernel for `tile`. Each block stages a `bm×bk` slice of A and a `bk×bn` slice of B into shared memory (every byte reused across the block — the reuse the naive one-thread-per-output kernel throws away), and each thread accumulates a `tm×tn` register tile with `__dp4a` (4 signed-int8 MACs/instruction) over the K-stage. Computes `C(M×N) = A(M×K)·B(K×N)` in int8 with int32 accumulation. The blocking constexprs are baked from `tile`, so a different lattice point yields a different kernel — genuine compiler output, not a fixed template. - [fn emit_tiled_dp4a_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_tiled_dp4a_bench): Emit a TIMING bench for the tiled kernel at `M×K×N`: fills A/B on device, warms up, times 30 launches with CUDA events, and prints `GOPS ` (2·M·N·K / seconds). Used by the autotuner to measure each lattice point on the real device and lock the fastest. - [fn emit_tiled_dp4a_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_tiled_dp4a_program): Emit a COMPLETE self-contained tiled-DP4A program for shape `M×K×N`: the tiled kernel plus a host `main` that fills A/B deterministically, launches `gemm_tiled_dp4a<<<(N/BN, M/BM), NTHREAD>>>`, and prints the int32 result row-major (one value per line) — so its output is directly comparable to a scalar oracle. Requires the shape to be tile-aligned (`M%bm==0`, `N%bn==0`, `K%bk==0`). - [fn emit_wmma](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma): Emit a WMMA tensor-core GEMM kernel for a tensor-core `MmaKind` — the SAME 16×16×16 fragment loop as the int8 IMMA path, over the operand/accumulator types the precision fixes (bf16/f16 → f32 accumulate). Row-major `A(M×K)·B(K×N)`. (Not for `Dp4aI8`, which is a CUDA-core kernel; use `emit_tiled_dp4a`.) - [fn emit_wmma_basic_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_basic_bench): Timing bench for the BASIC (one-warp-per-16×16-tile) WMMA kernel at `kind` — prints `GOPS `. - [fn emit_wmma_cpasync_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_cpasync_bench): Timing bench for the cp.async double-buffered WMMA kernel at `kind` + `tile` + `stages` — prints `GOPS`. - [fn emit_wmma_cpasync_i8_bench_for](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_cpasync_i8_bench_for) - [fn emit_wmma_cpasync_i8_bench_staged](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_cpasync_i8_bench_staged) - [fn emit_wmma_cpasync_i8_for](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_cpasync_i8_for) - [fn emit_wmma_cpasync_i8_program_for](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_cpasync_i8_program_for) - [fn emit_wmma_cpasync_i8_program_staged](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_cpasync_i8_program_staged): Program/bench for a specific pipeline DEPTH (`stages` shared buffers). 2 = double-buffer; 3-4 = deeper pipeline that keeps the tensor cores fed further ahead (needs `stages × smem` to fit). - [fn emit_wmma_cpasync_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_cpasync_program): Checksum-matching cp.async GEMM program for a tensor-core `kind` (bf16/f16) — Σ C ≡ the scalar oracle on int8-range operands (exact in bf16/f16, wide f32 accumulate). Launches the double-buffered `gemm_wmma_cpasync`. - [fn emit_wmma_i8](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_i8): Emit a WMMA int8 tensor-core GEMM kernel: one warp per 16×16 output tile, accumulating over K in 16-wide fragments with `wmma::mma_sync` (the IMMA path). Row-major A(M×K)·B(K×N) → int32 C(M×N). - [fn emit_wmma_i8_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_i8_bench): Timing bench for the WMMA int8 kernel: warms up, times 30 launches, prints `GOPS `. - [fn emit_wmma_i8_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_i8_program): Full self-contained WMMA int8 program for `M×K×N`: kernel + host `main` that fills A/B deterministically (same fill as the tiled program, so the SAME scalar oracle applies), launches `gemm_wmma_i8<<<(N/16, M/16), 32>>>` (one warp per 16×16 tile), and prints int32 C row-major. - [fn emit_wmma_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_program): Full self-contained WMMA program for `M×K×N` at `MmaKind` `kind` — fills A/B with small integers (exact in bf16/f16/int8), runs one warp per 16×16 tile, and prints `Σ C` (a double). Because the operands are exact small integers and the accumulate is wide (f32/int32), `Σ C` is an exact integer, so a scalar integer GEMM is the ≡ oracle regardless of precision. - [fn emit_wmma_tiled_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_tiled_bench): Timing bench for the PIPELINED (shared-memory, warp-tiled) WMMA kernel at `kind` + `tile` — prints `GOPS`. - [fn emit_wmma_tiled_i8](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_tiled_i8): Emit the pipelined-WMMA kernel with the default config. - [fn emit_wmma_tiled_i8_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_tiled_i8_bench): Emit a timing harness (default config): 30 launches, prints `GOPS `. - [fn emit_wmma_tiled_i8_bench_for](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_tiled_i8_bench_for): Emit a bench for a specific config (for the config sweep). - [fn emit_wmma_tiled_i8_for](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_tiled_i8_for): Emit just the pipelined-WMMA kernel for `tile` (structural / nvcc-compile checks). - [fn emit_wmma_tiled_i8_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_tiled_i8_program): Emit a full runnable program (default config). Same deterministic fill as the other GEMM programs. - [fn emit_wmma_tiled_i8_program_for](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_tiled_i8_program_for): Emit a program for a specific config (for the config sweep). - [fn emit_wmma_tiled_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.emit_wmma_tiled_program): Checksum-matching pipelined-WMMA GEMM program for a tensor-core `kind` (bf16/f16) — the shared-memory, warp-tiled kernel with the matmul emitters’ fill (`a[p]=(p%7)-3`, `b[p]=(p%5)-2`) and the `Σ C` integer checksum, so on int8-range operands (exact in bf16/f16) it equals the scalar oracle byte-for-byte. - [fn feasible_tiles](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.feasible_tiles): The full feasible tile grid — every legal tile that fits Ampere’s smem + register file. PROVABLY COMPLETE over this parameter space: nothing legal is silently dropped. - [fn lattice_best_bf16_bench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.lattice_best_bf16_bench): The knob lattice’s own best bf16 rung for a shape, as a runnable benchmark: the kernel `select_hmma_kernel` picks (cp.async when its tile divides the shape and fits, else the basic WMMA kernel). This is the backend-native baseline a lowering measures itself against — the fair opponent is the best thing this lattice can already emit, not its worst. - [fn pareto_frontier](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.pareto_frontier): CONSTRUCT the measurement frontier: the Pareto-optimal feasible tiles — those NOT dominated by any other feasible tile on the three physical axes (DRAM traffic ↓, SMEM traffic ↓, occupancy ↑). This is the honest “let it construct the answer” step: we do NOT pick a winner and we assume NO weighting — we only discard tiles that are provably worse on every axis (they cannot be optimal), then hand the survivors to the GPU, which crowns the winner by measurement. The frontier is a small superset of the true optimum; the machine, not us, resolves the un-modelable physics (bank conflicts, scheduling) that separates the survivors. - [fn select_hmma_kernel](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.select_hmma_kernel): Select the fastest LEGAL half-precision kernel for `(kind, shape, arch)`: cp.async when the default tile divides the shape and its bf16/f16 footprint fits static shared memory on an Ampere+ part, else the basic kernel. Callers pass a shape already known WMMA-legal (16-aligned) via `select_mma`. - [fn select_layout](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.select_layout): Select the layout to emit FROM THE PROBLEM: if the caller’s data is already TN (or we are free to choose the staging), prefer the tensor-core-native `Tn` for max throughput; if the data is fixed as `Nn` and a transpose would cost more than it saves, stay in `Nn` (where our kernel already beats cuBLAS). `caller_is_tn` = the operands are already available contraction-contiguous. This is the tradeoff knob, not a fixed choice. - [fn select_mma](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.select_mma): Select the MMA kind for a `(precision, shape, sm_arch)`. Tensor-core WMMA when the shape is 16-aligned and the arch provides the precision’s HMMA/IMMA; otherwise the always-legal DP4A CUDA-core fallback — we never emit a tensor-core kernel on a shape or GPU that cannot run it. - [fn select_primitive](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.select_primitive): SELECT the compute primitive FROM THE PROBLEM: use the tensor cores when the GPU has them AND the shape is WMMA-legal (16-aligned); otherwise fall back to DP4A on the CUDA cores. Correct by construction — we never emit a WMMA kernel on a shape or GPU that cannot run it. (Which of the two is actually faster when both are legal is settled by measurement on the frontier, but WMMA is the strictly-more-powerful default.) - [fn wmma_legal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/gemm_tile/fn.wmma_legal): A shape is WMMA-legal iff every dimension is a multiple of the int8 fragment size (16). ## logicaffeine_compile::codegen_cuda::knobs The CUDA backend’s optimization knob lattice. - [struct CudaKnobs](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/knobs/struct.CudaKnobs): The CUDA backend’s optimization knobs — one point in the lattice. Construct with `CudaKnobs::default` for the best-general point and flip individual knobs to trade off. Every field is a trade-off; there are deliberately no fields for strictly-better transforms (those are always applied, see `STRICTLY_BETTER`). - [struct KnobTradeoff](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/knobs/struct.KnobTradeoff): A single knob’s trade-off — why it is a knob and not a baked-in transform. - [enum CachePrecision](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/knobs/enum.CachePrecision): The precision an attention’s cache is stored in (`CudaKnobs::cache_precision`). - [enum LoadWidth](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/knobs/enum.LoadWidth): GEMV/GEMM weight-load width. Wider loads expose more memory-level parallelism (the Q8_0 forward is weight-bandwidth-bound), but cost registers per thread. - [enum MatmulPrecision](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/knobs/enum.MatmulPrecision): Contraction precision for a lowered matmul. - [enum ResolvedPrecision](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/knobs/enum.ResolvedPrecision): What a `MatmulPrecision` actually lowers to after `Auto` is resolved against what we can prove. - [enum StatePrecision](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/knobs/enum.StatePrecision): The precision a recurrent memory is stored in between steps (`CudaKnobs::recurrent_state`). - [const STRICTLY_BETTER](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/knobs/constant.STRICTLY_BETTER): Transforms that are strictly better — Pareto-dominant, never worse for any valid program — and are therefore applied UNCONDITIONALLY with no knob. If any entry here ever acquires a downside, it must grow a `CudaKnobs` field and move out of this list (the knob-lattice lock enforces the disjointness). ## logicaffeine_compile::codegen_cuda::lane The compiled generation lane: a model’s decode step, written in LOGOS from its `ModelSpec` and compiled to one CUDA program that loads the checkpoint, runs the prompt and generates. - [mod arena](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/arena/): The step-local memory of a lane’s forms. Every array a step computes and reads within the step — a tensor’s `f32` (or `i32`) buffer, or its quantized form — lives in one arena the program allocates once, placed by its lifetime: from the launch that first writes it whole to the last launch that touches it, through any view of it. A launch’s scratch lives there while the launch runs. The forms share the arena, one form running at a time. - [mod branches](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/branches/): A form’s launches as a graph over several streams. A launch runs after every earlier launch that writes memory it reads or writes, or reads memory it writes — memory by where it lives: a step-local array or a launch’s scratch by its bytes in the arena (which several tensors share in turn), anything else by its buffer, an alias — a view — where its array lives (`arena::home`). Each launch takes a stream: the stream whose last launch it follows, or one whose work it already follows, or the least recently used; it waits on another stream’s launch by an event only where nothing it already follows orders the two. The launches compute what they compute in order, every dependency kept. - [mod emit](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/emit/): The lane’s forms printed as one CUDA program, and the sidecar of values it reads. - [mod graph](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/graph/): The step graph: an authored step (a decode step, a prefill chunk) as the ops it runs and the tensors they touch, each tensor given the role a compiled lane needs to place it. - [mod kernels](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/): The lane’s kernel library: one CUDA kernel per kind of op a step runs, each templated over the forms the fusion rules ask of it (a residual added before a norm, an activation quantized in a producer’s epilogue, a result written into the row of a cache a position names). The planner instantiates them; no kernel here knows a model. - [mod plan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/): A step graph lowered to launches of the kernel library. The lane decides no fusion of its own: the step, lifted into the one IR, is optimized by the shared table under the lane’s shim (`LaneShim`), which answers whether a fused class has a launch; each op the optimizer leaves takes the launches its link names (`link`), a class the lane runs whole one launch, a class it runs as its parts each part’s. Then the lane’s schedule sets how the launches run — four rows a warp for a wide product (`rows_a_warp`), the shared-row attention, the split counts, a batch’s sequences as one launch (`sequences`) — and every tensor is given its buffers. - [mod residence](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/residence/): Where a lane’s arrays live. Every array the program allocates goes on the device while they fit the memory it is given; past it, constant matrices move to pinned host memory the device maps, in the order that costs a step least: a table only ever gathered from (a row a token), then each expert stack from the last layer’s back (a step reads its chosen experts’ rows), then the other matrices from the last read back — until the rest fits. A kernel reads a mapped matrix through the same pointer it reads one in device memory, so where a matrix lives changes no value. Matrices that read the same checkpoint rows (a tied head and the embedding table it is) share one upload. - [mod weights](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/weights/): Where each constant of a compiled step comes from. - [struct Form](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/struct.Form): One form of a lane: the step of `rows` rows (1 for the decode step; a batch’s, one a sequence), its LOGOS source, its graph, its schedule and where its step-local arrays live in the program’s arena. - [struct Lane](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/struct.Lane): A compiled lane: its forms, the decode step first, and the one program that runs them. - [struct LaneOptions](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/struct.LaneOptions): How a lane is compiled: its caches’ length in positions, its knobs, and its largest prefill chunk (a power of two up to `plan::MAX_CHUNK`; 1 runs the prompt a decode step at a time). - [enum FormKind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/enum.FormKind): What a form of a lane computes: the decode step, a prefill chunk of one sequence’s tokens, or a batch’s step of one token for each of its sequences. - [enum LaneError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/enum.LaneError): Why a model’s step does not compile to the lane, by name. - [fn batch_io](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/fn.batch_io): The names an authored batch of `rows` sequences reads and writes across steps: its tokens, one a sequence, and sequence `b`’s position `pos_s`, logits `logits_s` and next token `next_s`. - [fn compile](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/fn.compile): Compile the lane of `spec` against the checkpoint at `checkpoint`: its decode step and its prefill chunks. - [fn compile_batch](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/fn.compile_batch): `compile` with a batch step beside the decode step and the chunks: the model’s batch cut (`Cut::Batch`) of `batch` sequences, one token each a step, every weight read once for all of them, each sequence its own position, caches and next token. The program decodes up to `batch` prompts together, each prefilled into its own sequence’s state. - [fn compile_batch_holding](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/fn.compile_batch_holding): `compile_batch` with the fusion rules `held` held back. - [fn compile_holding](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/fn.compile_holding): `compile` with the fusion rules `held` (of `plan::RULES`) held back, their launches kept apart: the program each fusion is checked against, computing what the fused one computes. - [fn decode_io](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/fn.decode_io): The names the authored decode step reads and writes across steps. - [fn prefill_io](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/fn.prefill_io): The names an authored prefill chunk reads and writes across steps. ## logicaffeine_compile::codegen_cuda::lane::arena The step-local memory of a lane’s forms. Every array a step computes and reads within the step — a tensor’s `f32` (or `i32`) buffer, or its quantized form — lives in one arena the program allocates once, placed by its lifetime: from the launch that first writes it whole to the last launch that touches it, through any view of it. A launch’s scratch lives there while the launch runs. The forms share the arena, one form running at a time. - [struct Arena](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/arena/struct.Arena): A form’s arena: its placed arrays, its launches’ placed scratch, and the bytes they span. - [struct Placed](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/arena/struct.Placed): An array placed in the arena: `bytes` from `offset`, live from launch `first` to launch `last` of its form. - [struct PlacedScratch](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/arena/struct.PlacedScratch): A launch’s scratch placed in the arena: `bytes` from `offset`, live while launch `launch` of its form runs. - [struct Scratch](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/arena/struct.Scratch): A launch’s scratch: `tag` names it beside the launch’s result, `ty` is its element type and `bytes` its size. A counter — an arrival count the launch’s last block resets — is zero before the launch and left zero by it, so it keeps a zeroed buffer of its own; the rest live in the arena while the launch runs. - [const ALIGN](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/arena/constant.ALIGN): Every array’s alignment in the arena: `cudaMalloc`’s, past every vector load the kernels make. - [fn array_bytes](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/arena/fn.array_bytes): The bytes of a tensor of `len` elements’ array: its `f32` buffer, or its quantized form — the int8 words, then the low words under two words, then a scale a block — each part aligned. - [fn home](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/arena/fn.home): The tensor whose array a touch of tensor `name` lands in: an alias’s — a view’s — is the tensor it is a part of, through every alias, but the quantized form of an alias whose rows start inside a block is its own. - [fn place](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/arena/fn.place): Place the arrays of `s` that live within its step: a computed tensor’s that is not one of the step’s inputs or outputs, all of it written before any launch reads it — whole, or part by part over every unit (`join_in_place`) — so nothing the step reads of it was left by another array, or by an earlier step. Each lives from its first touch to its last, through any view of it. The largest first, each at the lowest aligned offset clear of every array placed live beside it. - [fn quant_parts](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/arena/fn.quant_parts): Where the parts of a quantized array placed at `offset` start: its words, its low words under two words, its scales. - [fn scratch](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/arena/fn.scratch): The scratch launch `l` takes under `numerics`: the delta rule’s unnormed outputs; an expert mixture’s router logits, choices and weights, and over a block’s rows its choices grouped by expert, each choice’s gathered activation row, hidden row (gate and up rows apart on the tensor cores, the hidden row quantized alone when they are paired) and weighed result; a tensor-core projection’s parts of the tiles its last wave cuts along `k`, and their counts; an `f32` GEMM’s parts of the tiles it cuts along `k`; the arg-max’s block maxima; a split attention’s chunk partials (none in tiles); an attention in two words’ keys and values in two words and their scales — and the arrival counts. ## logicaffeine_compile::codegen_cuda::lane::branches A form’s launches as a graph over several streams. A launch runs after every earlier launch that writes memory it reads or writes, or reads memory it writes — memory by where it lives: a step-local array or a launch’s scratch by its bytes in the arena (which several tensors share in turn), anything else by its buffer, an alias — a view — where its array lives (`arena::home`). Each launch takes a stream: the stream whose last launch it follows, or one whose work it already follows, or the least recently used; it waits on another stream’s launch by an event only where nothing it already follows orders the two. The launches compute what they compute in order, every dependency kept. - [struct Branched](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/branches/struct.Branched): A form’s launches over its streams. - [enum Region](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/branches/enum.Region): Memory a launch touches: bytes of the arena, or a buffer of its own. - [const STREAMS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/branches/constant.STREAMS): The streams a form’s launches spread over, the step’s own among them. - [fn branch](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/branches/fn.branch): The form’s launches spread over `STREAMS` streams. - [fn regions](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/branches/fn.regions): The memory launch `i` reads and writes: its tensors’ arrays and its scratch (written and read, as a launch’s own). ## logicaffeine_compile::codegen_cuda::lane::emit The lane’s forms printed as one CUDA program, and the sidecar of values it reads. - [struct Checkpoint](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/emit/struct.Checkpoint): The checkpoint a program is compiled against. - [struct Program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/emit/struct.Program): A compiled lane: the CUDA program and the sidecar it reads its computed constants from. - [fn emit](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/emit/fn.emit): Print `forms` as one CUDA program over the checkpoint `ckpt`, its caches `ctx` positions long. ## logicaffeine_compile::codegen_cuda::lane::graph The step graph: an authored step (a decode step, a prefill chunk) as the ops it runs and the tensors they touch, each tensor given the role a compiled lane needs to place it. - [struct Op](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/graph/struct.Op): One op of the step, its operands and result by name. - [struct StepGraph](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/graph/struct.StepGraph): An authored step as a graph: its tensors in their roles, its ops, and the step as the one IR holds it, which the shared optimizer reads. - [struct Tensor](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/graph/struct.Tensor): One tensor of the step: its shape as the program gives it (`rows × cols`), and its role. ## logicaffeine_compile::codegen_cuda::lane::kernels The lane’s kernel library: one CUDA kernel per kind of op a step runs, each templated over the forms the fusion rules ask of it (a residual added before a norm, an activation quantized in a producer’s epilogue, a result written into the row of a cache a position names). The planner instantiates them; no kernel here knows a model. - [enum Kernel](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/enum.Kernel): One library kernel: its name and its source. - [const ATTN_BLOCK_VALUES](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.ATTN_BLOCK_VALUES): The key and value elements an attention block reads a position, across its heads: four latent-attention heads’ worth (`(576 + 512) · 4`), which scored best from a thousand positions on (the 3060’s attention measurements), against two heads’ at a hundred. - [const ATTN_FOLD_PAIRS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.ATTN_FOLD_PAIRS): The value pairs a block of `lk_attention_fold` folds, a thread each. - [const ATTN_HELD_BYTES](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.ATTN_HELD_BYTES): The most shared memory an attention block (`lk_attention`) keeps its chunks’ partials in, so a row it takes whole (a batch’s sequence, a chunk’s row) weighs each chunk once: a block of 256 threads keeps three to a streaming multiprocessor. - [const ATTN_I8_QUERIES](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.ATTN_I8_QUERIES): The query vectors a block of the two-word attention (`lk_attention_i8`) takes, a warp 16 of them. - [const ATTN_MIN_SPLIT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.ATTN_MIN_SPLIT): The fewest positions a split of an attention’s span takes: below it a split’s partial costs more than its scores. - [const ATTN_MMA_QUERIES](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.ATTN_MMA_QUERIES): The query vectors a block of the f16 tensor-core attention (`lk_attention_mma`) takes, a warp 16 of them. - [const ATTN_SHARED_HEADS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.ATTN_SHARED_HEADS): The most query heads `lk_attention_shared` takes in its one block: four warps of four heads. - [const ATTN_SHARED_STEP](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.ATTN_SHARED_STEP): The cached rows `lk_attention_shared` stages a step (`LK_ST` in its source). - [const ATTN_TILE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.ATTN_TILE): The positions the attention scores at a time (`LK_TILE` in its source). - [const ATTN_TILE_Q](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.ATTN_TILE_Q): The query vectors a block of the tiled attention takes: heads of one key/value group over consecutive rows. - [const AXPY_R](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.AXPY_R) - [const AXPY_SUMS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.AXPY_SUMS): The bytes of the staged per-head matmul’s own sums in shared memory (`red`): an `f32` for each lane of each of its `AXPY_R · AXPY_W` warps — it stages only under the quantized numerics, which sum in `f32`. - [const AXPY_W](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.AXPY_W): The sub-blocks of outputs and the row groups a block of the staged per-head matmul takes. - [const BLOCKS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.BLOCKS): A weight matrix as the kernels read it, and the sub-block decoders of every format besides Q8_0 (template argument `F`, the GGUF type id): a Q8_0 matrix is its int8 values `q` and block scales `s`; any other is its blocks `b`, a row every `rb` bytes. `lk_sub` decodes sub-block `sb` (weights `32·sb …`) of a row into 32 int8 levels and, per half, a scale and an offset; a weight is `scale·level + offset` rounded as the CPU dequantizer rounds it (a product, then a sum); `lk_level` decodes one element of a sub-block alike. `lk_row_dot` is a row’s dot with `M` activation rows (`ld` apart) under numerics `Q`, one warp; `lk_dot` the same for any format, a Q8_0 matrix’s split arrays included; `lk_gemv_dot` a row’s dot with `M` activation rows of its length as the plain GEMV of its format takes it, the one dot of a format every kernel shares so a fused launch computes what its parts computed. - [const DELTA_CHUNK](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.DELTA_CHUNK): The rows of a chunk of the chunked delta rule (`LK_DC` in its source), the rows of a value head’s memory a block of its walk takes, and the threads of that block: two warps. - [const DELTA_PREP_SMEM](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.DELTA_PREP_SMEM): The dynamic shared memory of `lk_delta_prep`: a run of 32 of a chunk’s keys’ and queries’ values (then `T`), `A`, and the sums `T`’s lower blocks take — rows padded a value. - [const DELTA_STATE_ROWS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.DELTA_STATE_ROWS) - [const DELTA_STATE_THREADS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.DELTA_STATE_THREADS) - [const GEMM_BLK_TILE_M](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.GEMM_BLK_TILE_M): The activation rows of a dense block-format tensor-core GEMM block’s tile (its outputs: `GEMM_TILE_N`). - [const GEMM_PARTS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.GEMM_PARTS): The matrices a launch in parts (`lk_parts`: `lk_gemv_parts`, `lk_gemv_mma`, `lk_gemm_blk`‘s `G` 4) multiplies one activation by at most — the kernels’ `LK_PARTS`: six, so a recurrent layer’s query, key, value, output gate and two gates project its activation in one launch, the gates no launch of their own (at Qwen3.5-0.8B’s batch of 64 a single block on the 3060, 16.8 µs a layer). - [const GEMM_TILE_N](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.GEMM_TILE_N): The outputs a block of the tensor-core block GEMM computes (`lk_gemm_blk`’s tile). - [const GEMV_F32_ROWS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.GEMV_F32_ROWS): The activation rows a block of `lk_gemv_f32` takes, together (its `LK_F32_ROWS`): few enough that a wide chunk’s rows spread over the chip, every row’s dots summed as one row’s are. - [const GEMV_MMA_MIN_ROWS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.GEMV_MMA_MIN_ROWS): The fewest rows a batch’s Q8_0 projection takes to the tensor cores (`lk_gemv_mma`); fewer run on the GEMV. - [const GEMV_MMA_ROWS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.GEMV_MMA_ROWS): The most rows `lk_gemv_mma` takes in one launch: four m-tiles of 16. - [const HEAD_TILE_M](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.HEAD_TILE_M): The rows of a tiled per-head matmul block (`lk_head_tiled`), each block 64 of a head’s outputs. - [const PRELUDE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.PRELUDE): The helpers every kernel shares: the storage types, row addressing, warp and block reductions, the activation quantizer. - [const ROPE_HEAD](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.ROPE_HEAD): The widest head a rotation turns: its block holds the head’s values in shared memory (`lk_rope_head`’s `hv`). - [const STALL](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/constant.STALL): A stream held back for a span of the global timer. Under `--stagger ` one runs before each launch of a step, its span drawn from the seed, the form and the launch, so launches its streams leave unordered run in another order under each seed. - [fn accumulator](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.accumulator): The bytes of the lane’s sums under the numerics of kernel mode `mode` (`mode`), and their CUDA type: `f64` for the precise numerics (mode 0) — every sum of every kernel, a norm’s, a convolution’s, the delta rule’s, the router’s softmax and the experts’ — `f32` for the others. - [fn argmax_blocks](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.argmax_blocks): The blocks an arg-max over `n` values spreads across: a run of at least 2048 values a block, at most 64 blocks. - [fn attn_blocks_a_multiprocessor](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_blocks_a_multiprocessor): The blocks of an attention (`lk_attention`‘s `MB`) a multiprocessor holds at once, by the registers it leaves them: three for a launch of more blocks than the chip holds at two (`blocks` over `sms`), which come in waves, so occupancy bounds them — on the 3060, 5.7% faster for Llama-3.2-1B’s batch of 64 and 3.4% for Gemma-3-1B’s; two for a launch under one wave, whose blocks’ latency bounds it, and for the `f64` sums (`acc` 8 bytes), which need the registers. - [fn attn_flash_queries](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_flash_queries): The query vectors a block of the flash attention (`lk_attention_flash`) takes: 64 for heads and values to 128 wide, 32 past them, so a thread’s outputs stay 64 registers and the block’s shared memory within a block’s. - [fn attn_flash_smem_bytes](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_flash_smem_bytes): The flash attention block’s dynamic shared memory: its queries, two stages of a tile’s keys 32 values of the head at a time and of its values 16 keys at a time, and the tile’s weights — rows padded four values. - [fn attn_flash_threads](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_flash_threads): The threads of a flash attention block: 256 over 64 queries (a thread 4 queries by 4 keys), 128 over 32 — where the 3060 measured each fastest. - [fn attn_heads_per_block](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_heads_per_block): The query heads an attention block takes together: the largest divisor of `group`, at most 16, whose keys and values a position stay within `ATTN_BLOCK_VALUES` (one head whatever its width), whose accumulators (`g` heads’ value pairs a thread, twice over in a block that takes every chunk) stay within 32 registers, and whose queries, scores and chunk sums fit `smem` bytes — `None` when not even one head fits. - [fn attn_held_bytes](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_held_bytes): The bytes of a block’s `g` heads’ partials over `splits` chunks — each chunk’s maximum, sum and `vd` weighed values, in the accumulator’s `acc` bytes — and whether the block holds them (`held`): a row cut into chunks, the partials within `ATTN_HELD_BYTES`. - [fn attn_holds](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_holds) - [fn attn_i8_keys](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_i8_keys): The keys a tile of the two-word attention takes: 64, or 32 where heads or values pass 128 wide. - [fn attn_i8_rows](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_i8_rows): The key rows a key/value group’s two words take for a cache of `len` positions: whole tiles of 64. - [fn attn_i8_scratch](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_i8_scratch): The two-word attention’s scratch for a cache of `len` positions over `groups` key/value groups: the keys’ high and low words, the values’, and each row’s two scales — in bytes. - [fn attn_i8_smem_bytes](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_i8_smem_bytes): The two-word attention block’s dynamic shared memory: a tile’s keys’ and values’ two words, rows padded 16 bytes, and both its scales in two buffers. - [fn attn_mma_keys](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_mma_keys): The keys a tile of the f16 tensor-core attention takes: 64, or 32 where heads or values pass 192 wide. - [fn attn_mma_smem_bytes](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_mma_smem_bytes): The f16 tensor-core attention block’s dynamic shared memory: a tile’s keys (`attn_mma_keys`) and their values as f16, rows padded eight values. - [fn attn_path](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_path): The path an attention launch takes past a row of one chunk (`lk_attention`‘s `PATH`, `lk_attn_path`), fixed where it launches so its kernel compiles that path alone and ptxas allots its registers to it: the chunks’ partials of a grid of `z` split blocks a row folded by the last to arrive, held side by side by the row’s one block (`side` chunks at a time), weighed one at a time by it, or none where a row is one chunk (`splits` 1). - [fn attn_run_width](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_run_width): The lanes a key’s dot takes in an attention of heads `hd` wide (`lk_attn_run_width`, `lk_attention`’s `RW`): a half warp for a head of 9 to 16 fours, the whole warp otherwise. - [fn attn_shared_padded_heads](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_shared_padded_heads): The heads `lk_attention_shared` pads its `g` heads to: whole warps of four. - [fn attn_shared_smem_bytes](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_shared_smem_bytes): The dynamic shared memory of a block of `lk_attention_shared` over `g` heads of `hd`: two steps’ rows, and a step’s scores of every padded head. - [fn attn_shared_splits](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_shared_splits): The most chunks `lk_attention_shared` cuts a row’s span of `span` positions into, the decode step’s in every form: one block a streaming multiprocessor (`sms`), its shared memory a block’s, and no more than give each chunk `ATTN_MIN_SPLIT` positions. - [fn attn_side_bytes](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_side_bytes): The shared memory a block weighing `side` chunks side by side takes past `attn_smem_bytes`’ one tile of scores: a tile of its `g` heads’ scores for each other chunk. - [fn attn_side_chunks](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_side_chunks): The chunks of its row a block that holds them weighs side by side (`lk_attn_side`): as many as its threads’ value slots hold — each chunk `vd / 2` pairs a head, a thread `attn_values_per_thread` a head — and no more than the row’s `splits`; one where a chunk fills them. - [fn attn_smem_bytes](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_smem_bytes): The dynamic shared memory an attention block takes: its `g` query heads of `hd` (`f32`), then — in accumulators of `acc` bytes — their scores over a tile and each head’s maximum, sum and fold factor over each of `splits` chunks. - [fn attn_splits](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_splits): The most chunks an attention cuts a row’s span into: enough blocks for two a streaming multiprocessor (`sms`) over the `blocks` the head blocks of one row give, and no more than give each chunk `ATTN_MIN_SPLIT` positions of `span`. - [fn attn_tile_heads](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_tile_heads): The heads of one group a tiled attention block takes: the largest power of two dividing `group`, at most 32 — the block’s rows `ATTN_TILE_Q` over it. - [fn attn_tile_smem_bytes](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_tile_smem_bytes): The tiled attention block’s dynamic shared memory: a 32-wide chunk of its queries and of a tile’s 64 keys, the tile’s scores, and eight keys’ values. - [fn attn_tile_values](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_tile_values): The groups of four values, 128 apart, a thread of the tiled attention accumulates for each of its queries. - [fn attn_values_per_thread](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.attn_values_per_thread): The pairs of each head’s values a thread of an attention block (256 threads) accumulates: `lk_attention` weighs at most `g` times as many of its block’s `g` heads’ value slots a thread. - [fn axpy_pitch](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.axpy_pitch): The bytes of a row the staged per-head matmul holds in shared memory (`lk_axpy_pitch`): the units of `AXPY_W` sub-blocks and one more, 15 bytes of alignment slack, rounded to an odd number of words. - [fn axpy_staged](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.axpy_staged): Whether a per-head matmul whose rows are its inputs stages them (`lk_head_axpy_staged`, `AXPY_W` sub-blocks and `AXPY_R` row groups a block): under the quantized numerics in every block format but Q6_K and Q8_0 — 1.7–2.8 times the per-lane kernel on the 3060 there (19.9 µs to 9.7 for DeepSeek-V2-Lite’s Q4_K absorption); the per-lane kernel keeps the precise numerics’ `f64` sums, Q6_K’s heavier decode and Q8_0’s one activation row. The choice reads no count of activation rows: a prompt’s chunk and a decode step sum alike, so a prompt continues alike in chunks or a token at a time. - [fn block_holds_its_norm](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.block_holds_its_norm): Whether a block of `threads` runs a norm of a row of `cols` as the norm’s own block does, each of its threads one of the norm’s (`norm_threads`). A narrower block plays several of the norm’s warps a warp, one after another, and the row’s norm runs on that one block alone: DeepSeek-V2-Lite’s 320-thread down blocks playing the norm’s 1024 decoded at 142.0 tokens a second on the 3060, 146.7 with the norm’s tail cut and 146.3 with the norm its own launch. - [fn decodes](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.decodes): Whether the block library decodes `ty`: the formats with a sub-block decoder below. - [fn delta_chunk_scratch](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.delta_chunk_scratch): The floats of the chunked delta rule’s scratch over `chunks` chunks of `hv` value heads `d` wide: each chunk’s decayed keys and queries (a value of the width at a time), its `T·diag(β)` and masked scores, and its rows’ decays to its end with its own. - [fn delta_chunks_take](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.delta_chunks_take): Whether the chunked delta rule takes heads `d` wide: at most 128, in whole runs of 32 (a lane of the walk’s warp `d / 32` values of the width, the preparation’s runs of 32). - [fn format_arg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.format_arg): The template argument that names a weight format in the block library: its GGUF type id. - [fn gemm_blk_expert_rows](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.gemm_blk_expert_rows): The activation rows of a grouped GEMM block over an expert mixture’s choices: 128 when the average expert has more than 64 rows to multiply (`choices / experts`), 64 otherwise — a taller tile reads each expert’s decoded weights for more rows, a shorter one leaves fewer of its rows empty. - [fn gemm_blk_launch_smem](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.gemm_blk_launch_smem): The dynamic shared memory one launch of the block-format tensor-core GEMM over `k` takes: a Q8_0 matrix’s streamed path over a `k` of whole 128-value scale groups, the block path otherwise — so the streamed path’s blocks are not held to the block path’s larger stages, and two of them share a multiprocessor where its registers allow. - [fn gemm_blk_launch_threads](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.gemm_blk_launch_threads): The threads one launch of the block-format tensor-core GEMM over `k` takes: a Q8_0 matrix’s streamed path over 128 rows, eight warps of 64 rows by 32 outputs — two blocks of them, their registers and stages, share a multiprocessor — and a warp each 32 × 32 of the tile otherwise (`gemm_blk_threads`). - [fn gemm_blk_rows](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.gemm_blk_rows): The activation rows a dense tensor-core GEMM of a matrix in format `f` (its GGUF type id) takes a block: 64 for a Q8_0 matrix under two words, so two blocks of its streamed path, both words of each stage, share a multiprocessor; `GEMM_BLK_TILE_M` otherwise. - [fn gemm_blk_smem_bytes](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.gemm_blk_smem_bytes): The dynamic shared memory a block-format tensor-core GEMM block in format `f` (its GGUF type id) over `bm` activation rows may take, whichever path a launch takes (`gemm_blk_launch_smem` over every `k`): what its kernel is allowed. - [fn gemm_blk_tail](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.gemm_blk_tail): How a dense block GEMM of `tiles` tiles and `stages` stages of `k` fills its last wave of `workers` blocks: `(whole, split)` — the first `whole` tiles a block each, every later tile cut into `split` parts of its stages, as many as fill the wave. `split` 1 when the tiles fill whole waves, or a wave’s blocks cannot cut a remaining tile in two. - [fn gemm_blk_threads](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.gemm_blk_threads): The threads of a block-format tensor-core GEMM block over `bm` activation rows: a warp each 32 × 32 of the tile. - [fn gemm_f32_splits](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.gemm_f32_splits): The parts an `f32` router GEMM (`lk_gemm_f32`) of `tiles` 64 × 64 tiles cuts each tile’s `chunks` runs of 32 `k` into: as many as give the chip’s `sms` two blocks each, whole runs of chunks every one. - [fn gemv_blk_norm_threads](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.gemv_blk_norm_threads): The threads of a block-format projection that norms its row in its last block (`lk_gemv_blk_norm`): eight warps, four where a warp takes `per_warp` rows past one. - [fn gemv_f32_parts](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.gemv_f32_parts): The warps an `f32` GEMV (`lk_gemv_f32`) cuts each output row’s `k` into: the most, to eight, that keep 128 values a warp and give its `n` outputs no more than 16 warps a streaming multiprocessor of the chip’s `sms`. - [fn gemv_mma_launch](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.gemv_mma_launch): `lk_gemv_mma`’s launch over `m` rows (at most `GEMV_MMA_ROWS`) of a projection of `n` outputs and `k` on a chip of `sms` multiprocessors, `(mt, nt, mw, nw)`: the widest tile its rows fill (`gemv_mma_shape`), except that a narrow projection of long rows over four m-tiles — its blocks of 128 outputs leaving more than half the chip idle, each running long (`k` at least 2048) — takes blocks of 64 outputs, twice as many. On the 3060 at 64 rows: Gemma-3-1B’s down projection (6912 by 1152) 94 µs to 54 (62 as the 32-row tile in two slabs of grid layers), Qwen3.5-0.8B’s (3584 by 1024) 54 to 31 (35) and its output projection (2048 by 1024) 33 to 20 (22); wider or shorter projections are faster in blocks of 128. - [fn gemv_mma_shape](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.gemv_mma_shape): `lk_gemv_mma`’s shape over `mt` m-tiles, `(nt, mw, nw)`: four n-tiles of 8 outputs a block over one m-tile, a warp each; eight over two, a warp each n-tile over both; sixteen over four, a warp each two n-tiles over two m-tiles — so a block stages its activation rows once for `32·mt` outputs, and over four m-tiles each fragment a warp loads feeds two products. On the 3060 at 64 rows the two-by-two warps beat a warp each n-tile over all four m-tiles on Llama-3.2-1B’s down projection (8192 by 2048) 117 µs to 102, its output projection 33.8 to 30.9, its query, key and value 35.6 to 32.9 and its gate and up 171.6 to 168.8; at 16 and 32 rows two n-tiles a warp gain nothing. - [fn gemv_mma_smem_bytes](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.gemv_mma_smem_bytes): `lk_gemv_mma`‘s shared memory (`lk_mma_smem`): its stages (three, two under the two-word numerics), a stage four blocks of each of its `8·nt` matrix rows and `16·mt` activation rows (both words’ under two words), rows 144 bytes apart, and the stage’s scales. - [fn gemv_mma_threads](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.gemv_mma_threads): `lk_gemv_mma`’s threads: a warp each `nw` n-tiles over each `mw` of its `mt` m-tiles. - [fn gemv_mma_tiles](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.gemv_mma_tiles): `lk_gemv_mma`’s m-tiles for `m` rows (at most `GEMV_MMA_ROWS`): 1, 2 or 4. - [fn head_mode](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.head_mode): The numerics a per-head matmul — a latent’s expansion half — runs under: its activation `f32` under every numerics, with `f64` sums under the precise one (0) and `f32` sums under the quantized ones (3), so the absorbed latent attention computes what the expanded one does. - [fn mode](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.mode): The template argument that names a numerics mode in the library: 0 `f32` activations, 1 int8, 2 two-pass int8. - [fn moe_down_launch](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.moe_down_launch): The blocks and threads of a decode step’s down projection (`lk_moe_down`, `lk_moe_down_norm`) over a row of `d`: `moe_down_rows` outputs a block, a warp each of the `k` kept experts and the shared expert’s warps where its intermediate `sdff` is not 0. - [fn moe_down_rows](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.moe_down_rows): The outputs a block of the decode step’s expert down projection takes (`W` of `lk_moe_down`), and the warps its shared expert’s rows take (`SW`): four outputs where `d` divides by four, so each kept expert’s warp has four rows’ weight loads in flight over one load of the hidden row — and a warp a row of the shared expert’s where its rows are wider than an expert’s, so no warp holds the block back. Against a block of one output on the 3060, DeepSeek-V2-Lite’s down projections (Q8_0 beside a shared Q6_K, Q5_0 beside a shared Q4_K) drop 13–31%, gpt-oss-20b’s (MXFP4) 23–36% and Qwen3-30B-A3B’s shape (Q4_K, Q6_K) 16–33%; eight outputs lost but in MXFP4. - [fn moe_group_smem_bytes](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.moe_group_smem_bytes): The shared memory of `lk_moe_group` at `threads`: the running offsets and each warp’s counts. - [fn moe_group_threads](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.moe_group_threads): The threads of the block that groups a block’s expert choices (`lk_moe_group`): a warp a 32 choices, as many warps as 32 and as each warp’s count of every one of `experts` experts, beside the running offsets, fits 48 KB. - [fn norm_threads](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.norm_threads): The threads of a block that norms a row of `cols` (`lk_rmsnorm`, and the norm inside a rotation): the row’s width in whole warps, at most 1024 — each thread then holds at most `cols / 1024` values. - [fn route_warps](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.route_warps): The warps an expert router’s row takes (`WPE` of `lk_moe_route`): four for an `f32` router whose row splits into four parts of whole 16-byte words, so its experts fill four times the blocks; one for a quantized router, whose row is its format’s one dot. - [fn rows_a_warp](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/kernels/fn.rows_a_warp): The output rows a warp of a GEMV takes (`W` of `lk_row_dot`): four in a block format when one activation row meets a matrix of at least 2048 rows of at least 64 sub-blocks — four rows’ weight loads in flight over one load of the activation outran one row a warp by 12–20% on the 3060 there, and lost where fewer warps would cover the chip or a row leaves lanes idle — one otherwise. A Q8_0 row already moves sixteen bytes a lane at a time. ## logicaffeine_compile::codegen_cuda::lane::plan A step graph lowered to launches of the kernel library. The lane decides no fusion of its own: the step, lifted into the one IR, is optimized by the shared table under the lane’s shim (`LaneShim`), which answers whether a fused class has a launch; each op the optimizer leaves takes the launches its link names (`link`), a class the lane runs whole one launch, a class it runs as its parts each part’s. Then the lane’s schedule sets how the launches run — four rows a warp for a wide product (`rows_a_warp`), the shared-row attention, the split counts, a batch’s sequences as one launch (`sequences`) — and every tensor is given its buffers. - [struct Advance](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/struct.Advance): What the arg-max that closes a step writes besides its result: the token the next decode step reads (every form’s arg-max writes the decode step’s; a batch’s sequence `item` writes item `item` of its tokens) and the position the sequence’s next step reads; and the run generated so far, which only the host reads. - [struct Buffer](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/struct.Buffer): One tensor’s buffers. - [struct ConvPart](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/struct.ConvPart): One causal convolution of a merged launch (`Launch::ConvParts`): its input, weights, ring and output, its channels, and whether each head of its output is normed to unit length. - [struct Dst](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/struct.Dst): Where a kernel writes its result: a buffer, or the rows of a table of rows `pitch` wide from a starting row — the whole of it, or (`unit`) a part of every unit of it. - [struct Fusion](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/struct.Fusion): A fusion rule that fired: its name and the graph ops it joined. - [struct GemmPart](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/struct.GemmPart): A part of a GEMM in parts: its matrix, bias, destination and outputs a row. - [struct Part](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/struct.Part): A part of every unit of a wider tensor: unit `u`’s values start `u·pitch + offset` in. - [struct PreNorm](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/struct.PreNorm): The norm a norm launch takes of its added operand in the same block before adding it (`sandwich_norm`): the weight and epsilon of the norm that operand’s own launch took. - [struct RopeSide](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/struct.RopeSide): One rotation of a merged launch (`Launch::RopeParts`): its input (read in place as a part of every unit of a wider tensor where it names one), its norm, its destination, and its heads, `per_row` of them a row. - [struct Schedule](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/struct.Schedule): A step lowered: its launches in order (with the graph ops each computes — none for a quantize), its buffers, and the fusions that made the launches. - [struct SharedExperts](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/struct.SharedExperts): The shared experts a mixture takes into its own launches (`shared_expert`): one SwiGLU FFN of `dff`, its gate, up and down projections read in place in their `formats`. - [struct Split](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/struct.Split): An attention’s queries and keys in two parts, split at `own`: a query’s first `own` values its unit’s in `q` (`q_pitch` apart a (row, head)), the rest its unit’s in `q_tail`; a key’s first `own` its group’s in the keys, the rest its row’s in `k_tail`, every group’s alike — an expanded latent attention’s queries, each head’s unrotated part read in place in the query projection and its rotated part, and its keys, each head’s expansion and the rotated key the heads share, read in place in the cache. - [enum DType](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/enum.DType): The element type of a buffer. - [enum Fill](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/enum.Fill): What a buffer holds and how it is filled before the first step. - [enum Launch](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/enum.Launch): One launch of a library kernel. A producer names the tensor it computes (`out`); `f32` when it writes the tensor’s `f32` buffer, `quant` when it writes its quantized form. Row counts are the block’s (1 for a decode step). A `part` is where a launch reads its input `x` unit by unit: a part of every unit of a wider tensor (none, the whole of `x`). - [enum Router](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/enum.Router): How an expert mixture’s router weights are held: quantized checkpoint rows of a format, or `f32` values (an expert’s row of the input’s width at a time) — the router reads the input `f32` then, under every numerics. - [enum RowSel](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/enum.RowSel): Which row of a table a write starts at: the row a parameter names (1-based), or a fixed row. - [enum Touch](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/enum.Touch): How a launch touches a tensor: through its `f32` (or `i32`) buffer, or its quantized activation. - [const GEMV_ROWS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/constant.GEMV_ROWS): The most rows the GEMV kernel multiplies in one launch (its warp per output row holds an accumulator per row); a projection of more rows runs on the tensor cores, or (under the precise numerics) as slabs of this many rows. - [const MAX_CHUNK](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/constant.MAX_CHUNK): The largest prefill chunk a lane compiles. - [const QBLOCK](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/constant.QBLOCK): The values of an activation’s quantized form that share one scale. - [const RULES](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/constant.RULES): The steps of a lane a plan can hold back (`plan`’s `held`), in the order the lane takes them: the shared rules its kernels link, by their names in the shared table (`crate::tensor_graph::fuse`); `rows_a_warp`, the schedule’s four rows a warp for a wide product; the decode step’s products of one activation as one GEMV in parts (`gemv_parts`, the lane’s own rule in the table); and `sequences`, a batch’s launches over its sequences as one. The arg-max’s advance closes the step and is always taken; the activation quantizer’s fusion is the `fuse_quant` knob. - [fn attended_span](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/fn.attended_span): The most positions one query of an attention over a cache of `len` rows attends: the cache, or its window. - [fn gates_batch_rows](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/fn.gates_batch_rows): Whether `op` is a batch’s gated attentions (`attn_output_gate` over its sequences’ rows), or their fold with the quantize of the product: the op the lane runs as each sequence’s attention and its row’s set. - [fn kind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/fn.kind): A launch’s kind, as a census counts it. - [fn plan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/fn.plan): The step graph `g` lowered under `numerics` and `knobs`: `constants` holds the placement of every constant the graph declares, `io` the step’s carried names, `held` the steps of `RULES` held back — a shared rule, or a step of the lane’s schedule. - [fn quant_in_place](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/plan/fn.quant_in_place): A view `offset` elements into a tensor reads the tensor’s quantized form in place: it starts on a whole block. ## logicaffeine_compile::codegen_cuda::lane::residence Where a lane’s arrays live. Every array the program allocates goes on the device while they fit the memory it is given; past it, constant matrices move to pinned host memory the device maps, in the order that costs a step least: a table only ever gathered from (a row a token), then each expert stack from the last layer’s back (a step reads its chosen experts’ rows), then the other matrices from the last read back — until the rest fits. A kernel reads a mapped matrix through the same pointer it reads one in device memory, so where a matrix lives changes no value. Matrices that read the same checkpoint rows (a tied head and the embedding table it is) share one upload. - [struct Plan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/residence/struct.Plan): What a lane’s program allocates, before it decides where its matrices live. - [struct Residence](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/residence/struct.Residence): Where the program’s matrices live on a budget. - [const CONTEXT_RESERVE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/residence/constant.CONTEXT_RESERVE): The device memory a chip loses before the program allocates: what the driver holds back from every program (379 MiB of the RTX 3060’s 12 GiB under driver 580) and the program’s context with its modules loaded (113 MiB). - [const POOL_ALIGN](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/residence/constant.POOL_ALIGN): The alignment of every array carved from a pool: `cudaMalloc`’s, the arena’s. - [const SPARE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/residence/constant.SPARE): What the program’s graphs, streams and events, and the rounding of its three allocations to the driver’s 2 MiB granule, take of the device beside its arrays, past `SPARE_A_LAUNCH` for each launch it captures. - [const SPARE_A_LAUNCH](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/residence/constant.SPARE_A_LAUNCH): The device memory each captured launch’s graph node takes, at twice the 8 KiB a node of a 1000-launch graph takes on the RTX 3060. - [fn matrix_bytes](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/residence/fn.matrix_bytes): The bytes a matrix kept as rows takes of its pool: a Q8_0 matrix’s levels and its half scales, each an array; any other format’s blocks as the checkpoint lays them out and the 32 bytes a staged read runs past them. - [fn place](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/residence/fn.place): Where `plan`’s matrices live on `budget` bytes of device memory: as many of its order as must move to mapped host memory for the rest to fit, and the bytes each side takes — the decision the program makes when it starts. Refused when the arrays but the matrices outrun the budget. - [fn plan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/residence/fn.plan): What the program of `forms` allocates, its caches `ctx` positions long: the arena, the arrays it keeps on the device, its matrices in the order they leave it, and the spare its graphs take. - [fn pooled](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/residence/fn.pooled): The bytes an array of `n` bytes takes of its pool. - [fn shared_names](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/residence/fn.shared_names): The constant buffers every form shares, allocated once: the constants, and the carried state the decode step holds. ## logicaffeine_compile::codegen_cuda::lane::weights Where each constant of a compiled step comes from. - [struct Rows](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/weights/struct.Rows): A quantized matrix read straight from the checkpoint: `rows` rows of `cols` weights in `ty`, the device copy’s rows the runs’ rows in order. `transposed` when the program declares the matrix the other way round — a projection’s rows are its outputs, the columns of the `in × out` matrix the program multiplies by. - [struct Run](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/weights/struct.Run): `rows` consecutive checkpoint rows, the first at byte `offset` of the file. - [enum Placement](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/weights/enum.Placement): How a constant reaches the device. - [fn place](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane/weights/fn.place): Where constant `var` (of `len` elements) of a step authored from `spec` comes from. `q8` when the author declared it a quantized matrix — rows read in place, or values when the checkpoint keeps it in a float format; `positions` the rows of the rotary caches. ## logicaffeine_compile::codegen_cuda::lane_link The lane’s link: each op of the one IR, as the shared optimizer leaves it under the lane’s shim, to the launches the lane’s kernels run it with. - [struct Link](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane_link/struct.Link): What the link reads beside an op: the optimized graph, where each constant lives, the lane’s shim, and the names the step carries across steps. - [fn link](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane_link/fn.link): The launches every op of `g` runs as, in order, each with the lifted ops it computes, or the first op the lane cannot link and why. ## logicaffeine_compile::codegen_cuda::lane_shim What the compiled generation lane runs whole: the CUDA lane’s answer to the shared optimizer. - [struct LaneShim](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane_shim/struct.LaneShim): The lane under its knobs, compiling a form whose products are a batch’s (each row its own sequence) or not, with the lane rules `held` back. - [struct Latent](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane_shim/struct.Latent): A latent attention’s shape and names, as its expanded launches read them: the query projection `qr` (each head’s unrotated part its first `nope` values) and the rotated part `qpp`; the cache `kc`, `kw` wide a row — the latent `lora` values then the shared rotated key — `len` rows; the key and value halves of the latent’s expansion and their formats (`kro`: the key half’s checkpoint rows are its outputs); the result `ct`. - [fn chunks_apart](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/lane_shim/fn.chunks_apart): Whether an attention cut into `splits` chunks runs a block a chunk: where its rows’ head blocks alone leave the chip idle. ## logicaffeine_compile::codegen_cuda::matrix The INT8 weight-stationary GEMM path of the CUDA tier — the workload a GPU (and an RDU) actually exists for: `O(M×N) = A(M×K) · W(K×N)` in int8, the shape every transformer projection and attention dot reduces to. - [struct CudaGemmArtifact](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/matrix/struct.CudaGemmArtifact): A complete int8 weight-stationary GEMM CUDA program (weights + activations baked, computed with DP4A, printed row-major) plus its Makefile. - [fn blockscaled_gemm_dequant](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/matrix/fn.blockscaled_gemm_dequant): GROUND TRUTH (f64): dequantize every element (`q * scale`) then multiply-accumulate. The unambiguous meaning of a Q8_0 matmul, order-independent. - [fn blockscaled_gemm_int8](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/matrix/fn.blockscaled_gemm_int8): WHAT THE DP4A KERNEL COMPUTES: an exact int32 dot within each 32-block, scaled once by the two block scales, accumulated in f64. Algebraically identical to `blockscaled_gemm_dequant` (the scale is constant across a block) — the lock proves the implementation matches, catching any scale-indexing bug. - [fn emit_int8_gemm](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/matrix/fn.emit_int8_gemm): Emit a DP4A int8 GEMM CUDA program for `O(m×n) = A(m×k) · W(k×n)`, with `weights` (`k*n` row-major, `W[r][c] = weights[r*n+c]`) and `acts` (`m*k` row-major) baked in. Refuses (typed) if the RDU-shaped target does not advertise int8 weight-stationary GEMM — the exact certified gate the fabric uses. - [fn emit_scaled_int8_gemm](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/matrix/fn.emit_scaled_int8_gemm): Emit a block-scaled Q8_0 GEMM CUDA program: DP4A int8 dot per 32-block, scaled by the baked f32 block scales, accumulated in f32. Prints `O(m×n)` row-major as `%.9g` (one per line). `k` must be a multiple of 32 (whole Q8_0 blocks). Refuses (typed) if the RDU-shaped target lacks int8 weight-stationary GEMM. - [fn lower_elementwise_to_cuda](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/matrix/fn.lower_elementwise_to_cuda): Lower a recognized elementwise op (`C[p] = A[p] ⊕ B[p]`, from `crate::tensor_recognize::recognize_elementwise`) to a self-contained CUDA program — the elementwise analog of `lower_matmul_to_cuda`. One thread per element; the deterministic int8-range fill and the `Σ C` checksum match the matmul emitter’s convention, so it runs and prints on the GPU. A `B` of one row holds that row’s elements and is read at each element’s column. - [fn lower_matmul_to_cuda](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/matrix/fn.lower_matmul_to_cuda): Lower a RECOGNIZED LOGOS matmul (`C(M×N) = A(M×K)·B(K×N)`, from `crate::tensor_recognize::recognize_matmul`) to a self-contained CUDA program whose dims ARE the source program’s — the compiler generating the kernel, not a template. The emitted program reproduces the LOGOS matmul’s deterministic int8-range fill (`a[p]=(p%7)-3`, `b[p]=(p%5)-2`), computes `C=A·B` on the GPU, and prints the checksum `Σ C` — so its stdout equals the VM’s `Show checksum` byte-for-byte. `M,N,K` are baked from the spec. - [fn lower_matmul_to_cuda_with](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/matrix/fn.lower_matmul_to_cuda_with): Lower a recognized matmul under an explicit `CudaKnobs` point. The `precision` knob selects the kernel: `ResolvedPrecision::Int64` (always-correct i64 accumulation, the general default) or `ResolvedPrecision::Int8Dp4a` (`__dp4a` int8 fast path — valid only when operands fit int8, which is why it is opt-in). Both reproduce the LOGOS program’s fill + checksum, so both equal the VM byte-for-byte on any int8-safe program; they differ only in how the contraction is computed on the GPU. - [fn lower_reduction_to_cuda](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/matrix/fn.lower_reduction_to_cuda): Lower a recognized reduction (`rmsnorm`/`softmax`, from `crate::tensor_recognize::recognize_reduction`) with the program’s epsilon to a self-contained float CUDA program — the reduction analog of `lower_matmul_to_cuda`. Deterministic float fill, one thread per element, and a `Σ Y` checksum printed with fixed precision so it compiles + runs on the GPU. - [fn sample_gemm_data](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/matrix/fn.sample_gemm_data): A reproducible int8 `(weights K×N row-major, acts M×K row-major)` sample in `[-128, 127]`, shared by `compile_to_cuda_gemm` and the lock so the emitted kernel and the `eval_systolic` oracle read identical data (no drift). Deterministic in the indices — no RNG. ## logicaffeine_compile::codegen_cuda::provenance Where an emitted CUDA program came from, stated in its first line. Every whole-program emitter takes its header from `header`, so no program can claim a provenance it does not have — in particular, a hand-written lane cannot say it was compiled from a model’s `.lg`. - [enum Provenance](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/provenance/enum.Provenance): How a CUDA program was produced. - [fn header](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/provenance/fn.header): The program’s first line, newline included. ## logicaffeine_compile::codegen_cuda::qwen38 Qwen3.8-27B authored in LOGOS. - [struct Qwen38Cfg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/struct.Qwen38Cfg): Everything the emitter needs, read from the checkpoint rather than assumed. Field names mirror the GGUF metadata keys so a mismatch is easy to spot. - [const QWEN38_EXTRA_KERNELS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/constant.QWEN38_EXTRA_KERNELS): The last two kernels the hybrid needs: an f32-weight GEMV for GDN’s tiny gate projections (quantizing a `[d, 48]` matrix would risk the gates for a rounding error that buys 0.26% of bandwidth), a KV-cache store that splits the fused projection’s k and v halves into their caches, and the SwiGLU epilogue fused with the activation re-quantization so the FFN’s middle never round-trips through global memory as f32. - [fn emit_qwen38_generate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.emit_qwen38_generate): Emit a self-contained CUDA program that generates from the real Qwen3.8-27B weights and reports throughput. - [fn emit_qwen38_mtp_probe](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.emit_qwen38_mtp_probe): Emit the MTP ACCEPT-RATE PROBE. - [fn gen_qwen38_decode_batch_embed_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_decode_batch_embed_lg): A batched decode step’s embedding lookups alone. - [fn gen_qwen38_decode_batch_head_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_decode_batch_head_lg): A batched decode step’s head alone. - [fn gen_qwen38_decode_batch_layer_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_decode_batch_layer_lg): Layer `l` of a batched decode step alone. - [fn gen_qwen38_decode_batch_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_decode_batch_lg): B decode steps at once, each sequence with its own state. See `author::decode_batch`. - [fn gen_qwen38_decode_batch_tp_layer_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_decode_batch_tp_layer_lg): Layer `l` of a batched tensor-parallel decode step alone. - [fn gen_qwen38_decode_batch_tp_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_decode_batch_tp_lg): A batched decode step, tensor-parallel over `tp` chips. See `author::tp_decode_batch`. - [fn gen_qwen38_decode_embed_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_decode_embed_lg): A decode step’s embedding lookup alone. - [fn gen_qwen38_decode_head_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_decode_head_lg): A decode step’s head alone: the final norm, the LM head and the arg-max. - [fn gen_qwen38_decode_layer_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_decode_layer_lg): Layer `l` of a decode step alone, its attention reading a KV cache of `ctx` positions up to `pos`. - [fn gen_qwen38_decode_step_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_decode_step_lg): One decode step: token `tok` at position `pos` (1-based) in, the next token out, the KV caches and the Gated-DeltaNet state carried. See `author::decode_step`. - [fn gen_qwen38_filled_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_filled_lg): The authored forward (`gen_qwen38_lg`) with every declared tensor filled DETERMINISTICALLY right after its declaration (a hash of the element index salted by the tensor’s name, in (-0.2, 0.2)) and the first and last logit shown — the self-contained program the demo corpus (`examples/rdu_demo/qwen38_tiny.lg`) and the tier-agreement locks run without a weight file. Fills follow declarations because the weights are declared per block, interleaved with the compute that reads them. - [fn gen_qwen38_head_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_head_lg): The final norm and LM head alone. - [fn gen_qwen38_layer_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_layer_lg): Layer `l` alone, as the forward writes it. - [fn gen_qwen38_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_lg): The whole Qwen3.8 forward as a LOGOS program — the single token with no history — and its weight manifest. - [fn gen_qwen38_prefill_head_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_prefill_head_lg): A prefill chunk’s head alone. - [fn gen_qwen38_prefill_layer_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_prefill_layer_lg): Layer `l` of a prefill chunk of `chunk` rows from `pos0` alone. - [fn gen_qwen38_prefill_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_prefill_lg): A prefill chunk of one sequence from position `pos0`. See `author::prefill`. - [fn gen_qwen38_tp_decode_layer_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_tp_decode_layer_lg): Layer `l` of a tensor-parallel decode step alone. - [fn gen_qwen38_tp_decode_step_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.gen_qwen38_tp_decode_step_lg): A whole decode step, tensor-parallel over `tp` chips. See `author::tp_decode_step`. - [fn qwen38_rope_cache](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38/fn.qwen38_rope_cache): The rotary cache for `rows` positions, `rope_dim / 2` pairs a row: row `p` (1-based) holds the cosines and the sines of `(p − 1)·θ^(−2i/rope_dim)` — the angles `gk_qk_norm_rope_part` turns 0-based position `p − 1` by, over the rotary width — each computed in f64 and rounded once. ## logicaffeine_compile::codegen_cuda::qwen38_batched ════════════════════════════════════════════════════════════════════════════════════════════════ ★ BATCHED Qwen3.8-27B DECODE ★ — where the bandwidth wall stops being the wall. - [const BTG](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38_batched/constant.BTG): Sequences whose accumulators a single warp carries in registers. Above this the register file, not the bandwidth, decides the shape — so a larger batch is tiled over `grid.y` rather than over registers. - [const QWEN38_BATCHED_KERNELS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38_batched/constant.QWEN38_BATCHED_KERNELS): The batched device code. Every kernel is the single-sequence form with a sequence index added; the GEMV is the one that changes shape, because it is the one that decides the token time. - [fn emit_qwen38_generate_batched](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38_batched/fn.emit_qwen38_generate_batched): Emit the BATCHED decode program. `batch` sequences advance in lockstep, each with its own recurrence memory, conv ring and KV cache, sharing one pass over the weights. - [fn emit_qwen38_generate_batched_mtp](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38_batched/fn.emit_qwen38_generate_batched_mtp) - [fn emit_qwen38_generate_batched_pt](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38_batched/fn.emit_qwen38_generate_batched_pt): The same emitter with the prefill chunk width passed in rather than read from the environment. - [fn emit_qwen38_generate_batched_q4](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen38_batched/fn.emit_qwen38_generate_batched_q4): Every lane choice explicit — the form the compile gate and the equivalence locks drive. ## logicaffeine_compile::codegen_cuda::qwen_batched ════════════════════════════════════════════════════════════════════════════════════════════════ BATCHED Qwen3-30B decode — the lane where “beat llama” is a landslide, not a 4% wall. - [fn emit_qwen30b_generate_batched](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_batched/fn.emit_qwen30b_generate_batched): Emit a self-contained CUDA program that runs the real Qwen3-30B-A3B decode over `batch` parallel sequences and reports aggregate S_TG plus the golden token stream for every sequence. Weights `fopen` from `wdir`. ## logicaffeine_compile::codegen_cuda::qwen_emit The whole-forward orchestrator — composing a multi-stage LOGOS tensor-op program into ONE CUDA program that chains genuine PARALLEL kernels through shared device buffers. - [struct MoeWeights](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/struct.MoeWeights): A Mixture-of-Experts FFN block‘s weights, all int8-resident (Q8_0): the router `[E, d]`, and the E experts’ gate/up `[E·dff, d]` and down `[E·d, dff]` STACKED so expert `e`’s rows begin at `e·dff` (gate/up) or `e·d` (down). This is the Qwen3-30B-A3B block; the SAME struct describes any `(d, dff, E, K)` — the emitter indexes the experts by a base-pointer offset, so 8 experts and 128 experts share one code path. - [struct Q8Ref](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/struct.Q8Ref): A Q8_0 weight loaded resident as int8 quants + f32 block scales (the real Qwen weights: 8 GB int8 fits a 12 GB card where 32 GB of f32 would not). Dequant `W[o][t] = quants[o*in+t] * scales[o*nb + t/32]` — the matmul against it becomes a dequant-in-kernel GEMV, matching `codegen_cuda::qwen`’s certified matvec. - [struct Qwen30bCfg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/struct.Qwen30bCfg): The Qwen3-30B-A3B architecture (n_layer is overridable to keep local emit/compile fast; the per-layer shape is identical to the real model). - [enum ChainStep](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/enum.ChainStep): One step of a fused elementwise chain applied to the register-carried value `t`: a binary op against an external operand (`t = t ⊕ ext[idx]`), or a unary SiLU (`t = silu(t)`, no operand). - [enum ForwardError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/enum.ForwardError): Why a program is not a lowerable multi-stage tensor-op forward. - [enum InitVal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/enum.InitVal): A concrete element initializer value — integer or float. - [enum Q8MatKind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/enum.Q8MatKind): How a Q8_0 matmul lowers to CUDA. At batch-1 decode a matmul is bound on the int8 WEIGHT bytes, not the math — so these three modes trade accuracy/latency, NOT weight bandwidth. - [enum StageRefusal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/enum.StageRefusal): Why the forward refuses one statement — the statement by its top-level index, and what it is. - [const GEN_DEVICE_KERNELS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/constant.GEN_DEVICE_KERNELS) - [fn collect_inits](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/fn.collect_inits): Collect the concrete initializers a program writes — `Set item N of V to ` with literal `N` and an integer/float value (1-based `N`, recorded 0-based) — so the orchestrator’s INPUT buffers hold the program’s own values and its GPU output equals the VM’s, not merely a deterministic fill. Recurses through desugar `Splice`s. - [fn emit_forward](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/fn.emit_forward): Emit the composed CUDA program for a forward’s graph (`forward_graph`): one uniquely-named kernel per stage plus a host driver that allocates a buffer per variable, fills the inputs `v[p] = (p % 7) - 3` (float chains scale by 0.5), launches each stage in order, and prints every element of the final stage’s output. Deterministic, self-contained, `nvcc`-compilable; its output is checked against a clean-room reference of the same graph. - [fn emit_marlin_q8_gemm](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/fn.emit_marlin_q8_gemm): Generate the full Qwen3-30B-A3B forward as a LOGOS `.lg` string, plus the manifests the emitter needs: `weights` (f32 embedding + RMSNorm weights), `q8` (attention V/O + LM head, int8), `moe` (per-layer FFN, keyed by the block’s FFN output var). `dir` is where the weight files are (real `/workspace/...` on the pod, a placeholder for compile-only use). This is THE canonical authored-in-LOGOS 30B program: the pod run, the local emit lock, and every printed copy of the program come from it. The device-state kernels for autoregressive generation — a mirror of the proven 8B `cuda/qwen_forward.cu` decode loop, with f32 block scales (the extractor writes f32 `.s` files; scales are a negligible bandwidth fraction). Position + token live in device memory (`d_pos`/`d_tok`) so ONE captured graph replays every token. The GEMVs are the SAME uint4-coalesced DP4A kernels that beat llama on the single-token forward. ★ M5: the compiler EMITS the certified Marlin-class Q8_0 GEMM (it is not a hand-written `.cu`). Given the auto-tuned subtile count `nt` (the fastest golden config the auto-tuner picked for this shape/GPU — M2), this lowers the recognized `matmul` of a Q8_0 weight into a register-dequant tensor-core kernel: `mma.sync.m16n8k32.s8` (int8 tensor core), the mma-k==32 aligned to the Q8_0 scale block (SAT-certified, M3), per-block dequant scale applied in REGISTERS in the same float grouping as our dp4a GEMV (golden-bounded to 4.2e-7, M4). This is the fusion pass in action: GEMM + per-block-dequant + scale fused into ONE kernel, and the compiler right-sizes `nt` per shape rather than a hand-tuned constant. Beats dp4a’s 7.5x wall on batch. - [fn emit_moe_forward](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/fn.emit_moe_forward): Emit a self-contained CUDA program for ONE Mixture-of-Experts FFN block over real int8 weights: router GEMV → top-K route (softmax, keep K, renormalize) → each expert’s SwiGLU with an EXPERT-INDEXED weight base → weighted combine. The weights stream from files (int8 quants + f32 block scales), never a 4×-larger f32 buffer, so the 30B block (~30 GB int8) fits a 48 GB card. Dequant-in-kernel GEMV (f32 activation × int8 weight, f64 accumulate) matches the LOGOS `moe` op on the VM exactly; the whole block is captured as one CUDA graph. `x` is the block input (`d` floats, inlined). The experts are UNROLLED in the host launch list (not the kernels), so E scales without changing a kernel — the same emitter serves 8B-scale and 30B-scale. - [fn emit_qwen30b_generate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/fn.emit_qwen30b_generate): Emit a self-contained CUDA program that AUTOREGRESSIVELY GENERATES from the real Qwen3-30B-A3B weights: the per-token math is the recognized LOGOS forward (RMSNorm → Q/K/V → per-head QK-norm + RoPE → causal attention over a KV cache → O-proj → residual → RMSNorm → 8-of-128 MoE → residual → LM head), wrapped in the compiler’s generation runtime — a prompt prefill, then a T=1 decode step captured as ONE CUDA graph and replayed per token (device-side position + token). This is the “llama.cpp, but authored in LOGOS” whole demo: it prints the generated token stream and the fair tg-style tok/s (a growing KV cache, exactly like llama-bench tg128). - [fn forward_graph](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/fn.forward_graph): The forward of a program as the shared table fuses it under the forward’s shim (`ForwardShim`): every statement the front end lifts (`crate::spatial::passes::recognize_stages::walk`), or the program refused whole, each refusal naming its statement. The front end decides what a statement IS (an op, a declaration, a fill, a write no op computes); `kernel_refusal` decides whether this lane’s kernels compute it. `q8` and `moe` name the weights it reads in Q8_0. - [fn forward_graph_holding](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/fn.forward_graph_holding): `forward_graph` with the optimizer’s steps `held` held back: the program run apart where they would fuse. - [fn gen_qwen30b_lg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/fn.gen_qwen30b_lg) - [fn moe_dp4a_kernels](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/fn.moe_dp4a_kernels): The sparse fused MoE kernel set for a coalesced int8 path: the precision-independent router + top-K pair, then the single-pass (default) or two-pass (logit-exact) quantize/gate-up-SwiGLU/down-combine trio. Public so a checked-in copy of the kernel set can be pinned byte-equal to what the compiler emits today. - [fn recognize_attention](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/qwen_emit/fn.recognize_attention): The single-query GQA `attention` block as this lane’s tuple: `(q, kc, vc, out, h, kv, hd, l)` — the shared `qwen::AttentionSpec` without its position bound (this lane attends to every cached row). ## logicaffeine_compile::codegen_cuda::solbench SOL-ExecBench harness bridge — turn a recognized LOGOS fused-row op into a submittable `solution.json` plus a torch-binding CUDA kernel that conforms to the benchmark’s ABI. - [struct SolSolution](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/solbench/struct.SolSolution): A generated SOL-ExecBench solution: the manifest and the CUDA source it references. - [fn emit_fused_row_solution](https://docs.logicaffeine.com/logicaffeine_compile/codegen_cuda/solbench/fn.emit_fused_row_solution): Emit a SOL-ExecBench solution for a recognized fused-row op (RMSNorm plain/weighted/fused-add, or LayerNorm). `definition` is the problem’s Definition name; `inputs` the input tensor names in Definition order; `output` the output name. The emitted `run` binding matches that order (DPS). ## logicaffeine_compile::codegen_dram codegen_dram — the DRAM compute-in-memory target (ComputeDRAM bulk bitwise + RowClone). - [mod dataflow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/dataflow/): DRAM dataflow composition — the spatial-dataflow layer of the compute-in-memory target. - [mod kernels](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/kernels/): DRAM application kernels — the workloads in-memory compute is lightning-fast at: bitwise + COUNT over massive data, at zero data movement. Popcount is the linchpin — the reduction that turns the bitwise/XNOR machinery into counts, distances, and dot products: - [mod set_algebra](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/set_algebra/): Set algebra on the DRAM plane — the COMPLETE finite set algebra over BITSET-encoded sets, lowered to DRAM dataflow kernels. A set over a bounded universe is a bit vector (a row): membership of element `i` is bit `i`. Over that encoding the set algebra IS the bitwise algebra — - [enum DramFragment](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/enum.DramFragment): Where an op lives in the DRAM-co-processor model. - [enum DramLowerError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/enum.DramLowerError): Why the DRAM tier declines a program — a SOUND refusal, never wrong memory. - [enum DramTier](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/enum.DramTier): The in-DRAM hardware tier an OnPlane op needs — the HONEST hardware assumption. Copy/AND/OR run on UNMODIFIED off-the-shelf DRAM (ComputeDRAM, Gao et al. MICRO 2019); XOR needs the AMBIT tier (dual-contact cells, a minor DRAM modification; Seshadri et al. MICRO 2017). `None` iff not OnPlane. - [fn dram_prim](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/fn.dram_prim): For an OnPlane op, the ComputeDRAM primitive that realizes it (proven ≡VM in `unified_placement`). `None` for every non-OnPlane op — the op-coverage ratchet asserts this biconditional (OnPlane ⟺ `dram_prim` is `Some`). - [fn dram_refusal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/fn.dram_refusal): The fail-closed refusal gate every DRAM offload runs FIRST. `None` means the program clears the gate (a bulk-bitwise/copy region exists, inside the memory-device model). - [fn dram_tier](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/fn.dram_tier) - [fn fragment](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/fn.fragment): ★ THE SINGLE SOURCE OF TRUTH ★ for how the DRAM tier classifies every VM op. EXHAUSTIVE on `Op` (no `_` arm) — a new instruction cannot escape classification. - [fn has_bitwise_region](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/fn.has_bitwise_region): Whether the program carries any OnPlane bulk-bitwise/copy work — the DRAM-region existence probe. - [fn unsupported_reason](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/fn.unsupported_reason): Returns `Some(reason)` if `program` uses an op with no home in a memory device — concurrency (a DRAM has no thread scheduler) or networking (host-only IO). Shares the offload classifier with the other single-device tiers so they cannot drift. ## logicaffeine_compile::codegen_dram::dataflow DRAM dataflow composition — the spatial-dataflow layer of the compute-in-memory target. - [struct DramDataflow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/dataflow/struct.DramDataflow): A straight-line in-DRAM dataflow graph: a growable row heap (operands then scratch) and the prim sequence computed over it. `not`/`and`/`or`/`copy` append a node writing a FRESH scratch row and return its index; higher-level gates compose those. This is the compiler-side spatial graph the DRAM plane executes. - [fn bit_serial_add](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/dataflow/fn.bit_serial_add): Bit-serial ripple-carry ADD over `B` bitplanes (SIMD across the lanes packed in each row): for each bit i, `sum_i = a_i XOR b_i XOR carry`, `carry = MAJ(a_i, b_i, carry)`. `a`/`b` are the operand-plane row indices (LSB first); `carry0` is a zero row. Returns the `B` sum-plane rows. Composed entirely from the `{AND, OR, NOT}` basis — arithmetic emerging from boolean dataflow. - [fn bit_serial_mul](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/dataflow/fn.bit_serial_mul): Bit-serial unsigned MULTIPLY (shift-add): for each bit i of `b`, add `a` (masked by plane `b[i]`) shifted up by i into an `out_width`-plane accumulator. Composed from AND + `bit_serial_add` — integer multiply from the boolean basis. Result is `a·b` mod 2^out_width per lane; `zero` is a zero row (accumulator seed + carry-in + high-plane filler). - [fn bit_serial_sub](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/dataflow/fn.bit_serial_sub): Bit-serial two’s-complement SUBTRACT: `a - b = a + NOT(b) + 1` (mod 2^B). Negates each `b` plane and ripple-adds with carry-in 1 (`ones_carry` = a row with every lane’s bit set). Returns the `B` difference-plane rows. Arithmetic subtraction, still composed from the boolean basis in-DRAM. ## logicaffeine_compile::codegen_dram::kernels DRAM application kernels — the workloads in-memory compute is lightning-fast at: bitwise + COUNT over massive data, at zero data movement. Popcount is the linchpin — the reduction that turns the bitwise/XNOR machinery into counts, distances, and dot products: - [fn agreement_count](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/kernels/fn.agreement_count): Per-lane AGREEMENT COUNT popcount(a XNOR b) — the binary / 1-bit neural-net DOT PRODUCT. For ±1 codes packed as bits, the true dot product is `2·agreements − K`; the agreement count is the in-DRAM half (XNOR + popcount, no multiply), the final affine map is a scalar host step. - [fn hamming_distance](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/kernels/fn.hamming_distance): Per-lane HAMMING DISTANCE between two bit-serial codes `a`/`b` (K planes each): popcount(a XOR b). The core kernel of vector similarity search (ANN over binary codes) and binary-net inference. - [fn popcount](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/kernels/fn.popcount): Per-lane POPCOUNT of `planes`: for each lane, the number of set bits across the planes, as an `out_width`-plane per-lane integer (LSB first). A reduction realized ENTIRELY in the DRAM plane by folding each plane into a bit-serial counter. `zero` is a zero row (the initial counter value). - [fn ternary_binary_dot](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/kernels/fn.ternary_binary_dot): BitNet-style TERNARY·BINARY dot product — one matmul row, entirely in-DRAM, NO multiply. Ternary weights `w[k]` ∈ {−1,0,+1} are carried as two disjoint bitplane sets: `wp[k]`=1 iff w=+1, `wn[k]`=1 iff w=−1. Binary activations `x[k]` ∈ {0,1}. Then, per lane (per output neuron), `dot = Σ w[k]·x[k] = popcount(Wp AND X) − popcount(Wn AND X)` as a two’s-complement `out_width`-plane integer. `zero` is a zero row, `ones` an all-ones carry row (for the subtract). This is how a 1.58-bit LLM layer runs where the weights live: AND + popcount + subtract, no multiplier. ## logicaffeine_compile::codegen_dram::set_algebra Set algebra on the DRAM plane — the COMPLETE finite set algebra over BITSET-encoded sets, lowered to DRAM dataflow kernels. A set over a bounded universe is a bit vector (a row): membership of element `i` is bit `i`. Over that encoding the set algebra IS the bitwise algebra — - [enum SetOp](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/set_algebra/enum.SetOp): A finite set operation over bitset-encoded sets. - [fn lower](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/set_algebra/fn.lower): Lower a set op to a DRAM dataflow kernel over operand rows `a` (and `b` for binary ops; `b` is ignored for Complement). Returns the result row index. Built entirely from the DRAM basis. - [fn recognize](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/set_algebra/fn.recognize): Recognize a VM ISA op as a set operation, if it is one. `IntersectOp`/`UnionOp` are the VM’s first-class set ops; difference / symmetric_difference / complement have no VM ISA op yet (the AOT tier emits them as IndexSet methods), so they are not recognized from a VM program — but their kernels below are proven and ready to dispatch once those ops become first-class. - [fn reference](https://docs.logicaffeine.com/logicaffeine_compile/codegen_dram/set_algebra/fn.reference): The set-theoretic reference over bitset rows — the universe is the full row width (`!0` per word). ## logicaffeine_compile::codegen_mx LOGOS → mixed-signal XPU — the unification of the digital whole-program engine (`crate::codegen_sva`’s wprog engine, exact ≡VM) and the analog plane (`crate::codegen_ana`, ε-certified floats / ½-grid-certified-exact integers). - [struct MixedPartition](https://docs.logicaffeine.com/logicaffeine_compile/codegen_mx/struct.MixedPartition): The program’s analog/digital split. `bindings` dispatch; `refusals` stay on the engine; nothing is silently skipped — every function appears in exactly one list. - [struct RegionBinding](https://docs.logicaffeine.com/logicaffeine_compile/codegen_mx/struct.RegionBinding): One region function bound to the analog plane, certificate-admitted. - [struct RegionRefusal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_mx/struct.RegionRefusal): One region function that stays digital, with the NAMED reason — the ledger the partition lock pins (shrink-toward-binding is the win condition). - [struct StackBinding](https://docs.logicaffeine.com/logicaffeine_compile/codegen_mx/struct.StackBinding): One binding PLACED on the stack, with its certified thermal map — the S6 composition. - [struct StackPartition](https://docs.logicaffeine.com/logicaffeine_compile/codegen_mx/struct.StackPartition): The stacked partition: every certificate-admitted region placed on the stack’s analog tiers with a certified temperature map that MEETS the declared cooling budget; a region that placed but cannot be cooled is a LEDGERED refusal, not a hot surprise. The accelerator covenant is unchanged — stripping every binding leaves the digital program. - [enum Fabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_mx/enum.Fabric): The four faces of the machine (R4): which laws of physics serve a region. - [fn fabrics](https://docs.logicaffeine.com/logicaffeine_compile/codegen_mx/fn.fabrics): Classify every function’s fabric AFFINITY: a certificate-admitted region is `Dataflow`; a body reaching the `Solve` desugar (`solveLinear`) is `Dynamics`; one reaching the `Minimize` desugar (`minimizeQuadratic`) is `Relaxation`; everything else is `Digital` — the face that refuses nothing. Deterministic, total. - [fn partition](https://docs.logicaffeine.com/logicaffeine_compile/codegen_mx/fn.partition): Partition every function of `source` against `target`: certificate-admitted regions bind (int-exact or float-ε per `try_region`’s lane decision); everything else is ledgered with its typed reason. Deterministic: same source + target ⇒ the same partition, always. - [fn partition_on_stack](https://docs.logicaffeine.com/logicaffeine_compile/codegen_mx/fn.partition_on_stack): Partition `source` onto a STACK: region compilation against the stack’s analog tier, 3D placement, the exact-ℚ thermal solve, and the cooling gate — in that order, each failure a named ledger entry. Deterministic end to end. ## logicaffeine_compile::codegen_riscv LOGOS → RISC-V AOT codegen tier. Lowers the register bytecode `CompiledProgram` — the SAME IR the WASM backend and the Silicon ISA emitter consume — to RV64GC assembly text (SysV lp64d ABI, glibc), which a RISC-V GCC assembles+links and `qemu-user` runs, byte-for-byte identical to the VM. - [struct Runtime](https://docs.logicaffeine.com/logicaffeine_compile/codegen_riscv/struct.Runtime): What a RISC-V program links beside its assembly: the C of its runtime shim, and what its link line names after the assembly and the shim. - [enum RiscVLowerError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_riscv/enum.RiscVLowerError): An op / type / shape outside the current phase’s supported fragment. The `&str` names what is not yet lowered (an op name, or a reason like `"Show of non-scalar value"`). A refusal — the backend declines to emit rather than emit wrong code (mirrors `crate::vm::wasm::WasmLowerError`). - [const RISCV_RUNTIME_C](https://docs.logicaffeine.com/logicaffeine_compile/codegen_riscv/constant.RISCV_RUNTIME_C): `logos_show_f64` renders an f64 EXACTLY like the VM’s `Show` (Rust’s `{}` Display: shortest decimal that round-trips, NEVER scientific notation, bare integral floats, `NaN`/`inf`/`-inf`/`-0`). It finds the shortest significant-digit count whose `%e` form round-trips via `strtod`, then reformats that to fixed decimal notation so any magnitude prints without an exponent — matching Rust for every finite value. Called with the double in `fa0` (a named param, so no variadic-FP marshalling needed). - [fn codegen_program_riscv](https://docs.logicaffeine.com/logicaffeine_compile/codegen_riscv/fn.codegen_program_riscv): Emit `program` as RV64GC assembly text. Returns `RiscVLowerError::Unsupported` if the program uses any op/shape outside the currently-lowered fragment. - [fn links_value_runtime](https://docs.logicaffeine.com/logicaffeine_compile/codegen_riscv/fn.links_value_runtime): Whether the RV64GC assembly `asm` links the exact extension’s value runtime: it defines `VALUE_RUNTIME_SYMBOL`. - [fn mutates_own_collection](https://docs.logicaffeine.com/logicaffeine_compile/codegen_riscv/fn.mutates_own_collection): Whether this tier lowers `op` as a value-semantics mutation of a register’s own collection or Text, or of a value in its own record’s field: through an `_own` runtime helper that copies first only what the register’s owned flag (and, for a field, its field flag) says may be held elsewhere, so the change never reaches an alias and a loop of them runs in place. - [fn runtime](https://docs.logicaffeine.com/logicaffeine_compile/codegen_riscv/fn.runtime): The runtime the assembly `asm` links. A program the exact extension never reaches links `RISCV_RUNTIME_C` and the math library. One it reaches links the shim with the extension’s adapter after it (the extension’s C core over the shim’s collector, then the entry points the assembly calls), and `logicaffeine-data`’s value runtime built for RV64GC Linux with the system libraries it calls, statically. ## logicaffeine_compile::codegen_sass codegen_sass — the foundation of our OWN sm_86 SASS assembler (the MaxAs / turingas lever). - [struct Control](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/struct.Control): The per-instruction control codes — where the GPU’s static scheduling lives. - [struct DepGraph](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/struct.DepGraph): A register-dependency DAG over a straight-line SASS region: `deps[i]` lists earlier instructions that `i` must stay after (RAW/WAR/WAW hazards + barrier ordering). Any reordering that respects these edges preserves semantics — this is what the scheduler is free to permute to hide latency. - [struct SassInsn](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/struct.SassInsn): One decoded SASS instruction: its byte offset within the .text section and the raw 128-bit encoding. - [struct SassReport](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/struct.SassReport): What the COMPILER learns about the machine code `ptxas` produced for one of its kernels — the SASS-awareness the backend needs to reason about the ptxas ceiling (register pressure/occupancy, tensor-core utilisation, reuse-cache usage). Every field is read from the real cubin, not guessed. - [enum SassClass](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/enum.SassClass): Execution-unit class of a SASS opcode — what a scheduler must know to place it and set control codes. - [fn analyze_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/fn.analyze_source): The compiler emits `cu_src`, compiles it with nvcc to a cubin, and returns the SASS report — the backend “knowing” the machine code its codegen ultimately becomes. Requires nvcc + nvdisasm; returns None otherwise. - [fn assign_minimal_stalls](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/fn.assign_minimal_stalls): CONTROL-CODE ASSIGNER (perf): compute the MINIMAL stall per instruction from the fixed-latency dependency timing, keeping ptxas’s memory barriers. We walk the instruction order tracking the cycle each register’s fixed-latency result becomes ready; each instruction issues at the max of (prev issue + 1) and its producers’ ready cycles; the stall between two instructions is exactly that gap (clamped to `[1,15]`). This is the tightest schedule that still satisfies every fixed-latency hazard — if ptxas over-stalled anywhere, ours is faster; if it was already minimal, ours matches. Correctness is guarded on-device (a too-tight stall that violates a hazard we don’t model shows up as a wrong result). Returns the patched cubin bytes. - [fn assign_minimal_stalls_opt](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/fn.assign_minimal_stalls_opt): As above, but `floor_ptxas` selects whether to floor our computed stall at ptxas’s (sound) or trust our CALIBRATED model outright (`false` — the true test of whether the measured latencies are complete). - [fn assign_stalls_by_latency](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/fn.assign_stalls_by_latency): CONTROL-CODE ASSIGNER (correctness-first, stalls). Recompute every instruction’s STALL count from our own latency model — `stall = fixed_latency(class)` — which is provably >= the cycles any fixed-latency consumer needs (the immediate next instruction already issues `stall` cycles later, so later consumers have even more). We KEEP ptxas’s write/read barriers + wait masks (the variable-latency memory / cp.async tracking, the fragile part) untouched. If the kernel stays numerically correct with OUR stalls, the stall model is validated on-device — the first half of a working control-code assigner. Returns the patched cubin bytes. - [fn build_dependency_graph](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/fn.build_dependency_graph): Build the dependency DAG from per-instruction (reads, writes, is_barrier) triples. Barriers (BAR/BSYNC/ control) force a total order across themselves: nothing moves past a barrier in either direction. - [fn classify_opcode](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/fn.classify_opcode): Classify an sm_86 SASS base mnemonic (the token before the first `.`). Covers the full 81-opcode inventory extracted from real machine code (our GEMM + cuBLAS) — this is the ISA a SASS scheduler operates over. - [fn dependency_graph_from_cubin](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/fn.dependency_graph_from_cubin): Build the dependency DAG directly from a cubin, using nvdisasm to name each opcode (so classification — hence the read/write sets — is precise). Returns the graph paired with the parsed instructions. This is the mnemonic-aware, SOUND path the scheduler uses. - [fn find_text_section](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/fn.find_text_section): Locate the `.text.` section in a cubin ELF64: returns (file_offset, size_in_bytes). - [fn instructions](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/fn.instructions): Parse every 128-bit instruction out of the kernel’s .text section of a cubin. - [fn list_schedule](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/fn.list_schedule): LIST SCHEDULER — the scheduler engine. Given the sound dependency DAG and per-instruction latencies, produce a new instruction order that respects every hazard while placing latency-critical work early so its result is ready by the time a consumer needs it (classic critical-path list scheduling). Returns the new order as original-instruction indices. This is what a re-emitter writes back to close the gap ptxas’s schedule leaves. - [fn nvdisasm](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/fn.nvdisasm): Disassemble a cubin file to SASS text via nvdisasm (for inspection / labelling). - [fn optimize_reuse](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/fn.optimize_reuse): The reuse-cache optimizer pass — our first SASS optimization ON TOP of ptxas. The operand collector can REUSE a source register read by the previous instruction instead of re-reading the register file, saving RF bandwidth (the bottleneck under our 222-register, 16.7%-occupancy kernel). ptxas already sets many reuse flags; this finds the ones it MISSED: consecutive instructions that read the same register into the same operand slot (Ra→reuse bit 0 = `hi[58]`, Rb→reuse bit 1 = `hi[59]`) but where the flag is unset. RZ is skipped (reusing the zero register is pointless). Returns the patched cubin bytes and the number of flags added. The result MUST be validated on-device (varied-fill oracle) — the operand→slot mapping is verified there, never trusted blind. - [fn patch_hi](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/fn.patch_hi): Patch instruction `idx`’s high word (control codes live here) in-place in the cubin bytes. - [fn precise_dependency_graph](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/fn.precise_dependency_graph): Build a PRECISE dependency DAG from a cubin by parsing nvdisasm’s exact operands per instruction (not the conservative range approximation). This gives the scheduler maximal legal freedom — the graph has only the TRUE hazards, so a reschedule can hide latency ptxas left exposed. Returns (insns, classes, mnemonics, DAG). - [fn precise_operands](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sass/fn.precise_operands): PRECISE operand decode from the nvdisasm TEXT of one instruction (everything after the mnemonic, before the `;`). nvdisasm already prints the exact registers, so we parse them rather than reverse-engineer the binary operand fields. Returns (writes, reads) as register numbers (RZ/255 dropped). Rules, verified against real SASS: operand 0 is the WRITE destination UNLESS it is a memory ref `[...]` (a store — then it’s a read address and nothing is written); every other operand is a READ; registers inside `[...]` are address reads; a `.64`/`.128` width on an address adds the consecutive address registers; accumulate ops (IMMA/FFMA) naturally read their destination because it reappears as a later operand. Groups `{R8,R9,...}` expand. ## logicaffeine_compile::codegen_sva SVA/PSL Code Generation for Hardware Verification - [mod arbiter_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/arbiter_rtl/): arbiter_rtl — the deterministic NoC arbiter’s entropy core in silicon. - [mod autopipe](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/autopipe/): Pipelining combinational logic to a target clock with the fewest register bits, the cut certified optimal. - [mod backend](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/backend/): The target-backend seam. - [mod bignum_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bignum_rtl/): bignum_rtl — the numeric tower’s foundation in silicon: the BigInt datapath. - [mod bitblast](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/): Bit-blasting: `BoundedExpr` datapath (bitvector) operations → boolean `ProofExpr`. - [mod block_engine_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/block_engine_rtl/): block_engine_rtl — Stage 5 of the self-synthesizing bytecode XPU: the on-chip EXECUTE engine for a decoded block. Stage 4’s reconfigurable fabric runs a block’s certified SPATIAL placement (host-computed). This engine takes a block’s DECODED OPS DIRECTLY — no host placement step — and runs them on a universal reconfigurable datapath: one hardware array executes ANY bounded straight-line block by loading its op list as config. This is the unit the LGB1 decoder feeds: bytecode → ops → this engine → result, all on-chip. - [mod caravel_project](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/caravel_project/): A Caravel user project as data. - [mod caravel_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/caravel_rtl/): caravel_rtl — the Infinichip command player wrapped as an efabless Caravel user macro, the step that makes it literally shuttle-integratable. - [mod cdc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/cdc/): Clock Domain Crossing (CDC) Formal Verification - [mod chan_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chan_rtl/): chan_rtl — the deterministic channel in silicon: a bounded FIFO. - [mod chip_protocol](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/): The chips’ byte protocol on the UART, defined once. - [mod choreography](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/choreography/): The control plane of a spatial pipeline: the tokens and credits that make a metapipeline run, and the buffer depth that follows from them. - [mod ci](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ci/): CI/CD Integration — SARIF Output for GitHub Security Tab - [mod computedram_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/computedram_rtl/): computedram_rtl — Phase 4: the in-DRAM compute path proven end-to-end in simulation. - [mod controller_gen](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/controller_gen/): Designer → certified controller: turn a synthesized `PhasePlan` into a Verilog phase-FSM and let the existing RTL pipeline (`parse_transition_system` → `prove_invariant`) certify it. - [mod coproc_core](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coproc_core/): coproc_core — the coprocessors, ISSUED as CPU instructions. - [mod coproc_soc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coproc_soc/): coproc_soc — the ULX3S-flashable SoC wrapper around `coproc_core`. - [mod coverage](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coverage/): Specification Coverage Metrics - [mod crdt_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/crdt_rtl/): crdt_rtl — the CRDT merge unit in silicon. - [mod dae](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dae/): dae — Decoupled Access-Execute for the spatial fabric (`FabricTarget::agu`). - [mod ddr2_dfi](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_dfi/): ddr2_dfi — `ddr2_dfi_ctrl`, the LOGOS DDR2 controller at the DFI 1:2 rate: a 64-bit native request port (a word a command, write data on its own stream, read data back in request order) and two DFI phases a system clock, the interface LiteDRAM’s controller presents to its PHY, so either drives the same PHY. - [mod ddr2_jedec](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_jedec/): ddr2_jedec — a DDR2 part’s datasheet timing at one clock, and the JESD79-2 command rules a bus trace is held to. - [mod ddr2_phy](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/): ddr2_phy — a full custom hand-rolled DDR2 controller + PHY for the Nexys A7-100T’s on-board Micron MT47H64M16 (1 Gb, x16, 8 banks, DDR2-800). This is Phase 1 of the DRAM-into-Compute campaign: total ownership in the openXC7 flow (no vendor MIG), tied directly to the `dram_executor` command engine (`super::dram`), so the SAME command stream that drives the JEDEC-legal schedule also drives the deliberately-illegal ComputeDRAM cadences. - [mod ddr2_traffic](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/): ddr2_traffic — the K7 traffic: one stream of 64-bit words that every DDR2 controller of the comparative bench writes to the same part and reads back, the device and testbenches it runs on, and the judgement of a run’s log. - [mod ddr4_jedec](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/): ddr4_jedec — a DDR4 channel’s timing at its clock, the JESD79-4 command rules a trace is held to, and the in-order controller that turns line streams into commands on it. - [mod decision_workload](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/decision_workload/): The HFT decision as a workload: its one LOGOS source, lowered to a combinational select-DAG by `emit_decision_fabric` (the decision fabric), and run as ordinary bytecode on the routable scalar core by the program here — the CPU twin of `decision_hft_realbist`. Both blocks decide over the same realistic input ranges, so their gate-level switching power per decision is one comparison. - [mod dram](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/): dram — the DRAM machine. - [mod engine_build](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/engine_build/): LOGOS source → what the whole-program fabric engine loads: the program lowered to an engine config, proven to answer what the VM answers on the exact arguments about to be streamed before a byte is emitted, checked against the deployed engine’s profile and the flashed image’s caps. One path for every caller — the `emit_wpe_soc` example the board hosts compile through, and the Fabric Terminal’s library — so a program is lowered the same way wherever it runs. - [mod fabric_config](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_config/): fabric_config — Phase D: the config-driven reconfigurable grid = THE INTERPRETER. - [mod fabric_grid](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/): fabric_grid — a TRUE reconfigurable CGRA: place a fabric’s dataflow onto a 2-D array of identical tiles and route it through a LOCAL switchbox interconnect. The same silicon runs any fabric by reconfiguration — not a bespoke circuit per program. - [mod fabric_pipe](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/): fabric_pipe — the compiled residual circuit cut into register stages: a new input every clock, a short period. - [mod fabric_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/): fabric_rtl — Futamura’s first projection in silicon: “the specialized residual IS the circuit,” end-to-end from the REAL compiler. - [mod fabric_soc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/): fabric_soc — Phase E: the FLASHABLE reconfigurable-fabric SoC. - [mod fabric_target](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_target/): fabric_target — the ADL spine: a `FabricTarget` descriptor + `place_with_target`. - [mod fabric_tile](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_tile/): fabric_tile — the SINGLE SOURCE OF TRUTH for “which ISA ops the spatial fabric realizes”. - [mod fanout](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fanout/): fanout — the pit-of-success primitive for antenna-safe wide selects. - [mod floorplan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/): Floorplans read off a fitted build: a Logic Lock region for each instance named, a square beside the site its clock comes from, as small as what the instance needs at the parent region’s density allows, inside the parent region. - [mod flow_config](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/flow_config/): `flow_config` — the compiler emits its own physical-design configuration. - [mod fol_to_sva](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fol_to_sva/): FOL → SVA Formal Synthesis - [mod fol_to_verify](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fol_to_verify/): FOL → Bounded Verification IR Translation - [mod fp_hard](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/): The engine’s f32 multiply and add on the card’s floating-point DSP block (`fourteennm_fp_mac`), as the oracle (`super::fp_oracle`) measured it: a wrapper with the pipelined unit’s ports (`logos_fmul_p`’s and `logos_fadd_p`’s: `clk`, `a`, `b`, `y`) and exactly its latency, computing the engine’s own arithmetic (`Semantics::ENGINE`) on a block whose semantics are another member of the family, wherever a thin layer of logic around the block can make them one. - [mod fp_hypotheses](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hypotheses/): Binary32 multiply and add under a family of semantics: the hypotheses a hard floating-point block is told apart by. - [mod fp_oracle](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/): The hard floating-point oracle: a D5005 persona that measures which binary32 semantics the card’s floating-point DSP block computes (`fourteennm_fp_mac`, whose simulation model is encrypted), by running the block beside every class of the hypothesis family (`super::fp_hypotheses`) as soft units on one stream of operands and counting, class by class, the results that differ from the block’s. - [mod fp_receipt](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/): The card’s measurement of its floating-point DSP block as a receipt (`benchmarks/silicon/d5005/fp_hard_receipts.json`): what the oracle persona (`super::fp_oracle`) measured on the card, tied to the build that compiled it and the image the card ran, with what each mode’s block is for the engine (`super::fp_hard`). The block is the vendor’s and encrypted, so a receipt is a measurement recorded as one; the proofs hold everything around it. - [mod full_asm](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/full_asm/): full_asm — assemble a compiled LOGOS program (register bytecode `CompiledProgram`) into the instruction words the FULL soft-core (`soft_core.v`) executes: the whole 113-op ISA — user functions (hardware arg-copy `Call`), division/modulo (the sequential shared divider), and the structured heap (lists, tuples, ranges, sets, maps, structs) — so the ENTIRE benchmark suite compiles from `.lg` source to words that run on silicon byte-identically to the VM. - [mod fusion](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fusion/): Operand sharing — reader fusion on the RDU, decided from the cost model. - [mod gpu_simt_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/gpu_simt_rtl/): gpu_simt_rtl — the GPU processor edge: a tuneable SIMT data-parallel engine in silicon. - [mod handshake_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/handshake_rtl/): Handshake primitives of the spatial IR in silicon: the bounded FIFO (`Handshake::Fifo`), the counting semaphore (`Handshake::Semaphore`’s ready counter / valid flag), the arrive-all barrier (`Handshake::Barrier`) and the one-writer multicast bus (a `Group`). Each emitter is paired with a trace testbench whose expected values come from the Rust model of the same primitive, and the FIFO’s bound is proven by k-induction with our own certified SAT — the sequential analogue of the combinational proofs the datapaths carry. - [mod hart](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/): The board’s own CPU: an RV64IMAC hart with machine and user modes, built to run the LOGOS compiler from the board’s DDR2 so the board compiles programs for its fabric engine with no computer attached. - [mod hw_pipeline](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/): Hardware Verification Pipeline - [mod infinichip_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/infinichip_rtl/): infinichip_rtl — the integrated Infinichip memory subsystem, taken all the way to a signoff-clean Sky130 GDSII. - [mod keccak_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/keccak_rtl/): keccak_rtl — the flagship silicon FACT. - [mod lutmap](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/lutmap/): Mapping logic onto K-input LUTs for depth, the way an FPGA’s synthesis sees how deep a circuit is. - [mod memsched](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/memsched/): memsched — the static-memory-schedule FACT. - [mod metapipeline](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/metapipeline/): The metapipeline initiation-interval (II) model — P1 of the Plasticine lane, and the question an RDU engineer asks first: how often can a pipelined stage accept a new iteration, and how deep must the buffers between stages be? - [mod mul_tree](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/mul_tree/): mul_tree — a word multiply as an aligned tree of adds. The product `a · x mod 2^w` is the sum of the `w` partial products `x[i] ? a << i : 0`; the tree adds them pairwise, level by level, each add only as wide as the bits it can still change (a partial product shifted by `i` is zero below bit `i`, and nothing above bit `w − 1` survives), and a register can follow any level. On a fabric with carry chains every add is one chain and nothing multiplies; cut after every level, no stage holds more than one add. - [mod netlist](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/): Verilog to and-inverter graphs, through yosys: the bridge that puts any RTL the compiler prints in front of the certified equivalence engine (`logicaffeine_proof::sweep`, `logicaffeine_proof::seq_equiv`). - [mod onboard](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/onboard/): The compiler as the board’s own CPU runs it: LOGOS source → register bytecode → the fabric engine’s wire image, through exactly the path the laptop’s board hosts take (`super::engine_build`), with the VM’s golden proven against the engine model before a byte of the image exists. The board runs a `riscv64gc-unknown-linux-musl` build of this same code; `onboard_compiler_lock` holds its every answer byte-identical to the host build’s. - [mod pdk_target](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/): `PdkTarget` — the PROCESS a design is built out of, as data. - [mod plasticine](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine/): The Plasticine mesh descriptor — the open RDU (Prabhakar et al., ISCA 2017) and its SARA/Capstan-era successor configuration — as a physically-described target that wraps the certified `FabricTarget` seam. - [mod plasticine_place](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/): Mesh placement + static routing for a Plasticine configuration — P3 of the Plasticine lane. - [mod plasticine_report](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/): The Plasticine report — P4 of the Plasticine lane: the artifact an RDU engineer reads, generated from the model so no number in it is typed by hand. - [mod pmu](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pmu/): The PMU banking model — P2 of the Plasticine lane: the Pattern Memory Unit’s scratchpad as the papers describe it (ISCA’17 §3.2), with an executable meaning. - [mod pnr_certificate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pnr_certificate/): Proof-carrying place-and-route. - [mod power](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/power/): Power-Aware Formal Verification - [mod preflight](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/): Whether a persona build fits the card’s partial-reconfiguration region and can close its clock, decided before Quartus runs, from what the build ledger has measured. - [mod protocols](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/protocols/): Pre-Verified Protocol Templates - [mod psram](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/): The off-chip memory edge for a QSPI PSRAM — the block behind the memory-edge descriptor contract when the far side is a pseudo-SRAM instead of a DRAM. - [mod qor_harness](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/): qor_harness — the measurement harness of the comparative-synthesis bench. - [mod quartus](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/): Quartus Prime reports as data: a compile’s flow, the resources it used, the slack of every clock, the retimer’s limits, the router’s peak wire demand, and the resources and logic depth of every entity, read from the text reports Quartus writes into a project’s `output_files`. - [mod reconfig_fabric_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/reconfig_fabric_rtl/): reconfig_fabric_rtl — Stage 4 of the self-synthesizing bytecode XPU: the placer IN SILICON as a RECONFIGURABLE fabric. Stage 1 HARDWIRED a grid per block; Stage 3 proved `route_loop_body` correct for every bounded body. This stage makes the fabric CONFIG-DRIVEN: ONE fixed R×C tile array whose every tile’s operation and channel routing are RUNTIME inputs, so loading the certified placement of ANY block runs it on the same physical silicon — the reconfigurable array the on-chip placer configures. - [mod reverse_module](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/reverse_module/): R5 — the SVA REVERSE-MODULE OBLIGATION for Hardware Studio. - [mod rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl/): RTL / transition-system bounded model checking — including multi-bit (bitvector) registers. - [mod rtl_extract](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl_extract/): Verilog Declaration Parser - [mod rtl_kg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl_kg/): RTL KG + Spec-RTL Linking - [mod scalar_asm](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/scalar_asm/): scalar_asm — assemble a compiled LOGOS program (the register bytecode `CompiledProgram`) into the instruction words that `soft_core_scalar.v` executes, so a REAL `.lg` program can be streamed to the Nexys A7 FPGA over UART and run on silicon (see scripts/run-on-nexys-scalar.sh). - [mod scratchpad_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/scratchpad_rtl/): scratchpad_rtl — the on-chip scratchpad subsystem in silicon. - [mod select_hoist](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/select_hoist/): select_hoist — a decision fabric’s selects hoisted out of its arithmetic: every select an add, a shift or a compare reads is cofactored away, so the fabric becomes arithmetic over its inputs, compares of that arithmetic, and one tree of selects over the compares’ outcomes. - [mod sequencer_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/sequencer_rtl/): sequencer_rtl — Stage 1 of the self-synthesizing bytecode XPU: the AUTONOMOUS block-walk sequencer as synthesizable RTL. The CONTROL PLANE that `run_program_cfg_on_grid` modelled in software now exists in silicon: a register file that survives block reconfiguration, per-block placed grids, a block program- counter, a terminator FSM (Jump/Branch/Return), and a cycle counter — a hardwired micro-sequencer that walks the whole function itself, one block per clock, with no host help. - [mod shuttle_wrapper](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/shuttle_wrapper/): Packing EVERY signed-off macro into ONE Caravel shuttle submission. - [mod signal_design](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/signal_design/): Conflict-free traffic-signal PHASE DESIGNER (certified SAT synthesis). - [mod signoff_blocks](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/signoff_blocks/): The clock period every hardened block is signed off at — held here, derived from its measured SLOW corner, and the only period `emit_flow_config` accepts for a registered block. - [mod simd](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/): simd — configurable-precision packed SIMD lanes for the fabric datapath (`FabricTarget::simd`). - [mod simt_ports](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simt_ports/): simt_ports — the SIMT engine’s step on ports: its uniforms, its mask and every lane’s varying as inputs, every lane’s output and the warp-reduce as outputs, a step every clock. Where the engine’s register file (`emit_gpu_simt_verilog`) takes a step’s operands a slot a clock and hands its results back a read at a time, this takes them all at once, as a caller holding them in registers presents them, and reads no register of its own on the way in. - [mod soft_core_model](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/): The cycle-accurate Rust model of `benchmarks/silicon/soft_core.v` — the executable spec of the LOGOS universal interpreter in silicon. Fetch/decode/execute over a chip-word program (`[opcode:8][dst:8][a:8][b:8]`; wide/float/heap ops per the doc on `run_soft_core_typed`), returning the `Show` sequence. This is the differential ORACLE the whole spatial-interpreter campaign checks against: `compile_to_full_words` -> `run_soft_core_typed` must equal `compile::vm_outcome` for every program, and the iverilog testbenches agree with it. Lifted here (from `rtl.rs`’s test module) so both the in-crate RTL tests and the `logicaffeine_tests` integration locks share ONE oracle. - [mod spatial_emit](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/spatial_emit/): Spatial source emission for a counted loop — the bridge from the certified fabric IR to the open Plasticine toolchain (Spatial → PIR → plastiroute → Tungsten; Koeplinger et al., PLDI 2018; the chain is mirrored at gitlab.com/dataplane-ai). P4 of the Plasticine lane. - [mod storage_controller_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/storage_controller_rtl/): storage_controller — the deterministic NAND storage controller (the storage analog of `super::dram`). - [mod sufficiency](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/sufficiency/): Property Sufficiency Analysis - [mod sva_model](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/sva_model/): SVA Semantic Model - [mod sva_to_proof](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/sva_to_proof/): Bounded SVA/FOL obligation → `ProofExpr` (the certified-prover seam). - [mod sva_to_verify](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/sva_to_verify/): SVA → Bounded Verification IR Translation - [mod sva_vacuity](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/sva_vacuity/): SVA Nonvacuous Evaluation Tracking (IEEE 16.14.8) - [mod synthesis_refine](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/synthesis_refine/): CEGAR Refinement for SVA Synthesis - [mod synthesize](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/synthesize/): Sprint 5C: Top-Level Synthesis API - [mod systolic](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/systolic/): systolic — the weight-stationary spatial GEMM tile (Phase 1). - [mod terminal_protocol](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/terminal_protocol/): The Fabric Terminal’s wire protocol and screen, in one place: the link between a host and the terminal board (Board B, the Nexys A7-100T) that puts a LOGOS editor on a VGA screen, takes a keyboard on the board’s USB port, and runs each program on the fabric engine beside them. - [mod terminal_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/terminal_rtl/): The Fabric Terminal’s RTL, emitted from its templates (`codegen_sva/terminal/`) with every protocol byte and dimension filled from `super::terminal_protocol`: the UART, SLIP framing, the PS/2 port, the VGA text plane, the link controller, the activity panel and the Nexys A7-100T top with its pins; and `render`, the picture the screen’s frames are held to. The board build reads the emitted files (`board_files`) from `benchmarks/silicon/`, where `fabric_terminal --emit` writes them. - [mod timing_graph](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/timing_graph/): A circuit’s timing graph: how deep its logic is, where the depth sits, and the bound its loops put on the clock, known before Quartus runs. - [mod traffic_flow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/traffic_flow/): Traffic FLOW / capacity analysis as model checking. - [mod unified_placement](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/unified_placement/): unified_placement — Phase 5: ONE LOGOS program placed across THREE execution planes that all run LOGOS (host-CPU tiers, the reconfigurable fabric-CPU, and the DRAM-compute plane), under a single shared primitive descriptor, certified ≡ the VM. - [mod verified_compiler](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/verified_compiler/): Verified SVA Compiler via Futamura Projections - [mod verify_to_kernel](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/verify_to_kernel/): Spec Encoding: BoundedExpr → Kernel Term - [mod wpe_caravel](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/wpe_caravel/): The whole-program engine as a Caravel user project: the off-chip engine (`wpe_offchip`) on the Caravel user interface, its UART and its PSRAM on user GPIOs, clocked by `user_clock2` (`WPE_CLOCK`) and reset by the management SoC. - [mod wpe_floorplan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/wpe_floorplan/): The whole-program engine’s memory, planned against a real process — before place-and-route. - [mod wpe_offchip](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/wpe_offchip/): The whole-program engine with its bulk memories off the die: the same loader and interpret FSM, whose heap, frame stack and config image — any of them — live in a QSPI PSRAM behind one `psram_edge`, each through its own `psram_cache`, the caches sharing the edge through a `psram_arbiter`. - [mod wprog_engine_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/wprog_engine_rtl/): wprog_engine_rtl — the WHOLE-PROGRAM spatial engine: run an entire control-flow program on the reconfigurable fabric, streamed over the wire, not just one straight-line block. Where the block engine (`block_engine_rtl`) runs a single straight-line residual, this runs a whole `ProgramCfgFabric` — multiple basic blocks with branch conditions (`Select` cells), a register file that survives block reconfiguration, and a block-walk terminator (Jump / Branch / Return) — the RTL of `run_program_cfg_on_grid` driven by a flat config, so ANY acyclic branchy program runs on ONE physical array by loading its config. - [mod xpu_soc_rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/xpu_soc_rtl/): xpu_soc_rtl — Stage 6 of the self-synthesizing bytecode XPU: the SoC that receives a block’s BYTECODE OVER THE WIRE, parses it on-chip, and runs it on the reconfigurable execute engine — the north star made physical (in simulation). A block’s decoded op list is serialized to a byte stream (the wire format); the SoC clocks the bytes in one at a time into an on-chip buffer, assembles them into the engine’s config + inputs, and the engine computes the result — no host help beyond the bytes on the wire. - [mod z3_synth](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/z3_synth/): Sprint 4A: Z3 Synthesis Constraint Builder - [struct SvaProperty](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/struct.SvaProperty): A single SVA property ready for emission. - [enum SvaAssertionKind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/enum.SvaAssertionKind): Assertion type — determines the SVA wrapper. - [fn emit_psl_property](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fn.emit_psl_property): Emit a single PSL property. - [fn emit_rust_monitor](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fn.emit_rust_monitor): Emit a Rust runtime monitor scaffold for a property. - [fn emit_sva_module](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fn.emit_sva_module): Emit multiple SVA properties as a complete module. - [fn emit_sva_property](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fn.emit_sva_property): Emit a single SVA property with its assertion wrapper. - [fn sanitize_property_name](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fn.sanitize_property_name): Sanitize a human-readable property name into a valid SVA identifier. “Data Integrity” → “p_data_integrity” ## logicaffeine_compile::codegen_sva::arbiter_rtl arbiter_rtl — the deterministic NoC arbiter’s entropy core in silicon. - [const ARBITER_TEST_SEED](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/arbiter_rtl/constant.ARBITER_TEST_SEED): The fixed seed the arbiter differential uses (a stand-in for `LOGOS_SEED`). - [const SM64_GAMMA](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/arbiter_rtl/constant.SM64_GAMMA): The SplitMix64 golden constants — IDENTICAL to `logicaffeine_system::concurrency::SplitMix64`. - [const SM64_MIX1](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/arbiter_rtl/constant.SM64_MIX1) - [const SM64_MIX2](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/arbiter_rtl/constant.SM64_MIX2) - [fn emit_seeded_arbiter_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/arbiter_rtl/fn.emit_seeded_arbiter_testbench): A self-checking testbench: load a seed, step N times, and compare each hardware draw against the software oracle sequence from `arbiter_seq.hex`. Prints PASS/FAIL. - [fn emit_seeded_arbiter_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/arbiter_rtl/fn.emit_seeded_arbiter_verilog): Emit the clocked SplitMix64 draw core: on each `step`, advance the state and present the mixed 64-bit draw on `draw` with `draw_valid`. Combinational mixing, registered state — one draw per requested step, deterministic from the loaded `seed`. - [fn sm64_next](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/arbiter_rtl/fn.sm64_next): The software SplitMix64 draw — mirrors the runtime, the oracle the RTL is checked against. ## logicaffeine_compile::codegen_sva::autopipe Pipelining combinational logic to a target clock with the fewest register bits, the cut certified optimal. - [struct Plan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/autopipe/struct.Plan): A pipeline: each node’s stage, and the registers each net bit carries. - [enum Cuts](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/autopipe/enum.Cuts): Where registers may go. - [enum EmitError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/autopipe/enum.EmitError): Why a plan could not be written out. - [enum PipeError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/autopipe/enum.PipeError): Why logic was not pipelined. - [fn check](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/autopipe/fn.check): Whether `plan` pipelines `graph`: every edge’s register count is the difference of its ends’ stages, never below zero and zero out of a node its policy puts no register after; every input at stage 0 and every output with the registers to reach the latency; every named net’s registers the most its readers and the latency need; and no path between registers deeper than the period. - [fn emit](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/autopipe/fn.emit): `graph`’s logic pipelined by `plan` as a Verilog module named `module`: every connection reads its source through as many registers as the plan puts on it, clocked by `clk` and, when `enable` names a port, stepping only when it is high. An input of the source with one of those names that no logic reads is that port; one the logic reads is refused. - [fn min_latency](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/autopipe/fn.min_latency): The least latency `graph` pipelines in at `period`: the latest any output’s sink must be in the earliest schedule the difference constraints allow. - [fn pipeline](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/autopipe/fn.pipeline): The pipeline of `graph` at `period` and `latency` with the fewest register bits, its registers where `policy` allows. - [fn unpipelined](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/autopipe/fn.unpipelined): The logic of a pipeline with its registers taken out, and the latency they made: a graph `pipeline` cuts afresh at any period. A pipeline’s registers are plain flip-flops, one registered edge into each, and every path from its inputs to a node holds as many of them, so every output is the same number of clocks late; taken out, each is a wire from its data, or its data’s constant when the source hands it one. A register with more in than its data (an enable, a reset, a memory’s port) is refused by name, and so is a node whose paths hold different numbers of registers; a register in a loop leaves logic looping through none. ## logicaffeine_compile::codegen_sva::backend The target-backend seam. - [struct RduBackend](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/backend/struct.RduBackend): The SambaNova RDU slot — the placed-grid lane, for either RDU generation (`RduChip`). Its target is the chip’s `FabricTarget` derived from `RduChipFacts`. It cannot emit RDA/SambaFlow config today — that needs the vendor SDK — so its emission is honestly `BackendArtifact::SdkGated`: it hands back the `logos.spatial.neutral` v2 envelope under `"lane": "grid"`, the same envelope the spatial lane emits, with the ready-to-bridge deterministic grid dump as its body. Its proof-carrying `certify` works NOW (no SDK), so an RDU-bound placement already ships with a machine-checkable proof it ≡ the source. When the SDK lands, only the `envelope → RDA config` translation is added. - [struct SkyVerilogBackend](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/backend/struct.SkyVerilogBackend): The default backend: our Sky130/FPGA path. A faithful wrapper of the existing free emitters — byte-identical to calling `emit_grid_verilog` / `emit_config_grid_verilog` directly. - [enum BackendArtifact](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/backend/enum.BackendArtifact): What a backend produces from a placed grid. - [trait TargetBackend](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/backend/trait.TargetBackend): A named codegen backend for a described `FabricTarget`. - [fn serialize_grid](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/backend/fn.serialize_grid): A deterministic, parseable neutral dump of a placed grid — the artifact the vendor-config bridge consumes. Rows/cols are walked in order and every field is a `Copy` enum’s `Debug`, so the output is stable (no hashmap iteration). It is NOT any vendor’s format; it is the ready-to-bridge placement. ## logicaffeine_compile::codegen_sva::bignum_rtl bignum_rtl — the numeric tower’s foundation in silicon: the BigInt datapath. - [const LIMBS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bignum_rtl/constant.LIMBS) - [fn emit_bigint_alu_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bignum_rtl/fn.emit_bigint_alu_testbench): Self-checking ALU testbench: apply N (a,b) and compare sum/cout, diff/borrow, eq/lt against the software oracle from `bigint_{a,b}.hex` + `bigint_{sum,sub,cmp}.hex`. Prints PASS/FAIL. - [fn emit_bigint_alu_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bignum_rtl/fn.emit_bigint_alu_verilog): Emit the 256-bit add / subtract / compare datapath. The `{cout,sum}` / `{borrow,diff}` use a 257-bit context so the carry / borrow out of the top limb is captured; `lt` is the borrow (a < b ⇔ the subtract underflows), `eq` the magnitude equality. - [fn emit_bigint_div_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bignum_rtl/fn.emit_bigint_div_testbench): Emit the divide block’s self-checking testbench: drive `bigint_div`, wait for `done`, and check quotient+remainder against the native 256-bit unsigned `a / b` / `a % b` reference over edge cases plus a 2000-pair random sweep. PASS iff all match. - [fn emit_bigint_div_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bignum_rtl/fn.emit_bigint_div_verilog): Emit the BigInt divide block — a sequential 256-bit UNSIGNED long divider (1 bit/cycle restoring, W cycles) computing q = a / b, r = a % b over magnitudes, b==0 -> q=r=0. The wide analogue of `shared_divider`’s magnitude core (no signed fixup — BigInt carries its sign separately); it feeds the numeric-tower BigInt divide the way `shared_divider` feeds the 32-bit ALU. 4,340 LUT / 1,548 FF on the ECP5-85K. Proven == the reference magnitude division by iverilog (`tb_bigint_div`) and == `numeric::mag_div`’s algorithm by the Rust model test below. - [fn emit_bigint_mul_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bignum_rtl/fn.emit_bigint_mul_testbench): Self-checking multiplier testbench: N (a,b) 64-bit, compare `prod` against `(a*b)` 128-bit. - [fn emit_bigint_mul_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bignum_rtl/fn.emit_bigint_mul_verilog): Emit the 64×64→128 limb multiplier (the partial product `mag_mul` accumulates). - [fn limb_add](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bignum_rtl/fn.limb_add): The software limb-add — a faithful mirror of `logicaffeine_base::numeric::mag_add` (little-endian u64 limbs, u128 carry): the low `LIMBS` sum limbs and the carry-out. - [fn limb_lt](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bignum_rtl/fn.limb_lt): Unsigned magnitude compare — mirror of `mag_cmp` (most-significant limb dominates). - [fn limb_mul](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bignum_rtl/fn.limb_mul): The limb multiply `mag_mul` iterates: one 64×64→128 partial product. - [fn limb_sub](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bignum_rtl/fn.limb_sub): The software limb-subtract — mirror of `mag_sub`’s borrow chain, but total (defined for every a, b): the low `LIMBS` difference limbs and the borrow-out (`1` iff a < b, i.e. the subtraction underflowed). When `borrow == 0` the difference equals `mag_sub(a, b)`. - [fn wdiv256](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bignum_rtl/fn.wdiv256): The unsigned quotient `a / b` over 256-bit magnitudes — binary long division (b==0 → 0), the reference for `bigint_div`’s restoring loop; the soft-core’s `BigIntWide` Div routes to that block. - [fn wmul256](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bignum_rtl/fn.wmul256): The low 256 bits of `a * b` — schoolbook over `LIMBS` limbs, carries past the top limb dropped (the wraparound a fixed 256-bit datapath produces). This is `bigint_mul` (64×64) composed with the proven `bigint_alu` carry-adds; the reference for the soft-core’s `BigIntWide` Mul. ## logicaffeine_compile::codegen_sva::bitblast Bit-blasting: `BoundedExpr` datapath (bitvector) operations → boolean `ProofExpr`. - [struct BlastSize](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/struct.BlastSize): The cost of turning one blasted obligation into a `ProofExpr`. - [struct BlastWork](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/struct.BlastWork): ★ THE BLASTER’S WORK, COUNTED — not timed. What a blast costs is three walks: the datapath expression it is handed (every node blasted once — a node blasted twice doubles the work per level above it), the gates it allocates (no gate is shared by value, so every allocation is a gate), and the memoised walk that prices the result (every gate visited once per edge into it — a walk that forgot its memo walks the tree). Each is a count a lock can bound by the size of what it walks, and none of them moves when the machine is busy. - [struct Pred](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/struct.Pred): A blasted PREDICATE — one bit of the shared gate DAG. - [struct Word](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/struct.Word): A blasted datapath VALUE — its bits, LSB-first, in the shared gate DAG. Cloning is a refcount bump per bit, never a copy of the circuit. - [enum BlastRefusal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/enum.BlastRefusal): Why a bit-blast produced no formula. - [const BLAST_BUDGET_NODES](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/constant.BLAST_BUDGET_NODES): How many `ProofExpr` nodes we are willing to materialise for ONE bit-blasted obligation. - [fn assert_not](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.assert_not): Assert `¬p` into `cnf` — the refutation obligation for a miter, clausified STRAIGHT FROM THE GATE DAG. Emits exactly the clauses `Cnf::assert(&Not(pred_to_proof(p)))` emits, in the same order, over the same variables; it just never builds the tree to read them off. - [fn blast_pred](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.blast_pred): Blast a boolean-VALUED `BoundedExpr` into the shared DAG. - [fn blast_size](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.blast_size): What blasting `e` costs — gates allocated vs. `ProofExpr` nodes a materialisation would hold — without materialising it. `None` when `e` has no circuit. The instrument the budget reads, and the one a lock reads to prove the blast stays linear in the datapath. - [fn blast_word](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.blast_word): Blast a bitvector-VALUED `BoundedExpr` into the shared DAG — the bridge for a caller that still speaks the tree form. - [fn blast_work](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.blast_work): Run `f` and return what it returns with the blaster work it did on this thread. - [fn lower_bool](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.lower_bool): Lower a boolean-VALUED datapath comparison to a `ProofExpr`, or `None` if it has no circuit or its materialisation is over `BLAST_BUDGET_NODES`. Use `lower_bool_bounded` when the caller must tell those two apart by name. - [fn lower_bool_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.lower_bool_bounded): `lower_bool` with the refusal NAMED. The circuit is built in the shared DAG and PRICED before anything is materialised, so an obligation past the budget costs the DAG — never the tree, and never the allocator. - [fn lower_bool_within](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.lower_bool_within): `lower_bool_bounded` against an EXPLICIT ceiling. The production ceiling is `BLAST_BUDGET_NODES`; a caller passing its own is how a lock proves the guard is live code — shrink the ceiling and an obligation that certifies must come back `Budget`, with the same arithmetic, not a special case. - [fn pred_size](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.pred_size): What this predicate’s circuit costs — gates allocated vs. the `ProofExpr` tree a materialisation would hold. The instrument a budget reads. - [fn pred_to_proof](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.pred_to_proof): Materialise a predicate’s `ProofExpr` tree. The escape hatch for a consumer that genuinely needs the tree (an SMT printer, a `ProofExpr`-shaped prover call) — and the thing every path that only wants a CNF must NOT call, because the tree is exponentially larger than the circuit. - [fn word_binary](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.word_binary): One of the width-preserving binary circuits (`And..AShr`, and unary `Not` on `a`). `None` when the widths disagree or the op is boolean-valued — use `word_compare` for those. - [fn word_compare](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.word_compare): One of the boolean-valued comparisons (`Eq`, `ULt`, `SLt`). `None` for a value-producing op or a width mismatch. - [fn word_const](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.word_const): A constant word, truncated to `width`. - [fn word_select](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.word_select): The mux tile: `cond ? t : e`, bit by bit — the same 1-bit select `BitVecIte` blasts through, so a predicated select built here and one built from a `BoundedExpr` are the same circuit. - [fn word_size](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.word_size): What a whole WORD’s circuit costs, counting the DAG the bits SHARE exactly once — an adder’s carry chain feeds every bit above it, so pricing the bits separately would count the same gates over and over. The instrument a datapath budget reads before a miter exists. - [fn word_var](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.word_var): A named input word: the bits `name#0 .. name#(width-1)`, the same signal spelling `blast_word` gives a `BitVecVar` — so a circuit built here and one blasted from a `BoundedExpr` share a variable namespace and can be mitered against each other. - [fn words_equal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/bitblast/fn.words_equal): The miter: `a == b` over every bit. `None` on a width mismatch. ## logicaffeine_compile::codegen_sva::block_engine_rtl block_engine_rtl — Stage 5 of the self-synthesizing bytecode XPU: the on-chip EXECUTE engine for a decoded block. Stage 4’s reconfigurable fabric runs a block’s certified SPATIAL placement (host-computed). This engine takes a block’s DECODED OPS DIRECTLY — no host placement step — and runs them on a universal reconfigurable datapath: one hardware array executes ANY bounded straight-line block by loading its op list as config. This is the unit the LGB1 decoder feeds: bytecode → ops → this engine → result, all on-chip. - [struct BlockConfig](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/block_engine_rtl/struct.BlockConfig): A decoded block transcribed into the execute engine’s config: one 32-bit control word per cell (op + the two operand sources) plus two 64-bit constant slots per cell, and `result` (which cell’s value is the block result). - [fn emit_block_engine_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/block_engine_rtl/fn.emit_block_engine_testbench): A self-checking testbench: drive each input vector, compare `result` to the VM oracle in `bexec_{name}_{pin,eout}.hex` (the engine loads its config from `bexec_{name}_{ctrl,ac,bc,res}.hex`). - [fn emit_block_engine_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/block_engine_rtl/fn.emit_block_engine_verilog): Emit the universal block execute engine: a `k`-cell reconfigurable datapath over `n_in` inputs. Each cell decodes its control word into an op + two operand selects (input / constant / earlier cell) and computes combinationally; loading a decoded block’s op list runs it. Config is read once via `$readmemh`. - [fn serialize_block](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/block_engine_rtl/fn.serialize_block): Transcribe a decoded block (`FabricOp` list + result index) into the engine’s config, padded to `k` cells (unused cells are inert — their value is never referenced). ## logicaffeine_compile::codegen_sva::caravel_project A Caravel user project as data. - [struct CaravelProject](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/caravel_project/struct.CaravelProject): One user project on the Caravel harness. - [enum CaravelProjectUnplaceable](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/caravel_project/enum.CaravelProjectUnplaceable): Why a project cannot be hardened as described. - [const CARAVEL_PROJECTS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/caravel_project/constant.CARAVEL_PROJECTS) - [const DRAM_PROJECT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/caravel_project/constant.DRAM_PROJECT): The DRAM command-stream executor behind a Wishbone target: the project submitted and precheck-passed first. Every path is the one its evidence was recorded under. - [const WPE_PROJECT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/caravel_project/constant.WPE_PROJECT): The whole-program engine (`wpe_caravel`): its UART and its PSRAM on user GPIOs, clocked on `user_clock2` at the clock its UART bit period was derived from, faster than the chip signs its core clock for. Its ports are held to the harness’s minimum input delays (`flow_config::vehicle_macro_sdc`), so its hold margin is OpenLane’s placement default, 0.1 ns: the 0.7 ns the command player carries buffered 35,656 of the engine’s paths. ## logicaffeine_compile::codegen_sva::caravel_rtl caravel_rtl — the Infinichip command player wrapped as an efabless Caravel user macro, the step that makes it literally shuttle-integratable. - [fn emit_dram_executor_wb_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/caravel_rtl/fn.emit_dram_executor_wb_testbench): A self-checking Wishbone testbench: the “management SoC” writes a delta-0 plan word (op=1, bank=3, row=7) over Wishbone, strobes launch, and asserts the certified FSM issues that exact command — observed on `la_data_out`. Prints PASS/FAIL; no external vectors. - [fn emit_dram_executor_wb_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/caravel_rtl/fn.emit_dram_executor_wb_verilog): Emit the SELF-CONTAINED user macro: the certified `dram_executor` + the `dram_executor_wb` Wishbone front end. This is the design hardened + golden-DRC’d + dropped into Caravel’s golden `user_project_wrapper` for a shuttle submission. - [fn emit_dram_user_project_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/caravel_rtl/fn.emit_dram_user_project_verilog): Emit the SELF-CONTAINED full-interface user macro: `dram_executor` + `dram_executor_wb` core + `dram_user_project`. This is the macro hardened (with power pins + tap insertion) and placed as `mprj` inside the golden `user_project_wrapper` for a shuttle submission. - [fn emit_user_project_wrapper_around](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/caravel_rtl/fn.emit_user_project_wrapper_around): Emit a `user_project_wrapper` — the efabless golden Caravel wrapper interface, verbatim ports, instantiating the full-interface user macro `macro_module` as `mprj` and connecting EVERY wrapper pin 1:1 (the passthrough that makes the placed-and-routed wrapper LVS-clean). `carries` names what the macro holds, for the header. - [fn emit_user_project_wrapper_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/caravel_rtl/fn.emit_user_project_wrapper_verilog): Emit our `user_project_wrapper` for the DRAM command player: `emit_user_project_wrapper_around` `dram_user_project`. ## logicaffeine_compile::codegen_sva::cdc Clock Domain Crossing (CDC) Formal Verification - [struct CdcClockDomain](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/cdc/struct.CdcClockDomain): A clock domain for CDC analysis. - [struct CdcCrossing](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/cdc/struct.CdcCrossing): A signal crossing between clock domains. - [struct CdcReport](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/cdc/struct.CdcReport): CDC analysis report. - [struct CdcViolation](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/cdc/struct.CdcViolation): A CDC violation. - [enum CdcPattern](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/cdc/enum.CdcPattern): CDC synchronization pattern. - [enum CdcViolationType](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/cdc/enum.CdcViolationType): CDC violation type. - [fn analyze_cdc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/cdc/fn.analyze_cdc): Analyze an RTL module for clock domain crossing issues. - [fn cdc_sva_properties](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/cdc/fn.cdc_sva_properties): Generate SVA properties for CDC verification. ## logicaffeine_compile::codegen_sva::chan_rtl chan_rtl — the deterministic channel in silicon: a bounded FIFO. - [fn emit_chan_fifo_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chan_rtl/fn.emit_chan_fifo_testbench): A self-checking testbench: replay an N-step (push, pop, din) trace and compare the DUT’s pop sequence against the software channel oracle from `chan_{ctrl,din,pops}.hex`. - [fn emit_chan_fifo_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chan_rtl/fn.emit_chan_fifo_verilog): Emit the bounded sync FIFO: combinational front-read (`dout`), combinational `full`/`empty`/ handshake, registered pointers + count. `pushed = push & !full`, `popped = pop & !empty`. ## logicaffeine_compile::codegen_sva::chip_protocol The chips’ byte protocol on the UART, defined once. - [struct ResultFrame](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/struct.ResultFrame): The result frame that closes a run. - [enum ChipValue](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/enum.ChipValue): A value as the protocol carries it. - [enum FrameError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/enum.FrameError): Why bytes are not a record. - [enum HostCall](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/enum.HostCall): The program’s operations that reach the outside world through the host. The host services each with the one relay client (`logicaffeine_system::relay`); the chip never frames the relay protocol itself. - [enum Record](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/enum.Record): One record of the exchange. - [const FRAME_END](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/constant.FRAME_END): The result frame of a run that finished. - [const FRAME_END_CALL_STACK](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/constant.FRAME_END_CALL_STACK): The result frame of a run whose call stack overflowed the engine’s frame stack. - [const FRAME_END_HEAP](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/constant.FRAME_END_HEAP): The result frame of a run whose heap overflowed the engine’s heap. - [const FRAME_SYNC](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/constant.FRAME_SYNC): The first byte of the result frame. - [const IMAGE_GO](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/constant.IMAGE_GO): The program image is complete; the engine starts the run. - [const IMAGE_HEAP](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/constant.IMAGE_HEAP): The program image’s heap pre-load segment follows. - [const REC_CALL](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/constant.REC_CALL): A host call’s request. - [const REC_REPLY](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/constant.REC_REPLY): The host’s reply to a host call. - [const REC_SHOW](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/constant.REC_SHOW): A `Show` record. - [const TAGS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/constant.TAGS): Every value tag, in code order. - [const TAG_BOOL](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/constant.TAG_BOOL): A Bool, carried as 0 or 1. - [const TAG_FLOAT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/constant.TAG_FLOAT): A Real: its IEEE-754 bit pattern, rendered with the language’s `fmt_f64`. - [const TAG_INT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/constant.TAG_INT): A signed 64-bit Int. - [const TAG_TEXT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/constant.TAG_TEXT): A Text. On the engine, the shown value is a heap pointer to a char-list `[len, byte0..]`; on the wire, the length and the bytes. - [const TAG_WORD32](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/constant.TAG_WORD32): A `Word32`, rendered unsigned. - [fn fill_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/fn.fill_verilog): Fill a Verilog template’s protocol bytes from this table: `__V___` becomes the byte as a Verilog literal (`8'hA7`), `__X___` the hex a comment quotes (`0xA7`). Panics if a placeholder names no protocol byte. - [fn table_json](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/chip_protocol/fn.table_json): The whole table as JSON, for a host that is not Rust: `scripts/logos-chip.py` reads it from `chip_host --table` rather than restating a byte of it. ## logicaffeine_compile::codegen_sva::choreography The control plane of a spatial pipeline: the tokens and credits that make a metapipeline run, and the buffer depth that follows from them. - [struct Channel](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/choreography/struct.Channel): A credit-controlled channel between two stages. - [struct Choreography](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/choreography/struct.Choreography): The synthesized control plane of a metapipeline. - [struct ControlNet](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/choreography/struct.ControlNet): One control net of a channel. - [struct CreditRun](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/choreography/struct.CreditRun): What a credit-flow run did. - [enum ControlKind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/choreography/enum.ControlKind): Which way a control net runs. - [fn credit_depth](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/choreography/fn.credit_depth): Credits a channel needs to sustain one item every `ii` cycles: the loop’s bandwidth-delay product. A channel always holds at least one credit — without one nothing can be sent at all. - [fn eval_credit_flow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/choreography/fn.eval_credit_flow): Run the pipeline as a cycle-exact token/credit machine for `iters` iterations. - [fn synthesize](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/choreography/fn.synthesize): Synthesize the control plane of `mp` given the mesh distance of each edge (`hops[i]` for `mp.edges[i]`). Forward latency is producing the item plus carrying it; backward latency is the credit’s return trip. ## logicaffeine_compile::codegen_sva::ci CI/CD Integration — SARIF Output for GitHub Security Tab - [struct CiConfig](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ci/struct.CiConfig): CI verification configuration. - [struct CiReport](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ci/struct.CiReport): CI verification report with SARIF output. - [struct PropertyResult](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ci/struct.PropertyResult): A single property verification result. - [fn exit_code](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ci/fn.exit_code): Compute exit code: 0 if all pass, 1 if any fail. - [fn generate_github_actions_template](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ci/fn.generate_github_actions_template): Generate a GitHub Actions workflow template for Logicaffeine verification. - [fn run_ci_verification](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ci/fn.run_ci_verification): Run CI verification on spec and RTL files. ## logicaffeine_compile::codegen_sva::computedram_rtl computedram_rtl — Phase 4: the in-DRAM compute path proven end-to-end in simulation. - [fn emit_computedram_harness_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/computedram_rtl/fn.emit_computedram_harness_testbench): Emit `tb_computedram` — the harness (the fabric’s role): preload `src` with `pattern`, replay the delta-encoded ComputeDRAM stream (`cdram_plan.hex`) through `dram_executor` into the device, then read `dst` and assert it equals `pattern` (the RowClone oracle). `nwords` = stream length. - [fn emit_computedram_model_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/computedram_rtl/fn.emit_computedram_model_verilog): Emit `computedram_model` — the behavioral ComputeDRAM device. On the ACT→PRE→ACT compute cadence it performs RowClone (2 activations: `dst := src`); on ACT→PRE→ACT→PRE→ACT (3 activations) it performs the sense-amp triple-row MAJORITY over the ORIGINAL operand values, writing it to all three rows — so bitwise AND = MAJ(a,b,0) and OR = MAJ(a,b,1). Snapshots the originals so the tentative 2-row clone can be corrected by a 3rd activation. A RD/WR closes the cadence. Preload/read ports for the harness (which plays the fabric’s orchestration role). - [fn emit_computedram_reduce_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/computedram_rtl/fn.emit_computedram_reduce_testbench): Emit `tb_computedram_reduce` — proves in-DRAM bitwise AND and OR via triple-row activation. Preloads operands (`a=aval, b=bval, zero=0` for AND with a 0 control; `a2=aval, b2=bval, ones=~0` for OR with a 1 control), replays the concatenated `Maj` streams from `cdram_reduce.hex`, and asserts the majority result: `mem[a] == aval & bval` (AND = MAJ(a,b,0)) and `mem[a2] == aval | bval` (OR = MAJ(a,b,1)). ## logicaffeine_compile::codegen_sva::controller_gen Designer → certified controller: turn a synthesized `PhasePlan` into a Verilog phase-FSM and let the existing RTL pipeline (`parse_transition_system` → `prove_invariant`) certify it. - [fn generate_controller](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/controller_gen/fn.generate_controller): Generate a synthesizable Verilog controller (one 1-bit `mvN` register per movement, a `phase` counter) whose conflict-freedom is provable by `prove_invariant`. ## logicaffeine_compile::codegen_sva::coproc_core coproc_core — the coprocessors, ISSUED as CPU instructions. - [const COPROC_A](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coproc_core/constant.COPROC_A): Initial register-file operands (R0, R1); the rest reset to zero. Chosen with A > B (so the subtract has no underflow) and full-width carry/borrow activity. - [const COPROC_B](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coproc_core/constant.COPROC_B) - [const COPROC_PROGRAM](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coproc_core/constant.COPROC_PROGRAM): The demo program: issue each coprocessor op once, retire to a distinct register, then halt. - [fn emit_coproc_core_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coproc_core/fn.emit_coproc_core_testbench): Self-checking testbench: run the core to halt, read back R2..R5, compare to the oracle from `coproc_exp.hex` (the Rust model’s final register file). Prints PASS/FAIL. - [fn emit_coproc_core_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coproc_core/fn.emit_coproc_core_verilog): Emit the issuing core: PC + combinational ROM + 8×256-bit register file + decode/issue/retire, instantiating the real `bigint_alu` / `bigint_mul` / `crdt_merge` blocks as functional units. - [fn run_core](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coproc_core/fn.run_core): A cycle-faithful Rust MODEL of the core: fetch → decode → issue → retire, over the same coprocessor semantics the RTL instantiates. Returns the final 8×256-bit register file. The iverilog testbench proves the RTL reproduces exactly this. - [type Instr](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coproc_core/type.Instr): One decoded instruction: `(op, rd, rs, rt)`. ## logicaffeine_compile::codegen_sva::coproc_soc coproc_soc — the ULX3S-flashable SoC wrapper around `coproc_core`. - [const RESULT_REGS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coproc_soc/constant.RESULT_REGS): The result registers streamed out, in order: R2=BADD, R3=BSUB, R4=BMUL, R5=CMERGE. - [fn emit_coproc_soc_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coproc_soc/fn.emit_coproc_soc_testbench): Emit the self-checking testbench. The expected result registers are DERIVED from `run_core` (not hand-typed): the tb decodes the UART TX stream, reconstructs the sync byte + 128 payload bytes, and checks each MSB-first byte against the model’s retired R2..R5. PASS iff every byte matches — the software≡RTL proof over the serial framing. - [fn emit_coproc_soc_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coproc_soc/fn.emit_coproc_soc_verilog): Emit the flashable SoC wrapper: `coproc_core` + a 7-state UART-TX readout FSM. External pins (`clk`, `rst`, `uart_tx`, `led[7:0]`) fit the ULX3S; `CLKS_PER_BIT` = clk_hz / baud (217 for 25 MHz / 115200). The RTL is operand-independent — the core carries the operands internally. - [fn emit_ulx3s_coproc_lpf](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coproc_soc/fn.emit_ulx3s_coproc_lpf): Emit the ULX3S (LFE5U-85F caBGA381) board constraints: 25 MHz clock (G2), reset = FIRE1 (R1), UART TX → FTDI RXD (L4), 8 LEDs. Sites from the board’s `ulx3s_v20.lpf`. - [fn expected_stream](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coproc_soc/fn.expected_stream): The 129-byte serial frame the SoC streams: a 0xA5 sync byte, then R2..R5 (256-bit each), most-significant byte first. This is exactly what `scripts/coproc-host.py` reconstructs and what `tb_coproc_soc.v` samples off the wire — the single definition of the readout order. ## logicaffeine_compile::codegen_sva::coverage Specification Coverage Metrics - [struct SpecCoverage](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coverage/struct.SpecCoverage): Coverage metrics for a specification. - [fn compute_coverage](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/coverage/fn.compute_coverage): Compute specification coverage given a KG and a set of covered signal names. ## logicaffeine_compile::codegen_sva::crdt_rtl crdt_rtl — the CRDT merge unit in silicon. - [fn emit_crdt_merge_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/crdt_rtl/fn.emit_crdt_merge_testbench): A self-checking testbench: apply N (a,b) vectors and compare `merged`/`value` against the oracle from `crdt_{a,b,m}.hex` (computed in Rust). Prints PASS/FAIL. - [fn emit_crdt_merge_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/crdt_rtl/fn.emit_crdt_merge_verilog): Emit the combinational G-Counter merge unit: `merged[i] = max(a[i], b[i])` across the four 32-bit replica lanes, plus `value = sum(merged)` (34 bits: 32 + ceil(log2 4)). - [fn emit_dpu_ingest_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/crdt_rtl/fn.emit_dpu_ingest_verilog): Emit the DPU near-data ingest tile: the same per-lane join as `crdt_merge`, but wrapped in a clocked accumulator — on each `posedge clk` with `in_valid`, the state folds the arriving beat into the running join (`acc <= merge(acc, in_state)`); `rst` clears it. This is the sequential merge-on-ingest primitive a DPU runs at the data edge: because the join is commutative/associative/idempotent (certified in `the_crdt_convergence_order_is_a_total_order_proven_by_our_sat`), folding a stream through it is order-invariant — correct even when the controller delivers reads out of logical order. Unlike the combinational `crdt_merge` unit, this has genuine register-to-register paths, so it is the block that carries meaning through STA/signoff. - [fn merge_lane](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/crdt_rtl/fn.merge_lane): The join for one lane — per-replica `max`, exactly `GCounter::merge`. ## logicaffeine_compile::codegen_sva::dae dae — Decoupled Access-Execute for the spatial fabric (`FabricTarget::agu`). - [struct DaeSchedule](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dae/struct.DaeSchedule): A decoupled schedule: the SAME cells re-laid-out as `[agu lane .. | exec lane ..]` (AGU cells first), with every `Src::Val` remapped to the new positions. `agu_len` cells form the address-generation lane; the rest are the exec lane (compute + memory tiles, memory ops preserving program order). - [fn coupled_critical_depth](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dae/fn.coupled_critical_depth): The coupled body’s critical-path depth: the longest dependency chain feeding `result` (every operand counts — address arithmetic sits on the compute path). - [fn decouple_access](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dae/fn.decouple_access): Decouple a straight-line body into an AGU lane + exec lane. The AGU lane is the set of cells that transitively feed a memory tile’s address AND whose dependency cone never crosses a load (untainted) — the address arithmetic that can be precomputed off the compute path. Everything else (compute + the memory tiles + any pointer-chase address whose cone reads memory) stays in the exec lane, in program order. The two are concatenated AGU-first with every `Src::Val` remapped, so the layout is a valid topological reordering of the SAME cells — semantics-preserving by construction. - [fn emit_dae_stateful_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dae/fn.emit_dae_stateful_verilog): Emit a decoupled schedule that MUTATES the heap (`HeapWrite`/`HeapAlloc`, not just loads) as a SEQUENCED synthesizable datapath: the decoupled layout (AGU cells hoisted first) is run on the proven state-plane micro-sequencer (`emit_state_plane_verilog`), which commits heap writes in program order over one shared heap + a bump allocator. Module `state_{name}` (clk/rst/inN/result/done). Bit-identical to `eval_dae` (≡ the coupled body ≡ the VM); proven under iverilog by `dae_rtl_lock`. Distinct from the combinational load-only `emit_dae_verilog`, which realizes the parallel AGU lane for streaming reads. - [fn emit_dae_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dae/fn.emit_dae_testbench): A self-checking combinational testbench for `dae_{name}`: drive `n` input vectors (each `n_in` words) from `dae_{name}_in.hex`, compare the settled `result` against the `eval_dae` oracle in `dae_{name}_out.hex`. - [fn emit_dae_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dae/fn.emit_dae_verilog): Emit a decoupled schedule as COMBINATIONAL Verilog: the AGU lane (address arithmetic) and the exec lane (compute + loads) are emitted as two labelled regions, the loads reading a `depth`-word heap. Bit-identical to `eval_dae` (out-of-range loads read 0, matching the model) — proven under iverilog by `dae_rtl_lock`. LOAD-ONLY: `HeapWrite`/`HeapAlloc`/`Func` are the sequenced-state follow-on and panic here (the honest boundary), so the corpus is streaming reads with computed addresses — the canonical DAE case. - [fn eval_dae](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dae/fn.eval_dae): Evaluate a decoupled schedule against `inputs` + a shared `heap`, exactly as the coupled body would. Reuses the decision-fabric heap reduction over the re-laid-out cells — so agreement with the coupled eval is the semantics-preservation certificate. - [fn is_heap_cell](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dae/fn.is_heap_cell): True iff the cell touches the state plane (a load/store/alloc) — the side-effecting tiles the exec lane must keep in program order. - [fn schedule_for_target](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dae/fn.schedule_for_target): Schedule a body FOR a described target: decouple its address lane iff the target carries an AGU (`target.agu`), else leave it coupled (identity). This is the descriptor knob — a fabric without an AGU cannot exploit decoupling, so the transform only fires when the target can realize it. Either way the schedule is semantics-preserving (a proven reordering, or the identity). ## logicaffeine_compile::codegen_sva::ddr2_dfi ddr2_dfi — `ddr2_dfi_ctrl`, the LOGOS DDR2 controller at the DFI 1:2 rate: a 64-bit native request port (a word a command, write data on its own stream, read data back in request order) and two DFI phases a system clock, the interface LiteDRAM’s controller presents to its PHY, so either drives the same PHY. - [const DFI_CTRL_QUEUE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_dfi/constant.DFI_CTRL_QUEUE): The requests `ddr2_dfi_ctrl` holds: the window its bank lookahead sees. - [fn emit_ddr2_dfi_controller_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_dfi/fn.emit_ddr2_dfi_controller_verilog): Emit `ddr2_dfi_ctrl` for the clocked part `t`: every rule of `t` baked in, a `DFI_CTRL_QUEUE`-deep queue. ## logicaffeine_compile::codegen_sva::ddr2_jedec ddr2_jedec — a DDR2 part’s datasheet timing at one clock, and the JESD79-2 command rules a bus trace is held to. - [struct BusCmd](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_jedec/struct.BusCmd): One command as the bus carried it: the clock it was sampled on, the command its pins encode, the bank address and the address bus (the row for ACTIVATE, the column and A10 for READ and WRITE, A10 alone for PRECHARGE). - [struct BusFacts](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_jedec/struct.BusFacts): What a legal trace put on the bus. `end` is the clock after its last command or its last data beat, whichever is later; `data_cycles` the clocks its bursts held the data bus. - [struct CasEvent](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_jedec/struct.CasEvent): A READ or WRITE, with the row its bank had open and the clock its first data beat occupies the bus. - [struct Ddr2Grade](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_jedec/struct.Ddr2Grade): A DDR2 speed grade: its geometry, the CAS latency each clock period allows, and its datasheet minimums (and the tRAS and tREFI maximums), in picoseconds unless named in clocks. - [struct Ddr2Timing](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_jedec/struct.Ddr2Timing): A grade clocked: every rule in whole clocks. `wl` is `cl − 1`, `trpa` the precharge-all period. - [struct Violation](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_jedec/struct.Violation): The first broken rule: the index of the command that broke it (the trace’s length when the trace’s end did), the clock, the rule’s name, and the earlier command or limit it was measured against. - [const REFRESH_POSTPONE_MAX](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_jedec/constant.REFRESH_POSTPONE_MAX): The REFRESH commands JESD79-2 lets a controller postpone: by any clock t it owes at least floor(t / tREFI) − this. - [fn check_bus](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_jedec/fn.check_bus): Hold `trace` to the JESD79-2 command rules of `t`. NOP and DESELECT entries carry no command and are passed over; every other command must come on a later clock than the one before it. - [fn command_of_pins](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_jedec/fn.command_of_pins): The command on the bus for `(CS#, RAS#, CAS#, WE#)` by the JEDEC truth table, `None` for the one reserved pattern (RAS# and CAS# high, WE# low) or a level that is not 0 or 1. ## logicaffeine_compile::codegen_sva::ddr2_phy ddr2_phy — a full custom hand-rolled DDR2 controller + PHY for the Nexys A7-100T’s on-board Micron MT47H64M16 (1 Gb, x16, 8 banks, DDR2-800). This is Phase 1 of the DRAM-into-Compute campaign: total ownership in the openXC7 flow (no vendor MIG), tied directly to the `dram_executor` command engine (`super::dram`), so the SAME command stream that drives the JEDEC-legal schedule also drives the deliberately-illegal ComputeDRAM cadences. - [enum Ddr2Cmd](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/enum.Ddr2Cmd): A DDR2 command (JEDEC truth table over {CS#, RAS#, CAS#, WE#}, with CKE held high). - [enum InitStep](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/enum.InitStep): One step of the DDR2 power-up init sequence. - [enum ModeReg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/enum.ModeReg): A DDR2 mode register, identified by its `BA[1:0]` selector. - [const EMR1_DLL_ENABLE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/constant.EMR1_DLL_ENABLE): EMR1 with the DLL ENABLED (A0 = 0), full drive, ODT off, AL = 0, OCD exit — the first EMR1. - [const EMR1_OCD_DEFAULT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/constant.EMR1_OCD_DEFAULT): EMR1 OCD calibration DEFAULT (A9:A7 = 111). - [const EMR1_OCD_EXIT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/constant.EMR1_OCD_EXIT): EMR1 OCD calibration EXIT (A9:A7 = 000), DLL still enabled. - [fn ddr2_init_sequence](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/fn.ddr2_init_sequence): The JEDEC DDR2 power-up init sequence for this part, as data. `cke_low_cycles` is the ≥200 µs power-up hold expressed in controller cycles (a deployment parameter of the chosen clock). - [fn ddr2_pins](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/fn.ddr2_pins): The `(cs_n, ras_n, cas_n, we_n)` pin levels for a DDR2 command — the JEDEC DDR2 command truth table. This is the SINGLE SOURCE OF TRUTH the Verilog encoder is generated from. - [fn emit_ddr2_bank_model_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/fn.emit_ddr2_bank_model_verilog): Emit `ddr2_bank_model` — a behavioral DDR2 array that stores/returns data (CL read latency) AND enforces tRCD/tRAS/tRP/tWR, raising `model_error` on any violation (the round-trip checker). - [fn emit_ddr2_cmd_encoder_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/fn.emit_ddr2_cmd_encoder_testbench): A self-checking testbench for `ddr2_cmd_encoder`: drives every op with issue = 0 and issue = 1 and asserts the pins equal `ddr2_pins` (expectations GENERATED from the same truth table). PASS/FAIL. - [fn emit_ddr2_command_encoder_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/fn.emit_ddr2_command_encoder_verilog): Emit the combinational `ddr2_cmd_encoder` — op field + `issue` → DDR2 command pins. When `issue` is low the bus holds NOP (CS# low, RAS#/CAS#/WE# high). The `case` arms are GENERATED from `ddr2_pins`, so the netlist is by-construction consistent with the model/oracle. - [fn emit_ddr2_controller_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/fn.emit_ddr2_controller_testbench): Emit `tb_ddr2_ctrl` — writes `n_words` (distinct bank/col addresses), reads them back, and asserts each read equals the written data with no `model_error`. The access pattern is generated here. - [fn emit_ddr2_controller_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/fn.emit_ddr2_controller_verilog): Emit `ddr2_ctrl` — the request-driven DDR2 controller FSM (timings baked from the table). - [fn emit_ddr2_init_fsm_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/fn.emit_ddr2_init_fsm_verilog): Emit `ddr2_init_fsm` — a ROM-driven power-up sequencer. The ROM is GENERATED from `ddr2_init_sequence`; the FSM drives `{cke, cs_n, ras_n, cas_n, we_n, ba, a}` per entry, waits its cycle count, advances, and latches `init_done`. (Behavioral iverilog validation lands with the controller-integration brick; this brick pins the ROM to the JEDEC spec.) - [fn emit_ddr2_init_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/fn.emit_ddr2_init_testbench): A behavioral testbench for `ddr2_init_fsm`: a bus monitor records each isolated real command (NOP/DESELECT skipped) the FSM issues during power-up, and asserts the recorded log equals the JEDEC command sequence (generated from `ddr2_init_sequence`) and that `init_done` asserts. - [fn emit_transaction](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/fn.emit_transaction): Emit the controller’s per-request command sequence for one closed-page DDR2 access. - [fn executor_op_to_cmd](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/fn.executor_op_to_cmd): Map a `dram_executor` op field (0=ACT 1=RD 2=WR 3=PRE 4=REFpb) to its DDR2 command. Returns `None` for op codes outside the executor’s issued set. - [fn init_rom_word](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/fn.init_rom_word): Pack an init step into the 44-bit `ddr2_init_fsm` ROM word `{cke, cs_n, ras_n, cas_n, we_n, ba[1:0], a[12:0], wait[23:0]}` — the SINGLE encoding shared by the emitter and the drift lock, with the command pins taken from `ddr2_pins`. - [fn mr_opcode](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_phy/fn.mr_opcode): Encode the Mode Register (BA = 00) opcode from the timing table: burst length (A2:A0), sequential burst type (A3 = 0), CAS latency (A6:A4, == tRCD on the 5-5-5 grade), DLL reset (A8), and write recovery WR-1 (A11:A9). ## logicaffeine_compile::codegen_sva::ddr2_traffic ddr2_traffic — the K7 traffic: one stream of 64-bit words that every DDR2 controller of the comparative bench writes to the same part and reads back, the device and testbenches it runs on, and the judgement of a run’s log. - [struct Controller](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/struct.Controller): A controller the K7 traffic gate drives: its name in the K7 design table, the burst length its mode register sets, and how its requests carry a word. - [struct Delivery](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/struct.Delivery): A word the controller delivered back. - [struct Interface](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/struct.Interface): How a controller’s requests carry a word: in `parts` requests, part p at the word’s first column plus p × `cols_per_part`. - [struct Judgement](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/struct.Judgement): What a run measured. `stream_cycles` runs from the first accepted request to the last delivered word; `payload_cycles` is what the stream needs of an x16 DDR bus (two clocks a word, each way); `bus_span` runs from the first command to the last beat; `row_hits` counts column commands that found their row already open by an earlier column command; the write and read latencies run from a request’s acceptance to the column command that served it; `read_service` from the presentation of a word’s first read request to the word’s delivery, and `read_bus` to the last beat of the word’s read data on the DRAM bus — the same span without any PHY’s pipeline. - [struct Log](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/struct.Log): A run’s log: the bus, the requests as presented and as accepted, the deliveries, and the closing line (its clock and the testbench’s error count). Clocks are DRAM clocks from the end of reset. - [struct Place](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/struct.Place): Where a word lives: its bank, its row, and the first of its four x16 columns. - [struct Request](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/struct.Request): A request the requester presented or the controller accepted: the clock, write or read, the word, and which part. - [struct Stats](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/struct.Stats): A latency distribution in DRAM clocks: count, extremes, nearest-rank median and 99th percentile, mean. - [struct Traffic](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/struct.Traffic): The stream: `words` words written in order, then read back in the same order, each read presented as soon as the controller took the one before, or for the probe `PROBE_EVERY` clocks after it was presented. - [enum Kind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/enum.Kind) - [enum Pattern](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/enum.Pattern) - [const K7_CONTROLLERS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/constant.K7_CONTROLLERS): LOGOS’s `ddr2_ctrl` (a 16-bit request port, BL8), LOGOS’s `ddr2_dfi_ctrl` and LiteDRAM’s controller (each a 64-bit native port, BL4 at 1:2). - [const K7_GRADE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/constant.K7_GRADE): The K7 part. - [const K7_TCK_PS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/constant.K7_TCK_PS): The K7 DRAM clock period: DDR2-400. - [const PROBE_EVERY](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/constant.PROBE_EVERY): The DRAM clocks between the probe’s reads: more than any K7 controller needs to serve one read with a refresh in its way, so each read meets the controller idle. - [const SCATTER_ROWS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/constant.SCATTER_ROWS): The rows of every bank the scattered stream draws its words from. - [fn emit_ddr2_ctrl_traffic_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/fn.emit_ddr2_ctrl_traffic_testbench): `tb_qor_dram` for `ddr2_ctrl`: the stream through its 16-bit request port, four requests a word (part p at column 4 × the column word + p), the device behind it at burst length `t.bl` with every beat but the addressed one masked. A request is presented as soon as the one before was taken; for the probe, a word’s first read waits until `Traffic::every` clocks after the word before’s, and the reads start two of those after the last write. It reads `words.hex` (`Traffic::rom`) and writes `dram.log` (`read_log`). - [fn emit_ddr2_device_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/fn.emit_ddr2_device_verilog): `ddr2_device`: the part as a testbench sees it through an ideal PHY. It keeps each bank’s open row and stores 16-bit columns for `ROWB` row-address bits; a WRITE takes its burst (with a per-beat mask, 1 = not written) on the command’s clock, a READ returns its burst CL clocks later, both in the sequential burst order that wraps within the burst’s aligned block. An ACT past the stored rows, or a column command to a bank with no open row, raises `model_error`. Bus timing is not its business: the log’s JEDEC checker holds the bus to the rules. - [fn emit_ddr2_dfi_ctrl_traffic_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/fn.emit_ddr2_dfi_ctrl_traffic_testbench): `tb_qor_dram` for `ddr2_dfi_ctrl`: LiteDRAM’s testbench with the LOGOS controller in `litedram_ctrl`’s place, on the same native port and DFI, against the same SDRAMPHYModel; it has no stream framing (first/last) and no read back-pressure, which LiteDRAM’s crossbar does not read either. - [fn emit_litedram_traffic_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/fn.emit_litedram_traffic_testbench): `tb_qor_dram` for LiteDRAM: the stream through the native port of `litedram_ctrl`, the controller exactly as the bench synthesises it, its DFI wired to `litedram_phy_model`, LiteDRAM’s own SDRAMPHYModel (both from `litedram_controller.py`); one command a word, write data offered for every accepted write in order, read data always accepted, reads presented as for `ddr2_ctrl`. The system clock runs at half the DRAM clock, and the log counts DRAM clocks: DFI phase p of system clock k is DRAM clock 2k + p, a request presented or accepted at system clock k is logged at 2k. It reads `words.hex` and writes `dram.log`. - [fn judge](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/fn.judge): Judge a run of `traffic` through a controller with request interface `iface`, its bus held to `t`. - [fn k7_controller](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/fn.k7_controller) - [fn k7_ddr2_ctrl_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/fn.k7_ddr2_ctrl_verilog): `ddr2_ctrl` as the K7 bench builds, synthesises and drives it: the LOGOS DDR2 controller at the K7 part’s table, burst length 8. - [fn k7_dfi_ctrl_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/fn.k7_dfi_ctrl_verilog): `ddr2_dfi_ctrl` as the K7 bench builds, synthesises and drives it: the LOGOS DFI 1:2 controller at the K7 part’s rules, burst length 4. - [fn k7_timing](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/fn.k7_timing): The K7 part clocked at the K7 operating point, burst length `bl`. - [fn place](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/fn.place): The place of word `w`: ROW_BANK_COL, the column word in the low eight bits, the bank above, the row above that. - [fn read_log](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/fn.read_log): Read a log: `C `, `P ` (presented), `Q ` (accepted), `D `, `END `; blank lines pass. - [fn word_value](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr2_traffic/fn.word_value): The value written to word `w`: SplitMix64’s output for `w`, a bijection, so every word’s value is its own. ## logicaffeine_compile::codegen_sva::ddr4_jedec ddr4_jedec — a DDR4 channel’s timing at its clock, the JESD79-4 command rules a trace is held to, and the in-order controller that turns line streams into commands on it. - [struct BusChecker](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/struct.BusChecker): The JESD79-4 rules of one channel, held over a trace one command at a time. - [struct Ddr4Facts](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/struct.Ddr4Facts): What a legal trace put on the channel: its commands by kind, the bursts that turned the data bus around, the clocks its bursts held the data bus, and the clock after its last data or command. - [struct Ddr4Grade](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/struct.Ddr4Grade): A DDR4 channel as its controller is configured: geometry, latencies and timing minimums (picoseconds unless named in clocks). - [struct Ddr4Timed](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/struct.Ddr4Timed): A command and the memory clock it issues on. - [struct Ddr4Timing](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/struct.Ddr4Timing): A channel clocked: every rule in whole memory clocks. - [struct Location](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/struct.Location): Where a line lives: bank group, bank within it, row, and the burst’s first column (a multiple of eight). - [struct Scheduler](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/struct.Scheduler): The controller model: lines in, commands out in clock order. - [enum Ddr4Cmd](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/enum.Ddr4Cmd): One command on the channel. `PreAll` precharges every bank; `Ref` is an all-bank refresh. - [const BL](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/constant.BL): Beats in a burst: the burst length is fixed at eight (MEM_DDR4_BL_ENUM DDR4_BL_BL8). - [const D5005_EMIF_IP](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/constant.D5005_EMIF_IP): Where `Ddr4Grade::D5005_EMIF` is read from. - [const LOGGED_KINDS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/constant.LOGGED_KINDS): Clocks a command kind is logged as by `verilog_model`: ACT, READ, WRITE, PRECHARGE, PRECHARGE ALL, REFRESH. - [const LOOKAHEAD](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/constant.LOOKAHEAD): Lines the controller model holds ahead of its column commands, whose rows it may open early. Modeled: the depth of the hard controller’s command queue is not in its configuration. - [const REFRESH_POSTPONE_MAX](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/constant.REFRESH_POSTPONE_MAX): The REFRESH commands JESD79-4 lets a controller owe, and the most it may pay ahead, in fixed 1x mode. - [const REFRESH_PULL_IN_MAX](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/constant.REFRESH_PULL_IN_MAX) - [fn check_bus](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/fn.check_bus): Hold `trace` to the JESD79-4 rules of `t`: the first violation, or what the trace put on the channel. - [fn locate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/fn.locate): A line (one burst) by the controller’s address order, chip select, row, bank, column, bank group from the most significant end (CTRL_DDR4_ADDR_ORDER_ENUM DDR4_CTRL_ADDR_ORDER_CS_R_B_C_BG): consecutive lines take the bank groups in turn, then the bursts of a row, then the banks, then the rows. Lines past the channel’s last wrap. - [fn measure](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/fn.measure): The controller’s trace for `streams` held to the rules as it is issued, never held whole: what it put on the channel, or the first rule it broke. - [fn schedule](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/fn.schedule): The controller’s trace for `streams` (byte addresses in one channel, `line_bytes` to a burst) at `LOOKAHEAD`. - [fn stream_lines](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/fn.stream_lines): The lines a stream touches, in its order, with its direction: every line any of its elements covers, a line that consecutive elements share once. - [fn verilog_model](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/ddr4_jedec/fn.verilog_model): A DDR4 channel behind an Avalon-MM slave for simulation, scheduled by this module’s controller model: every line a burst brings is issued as `Scheduler::line_at` issues it at the memory clock the slave takes it (four to a controller clock), a write’s data is stored as it is taken, and a read’s data, as the memory held it when the read was taken, returns in order `PIPE` controller clocks after the controller clock its burst leaves the data bus in. With `LOG` set it writes, to `_.log`, every line it schedules (`L line write arrive column`) and every command it places (`C clock kind group bank row-or-column`, the kind an index of `LOGGED_KINDS`). ## logicaffeine_compile::codegen_sva::decision_workload The HFT decision as a workload: its one LOGOS source, lowered to a combinational select-DAG by `emit_decision_fabric` (the decision fabric), and run as ordinary bytecode on the routable scalar core by the program here — the CPU twin of `decision_hft_realbist`. Both blocks decide over the same realistic input ranges, so their gate-level switching power per decision is one comparison. - [const DECIDE_FN](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/decision_workload/constant.DECIDE_FN): The HFT decision: microprice market-making, a fat-finger clamp and a position risk gate, returning the signed order (+buy / -sell / 0). No division — the microprice arrives normalized — so the body is compare / arithmetic / branch only. - [const DECIDE_NAME](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/decision_workload/constant.DECIDE_NAME): The function name `DECIDE_FN` defines. - [const LCG_A](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/decision_workload/constant.LCG_A): The CPU twin’s stimulus: a 15-bit linear congruential generator, s’ = (s * A + C) mod 2^15. A ≡ 1 (mod 4) with C odd gives the full period of 32768 (Hull–Dobell), and every product stays below 2^31, so the 32-bit core and the 64-bit VM compute it identically. - [const LCG_C](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/decision_workload/constant.LCG_C) - [const LCG_MASK](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/decision_workload/constant.LCG_MASK) - [const SOFT_CORE_REALBIST_ITERATIONS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/decision_workload/constant.SOFT_CORE_REALBIST_ITERATIONS): Decisions the boot ROM makes before it halts — far more than any measured window spans. - [fn inline_body](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/decision_workload/fn.inline_body): The body of the single-`Return` function `func` spliced in at `indent` spaces, and the expression its final `Return e.` yields. Each parameter is bound to its argument: an integer literal is substituted at every whole-word use (a constant needs no register of its own), an argument that is the parameter’s own name needs no binding, and anything else is bound by `Let`. Refused: an argument count that is not the arity, and any `Return` other than the body’s last line — its early exit has no inline equivalent. - [fn inline_call](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/decision_workload/fn.inline_call): `inline_body`, with the returned value assigned to the already-declared `result`. - [fn soft_core_realbist_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/decision_workload/fn.soft_core_realbist_program): The boot ROM the block ships: the program at `SOFT_CORE_REALBIST_ITERATIONS`, encoded for the scalar core. - [fn soft_core_realbist_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/decision_workload/fn.soft_core_realbist_source): The CPU twin’s program: each iteration advances the LCG three times, mapping each output onto the realbist’s input ranges as it is drawn, runs the decision inline, and shows `signed_order * 4 + order_side` — the whole decision, side included, so the output stream classifies every decision as buy, sell, risk-blocked or no-trade. - [fn soft_core_realbist_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/decision_workload/fn.soft_core_realbist_verilog): The block’s top: the scalar core itself, whose `$readmemh("program.hex")` boot ROM holds `soft_core_realbist_program`. Only `clk` and `rst` enter; the decision stream leaves on `out`. ## logicaffeine_compile::codegen_sva::dram dram — the DRAM machine. - [struct ComputeDramTiming](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/struct.ComputeDramTiming): The sub-JEDEC violation window that triggers the ComputeDRAM effect, in controller cycles. - [struct DeviceModel](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/struct.DeviceModel): A bank-state DEVICE that executes the plan and reports each data burst’s completion cycle. The zero-jitter fact: these times equal the plan’s own (`cas.at + data_cycles`) exactly — the device adds nothing and guesses nothing. - [struct DramTimings](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/struct.DramTimings): LPDDR5X-class timing parameters, in CONTROLLER CLOCK CYCLES, plus geometry. Values are engineering-realistic for an LPDDR5X-6400-class part driven by a controller clock where one RD/WR burst (BL16) occupies `data_cycles` on the bus — the table is DATA for the memory architect to correct, and every measurement in this module re-derives from it. - [struct Efficiency](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/struct.Efficiency): The measured outcome of a plan. - [struct Gather](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/struct.Gather): The dynamic tail: explicit addresses (a pointer-chase), one element each. - [struct RowStore](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/struct.RowStore): A functional model of DRAM rows — the ComputeDRAM ORACLE the real silicon is measured against. Each row is a bit vector packed into `words` u64 words. - [struct StreamDesc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/struct.StreamDesc): A compile-time transfer descriptor — the vocabulary the Wave-1 static schedule hands to the memory edge: `count` elements of `elem_bytes` from `base`, advancing `stride_bytes` per element (stride == elem ⇒ sequential; stride > row ⇒ row-per- element; the dynamic tail is modeled as an explicit gather list, see `Gather`). - [struct TimedCmd](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/struct.TimedCmd): A command with its planned issue cycle. The PLAN is the artifact: Wave 3 proves windows of it timing-legal in the certified SAT, and the executor RTL runs it in order with no interpretation. - [enum ComputeDramOp](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/enum.ComputeDramOp): A bulk in-DRAM operation over whole rows of one bank. `RowCopy` is RowClone; `And`/`Or`/`Maj` are the triple-row-activation majority reductions (`And`/`Or` assume a preset control row established by a prior `RowCopy` — wired in the Phase 5 lowering). - [enum DramCmd](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/enum.DramCmd): One DRAM command. - [enum VisitOrder](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/enum.VisitOrder): How multi-stream access lists are ordered into the plan. - [fn check_legal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/fn.check_legal): The INDEPENDENT legality checker — a total function over the plan, sharing no code with the scheduler. Returns the first violation as `Err(description)`. - [fn delta_encode](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/fn.delta_encode): Encode a timed plan as executor words: `[delta:24][op:3][bank:5][row:32]`. `delta` = cycles after the PREVIOUS command (first word: cycles after reset). op: 0=ACT 1=RD 2=WR 3=PRE 4=REFpb. - [fn emit_computedram_stream](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/fn.emit_computedram_stream): Emit the raw, deliberately timing-VIOLATING command stream that triggers `op` on real DRAM: an `ACT → PRE → ACT (…)` cadence with sub-`tRAS`/sub-`tRP` gaps. The stream is NEVER JEDEC-legal (that is the point) — `check_legal` rejects it by design. - [fn emit_dram_executor_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/fn.emit_dram_executor_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 opcode/ bank/row of its word, and prints PASS/FAIL. (Absolute-time equality to the plan is the Rust-side lock; the bench pins order + payload + one-issue-per-word in RTL.) - [fn emit_dram_executor_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/fn.emit_dram_executor_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). The rung-3 controller. - [fn map_addr](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/fn.map_addr): Address → (bank, row): rows rotate across banks so sequential rows pipeline (bank k streams data while bank k+1 activates). A compile-time-known mapping — the schedule depends on it, and so does the blacklist remap. - [fn measure](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/fn.measure) - [fn planned_beats](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/fn.planned_beats): Planned data-beat completion times straight from the plan (what the compiler promises); `DeviceModel::execute` is what the device delivers. - [fn schedule](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/fn.schedule): The compile-time scheduler: bursts grouped into row visits, rows pipelined across banks (ACT ahead under tRRD/tFAW while the data bus streams), refresh co-scheduled per bank into planned slots before every deadline. Returns the timed plan. - [fn schedule_ordered](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/fn.schedule_ordered): `schedule` with an explicit multi-stream visit order (see `VisitOrder`). - [fn standard_report](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/fn.standard_report): The standard measurement scenarios — kernel-shaped traffic classes, each checked legal and measured. Returns a stable JSON document (pure function of the timing table; no clocks, no randomness) — the `benchmarks/results/dram_sim.json` artifact. - [fn word_majority](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/dram/fn.word_majority): Bitwise majority of three words — the sense-amp reduction ComputeDRAM performs per bit. ## logicaffeine_compile::codegen_sva::engine_build LOGOS source → what the whole-program fabric engine loads: the program lowered to an engine config, proven to answer what the VM answers on the exact arguments about to be streamed before a byte is emitted, checked against the deployed engine’s profile and the flashed image’s caps. One path for every caller — the `emit_wpe_soc` example the board hosts compile through, and the Fabric Terminal’s library — so a program is lowered the same way wherever it runs. - [struct FabricMap](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/engine_build/struct.FabricMap): What each part of the fabric does for one compiled program, read off the config the engine runs: the labels the Fabric Terminal draws beside its activity panel, whose BLOCKS tiles are the config’s blocks and whose CELLS strip is its cells in the engine’s flat order. - [struct MapBlock](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/engine_build/struct.MapBlock): One block of the config: a BLOCKS tile. - [enum Lifter](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/engine_build/enum.Lifter): A way to lift a program to an engine config. A lifter panics on a program it cannot take; `lower` tries the function lifters in order, so a caller that runs one lifter at a time (a process or an instance per attempt) takes the same path. - [enum MapNext](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/engine_build/enum.MapNext): A block’s terminator, as the map gives it. - [enum Profile](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/engine_build/enum.Profile): The deployed engine a program must fit. A `.wire` carries no record of the profile it was built for, and an over-cap image loads fine and returns a plausible wrong number, so this check is the guard. - [fn fabric_map](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/engine_build/fn.fabric_map): The map of `cfg`, with `names` for the registers of the blocks `Lifter::Main`’s `## Main` region runs — the blocks reached from block 0 without entering a call. - [fn fits_caps](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/engine_build/fn.fits_caps): Check the program against the caps of the image that is actually on the board (`NAME=N,…`, the recipe the build records beside every bitstream). The static dimensions are read off the config; DEPTH and HEAP are data-dependent, so they are MEASURED by running the program on the model with the exact params about to be streamed. An over-cap program loads fine and returns a plausible wrong number — this is the guard. - [fn lower](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/engine_build/fn.lower): Lower `func` to an engine config the same way the benchmark lane does: the single-function CFG lifter when it agrees with the VM on these params, else the multi-function (call-stack) lifter. Either way the config is PROVEN ≡ VM on the exact params about to be streamed before a byte is emitted. - [fn lower_main](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/engine_build/fn.lower_main): Lower a whole `## Main` program and PROVE the engine model prints exactly what the VM prints before a byte is emitted: the output tape rendered line by line == `vm_outcome(src).output`. - [fn main_register_names](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/engine_build/fn.main_register_names): The Main frame’s variable names by register — the registers a `Lifter::Main` config’s own blocks read and write. A function’s blocks have registers of their own frame, which these names do not describe. - [fn vm_golden](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/engine_build/fn.vm_golden): The VM’s answer for `func(params)` — a synthesized `## Main` showing the call, run on the reference VM (the same `vm_outcome` every execution tier is locked against). This is the golden the chip must reproduce. - [fn vm_output_lines](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/engine_build/fn.vm_output_lines): The VM’s OUTPUT for a whole program — one line per `Show` — the golden a Main program’s streamed records are checked against. ## logicaffeine_compile::codegen_sva::fabric_config fabric_config — Phase D: the config-driven reconfigurable grid = THE INTERPRETER. - [struct ConfigTable](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_config/struct.ConfigTable): A program corpus compiled to ONE reconfigurable tile array: every datapath placed as a same-shape island (all padded to `rows × cols`), plus the datapath widths for the certified reconfig proof. `grids[k]` is the island selected by `block_config(k)`. - [struct ConfigWord](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_config/struct.ConfigWord): A configuration word: the index of the datapath the array is currently configured to compute. Streamed per datapath from the bytecode frame — the config table is the projection of the program onto the array. - [fn block_config](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_config/fn.block_config): The config word that selects datapath / block `k`. (Trivial today — the index — but the named seam is where a richer encoding, e.g. an interned block id, would live.) - [fn certify_config_table](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_config/fn.certify_config_table): Certify the config table END TO END with our SAT: for EACH config value `k`, prove `config == k ⇒ the ONE reconfigurable array ≡ island k`, for ALL inputs (bounded at `width`). Returns the per-config verdicts — all `true` ⇒ the config word losslessly selects any datapath on one physical array. - [fn compile_to_config_table](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_config/fn.compile_to_config_table): Compile a set of `(source, function-name)` datapaths to a `ConfigTable`: if-convert each function to a single-output decision island, place it on the tile array, then PAD every island to the common `max_rows × max_cols` so they share ONE reconfigurable array. `width` is the datapath width for the SAT proof; `cfg_width` must index all datapaths (`(1 << cfg_width) >= sources.len()`). - [fn eval_config_table](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_config/fn.eval_config_table): Evaluate the reconfigurable array configured as datapath `k` on `inputs`. Because the reconfig proof certifies `config == k ⇒ array ≡ island k`, the array’s output IS `island k`’s — so this evaluates the placed island directly. The result is the value the physical fabric would drive when its config word is `block_config``(k)`. ## logicaffeine_compile::codegen_sva::fabric_grid fabric_grid — a TRUE reconfigurable CGRA: place a fabric’s dataflow onto a 2-D array of identical tiles and route it through a LOCAL switchbox interconnect. The same silicon runs any fabric by reconfiguration — not a bespoke circuit per program. - [struct BoundedBuild](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/struct.BoundedBuild): The `BoundedExpr` instance of `Datapath` — the tree form. - [struct GateBuild](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/struct.GateBuild): The shared-gate-DAG instance of `Datapath` — the form the certifier refutes, linear in the circuit instead of in its unfolding. - [struct Grid](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/struct.Grid): A placed-and-routed CGRA: a `rows × cols` array of tiles plus the tile/channel that carries the result. Feed-forward (dataflow goes south/east), so it is a combinational DAG. - [struct Tile](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/struct.Tile): One configured CGRA tile. - [enum CellKind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/enum.CellKind): A tile’s optional compute: an arithmetic op or a predicated select over its visible sources. - [enum Chan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/enum.Chan): Which output channel of a tile carries the fabric’s result. - [enum Drive](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/enum.Drive): What drives one of a tile’s output channels: a routed source, or the tile’s compute result. - [enum MemOp](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/enum.MemOp): The three state-plane operations a `Mem` tile performs against the shared heap (see `CellKind::Mem`). - [enum Src2](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/enum.Src2): A value source visible to a tile: its north/west channel inputs, a global input, a constant, or zero (an unused channel). - [const TILE_OPERAND_CHANNELS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/constant.TILE_OPERAND_CHANNELS): A mux tile’s operand channels: its north and its west. The interconnect gives each tile two. - [trait Datapath](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/trait.Datapath): The datapath vocabulary a placed grid — or a straight-line cell body — is lowered through. - [fn cells_datapath](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.cells_datapath): Lower a straight-line `LoopCell` body through the datapath vocabulary `b` — the placer’s own lowering vocabulary, and the SPECIFICATION side of the placement obligation. `None` for a cell with no propositional lowering (a functional unit, a memory tile, a packed-SIMD tile). - [fn cells_to_gates](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.cells_to_gates): An ALU/select cell body lowered STRAIGHT INTO THE SHARED GATE DAG at `width`. Linear in the CELLS: a cell read by three later cells is built once and shared by pointer, where the tree form copies it three times (and their readers copy those, and so on — `fib.lg`’s 75-cell body unfolds to 1 657 763 tree nodes from a few hundred). - [fn certify_reconfig](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.certify_reconfig): Certify the reconfigurable array END TO END (Phase 5): build one grid per source function (they must be same-shape residuals so they place identically), then for EACH config value `k` prove via our certified SAT that `config == k` reconfigures the ONE array to be EXACTLY the bespoke island `grids[k]`, for ALL inputs. Returns the per-config verdicts — all `true` ⇒ the config word (streamed per block from the bytecode frame) losslessly selects any block’s datapath on one physical array: “the fabric IS the interpreter”. Each source is `(program, fn_name)` with a straight-line residual body. - [fn emit_config_grid_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.emit_config_grid_verilog): Emit the N-CONFIG reconfigurable array as combinational RTL — the synthesizable twin of `time_mux_n_bounded`. ONE `rows×cols` tile grid runs ANY of `grids` selected by a `cfg`-bit config word: every tile computes all N fabrics’ drives over the SHARED (config-muxed) neighbour channels and selects by `cfg`; the result muxes the N output taps. `grids` must share dimensions (pad with `pad_grid` first). This is what a `fabric_soc` flashes: send `cfg` (the block index from the bytecode frame) + the inputs and the ONE array becomes that block’s datapath — proven semantics-preserving by `certify_config_table`. - [fn emit_grid_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.emit_grid_testbench): A self-checking testbench for the (combinational) tile array: drive each input vector, compare `result` to the VM oracle from `grid_{name}_{in,out}.hex`. - [fn emit_grid_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.emit_grid_verilog): Emit the tile array as combinational RTL: two channel wires (`vs`/`he`) per tile, each tile wired only to its north/west neighbours — a genuine nearest-neighbour spatial fabric. - [fn emit_time_multiplexed](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.emit_time_multiplexed): Emit the time-multiplexed array as combinational RTL: every tile computes BOTH fabrics’ drives and muxes each channel on `ctx`; the result muxes the two fabrics’ output taps. One silicon array, two programs — selected by a configuration bit. - [fn eval_grid](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.eval_grid): Simulate the grid (feed-forward, row-major) and return the PRIMARY output value. - [fn eval_grid_all](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.eval_grid_all): Simulate the grid and return ALL output values in `all_outs` order (for multi-output loop bodies). - [fn eval_grid_all_with_heap](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.eval_grid_all_with_heap): Like `eval_grid_all` but threads a SHARED heap (for a whole-program block walk with a state plane): every `Mem` tile touches `heap` (persisting across blocks), and ALL outputs are returned in `all_outs()` order so the block-sequencing controller can commit the block’s register writes + read its terminator operand. For a heap-free grid this equals `eval_grid_all` (the heap stays empty). - [fn eval_grid_with_heap](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.eval_grid_with_heap): Simulate a STATE-PLANE grid — one that carries `Mem` (heap read/write/alloc) tiles — threading ONE shared heap through the tiles in row-major (= placement = program) order, exactly as the model’s `eval_cells` threads its heap. Non-`Mem` tiles evaluate combinationally (`eval_cell`); a `Mem` tile touches the heap and drives its result onto its output channel. Returns the primary output. This is how Stage X2 proves collections/structs/text run on the grid: `eval_grid_with_heap ≡ the whole-program model ≡ the VM`. - [fn grid_area](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.grid_area): The grid’s area footprint: `(rows, cols, used_tiles)` — a tile is USED if it computes or drives a non-zero channel. Used to compare placements. - [fn grid_is_combinational](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.grid_is_combinational): True iff every placed tile is `Arith`/`Select` (or pure routing) — i.e. the grid is fully COMBINATIONAL and SAT-lowerable. A `Func` (division/float) tile has no bitblast lowering, so such a grid is proven by eval ≡ VM + iverilog, not by `certify_reconfig`/`certify_config_table`; those refuse a non-combinational grid rather than panic opaquely inside the SAT lowering. - [fn grid_output_datapath](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.grid_output_datapath): Lower output `which` (in `all_outs` order) through the datapath vocabulary `b`, resolving the array row-major so every tile’s north/west inputs are already lowered (the feed-forward invariant). `None` when any live tile has no propositional lowering. - [fn grid_output_to_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.grid_output_to_bounded): Lower output `which` (in `all_outs` order) to a `BoundedExpr` at `width`, naming global inputs via `name_in` — so the placed+routed array can be proven EQUAL to a reference expressed in the SAME variable namespace (e.g. a loop body’s `s0/iv/inv0`), exhaustively. - [fn grid_output_to_gates](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.grid_output_to_gates): Lower output `which` STRAIGHT INTO THE SHARED GATE DAG at `width` — the certifier’s path. Same walk, same tiles, same circuit as `grid_output_to_bounded`; it just never materialises the tree, which for a reconvergent datapath is exponentially larger than the array that computes it. `None` when a tile has no propositional lowering. - [fn grid_to_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.grid_to_bounded): The PRIMARY output’s `BoundedExpr` (output 0) with the default `in{k}` input names. - [fn pad_grid](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.pad_grid): Pad a placed grid to a larger `target_rows × target_cols` array: copy its tiles into the TOP-LEFT corner and leave the rest IDLE. This RESOLVES the same-shape constraint the reconfigurable-array proof needs (`time_mux_n_bounded` requires equal dimensions) — grids of DIFFERENT shapes co-reside on ONE array without touching any datapath. The output taps keep their positions (valid since the array only GREW), and the added IDLE tiles drive zero; because dataflow is feed-forward (south/east only), no downstream idle tile ever feeds an upstream one, so the padded grid computes EXACTLY the original (`eval_grid(pad_grid(g, R, C)) == eval_grid(g)`). Panics if asked to shrink. - [fn route_leveled](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.route_leveled): AREA-MINIMIZING placer (level scheduling). The naive `route_straight_line` gives every cell two rows (a routing row + a compute row). But a cell whose operands are all global inputs or constants (topological LEVEL 0) needs NO routing row — its operands are tapped directly — so all level-0 cells share ONE compute row (row 0), packed across columns. Deeper cells still get their own routing+compute rows. For DAGs with input-parallelism this collapses the row count (a chain saves a little; a wide fan-in tree saves a lot). Correctness is unchanged — the S3 SAT proof validates the compact placement exactly as it did the naive one. - [fn route_loop_body](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.route_loop_body): Map a LOOP BODY onto the tile array. Same diagonal placement + Manhattan routing as the straight-line case, but each `LoopCell` may be a `Select` (a mux tile — the grid already models it), and the body produces MULTIPLE outputs (one per loop-carried next-state register, in `next` order). Global-input / constant operands are tapped directly; cell-value operands route (each distinct producer takes one of the tile’s two channels — a computed PREDICATE routes exactly like a computed data arm, and two ports reading one producer share a channel). This grid is the combinational BODY datapath of a loop-on-a-grid — the controller (counter / fabric predicate) latches its outputs, exactly as with the hand-wired body. - [fn route_straight_line](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.route_straight_line): The placer + router. Map a straight-line fabric (`FabricOp` SSA, from the real compiled residual) onto the tile array. Placement: cell `i` computes on the diagonal at `(2(i+1), i)` — its own column `i` carries its result downward. Routing: an operand that is a global input or constant is TAPPED directly (inputs fan out for free); an operand that is another cell’s value is routed via a Manhattan path — forked EAST off its column (`he←N`, which coexists with the column’s downward `vs←N`, so fan-out costs nothing) and turned back into the consumer’s north (`vs←W`) or read from its west. Correct by construction; the S3 SAT proof catches any slip. - [fn run_program_cfg_on_grid](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.run_program_cfg_on_grid): Run a whole (acyclic-control-flow) function on the reconfigurable GRID (Stage X4 — the whole-program XPU). Each basic block’s straight-line body is PLACED on a fresh tile array (`route_loop_body`, the block’s live-in registers as inputs) with its downstream `Src`s as the grid’s outputs — every register write, then the terminator’s predicate/return operand; `eval_grid_all` reads them off the placed array, the register file is updated, and a block-sequencing controller walks the terminator graph (Jump/Branch/Return), reconfiguring the array to the next block. So a BRANCHY whole program runs as spatial dataflow on ONE array (each block a reconfiguration), proven ≡ `eval_program_cfg_fabric` ≡ the VM. A block may carry `Mem` (heap read/write/alloc) tiles: ONE heap is threaded across every reconfiguration (`eval_grid_all_with_heap`), so collections/structs persist across blocks — the state plane. (Loops are the separate loop fabric.) - [fn tile_channel_demand](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.tile_channel_demand): How many operand channels the switchbox must route into ONE tile for `cell`. - [fn time_mux_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.time_mux_bounded): The combined output of a TIME-MULTIPLEXED array: one physical grid whose every tile is muxed by a `ctx` selector between fabric `a`’s config (ctx=1) and fabric `b`’s config (ctx=0). Because the neighbour channels are themselves ctx-muxed, when ctx=1 the whole array carries `a`’s dataflow and when ctx=0 it carries `b`’s — proven in the P3 test. `a` and `b` must share dims. - [fn time_mux_n_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.time_mux_n_bounded): The RECONFIGURABLE array (Phase 5): ONE tile grid runs ANY of `grids` selected by a CONFIG WORD — the generalization of `time_mux_bounded` from a 1-bit `ctx` (2 fabrics) to a `cfg_width`-bit word (N fabrics). Every tile computes all N fabrics’ drives over the SHARED muxed neighbour channels, then selects by `config`; the output tap muxes likewise. This is “the fabric IS the interpreter”: the config word (streamed per block from the `LGB1` frame) reconfigures the SAME silicon to be any block’s datapath. `config` is fixed to a concrete value here so the lock proves, per value `k`, that the reconfigured array is EXACTLY the bespoke island `grids[k]` (`config == k ⇒ array ≡ grids[k]`). All grids must share dimensions (same-shape fabrics place identically). - [fn unroutable_cell](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_grid/fn.unroutable_cell): The first cell of `cells` the router cannot place, as `(cell index, channels it demands)`. `None` when every cell fits the interconnect. The gate a certifier consults BEFORE calling `route_loop_body`, so an unplaceable body is declined by name instead of panicking inside the placer. ## logicaffeine_compile::codegen_sva::fabric_pipe fabric_pipe — the compiled residual circuit cut into register stages: a new input every clock, a short period. - [struct PipelineSchedule](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/struct.PipelineSchedule): Where every op of a residual computes, and which op leaves the pipeline. - [enum FinalAdd](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/enum.FinalAdd): How the two words a sum’s compressor tree leaves are added. - [enum Inputs](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/enum.Inputs): Where a pipeline’s first stage reads its inputs. - [enum SumSharing](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/enum.SumSharing): How a sum that other sums read is lowered. - [const DECISION_CELLS_BUDGET](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/constant.DECISION_CELLS_BUDGET): The stage budget a decision is cut to on standard cells, in the units of `op_delay`: three carry chains and their selects. A register is ~20 µm² of flip-flop a bit there, where on a fabric it rides in a LUT’s slice, so a decision takes few stages and reads its ports (`Inputs::Ports`); each compare takes the sums it reads into its own rows (`SumSharing::Fold`), resolved by one add synthesis picks (`FinalAdd::Native`). MEASURED (2026-10-18, K1’s `decide` so lowered, its ports read, Sky130 HD: yosys 0.33 with OpenLane v1’s `DELAY 0` ABC script at a 2 ns target, OpenSTA at the typical corner, no wires): 18 = 5 stages, 44,306 µm² at 4.65 ns; 30 = 3 stages, 34,005 µm² at 3.57 ns; 36 = 2 stages, 30,843 µm² at 5.03 ns; one stage, 32,013 µm² at 7.71 ns. Without the folds, 27 and 30 were 32,750 µm² at 4.10 ns and 31,559 µm² at 4.34 ns. - [const DECISION_CHAIN_BUDGET](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/constant.DECISION_CHAIN_BUDGET): The stage budget a decision is cut to on a fabric with carry chains, in the units of `op_delay`: one unlowered add or subtract (a carry chain, 9) and an AND. The XORs that finish a compare’s sign start the next stage, so the mask a select fans out to its 64 bits leaves a register, never the end of a carry chain. MEASURED (2026-10-17, K1’s `decide`, Artix-7 fabric map, yosys 0.33 synth_xilinx + nextpnr-xilinx, seeds 1-3, median): 12 (the compare and its select in one stage) = 852 LUTs at 119.2 MHz, 10 = 848 at 147.3, 9.6 = 784 at 145.4, 6 = 848 at 147.8; at 8 and 9 one seed in three does not finish routing within 300 s. - [const FOLD_ROW_LIMIT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/constant.FOLD_ROW_LIMIT): The words a folded sum may bring into each reader’s rows; a larger sum resolves once and is read as one word. - [const GEMM_MUL_BITS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/constant.GEMM_MUL_BITS): The int8 width of the GEMM array’s multiply tiles. - [const GEMM_TERM_BUDGET](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/constant.GEMM_TERM_BUDGET): The term stage budget of the GEMM array, in the units of `loop_cell_delay`: the operand arithmetic in one stage, the int8 multiplies in the next. - [const HORNER_SEQ_BUDGET](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/constant.HORNER_SEQ_BUDGET): The stage budget `fabric_horner_seq` is cut to, in the units of `op_delay`. MEASURED (2026-10-17, the synthesis sequence of OpenLane’s synth.tcl under host yosys 0.33, AREA 0, abc target 1 ns, sky130_fd_sc_hd tt_025C_1v80, worst stage by abc `stime`): budget 4 is 1.36 ns over 311,772 µm² of cells, 5 is 1.43 ns over 258,289 µm², 6 is 1.99 ns, 7 is 2.65 ns; the single-stage residual is 13.85 ns. Five is the knee: the next tighter budget buys 5% of period for 21% more area. - [fn carry_save_lower](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.carry_save_lower): Carry-save lowering of a residual at datapath width `width` (64 on silicon; narrower so our SAT can check the lowering exhaustively), each shared sum resolved once (`SumSharing::Resolve`). Only the values the result depends on are lowered. Returns the new op list, which holds no `Add`, `Sub` or `Mul`, and the index of its result. - [fn carry_save_lower_with](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.carry_save_lower_with): `carry_save_lower` with the shared sums lowered as `sharing` says and each compressor tree’s last two words added as `final_add` says. Under `SumSharing::Fold` an add or subtract read only by adds and subtracts never resolves, however many read it, and one its rows fold into resolves only for its other readers; a multiply read more than once still resolves once. Under `FinalAdd::Native` the lowering holds one `Add` per resolved sum and nothing else additive. - [fn csd_digits](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.csd_digits): The canonical signed digits of `c` mod 2^`width`: `(shift, ±1)` pairs whose signed sum of powers of two is `c`, no two adjacent. The top digit is taken positive, since ±2^(width-1) agree mod 2^width. - [fn decision_ops](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.decision_ops): A decision fabric (`decision_fabric_from_source`: arithmetic cells and compare-selects) as a residual in the pipeline’s op vocabulary, and the index of its result. A compare becomes the mask of its outcome, all ones or zero (`compare_mask`); a select is `e ^ ((t ^ e) & mask)`. Every op is emitted once, so a predicate many selects test has one mask. A fabric with any other cell (a functional unit, a memory or heap tile) has no combinational form and is refused. - [fn dot_unrolled_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.dot_unrolled_source): The `u`-wide unrolled int8 dot product in LOGOS: each iteration accumulates `u` independent products, so the compiler places `u` multiply tiles that fire together, `u` MACs per clock. - [fn earliest_schedule](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.earliest_schedule): Every computed value in its earliest stage: the shortest pipeline whose stages each stay within `budget`. - [fn emit_csa_multiplier_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.emit_csa_multiplier_verilog): A parameterized Verilog module `{module}`: an unsigned AW×BW multiplier as a tree of 3:2 compressors over its partial-product rows, registered after CUT tree levels and (with FINAL) once more before a Kogge-Stone final add. One generator for every consumer, so the BigInt limb multiplier and the FPU carry the same tree under their own names. - [fn emit_fabric_pipelined_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.emit_fabric_pipelined_verilog): Emit the scheduled residual as a pipeline: module `fabric_{name}` with ports `clk`, `in0..`, and the registered `result`. Every assignment is its own net, so no operator’s signedness leaks into another’s. - [fn emit_horner_seq_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.emit_horner_seq_verilog): `benchmarks/silicon/fabric_horner_seq.v`: the RTL the flow hardens as `fabric_horner_seq`. - [fn gemm_mac_array_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.gemm_mac_array_verilog): `benchmarks/silicon/gemm_mac_array.v`: the eight-wide int8 MAC array `cgra_arr8` as the pipelined loop CGRA (operands, then products, ahead of a carry-save accumulator), with its pin-light top. - [fn horner_seq_pipeline](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.horner_seq_pipeline): The residual `fabric_horner_seq` hardens: the REAL compiler’s residual of the Horner polynomial (`POLY_BODY`), carry-save lowered at 64 bits and cut to `HORNER_SEQ_BUDGET`. - [fn is_wiring](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.is_wiring): Wiring costs no logic depth: a shift by a constant moves bits, and a bitwise op with a constant operand is constant bits or inverters. It takes its operands’ stage, and each reader rebuilds it from their registers. - [fn known_bits](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.known_bits): The bits of each value its construction fixes, as (mask of known bits, their values): shifts bring in zeros, masks and constants pin bits, a carry row’s bit 0 is zero. A register on a known bit holds a constant, which synthesis removes, so a schedule is charged only for the live bits it holds. - [fn latest_schedule](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.latest_schedule): Every computed value in its latest stage of that same shortest pipeline. - [fn matmul_array_top](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.matmul_array_top): A pin-light top for a MAC array’s CGRA `cgra_{name}`, so placement and routing measure the array’s paths rather than its I/O: a serial input shifts into the loop bound, the finished result latches, its parity drives one pin. - [fn op_delay](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.op_delay): The logic depth of one op, in units of a two-input XOR at the synthesis corner. Wiring is zero. A carry chain or a multiplier left unlowered is one indivisible op, so it occupies a stage of its own whatever the budget. - [fn schedule_pipeline](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.schedule_pipeline): Cut a residual into the shortest pipeline whose stages each stay within `budget` (in the units of `op_delay`), placing every computed value so the pipeline holds the fewest live register bits. An op deeper than the budget on its own still gets a stage, alone. - [fn simulate_pipeline](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_pipe/fn.simulate_pipeline): The cycle model of the emitted pipeline. Before each clock `t` the input vector `stream[t]` is presented; the returned vector holds the result register after each clock. Registers start at zero. ## logicaffeine_compile::codegen_sva::fabric_rtl fabric_rtl — Futamura’s first projection in silicon: “the specialized residual IS the circuit,” end-to-end from the REAL compiler. - [struct CfgBlock](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/struct.CfgBlock): One spatially-lowered basic block: a wired residual body + its live-in registers + the register writes it commits + its terminator. - [struct DecisionFabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/struct.DecisionFabric): A combinational decision datapath: SSA `LoopCell`s (arith + predicated select) over the function parameters (`Src::In`), plus the `Src` that drives the single output. - [struct FabricOp](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/struct.FabricOp): One residual operation: `v_i = a op b`. - [struct LoopFabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/struct.LoopFabric): A counted-loop residual lowered to a CGRA: a fixed BODY datapath (SSA over the current loop-carried state + the induction variable + loop invariants, INCLUDING predicated select tiles for data-dependent branches) driven by a sequential controller that clocks the state through the body once per induction value in the inclusive range `lo..=hi`. - [struct NestedFabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/struct.NestedFabric): A perfectly-nested counted loop lowered to a HIERARCHICAL CGRA: an outer counter over the shared loop-carried state, whose body is the inner loop (its own body datapath + inner counter), whose range may reference the outer induction variable. - [struct PipelinedLoop](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/struct.PipelinedLoop): A counted loop emitted in the pipelined accumulator form. - [struct ProgramCfgFabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/struct.ProgramCfgFabric): A whole function lowered to spatial block islands + a block-sequencing controller. - [struct WhileFabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/struct.WhileFabric): A `while`-loop residual lowered to a CGRA: a fixed body datapath streamed by a controller whose CONTINUE predicate is fabric-computed over the loop-carried state (no counter). - [struct WholeProgramFabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/struct.WholeProgramFabric): The whole-program fabric: a straight-line `Main`’s cells plus the ordered `Src`s it `Show`s. Evaluating it yields the program’s output TAPE, compared against the VM’s stdout — this is what covers `Show` and validates the whole fabric end-to-end (calls inlined, collections/structs/enums on the shared heap). - [enum AluOp](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/enum.AluOp): The straight-line ALU ops a dispatch-free residual is built from (the `alu.v` ops, each already proven ≡ the VM). 64-bit signed, wrapping — bit-identical to the VM’s `Int`. - [enum CmpKind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/enum.CmpKind): A signed comparison (the VM’s `Int` order) that gates a predicated select. - [enum Divergence](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/enum.Divergence): Why a cell’s fixed-width value is not the value the VM computes for the same operands. The fabric’s arithmetic is the 64-bit projection of the VM’s; the VM is exact and total in a way no fixed-width datapath is, so every point where the two part is named here, and a checked evaluation reports it instead of producing the wrapped, zeroed or saturated word. - [enum FuncUnit](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/enum.FuncUnit): A SEQUENTIAL functional unit — signed division and remainder. Unlike an `AluOp`, division is NOT a combinational tile: on silicon it is the multi-cycle `shared_divider` (already proven ≡ the VM by `rtl.rs::the_signed_divider_is_proven_correct_by_our_sat`), issued as a functional unit. Keeping it a distinct fabric cell lets the emitter wire that sequential unit rather than synthesize a giant combinational divider. Semantics mirror the soft-core’s `shared_divider` exactly, INCLUDING the divide-by-zero trap (`b == 0 → 0`). - [enum LoopCell](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/enum.LoopCell): One body cell of the CGRA fabric: an arithmetic tile, or a predicated SELECT (mux) tile whose comparison is folded in. A branch in the loop body is if-CONVERTED to a `Select`: both arms compute, the signed predicate selects — control becomes data, no divergence. - [enum LoweringError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/enum.LoweringError): Why the whole-program fabric lowering refused a program. A TYPED failure surface: unsupported constructs return `Err(LoweringError)` from the `try_*` entry points instead of panicking, so callers (and the `lowering_coverage_lock` ratchet) can tell “this construct is not lowered yet” apart from a real bug. The `Display` strings are byte-identical to the old `panic!` messages, so the panicking wrappers are unchanged. - [enum NestSrc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/enum.NestSrc): A range bound in the nested context: a circuit input, a constant, or the OUTER induction variable (so `for j from 1 to i` is expressible). - [enum Src](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/enum.Src): An operand of a residual op: a circuit input (a function parameter), a prior SSA value, or a compile-time constant (already specialized in by the partial evaluator). - [enum Term](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/enum.Term): A basic block’s terminator: where control goes after the block’s body runs. - [const POLY_BODY](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/constant.POLY_BODY): The demonstration residual: a degree-3 polynomial in Horner form, `2x³ + 5x² − 3x + 100`. Straight-line (`+ - *`), so the compiler residualizes it dispatch-free. - [const STATE_PLANE_HEAP_WORDS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/constant.STATE_PLANE_HEAP_WORDS): The heap-word budget for a state-plane kernel: enough words for the largest collection any vector touches (a generous fixed LUTRAM — collections in these kernels are a handful of words; addresses index the low `clog2(HEAP)` bits, so an in-bounds pointer always resolves). Kept a power of two for clean address slicing. - [const W](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/constant.W): The 64-bit datapath width — the VM’s `Int` is `i64`, so the circuit wraps identically. - [fn decision_fabric_from_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.decision_fabric_from_source): The Futamura P1 lowering for a branchy decision. Compile `src`, take function `fn_name`’s straight-line-with-branches body (entry `..` `Return`), and if-convert it to a combinational select-DAG: parameters become circuit inputs, every `If` a `Select`. Panics on a shape outside the compare/arith/branch family (the honest boundary — loops map to a CGRA, division to a separate functional unit). - [fn decision_fabric_has_state](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.decision_fabric_has_state): True iff the fabric carries a state-plane (heap) cell — i.e. it must be lowered by `emit_state_plane_verilog` (sequenced) rather than `emit_decision_fabric_verilog` (combinational). - [fn decision_fabric_is_float_arith](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.decision_fabric_is_float_arith): True iff the fabric is a pure FLOAT-arithmetic datapath (its cells are all `FuncUnit` float ops over float/Val operands) — lowered by `emit_float_datapath_verilog`. It must end in a float result (no `FFloorF` float→int bridge here — the caller floors the streamed f64 downstream) and carry no heap. - [fn decision_fabric_is_pow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.decision_fabric_is_pow): True iff the fabric is a pure POWER datapath (every cell is a `FuncUnit::Pow`) — lowered by `emit_pow_datapath_verilog`. Pow cannot settle combinationally (`FuncUnit::verilog` refuses it), so a Pow-bearing fabric takes this sequenced lane exactly as a float fabric takes the fpu.v lane. - [fn emit_decision_fabric_testbench_dummy](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_decision_fabric_testbench_dummy): A self-checking testbench for a COMBINATIONAL `decision_{name}` fabric: drive `n` input vectors (each `n_in` 64-bit words) from `dec_{name}_in.hex`, compare the settled `result` against the VM oracle in `dec_{name}_out.hex`, and print PASS/FAIL. The combinational analog of `emit_state_plane_testbench` — no clock, one `#1` settle per vector. Lets any Func/Cmp/Arith decision tile be iverilog-exercised ≡ the VM. - [fn emit_decision_fabric_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_decision_fabric_verilog): Emit the decision as a fixed COMBINATIONAL dataflow circuit — one `wire` per SSA cell, arith and predicated-select tiles, no clock. 64-bit so its wrapping arithmetic is bit-identical to the VM. - [fn emit_fabric_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_fabric_testbench): A self-checking testbench: drive N inputs, compare `result` against the VM oracle from `fabric_{in,out}.hex`. Prints PASS/FAIL. 64-bit values. - [fn emit_fabric_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_fabric_verilog): Emit the residual as a fixed dataflow circuit — one combinational `wire` per SSA value, no PC / fetch / dispatch. `result` names the SSA value driving the output. 64-bit, so the circuit’s wrapping arithmetic is bit-identical to the VM’s `Int`. - [fn emit_float_datapath_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_float_datapath_verilog): Lower a pure-float-arithmetic `DecisionFabric` to a SEQUENCED float datapath binding `fpu.v` (see the block comment above). Each cell is one multi-cycle FPU step; the streamed `result` is the f64 bit-pattern of the final float. Panics on any non-float-arith cell (the honest boundary — `FFloorF`/`Arith` are not bound here). - [fn emit_loop_fabric_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_loop_fabric_testbench): A self-checking testbench for the CGRA: for each recorded input vector, pulse reset, clock until `done`, and compare `result` against the VM oracle from `cgra_{in,out}.hex`. - [fn emit_loop_fabric_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_loop_fabric_verilog): Emit the CGRA as a SEQUENTIAL circuit: a combinational body datapath (one `wire` per SSA value + next-state) plus a controller that clocks the loop-carried state through it once per induction value in `lo..=hi`. No fetch, no opcode dispatch: the body is WIRED (spatial), the loop is a counter (temporal). `done` pulses when the loop is finished; `result` is the returned accumulator. - [fn emit_loop_fabric_verilog_int8](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_loop_fabric_verilog_int8): Emit the CGRA RTL with an INT8-NATIVE datapath: every multiply tile’s operands are `mul_bits`-bit signed, so each MAC maps to exactly ONE DSP48E1 (a 25×18 signed multiplier) instead of the ~10 DSPs a 64×64 multiply decomposes into. The product is sign-extended back to the 64-bit accumulator, so the ADDS and the carried accumulator stay exact 64-bit — the result is byte-identical to the 64-bit fabric (and the VM) whenever the multiply operands fit in `mul_bits` (which the int8 model guarantees, and the ≡VM locks verify). This is the datapath that makes the spatial array DSP-packable and fast on real silicon. - [fn emit_loop_fabric_verilog_pipelined](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_loop_fabric_verilog_pipelined): Emit the counted-loop CGRA with every accumulator in carry-save form and its terms pipelined ahead of it. - [fn emit_nested_fabric_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_nested_fabric_testbench): A self-checking testbench for the nested CGRA vs the VM oracle (`nested_{name}_{in,out}.hex`). - [fn emit_nested_fabric_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_nested_fabric_verilog): Emit the nested CGRA as a HIERARCHICAL FSM: an outer counter that, per iteration, sets up the inner range (from the outer iv) and runs the inner counter to completion, streaming the shared state through the inner body datapath. Three states — SETUP (arm inner for `oi`), RUN (inner iterates), and advance-outer — so the inner range recomputes correctly when the outer advances. - [fn emit_pow_datapath_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_pow_datapath_testbench): A self-checking testbench for a power datapath: for each of `n` input vectors, pulse `rst`, drive `in{k}`, run until `done` (bounded by `max_cycles`), and compare `result` against the VM oracle loaded from `pow_{name}_{in,out}.hex`. Mirrors `emit_state_plane_testbench` (the sequenced clocked harness). - [fn emit_pow_datapath_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_pow_datapath_verilog): Lower a pure-`Pow` `DecisionFabric` to a SEQUENCED power datapath (see the block comment above). Each cell is one `b`-step multiply loop over a shared accumulator; the streamed `result` is the final power. Panics on any non-Pow cell (the honest boundary — mixed lanes are a follow-on). - [fn emit_seq_block_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_seq_block_verilog): Emit a per-block SEQUENCED datapath (`seqblk_{name}`) for a `CfgBlock`: on a `start` pulse it walks the block’s SSA cells (combinational in one step, multi-cycle division/float via the shared units), then holds `done` high with every `needed` output (each register write’s `Src`, then the terminator operand) driven from the settled cell/register values. The block-walk sequencer starts it, waits `done`, latches the writes, and evaluates the terminator. Multi-cycle TILES are first-class here. - [fn emit_seq_datapath_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_seq_datapath_testbench): A self-checking CLOCKED testbench for a `seq_{name}` sequenced datapath: for each of `n` input vectors it pulses `rst`, waits for `done`, and checks `result` == the VM oracle (`seq_{name}_out.hex`). Multi-cycle tiles (the divider / FPU) make a vector take many clocks, so it spins on `done` with a generous timeout. - [fn emit_seq_datapath_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_seq_datapath_verilog): Emit a general SEQUENCED datapath over a `DecisionFabric`’s cells — the LATENCY-INSENSITIVE fabric. A combinational `Arith`/`Select` cell settles in one step; a `Func` DIVISION cell (`DivS`/`ModS`/`FloorDivS`) ISSUES the multi-cycle `shared_divider` and STALLS until its `done` (a variable-latency TILE). This is the same cell stream `emit_decision_fabric_verilog` wires as a pure combinational DAG, but with the sequential functional units as first-class multi-cycle tiles — so it composes with the fpu.v FPU (Phase B) and the block-walk sequencer (Phase C). Proven == `eval_decision_fabric` == the VM by iverilog. (Phase A: Arith/ Select/division; float/pow/mem are the following increments and PANIC here as the honest boundary.) - [fn emit_seq_program_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_seq_program_testbench): A self-checking clocked testbench for `seqprog_{name}`: per vector, load params, pulse rst, spin on `done` (multi-cycle tiles + the block walk take many clocks), and check `result` == the VM (`seqprog_{name}_out.hex`). - [fn emit_seq_program_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_seq_program_verilog): Emit the DONE-AWARE whole-program sequenced fabric (`seqprog_{name}`): the per-block sequenced datapaths (`seqblk_*`, each with multi-cycle division/float TILES) + a block-PC FSM that STARTS the current block, waits its `done`, latches the register writes, and takes the terminator (Jump/Branch/Return). This is the unification — one whole program (loop + division + float) on one spatial fabric, latency-insensitive. Proven == `run_program_cfg_on_grid` == the VM by iverilog. - [fn emit_seqprog_soc_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_seqprog_soc_verilog): Emit a Nexys A7 SoC wrapper for the whole-program sequenced fabric: a baked vector ROM steps `seqprog_{name}` through each input (drive params → pulse the fabric reset → wait `done` → capture result), streaming a 12-byte record `{0xA5, result[63:0] MSB-first, run_cycles[15:0], 0x5A}` out the UART TX per vector, then looping. Slow /128 core clock (781.25 kHz) + power-on reset. `vectors` are the params per run (n_params each). This is the multi-cycle fabric (division + fpu.v tiles) on real silicon. - [fn emit_state_plane_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_state_plane_testbench): A self-checking testbench for a state-plane controller: for each of `n` input vectors, pulse `rst`, drive `in{k}`, run until `done` (bounded by `max_cycles`), and compare `result` against the VM oracle loaded from `state_{name}_{in,out}.hex`. Mirrors `emit_loop_fabric_testbench` (the CGRA clocked harness). - [fn emit_state_plane_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_state_plane_verilog): Lower a heap-bearing `DecisionFabric` to a SEQUENCED state-plane controller (see the block comment above). `heap_words` sizes the shared LUTRAM. Pure-compute cells render as combinational `v{i}` wires (over the LATCHED cell registers `R[j]`) latched per step; heap cells access the LUTRAM with a bump-pointer `hp`. - [fn emit_while_fabric_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_while_fabric_testbench): A self-checking testbench for the while-CGRA: for each vector, pulse reset, clock until `done`, and compare `result` against the VM oracle from `while_{name}_{in,out}.hex`. - [fn emit_while_fabric_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.emit_while_fabric_verilog): Emit the while-CGRA as a SEQUENTIAL circuit: a combinational body datapath + a controller whose `running` flag is the FABRIC PREDICATE — evaluated on the init state (at reset) and on the next state (each step) to decide whether to keep iterating. No counter: the trip count is data. - [fn eval_decision_fabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.eval_decision_fabric): Evaluate the decision DAG (arith + select, 64-bit wrapping) — the reference the emitted circuit is checked against, bit-identical to the VM’s `Int`. - [fn eval_decision_fabric_heap](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.eval_decision_fabric_heap): Evaluate a decision fabric that reads the shared HEAP (the state plane). `heap` mirrors the VM’s exact layout — a collection at pointer `p` is `heap[p] = length` then its elements at `heap[p+1..=p+len]` (1-based) — so this evaluation is bit-identical to the VM’s `Int`. A `LoopCell::HeapRead` reads `heap[addr]`; `length of xs` is `HeapRead(p)`, `item i of xs` is `HeapRead(p + i)`. Reads are pure given the input heap, so the fabric stays a combinational DAG (heap WRITES/ALLOC are the next increment). - [fn eval_fabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.eval_fabric): Evaluate the residual op-by-op (64-bit wrapping) — the reference the circuit is checked against, identical to the VM’s arithmetic. - [fn eval_loop_body](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.eval_loop_body): Evaluate ONE execution of a loop fabric’s body over `bin` (the body-input convention: `0..n_state` = the current state, `n_state` = the induction variable, then the invariants), returning every SSA value. The single oracle every pipelined / metapipelined model of the body is checked against. - [fn eval_loop_fabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.eval_loop_fabric): Evaluate the CGRA op-by-op the way the sequential controller does: initialise the state, then for each induction value in `lo..=hi` apply the body and latch the next state. 64-bit wrapping — bit-identical to the VM’s `Int` reduced mod 2⁶⁴. This is the reference the emitted clocked circuit is checked against. - [fn eval_loop_fabric_heap](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.eval_loop_fabric_heap): Evaluate a FOREACH OVER A LOCAL HEAP LIST (`seq_heap_ptr.is_some()`). The prologue-heap island builds the list into a shared heap ONCE; then for each `iv` in `0..heap[list_ptr]` the body runs with that heap THREADED — the element `heap[list_ptr + 1 + iv]` is destructured via `HeapRead`, and any collection op in the body reads/writes the same heap (so mutation across iterations persists). Bit-identical to the VM. - [fn eval_loop_fabric_seq](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.eval_loop_fabric_seq): Evaluate a loop fabric, supplying the iterated SEQUENCE’s element values when it is a sequence loop (`seq_input.is_some()`). The induction range is then `0..=seq.len()-1` (an empty seq runs zero iterations, exactly like the VM), and each `LoopCell::MemRead` reads `seq[addr]`. For a numeric range loop, `seq` is unused and the bounds come from `lo`/`hi`. - [fn eval_nested_fabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.eval_nested_fabric): Evaluate the nested CGRA: the outer counter drives the inner loop to completion each iteration (the inner range may reference the outer iv). 64-bit wrapping — the VM’s `Int` mod 2⁶⁴. - [fn eval_program_cfg_fabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.eval_program_cfg_fabric): Evaluate a whole-function CFG fabric: seed the register file with `params`, then let the block-sequencing controller walk the graph — each block runs its wired residual over its live-in registers, commits its writes to the file, and its terminator predicate picks the successor — until a block returns. Equals the VM interpreting the same function (proven by `fabric_cfg_lock`). - [fn eval_program_cfg_fabric_traced](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.eval_program_cfg_fabric_traced): The same walk, reporting the returned value AND the sequence of values SHOWN along the path taken. - [fn eval_seq_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.eval_seq_program): The faithful MODEL of the whole-program SEQUENCED fabric (`emit_seq_program_verilog`): walk blocks by a PC, evaluating each block’s cells in order (threading ONE shared heap = the state plane) and taking the terminator (Jump/Branch/Return), exactly as the block-walk FSM does in RTL. This is the sequenced fabric’s own oracle — distinct from `run_program_cfg_on_grid` (which models the GRID realization and cannot place a looping heap body). Bit-identical to the VM’s `Int` for a lowered program. `budget` bounds the block walk (a loop that never returns panics, catching a lowering back-edge bug — never a silent hang). - [fn eval_while_fabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.eval_while_fabric): Evaluate the while-CGRA: initialise the state, then WHILE the fabric predicate holds apply the body and latch. 64-bit wrapping — the VM’s `Int` mod 2⁶⁴. A guard bounds non-termination. - [fn eval_whole_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.eval_whole_program): Run a whole-program fabric to its output tape — each `Show`n value RENDERED as the VM would print it: a text char-list decoded to its string, an Int as decimal. The strings are compared to the VM’s stdout lines. - [fn fabric_to_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.fabric_to_bounded): Lower a residual op-list to a `BoundedExpr` (bit-vector datapath) at the given width — the bridge that lets our certified SAT reason about the emitted circuit exhaustively. - [fn function_op_names](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.function_op_names): The op mnemonics a function’s decision body USES (entry `..` first `Return`) — the SAME segment `decision_fabric_from_source` lowers. This is the ground truth for “which ops a fabric built from this function actually exercises”, so a coverage-corpus program’s realized-op claim is welded to a program that genuinely contains the op (not merely declared). - [fn loop_cell_delay](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.loop_cell_delay): The logic depth of one body tile in the pipelined loop’s stage budget, in units of a 64-bit add. - [fn loop_fabric_from_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.loop_fabric_from_source): The genuine Futamura P1 lowering for a counted loop. Compile `src`, recover the range loop in function `fn_name` (a counted header and its unit step, or `NewRange`/`IterPrepare`/`IterNext`, and the back-edge `Jump`), and lower it to a `LoopFabric`: the loop-carried accumulators (state), the induction variable, the loop invariants, and the straight-line body (SSA). Panics on any shape outside the counted range-loop family (the honest boundary — nested loops / data-dependent exits are future work). - [fn loop_next_to_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.loop_next_to_bounded): Lower ONE loop-carried state register’s next-state (`next[which]`) to a `BoundedExpr` over the body inputs `s0..`, `iv`, `inv0..` at the given width — so our certified SAT can prove the induction STEP (the body transition ≡ the VM’s per-iteration semantics) exhaustively. - [fn nested_fabric_from_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.nested_fabric_from_source): Recover the perfectly-nested loop in `fn_name` and lower it to a `NestedFabric`. - [fn nested_inner_next_to_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.nested_inner_next_to_bounded): Lower ONE inner-body state register’s next-state to a `BoundedExpr` over `s0..`, `ij`, `oi`, `inv0..` — for the certified inner body step (the base of the double induction). - [fn poly_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.poly_program): The full program, with `Main` chosen by the caller (`Show poly(N).`). - [fn program_cfg_fabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.program_cfg_fabric): Panicking wrapper preserving the original contract for all existing callers: lowers `fn_name`’s CFG to a whole-program fabric, or panics with the same message the old code did. New code that wants to handle an unsupported construct gracefully should call `try_program_cfg_fabric`. - [fn residual_from_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.residual_from_source): The genuine Futamura P1 lowering. Compile `src` with the real compiler, take the straight-line register bytecode of function `fn_name` (its dispatch-free residual), and lower it register→SSA to a dataflow op-list. Parameters become circuit inputs; `LoadConst` becomes a baked-in constant; `Add/Sub/Mul` become wired functional units. Also returns the input arity (parameter count). Panics on a non-straight-line op (control flow / unsupported) — the honest boundary of this block. - [fn try_emit_seq_datapath_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.try_emit_seq_datapath_verilog): Graceful entry to a single sequenced decision datapath: `Ok(rtl)` when every cell is register-only, or `Err(StatePlaneUnlowered)` for a heap-reading fabric (which belongs on the state-plane emitter). The typed companion to `emit_seq_datapath_verilog`. - [fn try_emit_seq_program_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.try_emit_seq_program_verilog): Graceful entry to the whole-program sequenced fabric: `Ok(rtl)` when every block lowers (register tiles + the shared state plane for Seq/string programs), or `Err(StatePlaneUnlowered)` for the residual `MemRead` loop-sequence form. The typed companion to the panicking `emit_seq_program_verilog`. - [fn try_main_cfg_fabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.try_main_cfg_fabric): Lower the top-level `## Main` through the CFG engine. - [fn try_program_cfg_fabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.try_program_cfg_fabric) - [fn while_fabric_from_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.while_fabric_from_source): Recover the `while` loop in `fn_name` and lower it to a `WhileFabric`. The header (the back-edge target) computes the continue predicate; the body (to the back-edge) if-converts. - [fn while_next_to_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.while_next_to_bounded): Lower ONE while-body state register’s next-state to a `BoundedExpr` (over `s0..`, `inv0..`) for the certified body step. No induction variable in the body-input convention. - [fn whole_program_fabric_from_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.whole_program_fabric_from_program): Lower an already-COMPILED program to a whole-program fabric. Shared by the source path and by the HAND-AUTHORED-bytecode witnesses (`codegen_sva/rtl.rs`’s precedent): the reversible ALU ops (`RevXor`/`RevNeg`/`RevAdd`/`RevSub`) and the scheduler/CRDT-internal ops (`ChanClose`/`CrdtJoin`) that no LOGOS source emits are still real ISA ops the soft-core executes, so their fabric tile is proven by building a raw `CompiledProgram` (op + `Show`) and differencing the fabric tape against the VM oracle (`Vm::new(&prog).run(); vm.output()`) — never a hand-coded golden. Hand-authored bytecode carries no `PolicyRegistry`, so it runs with NO modeled conditions (a `CheckPolicy` in it would refuse loudly). - [fn whole_program_fabric_from_source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.whole_program_fabric_from_source): Lower a program’s `Main` (`code[0..]` up to its terminating `Halt`) to a whole-program fabric. STRAIGHT-LINE only: a top-level branch would make a `Show` conditional, which the combinational output tape cannot honor, so it is refused loudly. Calls inside Main inline normally (their branches if-convert). - [fn whole_program_op_names](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.whole_program_op_names): Like `function_op_names`, but scans the WHOLE compiled program — all functions plus the module-init prologue. Used to weld coverage for a compiler-emitted op that a user function never directly contains: `NewCrdt` is emitted in a `Shared` struct’s default-fill, which runs in global struct-init, not the user function’s own op stream. So `function_op_names(f)` cannot surface it; this can. - [fn with_seq_reserve](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_rtl/fn.with_seq_reserve): Run `f` with the per-collection reserve set to `n` (restored after). Use a small `n` for a program that fills its collections sequentially (e.g. the whole-transformer fabric engine) to right-size its heap. ## logicaffeine_compile::codegen_sva::fabric_soc fabric_soc — Phase E: the FLASHABLE reconfigurable-fabric SoC. - [const CFG_WIDTH](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/constant.CFG_WIDTH) - [const FABRIC_SOURCES](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/constant.FABRIC_SOURCES): The fabric SoC’s program corpus — the datapaths the ONE reconfigurable array can become, selected by the config word. Single-final-`Return` + conditional-`Set` style so branches if-convert to select tiles. - [const FLOAT_SOC_NAME](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/constant.FLOAT_SOC_NAME) - [const FLOAT_SOC_SRC](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/constant.FLOAT_SOC_SRC): The flashed float kernel: `fhypf(a,b) = sqrt(a*a + b*b)` — the Euclidean hypotenuse as a Real. Exercises the full float lane: `fp_mul` (twice) + `fp_addsub` + `fp_sqrt`. It returns a FLOAT (not floored) so the SoC streams the raw f64 bits — the host floors to the integer hypotenuse (no float→int RTL needed on-chip). - [const N_IN](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/constant.N_IN): The SoC’s input-port count — the max arity over the corpus (`clamp` has three). Functions with fewer inputs ignore the extra ports (their tiles never reference them). - [const STATE_SOC_NAME](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/constant.STATE_SOC_NAME) - [const STATE_SOC_SRC](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/constant.STATE_SOC_SRC): The flashed state-plane kernel: `grade(a,b,c)` is a WHOLE MULTI-OP-CLASS program — it builds the list `[a,b,c]` on the heap (COLLECTIONS), sums its elements (ARITHMETIC), and clamps the total to `[0, 100]` (CONTROL FLOW — two if-converted branches). So the flashed datapath exercises three distinct op-classes at once — Mem (HeapAlloc/Write/Read) + Arith (adds) + Select (the clamps) — all in ONE sequenced datapath on silicon: the fabric running a real program, not a single op. - [const WIDTH](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/constant.WIDTH): The datapath / config-word widths (8-bit datapath for the SAT proof; 3-bit config indexes ≤ 8 datapaths). - [fn emit_config_grid](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.emit_config_grid): The reconfigurable array RTL (`config_fabric`): ONE tile grid becoming any corpus datapath under `cfg`. - [fn emit_fabric_soc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.emit_fabric_soc): The flashable SoC: registered `(cfg, inputs)` in, the combinational `config_fabric`, a `cycles` counter, and registered `(result, cycles, done)` out. On `rst` release the array’s output settles in one clock; the SoC latches it, sets `cycles = 1` (the honest cost of a spatial decision), and raises `done`. Synthesizable as-is — the inputs wire to switches / a UART loader and the outputs to LEDs / a UART readback for bring-up. - [fn emit_fabric_soc_tb](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.emit_fabric_soc_tb): The self-checking testbench: drive the SoC over `(cfg, inputs)` vectors and `$display` `cfg result cycles` per vector. `fabric_soc_lock` parses these and checks each result ≡ the VM and each cycle count == 1. - [fn emit_float_soc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.emit_float_soc): The SIMPLE float SoC (`float_soc`) for the iverilog proof: `float_` under a CYCLE COUNTER, exposing the f64 `result` bits / `cycles` / `done`. A testbench presents float bit-patterns and reads the result. - [fn emit_float_soc_module](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.emit_float_soc_module): The sequenced float datapath RTL (`float_fhypf`) — the fpu.v-bound micro-sequencer for the kernel. - [fn emit_float_soc_tb](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.emit_float_soc_tb): A self-checking testbench for `float_soc`: drive each float pair (bit-patterns), run to `done`, and `$display(\"result_hex cycles\")`. `float_soc_lock` runs it under iverilog (with fpu.v) and checks each result’s f64 bits ≡ the model/Rust and each cycle count > 1. - [fn emit_nexys_fabric_soc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.emit_nexys_fabric_soc): Emit the BOARD-FLASHABLE top (`nexys_fabric_soc`) for the Nexys A7-100T: the reconfigurable `config_fabric` array, a baked-in vector ROM, and a settle sweep that measures on the chip how many clocks each datapath takes. For every vector the sweep loads a prime into the launch register, lets it settle, launches the vector and captures the array’s output `L` clocks later, for `L` from `LMAX - 1` down to 1, under two primes (the vector’s inputs inverted, and the next vector), `REPS` times. The settled value is the capture at `2·LMAX`; a result is settled inside the window only when the capture at `LMAX` already equals it under both primes. The streamed cycle count is the smallest `L` from which every capture equals the settled value, the worst over the repetitions, and 0 when the result did not settle inside the window. Each record goes out the UART TX as `(sync, cfg, result[8], cycles[2])`; a host checks each result against the VM. 100 MHz board clock, 115200 baud (CLKS_PER_BIT = 868). Pins in `nexys_fabric_soc.xdc`. - [fn emit_nexys_fabric_xdc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.emit_nexys_fabric_xdc): The board pin constraints for `nexys_fabric_soc` (Nexys A7-100T): 100 MHz clock (E3), reset (J15), UART TX (D4), status LEDs. No `uart_rx` — the vector ROM is baked in, so the SoC only streams out. - [fn emit_nexys_float_soc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.emit_nexys_float_soc): The FLASHABLE float SoC (`nexys_float_soc`) for the Nexys A7-100T: a baked-in `(a,b)` float ROM drives `float_` — pulse the datapath reset, wait `done` (counting the FPU pipeline cycles), capture the f64 result, and stream the 12-byte record `{0xA5, vec, result[63:0] MSB-first, cycles[15:0]}` out the UART TX, looping forever. The host decodes the f64 and floors it to the integer hypotenuse. 100 MHz; 8N1 115200. - [fn emit_nexys_float_xdc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.emit_nexys_float_xdc): The Nexys A7-100T pin constraints for `nexys_float_soc` — same ports as the fabric SoC, same pin map. - [fn emit_nexys_state_soc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.emit_nexys_state_soc): The FLASHABLE state SoC (`nexys_state_soc`) for the Nexys A7-100T: a baked-in `(a,b,c)` vector ROM drives `state_` — pulse the datapath reset, wait `done` (counting the multi-cycle latency), capture the result, and stream the 12-byte record `{0xA5, vec, result[63:0] MSB-first, cycles[15:0]}` out the UART TX, looping forever so a host can frame-lock at any time. 100 MHz; 8N1 115200 (CLKS_PER_BIT=868). - [fn emit_nexys_state_xdc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.emit_nexys_state_xdc): The Nexys A7-100T pin constraints for `nexys_state_soc` — identical ports to the fabric SoC (100 MHz clk, reset, UART TX, LEDs), so the same pin map. - [fn emit_state_soc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.emit_state_soc): The SIMPLE state SoC (`state_soc`) for the iverilog proof: it wraps `state_` with a CYCLE COUNTER (cycles from reset-release to `done`) and exposes `result`/`cycles`/`done`. A host/testbench presents `(a,b,c)`, pulses `rst`, and reads back the multi-cycle result — the board-independent ≡VM proof surface. - [fn emit_state_soc_module](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.emit_state_soc_module): The sequenced state-plane datapath RTL (`state_grade`) — the LUTRAM-heap micro-sequencer for the kernel. - [fn emit_state_soc_tb](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.emit_state_soc_tb): A self-checking testbench for `state_soc`: drive each `(a,b,c)` vector, pulse `rst`, run until `done`, and `$display(\"result cycles\")`. `state_soc_lock` runs it under iverilog and checks each result ≡ the VM and each cycle count > 1 (a sequenced state program, not a 1-clock combinational decision). - [fn fabric_grids_json](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.fabric_grids_json): The placed-and-routed tile arrays as JSON — the source of truth for every technical drawing of the fabric, so a drawing of a tile array is the placer’s own output, never hand-drawn. Contains the five `config_fabric` islands (the 8×3 array that runs 14/14 vectors on both boards) and the Horner cubic residual on both placers (the diagonal `route_straight_line` behind `grid_horner.v`, and the area-minimizing `route_leveled`). Pinned to `benchmarks/silicon/fabric_grids.json` by `fabric_grids_lock`. - [fn float_soc_vectors](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.float_soc_vectors): The `(a, b)` float pairs the float SoC runs on silicon → each hypotenuse (mostly Pythagorean integers). - [fn state_soc_vectors](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.state_soc_vectors): The input battery the state SoC runs on silicon (each a `(a,b,c)` triple → `clamp(a+b+c, 0, 100)`). Chosen to exercise the pass-through, the UPPER clamp (sum > 100), and the LOWER clamp (sum < 0) — so the control flow is genuinely taken on hardware, not just present. - [fn table](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.table): The compiled config table (padded islands on one array). The single source of truth for the RTL and the testbench’s expected values — both derive from it, never hand-typed. - [fn vectors](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_soc/fn.vectors): The test vectors the testbench drives — a battery per datapath, spanning each function’s cases. Kept in sync with `fabric_soc_lock`’s expected computation (both iterate this same list). ## logicaffeine_compile::codegen_sva::fabric_target fabric_target — the ADL spine: a `FabricTarget` descriptor + `place_with_target`. - [struct FabricTarget](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_target/struct.FabricTarget): A described fabric — the ADL. One certified lowering (`place_with_target`) retargets across shapes by varying this descriptor; each setting is either provably `≡VM` or refused with an `Unplaceable`. - [struct MemHierarchy](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_target/struct.MemHierarchy): The on-/off-chip memory hierarchy a target provides, in the SN40L three-tier shape (Phase 5). - [struct SiliconSpec](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_target/struct.SiliconSpec): Real-silicon facts about a physical target that do not map onto the placement fields (which model the per-datapath array). Present only for a target backed by a real chip; `None` for the abstract presets. Every value must be a published spec cited at the constructor — this is descriptor metadata, not a claim we place. - [enum Capability](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_target/enum.Capability): A capability a program cell requires from a target — the unit of the ADL’s typed refusal. - [enum Dataflow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_target/enum.Dataflow): The GEMM dataflow a target realizes. `Reduction` is the universal baseline — the 1-D dot-product MAC lane every fabric ships today; `WeightStationary` / `OutputStationary` are the 2-D systolic modes (Phase 1+). - [enum MemTier](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_target/enum.MemTier): A tier of the memory hierarchy a schedule demands (Phase 5). - [enum Precision](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_target/enum.Precision): A numeric format a target’s compute realizes (the precision dial, Phase 4). - [enum Unplaceable](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_target/enum.Unplaceable): Why a program cannot be placed on a given target — a TYPED refusal, never a silently-wrong grid. - [const ALL_ALU_OPS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_target/constant.ALL_ALU_OPS): Every combinational ALU op the fabric places (the `AluOp` universe). - [const ALL_FUNC_UNITS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_target/constant.ALL_FUNC_UNITS): Every sequential functional unit the fabric places (the `FuncUnit` universe). - [fn compile_to_config_table_on_target](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_target/fn.compile_to_config_table_on_target): Compile a whole program corpus onto ONE described array: if-convert each `(source, function)` to a decision island and place it THROUGH `target`, so every island shares the described shape. The resulting `ConfigTable` is certifiable by `super::fabric_config::certify_config_table` — `config == k ⇒ the described array ≡ island k`, for ALL inputs — the ADL’s retarget-a-corpus-onto-a-chosen-shape payoff. Returns a typed `Unplaceable` if any datapath needs a capability the target lacks or does not fit. - [fn place_with_target](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_target/fn.place_with_target): Place a dataflow body onto a DESCRIBED target: gate every cell against the target’s capability set, place with the certified `route_loop_body`, gate the placed shape against the described array, then pad onto it. Returns the placed+padded `Grid`, or a typed `Unplaceable` — a correct grid or a named refusal. ## logicaffeine_compile::codegen_sva::fabric_tile fabric_tile — the SINGLE SOURCE OF TRUTH for “which ISA ops the spatial fabric realizes”. - [enum FabricTile](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_tile/enum.FabricTile): The fabric tile an `Op` lowers to. A compute tile (`Alu`/`Cmp`/`Func`) has independently-fuzzable datapath semantics and MUST carry an `eval == VM` witness in the coverage lock; a structural tile (`Wire`/`Control`) is realized by the fabric framework itself (a route, a const, a controller edge) and is exercised by every fabric, so it carries no standalone fuzz witness. - [fn fabric_coverage](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_tile/fn.fabric_coverage): The fraction of the ISA the fabric datapath realizes (the rest runs on the interpreter fallback). Ratchets toward 1.0 as the campaign lowers each op category. - [fn fabric_realized_ops](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_tile/fn.fabric_realized_ops): The mnemonics of every op the fabric realizes today — the ground-truth “covered” set for the ratchet. - [fn fabric_tile](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_tile/fn.fabric_tile): THE authority: the fabric tile this op lowers to, or `None` when it still falls back to the interpreter. As the campaign lowers each op category, its arm moves from `None` into a `Some(tile)` here — and the coverage lock then demands its equivalence witness before the floor can rise. - [fn frontier_reason](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_tile/fn.frontier_reason): Why the fabric has no realization of an op on the interpreter-fallback frontier — `None` for every realized op, and `None` for a frontier op nobody has explained, which the coverage locks refuse: an op is tiled or it states its reason, there is no third state. A lane that meets one of these ops refuses the program with this sentence, never a silently dropped op. - [fn hosted_ops](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fabric_tile/fn.hosted_ops): The realized ops a described target’s envelope HOSTS: every op whose tile’s capability the descriptor provides (a structural tile is hosted everywhere). One descriptor’s column of the coverage ratchet — `rdu_op_coverage_lock` pins it for the SN50 exactly, so a capability lost on the descriptor is as red as a tile lost on the fabric. ## logicaffeine_compile::codegen_sva::fanout fanout — the pit-of-success primitive for antenna-safe wide selects. - [fn bounded_fanout_select](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fanout/fn.bounded_fanout_select): Emit a fan-out-bounded image of the one-bit select `sel_expr ? data_wire : 0` over `width` bits, sliced into `slice` groups. ## logicaffeine_compile::codegen_sva::floorplan Floorplans read off a fitted build: a Logic Lock region for each instance named, a square beside the site its clock comes from, as small as what the instance needs at the parent region’s density allows, inside the parent region. - [struct Anchor](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/struct.Anchor): Where an instance’s clock comes from: the instance, the clock its paths run on, and the site that clock leaves (a memory channel’s, its bank’s IO tile control). - [struct Anchors](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/struct.Anchors): The anchors ledger (`benchmarks/silicon/d5005/emif_anchors.json`): what it holds, the build whose reports placed the anchors, the day they were recorded, and the anchors. - [struct Assignment](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/struct.Assignment): One region: the instances it holds, the name Quartus gives it, its rectangle. - [struct Capacity](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/struct.Capacity): What a tile holds, as the fitter counted it. - [struct Density](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/struct.Density): A region’s resources a site: its ALMs and its M20Ks over its sites. - [struct Fill](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/struct.Fill): How much of a region a unit may take of each resource: of its logic (ALMs and registers), the rest room for the router and for the logic that shares the region; of its M20Ks and its DSP blocks, hard blocks that need no such room. - [struct Geometry](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/struct.Geometry): The device’s capacity map, as a probe’s fit counted it: each tile and what it holds. - [struct Need](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/struct.Need): What an instance needs of a region: its ALMs needed and its M20Ks. - [struct Needs](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/struct.Needs): What a unit needs placed. - [struct Ram](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/struct.Ram): A memory as synthesis left it: its path, the block it asked for (`AUTO`, `M20K block`, `MLAB`), each port’s depth and width, its byte enables’ byte when it has them, and whether a read on one port during a write on the other must give the old data. - [struct Rect](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/struct.Rect): A rectangle of sites, both corners inclusive. - [struct Region](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/struct.Region): A unit’s region of whole tiles: the instance, its name, its tiles in the map’s order (top row first, then left). - [struct Unit](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/struct.Unit): A unit the floorplan places: the instances its one region holds, the region’s name, what they need together. - [enum AnchorError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/enum.AnchorError): Why a build’s reports place no anchor for an instance. - [enum PlaceError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/enum.PlaceError): Why a floorplan places no region. - [enum Wire](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/enum.Wire): A bus the floorplan keeps short, weighted by its width in bits: between two units, by their index, or between a unit and a fixed site. - [fn anchor](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.anchor): The anchor of `instance` from a fitted build’s reports: the clock its setup paths run on (`instance_clock`), that clock’s targets in the clock table, and the fast signal of the place report those targets come from (`clock_site`). - [fn candidates](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.candidates): Every rectangle of whole tiles of `geometry` that holds `needs` at `fill`, overlaps none of `blocked`, is no longer than `aspect` times its width in sites, and is least: no rectangle a tile row or column smaller inside it holds the needs too. In order of their top row, then left column, then size. - [fn clock_site](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.clock_site): The site a clock comes from: the fast signal sharing one of its targets’ deepest hierarchy, or none when no fast signal shares any level or two share the deepest. - [fn clock_targets](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.clock_targets): Every clock of the timing analyzer’s `Clocks` table with its target cells. - [fn device](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.device): The device’s sites: the route region of the fit report’s `Logic Lock Region Constraints`, the whole core a flat build may place in. It is a row’s last cell: the place region before it separates its rectangles with the table’s own `;`. - [fn fabricless](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.fabricless): The tiles a probe’s fit found no flip-flop in: each region its log refuses as needing a flip-flop where there are none (`Deterministic overuse of FF resources in region (x0,y0) to (x1,y1)`), a tile of the device with no logic (hard IP, the core’s edge), which the next probe leaves out and no floorplan places a region on. - [fn fast_signal_sites](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.fast_signal_sites): Every net of the fit report’s `Global & Other Fast Signals Summary` with the site it is driven from. - [fn grow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.grow): The floorplan of `units` in regions of whole tiles, each unit in the order given. Its seed is the free tile where its wires are shortest (each wire’s width times the straight distance from the tile’s centre to the centre of the unit at its other end, placed before it, or to its fixed site), among the free tiles of an area that holds it at `fill`, the top row and left column first on a tie. The region then takes, one at a time, the free tile beside it nearest the centre of its sites so far (then where the wires are shortest, then the top row and left column) until it holds the unit, so it grows as compact as the tiles allow and bends round what is taken. A tile is free when no region before it took it and it overlaps nothing `blocked`. A unit no free area holds is refused by name. - [fn holds](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.holds): Whether a region of `capacity` holds a unit of `needs` at `fill`: each resource the unit needs within its share of the region’s. - [fn instance_clock](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.instance_clock): The clock an instance runs on: the latch clock of the most setup paths in the timing report whose both ends lie inside it, none when no path does or two clocks tie. - [fn instance_need](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.instance_need): An instance’s need as the fit report’s `Fitter Resource Utilization by Entity` states it (its totals, itself and everything under it). - [fn loose](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.loose): The instances of `graph` no unit of `units` holds, each with the bits its links carry to the units’ instances, heaviest first (then by path), those carrying none left out: a path between two units through an instance no unit holds is no wire of the floorplan’s (`unit_wires` counts links between units’ instances alone) until its module is dissolved into the graph (`netlist::module_graph`’s `through`). - [fn m20k_blocks](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.m20k_blocks): The M20K blocks a memory of `depth` words of `width` bits takes: the fewest over the block’s simple-dual-port shapes (512 × 40, 1,024 × 20, 2,048 × 10), as many blocks side by side as its width needs and stacked as its depth does, the stack a power of two deep (the fitter decodes it by the address’s top bits). - [fn parent_region](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.parent_region): The parent region a build’s floorplan lies in: the rectangles of its one Logic Lock region (a partial reconfiguration build’s persona), with that region’s density. - [fn place](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.place): The floorplan of `units`, each in the order given at its candidate of least cost: the width of each of its wires to a unit placed before it or to a fixed site, times the straight distance between centres, so a unit sits where its wires meet; a candidate overlaps no unit placed before it nor `blocked`. Ties go to the smaller perimeter (the more compact region), then area, then the top row and left column. A unit no candidate holds is refused by name. - [fn probe](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.probe): The geometry probe for `tiles`: a design of one register cell a tile (`c`), and the Logic Lock region pinning each cell to its tile (`geo_`), so a fit of it reports every tile’s capacity in its region usage. - [fn region](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.region): The square that holds `need` at `fill` of `density`, every site of it in `parent`, nearest `anchor`: the least side whose sites hold the need, then of its placements the one nearest the anchor (Chebyshev), then the one whose centre is nearest, then the lowest. None when no placement of that side fits, or the density holds none of what is needed. - [fn region_name](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.region_name): A Logic Lock region’s name for an instance path: `logos_` and the path, its levels and a generate block’s scope parted by `_`, an index’s brackets dropped (`ch[0].channel` is `logos_ch0_channel`). - [fn regions_tcl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.regions_tcl): The regions as Quartus settings: each a `PLACE_REGION` of its rectangles (`Region::rects`), its own name, core sites only, shared with the rest of the design. - [fn site](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.site): The site of a location the fitter names, `TILECTRL_X233_Y36_N2` its (233, 36). - [fn synthesized_needs](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.synthesized_needs): What the instances `members` need placed together as Quartus synthesized them, from the synthesis report `syn`: the entity table’s ALUTs, registers and DSP blocks of each member’s whole subtree summed, those ALUTs and registers in ALMs at `packing` packed as one (the fitter packs one member’s registers beside another’s LUTs), and the M20K blocks the fitter gives every memory under any of them (`Ram::m20k`). The member the entity table does not name, when one is missing. - [fn synthesized_rams](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.synthesized_rams): Every memory of the synthesis report’s RAM summaries (one a partition), each with what its inferred parameter section (`Parameter Settings for Inferred Entity Instance: `, the path its name continues) says of its byte enables and of a read across its ports; a memory no section names has neither. - [fn tcl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.tcl): The assignments as Quartus settings: each region a `PLACE_REGION` of every instance it holds, under its one name, core sites only, shared with the rest of the design. - [fn tiles](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.tiles): The device cut into tiles of `width` columns by `height` rows from its corner, row by row, the last of each row and column clipped to the device. - [fn unit_floorplan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.unit_floorplan): The floorplan of `units` in rectangles (`place`) on the wires `unit_wires` reads off the module’s graph. - [fn unit_regions](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.unit_regions): The floorplan of `units` in regions of whole tiles (`grow`) on the wires `unit_wires` reads off the module’s graph. - [fn unit_wires](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/floorplan/fn.unit_wires): The units a floorplan places and its wires, from a module’s graph: each of `units` (its instances paths under the module `graph` was read from, its region’s name, what its instances need together) placed under `under` (the module’s own path in the build); a wire between two units of the bits the graph counts between an instance of the one and an instance of the other (bits between two instances of one unit stay inside its region); and from a unit to an anchor (matched by an instance’s full path) of the bits that instance shares with the module’s ports, the way out to the anchor. Refused by name: an instance the module lacks, a unit of none, an instance two units hold, and two units of one region name. ## logicaffeine_compile::codegen_sva::flow_config `flow_config` — the compiler emits its own physical-design configuration. - [struct ClosureSettings](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/flow_config/struct.ClosureSettings): The electrical-closure settings, separated from the rest because they are the ones that were actually measured and the ones a future change is most likely to get wrong. - [struct DesignProfile](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/flow_config/struct.DesignProfile): What the compiler knows about a design that changes how it should be built. - [struct VehicleMacro](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/flow_config/struct.VehicleMacro): A macro hardened to sit INSIDE a shuttle vehicle’s wrapper — the Caravel user macro. - [enum AntennaStrategy](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/flow_config/enum.AntennaStrategy): How antenna violations are to be closed. These are NOT interchangeable, and choosing wrongly costs slew. - [enum MacroGrid](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/flow_config/enum.MacroGrid): How a vehicle user macro takes power from the wrapper around it, which decides how high it may route. - [enum SynthStrategy](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/flow_config/enum.SynthStrategy): One of OpenLane’s `SYNTH_STRATEGY` scripts: `AREA 0..=3` or `DELAY 0..=4`. - [const COMPARATIVE_HOLD_MARGIN_NS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/flow_config/constant.COMPARATIVE_HOLD_MARGIN_NS): The hold repair’s margin for a comparative block (`ClosureSettings::comparative`) whose caller gives none. The repair judges hold at the typical corner on estimated parasitics, and signoff checks every corner on extracted ones. MEASURED on the bench’s first fold-wrapped attempts: `qorsyn_k1_bambu_pipe_c_a7p10_p32_5` (RUN_2026.10.17_01.20.19) met hold by +0.09 ns at the typical corner after OpenLane’s 0.05 ns repair, and missed it by 0.04, 0.05 and 0.04 ns at the fastest corner on the min, max and nominal RC corners, a 0.14 ns gap; `qorsyn_k1_bambu_fsm_c_a7p10_p20_5` missed it by 0.03 ns the same way. One margin serves every candidate of a comparison, so it covers that gap with room: 0.19 ns would close it exactly. - [const COMPARATIVE_SYNTH_STRATEGY](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/flow_config/constant.COMPARATIVE_SYNTH_STRATEGY): The synthesis script of a comparative block (`ClosureSettings::comparative`) whose caller names none. OpenLane hands abc the clock period as its target, and an area script recovers area down to it, so a run at a period longer than the design needs closes a netlist slower than the design: the period it closes at says more about the period it was given than about the design. A delay script maps every candidate for speed. MEASURED by the clock-push search over the signed blocks under DELAY 0 (logs/clock-push, 10-17): decision_hft_bist 15.0 -> 4.4 ns, dram_executor 10.5 -> 5.0, cgra_sumto 18 -> 6.4, rev_alu_core 14.5 -> 7.7. - [fn openlane_config](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/flow_config/fn.openlane_config): Emit the OpenLane `config.json` for a design on a process. - [fn parse_wire_limit_um](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/flow_config/fn.parse_wire_limit_um): A wire limit as the flow scripts spell it: a length in um, or `openroad` for OpenROAD’s own limit, emitted as 0, which OpenLane reads as unset. A bare 0 is refused, so no typo drops a limit. - [fn vehicle_macro_config](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/flow_config/fn.vehicle_macro_config): The config for a vehicle user macro, or a refusal when the process’s vehicle has not been read. - [fn vehicle_macro_sdc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/flow_config/fn.vehicle_macro_sdc): The constraints a vehicle user macro is timed with: OpenLane’s own `base.sdc`, then the vehicle’s timing as it characterizes it (`HarnessTiming`) — the clock model the chip is signed off with, and every synchronous harness input’s minimum delay. ## logicaffeine_compile::codegen_sva::fol_to_sva FOL → SVA Formal Synthesis - [struct SynthesizedSva](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fol_to_sva/struct.SynthesizedSva): Result of SVA synthesis from a specification. - [fn synthesize_sva_from_spec](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fol_to_sva/fn.synthesize_sva_from_spec): Synthesize an SVA property from an English specification. ## logicaffeine_compile::codegen_sva::fol_to_verify FOL → Bounded Verification IR Translation - [struct FolTranslator](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fol_to_verify/struct.FolTranslator): Translator from Kripke-lowered FOL to bounded timestep model. ## logicaffeine_compile::codegen_sva::fp_hard The engine’s f32 multiply and add on the card’s floating-point DSP block (`fourteennm_fp_mac`), as the oracle (`super::fp_oracle`) measured it: a wrapper with the pipelined unit’s ports (`logos_fmul_p`’s and `logos_fadd_p`’s: `clk`, `a`, `b`, `y`) and exactly its latency, computing the engine’s own arithmetic (`Semantics::ENGINE`) on a block whose semantics are another member of the family, wherever a thin layer of logic around the block can make them one. - [struct Block](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/struct.Block): What the oracle measured of one mode of the block: the semantics it computes and its latency fully registered and with its output register alone. - [struct Measurement](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/struct.Measurement): What the card said of its block: each mode’s semantics and depths, the multiply-add’s latency and rounding. - [struct Plan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/struct.Plan): A wrapper’s build: the block’s registering, the registers after it, and what the logic around it corrects. - [struct Tally](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/struct.Tally): One mode’s counts as the measurement found them: each class’s steps differing from the block over every run, in the oracle’s order, and the steps no class explains. - [enum HardError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/enum.HardError): Why a block cannot be the engine’s unit. - [enum MeasureError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/enum.MeasureError): Why a measurement names no block. - [enum Op](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/enum.Op): The two operations a block computes for the engine. - [enum Registering](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/enum.Registering): How the block is registered in a wrapper. - [enum Rounding](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/enum.Rounding): How the block’s multiply-add rounds. - [fn hard_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/fn.hard_verilog): The wrapper `module` for the block’s `op` at `latency` clocks, free-running. - [fn hard_verilog_ce](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/fn.hard_verilog_ce): The wrapper `module` for the block’s `op` at `latency` steps, every register (the block’s and the pads) stepping where `step_en`, as the engine’s enabled cores step. - [fn hard_verilog_ce_for](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/fn.hard_verilog_ce_for): `hard_verilog_ce` computing `target` (`plan_for`): `hard_verilog_ce` is this of `Semantics::ENGINE`, byte for byte. - [fn hard_verilog_for](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/fn.hard_verilog_for): `hard_verilog` computing `target` (`plan_for`): `hard_verilog` is this of `Semantics::ENGINE`, byte for byte. - [fn plan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/fn.plan): The wrapper’s build for the block’s `op` at `latency` clocks, standing in for the engine’s own arithmetic (`plan_for` of `Semantics::ENGINE`). - [fn plan_for](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hard/fn.plan_for): The wrapper’s build for the block’s `op` at `latency` clocks that makes it compute `target`: the logic around it flushes the denormal operands the block reads as themselves where `target` reads zeros, flushes the denormal results the block keeps where `target` flushes them at the denormals’ place keeping their sign, and writes `0x7fc00000` for every NaN where that is `target`’s one NaN and the block’s is another. Refused by name is a block that reads a zero or flushes a result where `target` keeps a denormal, decides tininess elsewhere than `target`, flushes to another sign, or returns NaNs `target` does not and the wrapper cannot write. ## logicaffeine_compile::codegen_sva::fp_hypotheses Binary32 multiply and add under a family of semantics: the hypotheses a hard floating-point block is told apart by. - [struct Semantics](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hypotheses/struct.Semantics): One choice of everything IEEE 754 leaves to an implementation of binary32 multiply and add. - [enum Denormals](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hypotheses/enum.Denormals): How a denormal is read or written. - [enum FlushSign](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hypotheses/enum.FlushSign): The sign of a result flushed to zero. - [enum Nan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hypotheses/enum.Nan): The NaN an operation returns. - [enum Tininess](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hypotheses/enum.Tininess): Where a result below the least normal is decided to be one. - [const NANS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hypotheses/constant.NANS): The NaN encodings the family tries: four canonical NaNs, the first NaN operand’s payload with either default NaN for an invalid operation (an ARM core’s positive one, an x86 core’s negative one), and the default quiet NaN signed by the operands’ signs’ exclusive or (the D5005’s floating-point DSP block’s multiply). - [const SPECIALS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hypotheses/constant.SPECIALS): The operands every pair of which a hard block is first measured on: signed zeros, the denormals’ ends, the normals’ ends, one, infinities, quiet and signalling NaNs, a mid denormal and one above one. - [fn fadd_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hypotheses/fn.fadd_verilog): A combinational binary32 add under `s`, ports `a`, `b`, `y`. - [fn family](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hypotheses/fn.family): Every member: each choice of operand denormals, result denormals, tininess, flushed sign and NaN, the meaningless combinations folded away; `Semantics::ENGINE` first. - [fn fmul_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_hypotheses/fn.fmul_verilog): A combinational binary32 multiply under `s`, ports `a`, `b`, `y`. ## logicaffeine_compile::codegen_sva::fp_oracle The hard floating-point oracle: a D5005 persona that measures which binary32 semantics the card’s floating-point DSP block computes (`fourteennm_fp_mac`, whose simulation model is encrypted), by running the block beside every class of the hypothesis family (`super::fp_hypotheses`) as soft units on one stream of operands and counting, class by class, the results that differ from the block’s. - [struct Class](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/struct.Class): A class of the family: its members’ names (all one function, proven), and the semantics of the first, which the oracle builds. - [struct Depths](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/struct.Depths): How many steps deep a stand-in block is: fully registered, the multiply, the add and the multiply-add; with its output register alone, the multiply and the add. - [struct Header](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/struct.Header): The store’s header. - [struct Oracle](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/struct.Oracle): What the oracle is built from: the classes of the multiply and of the add, and the vectors its ROM holds. - [struct Record](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/struct.Record): A record: the operands, the three hard results and their flags (bits 3:0 the multiply’s {inexact, invalid, overflow, underflow} and 7:4 the add’s, of each block), which classes agree with the block, and the least-registered blocks’ results. - [struct Run](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/struct.Run): A run’s word (`ENGINE_RUN`‘s ARG0): its source in bits 1:0, whether it records every step in bit 2, the soft units’ tap in bits 7:4, and the steps each hard block’s results wait before they meet the soft units: the multiply’s in bits 11:8, the add’s in 15:12, the multiply-add’s in 19:16. - [struct Store](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/struct.Store): The store read back: the header, each class’s counter, the records. - [enum OracleError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/enum.OracleError): Why a discriminator ledger cannot make an oracle. - [enum Source](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/enum.Source): Where a run’s operands come from. - [const ADD_REGISTERS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/constant.ADD_REGISTERS) - [const DRAIN](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/constant.DRAIN): Steps a run takes past its last triple, so every result of every triple leaves the delay line. - [const HOST_PROGRAM](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/constant.HOST_PROGRAM): The measurement on the card (`sw/logos_fp_oracle.c`): the multiply’s and the add’s latencies as the taps at which their classes come nearest every vector (counting runs over the vectors at each tap, no delay: the first tap of the fewest disagreements, so a block no class names still has its depth); the multiply-add’s as the shift at which its results on the vectors whose C is zero are the products (a recording run at the last tap); then, the three aligned (`Run::aligned`), a recording run over the vectors and counting runs of `` triples from the random and the near streams; one JSON object on stdout. The exit status is 0 when every latency was found and every run completed, 1 when a latency was not, 2 when the card cannot be had or a command failed. - [const LEAST_REGISTERS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/constant.LEAST_REGISTERS): The register a least-registered block keeps: its output’s. - [const MAGIC](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/constant.MAGIC): The header’s first word: `LOGOSFPO`. - [const MAX_PRODUCT_CLASSES](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/constant.MAX_PRODUCT_CLASSES): The most product classes a record’s agreement bits hold: the two words it gives the multiply’s agreement, the least-registered multiply’s result beside the flags. - [const MAX_SUM_CLASSES](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/constant.MAX_SUM_CLASSES): The most sum classes a record’s agreement bits hold: three halves of the two words it gives the add, the fourth the least-registered add’s result. - [const MULTIPLY_ADD_REGISTERS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/constant.MULTIPLY_ADD_REGISTERS) - [const MULTIPLY_REGISTERS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/constant.MULTIPLY_REGISTERS): The registers each mode uses fully registered, every operand the mode reads crossing as many to the adder: the multiply’s and the multiply-add’s their input register and two pipeline registers (AX the chain-in pipeline’s, AY and AZ the multiplier’s), the add’s its input register alone, Quartus allowing an add no multiplier pipeline. - [const STORE_BEATS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/constant.STORE_BEATS): The store’s beats, 512 bits each. - [const TAPS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/constant.TAPS): The latencies the soft side can be delayed to: a tap of 0 to `TAPS - 1`, a block latency of 1 to `TAPS` steps. - [fn fma_vectors](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/fn.fma_vectors): The multiply-add’s own vectors: A and B in [1, 2) whose product is inexact, C the product rounded and negated, so a fused multiply-add gives the product’s rounding error and one rounding after another gives zero; then C a power of two beside the product. - [fn fp_mac_blackbox](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/fn.fp_mac_blackbox): The floating-point DSP block as the timing model takes it, a box only Quartus elaborates: its interface, one DSP block large (`logos_box_area`, two halves), its results registers inside it. - [fn hard_model_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/fn.hard_model_verilog): `fourteennm_fp_mac` as a simulator runs the oracle: `product` and `sum` the semantics a block’s multiply and add compute (the multiply-add one after the other), `depths` the steps deep a block is in each mode and registering, each register zero from configuration. The device’s own model is encrypted; this one stands in for it so a simulation of the persona can be held to what the oracle must say of a block whose semantics are known. - [fn host_header](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/fn.host_header): The host program’s table of the oracle’s classes (`sw/logos_fp_oracle.h`): their counts, the store’s layout, and each class’s members by name. - [fn persona_config](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/fn.persona_config): The persona’s accelerator configuration: an engine build on plain 512-bit lines, its compute clock the user clock divided by `divide`, its build identity (the BUILD register) the first eight bytes of the oracle engine’s SHA-256. - [fn persona_sources](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_oracle/fn.persona_sources): Every file of the persona’s tree for `scripts/d5005/build-afu.sh`: the engine build’s files (`afu_sources` of `persona_config`) with the oracle for its engine (the card’s floating-point DSP blocks left to Quartus), its simulation twin the oracle beside a stand-in block computing `model`, `depths` deep (what `scripts/d5005/run-cosim.sh` runs), and the measurement the card runs, `HOST_PROGRAM` with its class table (`host_header`). ## logicaffeine_compile::codegen_sva::fp_receipt The card’s measurement of its floating-point DSP block as a receipt (`benchmarks/silicon/d5005/fp_hard_receipts.json`): what the oracle persona (`super::fp_oracle`) measured on the card, tied to the build that compiled it and the image the card ran, with what each mode’s block is for the engine (`super::fp_hard`). The block is the vendor’s and encrypted, so a receipt is a measurement recorded as one; the proofs hold everything around it. - [struct CardRun](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/struct.CardRun): What the card’s run left beside its measurement, each file as the run wrote it. - [struct Inputs](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/struct.Inputs): Everything a receipt is read from. - [struct Ledger](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/struct.Ledger): The receipts ledger. - [struct Mode](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/struct.Mode): One mode of the block as the card measured it. - [struct Near](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/struct.Near): One class and the steps on which it differed from the block over every run. - [struct Receipt](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/struct.Receipt): A receipt: the run’s identity, the measurement’s size, and each mode. - [struct Steps](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/struct.Steps): The steps of each run. - [enum ReceiptError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/enum.ReceiptError): Why a receipt is not read or not recorded. - [enum Unit](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/enum.Unit): The engine’s unit on one mode’s block. - [const KEPT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/constant.KEPT): The inputs a receipt keeps beside the ledger, each under the name the card’s run wrote it (the discriminator ledger as `discriminators.json`), in `kept_dir`. - [const LEDGER_WHAT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/constant.LEDGER_WHAT): What the receipts ledger says of itself when it starts. - [const NEAREST](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/constant.NEAREST): How many of the classes nearest the block a mode keeps. - [fn engine_held](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/fn.engine_held): Whether `engine` is the engine the build compiled and was made of `discriminators`: its SHA-256 the build row’s `hw/rtl/logos_engine.v`, and every module of it the oracle writes itself (`Oracle::own_verilog`) the text the oracle of `discriminators` writes now, byte for byte. A receipt is recorded under it; kept, the engine is held by its SHA-256 thereafter, so the oracle’s code may move on. The library the engine embeds (the engine’s crossing and ports, the store’s memory) is held by the build’s SHA-256 alone, so the library may move on between a build and its receipt; an own module that does not regenerate is refused by name. - [fn kept](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/fn.kept): A card run’s file `name` as the ledger keeps it: as the run wrote it, but for a `sha256sum` line (`gbs.sha256`), which names its image by its file name alone, so no kept input names one machine’s directories. - [fn kept_dir](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/fn.kept_dir): Where a receipt’s inputs are kept, under `fp_receipts/` beside the ledger: the build and the measurement’s first twelve hex digits, one directory a measurement. - [fn receipt](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/fn.receipt): The receipt `inputs` make, as recorded at `recorded`. - [fn receipt_of](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/fn.receipt_of): The receipt that records `measurement`, by its SHA-256: the card run a hard-float build takes its blocks from, read against the discriminator ledger kept beside it (`fp_receipts//discriminators.json`). - [fn record](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fp_receipt/fn.record): `receipt`, refused unless `engine` is held (`engine_held`) and `ledger` (none: a new ledger) holds no receipt of the same measurement; with the ledger it is appended to, as written. ## logicaffeine_compile::codegen_sva::full_asm full_asm — assemble a compiled LOGOS program (register bytecode `CompiledProgram`) into the instruction words the FULL soft-core (`soft_core.v`) executes: the whole 113-op ISA — user functions (hardware arg-copy `Call`), division/modulo (the sequential shared divider), and the structured heap (lists, tuples, ranges, sets, maps, structs) — so the ENTIRE benchmark suite compiles from `.lg` source to words that run on silicon byte-identically to the VM. - [fn compile_to_full_words](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/full_asm/fn.compile_to_full_words): Compile a `.lg` source all the way to full soft-core imem words, through the chip compile path (`compile_for_chip` — plain Div/Mod, no magic reciprocals). `Err` if it doesn’t parse/compile or uses anything outside the chip’s integer subset. Targets the 32-bit datapath (the tape-out core); for a 64-bit datapath (VM parity on 64-bit-range arithmetic) use `compile_to_full_words_w`. - [fn compile_to_full_words_w](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/full_asm/fn.compile_to_full_words_w): The WIDTH-PARAMETRIC form of `compile_to_full_words`: compile `.lg` source to full soft-core imem words for a datapath of `width` bits (`32` = the tape-out core, byte-identical to the historical output; `64` = full-i64 VM parity — a constant that exceeds i32, like the benchmark PRNGs’ `% 2147483648` / `% 4294967296` moduli, is emitted as a 3-word `LoadConstWide64` instead of being truncated). Pair with `crate::codegen_sva::soft_core_model::run_soft_core_w` at the SAME width. - [fn encode_soft_core_full](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/full_asm/fn.encode_soft_core_full): Assemble a whole compiled program (from `crate::vm::Compiler::compile_for_chip`) into full soft-core imem words. TWO-PASS: pass 1 lays out Main then every function body, computing each code index’s imem word offset (a `Call` and a wide `LoadConst` occupy two words); pass 2 emits the words, resolving every Jump/branch/iter target and callee entry through that pc→imem map. `Err` if the program uses an op with no chip lowering (floats, Text, closures, CRDTs, channels, …) or overflows an operand field. - [fn encode_soft_core_full_w](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/full_asm/fn.encode_soft_core_full_w): The width-parametric form of `encode_soft_core_full`. `width` is retained as an API/experimental knob describing the runtime datapath’s fast-path size, but it NO LONGER changes the emitted image: every over-i32 constant is a 3-word `LoadConstWide64` (op 222) carrying the full `i64` at every width, and the value plane auto-promotes to BigInt on overflow exactly like the VM’s unbounded `Int`. So the full core reproduces the VM EXACTLY — every constant and every arithmetic result, into the BigInt tail — and does so identically at width 32 and 64 (BigInt handles exactness; the width is a perf/area knob, not a correctness switch). Runs on `crate::codegen_sva::soft_core_model::run_soft_core_w` at the matching width. (The distinct 32-bit tape-out core in `scalar_asm.rs` genuinely wraps at 2³² — that is the small-area chip.) - [fn to_hex](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/full_asm/fn.to_hex): Render imem words as a `.hex` file body (one 8-hex-digit word per line). ## logicaffeine_compile::codegen_sva::fusion Operand sharing — reader fusion on the RDU, decided from the cost model. - [struct OperandStream](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fusion/struct.OperandStream): One operand panel and the instances that want it. - [struct SharingDecision](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fusion/struct.SharingDecision): The decision, with the two costs that produced it. - [enum Sharing](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fusion/enum.Sharing): How an operand reaches the instances that want it. - [fn share_operand](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/fusion/fn.share_operand): Choose how `stream` reaches its consumers on `t`. Takes the machine and the shape, and nothing else. ## logicaffeine_compile::codegen_sva::gpu_simt_rtl gpu_simt_rtl — the GPU processor edge: a tuneable SIMT data-parallel engine in silicon. - [struct SimtEngine](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/gpu_simt_rtl/struct.SimtEngine): A tuneable SIMT data-parallel engine — the GPU tile. - [enum LaneArith](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/gpu_simt_rtl/enum.LaneArith): The datapath multiply strategy for the lane’s `a·x + b` arithmetic — a first-class, tuneable, SAT-certified knob. Every strategy is functionally identical (`a·x + b`, 64-bit wrapping); they trade cycle count against physical (routing / antenna) friendliness. - [enum Slot](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/gpu_simt_rtl/enum.Slot): One streamed load slot: a broadcast uniform input, the packed mask word, or a per-lane varying input. The load order (uniforms, then mask, then per-lane varyings) is the single source of truth shared by the RTL load FSM, the testbench, and the golden hex writer. - [fn emit_gpu_simt_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/gpu_simt_rtl/fn.emit_gpu_simt_testbench): A self-checking iverilog testbench: for each of `n_vectors` vectors, reset the load counter, stream the load slots from `gpu_{name}_in.hex`, pulse `go` (all lanes compute in one cycle), then read back every lane output + the reduced scalar via `raddr` and compare against the VM oracle in `gpu_{name}_out.hex`. Prints PASS/FAIL. Layout matches `write_gpu_hex`. - [fn emit_gpu_simt_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/gpu_simt_rtl/fn.emit_gpu_simt_verilog): Emit the SIMT engine as synthesizable RTL: a narrow streaming interface (a 64-bit `din` loaded slot-by-slot into an internal lane register file, a `go` pulse that runs ALL lanes in one cycle — the spatial SIMT step — and a `dout` read back by `raddr`) wrapped around N verbatim copies of the certified kernel, with per-lane predication and an optional warp-reduce. Module name `gpu_{name}`. Readback: `raddr` in `0..N` selects a lane output; `raddr == N` selects the reduced scalar (when a reduce is present). - [fn eval_gpu_simt](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/gpu_simt_rtl/fn.eval_gpu_simt): Evaluate the SIMT engine (the pure-Rust reference the silicon is checked against — N calls to the already-proven `eval_fabric`, one per lane). `lane_inputs[j]` are lane j’s `n_in` kernel inputs (uniform inputs are set equal across lanes by the caller); `mask[j]` gates lane j when predicated (masked → 0). Returns the per-lane outputs and the optional warp-reduced scalar. - [fn load_slots](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/gpu_simt_rtl/fn.load_slots): The canonical load-slot sequence for an engine. - [fn signoff_advisory](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/gpu_simt_rtl/fn.signoff_advisory): A SOFT signoff advisory (NEVER a lock, NEVER blocks emission): the wide combinational strategies (`Combinational`, `DecomposedFma`) at datapath widths >= 32 are met1-antenna-dense on Sky130 — even after fan-out splitting and low utilization, a handful of met1 area-ratio violations remain (empirically ~10 on the N=4 flagship). `SequentialFma` (one reused adder per lane, bounded fan-out) is antenna-trivial. Returns `Some(warning)` for the dense envelope, `None` otherwise. - [fn simt_masked_lane_to_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/gpu_simt_rtl/fn.simt_masked_lane_to_bounded): The BoundedExpr of ONE lane’s predicated output: `mask ? kernel : 0` — the SIMT divergence atom (a certified select over the compiled kernel). Uses the single-lane input names `in{k}` (all lanes are byte-identical modulo the lane suffix, so one lane’s proof covers the array). - [fn simt_reduce_to_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/gpu_simt_rtl/fn.simt_reduce_to_bounded): The BoundedExpr of the warp-reduce tail — a left fold of `op` over the lane-output variables `out0..out{N-1}`. Lowers the reduce so our SAT can certify it equals an independent fold (that every lane is summed, none dropped or duplicated). - [fn simt_sequential_fma_to_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/gpu_simt_rtl/fn.simt_sequential_fma_to_bounded): The BoundedExpr of the SEQUENTIAL shift-add multiply `a·x`, UNROLLED over `width` bits, for single-lane inputs `a = in0`, `x = in1`. This is the exact combinational image of the `SequentialFma` FSM’s `width`-step recurrence: `acc += (x[i] ? a<= thresh` — the set / increment / wait-threshold discipline every dataflow mesh’s semaphores implement. - [fn fifo_bound_certified](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/handshake_rtl/fn.fifo_bound_certified): `0 ≤ cnt ≤ depth` for EVERY push/pop stream, by k-induction over the FIFO’s count register exactly as the RTL computes it (`popped = pop ∧ cnt≠0`, `pushed = push ∧ cnt≠depth`). ## logicaffeine_compile::codegen_sva::hart The board’s own CPU: an RV64IMAC hart with machine and user modes, built to run the LOGOS compiler from the board’s DDR2 so the board compiles programs for its fabric engine with no computer attached. - [mod ddr2](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/): The hart’s main memory: the Nexys A7’s DDR2, a Micron MT47H64M16 (1 Gb, x16, eight banks of 8192 rows of 1024 columns), run by `hart_ddr2.v` at CK = 125 MHz — the slowest clock the part’s DLL is specified for, and twice the hart’s. One hart clock is a frame: two CK cycles, four data beats, one 64-bit word. - [mod image](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/image/): The boot image the board’s flash holds after its bitstream: a header the boot ROM checks, then a DEFLATE-compressed body of sections — the shim, the compiler (a static riscv64 Linux ELF), the bundle of LOGOS sources it may open, and, when a run is given them, the compiler’s arguments. The boot ROM refuses an image whose RTL fingerprint is not the bitstream’s, digests the compressed stream as it inflates it, and refuses one whose digest does not match. - [mod model](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/): The executable specification of the hart: an RV64IMAC processor with the Zicsr and Zifencei extensions, machine and user modes and eight physical-memory-protection entries, one architectural step at a time. The hart’s RTL is held to this model instruction by instruction, and this model is held to the RISC-V architecture tests and to `qemu-riscv64`. - [mod rtl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rtl/): The hart’s RTL, as Verilog source files the board image and the simulations read. The hart is held to `super::model` (and its decompressor to `super::rvc`) by `hart_rtl_lock`; the computer around it, to the board model `super::soc::Board` by `hart_soc_lock`; the DDR2 controller, to the part’s data sheet by `hart_ddr2_lock`. - [mod rvc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rvc/): The RV64C decompressor: every 16-bit instruction is a shorthand for one 32-bit instruction, and the hart executes the expansion. `expand` returns that 32-bit instruction, or `None` for an encoding the C extension reserves (an illegal instruction). HINT encodings expand to the base instruction whose destination is `x0` or whose effect is nil, as the specification defines them. The hart’s RTL expander is held to this function over all 65,536 encodings, and this function is held to the GNU disassembler. - [mod soc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/): The system around the hart on Board B, defined once: the physical memory map, the device registers, how the 128 MB of DDR2 is laid out for the firmware, and the flash image the boot ROM loads. The hart model reads the map as its physical memory attributes, the RTL takes it as parameters (`verilog_defines`), and the boot ROM and the shim compile against the C header this module writes (`c_header`) — so no address is ever written twice. ## logicaffeine_compile::codegen_sva::hart::ddr2 The hart’s main memory: the Nexys A7’s DDR2, a Micron MT47H64M16 (1 Gb, x16, eight banks of 8192 rows of 1024 columns), run by `hart_ddr2.v` at CK = 125 MHz — the slowest clock the part’s DLL is specified for, and twice the hart’s. One hart clock is a frame: two CK cycles, four data beats, one 64-bit word. - [struct Part](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/struct.Part): The part’s timing, from the MT47H64M16 data sheet (-25E grade), in picoseconds unless named in CK cycles. - [struct Schedule](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/struct.Schedule): The controller’s schedule, in frames: what `verilog_params` hands `hart_ddr2.v`. A line transaction issues ACTIVATE at frame 0 and its four column commands at `cas(k)`; the write data’s DQS preamble is the frame after a WRITE and its eight beats the two frames after that (WL = CL − 1 = four CK cycles); the bank is idle and every constraint met by `read_done` / `write_done`. - [const BURSTS_PER_LINE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/constant.BURSTS_PER_LINE) - [const BURST_BEATS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/constant.BURST_BEATS): Burst length, in beats (BL8): sixteen bytes, two frames. - [const CK_PS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/constant.CK_PS): One CK cycle, and one frame (a hart clock), in picoseconds. - [const FRAME_PS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/constant.FRAME_PS) - [const MT47H64M16](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/constant.MT47H64M16) - [fn calibration_line](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/fn.calibration_line): The line the controller writes and reads back to calibrate its read capture: thirty-two beats per byte lane, each byte distinct within its lane and from every other’s complement, so the first beat (or its complement) is found at exactly one place in the captured stream and the rest confirm it. - [fn cks](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/fn.cks): CK cycles covering at least `ps`. - [fn emr1](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/fn.emr1): Extended mode register 1: DLL on, full drive, no on-die termination, no additive latency, differential DQS; the off-chip driver calibration as given (0b111 default, 0 exit). - [fn frames](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/fn.frames): Frames covering at least `ps`. - [fn init_sequence](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/fn.init_sequence): The JEDEC power-up sequence in frames. - [fn init_word](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/fn.init_word): An init step as the controller’s ROM word: `{cke, cs_n, ras_n, cas_n, we_n, ba[2:0], a[12:0], frames[23:0]}` (45 bits), the command’s pins from the JEDEC truth table `ddr2_pins`. - [fn locate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/fn.locate): Where a byte of the RAM lives: (row, bank, column). The bank bits sit just above a row’s 2 KB, so consecutive rows of the address space rotate through the banks. - [fn mr](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/fn.mr): The mode register: BL8, sequential, CAS latency, write recovery, and whether the DLL resets. - [fn schedule](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/fn.schedule) - [fn verilog_params](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/ddr2/fn.verilog_params): The parameters `hart_ddr2.v` includes (`hart_ddr2_params.vh`): the schedule in frames, the power-up ROM, the calibration line. ## logicaffeine_compile::codegen_sva::hart::image The boot image the board’s flash holds after its bitstream: a header the boot ROM checks, then a DEFLATE-compressed body of sections — the shim, the compiler (a static riscv64 Linux ELF), the bundle of LOGOS sources it may open, and, when a run is given them, the compiler’s arguments. The boot ROM refuses an image whose RTL fingerprint is not the bitstream’s, digests the compressed stream as it inflates it, and refuses one whose digest does not match. - [struct BootImage](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/image/struct.BootImage): What a boot image carries. - [fn body](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/image/fn.body): The inflated body: a u32 section count and a reserved u32, the table of (u32 kind, u32 flags, u64 offset, u64 length), then each section at an 8-byte-aligned offset from the body’s start. - [fn build](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/image/fn.build): The image as the flash holds it at `IMAGE_OFFSET`: the 128-byte header, then the compressed body. - [fn bundle_bytes](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/image/fn.bundle_bytes): The bundle’s bytes: a u32 count, then per file its u32 name length, the name, its u64 length and its bytes. - [fn open](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/image/fn.open): An image read back: its fingerprint and its inflated body, every check the boot ROM makes applied. - [fn pack](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/image/fn.pack): The body’s compression: raw DEFLATE at the strongest level, the stream the boot ROM inflates. ## logicaffeine_compile::codegen_sva::hart::model The executable specification of the hart: an RV64IMAC processor with the Zicsr and Zifencei extensions, machine and user modes and eight physical-memory-protection entries, one architectural step at a time. The hart’s RTL is held to this model instruction by instruction, and this model is held to the RISC-V architecture tests and to `qemu-riscv64`. - [struct BusError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/struct.BusError): A physical access the bus refuses (no device at the address). - [struct Hart](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/struct.Hart): The architectural state of the hart. - [struct Region](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/struct.Region): A range of physical addresses and what it may be used for: its physical memory attributes. An access outside every region, or one its region does not permit, is an access fault before it reaches the bus — so a device register is never fetched from, never the target of an atomic, and never read or written in part. These attributes are the only source of access faults: every access they permit, the bus completes. - [struct Trap](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/struct.Trap): A synchronous exception: its `mcause` and the value `mtval` receives. - [enum Privilege](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/enum.Privilege): A privilege mode. - [enum Step](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/enum.Step): What one step did. - [const CAUSE_BREAKPOINT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/constant.CAUSE_BREAKPOINT) - [const CAUSE_FETCH_ACCESS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/constant.CAUSE_FETCH_ACCESS) - [const CAUSE_ILLEGAL_INSTRUCTION](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/constant.CAUSE_ILLEGAL_INSTRUCTION) - [const CAUSE_LOAD_ACCESS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/constant.CAUSE_LOAD_ACCESS) - [const CAUSE_MACHINE_ECALL](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/constant.CAUSE_MACHINE_ECALL) - [const CAUSE_MISALIGNED_LOAD](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/constant.CAUSE_MISALIGNED_LOAD) - [const CAUSE_MISALIGNED_STORE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/constant.CAUSE_MISALIGNED_STORE) - [const CAUSE_STORE_ACCESS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/constant.CAUSE_STORE_ACCESS) - [const CAUSE_USER_ECALL](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/constant.CAUSE_USER_ECALL) - [const MISA](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/constant.MISA): `misa`: RV64 with the A, C, I, M and U extensions. - [const PMP_ENTRIES](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/constant.PMP_ENTRIES): The number of physical-memory-protection entries the hart implements; entries 8 to 15 read as zero. - [trait Bus](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/model/trait.Bus): The hart’s view of the system: naturally aligned reads and writes of 1, 2, 4 or 8 bytes. ## logicaffeine_compile::codegen_sva::hart::rtl The hart’s RTL, as Verilog source files the board image and the simulations read. The hart is held to `super::model` (and its decompressor to `super::rvc`) by `hart_rtl_lock`; the computer around it, to the board model `super::soc::Board` by `hart_soc_lock`; the DDR2 controller, to the part’s data sheet by `hart_ddr2_lock`. - [const DDR2_PARAMS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rtl/constant.DDR2_PARAMS): The DDR2’s parameters, which the controller includes. - [const DEFINES](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rtl/constant.DEFINES): The memory map’s `define`s, which the computer’s files include. - [fn board_files](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rtl/fn.board_files): What the board’s top adds around the computer and its DDR2: the queue that carries bytes between the hart’s clock and the terminal’s. - [fn bringup_files](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rtl/fn.bringup_files): The bring-up image: the computer alone on Board B (`hart_bringup_top`), booting from the flash with its log on the USB UART — `board_files`, the log UART’s transmitter, the top and its pins. - [fn core_files](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rtl/fn.core_files): The hart itself: (file name, source). - [fn cpu_files](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rtl/fn.cpu_files): The hart with its caches, `hart_cpu`: the hart’s files, the instruction and data caches, their one way to memory, and the maintenance (fence.i, restart) they share. - [fn ddr2_files](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rtl/fn.ddr2_files): The DDR2 controller, `hart_ddr2`, with `DDR2_PARAMS` written from `super::ddr2::verilog_params` for the board’s part, and its Artix-7 PHY, `hart_ddr2_phy` (device primitives: the board’s build reads it, simulations do not). - [fn fingerprint](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rtl/fn.fingerprint): A bitstream’s fingerprint — what a boot image is built for, and what `SYS_RTL_MD5` reports: the md5 of every file the bitstream is built from, in order, then of the boot ROM’s words, so a changed ROM is another bitstream too. - [fn fingerprint_words](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rtl/fn.fingerprint_words): A fingerprint as the SoC’s `RTL_MD5_LO` / `RTL_MD5_HI` parameters take it: the words `SYS_RTL_MD5_LO` and `SYS_RTL_MD5_HI` read as, its bytes little-endian. - [fn loopback_files](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rtl/fn.loopback_files): The DDR2 PHY’s board probe, `hart_ddr2_loopback_top`: the PHY driving its own pads with the DDR2 held idle and sending what it reads back on the UART; its pins are the bring-up image’s, those its ports use. - [fn rom_hex](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rtl/fn.rom_hex): The boot ROM as the `$readmemh` words its block RAM starts with: a 64-bit little-endian word a line, zeros to the ROM’s end. - [fn soc_files](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rtl/fn.soc_files): The whole computer, `hart_soc`: `cpu_files`, the boot ROM, the scratch RAM, the device registers, and `DEFINES` written from `soc::verilog_defines`. The boot ROM’s contents come from the `ROM_INIT` file the build names (`rom_hex`). ## logicaffeine_compile::codegen_sva::hart::rvc The RV64C decompressor: every 16-bit instruction is a shorthand for one 32-bit instruction, and the hart executes the expansion. `expand` returns that 32-bit instruction, or `None` for an encoding the C extension reserves (an illegal instruction). HINT encodings expand to the base instruction whose destination is `x0` or whose effect is nil, as the specification defines them. The hart’s RTL expander is held to this function over all 65,536 encodings, and this function is held to the GNU disassembler. - [fn expand](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rvc/fn.expand): The 32-bit instruction the compressed instruction `c` stands for, or `None` for a reserved encoding. - [fn is_compressed](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/rvc/fn.is_compressed): Whether the low two bits mark a 16-bit (compressed) instruction. ## logicaffeine_compile::codegen_sva::hart::soc The system around the hart on Board B, defined once: the physical memory map, the device registers, how the 128 MB of DDR2 is laid out for the firmware, and the flash image the boot ROM loads. The hart model reads the map as its physical memory attributes, the RTL takes it as parameters (`verilog_defines`), and the boot ROM and the shim compile against the C header this module writes (`c_header`) — so no address is ever written twice. - [struct Board](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/struct.Board): The whole board: the hart at its reset vector over the devices. - [struct Devices](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/struct.Devices): The board’s devices, as the model of the system around the hart: memory, the flash behind the streaming port, and every register in `REGS` with the behaviour its line documents. The RTL SoC is held to these. The bus completes every access the memory map permits (`memory_map`): a device address no register holds reads as zero and ignores writes. - [struct Reg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/struct.Reg): A device register: its name in the C header and its address. - [enum Stopped](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/enum.Stopped): How a run of the board ended. - [const BOOT_WORK_BASE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.BOOT_WORK_BASE): The boot ROM’s working tables (the inflater’s), in the mapping region: nothing uses it before the compiler runs, and the shim zeroes every page it hands out there. - [const BUTTONS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.BUTTONS) - [const CONSTANTS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.CONSTANTS): Every constant the firmware compiles against, by its C name. - [const DDR](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.DDR) - [const FIRMWARE_BASE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.FIRMWARE_BASE) - [const FLASH_SIZE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.FLASH_SIZE): The flash: the bitstream at 0, the boot image here. - [const HART_HWCAP](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.HART_HWCAP): The extensions the compiler sees, as Linux reports them in `AT_HWCAP` (a bit per extension letter): the hart’s I, M, A and C, and the F and D the shim provides — exactly what `qemu-riscv64` reports for the same binary. - [const HART_HZ](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.HART_HZ): The hart’s clock: the DDR2 controller’s divided clock, which the hart shares. - [const IMAGE_HEADER_SIZE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.IMAGE_HEADER_SIZE) - [const IMAGE_MAGIC](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.IMAGE_MAGIC): The boot image’s header: `IMAGE_MAGIC`, a version and the header’s size, the RTL fingerprint it was built for, the body’s inflated and compressed lengths, and the sha256 of the compressed body. - [const IMAGE_OFFSET](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.IMAGE_OFFSET) - [const IMAGE_VERSION](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.IMAGE_VERSION) - [const IO_BASE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.IO_BASE): Device registers. - [const IO_SIZE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.IO_SIZE) - [const LINK](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.LINK) - [const MMAP_BASE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.MMAP_BASE) - [const MMAP_SIZE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.MMAP_SIZE) - [const QSPI](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.QSPI) - [const RAM_BASE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.RAM_BASE): The DDR2. - [const RAM_SIZE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.RAM_SIZE) - [const REGS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.REGS): Every device register. - [const RESET_PC](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.RESET_PC) - [const ROM_BASE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.ROM_BASE): The boot ROM: the hart’s reset vector. Address 0 stays unmapped, so a null pointer faults. - [const ROM_SIZE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.ROM_SIZE) - [const SECTION_ARGS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.SECTION_ARGS) - [const SECTION_BUNDLE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.SECTION_BUNDLE) - [const SECTION_FIRMWARE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.SECTION_FIRMWARE) - [const SECTION_SHIM](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.SECTION_SHIM): A section of the boot image’s body. - [const SHIM_BASE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.SHIM_BASE): How the DDR2 is laid out once the shim runs: the shim itself, the firmware’s image and heap, the region its anonymous mappings come from, the boot image’s staging area, and the firmware’s stack. - [const SHIM_SIZE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.SHIM_SIZE) - [const SOC_ID](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.SOC_ID): `SYS_ID`: “LOGOSHRT” read as a little-endian word. - [const SOC_RESET_KEY](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.SOC_RESET_KEY): The value `SYS_RESET` takes to restart the board. - [const SRAM_BASE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.SRAM_BASE): Scratch RAM in block RAM: the boot ROM’s stack and data before the DDR2 is calibrated. It never holds code. - [const SRAM_SIZE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.SRAM_SIZE) - [const STACK_BASE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.STACK_BASE) - [const STACK_SIZE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.STACK_SIZE) - [const STAGING_BASE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.STAGING_BASE) - [const STAGING_SIZE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.STAGING_SIZE) - [const SYS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.SYS) - [const UART](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/constant.UART) - [fn c_header](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/fn.c_header): The C header the boot ROM and the shim compile against. - [fn memory_map](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/fn.memory_map): The physical memory map the hart enforces. - [fn verilog_defines](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hart/soc/fn.verilog_defines): The RTL’s view of the same map, as `define`s the SoC’s Verilog includes (once, however many files include it). ## logicaffeine_compile::codegen_sva::hw_pipeline Hardware Verification Pipeline - [struct EquivalenceResult](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/struct.EquivalenceResult): Result of checking semantic equivalence between FOL and SVA. - [struct HwSignalDecl](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/struct.HwSignalDecl): Declares a hardware signal with its English name and SVA name. - [struct HwSpec](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/struct.HwSpec): A compiled hardware specification. - [struct KgLink](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/struct.KgLink): A directed relation between two nodes (indices into `KgSummary::nodes`). - [struct KgNode](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/struct.KgNode): A node in the renderable knowledge-graph view: a signal with its role and width. - [struct KgSummary](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/struct.KgSummary): A compact, render-ready view of the hardware knowledge graph extracted from an English spec — signals as nodes, relations (drives / triggers / handshakes / …) as directed links. - [struct PipelineResult](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/struct.PipelineResult): Full pipeline result. - [struct SignalMap](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/struct.SignalMap): Maps FOL argument names (from English proper nouns) to SVA signal names. - [struct WaveSignal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/struct.WaveSignal): One signal’s value over time in a counterexample waveform. `width` is the bit width (1 = a boolean control bit); each `values[t]` is the (reconstructed) register value at timestep `t`, or `None` if unconstrained there. - [struct Waveform](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/struct.Waveform): A counterexample rendered as a waveform: signals (rows) over discrete timesteps (columns). - [enum HwError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/enum.HwError): Error type for hardware verification pipeline. - [enum VacuityReport](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/enum.VacuityReport): A vacuity verdict for a synthesized property. - [fn check_bounded_equivalence](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/fn.check_bounded_equivalence): Check bounded equivalence between two BoundedExpr trees. - [fn check_spec_vacuity](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/fn.check_spec_vacuity): Vacuity check (Z3-free, certified): does the property’s trigger ever fire? An unsatisfiable antecedent means the property passes vacuously — a dead trigger that usually signals a malformed spec. Reuses `logicaffeine_proof::bmc::check_vacuity`. - [fn check_structural_equivalence](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/fn.check_structural_equivalence): Check structural equivalence between two SVA expressions. - [fn compile_hw_property](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/fn.compile_hw_property): Compile an English hardware property with signal declarations. - [fn compile_hw_spec](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/fn.compile_hw_spec): Compile an English hardware spec to FOL text. - [fn counterexample_waveform](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/fn.counterexample_waveform): Turn a counterexample’s bindings into a waveform. Handles both 1-bit signals (`name@t`) and bit-blasted multi-bit registers (`name@t#i`), reconstructing each register’s integer value per timestep from its bits. Signals are sorted by name; each row spans `0..timesteps`. Malformed keys (no `@t`) are skipped. - [fn emit_hw_sva](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/fn.emit_hw_sva): Emit SVA from a property specification. - [fn extract_kg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/fn.extract_kg): Extract a Knowledge Graph from an English hardware spec (one call). - [fn kg_summary](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/fn.kg_summary): Extract a render-ready knowledge graph from an English hardware spec. Pure Rust (no Z3), so it runs in the browser. Merges the legacy and typed (ontology) edge sets. - [fn prove_bounded_equivalence](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/fn.prove_bounded_equivalence): Check FOL ↔ SVA semantic equivalence at a bound with our pure-Rust, certified prover (no Z3) — the in-browser counterpart of `check_z3_equivalence`. Lowers both bounded obligations to `ProofExpr` and discharges `F ↔ S` through the CDCL → RUP tiers: an `equivalent` verdict is RUP-certified, a non-equivalent one carries a counterexample trace (`name@t` → `"1"`/`"0"`). Errors (fail-closed, never a false “equivalent”) if either obligation leaves the Boolean fragment — data-path needs bit-blasting, not wired yet. - [fn prove_spec_sva_equivalence](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/fn.prove_spec_sva_equivalence): End-to-end: an English spec and a candidate SVA string → certified semantic equivalence with our prover. The Z3-free counterpart of `check_z3_equivalence`: the same translators, our CDCL → RUP tiers instead of Z3. - [fn translate_spec_to_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/fn.translate_spec_to_bounded): Translate a LOGOS spec to bounded verification IR using compile_kripke_with. - [fn translate_sva_to_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/hw_pipeline/fn.translate_sva_to_bounded): Translate an SVA string to bounded verification IR. ## logicaffeine_compile::codegen_sva::infinichip_rtl infinichip_rtl — the integrated Infinichip memory subsystem, taken all the way to a signoff-clean Sky130 GDSII. - [fn emit_infinichip_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/infinichip_rtl/fn.emit_infinichip_testbench): Emit a SELF-CHECKING integration testbench: it drives all three datapaths through the composed `infinichip` top and asserts (1) the ECC read path corrects a single-bit fault and recovers the data one edge after the codeword arrives, (2) the double-buffer banks stay disjoint across a swap, and (3) the command player issues a loaded command with the exact decoded payload. Prints PASS/FAIL — no external vectors needed. - [fn emit_infinichip_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/infinichip_rtl/fn.emit_infinichip_verilog): Emit the SELF-CONTAINED `infinichip.v`: every certified sub-block definition inlined, followed by the structural top. One PDK-agnostic file → tapes out on Sky130 with no cross-file deps. ## logicaffeine_compile::codegen_sva::keccak_rtl keccak_rtl — the flagship silicon FACT. - [struct NttCuts](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/keccak_rtl/struct.NttCuts): Where the pipelined butterfly’s registers go: `self.0[i]` puts one after step `i` (`NTT_STEPS`). The operands and the results are always registered. - [const KYBER_Q](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/keccak_rtl/constant.KYBER_Q): q and Montgomery constant — identical to `logicaffeine_system::ntt`. - [const KYBER_QINV_I16](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/keccak_rtl/constant.KYBER_QINV_I16) - [const NTT_STEPS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/keccak_rtl/constant.NTT_STEPS): The steps of `emit_ntt_butterfly_pipelined_verilog`’s datapath a register may follow: the four levels of the product’s adder tree; `m`’s high-byte correction; `m`; the two partial sums of `13·m + (m >>> 8)`; that sum; `t`. - [const RC](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/keccak_rtl/constant.RC): The 24 Keccak-f round constants (FIPS-202) — same table as the native kernel. - [fn emit_keccak_core_half_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/keccak_rtl/fn.emit_keccak_core_half_verilog): Emit `keccak_core_half`: the iterative core with a register between theta and the rest of each round, two clocks a round (48 for the permutation), each half carrying only its own wiring — theta’s column parities, then rho and pi’s lane moves into chi. The same ports and handshake as `keccak_core`. - [fn emit_keccak_core_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/keccak_rtl/fn.emit_keccak_core_verilog): Emit the clocked iterative core: `start` latches `s_in`, then one round/cycle for 24 cycles applying `RC[round]`; `done` pulses with `s_out` = the permutation result. - [fn emit_keccak_round_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/keccak_rtl/fn.emit_keccak_round_verilog): Emit the combinational one-round `Keccak-f[1600]` module: state `s` + round constant `rc` → `o`. Lane i occupies bits `[64*i +: 64]` (little-endian lane packing). - [fn emit_keccak_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/keccak_rtl/fn.emit_keccak_testbench): Self-checking testbench: load the input state + the oracle’s 24-round output from `keccak_vec.hex` (50 × 64-bit words: 25 input lanes then 25 expected lanes), run the core, compare bit-exact. Prints PASS/FAIL. - [fn emit_keccak_top_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/keccak_rtl/fn.emit_keccak_top_verilog): Emit a NARROW-BUS wrapper around `keccak_core` so it place-and-routes on a real FPGA: the bare core exposes a 1600-bit parallel state port (fine for simulation, but 1600 pins exceed any FPGA’s IO), so `keccak_top` streams the 25 lanes in and out over a 64-bit bus addressed by a 5-bit lane index. `we` writes `din` to lane `idx`; `go` launches the permutation; `done` marks completion; `dout` reads lane `idx` of the result. ~140 IOs — routes on the ECP5. - [fn emit_ntt_butterfly_pipelined_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/keccak_rtl/fn.emit_ntt_butterfly_pipelined_verilog): Emit module `name`: `emit_ntt_butterfly_verilog`’s butterfly as a pipeline taking one butterfly a cycle, its result `NttCuts::latency` edges after its operands, registered after the steps `cuts` names. Each value a later stage reads reaches it through one register a stage, and only those values are carried. - [fn emit_ntt_butterfly_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/keccak_rtl/fn.emit_ntt_butterfly_verilog): Emit the combinational Montgomery `fqmul` + one Cooley–Tukey butterfly: inputs `a`, `b` (the two coefficients) and `zeta`; outputs `hi = a + t`, `lo = a - t` where `t = fqmul(zeta, b)` — all wrapping 16-bit, matching `ntt_scalar`’s inner step. - [fn fqmul](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/keccak_rtl/fn.fqmul) - [fn montgomery_reduce](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/keccak_rtl/fn.montgomery_reduce): The reference Montgomery reduction (mirrors `ntt::montgomery_reduce`) — the oracle the emitted RTL is checked against. ## logicaffeine_compile::codegen_sva::lutmap Mapping logic onto K-input LUTs for depth, the way an FPGA’s synthesis sees how deep a circuit is. - [struct Lut](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/lutmap/struct.Lut): A LUT of the cover: its root node and its leaves, nodes of the balanced network. - [struct Mapping](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/lutmap/struct.Mapping): A network mapped onto LUTs. - [struct Xag](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/lutmap/struct.Xag): An AND-XOR graph: node 0 is the constant, and every node’s fanins come before it. - [enum Gate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/lutmap/enum.Gate): A node of an `Xag`. - [const CUTS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/lutmap/constant.CUTS): How many cuts each node keeps. - [const FALSE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/lutmap/constant.FALSE) - [const MAX_K](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/lutmap/constant.MAX_K): The largest LUT `map` maps to. - [const TRUE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/lutmap/constant.TRUE) - [fn complemented](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/lutmap/fn.complemented) - [fn function](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/lutmap/fn.function): The truth table of `root` over `leaves` (at most six): bit `i` of the table is the root’s value when leaf `j` holds bit `j` of `i`. Every path from the root down must end at a leaf, as a cut’s do. - [fn map](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/lutmap/fn.map): Map `xag` onto LUTs of at most `k` inputs (`2 ≤ k ≤ MAX_K`), its supergates confined to `group`s (one entry a node), covering the nodes `outputs` read. - [fn node](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/lutmap/fn.node) - [type Lit](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/lutmap/type.Lit): A node and whether the edge to it is complemented: `node << 1 | complemented`. ## logicaffeine_compile::codegen_sva::memsched memsched — the static-memory-schedule FACT. - [struct CachePlan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/memsched/struct.CachePlan): The software-managed-cache plan for a program (GAPS G19, `MEMORY_EDGE_SPEC.md §3`): the datapath memory sites partitioned into `prefetch` (compile-time-known address stream — served from the static schedule, zero runtime miss, zero-jitter) and `probe` (data-dependent — a tag probe that may miss and fall back to the managed cache). `pc` values index `CompiledProgram::code`. - [struct MemSchedReport](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/memsched/struct.MemSchedReport): The measured verdict for one program. - [enum RegClass](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/memsched/enum.RegClass): The address class of a register within one code segment (one function body). - [enum SiteKind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/memsched/enum.SiteKind): The memory shape of one ISA op. Exhaustive over every variant — no wildcard. - [fn analyze](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/memsched/fn.analyze): Analyze a compiled program: classify every op site, resolving indexed sites against the enclosing function segment’s register classes. - [fn cache_plan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/memsched/fn.cache_plan): Build the managed-cache plan: exactly the memsched static/dynamic partition, so the probe list — the ONLY sites that can miss — equals the compiler’s `dynamic_sites`, and streaming kernels (all-static) produce an EMPTY probe list (they never touch the managed-cache path, preserving their zero-jitter contract). - [fn explain_dynamic_sites](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/memsched/fn.explain_dynamic_sites): Human-readable diagnosis of the first `limit` DYNAMIC sites: which op, which index register, and every write shape that register has in its segment — the tool for understanding why a kernel’s fraction is what it is (and for sharpening the floor). - [fn site_kind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/memsched/fn.site_kind): Classify one op’s memory behavior. EXHAUSTIVE — adding a VM op forces a decision here. ## logicaffeine_compile::codegen_sva::metapipeline The metapipeline initiation-interval (II) model — P1 of the Plasticine lane, and the question an RDU engineer asks first: how often can a pipelined stage accept a new iteration, and how deep must the buffers between stages be? - [struct Metapipeline](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/metapipeline/struct.Metapipeline): A metapipeline: stages in issue order, with the producer→consumer buffer edges between them. - [struct PipelinedRun](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/metapipeline/struct.PipelinedRun): The result of a cycle-timed pipelined run of a counted loop. - [struct Stage](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/metapipeline/struct.Stage): One metapipeline stage’s timing. - [struct UnitModel](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/metapipeline/struct.UnitModel): Per-cell timing: how many cycles a cell’s result takes (`latency`) and how many cycles the cell’s unit is busy per iteration (`occupancy`, the resource II). A fully pipelined unit has occupancy 1 whatever its latency; a sequential unit (an iterative divider) has occupancy == latency. - [fn eval_loop_fabric_at_ii](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/metapipeline/fn.eval_loop_fabric_at_ii): Execute a counted loop as a pipeline issuing one iteration every `ii` cycles. Iteration `t` issues at cycle `t*ii`, reads each carried register’s value as of that cycle (the latest write whose completion cycle `<=` the issue cycle), and completes register `k`’s write at `t*ii + depth_k`. With `ii >=` the recurrence II every read sees the previous iteration’s write and the result equals `eval_loop_fabric`; below it, reads are stale (hazards). - [fn loop_stage](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/metapipeline/fn.loop_stage): Model one counted loop as ONE metapipeline stage. ## logicaffeine_compile::codegen_sva::mul_tree mul_tree — a word multiply as an aligned tree of adds. The product `a · x mod 2^w` is the sum of the `w` partial products `x[i] ? a << i : 0`; the tree adds them pairwise, level by level, each add only as wide as the bits it can still change (a partial product shifted by `i` is zero below bit `i`, and nothing above bit `w − 1` survives), and a register can follow any level. On a fabric with carry chains every add is one chain and nothing multiplies; cut after every level, no stage holds more than one add. - [struct MulTree](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/mul_tree/struct.MulTree): The tree of one multiply: its declarations and combinational assignments, its registers with the value each takes every clock, the signal holding the product after the last level, and the clocks from its operands to it. - [fn mul_tree](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/mul_tree/fn.mul_tree): The product `a · x mod 2^width` of the `width`-bit Verilog expressions `a` and `x`, its signals named after `prefix`, registered after each level `level` for which `cut(level)` holds (the last level’s sum is the product). - [fn mul_tree_levels](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/mul_tree/fn.mul_tree_levels): The levels of the tree over `width` partial products: the pairwise adds that bring them down to one. ## logicaffeine_compile::codegen_sva::netlist Verilog to and-inverter graphs, through yosys: the bridge that puts any RTL the compiler prints in front of the certified equivalence engine (`logicaffeine_proof::sweep`, `logicaffeine_proof::seq_equiv`). - [struct ClockSource](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/struct.ClockSource): A net that clocks registers or memory ports: its name, what drives it, and the register bits it clocks. - [struct CutNetlist](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/struct.CutNetlist): A design with its units cut out: its netlist and the instances, by name. - [struct Domains](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/struct.Domains): The sequential elements of a flattened module. - [struct Graph](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/struct.Graph): A module’s instances as a floorplan’s wires: every instance, each pair of them and the bits between them, and each instance and the bits between it and the module’s own ports, in name order, no wire of no bits. - [struct Link](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/struct.Link): Two instances of a module and the bits between them. - [struct Netlist](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/struct.Netlist): A synthesized module: its bit-level circuit, its word-level yosys JSON, and its clock domains. - [struct UnitInstance](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/struct.UnitInstance): An instance of a unit cut out of a design (`synthesize_cut`): its flattened name, its module, the parameters it gives its module (by name, each value in one spelling, `rtlil_value`; every one it leaves is the module’s default), and its input and output ports with their widths, in the order the netlist lists them. - [enum ClockDriver](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/enum.ClockDriver): What drives a net that clocks registers. - [enum NetlistError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/enum.NetlistError): Why a module did not become an and-inverter graph. - [enum Undefined](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/enum.Undefined): What an undefined bit of the source is in the circuit. - [fn clock_sources](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/fn.clock_sources): Every net that clocks a register or a memory port of `top` with its parameters set, flattened: what drives it and the register bits it clocks, the nets no port drives first, then by the bits they clock. A clock a register or logic makes inside a design reaches no global network unless the fitter gives it one, and a persona’s region cannot; it rides general routing, its skew paid for in the delay the router adds for hold, so a design is refused such a clock before it is fitted. - [fn module_graph](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/fn.module_graph): The instances of `module` in `verilog` as a floorplan’s wires: each pair of its instances and the bits between them, and each instance and the bits between it and the module’s own ports. The modules `through` names are dissolved into it (`flatten`), so their instances are the module’s, named by path (`fast|unit`; a generate block’s `lane_port[0].port`); every other module is read by its ports alone (`read_verilog -lib`), so nothing under an instance is elaborated. The bits between two ends are the nets one drives and the other reads, and what each drives into the other through the module’s own logic (its registers, multiplexers and the rest, one cell or more): the fewer of the nets leaving the one and the nets arriving at the other, so a bus through a register stage counts its width and a select steering a bus one bit. A net two ends only read joins neither to the other: a broadcast is a star from its driver, not a wire between every two of its readers. A glue cell’s clock pins carry no bits: the clock network is no wire a floorplan shortens. - [fn script](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/fn.script): The yosys script that elaborates `top` with `params` and writes `design.json` and `design.aag`, every undefined bit a free input. The design is read deferred: a module is elaborated only as the hierarchy instantiates it, with its instance’s parameters, never at its defaults on the way in. - [fn script_cut](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/fn.script_cut): `script_reading` with every instance of the `units` modules cut out: each module read from `units.v` as its ports alone (`read_verilog -lib`, its body never elaborated; a module no unit is named is an error), and once the design is flat and written, each instance turned into ports of the top (`expose -evert`) — its outputs inputs named `.[bit]`, its inputs outputs of the same names. - [fn script_reading](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/fn.script_reading): `script`, each undefined bit read as `undefined` says. - [fn synthesize](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/fn.synthesize): Synthesize `top` of `verilog` with `params` set into an and-inverter graph, every undefined bit a free input. - [fn synthesize_cut](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/fn.synthesize_cut): `top` with every instance of the `units` modules cut out (`script_cut`), each undefined bit read as `undefined` says: a composition whose units are proven apart, to be proven over its units as functions it knows nothing of. - [fn synthesize_reading](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/netlist/fn.synthesize_reading): `synthesize`, each undefined bit read as `undefined` says. ## logicaffeine_compile::codegen_sva::onboard The compiler as the board’s own CPU runs it: LOGOS source → register bytecode → the fabric engine’s wire image, through exactly the path the laptop’s board hosts take (`super::engine_build`), with the VM’s golden proven against the engine model before a byte of the image exists. The board runs a `riscv64gc-unknown-linux-musl` build of this same code; `onboard_compiler_lock` holds its every answer byte-identical to the host build’s. - [struct Compiled](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/onboard/struct.Compiled): One program compiled for the fabric engine. - [struct Entry](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/onboard/struct.Entry): One program of a library: its title, its source file, and what the engine runs of it. - [struct Reply](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/onboard/struct.Reply): The engine’s reply so far: every `Show` it sent, each rendered as the VM prints it, and how the run ended once the result frame is whole. - [enum Ended](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/onboard/enum.Ended): How an engine run ended, read from its result frame. - [enum Golden](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/onboard/enum.Golden): The VM’s answer the engine must reproduce: a Main program’s output, one line per `Show`, or a function’s value. - [enum Run](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/onboard/enum.Run): What the engine is asked to run: the program’s `## Main`, or one of its functions on arguments. - [fn agrees](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/onboard/fn.agrees): FABRIC == VM: a finished run whose shows are the VM’s lines (a Main program) or whose result is the VM’s answer (a function). An overflowed run never agrees. - [fn compile](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/onboard/fn.compile): Compile `src` for the engine: lower `run` and prove it ≡ VM (`lower_main` / `lower`), check the image against the engine `profile` and the flashed image’s `caps` (`NAME=N,…`, DEPTH and HEAP measured on the exact arguments), then emit the wire image and the bytecode it was lowered from. A refusal is the sentence a person reads on the screen. - [fn engine_reply](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/onboard/fn.engine_reply): Decode what the engine has sent of one run — its bytes arrive in pieces, so a reply cut short is not an error, only not over yet. Bytes before the first record or frame (the engine’s power-on byte) are skipped. A program that calls the host is refused by name: the board answers no host calls. - [fn hw_caps](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/onboard/fn.hw_caps): The caps of Board B’s hardware engine, written the way a build recipe writes them. - [fn library](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/onboard/fn.library): The entries of a library file (`benchmarks/silicon/programs/terminal_library.txt`’s format): one per line, `title | program file | function | arguments`, a `## Main` program with neither function nor arguments; `#` starts a comment line. - [fn register_bytecode](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/onboard/fn.register_bytecode): The register bytecode of `src`, compiled the way the fabric lifters compile it, as a binary ISA frame. - [fn report](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/onboard/fn.report): A compile’s report, one `key=value` line per fact: `lifter=`, then `golden=` (a function’s value) or `golden_json=` (a Main program’s lines), then `bytecode=` and `wire=` in lowercase hex. A refusal is the single line `error=` followed by the sentence. - [fn shown](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/onboard/fn.shown): One shown value as the VM prints it — through the engine model’s own rendering, so the board and the laptop can never print a value two ways. ## logicaffeine_compile::codegen_sva::pdk_target `PdkTarget` — the PROCESS a design is built out of, as data. - [struct HarnessTiming](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/struct.HarnessTiming): The vehicle’s timing as efabless characterizes it: what a user macro’s ports see from the harness, and the clock model the whole chip is signed off with. - [struct LayerRc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/struct.LayerRc): One routing layer’s wire RC per unit length, as `set_layer_rc` takes it. - [struct MemoryPlan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/struct.MemoryPlan): How a `MemoryRequest` maps onto real macros. - [struct MemoryRequest](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/struct.MemoryRequest): A memory the design needs, expressed the way RTL expresses it. - [struct PdkTarget](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/struct.PdkTarget): One process, as data. - [struct SramMacro](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/struct.SramMacro): A standard-cell SRAM macro the PDK actually ships, with the facts that decide whether a design can use it. - [struct UserArea](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/struct.UserArea): The fixed geometry of a shuttle vehicle. `None` for a standalone die, where the user chooses. - [enum HarnessClock](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/enum.HarnessClock): The clocks the vehicle’s harness gives a user macro. - [enum Implementation](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/enum.Implementation): How a `MemoryRequest` is best built. NOT always a macro — and getting this wrong is expensive in both directions. - [enum PdkUnsupported](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/enum.PdkUnsupported): Why a process cannot build what was asked for. Typed, so a caller cannot mistake a refusal for a plan — the mistake that produces a design nobody can fabricate. - [const FLOP_BIT_UM2](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/constant.FLOP_BIT_UM2): Silicon area per stored bit when an array is built from FLIP-FLOPS, in um^2. - [const GF180MCUC](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/constant.GF180MCUC): GlobalFoundries 180 nm MCU. The variant this project’s vendored OpenLane supports is C. - [const MEASURED_CELLS_PER_MM2](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/constant.MEASURED_CELLS_PER_MM2): Measured standard-cell density on this flow: 173,895 cells/mm^2, the median across the twelve sky130 blocks in `benchmarks/silicon/sky130_signoff*.json` (range 121k-224k). - [const SKY130A](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/constant.SKY130A): SkyWater 130 nm, the process every block in this repo has been hardened on. - [const SKY130A_LAYER_RC](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pdk_target/constant.SKY130A_LAYER_RC): sky130A signal-layer RC for the pre-route estimate. ## logicaffeine_compile::codegen_sva::plasticine The Plasticine mesh descriptor — the open RDU (Prabhakar et al., ISCA 2017) and its SARA/Capstan-era successor configuration — as a physically-described target that wraps the certified `FabricTarget` seam. - [struct DramSpec](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine/struct.DramSpec): Off-chip memory of a Plasticine configuration: channel count, kind, and published peak bandwidth. - [struct PlasticineBackend](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine/struct.PlasticineBackend): The Plasticine backend: certifies a placement TODAY (backend-agnostic SAT proof). Counted loops reach the open toolchain (Spatial → PIR → plastiroute → Tungsten, mirrored at gitlab.com/dataplane-ai) as Spatial source through `super::spatial_emit` and `largo emit plasticine`; a placed straight-line `Grid` has no Spatial/PIR form yet, so its artifact is the ready-to-bridge neutral placement with the reason stated. - [struct PlasticineTarget](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine/struct.PlasticineTarget): A published Plasticine mesh configuration. ## logicaffeine_compile::codegen_sva::plasticine_place Mesh placement + static routing for a Plasticine configuration — P3 of the Plasticine lane. - [struct Allocation](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/struct.Allocation) - [struct BufferAllocation](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/struct.BufferAllocation): PMUs one buffer edge needs. - [struct LinkBudget](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/struct.LinkBudget): Switch/link budget per mesh segment (Spade `SpadeConfig` defaults: `vlink 2`, `slink 4`, `vc 4`). - [struct MeshNet](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/struct.MeshNet): One vector net to route. - [struct MeshRouting](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/struct.MeshRouting): The vector nets of one placement, routed. For every net, in order: the mesh links it occupies, and its occupancy keys — `(link, 0)` for a channel of a directed link, `((cell, cell), 1)` for a perimeter port carrying DRAM → mesh and `((cell, cell), 2)` for mesh → DRAM — so that the largest count over keys of a legal routing never exceeds the channel budget. - [struct Placed](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/struct.Placed) - [struct Placement](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/struct.Placement) - [struct Route](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/struct.Route): A routed edge: PCU (writer chain tail) → PMU → PCU (reader chain head), with its hop count. - [struct StageAllocation](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/struct.StageAllocation): PCUs one stage needs. - [enum Endpoint](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/enum.Endpoint): A net endpoint on the mesh. - [enum Unit](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/enum.Unit): A placed unit on the checkerboard. - [trait MeshRouter](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/trait.MeshRouter): A router for the mesh’s vector nets. `place_unrolled` places with row-balanced cells and routes through the installed router (`place_routed`), or falls back to `place`’s xy-static routes when none is. - [fn allocate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/fn.allocate): Allocate PCUs/PMUs for `mp` on `t`; `buffer_words[i]` is the tile size flowing over `mp.edges[i]`. Every stage is hosted on PCUs. - [fn allocate_hosted](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/fn.allocate_hosted): `allocate` with the stages listed in `ag_stages` hosted on the PERIMETER ADDRESS GENERATORS (ISCA’17 §3.4: the AGs at the chip’s edges drive the DRAM tile loads and stores) rather than on PCUs: such a stage takes no PCU and places no FU stage; `place` routes it from the mesh edge. - [fn dram_streams](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/fn.dram_streams): Perimeter DRAM ports one instance of `mp` needs, `(into the mesh, out of the mesh)`: every buffer edge written by a perimeter-hosted stage is one inbound stream, every edge read by one is one outbound stream (each PMU of a spanning buffer is its own stream). - [fn install_mesh_router](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/fn.install_mesh_router): Install this process’s mesh router, once; `Err` hands back the argument when one is already installed. Certified place-and-route installs its congestion-negotiating router this way, from its own side: the compiler never depends on it, so the published tree builds without it. - [fn lanes_need_banks](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/fn.lanes_need_banks): The capability a placement demands of the descriptor beyond depth: at least one bank per lane for a conflict-free vector access (Plasticine: 16 banks for 16 lanes). - [fn max_par](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/fn.max_par): The widest unroll factor whose replicated allocation fits `t` by CAPACITY (at least 1 when one instance fits) — PCUs, PMUs, and the perimeter DRAM ports (`rows × 2 sides × vector_links` per direction, ISCA’17 §3.4–3.5) — before routing is considered. - [fn max_routable_par](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/fn.max_routable_par): The widest unroll that fits `t` AND routes statically within `budget` — the routability-aware unroll (the static vector network’s perimeter ports, not PCU/PMU capacity, bound a DRAM-fed unroll first on a large mesh). Returns `(routable, capacity)`; `routable == 1` is reported even when a single instance exceeds the budget, so a row can still say `routed_statically: false` honestly. - [fn max_routable_par_within](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/fn.max_routable_par_within): `max_routable_par` searching below `upper` (capped at capacity) — for an unroll that the work itself bounds below capacity (fewer outer iterations than instances). The search is a BISECTION over `[1, upper]`: routability is treated as monotone in the unroll (more instances, more perimeter streams), so the result is the widest unroll the bisection finds routable — a stalled negotiation at some intermediate width would hide a wider routable one, which is the honest limit of a heuristic router without the exact rung on the full problem. - [fn mesh_router](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/fn.mesh_router): The installed mesh router, if any. - [fn place](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/fn.place): Place the allocation on the checkerboard in pipeline order (a row-major snake over PCU cells, each stage’s chain contiguous, each edge’s PMU(s) taken from the PMU cells nearest the writer’s tail), then route every edge X-Y and count link occupancy against the budget. - [fn place_metapipeline](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/fn.place_metapipeline): Allocate + place in one call. - [fn place_routed](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/fn.place_routed): Place `alloc` on the checkerboard with row-balanced PCU cells and each edge’s PMU(s) on the free PMU cells nearest its writer and reader (a perimeter-hosted end pulls the PMU toward the nearer side), then route every vector net — writer tail → PMU → reader head per buffer, DRAM ↔ PMU for perimeter-hosted stages, and the PCU→PCU links inside every chain (reported as a route on the self-edge `(stage, stage)`) — through `router`, whose independent legality verdict is `routed_statically`. `max_link_occupancy` counts the channels one directed link — or one direction of a perimeter port — carries (never above the budget when legal). - [fn place_unrolled](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/fn.place_unrolled): Allocate `mp` (with `ag_stages` on the perimeter address generators) once, unroll it `par` ways, and place every instance — a typed `TooSmall` when the replicated allocation exceeds the mesh. - [fn pmus_for](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/fn.pmus_for): PMUs a `depth`-deep N-buffer of `words` needs on `t`: a PMU’s address space is partitioned `depth` ways (Spatial’s N-buffering), so one PMU holds `words_per_pmu / depth` words per buffer; an empty tile still occupies one PMU (the buffer exists). - [fn words_per_pmu](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/fn.words_per_pmu): 32-bit words one PMU holds (ISCA’17: 16 banks × 16 KB = 256 KB = 65,536 words). - [type Link](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_place/type.Link): A mesh link `((r,c),(r',c'))`; a link whose ends coincide is a perimeter port of that edge cell. ## logicaffeine_compile::codegen_sva::plasticine_report The Plasticine report — P4 of the Plasticine lane: the artifact an RDU engineer reads, generated from the model so no number in it is typed by hand. - [struct BufferRow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/struct.BufferRow) - [struct CertificateRow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/struct.CertificateRow) - [struct ChannelRow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/struct.ChannelRow): One channel’s control plane: the credit solve beside Spatial’s N-buffer rule, and which one binds. - [struct ControlRow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/struct.ControlRow): The control plane as a whole: two nets per channel, budgeted on the scalar network. - [struct GemmRow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/struct.GemmRow) - [struct OperandRow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/struct.OperandRow): One operand of a GEMM and how the compiler decided to feed the unrolled instances. - [struct PlasticineArtifact](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/struct.PlasticineArtifact): The placed, certified artifact of one counted loop on a Plasticine target — what `largo emit plasticine` writes and `crate::compile::compile_to_plasticine` returns. - [struct StageRow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/struct.StageRow) - [struct VmAnchor](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/struct.VmAnchor) - [struct Workload](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/struct.Workload) - [struct WorkloadRow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/struct.WorkloadRow): One (workload, target) row of the report. - [enum WorkloadKind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/enum.WorkloadKind): What a workload is. - [const CALIBRATION_PATH](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/constant.CALIBRATION_PATH): The calibration file joining each toolchain row with our MODELED counterpart (generated with the report). - [const CALIBRATION_TOLERANCE_PCT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/constant.CALIBRATION_TOLERANCE_PCT): The per-cent difference the calibration lock allows between modeled and simulated cycles. - [const CERTIFICATE_WIDTH](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/constant.CERTIFICATE_WIDTH): The bit width the routed-datapath certificate is proven at (the bounded fragment). - [const PROVENANCE_MODELED](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/constant.PROVENANCE_MODELED): The provenance every row carries: a paper-parameterized model, never a simulation or silicon. - [const PROVENANCE_SIMULATED](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/constant.PROVENANCE_SIMULATED): The provenance of a toolchain-simulated row. - [const REPORT_PATH](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/constant.REPORT_PATH): Where the generated report lives (repo-relative). - [const TOOLCHAIN_LEDGER_PATH](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/constant.TOOLCHAIN_LEDGER_PATH): The public toolchain’s ledger (written only by `scripts/accel/plasticine-gate-ledger.py`): Tungsten simulations. - [const UNMODELED_KINDS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/constant.UNMODELED_KINDS): The kinds of toolchain row the model has no counterpart for, each with the reason — listed in the calibration as uncalibrated, never dropped and never joined with a model that does not describe them. - [fn blackscholes_query](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.blackscholes_query): The option price of Spatial’s `BlackScholes` regression app (`pir/regression/BlackScholes.scala`, `BlkSchlsEqEuroNoDiv`, with the Taylor approximations of `spatial.lang.api.MathAPI` its `CNDF` and the pricing call), transcribed: over the columns `prices`, `strikes`, `rates`, `vols`, `times` (`Real`) and `types` (`Int`), read in that order. Spatial’s `-x` is LOGOS’s `0 - x`. - [fn calibration](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.calibration): The calibration document: every toolchain row on a mesh we model, joined with the model, and every row of a kind the model does not describe, or whose routed run did not finish clean, listed as uncalibrated with the reason. - [fn calibration_row](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.calibration_row): One toolchain row joined with our model: the same app shape, tile (`ts`) and a single instance (its loop pars are 1), on the same mesh — modeled cycles vs Tungsten’s, the per-cent difference, and the unit counts side by side (PIR’s PCU count includes the control/address units its partitioner splits off; our row counts compute PCUs and perimeter address-generator stages separately — printed, not conflated). A dot product is the `1 × 1 × N` GEMM: its `ts` the K-chunk, its `ip` the reduce’s lanes, and its `op` (how many tiles are reduced at once) the GEMM’s `loop_kk`. Rows of `kind: "dot"` are modeled as that GEMM. - [fn canonical_targets](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.canonical_targets): The two published configurations. - [fn canonical_workloads](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.canonical_workloads): The canonical workloads: the metapipeline corpus, the MoE argmax round, a dot product, and the two GEMM shapes the Tenstorrent ledger measures. - [fn counted_loop_fabric](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.counted_loop_fabric): The counted-loop shape the single-stage metapipeline model takes — the FIRST gate of `lower_counted_loop`, on its own so a lane can ask the question without placing: `fn_name` of `source` as a `LoopFabric` (a numeric `Repeat for i from lo to hi` over scalar carried state), or the typed reason it is not one. - [fn gda_query](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.gda_query): The covariance step of Spatial’s `GDA` regression app (`pir/regression/GDA.scala`), transcribed: over the arrays `y` (at the row), `x` (row-major), `mu1` and `mu0` (at the column), read in that order, the row term `x(rr, cc) - mux(y(rr) == 1, mu1(cc), mu0(cc))`, each row’s outer product with itself summed into `sigma`. - [fn gemm_metapipeline](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.gemm_metapipeline): The per-tile GEMM metapipeline on `t`: load (perimeter AGs: A row-panel + B column-panel, DRAM → PMU) → mac-reduce (a PCU: `lanes`-wide multiply, the `log2(lanes)+1`-stage reduction tree, the accumulator fused into its last stage — ISCA’17 §3.1) → store (AG: the C tile). Returns the metapipeline, the words on each edge (`[A+B panel, C tile]`) and the AG-hosted stage indices. - [fn gemm_row](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.gemm_row): The GEMM row: the tile (or the PMU-fitting default), the unroll (or the widest that fits AND routes statically; `par_capacity` records the capacity bound), the placement, and the roofline — compute cycles at the pipeline II vs the DRAM channel bandwidth over the bytes the tiling moves (B column-panels once, A re-streamed per column panel, C once). A GEMM row with mesh replication only — the intra-tile loops run one pass each. - [fn gemm_row_unrolled](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.gemm_row_unrolled): `intra` is the product of the unrolls INSIDE one tile’s chunk (the emitted nest’s row and column loops) and `kk` the reduction chunks run side by side (`loop_kk`, a dot product’s `op`): both divide the work per tile, where `par` divides the number of column panels — different axes, and the model needs each to reproduce an unrolled program. `k_tile` is the reduction chunk the operands stream in (Spatial’s `ts` along K; `None` streams a tile’s panels whole). - [fn gemm_tile_for](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.gemm_tile_for): The largest square tile (a multiple of 8, at least 1) whose double-buffered A row-panel + B column-panel (`2 · tile · k` words) fits ONE PMU on `t`. - [fn kmeans_distance_query](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.kmeans_distance_query): The distance a feature adds in Spatial’s `Kmeans` regression app (`pir/regression/Kmeans.scala`), transcribed: `(pts(pt,d) - cts(ct,d)) ** 2` over the point’s feature and the centroid’s, read in that order. - [fn logos_blackscholes_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.logos_blackscholes_program): Black-Scholes in LOGOS over `n` options, as Spatial’s BlackScholes app prices them — its Taylor approximations written as LOGOS functions, the six columns declared in the app’s order and filled with residues (types `p % 2`, the prices, strikes, rates, volatilities and times scaled into ranges the approximations are taken over), every option priced by one counted loop. It shows `Σ (t + 1)·out[t]`, a checksum a permuted or partial result does not reproduce. - [fn logos_dot_program](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.logos_dot_program): A canonical LOGOS dot product `Σ_{t MIN_DATE && date < MAX_DATE && disct >= MIN_DISC && disct <= MAX_DISC && quant < 24 ? price·disct : 0` with its `MIN_DATE = 0`, `MAX_DATE = 9999`, `MIN_DISC = 0`, `MAX_DISC = 9999`. - [fn unmodeled](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.unmodeled) - [fn workload_row](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/plasticine_report/fn.workload_row): The row for any workload on `t`. ## logicaffeine_compile::codegen_sva::pmu The PMU banking model — P2 of the Plasticine lane: the Pattern Memory Unit’s scratchpad as the papers describe it (ISCA’17 §3.2), with an executable meaning. - [struct AffineAccess](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pmu/struct.AffineAccess): One vector access: lane `l` reads/writes `base + stride * l` for `l` in `0..lanes`. - [struct Pmu](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pmu/struct.Pmu): Banked storage with a flat-address interface: the executable meaning of the banking modes. - [struct PmuSpec](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pmu/struct.PmuSpec): A PMU’s published shape. - [enum BankingMode](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pmu/enum.BankingMode): How addresses map to banks. - [fn address_datapath_stages](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pmu/fn.address_datapath_stages): FU stages the address datapath needs for an affine address `base + Σ stride_k * idx_k` over `dims` counters (+1 for the lane offset when vectorized): one multiply-add per dimension, chained. - [fn address_fits](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pmu/fn.address_fits): Gate an address pattern against the PMU’s datapath depth — typed refusal. - [fn bank_of](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pmu/fn.bank_of): The bank an address lives in under `mode`. - [fn conflicts](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pmu/fn.conflicts): Cycles a vector access costs: the most lanes that land in one bank (1 = conflict-free). Under duplication a read is always 1 (every bank has the data; lanes are served from distinct copies). - [fn memory_ii](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pmu/fn.memory_ii): The memory II of a stage: the costliest of its vector accesses per iteration. - [fn strided_banking_for](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pmu/fn.strided_banking_for): The strided-banking configuration that makes a stride-`stride` vector access conflict-free: granularity = stride (lane `l` lands in bank `(base/stride + l) % banks`, all distinct while `lanes <= banks`). ## logicaffeine_compile::codegen_sva::pnr_certificate Proof-carrying place-and-route. - [struct PlacementCertificate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pnr_certificate/struct.PlacementCertificate): A machine-checkable certificate that a placed mapping `grid` computes its datapath spec for every bounded assignment. It carries the refuted CNF (`¬(grid ≡ datapath)`) and the propagation-redundancy + RUP refutation of it. It is self-contained: `recheck` needs nothing but the certificate. - [enum CertifyRefusal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pnr_certificate/enum.CertifyRefusal): Why a mapping earned no certificate. The three answers are genuinely different — “we cannot express this obligation”, “we will not pay to materialise it”, and “it is not true” — and a caller that prints `Uncertified { reason }` must not collapse them into one sentence. - [const GATE_BUDGET_NODES](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pnr_certificate/constant.GATE_BUDGET_NODES): How large a SHARED GATE DAG the certificate path will pay to refute. - [fn certify_external_placement](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pnr_certificate/fn.certify_external_placement): Import-and-certify — the SDK-facing seam. Certify a placement PRODUCED BY AN EXTERNAL TOOL (e.g. the SambaFlow place-and-route) against the English `source` datapath: lower the external `placement` grid and the `source` spec to the same bounded fragment, then prove they agree for every input and keep the re-checkable witness. Returns `None` (fail-closed) if the placement is NOT equivalent to the source, or the obligation escapes the propositional fragment. We need nothing from the vendor but the placed grid — no config format, no trust in their placer: the certificate stands on its own via `PlacementCertificate::recheck`. This is how a vendor mapping earns a proof it computes the intended program. - [fn certify_gates](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pnr_certificate/fn.certify_gates): Certify a placement whose grid and datapath are ALREADY blasted into the shared gate DAG — the path that never materialises a `ProofExpr` tree, and therefore the only one that can certify a reconvergent datapath (a multiply chain’s tree is exponentially larger than its circuit). Fail-closed exactly like `certify_mapping`: a grid that is not equivalent to its spec earns no certificate. - [fn certify_gates_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pnr_certificate/fn.certify_gates_bounded): `certify_gates` with the refusal NAMED, against the production `GATE_BUDGET_NODES`. - [fn certify_gates_within](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pnr_certificate/fn.certify_gates_within): `certify_gates_bounded` against an EXPLICIT gate ceiling — the seam a lock shrinks to prove the budget is live code and not a constant nobody reads. - [fn certify_mapping](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pnr_certificate/fn.certify_mapping): Emit a proof-carrying certificate that the placed `grid` equals the `datapath` spec for every bounded input, by refuting `¬(grid ≡ datapath)` and KEEPING the checkable refutation. Fail-closed: returns `None` when the equivalence does not actually hold (a wrong mapping earns no certificate) or the obligation leaves the propositional fragment (bit-blast the datapath first). A returned certificate is guaranteed `recheck`-valid by construction — the underlying prover only hands back a refutation it has already PR/RUP-verified. - [fn certify_mapping_bounded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pnr_certificate/fn.certify_mapping_bounded): `certify_mapping` with the refusal NAMED. The obligation is PRICED in the shared gate DAG before any `ProofExpr` is materialised, so an encoding too big to hold fails as a typed refusal in milliseconds instead of walking the allocator off a cliff. - [fn certify_mapping_within](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/pnr_certificate/fn.certify_mapping_within): `certify_mapping_bounded` against an EXPLICIT bit-blast ceiling — the seam a lock shrinks to prove the budget is live code and not a constant nobody reads. ## logicaffeine_compile::codegen_sva::power Power-Aware Formal Verification - [struct PowerCrossing](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/power/struct.PowerCrossing): A signal crossing between power domains. - [struct PowerDomain](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/power/struct.PowerDomain): A power domain definition. - [struct PowerReport](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/power/struct.PowerReport): Power analysis report. - [struct PowerViolation](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/power/struct.PowerViolation): A power violation. - [enum PowerState](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/power/enum.PowerState): Power domain state. - [enum PowerViolationType](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/power/enum.PowerViolationType): Power violation type. - [fn analyze_power](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/power/fn.analyze_power): Analyze power domains and crossings for violations. - [fn power_sequence_properties](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/power/fn.power_sequence_properties): Generate SVA properties for power sequencing. - [fn verify_isolation](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/power/fn.verify_isolation): Generate SVA properties for power isolation verification. ## logicaffeine_compile::codegen_sva::preflight Whether a persona build fits the card’s partial-reconfiguration region and can close its clock, decided before Quartus runs, from what the build ledger has measured. - [struct Capacity](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/struct.Capacity): What a persona may use: the region the ledger’s last persona was placed in, and that compile’s name. - [struct Design](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/struct.Design): A design as the timing model reads it: its area, its deepest path and its loop bound, in the model’s unit. - [struct Holds](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/struct.Holds): A design’s or a device’s ALMs, DSP blocks and M20K blocks. - [struct Packing](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/struct.Packing): How Quartus packs a synthesis into ALMs: the ALMs an ALUT takes, over the syntheses their ALUTs set, and the ALMs a register takes, over the syntheses their registers set (none when the ledger records no such synthesis). - [struct PartTiming](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/struct.PartTiming): One timed part’s figures. - [struct Predicted](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/struct.Predicted): What a design is predicted to take and how fast it can run. - [struct Preflight](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/struct.Preflight): A design’s preflight: what it is predicted to take, the region it is held to, every refusal, and every way it is tight without being refused. - [struct Target](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/struct.Target): The clock a design must close: its period, and the nanoseconds one unit of the model’s delay takes on the card. - [struct Timed](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/struct.Timed): A part of a design timed on its own: its name, its design, and the periods its paths have. - [enum DesignError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/enum.DesignError): Why a timing graph is no design: one the model could not time, or not a graph. - [enum LoopBound](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/enum.LoopBound): The loop bound of a design: no loop, a loop through no register, or the most delay a register a loop holds. - [enum Refusal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/enum.Refusal): Why a design is not built. - [const DEVICE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/constant.DEVICE): What the D5005’s device holds: the 1SX280’s ALMs, DSP blocks and M20Ks. - [fn alms_per_alut](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/fn.alms_per_alut): The ALMs Quartus packs an ALUT into (`packing`’s, over the syntheses their ALUTs set). - [fn capacity](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/fn.capacity): The PR region of the last persona compile the ledger records with one. - [fn device_library](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/fn.device_library): The device primitives `verilog` instantiates and does not define, each declared as the box it is: the card’s floating-point DSP block (`fourteennm_fp_mac`, `super::fp_oracle::fp_mac_blackbox`), which only Quartus elaborates. - [fn fitter_seconds](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/fn.fitter_seconds): The fitter’s time for a persona of `alms` ALMs: `seconds = a × alms^b`, least squares in logs over every persona fit the ledger records with its region and fitter time; none without two of different sizes. - [fn fullest](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/fn.fullest): The fullest persona that fit: the passed compile whose region needed the most ALMs, and those ALMs. - [fn over](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/fn.over): Each resource `needs` takes past what `device` holds, named. - [fn packing](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/fn.packing): The packing every synthesis the ledger records from one Verilog file shows: each synthesis’s estimated ALMs over its top’s ALUTs and registers, each synthesis set by the term the larger packing gives it (first by which it holds more of), each packing the geometric mean over the syntheses it sets, settled when no synthesis changes side. - [fn preflight](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/fn.preflight): The preflight of `design` against what `ledger` and `calibration` measured, at `target`, timed whole a period a path. - [fn preflight_domains](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/fn.preflight_domains): The preflight of a design of `area`, each of its `parts` timed on its own at its cycles of `target`’s period. - [fn synthesized_holds](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/preflight/fn.synthesized_holds): What a synthesized flat image needs of the device, from its synthesis report: the ALMs and DSP blocks its partitions’ estimates sum to, and the M20K blocks the fitter gives its memories (`floorplan::Ram::m20k`, every partition’s), not its block memory bits over a block’s 20,480: a stack of blocks a power of two deep, and a byte-enabled block’s 32 bits, take more blocks than the bits do. None when the report gives no partition’s ALMs or DSP blocks. ## logicaffeine_compile::codegen_sva::protocols Pre-Verified Protocol Templates - [mod riscv](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/protocols/riscv/): RISC-V ISA Formal Verification Templates - [struct ProtocolProperty](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/protocols/struct.ProtocolProperty): A protocol template — produces parameterized SVA properties. - [fn apb_protocol](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/protocols/fn.apb_protocol): APB setup/access phase properties. - [fn axi4_write_handshake](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/protocols/fn.axi4_write_handshake): AXI4 write channel handshake properties. - [fn i2c_protocol](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/protocols/fn.i2c_protocol): I2C properties. - [fn spi_protocol](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/protocols/fn.spi_protocol): SPI properties. - [fn uart_tx](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/protocols/fn.uart_tx): UART transmit properties. ## logicaffeine_compile::codegen_sva::protocols::riscv RISC-V ISA Formal Verification Templates - [struct RiscvConfig](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/protocols/riscv/struct.RiscvConfig): RISC-V CPU configuration. - [enum RiscvExtension](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/protocols/riscv/enum.RiscvExtension): RISC-V extension identifiers. - [fn riscv_alu_properties](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/protocols/riscv/fn.riscv_alu_properties): Generate ALU instruction properties. - [fn riscv_branch_properties](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/protocols/riscv/fn.riscv_branch_properties): Generate branch instruction properties. - [fn riscv_decoder_properties](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/protocols/riscv/fn.riscv_decoder_properties): Generate decoder mutual exclusion properties. - [fn riscv_memory_properties](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/protocols/riscv/fn.riscv_memory_properties): Generate memory access properties. - [fn riscv_register_properties](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/protocols/riscv/fn.riscv_register_properties): Generate register file properties. ## logicaffeine_compile::codegen_sva::psram The off-chip memory edge for a QSPI PSRAM — the block behind the memory-edge descriptor contract when the far side is a pseudo-SRAM instead of a DRAM. - [struct EdgeOverrides](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/struct.EdgeOverrides): Controller parameters a test may override, to drive the part out of its rules on purpose. - [struct PsramBurst](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/struct.PsramBurst): One burst: `words` consecutive 64-bit words from word address `word_addr`, one CE# low. - [struct PsramCache](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/struct.PsramCache): The heap cache in front of the edge: direct-mapped, write-back and write-allocate, `2^index_bits` lines of `2^offset_bits` words, each line filled and written back as one burst. - [struct PsramEdge](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/struct.PsramEdge): The edge: a part, the system clock that drives the controller, and the number of system cycles per SCLK half-period. The controller counts cycles, so the rules that set a minimum time — tPU, tRST, tCPH, tCLK, tACLK — are met for every clock no faster than `sys_period_ps`, while tCEM, which caps how long a burst may hold CE# low, must hold at the slowest clock the edge is run at, `slowest_period_ps`. - [struct PsramPart](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/struct.PsramPart): A QSPI PSRAM, as its datasheet specifies it. Times in picoseconds. - [enum PsramUnplaceable](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/enum.PsramUnplaceable): Why an edge or a plan cannot be built for a part. - [const APS6404L_3SQN](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/constant.APS6404L_3SQN): AP Memory APS6404L-3SQN: 64 Mb (8M x 8) QSPI PSRAM, 3.3 V package, standard temperature grade. - [const EDGE_WORD_ADDR_BITS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/constant.EDGE_WORD_ADDR_BITS): Width of the edge’s word address (`req_addr`): the 24-bit QPI byte address of an 8 MiB part, less the three bits inside a word. - [fn check_legal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/fn.check_legal): Every rule a burst plan must satisfy, checked independently of the planner. - [fn emit_psram_arbiter_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/fn.emit_psram_arbiter_testbench): A randomized testbench for caches sharing the edge through the arbiter: `n` caches, each over its own region of the part, driven by one engine-shaped driver that issues to any subset of them in the same cycle — a read, a write, or a write and a read each — and nothing while any is `busy`. Prints `MULTI-ERRORS`, `PSRAM-VIOLATIONS`, the longest stall as `MULTI-MAX-STALL`, then `MULTI-DONE`. - [fn emit_psram_arbiter_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/fn.emit_psram_arbiter_verilog): Several caches share one edge. When the edge is idle the lowest-numbered requester is granted and its request goes to the edge; that cache owns the edge until the burst completes and sees `c_ready` exactly once more when it does, in a cycle in which no other cache is granted. The edge’s write-data takes and read strobes go to every cache: only the owner is ever in a burst state, the only states that listen. - [fn emit_psram_cache_hit_function](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/fn.emit_psram_cache_hit_function): The engine-side lookup of a cache’s registered hits: `{inst}_hit(a)`, the hit of address `a` in the cache instance `inst`’s lines as they will hold after this edge — none after a reset, and a fill completing now holding the line it fills — read from the instance’s exported `{inst}_tags`, `{inst}_vals`, `{inst}_filled`, `{inst}_fidx` and `{inst}_ftag`. Registering `{inst}_hit(a)` beside an address `a` the engine sets, and `{inst}_hit` of the held address every other cycle, gives the cache exactly the hit it would have looked up itself, a cycle earlier. - [fn emit_psram_cache_hit_wires](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/fn.emit_psram_cache_hit_wires): The wires a cache instance `inst` exports to its engine-side lookup (`emit_psram_cache_hit_function`), declared. - [fn emit_psram_cache_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/fn.emit_psram_cache_testbench): A randomized testbench for the cache: an engine-shaped driver that issues nothing while `busy` and otherwise a read (then waits a cycle and checks `rd` against a reference memory), a write of one or both halves of a word, or a write and a read together. Once the edge has initialized the part it writes every word it will use — `words` consecutive from 0 and `words` scattered over the whole part — then runs `ops` random operations. Prints `CACHE-ERRORS`, `PSRAM-VIOLATIONS`, the longest `busy` run as `CACHE-MAX-STALL`, the rising edge after reset at which `req_ready` was first seen as `EDGE-READY-AT`, then `CACHE-DONE`. The clock runs at `run_period_ps`, anywhere in the edge’s range. - [fn emit_psram_cache_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/fn.emit_psram_cache_verilog): The cache. Its engine side is a registered-read memory port: `ra` holds the read address and `rd` is `data[ra]` one cycle later, refreshed every cycle, so a resident line reads exactly as a block RAM does; `req_r`/`req_w` pulse the cycle after the engine issues a read or a write, whose address, data and half-word enables `wm` hold until its next one. `busy` is high while a miss is served — a dirty victim written back, then the line filled, with a write miss merging its enabled halves into the fill — and while a read issued together with a write waits for it. - [fn emit_psram_edge_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/fn.emit_psram_edge_testbench): A testbench: the controller and the model, the bursts issued in order (write data taken from `wdata` in order), every word read printed as `RD `, every burst’s cycles from acceptance to the next `req_ready` as `BURST `, then the model’s total and `PSRAM-DONE`. - [fn emit_psram_edge_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/fn.emit_psram_edge_verilog): The controller. One request is one burst: `req_len` words at word address `req_addr`. A write takes `wdata` at the start of each word (pulsing `wdata_take`); a read returns each word on `rdata` with a one-cycle `rdata_valid`. `req_ready` is high whenever a request can be taken. - [fn emit_psram_model_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/fn.emit_psram_model_verilog): A pin-level model of the part: its semantics (SPI until Enter-QPI, Reset-Enable + Reset before use, bursts wrapping inside a page) and every rule it checks — the timing rules, an SIO bit the part samples that nobody drives (`float`), and a host driving against the part’s read data (`contend`) — each counted by name on a `PSRAM-VIOLATION ` line. `violations` holds the total. - [fn plan_stream](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/fn.plan_stream): Split a stream of 8-byte words into bursts the part can take: at every page boundary and at the longest burst tCEM allows. A strided stream is one burst per word. - [fn psram_cache_hit_ports](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/psram/fn.psram_cache_hit_ports): The port connections of a cache instance `inst` whose engine registers its hits in `rhit` and `whit`. ## logicaffeine_compile::codegen_sva::qor_harness qor_harness — the measurement harness of the comparative-synthesis bench. - [struct Bind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.Bind): Contract bits `[lsb, lsb + width)` of port `contract` connect to DUT port `dut`. Several binds to one input DUT port concatenate, the first in the least significant bits; an input DUT port wider than what is bound to it is sign-extended when the topmost bound contract field is signed, else zero-extended. An output DUT port contributes its low `width` bits. - [struct Candidate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.Candidate): One implementation of a kernel, as the harness drives it. - [struct DcrBus](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.DcrBus): A device’s configuration-register port: `valid` with `rw` high writes `data` to register `addr`; with `rw` low it reads, and the device answers on `rsp_valid`. - [struct DcrWrite](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.DcrWrite): One configuration-register write. - [struct Drive](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.Drive): DUT input `dut` takes `value` in beat `beat` of every call; a port is 0 in the beats that do not drive it. - [struct DutPort](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.DutPort): A port of the DUT’s top module, as its netlist declares it. - [struct Field](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.Field): How one 64-bit chunk of an input port is drawn from its lane word: `lanes` packed sub-lanes of `width` bits each. A single-lane field is `base + slice` (sign-extended when `signed`) as a 64-bit value; a packed field (`lanes > 1`) carries no offset and packs each sub-lane’s raw slice. - [struct ImageLine](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.ImageLine): One constant line of a device’s memory (a program image): its line address and its bytes in hex, the byte at the highest address first. - [struct InPort](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.InPort): An input port of a kernel contract: `bits` wide, one `Field` per 64-bit chunk (least significant first). A port with `hold > 1` (a power of two) keeps the value drawn at its first operation for `hold` operations — a weight tile reused across rows. - [struct Kernel](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.Kernel): A kernel of the bench: its contract and its golden. - [struct LineBus](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.LineBus): The memory a device reads and writes whole lines of, served by the harness over `ports` channels: each a request (`_req_valid`, `_rw`, `_byteen`, `_addr` — a line address — `_data`, `_tag`, `_ready`) and a read response (`_rsp_valid`, `_data`, `_tag`, `_ready`); a write has no response. Each signal carries every port’s value side by side, port 0 in the most significant bits when `msb_first`. The harness accepts every request and answers each read in order on its port from the next cycle on, with the line as it is when answered: an ideal memory, never a candidate’s bottleneck. - [struct LineRegion](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.LineRegion): Lines of a device’s memory holding contract ports from line `base_line` on: the listed ports in order, each as `words_per_port` words, packed from the region’s first byte. An input region answers reads with the call’s operands; an output region keeps the device’s writes. - [struct Manifest](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.Manifest) - [struct ManifestEntry](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.ManifestEntry): A third-party candidate: the harness-facing description, the tool (a key of `scripts/qor/qor-tools.toml`), the source it read and the exact command that generated its files. - [struct ManifestFile](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.ManifestFile): One generated RTL file of a third-party candidate and the SHA3-256 of its bytes. - [struct ManifestRefusal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.ManifestRefusal): A candidate a tool would not build — its crash, its error, or its deadline — kept in the manifest so the comparison prints a refusal in that cell rather than a silent gap. - [struct MemBind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.MemBind): Contract ports carried through a memory interface instead of scalar ports. The memory’s words are the listed contract ports in order, each split into `words_per_port` words (least significant first), so one wide port can become an array and several ports one array. - [struct OutPort](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.OutPort): An output port of a kernel contract. - [struct RegSlot](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.RegSlot): One cycle of a register-file transfer: contract bits `[lsb, lsb + width)` of port `contract`. - [struct Reset](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.Reset): A DUT reset input. - [struct Run](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/struct.Run): A finished testbench run: results folded, the signature, total cycles, the cycle the first result was folded on, and the (ops, cycles) mark at half the run. - [enum Dir](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/enum.Dir): A DUT port’s direction. - [enum DriveValue](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/enum.DriveValue): What a beat schedule drives onto one DUT input port in one beat. - [enum Golden](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/enum.Golden): The reference a kernel’s results are checked against. - [enum MemKind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/enum.MemKind): The memory protocol a `MemBind` speaks. - [enum Mode](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/enum.Mode): Which values a field draws: uniformly over its domain, or only its two ends. - [enum Protocol](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/enum.Protocol): How the harness hands operands to a candidate and collects its results. - [enum QorError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/enum.QorError): Why a harness, golden, or run was refused. - [enum SourceKind](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/enum.SourceKind): Where a kernel’s LOGOS candidate comes from: compiled from a LOGOS program by the compiler, or written by one of the RTL generators in this module tree. - [const GEMM_ACC_BITS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/constant.GEMM_ACC_BITS): The accumulator width every GEMM candidate’s output carries. - [const GEMM_BITS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/constant.GEMM_BITS) - [const GEMM_DIM](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/constant.GEMM_DIM): GEMM tile rows and columns, and the operand width. - [const GEMM_MATCHED_ACC_BITS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/constant.GEMM_MATCHED_ACC_BITS): The narrower accumulator Gemmini’s default configuration gives its mesh (`spatialArrayOutputType` SInt(20)): wide enough for every sum of eight int8 products, so the matched rows compute the same results with less state. - [const K6_PORTS_EVERY](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/constant.K6_PORTS_EVERY): The K6 ports engine’s register placement: a register after every `K6_PORTS_EVERY`-th level of each lane’s multiply tree and after its last (`simt_ports`). MEASURED (2026-10-18, Sky130 HD: yosys 0.33 with OpenLane v1’s `DELAY 0` ABC script at a 2 ns target, OpenSTA at the typical corner, no wires; a step every clock throughout): every level = 536,394 µm² at 3.35 ns and 8 clocks; every second = 488,462 at 3.86 and 5; every third = 468,797 at 5.10 and 4; the product only = 437,985 at 8.30 and 3; no register in the tree = 423,320 at 9.27 and 2. Every second is within 5% of every level in steps a second per area, with 39% of its flip-flops and three clocks fewer. - [const K6_STREAMED_EVERY](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/constant.K6_STREAMED_EVERY): The streamed K6 engine’s register placement: a register after every `K6_STREAMED_EVERY`-th level of its multiply tree (`LaneArith::Streamed`). MEASURED (2026-10-17, Artix-7 fabric map, yosys 0.33 synth_xilinx + nextpnr-xilinx, median of the seeds that routed): every level = 3421 LUTs at 128.2 MHz and 24 clocks an operation, 1.56 million results a second per thousand LUTs; every second = 3403 at 106.6 MHz and 21 clocks, 1.49; every third = 3394 at 90.7 and 20, 1.34; the whole tree in one stage = 3387 at 63.7 and 19, 0.99. Fewer registers hold half (every second) to a quarter (one stage) of the flip-flops. - [const LANE_MIX](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/constant.LANE_MIX): The per-lane constant multiplier: lane `k` XORs `k · LANE_MIX` into its rotated state. - [const MANIFEST](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/constant.MANIFEST): The manifest of third-party candidates. - [const SEED](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/constant.SEED): The stimulus state after reset. - [const SIMT_LANES](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/constant.SIMT_LANES): SIMT lanes of the K6 engine. - [fn advance](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.advance): The stimulus state `n` steps after `s`. - [fn beat_capture_depths](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.beat_capture_depths): The results each slot of a beat schedule must be able to hold. The harness folds one result per cycle in operation order, so a slot whose result arrives while an earlier slot of its call is still outstanding waits — and when the call after it delivers that slot again before the fold reaches it (results handed back last first), the slot queues two. Found by running the schedule itself: slot `j` of call `n` is captured at `n * period + captures[j]` and folded once every earlier result has been. A schedule that brings more results per call than a call has cycles outruns the fold and is refused. - [fn check_ports](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.check_ports): Refuse a candidate whose binding, clock, reset or protocol ports do not fit its DUT’s ports. - [fn contract_ref](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.contract_ref): A contract reference `port` or `port@j`: the port and the batch slot (operation `j` of the batch a batched candidate takes per call). - [fn emit_fold_wrapper](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.emit_fold_wrapper): The synthesis wrapper `qorsyn_(clk, rst, sig)` of a design measured without a functional contract (a memory controller, whose functional gate is a board memtest): every input of `top` from a register the seeded xorshift64 stimulus refills each cycle, one rotated lane word per 64 bits as the harness draws operands; every output bit folded into a registered 64-bit XOR whose low 16 bits are `sig`; the design kept whole as `u_dut`, so its cells and its register-to-register paths are what synthesis and place-and-route measure. - [fn emit_harness](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.emit_harness): The wrapper `qorbist_(clk, rst, sig)` around `c` for kernel `k` in `mode`. Call `check_ports` first: the wrapper assumes the binding fits. - [fn emit_harness_as](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.emit_harness_as): `emit_harness` as the module `name` — the harness hardened as a block of its own, whose top module the flow names after the block. - [fn emit_pass_wrapper](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.emit_pass_wrapper): The power block `` of a design measured without a functional harness — a memory controller, driven at gate level by the K7 traffic testbench: its clock and reset renamed `clk` and `rst` (active high), every other port passed straight through under its own name, the design kept whole as `u_dut`, so the flow’s cells are told apart from its own. A port named `clk` or `rst` that is not the clock or reset would collide, and is refused. - [fn emit_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.emit_testbench): A testbench that resets the harness for five cycles and runs it until `ops` results are folded. It prints `QOR first cycles ` when the first result is folded, `QOR mid ops cycles ` at half the run, and `QOR ops misr cycles ` at the end; an unknown MISR bit prints `QOR X op ` and stops. Two watchdogs end a run that cannot finish: `max_cycles` in all (`QOR TIMEOUT ops `), and `max_idle` cycles without a folded result (`QOR TIMEOUT idle cycles ops cycle `), which refuses a candidate that has stopped answering long before the whole budget would. - [fn emit_testbench_as](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.emit_testbench_as): `emit_testbench` around the harness module `m` — one emitted by `emit_harness_as`. - [fn emit_trace_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.emit_trace_testbench): `emit_testbench`’s run with every folded result printed as `QOR r ...` (kernel output order, each port in hex at its contract width), for locating the first operation a candidate gets wrong. - [fn emit_trace_testbench_as](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.emit_trace_testbench_as): `emit_trace_testbench` around the harness module `m` — one emitted by `emit_harness_as`. - [fn fold](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.fold): One result folded to 64 bits: chunk `c` (counted across ports in order) rotated left by `c`. - [fn gemm_os_candidate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.gemm_os_candidate): The LOGOS output-stationary GEMM array streaming one tile every `GEMM_DIM` beats: beat `t` carries lane `t` of every row’s activations and weight row `t`, the first beat raises `first`, and row `i` of a tile is read `os_streaming_result_offset` cycles after its first beat. - [fn gemm_os_candidate_acc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.gemm_os_candidate_acc): `gemm_os_candidate` with `acc_bits`-wide accumulators (each sum sign-extended onto its output port), named for the width when it is not the contract’s. - [fn gemm_ws_candidate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.gemm_ws_candidate): The LOGOS weight-stationary GEMM tile with run-time weights on the K3 beat schedule of period `period`: load the tile’s weight rows, stream its activation rows, drain; row `t`’s result emerges `pipelined_latency` cycles after its activation. - [fn gemm_ws_candidate_acc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.gemm_ws_candidate_acc): `gemm_ws_candidate` with `acc_bits`-wide accumulators (each sum sign-extended onto its output port), named for the width when it is not the contract’s. - [fn gemm_ws_period](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.gemm_ws_period): The period of one weight-stationary call: `GEMM_DIM` weight-row loads, `GEMM_DIM` activation rows, then the drain until the last row has passed every column — the weights live in the PEs, so the next call’s loads must wait for it. - [fn golden](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.golden): The golden results of `k` over `stim`. - [fn harness_module](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.harness_module): The harness module’s name for `c`. - [fn jump_rows](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.jump_rows): The 64×64 GF(2) matrix of `n` stimulus steps as rows: bit `i` of `advance``(s, n)` is the parity of `s & rows[i]` (xorshift is linear, so `n` steps are one matrix). - [fn kernel](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.kernel): The kernel with id `id`. - [fn kernels](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.kernels): The kernels of the bench, in id order. - [fn lane_word](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.lane_word): The 64-bit word input lane `k` reads from state `s`. - [fn logos_candidate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.logos_candidate): The LOGOS candidate of kernel `id`: its harness-facing description and its Verilog files (file name, contents). K1, K2 and K6 are compiled from their LOGOS programs; K4 and K5 come from the RTL generators; the remaining kernels’ candidates are built by their own protocols. - [fn logos_candidates](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.logos_candidates): Every LOGOS candidate of kernel `id`, the default first. K1 has the decision fabric in registers, sequenced one cell a cycle, pipelined one carry chain to a stage for a fabric with carry chains (`fabric_pipe::decision_ops`, `DECISION_CHAIN_BUDGET`), pipelined for standard cells (each compare’s sums folded into it, `DECISION_CELLS_BUDGET`, its ports read), and hoisted into one clock (`select_hoist`, its sums folded into the compares that read them, its ports read). K4 has the Keccak core a round a clock and a half round a clock (`keccak_core_half`). K2 has the residual in registers, sequenced one cell a cycle, and pipelined (`fabric_pipe`, the RTL the `fabric_horner_seq` block hardens). K5 has the butterfly in registers and its pipeline registered once a multiply and after every step. K6 has one per lane multiply strategy: the sequential shift-add (the signoff-clean default), the two-stage decomposed FMA, the single-cycle combinational multiply and the streamed shared multiply, and the engine’s step on ports (`simt_ports`). - [fn manifest_candidate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.manifest_candidate): Read manifest entry `name` under `root` and its files, refusing any file whose bytes no longer hash to the recorded SHA3-256. - [fn misr_step](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.misr_step): The MISR update: shift left with the parity of the old state fed back, XOR the folded result. - [fn next_state](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.next_state): One step of the stimulus generator: xorshift64 with shifts 13, 7, 17. - [fn parse_run](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.parse_run): The verdict a testbench printed. - [fn read_manifest](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.read_manifest): The manifest under `root`. - [fn sha3_hex](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.sha3_hex): The lowercase hex SHA3-256 of `bytes`. - [fn signature](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.signature): The signature of a result sequence. - [fn stimulus](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.stimulus): The operand values of the first `ops` operations of `k` in `mode`. - [fn trace_lines](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/fn.trace_lines): The golden results of `results` as `emit_trace_testbench` prints them: one line per operation, ` ...`, each port in hex at its contract width. - [type Words](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/qor_harness/type.Words): One operation’s values: per port, per 64-bit chunk. ## logicaffeine_compile::codegen_sva::quartus Quartus Prime reports as data: a compile’s flow, the resources it used, the slack of every clock, the retimer’s limits, the router’s peak wire demand, and the resources and logic depth of every entity, read from the text reports Quartus writes into a project’s `output_files`. - [struct Build](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.Build): One compile, as its reports state it. - [struct ClockNet](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.ClockNet): A net the fitter uses as a clock: its fan-out, and whether it rides a global network. - [struct EntityTotal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.EntityTotal): An entity’s instances, totalled over the outermost ones (an instance inside another instance of the same entity is already in its total). - [struct Estimate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.Estimate): Synthesis’s estimate of a design’s resources. - [struct Evidence](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.Evidence): What a compile is judged by beyond its flow report, which a module that dies at startup leaves as the last one to finish wrote it. - [struct Flow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.Flow): A compile’s flow report. - [struct HoldDelay](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.HoldDelay): Routing delay the fitter added on one clock transfer to meet hold. - [struct Input](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.Input): A file a compile read, by its SHA-256. - [struct Ledger](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.Ledger): Every compile recorded, in recording order: the history every later build is priced from. Rows are written by `Ledger::record` from reports, never by hand. - [struct Node](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.Node): One row of the entity table: totals of the node and everything under it. - [struct PartitionEstimate](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.PartitionEstimate): A partition’s synthesis estimate: in a partial-reconfiguration build the static region and each persona apart. - [struct Phase](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.Phase): One module of the flow: its elapsed wall time and its peak virtual memory (none for the total). - [struct Ratio](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.Ratio) - [struct RegionUsage](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.RegionUsage): A Logic Lock region as the fitter left it: what was placed in it needs (ALMs after dense packing, logic registers, M20Ks, DSP blocks after dense merging) over what the region holds, and the rectangles it is, each its corners. - [struct Row](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.Row): One recorded compile: its name, when it was recorded, the inputs it was handed, its reports read, whether it passed, and the compile it resumed, when its job went on from another’s: the modules that compile ran and this job did not are that compile’s, judged in its row. - [struct Slack](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.Slack): One timing analysis of one clock. - [struct Usage](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.Usage): A fit’s resources as its summary states them. - [struct Verdict](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.Verdict): Whether a compile ran every module it runs to the end, every reason it did not, and the exit status and modules it was judged against (none when its flow report was all there was). Whether its timing closed is the slack’s to say, not the verdict’s. - [struct WireDemand](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/struct.WireDemand): The router’s estimated peak demand for one kind of wire. - [enum QuartusError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/enum.QuartusError): Why a compile’s reports could not be read. - [const ENTITY_ROWS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/constant.ENTITY_ROWS): How many entity totals a `Build` keeps. - [const TOP_ROWS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/constant.TOP_ROWS): How many nodes of each partition’s top two levels a `Build` keeps. - [fn by_entity](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.by_entity): The entity table rolled up by entity, largest total ALUTs first. - [fn clock_nets](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.clock_nets): The nets the `control` report’s table uses as clocks (usage `Clock`, not a clock’s enable or clear), each marked global when the `globals` report’s fast-signal summary names it or the buffer the fitter inserted to put it on one (`clk~FITTER_INSERTED_0`); those off every global first, then by fan-out. - [fn judge](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.judge): The verdict on `build` given `evidence`: it ran to the end when its flow report says Successful, every module the job runs is in that report, the flow exited 0, its log holds no failure line, and its report was written after the job started. - [fn log_failure](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.log_failure): The first line of a Quartus log that says the flow failed: a fatal error, a module or shell that was unsuccessful, or the OFS build script’s own failure line. - [fn parse_flow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.parse_flow): A compile’s flow report. - [fn parse_hierarchy](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.parse_hierarchy): Every row of the entity table (“Resource Utilization by Entity”), depth from the node’s indentation. - [fn parse_hold](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.parse_hold): The delay the router added to meet hold, a row a clock transfer (`Estimated Delay Added for Hold Timing Summary`). - [fn parse_processors](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.parse_processors): The processors parallel compilation was allowed: the fitter’s message (“will use up to 8 processors”, “will use 24 of the 24 processors detected”), or its Parallel Compilation table. - [fn parse_region_usage](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.parse_region_usage): Every region of the fit report’s `Logic Lock Region Usage Summary`, a column each. A region’s rectangles are separated by the table’s own `;`, so with one region the placement row’s every rectangle is its; with several, a region’s cell is read alone. - [fn parse_retime](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.parse_retime): The retimer’s limit table: each clock transfer and the reason it stopped. - [fn parse_sta_summary](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.parse_sta_summary): A timing summary: `Type : ''`, `Slack`, `TNS`, `Corner` a block. - [fn parse_summary](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.parse_summary): A `.fit.summary` (or any `Key : value` summary). - [fn parse_synthesis](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.parse_synthesis): Each partition’s synthesis resource usage summary, in report order. - [fn parse_wire_demand](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.parse_wire_demand): The router’s headline peak demands (`Info (20215)`), one a kind of wire, each once however often it is printed. - [fn read](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.read): One compile of `revision`, read from its project’s `output_files` directory. - [fn utc](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.utc): `seconds` since the Unix epoch as an RFC 3339 UTC timestamp. - [fn worst_setup](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/quartus/fn.worst_setup): The setup analysis with the least slack. ## logicaffeine_compile::codegen_sva::reconfig_fabric_rtl reconfig_fabric_rtl — Stage 4 of the self-synthesizing bytecode XPU: the placer IN SILICON as a RECONFIGURABLE fabric. Stage 1 HARDWIRED a grid per block; Stage 3 proved `route_loop_body` correct for every bounded body. This stage makes the fabric CONFIG-DRIVEN: ONE fixed R×C tile array whose every tile’s operation and channel routing are RUNTIME inputs, so loading the certified placement of ANY block runs it on the same physical silicon — the reconfigurable array the on-chip placer configures. - [struct ReconfigConfig](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/reconfig_fabric_rtl/struct.ReconfigConfig): A placed grid transcribed into the reconfigurable fabric’s config: one 32-bit control word per tile, two 64-bit constant slots per tile (operand `a`/`b` `Const` values), and the output tap (`out_sel` = flat tile index, `out_chan` = 0 for the vertical channel / 1 for the horizontal). - [fn emit_reconfig_fabric_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/reconfig_fabric_rtl/fn.emit_reconfig_fabric_verilog): Emit the universal reconfigurable fabric: a fixed `rows`×`cols` config-driven CGRA. Each tile decodes its control word (loaded via `$readmemh`) into an operation + channel routing and computes the same feed-forward dataflow the hardwired grid does; loading `route_loop_body`’s certified placement runs any bounded Arith block on this ONE array. Combinational (feed-forward south/east) — the answer settles in zero clocks; the config is read once at elaboration. - [fn emit_reconfig_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/reconfig_fabric_rtl/fn.emit_reconfig_testbench): A self-checking testbench for the reconfigurable fabric: drive each input vector and compare `result` to the VM oracle in `reconfig_{name}_{pin,eout}.hex` (the fabric loads its config from `reconfig_{name}_{ctrl,sac,sbc,out}.hex`). One block’s config + vectors are written per run; the fabric RTL is fixed, so it compiles once and re-runs per block. - [fn serialize_grid_config](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/reconfig_fabric_rtl/fn.serialize_grid_config): Transcribe a placed `Grid` (Arith tiles, single `Val` output) into the reconfigurable fabric’s config, laid out row-major over `rows*cols` tiles (the grid must already be padded to `rows`×`cols`). ## logicaffeine_compile::codegen_sva::reverse_module R5 — the SVA REVERSE-MODULE OBLIGATION for Hardware Studio. - [struct JournaledInjectivity](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/reverse_module/struct.JournaledInjectivity): A discharged JOURNALED-op injectivity obligation — the hardware twin of the software minimal-bit journaling (corner 1). A `Journaled` op `F` is many-to-one (it erases), but AUGMENTED with its Bennett ancilla `J` (the journal entry — the exact bits it destroyed), the map `x ↦ (F(x), J(x))` is INJECTIVE: the reverse module reconstructs `x` from the post-state AND the ancilla. This closes the R4 gap — the Z3/exhaustive proofs covered the `Bijection` core, and this covers every `Journaled` op the same way. - [struct ReverseModuleObligation](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/reverse_module/struct.ReverseModuleObligation): A discharged reverse-module obligation: the constructive reverse gate plus the SVA property that pins the reverse-module identity, produced only when every attempted method AGREED that `U` is reversible. - [fn discharge_journaled_injective](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/reverse_module/fn.discharge_journaled_injective): Prove a `Journaled` op is INJECTIVE once augmented with its Bennett ancilla. `augmented[x]` is the packed `(F(x), J(x))` output for input `x` (all `2^in_bits` inputs present). Injective iff every packed output is distinct — an EXHAUSTIVE bit-blast, the same rigor as `certify_gate`, so the core needs no SMT solver. Fails loud on a collision: two inputs share an augmented output, so the ancilla did NOT capture the erased bits — a genuine (un-reversible) Landauer erasure. - [fn discharge_reverse_module](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/reverse_module/fn.discharge_reverse_module): Discharge the reverse-module obligation for the `n`-bit combinational unit `truth_table`. Proves reversibility by exhaustive bit-blast AND — when `linear_rows` (the GF(2) transfer matrix) is given — the algebraic GF(2) certificate, and REQUIRES the two verdicts to agree. On success returns the reverse module + SVA property; on failure names the erasure or the method disagreement. ## logicaffeine_compile::codegen_sva::rtl RTL / transition-system bounded model checking — including multi-bit (bitvector) registers. - [struct Register](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl/struct.Register): A hardware register: a width, an optional initial value, and its next-state function. - [struct RtlParseError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl/struct.RtlParseError): A Verilog parse error (kept distinct so the BMC layer can surface it verbatim). - [struct TransitionSystem](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl/struct.TransitionSystem): A synchronous transition system over Boolean and bitvector registers. - [enum NextState](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl/enum.NextState): A next-state function: a direct expression, or a guarded `if/else` (from RTL reset/mux logic). Guards reference the current state and free inputs. - [fn emit_alu_datapath_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl/fn.emit_alu_datapath_verilog): Emit the GENERAL INTEGER ALU datapath — the combinational functional unit that executes the arithmetic / bitwise / signed-comparison ops straight off a WIRE OPCODE BYTE. The `case` labels are the stable `binisa` opcodes (one source of truth with the wire format), so the ALU decodes the same bytes the network carries. Each operation is proven correct by our own certified SAT (the identity battery `the_general_alu_datapath_is_proven_correct_by_our_sat`); comparisons are SIGNED (matching the VM’s i64 semantics) and yield 0/1. This is the ratchet frontier grown from the reversible core. - [fn emit_isa_core_decoder_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl/fn.emit_isa_core_decoder_verilog): Emit the ISA opcode decoder for the reversible core — the silicon FRONT-END that turns a wire opcode BYTE (the exact byte `crate::vm::binisa::encode_program` puts on the wire) into the reversible ALU’s 3-bit control select plus a `core` valid flag. The `case` labels are DERIVED from `crate::vm::binisa::opcode`, so the decoder and the wire format share ONE source of truth: the byte the network carries is the byte the chip decodes, with no translation layer. Compose with `emit_reversible_alu_core_verilog` — wire `isa_core_decoder.sel → rev_alu_core.op`. - [fn emit_reversible_alu_core_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl/fn.emit_reversible_alu_core_verilog): Emit the LOGOS reversible ALU CORE as synthesizable Verilog — the abelian charge-recovery datapath of the VM: two `width`-bit registers `a`,`b` and a 3-bit opcode selecting `RevAdd`/`RevSub`/`RevXor`/ `RevNeg`/`RevSwap`. For every fixed opcode the transition on `(a,b)` is a BIJECTION, so the whole ALU runs backward with zero erased bits. The 32-bit form place-and-routes on a Lattice ECP5 (ULX3S) via `scripts/synth-soft-core.sh` (`benchmarks/silicon/rev_alu_core.v`): 336 LUTs + 64 FFs at ~136 MHz. - [fn emit_reversible_alu_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl/fn.emit_reversible_alu_verilog): Emit a synthesizable Verilog SOFT-CORE for the reversible ALU datapath (corner 5, phase 3) — the register-VM’s `RevAdd` charge-recovery core as RTL: a `width`-bit register advanced by `step` each clock. `q := (q + step) mod 2^width` is a PERMUTATION of the state space (a cyclic reversible datapath whose reverse module is the `−step` decrement), and the emitted text is real synthesizable Verilog — `parse_transition_system` accepts it and BMC / k-induction discharge its obligations. This is the round-tripping HDL twin of the software `RevAdd`; the full VM-datapath soft-core + a VM↔RTL SMT equivalence are the larger MAKE_A_CHIP build this slice opens. - [fn emit_reversible_datapath_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl/fn.emit_reversible_datapath_verilog): Emit the reversible `RevAdd` DATAPATH as synthesizable Verilog — a `width`-bit accumulator advanced by a data INPUT each clock (`q := (q + delta) mod 2^width`), the genuine charge-recovery ALU slice (its reverse is `q := q − delta`). For every fixed `delta` the clocked transition is a bijection in `q`. Unlike the constant-step `emit_reversible_alu_verilog`, this is the real datapath the VM’s `RevAdd` maps to; `benchmarks/silicon/` synthesizes + place-and-routes the 32-bit form on an ECP5 FPGA. - [fn emit_shared_divider_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl/fn.emit_shared_divider_testbench): Emit the divider’s self-checking testbench: drive the sequential `shared_divider`, wait for `done`, and check quotient+remainder against the combinational `$signed` div/mod oracle over every sign/edge case plus a 4000-pair pseudo-random sweep. PASS iff all match. - [fn emit_shared_divider_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl/fn.emit_shared_divider_verilog): Emit the SHARED ITERATIVE DIVIDER — one sequential restoring divider that computes signed quotient AND remainder, replacing the ~24,600-cell COMBINATIONAL `$signed(a)/$signed(b)` + `$signed(a)%$signed(b)` the ALU instantiates per-op (Div/Mod/FloorDiv). It costs 833 LUT / 204 FF placed-and-routed on the ECP5-85K at ~100 MHz — a ~26× LUT drop vs the ~22,000-LUT combinational divide, the lever that fits the full 113-op CPU under 83,640. Truncated (round-toward-zero) semantics matching the VM: quotient sign = sign(a)^sign(b), remainder sign = sign(a); b==0 → q=r=0. One 1-bit/cycle restoring loop over |a|/|b| (W cycles) then a sign fixup; the soft-core pulses `start` and stalls until `done`. The module is Verilog-parameterized (default W=32; instantiate #(.W(64)) for the BigInt lane), so this emitter is the single source for the on-disk `shared_divider.v`, proven == the combinational oracle by iverilog (`emit_shared_divider_testbench`). - [fn emit_yosys_tapeout_flow](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl/fn.emit_yosys_tapeout_flow): Emit a yosys synthesis FLOW (`.ys`) that takes the reversible soft-core RTL to a gate-level netlist (corner 5, phase 5). This is the tape-out-ready boundary produced IN-REPO: the synthesizable, formally-verified reversible RTL (`emit_reversible_alu_verilog`) PLUS this flow. Executing it needs the external `yosys` synthesizer (not installed here); mapping the generic gate set to an adiabatic / charge-recovery PDK and running a foundry are the physical tape-out steps beyond software. The flow reads the module, elaborates, techmaps, maps to a generic gate library, and writes the gate-level netlist + a resource report. - [fn lec_next_state_matches_vm](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl/fn.lec_next_state_matches_vm): LOGICAL EQUIVALENCE CHECK (corner 5, phase 3) — discharged by OUR OWN certified SAT, not yosys’s SAT or Z3. Parse the soft-core RTL, extract register `reg`’s next-state, and prove it equals `spec` (the VM op’s datapath function) for EVERY input by refuting the miter `rtl_next ≠ spec` with `logicaffeine_proof::sat::prove_unsat` — a bit-blasted CDCL refutation, the LEC “back-check”. This is the equivalence a tool like yosys `equiv` runs on its internal SAT, done here on ours. Returns `Some(true)` iff the RTL datapath is equivalent to the VM spec, `Some(false)` if a differing input exists, `None` if the RTL / next-state / miter can’t be lowered to the bit-blaster. - [fn parse_transition_system](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl/fn.parse_transition_system): Parse a synthesizable Verilog module into a `TransitionSystem`. Errors (never silently mis-parses) on anything outside the supported subset. ## logicaffeine_compile::codegen_sva::rtl_extract Verilog Declaration Parser - [struct RtlModule](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl_extract/struct.RtlModule): Extracted module structure. - [struct RtlParam](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl_extract/struct.RtlParam): A parameter declaration. - [struct RtlParseError](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl_extract/struct.RtlParseError): Parse error. - [struct RtlPort](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl_extract/struct.RtlPort): A port in the module declaration. - [struct RtlSignal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl_extract/struct.RtlSignal): An internal signal declaration. - [enum PortDirection](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl_extract/enum.PortDirection): Port direction. - [enum SignalType](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl_extract/enum.SignalType): Signal type. - [fn parse_verilog_module](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl_extract/fn.parse_verilog_module): Parse a Verilog module declaration and extract its structure. ## logicaffeine_compile::codegen_sva::rtl_kg RTL KG + Spec-RTL Linking - [struct LinkResult](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl_kg/struct.LinkResult): Link result reporting unmatched signals. - [fn link_kg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl_kg/fn.link_kg): Link a spec KG to an RTL KG by signal name matching. Strategy: exact match → case-insensitive match. - [fn rtl_to_kg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/rtl_kg/fn.rtl_to_kg): Convert an RtlModule to a HwKnowledgeGraph. ## logicaffeine_compile::codegen_sva::scalar_asm scalar_asm — assemble a compiled LOGOS program (the register bytecode `CompiledProgram`) into the instruction words that `soft_core_scalar.v` executes, so a REAL `.lg` program can be streamed to the Nexys A7 FPGA over UART and run on silicon (see scripts/run-on-nexys-scalar.sh). - [fn allocate_scalar_registers](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/scalar_asm/fn.allocate_scalar_registers): Map a function-free scalar program’s registers onto the core’s sixteen by liveness. The VM numbers registers freely (a fresh one per `Let`, named values above the temporaries that computed them); the chip needs only as many as are ever live at once. Two registers may share a physical one unless one is live where the other is written (a `Move`’s source does not count against its destination), and the interference graph is coloured Chaitin–Briggs style — simplify below sixteen neighbours, else optimistically, then colour in reverse — lowest register first, so the result is deterministic. - [fn compile_to_scalar_words](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/scalar_asm/fn.compile_to_scalar_words): Compile a `.lg` source string all the way to soft_core_scalar imem words, through the SAME front-end and oracle-driven compiler the VM uses (so the chip runs byte-identically to `vm_outcome`). `Err` if it doesn’t parse/compile, or uses anything outside the function-free scalar subset. - [fn encode_soft_core_scalar](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/scalar_asm/fn.encode_soft_core_scalar): Assemble a whole compiled program into soft_core_scalar imem words. Function-free only (a program with user functions returns `Err`; their calling-convention translation is a separate pass). At most 256 words (the imem depth). Registers are first mapped onto the core’s sixteen by liveness (`allocate_scalar_registers`). - [fn to_hex](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/scalar_asm/fn.to_hex): Render imem words as a `.hex` file body (one 8-hex-digit word per line) for scripts/nexys-host.py. ## logicaffeine_compile::codegen_sva::scratchpad_rtl scratchpad_rtl — the on-chip scratchpad subsystem in silicon. - [enum Decode](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/scratchpad_rtl/enum.Decode): The decode verdict. - [const CW_BITS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/scratchpad_rtl/constant.CW_BITS): Total codeword width (72) and data width (64) of the scratchpad ECC. - [const DATA_BITS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/scratchpad_rtl/constant.DATA_BITS) - [fn decode](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/scratchpad_rtl/fn.decode): SECDED decode: a (possibly corrupted) 72-bit codeword → (recovered data, verdict). - [fn emit_double_buffer_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/scratchpad_rtl/fn.emit_double_buffer_verilog): Emit the ping-pong double-buffer controller: `swap` toggles which bank compute reads (`read_bank`) vs the DMA fills (`fill_bank` = ~read_bank). The safety invariant `read_bank != fill_bank` holds by construction (they are complements). - [fn emit_secded_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/scratchpad_rtl/fn.emit_secded_testbench): Emit a self-checking testbench: encode `din`, inject a fault pattern from `secded_vec.hex` (each line: `din flip_mask expect_dout expect_corrected expect_double`), decode, and compare. Prints PASS/FAIL. - [fn emit_secded_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/scratchpad_rtl/fn.emit_secded_verilog): Emit the SECDED(72,64) encoder + decoder/corrector as synthesizable Verilog, generated from the SAME incidence as `encode`/`decode`, so they cannot diverge. Interface: `enc` takes 64-bit `din` → 72-bit `cw`; `dec` takes a 72-bit `cw_in` → 64-bit `dout` + `corrected` + `double_err`. - [fn encode](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/scratchpad_rtl/fn.encode): SECDED encode: 64 data bits → a 72-bit codeword (`bit 0` = overall parity, bits 1..=71 = Hamming(71,64)). ## logicaffeine_compile::codegen_sva::select_hoist select_hoist — a decision fabric’s selects hoisted out of its arithmetic: every select an add, a shift or a compare reads is cofactored away, so the fabric becomes arithmetic over its inputs, compares of that arithmetic, and one tree of selects over the compares’ outcomes. - [const HOIST_NODE_LIMIT](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/select_hoist/constant.HOIST_NODE_LIMIT): The nodes a hoisted fabric may grow to before the pass refuses it: an expansion that would outgrow this many is one whose predicates do not collapse, and the fabric is better left as it is. - [fn hoist_selects](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/select_hoist/fn.hoist_selects): `df` with every select its arithmetic or compares read cofactored away and its tree of selects ordered latest predicate first, at datapath width `width` (64 on silicon; narrower so our SAT can check the pass exhaustively). Refused when `df` holds a cell with no combinational form (a functional unit, a memory or heap tile), or when the expansion outgrows `HOIST_NODE_LIMIT`. - [fn reads_a_select](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/select_hoist/fn.reads_a_select): Whether arithmetic or a compare of `df` reads a select’s value: what `hoist_selects` leaves none of. ## logicaffeine_compile::codegen_sva::sequencer_rtl sequencer_rtl — Stage 1 of the self-synthesizing bytecode XPU: the AUTONOMOUS block-walk sequencer as synthesizable RTL. The CONTROL PLANE that `run_program_cfg_on_grid` modelled in software now exists in silicon: a register file that survives block reconfiguration, per-block placed grids, a block program- counter, a terminator FSM (Jump/Branch/Return), and a cycle counter — a hardwired micro-sequencer that walks the whole function itself, one block per clock, with no host help. - [fn emit_sequencer_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/sequencer_rtl/fn.emit_sequencer_testbench): A self-checking testbench for the sequencer: for each vector, load the params, pulse reset, run the FSM to `done`, and compare BOTH `result` and `cycles` to the VM oracle in `seq_{name}_{out,cyc}.hex` (inputs in `seq_{name}_in.hex`). The step-count check pins the trajectory, not just the answer. - [fn emit_sequencer_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/sequencer_rtl/fn.emit_sequencer_verilog): Emit the autonomous block-walk sequencer for a whole-function CFG fabric: the per-block placed-grid modules followed by a `seq_{name}` top that carries the register file + block-PC + terminator FSM + cycle counter. One block step per clock; `done` pulses high with the return value on `result` and the block-step count on `cycles`. - [fn eval_sequencer](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/sequencer_rtl/fn.eval_sequencer): Evaluate a whole-function CFG fabric on the sequencer’s model and return `(result, block_steps)`. This IS `run_program_cfg_on_grid` — the same place-per-block (`route_loop_body`) + `eval_grid_all` walk over a register file — with a step counter added, so the returned value is identical to the grid walk (≡ the CFG model ≡ the VM) and `block_steps` is the exact number of block executions the RTL must take (the trajectory, not merely the answer). The reference the iverilog differential checks against. ## logicaffeine_compile::codegen_sva::shuttle_wrapper Packing EVERY signed-off macro into ONE Caravel shuttle submission. - [struct MacroPort](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/shuttle_wrapper/struct.MacroPort): One port of a macro, as its RTL declares it. - [struct Placement](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/shuttle_wrapper/struct.Placement): Where a macro sits in the user area, in LEF orientation terms. - [struct ShuttleMacro](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/shuttle_wrapper/struct.ShuttleMacro): A hardened, signoff-clean macro and the footprint its LEF reports. - [enum ShuttleUnplaceable](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/shuttle_wrapper/enum.ShuttleUnplaceable): Why a set of macros cannot share one user area. - [const CLEAN_MACROS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/shuttle_wrapper/constant.CLEAN_MACROS): Every signoff-clean macro, with the footprint its own hardened LEF reports. - [const MACRO_ADDR_STRIDE](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/shuttle_wrapper/constant.MACRO_ADDR_STRIDE): Address window per macro. 0x100 gives 64 registers — far more than the widest macro here needs (18 ports), and keeps each base a readable multiple in a memory map a human debugs. - [const MACRO_KEEPOUT_UM](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/shuttle_wrapper/constant.MACRO_KEEPOUT_UM): Micrometres of keep-out around every macro. - [fn emit_macro_cfg](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/shuttle_wrapper/fn.emit_macro_cfg): OpenLane `macro.cfg` lines: ` `. - [fn emit_pdn_hooks](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/shuttle_wrapper/fn.emit_pdn_hooks): `FP_PDN_MACRO_HOOKS` — every macro must be hooked to the user-area supply, or the power connections check fails the submission outright. - [fn plan_shuttle](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/shuttle_wrapper/fn.plan_shuttle): Shelf-pack the macros into the user area, tallest first. ## logicaffeine_compile::codegen_sva::signal_design Conflict-free traffic-signal PHASE DESIGNER (certified SAT synthesis). - [struct Intersection](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/signal_design/struct.Intersection): An intersection: a set of movements and the pairs that may not be green together. - [struct PhasePlan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/signal_design/struct.PhasePlan): A synthesized signal plan: each movement assigned to a green phase. - [fn design_from_spec](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/signal_design/fn.design_from_spec): Parse an English spec into an `Intersection`, then design its minimal plan. - [fn design_phase_plan](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/signal_design/fn.design_phase_plan): Design the minimal-phase conflict-free plan for an intersection, or `None` if it has no movements. - [fn is_valid_coloring](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/signal_design/fn.is_valid_coloring): Re-check that a plan is a genuine conflict-free colouring (used by tests and as a guard). - [fn parse_intersection](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/signal_design/fn.parse_intersection): Parse a focused English spec into an `Intersection`. ## logicaffeine_compile::codegen_sva::signoff_blocks The clock period every hardened block is signed off at — held here, derived from its measured SLOW corner, and the only period `emit_flow_config` accepts for a registered block. - [struct SignoffBlock](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/signoff_blocks/struct.SignoffBlock): One hardened block’s signoff clock. - [const SLOW_CORNER_MARGIN](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/signoff_blocks/constant.SLOW_CORNER_MARGIN): Headroom kept above the measured slow-corner requirement. Lengthening the period relaxes timing-driven synthesis and resizing, so the rebuilt critical path can come out a little slower than the one measured; 5% absorbs that without a second round. - [static SIGNOFF_BLOCKS](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/signoff_blocks/static.SIGNOFF_BLOCKS): Every hardened block, with the run its measurement came from: the period that run was built at and its worst setup slack across every corner, so the derivation is visible, not just its result. A block iterates: when a run at the derived period still misses, its entry moves to THAT run. - [fn honest_period_ns](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/signoff_blocks/fn.honest_period_ns): The period a block must be built at, given the period it was measured at and the worst setup slack across every corner of that run. A block that met every corner keeps its period; one that missed gets the miss plus `SLOW_CORNER_MARGIN`, rounded UP to the 0.5 ns grid. - [fn registered_period_ns](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/signoff_blocks/fn.registered_period_ns): The registered signoff period for `name`, if the block is registered. - [fn registered_synth_strategy](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/signoff_blocks/fn.registered_synth_strategy): The synthesis strategy `name`’s period was measured under (`Some(None)` for OpenLane’s default), if the block is registered. - [fn resolve_synth_strategy](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/signoff_blocks/fn.resolve_synth_strategy): The strategy `name` is synthesized under, given the one asked for (`None`: none asked; `Some(None)`: OpenLane’s default). A registered block takes its registered strategy and refuses any other; an unregistered block takes what was asked. ## logicaffeine_compile::codegen_sva::simd simd — configurable-precision packed SIMD lanes for the fabric datapath (`FabricTarget::simd`). - [enum LaneTy](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/enum.LaneTy): A packed lane type: `lanes` values of `width` bits, `lanes * width == 64`. - [enum VecOp](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/enum.VecOp): A packed integer SIMD operation carried by a `LoopCell::VectorArith` / `CellKind::Simd` tile. `Add` is the carry-isolated SWAR add (proven ≡ lane-wise by `simd_tile_lock`); the bitwise ops never cross a lane boundary, so they are the native 64-bit op. - [const FP16_ADD_V](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/constant.FP16_ADD_V): The synthesizable combinational IEEE-754 `f16` (binary16) adder — the f32 adder narrowed to 5-bit exponent, 10-bit mantissa, bias 15 (window 128-bit, LSB0=64, leading-ref=74, normalize-target=13). Proven bit-exact to the `f16_add` reference under iverilog; instantiated once per lane by the packed F16×4 tile. - [const FP16_MUL_V](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/constant.FP16_MUL_V): The synthesizable combinational IEEE-754 `f16` multiplier — the f32 multiplier narrowed to binary16 (11-bit significand product = 22 bits, leading at 20/21). Proven bit-exact to `f16_mul` under iverilog. - [const FP32_ADD_V](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/constant.FP32_ADD_V): The synthesizable combinational IEEE-754 `f32` adder — a faithful port of the PROVEN f64 `fp_addsub` (`benchmarks/silicon/fpu.v`): align both significands in a wide 128-bit window (64 bits of alignment room, so every bit survives to sticky), add/sub, leading-zero-count, normalize the leading 1 to bit 26 (24-bit significand at `[26:3]`, guard/round/sticky at `[2:0]`), round-to-nearest-ties-even, and pack (overflow→Inf, underflow→subnormal via `pack_sub32`). `sub=1` computes `a-b`. Proven bit-exact to Rust `f32` under iverilog by `simd_float_rtl_lock`. This module is instantiated once per lane by the packed F32×2 tile. - [const FP32_MUL_V](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/constant.FP32_MUL_V): The synthesizable combinational IEEE-754 `f32` multiplier — a faithful port of the proven f64 `fp_mul`: pre-normalize each significand (leading 1 to bit 23), multiply (24×24=48-bit, leading at 46/47), normalize the leading 1 to bit 47, round-to-nearest-ties-even, and pack (overflow→Inf, underflow→subnormal, rounded once from the EXACT product to avoid double-rounding). Proven bit-exact to Rust `f32` under iverilog. - [fn emit_fp32_scalar_add_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.emit_fp32_scalar_add_testbench): A self-checking combinational testbench for the scalar `fp32_add`: drive `n` `(a,b)` 32-bit vectors from `fp32_add_a.hex`/`_b.hex`, compare the settled `y` against Rust’s `f32` add oracle in `fp32_add_o.hex`. - [fn emit_fp32_scalar_mul_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.emit_fp32_scalar_mul_testbench): A self-checking combinational testbench for the scalar `fp32_mul`: drive `n` `(a,b)` vectors, compare `y` against Rust’s `f32` multiply oracle in `fp32_mul_o.hex`. - [fn emit_simd_add_testbench](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.emit_simd_add_testbench): A self-checking combinational testbench for `simd_{name}`: drive `n` `(a,b)` vectors from `simd_{name}_a.hex`/`_b.hex`, compare the settled `r` against the lane-wise oracle in `_o.hex`, print PASS. - [fn emit_simd_add_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.emit_simd_add_verilog): Emit the packed SWAR add as a COMBINATIONAL Verilog module — the SIMD tile the RTL flow tapes out: `r = ((a & M) + (b & M)) ^ ((a ^ b) & ~M)`, one datapath op, carry blocked at every lane boundary. Proven ≡ the lane-wise spec under iverilog by `simd_rtl_lock` (and ≡ N scalar adds by SAT in `simd_tile_lock`). - [fn emit_simd_fadd_f16x4_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.emit_simd_fadd_f16x4_verilog): Emit the packed F16×4 add tile: four `fp16_add` lanes over the 64-bit operands. Module `simd_fadd_f16x4` (ports `a,b,r`). Compile alongside `FP16_ADD_V`; proven ≡ `eval_lanewise_fadd_f16x4` under iverilog. - [fn emit_simd_fadd_f32x2_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.emit_simd_fadd_f32x2_verilog): Emit the packed F32×2 add tile: two `fp32_add` lanes (low = bits `[31:0]`, high = `[63:32]`) driven in parallel from the 64-bit operands. Module name `simd_fadd_f32x2` (ports `a,b,r`), so the standard SIMD testbench drives it. Compile alongside `FP32_ADD_V`; proven ≡ `eval_lanewise_fadd_f32x2` under iverilog. - [fn emit_simd_fmul_f16x4_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.emit_simd_fmul_f16x4_verilog): Emit the packed F16×4 multiply tile: four `fp16_mul` lanes. Module `simd_fmul_f16x4`. Compile alongside `FP16_MUL_V`; proven ≡ `eval_lanewise_fmul_f16x4` under iverilog. - [fn emit_simd_fmul_f32x2_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.emit_simd_fmul_f32x2_verilog): Emit the packed F32×2 multiply tile: two `fp32_mul` lanes in parallel. Module name `simd_fmul_f32x2`. Compile alongside `FP32_MUL_V`; proven ≡ `eval_lanewise_fmul_f32x2` under iverilog. - [fn eval_lanewise_add](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.eval_lanewise_add): Evaluate the lane-wise add SPEC concretely (each lane an independent `width`-bit wrapping add). - [fn eval_lanewise_fadd_f16x4](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.eval_lanewise_fadd_f16x4): Packed-float add for F16×4 — the SPEC: four independent scalar binary16 adds. Lanes are isolated (a NaN/Inf/subnormal in one cannot perturb another); the parallel `fp16` FPU lanes realize it in silicon. - [fn eval_lanewise_fadd_f32x2](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.eval_lanewise_fadd_f32x2): Packed-float add for F32×2 (two IEEE-754 `f32` lanes in one 64-bit word, lane 0 low) — the SPEC: each lane an independent scalar `f32` add. A NaN/Inf/subnormal in one lane cannot perturb the other; SAT cannot bitblast IEEE arithmetic, so `simd_tile_lock` certifies this by per-lane bit-exactness + a cross-lane non-contamination battery (the way the scalar float lane is already proven). This is the model the parallel `fp32` FPU lanes realize in silicon. - [fn eval_lanewise_fmul_f16x4](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.eval_lanewise_fmul_f16x4): Packed-float multiply for F16×4 (see `eval_lanewise_fadd_f16x4`). - [fn eval_lanewise_fmul_f32x2](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.eval_lanewise_fmul_f32x2): Packed-float multiply for F32×2 (see `eval_lanewise_fadd_f32x2`). - [fn f16_add](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.f16_add): One correctly-rounded IEEE-754 binary16 add: widen (exact), add in f32 (exact — the sum of two f16s fits in f32’s 24-bit significand), round back RNE. Equals the native binary16 add bit-for-bit (both correctly rounded). - [fn f16_mul](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.f16_mul): One correctly-rounded IEEE-754 binary16 multiply (see `f16_add`; the product of two f16s is exact in f32). - [fn f16_to_f32](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.f16_to_f32): Widen an IEEE-754 binary16 bit pattern to `f32` — EXACT (every f16 value is representable in f32). - [fn f32_to_f16](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.f32_to_f16): Round an `f32` to an IEEE-754 binary16 bit pattern, round-to-nearest-ties-even (overflow→Inf, underflow→subnormal/0, NaN→canonical qNaN). The one rounding step in the f16 reference; anchored by known-value assertions in `simd_tile_lock`. - [fn lanewise_add_body](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.lanewise_add_body): The LANE-WISE reference for packed add — the SPEC: each lane independently computes `(a_j + b_j) mod 2^w`, expressed as an `AluOp` residual (shift the lane down, add, mask to `width`, shift back, OR the lanes). This is “N independent scalar adds” made concrete. - [fn naive_add_body](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.naive_add_body): A deliberately NAIVE (non-isolated) packed add — a single 64-bit add. Carry bleeds across lane boundaries, so it must NOT equal the lane-wise spec (the non-vacuity witness for the isolation proof). - [fn pack_f16x4](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.pack_f16x4): Pack four f16 lanes into a 64-bit word (lane 0 low). - [fn pack_f32x2](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.pack_f32x2): Pack two `f32` lanes into one 64-bit word (lane 0 low). - [fn swar_add_body](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simd/fn.swar_add_body): The PACKED SWAR add — one datapath op that blocks carry at every lane boundary: `((a & M) + (b & M)) ^ ((a ^ b) & ~M)`, where `M` clears each lane’s top bit. This is what the SIMD tile emits; `simd_tile_lock` certifies it equals `lanewise_add_body`. ## logicaffeine_compile::codegen_sva::simt_ports simt_ports — the SIMT engine’s step on ports: its uniforms, its mask and every lane’s varying as inputs, every lane’s output and the warp-reduce as outputs, a step every clock. Where the engine’s register file (`emit_gpu_simt_verilog`) takes a step’s operands a slot a clock and hands its results back a read at a time, this takes them all at once, as a caller holding them in registers presents them, and reads no register of its own on the way in. - [struct SimtPorts](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simt_ports/struct.SimtPorts): A ports engine’s RTL and the clocks from a step’s operands to its results. - [fn emit_simt_ports_verilog](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/simt_ports/fn.emit_simt_ports_verilog): Emit `eng`’s step on ports as module `name`: inputs `clk`, `a`, `b`, `mask` (when the engine is predicated) and `x0..`, outputs `y0..` and `reduced` (when it reduces). Refused unless the lane kernel computes `a·x + b` with `a` and `b` uniform and `x` per lane, and its reduce, if any, is an Add, Or, Xor or And: those fold a tree of lanes to the same word as the engine’s fold from the op’s identity. ## logicaffeine_compile::codegen_sva::soft_core_model The cycle-accurate Rust model of `benchmarks/silicon/soft_core.v` — the executable spec of the LOGOS universal interpreter in silicon. Fetch/decode/execute over a chip-word program (`[opcode:8][dst:8][a:8][b:8]`; wide/float/heap ops per the doc on `run_soft_core_typed`), returning the `Show` sequence. This is the differential ORACLE the whole spatial-interpreter campaign checks against: `compile_to_full_words` -> `run_soft_core_typed` must equal `compile::vm_outcome` for every program, and the iverilog testbenches agree with it. Lifted here (from `rtl.rs`’s test module) so both the in-crate RTL tests and the `logicaffeine_tests` integration locks share ONE oracle. - [struct SoftCoreRun](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/struct.SoftCoreRun): A run of the core: everything it showed, and how it failed if it did. - [enum ChipFailure](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/enum.ChipFailure): How the core stopped with a FAILURE (a trap-halt rather than a clean `Halt`). - [enum RegVal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/enum.RegVal): A VALUE integer register cell — the chip’s exact mirror of the VM’s `Int`/`BigInt` tower. The common case is a machine word (`Small`, the FAST path that keeps the 32-bit oracle byte-identical and the model fast over the 5e8-cycle budget); an integer that overflows the datapath promotes to an exact `Big` (unbounded `BigInt`), EXACTLY as `crate::vm::value::Value` / `RuntimeValue::Int` promotes to `RuntimeValue::BigInt`. INVARIANT (mirrors `RuntimeValue::from_bigint`): a `Big` never holds a value that fits `i64` — every arithmetic result normalizes back to `Small` when it fits — so a value has one canonical representation and the printed decimal is unique. Pointers, list lengths, map tags, iterator cursors, and register indices stay `Small` (they are addresses, never over-i64), so the structural heap/pointer machinery reads them through `RegVal::sm` with no BigInt on the hot structural path. - [enum ShowVal](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/enum.ShowVal): One `Show` output of the soft-core, tagged by the datapath that produced it: an integer `Show` (opcode 89, the 32-bit ALU/heap result) or a FLOAT `Show` (opcode 212 `ShowF`, an f64 from the FPU float bank). The chip is dynamically typed at the VM level, but the encoder statically lowers each `Show` to the one whose operand type it proved — so the model carries the same distinction and `ShowVal::fmt` renders each exactly as the VM does (ints bare, floats via `fmt_f64`). - [fn run_soft_core](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/fn.run_soft_core): The integer-differential view of `run_soft_core_typed`: the `Show` sequence as raw `i64` values. The pure integer programs (the hand-assembled ≡VM differential, the testbench emitter, the silicon demo) never emit a float `Show`, so at the 32-bit width this stays value-identical to the pre-FPU model (a 32-bit result carried in the low bits of an `i64`). A float program uses `run_soft_core_typed` + `ShowVal::fmt` instead (panics loudly here if one leaks a float). - [fn run_soft_core_outcome](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/fn.run_soft_core_outcome): Run `imem` and report the failure contract the RTL’s `failed`/`reasoned` ports carry: a reasoned trap’s last Text record IS its reason (so it leaves `shows`); a trap without text is `Trap`. - [fn run_soft_core_typed](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/fn.run_soft_core_typed) - [fn run_soft_core_typed_preloaded](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/fn.run_soft_core_typed_preloaded): Run with `preload` seeded into the heap as `heap[0..preload.len()]` — the model twin of the SoC’s weight DATA phase. With `preload = [len, w0, w1, …]` that is a `Seq of Int` at pointer 0, so the compiled `loaded()` (pointer 0) makes `item i of loaded()` read `heap[i]`. The bump allocator continues after it. - [fn run_soft_core_typed_w](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/fn.run_soft_core_typed_w): The WIDTH-PARAMETRIC form of `run_soft_core_typed` — the real fetch/decode/execute loop. Every integer VALUE is an auto-promoting `RegVal` (fast `Small(i64)` + exact `Big(BigInt)` on overflow), so the datapath’s `Int` is UNBOUNDED exactly like the VM’s — the chip differs NOWHERE from the VM on integers at ANY `width`. This is a REFRAME of the old width toggle: `width` no longer masks value arithmetic (a product that overflows i32/i64 PROMOTES, matching the VM, rather than wrapping), so `width == 32` and `width == 64` both equal `vm_outcome` on the `ShowVal` output. `width` survives as a perf/area knob and the datapath-width parameter for the raw-i64 OUTPUT VIEW (`run_soft_core_w`, which masks each value to `width` bits to model a fixed-width hardware output register). Addresses/iterators stay `usize`; the float bank stays f64 (width-independent). - [fn run_soft_core_w](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/fn.run_soft_core_w): The WIDTH-PARAMETRIC integer-differential view of `run_soft_core_typed_w`: the `Show` sequence as raw `i64` values MASKED to the datapath `width` — the fixed-width tape-out core’s OUTPUT REGISTER view (`width == 32` truncates each value to i32, `width == 64` is the full i64 pattern). This is DISTINCT from `run_soft_core_typed_w`, whose `ShowVal` carries the UNBOUNDED value (VM-exact via BigInt): the typed path is the chip that “differs nowhere from the VM”; this raw view models what a `width`-bit hardware output register would show if you read the low bits, so the 32-bit tape-out core’s wrap is still observable here. A value that overflowed to `Big` contributes its low-64-bit two’s-complement pattern, then sign-extended to `width`. (Float/Text/Word32 `Show`s panic — the pure-integer callers never emit them.) - [fn sign_extend_to_width](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/fn.sign_extend_to_width): Sign-extend the low `width` bits of a value to a full i64 — a fixed-width datapath’s result register. `width >= 64` is the identity; `width == 32` reproduces the 32-bit core’s `as i32` truncation exactly. The SAME logic yields a 32-, 64-, or any-power-of-two-width core — the toggle. - [fn soft_core_alu](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/fn.soft_core_alu): The Rust model of `alu.v` (32-bit), mirroring `emit_alu_datapath_verilog` exactly (wrapping / signed). Div / ExactDiv / Mod / FloorDiv are NOT here — they route to `soft_core_divider` (mirroring the soft-core’s `shared_divider`). DivPow2 stays (a cheap arithmetic shift). - [fn soft_core_alu_w](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/fn.soft_core_alu_w): Width-parametric model of `alu.v` — computes in i64 and sign-extends to `width` bits. `soft_core_alu` is the `width == 32` case (proven equal by `alu_width_toggle_is_32bit_faithful_and_64bit_wide`). Div/Mod/ FloorDiv route to `soft_core_divider_w`, mirroring the shared divider. - [fn soft_core_divider](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/fn.soft_core_divider): The Rust model of the soft-core’s `shared_divider` unit (truncated signed division): Div / ExactDiv → quotient, Mod → remainder (dividend’s sign), FloorDiv → floor-adjusted quotient; b==0 → 0. `run_soft_core` issues opcodes 12/13/14/15 here instead of the combinational ALU, mirroring the RTL (the divider is proven == this by iverilog `tb_shared_divider`). - [fn soft_core_divider_w](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/soft_core_model/fn.soft_core_divider_w): Width-parametric model of the shared divider (truncated signed division), sign-extended to `width`. `soft_core_divider` is the `width == 32` case. ## logicaffeine_compile::codegen_sva::spatial_emit Spatial source emission for a counted loop — the bridge from the certified fabric IR to the open Plasticine toolchain (Spatial → PIR → plastiroute → Tungsten; Koeplinger et al., PLDI 2018; the chain is mirrored at gitlab.com/dataplane-ai). P4 of the Plasticine lane. - [struct GdaColumn](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/spatial_emit/struct.GdaColumn): One array a scatter row term reads, as the GDA app declares it: its name, its axis and its host data. - [struct GdaPar](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/spatial_emit/struct.GdaPar): The knobs of Spatial’s `GDA` regression app (`pir/regression/GDA.scala`): the rows a tile of the data loads (`ts`), how many such tiles run at once (`op`), the rows of a tile reduced at once (`mp1`), the covariance rows one rank-1 update writes at once (`mp2`), and the lanes of the loads, the store and the column loops (`ip`). - [struct GemmUnroll](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/spatial_emit/struct.GemmUnroll): Emit a Spatial REGRESSION-HARNESS GEMM app for `C[m×n] = A[m×k] · B[k×n]` — the structure of Spatial’s own `regression/GEMM.scala` (an output tile `its × ts` accumulated over `k` in `ts`-chunks by a `MemReduce`, an `ip`-lane `Reduce` per dot product) with OUR shape and tiles, so a LOGOS matmul runs through the public chain as the toolchain’s authors would write it. Host data are small residues so the 32-bit sums stay exact and the harness’s `PASS` line means equality. Typed refusal when the tiles do not divide the shape (the template streams whole tiles). How wide each loop of the GEMM nest runs. Spatial’s own regression variants set exactly these, and a factor left at 1 is a loop we run serially where the hand-written app runs it wide. - [struct KmeansPar](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/spatial_emit/struct.KmeansPar): The knobs of Spatial’s `Kmeans` regression app (`pir/regression/Kmeans.scala`): the points a tile loads (`ts`), the lanes of the loads, the store and the feature loops (`ip`), how many tiles run at once (`op`), and how many points, centroids and centroid updates run at once (`mp1`, `mp2`, `mp3`). - [struct MapColumn](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/spatial_emit/struct.MapColumn): One column of a zip map as the app declares it: its name, its element type and the host data the program fills it with. - [struct MapPar](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/spatial_emit/struct.MapPar): The knobs of Spatial’s `BlackScholes` regression app (`pir/regression/BlackScholes.scala`): the tile `ts` of every column each outer iteration streams through FIFOs, how many tiles run at once (`op`), and the lanes of the loads, the map and the store (`ip`). - [struct OuterPar](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/spatial_emit/struct.OuterPar): The knobs of Spatial’s `OuterProduct` regression app (`pir/regression/OuterProduct.scala`): the tiles of the two vectors (`ts1`, `ts2`), the lanes of the loads and the store (`ip`), the lanes of the tile’s column and row loops (`ip1`, `ip2`), and how many tiles of each vector run at once (`op1`, `op2`). - [struct ZipColumn](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/spatial_emit/struct.ZipColumn): One column of a zip sum as the app declares it: its name (a Scala identifier the app does not otherwise use) and the host data the program fills it with. - [struct ZipPar](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/spatial_emit/struct.ZipPar): The knobs of Spatial’s reduce-over-tiles regression apps (`pir/regression/DotProduct.scala`, `TPCHQ6.scala`): the tile `ts` each outer iteration loads of every column, how many tiles run at once (`op`), and the lanes of the loads and of the inner reduce (`ip`). - [fn emit_spatial_counted_loop](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/spatial_emit/fn.emit_spatial_counted_loop): Emit Spatial source for the counted loop `lf` of LOGOS function `fn_name` as a standalone `SpatialApp` (arguments from the command line, the result printed), or a typed reason it cannot. - [fn emit_spatial_counted_loop_test](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/spatial_emit/fn.emit_spatial_counted_loop_test): Emit a Spatial REGRESSION-HARNESS app (`class extends SpatialTest`) for the counted loop: the sample `params` are its `runtimeArgs`, the VM’s answer `gold` is checked on the host, and the harness’s `PASS: true ()` line is what the toolchain ledger parses. Values are 64-bit `Long`: PIR’s Tungsten codegen lowers `Fix(true,64,0)` to C `long`, so the simulation computes what the VM computes (the ISCA’17 FU is 32-bit; a silicon run would need the narrower type). - [fn emit_spatial_gda_test](https://docs.logicaffeine.com/logicaffeine_compile/codegen_sva/spatial_emit/fn.emit_spatial_gda_test): Emit a Spatial REGRESSION-HARNESS scatter accumulation `S = Σ_{r