1# `cranelift-assembler-x64-meta`
2
3This crate generates Cranelift-specific assembly code for x64 instructions. It
4is designed to fit in with Cranelift-specific logic (e.g., register allocation)
5and only needs to define the x64 instructions Cranelift emits. It is written in
6the style of `cranelift-codegen-meta` and _could_ be migrated there (though not
7necessarily).
8
9### Structure
10
11- [`dsl.rs`](src/dsl.rs): defines a domain-specific language (DSL) for
12  describing x64 instructions; this language is intended to be compact--i.e.,
13  define an x64 instruction on a single line--and a close-to-direct mapping of
14  what we read in the x64 developer manual
15- [`instructions.rs`](src/instructions.rs): defines x64 instructions using the
16  DSL; add new instructions here
17- [`generate.rs`](src/generate.rs): generates Rust code from the defined
18  instructions to: assemble machine code, pretty-print, register-allocate.
19
20### Use
21
22This is primarily intended to be used for generating Rust code, i.e.,
23`generate_rust_assembler("some-file.rs")`. It also has the ability to print
24a list of the defined instructions:
25
26```console
27$ cargo run
28andb: I(al, imm8) => 0x24 ib
29andw: I(ax, imm16) => 0x25 iw
30andl: I(eax, imm32) => 0x25 id
31...
32```
33
34### Troubleshooting
35
36When something goes wrong, it can be helpful to compare the output of this
37assembler with a known-good disassembler like XED.
38
39When testing finds a miscompilation, it prints the emitted bytes. To use XED to
40disassemble this:
41
42```
43$ <path to xed>/obj/wkit/bin/xed -d 4080
44```
45
46To generate the expected bytes:
47
48```
49$ <path to xed>/obj/wkit/bin/xed -64 -A -e AND bpl IMM:48
50```
51
52XED also documents its CLI interface: [Intel XED command
53interface](https://intelxed.github.io/ref-manual/group__CMDLINE.html).
54