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:`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
39Type and Size Suffices
40~~~~~~~~~~~~~~~~~~~~~~
41
42Instructions which operate with data have an implied type of *data* operands.
43This data type is specified as a suffix of instruction mnemonic.
44
45There are instructions which have 2 type suffices:
46the first is the data type of the destination operand,
47the second is the data type of source *data* operand(s).
48
49Note that data type specified by an instruction does not apply
50to other kinds of operands such as *addresses*, *offsets* and so on.
51
52The 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
64Instructions which have no type suffices are assumed to operate with typeless data.
65The 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
91Examples 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
98Examples of instructions with one data type:
99
100.. parsed-literal::
101
102    v_max3_f32
103    v_max3_i16
104
105Examples 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
113Examples 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
122Encoding Suffices
123~~~~~~~~~~~~~~~~~
124
125Most *VOP1*, *VOP2* and *VOPC* instructions have several variants:
126they may also be encoded in *VOP3*, *DPP* and *SDWA* formats.
127
128The assembler will automatically use optimal encoding based on instruction operands.
129To 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
140These suffices are used in this reference to indicate the assumed encoding.
141When no suffix is specified, a native encoding is implied.
142
143Operands
144========
145
146Syntax
147~~~~~~
148
149Syntax of most operands is described :doc:`in this document<AMDGPUOperandSyntax>`.
150
151For 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
157Modifiers
158=========
159
160Syntax
161~~~~~~
162
163Syntax of modifiers is described :doc:`in this document<AMDGPUModifierSyntax>`.
164
165Information about modifiers supported for individual instructions may be found in GPU-specific documents:
166
167* :doc:`GFX7<AMDGPU/AMDGPUAsmGFX7>`
168* :doc:`GFX8<AMDGPU/AMDGPUAsmGFX8>`
169* :doc:`GFX9<AMDGPU/AMDGPUAsmGFX9>`
170
171