| ===================================== |
| Syntax of AMDGPU Instruction Operands |
| ===================================== |
| |
| .. contents:: |
| :local: |
| |
| Conventions |
| =========== |
| |
| The following notation is used throughout this document: |
| |
| =================== ============================================================================= |
| Notation Description |
| =================== ============================================================================= |
| {0..N} Any integer value in the range from 0 to N (inclusive). |
| <x> Syntax and meaning of *x* are explained elsewhere. |
| =================== ============================================================================= |
| |
| .. _amdgpu_syn_operands: |
| |
| Operands |
| ======== |
| |
| .. _amdgpu_synid_v: |
| |
| v (32-bit) |
| ---------- |
| |
| Vector registers. There are 256 32-bit vector registers. |
| |
| A sequence of *vector* registers may be used to operate with more than 32 bits of data. |
| |
| Assembler currently supports tuples with 1 to 12, 16 and 32 *vector* registers. |
| |
| =================================================== ==================================================================== |
| Syntax Description |
| =================================================== ==================================================================== |
| **v**\<N> A single 32-bit *vector* register. |
| |
| *N* must be a decimal |
| :ref:`integer number<amdgpu_synid_integer_number>`. |
| **v[**\ <N>\ **]** A single 32-bit *vector* register. |
| |
| *N* may be specified as an |
| :ref:`integer number<amdgpu_synid_integer_number>` |
| or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. |
| **v[**\ <N>:<K>\ **]** A sequence of (\ *K-N+1*\ ) *vector* registers. |
| |
| *N* and *K* may be specified as |
| :ref:`integer numbers<amdgpu_synid_integer_number>` |
| or :ref:`absolute expressions<amdgpu_synid_absolute_expression>`. |
| **[v**\ <N>, \ **v**\ <N+1>, ... **v**\ <K>\ **]** A sequence of (\ *K-N+1*\ ) *vector* registers. |
| |
| Register indices must be specified as decimal |
| :ref:`integer numbers<amdgpu_synid_integer_number>`. |
| =================================================== ==================================================================== |
| |
| Note: *N* and *K* must satisfy the following conditions: |
| |
| * *N* <= *K*. |
| * 0 <= *N* <= 255. |
| * 0 <= *K* <= 255. |
| * *K-N+1* must be in the range from 1 to 12 or equal to 16 or 32. |
| |
| GFX90A and GFX940 have an additional alignment requirement: |
| pairs of *vector* registers must be even-aligned |
| (first register must be even). |
| |
| Examples: |
| |
| .. parsed-literal:: |
| |
| v255 |
| v[0] |
| v[0:1] |
| v[1:1] |
| v[0:3] |
| v[2*2] |
| v[1-1:2-1] |
| [v252] |
| [v252,v253,v254,v255] |
| |
| .. _amdgpu_synid_nsa: |
| |
| **Non-Sequential Address (NSA) Syntax** |
| |
| GFX10+ *image* instructions may use special *NSA* (Non-Sequential Address) |
| syntax for *image addresses*: |
| |
| ===================================== ================================================= |
| Syntax Description |
| ===================================== ================================================= |
| **[Vm**, \ **Vn**, ... **Vk**\ **]** A sequence of 32-bit *vector* registers. |
| Each register may be specified using the syntax |
| defined :ref:`above<amdgpu_synid_v>`. |
| |
| In contrast with the standard syntax, registers |
| in *NSA* sequence are not required to have |
| consecutive indices. Moreover, the same register |
| may appear in the sequence more than once. |
| |
| GFX11+ has an additional limitation: if address |
| size occupies more than 5 dwords, registers |
| starting from the 5th element must be contiguous. |
| ===================================== ================================================= |
| |
| Examples: |
| |
| .. parsed-literal:: |
| |
| [v32,v1,v[2]] |
| [v[32],v[1:1],[v2]] |
| [v4,v4,v4,v4] |
| |
| .. _amdgpu_synid_v16: |
| |
| v (16-bit) |
| ---------- |
| |
| 16-bit vector registers. Each :ref:`32-bit vector register<amdgpu_synid_v>` is divided into two 16-bit low and high registers, so there are 512 16-bit vector registers. |
| |
| Only VOP3, VOP3P and VINTERP instructions may access all 512 registers (using :ref:`op_sel<amdgpu_synid_op_sel>` modifier). |
| VOP1, VOP2 and VOPC instructions may currently access only 128 low 16-bit registers using the syntax described below. |
| |
| .. WARNING:: This section is incomplete. The support of 16-bit registers in the assembler is still WIP. |
| |
| \ |
| =================================================== ==================================================================== |
| Syntax Description |
| =================================================== ==================================================================== |
| **v**\<N> A single 16-bit *vector* register (low half). |
| =================================================== ==================================================================== |
| |
| Note: *N* must satisfy the following conditions: |
| |
| * 0 <= *N* <= 127. |
| |
| Examples: |
| |
| .. parsed-literal:: |
| |
| v127 |
| |
| .. _amdgpu_synid_a: |
| |
| a |
| - |
| |
| Accumulator registers. There are 256 32-bit accumulator registers. |
| |
| A sequence of *accumulator* registers may be used to operate with more than 32 bits of data. |
| |
| Assembler currently supports tuples with 1 to 12, 16 and 32 *accumulator* registers. |
| |
| =================================================== ========================================================= ==================================================================== |
| Syntax Alternative Syntax (SP3) Description |
| =================================================== ========================================================= ==================================================================== |
| **a**\<N> **acc**\<N> A single 32-bit *accumulator* register. |
| |
| *N* must be a decimal |
| :ref:`integer number<amdgpu_synid_integer_number>`. |
| **a[**\ <N>\ **]** **acc[**\ <N>\ **]** A single 32-bit *accumulator* register. |
| |
| *N* may be specified as an |
| :ref:`integer number<amdgpu_synid_integer_number>` |
| or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. |
| **a[**\ <N>:<K>\ **]** **acc[**\ <N>:<K>\ **]** A sequence of (\ *K-N+1*\ ) *accumulator* registers. |
| |
| *N* and *K* may be specified as |
| :ref:`integer numbers<amdgpu_synid_integer_number>` |
| or :ref:`absolute expressions<amdgpu_synid_absolute_expression>`. |
| **[a**\ <N>, \ **a**\ <N+1>, ... **a**\ <K>\ **]** **[acc**\ <N>, \ **acc**\ <N+1>, ... **acc**\ <K>\ **]** A sequence of (\ *K-N+1*\ ) *accumulator* registers. |
| |
| Register indices must be specified as decimal |
| :ref:`integer numbers<amdgpu_synid_integer_number>`. |
| =================================================== ========================================================= ==================================================================== |
| |
| Note: *N* and *K* must satisfy the following conditions: |
| |
| * *N* <= *K*. |
| * 0 <= *N* <= 255. |
| * 0 <= *K* <= 255. |
| * *K-N+1* must be in the range from 1 to 12 or equal to 16 or 32. |
| |
| GFX90A and GFX940 have an additional alignment requirement: |
| pairs of *accumulator* registers must be even-aligned |
| (first register must be even). |
| |
| Examples: |
| |
| .. parsed-literal:: |
| |
| a255 |
| a[0] |
| a[0:1] |
| a[1:1] |
| a[0:3] |
| a[2*2] |
| a[1-1:2-1] |
| [a252] |
| [a252,a253,a254,a255] |
| |
| acc0 |
| acc[1] |
| [acc250] |
| [acc2,acc3] |
| |
| .. _amdgpu_synid_s: |
| |
| s |
| - |
| |
| Scalar 32-bit registers. The number of available *scalar* registers depends on the GPU: |
| |
| ======= ============================ |
| GPU Number of *scalar* registers |
| ======= ============================ |
| GFX7 104 |
| GFX8 102 |
| GFX9 102 |
| GFX10+ 106 |
| ======= ============================ |
| |
| A sequence of *scalar* registers may be used to operate with more than 32 bits of data. |
| Assembler currently supports tuples with 1 to 12, 16 and 32 *scalar* registers. |
| |
| Pairs of *scalar* registers must be even-aligned (first register must be even). |
| Sequences of 4 and more *scalar* registers must be quad-aligned. |
| |
| ======================================================== ==================================================================== |
| Syntax Description |
| ======================================================== ==================================================================== |
| **s**\ <N> A single 32-bit *scalar* register. |
| |
| *N* must be a decimal |
| :ref:`integer number<amdgpu_synid_integer_number>`. |
| |
| **s[**\ <N>\ **]** A single 32-bit *scalar* register. |
| |
| *N* may be specified as an |
| :ref:`integer number<amdgpu_synid_integer_number>` |
| or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. |
| **s[**\ <N>:<K>\ **]** A sequence of (\ *K-N+1*\ ) *scalar* registers. |
| |
| *N* and *K* may be specified as |
| :ref:`integer numbers<amdgpu_synid_integer_number>` |
| or :ref:`absolute expressions<amdgpu_synid_absolute_expression>`. |
| |
| **[s**\ <N>, \ **s**\ <N+1>, ... **s**\ <K>\ **]** A sequence of (\ *K-N+1*\ ) *scalar* registers. |
| |
| Register indices must be specified as decimal |
| :ref:`integer numbers<amdgpu_synid_integer_number>`. |
| ======================================================== ==================================================================== |
| |
| Note: *N* and *K* must satisfy the following conditions: |
| |
| * *N* must be properly aligned based on the sequence size. |
| * *N* <= *K*. |
| * 0 <= *N* < *SMAX*\ , where *SMAX* is the number of available *scalar* registers. |
| * 0 <= *K* < *SMAX*\ , where *SMAX* is the number of available *scalar* registers. |
| * *K-N+1* must be in the range from 1 to 12 or equal to 16 or 32. |
| |
| Examples: |
| |
| .. parsed-literal:: |
| |
| s0 |
| s[0] |
| s[0:1] |
| s[1:1] |
| s[0:3] |
| s[2*2] |
| s[1-1:2-1] |
| [s4] |
| [s4,s5,s6,s7] |
| |
| Examples of *scalar* registers with an invalid alignment: |
| |
| .. parsed-literal:: |
| |
| s[1:2] |
| s[2:5] |
| |
| .. _amdgpu_synid_trap: |
| |
| trap |
| ---- |
| |
| A set of trap handler registers: |
| |
| * :ref:`ttmp<amdgpu_synid_ttmp>` |
| * :ref:`tba<amdgpu_synid_tba>` |
| * :ref:`tma<amdgpu_synid_tma>` |
| |
| .. _amdgpu_synid_ttmp: |
| |
| ttmp |
| ---- |
| |
| Trap handler temporary scalar registers, 32-bits wide. |
| The number of available *ttmp* registers depends on the GPU: |
| |
| ======= =========================== |
| GPU Number of *ttmp* registers |
| ======= =========================== |
| GFX7 12 |
| GFX8 12 |
| GFX9 16 |
| GFX10+ 16 |
| ======= =========================== |
| |
| A sequence of *ttmp* registers may be used to operate with more than 32 bits of data. |
| Assembler currently supports tuples with 1 to 12 and 16 *ttmp* registers. |
| |
| Pairs of *ttmp* registers must be even-aligned (first register must be even). |
| Sequences of 4 and more *ttmp* registers must be quad-aligned. |
| |
| ============================================================= ==================================================================== |
| Syntax Description |
| ============================================================= ==================================================================== |
| **ttmp**\ <N> A single 32-bit *ttmp* register. |
| |
| *N* must be a decimal |
| :ref:`integer number<amdgpu_synid_integer_number>`. |
| **ttmp[**\ <N>\ **]** A single 32-bit *ttmp* register. |
| |
| *N* may be specified as an |
| :ref:`integer number<amdgpu_synid_integer_number>` |
| or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. |
| **ttmp[**\ <N>:<K>\ **]** A sequence of (\ *K-N+1*\ ) *ttmp* registers. |
| |
| *N* and *K* may be specified as |
| :ref:`integer numbers<amdgpu_synid_integer_number>` |
| or :ref:`absolute expressions<amdgpu_synid_absolute_expression>`. |
| **[ttmp**\ <N>, \ **ttmp**\ <N+1>, ... **ttmp**\ <K>\ **]** A sequence of (\ *K-N+1*\ ) *ttmp* registers. |
| |
| Register indices must be specified as decimal |
| :ref:`integer numbers<amdgpu_synid_integer_number>`. |
| ============================================================= ==================================================================== |
| |
| Note: *N* and *K* must satisfy the following conditions: |
| |
| * *N* must be properly aligned based on the sequence size. |
| * *N* <= *K*. |
| * 0 <= *N* < *TMAX*, where *TMAX* is the number of available *ttmp* registers. |
| * 0 <= *K* < *TMAX*, where *TMAX* is the number of available *ttmp* registers. |
| * *K-N+1* must be in the range from 1 to 12 or equal to 16. |
| |
| Examples: |
| |
| .. parsed-literal:: |
| |
| ttmp0 |
| ttmp[0] |
| ttmp[0:1] |
| ttmp[1:1] |
| ttmp[0:3] |
| ttmp[2*2] |
| ttmp[1-1:2-1] |
| [ttmp4] |
| [ttmp4,ttmp5,ttmp6,ttmp7] |
| |
| Examples of *ttmp* registers with an invalid alignment: |
| |
| .. parsed-literal:: |
| |
| ttmp[1:2] |
| ttmp[2:5] |
| |
| .. _amdgpu_synid_tba: |
| |
| tba |
| --- |
| |
| Trap base address, 64-bits wide. Holds the pointer to the current |
| trap handler program. |
| |
| ================== ======================================================================= ============= |
| Syntax Description Availability |
| ================== ======================================================================= ============= |
| tba 64-bit *trap base address* register. GFX7, GFX8 |
| [tba] 64-bit *trap base address* register (an SP3 syntax). GFX7, GFX8 |
| [tba_lo,tba_hi] 64-bit *trap base address* register (an SP3 syntax). GFX7, GFX8 |
| ================== ======================================================================= ============= |
| |
| High and low 32 bits of *trap base address* may be accessed as separate registers: |
| |
| ================== ======================================================================= ============= |
| Syntax Description Availability |
| ================== ======================================================================= ============= |
| tba_lo Low 32 bits of *trap base address* register. GFX7, GFX8 |
| tba_hi High 32 bits of *trap base address* register. GFX7, GFX8 |
| [tba_lo] Low 32 bits of *trap base address* register (an SP3 syntax). GFX7, GFX8 |
| [tba_hi] High 32 bits of *trap base address* register (an SP3 syntax). GFX7, GFX8 |
| ================== ======================================================================= ============= |
| |
| .. _amdgpu_synid_tma: |
| |
| tma |
| --- |
| |
| Trap memory address, 64-bits wide. |
| |
| ================= ======================================================================= ================== |
| Syntax Description Availability |
| ================= ======================================================================= ================== |
| tma 64-bit *trap memory address* register. GFX7, GFX8 |
| [tma] 64-bit *trap memory address* register (an SP3 syntax). GFX7, GFX8 |
| [tma_lo,tma_hi] 64-bit *trap memory address* register (an SP3 syntax). GFX7, GFX8 |
| ================= ======================================================================= ================== |
| |
| High and low 32 bits of *trap memory address* may be accessed as separate registers: |
| |
| ================= ======================================================================= ================== |
| Syntax Description Availability |
| ================= ======================================================================= ================== |
| tma_lo Low 32 bits of *trap memory address* register. GFX7, GFX8 |
| tma_hi High 32 bits of *trap memory address* register. GFX7, GFX8 |
| [tma_lo] Low 32 bits of *trap memory address* register (an SP3 syntax). GFX7, GFX8 |
| [tma_hi] High 32 bits of *trap memory address* register (an SP3 syntax). GFX7, GFX8 |
| ================= ======================================================================= ================== |
| |
| .. _amdgpu_synid_flat_scratch: |
| |
| flat_scratch |
| ------------ |
| |
| Flat scratch address, 64-bits wide. Holds the base address of scratch memory. |
| |
| ================================== ================================================================ |
| Syntax Description |
| ================================== ================================================================ |
| flat_scratch 64-bit *flat scratch* address register. |
| [flat_scratch] 64-bit *flat scratch* address register (an SP3 syntax). |
| [flat_scratch_lo,flat_scratch_hi] 64-bit *flat scratch* address register (an SP3 syntax). |
| ================================== ================================================================ |
| |
| High and low 32 bits of *flat scratch* address may be accessed as separate registers: |
| |
| ========================= ========================================================================= |
| Syntax Description |
| ========================= ========================================================================= |
| flat_scratch_lo Low 32 bits of *flat scratch* address register. |
| flat_scratch_hi High 32 bits of *flat scratch* address register. |
| [flat_scratch_lo] Low 32 bits of *flat scratch* address register (an SP3 syntax). |
| [flat_scratch_hi] High 32 bits of *flat scratch* address register (an SP3 syntax). |
| ========================= ========================================================================= |
| |
| .. _amdgpu_synid_xnack: |
| .. _amdgpu_synid_xnack_mask: |
| |
| xnack_mask |
| ---------- |
| |
| Xnack mask, 64-bits wide. Holds a 64-bit mask of which threads |
| received an *XNACK* due to a vector memory operation. |
| |
| For availability of *xnack* feature, refer to :ref:`this table<amdgpu-processors>`. |
| |
| ============================== ===================================================== |
| Syntax Description |
| ============================== ===================================================== |
| xnack_mask 64-bit *xnack mask* register. |
| [xnack_mask] 64-bit *xnack mask* register (an SP3 syntax). |
| [xnack_mask_lo,xnack_mask_hi] 64-bit *xnack mask* register (an SP3 syntax). |
| ============================== ===================================================== |
| |
| High and low 32 bits of *xnack mask* may be accessed as separate registers: |
| |
| ===================== ============================================================== |
| Syntax Description |
| ===================== ============================================================== |
| xnack_mask_lo Low 32 bits of *xnack mask* register. |
| xnack_mask_hi High 32 bits of *xnack mask* register. |
| [xnack_mask_lo] Low 32 bits of *xnack mask* register (an SP3 syntax). |
| [xnack_mask_hi] High 32 bits of *xnack mask* register (an SP3 syntax). |
| ===================== ============================================================== |
| |
| .. _amdgpu_synid_vcc: |
| .. _amdgpu_synid_vcc_lo: |
| |
| vcc |
| --- |
| |
| Vector condition code, 64-bits wide. A bit mask with one bit per thread; |
| it holds the result of a vector compare operation. |
| |
| Note that GFX10+ H/W does not use high 32 bits of *vcc* in *wave32* mode. |
| |
| ================ ========================================================================= |
| Syntax Description |
| ================ ========================================================================= |
| vcc 64-bit *vector condition code* register. |
| [vcc] 64-bit *vector condition code* register (an SP3 syntax). |
| [vcc_lo,vcc_hi] 64-bit *vector condition code* register (an SP3 syntax). |
| ================ ========================================================================= |
| |
| High and low 32 bits of *vector condition code* may be accessed as separate registers: |
| |
| ================ ========================================================================= |
| Syntax Description |
| ================ ========================================================================= |
| vcc_lo Low 32 bits of *vector condition code* register. |
| vcc_hi High 32 bits of *vector condition code* register. |
| [vcc_lo] Low 32 bits of *vector condition code* register (an SP3 syntax). |
| [vcc_hi] High 32 bits of *vector condition code* register (an SP3 syntax). |
| ================ ========================================================================= |
| |
| .. _amdgpu_synid_m0: |
| |
| m0 |
| -- |
| |
| A 32-bit memory register. It has various uses, |
| including register indexing and bounds checking. |
| |
| =========== =================================================== |
| Syntax Description |
| =========== =================================================== |
| m0 A 32-bit *memory* register. |
| [m0] A 32-bit *memory* register (an SP3 syntax). |
| =========== =================================================== |
| |
| .. _amdgpu_synid_exec: |
| |
| exec |
| ---- |
| |
| Execute mask, 64-bits wide. A bit mask with one bit per thread, |
| which is applied to vector instructions and controls which threads execute |
| and which ignore the instruction. |
| |
| Note that GFX10+ H/W does not use high 32 bits of *exec* in *wave32* mode. |
| |
| ===================== ================================================================= |
| Syntax Description |
| ===================== ================================================================= |
| exec 64-bit *execute mask* register. |
| [exec] 64-bit *execute mask* register (an SP3 syntax). |
| [exec_lo,exec_hi] 64-bit *execute mask* register (an SP3 syntax). |
| ===================== ================================================================= |
| |
| High and low 32 bits of *execute mask* may be accessed as separate registers: |
| |
| ===================== ================================================================= |
| Syntax Description |
| ===================== ================================================================= |
| exec_lo Low 32 bits of *execute mask* register. |
| exec_hi High 32 bits of *execute mask* register. |
| [exec_lo] Low 32 bits of *execute mask* register (an SP3 syntax). |
| [exec_hi] High 32 bits of *execute mask* register (an SP3 syntax). |
| ===================== ================================================================= |
| |
| .. _amdgpu_synid_vccz: |
| |
| vccz |
| ---- |
| |
| A single bit flag indicating that the :ref:`vcc<amdgpu_synid_vcc>` |
| is all zeros. |
| |
| Note: when GFX10+ operates in *wave32* mode, this register reflects |
| the state of :ref:`vcc_lo<amdgpu_synid_vcc_lo>`. |
| |
| .. _amdgpu_synid_execz: |
| |
| execz |
| ----- |
| |
| A single bit flag indicating that the :ref:`exec<amdgpu_synid_exec>` |
| is all zeros. |
| |
| Note: when GFX10+ operates in *wave32* mode, this register reflects |
| the state of :ref:`exec_lo<amdgpu_synid_exec>`. |
| |
| .. _amdgpu_synid_scc: |
| |
| scc |
| --- |
| |
| A single bit flag indicating the result of a scalar compare operation. |
| |
| .. _amdgpu_synid_lds_direct: |
| |
| lds_direct |
| ---------- |
| |
| A special operand which supplies a 32-bit value |
| fetched from *LDS* memory using :ref:`m0<amdgpu_synid_m0>` as an address. |
| |
| .. _amdgpu_synid_null: |
| |
| null |
| ---- |
| |
| This is a special operand that may be used as a source or a destination. |
| |
| When used as a destination, the result of the operation is discarded. |
| |
| When used as a source, it supplies zero value. |
| |
| .. _amdgpu_synid_constant: |
| |
| inline constant |
| --------------- |
| |
| An *inline constant* is an integer or a floating-point value |
| encoded as a part of an instruction. Compare *inline constants* |
| with :ref:`literals<amdgpu_synid_literal>`. |
| |
| Inline constants include: |
| |
| * :ref:`Integer inline constants<amdgpu_synid_iconst>`; |
| * :ref:`Floating-point inline constants<amdgpu_synid_fconst>`; |
| * :ref:`Inline values<amdgpu_synid_ival>`. |
| |
| If a number may be encoded as either |
| a :ref:`literal<amdgpu_synid_literal>` or |
| a :ref:`constant<amdgpu_synid_constant>`, |
| the assembler selects the latter encoding as more efficient. |
| |
| .. _amdgpu_synid_iconst: |
| |
| iconst |
| ~~~~~~ |
| |
| An :ref:`integer number<amdgpu_synid_integer_number>` or |
| an :ref:`absolute expression<amdgpu_synid_absolute_expression>` |
| encoded as an *inline constant*. |
| |
| Only a small fraction of integer numbers may be encoded as *inline constants*. |
| They are enumerated in the table below. |
| Other integer numbers are encoded as :ref:`literals<amdgpu_synid_literal>`. |
| |
| ================================== ==================================== |
| Value Note |
| ================================== ==================================== |
| {0..64} Positive integer inline constants. |
| {-16..-1} Negative integer inline constants. |
| ================================== ==================================== |
| |
| .. _amdgpu_synid_fconst: |
| |
| fconst |
| ~~~~~~ |
| |
| A :ref:`floating-point number<amdgpu_synid_floating-point_number>` |
| encoded as an *inline constant*. |
| |
| Only a small fraction of floating-point numbers may be encoded |
| as *inline constants*. They are enumerated in the table below. |
| Other floating-point numbers are encoded as |
| :ref:`literals<amdgpu_synid_literal>`. |
| |
| ===================== ===================================================== ================== |
| Value Note Availability |
| ===================== ===================================================== ================== |
| 0.0 The same as integer constant 0. All GPUs |
| 0.5 Floating-point constant 0.5 All GPUs |
| 1.0 Floating-point constant 1.0 All GPUs |
| 2.0 Floating-point constant 2.0 All GPUs |
| 4.0 Floating-point constant 4.0 All GPUs |
| -0.5 Floating-point constant -0.5 All GPUs |
| -1.0 Floating-point constant -1.0 All GPUs |
| -2.0 Floating-point constant -2.0 All GPUs |
| -4.0 Floating-point constant -4.0 All GPUs |
| 0.1592 1.0/(2.0*pi). Use only for 16-bit operands. GFX8+ |
| 0.15915494 1.0/(2.0*pi). Use only for 16- and 32-bit operands. GFX8+ |
| 0.15915494309189532 1.0/(2.0*pi). GFX8+ |
| ===================== ===================================================== ================== |
| |
| .. WARNING:: Floating-point inline constants cannot be used with *16-bit integer* operands. \ |
| Assembler encodes these values as literals. |
| |
| .. _amdgpu_synid_ival: |
| |
| ival |
| ~~~~ |
| |
| A symbolic operand encoded as an *inline constant*. |
| These operands provide read-only access to H/W registers. |
| |
| ===================== ========================= ================================================ ============= |
| Syntax Alternative Syntax (SP3) Note Availability |
| ===================== ========================= ================================================ ============= |
| shared_base src_shared_base Base address of shared memory region. GFX9+ |
| shared_limit src_shared_limit Address of the end of shared memory region. GFX9+ |
| private_base src_private_base Base address of private memory region. GFX9+ |
| private_limit src_private_limit Address of the end of private memory region. GFX9+ |
| pops_exiting_wave_id src_pops_exiting_wave_id A dedicated counter for POPS. GFX9, GFX10 |
| ===================== ========================= ================================================ ============= |
| |
| .. _amdgpu_synid_literal: |
| |
| literal |
| ------- |
| |
| A *literal* is a 64-bit value encoded as a separate |
| 32-bit dword in the instruction stream. Compare *literals* |
| with :ref:`inline constants<amdgpu_synid_constant>`. |
| |
| If a number may be encoded as either |
| a :ref:`literal<amdgpu_synid_literal>` or |
| an :ref:`inline constant<amdgpu_synid_constant>`, |
| assembler selects the latter encoding as more efficient. |
| |
| Literals may be specified as |
| :ref:`integer numbers<amdgpu_synid_integer_number>`, |
| :ref:`floating-point numbers<amdgpu_synid_floating-point_number>`, |
| :ref:`absolute expressions<amdgpu_synid_absolute_expression>` or |
| :ref:`relocatable expressions<amdgpu_synid_relocatable_expression>`. |
| |
| An instruction may use only one literal, |
| but several operands may refer to the same literal. |
| |
| .. _amdgpu_synid_uimm8: |
| |
| uimm8 |
| ----- |
| |
| An 8-bit :ref:`integer number<amdgpu_synid_integer_number>` |
| or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. |
| The value must be in the range 0..0xFF. |
| |
| .. _amdgpu_synid_uimm32: |
| |
| uimm32 |
| ------ |
| |
| A 32-bit :ref:`integer number<amdgpu_synid_integer_number>` |
| or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. |
| The value must be in the range 0..0xFFFFFFFF. |
| |
| .. _amdgpu_synid_uimm20: |
| |
| uimm20 |
| ------ |
| |
| A 20-bit :ref:`integer number<amdgpu_synid_integer_number>` |
| or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. |
| |
| The value must be in the range 0..0xFFFFF. |
| |
| .. _amdgpu_synid_simm21: |
| |
| simm21 |
| ------ |
| |
| A 21-bit :ref:`integer number<amdgpu_synid_integer_number>` |
| or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. |
| |
| The value must be in the range -0x100000..0x0FFFFF. |
| |
| .. _amdgpu_synid_off: |
| |
| off |
| --- |
| |
| A special entity which indicates that the value of this operand is not used. |
| |
| ================================== =================================================== |
| Syntax Description |
| ================================== =================================================== |
| off Indicates an unused operand. |
| ================================== =================================================== |
| |
| |
| .. _amdgpu_synid_number: |
| |
| Numbers |
| ======= |
| |
| .. _amdgpu_synid_integer_number: |
| |
| Integer Numbers |
| --------------- |
| |
| Integer numbers are 64 bits wide. |
| They are converted to :ref:`expected operand type<amdgpu_syn_instruction_type>` |
| as described :ref:`here<amdgpu_synid_int_conv>`. |
| |
| Integer numbers may be specified in binary, octal, |
| hexadecimal and decimal formats: |
| |
| ============ =============================== ======== |
| Format Syntax Example |
| ============ =============================== ======== |
| Decimal [-]?[1-9][0-9]* -1234 |
| Binary [-]?0b[01]+ 0b1010 |
| Octal [-]?0[0-7]+ 010 |
| Hexadecimal [-]?0x[0-9a-fA-F]+ 0xff |
| \ [-]?[0x]?[0-9][0-9a-fA-F]*[hH] 0ffh |
| ============ =============================== ======== |
| |
| .. _amdgpu_synid_floating-point_number: |
| |
| Floating-Point Numbers |
| ---------------------- |
| |
| All floating-point numbers are handled as double (64 bits wide). |
| They are converted to |
| :ref:`expected operand type<amdgpu_syn_instruction_type>` |
| as described :ref:`here<amdgpu_synid_fp_conv>`. |
| |
| Floating-point numbers may be specified in hexadecimal and decimal formats: |
| |
| ============ ======================================================== ====================== ==================== |
| Format Syntax Examples Note |
| ============ ======================================================== ====================== ==================== |
| Decimal [-]?[0-9]*[.][0-9]*([eE][+-]?[0-9]*)? -1.234, 234e2 Must include either |
| a decimal separator |
| or an exponent. |
| Hexadecimal [-]0x[0-9a-fA-F]*(.[0-9a-fA-F]*)?[pP][+-]?[0-9a-fA-F]+ -0x1afp-10, 0x.1afp10 |
| ============ ======================================================== ====================== ==================== |
| |
| .. _amdgpu_synid_expression: |
| |
| Expressions |
| =========== |
| |
| An expression is evaluated to a 64-bit integer. |
| Note that floating-point expressions are not supported. |
| |
| There are two kinds of expressions: |
| |
| * :ref:`Absolute<amdgpu_synid_absolute_expression>`. |
| * :ref:`Relocatable<amdgpu_synid_relocatable_expression>`. |
| |
| .. _amdgpu_synid_absolute_expression: |
| |
| Absolute Expressions |
| -------------------- |
| |
| The value of an absolute expression does not change after program relocation. |
| Absolute expressions must not include unassigned and relocatable values |
| such as labels. |
| |
| Absolute expressions are evaluated to 64-bit integer values and converted to |
| :ref:`expected operand type<amdgpu_syn_instruction_type>` |
| as described :ref:`here<amdgpu_synid_int_conv>`. |
| |
| Examples: |
| |
| .. parsed-literal:: |
| |
| x = -1 |
| y = x + 10 |
| |
| .. _amdgpu_synid_relocatable_expression: |
| |
| Relocatable Expressions |
| ----------------------- |
| |
| The value of a relocatable expression depends on program relocation. |
| |
| Note that use of relocatable expressions is limited to branch targets |
| and 32-bit integer operands. |
| |
| A relocatable expression is evaluated to a 64-bit integer value, |
| which depends on operand kind and |
| :ref:`relocation type<amdgpu-relocation-records>` of symbol(s) |
| used in the expression. For example, if an instruction refers to a label, |
| this reference is evaluated to an offset from the address after |
| the instruction to the label address: |
| |
| .. parsed-literal:: |
| |
| label: |
| v_add_co_u32_e32 v0, vcc, label, v1 // 'label' operand is evaluated to -4 |
| |
| Note that values of relocatable expressions are usually unknown |
| at assembly time; they are resolved later by a linker and converted to |
| :ref:`expected operand type<amdgpu_syn_instruction_type>` |
| as described :ref:`here<amdgpu_synid_rl_conv>`. |
| |
| Operands and Operations |
| ----------------------- |
| |
| Expressions are composed of 64-bit integer operands and operations. |
| Operands include :ref:`integer numbers<amdgpu_synid_integer_number>` |
| and :ref:`symbols<amdgpu_synid_symbol>`. |
| |
| Expressions may also use "." which is a reference |
| to the current PC (program counter). |
| |
| :ref:`Unary<amdgpu_synid_expression_un_op>` and |
| :ref:`binary<amdgpu_synid_expression_bin_op>` |
| operations produce 64-bit integer results. |
| |
| Syntax of Expressions |
| --------------------- |
| |
| Syntax of expressions is shown below:: |
| |
| expr ::= expr binop expr | primaryexpr ; |
| |
| primaryexpr ::= '(' expr ')' | symbol | number | '.' | unop primaryexpr ; |
| |
| binop ::= '&&' |
| | '||' |
| | '|' |
| | '^' |
| | '&' |
| | '!' |
| | '==' |
| | '!=' |
| | '<>' |
| | '<' |
| | '<=' |
| | '>' |
| | '>=' |
| | '<<' |
| | '>>' |
| | '+' |
| | '-' |
| | '*' |
| | '/' |
| | '%' ; |
| |
| unop ::= '~' |
| | '+' |
| | '-' |
| | '!' ; |
| |
| .. _amdgpu_synid_expression_bin_op: |
| |
| Binary Operators |
| ---------------- |
| |
| Binary operators are described in the following table. |
| They operate on and produce 64-bit integers. |
| Operators with higher priority are performed first. |
| |
| ========== ========= =============================================== |
| Operator Priority Meaning |
| ========== ========= =============================================== |
| \* 5 Integer multiplication. |
| / 5 Integer division. |
| % 5 Integer signed remainder. |
| \+ 4 Integer addition. |
| \- 4 Integer subtraction. |
| << 3 Integer shift left. |
| >> 3 Logical shift right. |
| == 2 Equality comparison. |
| != 2 Inequality comparison. |
| <> 2 Inequality comparison. |
| < 2 Signed less than comparison. |
| <= 2 Signed less than or equal comparison. |
| > 2 Signed greater than comparison. |
| >= 2 Signed greater than or equal comparison. |
| \| 1 Bitwise or. |
| ^ 1 Bitwise xor. |
| & 1 Bitwise and. |
| && 0 Logical and. |
| || 0 Logical or. |
| ========== ========= =============================================== |
| |
| .. _amdgpu_synid_expression_un_op: |
| |
| Unary Operators |
| --------------- |
| |
| Unary operators are described in the following table. |
| They operate on and produce 64-bit integers. |
| |
| ========== =============================================== |
| Operator Meaning |
| ========== =============================================== |
| ! Logical negation. |
| ~ Bitwise negation. |
| \+ Integer unary plus. |
| \- Integer unary minus. |
| ========== =============================================== |
| |
| .. _amdgpu_synid_symbol: |
| |
| Symbols |
| ------- |
| |
| A symbol is a named 64-bit integer value, representing a relocatable |
| address or an absolute (non-relocatable) number. |
| |
| Symbol names have the following syntax: |
| ``[a-zA-Z_.][a-zA-Z0-9_$.@]*`` |
| |
| The table below provides several examples of syntax used for symbol definition. |
| |
| ================ ========================================================== |
| Syntax Meaning |
| ================ ========================================================== |
| .globl <S> Declares a global symbol S without assigning it a value. |
| .set <S>, <E> Assigns the value of an expression E to a symbol S. |
| <S> = <E> Assigns the value of an expression E to a symbol S. |
| <S>: Declares a label S and assigns it the current PC value. |
| ================ ========================================================== |
| |
| A symbol may be used before it is declared or assigned; |
| unassigned symbols are assumed to be PC-relative. |
| |
| Additional information about symbols may be found :ref:`here<amdgpu-symbols>`. |
| |
| .. _amdgpu_synid_conv: |
| |
| Type and Size Conversion |
| ======================== |
| |
| This section describes what happens when a 64-bit |
| :ref:`integer number<amdgpu_synid_integer_number>`, a |
| :ref:`floating-point number<amdgpu_synid_floating-point_number>` or an |
| :ref:`expression<amdgpu_synid_expression>` |
| is used for an operand which has a different type or size. |
| |
| .. _amdgpu_synid_int_conv: |
| |
| Conversion of Integer Values |
| ---------------------------- |
| |
| Instruction operands may be specified as 64-bit |
| :ref:`integer numbers<amdgpu_synid_integer_number>` or |
| :ref:`absolute expressions<amdgpu_synid_absolute_expression>`. |
| These values are converted to the |
| :ref:`expected operand type<amdgpu_syn_instruction_type>` |
| using the following steps: |
| |
| 1. *Validation*. Assembler checks if the input value may be truncated |
| without loss to the required *truncation width* (see the table below). |
| There are two cases when this operation is enabled: |
| |
| * The truncated bits are all 0. |
| * The truncated bits are all 1 and the value after truncation has its MSB bit set. |
| |
| In all other cases, the assembler triggers an error. |
| |
| 2. *Conversion*. The input value is converted to the expected type |
| as described in the table below. Depending on operand kind, this conversion |
| is performed by either assembler or AMDGPU H/W (or both). |
| |
| ============== ================= =============== ==================================================================== |
| Expected type Truncation Width Conversion Description |
| ============== ================= =============== ==================================================================== |
| i16, u16, b16 16 num.u16 Truncate to 16 bits. |
| i32, u32, b32 32 num.u32 Truncate to 32 bits. |
| i64 32 {-1,num.i32} Truncate to 32 bits and then sign-extend the result to 64 bits. |
| u64, b64 32 {0,num.u32} Truncate to 32 bits and then zero-extend the result to 64 bits. |
| f16 16 num.u16 Use low 16 bits as an f16 value. |
| f32 32 num.u32 Use low 32 bits as an f32 value. |
| f64 32 {num.u32,0} Use low 32 bits of the number as high 32 bits |
| of the result; low 32 bits of the result are zeroed. |
| ============== ================= =============== ==================================================================== |
| |
| Examples of enabled conversions: |
| |
| .. parsed-literal:: |
| |
| // GFX9 |
| |
| v_add_u16 v0, -1, 0 // src0 = 0xFFFF |
| v_add_f16 v0, -1, 0 // src0 = 0xFFFF (NaN) |
| // |
| v_add_u32 v0, -1, 0 // src0 = 0xFFFFFFFF |
| v_add_f32 v0, -1, 0 // src0 = 0xFFFFFFFF (NaN) |
| // |
| v_add_u16 v0, 0xff00, v0 // src0 = 0xff00 |
| v_add_u16 v0, 0xffffffffffffff00, v0 // src0 = 0xff00 |
| v_add_u16 v0, -256, v0 // src0 = 0xff00 |
| // |
| s_bfe_i64 s[0:1], 0xffefffff, s3 // src0 = 0xffffffffffefffff |
| s_bfe_u64 s[0:1], 0xffefffff, s3 // src0 = 0x00000000ffefffff |
| v_ceil_f64_e32 v[0:1], 0xffefffff // src0 = 0xffefffff00000000 (-1.7976922776554302e308) |
| // |
| x = 0xffefffff // |
| s_bfe_i64 s[0:1], x, s3 // src0 = 0xffffffffffefffff |
| s_bfe_u64 s[0:1], x, s3 // src0 = 0x00000000ffefffff |
| v_ceil_f64_e32 v[0:1], x // src0 = 0xffefffff00000000 (-1.7976922776554302e308) |
| |
| Examples of disabled conversions: |
| |
| .. parsed-literal:: |
| |
| // GFX9 |
| |
| v_add_u16 v0, 0x1ff00, v0 // truncated bits are not all 0 or 1 |
| v_add_u16 v0, 0xffffffffffff00ff, v0 // truncated bits do not match MSB of the result |
| |
| .. _amdgpu_synid_fp_conv: |
| |
| Conversion of Floating-Point Values |
| ----------------------------------- |
| |
| Instruction operands may be specified as 64-bit |
| :ref:`floating-point numbers<amdgpu_synid_floating-point_number>`. |
| These values are converted to the |
| :ref:`expected operand type<amdgpu_syn_instruction_type>` |
| using the following steps: |
| |
| 1. *Validation*. Assembler checks if the input f64 number can be converted |
| to the *required floating-point type* (see the table below) without overflow |
| or underflow. Precision lost is allowed. If this conversion is not possible, |
| the assembler triggers an error. |
| |
| 2. *Conversion*. The input value is converted to the expected type |
| as described in the table below. Depending on operand kind, this is |
| performed by either assembler or AMDGPU H/W (or both). |
| |
| ============== ================ ================= ================================================================= |
| Expected type Required FP Type Conversion Description |
| ============== ================ ================= ================================================================= |
| i16, u16, b16 f16 f16(num) Convert to f16 and use bits of the result as an integer value. |
| The value has to be encoded as a literal, or an error occurs. |
| Note that the value cannot be encoded as an inline constant. |
| i32, u32, b32 f32 f32(num) Convert to f32 and use bits of the result as an integer value. |
| i64, u64, b64 \- \- Conversion disabled. |
| f16 f16 f16(num) Convert to f16. |
| f32 f32 f32(num) Convert to f32. |
| f64 f64 {num.u32.hi,0} Use high 32 bits of the number as high 32 bits of the result; |
| zero-fill low 32 bits of the result. |
| |
| Note that the result may differ from the original number. |
| ============== ================ ================= ================================================================= |
| |
| Examples of enabled conversions: |
| |
| .. parsed-literal:: |
| |
| // GFX9 |
| |
| v_add_f16 v0, 1.0, 0 // src0 = 0x3C00 (1.0) |
| v_add_u16 v0, 1.0, 0 // src0 = 0x3C00 |
| // |
| v_add_f32 v0, 1.0, 0 // src0 = 0x3F800000 (1.0) |
| v_add_u32 v0, 1.0, 0 // src0 = 0x3F800000 |
| |
| // src0 before conversion: |
| // 1.7976931348623157e308 = 0x7fefffffffffffff |
| // src0 after conversion: |
| // 1.7976922776554302e308 = 0x7fefffff00000000 |
| v_ceil_f64 v[0:1], 1.7976931348623157e308 |
| |
| v_add_f16 v1, 65500.0, v2 // ok for f16. |
| v_add_f32 v1, 65600.0, v2 // ok for f32, but would result in overflow for f16. |
| |
| Examples of disabled conversions: |
| |
| .. parsed-literal:: |
| |
| // GFX9 |
| |
| v_add_f16 v1, 65600.0, v2 // overflow |
| |
| .. _amdgpu_synid_rl_conv: |
| |
| Conversion of Relocatable Values |
| -------------------------------- |
| |
| :ref:`Relocatable expressions<amdgpu_synid_relocatable_expression>` |
| may be used with 32-bit integer operands and jump targets. |
| |
| When the value of a relocatable expression is resolved by a linker, it is |
| converted as needed and truncated to the operand size. The conversion depends |
| on :ref:`relocation type<amdgpu-relocation-records>` and operand kind. |
| |
| For example, when a 32-bit operand of an instruction refers |
| to a relocatable expression *expr*, this reference is evaluated |
| to a 64-bit offset from the address after the |
| instruction to the address being referenced, *counted in bytes*. |
| Then the value is truncated to 32 bits and encoded as a literal: |
| |
| .. parsed-literal:: |
| |
| expr = . |
| v_add_co_u32_e32 v0, vcc, expr, v1 // 'expr' operand is evaluated to -4 |
| // and then truncated to 0xFFFFFFFC |
| |
| As another example, when a branch instruction refers to a label, |
| this reference is evaluated to an offset from the address after the |
| instruction to the label address, *counted in dwords*. |
| Then the value is truncated to 16 bits: |
| |
| .. parsed-literal:: |
| |
| label: |
| s_branch label // 'label' operand is evaluated to -1 and truncated to 0xFFFF |
