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 .. TODO: Describe the parsers default behaviour when optional YAML attributes
  94    are missing.
  95 .. TODO: Describe the syntax of the machine instructions.
  96 .. TODO: Describe the syntax of the immediate machine operands.
  97 .. TODO: Describe the syntax of the register machine operands.
  98 .. TODO: Describe the syntax of the virtual register operands and their YAML
  99    definitions.
 100 .. TODO: Describe the syntax of the register operand flags and the subregisters.
 101 .. TODO: Describe the machine function's YAML flag attributes.
 102 .. TODO: Describe the machine basic block's YAML flag, successors and livein
 103    attributes. Describe the syntax for the machine basic block operands.
 104 .. TODO: Describe the syntax for the global value, external symbol and register
 105    mask machine operands.
 106 .. TODO: Describe the frame information YAML mapping.
 107 .. TODO: Describe the syntax of the stack object machine operands and their
 108    YAML definitions.
 109 .. TODO: Describe the syntax of the constant pool machine operands and their
 110    YAML definitions.
 111 .. TODO: Describe the syntax of the jump table machine operands and their
 112    YAML definitions.
 113 .. TODO: Describe the syntax of the block address machine operands.
 114 .. TODO: Describe the syntax of the CFI index machine operands.
 115 .. TODO: Describe the syntax of the metadata machine operands, and the
 116    instructions debug location attribute.
 117 .. TODO: Describe the syntax of the target index machine operands.
 118 .. TODO: Describe the syntax of the register live out machine operands.
 119 .. TODO: Describe the syntax of the machine memory operands.