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 a 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 411.. _amdgpu_synid_xnack: 412 413xnack 414----- 415 416Xnack mask, 64-bits wide. Holds a 64-bit mask of which threads 417received an *XNACK* due to a vector memory operation. 418 419.. WARNING:: GFX7 does not support *xnack* feature. For availability of this feature in other GPUs, refer :ref:`this table<amdgpu-processors>`. 420 421\ 422 423 ============================== ===================================================== 424 Syntax Description 425 ============================== ===================================================== 426 xnack_mask 64-bit *xnack mask* register. 427 [xnack_mask] 64-bit *xnack mask* register (an SP3 syntax). 428 [xnack_mask_lo,xnack_mask_hi] 64-bit *xnack mask* register (an SP3 syntax). 429 ============================== ===================================================== 430 431High and low 32 bits of *xnack mask* may be accessed as separate registers: 432 433 ===================== ============================================================== 434 Syntax Description 435 ===================== ============================================================== 436 xnack_mask_lo Low 32 bits of *xnack mask* register. 437 xnack_mask_hi High 32 bits of *xnack mask* register. 438 [xnack_mask_lo] Low 32 bits of *xnack mask* register (an SP3 syntax). 439 [xnack_mask_hi] High 32 bits of *xnack mask* register (an SP3 syntax). 440 ===================== ============================================================== 441 442.. _amdgpu_synid_vcc: 443.. _amdgpu_synid_vcc_lo: 444 445vcc 446--- 447 448Vector condition code, 64-bits wide. A bit mask with one bit per thread; 449it holds the result of a vector compare operation. 450 451Note that GFX10 H/W does not use high 32 bits of *vcc* in *wave32* mode. 452 453 ================ ========================================================================= 454 Syntax Description 455 ================ ========================================================================= 456 vcc 64-bit *vector condition code* register. 457 [vcc] 64-bit *vector condition code* register (an SP3 syntax). 458 [vcc_lo,vcc_hi] 64-bit *vector condition code* register (an SP3 syntax). 459 ================ ========================================================================= 460 461High and low 32 bits of *vector condition code* may be accessed as separate registers: 462 463 ================ ========================================================================= 464 Syntax Description 465 ================ ========================================================================= 466 vcc_lo Low 32 bits of *vector condition code* register. 467 vcc_hi High 32 bits of *vector condition code* register. 468 [vcc_lo] Low 32 bits of *vector condition code* register (an SP3 syntax). 469 [vcc_hi] High 32 bits of *vector condition code* register (an SP3 syntax). 470 ================ ========================================================================= 471 472.. _amdgpu_synid_m0: 473 474m0 475-- 476 477A 32-bit memory register. It has various uses, 478including register indexing and bounds checking. 479 480 =========== =================================================== 481 Syntax Description 482 =========== =================================================== 483 m0 A 32-bit *memory* register. 484 [m0] A 32-bit *memory* register (an SP3 syntax). 485 =========== =================================================== 486 487.. _amdgpu_synid_exec: 488 489exec 490---- 491 492Execute mask, 64-bits wide. A bit mask with one bit per thread, 493which is applied to vector instructions and controls which threads execute 494and which ignore the instruction. 495 496Note that GFX10 H/W does not use high 32 bits of *exec* in *wave32* mode. 497 498 ===================== ================================================================= 499 Syntax Description 500 ===================== ================================================================= 501 exec 64-bit *execute mask* register. 502 [exec] 64-bit *execute mask* register (an SP3 syntax). 503 [exec_lo,exec_hi] 64-bit *execute mask* register (an SP3 syntax). 504 ===================== ================================================================= 505 506High and low 32 bits of *execute mask* may be accessed as separate registers: 507 508 ===================== ================================================================= 509 Syntax Description 510 ===================== ================================================================= 511 exec_lo Low 32 bits of *execute mask* register. 512 exec_hi High 32 bits of *execute mask* register. 513 [exec_lo] Low 32 bits of *execute mask* register (an SP3 syntax). 514 [exec_hi] High 32 bits of *execute mask* register (an SP3 syntax). 515 ===================== ================================================================= 516 517.. _amdgpu_synid_vccz: 518 519vccz 520---- 521 522A single bit flag indicating that the :ref:`vcc<amdgpu_synid_vcc>` is all zeros. 523 524Note: when GFX10 operates in *wave32* mode, this register reflects state of :ref:`vcc_lo<amdgpu_synid_vcc_lo>`. 525 526.. _amdgpu_synid_execz: 527 528execz 529----- 530 531A single bit flag indicating that the :ref:`exec<amdgpu_synid_exec>` is all zeros. 532 533Note: when GFX10 operates in *wave32* mode, this register reflects state of :ref:`exec_lo<amdgpu_synid_exec>`. 534 535.. _amdgpu_synid_scc: 536 537scc 538--- 539 540A single bit flag indicating the result of a scalar compare operation. 541 542.. _amdgpu_synid_lds_direct: 543 544lds_direct 545---------- 546 547A special operand which supplies a 32-bit value 548fetched from *LDS* memory using :ref:`m0<amdgpu_synid_m0>` as an address. 549 550.. _amdgpu_synid_null: 551 552null 553---- 554 555This is a special operand which may be used as a source or a destination. 556 557When used as a destination, the result of the operation is discarded. 558 559When used as a source, it supplies zero value. 560 561GFX10 only. 562 563.. WARNING:: Due to a H/W bug, this operand cannot be used with VALU instructions in first generation of GFX10. 564 565.. _amdgpu_synid_constant: 566 567inline constant 568--------------- 569 570An *inline constant* is an integer or a floating-point value encoded as a part of an instruction. 571Compare *inline constants* with :ref:`literals<amdgpu_synid_literal>`. 572 573Inline constants include: 574 575* :ref:`iconst<amdgpu_synid_iconst>` 576* :ref:`fconst<amdgpu_synid_fconst>` 577* :ref:`ival<amdgpu_synid_ival>` 578 579If a number may be encoded as either 580a :ref:`literal<amdgpu_synid_literal>` or 581a :ref:`constant<amdgpu_synid_constant>`, 582assembler selects the latter encoding as more efficient. 583 584.. _amdgpu_synid_iconst: 585 586iconst 587~~~~~~ 588 589An :ref:`integer number<amdgpu_synid_integer_number>` or 590an :ref:`absolute expression<amdgpu_synid_absolute_expression>` 591encoded as an *inline constant*. 592 593Only a small fraction of integer numbers may be encoded as *inline constants*. 594They are enumerated in the table below. 595Other integer numbers have to be encoded as :ref:`literals<amdgpu_synid_literal>`. 596 597 ================================== ==================================== 598 Value Note 599 ================================== ==================================== 600 {0..64} Positive integer inline constants. 601 {-16..-1} Negative integer inline constants. 602 ================================== ==================================== 603 604.. WARNING:: GFX7 does not support inline constants for *f16* operands. 605 606.. _amdgpu_synid_fconst: 607 608fconst 609~~~~~~ 610 611A :ref:`floating-point number<amdgpu_synid_floating-point_number>` 612encoded as an *inline constant*. 613 614Only a small fraction of floating-point numbers may be encoded as *inline constants*. 615They are enumerated in the table below. 616Other floating-point numbers have to be encoded as :ref:`literals<amdgpu_synid_literal>`. 617 618 ===================== ===================================================== ================== 619 Value Note Availability 620 ===================== ===================================================== ================== 621 0.0 The same as integer constant 0. All GPUs 622 0.5 Floating-point constant 0.5 All GPUs 623 1.0 Floating-point constant 1.0 All GPUs 624 2.0 Floating-point constant 2.0 All GPUs 625 4.0 Floating-point constant 4.0 All GPUs 626 -0.5 Floating-point constant -0.5 All GPUs 627 -1.0 Floating-point constant -1.0 All GPUs 628 -2.0 Floating-point constant -2.0 All GPUs 629 -4.0 Floating-point constant -4.0 All GPUs 630 0.1592 1.0/(2.0*pi). Use only for 16-bit operands. GFX8, GFX9, GFX10 631 0.15915494 1.0/(2.0*pi). Use only for 16- and 32-bit operands. GFX8, GFX9, GFX10 632 0.15915494309189532 1.0/(2.0*pi). GFX8, GFX9, GFX10 633 ===================== ===================================================== ================== 634 635.. WARNING:: GFX7 does not support inline constants for *f16* operands. 636 637.. _amdgpu_synid_ival: 638 639ival 640~~~~ 641 642A symbolic operand encoded as an *inline constant*. 643These operands provide read-only access to H/W registers. 644 645 ======================== ================================================ ============= 646 Syntax Note Availability 647 ======================== ================================================ ============= 648 shared_base Base address of shared memory region. GFX9, GFX10 649 shared_limit Address of the end of shared memory region. GFX9, GFX10 650 private_base Base address of private memory region. GFX9, GFX10 651 private_limit Address of the end of private memory region. GFX9, GFX10 652 pops_exiting_wave_id A dedicated counter for POPS. GFX9, GFX10 653 ======================== ================================================ ============= 654 655.. _amdgpu_synid_literal: 656 657literal 658------- 659 660A *literal* is a 64-bit value encoded as a separate 32-bit dword in the instruction stream. 661Compare *literals* with :ref:`inline constants<amdgpu_synid_constant>`. 662 663If a number may be encoded as either 664a :ref:`literal<amdgpu_synid_literal>` or 665an :ref:`inline constant<amdgpu_synid_constant>`, 666assembler selects the latter encoding as more efficient. 667 668Literals may be specified as :ref:`integer numbers<amdgpu_synid_integer_number>`, 669:ref:`floating-point numbers<amdgpu_synid_floating-point_number>`, 670:ref:`absolute expressions<amdgpu_synid_absolute_expression>` or 671:ref:`relocatable expressions<amdgpu_synid_relocatable_expression>`. 672 673An instruction may use only one literal but several operands may refer the same literal. 674 675.. _amdgpu_synid_uimm8: 676 677uimm8 678----- 679 680A 8-bit :ref:`integer number<amdgpu_synid_integer_number>` 681or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 682The value must be in the range 0..0xFF. 683 684.. _amdgpu_synid_uimm32: 685 686uimm32 687------ 688 689A 32-bit :ref:`integer number<amdgpu_synid_integer_number>` 690or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 691The value must be in the range 0..0xFFFFFFFF. 692 693.. _amdgpu_synid_uimm20: 694 695uimm20 696------ 697 698A 20-bit :ref:`integer number<amdgpu_synid_integer_number>` 699or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 700 701The value must be in the range 0..0xFFFFF. 702 703.. _amdgpu_synid_uimm21: 704 705uimm21 706------ 707 708A 21-bit :ref:`integer number<amdgpu_synid_integer_number>` 709or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 710 711The value must be in the range 0..0x1FFFFF. 712 713.. WARNING:: Assembler currently supports 20-bit offsets only. Use :ref:`uimm20<amdgpu_synid_uimm20>` as a replacement. 714 715.. _amdgpu_synid_simm21: 716 717simm21 718------ 719 720A 21-bit :ref:`integer number<amdgpu_synid_integer_number>` 721or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`. 722 723The value must be in the range -0x100000..0x0FFFFF. 724 725.. WARNING:: Assembler currently supports 20-bit unsigned offsets only. Use :ref:`uimm20<amdgpu_synid_uimm20>` as a replacement. 726 727.. _amdgpu_synid_off: 728 729off 730--- 731 732A special entity which indicates that the value of this operand is not used. 733 734 ================================== =================================================== 735 Syntax Description 736 ================================== =================================================== 737 off Indicates an unused operand. 738 ================================== =================================================== 739 740 741.. _amdgpu_synid_number: 742 743Numbers 744======= 745 746.. _amdgpu_synid_integer_number: 747 748Integer Numbers 749--------------- 750 751Integer numbers are 64 bits wide. 752They are converted to :ref:`expected operand type<amdgpu_syn_instruction_type>` 753as described :ref:`here<amdgpu_synid_int_conv>`. 754 755Integer numbers may be specified in binary, octal, hexadecimal and decimal formats: 756 757 ============ =============================== ======== 758 Format Syntax Example 759 ============ =============================== ======== 760 Decimal [-]?[1-9][0-9]* -1234 761 Binary [-]?0b[01]+ 0b1010 762 Octal [-]?0[0-7]+ 010 763 Hexadecimal [-]?0x[0-9a-fA-F]+ 0xff 764 \ [-]?[0x]?[0-9][0-9a-fA-F]*[hH] 0ffh 765 ============ =============================== ======== 766 767.. _amdgpu_synid_floating-point_number: 768 769Floating-Point Numbers 770---------------------- 771 772All floating-point numbers are handled as double (64 bits wide). 773They are converted to 774:ref:`expected operand type<amdgpu_syn_instruction_type>` 775as described :ref:`here<amdgpu_synid_fp_conv>`. 776 777Floating-point numbers may be specified in hexadecimal and decimal formats: 778 779 ============ ======================================================== ====================== ==================== 780 Format Syntax Examples Note 781 ============ ======================================================== ====================== ==================== 782 Decimal [-]?[0-9]*[.][0-9]*([eE][+-]?[0-9]*)? -1.234, 234e2 Must include either 783 a decimal separator 784 or an exponent. 785 Hexadecimal [-]0x[0-9a-fA-F]*(.[0-9a-fA-F]*)?[pP][+-]?[0-9a-fA-F]+ -0x1afp-10, 0x.1afp10 786 ============ ======================================================== ====================== ==================== 787 788.. _amdgpu_synid_expression: 789 790Expressions 791=========== 792 793An expression is evaluated to a 64-bit integer. 794Note that floating-point expressions are not supported. 795 796There are two kinds of expressions: 797 798* :ref:`Absolute<amdgpu_synid_absolute_expression>`. 799* :ref:`Relocatable<amdgpu_synid_relocatable_expression>`. 800 801.. _amdgpu_synid_absolute_expression: 802 803Absolute Expressions 804-------------------- 805 806The value of an absolute expression does not change after program relocation. 807Absolute expressions must not include unassigned and relocatable values 808such as labels. 809 810Absolute expressions are evaluated to 64-bit integer values and converted to 811:ref:`expected operand type<amdgpu_syn_instruction_type>` 812as described :ref:`here<amdgpu_synid_int_conv>`. 813 814Examples: 815 816.. parsed-literal:: 817 818 x = -1 819 y = x + 10 820 821.. _amdgpu_synid_relocatable_expression: 822 823Relocatable Expressions 824----------------------- 825 826The value of a relocatable expression depends on program relocation. 827 828Note that use of relocatable expressions is limited with branch targets 829and 32-bit integer operands. 830 831A relocatable expression is evaluated to a 64-bit integer value 832which depends on operand kind and :ref:`relocation type<amdgpu-relocation-records>` 833of symbol(s) used in the expression. For example, if an instruction refers a label, 834this reference is evaluated to an offset from the address after the instruction 835to the label address: 836 837.. parsed-literal:: 838 839 label: 840 v_add_co_u32_e32 v0, vcc, label, v1 // 'label' operand is evaluated to -4 841 842Note that values of relocatable expressions are usually unknown at assembly time; 843they are resolved later by a linker and converted to 844:ref:`expected operand type<amdgpu_syn_instruction_type>` 845as described :ref:`here<amdgpu_synid_rl_conv>`. 846 847Operands and Operations 848----------------------- 849 850Expressions are composed of 64-bit integer operands and operations. 851Operands include :ref:`integer numbers<amdgpu_synid_integer_number>` 852and :ref:`symbols<amdgpu_synid_symbol>`. 853 854Expressions may also use "." which is a reference to the current PC (program counter). 855 856:ref:`Unary<amdgpu_synid_expression_un_op>` and :ref:`binary<amdgpu_synid_expression_bin_op>` 857operations produce 64-bit integer results. 858 859Syntax of Expressions 860--------------------- 861 862The syntax of expressions is shown below:: 863 864 expr ::= expr binop expr | primaryexpr ; 865 866 primaryexpr ::= '(' expr ')' | symbol | number | '.' | unop primaryexpr ; 867 868 binop ::= '&&' 869 | '||' 870 | '|' 871 | '^' 872 | '&' 873 | '!' 874 | '==' 875 | '!=' 876 | '<>' 877 | '<' 878 | '<=' 879 | '>' 880 | '>=' 881 | '<<' 882 | '>>' 883 | '+' 884 | '-' 885 | '*' 886 | '/' 887 | '%' ; 888 889 unop ::= '~' 890 | '+' 891 | '-' 892 | '!' ; 893 894.. _amdgpu_synid_expression_bin_op: 895 896Binary Operators 897---------------- 898 899Binary operators are described in the following table. 900They operate on and produce 64-bit integers. 901Operators with higher priority are performed first. 902 903 ========== ========= =============================================== 904 Operator Priority Meaning 905 ========== ========= =============================================== 906 \* 5 Integer multiplication. 907 / 5 Integer division. 908 % 5 Integer signed remainder. 909 \+ 4 Integer addition. 910 \- 4 Integer subtraction. 911 << 3 Integer shift left. 912 >> 3 Logical shift right. 913 == 2 Equality comparison. 914 != 2 Inequality comparison. 915 <> 2 Inequality comparison. 916 < 2 Signed less than comparison. 917 <= 2 Signed less than or equal comparison. 918 > 2 Signed greater than comparison. 919 >= 2 Signed greater than or equal comparison. 920 \| 1 Bitwise or. 921 ^ 1 Bitwise xor. 922 & 1 Bitwise and. 923 && 0 Logical and. 924 || 0 Logical or. 925 ========== ========= =============================================== 926 927.. _amdgpu_synid_expression_un_op: 928 929Unary Operators 930--------------- 931 932Unary operators are described in the following table. 933They operate on and produce 64-bit integers. 934 935 ========== =============================================== 936 Operator Meaning 937 ========== =============================================== 938 ! Logical negation. 939 ~ Bitwise negation. 940 \+ Integer unary plus. 941 \- Integer unary minus. 942 ========== =============================================== 943 944.. _amdgpu_synid_symbol: 945 946Symbols 947------- 948 949A symbol is a named 64-bit integer value, representing a relocatable 950address or an absolute (non-relocatable) number. 951 952Symbol names have the following syntax: 953 ``[a-zA-Z_.][a-zA-Z0-9_$.@]*`` 954 955The table below provides several examples of syntax used for symbol definition. 956 957 ================ ========================================================== 958 Syntax Meaning 959 ================ ========================================================== 960 .globl <S> Declares a global symbol S without assigning it a value. 961 .set <S>, <E> Assigns the value of an expression E to a symbol S. 962 <S> = <E> Assigns the value of an expression E to a symbol S. 963 <S>: Declares a label S and assigns it the current PC value. 964 ================ ========================================================== 965 966A symbol may be used before it is declared or assigned; 967unassigned symbols are assumed to be PC-relative. 968 969Additional information about symbols may be found :ref:`here<amdgpu-symbols>`. 970 971.. _amdgpu_synid_conv: 972 973Type and Size Conversion 974======================== 975 976This section describes what happens when a 64-bit 977:ref:`integer number<amdgpu_synid_integer_number>`, a 978:ref:`floating-point number<amdgpu_synid_floating-point_number>` or an 979:ref:`expression<amdgpu_synid_expression>` 980is used for an operand which has a different type or size. 981 982.. _amdgpu_synid_int_conv: 983 984Conversion of Integer Values 985---------------------------- 986 987Instruction operands may be specified as 64-bit :ref:`integer numbers<amdgpu_synid_integer_number>` or 988:ref:`absolute expressions<amdgpu_synid_absolute_expression>`. These values are converted to 989the :ref:`expected operand type<amdgpu_syn_instruction_type>` using the following steps: 990 9911. *Validation*. Assembler checks if the input value may be truncated without loss to the required *truncation width* 992(see the table below). There are two cases when this operation is enabled: 993 994 * The truncated bits are all 0. 995 * The truncated bits are all 1 and the value after truncation has its MSB bit set. 996 997In all other cases assembler triggers an error. 998 9992. *Conversion*. The input value is converted to the expected type as described in the table below. 1000Depending on operand kind, this conversion is performed by either assembler or AMDGPU H/W (or both). 1001 1002 ============== ================= =============== ==================================================================== 1003 Expected type Truncation Width Conversion Description 1004 ============== ================= =============== ==================================================================== 1005 i16, u16, b16 16 num.u16 Truncate to 16 bits. 1006 i32, u32, b32 32 num.u32 Truncate to 32 bits. 1007 i64 32 {-1,num.i32} Truncate to 32 bits and then sign-extend the result to 64 bits. 1008 u64, b64 32 {0,num.u32} Truncate to 32 bits and then zero-extend the result to 64 bits. 1009 f16 16 num.u16 Use low 16 bits as an f16 value. 1010 f32 32 num.u32 Use low 32 bits as an f32 value. 1011 f64 32 {num.u32,0} Use low 32 bits of the number as high 32 bits 1012 of the result; low 32 bits of the result are zeroed. 1013 ============== ================= =============== ==================================================================== 1014 1015Examples of enabled conversions: 1016 1017.. parsed-literal:: 1018 1019 // GFX9 1020 1021 v_add_u16 v0, -1, 0 // src0 = 0xFFFF 1022 v_add_f16 v0, -1, 0 // src0 = 0xFFFF (NaN) 1023 // 1024 v_add_u32 v0, -1, 0 // src0 = 0xFFFFFFFF 1025 v_add_f32 v0, -1, 0 // src0 = 0xFFFFFFFF (NaN) 1026 // 1027 v_add_u16 v0, 0xff00, v0 // src0 = 0xff00 1028 v_add_u16 v0, 0xffffffffffffff00, v0 // src0 = 0xff00 1029 v_add_u16 v0, -256, v0 // src0 = 0xff00 1030 // 1031 s_bfe_i64 s[0:1], 0xffefffff, s3 // src0 = 0xffffffffffefffff 1032 s_bfe_u64 s[0:1], 0xffefffff, s3 // src0 = 0x00000000ffefffff 1033 v_ceil_f64_e32 v[0:1], 0xffefffff // src0 = 0xffefffff00000000 (-1.7976922776554302e308) 1034 // 1035 x = 0xffefffff // 1036 s_bfe_i64 s[0:1], x, s3 // src0 = 0xffffffffffefffff 1037 s_bfe_u64 s[0:1], x, s3 // src0 = 0x00000000ffefffff 1038 v_ceil_f64_e32 v[0:1], x // src0 = 0xffefffff00000000 (-1.7976922776554302e308) 1039 1040Examples of disabled conversions: 1041 1042.. parsed-literal:: 1043 1044 // GFX9 1045 1046 v_add_u16 v0, 0x1ff00, v0 // truncated bits are not all 0 or 1 1047 v_add_u16 v0, 0xffffffffffff00ff, v0 // truncated bits do not match MSB of the result 1048 1049.. _amdgpu_synid_fp_conv: 1050 1051Conversion of Floating-Point Values 1052----------------------------------- 1053 1054Instruction operands may be specified as 64-bit :ref:`floating-point numbers<amdgpu_synid_floating-point_number>`. 1055These values are converted to the :ref:`expected operand type<amdgpu_syn_instruction_type>` using the following steps: 1056 10571. *Validation*. Assembler checks if the input f64 number can be converted 1058to the *required floating-point type* (see the table below) without overflow or underflow. 1059Precision lost is allowed. If this conversion is not possible, assembler triggers an error. 1060 10612. *Conversion*. The input value is converted to the expected type as described in the table below. 1062Depending on operand kind, this is performed by either assembler or AMDGPU H/W (or both). 1063 1064 ============== ================ ================= ================================================================= 1065 Expected type Required FP Type Conversion Description 1066 ============== ================ ================= ================================================================= 1067 i16, u16, b16 f16 f16(num) Convert to f16 and use bits of the result as an integer value. 1068 i32, u32, b32 f32 f32(num) Convert to f32 and use bits of the result as an integer value. 1069 i64, u64, b64 \- \- Conversion disabled. 1070 f16 f16 f16(num) Convert to f16. 1071 f32 f32 f32(num) Convert to f32. 1072 f64 f64 {num.u32.hi,0} Use high 32 bits of the number as high 32 bits of the result; 1073 zero-fill low 32 bits of the result. 1074 1075 Note that the result may differ from the original number. 1076 ============== ================ ================= ================================================================= 1077 1078Examples of enabled conversions: 1079 1080.. parsed-literal:: 1081 1082 // GFX9 1083 1084 v_add_f16 v0, 1.0, 0 // src0 = 0x3C00 (1.0) 1085 v_add_u16 v0, 1.0, 0 // src0 = 0x3C00 1086 // 1087 v_add_f32 v0, 1.0, 0 // src0 = 0x3F800000 (1.0) 1088 v_add_u32 v0, 1.0, 0 // src0 = 0x3F800000 1089 1090 // src0 before conversion: 1091 // 1.7976931348623157e308 = 0x7fefffffffffffff 1092 // src0 after conversion: 1093 // 1.7976922776554302e308 = 0x7fefffff00000000 1094 v_ceil_f64 v[0:1], 1.7976931348623157e308 1095 1096 v_add_f16 v1, 65500.0, v2 // ok for f16. 1097 v_add_f32 v1, 65600.0, v2 // ok for f32, but would result in overflow for f16. 1098 1099Examples of disabled conversions: 1100 1101.. parsed-literal:: 1102 1103 // GFX9 1104 1105 v_add_f16 v1, 65600.0, v2 // overflow 1106 1107.. _amdgpu_synid_rl_conv: 1108 1109Conversion of Relocatable Values 1110-------------------------------- 1111 1112:ref:`Relocatable expressions<amdgpu_synid_relocatable_expression>` 1113may be used with 32-bit integer operands and jump targets. 1114 1115When the value of a relocatable expression is resolved by a linker, it is 1116converted as needed and truncated to the operand size. The conversion depends 1117on :ref:`relocation type<amdgpu-relocation-records>` and operand kind. 1118 1119For example, when a 32-bit operand of an instruction refers a relocatable expression *expr*, 1120this reference is evaluated to a 64-bit offset from the address after the 1121instruction to the address being referenced, *counted in bytes*. 1122Then the value is truncated to 32 bits and encoded as a literal: 1123 1124.. parsed-literal:: 1125 1126 expr = . 1127 v_add_co_u32_e32 v0, vcc, expr, v1 // 'expr' operand is evaluated to -4 1128 // and then truncated to 0xFFFFFFFC 1129 1130As another example, when a branch instruction refers a label, 1131this reference is evaluated to an offset from the address after the 1132instruction to the label address, *counted in dwords*. 1133Then the value is truncated to 16 bits: 1134 1135.. parsed-literal:: 1136 1137 label: 1138 s_branch label // 'label' operand is evaluated to -1 and truncated to 0xFFFF 1139