[llvm] r316350 - [globalisel] Add very brief docs summarizing the ISel part of the LLVMDev tutorial.

[Daniel Sanders via llvm-commits]

Author: dsanders
Date: Mon Oct 23 10:18:44 2017
New Revision: 316350

URL: http://llvm.org/viewvc/llvm-project?rev=316350&view=rev
Log:
[globalisel] Add very brief docs summarizing the ISel part of the LLVMDev tutorial.

Also added links to the talks available.


Modified:
    llvm/trunk/docs/GlobalISel.rst

Modified: llvm/trunk/docs/GlobalISel.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/GlobalISel.rst?rev=316350&r1=316349&r2=316350&view=diff
==============================================================================
--- llvm/trunk/docs/GlobalISel.rst (original)
+++ llvm/trunk/docs/GlobalISel.rst Mon Oct 23 10:18:44 2017
@@ -503,16 +503,69 @@ The simple API consists of:
 This target-provided method is responsible for mutating (or replacing) a
 possibly-generic MI into a fully target-specific equivalent.
 It is also responsible for doing the necessary constraining of gvregs into the
-appropriate register classes.
+appropriate register classes as well as passing through COPY instructions to
+the register allocator.
 
 The ``InstructionSelector`` can fold other instructions into the selected MI,
 by walking the use-def chain of the vreg operands.
 As GlobalISel is Global, this folding can occur across basic blocks.
 
-``TODO``:
-Currently, the Select pass is implemented with hand-written c++, similar to
-FastISel, rather than backed by tblgen'erated pattern-matching.
-We intend to eventually reuse SelectionDAG patterns.
+SelectionDAG Rule Imports
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TableGen will import SelectionDAG rules and provide the following function to
+execute them:
+
+  .. code-block:: c++
+
+    bool selectImpl(MachineInstr &MI)
+
+The ``--stats`` option can be used to determine what proportion of rules were
+successfully imported. The easiest way to use this is to copy the
+``-gen-globalisel`` tablegen command from ``ninja -v`` and modify it.
+
+Similarly, the ``--warn-on-skipped-patterns`` option can be used to obtain the
+reasons that rules weren't imported. This can be used to focus on the most
+important rejection reasons.
+
+PatLeaf Predicates
+^^^^^^^^^^^^^^^^^^
+
+PatLeafs cannot be imported because their C++ is implemented in terms of
+``SDNode`` objects. PatLeafs that handle immediate predicates should be
+replaced by ``ImmLeaf``, ``IntImmLeaf``, or ``FPImmLeaf`` as appropriate.
+
+There's no standard answer for other PatLeafs. Some standard predicates have
+been baked into TableGen but this should not generally be done.
+
+Custom SDNodes
+^^^^^^^^^^^^^^
+
+Custom SDNodes should be mapped to Target Pseudos using ``GINodeEquiv``. This
+will cause the instruction selector to import them but you will also need to
+ensure the target pseudo is introduced to the MIR before the instruction
+selector. Any preceeding pass is suitable but the legalizer will be a
+particularly common choice.
+
+ComplexPatterns
+^^^^^^^^^^^^^^^
+
+ComplexPatterns cannot be imported because their C++ is implemented in terms of
+``SDNode`` objects. GlobalISel versions should be defined with
+``GIComplexOperandMatcher`` and mapped to ComplexPattern with
+``GIComplexPatternEquiv``.
+
+The following predicates are useful for porting ComplexPattern:
+
+* isBaseWithConstantOffset() - Check for base+offset structures
+* isOperandImmEqual() - Check for a particular constant
+* isObviouslySafeToFold() - Check for reasons an instruction can't be sunk and folded into another.
+
+There are some important points for the C++ implementation:
+
+* Don't modify MIR in the predicate
+* Renderer lambdas should capture by value to avoid use-after-free. They will be used after the predicate returns.
+* Only create instructions in a renderer lambda. GlobalISel won't clean up things you create but don't use.
 
 
 .. _maintainability:
@@ -636,3 +689,14 @@ Additionally:
 
 * ``TargetPassConfig`` --- create the passes constituting the pipeline,
   including additional passes not included in the :ref:`pipeline`.
+
+.. _other_resources:
+
+Resources
+=========
+
+* `Global Instruction Selection - A Proposal by Quentin Colombet @LLVMDevMeeting 2015 <https://www.youtube.com/watch?v=F6GGbYtae3g>`_
+* `Global Instruction Selection - Status by Quentin Colombet, Ahmed Bougacha, and Tim Northover @LLVMDevMeeting 2016 <https://www.youtube.com/watch?v=6tfb344A7w8>`_
+* `GlobalISel - LLVM's Latest Instruction Selection Framework by Diana Picus @FOSDEM17 <https://www.youtube.com/watch?v=d6dF6E4BPeU>`_
+* GlobalISel: Past, Present, and Future by Quentin Colombet and Ahmed Bougacha @LLVMDevMeeting 2017
+* Head First into GlobalISel by Daniel Sanders, Aditya Nandakumar, and Justin Bogner @LLVMDevMeeting 2017