1Extending the disassembler
2==========================
3
4The output of the disassembler can be extended and customized. This may be
5useful for example to add comments and annotations to the disassembly, print
6aliases for register names, or add an offset to disassembled addresses.
7
8The general procedure to achieve this is to create a sub-class of
9`Disassembler` and override the appropriate virtual functions.
10
11The `Disassembler` class provides virtual methods that implement how specific
12disassembly elements are printed. See
13[src/a64/disasm-a64.h](/src/a64/disasm-a64.h) for details. These include
14functions like:
15
16    virtual void AppendRegisterNameToOutput(const Instruction* instr,
17                                            const CPURegister& reg);
18    virtual void AppendPCRelativeOffsetToOutput(const Instruction* instr,
19                                                int64_t offset);
20    virtual void AppendCodeRelativeAddressToOutput(const Instruction* instr,
21                                                   const void* addr);
22    virtual void AppendCodeRelativeCodeAddressToOutput(const Instruction* instr,
23                                                       const void* addr);
24
25They can be overridden for example to use different register names and annotate
26code addresses.
27
28More complex modifications can be performed by overriding the visitor functions
29of the disassembler. The VIXL `Decoder` uses a visitor pattern implementation,
30so the `Disassembler` (as a sub-class of `DecoderVisitor`) must provide a
31visitor function for each sub-type of instructions. The complete list of
32visitors is defined by the macro `VISITOR_LIST` in
33[src/a64/decoder-a64.h](/src/a64/decoder-a64.h).
34
35The [/examples/custom-disassembler.h](/examples/custom-disassembler.h) and
36[/examples/custom-disassembler.cc](/examples/custom-disassembler.cc) example
37files show how the methods can be overridden to use different register names,
38map code addresses, annotate code addresses, and add comments:
39
40    VIXL disasm  0x7fff04cb05e0:  add x10, x16, x17
41    custom disasm -0x8: add x10, ip0, ip1 // add/sub to x10
42
43    VIXL disasm  0x7fff04cb05e4:  cbz x10, #+0x28 (addr  0x7fff04cb060c)
44    custom disasm -0x4: cbz x10, #+0x28 (addr  0x24 ; label: somewhere)
45
46    VIXL disasm  0x7fff04cb05e8:  add x11, x16, x17
47    custom disasm  0x0: add x11, ip0, ip1
48
49    VIXL disasm  0x7fff04cb05ec:  add w5, w6, w30
50    custom disasm  0x4: add w5, w6, w30
51
52    VIXL disasm  0x7fff04cb05f0:  tbz w10, #2, #-0x10 (addr  0x7fff04cb05e0)
53    custom disasm  0x8: tbz w10, #2, #-0x10 (addr -0x8)
54
55
56One can refer to the implementation of visitor functions for the `Disassembler`
57(in [src/a64/disasm-a64.cc](/src/a64/disasm-a64.cc)) or even for the `Simulator`
58(in [src/a64/simulator-a64.cc](/src/a64/simulator-a64.cc)) to see how to extract
59information from instructions.
60