========================= AMDGPU Instruction Syntax ========================= .. contents:: :local: .. _amdgpu_syn_instructions: Instructions ============ Syntax ~~~~~~ Syntax of Regular Instructions ------------------------------ An instruction has the following syntax: | ``<``\ *opcode mnemonic*\ ``> <``\ *operand0*\ ``>, <``\ *operand1*\ ``>,... <``\ *modifier0*\ ``> <``\ *modifier1*\ ``>...`` :doc:`Operands` are normally comma-separated, while :doc:`modifiers` 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`. * :ref:`Destination operand type suffix`. * :ref:`Source operand type suffix`. * :ref:`Encoding suffix`. .. _amdgpu_syn_instruction_pk: Packing Suffix ~~~~~~~~~~~~~~ Most instructions which operate on packed data have a *_pk* suffix. Unless otherwise :ref:`noted`, these instructions operate on and produce packed data composed of two values. The type of values is indicated by :ref:`type suffices`. 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` 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 :doc:`in this document`. For detailed information about operands, follow *operand links* in GPU-specific documents. Modifiers ========= Syntax ~~~~~~ The syntax of modifiers is described :doc:`in this document`. Information about modifiers supported for individual instructions may be found in GPU-specific documents.