llvm/docs/AMDGPUOperandSyntax.rst

   1 =====================================
   2 Syntax of AMDGPU Instruction Operands
   3 =====================================
   4
   5 .. contents::
   6    :local:
   7
   8 Conventions
   9 ===========
  10
  11 The 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
  22 Operands
  23 ========
  24
  25 .. _amdgpu_synid_v:
  26
  27 v (32-bit)
  28 ----------
  29
  30 Vector registers. There are 256 32-bit vector registers.
  31
  32 A sequence of *vector* registers may be used to operate with more than 32 bits of data.
  33
  34 Assembler 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
  59 Note: *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
  66 GFX90A and GFX940 have an additional alignment requirement:
  67 pairs of *vector* registers must be even-aligned
  68 (first register must be even).
  69
  70 Examples:
  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
  88 GFX10+ *image* instructions may use special *NSA* (Non-Sequential Address)
  89 syntax 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
 108 Examples:
 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
 118 v (16-bit)
 119 ----------
 120
 121 16-bit vector registers. Each :ref:`32-bit vector register<amdgpu_synid_v>` is divided into two 16-bit low and high registers, so there are 512 16-bit vector registers.
 122
 123 Only VOP3, VOP3P and VINTERP instructions may access all 512 registers (using :ref:`op_sel<amdgpu_synid_op_sel>` modifier).
 124 VOP1, 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
 135 Note: *N* must satisfy the following conditions:
 136
 137 * 0 <= *N* <= 127.
 138
 139 Examples:
 140
 141 .. parsed-literal::
 142
 143   v127
 144
 145 .. _amdgpu_synid_a:
 146
 147 a
 148 -
 149
 150 Accumulator registers. There are 256 32-bit accumulator registers.
 151
 152 A sequence of *accumulator* registers may be used to operate with more than 32 bits of data.
 153
 154 Assembler 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
 179 Note: *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
 186 GFX90A and GFX940 have an additional alignment requirement:
 187 pairs of *accumulator* registers must be even-aligned
 188 (first register must be even).
 189
 190 Examples:
 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
 211 s
 212 -
 213
 214 Scalar 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
 225 A sequence of *scalar* registers may be used to operate with more than 32 bits of data.
 226 Assembler currently supports tuples with 1 to 12, 16 and 32 *scalar* registers.
 227
 228 Pairs of *scalar* registers must be even-aligned (first register must be even).
 229 Sequences 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
 256 Note: *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
 264 Examples:
 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
 278 Examples 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
 287 trap
 288 ----
 289
 290 A 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
 298 ttmp
 299 ----
 300
 301 Trap handler temporary scalar registers, 32-bits wide.
 302 The 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
 313 A sequence of *ttmp* registers may be used to operate with more than 32 bits of data.
 314 Assembler currently supports tuples with 1 to 12 and 16 *ttmp* registers.
 315
 316 Pairs of *ttmp* registers must be even-aligned (first register must be even).
 317 Sequences 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
 342 Note: *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
 350 Examples:
 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
 364 Examples 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
 373 tba
 374 ---
 375
 376 Trap base address, 64-bits wide. Holds the pointer to the current
 377 trap 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
 387 High 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
 400 tma
 401 ---
 402
 403 Trap 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
 413 High 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
 426 flat_scratch
 427 ------------
 428
 429 Flat 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
 439 High 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
 453 xnack_mask
 454 ----------
 455
 456 Xnack mask, 64-bits wide. Holds a 64-bit mask of which threads
 457 received an *XNACK* due to a vector memory operation.
 458
 459 For 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
 469 High 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
 483 vcc
 484 ---
 485
 486 Vector condition code, 64-bits wide. A bit mask with one bit per thread;
 487 it holds the result of a vector compare operation.
 488
 489 Note 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
 499 High 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
 512 m0
 513 --
 514
 515 A 32-bit memory register. It has various uses,
 516 including 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
 527 exec
 528 ----
 529
 530 Execute mask, 64-bits wide. A bit mask with one bit per thread,
 531 which is applied to vector instructions and controls which threads execute
 532 and which ignore the instruction.
 533
 534 Note 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
 544 High 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
 557 vccz
 558 ----
 559
 560 A single bit flag indicating that the :ref:`vcc<amdgpu_synid_vcc>`
 561 is all zeros.
 562
 563 Note: when GFX10+ operates in *wave32* mode, this register reflects
 564 the state of :ref:`vcc_lo<amdgpu_synid_vcc_lo>`.
 565
 566 .. _amdgpu_synid_execz:
 567
 568 execz
 569 -----
 570
 571 A single bit flag indicating that the :ref:`exec<amdgpu_synid_exec>`
 572 is all zeros.
 573
 574 Note: when GFX10+ operates in *wave32* mode, this register reflects
 575 the state of :ref:`exec_lo<amdgpu_synid_exec>`.
 576
 577 .. _amdgpu_synid_scc:
 578
 579 scc
 580 ---
 581
 582 A single bit flag indicating the result of a scalar compare operation.
 583
 584 .. _amdgpu_synid_lds_direct:
 585
 586 lds_direct
 587 ----------
 588
 589 A special operand which supplies a 32-bit value
 590 fetched from *LDS* memory using :ref:`m0<amdgpu_synid_m0>` as an address.
 591
 592 .. _amdgpu_synid_null:
 593
 594 null
 595 ----
 596
 597 This is a special operand that may be used as a source or a destination.
 598
 599 When used as a destination, the result of the operation is discarded.
 600
 601 When used as a source, it supplies zero value.
 602
 603 .. _amdgpu_synid_constant:
 604
 605 inline constant
 606 ---------------
 607
 608 An *inline constant* is an integer or a floating-point value
 609 encoded as a part of an instruction. Compare *inline constants*
 610 with :ref:`literals<amdgpu_synid_literal>`.
 611
 612 Inline 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
 618 If a number may be encoded as either
 619 a :ref:`literal<amdgpu_synid_literal>` or
 620 a :ref:`constant<amdgpu_synid_constant>`,
 621 the assembler selects the latter encoding as more efficient.
 622
 623 .. _amdgpu_synid_iconst:
 624
 625 iconst
 626 ~~~~~~
 627
 628 An :ref:`integer number<amdgpu_synid_integer_number>` or
 629 an :ref:`absolute expression<amdgpu_synid_absolute_expression>`
 630 encoded as an *inline constant*.
 631
 632 Only a small fraction of integer numbers may be encoded as *inline constants*.
 633 They are enumerated in the table below.
 634 Other 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
 645 fconst
 646 ~~~~~~
 647
 648 A :ref:`floating-point number<amdgpu_synid_floating-point_number>`
 649 encoded as an *inline constant*.
 650
 651 Only a small fraction of floating-point numbers may be encoded
 652 as *inline constants*. They are enumerated in the table below.
 653 Other 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
 678 ival
 679 ~~~~
 680
 681 A symbolic operand encoded as an *inline constant*.
 682 These 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
 696 literal
 697 -------
 698
 699 A *literal* is a 64-bit value encoded as a separate
 700 32-bit dword in the instruction stream. Compare *literals*
 701 with :ref:`inline constants<amdgpu_synid_constant>`.
 702
 703 If a number may be encoded as either
 704 a :ref:`literal<amdgpu_synid_literal>` or
 705 an :ref:`inline constant<amdgpu_synid_constant>`,
 706 assembler selects the latter encoding as more efficient.
 707
 708 Literals 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
 714 An instruction may use only one literal,
 715 but several operands may refer to the same literal.
 716
 717 .. _amdgpu_synid_uimm8:
 718
 719 uimm8
 720 -----
 721
 722 An 8-bit :ref:`integer number<amdgpu_synid_integer_number>`
 723 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.
 724 The value must be in the range 0..0xFF.
 725
 726 .. _amdgpu_synid_uimm32:
 727
 728 uimm32
 729 ------
 730
 731 A 32-bit :ref:`integer number<amdgpu_synid_integer_number>`
 732 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.
 733 The value must be in the range 0..0xFFFFFFFF.
 734
 735 .. _amdgpu_synid_uimm20:
 736
 737 uimm20
 738 ------
 739
 740 A 20-bit :ref:`integer number<amdgpu_synid_integer_number>`
 741 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.
 742
 743 The value must be in the range 0..0xFFFFF.
 744
 745 .. _amdgpu_synid_simm21:
 746
 747 simm21
 748 ------
 749
 750 A 21-bit :ref:`integer number<amdgpu_synid_integer_number>`
 751 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.
 752
 753 The value must be in the range -0x100000..0x0FFFFF.
 754
 755 .. _amdgpu_synid_off:
 756
 757 off
 758 ---
 759
 760 A 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
 771 Numbers
 772 =======
 773
 774 .. _amdgpu_synid_integer_number:
 775
 776 Integer Numbers
 777 ---------------
 778
 779 Integer numbers are 64 bits wide.
 780 They are converted to :ref:`expected operand type<amdgpu_syn_instruction_type>`
 781 as described :ref:`here<amdgpu_synid_int_conv>`.
 782
 783 Integer numbers may be specified in binary, octal,
 784 hexadecimal 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
 798 Floating-Point Numbers
 799 ----------------------
 800
 801 All floating-point numbers are handled as double (64 bits wide).
 802 They are converted to
 803 :ref:`expected operand type<amdgpu_syn_instruction_type>`
 804 as described :ref:`here<amdgpu_synid_fp_conv>`.
 805
 806 Floating-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
 819 Expressions
 820 ===========
 821
 822 An expression is evaluated to a 64-bit integer.
 823 Note that floating-point expressions are not supported.
 824
 825 There 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
 832 Absolute Expressions
 833 --------------------
 834
 835 The value of an absolute expression does not change after program relocation.
 836 Absolute expressions must not include unassigned and relocatable values
 837 such as labels.
 838
 839 Absolute expressions are evaluated to 64-bit integer values and converted to
 840 :ref:`expected operand type<amdgpu_syn_instruction_type>`
 841 as described :ref:`here<amdgpu_synid_int_conv>`.
 842
 843 Examples:
 844
 845 .. parsed-literal::
 846
 847     x = -1
 848     y = x + 10
 849
 850 .. _amdgpu_synid_relocatable_expression:
 851
 852 Relocatable Expressions
 853 -----------------------
 854
 855 The value of a relocatable expression depends on program relocation.
 856
 857 Note that use of relocatable expressions is limited to branch targets
 858 and 32-bit integer operands.
 859
 860 A relocatable expression is evaluated to a 64-bit integer value,
 861 which depends on operand kind and
 862 :ref:`relocation type<amdgpu-relocation-records>` of symbol(s)
 863 used in the expression. For example, if an instruction refers to a label,
 864 this reference is evaluated to an offset from the address after
 865 the 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
 872 Note that values of relocatable expressions are usually unknown
 873 at assembly time; they are resolved later by a linker and converted to
 874 :ref:`expected operand type<amdgpu_syn_instruction_type>`
 875 as described :ref:`here<amdgpu_synid_rl_conv>`.
 876
 877 Operands and Operations
 878 -----------------------
 879
 880 Expressions are composed of 64-bit integer operands and operations.
 881 Operands include :ref:`integer numbers<amdgpu_synid_integer_number>`
 882 and :ref:`symbols<amdgpu_synid_symbol>`.
 883
 884 Expressions may also use "." which is a reference
 885 to the current PC (program counter).
 886
 887 :ref:`Unary<amdgpu_synid_expression_un_op>` and
 888 :ref:`binary<amdgpu_synid_expression_bin_op>`
 889 operations produce 64-bit integer results.
 890
 891 Syntax of Expressions
 892 ---------------------
 893
 894 Syntax 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
 928 Binary Operators
 929 ----------------
 930
 931 Binary operators are described in the following table.
 932 They operate on and produce 64-bit integers.
 933 Operators 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
 961 Unary Operators
 962 ---------------
 963
 964 Unary operators are described in the following table.
 965 They 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
 978 Symbols
 979 -------
 980
 981 A symbol is a named 64-bit integer value, representing a relocatable
 982 address or an absolute (non-relocatable) number.
 983
 984 Symbol names have the following syntax:
 985     ``[a-zA-Z_.][a-zA-Z0-9_$.@]*``
 986
 987 The 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
 998 A symbol may be used before it is declared or assigned;
 999 unassigned symbols are assumed to be PC-relative.
1000
1001 Additional information about symbols may be found :ref:`here<amdgpu-symbols>`.
1002
1003 .. _amdgpu_synid_conv:
1004
1005 Type and Size Conversion
1006 ========================
1007
1008 This 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>`
1012 is used for an operand which has a different type or size.
1013
1014 .. _amdgpu_synid_int_conv:
1015
1016 Conversion of Integer Values
1017 ----------------------------
1018
1019 Instruction operands may be specified as 64-bit
1020 :ref:`integer numbers<amdgpu_synid_integer_number>` or
1021 :ref:`absolute expressions<amdgpu_synid_absolute_expression>`.
1022 These values are converted to the
1023 :ref:`expected operand type<amdgpu_syn_instruction_type>`
1024 using the following steps:
1025
1026 1. *Validation*. Assembler checks if the input value may be truncated
1027 without loss to the required *truncation width* (see the table below).
1028 There 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
1033 In all other cases, the assembler triggers an error.
1034
1035 2. *Conversion*. The input value is converted to the expected type
1036 as described in the table below. Depending on operand kind, this conversion
1037 is 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
1052 Examples 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
1077 Examples 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
1088 Conversion of Floating-Point Values
1089 -----------------------------------
1090
1091 Instruction operands may be specified as 64-bit
1092 :ref:`floating-point numbers<amdgpu_synid_floating-point_number>`.
1093 These values are converted to the
1094 :ref:`expected operand type<amdgpu_syn_instruction_type>`
1095 using the following steps:
1096
1097 1. *Validation*. Assembler checks if the input f64 number can be converted
1098 to the *required floating-point type* (see the table below) without overflow
1099 or underflow. Precision lost is allowed. If this conversion is not possible,
1100 the assembler triggers an error.
1101
1102 2. *Conversion*. The input value is converted to the expected type
1103 as described in the table below. Depending on operand kind, this is
1104 performed 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
1122 Examples 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
1143 Examples 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
1153 Conversion of Relocatable Values
1154 --------------------------------
1155
1156 :ref:`Relocatable expressions<amdgpu_synid_relocatable_expression>`
1157 may be used with 32-bit integer operands and jump targets.
1158
1159 When the value of a relocatable expression is resolved by a linker, it is
1160 converted as needed and truncated to the operand size. The conversion depends
1161 on :ref:`relocation type<amdgpu-relocation-records>` and operand kind.
1162
1163 For example, when a 32-bit operand of an instruction refers
1164 to a relocatable expression *expr*, this reference is evaluated
1165 to a 64-bit offset from the address after the
1166 instruction to the address being referenced, *counted in bytes*.
1167 Then 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
1175 As another example, when a branch instruction refers to a label,
1176 this reference is evaluated to an offset from the address after the
1177 instruction to the label address, *counted in dwords*.
1178 Then 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