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* is explained elsewhere.
  18     =================== =============================================================================
  19
  20 .. _amdgpu_syn_operands:
  21
  22 Operands
  23 ========
  24
  25 .. _amdgpu_synid_v:
  26
  27 v
  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 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
  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 equal to 1, 2, 3, 4, 8 or 16.
  65
  66 Examples:
  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
  82 GFX10 *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
  97 Examples:
  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
 107 a
 108 -
 109
 110 Accumulator registers. There are 256 32-bit accumulator registers.
 111
 112 A sequence of *accumulator* registers may be used to operate with more than 32 bits of data.
 113
 114 Assembler 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
 139 Note: *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
 146 Examples:
 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
 167 s
 168 -
 169
 170 Scalar 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
 181 A sequence of *scalar* registers may be used to operate with more than 32 bits of data.
 182 Assembler currently supports sequences of 1, 2, 4, 8 and 16 *scalar* registers.
 183
 184 Pairs of *scalar* registers must be even-aligned (the first register must be even).
 185 Sequences 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
 212 Note: *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
 220 Examples:
 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
 234 Examples 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
 243 trap
 244 ----
 245
 246 A 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
 254 ttmp
 255 ----
 256
 257 Trap handler temporary scalar registers, 32-bits wide.
 258 The 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
 269 A sequence of *ttmp* registers may be used to operate with more than 32 bits of data.
 270 Assembler currently supports sequences of 1, 2, 4, 8 and 16 *ttmp* registers.
 271
 272 Pairs of *ttmp* registers must be even-aligned (the first register must be even).
 273 Sequences 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
 298 Note: *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
 306 Examples:
 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
 320 Examples 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
 329 tba
 330 ---
 331
 332 Trap 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
 342 High 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
 353 Note that *tba*, *tba_lo* and *tba_hi* are not accessible as assembler registers in GFX9 and GFX10,
 354 but *tba* is readable/writable with the help of *s_get_reg* and *s_set_reg* instructions.
 355
 356 .. _amdgpu_synid_tma:
 357
 358 tma
 359 ---
 360
 361 Trap 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
 371 High 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
 382 Note that *tma*, *tma_lo* and *tma_hi* are not accessible as assembler registers in GFX9 and GFX10,
 383 but *tma* is readable/writable with the help of *s_get_reg* and *s_set_reg* instructions.
 384
 385 .. _amdgpu_synid_flat_scratch:
 386
 387 flat_scratch
 388 ------------
 389
 390 Flat 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
 400 High 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
 413 xnack
 414 -----
 415
 416 Xnack mask, 64-bits wide. Holds a 64-bit mask of which threads
 417 received 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
 431 High 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
 445 vcc
 446 ---
 447
 448 Vector condition code, 64-bits wide. A bit mask with one bit per thread;
 449 it holds the result of a vector compare operation.
 450
 451 Note 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
 461 High 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
 474 m0
 475 --
 476
 477 A 32-bit memory register. It has various uses,
 478 including 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
 489 exec
 490 ----
 491
 492 Execute mask, 64-bits wide. A bit mask with one bit per thread,
 493 which is applied to vector instructions and controls which threads execute
 494 and which ignore the instruction.
 495
 496 Note 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
 506 High 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
 519 vccz
 520 ----
 521
 522 A single bit flag indicating that the :ref:`vcc<amdgpu_synid_vcc>` is all zeros.
 523
 524 Note: when GFX10 operates in *wave32* mode, this register reflects state of :ref:`vcc_lo<amdgpu_synid_vcc_lo>`.
 525
 526 .. _amdgpu_synid_execz:
 527
 528 execz
 529 -----
 530
 531 A single bit flag indicating that the :ref:`exec<amdgpu_synid_exec>` is all zeros.
 532
 533 Note: when GFX10 operates in *wave32* mode, this register reflects state of :ref:`exec_lo<amdgpu_synid_exec>`.
 534
 535 .. _amdgpu_synid_scc:
 536
 537 scc
 538 ---
 539
 540 A single bit flag indicating the result of a scalar compare operation.
 541
 542 .. _amdgpu_synid_lds_direct:
 543
 544 lds_direct
 545 ----------
 546
 547 A special operand which supplies a 32-bit value
 548 fetched from *LDS* memory using :ref:`m0<amdgpu_synid_m0>` as an address.
 549
 550 .. _amdgpu_synid_null:
 551
 552 null
 553 ----
 554
 555 This is a special operand which may be used as a source or a destination.
 556
 557 When used as a destination, the result of the operation is discarded.
 558
 559 When used as a source, it supplies zero value.
 560
 561 GFX10 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
 567 inline constant
 568 ---------------
 569
 570 An *inline constant* is an integer or a floating-point value encoded as a part of an instruction.
 571 Compare *inline constants* with :ref:`literals<amdgpu_synid_literal>`.
 572
 573 Inline constants include:
 574
 575 * :ref:`iconst<amdgpu_synid_iconst>`
 576 * :ref:`fconst<amdgpu_synid_fconst>`
 577 * :ref:`ival<amdgpu_synid_ival>`
 578
 579 If a number may be encoded as either
 580 a :ref:`literal<amdgpu_synid_literal>` or
 581 a :ref:`constant<amdgpu_synid_constant>`,
 582 assembler selects the latter encoding as more efficient.
 583
 584 .. _amdgpu_synid_iconst:
 585
 586 iconst
 587 ~~~~~~
 588
 589 An :ref:`integer number<amdgpu_synid_integer_number>` or
 590 an :ref:`absolute expression<amdgpu_synid_absolute_expression>`
 591 encoded as an *inline constant*.
 592
 593 Only a small fraction of integer numbers may be encoded as *inline constants*.
 594 They are enumerated in the table below.
 595 Other 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
 608 fconst
 609 ~~~~~~
 610
 611 A :ref:`floating-point number<amdgpu_synid_floating-point_number>`
 612 encoded as an *inline constant*.
 613
 614 Only a small fraction of floating-point numbers may be encoded as *inline constants*.
 615 They are enumerated in the table below.
 616 Other 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
 639 ival
 640 ~~~~
 641
 642 A symbolic operand encoded as an *inline constant*.
 643 These 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
 657 literal
 658 -------
 659
 660 A *literal* is a 64-bit value encoded as a separate 32-bit dword in the instruction stream.
 661 Compare *literals* with :ref:`inline constants<amdgpu_synid_constant>`.
 662
 663 If a number may be encoded as either
 664 a :ref:`literal<amdgpu_synid_literal>` or
 665 an :ref:`inline constant<amdgpu_synid_constant>`,
 666 assembler selects the latter encoding as more efficient.
 667
 668 Literals 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
 673 An instruction may use only one literal but several operands may refer the same literal.
 674
 675 .. _amdgpu_synid_uimm8:
 676
 677 uimm8
 678 -----
 679
 680 A 8-bit :ref:`integer number<amdgpu_synid_integer_number>`
 681 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.
 682 The value must be in the range 0..0xFF.
 683
 684 .. _amdgpu_synid_uimm32:
 685
 686 uimm32
 687 ------
 688
 689 A 32-bit :ref:`integer number<amdgpu_synid_integer_number>`
 690 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.
 691 The value must be in the range 0..0xFFFFFFFF.
 692
 693 .. _amdgpu_synid_uimm20:
 694
 695 uimm20
 696 ------
 697
 698 A 20-bit :ref:`integer number<amdgpu_synid_integer_number>`
 699 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.
 700
 701 The value must be in the range 0..0xFFFFF.
 702
 703 .. _amdgpu_synid_uimm21:
 704
 705 uimm21
 706 ------
 707
 708 A 21-bit :ref:`integer number<amdgpu_synid_integer_number>`
 709 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.
 710
 711 The 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
 717 simm21
 718 ------
 719
 720 A 21-bit :ref:`integer number<amdgpu_synid_integer_number>`
 721 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.
 722
 723 The 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
 729 off
 730 ---
 731
 732 A 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
 743 Numbers
 744 =======
 745
 746 .. _amdgpu_synid_integer_number:
 747
 748 Integer Numbers
 749 ---------------
 750
 751 Integer numbers are 64 bits wide.
 752 They are converted to :ref:`expected operand type<amdgpu_syn_instruction_type>`
 753 as described :ref:`here<amdgpu_synid_int_conv>`.
 754
 755 Integer 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
 769 Floating-Point Numbers
 770 ----------------------
 771
 772 All floating-point numbers are handled as double (64 bits wide).
 773 They are converted to
 774 :ref:`expected operand type<amdgpu_syn_instruction_type>`
 775 as described :ref:`here<amdgpu_synid_fp_conv>`.
 776
 777 Floating-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
 790 Expressions
 791 ===========
 792
 793 An expression is evaluated to a 64-bit integer.
 794 Note that floating-point expressions are not supported.
 795
 796 There 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
 803 Absolute Expressions
 804 --------------------
 805
 806 The value of an absolute expression does not change after program relocation.
 807 Absolute expressions must not include unassigned and relocatable values
 808 such as labels.
 809
 810 Absolute expressions are evaluated to 64-bit integer values and converted to
 811 :ref:`expected operand type<amdgpu_syn_instruction_type>`
 812 as described :ref:`here<amdgpu_synid_int_conv>`.
 813
 814 Examples:
 815
 816 .. parsed-literal::
 817
 818     x = -1
 819     y = x + 10
 820
 821 .. _amdgpu_synid_relocatable_expression:
 822
 823 Relocatable Expressions
 824 -----------------------
 825
 826 The value of a relocatable expression depends on program relocation.
 827
 828 Note that use of relocatable expressions is limited with branch targets
 829 and 32-bit integer operands.
 830
 831 A relocatable expression is evaluated to a 64-bit integer value
 832 which depends on operand kind and :ref:`relocation type<amdgpu-relocation-records>`
 833 of symbol(s) used in the expression. For example, if an instruction refers a label,
 834 this reference is evaluated to an offset from the address after the instruction
 835 to 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
 842 Note that values of relocatable expressions are usually unknown at assembly time;
 843 they are resolved later by a linker and converted to
 844 :ref:`expected operand type<amdgpu_syn_instruction_type>`
 845 as described :ref:`here<amdgpu_synid_rl_conv>`.
 846
 847 Operands and Operations
 848 -----------------------
 849
 850 Expressions are composed of 64-bit integer operands and operations.
 851 Operands include :ref:`integer numbers<amdgpu_synid_integer_number>`
 852 and :ref:`symbols<amdgpu_synid_symbol>`.
 853
 854 Expressions 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>`
 857 operations produce 64-bit integer results.
 858
 859 Syntax of Expressions
 860 ---------------------
 861
 862 The 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
 896 Binary Operators
 897 ----------------
 898
 899 Binary operators are described in the following table.
 900 They operate on and produce 64-bit integers.
 901 Operators 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
 929 Unary Operators
 930 ---------------
 931
 932 Unary operators are described in the following table.
 933 They 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
 946 Symbols
 947 -------
 948
 949 A symbol is a named 64-bit integer value, representing a relocatable
 950 address or an absolute (non-relocatable) number.
 951
 952 Symbol names have the following syntax:
 953     ``[a-zA-Z_.][a-zA-Z0-9_$.@]*``
 954
 955 The 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
 966 A symbol may be used before it is declared or assigned;
 967 unassigned symbols are assumed to be PC-relative.
 968
 969 Additional information about symbols may be found :ref:`here<amdgpu-symbols>`.
 970
 971 .. _amdgpu_synid_conv:
 972
 973 Type and Size Conversion
 974 ========================
 975
 976 This 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>`
 980 is used for an operand which has a different type or size.
 981
 982 .. _amdgpu_synid_int_conv:
 983
 984 Conversion of Integer Values
 985 ----------------------------
 986
 987 Instruction 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
 989 the :ref:`expected operand type<amdgpu_syn_instruction_type>` using the following steps:
 990
 991 1. *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
 997 In all other cases assembler triggers an error.
 998
 999 2. *Conversion*. The input value is converted to the expected type as described in the table below.
1000 Depending 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
1015 Examples 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
1040 Examples 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
1051 Conversion of Floating-Point Values
1052 -----------------------------------
1053
1054 Instruction operands may be specified as 64-bit :ref:`floating-point numbers<amdgpu_synid_floating-point_number>`.
1055 These values are converted to the :ref:`expected operand type<amdgpu_syn_instruction_type>` using the following steps:
1056
1057 1. *Validation*. Assembler checks if the input f64 number can be converted
1058 to the *required floating-point type* (see the table below) without overflow or underflow.
1059 Precision lost is allowed. If this conversion is not possible, assembler triggers an error.
1060
1061 2. *Conversion*. The input value is converted to the expected type as described in the table below.
1062 Depending 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
1078 Examples 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
1099 Examples 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
1109 Conversion of Relocatable Values
1110 --------------------------------
1111
1112 :ref:`Relocatable expressions<amdgpu_synid_relocatable_expression>`
1113 may be used with 32-bit integer operands and jump targets.
1114
1115 When the value of a relocatable expression is resolved by a linker, it is
1116 converted as needed and truncated to the operand size. The conversion depends
1117 on :ref:`relocation type<amdgpu-relocation-records>` and operand kind.
1118
1119 For example, when a 32-bit operand of an instruction refers a relocatable expression *expr*,
1120 this reference is evaluated to a 64-bit offset from the address after the
1121 instruction to the address being referenced, *counted in bytes*.
1122 Then 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
1130 As another example, when a branch instruction refers a label,
1131 this reference is evaluated to an offset from the address after the
1132 instruction to the label address, *counted in dwords*.
1133 Then 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