Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# The Sail RISC-V model in Lean is generated (see sail-riscv-lean/README.md): collapse it in diffs.
sail-riscv-lean/LeanRV64D/** linguist-generated=true
sail-riscv-lean/LeanRV64D.lean linguist-generated=true
44 changes: 44 additions & 0 deletions .github/workflows/sail-riscv-lean.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
name: Sail RISC-V Lean model

on:
push:
branches: ["main"]
paths: ["sail-riscv-lean/**", ".github/workflows/sail-riscv-lean.yml"]
pull_request:
paths: ["sail-riscv-lean/**", ".github/workflows/sail-riscv-lean.yml"]

permissions:
contents: read

concurrency:
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
cancel-in-progress: true

jobs:
# Regenerates the model from the commits in sail-riscv-lean/PINS and fails if it differs from
# the committed one: the model is exactly what the Sail compiler outputs, nothing hand-written.
generated:
name: Model matches its pinned sources
runs-on: ubuntu-latest
timeout-minutes: 60
defaults:
run:
working-directory: sail-riscv-lean
steps:
- name: Checkout sources
uses: actions/checkout@v4

- name: Install system dependencies
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends opam libgmp-dev z3 pkg-config cmake
opam init -y --bare --disable-sandboxing

- name: Regenerate the model
run: scripts/generate.sh

- name: Model is up to date
run: |
paths="LeanRV64D LeanRV64D.lean lakefile.toml lean-toolchain"
git status --porcelain -- $paths
test -z "$(git status --porcelain -- $paths)"
1 change: 1 addition & 0 deletions formal-riscv/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.lake/
98 changes: 98 additions & 0 deletions formal-riscv/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# formal-riscv: the Clean model against the Sail RISC-V spec

Proves, instruction by instruction, that what the AIR's Clean model (`../formal`, PR #1027)
computes is what the official RISC-V spec says. The spec is the Sail model
([riscv/sail-riscv](https://github.com/riscv/sail-riscv)), translated to Lean by the Lean
backend of the Sail compiler ([rems-project/sail](https://github.com/rems-project/sail)). The
translation lives in `../sail-riscv-lean`, generated from the commits pinned in its `PINS`; CI
checks that it is exactly what the Sail compiler outputs for them.
The approach follows [zisk-fv](https://github.com/eth-act/zisk-fv) (`ZiskFv/SailSpec/`).

## Build

```bash
cd formal-riscv
lake exe cache get # Mathlib oleans
lake build
```

The first build compiles Clean, the Clean model and the Sail model (the largest Sail module,
`InstsEnd`, takes minutes).

`../formal` and `../sail-riscv-lean` are path dependencies, but this project has its own
`lake-manifest.json`: when `formal/` updates Mathlib or Clean, run `lake update` here too so both
use the same versions. `lean-toolchain` must match `formal/lean-toolchain`; `lake update` may set
it to the Sail model's version, so check it afterwards.
This folder is not built by CI (`.github/workflows/formal.yml` only covers `formal/**`).

## Structure

Each instruction is three steps:

```
Sail execute_RTYPE … SLL ──(1)── sllPure ──(2)── Alu.shiftResult ──(3)── ALU bus message
(state) (values) (Clean model) (what the CPU learns)
```

1. **Sail** (`RiscvEquiv/Sll/Sail.lean`): the instruction's computation is taken out of Sail
and written as a pure function, `sllPure`, with no state. `execute_SLL` proves that what
Sail does to the registers is exactly: read `rs1` and `rs2`, write `sllPure x[rs1] x[rs2]`
to `rd`.
2. **Bridge** (`RiscvEquiv/Sll/Bridge.lean`): Sail works with 64-bit vectors (`BitVec 64`), the
Clean model with naturals. `sllPure_toNat` proves that `sllPure`, read as a natural with
`.toNat`, is the Clean model's function at the flags of `SLL` (`Alu.shiftResult`; for `SLT`
and `SLTU` it is `Alu.ltBit`).
3. **Alu** (`RiscvEquiv/Sll/Alu.lean`): `sll_alu_matches_sail` proves that if the CPU pulls an
ALU bus message with the flags of `SLL`, its result is `sllPure a b`. It uses the bus
guarantees (`Alu.Guarantees`) that PR #1027 already proves for each table.

In one line: Sail = `*Pure`, `*Pure` = Clean function, Clean function = what arrives on the bus.

`AluBus.lean` is shared: one lemma per clause of `Alu.Guarantees` (SHIFT, SHIFT with
`word = 1`, LT, EQ) that reads a message's result as a natural. Each `Alu.lean` instantiates
one of them at its flags, so it is one line per instruction. Each clause takes only the range
hypotheses its chip's spec assumes: none for SHIFT, the low words for LT, all four for EQ.

`FreeM.lean` is shared by the `Sail.lean` files: the Sail model runs in a free monad, and
`FreeM.lean` proves its monad laws, which lean-sail does not provide, so the proofs can
flatten Sail's nested `do` blocks.

The immediate versions have no `Bridge.lean`: they are the register version with the
immediate as the second operand, so they reuse its bridge and its `Alu` theorem.

Done so far:

| Instructions | Folder | Table |
|---|---|---|
| `SLL`, `SRL`, `SRA` | `Sll/`, `Srl/`, `Sra/` | SHIFT |
| `SLLI`, `SRLI`, `SRAI` | `ShiftImm/` | SHIFT |
| `SLLW`, `SRLW`, `SRAW`, `SLLIW`, `SRLIW`, `SRAIW` (low 32 bits) | `ShiftW/` | SHIFT |
| `SLT`, `SLTU` | `Slt/` | LT |
| `SLTI`, `SLTIU` | `SltImm/` | LT |
| `BEQ`, `BNE` (condition only) | `Beq/` | EQ |
| `BLT`, `BGE`, `BLTU`, `BGEU` (condition only) | `Blt/` | LT |

## Trust and scope

- That the Sail model matches the RISC-V manual is assumed (it is the official model).
- That the Clean model matches the Rust circuit is checked by `prover/src/tests/lean_diff.rs`,
a randomized test, not a proof.
- The PC and the register file are not modeled on the circuit side yet: that needs the CPU in
Clean. Steps 1 to 3 connect values only.
- Word shifts: only the 32-bit result (`outLo`) is connected. The sign extension to 64 bits
is done by the CPU32 chip, not modeled yet. The first operand is assumed to be what CPU32
sends (`spec/src/cpu32.toml`): the low word of `rs1`, zero-extended (`SLLW`, `SRLW`) or
sign-extended (`SRAW`).
- Branches: only the condition is connected to the circuit. Sail's jump to `PC + imm` needs the
PC on the circuit side (the CPU in Clean).
- The Sail model declares some platform settings as `axiom`s (`LeanRV64D/RiscvExtras.lean`).
The branch theorems mention `jump_to`, which depends on `sys_enable_experimental_extensions`,
so `#print axioms` lists it; the proofs themselves use only Lean's standard axioms.
- The `Alu` theorems assume (hypotheses `ha`, `hb`) that the CPU sends `x[rs1]` and the second
operand (`x[rs2]`, `shamt`, or the immediate sign-extended to 64 bits) on the bus. Proving
that also needs the CPU in Clean; it will be a fourth step per instruction on top of these
three.
- The `Alu` theorems also assume (hypothesis `hflags`) the flag byte of each instruction: that
the circuit decodes the opcode to those flags is not proven here.
- Word shifts with a register operand: CPU32 sends the low word of `rs2` sign-extended, not
`x[rs2]`, so `hb` asks only that the shift amount agrees mod 32, which is all RISC-V reads.
27 changes: 27 additions & 0 deletions formal-riscv/RiscvEquiv.lean
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
import RiscvEquiv.AluBus
import RiscvEquiv.FreeM
import RiscvEquiv.Sll.Sail
import RiscvEquiv.Sll.Bridge
import RiscvEquiv.Sll.Alu
import RiscvEquiv.Srl.Sail
import RiscvEquiv.Srl.Bridge
import RiscvEquiv.Srl.Alu
import RiscvEquiv.Sra.Sail
import RiscvEquiv.Sra.Bridge
import RiscvEquiv.Sra.Alu
import RiscvEquiv.ShiftImm.Sail
import RiscvEquiv.ShiftImm.Alu
import RiscvEquiv.Slt.Sail
import RiscvEquiv.Slt.Bridge
import RiscvEquiv.Slt.Alu
import RiscvEquiv.SltImm.Sail
import RiscvEquiv.SltImm.Alu
import RiscvEquiv.Beq.Sail
import RiscvEquiv.Beq.Bridge
import RiscvEquiv.Beq.Alu
import RiscvEquiv.Blt.Sail
import RiscvEquiv.Blt.Bridge
import RiscvEquiv.Blt.Alu
import RiscvEquiv.ShiftW.Sail
import RiscvEquiv.ShiftW.Bridge
import RiscvEquiv.ShiftW.Alu
102 changes: 102 additions & 0 deletions formal-riscv/RiscvEquiv/AluBus.lean
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
import LambdaVM.Buses.Alu

/-!
# Reading ALU bus messages as naturals

The CPU does not read the tables' rows: it pulls a message from the ALU bus and learns
`Alu.Guarantees` (`formal/LambdaVM/Buses/Alu.lean`), which each table's soundness establishes
for every message it pushes. The guarantees are stated on field elements and for generic flags.
This file has one lemma per clause (SHIFT, SHIFT with `word = 1`, LT, EQ) that reads the result
of a message as a natural in terms of its 64-bit operands `a` and `b`. Each instruction's
`Alu.lean` instantiates one of them at its flags and rewrites with its bridge.
-/

namespace RiscvEquiv

open LambdaVM

/-- `ltBit` is a bit. -/
lemma ltBit_lt_two (s i L R : ℕ) : Alu.ltBit s i L R < 2 := by
unfold Alu.ltBit
split <;> omega

/-- `eqBit` is a bit. -/
lemma eqBit_lt_two (i A B : ℕ) : Alu.eqBit i A B < 2 := by
unfold Alu.eqBit
split_ifs <;> omega

/-- With `word = 0` only the shift amount mod 64 matters. -/
lemma shiftResult_amt (s d x s₁ s₂ : ℕ) (h : s₁ % 64 = s₂ % 64) :
Alu.shiftResult 0 s d x s₁ = Alu.shiftResult 0 s d x s₂ := by
simp [Alu.shiftResult, h]

/-- With `word = 1` only the shift amount mod 32 matters. -/
lemma shiftResult_word_amt (s d x s₁ s₂ : ℕ) (h : s₁ % 32 = s₂ % 32) :
Alu.shiftResult 1 s d x s₁ = Alu.shiftResult 1 s d x s₂ := by
simp [Alu.shiftResult, h]

/-- A SHIFT message with `word = 0` and flags `signed = s`, `direction = d` carries
`shiftResult` of its operands. SHIFT reads only the low byte of the shift amount; mod 64 it is
the low bits of `b`. No range hypotheses: SHIFT range-checks its operands itself. -/
lemma shift_alu (m : Alu.Msg (F p)) (hg : Alu.Guarantees m)
(s d : ℕ) (hs : s < 2) (hd : d < 2) (hflags : m.flags.val = opselSHIFT + 32 * s + 64 * d)
(x : ℕ) (b : BitVec 64) (ha : dword m.in1Lo m.in1Hi = x)
(hb : dword m.in2Lo m.in2Hi = b.toNat) :
dword m.outLo m.outHi = Alu.shiftResult 0 s d x b.toNat := by
obtain ⟨-, -, hshift⟩ := hg
obtain ⟨-, -, hout⟩ := hshift 0 s d (by norm_num) hs hd (by simpa using hflags)
have hamt : m.in2Lo.val % 256 % 64 = b.toNat % 64 := by
rw [← hb, dword]
omega
rw [hout, ha, shiftResult_amt _ _ _ _ _ hamt]

/-- A SHIFT message with `word = 1` and flags `signed = s`, `direction = d` carries, in `outLo`,
the low word of `shiftResult` of its operands. Only the shift amount mod 32 matters, so `hb`
asks only that: CPU32 sends the low word of `rs2` sign-extended, not `x[rs2]`. No range
hypotheses, as in `shift_alu`. -/
lemma shift_word_alu_low (m : Alu.Msg (F p)) (hg : Alu.Guarantees m)
(s d : ℕ) (hs : s < 2) (hd : d < 2) (hflags : m.flags.val = opselSHIFT + 1 + 32 * s + 64 * d)
(x : ℕ) (b : BitVec 64) (ha : dword m.in1Lo m.in1Hi = x)
(hb : dword m.in2Lo m.in2Hi % 32 = b.toNat % 32) :
m.outLo.val = Alu.shiftResult 1 s d x b.toNat % 2^32 := by
obtain ⟨-, -, hshift⟩ := hg
obtain ⟨hlo, -, hout⟩ := hshift 1 s d (by norm_num) hs hd hflags
have hamt : m.in2Lo.val % 256 % 32 = b.toNat % 32 := by
rw [← hb, dword]
omega
have hlow : m.outLo.val = dword m.outLo m.outHi % 2^32 := by
rw [dword]
omega
rw [hlow, hout, ha, shiftResult_word_amt _ _ _ _ _ hamt]

/-- An LT message with flags `signed = s`, `invert = i` carries `ltBit s i` of its operands.
The result travels as `(bit, 0)`. Only the low words need a range hypothesis: LT range-checks
the high ones itself. -/
lemma lt_alu_bit (m : Alu.Msg (F p)) (hg : Alu.Guarantees m)
(h1 : m.in1Lo.val < 2^32) (h3 : m.in2Lo.val < 2^32)
(s i : ℕ) (hs : s < 2) (hi : i < 2) (hflags : m.flags.val = opselLT + 32 * s + 64 * i)
(a b : BitVec 64) (ha : dword m.in1Lo m.in1Hi = a.toNat)
(hb : dword m.in2Lo m.in2Hi = b.toNat) :
dword m.outLo m.outHi = Alu.ltBit s i a.toNat b.toNat := by
obtain ⟨hlt, -, -⟩ := hg
obtain ⟨hhi, hlo⟩ := hlt s i hs hi hflags h1 h3
have hbit := ltBit_lt_two s i a.toNat b.toNat
rw [dword, hhi, hlo, ha, hb, ZMod.val_zero, val_natCast_of_lt_two_pow_40 (by omega),
mul_zero, add_zero]

/-- An EQ message with flag `invert = i` carries `eqBit i` of its operands. The result travels
as `(bit, 0)`. -/
lemma eq_alu_bit (m : Alu.Msg (F p)) (hg : Alu.Guarantees m)
(h1 : m.in1Lo.val < 2^32) (h2 : m.in1Hi.val < 2^32)
(h3 : m.in2Lo.val < 2^32) (h4 : m.in2Hi.val < 2^32)
(i : ℕ) (hi : i < 2) (hflags : m.flags.val = opselEQ + 64 * i)
(a b : BitVec 64) (ha : dword m.in1Lo m.in1Hi = a.toNat)
(hb : dword m.in2Lo m.in2Hi = b.toNat) :
dword m.outLo m.outHi = Alu.eqBit i a.toNat b.toNat := by
obtain ⟨-, heq, -⟩ := hg
obtain ⟨hhi, hlo⟩ := heq i hi hflags h1 h2 h3 h4
have hbit := eqBit_lt_two i a.toNat b.toNat
rw [dword, hhi, hlo, ha, hb, ZMod.val_zero, val_natCast_of_lt_two_pow_40 (by omega),
mul_zero, add_zero]

end RiscvEquiv
41 changes: 41 additions & 0 deletions formal-riscv/RiscvEquiv/Beq/Alu.lean
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
import RiscvEquiv.Beq.Bridge
import RiscvEquiv.AluBus

/-!
# BEQ and BNE: what the CPU learns from the ALU bus is Sail's condition

Same shape as `Slt/Alu.lean`, with the EQ clause of `Alu.Guarantees` (`eq_alu_bit`, in
`AluBus.lean`): the flag byte is
`opsel(EQ) + 64·invert`, and the result travels as `(bit, 0)`. The CPU takes the branch when
the bit is `1`.
-/

namespace RiscvEquiv

open LambdaVM

/-- An ALU message with the flags of `BEQ` (`opsel = EQ`, `invert = 0`) and range-checked
operands carries Sail's `BEQ` condition. -/
theorem beq_alu_matches_sail (m : Alu.Msg (F p)) (hg : Alu.Guarantees m)
(h1 : m.in1Lo.val < 2^32) (h2 : m.in1Hi.val < 2^32)
(h3 : m.in2Lo.val < 2^32) (h4 : m.in2Hi.val < 2^32)
(hflags : m.flags.val = opselEQ)
(a b : BitVec 64) (ha : dword m.in1Lo m.in1Hi = a.toNat)
(hb : dword m.in2Lo m.in2Hi = b.toNat) :
dword m.outLo m.outHi = (beqPure a b).toNat := by
rw [beqPure_toNat]
exact eq_alu_bit m hg h1 h2 h3 h4 0 (by norm_num) (by simpa using hflags) a b ha hb

/-- An ALU message with the flags of `BNE` (`opsel = EQ`, `invert = 1`) and range-checked
operands carries Sail's `BNE` condition. -/
theorem bne_alu_matches_sail (m : Alu.Msg (F p)) (hg : Alu.Guarantees m)
(h1 : m.in1Lo.val < 2^32) (h2 : m.in1Hi.val < 2^32)
(h3 : m.in2Lo.val < 2^32) (h4 : m.in2Hi.val < 2^32)
(hflags : m.flags.val = opselEQ + 64)
(a b : BitVec 64) (ha : dword m.in1Lo m.in1Hi = a.toNat)
(hb : dword m.in2Lo m.in2Hi = b.toNat) :
dword m.outLo m.outHi = (bnePure a b).toNat := by
rw [bnePure_toNat]
exact eq_alu_bit m hg h1 h2 h3 h4 1 (by norm_num) (by simpa using hflags) a b ha hb

end RiscvEquiv
26 changes: 26 additions & 0 deletions formal-riscv/RiscvEquiv/Beq/Bridge.lean
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
import RiscvEquiv.Beq.Sail
import LambdaVM.Buses.Alu

/-!
# BEQ and BNE: the Clean model's equality bit is Sail's condition

The EQ table's result is `Alu.eqBit invert A B`, `(A = B) xor invert` on naturals. With
`invert = 0` it is the `BEQ` condition, with `invert = 1` the `BNE` one. Two 64-bit vectors
are equal exactly when their naturals are, so the bridge is one case split.
-/

namespace RiscvEquiv

open LambdaVM

/-- `beqPure` as a bit is `eqBit` with the flags of `BEQ` (`invert = 0`). -/
theorem beqPure_toNat (a b : BitVec 64) :
(beqPure a b).toNat = Alu.eqBit 0 a.toNat b.toNat := by
by_cases h : a = b <;> simp [beqPure, Alu.eqBit, h, BitVec.toNat_inj]

/-- `bnePure` as a bit is `eqBit` with the flags of `BNE` (`invert = 1`). -/
theorem bnePure_toNat (a b : BitVec 64) :
(bnePure a b).toNat = Alu.eqBit 1 a.toNat b.toNat := by
by_cases h : a = b <;> simp [bnePure, Alu.eqBit, h, BitVec.toNat_inj]

end RiscvEquiv
Loading
Loading