1.. _irtranslator: 2 3IRTranslator 4============ 5 6.. contents:: 7 :local: 8 9This pass translates the input LLVM-IR ``Function`` to a :doc:`GMIR` 10``MachineFunction``. This is typically a direct translation but does 11occasionally get a bit more involved. For example: 12 13.. code-block:: llvm 14 15 %2 = add i32 %0, %1 16 17becomes: 18 19.. code-block:: none 20 21 %2:_(s32) = G_ADD %0:_(s32), %1:_(s32) 22 23whereas 24 25.. code-block:: llvm 26 27 call i32 @puts(i8* %cast210) 28 29is 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 38Target Intrinsics 39----------------- 40 41There has been some (off-list) debate about whether to add target hooks for 42translating target intrinsics. Among those who discussed it, it was generally 43agreed that the IRTranslator should be able to lower target intrinsics in a 44customizable way but no work has happened to implement this at the time of 45writing. 46 47.. _translator-call-lower: 48 49Translating Function Calls 50-------------------------- 51 52The ``IRTranslator`` also implements the ABI's calling convention by lowering 53calls, returns, and arguments to the appropriate physical register usage and 54instruction sequences. This is achieved using the ``CallLowering`` interface, 55which provides several hooks that targets should implement: 56``lowerFormalArguments``, ``lowerReturn``, ``lowerCall`` etc. 57 58In essence, all of these hooks need to find a way to move the argument/return 59values between the virtual registers used in the rest of the function and either 60physical registers or the stack, as dictated by the ABI. This may involve 61splitting large types into smaller ones, introducing sign/zero extensions etc. 62In order to share as much of this code as possible between the different 63backends, ``CallLowering`` makes available a few helpers and interfaces: 64 65* ``ArgInfo`` - used for formal arguments, but also return values, actual 66 arguments and call results; contains info such as the IR type, the virtual 67 registers etc; large values will likely have to be split into several 68 ``ArgInfo`` objects (``CallLowering::splitToValueTypes`` can help with that); 69 70* ``ValueAssigner`` - uses a ``CCAssignFn``, usually generated by TableGen (see 71 :ref:`backend-calling-convs`), to decide where to put each 72 ``ArgInfo`` (physical register or stack); backends can use the provided 73 ``IncomingValueAssigner`` (for formal arguments and call results) and 74 ``OutgoingValueAssigner`` (for actual arguments and function returns), but 75 it's also possible to subclass them; 76 77* ``ValueHandler`` - inserts the necessary instructions for putting each value 78 where it belongs; it has pure virtual methods for assigning values to 79 registers or to addresses, and a host of other helpers; 80 81* ``determineAndHandleAssignments`` (or for more fine grained control, 82 ``determineAssignments`` and ``handleAssignments``) - contains some boilerplate 83 for invoking a given ``ValueAssigner`` and ``ValueHandler`` on a series of 84 ``ArgInfo`` objects. 85 86.. _irtranslator-aggregates: 87 88Aggregates 89^^^^^^^^^^ 90 91.. caution:: 92 93 This has changed since it was written and is no longer accurate. It has not 94 been refreshed in this pass of improving the documentation as I haven't 95 worked much in this part of the codebase and it should have attention from 96 someone more knowledgeable about it. 97 98Aggregates are lowered into multiple virtual registers, similar to 99SelectionDAG's multiple vregs via ``GetValueVTs``. 100 101``TODO``: 102As some of the bits are undef (padding), we should consider augmenting the 103representation with additional metadata (in effect, caching computeKnownBits 104information on vregs). 105See `PR26161 <https://llvm.org/PR26161>`_: [GlobalISel] Value to vreg during 106IR to MachineInstr translation for aggregate type 107 108.. _irtranslator-constants: 109 110Translation of Constants 111------------------------ 112 113Constant operands are translated as a use of a virtual register that is defined 114by a ``G_CONSTANT`` or ``G_FCONSTANT`` instruction. These instructions are 115placed in the entry block to allow them to be subject to the continuous CSE 116implementation (``CSEMIRBuilder``). Their debug location information is removed 117to prevent this from confusing debuggers. 118 119This is beneficial as it allows us to fold constants into immediate operands 120during :ref:`instructionselect`, while still avoiding redundant materializations 121for expensive non-foldable constants. However, this can lead to unnecessary 122spills and reloads in an -O0 pipeline, as these virtual registers can have long 123live ranges. This can be mitigated by running a `localizer <https://github.com/llvm/llvm-project/blob/main/llvm/lib/CodeGen/GlobalISel/Localizer.cpp>`_ 124after the translator. 125