llvm/docs/GlobalISel/IRTranslator.rst

   1 .. _irtranslator:
   2
   3 IRTranslator
   4 ============
   5
   6 .. contents::
   7   :local:
   8
   9 This pass translates the input LLVM-IR ``Function`` to a GMIR
  10 ``MachineFunction``. This is typically a direct translation but does
  11 occasionally get a bit more involved. For example:
  12
  13 .. code-block:: llvm
  14
  15   %2 = add i32 %0, %1
  16
  17 becomes:
  18
  19 .. code-block:: none
  20
  21   %2:_(s32) = G_ADD %0:_(s32), %1:_(s32)
  22
  23 whereas
  24
  25 .. code-block:: llvm
  26
  27   call i32 @puts(i8* %cast210)
  28
  29 is translated according to the ABI rules of the target.
  30
  31 .. note::
  32
  33   The currently implemented portion of the :doc:`../LangRef` is sufficient for
  34   many compilations but it is not 100% complete. Users seeking to compile
  35   LLVM-IR containing some of the rarer features may need to implement the
  36   translation.
  37
  38 Target Intrinsics
  39 -----------------
  40
  41 There has been some (off-list) debate about whether to add target hooks for
  42 translating target intrinsics. Among those who discussed it, it was generally
  43 agreed that the IRTranslator should be able to lower target intrinsics in a
  44 customizable way but no work has happened to implement this at the time of
  45 writing.
  46
  47 .. _translator-call-lower:
  48
  49 Translating Function Calls
  50 --------------------------
  51
  52 The ``IRTranslator`` also implements the ABI's calling convention by lowering
  53 calls, returns, and arguments to the appropriate physical register usage and
  54 instruction sequences. This is achieved using the ``CallLowering``
  55 implementation,
  56
  57 .. _irtranslator-aggregates:
  58
  59 Aggregates
  60 ^^^^^^^^^^
  61
  62 .. caution::
  63
  64   This has changed since it was written and is no longer accurate. It has not
  65   been refreshed in this pass of improving the documentation as I haven't
  66   worked much in this part of the codebase and it should have attention from
  67   someone more knowledgeable about it.
  68
  69 Aggregates are lowered into multiple virtual registers, similar to
  70 SelectionDAG's multiple vregs via ``GetValueVTs``.
  71
  72 ``TODO``:
  73 As some of the bits are undef (padding), we should consider augmenting the
  74 representation with additional metadata (in effect, caching computeKnownBits
  75 information on vregs).
  76 See `PR26161 <https://llvm.org/PR26161>`_: [GlobalISel] Value to vreg during
  77 IR to MachineInstr translation for aggregate type
  78
  79 .. _irtranslator-constants:
  80
  81 Translation of Constants
  82 ------------------------
  83
  84 Constant operands are translated as a use of a virtual register that is defined
  85 by a ``G_CONSTANT`` or ``G_FCONSTANT`` instruction. These instructions are
  86 placed in the entry block to allow them to be subject to the continuous CSE
  87 implementation (``CSEMIRBuilder``). Their debug location information is removed
  88 to prevent this from confusing debuggers.
  89
  90 This is beneficial as it allows us to fold constants into immediate operands
  91 during :ref:`instructionselect`, while still avoiding redundant materializations
  92 for expensive non-foldable constants. However, this can lead to unnecessary
  93 spills and reloads in an -O0 pipeline, as these virtual registers can have long
  94 live ranges. This can be mitigated by running a `localizer <https://github.com/llvm/llvm-project/blob/main/llvm/lib/CodeGen/GlobalISel/Localizer.cpp>`_
  95 after the translator.