#assembly #cranelift #x86-64 #instructions

build cranelift-assembler-x64-meta

Generate a Cranelift-specific assembler for x64 instructions

5 unstable releases

new 0.119.0 Apr 21, 2025
0.118.0 Mar 20, 2025
0.117.2 Feb 25, 2025
0.117.1 Feb 21, 2025
0.117.0 Feb 20, 2025

#145 in Programming languages

Download history 920/week @ 2025-02-14 10112/week @ 2025-02-21 16926/week @ 2025-02-28 16677/week @ 2025-03-07 20572/week @ 2025-03-14 16466/week @ 2025-03-21 31373/week @ 2025-03-28 51190/week @ 2025-04-04 28915/week @ 2025-04-11 37223/week @ 2025-04-18

151,433 downloads per month
Used in 69 crates (2 directly)

Apache-2.0 WITH LLVM-exception

96KB
1.5K SLoC

cranelift-assembler-x64-meta

This crate generates Cranelift-specific assembly code for x64 instructions. It is designed to fit in with Cranelift-specific logic (e.g., register allocation) and only needs to define the x64 instructions Cranelift emits. It is written in the style of cranelift-codegen-meta and could be migrated there (though not necessarily).

Structure

  • dsl.rs: defines a domain-specific language (DSL) for describing x64 instructions; this language is intended to be compact--i.e., define an x64 instruction on a single line--and a close-to-direct mapping of what we read in the x64 developer manual
  • instructions.rs: defines x64 instructions using the DSL; add new instructions here
  • generate.rs: generates Rust code from the defined instructions to: assemble machine code, pretty-print, register-allocate.

Use

This is primarily intended to be used for generating Rust code, i.e., generate_rust_assembler("some-file.rs"). It also has the ability to print a list of the defined instructions:

$ cargo run
andb: I(al, imm8) => 0x24 ib
andw: I(ax, imm16) => 0x25 iw
andl: I(eax, imm32) => 0x25 id
...

Troubleshooting

When something goes wrong, it can be helpful to compare the output of this assembler with a known-good disassembler like XED.

When testing finds a miscompilation, it prints the emitted bytes. To use XED to disassemble this:

$ <path to xed>/obj/wkit/bin/xed -d 4080

To generate the expected bytes:

$ <path to xed>/obj/wkit/bin/xed -64 -A -e AND bpl IMM:48

XED also documents its CLI interface: Intel XED command interface.

Dependencies