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
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

16 changes: 10 additions & 6 deletions crates/clazel-a64/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,23 @@ version = "0.0.0"
edition.workspace = true
license.workspace = true
publish.workspace = true
description = "The A64 (64-bit Arm) instruction-set subset the JIT emits (docs/phases/jit.md item J.4): semantics, encoder and decoder. Empty until then; it holds the vendored instruction-set sources."
description = "The A64 (64-bit Arm) instruction-set subset the JIT emits (docs/phases/jit.md item J.4): semantics, encoder and decoder. Only the primary spec and the contracts exist so far; it also holds the vendored instruction-set sources."

# No dependencies yet: jit.md item J.2 only vendors this crate's test data and
# inputs. The specification and implementation arrive with the item named in
# src/lib.rs.
[dependencies]
vstd = "=0.0.0-2026-10-04-0306"

# Verification tier (docs/VERIFICATION.md). `tier` is what is proven about the
# shipped code today (nothing: the crate is empty); `target-tier` is what
# jit.md's "Crates" table sets. The contracts come first (rule 3).
# shipped code today (nothing: the spec and the contracts are written, but no
# encoder or decoder exists, so there is no shipped code to prove);
# `target-tier` is what jit.md's "Crates" table sets. The contracts come first
# (rule 3).
[package.metadata.clazel]
tier = 0
target-tier = 2

[package.metadata.verus]
verify = true

[lints]
workspace = true

Expand Down
2 changes: 1 addition & 1 deletion crates/clazel-a64/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Part of [Clazel](../../README.md). The A64 (64-bit Arm) subset the JIT emits:
its semantics, encoder and decoder ([jit.md](../../docs/phases/jit.md) item
J.4).

Nothing is implemented yet (tier 0, target tier 2). Item J.2 vendored or
The primary spec (`src/spec.rs`, from the Sail Arm model) and the encoder/decoder contracts (`src/contract.rs`, `src/api.rs`) are written; no encoder or decoder exists yet (tier 0, target tier 2). Item J.2 vendored or
pinned the sources the semantics will be written against, in `tests/data/`:

| Suite | What | Held as |
Expand Down
49 changes: 49 additions & 0 deletions crates/clazel-a64/mutations.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
{
"mutations": [
{
"id": "add-with-carry-carry-inverted",
"file": "src/spec.rs",
"find": "let flag_c = if result == unsigned_sum {",
"replace": "let flag_c = if result != unsigned_sum {",
"expect": "killed",
"reason": "Inverts the carry flag of AddWithCarry (sail-arm v8_base.sail): 0xFFFFFFFF + 1 would set Z but clear C, so `b.hs` after `adds` would branch the wrong way and example_add_with_carry is false.",
"certificate": {
"file": "src/examples.rs",
"lemma": "example_add_with_carry()",
"witness": "add_with_carry(32, 0xFFFF_FFFF, 1, 0).1 == 0b0100int",
"reveal": [
"vstd::arithmetic::power::pow"
]
}
},
{
"id": "add-with-carry-no-overflow-flag",
"file": "src/spec.rs",
"find": "flag_n * 8 + flag_z * 4 + flag_c * 2 + flag_v)",
"replace": "flag_n * 8 + flag_z * 4 + flag_c * 2)",
"expect": "killed",
"reason": "Never sets V: 0x7FFFFFFF + 1 overflows as a signed add, so AddWithCarry must set V; without it `b.vs` and the signed conditions are wrong and example_add_with_carry is false.",
"certificate": {
"file": "src/examples.rs",
"lemma": "example_add_with_carry()",
"witness": "add_with_carry(32, 0x7FFF_FFFF, 1, 0).1 == 0b1000int",
"reveal": [
"vstd::arithmetic::power::pow"
]
}
},
{
"id": "bcond-imm19-at-bit-4",
"file": "src/spec.rs",
"find": "((imm19 as int) % 0x8_0000) * 0x20 + (\n cond as int)",
"replace": "((imm19 as int) % 0x8_0000) * 0x10 + (\n cond as int)",
"expect": "killed",
"reason": "Places B.cond's imm19 at bit 4 instead of bit 5 (decode_b_cond: imm19 @ 5): `b.eq #8` would encode as 54000020, so example_branches is false.",
"certificate": {
"file": "src/examples.rs",
"lemma": "example_branches()",
"witness": "encode(Instr::BCond { cond: 0, imm19: 2 }) == 0x5400_0020u32"
}
}
]
}
34 changes: 34 additions & 0 deletions crates/clazel-a64/src/api.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
//! The contract-only API of the encoder and the decoder: a trait with no
//! implementation, so Verus accepts it with no escape hatch (CLAUDE.md rule
//! 4), the pattern of `clazel-x64`'s `api.rs`. The implementation (the
//! second half of J.4) implements it, or replaces it with free functions
//! whose `requires` and `ensures` are the same predicates.

#[allow(unused_imports)]
use super::spec::*;
#[allow(unused_imports)]
use vstd::prelude::*;

verus! {

/// Encoder and decoder of the subset, with their contracts.
pub trait A64Codec {
/// The canonical encoding of `i` (see [`crate::spec::encode`]).
fn encode_instr(i: &Instr) -> (out: u32)
requires
crate::contract::encode_requires(*i),
ensures
crate::contract::encode_ensures(*i, out),
;

/// Decodes one instruction word: the instruction, or `None` if the word
/// is not the canonical encoding of an instruction of the subset.
fn decode_instr(w: u32) -> (r: Option<Instr>)
requires
crate::contract::decode_requires(w),
ensures
crate::contract::decode_ensures(w, r),
;
}

} // verus!
84 changes: 84 additions & 0 deletions crates/clazel-a64/src/contract.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
//! Contracts the encoder and the decoder must be proven to meet (CLAUDE.md
//! rule 3, docs/SPEC-STYLE.md). Each method of [`super::api::A64Codec`] has
//! one `requires` and one `ensures` predicate here, written in terms of
//! [`super::spec`]. Reviewing these and the spec is enough to know what the
//! implementation guarantees.
//!
//! What they say (jit.md J.4):
//!
//! - **The encoder emits only the canonical encoding** of a valid
//! instruction: the 32-bit word [`encode`] gives.
//! - **The decoder accepts only canonical encodings.** A `Some` result is a
//! valid instruction whose canonical encoding is the word. A `None` result
//! means that the word is no valid instruction's canonical encoding:
//! nothing the subset names is refused, and everything else (other
//! instructions, the field values [`valid_instr`] excludes, such as a shift
//! by 0 written `LSR`, a condition of `AL` or `NV`, a load with base `SP`,
//! unallocated encodings) is.
//! - **They are inverse on the subset:** [`encode_decode_inverse`] and
//! [`decode_encode_inverse`] follow from the two ensures above together
//! with [`canonical_injective`]; the last is a statement about the spec,
//! to be proven in the implementation half (it is what makes the decoder's
//! `Some` result unique). A64 words have a fixed size, so there is no
//! prefix question as on x86-64: the decoder takes one word.
//!
//! The words are in memory little-endian ([`word_bytes`]); turning four
//! bytes into a word is the caller's (`u32::from_le_bytes`).

#[allow(unused_imports)]
use super::spec::*;
#[allow(unused_imports)]
use vstd::prelude::*;

verus! {

/// Precondition of the encoder: the instruction is in the subset.
pub open spec fn encode_requires(i: Instr) -> bool {
valid_instr(i)
}

/// Postcondition of the encoder: the word is the canonical encoding.
pub open spec fn encode_ensures(i: Instr, out: u32) -> bool {
is_canonical_encoding(out, i)
}

/// Precondition of the decoder: none. Every word is a legal input.
pub open spec fn decode_requires(w: u32) -> bool {
true
}

/// Postcondition of the decoder.
pub open spec fn decode_ensures(w: u32, r: Option<Instr>) -> bool {
match r {
Some(i) => is_canonical_encoding(w, i),
None => forall|i: Instr| !is_canonical_encoding(w, i),
}
}

/// No two instructions of the subset share a canonical encoding, so a
/// decoder's `Some` is unique. To be proven about [`encode`] in the
/// implementation half; the contracts above are meaningful (a decoder may
/// pick any match) without it.
pub open spec fn canonical_injective() -> bool {
forall|i: Instr, j: Instr, w: u32|
is_canonical_encoding(w, i) && is_canonical_encoding(w, j) ==> i == j
}

/// The canonical encoding of every instruction of the subset is a 32-bit
/// word (so the encoder's `u32` result can hold it). To be proven about
/// [`encode`] in the implementation half.
pub open spec fn encode_fits() -> bool {
forall|i: Instr| valid_instr(i) ==> 0 <= #[trigger] encode(i) < 0x1_0000_0000
}

/// The encoder's output is read back by the decoder.
pub open spec fn encode_decode_inverse(i: Instr, w: u32) -> bool {
encode_ensures(i, w) ==> decode_ensures(w, Some(i))
}

/// A decoded instruction encodes to the word decoded.
pub open spec fn decode_encode_inverse(w: u32, i: Instr) -> bool {
decode_ensures(w, Some(i)) ==> encode(i) == w as int
}

} // verus!
Loading
Loading