| # LLVM's Optional Rich Disassembly Output | |
| ## Introduction | |
| LLVM's default disassembly output is raw text. To allow consumers more ability | |
| to introspect the instructions' textual representation or to reformat for a more | |
| user friendly display there is an optional rich disassembly output. | |
| This optional output is sufficient to reference into individual portions of the | |
| instruction text. This is intended for clients like disassemblers, list file | |
| generators, and pretty-printers, which need more than the raw instructions and | |
| the ability to print them. | |
| To provide this functionality the assembly text is marked up with annotations. | |
| The markup is simple enough in syntax to be robust even in the case of version | |
| mismatches between consumers and producers. That is, the syntax generally does | |
| not carry semantics beyond "this text has an annotation," so consumers can | |
| simply ignore annotations they do not understand or do not care about. | |
| After calling `LLVMCreateDisasm()` to create a disassembler context the | |
| optional output is enable with this call: | |
| ```c | |
| LLVMSetDisasmOptions(DC, LLVMDisassembler_Option_UseMarkup); | |
| ``` | |
| Then subsequent calls to `LLVMDisasmInstruction()` will return output strings | |
| with the marked up annotations. | |
| ## Instruction Annotations | |
| (contextual markups)= | |
| ### Contextual markups | |
| Annotated assembly display will supply contextual markup to help clients more | |
| efficiently implement things like pretty printers. Most markup will be target | |
| independent, so clients can effectively provide good display without any target | |
| specific knowledge. | |
| Annotated assembly goes through the normal instruction printer, but optionally | |
| includes contextual tags on portions of the instruction string. An annotation | |
| is any '\<' '>' delimited section of text(1). | |
| ```bat | |
| annotation: '<' tag-name tag-modifier-list ':' annotated-text '>' | |
| tag-name: identifier | |
| tag-modifier-list: comma delimited identifier list | |
| ``` | |
| The tag-name is an identifier which gives the type of the annotation. For the | |
| first pass, this will be very simple, with memory references, registers, and | |
| immediates having the tag names "mem", "reg", and "imm", respectively. | |
| The tag-modifier-list is typically additional target-specific context, such as | |
| register class. | |
| Clients should accept and ignore any tag-names or tag-modifiers they do not | |
| understand, allowing the annotations to grow in richness without breaking older | |
| clients. | |
| For example, a possible annotation of an ARM load of a stack-relative location | |
| might be annotated as: | |
| ```text | |
| ldr <reg gpr:r0>, <mem regoffset:[<reg gpr:sp>, <imm:#4>]> | |
| ``` | |
| 1: For assembly dialects in which '\<' and/or '>' are legal tokens, a literal token is escaped by following immediately with a repeat of the character. For example, a literal '\<' character is output as '\<<' in an annotated assembly string. | |
| ### C API Details | |
| The intended consumers of this information use the C API, therefore the new C | |
| API function for the disassembler will be added to provide an option to produce | |
| disassembled instructions with annotations, `LLVMSetDisasmOptions()` and the | |
| `LLVMDisassembler_Option_UseMarkup` option (see above). |