Skip to content

riscv-coq connection theorems: generic transfer proved, per-instruction retirements for ALU and control - #4

Draft
JasonGross wants to merge 19 commits into
mit-plv:mainfrom
JasonGross:fable/riscv-connection-skeleton
Draft

JasonGross wants to merge 19 commits into
mit-plv:mainfrom
JasonGross:fable/riscv-connection-skeleton

Conversation

@JasonGross

@JasonGross JasonGross commented Sep 18, 2026 •

Copy link
Copy Markdown

Connection theorems between riscv-coq's omnisemantics and granite's reference semantics, for #1. Stacked on #3 (same base as the analysis in that thread).

riscvConnection/RiscvCoqConnection.v relates riscv-coq's run1 on the concrete MetricMinimalMMIO platform (with an MMIOSpec parameter) to one clock cycle of isaSpec/Spec.v's semantics.machine paired with the abstracted MMIO log.

  • A generic section OmniSimulation (fully proved): from one per-cycle simulation hypothesis it derives the transfer of coqutil's always (under all admissible inputs), of eventually/runsTo (under fair inputs), and of the always (eventually P) shape bedrock2 uses.
  • A section Connection instantiating it: the state relation (registers, pc, memories through riscv-coq's executable-address set, MMIO log, leakage trace; no CSRs, no metrics), decode_agree (proved for all 14 instructions), the per-cycle lemma cycle_sim_i as a fold over per-phase micro-step lemmas, and the corollaries granite_always, granite_eventually, granite_runsTo, granite_always_eventually, granite_io_spec as two-line applications.
  • Proved retirements: fetch, the seven ALU instructions, beq/bne/jalr, aligned non-MMIO lw/sw, the CSR/invalid case (impossible on this platform), the progress measure outside MMIO waits. The riscv-coq machine is the concrete DefaultRiscvState (identity address translation).
  • Remaining admits, each marked ADMIT in the file: MMIO wait phases (including MMIO and misaligned lw/sw), leakage alignment, interrupts, and the final io_spec weakening (needs a second relation for retirement targets in the generic section).

Build: the new theory needs coqutil and riscv-coq (stdlib-bits versions) built from source and found through COQPATH; see the README note. No change to granite's semantics or to riscv-coq.

Written by Claude Fable 5.1.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm

JasonGross and others added 6 commits September 15, 2026 22:12
A plain `dune build` at the root recurses into quartz/test, whose rules
run the quartz tests and need a slang binary that is not part of a
granite checkout, so the build fails before compiling anything of
granite. The default alias now covers core, app, isaSpec, quartz/lang
and quartz/examples, which is what quartz's own root dune file does.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
Bit vectors are stdlib's bits n := Zmod (2^n) (rocq-stdlib >= 9.1),
widths are Z, and the quartz submodule moves to the quartz commit that
makes the same change (mit-plv/quartz#2), so that granite and quartz
share one representation and rocq-stdpp-bitvector is no longer a
dependency.

core/Bits.v provides what stdpp.bitvector.definitions provided: the
bits notation, a Number Notation whose literals are constructor-shaped
so that closed constants still compute with Zmod.of_small_Z opaque
(simpl/cbn through of_small_Z are exponential in the nesting depth),
EqDecision/Countable/Inhabited/Finite instances, and the
granite-specific helpers on top of Zmod. Sections over an abstract
width take a Finite (bits idx_sz) hypothesis whose proof term is
canonical, because hint-generated instances differ between files and
then fail to unify.

Proof scripts change only where the two sides of a simulation used to
be syntactically equal by construction and now differ in spelling:
quartz interprets equality tests as Zmod.eqb while granite's programs
compare with Zmod.unsigned _ =? Zmod.unsigned _, so the scripts unfold
Zmod.eqb (and nonzero of an embedded boolean) before the case splits
that must hit both sides. Auto-generated hypothesis names follow the
new types, and two `clear`s that implicitly kept section variables
through the type of a kept hypothesis are made explicit or dropped.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
Bump the quartz submodule to fable/monomorphize (201186a), which stacks
Andres's monomorphization work on the stdlib-bits port. Two things in
that work reach granite. lang/let_lift.v is gone, so QuartzImpl_helpers
no longer imports it. The cpu program in Processor.v now calls the
helper constants directly (fifo1.full, btb.predPc, ...) instead of
going through the record implementations, so making fifo1.impl and the
other records opaque no longer keeps quartz's side of the lowering
lemmas folded while granite's simulation specs still spell the record
projections. QuartzImpl makes the constants opaque instead: with the
records transparent both sides reduce to the same fn.interp of the
constant, and the proof scripts go through unchanged.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
…imulation proof

MemoryImpl is a memory with no cache, write-through stores, one
outstanding load and a one-slot response buffer; its control state, and
hence RespReady, Full and the timing of responses, is a function of the
leakage trace alone (ctrl_exec_leakage). MemoryImplSimulates instantiates
MemorySpec's SpecParams by replaying the implementation on the trace and
proves Simulates.simulates between MemoryImpl.spec and MemorySpec.spec,
so the implementation can stand in for the memory model of the pipeline
proofs.

This is Andres Erbsen's gist
https://gist.github.com/andres-erbsen/d2a697b60e8455af7110bb4aa0ecafe8
ported from stdpp bitvectors to stdlib bits: bv Params.width is
bits Params.width, and bv_0 _ and the applied zeroes are the zeroes
literal. Nothing else changed; simulates is closed under the global
context.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
riscvConnection/RiscvCoqConnection.v states the theorems we expect to
prove between riscv-coq's omnisemantics (run1 under any PrimitivesParams
platform) and granite's reference semantics (isaSpec/Spec.v), for
mit-plv#1. Every non-trivial proof is Admitted by design.

A generic section derives the transfer of coqutil's `always`, of
`eventually`/`runsTo`, and of `always (eventually P)` from one core
step-simulation assumption, so that the work is shared between the
corollaries. The instantiation states the state relation, the one lemma
with content (cycle_sim), and the corollaries as two-line applications.
The open issues (interrupts, missing instructions, CSRs and traps,
misaligned accesses, leakage alignment, progress) are named hypotheses.

The new theory needs coqutil and riscv-coq (stdlib-bits versions) built
from source and found through COQPATH; see the README.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
@andres-erbsen

Copy link
Copy Markdown

@JasonGross-fiat-crypto-bot fill in more of the proof structure, but feel free to leave admits for the known discrepencies we have already discussed. if a major roadblock comes up, don't try to work around it, just report back

@JasonGross

Copy link
Copy Markdown
Author

On it: filling in the proof structure of RiscvCoqConnection.v, admits only at the discrepancies already listed; will report back here if anything major blocks.


Written by Claude Fable 5.1 via Claude Code (session https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm).

JasonGross and others added 12 commits September 20, 2026 00:44
transfer_always, transfer_eventually, transfer_runsTo and
transfer_always_eventually are now proved from two core assumptions
(retire-or-stutter over all admissible inputs, and the same with a
decreasing measure over fair inputs), which the instantiation derives
from one per-input cycle lemma. always is transferred over all
admissible inputs; eventually needs the fair subclass, since an input
that may stutter forever falsifies every eventually. No Admitted left in
the generic section.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
An abstract PrimitivesParams cannot be inverted: riscv-coq's Primitives
class only states sufficient conditions for mcomp_sat, so a hypothesis
mcomp_sat run1 m Q on an abstract platform says nothing about the
successor riscv-coq takes. Use MetricMinimalMMIO (what the bedrock2
compiler and GarageDoor run on), as the Kami connection does. With it,
run1_step_weaken and csr_primitives_stuck become lemmas.

Admissible inputs now execute at most one driver micro-step per cycle,
so a cycle retires at most one instruction; fair inputs additionally
schedule a micro-step and keep the MMIO handshake ready and valid. The
one per-input lemma cycle_sim_i yields both core forms (cycle_sim for
always over admissible inputs, cycle_sim_fair for eventually over fair
inputs), and the corollaries are unchanged two-line applications.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
to_riscv maps granite's decoded instruction to riscv-coq's, with the
immediates written the way riscv-coq's decode computes them. The proof
turns the decide hypotheses of granite's decoder into facts about the
unsigned fields, rewrites riscv-coq's bitSlice into granite's slices,
and reduces riscv-coq's decode chain; the shift immediates use that bits
25..31 are zero, csrrw reads its index off lookupCSR, sw commutes the
lor of the S immediate. The B-type immediate identity (nested Zmod.app
against shifted lors) is factored into b_imm_agree and left admitted as
decoder bookkeeping; it is not a discrepancy.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
… proved

cycle_sim_i now dispatches on the driver list (empty, one micro-step, or
too long) and on granite's phase, and delegates to stutter_empty,
stutter_leak, stutter_interrupt, retire_alu, retire_mul, retire_ctrl,
retire_mem, retire_csr_or_invalid and mmio_wait. The MMIO abstraction
cycle_mmio is now concrete (events read off the ready/valid handshake),
and the idle relation records idle wires and allows the StepInterrupt
phase. Every remaining admit carries an ADMIT marker naming the
discrepancy it stands for, or says that it is unfinished work.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
…fold

granite's own driver retires exactly one instruction per cycle with three
micro-steps ([None; None; None] in Spec.v's and TestSpec.v's examples:
leak, execute, interrupt poll), and the phase cycle StepLeak -> StepInstr
-> StepInterrupt -> StepLeak means at most one instruction retires in
three micro-steps. So admissible inputs now allow driver lists of length
at most three, which makes granite's driver admissible, instead of the
earlier "at most one micro-step". Whether arbitrary driver lists must be
supported (a multi-step core with a list of riscv-coq steps) is left as
a question for the PR.

cycle_sim_i is accordingly a fold: next_unfold exposes one cycle as the
prologue (interrupt latch, MMIO handshake), up to three micro-steps each
followed by the wire update, the final wire update and the default
machine update; the bookkeeping lemmas related_prologue,
related_update_mmio and related_set_default are proved for idle states
(the in-flight cases are properties of the in-flight relation parameter,
one of them marked ADMIT-HYP for the MMIO wait phases); msteps_sim folds
the per-phase micro-step lemmas, using that after a retirement the
remaining micro-steps of the cycle stutter. The accumulated leakage is
modelled as an abstract function of the architectural core so the
bookkeeping does not disturb it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
The state relation now has three constructors: idle (StepLeak or
StepInterrupt), post-leak (StepInstr inst, with inst the decode of the
word at Pc in Imem, and the leakage one event ahead of getTrace), and
the MMIO wait phase, which stays an abstract parameter. The idle and
post-leak constructors share a core_related record (idle wires, empty
MMIO buffers, no interrupt latched, registers, pc, memories, log), and
the cycle bookkeeping lemmas (default machine update, wire update,
prologue) are proved once for the record. Executable addresses are
required not to be MMIO, mirroring MinimalMMIO's valid_machine. The ISA
parameters get their specs as hypotheses: params.decode is granite's
decoder and the platform's isMMIOAddr agrees with granite's.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
For a related state whose pc is executable, riscv-coq's loadWord at pc
returns exactly granite's LoadWord of Imem at Pc. The proof goes byte
by byte through coqutil's footprint/option_all and granite's
load_bytes, using that executable addresses are non-MMIO (so present
in riscv-coq's memory), that Dmem agrees with Imem there, and that
granite's N addressing does not wrap within an executable word (a new
clause of mem_related). le_combine_granite bridges coqutil's
little-endian combine and stdpp's little_endian_to_Z.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
On this platform reading the privilege mode is impossible
(GetPrivMode interprets to False), so a run1_step hypothesis for a
csrrw is False: reduce_run1 unfolds run1 through the free-monad
interpreter with decode kept opaque, fetch_related identifies the
fetched word with granite's, decode_agree turns riscv-coq's decode of
it into the CSRInstruction, and the CSR execution reduces to the
impossible primitive. A word granite decodes as InvalidInstr is
excluded by the isa_coverage hypothesis. This discharges the CSR/trap
admit; it is a lemma, not a discrepancy.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
… waits

The measure is no longer a section parameter. It counts the stuttering
cycles until the next retirement on a one-micro-step-per-cycle driver:
5 in StepInterrupt, 4 in StepLeak, 3 in StepInstr, then 2/1/0 in the
MMIO wait according to whether a request is still to be sent, a
response still to arrive, or a response is buffered.

mstep_measure: a stuttering micro-step decreases it, except that a
waiting state may keep waiting. msteps_measure: one to three
micro-steps from a state not waiting on MMIO retire or decrease the
measure (waiting states are bounded by 2, below every other phase).
cycle_sim_i is now the plain admissible form (no measure) and
cycle_sim_fair_i the fair form; the latter is proved for the three
non-wait phases and delegates the wait phase to wait_cycle_progress,
the one remaining MMIO-wait admit at cycle level (a fair cycle from a
wait either sends the request, or delivers the response and retires).
The empty-driver stutter is the xs = [] case of msteps_sim, already
proved; fair inputs exclude it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
granite builds the immediate with nested Zmod.app, riscv-coq with
shifted Z.lor. unsigned_app turns each app into a shifted lor, the
shifts distribute and compose, and the two sides differ only by lor
associativity and commutativity (closed by bit extensionality). No
range facts about the slices are needed. Decoder bookkeeping, not a
discrepancy; decode_agree no longer depends on an admit.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
…successor

Register file: regs_related_get identifies riscv-coq's getReg with
granite's readReg (register 0 reads zero on both sides), and
regs_related_set carries the relation through setReg/writeReg (a write
to register 0 is dropped by riscv-coq and invisible in granite's
readReg). The immediates: signExtend 12 of the unsigned field is
Zmod.signed (smod_unsigned); the 20-bit immediates (Lui, Auipc) agree
after commuting the shift with the sign extension (imm20_agree). Both
machines add 4 to the pc.

The leakage clause of the post-instruction state is the one part not
provable today: leak_retire (ADMIT-HYP, leakage alignment) says that
riscv-coq's step realigns the two traces after granite's StepLeak
emitted the event early; it excludes mul, whose granite event carries
the zero-operand bit. Everything else in retire_alu is closed: the
witness is the riscv-coq successor, the phase, wires, buffers,
registers, pc, memory and log are related.

The register lemmas need map.ok for the register map (new section
hypothesis) and stdpp's finite/vector lemmas; riscv-coq's decode is
now written Decode.decode to avoid stdpp's decode.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
The branch decision is riscv-coq's reg_eqb against granite's
bool_decide on the same register values (regs_related_get); the
13-bit and 12-bit offsets agree by smod_unsigned. The alignment test
is the same predicate on both sides (aligned_agree: remu addr 4 /= 0
against is_word_aligned 4). On a misaligned target riscv-coq raises an
exception, which reads a CSR field and is therefore False on this
platform, so that case is vacuous; granite's trap on the same
condition is never reached. jalr: the link register gets pc + 4 on
both sides and the target masks bit 0 (lnot1). The leakage clause is
leak_retire, as for the ALU class.

granite_io_spec's final weakening stays admitted with a precise note:
it needs log_related in waiting states, which the MMIO wait design
must settle (see the comment in the file and the report).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
@JasonGross

Copy link
Copy Markdown
Author

Pushed 12 commits (head 4381075), dune build green.

Two statement changes, each its own commit so it can be reverted alone:

  • The platform is the concrete MetricMinimalMMIO with an MMIOSpec parameter (GarageDoor's platform). riscv-coq's Primitives class only gives sufficient conditions for mcomp_sat, so an abstract platform cannot be inverted (the Kami connection inverts the concrete interpreter for the same reason). CSR instructions and traps are therefore impossible in a hypothesis; that is now a lemma.
  • always transfers under all admissible inputs (no interrupt, at most three driver micro-steps per cycle, so at most one retirement) and eventually under fair inputs (a micro-step scheduled, MMIO handshake ready and valid). Question: is one instruction per cycle the intended driver interface, or must arbitrary DriverOut_nSteps lists be supported?

Proved: the generic section; decode_agree for all 14 instructions; fetch; the seven ALU instructions and beq/bne/jalr retire to the riscv-coq successor; the progress measure outside MMIO waits. Print Assumptions of granite_always: mstutter_interrupt, mstutter_leak, mwait, retire_mem, retire_mul; granite_eventually adds wait_cycle_progress.

Admits, each marked ADMIT: MMIO wait (four sites), leakage alignment (three), interrupts (one). One roadblock, left admitted rather than worked around: the final io_spec weakening needs the log relation in waiting states, which is false as stated (granite logs a store when the request leaves the buffer, riscv-coq when the instruction completes). The fix is a second relation for retirement targets in the generic section; note at the admit. Next: the aligned non-MMIO lw/sw case of retire_mem.


Written by Claude Fable 5.1 via Claude Code (session https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm).

@JasonGross JasonGross changed the title State the riscv-coq connection theorems (Admitted skeleton, for #1) riscv-coq connection theorems: generic transfer proved, per-instruction retirements for ALU and control Sep 20, 2026
The riscv-coq side is now the default RiscvMachine instance
(DefaultRiscvState: translate is the identity, as the comment already
said), so lw/sw reduce through the platform's load/store. On the
platform, a store or load whose four bytes are not all present falls
into the MMIO branch, which requires the address to be MMIO; granite's
test says it is not, so that case is vacuous. Otherwise the four bytes
are present and, by mem_related, are granite's.

Memory lemmas: load_bytes_related / load_word_related (riscv-coq's
loadWord of a non-MMIO aligned word is granite's LoadWord),
mem_related_store (unchecked_store_bytes of le_split against granite's
StoreWord through the byte-wise store_bytes lemmas, with the written
addresses removed from getXAddrs), to_byte_le (granite's
bits_to_little_endian is coqutil's le_split), and the address
arithmetic of an aligned word (no wrap-around, footprint offsets).
Alignment: aligned_mod4 and aligned_no_wrap from is_word_aligned; the
MMIO test through params_isMMIO (mmio_test_false).

retire_mem now dispatches on granite's alignment and MMIO tests; the
two delegated lemmas retire_mem_misaligned and retire_mem_mmio are the
only remaining admits of the memory class. Section hypotheses gained
map.ok Mem; coqutil's Map.Properties/Map.OfListWord and stdpp's
fin_maps are imported.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
@JasonGross

Copy link
Copy Markdown
Author

Head d8ae5e2: retire_mem's aligned non-MMIO lw/sw cases are proved (riscv-coq's loadWord/storeWord against granite's byte-wise LoadWord/StoreWord, written addresses removed from getXAddrs); the memory class keeps admits only for the MMIO and misaligned branches. The riscv-coq machine is now the concrete DefaultRiscvState (identity translation), as the file's comment already intended. One more entry for the discrepancy list: a store wrapping past 2^32 differs between the sides (granite addresses Dmem by N); alignment excludes it here.

The io_spec roadblock is intrinsic to the current log abstraction, not to the proof structure: granite's abstract log records an MMIO store when the request leaves the buffer, riscv-coq's when the instruction completes, so during a wait the two logs differ by one event, and the states the generic transfer lemmas deliver can be waiting states. A second relation for retirement targets does not help, since the eventually base case and the always invariant both land on such states.

Proposed fix, not applied because it changes what granite_io_spec says: let cycle_mmio (this file's abstraction, not granite's semantics) record the MMIO event when the response handshake fires. Then the abstract log equals riscv-coq's at every related state and the weakening is a few lines; the cost is that the log lags the hardware request by the response handshake. Fine to do that, or should the log stay at request time and the theorem be stated modulo that lag?


Written by Claude Fable 5.1 via Claude Code (session https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants