diff options
Diffstat (limited to 'docs/MIRLangRef.rst')
| -rw-r--r-- | docs/MIRLangRef.rst | 186 |
1 files changed, 176 insertions, 10 deletions
diff --git a/docs/MIRLangRef.rst b/docs/MIRLangRef.rst index b4ca8f2347a7..f170c7210879 100644 --- a/docs/MIRLangRef.rst +++ b/docs/MIRLangRef.rst @@ -121,6 +121,8 @@ Tests are more accessible and future proof when simplified: contains dummy functions (see above). The .mir loader will create the IR functions automatically in this case. +.. _limitations: + Limitations ----------- @@ -238,6 +240,8 @@ in the block's definition: The block's name should be identical to the name of the IR block that this machine block is based on. +.. _block-references: + Block References ^^^^^^^^^^^^^^^^ @@ -246,13 +250,25 @@ blocks are referenced using the following syntax: .. code-block:: text - %bb.<id>[.<name>] + %bb.<id> -Examples: +Example: .. code-block:: llvm %bb.0 + +The following syntax is also supported, but the former syntax is preferred for +block references: + +.. code-block:: text + + %bb.<id>[.<name>] + +Example: + +.. code-block:: llvm + %bb.1.then Successors @@ -418,7 +434,40 @@ immediate machine operand ``-42``: %eax = MOV32ri -42 -.. TODO: Describe the CIMM (Rare) and FPIMM immediate operands. +An immediate operand is also used to represent a subregister index when the +machine instruction has one of the following opcodes: + +- ``EXTRACT_SUBREG`` + +- ``INSERT_SUBREG`` + +- ``REG_SEQUENCE`` + +- ``SUBREG_TO_REG`` + +In case this is true, the Machine Operand is printed according to the target. + +For example: + +In AArch64RegisterInfo.td: + +.. code-block:: text + + def sub_32 : SubRegIndex<32>; + +If the third operand is an immediate with the value ``15`` (target-dependent +value), based on the instruction's opcode and the operand's index the operand +will be printed as ``%subreg.sub_32``: + +.. code-block:: text + + %1:gpr64 = SUBREG_TO_REG 0, %0, %subreg.sub_32 + +For integers > 64bit, we use a special machine operand, ``MO_CImmediate``, +which stores the immediate in a ``ConstantInt`` using an ``APInt`` (LLVM's +arbitrary precision integers). + +.. TODO: Describe the FPIMM immediate operands. .. _register-operands: @@ -484,6 +533,9 @@ corresponding internal ``llvm::RegState`` representation: * - ``debug-use`` - ``RegState::Debug`` + * - ``renamable`` + - ``RegState::Renamable`` + .. _subregister-indices: Subregister Indices @@ -501,6 +553,53 @@ lower bits from the 32-bit virtual register 0 to the 8-bit virtual register 1: The names of the subregister indices are target specific, and are typically defined in the target's ``*RegisterInfo.td`` file. +Constant Pool Indices +^^^^^^^^^^^^^^^^^^^^^ + +A constant pool index (CPI) operand is printed using its index in the +function's ``MachineConstantPool`` and an offset. + +For example, a CPI with the index 1 and offset 8: + +.. code-block:: text + + %1:gr64 = MOV64ri %const.1 + 8 + +For a CPI with the index 0 and offset -12: + +.. code-block:: text + + %1:gr64 = MOV64ri %const.0 - 12 + +A constant pool entry is bound to a LLVM IR ``Constant`` or a target-specific +``MachineConstantPoolValue``. When serializing all the function's constants the +following format is used: + +.. code-block:: text + + constants: + - id: <index> + value: <value> + alignment: <alignment> + isTargetSpecific: <target-specific> + +where ``<index>`` is a 32-bit unsigned integer, ``<value>`` is a `LLVM IR Constant +<https://www.llvm.org/docs/LangRef.html#constants>`_, alignment is a 32-bit +unsigned integer, and ``<target-specific>`` is either true or false. + +Example: + +.. code-block:: text + + constants: + - id: 0 + value: 'double 3.250000e+00' + alignment: 8 + - id: 1 + value: 'g-(LPC0+8)' + alignment: 4 + isTargetSpecific: true + Global Value Operands ^^^^^^^^^^^^^^^^^^^^^ @@ -520,24 +619,91 @@ If the identifier doesn't match the regular expression The unnamed global values are represented using an unsigned numeric value with the '@' prefix, like in the following examples: ``@0``, ``@989``. +Target-dependent Index Operands +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A target index operand is a target-specific index and an offset. The +target-specific index is printed using target-specific names and a positive or +negative offset. + +For example, the ``amdgpu-constdata-start`` is associated with the index ``0`` +in the AMDGPU backend. So if we have a target index operand with the index 0 +and the offset 8: + +.. code-block:: text + + %sgpr2 = S_ADD_U32 _, target-index(amdgpu-constdata-start) + 8, implicit-def _, implicit-def _ + +Jump-table Index Operands +^^^^^^^^^^^^^^^^^^^^^^^^^ + +A jump-table index operand with the index 0 is printed as following: + +.. code-block:: text + + tBR_JTr killed %r0, %jump-table.0 + +A machine jump-table entry contains a list of ``MachineBasicBlocks``. When serializing all the function's jump-table entries, the following format is used: + +.. code-block:: text + + jumpTable: + kind: <kind> + entries: + - id: <index> + blocks: [ <bbreference>, <bbreference>, ... ] + +where ``<kind>`` is describing how the jump table is represented and emitted (plain address, relocations, PIC, etc.), and each ``<index>`` is a 32-bit unsigned integer and ``blocks`` contains a list of :ref:`machine basic block references <block-references>`. + +Example: + +.. code-block:: text + + jumpTable: + kind: inline + entries: + - id: 0 + blocks: [ '%bb.3', '%bb.9', '%bb.4.d3' ] + - id: 1 + blocks: [ '%bb.7', '%bb.7', '%bb.4.d3', '%bb.5' ] + +External Symbol Operands +^^^^^^^^^^^^^^^^^^^^^^^^^ + +An external symbol operand is represented using an identifier with the ``$`` +prefix. The identifier is surrounded with ""'s and escaped if it has any +special non-printable characters in it. + +Example: + +.. code-block:: text + + CALL64pcrel32 $__stack_chk_fail, csr_64, implicit %rsp, implicit-def %rsp + +MCSymbol Operands +^^^^^^^^^^^^^^^^^ + +A MCSymbol operand is holding a pointer to a ``MCSymbol``. For the limitations +of this operand in MIR, see :ref:`limitations <limitations>`. + +The syntax is: + +.. code-block:: text + + EH_LABEL <mcsymbol Ltmp1> + .. TODO: Describe the parsers default behaviour when optional YAML attributes are missing. .. TODO: Describe the syntax for the bundled instructions. .. TODO: Describe the syntax for virtual register YAML definitions. .. TODO: Describe the machine function's YAML flag attributes. -.. TODO: Describe the syntax for the external symbol and register - mask machine operands. +.. TODO: Describe the syntax for the register mask machine operands. .. TODO: Describe the frame information YAML mapping. .. TODO: Describe the syntax of the stack object machine operands and their YAML definitions. -.. TODO: Describe the syntax of the constant pool machine operands and their - YAML definitions. -.. TODO: Describe the syntax of the jump table machine operands and their - YAML definitions. .. TODO: Describe the syntax of the block address machine operands. .. TODO: Describe the syntax of the CFI index machine operands. .. TODO: Describe the syntax of the metadata machine operands, and the instructions debug location attribute. -.. TODO: Describe the syntax of the target index machine operands. .. TODO: Describe the syntax of the register live out machine operands. .. TODO: Describe the syntax of the machine memory operands. |