--- /dev/null
+========================================
+Machine IR (MIR) Format Reference Manual
+========================================
+
+.. contents::
+ :local:
+
+.. warning::
+ This is a work in progress.
+
+Introduction
+============
+
+This document is a reference manual for the Machine IR (MIR) serialization
+format. MIR is a human readable serialization format that is used to represent
+LLVM's :ref:`machine specific intermediate representation
+<machine code representation>`.
+
+The MIR serialization format is designed to be used for testing the code
+generation passes in LLVM.
+
+Overview
+========
+
+The MIR serialization format uses a YAML container. YAML is a standard
+data serialization language, and the full YAML language spec can be read at
+`yaml.org
+<http://www.yaml.org/spec/1.2/spec.html#Introduction>`_.
+
+A MIR file is split up into a series of `YAML documents`_. The first document
+can contain an optional embedded LLVM IR module, and the rest of the documents
+contain the serialized machine functions.
+
+.. _YAML documents: http://www.yaml.org/spec/1.2/spec.html#id2800132
+
+High Level Structure
+====================
+
+Embedded Module
+---------------
+
+When the first YAML document contains a `YAML block literal string`_, the MIR
+parser will treat this string as an LLVM assembly language string that
+represents an embedded LLVM IR module.
+Here is an example of a YAML document that contains an LLVM module:
+
+.. code-block:: llvm
+
+ --- |
+ define i32 @inc(i32* %x) {
+ entry:
+ %0 = load i32, i32* %x
+ %1 = add i32 %0, 1
+ store i32 %1, i32* %x
+ ret i32 %1
+ }
+ ...
+
+.. _YAML block literal string: http://www.yaml.org/spec/1.2/spec.html#id2795688
+
+Machine Functions
+-----------------
+
+The remaining YAML documents contain the machine functions. This is an example
+of such YAML document:
+
+.. code-block:: yaml
+
+ ---
+ name: inc
+ tracksRegLiveness: true
+ liveins:
+ - { reg: '%rdi' }
+ body:
+ - id: 0
+ name: entry
+ liveins: [ '%rdi' ]
+ instructions:
+ - '%eax = MOV32rm %rdi, 1, _, 0, _'
+ - '%eax = INC32r killed %eax, implicit-def dead %eflags'
+ - 'MOV32mr killed %rdi, 1, _, 0, _, %eax'
+ - 'RETQ %eax'
+ ...
+
+The document above consists of attributes that represent the various
+properties and data structures in a machine function.
+
+The attribute ``name`` is required, and its value should be identical to the
+name of a function that this machine function is based on.
+
+The attribute ``body`` contains a list of YAML mappings that represent the
+function's machine basic blocks.
+
+The first machine basic block in the ``body`` list above contains the attribute
+``instructions``. This attribute stores a list of string literals which
+represent the machine instructions for that basic block.
+
+.. TODO: Describe the parsers default behaviour when optional YAML attributes
+ are missing.
+.. TODO: Describe the syntax of the machine instructions.
+.. TODO: Describe the syntax of the immediate machine operands.
+.. TODO: Describe the syntax of the register machine operands.
+.. TODO: Describe the syntax of the virtual register operands and their YAML
+ definitions.
+.. TODO: Describe the syntax of the register operand flags and the subregisters.
+.. TODO: Describe the machine function's YAML flag attributes.
+.. TODO: Describe the machine basic block's YAML flag, successors and livein
+ attributes. Describe the syntax for the machine basic block operands.
+.. TODO: Describe the syntax for the global value, external symbol and register
+ mask machine operands.
+.. TODO: Describe the frame information YAML mapping.
+.. TODO: Describe the syntax of the stack object machine operands and their
+ YAML definitions.
+.. TODO: Describe the syntax of the constant pool machine operands and their
+ YAML definitions.
+.. TODO: Describe the syntax of the jump table machine operands and their
+ YAML definitions.
+.. TODO: Describe the syntax of the block address machine operands.
+.. TODO: Describe the syntax of the CFI index machine operands.
+.. TODO: Describe the syntax of the metadata machine operands, and the
+ instructions debug location attribute.
+.. TODO: Describe the syntax of the target index machine operands.
+.. TODO: Describe the syntax of the register live out machine operands.
+.. TODO: Describe the syntax of the machine memory operands.