1 ========================================
2 Machine IR (MIR) Format Reference Manual
3 ========================================
9 This is a work in progress.
14 This document is a reference manual for the Machine IR (MIR) serialization
15 format. MIR is a human readable serialization format that is used to represent
16 LLVM's :ref:`machine specific intermediate representation
17 <machine code representation>`.
19 The MIR serialization format is designed to be used for testing the code
20 generation passes in LLVM.
25 The MIR serialization format uses a YAML container. YAML is a standard
26 data serialization language, and the full YAML language spec can be read at
28 <http://www.yaml.org/spec/1.2/spec.html#Introduction>`_.
30 A MIR file is split up into a series of `YAML documents`_. The first document
31 can contain an optional embedded LLVM IR module, and the rest of the documents
32 contain the serialized machine functions.
34 .. _YAML documents: http://www.yaml.org/spec/1.2/spec.html#id2800132
42 When the first YAML document contains a `YAML block literal string`_, the MIR
43 parser will treat this string as an LLVM assembly language string that
44 represents an embedded LLVM IR module.
45 Here is an example of a YAML document that contains an LLVM module:
50 define i32 @inc(i32* %x) {
52 %0 = load i32, i32* %x
59 .. _YAML block literal string: http://www.yaml.org/spec/1.2/spec.html#id2795688
64 The remaining YAML documents contain the machine functions. This is an example
65 of such YAML document:
71 tracksRegLiveness: true
79 - '%eax = MOV32rm %rdi, 1, _, 0, _'
80 - '%eax = INC32r killed %eax, implicit-def dead %eflags'
81 - 'MOV32mr killed %rdi, 1, _, 0, _, %eax'
85 The document above consists of attributes that represent the various
86 properties and data structures in a machine function.
88 The attribute ``name`` is required, and its value should be identical to the
89 name of a function that this machine function is based on.
91 The attribute ``body`` contains a list of YAML mappings that represent the
92 function's machine basic blocks.
94 The first machine basic block in the ``body`` list above contains the attribute
95 ``instructions``. This attribute stores a list of string literals which
96 represent the machine instructions for that basic block.
98 .. TODO: Describe the parsers default behaviour when optional YAML attributes
100 .. TODO: Describe the syntax of the machine instructions.
101 .. TODO: Describe the syntax of the immediate machine operands.
102 .. TODO: Describe the syntax of the register machine operands.
103 .. TODO: Describe the syntax of the virtual register operands and their YAML
105 .. TODO: Describe the syntax of the register operand flags and the subregisters.
106 .. TODO: Describe the machine function's YAML flag attributes.
107 .. TODO: Describe the machine basic block's YAML flag, successors and livein
108 attributes. Describe the syntax for the machine basic block operands.
109 .. TODO: Describe the syntax for the global value, external symbol and register
110 mask machine operands.
111 .. TODO: Describe the frame information YAML mapping.
112 .. TODO: Describe the syntax of the stack object machine operands and their
114 .. TODO: Describe the syntax of the constant pool machine operands and their
116 .. TODO: Describe the syntax of the jump table machine operands and their
118 .. TODO: Describe the syntax of the block address machine operands.
119 .. TODO: Describe the syntax of the CFI index machine operands.
120 .. TODO: Describe the syntax of the metadata machine operands, and the
121 instructions debug location attribute.
122 .. TODO: Describe the syntax of the target index machine operands.
123 .. TODO: Describe the syntax of the register live out machine operands.
124 .. TODO: Describe the syntax of the machine memory operands.