Revert r371023 "[lib/ObjectYAML] - Stop calling error(1) when mapping the st_other...
[llvm-complete.git] / docs / AMDGPUInstructionSyntax.rst
blob588635023cbf7e904368f5a45289191d01ea0698
1 =========================
2 AMDGPU Instruction Syntax
3 =========================
5 .. contents::
6    :local:
8 .. _amdgpu_syn_instructions:
10 Instructions
11 ============
13 Syntax
14 ~~~~~~
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:
28 Opcode Mnemonic
29 ~~~~~~~~~~~~~~~
31 Opcode mnemonic describes opcode semantics and may include one or more suffices in this order:
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>`.
37 .. _amdgpu_syn_instruction_type:
39 Type and Size Suffices
40 ~~~~~~~~~~~~~~~~~~~~~~
42 Instructions which operate with data have an implied type of *data* operands.
43 This data type is specified as a suffix of instruction mnemonic.
45 There are instructions which have 2 type suffices:
46 the first is the data type of the destination operand,
47 the second is the data type of source *data* operand(s).
49 Note that data type specified by an instruction does not apply
50 to other kinds of operands such as *addresses*, *offsets* and so on.
52 The following table enumerates the most frequently used type suffices.
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     ============================================ ======================= =================
64 Instructions which have no type suffices are assumed to operate with typeless data.
65 The size of data is specified by size suffices:
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     ================= =================== =====================================
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.
91 Examples of instructions with different types of source and destination operands:
93 .. parsed-literal::
95     s_bcnt0_i32_b64
96     v_cvt_f32_u32
98 Examples of instructions with one data type:
100 .. parsed-literal::
102     v_max3_f32
103     v_max3_i16
105 Examples of instructions which operate with packed data:
107 .. parsed-literal::
109     v_pk_add_u16
110     v_pk_add_i16
111     v_pk_add_f16
113 Examples of typeless instructions which operate on b128 data:
115 .. parsed-literal::
117     buffer_store_dwordx4
118     flat_load_dwordx4
120 .. _amdgpu_syn_instruction_enc:
122 Encoding Suffices
123 ~~~~~~~~~~~~~~~~~
125 Most *VOP1*, *VOP2* and *VOPC* instructions have several variants:
126 they may also be encoded in *VOP3*, *DPP* and *SDWA* formats.
128 The assembler will automatically use optimal encoding based on instruction operands.
129 To force specific encoding, one can add a suffix to the opcode of the instruction:
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     =================================================== =================
140 These suffices are used in this reference to indicate the assumed encoding.
141 When no suffix is specified, a native encoding is implied.
143 Operands
144 ========
146 Syntax
147 ~~~~~~
149 Syntax of most operands is described :doc:`in this document<AMDGPUOperandSyntax>`.
151 For detailed information about operands follow *operand links* in GPU-specific documents:
153 * :doc:`GFX7<AMDGPU/AMDGPUAsmGFX7>`
154 * :doc:`GFX8<AMDGPU/AMDGPUAsmGFX8>`
155 * :doc:`GFX9<AMDGPU/AMDGPUAsmGFX9>`
156 * :doc:`GFX10<AMDGPU/AMDGPUAsmGFX10>`
158 Modifiers
159 =========
161 Syntax
162 ~~~~~~
164 Syntax of modifiers is described :doc:`in this document<AMDGPUModifierSyntax>`.
166 Information about modifiers supported for individual instructions may be found in GPU-specific documents:
168 * :doc:`GFX7<AMDGPU/AMDGPUAsmGFX7>`
169 * :doc:`GFX8<AMDGPU/AMDGPUAsmGFX8>`
170 * :doc:`GFX9<AMDGPU/AMDGPUAsmGFX9>`
171 * :doc:`GFX10<AMDGPU/AMDGPUAsmGFX10>`