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-x64/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 x86-64 instruction-set subset the JIT emits (docs/phases/jit.md item J.3): semantics, encoder and decoder. Empty until then; it holds the vendored instruction-set sources."
description = "The x86-64 instruction-set subset the JIT emits (docs/phases/jit.md item J.3): 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-x64/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
Part of [Clazel](../../README.md). The x86-64 subset the JIT emits: its
semantics, encoder and decoder ([jit.md](../../docs/phases/jit.md) item J.3).

Nothing is implemented yet (tier 0, target tier 2). Item J.2 vendored or
The primary spec (`src/spec.rs`, from ACL2) 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
43 changes: 43 additions & 0 deletions crates/clazel-x64/mutations.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
{
"mutations": [
{
"id": "rex-swaps-w-and-r",
"file": "src/spec.rs",
"find": "8 * bool_to_bit(w) + 4 * bool_to_bit(r)",
"replace": "4 * bool_to_bit(w) + 8 * bool_to_bit(r)",
"expect": "killed",
"reason": "Swaps REX.W and REX.R (Intel SDM vol. 2 §2.2.1, ACL2 x86isa): `add rax, rbx` would encode as 44 01 D8, a 32-bit add with an extended register, so example_add_rax_rbx is false.",
"certificate": {
"file": "src/examples.rs",
"lemma": "example_add_rax_rbx()",
"witness": "encode(Instr::AluRR { alu: AluOp::Add, sz: Size::W64, dst: 0, src: 3 })[0] == 0x44u8"
}
},
{
"id": "mov-imm32-register-not-reduced",
"file": "src/spec.rs",
"find": "(0xB8 + (dst as int) % 8) as u8,\n ] + le_bytes(imm as int, 4),",
"replace": "(0xB8 + (dst as int)) as u8,\n ] + le_bytes(imm as int, 4),",
"expect": "killed",
"reason": "Adds the whole register number to the B8+r opcode instead of its low three bits (the fourth is REX.B): `mov r8d, imm32` would be 41 C0 …, so example_mov_imm32_r8 is false.",
"certificate": {
"file": "src/examples.rs",
"lemma": "example_mov_imm32_r8()",
"witness": "encode(Instr::MovImm32 { dst: 8, imm_u32: 0x12345678 })[1] == 0xC0u8"
}
},
{
"id": "sib-swaps-index-and-base",
"file": "src/spec.rs",
"find": "(sib_scale(m) * 64 + (ix % 8) * 8 + (m.base as int) % 8) as u8",
"replace": "(sib_scale(m) * 64 + ((m.base as int) % 8) * 8 + ix % 8) as u8",
"expect": "killed",
"reason": "Swaps the SIB index and base fields: `mov rax, [rbx + rcx*4 + 0x10]` would address [rcx + rbx*4 + 0x10] (SIB 99), so example_mov_load is false.",
"certificate": {
"file": "src/examples.rs",
"lemma": "example_mov_load()",
"witness": "encode(Instr::MovLoad { sz: Size::W64, dst: 0, mem: Mem { base: 3, index: Some(Index { reg: 1, scale: 2 }), disp: 0x10 } })[3] == 0x99u8"
}
}
]
}
35 changes: 35 additions & 0 deletions crates/clazel-x64/src/api.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
//! 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-js-lexer`'s `api.rs`. The implementation (the
//! second half of J.3) 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 X64Codec {
/// The canonical encoding of `i` (see [`crate::spec::encode`]).
fn encode_instr(i: &Instr) -> (out: Vec<u8>)
requires
crate::contract::encode_requires(*i),
ensures
crate::contract::encode_ensures(*i, out@),
;

/// Decodes one instruction at the start of `bytes`: the instruction and
/// its length, or `None` if the bytes do not begin with the canonical
/// encoding of an instruction of the subset.
fn decode_instr(bytes: &[u8]) -> (r: Option<(Instr, usize)>)
requires
crate::contract::decode_requires(bytes@),
ensures
crate::contract::decode_ensures(bytes@, r),
;
}

} // verus!
73 changes: 73 additions & 0 deletions crates/clazel-x64/src/contract.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
//! Contracts the encoder and the decoder must be proven to meet (CLAUDE.md
//! rule 3, docs/SPEC-STYLE.md). Each method of [`super::api::X64Codec`] 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.3):
//!
//! - **The encoder emits only the canonical encoding** of a valid
//! instruction.
//! - **The decoder accepts only canonical encodings.** A `Some` result is a
//! valid instruction whose canonical encoding is exactly the bytes it
//! consumed. A `None` result means that no valid instruction's canonical
//! encoding begins the input: nothing the subset names is refused, and
//! everything else (redundant prefixes, alternative ModRM forms, other
//! opcodes, a truncated instruction) is.
//! - **They are inverse on the subset:** [`encode_decode_inverse`] and
//! [`decode_encode_inverse`] follow from the two ensures above together
//! with [`canonical_prefix_free`]; 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).

#[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 bytes are the canonical encoding.
pub open spec fn encode_ensures(i: Instr, out: Seq<u8>) -> bool {
is_canonical_encoding(out, i)
}

/// Precondition of the decoder: none. Every byte string is a legal input.
pub open spec fn decode_requires(bytes: Seq<u8>) -> bool {
true
}

/// Postcondition of the decoder.
pub open spec fn decode_ensures(bytes: Seq<u8>, r: Option<(Instr, usize)>) -> bool {
match r {
Some((i, n)) => n <= bytes.len() && is_canonical_encoding(bytes.subrange(0, n as int), i),
None => forall|i: Instr| !starts_with_encoding(bytes, i),
}
}

/// No canonical encoding is a proper prefix of another instruction's, nor
/// two different instructions' encodings of one input: the set of canonical
/// encodings is a prefix code, 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_prefix_free() -> bool {
forall|i: Instr, j: Instr, bytes: Seq<u8>|
starts_with_encoding(bytes, i) && starts_with_encoding(bytes, j) ==> i == j
}

/// The encoder's output is read back by the decoder, whatever follows it.
pub open spec fn encode_decode_inverse(i: Instr, rest: Seq<u8>) -> bool {
valid_instr(i) ==> starts_with_encoding(encode(i) + rest, i)
}

/// A decoded instruction encodes to the bytes decoded.
pub open spec fn decode_encode_inverse(bytes: Seq<u8>, i: Instr, n: usize) -> bool {
decode_ensures(bytes, Some((i, n))) ==> encode(i) == bytes.subrange(0, n as int)
}

} // verus!
85 changes: 85 additions & 0 deletions crates/clazel-x64/src/examples.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
//! Small examples evaluated against the spec: evidence that the canonical
//! encoding and the semantics compute what an assembler and the programmer's
//! reading of the instruction say.
//!
//! The byte strings are the usual ones for the instructions (they are what
//! any x86-64 assembler emits for these forms, with the `mod = 10` SIB
//! memory operand the canonical encoding fixes). They are not copied from
//! the Intel SDM, which the author of the primary transcription does not
//! read. The decoder differential against `iced-x86` (J.3) is the thorough
//! check of the encoding; these are a smoke test of it.

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

verus! {

/// `add rax, rbx` is `48 01 D8`.
pub proof fn example_add_rax_rbx()
ensures
encode(Instr::AluRR { alu: AluOp::Add, sz: Size::W64, dst: 0, src: 3 })
=~= seq![0x48u8, 0x01, 0xD8],
{
reveal_with_fuel(le_bytes, 5);
}

/// `mov rax, [rbx + rcx*4 + 0x10]` with the fixed `mod = 10` SIB form is
/// `48 8B 84 8B 10 00 00 00`.
pub proof fn example_mov_load()
ensures
encode(
Instr::MovLoad {
sz: Size::W64,
dst: 0,
mem: Mem { base: 3, index: Some(Index { reg: 1, scale: 2 }), disp: 0x10 },
},
) =~= seq![0x48u8, 0x8B, 0x84, 0x8B, 0x10, 0x00, 0x00, 0x00],
{
reveal_with_fuel(le_bytes, 5);
}

/// `mov r8d, 0x12345678` is `41 B8 78 56 34 12`.
pub proof fn example_mov_imm32_r8()
ensures
encode(Instr::MovImm32 { dst: 8, imm_u32: 0x12345678 }) =~= seq![
0x41u8, 0xB8, 0x78, 0x56, 0x34, 0x12,
],
{
reveal_with_fuel(le_bytes, 5);
}

/// `sete sil` needs a `REX` byte: `40 0F 94 C6`.
pub proof fn example_sete_sil()
ensures
encode(Instr::Setcc { cc: 4, dst: 6 }) =~= seq![0x40u8, 0x0F, 0x94, 0xC6],
{
}

/// `addsd xmm1, xmm2` is `F2 0F 58 CA`.
pub proof fn example_addsd()
ensures
encode(Instr::FpArith { fop: BinOp::Add, dst: 1, xsrc: XmmSrc::Reg(2) }) =~= seq![
0xF2u8, 0x0F, 0x58, 0xCA,
],
{
}

/// `movq xmm0, rax` is `66 48 0F 6E C0`.
pub proof fn example_movq_to_xmm()
ensures
encode(Instr::MovqToXmm { dst: 0, src: 0 }) =~= seq![0x66u8, 0x48, 0x0F, 0x6E, 0xC0],
{
}

/// `ret` is `C3` and `jmp +0` is `E9 00 00 00 00`.
pub proof fn example_ret_jmp()
ensures
encode(Instr::Ret) =~= seq![0xC3u8],
encode(Instr::Jmp { rel: 0 }) =~= seq![0xE9u8, 0, 0, 0, 0],
{
reveal_with_fuel(le_bytes, 5);
}

} // verus!
24 changes: 19 additions & 5 deletions crates/clazel-x64/src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,8 +1,22 @@
//! The x86-64 instruction-set subset the JIT emits (docs/phases/jit.md item J.3).
//!
//! Empty for now: item J.2 only creates the crate, so that the instruction-set
//! sources (`tests/data/`) have a home. The spec (semantics as a `spec fn`)
//! and its contracts come first (CLAUDE.md rule 3), then the encoder and
//! decoder.
//! This is the first half of item J.3: the primary spec, written before any
//! encoder or decoder (CLAUDE.md rule 3).
//!
//! Tier: see `[package.metadata.clazel]` in `Cargo.toml` and `docs/VERIFICATION.md`.
//! - [`spec`]: the **primary transcription**, from the ACL2 `x86isa` model
//! (`tests/data/acl2-x86isa`): the machine state, the semantics of every
//! instruction of the subset, and the canonical encoding.
//!
//! - [`contract`]: what the encoder and decoder must be proven to satisfy.
//! - [`api`]: the contract-only trait [`api::X64Codec`] (no implementation).
//!
//! The independent transcription, from Intel's SDM, is written by another
//! session that does not read [`spec`]; it is not here yet.
//!
//! Tier: see `[package.metadata.clazel]` in `Cargo.toml` and
//! `docs/VERIFICATION.md`.

pub mod api;
pub mod contract;
pub mod examples;
pub mod spec;
Loading
Loading