forked from OSchip/llvm-project
[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
This commit is contained in:
Daniel Sanders
parent
52590319a2
commit
6f665fc786
|
|
@ -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:
|
||||
|
||||
.. _api-calllowering:
|
||||
.. code-block:: llvm
|
||||
|
||||
API: CallLowering
|
||||
^^^^^^^^^^^^^^^^^
|
||||
%2 = add i32 %0, %1
|
||||
|
||||
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.
|
||||
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``.
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue