1 files changed, 63 insertions, 15 deletions
diff --git a/docs/MIRLangRef.rst b/docs/MIRLangRef.rst
index f6ee6ccd0506..d5e227a2018c 100644
--- a/docs/MIRLangRef.rst
+++ b/docs/MIRLangRef.rst
@@ -39,37 +39,85 @@ MIR Testing Guide
 You can use the MIR format for testing in two different ways:
 
 - You can write MIR tests that invoke a single code generation pass using the
-  ``run-pass`` option in llc.
+  ``-run-pass`` option in llc.
 
-- You can use llc's ``stop-after`` option with existing or new LLVM assembly
+- You can use llc's ``-stop-after`` option with existing or new LLVM assembly
   tests and check the MIR output of a specific code generation pass.
 
 Testing Individual Code Generation Passes
 -----------------------------------------
 
-The ``run-pass`` option in llc allows you to create MIR tests that invoke
-just a single code generation pass. When this option is used, llc will parse
-an input MIR file, run the specified code generation pass, and print the
-resulting MIR to the standard output stream.
+The ``-run-pass`` option in llc allows you to create MIR tests that invoke just
+a single code generation pass. When this option is used, llc will parse an
+input MIR file, run the specified code generation pass(es), and output the
+resulting MIR code.
 
-You can generate an input MIR file for the test by using the ``stop-after``
-option in llc. For example, if you would like to write a test for the
-post register allocation pseudo instruction expansion pass, you can specify
-the machine copy propagation pass in the ``stop-after`` option, as it runs
-just before the pass that we are trying to test:
+You can generate an input MIR file for the test by using the ``-stop-after`` or
+``-stop-before`` option in llc. For example, if you would like to write a test
+for the post register allocation pseudo instruction expansion pass, you can
+specify the machine copy propagation pass in the ``-stop-after`` option, as it
+runs just before the pass that we are trying to test:
 
-   ``llc -stop-after machine-cp bug-trigger.ll > test.mir``
+   ``llc -stop-after=machine-cp bug-trigger.ll > test.mir``
 
 After generating the input MIR file, you'll have to add a run line that uses
 the ``-run-pass`` option to it. In order to test the post register allocation
 pseudo instruction expansion pass on X86-64, a run line like the one shown
 below can be used:
 
-    ``# RUN: llc -run-pass postrapseudos -march=x86-64 %s -o /dev/null | FileCheck %s``
+    ``# RUN: llc -o - %s -mtriple=x86_64-- -run-pass=postrapseudos | FileCheck %s``
 
 The MIR files are target dependent, so they have to be placed in the target
-specific test directories. They also need to specify a target triple or a
-target architecture either in the run line or in the embedded LLVM IR module.
+specific test directories (``lib/CodeGen/TARGETNAME``). They also need to
+specify a target triple or a target architecture either in the run line or in
+the embedded LLVM IR module.
+
+Simplifying MIR files
+^^^^^^^^^^^^^^^^^^^^^
+
+The MIR code coming out of ``-stop-after``/``-stop-before`` is very verbose;
+Tests are more accessible and future proof when simplified:
+
+- Machine function attributes often have default values or the test works just
+  as well with default values. Typical candidates for this are: `alignment:`,
+  `exposesReturnsTwice`, `legalized`, `regBankSelected`, `selected`.
+  The whole `frameInfo` section is often unnecessary if there is no special
+  frame usage in the function. `tracksRegLiveness` on the other hand is often
+  necessary for some passes that care about block livein lists.
+
+- The (global) `liveins:` list is typically only interesting for early
+  instruction selection passes and can be removed when testing later passes.
+  The per-block `liveins:` on the other hand are necessary if
+  `tracksRegLiveness` is true.
+
+- Branch probability data in block `successors:` lists can be dropped if the
+  test doesn't depend on it. Example:
+  `successors: %bb.1(0x40000000), %bb.2(0x40000000)` can be replaced with
+  `successors: %bb.1, %bb.2`.
+
+- MIR code contains a whole IR module. This is necessary because there are
+  no equivalents in MIR for global variables, references to external functions,
+  function attributes, metadata, debug info. Instead some MIR data references
+  the IR constructs. You can often remove them if the test doesn't depend on
+  them.
+
+- Alias Analysis is performed on IR values. These are referenced by memory
+  operands in MIR. Example: `:: (load 8 from %ir.foobar, !alias.scope !9)`.
+  If the test doesn't depend on (good) alias analysis the references can be
+  dropped: `:: (load 8)`
+
+- MIR blocks can reference IR blocks for debug printing, profile information
+  or debug locations. Example: `bb.42.myblock` in MIR references the IR block
+  `myblock`. It is usually possible to drop the `.myblock` reference and simply
+  use `bb.42`.
+
+- If there are no memory operands or blocks referencing the IR then the
+  IR function can be replaced by a parameterless dummy function like
+  `define @func() { ret void }`.
+
+- It is possible to drop the whole IR section of the MIR file if it only
+  contains dummy functions (see above). The .mir loader will create the
+  IR functions automatically in this case.
 
 Limitations
 -----------