diff options
Diffstat (limited to 'docs/MIRLangRef.rst')
-rw-r--r-- | docs/MIRLangRef.rst | 78 |
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 ----------- |