Skip to content

JIT J.2: pin the x86-64 and A64 instruction-set sources - #179

Open
atiernan wants to merge 13 commits into
claude/js-vm-specfrom
claude/jit-isa-sources
Open

atiernan wants to merge 13 commits into
claude/js-vm-specfrom
claude/jit-isa-sources

Conversation

@atiernan

@atiernan atiernan commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

JIT plan item J.2, test data: the instruction-set sources that J.3 (clazel-x64) and J.4 (clazel-a64) are transcribed from, plus test-only reference disassemblers. There is no implementation yet.

Stacked on #176. Merge that PR first, or retarget this one to main afterwards.

New crates

clazel-x64 and clazel-a64 are empty: Primitive, tier 0, target tier 2.

Sources

Suite Pin Held as
acl2-x86isa acl2/acl2 33b05575, books/projects/x86isa subset vendored, 2.6 MB, BSD-3
acl2-rtl acl2/acl2 33b05575, Russinoff's RTL library (books/rtl/rel11: lib/ and the package), which the x86isa SSE books call vendored, 0.3 MB, BSD-3
sail-x86-from-acl2 rems-project 0c6c023d vendored, 0.8 MB, BSD-3/BSD-2
intel-sdm Intel SDM vol. 2, by URL, size and SHA-256 not vendored: Intel's terms forbid redistribution
sail-arm rems-project/sail-arm 5416ef6b, arm-v9.4-a subset vendored, 3.9 MB, BSD-3-Clause-Clear
arm-mrs Arm machine-readable spec Instructions.json, release FAT-2026-09, by SHA-256 not vendored: 117 MB
arm-arm Arm ARM DDI 0487 M.d, by URL, size and SHA-256 not vendored: Arm's terms forbid copying

Each suite has a SOURCE.md and licence, and an xtask inventory table (path, size, SHA-256) in xtask/src/testdata/isa.rs.

Decision recorded in docs/phases/jit.md

The maintainer made this decision on 2026-11-16, because the formal sources turned out not to be independent:

  • x86-64: Sail x86 is an automatic translation of ACL2 x86isa.
  • A64: Sail Arm is a translation of Arm's ASL, which is the same data as the machine-readable spec.

What the plan now says:

  • x86-64: the primary spec comes from ACL2 x86isa, and the independent transcription from the Intel SDM's prose and pseudocode. The Sail x86 translation is kept only as a check on our reading of ACL2.
  • A64: the primary spec comes from Sail Arm and ASL, and the independent transcription from the Arm ARM's prose.
  • For both: a different session writes the independent transcription without reading the primary one. The hardware differential tests check both.
  • Rejected: shina-lab/sail-x86 was considered and rejected: single author, unreviewed, floating point left external.

Test dependencies

Every new package has a test row in docs/DEPENDENCIES.md, and the allowlist is now 232 packages.

  • yaxpeax-x86 =2.2.1, used without features. It replaced iced-x86 1.22.0, whose decoder Miri reports as undefined behaviour under Stacked Borrows.
  • yaxpeax-arm =0.5.0 and yaxpeax-arch =0.3.3, with bitvec, funty, radium, tap and wyz.

For a human to check

  • The Arm ARM pin is the early-access issue M.d ("EAC"). Its URL uses an opaque id Arm may withdraw. Pinning the newest final issue may be better.
  • The arm-mrs hash was taken from the kernel.googlesource.com mirror. It should be compared with Arm's own tarball.
  • The ACL2 and Sail subsets were picked by file name. J.3 and J.4 may need more files.
  • The proposed benchmark set is Octane 2.0's compute-bound part, pinned in jit.md. The JIT-off numbers wait for an engine.

Verification

  • cargo xtask testdata: TEST DATA UP TO DATE. cargo xtask check: STATIC CHECKS PASSED.
  • cargo test -p xtask -p clazel-x64 -p clazel-a64 passes, and clippy is clean.
  • cargo xtask verify --changed was not run locally, because the new crates change Cargo.lock. CI's full verification is the check, and its proof jobs need approval.

🤖 Generated with Claude Code

atiernan and others added 5 commits November 16, 2026 14:35
…set sources (J.2)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Inventories for the vendored trees, and a table of pins for files that are
named but not held.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…a64 (J.2)

ACL2 x86isa, the Sail x86 models, Sail Arm and Arm's machine-readable
specification, each with SOURCE.md and licence; the Intel SDM and Arm's
Instructions.json pinned by SHA-256. The READMEs record that the Sail x86
model is a translation of the ACL2 one and the Sail Arm model derives from
Arm's ASL.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…s and benchmark proposal

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…pin the Arm ARM (J.2)

The second transcriptions come from the vendors' manuals (Intel SDM,
Arm ARM) written by a different session; the Sail x86 translation is only a
check on our reading of ACL2. shina-lab/sail-x86 is removed (single author,
unreviewed, floating point external). The Arm Architecture Reference Manual
issue M.d is pinned by URL, size and SHA-256, not vendored.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The J.3 transcription found the floating-point instructions defined with
Russinoff's RTL library (books/rtl/rel11/lib), and ucomisd in
machine/instructions/fp/logical.lisp, neither of which J.2 vendored. Both
come from the same acl2/acl2 commit, 33b05575. The library is a new suite,
acl2-rtl (0.3 MB, BSD-3-Clause), since its paths are relative to
books/rtl/rel11, not books/projects/x86isa.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
atiernan and others added 2 commits November 16, 2026 23:12
…h forbids file access

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Miri (Stacked Borrows) reports undefined behaviour in iced-x86 1.22.0's
decoder (decoder/handlers/legacy.rs:2006), which failed CI's Miri job.
yaxpeax-x86 2.2.1 (0BSD) passes the same tests under Miri. It is used
without features: its std would turn on yaxpeax-arch's, which yaxpeax-arm
0.5.0 does not build with. iced-x86 and lazy_static leave the allowlist;
yaxpeax-x86 joins it, and its other dependencies are already listed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@atiernan
atiernan changed the base branch from claude/js-jit-compiler-next-21ddc8 to claude/js-vm-spec November 17, 2026 13:11
@atiernan
atiernan added this pull request to stack #188 November 17, 2026 13:11
@atiernan
atiernan temporarily deployed to full-verification November 18, 2026 13:59 — with GitHub Actions Inactive

This branch is being deployed

1 queued deployment
full-verification — 5a481b93 Deployed Nov 20, 2026 by atiernan via Approve the proofs #615
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.

1 participant