| # AMDGPU Instructions Notation | |
| (amdgpu_syn_instruction_notation)= | |
| ## Introduction | |
| This is an overview of notation used to describe the syntax of AMDGPU assembler instructions. | |
| This notation looks a lot like the {ref}`syntax of assembler instructions<amdgpu_syn_instructions>`, | |
| except that instead of real operands and modifiers, it uses references to their descriptions. | |
| ## Instructions | |
| ### Notation | |
| This is the notation used to describe AMDGPU instructions: | |
| \<{ref}`opcode description <amdgpu_syn_opcode_notation>`\> \<{ref}`operands description <amdgpu_syn_instruction_operands_notation>`\> \<{ref}`modifiers description <amdgpu_syn_instruction_modifiers_notation>`\> | |
| (amdgpu_syn_opcode_notation)= | |
| ## Opcode | |
| ### Notation | |
| TBD | |
| (amdgpu_syn_instruction_operands_notation)= | |
| ## Operands | |
| An instruction may have zero or more *operands*. They are comma-separated in the description: | |
| \<{ref}`description of operand 0 <amdgpu_syn_instruction_operand_notation>`\>, \<{ref}`description of operand 1 <amdgpu_syn_instruction_operand_notation>`\>, `...` | |
| The order of *operands* is fixed. *Operands* cannot be omitted | |
| except for special cases described below. | |
| (amdgpu_syn_instruction_operand_notation)= | |
| ### Notation | |
| An operand is described using the following notation: | |
| > *\<kind>\<name>\<tag0>\<tag1>...* | |
| Where: | |
| - *kind* is an optional prefix describing operand {ref}`kind<amdgpu_syn_instruction_operand_kinds>`. | |
| - *name* is a link to a description of the operand. | |
| - *tags* are optional. They are used to indicate | |
| {ref}`special operand properties<amdgpu_syn_instruction_operand_tags>`. | |
| (amdgpu_syn_instruction_operand_kinds)= | |
| #### Operand Kinds | |
| Operand kind indicates which values are accepted by the operand. | |
| - Operands which only accept *vector* registers are labelled with 'v' prefix. | |
| - Operands which only accept *scalar* registers and values are labelled with 's' prefix. | |
| - Operands which accept any registers and values have no prefix. | |
| Examples: | |
| ``` | |
| vdata // operand only accepts vector registers | |
| sdst // operand only accepts scalar registers | |
| src1 // operand accepts vector registers, scalar registers, and scalar values | |
| ``` | |
| (amdgpu_syn_instruction_operand_tags)= | |
| #### Operand Tags | |
| Operand tags indicate special operand properties. | |
| | Operand tag | Meaning | | |
| | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | |
| | :opt | An optional operand. | | |
| | :m | An operand which may be used with operand modifiers {ref}`abs<amdgpu_synid_abs>`, {ref}`neg<amdgpu_synid_neg>` or {ref}`sext<amdgpu_synid_sext>`. | | |
| | :dst | An input operand which is also used as a destination if {ref}`glc<amdgpu_synid_glc>` modifier is specified. | | |
| | :fx | This is a *f32* or *f16* operand, depending on {ref}`m_op_sel_hi<amdgpu_synid_mad_mix_op_sel_hi>` modifier. | | |
| | :\<type> | The operand *type* differs from the *type* {ref}`implied by the opcode name<amdgpu_syn_instruction_type>`. This tag specifies the actual operand *type*. | | |
| Examples: | |
| ``` | |
| src1:m // src1 operand may be used with operand modifiers | |
| vdata:dst // vdata operand may be used as both source and destination | |
| vdst:u32 // vdst operand has u32 type | |
| ``` | |
| (amdgpu_syn_instruction_modifiers_notation)= | |
| ## Modifiers | |
| An instruction may have zero or more optional *modifiers*. They are space-separated in the description: | |
| \<{ref}`description of modifier 0 <amdgpu_syn_instruction_modifier_notation>`\> \<{ref}`description of modifier 1 <amdgpu_syn_instruction_modifier_notation>`\> `...` | |
| The order of *modifiers* is fixed. | |
| (amdgpu_syn_instruction_modifier_notation)= | |
| ### Notation | |
| A *modifier* is described using the following notation: | |
| > *\<name>* | |
| Where the *name* is a link to a description of the *modifier*. |