docs/AMDGPUInstructionSyntax.rst

   1 =========================
   2 AMDGPU Instruction Syntax
   3 =========================
   4
   5 .. contents::
   6    :local:
   7
   8 .. _amdgpu_syn_instructions:
   9
  10 Instructions
  11 ============
  12
  13 Syntax
  14 ~~~~~~
  15
  16 An instruction has the following syntax:
  17
  18     ``<``\ *opcode mnemonic*\ ``>    <``\ *operand0*\ ``>, <``\ *operand1*\ ``>,...    <``\ *modifier0*\ ``> <``\ *modifier1*\ ``>...``
  19
  20 :doc:`Operands<AMDGPUOperandSyntax>` are normally comma-separated while
  21 :doc:`modifiers<AMDGPUModifierSyntax>` are space-separated.
  22
  23 The order of *operands* and *modifiers* is fixed.
  24 Most *modifiers* are optional and may be omitted.
  25
  26 .. _amdgpu_syn_instruction_mnemo:
  27
  28 Opcode Mnemonic
  29 ~~~~~~~~~~~~~~~
  30
  31 Opcode mnemonic describes opcode semantics and may include one or more suffices in this order:
  32
  33 * :ref:`Destination operand type suffix<amdgpu_syn_instruction_type>`.
  34 * :ref:`Source operand type suffix<amdgpu_syn_instruction_type>`.
  35 * :ref:`Encoding suffix<amdgpu_syn_instruction_enc>`.
  36
  37 .. _amdgpu_syn_instruction_type:
  38
  39 Type and Size Suffices
  40 ~~~~~~~~~~~~~~~~~~~~~~
  41
  42 Instructions which operate with data have an implied type of *data* operands.
  43 This data type is specified as a suffix of instruction mnemonic.
  44
  45 There are instructions which have 2 type suffices:
  46 the first is the data type of the destination operand,
  47 the second is the data type of source *data* operand(s).
  48
  49 Note that data type specified by an instruction does not apply
  50 to other kinds of operands such as *addresses*, *offsets* and so on.
  51
  52 The following table enumerates the most frequently used type suffices.
  53
  54     ============================================ ======================= =================
  55     Type Suffices                                Packed instruction?     Data Type
  56     ============================================ ======================= =================
  57     _b512, _b256, _b128, _b64, _b32, _b16, _b8   No                      Bits.
  58     _u64, _u32, _u16, _u8                        No                      Unsigned integer.
  59     _i64, _i32, _i16, _i8                        No                      Signed integer.
  60     _f64, _f32, _f16                             No                      Floating-point.
  61     _b16, _u16, _i16, _f16                       Yes                     Packed.
  62     ============================================ ======================= =================
  63
  64 Instructions which have no type suffices are assumed to operate with typeless data.
  65 The size of data is specified by size suffices:
  66
  67     ================= =================== =====================================
  68     Size Suffix       Implied data type   Required register size in dwords
  69     ================= =================== =====================================
  70     \-                b32                 1
  71     x2                b64                 2
  72     x3                b96                 3
  73     x4                b128                4
  74     x8                b256                8
  75     x16               b512                16
  76     x                 b32                 1
  77     xy                b64                 2
  78     xyz               b96                 3
  79     xyzw              b128                4
  80     d16_x             b16                 1
  81     d16_xy            b16x2               2 for GFX8.0, 1 for GFX8.1 and GFX9
  82     d16_xyz           b16x3               3 for GFX8.0, 2 for GFX8.1 and GFX9
  83     d16_xyzw          b16x4               4 for GFX8.0, 2 for GFX8.1 and GFX9
  84     ================= =================== =====================================
  85
  86 .. WARNING::
  87     There are exceptions from rules described above.
  88     Operands which have type different from type specified by the opcode are
  89     :ref:`tagged<amdgpu_syn_instruction_operand_tags>` in the description.
  90
  91 Examples of instructions with different types of source and destination operands:
  92
  93 .. parsed-literal::
  94
  95     s_bcnt0_i32_b64
  96     v_cvt_f32_u32
  97
  98 Examples of instructions with one data type:
  99
 100 .. parsed-literal::
 101
 102     v_max3_f32
 103     v_max3_i16
 104
 105 Examples of instructions which operate with packed data:
 106
 107 .. parsed-literal::
 108
 109     v_pk_add_u16
 110     v_pk_add_i16
 111     v_pk_add_f16
 112
 113 Examples of typeless instructions which operate on b128 data:
 114
 115 .. parsed-literal::
 116
 117     buffer_store_dwordx4
 118     flat_load_dwordx4
 119
 120 .. _amdgpu_syn_instruction_enc:
 121
 122 Encoding Suffices
 123 ~~~~~~~~~~~~~~~~~
 124
 125 Most *VOP1*, *VOP2* and *VOPC* instructions have several variants:
 126 they may also be encoded in *VOP3*, *DPP* and *SDWA* formats.
 127
 128 The assembler will automatically use optimal encoding based on instruction operands.
 129 To force specific encoding, one can add a suffix to the opcode of the instruction:
 130
 131     =================================================== =================
 132     Encoding                                            Encoding Suffix
 133     =================================================== =================
 134     Native 32-bit encoding (*VOP1*, *VOP2* or *VOPC*)   _e32
 135     *VOP3* (64-bit) encoding                            _e64
 136     *DPP* encoding                                      _dpp
 137     *SDWA* encoding                                     _sdwa
 138     =================================================== =================
 139
 140 These suffices are used in this reference to indicate the assumed encoding.
 141 When no suffix is specified, a native encoding is implied.
 142
 143 Operands
 144 ========
 145
 146 Syntax
 147 ~~~~~~
 148
 149 Syntax of most operands is described :doc:`in this document<AMDGPUOperandSyntax>`.
 150
 151 For detailed information about operands follow *operand links* in GPU-specific documents:
 152
 153 * :doc:`GFX7<AMDGPU/AMDGPUAsmGFX7>`
 154 * :doc:`GFX8<AMDGPU/AMDGPUAsmGFX8>`
 155 * :doc:`GFX9<AMDGPU/AMDGPUAsmGFX9>`
 156 * :doc:`GFX10<AMDGPU/AMDGPUAsmGFX10>`
 157
 158 Modifiers
 159 =========
 160
 161 Syntax
 162 ~~~~~~
 163
 164 Syntax of modifiers is described :doc:`in this document<AMDGPUModifierSyntax>`.
 165
 166 Information about modifiers supported for individual instructions may be found in GPU-specific documents:
 167
 168 * :doc:`GFX7<AMDGPU/AMDGPUAsmGFX7>`
 169 * :doc:`GFX8<AMDGPU/AMDGPUAsmGFX8>`
 170 * :doc:`GFX9<AMDGPU/AMDGPUAsmGFX9>`
 171 * :doc:`GFX10<AMDGPU/AMDGPUAsmGFX10>`
 172