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