Add a section about simplifying .mir tests

[MatzeB]

Summary

I wrote down some tips and tricks to simplify .mir tests.

Any typos or further suggestions?

[MatzeB]

Add a sentence about dropping branch probability information.

[ab]

Makes sense to me. I wish we didn't need this, but progress is made one step at a time

docs/MIRLangRef.rst

117 ↗

(On Diff #95229)

Whoa, I didn't know this worked! This section is already helping =]

[MatzeB]

In D32058#726790, @ab wrote:

Makes sense to me. I wish we didn't need this, but progress is made one step at a time

Me too! I'd rather have an llc -run-pass=strip-ir than writing explanations on how to do it. But for now this is better than nothing and something you can point to in reviews.

[qcolombet]

llvm/trunk/docs/MIRLangRef.rst

120

Isn't that true only if you have one function. I think I saw it failed when having more than one. (We should fix that of course, if that's still the case!)

[MatzeB]

llvm/trunk/docs/MIRLangRef.rst

120

It definitely works with multiple functions. I think the logic just doesn't kick in if no IR block exists in the file.

[qcolombet]

llvm/trunk/docs/MIRLangRef.rst

120

Oh, that could be it. So we at least need to put an empty IR section, right?

[MatzeB]

llvm/trunk/docs/MIRLangRef.rst

120

So we at least need to put an empty IR section, right?

No, that's the point in todays strange behavior: As soon as you have an (even empty) IR section you need to create the dummy functions manually.

llvm/trunk/docs/MIRLangRef.rst

below can be used:
 
     ``# 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 (``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
 -----------
 
 Currently the MIR format has several limitations in terms of which state it
 can serialize:
 
 - The target-specific state in the target-specific ``MachineFunctionInfo``
   subclasses isn't serialized at the moment.