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
 204 .. TODO: Describe the parsers default behaviour when optional YAML attributes
 205    are missing.
 206 .. TODO: Describe the syntax of the machine instructions.
 207 .. TODO: Describe the syntax of the immediate machine operands.
 208 .. TODO: Describe the syntax of the register machine operands.
 209 .. TODO: Describe the syntax of the virtual register operands and their YAML
 210    definitions.
 211 .. TODO: Describe the syntax of the register operand flags and the subregisters.
 212 .. TODO: Describe the machine function's YAML flag attributes.
 213 .. TODO: Describe the syntax for the global value, external symbol and register
 214    mask machine operands.
 215 .. TODO: Describe the frame information YAML mapping.
 216 .. TODO: Describe the syntax of the stack object machine operands and their
 217    YAML definitions.
 218 .. TODO: Describe the syntax of the constant pool machine operands and their
 219    YAML definitions.
 220 .. TODO: Describe the syntax of the jump table machine operands and their
 221    YAML definitions.
 222 .. TODO: Describe the syntax of the block address machine operands.
 223 .. TODO: Describe the syntax of the CFI index machine operands.
 224 .. TODO: Describe the syntax of the metadata machine operands, and the
 225    instructions debug location attribute.
 226 .. TODO: Describe the syntax of the target index machine operands.
 227 .. TODO: Describe the syntax of the register live out machine operands.
 228 .. TODO: Describe the syntax of the machine memory operands.