1=========================
2AMDGPU Instruction Syntax
3=========================
4
5.. contents::
6   :local:
7
8.. _amdgpu_syn_instructions:
9
10Instructions
11============
12
13Syntax
14~~~~~~
15
16An 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
23The order of *operands* and *modifiers* is fixed.
24Most *modifiers* are optional and may be omitted.
25
26.. _amdgpu_syn_instruction_mnemo:
27
28Opcode Mnemonic
29~~~~~~~~~~~~~~~
30
31Opcode mnemonic describes opcode semantics and may include one or more suffices in this order:
32
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>`.
37
38.. _amdgpu_syn_instruction_pk:
39
40Packing Suffix
41~~~~~~~~~~~~~~
42
43Most instructions which operate on packed data have a *_pk* suffix.
44Unless otherwise :ref:`noted<amdgpu_syn_instruction_operand_tags>`,
45these instructions operate on and produce packed data composed of
46two values. The type of values is indicated by
47:ref:`type suffices<amdgpu_syn_instruction_type>`.
48
49For example, the following instruction sums up two pairs of f16 values
50and produces a pair of f16 values:
51
52.. parsed-literal::
53
54    v_pk_add_f16 v1, v2, v3     // Each operand has f16x2 type
55
56.. _amdgpu_syn_instruction_type:
57
58Type and Size Suffices
59~~~~~~~~~~~~~~~~~~~~~~
60
61Instructions which operate with data have an implied type of *data* operands.
62This data type is specified as a suffix of instruction mnemonic.
63
64There are instructions which have 2 type suffices:
65the first is the data type of the destination operand,
66the second is the data type of source *data* operand(s).
67
68Note that data type specified by an instruction does not apply
69to other kinds of operands such as *addresses*, *offsets* and so on.
70
71The following table enumerates the most frequently used type suffices.
72
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    ============================================ ======================= ============================
82
83Instructions which have no type suffices are assumed to operate with typeless data.
84The size of data is specified by size suffices:
85
86    ================= =================== =====================================
87    Size Suffix       Implied data type   Required register size in dwords
88    ================= =================== =====================================
89    \-                b32                 1
90    x2                b64                 2
91    x3                b96                 3
92    x4                b128                4
93    x8                b256                8
94    x16               b512                16
95    x                 b32                 1
96    xy                b64                 2
97    xyz               b96                 3
98    xyzw              b128                4
99    d16_x             b16                 1
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    ================= =================== =====================================
104
105.. WARNING::
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.
109
110Examples of instructions with different types of source and destination operands:
111
112.. parsed-literal::
113
114    s_bcnt0_i32_b64
115    v_cvt_f32_u32
116
117Examples of instructions with one data type:
118
119.. parsed-literal::
120
121    v_max3_f32
122    v_max3_i16
123
124Examples of instructions which operate with packed data:
125
126.. parsed-literal::
127
128    v_pk_add_u16
129    v_pk_add_i16
130    v_pk_add_f16
131
132Examples of typeless instructions which operate on b128 data:
133
134.. parsed-literal::
135
136    buffer_store_dwordx4
137    flat_load_dwordx4
138
139.. _amdgpu_syn_instruction_enc:
140
141Encoding Suffices
142~~~~~~~~~~~~~~~~~
143
144Most *VOP1*, *VOP2* and *VOPC* instructions have several variants:
145they may also be encoded in *VOP3*, *DPP* and *SDWA* formats.
146
147The assembler will automatically use optimal encoding based on instruction operands.
148To force specific encoding, one can add a suffix to the opcode of the instruction:
149
150    =================================================== =================
151    Encoding                                            Encoding Suffix
152    =================================================== =================
153    *VOP1*, *VOP2* and *VOPC* (32-bit) encoding         _e32
154    *VOP3* (64-bit) encoding                            _e64
155    *DPP* encoding                                      _dpp
156    *SDWA* encoding                                     _sdwa
157    =================================================== =================
158
159These suffices are used in this reference to indicate the assumed encoding.
160When no suffix is specified, native instruction encoding is implied.
161
162Operands
163========
164
165Syntax
166~~~~~~
167
168Syntax of generic operands is described :doc:`in this document<AMDGPUOperandSyntax>`.
169
170For detailed information about operands follow *operand links* in GPU-specific documents.
171
172Modifiers
173=========
174
175Syntax
176~~~~~~
177
178Syntax of modifiers is described :doc:`in this document<AMDGPUModifierSyntax>`.
179
180Information about modifiers supported for individual instructions may be found in GPU-specific documents.
181