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* is explained elsewhere. 18 =================== ============================================================================= 19 20.. _amdgpu_syn_operands: 21 22Operands 23======== 24 25.. _amdgpu_synid_v: 26 27v 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 sequences of 1, 2, 3, 4, 8 and 16 *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 equal to 1, 2, 3, 4, 8 or 16. 65 66Examples: 67 68.. parsed-literal:: 69 70 v255 71 v[0] 72 v[0:1] 73 v[1:1] 74 v[0:3] 75 v[2*2] 76 v[1-1:2-1] 77 [v252] 78 [v252,v253,v254,v255] 79 80.. _amdgpu_synid_nsa: 81 82GFX10 *Image* instructions may use special *NSA* (Non-Sequential Address) syntax for *image addresses*: 83 84 ===================================== ================================================= 85 Syntax Description 86 ===================================== ================================================= 87 **[Vm**, \ **Vn**, ... **Vk**\ **]** A sequence of 32-bit *vector* registers. 88 Each register may be specified using syntax 89 defined :ref:`above<amdgpu_synid_v>`. 90 91 In contrast with standard syntax, registers 92 in *NSA* sequence are not required to have 93 consecutive indices. Moreover, the same register 94 may appear in the list more than once. 95 ===================================== ================================================= 96 97Examples: 98 99.. parsed-literal:: 100 101 [v32,v1,v[2]] 102 [v[32],v[1:1],[v2]] 103 [v4,v4,v4,v4] 104 105.. _amdgpu_synid_a: 106 107a 108- 109 110Accumulator registers. There are 256 32-bit accumulator registers. 111 112A sequence of *accumulator* registers may be used to operate with more than 32 bits of data. 113 114Assembler currently supports sequences of 1, 2, 4 and 16 *accumulator* registers. 115 116 =================================================== ========================================================= ==================================================================== 117 Syntax An Alternative Syntax (SP3) Description 118 =================================================== ========================================================= ==================================================================== 119 **a**\<N> **acc**\<N> A single 32-bit *accumulator* register. 120 121 *N* must be a decimal 122 :ref:`integer number<amdgpu_synid_integer_number>`. 123 **a[**\ <N>\ **]** **acc[**\ <N>\ **]** A single 32-bit *accumulator* register. 124 125 *N* may be specified as an 126 :ref:`integer number<amdgpu_synid_integer_number>` 127 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 128 **a[**\ <N>:<K>\ **]** **acc[**\ <N>:<K>\ **]** A sequence of (\ *K-N+1*\ ) *accumulator* registers. 129 130 *N* and *K* may be specified as 131 :ref:`integer numbers<amdgpu_synid_integer_number>` 132 or :ref:`absolute expressions<amdgpu_synid_absolute_expression>`. 133 **[a**\ <N>, \ **a**\ <N+1>, ... **a**\ <K>\ **]** **[acc**\ <N>, \ **acc**\ <N+1>, ... **acc**\ <K>\ **]** A sequence of (\ *K-N+1*\ ) *accumulator* registers. 134 135 Register indices must be specified as decimal 136 :ref:`integer numbers<amdgpu_synid_integer_number>`. 137 =================================================== ========================================================= ==================================================================== 138 139Note: *N* and *K* must satisfy the following conditions: 140 141* *N* <= *K*. 142* 0 <= *N* <= 255. 143* 0 <= *K* <= 255. 144* *K-N+1* must be equal to 1, 2, 4 or 16. 145 146Examples: 147 148.. parsed-literal:: 149 150 a255 151 a[0] 152 a[0:1] 153 a[1:1] 154 a[0:3] 155 a[2*2] 156 a[1-1:2-1] 157 [a252] 158 [a252,a253,a254,a255] 159 160 acc0 161 acc[1] 162 [acc250] 163 [acc2,acc3] 164 165.. _amdgpu_synid_s: 166 167s 168- 169 170Scalar 32-bit registers. The number of available *scalar* registers depends on GPU: 171 172 ======= ============================ 173 GPU Number of *scalar* registers 174 ======= ============================ 175 GFX7 104 176 GFX8 102 177 GFX9 102 178 GFX10 106 179 ======= ============================ 180 181A sequence of *scalar* registers may be used to operate with more than 32 bits of data. 182Assembler currently supports sequences of 1, 2, 4, 8 and 16 *scalar* registers. 183 184Pairs of *scalar* registers must be even-aligned (the first register must be even). 185Sequences of 4 and more *scalar* registers must be quad-aligned. 186 187 ======================================================== ==================================================================== 188 Syntax Description 189 ======================================================== ==================================================================== 190 **s**\ <N> A single 32-bit *scalar* register. 191 192 *N* must be a decimal 193 :ref:`integer number<amdgpu_synid_integer_number>`. 194 195 **s[**\ <N>\ **]** A single 32-bit *scalar* register. 196 197 *N* may be specified as an 198 :ref:`integer number<amdgpu_synid_integer_number>` 199 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 200 **s[**\ <N>:<K>\ **]** A sequence of (\ *K-N+1*\ ) *scalar* registers. 201 202 *N* and *K* may be specified as 203 :ref:`integer numbers<amdgpu_synid_integer_number>` 204 or :ref:`absolute expressions<amdgpu_synid_absolute_expression>`. 205 206 **[s**\ <N>, \ **s**\ <N+1>, ... **s**\ <K>\ **]** A sequence of (\ *K-N+1*\ ) *scalar* registers. 207 208 Register indices must be specified as decimal 209 :ref:`integer numbers<amdgpu_synid_integer_number>`. 210 ======================================================== ==================================================================== 211 212Note: *N* and *K* must satisfy the following conditions: 213 214* *N* must be properly aligned based on sequence size. 215* *N* <= *K*. 216* 0 <= *N* < *SMAX*\ , where *SMAX* is the number of available *scalar* registers. 217* 0 <= *K* < *SMAX*\ , where *SMAX* is the number of available *scalar* registers. 218* *K-N+1* must be equal to 1, 2, 4, 8 or 16. 219 220Examples: 221 222.. parsed-literal:: 223 224 s0 225 s[0] 226 s[0:1] 227 s[1:1] 228 s[0:3] 229 s[2*2] 230 s[1-1:2-1] 231 [s4] 232 [s4,s5,s6,s7] 233 234Examples of *scalar* registers with an invalid alignment: 235 236.. parsed-literal:: 237 238 s[1:2] 239 s[2:5] 240 241.. _amdgpu_synid_trap: 242 243trap 244---- 245 246A set of trap handler registers: 247 248* :ref:`ttmp<amdgpu_synid_ttmp>` 249* :ref:`tba<amdgpu_synid_tba>` 250* :ref:`tma<amdgpu_synid_tma>` 251 252.. _amdgpu_synid_ttmp: 253 254ttmp 255---- 256 257Trap handler temporary scalar registers, 32-bits wide. 258The number of available *ttmp* registers depends on GPU: 259 260 ======= =========================== 261 GPU Number of *ttmp* registers 262 ======= =========================== 263 GFX7 12 264 GFX8 12 265 GFX9 16 266 GFX10 16 267 ======= =========================== 268 269A sequence of *ttmp* registers may be used to operate with more than 32 bits of data. 270Assembler currently supports sequences of 1, 2, 4, 8 and 16 *ttmp* registers. 271 272Pairs of *ttmp* registers must be even-aligned (the first register must be even). 273Sequences of 4 and more *ttmp* registers must be quad-aligned. 274 275 ============================================================= ==================================================================== 276 Syntax Description 277 ============================================================= ==================================================================== 278 **ttmp**\ <N> A single 32-bit *ttmp* register. 279 280 *N* must be a decimal 281 :ref:`integer number<amdgpu_synid_integer_number>`. 282 **ttmp[**\ <N>\ **]** A single 32-bit *ttmp* register. 283 284 *N* may be specified as an 285 :ref:`integer number<amdgpu_synid_integer_number>` 286 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 287 **ttmp[**\ <N>:<K>\ **]** A sequence of (\ *K-N+1*\ ) *ttmp* registers. 288 289 *N* and *K* may be specified as 290 :ref:`integer numbers<amdgpu_synid_integer_number>` 291 or :ref:`absolute expressions<amdgpu_synid_absolute_expression>`. 292 **[ttmp**\ <N>, \ **ttmp**\ <N+1>, ... **ttmp**\ <K>\ **]** A sequence of (\ *K-N+1*\ ) *ttmp* registers. 293 294 Register indices must be specified as decimal 295 :ref:`integer numbers<amdgpu_synid_integer_number>`. 296 ============================================================= ==================================================================== 297 298Note: *N* and *K* must satisfy the following conditions: 299 300* *N* must be properly aligned based on sequence size. 301* *N* <= *K*. 302* 0 <= *N* < *TMAX*, where *TMAX* is the number of available *ttmp* registers. 303* 0 <= *K* < *TMAX*, where *TMAX* is the number of available *ttmp* registers. 304* *K-N+1* must be equal to 1, 2, 4, 8 or 16. 305 306Examples: 307 308.. parsed-literal:: 309 310 ttmp0 311 ttmp[0] 312 ttmp[0:1] 313 ttmp[1:1] 314 ttmp[0:3] 315 ttmp[2*2] 316 ttmp[1-1:2-1] 317 [ttmp4] 318 [ttmp4,ttmp5,ttmp6,ttmp7] 319 320Examples of *ttmp* registers with an invalid alignment: 321 322.. parsed-literal:: 323 324 ttmp[1:2] 325 ttmp[2:5] 326 327.. _amdgpu_synid_tba: 328 329tba 330--- 331 332Trap base address, 64-bits wide. Holds the pointer to the current trap handler program. 333 334 ================== ======================================================================= ============= 335 Syntax Description Availability 336 ================== ======================================================================= ============= 337 tba 64-bit *trap base address* register. GFX7, GFX8 338 [tba] 64-bit *trap base address* register (an SP3 syntax). GFX7, GFX8 339 [tba_lo,tba_hi] 64-bit *trap base address* register (an SP3 syntax). GFX7, GFX8 340 ================== ======================================================================= ============= 341 342High and low 32 bits of *trap base address* may be accessed as separate registers: 343 344 ================== ======================================================================= ============= 345 Syntax Description Availability 346 ================== ======================================================================= ============= 347 tba_lo Low 32 bits of *trap base address* register. GFX7, GFX8 348 tba_hi High 32 bits of *trap base address* register. GFX7, GFX8 349 [tba_lo] Low 32 bits of *trap base address* register (an SP3 syntax). GFX7, GFX8 350 [tba_hi] High 32 bits of *trap base address* register (an SP3 syntax). GFX7, GFX8 351 ================== ======================================================================= ============= 352 353Note that *tba*, *tba_lo* and *tba_hi* are not accessible as assembler registers in GFX9 and GFX10, 354but *tba* is readable/writable with the help of *s_get_reg* and *s_set_reg* instructions. 355 356.. _amdgpu_synid_tma: 357 358tma 359--- 360 361Trap memory address, 64-bits wide. 362 363 ================= ======================================================================= ================== 364 Syntax Description Availability 365 ================= ======================================================================= ================== 366 tma 64-bit *trap memory address* register. GFX7, GFX8 367 [tma] 64-bit *trap memory address* register (an SP3 syntax). GFX7, GFX8 368 [tma_lo,tma_hi] 64-bit *trap memory address* register (an SP3 syntax). GFX7, GFX8 369 ================= ======================================================================= ================== 370 371High and low 32 bits of *trap memory address* may be accessed as separate registers: 372 373 ================= ======================================================================= ================== 374 Syntax Description Availability 375 ================= ======================================================================= ================== 376 tma_lo Low 32 bits of *trap memory address* register. GFX7, GFX8 377 tma_hi High 32 bits of *trap memory address* register. GFX7, GFX8 378 [tma_lo] Low 32 bits of *trap memory address* register (an SP3 syntax). GFX7, GFX8 379 [tma_hi] High 32 bits of *trap memory address* register (an SP3 syntax). GFX7, GFX8 380 ================= ======================================================================= ================== 381 382Note that *tma*, *tma_lo* and *tma_hi* are not accessible as assembler registers in GFX9 and GFX10, 383but *tma* is readable/writable with the help of *s_get_reg* and *s_set_reg* instructions. 384 385.. _amdgpu_synid_flat_scratch: 386 387flat_scratch 388------------ 389 390Flat scratch address, 64-bits wide. Holds the base address of scratch memory. 391 392 ================================== ================================================================ 393 Syntax Description 394 ================================== ================================================================ 395 flat_scratch 64-bit *flat scratch* address register. 396 [flat_scratch] 64-bit *flat scratch* address register (an SP3 syntax). 397 [flat_scratch_lo,flat_scratch_hi] 64-bit *flat scratch* address register (an SP3 syntax). 398 ================================== ================================================================ 399 400High and low 32 bits of *flat scratch* address may be accessed as separate registers: 401 402 ========================= ========================================================================= 403 Syntax Description 404 ========================= ========================================================================= 405 flat_scratch_lo Low 32 bits of *flat scratch* address register. 406 flat_scratch_hi High 32 bits of *flat scratch* address register. 407 [flat_scratch_lo] Low 32 bits of *flat scratch* address register (an SP3 syntax). 408 [flat_scratch_hi] High 32 bits of *flat scratch* address register (an SP3 syntax). 409 ========================= ========================================================================= 410 411Note that *flat_scratch*, *flat_scratch_lo* and *flat_scratch_hi* are not accessible as assembler 412registers in GFX10, but *flat_scratch* is readable/writable with the help of 413*s_get_reg* and *s_set_reg* instructions. 414 415.. _amdgpu_synid_xnack: 416 417xnack 418----- 419 420Xnack mask, 64-bits wide. Holds a 64-bit mask of which threads 421received an *XNACK* due to a vector memory operation. 422 423.. WARNING:: GFX7 does not support *xnack* feature. For availability of this feature in other GPUs, refer :ref:`this table<amdgpu-processors>`. 424 425\ 426 427 ============================== ===================================================== 428 Syntax Description 429 ============================== ===================================================== 430 xnack_mask 64-bit *xnack mask* register. 431 [xnack_mask] 64-bit *xnack mask* register (an SP3 syntax). 432 [xnack_mask_lo,xnack_mask_hi] 64-bit *xnack mask* register (an SP3 syntax). 433 ============================== ===================================================== 434 435High and low 32 bits of *xnack mask* may be accessed as separate registers: 436 437 ===================== ============================================================== 438 Syntax Description 439 ===================== ============================================================== 440 xnack_mask_lo Low 32 bits of *xnack mask* register. 441 xnack_mask_hi High 32 bits of *xnack mask* register. 442 [xnack_mask_lo] Low 32 bits of *xnack mask* register (an SP3 syntax). 443 [xnack_mask_hi] High 32 bits of *xnack mask* register (an SP3 syntax). 444 ===================== ============================================================== 445 446Note that *xnack_mask*, *xnack_mask_lo* and *xnack_mask_hi* are not accessible as assembler 447registers in GFX10, but *xnack_mask* is readable/writable with the help of 448*s_get_reg* and *s_set_reg* instructions. 449 450.. _amdgpu_synid_vcc: 451.. _amdgpu_synid_vcc_lo: 452 453vcc 454--- 455 456Vector condition code, 64-bits wide. A bit mask with one bit per thread; 457it holds the result of a vector compare operation. 458 459Note that GFX10 H/W does not use high 32 bits of *vcc* in *wave32* mode. 460 461 ================ ========================================================================= 462 Syntax Description 463 ================ ========================================================================= 464 vcc 64-bit *vector condition code* register. 465 [vcc] 64-bit *vector condition code* register (an SP3 syntax). 466 [vcc_lo,vcc_hi] 64-bit *vector condition code* register (an SP3 syntax). 467 ================ ========================================================================= 468 469High and low 32 bits of *vector condition code* may be accessed as separate registers: 470 471 ================ ========================================================================= 472 Syntax Description 473 ================ ========================================================================= 474 vcc_lo Low 32 bits of *vector condition code* register. 475 vcc_hi High 32 bits of *vector condition code* register. 476 [vcc_lo] Low 32 bits of *vector condition code* register (an SP3 syntax). 477 [vcc_hi] High 32 bits of *vector condition code* register (an SP3 syntax). 478 ================ ========================================================================= 479 480.. _amdgpu_synid_m0: 481 482m0 483-- 484 485A 32-bit memory register. It has various uses, 486including register indexing and bounds checking. 487 488 =========== =================================================== 489 Syntax Description 490 =========== =================================================== 491 m0 A 32-bit *memory* register. 492 [m0] A 32-bit *memory* register (an SP3 syntax). 493 =========== =================================================== 494 495.. _amdgpu_synid_exec: 496 497exec 498---- 499 500Execute mask, 64-bits wide. A bit mask with one bit per thread, 501which is applied to vector instructions and controls which threads execute 502and which ignore the instruction. 503 504Note that GFX10 H/W does not use high 32 bits of *exec* in *wave32* mode. 505 506 ===================== ================================================================= 507 Syntax Description 508 ===================== ================================================================= 509 exec 64-bit *execute mask* register. 510 [exec] 64-bit *execute mask* register (an SP3 syntax). 511 [exec_lo,exec_hi] 64-bit *execute mask* register (an SP3 syntax). 512 ===================== ================================================================= 513 514High and low 32 bits of *execute mask* may be accessed as separate registers: 515 516 ===================== ================================================================= 517 Syntax Description 518 ===================== ================================================================= 519 exec_lo Low 32 bits of *execute mask* register. 520 exec_hi High 32 bits of *execute mask* register. 521 [exec_lo] Low 32 bits of *execute mask* register (an SP3 syntax). 522 [exec_hi] High 32 bits of *execute mask* register (an SP3 syntax). 523 ===================== ================================================================= 524 525.. _amdgpu_synid_vccz: 526 527vccz 528---- 529 530A single bit flag indicating that the :ref:`vcc<amdgpu_synid_vcc>` is all zeros. 531 532Note: when GFX10 operates in *wave32* mode, this register reflects state of :ref:`vcc_lo<amdgpu_synid_vcc_lo>`. 533 534.. _amdgpu_synid_execz: 535 536execz 537----- 538 539A single bit flag indicating that the :ref:`exec<amdgpu_synid_exec>` is all zeros. 540 541Note: when GFX10 operates in *wave32* mode, this register reflects state of :ref:`exec_lo<amdgpu_synid_exec>`. 542 543.. _amdgpu_synid_scc: 544 545scc 546--- 547 548A single bit flag indicating the result of a scalar compare operation. 549 550.. _amdgpu_synid_lds_direct: 551 552lds_direct 553---------- 554 555A special operand which supplies a 32-bit value 556fetched from *LDS* memory using :ref:`m0<amdgpu_synid_m0>` as an address. 557 558.. _amdgpu_synid_null: 559 560null 561---- 562 563This is a special operand which may be used as a source or a destination. 564 565When used as a destination, the result of the operation is discarded. 566 567When used as a source, it supplies zero value. 568 569GFX10 only. 570 571.. WARNING:: Due to a H/W bug, this operand cannot be used with VALU instructions in first generation of GFX10. 572 573.. _amdgpu_synid_constant: 574 575inline constant 576--------------- 577 578An *inline constant* is an integer or a floating-point value encoded as a part of an instruction. 579Compare *inline constants* with :ref:`literals<amdgpu_synid_literal>`. 580 581Inline constants include: 582 583* :ref:`iconst<amdgpu_synid_iconst>` 584* :ref:`fconst<amdgpu_synid_fconst>` 585* :ref:`ival<amdgpu_synid_ival>` 586 587If a number may be encoded as either 588a :ref:`literal<amdgpu_synid_literal>` or 589a :ref:`constant<amdgpu_synid_constant>`, 590assembler selects the latter encoding as more efficient. 591 592.. _amdgpu_synid_iconst: 593 594iconst 595~~~~~~ 596 597An :ref:`integer number<amdgpu_synid_integer_number>` or 598an :ref:`absolute expression<amdgpu_synid_absolute_expression>` 599encoded as an *inline constant*. 600 601Only a small fraction of integer numbers may be encoded as *inline constants*. 602They are enumerated in the table below. 603Other integer numbers have to be encoded as :ref:`literals<amdgpu_synid_literal>`. 604 605 ================================== ==================================== 606 Value Note 607 ================================== ==================================== 608 {0..64} Positive integer inline constants. 609 {-16..-1} Negative integer inline constants. 610 ================================== ==================================== 611 612.. WARNING:: GFX7 does not support inline constants for *f16* operands. 613 614.. _amdgpu_synid_fconst: 615 616fconst 617~~~~~~ 618 619A :ref:`floating-point number<amdgpu_synid_floating-point_number>` 620encoded as an *inline constant*. 621 622Only a small fraction of floating-point numbers may be encoded as *inline constants*. 623They are enumerated in the table below. 624Other floating-point numbers have to be encoded as :ref:`literals<amdgpu_synid_literal>`. 625 626 ===================== ===================================================== ================== 627 Value Note Availability 628 ===================== ===================================================== ================== 629 0.0 The same as integer constant 0. All GPUs 630 0.5 Floating-point constant 0.5 All GPUs 631 1.0 Floating-point constant 1.0 All GPUs 632 2.0 Floating-point constant 2.0 All GPUs 633 4.0 Floating-point constant 4.0 All GPUs 634 -0.5 Floating-point constant -0.5 All GPUs 635 -1.0 Floating-point constant -1.0 All GPUs 636 -2.0 Floating-point constant -2.0 All GPUs 637 -4.0 Floating-point constant -4.0 All GPUs 638 0.1592 1.0/(2.0*pi). Use only for 16-bit operands. GFX8, GFX9, GFX10 639 0.15915494 1.0/(2.0*pi). Use only for 16- and 32-bit operands. GFX8, GFX9, GFX10 640 0.15915494309189532 1.0/(2.0*pi). GFX8, GFX9, GFX10 641 ===================== ===================================================== ================== 642 643.. WARNING:: Floating-point inline constants cannot be used with *16-bit integer* operands. \ 644 Assembler will attempt to encode these values as literals. 645 646.. WARNING:: GFX7 does not support inline constants for *f16* operands. 647 648.. _amdgpu_synid_ival: 649 650ival 651~~~~ 652 653A symbolic operand encoded as an *inline constant*. 654These operands provide read-only access to H/W registers. 655 656 ======================== ================================================ ============= 657 Syntax Note Availability 658 ======================== ================================================ ============= 659 shared_base Base address of shared memory region. GFX9, GFX10 660 shared_limit Address of the end of shared memory region. GFX9, GFX10 661 private_base Base address of private memory region. GFX9, GFX10 662 private_limit Address of the end of private memory region. GFX9, GFX10 663 pops_exiting_wave_id A dedicated counter for POPS. GFX9, GFX10 664 ======================== ================================================ ============= 665 666.. _amdgpu_synid_literal: 667 668literal 669------- 670 671A *literal* is a 64-bit value encoded as a separate 32-bit dword in the instruction stream. 672Compare *literals* with :ref:`inline constants<amdgpu_synid_constant>`. 673 674If a number may be encoded as either 675a :ref:`literal<amdgpu_synid_literal>` or 676an :ref:`inline constant<amdgpu_synid_constant>`, 677assembler selects the latter encoding as more efficient. 678 679Literals may be specified as :ref:`integer numbers<amdgpu_synid_integer_number>`, 680:ref:`floating-point numbers<amdgpu_synid_floating-point_number>`, 681:ref:`absolute expressions<amdgpu_synid_absolute_expression>` or 682:ref:`relocatable expressions<amdgpu_synid_relocatable_expression>`. 683 684An instruction may use only one literal but several operands may refer the same literal. 685 686.. _amdgpu_synid_uimm8: 687 688uimm8 689----- 690 691A 8-bit :ref:`integer number<amdgpu_synid_integer_number>` 692or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 693The value must be in the range 0..0xFF. 694 695.. _amdgpu_synid_uimm32: 696 697uimm32 698------ 699 700A 32-bit :ref:`integer number<amdgpu_synid_integer_number>` 701or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 702The value must be in the range 0..0xFFFFFFFF. 703 704.. _amdgpu_synid_uimm20: 705 706uimm20 707------ 708 709A 20-bit :ref:`integer number<amdgpu_synid_integer_number>` 710or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 711 712The value must be in the range 0..0xFFFFF. 713 714.. _amdgpu_synid_uimm21: 715 716uimm21 717------ 718 719A 21-bit :ref:`integer number<amdgpu_synid_integer_number>` 720or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 721 722The value must be in the range 0..0x1FFFFF. 723 724.. WARNING:: Assembler currently supports 20-bit offsets only. Use :ref:`uimm20<amdgpu_synid_uimm20>` as a replacement. 725 726.. _amdgpu_synid_simm21: 727 728simm21 729------ 730 731A 21-bit :ref:`integer number<amdgpu_synid_integer_number>` 732or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 733 734The value must be in the range -0x100000..0x0FFFFF. 735 736.. WARNING:: Assembler currently supports 20-bit unsigned offsets only. Use :ref:`uimm20<amdgpu_synid_uimm20>` as a replacement. 737 738.. _amdgpu_synid_off: 739 740off 741--- 742 743A special entity which indicates that the value of this operand is not used. 744 745 ================================== =================================================== 746 Syntax Description 747 ================================== =================================================== 748 off Indicates an unused operand. 749 ================================== =================================================== 750 751 752.. _amdgpu_synid_number: 753 754Numbers 755======= 756 757.. _amdgpu_synid_integer_number: 758 759Integer Numbers 760--------------- 761 762Integer numbers are 64 bits wide. 763They are converted to :ref:`expected operand type<amdgpu_syn_instruction_type>` 764as described :ref:`here<amdgpu_synid_int_conv>`. 765 766Integer numbers may be specified in binary, octal, hexadecimal and decimal formats: 767 768 ============ =============================== ======== 769 Format Syntax Example 770 ============ =============================== ======== 771 Decimal [-]?[1-9][0-9]* -1234 772 Binary [-]?0b[01]+ 0b1010 773 Octal [-]?0[0-7]+ 010 774 Hexadecimal [-]?0x[0-9a-fA-F]+ 0xff 775 \ [-]?[0x]?[0-9][0-9a-fA-F]*[hH] 0ffh 776 ============ =============================== ======== 777 778.. _amdgpu_synid_floating-point_number: 779 780Floating-Point Numbers 781---------------------- 782 783All floating-point numbers are handled as double (64 bits wide). 784They are converted to 785:ref:`expected operand type<amdgpu_syn_instruction_type>` 786as described :ref:`here<amdgpu_synid_fp_conv>`. 787 788Floating-point numbers may be specified in hexadecimal and decimal formats: 789 790 ============ ======================================================== ====================== ==================== 791 Format Syntax Examples Note 792 ============ ======================================================== ====================== ==================== 793 Decimal [-]?[0-9]*[.][0-9]*([eE][+-]?[0-9]*)? -1.234, 234e2 Must include either 794 a decimal separator 795 or an exponent. 796 Hexadecimal [-]0x[0-9a-fA-F]*(.[0-9a-fA-F]*)?[pP][+-]?[0-9a-fA-F]+ -0x1afp-10, 0x.1afp10 797 ============ ======================================================== ====================== ==================== 798 799.. _amdgpu_synid_expression: 800 801Expressions 802=========== 803 804An expression is evaluated to a 64-bit integer. 805Note that floating-point expressions are not supported. 806 807There are two kinds of expressions: 808 809* :ref:`Absolute<amdgpu_synid_absolute_expression>`. 810* :ref:`Relocatable<amdgpu_synid_relocatable_expression>`. 811 812.. _amdgpu_synid_absolute_expression: 813 814Absolute Expressions 815-------------------- 816 817The value of an absolute expression does not change after program relocation. 818Absolute expressions must not include unassigned and relocatable values 819such as labels. 820 821Absolute expressions are evaluated to 64-bit integer values and converted to 822:ref:`expected operand type<amdgpu_syn_instruction_type>` 823as described :ref:`here<amdgpu_synid_int_conv>`. 824 825Examples: 826 827.. parsed-literal:: 828 829 x = -1 830 y = x + 10 831 832.. _amdgpu_synid_relocatable_expression: 833 834Relocatable Expressions 835----------------------- 836 837The value of a relocatable expression depends on program relocation. 838 839Note that use of relocatable expressions is limited with branch targets 840and 32-bit integer operands. 841 842A relocatable expression is evaluated to a 64-bit integer value 843which depends on operand kind and :ref:`relocation type<amdgpu-relocation-records>` 844of symbol(s) used in the expression. For example, if an instruction refers a label, 845this reference is evaluated to an offset from the address after the instruction 846to the label address: 847 848.. parsed-literal:: 849 850 label: 851 v_add_co_u32_e32 v0, vcc, label, v1 // 'label' operand is evaluated to -4 852 853Note that values of relocatable expressions are usually unknown at assembly time; 854they are resolved later by a linker and converted to 855:ref:`expected operand type<amdgpu_syn_instruction_type>` 856as described :ref:`here<amdgpu_synid_rl_conv>`. 857 858Operands and Operations 859----------------------- 860 861Expressions are composed of 64-bit integer operands and operations. 862Operands include :ref:`integer numbers<amdgpu_synid_integer_number>` 863and :ref:`symbols<amdgpu_synid_symbol>`. 864 865Expressions may also use "." which is a reference to the current PC (program counter). 866 867:ref:`Unary<amdgpu_synid_expression_un_op>` and :ref:`binary<amdgpu_synid_expression_bin_op>` 868operations produce 64-bit integer results. 869 870Syntax of Expressions 871--------------------- 872 873Syntax of expressions is shown below:: 874 875 expr ::= expr binop expr | primaryexpr ; 876 877 primaryexpr ::= '(' expr ')' | symbol | number | '.' | unop primaryexpr ; 878 879 binop ::= '&&' 880 | '||' 881 | '|' 882 | '^' 883 | '&' 884 | '!' 885 | '==' 886 | '!=' 887 | '<>' 888 | '<' 889 | '<=' 890 | '>' 891 | '>=' 892 | '<<' 893 | '>>' 894 | '+' 895 | '-' 896 | '*' 897 | '/' 898 | '%' ; 899 900 unop ::= '~' 901 | '+' 902 | '-' 903 | '!' ; 904 905.. _amdgpu_synid_expression_bin_op: 906 907Binary Operators 908---------------- 909 910Binary operators are described in the following table. 911They operate on and produce 64-bit integers. 912Operators with higher priority are performed first. 913 914 ========== ========= =============================================== 915 Operator Priority Meaning 916 ========== ========= =============================================== 917 \* 5 Integer multiplication. 918 / 5 Integer division. 919 % 5 Integer signed remainder. 920 \+ 4 Integer addition. 921 \- 4 Integer subtraction. 922 << 3 Integer shift left. 923 >> 3 Logical shift right. 924 == 2 Equality comparison. 925 != 2 Inequality comparison. 926 <> 2 Inequality comparison. 927 < 2 Signed less than comparison. 928 <= 2 Signed less than or equal comparison. 929 > 2 Signed greater than comparison. 930 >= 2 Signed greater than or equal comparison. 931 \| 1 Bitwise or. 932 ^ 1 Bitwise xor. 933 & 1 Bitwise and. 934 && 0 Logical and. 935 || 0 Logical or. 936 ========== ========= =============================================== 937 938.. _amdgpu_synid_expression_un_op: 939 940Unary Operators 941--------------- 942 943Unary operators are described in the following table. 944They operate on and produce 64-bit integers. 945 946 ========== =============================================== 947 Operator Meaning 948 ========== =============================================== 949 ! Logical negation. 950 ~ Bitwise negation. 951 \+ Integer unary plus. 952 \- Integer unary minus. 953 ========== =============================================== 954 955.. _amdgpu_synid_symbol: 956 957Symbols 958------- 959 960A symbol is a named 64-bit integer value, representing a relocatable 961address or an absolute (non-relocatable) number. 962 963Symbol names have the following syntax: 964 ``[a-zA-Z_.][a-zA-Z0-9_$.@]*`` 965 966The table below provides several examples of syntax used for symbol definition. 967 968 ================ ========================================================== 969 Syntax Meaning 970 ================ ========================================================== 971 .globl <S> Declares a global symbol S without assigning it a value. 972 .set <S>, <E> Assigns the value of an expression E to a symbol S. 973 <S> = <E> Assigns the value of an expression E to a symbol S. 974 <S>: Declares a label S and assigns it the current PC value. 975 ================ ========================================================== 976 977A symbol may be used before it is declared or assigned; 978unassigned symbols are assumed to be PC-relative. 979 980Additional information about symbols may be found :ref:`here<amdgpu-symbols>`. 981 982.. _amdgpu_synid_conv: 983 984Type and Size Conversion 985======================== 986 987This section describes what happens when a 64-bit 988:ref:`integer number<amdgpu_synid_integer_number>`, a 989:ref:`floating-point number<amdgpu_synid_floating-point_number>` or an 990:ref:`expression<amdgpu_synid_expression>` 991is used for an operand which has a different type or size. 992 993.. _amdgpu_synid_int_conv: 994 995Conversion of Integer Values 996---------------------------- 997 998Instruction operands may be specified as 64-bit :ref:`integer numbers<amdgpu_synid_integer_number>` or 999:ref:`absolute expressions<amdgpu_synid_absolute_expression>`. These values are converted to 1000the :ref:`expected operand type<amdgpu_syn_instruction_type>` using the following steps: 1001 10021. *Validation*. Assembler checks if the input value may be truncated without loss to the required *truncation width* 1003(see the table below). There are two cases when this operation is enabled: 1004 1005 * The truncated bits are all 0. 1006 * The truncated bits are all 1 and the value after truncation has its MSB bit set. 1007 1008In all other cases assembler triggers an error. 1009 10102. *Conversion*. The input value is converted to the expected type as described in the table below. 1011Depending on operand kind, this conversion is performed by either assembler or AMDGPU H/W (or both). 1012 1013 ============== ================= =============== ==================================================================== 1014 Expected type Truncation Width Conversion Description 1015 ============== ================= =============== ==================================================================== 1016 i16, u16, b16 16 num.u16 Truncate to 16 bits. 1017 i32, u32, b32 32 num.u32 Truncate to 32 bits. 1018 i64 32 {-1,num.i32} Truncate to 32 bits and then sign-extend the result to 64 bits. 1019 u64, b64 32 {0,num.u32} Truncate to 32 bits and then zero-extend the result to 64 bits. 1020 f16 16 num.u16 Use low 16 bits as an f16 value. 1021 f32 32 num.u32 Use low 32 bits as an f32 value. 1022 f64 32 {num.u32,0} Use low 32 bits of the number as high 32 bits 1023 of the result; low 32 bits of the result are zeroed. 1024 ============== ================= =============== ==================================================================== 1025 1026Examples of enabled conversions: 1027 1028.. parsed-literal:: 1029 1030 // GFX9 1031 1032 v_add_u16 v0, -1, 0 // src0 = 0xFFFF 1033 v_add_f16 v0, -1, 0 // src0 = 0xFFFF (NaN) 1034 // 1035 v_add_u32 v0, -1, 0 // src0 = 0xFFFFFFFF 1036 v_add_f32 v0, -1, 0 // src0 = 0xFFFFFFFF (NaN) 1037 // 1038 v_add_u16 v0, 0xff00, v0 // src0 = 0xff00 1039 v_add_u16 v0, 0xffffffffffffff00, v0 // src0 = 0xff00 1040 v_add_u16 v0, -256, v0 // src0 = 0xff00 1041 // 1042 s_bfe_i64 s[0:1], 0xffefffff, s3 // src0 = 0xffffffffffefffff 1043 s_bfe_u64 s[0:1], 0xffefffff, s3 // src0 = 0x00000000ffefffff 1044 v_ceil_f64_e32 v[0:1], 0xffefffff // src0 = 0xffefffff00000000 (-1.7976922776554302e308) 1045 // 1046 x = 0xffefffff // 1047 s_bfe_i64 s[0:1], x, s3 // src0 = 0xffffffffffefffff 1048 s_bfe_u64 s[0:1], x, s3 // src0 = 0x00000000ffefffff 1049 v_ceil_f64_e32 v[0:1], x // src0 = 0xffefffff00000000 (-1.7976922776554302e308) 1050 1051Examples of disabled conversions: 1052 1053.. parsed-literal:: 1054 1055 // GFX9 1056 1057 v_add_u16 v0, 0x1ff00, v0 // truncated bits are not all 0 or 1 1058 v_add_u16 v0, 0xffffffffffff00ff, v0 // truncated bits do not match MSB of the result 1059 1060.. _amdgpu_synid_fp_conv: 1061 1062Conversion of Floating-Point Values 1063----------------------------------- 1064 1065Instruction operands may be specified as 64-bit :ref:`floating-point numbers<amdgpu_synid_floating-point_number>`. 1066These values are converted to the :ref:`expected operand type<amdgpu_syn_instruction_type>` using the following steps: 1067 10681. *Validation*. Assembler checks if the input f64 number can be converted 1069to the *required floating-point type* (see the table below) without overflow or underflow. 1070Precision lost is allowed. If this conversion is not possible, assembler triggers an error. 1071 10722. *Conversion*. The input value is converted to the expected type as described in the table below. 1073Depending on operand kind, this is performed by either assembler or AMDGPU H/W (or both). 1074 1075 ============== ================ ================= ================================================================= 1076 Expected type Required FP Type Conversion Description 1077 ============== ================ ================= ================================================================= 1078 i16, u16, b16 f16 f16(num) Convert to f16 and use bits of the result as an integer value. 1079 The value has to be encoded as a literal or an error occurs. 1080 Note that the value cannot be encoded as an inline constant. 1081 i32, u32, b32 f32 f32(num) Convert to f32 and use bits of the result as an integer value. 1082 i64, u64, b64 \- \- Conversion disabled. 1083 f16 f16 f16(num) Convert to f16. 1084 f32 f32 f32(num) Convert to f32. 1085 f64 f64 {num.u32.hi,0} Use high 32 bits of the number as high 32 bits of the result; 1086 zero-fill low 32 bits of the result. 1087 1088 Note that the result may differ from the original number. 1089 ============== ================ ================= ================================================================= 1090 1091Examples of enabled conversions: 1092 1093.. parsed-literal:: 1094 1095 // GFX9 1096 1097 v_add_f16 v0, 1.0, 0 // src0 = 0x3C00 (1.0) 1098 v_add_u16 v0, 1.0, 0 // src0 = 0x3C00 1099 // 1100 v_add_f32 v0, 1.0, 0 // src0 = 0x3F800000 (1.0) 1101 v_add_u32 v0, 1.0, 0 // src0 = 0x3F800000 1102 1103 // src0 before conversion: 1104 // 1.7976931348623157e308 = 0x7fefffffffffffff 1105 // src0 after conversion: 1106 // 1.7976922776554302e308 = 0x7fefffff00000000 1107 v_ceil_f64 v[0:1], 1.7976931348623157e308 1108 1109 v_add_f16 v1, 65500.0, v2 // ok for f16. 1110 v_add_f32 v1, 65600.0, v2 // ok for f32, but would result in overflow for f16. 1111 1112Examples of disabled conversions: 1113 1114.. parsed-literal:: 1115 1116 // GFX9 1117 1118 v_add_f16 v1, 65600.0, v2 // overflow 1119 1120.. _amdgpu_synid_rl_conv: 1121 1122Conversion of Relocatable Values 1123-------------------------------- 1124 1125:ref:`Relocatable expressions<amdgpu_synid_relocatable_expression>` 1126may be used with 32-bit integer operands and jump targets. 1127 1128When the value of a relocatable expression is resolved by a linker, it is 1129converted as needed and truncated to the operand size. The conversion depends 1130on :ref:`relocation type<amdgpu-relocation-records>` and operand kind. 1131 1132For example, when a 32-bit operand of an instruction refers a relocatable expression *expr*, 1133this reference is evaluated to a 64-bit offset from the address after the 1134instruction to the address being referenced, *counted in bytes*. 1135Then the value is truncated to 32 bits and encoded as a literal: 1136 1137.. parsed-literal:: 1138 1139 expr = . 1140 v_add_co_u32_e32 v0, vcc, expr, v1 // 'expr' operand is evaluated to -4 1141 // and then truncated to 0xFFFFFFFC 1142 1143As another example, when a branch instruction refers a label, 1144this reference is evaluated to an offset from the address after the 1145instruction to the label address, *counted in dwords*. 1146Then the value is truncated to 16 bits: 1147 1148.. parsed-literal:: 1149 1150 label: 1151 s_branch label // 'label' operand is evaluated to -1 and truncated to 0xFFFF 1152