docs/MIRLangRef.rst

   1 ========================================
   2 Machine IR (MIR) Format Reference Manual
   3 ========================================
   4
   5 .. contents::
   6    :local:
   7
   8 .. warning::
   9   This is a work in progress.
  10
  11 Introduction
  12 ============
  13
  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>`.
  18
  19 The MIR serialization format is designed to be used for testing the code
  20 generation passes in LLVM.
  21
  22 Overview
  23 ========
  24
  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
  27 `yaml.org
  28 <http://www.yaml.org/spec/1.2/spec.html#Introduction>`_.
  29
  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.
  33
  34 .. _YAML documents: http://www.yaml.org/spec/1.2/spec.html#id2800132
  35
  36 High Level Structure
  37 ====================
  38
  39 Embedded Module
  40 ---------------
  41
  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:
  46
  47 .. code-block:: llvm
  48
  49      --- |
  50        define i32 @inc(i32* %x) {
  51        entry:
  52          %0 = load i32, i32* %x
  53          %1 = add i32 %0, 1
  54          store i32 %1, i32* %x
  55          ret i32 %1
  56        }
  57      ...
  58
  59 .. _YAML block literal string: http://www.yaml.org/spec/1.2/spec.html#id2795688
  60
  61 Machine Functions
  62 -----------------
  63
  64 The remaining YAML documents contain the machine functions. This is an example
  65 of such YAML document:
  66
  67 .. code-block:: llvm
  68
  69      ---
  70      name:            inc
  71      tracksRegLiveness: true
  72      liveins:
  73        - { reg: '%rdi' }
  74      body: |
  75        bb.0.entry:
  76          liveins: %rdi
  77
  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`` is a `YAML block literal string`_. Its value represents
  91 the function's machine basic blocks and their machine instructions.
  92
  93 Machine Instructions Format Reference
  94 =====================================
  95
  96 The machine basic blocks and their instructions are represented using a custom,
  97 human readable serialization language. This language is used in the
  98 `YAML block literal string`_ that corresponds to the machine function's body.
  99
 100 A source string that uses this language contains a list of machine basic
 101 blocks, which are described in the section below.
 102
 103 Machine Basic Blocks
 104 --------------------
 105
 106 A machine basic block is defined in a single block definition source construct
 107 that contains the block's ID.
 108 The example below defines two blocks that have an ID of zero and one:
 109
 110 .. code-block:: llvm
 111
 112     bb.0:
 113       <instructions>
 114     bb.1:
 115       <instructions>
 116
 117 A machine basic block can also have a name. It should be specified after the ID
 118 in the block's definition:
 119
 120 .. code-block:: llvm
 121
 122     bb.0.entry:       ; This block's name is "entry"
 123        <instructions>
 124
 125 The block's name should be identical to the name of the IR block that this
 126 machine block is based on.
 127
 128 Block References
 129 ^^^^^^^^^^^^^^^^
 130
 131 The machine basic blocks are identified by their ID numbers. Individual
 132 blocks are referenced using the following syntax:
 133
 134 .. code-block:: llvm
 135
 136     %bb.<id>[.<name>]
 137
 138 Examples:
 139
 140 .. code-block:: llvm
 141
 142     %bb.0
 143     %bb.1.then
 144
 145 Successors
 146 ^^^^^^^^^^
 147
 148 The machine basic block's successors have to be specified before any of the
 149 instructions:
 150
 151 .. code-block:: llvm
 152
 153     bb.0.entry:
 154       successors: %bb.1.then, %bb.2.else
 155       <instructions>
 156     bb.1.then:
 157       <instructions>
 158     bb.2.else:
 159       <instructions>
 160
 161 The branch weights can be specified in brackets after the successor blocks.
 162 The example below defines a block that has two successors with branch weights
 163 of 32 and 16:
 164
 165 .. code-block:: llvm
 166
 167     bb.0.entry:
 168       successors: %bb.1.then(32), %bb.2.else(16)
 169
 170 Live In Registers
 171 ^^^^^^^^^^^^^^^^^
 172
 173 The machine basic block's live in registers have to be specified before any of
 174 the instructions:
 175
 176 .. code-block:: llvm
 177
 178     bb.0.entry:
 179       liveins: %edi, %esi
 180
 181 The list of live in registers and successors can be empty. The language also
 182 allows multiple live in register and successor lists - they are combined into
 183 one list by the parser.
 184
 185 Miscellaneous Attributes
 186 ^^^^^^^^^^^^^^^^^^^^^^^^
 187
 188 The attributes ``IsAddressTaken``, ``IsLandingPad`` and ``Alignment`` can be
 189 specified in brackets after the block's definition:
 190
 191 .. code-block:: llvm
 192
 193     bb.0.entry (address-taken):
 194       <instructions>
 195     bb.2.else (align 4):
 196       <instructions>
 197     bb.3(landing-pad, align 4):
 198       <instructions>
 199
 200 .. TODO: Describe the way the reference to an unnamed LLVM IR block can be
 201    preserved.
 202
 203 Machine Instructions
 204 --------------------
 205
 206 A machine instruction is composed of a name, machine operands,
 207 :ref:`instruction flags <instruction-flags>`, and machine memory operands.
 208
 209 The instruction's name is usually specified before the operands. The example
 210 below shows an instance of the X86 ``RETQ`` instruction with a single machine
 211 operand:
 212
 213 .. code-block:: llvm
 214
 215     RETQ %eax
 216
 217 However, if the machine instruction has one or more explicitly defined register
 218 operands, the instruction's name has to be specified after them. The example
 219 below shows an instance of the AArch64 ``LDPXpost`` instruction with three
 220 defined register operands:
 221
 222 .. code-block:: llvm
 223
 224     %sp, %fp, %lr = LDPXpost %sp, 2
 225
 226 The instruction names are serialized using the exact definitions from the
 227 target's ``*InstrInfo.td`` files, and they are case sensitive. This means that
 228 similar instruction names like ``TSTri`` and ``tSTRi`` represent different
 229 machine instructions.
 230
 231 .. _instruction-flags:
 232
 233 Instruction Flags
 234 ^^^^^^^^^^^^^^^^^
 235
 236 The flag ``frame-setup`` can be specified before the instruction's name:
 237
 238 .. code-block:: llvm
 239
 240     %fp = frame-setup ADDXri %sp, 0, 0
 241
 242
 243 .. TODO: Describe the parsers default behaviour when optional YAML attributes
 244    are missing.
 245 .. TODO: Describe the syntax for the bundled instructions.
 246 .. TODO: Describe the syntax of the immediate machine operands.
 247 .. TODO: Describe the syntax of the register machine operands.
 248 .. TODO: Describe the syntax of the virtual register operands and their YAML
 249    definitions.
 250 .. TODO: Describe the syntax of the register operand flags and the subregisters.
 251 .. TODO: Describe the machine function's YAML flag attributes.
 252 .. TODO: Describe the syntax for the global value, external symbol and register
 253    mask machine operands.
 254 .. TODO: Describe the frame information YAML mapping.
 255 .. TODO: Describe the syntax of the stack object machine operands and their
 256    YAML definitions.
 257 .. TODO: Describe the syntax of the constant pool machine operands and their
 258    YAML definitions.
 259 .. TODO: Describe the syntax of the jump table machine operands and their
 260    YAML definitions.
 261 .. TODO: Describe the syntax of the block address machine operands.
 262 .. TODO: Describe the syntax of the CFI index machine operands.
 263 .. TODO: Describe the syntax of the metadata machine operands, and the
 264    instructions debug location attribute.
 265 .. TODO: Describe the syntax of the target index machine operands.
 266 .. TODO: Describe the syntax of the register live out machine operands.
 267 .. TODO: Describe the syntax of the machine memory operands.