1===================================== 2Syntax of AMDGPU Instruction Operands 3===================================== 4 5.. contents:: 6 :local: 7 8Conventions 9=========== 10 11The following notation is used throughout this document: 12 13 =================== ============================================================================= 14 Notation Description 15 =================== ============================================================================= 16 {0..N} Any integer value in the range from 0 to N (inclusive). 17 <x> Syntax and meaning of *x* is explained elsewhere. 18 =================== ============================================================================= 19 20.. _amdgpu_syn_operands: 21 22Operands 23======== 24 25.. _amdgpu_synid_v: 26 27v 28- 29 30Vector registers. There are 256 32-bit vector registers. 31 32A sequence of *vector* registers may be used to operate with more than 32 bits of data. 33 34Assembler currently supports sequences of 1, 2, 3, 4, 8 and 16 *vector* registers. 35 36 =================================================== ==================================================================== 37 Syntax Description 38 =================================================== ==================================================================== 39 **v**\<N> A single 32-bit *vector* register. 40 41 *N* must be a decimal 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 57Note. *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 64Examples: 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 93Note. Reqister indices must be in the range 0..255. They must be specified as decimal integer numbers. 94 95Examples: 96 97.. parsed-literal:: 98 99 [v32,v1,v2] 100 [v4,v4,v4,v4] 101 102.. _amdgpu_synid_s: 103 104s 105- 106 107Scalar 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 118A sequence of *scalar* registers may be used to operate with more than 32 bits of data. 119Assembler currently supports sequences of 1, 2, 4, 8 and 16 *scalar* registers. 120 121Pairs of *scalar* registers must be even-aligned (the first register must be even). 122Sequences 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 145Note. *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 153Examples: 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 167Examples 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 176trap 177---- 178 179A 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 187ttmp 188---- 189 190Trap handler temporary scalar registers, 32-bits wide. 191The 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 202A sequence of *ttmp* registers may be used to operate with more than 32 bits of data. 203Assembler currently supports sequences of 1, 2, 4, 8 and 16 *ttmp* registers. 204 205Pairs of *ttmp* registers must be even-aligned (the first register must be even). 206Sequences 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 229Note. *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 237Examples: 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 251Examples 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 260tba 261--- 262 263Trap 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 273High 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 284Note that *tba*, *tba_lo* and *tba_hi* are not accessible as assembler registers in GFX9 and GFX10, 285but *tba* is readable/writable with the help of *s_get_reg* and *s_set_reg* instructions. 286 287.. _amdgpu_synid_tma: 288 289tma 290--- 291 292Trap 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 302High 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 313Note that *tma*, *tma_lo* and *tma_hi* are not accessible as assembler registers in GFX9 and GFX10, 314but *tma* is readable/writable with the help of *s_get_reg* and *s_set_reg* instructions. 315 316.. _amdgpu_synid_flat_scratch: 317 318flat_scratch 319------------ 320 321Flat 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 331High 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 344xnack 345----- 346 347Xnack mask, 64-bits wide. Holds a 64-bit mask of which threads 348received 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 362High 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 376vcc 377--- 378 379Vector condition code, 64-bits wide. A bit mask with one bit per thread; 380it holds the result of a vector compare operation. 381 382Note 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 392High 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 405m0 406-- 407 408A 32-bit memory register. It has various uses, 409including 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 420exec 421---- 422 423Execute mask, 64-bits wide. A bit mask with one bit per thread, 424which is applied to vector instructions and controls which threads execute 425and which ignore the instruction. 426 427Note 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 437High 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 450vccz 451---- 452 453A single bit flag indicating that the :ref:`vcc<amdgpu_synid_vcc>` is all zeros. 454 455Note. When GFX10 operates in *wave32* mode, this register reflects state of :ref:`vcc_lo<amdgpu_synid_vcc_lo>`. 456 457.. _amdgpu_synid_execz: 458 459execz 460----- 461 462A single bit flag indicating that the :ref:`exec<amdgpu_synid_exec>` is all zeros. 463 464Note. When GFX10 operates in *wave32* mode, this register reflects state of :ref:`exec_lo<amdgpu_synid_exec>`. 465 466.. _amdgpu_synid_scc: 467 468scc 469--- 470 471A single bit flag indicating the result of a scalar compare operation. 472 473.. _amdgpu_synid_lds_direct: 474 475lds_direct 476---------- 477 478A special operand which supplies a 32-bit value 479fetched from *LDS* memory using :ref:`m0<amdgpu_synid_m0>` as an address. 480 481.. _amdgpu_synid_null: 482 483null 484---- 485 486This is a special operand which may be used as a source or a destination. 487 488When used as a destination, the result of the operation is discarded. 489 490When used as a source, it supplies zero value. 491 492GFX10 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 498constant 499-------- 500 501A 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 507In contrast with :ref:`literals<amdgpu_synid_literal>`, these operands are encoded as a part of instruction. 508 509If a number may be encoded as either 510a :ref:`literal<amdgpu_synid_literal>` or 511a :ref:`constant<amdgpu_synid_constant>`, 512assembler selects the latter encoding as more efficient. 513 514.. _amdgpu_synid_iconst: 515 516iconst 517~~~~~~ 518 519An :ref:`integer number<amdgpu_synid_integer_number>` 520encoded as an *inline constant*. 521 522Only a small fraction of integer numbers may be encoded as *inline constants*. 523They are enumerated in the table below. 524Other integer numbers have to be encoded as :ref:`literals<amdgpu_synid_literal>`. 525 526Integer *inline constants* are converted to 527:ref:`expected operand type<amdgpu_syn_instruction_type>` 528as 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 541fconst 542~~~~~~ 543 544A :ref:`floating-point number<amdgpu_synid_floating-point_number>` 545encoded as an *inline constant*. 546 547Only a small fraction of floating-point numbers may be encoded as *inline constants*. 548They are enumerated in the table below. 549Other floating-point numbers have to be encoded as :ref:`literals<amdgpu_synid_literal>`. 550 551Floating-point *inline constants* are converted to 552:ref:`expected operand type<amdgpu_syn_instruction_type>` 553as 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 576ival 577~~~~ 578 579A symbolic operand encoded as an *inline constant*. 580These 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 594literal 595------- 596 597A literal is a 64-bit value which is encoded as a separate 32-bit dword in the instruction stream. 598 599If a number may be encoded as either 600a :ref:`literal<amdgpu_synid_literal>` or 601an :ref:`inline constant<amdgpu_synid_constant>`, 602assembler selects the latter encoding as more efficient. 603 604Literals 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 609A 64-bit literal value is converted by assembler 610to an :ref:`expected operand type<amdgpu_syn_instruction_type>` 611as described :ref:`here<amdgpu_synid_lit_conv>`. 612 613An instruction may use only one literal but several operands may refer the same literal. 614 615.. _amdgpu_synid_uimm8: 616 617uimm8 618----- 619 620A 8-bit positive :ref:`integer number<amdgpu_synid_integer_number>`. 621The value is encoded as part of the opcode so it is free to use. 622 623.. _amdgpu_synid_uimm32: 624 625uimm32 626------ 627 628A 32-bit positive :ref:`integer number<amdgpu_synid_integer_number>`. 629The value is stored as a separate 32-bit dword in the instruction stream. 630 631.. _amdgpu_synid_uimm20: 632 633uimm20 634------ 635 636A 20-bit positive :ref:`integer number<amdgpu_synid_integer_number>`. 637 638.. _amdgpu_synid_uimm21: 639 640uimm21 641------ 642 643A 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 649simm21 650------ 651 652A 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 658off 659--- 660 661A 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 672Numbers 673======= 674 675.. _amdgpu_synid_integer_number: 676 677Integer Numbers 678--------------- 679 680Integer numbers are 64 bits wide. 681They 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 693Examples: 694 695.. parsed-literal:: 696 697 -1234 698 0b1010 699 010 700 0xff 701 0ffh 702 703.. _amdgpu_synid_floating-point_number: 704 705Floating-Point Numbers 706---------------------- 707 708All floating-point numbers are handled as double (64 bits wide). 709 710Floating-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 719Examples: 720 721.. parsed-literal:: 722 723 -1.234 724 234e2 725 -0x1afp-10 726 0x.1afp10 727 728.. _amdgpu_synid_expression: 729 730Expressions 731=========== 732 733An expression specifies an address or a numeric value. 734There 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 741Absolute Expressions 742-------------------- 743 744The value of an absolute expression remains the same after program relocation. 745Absolute expressions must not include unassigned and relocatable values 746such as labels. 747 748Examples: 749 750.. parsed-literal:: 751 752 x = -1 753 y = x + 10 754 755.. _amdgpu_synid_relocatable_expression: 756 757Relocatable Expressions 758----------------------- 759 760The value of a relocatable expression depends on program relocation. 761 762Note that use of relocatable expressions is limited with branch targets 763and 32-bit :ref:`literals<amdgpu_synid_literal>`. 764 765Addition information about relocation may be found :ref:`here<amdgpu-relocation-records>`. 766 767Examples: 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 774Expression Data Type 775-------------------- 776 777Expressions and operands of expressions are interpreted as 64-bit integers. 778 779Expressions may include 64-bit :ref:`floating-point numbers<amdgpu_synid_floating-point_number>` (double). 780However these operands are also handled as 64-bit integers 781using binary representation of specified floating-point numbers. 782No conversion from floating-point to integer is performed. 783 784Examples: 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 791Syntax 792------ 793 794Expressions 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 801Expressions may also use "." which is a reference to the current PC (program counter). 802 803The 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 837Binary Operators 838---------------- 839 840Binary operators are described in the following table. 841They operate on and produce 64-bit integers. 842Operators 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 870Unary Operators 871--------------- 872 873Unary operators are described in the following table. 874They 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 887Symbols 888------- 889 890A symbol is a named 64-bit value, representing a relocatable 891address or an absolute (non-relocatable) number. 892 893Symbol names have the following syntax: 894 ``[a-zA-Z_.][a-zA-Z0-9_$.@]*`` 895 896The 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 907A symbol may be used before it is declared or assigned; 908unassigned symbols are assumed to be PC-relative. 909 910Addition information about symbols may be found :ref:`here<amdgpu-symbols>`. 911 912.. _amdgpu_synid_conv: 913 914Conversions 915=========== 916 917This 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>` 921is used for an operand which has a different type or size. 922 923Depending 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 930Inline Constants 931---------------- 932 933.. _amdgpu_synid_int_const_conv: 934 935Integer Inline Constants 936~~~~~~~~~~~~~~~~~~~~~~~~ 937 938Integer :ref:`inline constants<amdgpu_synid_constant>` 939may be thought of as 64-bit 940:ref:`integer numbers<amdgpu_synid_integer_number>`; 941when used as operands they are truncated to the size of 942:ref:`expected operand type<amdgpu_syn_instruction_type>`. 943No data type conversions are performed. 944 945Examples: 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 959Floating-Point Inline Constants 960~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 961 962Floating-point :ref:`inline constants<amdgpu_synid_constant>` 963may be thought of as 64-bit 964:ref:`floating-point numbers<amdgpu_synid_floating-point_number>`; 965when used as operands they are converted to a floating-point number of 966:ref:`expected operand size<amdgpu_syn_instruction_type>`. 967 968Examples: 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 983Literals 984-------- 985 986.. _amdgpu_synid_int_lit_conv: 987 988Integer Literals 989~~~~~~~~~~~~~~~~ 990 991Integer :ref:`literals<amdgpu_synid_literal>` 992are specified as 64-bit :ref:`integer numbers<amdgpu_synid_integer_number>`. 993 994When 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 1010The condition *cond(X,S)* indicates if a 64-bit number *X* 1011can be converted to a smaller size *S* by truncation of upper bits. 1012There 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 1017Examples 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 1031Examples 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 1042Floating-Point Literals 1043~~~~~~~~~~~~~~~~~~~~~~~ 1044 1045Floating-point :ref:`literals<amdgpu_synid_literal>` are specified as 64-bit 1046:ref:`floating-point numbers<amdgpu_synid_floating-point_number>`. 1047 1048When 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 1065The condition *cond(X,S)* indicates if an f64 number *X* can be converted 1066to a smaller *S*-bit floating-point type without overflow or underflow. 1067Precision lost is allowed. 1068 1069Examples 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 1082Examples 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 1092Expressions 1093~~~~~~~~~~~ 1094 1095Expressions operate with and result in 64-bit integers. 1096 1097When used as operands they are truncated to 1098:ref:`expected operand size<amdgpu_syn_instruction_type>`. 1099No data type conversions are performed. 1100 1101Examples: 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 1112