llvm.org GIT mirror llvm / 32dcc28
Add initial documentation for the MIR serialization format. Differential Revision: http://reviews.llvm.org/D11736 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@244292 91177308-0d34-0410-b5e6-96231b3b80d8 Alex Lorenz 4 years ago
2 changed file(s) with 129 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
0 ========================================
1 Machine IR (MIR) Format Reference Manual
2 ========================================
3
4 .. contents::
5 :local:
6
7 .. warning::
8 This is a work in progress.
9
10 Introduction
11 ============
12
13 This document is a reference manual for the Machine IR (MIR) serialization
14 format. MIR is a human readable serialization format that is used to represent
15 LLVM's :ref:`machine specific intermediate representation
16 `.
17
18 The MIR serialization format is designed to be used for testing the code
19 generation passes in LLVM.
20
21 Overview
22 ========
23
24 The MIR serialization format uses a YAML container. YAML is a standard
25 data serialization language, and the full YAML language spec can be read at
26 `yaml.org
27 `_.
28
29 A MIR file is split up into a series of `YAML documents`_. The first document
30 can contain an optional embedded LLVM IR module, and the rest of the documents
31 contain the serialized machine functions.
32
33 .. _YAML documents: http://www.yaml.org/spec/1.2/spec.html#id2800132
34
35 High Level Structure
36 ====================
37
38 Embedded Module
39 ---------------
40
41 When the first YAML document contains a `YAML block literal string`_, the MIR
42 parser will treat this string as an LLVM assembly language string that
43 represents an embedded LLVM IR module.
44 Here is an example of a YAML document that contains an LLVM module:
45
46 .. code-block:: llvm
47
48 --- |
49 define i32 @inc(i32* %x) {
50 entry:
51 %0 = load i32, i32* %x
52 %1 = add i32 %0, 1
53 store i32 %1, i32* %x
54 ret i32 %1
55 }
56 ...
57
58 .. _YAML block literal string: http://www.yaml.org/spec/1.2/spec.html#id2795688
59
60 Machine Functions
61 -----------------
62
63 The remaining YAML documents contain the machine functions. This is an example
64 of such YAML document:
65
66 .. code-block:: yaml
67
68 ---
69 name: inc
70 tracksRegLiveness: true
71 liveins:
72 - { reg: '%rdi' }
73 body:
74 - id: 0
75 name: entry
76 liveins: [ '%rdi' ]
77 instructions:
78 - '%eax = MOV32rm %rdi, 1, _, 0, _'
79 - '%eax = INC32r killed %eax, implicit-def dead %eflags'
80 - 'MOV32mr killed %rdi, 1, _, 0, _, %eax'
81 - 'RETQ %eax'
82 ...
83
84 The document above consists of attributes that represent the various
85 properties and data structures in a machine function.
86
87 The attribute ``name`` is required, and its value should be identical to the
88 name of a function that this machine function is based on.
89
90 The attribute ``body`` contains a list of YAML mappings that represent the
91 function's machine basic blocks.
92
93 The first machine basic block in the ``body`` list above contains the attribute
94 ``instructions``. This attribute stores a list of string literals which
95 represent the machine instructions for that basic block.
96
97 .. TODO: Describe the parsers default behaviour when optional YAML attributes
98 are missing.
99 .. TODO: Describe the syntax of the machine instructions.
100 .. TODO: Describe the syntax of the immediate machine operands.
101 .. TODO: Describe the syntax of the register machine operands.
102 .. TODO: Describe the syntax of the virtual register operands and their YAML
103 definitions.
104 .. TODO: Describe the syntax of the register operand flags and the subregisters.
105 .. TODO: Describe the machine function's YAML flag attributes.
106 .. TODO: Describe the machine basic block's YAML flag, successors and livein
107 attributes. Describe the syntax for the machine basic block operands.
108 .. TODO: Describe the syntax for the global value, external symbol and register
109 mask machine operands.
110 .. TODO: Describe the frame information YAML mapping.
111 .. TODO: Describe the syntax of the stack object machine operands and their
112 YAML definitions.
113 .. TODO: Describe the syntax of the constant pool machine operands and their
114 YAML definitions.
115 .. TODO: Describe the syntax of the jump table machine operands and their
116 YAML definitions.
117 .. TODO: Describe the syntax of the block address machine operands.
118 .. TODO: Describe the syntax of the CFI index machine operands.
119 .. TODO: Describe the syntax of the metadata machine operands, and the
120 instructions debug location attribute.
121 .. TODO: Describe the syntax of the target index machine operands.
122 .. TODO: Describe the syntax of the register live out machine operands.
123 .. TODO: Describe the syntax of the machine memory operands.
260260 MergeFunctions
261261 BitSets
262262 FaultMaps
263 MIRLangRef
263264
264265 :doc:`WritingAnLLVMPass`
265266 Information on how to write LLVM transformations and analyses.
271272 The design and implementation of the LLVM code generator. Useful if you are
272273 working on retargetting LLVM to a new architecture, designing a new codegen
273274 pass, or enhancing existing components.
275
276 :doc:`Machine IR (MIR) Format Reference Manual `
277 A reference manual for the MIR serialization format, which is used to test
278 LLVM's code generation passes.
274279
275280 :doc:`TableGen `
276281 Describes the TableGen tool, which is used heavily by the LLVM code