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:: yaml
  68
  69      ---
  70      name:            inc
  71      tracksRegLiveness: true
  72      liveins:
  73        - { reg: '%rdi' }
  74      body:
  75        - id:              0
  76          name:            entry
  77          liveins:         [ '%rdi' ]
  78          instructions:
  79            - '%eax = MOV32rm %rdi, 1, _, 0, _'
  80            - '%eax = INC32r killed %eax, implicit-def dead %eflags'
  81            - 'MOV32mr killed %rdi, 1, _, 0, _, %eax'
  82            - 'RETQ %eax'
  83      ...
  84
  85 The document above consists of attributes that represent the various
  86 properties and data structures in a machine function.
  87
  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.
  90
  91 The attribute ``body`` contains a list of YAML mappings that represent the
  92 function's machine basic blocks.
  93
  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.
  97
  98 .. TODO: Describe the parsers default behaviour when optional YAML attributes
  99    are missing.
 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
 104    definitions.
 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
 113    YAML definitions.
 114 .. TODO: Describe the syntax of the constant pool machine operands and their
 115    YAML definitions.
 116 .. TODO: Describe the syntax of the jump table machine operands and their
 117    YAML definitions.
 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.