Index: docs/MachineIRRef.rst
===================================================================
--- /dev/null
+++ docs/MachineIRRef.rst
@@ -0,0 +1,95 @@
+========================================
+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 `machine specific intermediate representation
+<CodeGenerator.html#machine-code-description-classes>`_.
+
+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
+<http://www.yaml.org/spec/1.2/spec.html#id2800132>`_. The first document
+can contain an optional embedded LLVM IR module, and the rest of the documents
+contain the serialized machine functions.
+
+High Level Structure
+====================
+
+Embedded Module
+---------------
+
+When the first YAML document contains a `YAML block literal string
+<http://www.yaml.org/spec/1.2/spec.html#id2795688>`_, 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
+       }
+     ...
+
+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.
+
Index: docs/index.rst
===================================================================
--- docs/index.rst
+++ docs/index.rst
@@ -261,6 +261,7 @@
    MergeFunctions
    BitSets
    FaultMaps
+   MachineIRRef
 
 :doc:`WritingAnLLVMPass`
    Information on how to write LLVM transformations and analyses.
@@ -273,6 +274,10 @@
    working on retargetting LLVM to a new architecture, designing a new codegen
    pass, or enhancing existing components.
 
+:doc:`MIR Format Reference <MachineIRRef>`
+   A reference manual for the MIR serialization format, which is used to test
+   LLVM's code generation passes.
+
 :doc:`TableGen <TableGen/index>`
    Describes the TableGen tool, which is used heavily by the LLVM code
    generator.