From: Daniel Sanders Date: Sat, 26 Oct 2019 02:54:01 +0000 (-0700) Subject: [globalisel][docs] Rewrite the IRTranslator documentation X-Git-Tag: llvmorg-11-init~5558 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=6f665fc7868b4eca6fc644e0a99807fcbd831dfc;p=platform%2Fupstream%2Fllvm.git [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 --- 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 `_ +after the translator.