From 305f70be76f8d69b9933161a521f9b655f5a52d9 Mon Sep 17 00:00:00 2001 From: Daniel Sanders Date: Mon, 23 Oct 2017 17:18:44 +0000 Subject: [PATCH] [globalisel] Add very brief docs summarizing the ISel part of the LLVMDev tutorial. Also added links to the talks available. llvm-svn: 316350 --- llvm/docs/GlobalISel.rst | 74 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 69 insertions(+), 5 deletions(-) diff --git a/llvm/docs/GlobalISel.rst b/llvm/docs/GlobalISel.rst index c124911978c5..8746685491c7 100644 --- a/llvm/docs/GlobalISel.rst +++ b/llvm/docs/GlobalISel.rst @@ -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 `_ +* `Global Instruction Selection - Status by Quentin Colombet, Ahmed Bougacha, and Tim Northover @LLVMDevMeeting 2016 `_ +* `GlobalISel - LLVM's Latest Instruction Selection Framework by Diana Picus @FOSDEM17 `_ +* 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