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
BranchEffectresolved at an address. - Branch
Effect - What an instruction does to the flow of control, apart from any address.
- DReg
- 64-bit SIMD/FP scalar register (d0-d31).
- Flag
Effect - 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:op2encoding and the direction of the access. - SysReg
Def - A system register the architecture names.
- Token
alloc - 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).
- ZaTile
Mask - The set of ZA tiles an instruction names, one per bit.
- ZaTile
Name - One tile’s name as ZERO writes it:
za, orza<n>.<size>.
Enums§
- Branch
Kind - What kind of branch an instruction takes.
- Decode
Error - Why a word decoded to no instruction, or why bytes held none.
- DynReg
Sp - 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. - DynReg
Zr - A general-purpose register whose width another field chooses, such as
TBZ’s
b5, with register 31 the zero register. - DynScalar
Simd - A scalar SIMD and floating-point register whose width a size field
chooses, as a template’s
<V><d>writes it. - Element
Width - The width of one lane of a vector, as the architecture letters it.
- Token
Kind - 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.
- Token
Sink - Where the formatter writes its tokens.
Functions§
- decode
Deprecated - 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 ataddress.