[globalisel][docs] Rewrite the IRTranslator documentation

[dsanders]

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

[arsenm]

llvm/docs/GlobalISel/IRTranslator.rst

69–70

This is no longer accurate, and multiple registers are produced

[rovka]

llvm/docs/GlobalISel/IRTranslator.rst

88

+ "prevent" or something.

94

Maybe a link to the in-tree Localizer pass?

[dsanders]

Fixed the review comments
Strengthened the caution on the CallLowering section as Matt confirmed it's no longer accurate

[dsanders]

llvm/docs/GlobalISel/IRTranslator.rst

69–70

I've strengthened the caution on this section. I've asked Aditya to look into updating this section but he's not going to be able to get to it until Friday at the earliest

94

Done. I've used a link that tracks master for this one since we're linking to the pass itself rather than any specific code. We should probably turn it into a proper documentation page at some point.

[rovka]

LGTM.

llvm/docs/GlobalISel/IRTranslator.rst

 .. _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.
-
-.. _api-calllowering:
-
-API: CallLowering
-^^^^^^^^^^^^^^^^^
-
-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.
+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.
+
+.. note::
+
+  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.
+
+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``.
 
 ``TODO``:
 As some of the bits are undef (padding), we should consider augmenting the
 representation with additional metadata (in effect, caching computeKnownBits
 information on vregs).
 See `PR26161 <http://llvm.org/PR26161>`_: [GlobalISel] Value to vreg during
 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.