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 mimics the :ref:`syntax of assembler instructions<amdgpu_syn_instructions>`
  16 except that instead of real operands and modifiers it provides references to their description.
  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>`\ ``>  <``\ :ref:`operands description<amdgpu_syn_instruction_operands_notation>`\ ``>  <``\ :ref:`modifiers description<amdgpu_syn_instruction_modifiers_notation>`\ ``>``
  27
  28 .. _amdgpu_syn_opcode_notation:
  29
  30 Opcode
  31 ======
  32
  33 Notation
  34 ~~~~~~~~
  35
  36 TBD
  37
  38 .. _amdgpu_syn_instruction_operands_notation:
  39
  40 Operands
  41 ========
  42
  43 An instruction may have zero or more *operands*. They are comma-separated in the description:
  44
  45     ``<``\ :ref:`description of operand 0<amdgpu_syn_instruction_operand_notation>`\ ``>, <``\ :ref:`description of operand 1<amdgpu_syn_instruction_operand_notation>`\ ``>, ...``
  46
  47 The order of *operands* is fixed. *Operands* cannot be omitted
  48 except for special cases described below.
  49
  50 .. _amdgpu_syn_instruction_operand_notation:
  51
  52 Notation
  53 ~~~~~~~~
  54
  55 An operand is described using the following notation:
  56
  57     *<name><tag0><tag1>...*
  58
  59 Where:
  60
  61 * *name* is a link to a description of the operand.
  62 * *tags* are optional. They are used to indicate special operand properties:
  63
  64 .. _amdgpu_syn_instruction_operand_tags:
  65
  66     ============== =================================================================================
  67     Operand tag    Meaning
  68     ============== =================================================================================
  69     :opt           An optional operand.
  70     :m             An operand which may be used with
  71                    :ref:`VOP3 operand modifiers<amdgpu_synid_vop3_operand_modifiers>` or
  72                    :ref:`SDWA operand modifiers<amdgpu_synid_sdwa_operand_modifiers>`.
  73     :dst           An input operand which may also serve as a destination
  74                    if :ref:`glc<amdgpu_synid_glc>` modifier is specified.
  75     :fx            This is an *f32* or *f16* operand depending on
  76                    :ref:`m_op_sel_hi<amdgpu_synid_mad_mix_op_sel_hi>` modifier.
  77     :<type>        Operand *type* differs from *type*
  78                    :ref:`implied by the opcode name<amdgpu_syn_instruction_type>`.
  79                    This tag specifies actual operand *type*.
  80     ============== =================================================================================
  81
  82 Examples:
  83
  84 .. parsed-literal::
  85
  86     src1:m             // src1 operand may be used with operand modifiers
  87     vdata:dst          // vdata operand may be used as both source and destination
  88     vdst:u32           // vdst operand has u32 type
  89
  90 .. _amdgpu_syn_instruction_modifiers_notation:
  91
  92 Modifiers
  93 =========
  94
  95 An instruction may have zero or more optional *modifiers*. They are space-separated in the description:
  96
  97     ``<``\ :ref:`description of modifier 0<amdgpu_syn_instruction_modifier_notation>`\ ``> <``\ :ref:`description of modifier 1<amdgpu_syn_instruction_modifier_notation>`\ ``> ...``
  98
  99 The order of *modifiers* is fixed.
 100
 101 .. _amdgpu_syn_instruction_modifier_notation:
 102
 103 Notation
 104 ~~~~~~~~
 105
 106 A *modifier* is described using the following notation:
 107
 108     *<name>*
 109
 110 Where *name* is a link to a description of the *modifier*.