Skip to main content

Crate exarmo_aarch64

Crate exarmo_aarch64 

Source
Expand description

§exarmo-aarch64

An AArch64 disassembler, generated from Arm’s machine-readable A64 ISA specification. It decodes every instruction the specification describes, including Advanced SIMD, floating-point, SVE, SME and the Future Architecture Technologies extensions.

This version is generated from Arm’s 2026-09 release of the specification.

cargo add exarmo-aarch64
// nop
let instruction = exarmo_aarch64::decode_bytes(&[0x1f, 0x20, 0x03, 0xd5]).unwrap();
assert_eq!(instruction.at(0x1000).to_string(), "nop");

decode_bytes decodes an instruction from a byte slice, and decode_word from a 32-bit instruction word. disassemble returns an iterator over the instructions in a byte buffer. Each instruction is an Instruction, which holds no address. at gives it one, for the text and for anything PC-relative. An instruction also gives:

  • its encoding and mnemonic, as fieldless enums to switch on
  • its operands, as a positional view a consumer can read without matching on every encoding
  • its text as a token stream, each token with its kind and the operand it belongs to, for syntax highlighting
  • the condition flags it reads and writes, and what it does to the flow of control
  • whether the word is CONSTRAINED UNPREDICTABLE
  • the ACLE Advanced SIMD intrinsics it implements

exarmo-aarch64-capi provides a C API around this crate. exarmo-cli provides a command-line disassembler built on this crate and exarmo-aarch32.

§Crate features

The crate is #![no_std]. Its default alloc feature can be turned off for use in an environment without an allocator. That removes Token and the TokenSink impls for Vec<Token> and String.

§Examples

§Decoding

disassemble returns an iterator over the instructions in a byte buffer and their addresses. decode_bytes decodes one instruction from a byte slice, and decode_word one from a 32-bit word. For a word that is not an instruction, each returns a DecodeError that says why.

use exarmo_aarch64::{DecodeError, decode_word, disassemble};

// str x0, [sp, #-16]!
// ldr x0, [sp], #16
let code = [0xe0, 0x0f, 0x1f, 0xf8, 0xe0, 0x07, 0x41, 0xf8];
let text: Vec<_> = disassemble(&code, 0x1000)
    .map(|(address, instruction)| instruction.unwrap().at(address).to_string())
    .collect();
assert_eq!(text, ["str\tx0, [sp, #-0x10]!", "ldr\tx0, [sp], #0x10"]);

// No row of the exception generation class allocates this word.
assert_eq!(decode_word(0xd478da60), Err(DecodeError::Unallocated));

§What an instruction is

An Instruction is an enum with a variant for every encoding and alias the specification describes. Each variant holds the fields of its encoding. For example, cset x0, eq decodes to CsetCsinc64Condsel. Its Xd field is an XRegZr, a 64-bit register where 31 is the zero register. Its invcond field holds ne, the inverse of the condition the assembly writes.

There are thousands of variants, so most code does not match on them. Instruction::encoding returns the variant as an Encoding, a fieldless enum with a name for each. Instruction::mnemonic returns a Mnemonic, which many encodings share. Instruction::operands, below, reads the operands of any variant in one shape.

use exarmo_aarch64::{Encoding, Instruction, Mnemonic, decode_word};

// cset x0, eq
let cset = decode_word(0x9a9f17e0).unwrap();
let Instruction::CsetCsinc64Condsel { Xd, .. } = cset else {
    unreachable!()
};
assert_eq!(Xd.num(), 0);

assert_eq!(cset.encoding(), Encoding::CsetCsinc64Condsel);
assert_eq!(cset.encoding().name(), "CsetCsinc64Condsel");
assert_eq!(cset.mnemonic(), Mnemonic::Cset);
assert_eq!(cset.mnemonic().name(), "cset");

§Operands

Instruction::operands gives the operands in the order the assembly writes them, each an Operand. A memory operand is a single value that holds its base, offset and writeback.

use exarmo_aarch64::{
    Mem, Offset, Operand, Reg, RegOperand, Writeback, XRegSp, XRegZr, decode_word,
};

// str x0, [sp, #-16]!
let str = decode_word(0xf81f0fe0).unwrap();
assert_eq!(
    str.operands().as_slice(),
    [
        Operand::Reg(RegOperand::plain(Reg::X(XRegZr::new(0)))),
        Operand::Mem(Mem {
            base: Reg::XSp(XRegSp::new(31)),
            base_arrangement: None,
            offset: Offset::Imm { value: -16, mul_vl: false },
            writeback: Writeback::Pre,
        }),
    ]
);

A condition operand holds the condition as the assembly writes it. The field of cset x0, eq holds ne, and its operand is eq.

use exarmo_aarch64::{Cond, Operand, decode_word};

// cset x0, eq
let cset = decode_word(0x9a9f17e0).unwrap();
assert_eq!(cset.operands()[1], Operand::Cond(Cond::Eq));

§Tokens

InstructionAt::write_tokens writes the text to a TokenSink as tokens, each with its TokenKind and the index of the operand it is part of. Number tokens carry their values, so you never need to parse the text. The tokens module shows how to write your own sink.

use exarmo_aarch64::{Token, TokenKind, decode_word};

// ldr x0, [x1, #8]
let mut tokens: Vec<Token> = Vec::new();
decode_word(0xf9400420).unwrap().at(0).write_tokens(&mut tokens).unwrap();

let kinds: Vec<_> = tokens.iter().map(|t| (t.kind, t.operand, t.text.as_str())).collect();
assert_eq!(
    kinds,
    [
        (TokenKind::Mnemonic, None, "ldr"),
        (TokenKind::Text, None, "\t"),
        (TokenKind::Register, Some(0), "x0"),
        (TokenKind::Separator, None, ", "),
        (TokenKind::Bracket, Some(1), "["),
        (TokenKind::Register, Some(1), "x1"),
        (TokenKind::Text, Some(1), ", "),
        (TokenKind::Text, Some(1), "#"),
        (TokenKind::Immediate(8), Some(1), "0x8"),
        (TokenKind::Bracket, Some(1), "]"),
    ]
);

§Flags and control flow

Instruction::flags returns the condition flags an instruction writes and reads. InstructionAt::branch returns what it does to the flow of control, and for a direct branch, the address it branches to.

use exarmo_aarch64::{BranchKind, Flags, decode_word};

// cmp x0, #0x41
let cmp = decode_word(0xf101041f).unwrap();
assert_eq!(cmp.flags().writes, Flags::NZCV);
assert!(cmp.flags().reads.is_empty());

// b.ne #12
let branch = decode_word(0x54000061).unwrap().at(0x1000).branch();
assert_eq!(branch.kind, BranchKind::Direct);
assert!(branch.conditional);
assert_eq!(branch.target, Some(0x100c));

// bl #64
let call = decode_word(0x94000010).unwrap().at(0x1000).branch();
assert_eq!(call.kind, BranchKind::DirectCall);
assert_eq!(call.target, Some(0x1040));

// ret
let ret = decode_word(0xd65f03c0).unwrap().at(0x1000).branch();
assert_eq!(ret.kind, BranchKind::Return);
assert_eq!(ret.target, None);

§CONSTRAINED UNPREDICTABLE words

For some words, the architecture permits the processor to execute the instruction or to do something else. Decoding one of these words returns the instruction, and Instruction::unpredictable returns true for it.

use exarmo_aarch64::decode_word;

// rcwsetp x0, x0, [sp], which names x0 for both registers of its pair
let rcwsetp = decode_word(0x1920b3e0).unwrap();
assert_eq!(rcwsetp.at(0).to_string(), "rcwsetp\tx0, x0, [sp]");
assert!(rcwsetp.unpredictable());

§System registers and operations

MRS and MSR take a SysReg operand, which gives the register’s name where the architecture has one. AT, DC, IC and TLBI take a system operation, and MSR (immediate) a PSTATE field. Their operands refer to rows of SysOp::all.

use exarmo_aarch64::{Mnemonic, Operand, decode_word};

// msr vbar_el3, x0
let Operand::SysReg(register) = decode_word(0xd51ec000).unwrap().operands()[0] else {
    unreachable!()
};
assert_eq!(register.name(), Some("vbar_el3"));
assert!(register.is_write());

// ic iallu
let Operand::SysOp(operation) = decode_word(0xd508751f).unwrap().operands()[0] else {
    unreachable!()
};
assert_eq!(operation.def().name, "iallu");
assert_eq!(operation.def().instruction, Mnemonic::Ic);

§Intrinsics

Instruction::intrinsics lists the ACLE Advanced SIMD intrinsics an instruction implements, and binds each argument to one of the instruction’s operands.

use exarmo_aarch64::{Output, Source, decode_word};

// addp v0.8b, v1.8b, v0.8b
let addp = decode_word(0x0e20bc20).unwrap();
let vpadd = addp.intrinsics().iter().find(|i| i.name() == "vpadd_s8").unwrap();
assert_eq!(vpadd.arguments, [Source::Operand(1), Source::Operand(2)]);
assert_eq!(vpadd.result, Output::Operand(0));

Re-exports§

pub use sysops::RegisterAccess;
pub use sysops::RegisterUse;
pub use sysops::SysOp;
pub use sysops::SysOpRef;
pub use generated::Encoding;
pub use generated::Instruction;
pub use generated::InstructionAt;
pub use generated::Mnemonic;
pub use generated::ModifierKind;
pub use generated::PROVENANCE;
pub use generated::Provenance;
pub use generated::decode_word;
pub use intrinsics::Intrinsic;
pub use intrinsics::IntrinsicDef;
pub use intrinsics::IntrinsicType;
pub use intrinsics::IntrinsicTypeDef;
pub use intrinsics::Output;
pub use intrinsics::Source;
pub use intrinsics::TypeKind;
pub use operands::Mem;
pub use operands::Modifier;
pub use operands::Offset;
pub use operands::Operand;
pub use operands::Operands;
pub use operands::Reg;
pub use operands::RegList;
pub use operands::RegOperand;
pub use operands::ZaArray;
pub use operands::ZaSlice;
pub use generated::enums::*;

Modules§

generated
The decoder, instruction model and tables generated from ARM’s XML. Generated code for AArch64 instruction decoding.
intrinsics
The ACLE intrinsics an instruction realises.
operands
An instruction’s operands, seen without matching on its variant.
rendering
Writing an instruction from its operands view.
sysops
The system operations and PSTATE fields the architecture names.
tokens
An instruction rendered as tokens.

Structs§

Arrangement
How many lanes of what width a vector operand holds.
BReg
8-bit SIMD/FP scalar register (b0-b31).
Branch
A BranchEffect resolved at an address.
BranchEffect
What an instruction does to the flow of control, apart from any address.
DReg
64-bit SIMD/FP scalar register (d0-d31).
FlagEffect
What an instruction does with the condition flags, read from its Execute pseudocode.
Flags
A set of the condition flags N, Z, C and V.
GpReg
A general-purpose register whose width the instruction does not fix.
HReg
16-bit SIMD/FP scalar register (h0-h31).
Hex
A number written in hex with its 0x.
PNReg
SVE predicate-as-counter register (pn0-pn15).
PReg
SVE predicate register (p0-p15).
PcRead
How an instruction reads the PC for a label. The architecture reads the PC ahead of the instruction, and a literal load or a page-relative address aligns it down first.
QReg
128-bit SIMD/FP vector register (q0-q31).
SReg
32-bit SIMD/FP scalar register (s0-s31).
Symbol
A value from a value table, such as a shift, an extend, a barrier option or a data type, as its bits and its name.
SysReg
A system register operand of MRS/MSR, holding its op0:op1:CRn:CRm:op2 encoding and the direction of the access.
SysRegDef
A system register the architecture names.
Tokenalloc
A token as the Vec<Token> sink records it.
VReg
128-bit SIMD vector register (v0-v31).
WRegSp
A 32-bit W register where register 31 is WSP, the stack pointer.
WRegZr
A 32-bit W register where register 31 is WZR, the zero register.
XRegSp
A 64-bit X register where register 31 is SP, the stack pointer.
XRegZr
A 64-bit X register where register 31 is XZR, the zero register.
ZATile
SME ZA tile register (za0-za15).
ZReg
SVE scalable vector register (z0-z31).
ZaTileMask
The set of ZA tiles an instruction names, one per bit.
ZaTileName
One tile’s name as ZERO writes it: za, or za<n>.<size>.

Enums§

BranchKind
What kind of branch an instruction takes.
DecodeError
Why a word decoded to no instruction, or why bytes held none.
DynRegSp
A general-purpose register whose width another field chooses, with register 31 the stack pointer. The assembly writes it <R><n|SP>, as SVE’s DUP and CPY do.
DynRegZr
A general-purpose register whose width another field chooses, such as TBZ’s b5, with register 31 the zero register.
DynScalarSimd
A scalar SIMD and floating-point register whose width a size field chooses, as a template’s <V><d> writes it.
ElementWidth
The width of one lane of a vector, as the architecture letters it.
TokenKind
What a token is.
Writeback
Whether and how a memory operand writes its base back.

Traits§

Decoded
A decoded instruction, whichever instruction set read it.
TokenSink
Where the formatter writes its tokens.

Functions§

decodeDeprecated
Decode the 32-bit AArch64 instruction word bits.
decode_bytes
Decode the little-endian instruction in the first four bytes of bytes.
disassemble
Decode each instruction of bytes, the first of which is at address.