1195 lines · plain
1=====================================2Syntax of AMDGPU Instruction Operands3=====================================4 5.. contents::6 :local:7 8Conventions9===========10 11The following notation is used throughout this document:12 13 =================== =============================================================================14 Notation Description15 =================== =============================================================================16 {0..N} Any integer value in the range from 0 to N (inclusive).17 <x> Syntax and meaning of *x* are explained elsewhere.18 =================== =============================================================================19 20.. _amdgpu_syn_operands:21 22Operands23========24 25.. _amdgpu_synid_v:26 27v (32-bit)28----------29 30Vector registers. There are 256 32-bit vector registers.31 32A sequence of *vector* registers may be used to operate with more than 32 bits of data.33 34Assembler currently supports tuples with 1 to 12, 16 and 32 *vector* registers.35 36 =================================================== ====================================================================37 Syntax Description38 =================================================== ====================================================================39 **v**\<N> A single 32-bit *vector* register.40 41 *N* must be a decimal42 :ref:`integer number<amdgpu_synid_integer_number>`.43 **v[**\ <N>\ **]** A single 32-bit *vector* register.44 45 *N* may be specified as an46 :ref:`integer number<amdgpu_synid_integer_number>`47 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.48 **v[**\ <N>:<K>\ **]** A sequence of (\ *K-N+1*\ ) *vector* registers.49 50 *N* and *K* may be specified as51 :ref:`integer numbers<amdgpu_synid_integer_number>`52 or :ref:`absolute expressions<amdgpu_synid_absolute_expression>`.53 **[v**\ <N>, \ **v**\ <N+1>, ... **v**\ <K>\ **]** A sequence of (\ *K-N+1*\ ) *vector* registers.54 55 Register indices must be specified as decimal56 :ref:`integer numbers<amdgpu_synid_integer_number>`.57 =================================================== ====================================================================58 59Note: *N* and *K* must satisfy the following conditions:60 61* *N* <= *K*.62* 0 <= *N* <= 255.63* 0 <= *K* <= 255.64* *K-N+1* must be in the range from 1 to 12 or equal to 16 or 32.65 66GFX90A and GFX942 have an additional alignment requirement:67pairs of *vector* registers must be even-aligned68(first register must be even).69 70Examples:71 72.. parsed-literal::73 74 v25575 v[0]76 v[0:1]77 v[1:1]78 v[0:3]79 v[2*2]80 v[1-1:2-1]81 [v252]82 [v252,v253,v254,v255]83 84.. _amdgpu_synid_nsa:85 86**Non-Sequential Address (NSA) Syntax**87 88GFX10+ *image* instructions may use special *NSA* (Non-Sequential Address)89syntax for *image addresses*:90 91 ===================================== =================================================92 Syntax Description93 ===================================== =================================================94 **[Vm**, \ **Vn**, ... **Vk**\ **]** A sequence of 32-bit *vector* registers.95 Each register may be specified using the syntax96 defined :ref:`above<amdgpu_synid_v>`.97 98 In contrast with the standard syntax, registers99 in *NSA* sequence are not required to have100 consecutive indices. Moreover, the same register101 may appear in the sequence more than once.102 103 GFX11+ has an additional limitation: if address104 size occupies more than 5 dwords, registers105 starting from the 5th element must be contiguous.106 ===================================== =================================================107 108Examples:109 110.. parsed-literal::111 112 [v32,v1,v[2]]113 [v[32],v[1:1],[v2]]114 [v4,v4,v4,v4]115 116.. _amdgpu_synid_v16:117 118v (16-bit)119----------120 12116-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.122 123Only VOP3, VOP3P and VINTERP instructions may access all 512 registers (using :ref:`op_sel<amdgpu_synid_op_sel>` modifier).124VOP1, VOP2 and VOPC instructions may currently access only 128 low 16-bit registers using the syntax described below.125 126.. WARNING:: This section is incomplete. The support of 16-bit registers in the assembler is still WIP.127 128\129 =================================================== ====================================================================130 Syntax Description131 =================================================== ====================================================================132 **v**\<N> A single 16-bit *vector* register (low half).133 =================================================== ====================================================================134 135Note: *N* must satisfy the following conditions:136 137* 0 <= *N* <= 127.138 139Examples:140 141.. parsed-literal::142 143 v127144 145.. _amdgpu_synid_a:146 147a148-149 150Accumulator registers. There are 256 32-bit accumulator registers.151 152A sequence of *accumulator* registers may be used to operate with more than 32 bits of data.153 154Assembler currently supports tuples with 1 to 12, 16 and 32 *accumulator* registers.155 156 =================================================== ========================================================= ====================================================================157 Syntax Alternative Syntax (SP3) Description158 =================================================== ========================================================= ====================================================================159 **a**\<N> **acc**\<N> A single 32-bit *accumulator* register.160 161 *N* must be a decimal162 :ref:`integer number<amdgpu_synid_integer_number>`.163 **a[**\ <N>\ **]** **acc[**\ <N>\ **]** A single 32-bit *accumulator* register.164 165 *N* may be specified as an166 :ref:`integer number<amdgpu_synid_integer_number>`167 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.168 **a[**\ <N>:<K>\ **]** **acc[**\ <N>:<K>\ **]** A sequence of (\ *K-N+1*\ ) *accumulator* registers.169 170 *N* and *K* may be specified as171 :ref:`integer numbers<amdgpu_synid_integer_number>`172 or :ref:`absolute expressions<amdgpu_synid_absolute_expression>`.173 **[a**\ <N>, \ **a**\ <N+1>, ... **a**\ <K>\ **]** **[acc**\ <N>, \ **acc**\ <N+1>, ... **acc**\ <K>\ **]** A sequence of (\ *K-N+1*\ ) *accumulator* registers.174 175 Register indices must be specified as decimal176 :ref:`integer numbers<amdgpu_synid_integer_number>`.177 =================================================== ========================================================= ====================================================================178 179Note: *N* and *K* must satisfy the following conditions:180 181* *N* <= *K*.182* 0 <= *N* <= 255.183* 0 <= *K* <= 255.184* *K-N+1* must be in the range from 1 to 12 or equal to 16 or 32.185 186GFX90A and GFX942 have an additional alignment requirement:187pairs of *accumulator* registers must be even-aligned188(first register must be even).189 190Examples:191 192.. parsed-literal::193 194 a255195 a[0]196 a[0:1]197 a[1:1]198 a[0:3]199 a[2*2]200 a[1-1:2-1]201 [a252]202 [a252,a253,a254,a255]203 204 acc0205 acc[1]206 [acc250]207 [acc2,acc3]208 209.. _amdgpu_synid_s:210 211s212-213 214Scalar 32-bit registers. The number of available *scalar* registers depends on the GPU:215 216 ======= ============================217 GPU Number of *scalar* registers218 ======= ============================219 GFX7 104220 GFX8 102221 GFX9 102222 GFX10+ 106223 ======= ============================224 225A sequence of *scalar* registers may be used to operate with more than 32 bits of data.226Assembler currently supports tuples with 1 to 12, 16 and 32 *scalar* registers.227 228Pairs of *scalar* registers must be even-aligned (first register must be even).229Sequences of 4 and more *scalar* registers must be quad-aligned.230 231 ======================================================== ====================================================================232 Syntax Description233 ======================================================== ====================================================================234 **s**\ <N> A single 32-bit *scalar* register.235 236 *N* must be a decimal237 :ref:`integer number<amdgpu_synid_integer_number>`.238 239 **s[**\ <N>\ **]** A single 32-bit *scalar* register.240 241 *N* may be specified as an242 :ref:`integer number<amdgpu_synid_integer_number>`243 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.244 **s[**\ <N>:<K>\ **]** A sequence of (\ *K-N+1*\ ) *scalar* registers.245 246 *N* and *K* may be specified as247 :ref:`integer numbers<amdgpu_synid_integer_number>`248 or :ref:`absolute expressions<amdgpu_synid_absolute_expression>`.249 250 **[s**\ <N>, \ **s**\ <N+1>, ... **s**\ <K>\ **]** A sequence of (\ *K-N+1*\ ) *scalar* registers.251 252 Register indices must be specified as decimal253 :ref:`integer numbers<amdgpu_synid_integer_number>`.254 ======================================================== ====================================================================255 256Note: *N* and *K* must satisfy the following conditions:257 258* *N* must be properly aligned based on the sequence size.259* *N* <= *K*.260* 0 <= *N* < *SMAX*\ , where *SMAX* is the number of available *scalar* registers.261* 0 <= *K* < *SMAX*\ , where *SMAX* is the number of available *scalar* registers.262* *K-N+1* must be in the range from 1 to 12 or equal to 16 or 32.263 264Examples:265 266.. parsed-literal::267 268 s0269 s[0]270 s[0:1]271 s[1:1]272 s[0:3]273 s[2*2]274 s[1-1:2-1]275 [s4]276 [s4,s5,s6,s7]277 278Examples of *scalar* registers with an invalid alignment:279 280.. parsed-literal::281 282 s[1:2]283 s[2:5]284 285.. _amdgpu_synid_trap:286 287trap288----289 290A set of trap handler registers:291 292* :ref:`ttmp<amdgpu_synid_ttmp>`293* :ref:`tba<amdgpu_synid_tba>`294* :ref:`tma<amdgpu_synid_tma>`295 296.. _amdgpu_synid_ttmp:297 298ttmp299----300 301Trap handler temporary scalar registers, 32-bits wide.302The number of available *ttmp* registers depends on the GPU:303 304 ======= ===========================305 GPU Number of *ttmp* registers306 ======= ===========================307 GFX7 12308 GFX8 12309 GFX9 16310 GFX10+ 16311 ======= ===========================312 313A sequence of *ttmp* registers may be used to operate with more than 32 bits of data.314Assembler currently supports tuples with 1 to 12 and 16 *ttmp* registers.315 316Pairs of *ttmp* registers must be even-aligned (first register must be even).317Sequences of 4 and more *ttmp* registers must be quad-aligned.318 319 ============================================================= ====================================================================320 Syntax Description321 ============================================================= ====================================================================322 **ttmp**\ <N> A single 32-bit *ttmp* register.323 324 *N* must be a decimal325 :ref:`integer number<amdgpu_synid_integer_number>`.326 **ttmp[**\ <N>\ **]** A single 32-bit *ttmp* register.327 328 *N* may be specified as an329 :ref:`integer number<amdgpu_synid_integer_number>`330 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.331 **ttmp[**\ <N>:<K>\ **]** A sequence of (\ *K-N+1*\ ) *ttmp* registers.332 333 *N* and *K* may be specified as334 :ref:`integer numbers<amdgpu_synid_integer_number>`335 or :ref:`absolute expressions<amdgpu_synid_absolute_expression>`.336 **[ttmp**\ <N>, \ **ttmp**\ <N+1>, ... **ttmp**\ <K>\ **]** A sequence of (\ *K-N+1*\ ) *ttmp* registers.337 338 Register indices must be specified as decimal339 :ref:`integer numbers<amdgpu_synid_integer_number>`.340 ============================================================= ====================================================================341 342Note: *N* and *K* must satisfy the following conditions:343 344* *N* must be properly aligned based on the sequence size.345* *N* <= *K*.346* 0 <= *N* < *TMAX*, where *TMAX* is the number of available *ttmp* registers.347* 0 <= *K* < *TMAX*, where *TMAX* is the number of available *ttmp* registers.348* *K-N+1* must be in the range from 1 to 12 or equal to 16.349 350Examples:351 352.. parsed-literal::353 354 ttmp0355 ttmp[0]356 ttmp[0:1]357 ttmp[1:1]358 ttmp[0:3]359 ttmp[2*2]360 ttmp[1-1:2-1]361 [ttmp4]362 [ttmp4,ttmp5,ttmp6,ttmp7]363 364Examples of *ttmp* registers with an invalid alignment:365 366.. parsed-literal::367 368 ttmp[1:2]369 ttmp[2:5]370 371.. _amdgpu_synid_tba:372 373tba374---375 376Trap base address, 64-bits wide. Holds the pointer to the current377trap handler program.378 379 ================== ======================================================================= =============380 Syntax Description Availability381 ================== ======================================================================= =============382 tba 64-bit *trap base address* register. GFX7, GFX8383 [tba] 64-bit *trap base address* register (an SP3 syntax). GFX7, GFX8384 [tba_lo,tba_hi] 64-bit *trap base address* register (an SP3 syntax). GFX7, GFX8385 ================== ======================================================================= =============386 387High and low 32 bits of *trap base address* may be accessed as separate registers:388 389 ================== ======================================================================= =============390 Syntax Description Availability391 ================== ======================================================================= =============392 tba_lo Low 32 bits of *trap base address* register. GFX7, GFX8393 tba_hi High 32 bits of *trap base address* register. GFX7, GFX8394 [tba_lo] Low 32 bits of *trap base address* register (an SP3 syntax). GFX7, GFX8395 [tba_hi] High 32 bits of *trap base address* register (an SP3 syntax). GFX7, GFX8396 ================== ======================================================================= =============397 398.. _amdgpu_synid_tma:399 400tma401---402 403Trap memory address, 64-bits wide.404 405 ================= ======================================================================= ==================406 Syntax Description Availability407 ================= ======================================================================= ==================408 tma 64-bit *trap memory address* register. GFX7, GFX8409 [tma] 64-bit *trap memory address* register (an SP3 syntax). GFX7, GFX8410 [tma_lo,tma_hi] 64-bit *trap memory address* register (an SP3 syntax). GFX7, GFX8411 ================= ======================================================================= ==================412 413High and low 32 bits of *trap memory address* may be accessed as separate registers:414 415 ================= ======================================================================= ==================416 Syntax Description Availability417 ================= ======================================================================= ==================418 tma_lo Low 32 bits of *trap memory address* register. GFX7, GFX8419 tma_hi High 32 bits of *trap memory address* register. GFX7, GFX8420 [tma_lo] Low 32 bits of *trap memory address* register (an SP3 syntax). GFX7, GFX8421 [tma_hi] High 32 bits of *trap memory address* register (an SP3 syntax). GFX7, GFX8422 ================= ======================================================================= ==================423 424.. _amdgpu_synid_flat_scratch:425 426flat_scratch427------------428 429Flat scratch address, 64-bits wide. Holds the base address of scratch memory.430 431 ================================== ================================================================432 Syntax Description433 ================================== ================================================================434 flat_scratch 64-bit *flat scratch* address register.435 [flat_scratch] 64-bit *flat scratch* address register (an SP3 syntax).436 [flat_scratch_lo,flat_scratch_hi] 64-bit *flat scratch* address register (an SP3 syntax).437 ================================== ================================================================438 439High and low 32 bits of *flat scratch* address may be accessed as separate registers:440 441 ========================= =========================================================================442 Syntax Description443 ========================= =========================================================================444 flat_scratch_lo Low 32 bits of *flat scratch* address register.445 flat_scratch_hi High 32 bits of *flat scratch* address register.446 [flat_scratch_lo] Low 32 bits of *flat scratch* address register (an SP3 syntax).447 [flat_scratch_hi] High 32 bits of *flat scratch* address register (an SP3 syntax).448 ========================= =========================================================================449 450.. _amdgpu_synid_xnack:451.. _amdgpu_synid_xnack_mask:452 453xnack_mask454----------455 456Xnack mask, 64-bits wide. Holds a 64-bit mask of which threads457received an *XNACK* due to a vector memory operation.458 459For availability of *xnack* feature, refer to :ref:`this table<amdgpu-processors>`.460 461 ============================== =====================================================462 Syntax Description463 ============================== =====================================================464 xnack_mask 64-bit *xnack mask* register.465 [xnack_mask] 64-bit *xnack mask* register (an SP3 syntax).466 [xnack_mask_lo,xnack_mask_hi] 64-bit *xnack mask* register (an SP3 syntax).467 ============================== =====================================================468 469High and low 32 bits of *xnack mask* may be accessed as separate registers:470 471 ===================== ==============================================================472 Syntax Description473 ===================== ==============================================================474 xnack_mask_lo Low 32 bits of *xnack mask* register.475 xnack_mask_hi High 32 bits of *xnack mask* register.476 [xnack_mask_lo] Low 32 bits of *xnack mask* register (an SP3 syntax).477 [xnack_mask_hi] High 32 bits of *xnack mask* register (an SP3 syntax).478 ===================== ==============================================================479 480.. _amdgpu_synid_vcc:481.. _amdgpu_synid_vcc_lo:482.. _amdgpu_synid_vcc_hi:483 484vcc485---486 487Vector condition code, 64-bits wide. A bit mask with one bit per thread;488it holds the result of a vector compare operation.489 490Note that GFX10+ H/W does not use high 32 bits of *vcc* in *wave32* mode.491 492 ================ =========================================================================493 Syntax Description494 ================ =========================================================================495 vcc 64-bit *vector condition code* register.496 [vcc] 64-bit *vector condition code* register (an SP3 syntax).497 [vcc_lo,vcc_hi] 64-bit *vector condition code* register (an SP3 syntax).498 ================ =========================================================================499 500High and low 32 bits of *vector condition code* may be accessed as separate registers:501 502 ================ =========================================================================503 Syntax Description504 ================ =========================================================================505 vcc_lo Low 32 bits of *vector condition code* register.506 vcc_hi High 32 bits of *vector condition code* register.507 [vcc_lo] Low 32 bits of *vector condition code* register (an SP3 syntax).508 [vcc_hi] High 32 bits of *vector condition code* register (an SP3 syntax).509 ================ =========================================================================510 511.. _amdgpu_synid_m0:512 513m0514--515 516A 32-bit memory register. It has various uses,517including register indexing and bounds checking.518 519 =========== ===================================================520 Syntax Description521 =========== ===================================================522 m0 A 32-bit *memory* register.523 [m0] A 32-bit *memory* register (an SP3 syntax).524 =========== ===================================================525 526.. _amdgpu_synid_exec:527.. _amdgpu_synid_exec_lo:528.. _amdgpu_synid_exec_hi:529 530exec531----532 533Execute mask, 64-bits wide. A bit mask with one bit per thread,534which is applied to vector instructions and controls which threads execute535and which ignore the instruction.536 537Note that GFX10+ H/W does not use high 32 bits of *exec* in *wave32* mode.538 539 ===================== =================================================================540 Syntax Description541 ===================== =================================================================542 exec 64-bit *execute mask* register.543 [exec] 64-bit *execute mask* register (an SP3 syntax).544 [exec_lo,exec_hi] 64-bit *execute mask* register (an SP3 syntax).545 ===================== =================================================================546 547High and low 32 bits of *execute mask* may be accessed as separate registers:548 549 ===================== =================================================================550 Syntax Description551 ===================== =================================================================552 exec_lo Low 32 bits of *execute mask* register.553 exec_hi High 32 bits of *execute mask* register.554 [exec_lo] Low 32 bits of *execute mask* register (an SP3 syntax).555 [exec_hi] High 32 bits of *execute mask* register (an SP3 syntax).556 ===================== =================================================================557 558.. _amdgpu_synid_vccz:559 560vccz561----562 563A single bit flag indicating that the :ref:`vcc<amdgpu_synid_vcc>`564is all zeros.565 566Note: when GFX10+ operates in *wave32* mode, this register reflects567the state of :ref:`vcc_lo<amdgpu_synid_vcc_lo>`.568 569.. _amdgpu_synid_execz:570 571execz572-----573 574A single bit flag indicating that the :ref:`exec<amdgpu_synid_exec>`575is all zeros.576 577Note: when GFX10+ operates in *wave32* mode, this register reflects578the state of :ref:`exec_lo<amdgpu_synid_exec>`.579 580.. _amdgpu_synid_scc:581 582scc583---584 585A single bit flag indicating the result of a scalar compare operation.586 587.. _amdgpu_synid_lds_direct:588 589lds_direct590----------591 592A special operand which supplies a 32-bit value593fetched from *LDS* memory using :ref:`m0<amdgpu_synid_m0>` as an address.594 595.. _amdgpu_synid_null:596 597null598----599 600This is a special operand that may be used as a source or a destination.601 602When used as a destination, the result of the operation is discarded.603 604When used as a source, it supplies zero value.605 606.. _amdgpu_synid_constant:607 608inline constant609---------------610 611An *inline constant* is an integer or a floating-point value612encoded as a part of an instruction. Compare *inline constants*613with :ref:`literals<amdgpu_synid_literal>`.614 615Inline constants include:616 617* :ref:`Integer inline constants<amdgpu_synid_iconst>`;618* :ref:`Floating-point inline constants<amdgpu_synid_fconst>`;619* :ref:`Inline values<amdgpu_synid_ival>`.620 621If a number may be encoded as either622a :ref:`literal<amdgpu_synid_literal>` or623a :ref:`constant<amdgpu_synid_constant>`,624the assembler selects the latter encoding as more efficient.625 626.. _amdgpu_synid_iconst:627 628iconst629~~~~~~630 631An :ref:`integer number<amdgpu_synid_integer_number>` or632an :ref:`absolute expression<amdgpu_synid_absolute_expression>`633encoded as an *inline constant*.634 635Only a small fraction of integer numbers may be encoded as *inline constants*.636They are enumerated in the table below.637Other integer numbers are encoded as :ref:`literals<amdgpu_synid_literal>`.638 639 ================================== ====================================640 Value Note641 ================================== ====================================642 {0..64} Positive integer inline constants.643 {-16..-1} Negative integer inline constants.644 ================================== ====================================645 646.. _amdgpu_synid_fconst:647 648fconst649~~~~~~650 651A :ref:`floating-point number<amdgpu_synid_floating-point_number>`652encoded as an *inline constant*.653 654Only a small fraction of floating-point numbers may be encoded655as *inline constants*. They are enumerated in the table below.656Other floating-point numbers are encoded as657:ref:`literals<amdgpu_synid_literal>`.658 659 ===================== ===================================================== ==================660 Value Note Availability661 ===================== ===================================================== ==================662 0.0 The same as integer constant 0. All GPUs663 0.5 Floating-point constant 0.5 All GPUs664 1.0 Floating-point constant 1.0 All GPUs665 2.0 Floating-point constant 2.0 All GPUs666 4.0 Floating-point constant 4.0 All GPUs667 -0.5 Floating-point constant -0.5 All GPUs668 -1.0 Floating-point constant -1.0 All GPUs669 -2.0 Floating-point constant -2.0 All GPUs670 -4.0 Floating-point constant -4.0 All GPUs671 0.1592 1.0/(2.0*pi). Use only for 16-bit operands. GFX8+672 0.15915494 1.0/(2.0*pi). Use only for 16- and 32-bit operands. GFX8+673 0.15915494309189532 1.0/(2.0*pi). GFX8+674 ===================== ===================================================== ==================675 676.. WARNING:: Floating-point inline constants cannot be used with *16-bit integer* operands. \677 Assembler encodes these values as literals.678 679.. _amdgpu_synid_ival:680 681ival682~~~~683 684A symbolic operand encoded as an *inline constant*.685These operands provide read-only access to H/W registers.686 687 ===================== ========================= ================================================ =============688 Syntax Alternative Syntax (SP3) Note Availability689 ===================== ========================= ================================================ =============690 shared_base src_shared_base Base address of shared memory region. GFX9+691 shared_limit src_shared_limit Address of the end of shared memory region. GFX9+692 private_base src_private_base Base address of private memory region. GFX9+693 private_limit src_private_limit Address of the end of private memory region. GFX9+694 pops_exiting_wave_id src_pops_exiting_wave_id A dedicated counter for POPS. GFX9, GFX10695 ===================== ========================= ================================================ =============696 697.. _amdgpu_synid_literal:698 699literal700-------701 702A *literal* is a 64-bit value encoded as a separate70332-bit dword in the instruction stream. Compare *literals*704with :ref:`inline constants<amdgpu_synid_constant>`.705 706If a number may be encoded as either707a :ref:`literal<amdgpu_synid_literal>` or708an :ref:`inline constant<amdgpu_synid_constant>`,709assembler selects the latter encoding as more efficient.710 711Literals may be specified as712:ref:`integer numbers<amdgpu_synid_integer_number>`,713:ref:`floating-point numbers<amdgpu_synid_floating-point_number>`,714:ref:`absolute expressions<amdgpu_synid_absolute_expression>` or715:ref:`relocatable expressions<amdgpu_synid_relocatable_expression>`.716 717An instruction may use only one literal,718but several operands may refer to the same literal.719 720.. _amdgpu_synid_uimm8:721 722uimm8723-----724 725An 8-bit :ref:`integer number<amdgpu_synid_integer_number>`726or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.727The value must be in the range 0..0xFF.728 729.. _amdgpu_synid_uimm32:730 731uimm32732------733 734A 32-bit :ref:`integer number<amdgpu_synid_integer_number>`735or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.736The value must be in the range 0..0xFFFFFFFF.737 738.. _amdgpu_synid_uimm20:739 740uimm20741------742 743A 20-bit :ref:`integer number<amdgpu_synid_integer_number>`744or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.745 746The value must be in the range 0..0xFFFFF.747 748.. _amdgpu_synid_simm21:749 750simm21751------752 753A 21-bit :ref:`integer number<amdgpu_synid_integer_number>`754or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.755 756The value must be in the range -0x100000..0x0FFFFF.757 758.. _amdgpu_synid_simm8:759 760simm8761-----762 763An 8-bit :ref:`integer number<amdgpu_synid_integer_number>`764or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.765 766.. _amdgpu_synid_off:767 768off769---770 771A special entity which indicates that the value of this operand is not used.772 773 ================================== ===================================================774 Syntax Description775 ================================== ===================================================776 off Indicates an unused operand.777 ================================== ===================================================778 779 780.. _amdgpu_synid_number:781 782Numbers783=======784 785.. _amdgpu_synid_integer_number:786 787Integer Numbers788---------------789 790Integer numbers are 64 bits wide.791They are converted to :ref:`expected operand type<amdgpu_syn_instruction_type>`792as described :ref:`here<amdgpu_synid_int_conv>`.793 794Integer numbers may be specified in binary, octal,795hexadecimal and decimal formats:796 797 ============ =============================== ========798 Format Syntax Example799 ============ =============================== ========800 Decimal [-]?[1-9][0-9]* -1234801 Binary [-]?0b[01]+ 0b1010802 Octal [-]?0[0-7]+ 010803 Hexadecimal [-]?0x[0-9a-fA-F]+ 0xff804 \ [-]?[0x]?[0-9][0-9a-fA-F]*[hH] 0ffh805 ============ =============================== ========806 807.. _amdgpu_synid_floating-point_number:808 809Floating-Point Numbers810----------------------811 812All floating-point numbers are handled as double (64 bits wide).813They are converted to814:ref:`expected operand type<amdgpu_syn_instruction_type>`815as described :ref:`here<amdgpu_synid_fp_conv>`.816 817Floating-point numbers may be specified in hexadecimal and decimal formats:818 819 ============ ======================================================== ====================== ====================820 Format Syntax Examples Note821 ============ ======================================================== ====================== ====================822 Decimal [-]?[0-9]*[.][0-9]*([eE][+-]?[0-9]*)? -1.234, 234e2 Must include either823 a decimal separator824 or an exponent.825 Hexadecimal [-]0x[0-9a-fA-F]*(.[0-9a-fA-F]*)?[pP][+-]?[0-9a-fA-F]+ -0x1afp-10, 0x.1afp10826 ============ ======================================================== ====================== ====================827 828.. _amdgpu_synid_expression:829 830Expressions831===========832 833An expression is evaluated to a 64-bit integer.834Note that floating-point expressions are not supported.835 836There are two kinds of expressions:837 838* :ref:`Absolute<amdgpu_synid_absolute_expression>`.839* :ref:`Relocatable<amdgpu_synid_relocatable_expression>`.840 841.. _amdgpu_synid_absolute_expression:842 843Absolute Expressions844--------------------845 846The value of an absolute expression does not change after program relocation.847Absolute expressions must not include unassigned and relocatable values848such as labels.849 850Absolute expressions are evaluated to 64-bit integer values and converted to851:ref:`expected operand type<amdgpu_syn_instruction_type>`852as described :ref:`here<amdgpu_synid_int_conv>`.853 854Examples:855 856.. parsed-literal::857 858 x = -1859 y = x + 10860 861.. _amdgpu_synid_relocatable_expression:862 863Relocatable Expressions864-----------------------865 866The value of a relocatable expression depends on program relocation.867 868Note that use of relocatable expressions is limited to branch targets869and 32-bit integer operands.870 871A relocatable expression is evaluated to a 64-bit integer value,872which depends on operand kind and873:ref:`relocation type<amdgpu-relocation-records>` of symbol(s)874used in the expression. For example, if an instruction refers to a label,875this reference is evaluated to an offset from the address after876the instruction to the label address:877 878.. parsed-literal::879 880 label:881 v_add_co_u32_e32 v0, vcc, label, v1 // 'label' operand is evaluated to -4882 883Note that values of relocatable expressions are usually unknown884at assembly time; they are resolved later by a linker and converted to885:ref:`expected operand type<amdgpu_syn_instruction_type>`886as described :ref:`here<amdgpu_synid_rl_conv>`.887 888Operands and Operations889-----------------------890 891Expressions are composed of 64-bit integer operands and operations.892Operands include :ref:`integer numbers<amdgpu_synid_integer_number>`893and :ref:`symbols<amdgpu_synid_symbol>`.894 895Expressions may also use "." which is a reference896to the current PC (program counter).897 898:ref:`Unary<amdgpu_synid_expression_un_op>` and899:ref:`binary<amdgpu_synid_expression_bin_op>`900operations produce 64-bit integer results.901 902Syntax of Expressions903---------------------904 905Syntax of expressions is shown below::906 907 expr ::= expr binop expr | primaryexpr ;908 909 primaryexpr ::= '(' expr ')' | symbol | number | '.' | unop primaryexpr ;910 911 binop ::= '&&'912 | '||'913 | '|'914 | '^'915 | '&'916 | '!'917 | '=='918 | '!='919 | '<>'920 | '<'921 | '<='922 | '>'923 | '>='924 | '<<'925 | '>>'926 | '+'927 | '-'928 | '*'929 | '/'930 | '%' ;931 932 unop ::= '~'933 | '+'934 | '-'935 | '!' ;936 937.. _amdgpu_synid_expression_bin_op:938 939Binary Operators940----------------941 942Binary operators are described in the following table.943They operate on and produce 64-bit integers.944Operators with higher priority are performed first.945 946 ========== ========= ===============================================947 Operator Priority Meaning948 ========== ========= ===============================================949 \* 5 Integer multiplication.950 / 5 Integer division.951 % 5 Integer signed remainder.952 \+ 4 Integer addition.953 \- 4 Integer subtraction.954 << 3 Integer shift left.955 >> 3 Logical shift right.956 == 2 Equality comparison.957 != 2 Inequality comparison.958 <> 2 Inequality comparison.959 < 2 Signed less than comparison.960 <= 2 Signed less than or equal comparison.961 > 2 Signed greater than comparison.962 >= 2 Signed greater than or equal comparison.963 \| 1 Bitwise or.964 ^ 1 Bitwise xor.965 & 1 Bitwise and.966 && 0 Logical and.967 || 0 Logical or.968 ========== ========= ===============================================969 970.. _amdgpu_synid_expression_un_op:971 972Unary Operators973---------------974 975Unary operators are described in the following table.976They operate on and produce 64-bit integers.977 978 ========== ===============================================979 Operator Meaning980 ========== ===============================================981 ! Logical negation.982 ~ Bitwise negation.983 \+ Integer unary plus.984 \- Integer unary minus.985 ========== ===============================================986 987.. _amdgpu_synid_symbol:988 989Symbols990-------991 992A symbol is a named 64-bit integer value, representing a relocatable993address or an absolute (non-relocatable) number.994 995Symbol names have the following syntax:996 ``[a-zA-Z_.][a-zA-Z0-9_$.@]*``997 998The table below provides several examples of syntax used for symbol definition.999 1000 ================ ==========================================================1001 Syntax Meaning1002 ================ ==========================================================1003 .globl <S> Declares a global symbol S without assigning it a value.1004 .set <S>, <E> Assigns the value of an expression E to a symbol S.1005 <S> = <E> Assigns the value of an expression E to a symbol S.1006 <S>: Declares a label S and assigns it the current PC value.1007 ================ ==========================================================1008 1009A symbol may be used before it is declared or assigned;1010unassigned symbols are assumed to be PC-relative.1011 1012Additional information about symbols may be found :ref:`here<amdgpu-symbols>`.1013 1014.. _amdgpu_synid_conv:1015 1016Type and Size Conversion1017========================1018 1019This section describes what happens when a 64-bit1020:ref:`integer number<amdgpu_synid_integer_number>`, a1021:ref:`floating-point number<amdgpu_synid_floating-point_number>` or an1022:ref:`expression<amdgpu_synid_expression>`1023is used for an operand which has a different type or size.1024 1025.. _amdgpu_synid_int_conv:1026 1027Conversion of Integer Values1028----------------------------1029 1030Instruction operands may be specified as 64-bit1031:ref:`integer numbers<amdgpu_synid_integer_number>` or1032:ref:`absolute expressions<amdgpu_synid_absolute_expression>`.1033These values are converted to the1034:ref:`expected operand type<amdgpu_syn_instruction_type>`1035using the following steps:1036 10371. *Validation*. Assembler checks if the input value may be truncated1038without loss to the required *truncation width* (see the table below).1039There are two cases when this operation is enabled:1040 1041 * The truncated bits are all 0.1042 * The truncated bits are all 1 and the value after truncation has its MSB bit set.1043 1044In all other cases, the assembler triggers an error.1045 10462. *Conversion*. The input value is converted to the expected type1047as described in the table below. Depending on operand kind, this conversion1048is performed by either assembler or AMDGPU H/W (or both).1049 1050 ============== ================= =============== ====================================================================1051 Expected type Truncation Width Conversion Description1052 ============== ================= =============== ====================================================================1053 i16, u16, b16 16 num.u16 Truncate to 16 bits.1054 i32, u32, b32 32 num.u32 Truncate to 32 bits.1055 i64 32 {-1,num.i32} Truncate to 32 bits and then sign-extend the result to 64 bits.1056 u64, b64 32 {0,num.u32} Truncate to 32 bits and then zero-extend the result to 64 bits.1057 f16 16 num.u16 Use low 16 bits as an f16 value.1058 f32 32 num.u32 Use low 32 bits as an f32 value.1059 f64 32 {num.u32,0} Use low 32 bits of the number as high 32 bits1060 of the result; low 32 bits of the result are zeroed.1061 ============== ================= =============== ====================================================================1062 1063Examples of enabled conversions:1064 1065.. parsed-literal::1066 1067 // GFX91068 1069 v_add_u16 v0, -1, 0 // src0 = 0xFFFF1070 v_add_f16 v0, -1, 0 // src0 = 0xFFFF (NaN)1071 //1072 v_add_u32 v0, -1, 0 // src0 = 0xFFFFFFFF1073 v_add_f32 v0, -1, 0 // src0 = 0xFFFFFFFF (NaN)1074 //1075 v_add_u16 v0, 0xff00, v0 // src0 = 0xff001076 v_add_u16 v0, 0xffffffffffffff00, v0 // src0 = 0xff001077 v_add_u16 v0, -256, v0 // src0 = 0xff001078 //1079 s_bfe_i64 s[0:1], 0xffefffff, s3 // src0 = 0xffffffffffefffff1080 s_bfe_u64 s[0:1], 0xffefffff, s3 // src0 = 0x00000000ffefffff1081 v_ceil_f64_e32 v[0:1], 0xffefffff // src0 = 0xffefffff00000000 (-1.7976922776554302e308)1082 //1083 x = 0xffefffff //1084 s_bfe_i64 s[0:1], x, s3 // src0 = 0xffffffffffefffff1085 s_bfe_u64 s[0:1], x, s3 // src0 = 0x00000000ffefffff1086 v_ceil_f64_e32 v[0:1], x // src0 = 0xffefffff00000000 (-1.7976922776554302e308)1087 1088Examples of disabled conversions:1089 1090.. parsed-literal::1091 1092 // GFX91093 1094 v_add_u16 v0, 0x1ff00, v0 // truncated bits are not all 0 or 11095 v_add_u16 v0, 0xffffffffffff00ff, v0 // truncated bits do not match MSB of the result1096 1097.. _amdgpu_synid_fp_conv:1098 1099Conversion of Floating-Point Values1100-----------------------------------1101 1102Instruction operands may be specified as 64-bit1103:ref:`floating-point numbers<amdgpu_synid_floating-point_number>`.1104These values are converted to the1105:ref:`expected operand type<amdgpu_syn_instruction_type>`1106using the following steps:1107 11081. *Validation*. Assembler checks if the input f64 number can be converted1109to the *required floating-point type* (see the table below) without overflow1110or underflow. Precision lost is allowed. If this conversion is not possible,1111the assembler triggers an error.1112 11132. *Conversion*. The input value is converted to the expected type1114as described in the table below. Depending on operand kind, this is1115performed by either assembler or AMDGPU H/W (or both).1116 1117 ============== ================ ================= =================================================================1118 Expected type Required FP Type Conversion Description1119 ============== ================ ================= =================================================================1120 i16, u16, b16 f16 f16(num) Convert to f16 and use bits of the result as an integer value.1121 The value has to be encoded as a literal, or an error occurs.1122 Note that the value cannot be encoded as an inline constant.1123 i32, u32, b32 f32 f32(num) Convert to f32 and use bits of the result as an integer value.1124 i64, u64, b64 \- \- Conversion disabled.1125 f16 f16 f16(num) Convert to f16.1126 f32 f32 f32(num) Convert to f32.1127 f64 f64 {num.u32.hi,0} Use high 32 bits of the number as high 32 bits of the result;1128 zero-fill low 32 bits of the result.1129 1130 Note that the result may differ from the original number.1131 ============== ================ ================= =================================================================1132 1133Examples of enabled conversions:1134 1135.. parsed-literal::1136 1137 // GFX91138 1139 v_add_f16 v0, 1.0, 0 // src0 = 0x3C00 (1.0)1140 v_add_u16 v0, 1.0, 0 // src0 = 0x3C001141 //1142 v_add_f32 v0, 1.0, 0 // src0 = 0x3F800000 (1.0)1143 v_add_u32 v0, 1.0, 0 // src0 = 0x3F8000001144 1145 // src0 before conversion:1146 // 1.7976931348623157e308 = 0x7fefffffffffffff1147 // src0 after conversion:1148 // 1.7976922776554302e308 = 0x7fefffff000000001149 v_ceil_f64 v[0:1], 1.7976931348623157e3081150 1151 v_add_f16 v1, 65500.0, v2 // ok for f16.1152 v_add_f32 v1, 65600.0, v2 // ok for f32, but would result in overflow for f16.1153 1154Examples of disabled conversions:1155 1156.. parsed-literal::1157 1158 // GFX91159 1160 v_add_f16 v1, 65600.0, v2 // overflow1161 1162.. _amdgpu_synid_rl_conv:1163 1164Conversion of Relocatable Values1165--------------------------------1166 1167:ref:`Relocatable expressions<amdgpu_synid_relocatable_expression>`1168may be used with 32-bit integer operands and jump targets.1169 1170When the value of a relocatable expression is resolved by a linker, it is1171converted as needed and truncated to the operand size. The conversion depends1172on :ref:`relocation type<amdgpu-relocation-records>` and operand kind.1173 1174For example, when a 32-bit operand of an instruction refers1175to a relocatable expression *expr*, this reference is evaluated1176to a 64-bit offset from the address after the1177instruction to the address being referenced, *counted in bytes*.1178Then the value is truncated to 32 bits and encoded as a literal:1179 1180.. parsed-literal::1181 1182 expr = .1183 v_add_co_u32_e32 v0, vcc, expr, v1 // 'expr' operand is evaluated to -41184 // and then truncated to 0xFFFFFFFC1185 1186As another example, when a branch instruction refers to a label,1187this reference is evaluated to an offset from the address after the1188instruction to the label address, *counted in dwords*.1189Then the value is truncated to 16 bits:1190 1191.. parsed-literal::1192 1193 label:1194 s_branch label // 'label' operand is evaluated to -1 and truncated to 0xFFFF1195