[globalisel][docs] Rewrite the IRTranslator documentation

Summary:
I haven't refreshed the Function Calls section as I don't feel I have
sufficient knowledge of that area. It would be appreciated if someone could
review that section.

Note: I'm aware that pygments doesn't support 'mir' as used in one of the
code-block directives. This currently emits a warning and I decided to
keep it to enable finding them later. Maybe we can teach pygments to
support it.

Depends on D69456

Reviewers: volkan, aditya_nandakumar

Subscribers: rovka, Petar.Avramovic, llvm-commits

Tags: #llvm

Differential Revision: https://reviews.llvm.org/D69457

diff --git a/llvm/docs/GlobalISel/IRTranslator.rst b/llvm/docs/GlobalISel/IRTranslator.rst
index 515df56..1d68524 100644 (file)
--- a/llvm/docs/GlobalISel/IRTranslator.rst
+++ b/llvm/docs/GlobalISel/IRTranslator.rst
@@ -1,30 +1,71 @@
 .. _irtranslator:
 
 IRTranslator
-------------
+============
 
-This pass translates the input LLVM IR ``Function`` to a GMIR
-``MachineFunction``.
+.. contents::
+  :local:
 
-``TODO``:
-This currently doesn't support the more complex instructions, in particular
-those involving control flow (``switch``, ``invoke``, ...).
-For ``switch`` in particular, we can initially use the ``LowerSwitch`` pass.
+This pass translates the input LLVM-IR ``Function`` to a GMIR
+``MachineFunction``. This is typically a direct translation but does
+occasionally get a bit more involved. For example:
+
+.. code-block:: llvm
+
+  %2 = add i32 %0, %1
+
+becomes:
+
+.. code-block:: mir
+
+  %2:_(s32) = G_ADD %0:_(s32), %1:_(s32)
+
+whereas
+
+.. code-block:: llvm
+
+  call i32 @puts(i8* %cast210)
+
+is translated according to the ABI rules of the target.
 
-.. _api-calllowering:
+.. note::
 
-API: CallLowering
-^^^^^^^^^^^^^^^^^
+  The currently implemented portion of the :doc:`../LangRef` is sufficient for
+  many compilations but it is not 100% complete. Users seeking to compile
+  LLVM-IR containing some of the rarer features may need to implement the
+  translation.
 
-The ``IRTranslator`` (using the ``CallLowering`` target-provided utility) also
-implements the ABI's calling convention by lowering calls, returns, and
-arguments to the appropriate physical register usage and instruction sequences.
+Target Intrinsics
+-----------------
+
+There has been some (off-list) debate about whether to add target hooks for
+translating target intrinsics. Among those who discussed it, it was generally
+agreed that the IRTranslator should be able to lower target intrinsics in a
+customizable way but no work has happened to implement this at the time of
+writing.
+
+.. _translator-call-lower:
+
+Translating Function Calls
+--------------------------
+
+The ``IRTranslator`` also implements the ABI's calling convention by lowering
+calls, returns, and arguments to the appropriate physical register usage and
+instruction sequences. This is achieved using the ``CallLowering``
+implementation,
 
 .. _irtranslator-aggregates:
 
 Aggregates
 ^^^^^^^^^^
 
+.. caution::
+
+  This has changed since it was written and is no longer accurate. It has not
+  been refreshed in this pass of improving the documentation as I haven't
+  worked much in this part of the codebase and it should have attention from
+  someone more knowledgeable about it.
+
 Aggregates are lowered to a single scalar vreg.
 This differs from SelectionDAG's multiple vregs via ``GetValueVTs``.
 
@@ -37,21 +78,18 @@ IR to MachineInstr translation for aggregate type
 
 .. _irtranslator-constants:
 
-Constant Lowering
-^^^^^^^^^^^^^^^^^
+Translation of Constants
+------------------------
 
-The ``IRTranslator`` lowers ``Constant`` operands into uses of gvregs defined
-by ``G_CONSTANT`` or ``G_FCONSTANT`` instructions.
-Currently, these instructions are always emitted in the entry basic block.
-In a ``MachineFunction``, each ``Constant`` is materialized by a single gvreg.
+Constant operands are translated as a use of a virtual register that is defined
+by a ``G_CONSTANT`` or ``G_FCONSTANT`` instruction. These instructions are
+placed in the entry block to allow them to be subject to the continuous CSE
+implementation (``CSEMIRBuilder``). Their debug location information is removed
+to prevent this from confusing debuggers.
 
 This is beneficial as it allows us to fold constants into immediate operands
 during :ref:`instructionselect`, while still avoiding redundant materializations
-for expensive non-foldable constants.
-However, this can lead to unnecessary spills and reloads in an -O0 pipeline, as
-these vregs can have long live ranges.
-
-``TODO``:
-We're investigating better placement of these instructions, in fast and
-optimized modes.
-
+for expensive non-foldable constants. However, this can lead to unnecessary
+spills and reloads in an -O0 pipeline, as these virtual registers can have long
+live ranges. This can be mitigated by running a `localizer <https://github.com/llvm/llvm-project/blob/master/llvm/lib/CodeGen/GlobalISel/Localizer.cpp>`_
+after the translator.