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
85 changes: 85 additions & 0 deletions Cargo.lock

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

3 changes: 3 additions & 0 deletions crates/clazel-a64/.gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Vendored data is compared byte for byte (see the root attributes file); the
# upstream files' line endings are part of what they test.
tests/data/** -text
25 changes: 25 additions & 0 deletions crates/clazel-a64/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
[package]
name = "clazel-a64"
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."

# 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.

# 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).
[package.metadata.clazel]
tier = 0
target-tier = 2

[lints]
workspace = true

[dev-dependencies]
yaxpeax-arm = { version = "=0.5.0", default-features = false, features = ["fmt"] }
yaxpeax-arch = { version = "=0.3.3", default-features = false }
43 changes: 43 additions & 0 deletions crates/clazel-a64/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# clazel-a64

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
pinned the sources the semantics will be written against, in `tests/data/`:

| Suite | What | Held as |
|---|---|---|
| `sail-arm` | the Sail Armv9.4-A model: A64 base instructions and shared pseudocode (BSD-3-Clause-Clear) | 3.9 MB, vendored |
| `arm-mrs` | Arm's machine-readable specification, 2026-09 release (BSD-3-Clause) | licence and README vendored; `Instructions.json` (116,678,333 bytes) pinned by SHA-256 |
| `arm-arm` | Arm Architecture Reference Manual for A-profile (DDI 0487), issue M.d | pinned by URL, size (129,014,701 bytes) and SHA-256, not vendored (Arm's terms forbid copying) |

Each has a `SOURCE.md` with the upstream, the commit (or the SHA-256) and the
licence. The tables in `tests/generated/` list every file's size and hash.

## Where the transcriptions come from

Decided by the user on 2026-11-16 (jit.md, the note under J.4):

- The **primary spec** is transcribed from the Sail Arm model and Arm's ASL.
- The **independent transcription** is made from the Arm Architecture
Reference Manual's prose, by a **different session** that does not read the
primary transcription.
- The **hardware differential tests** on the macOS runner (exit criterion 3)
are the further check against both.

## The two formal A64 sources are one source

The Sail Arm model's README says its Sail files "are derived from the 2023-03
version of Arm's ASL specification using the automatic ASL-to-Sail
translation tool". Arm's machine-readable specification (`Instructions.json`)
carries the same ASL as the operation of each instruction. So the two are one
source in two syntaxes (the Sail model is from the 2023-03 ASL, the JSON from
2026-09), and they share Arm's own errors, if any. That is why the second
transcription comes from the manual's prose.

The `arm-mrs` JSON is also the only machine-readable encoding table
(`Instructions.json` has every encoding with its fixed and variable bits), so
the decoder differential against `yaxpeax-arm` can be checked against it as
well.
8 changes: 8 additions & 0 deletions crates/clazel-a64/src/lib.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
//! The A64 (64-bit Arm) instruction-set subset the JIT emits (docs/phases/jit.md item J.4).
//!
//! 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.
//!
//! Tier: see `[package.metadata.clazel]` in `Cargo.toml` and `docs/VERIFICATION.md`.
17 changes: 17 additions & 0 deletions crates/clazel-a64/tests/data/arm-arm/LICENSE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Licence of the Arm Architecture Reference Manual

None granted for redistribution. The Arm Architecture Reference Manual for
A-profile architecture (DDI 0487) is Arm Limited's copyright and is published
under Arm's documentation terms, not under an open licence. Arm's website
terms (https://www.arm.com/company/policies/terms-and-conditions, read on
2026-11-16) forbid reproducing or copying its content without express written
permission, and allow a personal reference copy only. We found no grant to
redistribute the manual. Arm's own machine-readable specification, a different
product, is BSD-3-Clause (`../arm-mrs/`). The PDF is therefore not vendored:
`SOURCE.md` pins it by URL, size and SHA-256.

The proprietary notice inside the PDF was not read (the 129 MB file was read
only for its hash); a person should read it before anyone proposes vendoring
any part of the document.

This file is a statement of that decision, not a copy of a licence.
34 changes: 34 additions & 0 deletions crates/clazel-a64/tests/data/arm-arm/SOURCE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Arm Architecture Reference Manual for A-profile architecture (DDI 0487), issue M.d, pinned and not vendored

Upstream: https://documentation-service.arm.com/static/6abbec2a6db85c5e6614a4a1
SHA-256: 80d589a4645feba6bdb9d77edfaf04d4394d5d5444a4c41f97cf4fdd20eee3d5 DDI0487M_d_a-profile_architecture_reference_manual.pdf
Size: 129014701 DDI0487M_d_a-profile_architecture_reference_manual.pdf
License: Arm copyright, proprietary notice, no licence to redistribute. See `LICENSE.md`.

The file is what Arm's own documentation service serves for DDI 0487 "latest"
on 2026-11-16: its API
(`https://documentation-service.arm.com/documentation/ddi0487/latest`) names
version label **M.d** (document quality "EAC", Arm's early-access label for a
release not yet final) and lists this PDF as the resource
`DDI0487M_d_a-profile_architecture_reference_manual.pdf`. The human-facing
page is https://developer.arm.com/documentation/ddi0487/latest, which
redirects to support.arm.com and is a script-driven page that a plain client
cannot read; the `static/` URL above is the one the API gave, fetched without
its `token` query parameter, and it returned the PDF (`%PDF-1.7`, 129,014,701
bytes, 129 MB).

This is the source of the independent A64 transcription of jit.md item J.4:
the instruction pages (Part C, "The A64 Instruction Set") give each
instruction's encoding and its pseudocode, and Part B gives the application
level model. Pinned Arm ARM issues change: when Arm publishes M.e or a final
M.d, the hash no longer matches and a person must repin after reading the
change list.

The PDF is not in this repository: it is far over the size budget (129 MB),
and Arm's documents carry a proprietary notice with no right to redistribute
(`LICENSE.md`). Nothing was checked against a mirror. The `static/` URL is
Arm's own host, but it is an opaque document id, and Arm may withdraw it when
it replaces the issue; if so, repin from the page above.

`xtask/src/testdata/isa.rs` writes `tests/generated/arm_arm.rs`, the table of
this pin.
31 changes: 31 additions & 0 deletions crates/clazel-a64/tests/data/arm-mrs/LICENSE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Licence of Arm's AARCHMRS open-source package

Transcribed from `docs/notice.html` of the package (ARM Machine Readable
Schema 2.9.6; the original is `notice.html` beside this file).

Copyright 2010-2026 Arm Limited or its affiliates.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.

Neither the name of the copyright holder nor the names of its contributors may
be used to endorse or promote products derived from this software without
specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 changes: 30 additions & 0 deletions crates/clazel-a64/tests/data/arm-mrs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# AARCHMRS containing the JSON files for A-profile Architecture

## Introduction

This is the Arm Architecture Machine Readable Specification containing
JSON files representing the architecture as a machine readable format.

This package contains a subset of the information provided in the packages
with Arm proprietary licenses. Content that is not currently in a machine-readable
format, as well as all descriptive content, is omitted.

The [notice](docs/notice.html) gives details of the license terms and conditions
under which this package is provided.

## Package contents

- `Features.json` contains the architecture feature constraints.
- `Instructions.json` contains the A64, A32, and T32 Instruction Set Architecture.
- `Registers.json` contains the AArch32, AArch64, and MemoryMapped
System Registers and System instructions.
- [`schema`](schema/) contains JSON schema for the data.
- [`docs`](docs/index.html) contains the rendered view of the schema
as well as user guides to help understand the data above.

## Package quality

- The architectural content contained within the data files has the same quality
as the equivalent XML releases.
- The schema is still under development and is subject to change.

30 changes: 30 additions & 0 deletions crates/clazel-a64/tests/data/arm-mrs/SOURCE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Arm's open-source machine-readable specification of the A-profile architecture (README and licence vendored, Instructions.json pinned)

Upstream: https://kernel.googlesource.com/pub/scm/linux/kernel/git/maz/AARCHMRS/+/1346b16d47619400448f3cb6d4f22d62d3b76848
Commit: 1346b16d47619400448f3cb6d4f22d62d3b76848
SHA-256: ef75f3ec02df1b9b9c0612f4ea259d6710ac3de686b097d8f9c83d1d97aa800a Instructions.json
Size: 116678333 Instructions.json
License: BSD-3-Clause (Arm Limited), as stated in `notice.html` (the package's own notice; `LICENSE.md` is its text). Redistribution is allowed.

Arm publishes the package as `AARCHMRS_OPENSOURCE_A_profile_FAT-2026-09` on its
developer site (the "Exploration Tools" page of the A-profile architecture; the
site redirected our client to support.arm.com and was not fetched). The commit
above is a mirror of that release in a git repository (Marc Zyngier's
AARCHMRS repository at kernel.googlesource.com, whose commit message is the
release name, 2026-10-15). The mirror is third-party: a person should compare
its hashes with the tarball from Arm's site before relying on it.

Vendored, byte for byte: `README.md` and `notice.html` (the licence; schema
2.9.6).

**`Instructions.json` is pinned, not vendored.** It holds the A64, A32 and T32
instruction sets with their encodings and their ASL operations, and it is
116,678,333 bytes (116 MB), far over this suite's size budget, and it cannot
be cut to the A64 base instructions without rewriting it. The pin above is
the SHA-256 of the file as stored in the commit (LF line endings). A reader
(jit.md item J.4) fetches the commit, takes `Instructions.json` and checks the
hash. `Features.json` and `Registers.json` are not needed for the subset.

`xtask/src/testdata/isa.rs` writes `tests/generated/arm_mrs.rs`, the inventory
of the two vendored files and the table of the pin. Nothing reads the
specification yet. The Sail model derived from the same ASL is `sail-arm`.
Loading
Loading