llvm/docs/GlobalISel/GMIR.rst

   1 .. _gmir:
   2
   3 Generic Machine IR
   4 ==================
   5
   6 .. contents::
   7    :local:
   8
   9 Generic MIR (gMIR) is an intermediate representation that shares the same data
  10 structures as :doc:`MachineIR (MIR) <../MIRLangRef>` but has more relaxed
  11 constraints. As the compilation pipeline proceeds, these constraints are
  12 gradually tightened until gMIR has become MIR.
  13
  14 The rest of this document will assume that you are familiar with the concepts
  15 in :doc:`MachineIR (MIR) <../MIRLangRef>` and will highlight the differences
  16 between MIR and gMIR.
  17
  18 .. _gmir-instructions:
  19
  20 Generic Machine Instructions
  21 ----------------------------
  22
  23 .. note::
  24
  25   This section expands on :ref:`mir-instructions` from the MIR Language
  26   Reference.
  27
  28 Whereas MIR deals largely in Target Instructions and only has a small set of
  29 target independent opcodes such as ``COPY``, ``PHI``, and ``REG_SEQUENCE``,
  30 gMIR defines a rich collection of ``Generic Opcodes`` which are target
  31 independent and describe operations which are typically supported by targets.
  32 One example is ``G_ADD`` which is the generic opcode for an integer addition.
  33 More information on each of the generic opcodes can be found at
  34 :doc:`GenericOpcode`.
  35
  36 The ``MachineIRBuilder`` class wraps the ``MachineInstrBuilder`` and provides
  37 a convenient way to create these generic instructions.
  38
  39 .. _gmir-gvregs:
  40
  41 Generic Virtual Registers
  42 -------------------------
  43
  44 .. note::
  45
  46   This section expands on :ref:`mir-registers` from the MIR Language
  47   Reference.
  48
  49 Generic virtual registers are like virtual registers but they are not assigned a
  50 Register Class constraint. Instead, generic virtual registers have less strict
  51 constraints starting with a :ref:`gmir-llt` and then further constrained to a
  52 :ref:`gmir-regbank`. Eventually they will be constrained to a register class
  53 at which point they become normal virtual registers.
  54
  55 Generic virtual registers can be used with all the virtual register API's
  56 provided by ``MachineRegisterInfo``. In particular, the def-use chain API's can
  57 be used without needing to distinguish them from non-generic virtual registers.
  58
  59 For simplicity, most generic instructions only accept virtual registers (both
  60 generic and non-generic). There are some exceptions to this but in general:
  61
  62 * instead of immediates, they use a generic virtual register defined by an
  63   instruction that materializes the immediate value (see
  64   :ref:`irtranslator-constants`). Typically this is a G_CONSTANT or a
  65   G_FCONSTANT. One example of an exception to this rule is G_SEXT_INREG where
  66   having an immediate is mandatory.
  67 * instead of physical register, they use a generic virtual register that is
  68   either defined by a ``COPY`` from the physical register or used by a ``COPY``
  69   that defines the physical register.
  70
  71 .. admonition:: Historical Note
  72
  73   We started with an alternative representation, where MRI tracks a size for
  74   each generic virtual register, and instructions have lists of types.
  75   That had two flaws: the type and size are redundant, and there was no generic
  76   way of getting a given operand's type (as there was no 1:1 mapping between
  77   instruction types and operands).
  78   We considered putting the type in some variant of MCInstrDesc instead:
  79   See `PR26576 <https://llvm.org/PR26576>`_: [GlobalISel] Generic MachineInstrs
  80   need a type but this increases the memory footprint of the related objects
  81
  82 .. _gmir-regbank:
  83
  84 Register Bank
  85 -------------
  86
  87 A Register Bank is a set of register classes defined by the target. This
  88 definition is rather loose so let's talk about what they can achieve.
  89
  90 Suppose we have a processor that has two register files, A and B. These are
  91 equal in every way and support the same instructions for the same cost. They're
  92 just physically stored apart and each instruction can only access registers from
  93 A or B but never a mix of the two. If we want to perform an operation on data
  94 that's in split between the two register files, we must first copy all the data
  95 into a single register file.
  96
  97 Given a processor like this, we would benefit from clustering related data
  98 together into one register file so that we minimize the cost of copying data
  99 back and forth to satisfy the (possibly conflicting) requirements of all the
 100 instructions. Register Banks are a means to constrain the register allocator to
 101 use a particular register file for a virtual register.
 102
 103 In practice, register files A and B are rarely equal. They can typically store
 104 the same data but there's usually some restrictions on what operations you can
 105 do on each register file. A fairly common pattern is for one of them to be
 106 accessible to integer operations and the other accessible to floating point
 107 operations. To accommodate this, let's rename A and B to GPR (general purpose
 108 registers) and FPR (floating point registers).
 109
 110 We now have some additional constraints that limit us. An operation like G_FMUL
 111 has to happen in FPR and G_ADD has to happen in GPR. However, even though this
 112 prescribes a lot of the assignments we still have some freedom. A G_LOAD can
 113 happen in both GPR and FPR, and which we want depends on who is going to consume
 114 the loaded data. Similarly, G_FNEG can happen in both GPR and FPR. If we assign
 115 it to FPR, then we'll use floating point negation. However, if we assign it to
 116 GPR then we can equivalently G_XOR the sign bit with 1 to invert it.
 117
 118 In summary, Register Banks are a means of disambiguating between seemingly
 119 equivalent choices based on some analysis of the differences when each choice
 120 is applied in a given context.
 121
 122 To give some concrete examples:
 123
 124 AArch64
 125
 126   AArch64 has three main banks. GPR for integer operations, FPR for floating
 127   point and also for the NEON vector instruction set. The third is CCR and
 128   describes the condition code register used for predication.
 129
 130 MIPS
 131
 132   MIPS has five main banks of which many programs only really use one or two.
 133   GPR is the general purpose bank for integer operations. FGR or CP1 is for
 134   the floating point operations as well as the MSA vector instructions and a
 135   few other application specific extensions. CP0 is for system registers and
 136   few programs will use it. CP2 and CP3 are for any application specific
 137   coprocessors that may be present in the chip. Arguably, there is also a sixth
 138   for the LO and HI registers but these are only used for the result of a few
 139   operations and it's of questionable value to model distinctly from GPR.
 140
 141 X86
 142
 143   X86 can be seen as having 3 main banks: general-purpose, x87, and
 144   vector (which could be further split into a bank per domain for single vs
 145   double precision instructions). It also looks like there's arguably a few
 146   more potential banks such as one for the AVX512 Mask Registers.
 147
 148 Register banks are described by a target-provided API,
 149 :ref:`RegisterBankInfo <api-registerbankinfo>`.
 150
 151 .. _gmir-llt:
 152
 153 Low Level Type
 154 --------------
 155
 156 Additionally, every generic virtual register has a type, represented by an
 157 instance of the ``LLT`` class.
 158
 159 Like ``EVT``/``MVT``/``Type``, it has no distinction between unsigned and signed
 160 integer types.  Furthermore, it also has no distinction between integer and
 161 floating-point types: it mainly conveys absolutely necessary information, such
 162 as size and number of vector lanes:
 163
 164 * ``sN`` for scalars
 165 * ``pN`` for pointers
 166 * ``<N x sM>`` for vectors
 167
 168 ``LLT`` is intended to replace the usage of ``EVT`` in SelectionDAG.
 169
 170 Here are some LLT examples and their ``EVT`` and ``Type`` equivalents:
 171
 172    =============  =========  ======================================
 173    LLT            EVT        IR Type
 174    =============  =========  ======================================
 175    ``s1``         ``i1``     ``i1``
 176    ``s8``         ``i8``     ``i8``
 177    ``s32``        ``i32``    ``i32``
 178    ``s32``        ``f32``    ``float``
 179    ``s17``        ``i17``    ``i17``
 180    ``s16``        N/A        ``{i8, i8}`` [#abi-dependent]_
 181    ``s32``        N/A        ``[4 x i8]`` [#abi-dependent]_
 182    ``p0``         ``iPTR``   ``i8*``, ``i32*``, ``%opaque*``
 183    ``p2``         ``iPTR``   ``i8 addrspace(2)*``
 184    ``<4 x s32>``  ``v4f32``  ``<4 x float>``
 185    ``s64``        ``v1f64``  ``<1 x double>``
 186    ``<3 x s32>``  ``v3i32``  ``<3 x i32>``
 187    =============  =========  ======================================
 188
 189
 190 Rationale: instructions already encode a specific interpretation of types
 191 (e.g., ``add`` vs. ``fadd``, or ``sdiv`` vs. ``udiv``).  Also encoding that
 192 information in the type system requires introducing bitcast with no real
 193 advantage for the selector.
 194
 195 Pointer types are distinguished by address space.  This matches IR, as opposed
 196 to SelectionDAG where address space is an attribute on operations.
 197 This representation better supports pointers having different sizes depending
 198 on their addressspace.
 199
 200 .. note::
 201
 202   .. caution::
 203
 204     Is this still true? I thought we'd removed the 1-element vector concept.
 205     Hypothetically, it could be distinct from a scalar but I think we failed to
 206     find a real occurrence.
 207
 208   Currently, LLT requires at least 2 elements in vectors, but some targets have
 209   the concept of a '1-element vector'.  Representing them as their underlying
 210   scalar type is a nice simplification.
 211
 212 .. rubric:: Footnotes
 213
 214 .. [#abi-dependent] This mapping is ABI dependent. Here we've assumed no additional padding is required.
 215
 216 Generic Opcode Reference
 217 ------------------------
 218
 219 The Generic Opcodes that are available are described at :doc:`GenericOpcode`.