1 =========================
2 AMDGPU Instruction Syntax
3 =========================
8 .. _amdgpu_syn_instructions:
16 An instruction has the following syntax:
18 ``<``\ *opcode mnemonic*\ ``> <``\ *operand0*\ ``>, <``\ *operand1*\ ``>,... <``\ *modifier0*\ ``> <``\ *modifier1*\ ``>...``
20 :doc:`Operands<AMDGPUOperandSyntax>` are normally comma-separated while
21 :doc:`modifiers<AMDGPUModifierSyntax>` are space-separated.
23 The order of *operands* and *modifiers* is fixed.
24 Most *modifiers* are optional and may be omitted.
26 .. _amdgpu_syn_instruction_mnemo:
31 Opcode mnemonic describes opcode semantics and may include one or more suffices in this order:
33 * :ref:`Packing suffix<amdgpu_syn_instruction_pk>`.
34 * :ref:`Destination operand type suffix<amdgpu_syn_instruction_type>`.
35 * :ref:`Source operand type suffix<amdgpu_syn_instruction_type>`.
36 * :ref:`Encoding suffix<amdgpu_syn_instruction_enc>`.
38 .. _amdgpu_syn_instruction_pk:
43 Most instructions which operate on packed data have a *_pk* suffix.
44 Unless otherwise :ref:`noted<amdgpu_syn_instruction_operand_tags>`,
45 these instructions operate on and produce packed data composed of
46 two values. The type of values is indicated by
47 :ref:`type suffices<amdgpu_syn_instruction_type>`.
49 For example, the following instruction sums up two pairs of f16 values
50 and produces a pair of f16 values:
54 v_pk_add_f16 v1, v2, v3 // Each operand has f16x2 type
56 .. _amdgpu_syn_instruction_type:
58 Type and Size Suffices
59 ~~~~~~~~~~~~~~~~~~~~~~
61 Instructions which operate with data have an implied type of *data* operands.
62 This data type is specified as a suffix of instruction mnemonic.
64 There are instructions which have 2 type suffices:
65 the first is the data type of the destination operand,
66 the second is the data type of source *data* operand(s).
68 Note that data type specified by an instruction does not apply
69 to other kinds of operands such as *addresses*, *offsets* and so on.
71 The following table enumerates the most frequently used type suffices.
73 ============================================ ======================= ============================
74 Type Suffices Packed instruction? Data Type
75 ============================================ ======================= ============================
76 _b512, _b256, _b128, _b64, _b32, _b16, _b8 No Bits.
77 _u64, _u32, _u16, _u8 No Unsigned integer.
78 _i64, _i32, _i16, _i8 No Signed integer.
79 _f64, _f32, _f16 No Floating-point.
80 _b16, _u16, _i16, _f16 Yes Packed (b16x2, u16x2, etc).
81 ============================================ ======================= ============================
83 Instructions which have no type suffices are assumed to operate with typeless data.
84 The size of data is specified by size suffices:
86 ================= =================== =====================================
87 Size Suffix Implied data type Required register size in dwords
88 ================= =================== =====================================
100 d16_xy b16x2 2 for GFX8.0, 1 for GFX8.1 and GFX9+
101 d16_xyz b16x3 3 for GFX8.0, 2 for GFX8.1 and GFX9+
102 d16_xyzw b16x4 4 for GFX8.0, 2 for GFX8.1 and GFX9+
103 ================= =================== =====================================
106 There are exceptions from rules described above.
107 Operands which have type different from type specified by the opcode are
108 :ref:`tagged<amdgpu_syn_instruction_operand_tags>` in the description.
110 Examples of instructions with different types of source and destination operands:
117 Examples of instructions with one data type:
124 Examples of instructions which operate with packed data:
132 Examples of typeless instructions which operate on b128 data:
139 .. _amdgpu_syn_instruction_enc:
144 Most *VOP1*, *VOP2* and *VOPC* instructions have several variants:
145 they may also be encoded in *VOP3*, *DPP* and *SDWA* formats.
147 The assembler will automatically use optimal encoding based on instruction operands.
148 To force specific encoding, one can add a suffix to the opcode of the instruction:
150 =================================================== =================
151 Encoding Encoding Suffix
152 =================================================== =================
153 *VOP1*, *VOP2* and *VOPC* (32-bit) encoding _e32
154 *VOP3* (64-bit) encoding _e64
156 *SDWA* encoding _sdwa
157 =================================================== =================
159 These suffices are used in this reference to indicate the assumed encoding.
160 When no suffix is specified, native instruction encoding is implied.
168 Syntax of generic operands is described :doc:`in this document<AMDGPUOperandSyntax>`.
170 For detailed information about operands follow *operand links* in GPU-specific documents:
172 * :doc:`GFX7<AMDGPU/AMDGPUAsmGFX7>`
173 * :doc:`GFX8<AMDGPU/AMDGPUAsmGFX8>`
174 * :doc:`GFX9<AMDGPU/AMDGPUAsmGFX9>`
175 * :doc:`GFX10<AMDGPU/AMDGPUAsmGFX10>`
183 Syntax of modifiers is described :doc:`in this document<AMDGPUModifierSyntax>`.
185 Information about modifiers supported for individual instructions may be found in GPU-specific documents:
187 * :doc:`GFX7<AMDGPU/AMDGPUAsmGFX7>`
188 * :doc:`GFX8<AMDGPU/AMDGPUAsmGFX8>`
189 * :doc:`GFX9<AMDGPU/AMDGPUAsmGFX9>`
190 * :doc:`GFX10<AMDGPU/AMDGPUAsmGFX10>`