# 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.
