1===================================== 2Syntax of AMDGPU Instruction Operands 3===================================== 4 5.. contents:: 6 :local: 7 8Conventions 9=========== 10 11The following notation is used throughout this document: 12 13 =================== ============================================================================= 14 Notation Description 15 =================== ============================================================================= 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 22Operands 23======== 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 Description 38 =================================================== ==================================================================== 39 **v**\<N> A single 32-bit *vector* register. 40 41 *N* must be a decimal 42 :ref:`integer number<amdgpu_synid_integer_number>`. 43 **v[**\ <N>\ **]** A single 32-bit *vector* register. 44 45 *N* may be specified as an 46 :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 as 51 :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 decimal 56 :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 GFX940 have an additional alignment requirement: 67pairs of *vector* registers must be even-aligned 68(first register must be even). 69 70Examples: 71 72.. parsed-literal:: 73 74 v255 75 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 Description 93 ===================================== ================================================= 94 **[Vm**, \ **Vn**, ... **Vk**\ **]** A sequence of 32-bit *vector* registers. 95 Each register may be specified using the syntax 96 defined :ref:`above<amdgpu_synid_v>`. 97 98 In contrast with the standard syntax, registers 99 in *NSA* sequence are not required to have 100 consecutive indices. Moreover, the same register 101 may appear in the sequence more than once. 102 103 GFX11+ has an additional limitation: if address 104 size occupies more than 5 dwords, registers 105 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 Description 131 =================================================== ==================================================================== 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 v127 144 145.. _amdgpu_synid_a: 146 147a 148- 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) Description 158 =================================================== ========================================================= ==================================================================== 159 **a**\<N> **acc**\<N> A single 32-bit *accumulator* register. 160 161 *N* must be a decimal 162 :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 an 166 :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 as 171 :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 decimal 176 :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 GFX940 have an additional alignment requirement: 187pairs of *accumulator* registers must be even-aligned 188(first register must be even). 189 190Examples: 191 192.. parsed-literal:: 193 194 a255 195 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 acc0 205 acc[1] 206 [acc250] 207 [acc2,acc3] 208 209.. _amdgpu_synid_s: 210 211s 212- 213 214Scalar 32-bit registers. The number of available *scalar* registers depends on the GPU: 215 216 ======= ============================ 217 GPU Number of *scalar* registers 218 ======= ============================ 219 GFX7 104 220 GFX8 102 221 GFX9 102 222 GFX10+ 106 223 ======= ============================ 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 Description 233 ======================================================== ==================================================================== 234 **s**\ <N> A single 32-bit *scalar* register. 235 236 *N* must be a decimal 237 :ref:`integer number<amdgpu_synid_integer_number>`. 238 239 **s[**\ <N>\ **]** A single 32-bit *scalar* register. 240 241 *N* may be specified as an 242 :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 as 247 :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 decimal 253 :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 s0 269 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 287trap 288---- 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 298ttmp 299---- 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* registers 306 ======= =========================== 307 GFX7 12 308 GFX8 12 309 GFX9 16 310 GFX10+ 16 311 ======= =========================== 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 Description 321 ============================================================= ==================================================================== 322 **ttmp**\ <N> A single 32-bit *ttmp* register. 323 324 *N* must be a decimal 325 :ref:`integer number<amdgpu_synid_integer_number>`. 326 **ttmp[**\ <N>\ **]** A single 32-bit *ttmp* register. 327 328 *N* may be specified as an 329 :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 as 334 :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 decimal 339 :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 ttmp0 355 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 373tba 374--- 375 376Trap base address, 64-bits wide. Holds the pointer to the current 377trap handler program. 378 379 ================== ======================================================================= ============= 380 Syntax Description Availability 381 ================== ======================================================================= ============= 382 tba 64-bit *trap base address* register. GFX7, GFX8 383 [tba] 64-bit *trap base address* register (an SP3 syntax). GFX7, GFX8 384 [tba_lo,tba_hi] 64-bit *trap base address* register (an SP3 syntax). GFX7, GFX8 385 ================== ======================================================================= ============= 386 387High and low 32 bits of *trap base address* may be accessed as separate registers: 388 389 ================== ======================================================================= ============= 390 Syntax Description Availability 391 ================== ======================================================================= ============= 392 tba_lo Low 32 bits of *trap base address* register. GFX7, GFX8 393 tba_hi High 32 bits of *trap base address* register. GFX7, GFX8 394 [tba_lo] Low 32 bits of *trap base address* register (an SP3 syntax). GFX7, GFX8 395 [tba_hi] High 32 bits of *trap base address* register (an SP3 syntax). GFX7, GFX8 396 ================== ======================================================================= ============= 397 398.. _amdgpu_synid_tma: 399 400tma 401--- 402 403Trap memory address, 64-bits wide. 404 405 ================= ======================================================================= ================== 406 Syntax Description Availability 407 ================= ======================================================================= ================== 408 tma 64-bit *trap memory address* register. GFX7, GFX8 409 [tma] 64-bit *trap memory address* register (an SP3 syntax). GFX7, GFX8 410 [tma_lo,tma_hi] 64-bit *trap memory address* register (an SP3 syntax). GFX7, GFX8 411 ================= ======================================================================= ================== 412 413High and low 32 bits of *trap memory address* may be accessed as separate registers: 414 415 ================= ======================================================================= ================== 416 Syntax Description Availability 417 ================= ======================================================================= ================== 418 tma_lo Low 32 bits of *trap memory address* register. GFX7, GFX8 419 tma_hi High 32 bits of *trap memory address* register. GFX7, GFX8 420 [tma_lo] Low 32 bits of *trap memory address* register (an SP3 syntax). GFX7, GFX8 421 [tma_hi] High 32 bits of *trap memory address* register (an SP3 syntax). GFX7, GFX8 422 ================= ======================================================================= ================== 423 424.. _amdgpu_synid_flat_scratch: 425 426flat_scratch 427------------ 428 429Flat scratch address, 64-bits wide. Holds the base address of scratch memory. 430 431 ================================== ================================================================ 432 Syntax Description 433 ================================== ================================================================ 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 Description 443 ========================= ========================================================================= 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_mask 454---------- 455 456Xnack mask, 64-bits wide. Holds a 64-bit mask of which threads 457received 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 Description 463 ============================== ===================================================== 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 Description 473 ===================== ============================================================== 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 483vcc 484--- 485 486Vector condition code, 64-bits wide. A bit mask with one bit per thread; 487it holds the result of a vector compare operation. 488 489Note that GFX10+ H/W does not use high 32 bits of *vcc* in *wave32* mode. 490 491 ================ ========================================================================= 492 Syntax Description 493 ================ ========================================================================= 494 vcc 64-bit *vector condition code* register. 495 [vcc] 64-bit *vector condition code* register (an SP3 syntax). 496 [vcc_lo,vcc_hi] 64-bit *vector condition code* register (an SP3 syntax). 497 ================ ========================================================================= 498 499High and low 32 bits of *vector condition code* may be accessed as separate registers: 500 501 ================ ========================================================================= 502 Syntax Description 503 ================ ========================================================================= 504 vcc_lo Low 32 bits of *vector condition code* register. 505 vcc_hi High 32 bits of *vector condition code* register. 506 [vcc_lo] Low 32 bits of *vector condition code* register (an SP3 syntax). 507 [vcc_hi] High 32 bits of *vector condition code* register (an SP3 syntax). 508 ================ ========================================================================= 509 510.. _amdgpu_synid_m0: 511 512m0 513-- 514 515A 32-bit memory register. It has various uses, 516including register indexing and bounds checking. 517 518 =========== =================================================== 519 Syntax Description 520 =========== =================================================== 521 m0 A 32-bit *memory* register. 522 [m0] A 32-bit *memory* register (an SP3 syntax). 523 =========== =================================================== 524 525.. _amdgpu_synid_exec: 526 527exec 528---- 529 530Execute mask, 64-bits wide. A bit mask with one bit per thread, 531which is applied to vector instructions and controls which threads execute 532and which ignore the instruction. 533 534Note that GFX10+ H/W does not use high 32 bits of *exec* in *wave32* mode. 535 536 ===================== ================================================================= 537 Syntax Description 538 ===================== ================================================================= 539 exec 64-bit *execute mask* register. 540 [exec] 64-bit *execute mask* register (an SP3 syntax). 541 [exec_lo,exec_hi] 64-bit *execute mask* register (an SP3 syntax). 542 ===================== ================================================================= 543 544High and low 32 bits of *execute mask* may be accessed as separate registers: 545 546 ===================== ================================================================= 547 Syntax Description 548 ===================== ================================================================= 549 exec_lo Low 32 bits of *execute mask* register. 550 exec_hi High 32 bits of *execute mask* register. 551 [exec_lo] Low 32 bits of *execute mask* register (an SP3 syntax). 552 [exec_hi] High 32 bits of *execute mask* register (an SP3 syntax). 553 ===================== ================================================================= 554 555.. _amdgpu_synid_vccz: 556 557vccz 558---- 559 560A single bit flag indicating that the :ref:`vcc<amdgpu_synid_vcc>` 561is all zeros. 562 563Note: when GFX10+ operates in *wave32* mode, this register reflects 564the state of :ref:`vcc_lo<amdgpu_synid_vcc_lo>`. 565 566.. _amdgpu_synid_execz: 567 568execz 569----- 570 571A single bit flag indicating that the :ref:`exec<amdgpu_synid_exec>` 572is all zeros. 573 574Note: when GFX10+ operates in *wave32* mode, this register reflects 575the state of :ref:`exec_lo<amdgpu_synid_exec>`. 576 577.. _amdgpu_synid_scc: 578 579scc 580--- 581 582A single bit flag indicating the result of a scalar compare operation. 583 584.. _amdgpu_synid_lds_direct: 585 586lds_direct 587---------- 588 589A special operand which supplies a 32-bit value 590fetched from *LDS* memory using :ref:`m0<amdgpu_synid_m0>` as an address. 591 592.. _amdgpu_synid_null: 593 594null 595---- 596 597This is a special operand that may be used as a source or a destination. 598 599When used as a destination, the result of the operation is discarded. 600 601When used as a source, it supplies zero value. 602 603.. _amdgpu_synid_constant: 604 605inline constant 606--------------- 607 608An *inline constant* is an integer or a floating-point value 609encoded as a part of an instruction. Compare *inline constants* 610with :ref:`literals<amdgpu_synid_literal>`. 611 612Inline constants include: 613 614* :ref:`Integer inline constants<amdgpu_synid_iconst>`; 615* :ref:`Floating-point inline constants<amdgpu_synid_fconst>`; 616* :ref:`Inline values<amdgpu_synid_ival>`. 617 618If a number may be encoded as either 619a :ref:`literal<amdgpu_synid_literal>` or 620a :ref:`constant<amdgpu_synid_constant>`, 621the assembler selects the latter encoding as more efficient. 622 623.. _amdgpu_synid_iconst: 624 625iconst 626~~~~~~ 627 628An :ref:`integer number<amdgpu_synid_integer_number>` or 629an :ref:`absolute expression<amdgpu_synid_absolute_expression>` 630encoded as an *inline constant*. 631 632Only a small fraction of integer numbers may be encoded as *inline constants*. 633They are enumerated in the table below. 634Other integer numbers are encoded as :ref:`literals<amdgpu_synid_literal>`. 635 636 ================================== ==================================== 637 Value Note 638 ================================== ==================================== 639 {0..64} Positive integer inline constants. 640 {-16..-1} Negative integer inline constants. 641 ================================== ==================================== 642 643.. _amdgpu_synid_fconst: 644 645fconst 646~~~~~~ 647 648A :ref:`floating-point number<amdgpu_synid_floating-point_number>` 649encoded as an *inline constant*. 650 651Only a small fraction of floating-point numbers may be encoded 652as *inline constants*. They are enumerated in the table below. 653Other floating-point numbers are encoded as 654:ref:`literals<amdgpu_synid_literal>`. 655 656 ===================== ===================================================== ================== 657 Value Note Availability 658 ===================== ===================================================== ================== 659 0.0 The same as integer constant 0. All GPUs 660 0.5 Floating-point constant 0.5 All GPUs 661 1.0 Floating-point constant 1.0 All GPUs 662 2.0 Floating-point constant 2.0 All GPUs 663 4.0 Floating-point constant 4.0 All GPUs 664 -0.5 Floating-point constant -0.5 All GPUs 665 -1.0 Floating-point constant -1.0 All GPUs 666 -2.0 Floating-point constant -2.0 All GPUs 667 -4.0 Floating-point constant -4.0 All GPUs 668 0.1592 1.0/(2.0*pi). Use only for 16-bit operands. GFX8+ 669 0.15915494 1.0/(2.0*pi). Use only for 16- and 32-bit operands. GFX8+ 670 0.15915494309189532 1.0/(2.0*pi). GFX8+ 671 ===================== ===================================================== ================== 672 673.. WARNING:: Floating-point inline constants cannot be used with *16-bit integer* operands. \ 674 Assembler encodes these values as literals. 675 676.. _amdgpu_synid_ival: 677 678ival 679~~~~ 680 681A symbolic operand encoded as an *inline constant*. 682These operands provide read-only access to H/W registers. 683 684 ===================== ========================= ================================================ ============= 685 Syntax Alternative Syntax (SP3) Note Availability 686 ===================== ========================= ================================================ ============= 687 shared_base src_shared_base Base address of shared memory region. GFX9+ 688 shared_limit src_shared_limit Address of the end of shared memory region. GFX9+ 689 private_base src_private_base Base address of private memory region. GFX9+ 690 private_limit src_private_limit Address of the end of private memory region. GFX9+ 691 pops_exiting_wave_id src_pops_exiting_wave_id A dedicated counter for POPS. GFX9, GFX10 692 ===================== ========================= ================================================ ============= 693 694.. _amdgpu_synid_literal: 695 696literal 697------- 698 699A *literal* is a 64-bit value encoded as a separate 70032-bit dword in the instruction stream. Compare *literals* 701with :ref:`inline constants<amdgpu_synid_constant>`. 702 703If a number may be encoded as either 704a :ref:`literal<amdgpu_synid_literal>` or 705an :ref:`inline constant<amdgpu_synid_constant>`, 706assembler selects the latter encoding as more efficient. 707 708Literals may be specified as 709:ref:`integer numbers<amdgpu_synid_integer_number>`, 710:ref:`floating-point numbers<amdgpu_synid_floating-point_number>`, 711:ref:`absolute expressions<amdgpu_synid_absolute_expression>` or 712:ref:`relocatable expressions<amdgpu_synid_relocatable_expression>`. 713 714An instruction may use only one literal, 715but several operands may refer to the same literal. 716 717.. _amdgpu_synid_uimm8: 718 719uimm8 720----- 721 722An 8-bit :ref:`integer number<amdgpu_synid_integer_number>` 723or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 724The value must be in the range 0..0xFF. 725 726.. _amdgpu_synid_uimm32: 727 728uimm32 729------ 730 731A 32-bit :ref:`integer number<amdgpu_synid_integer_number>` 732or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 733The value must be in the range 0..0xFFFFFFFF. 734 735.. _amdgpu_synid_uimm20: 736 737uimm20 738------ 739 740A 20-bit :ref:`integer number<amdgpu_synid_integer_number>` 741or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 742 743The value must be in the range 0..0xFFFFF. 744 745.. _amdgpu_synid_simm21: 746 747simm21 748------ 749 750A 21-bit :ref:`integer number<amdgpu_synid_integer_number>` 751or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 752 753The value must be in the range -0x100000..0x0FFFFF. 754 755.. _amdgpu_synid_off: 756 757off 758--- 759 760A special entity which indicates that the value of this operand is not used. 761 762 ================================== =================================================== 763 Syntax Description 764 ================================== =================================================== 765 off Indicates an unused operand. 766 ================================== =================================================== 767 768 769.. _amdgpu_synid_number: 770 771Numbers 772======= 773 774.. _amdgpu_synid_integer_number: 775 776Integer Numbers 777--------------- 778 779Integer numbers are 64 bits wide. 780They are converted to :ref:`expected operand type<amdgpu_syn_instruction_type>` 781as described :ref:`here<amdgpu_synid_int_conv>`. 782 783Integer numbers may be specified in binary, octal, 784hexadecimal and decimal formats: 785 786 ============ =============================== ======== 787 Format Syntax Example 788 ============ =============================== ======== 789 Decimal [-]?[1-9][0-9]* -1234 790 Binary [-]?0b[01]+ 0b1010 791 Octal [-]?0[0-7]+ 010 792 Hexadecimal [-]?0x[0-9a-fA-F]+ 0xff 793 \ [-]?[0x]?[0-9][0-9a-fA-F]*[hH] 0ffh 794 ============ =============================== ======== 795 796.. _amdgpu_synid_floating-point_number: 797 798Floating-Point Numbers 799---------------------- 800 801All floating-point numbers are handled as double (64 bits wide). 802They are converted to 803:ref:`expected operand type<amdgpu_syn_instruction_type>` 804as described :ref:`here<amdgpu_synid_fp_conv>`. 805 806Floating-point numbers may be specified in hexadecimal and decimal formats: 807 808 ============ ======================================================== ====================== ==================== 809 Format Syntax Examples Note 810 ============ ======================================================== ====================== ==================== 811 Decimal [-]?[0-9]*[.][0-9]*([eE][+-]?[0-9]*)? -1.234, 234e2 Must include either 812 a decimal separator 813 or an exponent. 814 Hexadecimal [-]0x[0-9a-fA-F]*(.[0-9a-fA-F]*)?[pP][+-]?[0-9a-fA-F]+ -0x1afp-10, 0x.1afp10 815 ============ ======================================================== ====================== ==================== 816 817.. _amdgpu_synid_expression: 818 819Expressions 820=========== 821 822An expression is evaluated to a 64-bit integer. 823Note that floating-point expressions are not supported. 824 825There are two kinds of expressions: 826 827* :ref:`Absolute<amdgpu_synid_absolute_expression>`. 828* :ref:`Relocatable<amdgpu_synid_relocatable_expression>`. 829 830.. _amdgpu_synid_absolute_expression: 831 832Absolute Expressions 833-------------------- 834 835The value of an absolute expression does not change after program relocation. 836Absolute expressions must not include unassigned and relocatable values 837such as labels. 838 839Absolute expressions are evaluated to 64-bit integer values and converted to 840:ref:`expected operand type<amdgpu_syn_instruction_type>` 841as described :ref:`here<amdgpu_synid_int_conv>`. 842 843Examples: 844 845.. parsed-literal:: 846 847 x = -1 848 y = x + 10 849 850.. _amdgpu_synid_relocatable_expression: 851 852Relocatable Expressions 853----------------------- 854 855The value of a relocatable expression depends on program relocation. 856 857Note that use of relocatable expressions is limited to branch targets 858and 32-bit integer operands. 859 860A relocatable expression is evaluated to a 64-bit integer value, 861which depends on operand kind and 862:ref:`relocation type<amdgpu-relocation-records>` of symbol(s) 863used in the expression. For example, if an instruction refers to a label, 864this reference is evaluated to an offset from the address after 865the instruction to the label address: 866 867.. parsed-literal:: 868 869 label: 870 v_add_co_u32_e32 v0, vcc, label, v1 // 'label' operand is evaluated to -4 871 872Note that values of relocatable expressions are usually unknown 873at assembly time; they are resolved later by a linker and converted to 874:ref:`expected operand type<amdgpu_syn_instruction_type>` 875as described :ref:`here<amdgpu_synid_rl_conv>`. 876 877Operands and Operations 878----------------------- 879 880Expressions are composed of 64-bit integer operands and operations. 881Operands include :ref:`integer numbers<amdgpu_synid_integer_number>` 882and :ref:`symbols<amdgpu_synid_symbol>`. 883 884Expressions may also use "." which is a reference 885to the current PC (program counter). 886 887:ref:`Unary<amdgpu_synid_expression_un_op>` and 888:ref:`binary<amdgpu_synid_expression_bin_op>` 889operations produce 64-bit integer results. 890 891Syntax of Expressions 892--------------------- 893 894Syntax of expressions is shown below:: 895 896 expr ::= expr binop expr | primaryexpr ; 897 898 primaryexpr ::= '(' expr ')' | symbol | number | '.' | unop primaryexpr ; 899 900 binop ::= '&&' 901 | '||' 902 | '|' 903 | '^' 904 | '&' 905 | '!' 906 | '==' 907 | '!=' 908 | '<>' 909 | '<' 910 | '<=' 911 | '>' 912 | '>=' 913 | '<<' 914 | '>>' 915 | '+' 916 | '-' 917 | '*' 918 | '/' 919 | '%' ; 920 921 unop ::= '~' 922 | '+' 923 | '-' 924 | '!' ; 925 926.. _amdgpu_synid_expression_bin_op: 927 928Binary Operators 929---------------- 930 931Binary operators are described in the following table. 932They operate on and produce 64-bit integers. 933Operators with higher priority are performed first. 934 935 ========== ========= =============================================== 936 Operator Priority Meaning 937 ========== ========= =============================================== 938 \* 5 Integer multiplication. 939 / 5 Integer division. 940 % 5 Integer signed remainder. 941 \+ 4 Integer addition. 942 \- 4 Integer subtraction. 943 << 3 Integer shift left. 944 >> 3 Logical shift right. 945 == 2 Equality comparison. 946 != 2 Inequality comparison. 947 <> 2 Inequality comparison. 948 < 2 Signed less than comparison. 949 <= 2 Signed less than or equal comparison. 950 > 2 Signed greater than comparison. 951 >= 2 Signed greater than or equal comparison. 952 \| 1 Bitwise or. 953 ^ 1 Bitwise xor. 954 & 1 Bitwise and. 955 && 0 Logical and. 956 || 0 Logical or. 957 ========== ========= =============================================== 958 959.. _amdgpu_synid_expression_un_op: 960 961Unary Operators 962--------------- 963 964Unary operators are described in the following table. 965They operate on and produce 64-bit integers. 966 967 ========== =============================================== 968 Operator Meaning 969 ========== =============================================== 970 ! Logical negation. 971 ~ Bitwise negation. 972 \+ Integer unary plus. 973 \- Integer unary minus. 974 ========== =============================================== 975 976.. _amdgpu_synid_symbol: 977 978Symbols 979------- 980 981A symbol is a named 64-bit integer value, representing a relocatable 982address or an absolute (non-relocatable) number. 983 984Symbol names have the following syntax: 985 ``[a-zA-Z_.][a-zA-Z0-9_$.@]*`` 986 987The table below provides several examples of syntax used for symbol definition. 988 989 ================ ========================================================== 990 Syntax Meaning 991 ================ ========================================================== 992 .globl <S> Declares a global symbol S without assigning it a value. 993 .set <S>, <E> Assigns the value of an expression E to a symbol S. 994 <S> = <E> Assigns the value of an expression E to a symbol S. 995 <S>: Declares a label S and assigns it the current PC value. 996 ================ ========================================================== 997 998A symbol may be used before it is declared or assigned; 999unassigned symbols are assumed to be PC-relative. 1000 1001Additional information about symbols may be found :ref:`here<amdgpu-symbols>`. 1002 1003.. _amdgpu_synid_conv: 1004 1005Type and Size Conversion 1006======================== 1007 1008This section describes what happens when a 64-bit 1009:ref:`integer number<amdgpu_synid_integer_number>`, a 1010:ref:`floating-point number<amdgpu_synid_floating-point_number>` or an 1011:ref:`expression<amdgpu_synid_expression>` 1012is used for an operand which has a different type or size. 1013 1014.. _amdgpu_synid_int_conv: 1015 1016Conversion of Integer Values 1017---------------------------- 1018 1019Instruction operands may be specified as 64-bit 1020:ref:`integer numbers<amdgpu_synid_integer_number>` or 1021:ref:`absolute expressions<amdgpu_synid_absolute_expression>`. 1022These values are converted to the 1023:ref:`expected operand type<amdgpu_syn_instruction_type>` 1024using the following steps: 1025 10261. *Validation*. Assembler checks if the input value may be truncated 1027without loss to the required *truncation width* (see the table below). 1028There are two cases when this operation is enabled: 1029 1030 * The truncated bits are all 0. 1031 * The truncated bits are all 1 and the value after truncation has its MSB bit set. 1032 1033In all other cases, the assembler triggers an error. 1034 10352. *Conversion*. The input value is converted to the expected type 1036as described in the table below. Depending on operand kind, this conversion 1037is performed by either assembler or AMDGPU H/W (or both). 1038 1039 ============== ================= =============== ==================================================================== 1040 Expected type Truncation Width Conversion Description 1041 ============== ================= =============== ==================================================================== 1042 i16, u16, b16 16 num.u16 Truncate to 16 bits. 1043 i32, u32, b32 32 num.u32 Truncate to 32 bits. 1044 i64 32 {-1,num.i32} Truncate to 32 bits and then sign-extend the result to 64 bits. 1045 u64, b64 32 {0,num.u32} Truncate to 32 bits and then zero-extend the result to 64 bits. 1046 f16 16 num.u16 Use low 16 bits as an f16 value. 1047 f32 32 num.u32 Use low 32 bits as an f32 value. 1048 f64 32 {num.u32,0} Use low 32 bits of the number as high 32 bits 1049 of the result; low 32 bits of the result are zeroed. 1050 ============== ================= =============== ==================================================================== 1051 1052Examples of enabled conversions: 1053 1054.. parsed-literal:: 1055 1056 // GFX9 1057 1058 v_add_u16 v0, -1, 0 // src0 = 0xFFFF 1059 v_add_f16 v0, -1, 0 // src0 = 0xFFFF (NaN) 1060 // 1061 v_add_u32 v0, -1, 0 // src0 = 0xFFFFFFFF 1062 v_add_f32 v0, -1, 0 // src0 = 0xFFFFFFFF (NaN) 1063 // 1064 v_add_u16 v0, 0xff00, v0 // src0 = 0xff00 1065 v_add_u16 v0, 0xffffffffffffff00, v0 // src0 = 0xff00 1066 v_add_u16 v0, -256, v0 // src0 = 0xff00 1067 // 1068 s_bfe_i64 s[0:1], 0xffefffff, s3 // src0 = 0xffffffffffefffff 1069 s_bfe_u64 s[0:1], 0xffefffff, s3 // src0 = 0x00000000ffefffff 1070 v_ceil_f64_e32 v[0:1], 0xffefffff // src0 = 0xffefffff00000000 (-1.7976922776554302e308) 1071 // 1072 x = 0xffefffff // 1073 s_bfe_i64 s[0:1], x, s3 // src0 = 0xffffffffffefffff 1074 s_bfe_u64 s[0:1], x, s3 // src0 = 0x00000000ffefffff 1075 v_ceil_f64_e32 v[0:1], x // src0 = 0xffefffff00000000 (-1.7976922776554302e308) 1076 1077Examples of disabled conversions: 1078 1079.. parsed-literal:: 1080 1081 // GFX9 1082 1083 v_add_u16 v0, 0x1ff00, v0 // truncated bits are not all 0 or 1 1084 v_add_u16 v0, 0xffffffffffff00ff, v0 // truncated bits do not match MSB of the result 1085 1086.. _amdgpu_synid_fp_conv: 1087 1088Conversion of Floating-Point Values 1089----------------------------------- 1090 1091Instruction operands may be specified as 64-bit 1092:ref:`floating-point numbers<amdgpu_synid_floating-point_number>`. 1093These values are converted to the 1094:ref:`expected operand type<amdgpu_syn_instruction_type>` 1095using the following steps: 1096 10971. *Validation*. Assembler checks if the input f64 number can be converted 1098to the *required floating-point type* (see the table below) without overflow 1099or underflow. Precision lost is allowed. If this conversion is not possible, 1100the assembler triggers an error. 1101 11022. *Conversion*. The input value is converted to the expected type 1103as described in the table below. Depending on operand kind, this is 1104performed by either assembler or AMDGPU H/W (or both). 1105 1106 ============== ================ ================= ================================================================= 1107 Expected type Required FP Type Conversion Description 1108 ============== ================ ================= ================================================================= 1109 i16, u16, b16 f16 f16(num) Convert to f16 and use bits of the result as an integer value. 1110 The value has to be encoded as a literal, or an error occurs. 1111 Note that the value cannot be encoded as an inline constant. 1112 i32, u32, b32 f32 f32(num) Convert to f32 and use bits of the result as an integer value. 1113 i64, u64, b64 \- \- Conversion disabled. 1114 f16 f16 f16(num) Convert to f16. 1115 f32 f32 f32(num) Convert to f32. 1116 f64 f64 {num.u32.hi,0} Use high 32 bits of the number as high 32 bits of the result; 1117 zero-fill low 32 bits of the result. 1118 1119 Note that the result may differ from the original number. 1120 ============== ================ ================= ================================================================= 1121 1122Examples of enabled conversions: 1123 1124.. parsed-literal:: 1125 1126 // GFX9 1127 1128 v_add_f16 v0, 1.0, 0 // src0 = 0x3C00 (1.0) 1129 v_add_u16 v0, 1.0, 0 // src0 = 0x3C00 1130 // 1131 v_add_f32 v0, 1.0, 0 // src0 = 0x3F800000 (1.0) 1132 v_add_u32 v0, 1.0, 0 // src0 = 0x3F800000 1133 1134 // src0 before conversion: 1135 // 1.7976931348623157e308 = 0x7fefffffffffffff 1136 // src0 after conversion: 1137 // 1.7976922776554302e308 = 0x7fefffff00000000 1138 v_ceil_f64 v[0:1], 1.7976931348623157e308 1139 1140 v_add_f16 v1, 65500.0, v2 // ok for f16. 1141 v_add_f32 v1, 65600.0, v2 // ok for f32, but would result in overflow for f16. 1142 1143Examples of disabled conversions: 1144 1145.. parsed-literal:: 1146 1147 // GFX9 1148 1149 v_add_f16 v1, 65600.0, v2 // overflow 1150 1151.. _amdgpu_synid_rl_conv: 1152 1153Conversion of Relocatable Values 1154-------------------------------- 1155 1156:ref:`Relocatable expressions<amdgpu_synid_relocatable_expression>` 1157may be used with 32-bit integer operands and jump targets. 1158 1159When the value of a relocatable expression is resolved by a linker, it is 1160converted as needed and truncated to the operand size. The conversion depends 1161on :ref:`relocation type<amdgpu-relocation-records>` and operand kind. 1162 1163For example, when a 32-bit operand of an instruction refers 1164to a relocatable expression *expr*, this reference is evaluated 1165to a 64-bit offset from the address after the 1166instruction to the address being referenced, *counted in bytes*. 1167Then the value is truncated to 32 bits and encoded as a literal: 1168 1169.. parsed-literal:: 1170 1171 expr = . 1172 v_add_co_u32_e32 v0, vcc, expr, v1 // 'expr' operand is evaluated to -4 1173 // and then truncated to 0xFFFFFFFC 1174 1175As another example, when a branch instruction refers to a label, 1176this reference is evaluated to an offset from the address after the 1177instruction to the label address, *counted in dwords*. 1178Then the value is truncated to 16 bits: 1179 1180.. parsed-literal:: 1181 1182 label: 1183 s_branch label // 'label' operand is evaluated to -1 and truncated to 0xFFFF 1184