| # AMDGPU Instruction Syntax | |
| (amdgpu_syn_instructions)= | |
| ## Instructions | |
| ### Syntax | |
| #### Syntax of Regular Instructions | |
| An instruction has the following syntax: | |
| > `<`*opcode mnemonic*`> <`*operand0*`>, | |
| > <`*operand1*`>,... <`*modifier0*`> <`*modifier1*`>...` | |
| [Operands](AMDGPUOperandSyntax.md) are normally comma-separated, while | |
| [modifiers](AMDGPUModifierSyntax.md) are space-separated. | |
| The order of *operands* and *modifiers* is fixed. | |
| Most *modifiers* are optional and may be omitted. | |
| #### Syntax of VOPD Instructions | |
| *VOPDX* and *VOPDY* instructions must be concatenated with the :: operator to form a single *VOPD* instruction: | |
| > `<`*VOPDX instruction*`> :: <`*VOPDY instruction*`>` | |
| An example: | |
| :::{parsed-literal} | |
| v_dual_add_f32 v255, v255, v2 :: v_dual_fmaak_f32 v6, v2, v3, 1.0 | |
| ::: | |
| Note that *VOPDX* and *VOPDY* instructions cannot be used as separate opcodes. | |
| (amdgpu_syn_instruction_mnemo)= | |
| ### Opcode Mnemonic | |
| Opcode mnemonic describes opcode semantics | |
| and may include one or more suffices in this order: | |
| - {ref}`Packing suffix<amdgpu_syn_instruction_pk>`. | |
| - {ref}`Destination operand type suffix<amdgpu_syn_instruction_type>`. | |
| - {ref}`Source operand type suffix<amdgpu_syn_instruction_type>`. | |
| - {ref}`Encoding suffix<amdgpu_syn_instruction_enc>`. | |
| (amdgpu_syn_instruction_pk)= | |
| ### Packing Suffix | |
| Most instructions which operate on packed data have a *\_pk* suffix. | |
| Unless otherwise {ref}`noted<amdgpu_syn_instruction_operand_tags>`, | |
| these instructions operate on and produce packed data composed of | |
| two values. The type of values is indicated by | |
| {ref}`type suffices<amdgpu_syn_instruction_type>`. | |
| For example, the following instruction sums up two pairs of f16 values | |
| and produces a pair of f16 values: | |
| :::{parsed-literal} | |
| v_pk_add_f16 v1, v2, v3 // Each operand has f16x2 type | |
| ::: | |
| (amdgpu_syn_instruction_type)= | |
| ### Type and Size Suffices | |
| Instructions which operate with data have an implied type of *data* operands. | |
| This data type is specified as a suffix of instruction mnemonic. | |
| There are instructions which have 2 type suffices: | |
| the first is the data type of the destination operand, | |
| the second is the data type of source *data* operand(s). | |
| Note that data type specified by an instruction does not apply | |
| to other kinds of operands such as *addresses*, *offsets* and so on. | |
| The following table enumerates the most frequently used type suffices. | |
| | Type Suffices | Packed instruction? | Data Type | | |
| | ------------------------------------------------- | ------------------- | --------------------------- | | |
| | \_b512, \_b256, \_b128, \_b64, \_b32, \_b16, \_b8 | No | Bits. | | |
| | \_u64, \_u32, \_u16, \_u8 | No | Unsigned integer. | | |
| | \_i64, \_i32, \_i16, \_i8 | No | Signed integer. | | |
| | \_f64, \_f32, \_f16 | No | Floating-point. | | |
| | \_b16, \_u16, \_i16, \_f16 | Yes | Packed (b16x2, u16x2, etc). | | |
| Instructions which have no type suffices are assumed to operate with typeless data. | |
| The size of typeless data is specified by size suffices: | |
| | Size Suffix | Implied data type | Required register size in dwords | | |
| | --------------- | ----------------- | ------------------------------------ | | |
| | - | b32 | 1 | | |
| | x2 | b64 | 2 | | |
| | x3 | b96 | 3 | | |
| | x4 | b128 | 4 | | |
| | x8 | b256 | 8 | | |
| | x16 | b512 | 16 | | |
| | x | b32 | 1 | | |
| | xy | b64 | 2 | | |
| | xyz | b96 | 3 | | |
| | xyzw | b128 | 4 | | |
| | d16_x | b16 | 1 | | |
| | d16_xy | b16x2 | 2 for GFX8.0, 1 for GFX8.1 and GFX9+ | | |
| | d16_xyz | b16x3 | 3 for GFX8.0, 2 for GFX8.1 and GFX9+ | | |
| | d16_xyzw | b16x4 | 4 for GFX8.0, 2 for GFX8.1 and GFX9+ | | |
| | d16_format_x | b16 | 1 | | |
| | d16_format_xy | b16x2 | 1 | | |
| | d16_format_xyz | b16x3 | 2 | | |
| | d16_format_xyzw | b16x4 | 2 | | |
| :::{WARNING} | |
| There are exceptions to the rules described above. | |
| Operands which have a type different from the type specified by the opcode are | |
| {ref}`tagged<amdgpu_syn_instruction_operand_tags>` in the description. | |
| ::: | |
| Examples of instructions with different types of source and destination operands: | |
| :::{parsed-literal} | |
| s_bcnt0_i32_b64 | |
| v_cvt_f32_u32 | |
| ::: | |
| Examples of instructions with one data type: | |
| :::{parsed-literal} | |
| v_max3_f32 | |
| v_max3_i16 | |
| ::: | |
| Examples of instructions which operate with packed data: | |
| :::{parsed-literal} | |
| v_pk_add_u16 | |
| v_pk_add_i16 | |
| v_pk_add_f16 | |
| ::: | |
| Examples of typeless instructions which operate on b128 data: | |
| :::{parsed-literal} | |
| buffer_store_dwordx4 | |
| flat_load_dwordx4 | |
| ::: | |
| (amdgpu_syn_instruction_enc)= | |
| ### Encoding Suffices | |
| Most *VOP1*, *VOP2* and *VOPC* instructions have several variants: | |
| they may also be encoded in *VOP3*, *DPP* and *SDWA* formats. | |
| The assembler selects an optimal encoding automatically | |
| based on instruction operands and modifiers, | |
| unless a specific encoding is explicitly requested. | |
| To force specific encoding, one can add a suffix to the opcode of the instruction: | |
| | Encoding | Encoding Suffix | | |
| | ------------------------------------------- | --------------- | | |
| | *VOP1*, *VOP2* and *VOPC* (32-bit) encoding | \_e32 | | |
| | *VOP3* (64-bit) encoding | \_e64 | | |
| | *DPP* encoding | \_dpp | | |
| | *SDWA* encoding | \_sdwa | | |
| | *VOP3 DPP* encoding | \_e64_dpp | | |
| This reference uses encoding suffices to specify which encoding is implied. | |
| When no suffix is specified, native instruction encoding is assumed. | |
| ## Operands | |
| ### Syntax | |
| The syntax of generic operands is described [in this document](AMDGPUOperandSyntax.md). | |
| For detailed information about operands, follow *operand links* in GPU-specific documents. | |
| ## Modifiers | |
| ### Syntax | |
| The syntax of modifiers is described [in this document](AMDGPUModifierSyntax.md). | |
| Information about modifiers supported for individual instructions | |
| may be found in GPU-specific documents. |