llvm/docs/AMDGPUInstructionNotation.rst

   1 ============================
   2 AMDGPU Instructions Notation
   3 ============================
   4
   5 .. contents::
   6    :local:
   7
   8 .. _amdgpu_syn_instruction_notation:
   9
  10 Introduction
  11 ============
  12
  13 This is an overview of notation used to describe the syntax of AMDGPU assembler instructions.
  14
  15 This notation looks a lot like the :ref:`syntax of assembler instructions<amdgpu_syn_instructions>`,
  16 except that instead of real operands and modifiers, it uses references to their descriptions.
  17
  18 Instructions
  19 ============
  20
  21 Notation
  22 ~~~~~~~~
  23
  24 This is the notation used to describe AMDGPU instructions:
  25
  26   | ``<``\ :ref:`opcode description<amdgpu_syn_opcode_notation>`\ ``>
  27       <``\ :ref:`operands description<amdgpu_syn_instruction_operands_notation>`\ ``>
  28       <``\ :ref:`modifiers description<amdgpu_syn_instruction_modifiers_notation>`\ ``>``
  29
  30 .. _amdgpu_syn_opcode_notation:
  31
  32 Opcode
  33 ======
  34
  35 Notation
  36 ~~~~~~~~
  37
  38 TBD
  39
  40 .. _amdgpu_syn_instruction_operands_notation:
  41
  42 Operands
  43 ========
  44
  45 An instruction may have zero or more *operands*. They are comma-separated in the description:
  46
  47   | ``<``\ :ref:`description of operand 0<amdgpu_syn_instruction_operand_notation>`\ ``>,
  48       <``\ :ref:`description of operand 1<amdgpu_syn_instruction_operand_notation>`\ ``>, ...``
  49
  50 The order of *operands* is fixed. *Operands* cannot be omitted
  51 except for special cases described below.
  52
  53 .. _amdgpu_syn_instruction_operand_notation:
  54
  55 Notation
  56 ~~~~~~~~
  57
  58 An operand is described using the following notation:
  59
  60     *<kind><name><tag0><tag1>...*
  61
  62 Where:
  63
  64 * *kind* is an optional prefix describing operand :ref:`kind<amdgpu_syn_instruction_operand_kinds>`.
  65 * *name* is a link to a description of the operand.
  66 * *tags* are optional. They are used to indicate
  67   :ref:`special operand properties<amdgpu_syn_instruction_operand_tags>`.
  68
  69 .. _amdgpu_syn_instruction_operand_kinds:
  70
  71 Operand Kinds
  72 ^^^^^^^^^^^^^
  73
  74 Operand kind indicates which values are accepted by the operand.
  75
  76 * Operands which only accept *vector* registers are labelled with 'v' prefix.
  77 * Operands which only accept *scalar* registers and values are labelled with 's' prefix.
  78 * Operands which accept any registers and values have no prefix.
  79
  80 Examples:
  81
  82 .. parsed-literal::
  83
  84     vdata          // operand only accepts vector registers
  85     sdst           // operand only accepts scalar registers
  86     src1           // operand accepts vector registers, scalar registers, and scalar values
  87
  88 .. _amdgpu_syn_instruction_operand_tags:
  89
  90 Operand Tags
  91 ^^^^^^^^^^^^
  92
  93 Operand tags indicate special operand properties.
  94
  95     ============== =================================================================================
  96     Operand tag    Meaning
  97     ============== =================================================================================
  98     :opt           An optional operand.
  99     :m             An operand which may be used with operand modifiers
 100                    :ref:`abs<amdgpu_synid_abs>`, :ref:`neg<amdgpu_synid_neg>` or
 101                    :ref:`sext<amdgpu_synid_sext>`.
 102     :dst           An input operand which is also used as a destination
 103                    if :ref:`glc<amdgpu_synid_glc>` modifier is specified.
 104     :fx            This is a *f32* or *f16* operand, depending on
 105                    :ref:`m_op_sel_hi<amdgpu_synid_mad_mix_op_sel_hi>` modifier.
 106     :<type>        The operand *type* differs from the *type*
 107                    :ref:`implied by the opcode name<amdgpu_syn_instruction_type>`.
 108                    This tag specifies the actual operand *type*.
 109     ============== =================================================================================
 110
 111 Examples:
 112
 113 .. parsed-literal::
 114
 115     src1:m             // src1 operand may be used with operand modifiers
 116     vdata:dst          // vdata operand may be used as both source and destination
 117     vdst:u32           // vdst operand has u32 type
 118
 119 .. _amdgpu_syn_instruction_modifiers_notation:
 120
 121 Modifiers
 122 =========
 123
 124 An instruction may have zero or more optional *modifiers*. They are space-separated in the description:
 125
 126   | ``<``\ :ref:`description of modifier 0<amdgpu_syn_instruction_modifier_notation>`\ ``>
 127       <``\ :ref:`description of modifier 1<amdgpu_syn_instruction_modifier_notation>`\ ``> ...``
 128
 129 The order of *modifiers* is fixed.
 130
 131 .. _amdgpu_syn_instruction_modifier_notation:
 132
 133 Notation
 134 ~~~~~~~~
 135
 136 A *modifier* is described using the following notation:
 137
 138     *<name>*
 139
 140 Where the *name* is a link to a description of the *modifier*.