1 2.. _gmir-opcodes: 3 4Generic Opcodes 5=============== 6 7.. contents:: 8 :local: 9 10.. note:: 11 12 This documentation does not yet fully account for vectors. Many of the 13 scalar/integer/floating-point operations can also take vectors. 14 15Constants 16--------- 17 18G_IMPLICIT_DEF 19^^^^^^^^^^^^^^ 20 21An undefined value. 22 23.. code-block:: none 24 25 %0:_(s32) = G_IMPLICIT_DEF 26 27G_CONSTANT 28^^^^^^^^^^ 29 30An integer constant. 31 32.. code-block:: none 33 34 %0:_(s32) = G_CONSTANT i32 1 35 36G_FCONSTANT 37^^^^^^^^^^^ 38 39A floating point constant. 40 41.. code-block:: none 42 43 %0:_(s32) = G_FCONSTANT float 1.0 44 45G_FRAME_INDEX 46^^^^^^^^^^^^^ 47 48The address of an object in the stack frame. 49 50.. code-block:: none 51 52 %1:_(p0) = G_FRAME_INDEX %stack.0.ptr0 53 54G_GLOBAL_VALUE 55^^^^^^^^^^^^^^ 56 57The address of a global value. 58 59.. code-block:: none 60 61 %0(p0) = G_GLOBAL_VALUE @var_local 62 63G_BLOCK_ADDR 64^^^^^^^^^^^^ 65 66The address of a basic block. 67 68.. code-block:: none 69 70 %0:_(p0) = G_BLOCK_ADDR blockaddress(@test_blockaddress, %ir-block.block) 71 72Integer Extension and Truncation 73-------------------------------- 74 75G_ANYEXT 76^^^^^^^^ 77 78Extend the underlying scalar type of an operation, leaving the high bits 79unspecified. 80 81.. code-block:: none 82 83 %1:_(s32) = G_ANYEXT %0:_(s16) 84 85G_SEXT 86^^^^^^ 87 88Sign extend the underlying scalar type of an operation, copying the sign bit 89into the newly-created space. 90 91.. code-block:: none 92 93 %1:_(s32) = G_SEXT %0:_(s16) 94 95G_SEXT_INREG 96^^^^^^^^^^^^ 97 98Sign extend the value from an arbitrary bit position, copying the sign bit 99into all bits above it. This is equivalent to a shl + ashr pair with an 100appropriate shift amount. $sz is an immediate (MachineOperand::isImm() 101returns true) to allow targets to have some bitwidths legal and others 102lowered. This opcode is particularly useful if the target has sign-extension 103instructions that are cheaper than the constituent shifts as the optimizer is 104able to make decisions on whether it's better to hang on to the G_SEXT_INREG 105or to lower it and optimize the individual shifts. 106 107.. code-block:: none 108 109 %1:_(s32) = G_SEXT_INREG %0:_(s32), 16 110 111G_ZEXT 112^^^^^^ 113 114Zero extend the underlying scalar type of an operation, putting zero bits 115into the newly-created space. 116 117.. code-block:: none 118 119 %1:_(s32) = G_ZEXT %0:_(s16) 120 121G_TRUNC 122^^^^^^^ 123 124Truncate the underlying scalar type of an operation. This is equivalent to 125G_EXTRACT for scalar types, but acts elementwise on vectors. 126 127.. code-block:: none 128 129 %1:_(s16) = G_TRUNC %0:_(s32) 130 131Type Conversions 132---------------- 133 134G_INTTOPTR 135^^^^^^^^^^ 136 137Convert an integer to a pointer. 138 139.. code-block:: none 140 141 %1:_(p0) = G_INTTOPTR %0:_(s32) 142 143G_PTRTOINT 144^^^^^^^^^^ 145 146Convert a pointer to an integer. 147 148.. code-block:: none 149 150 %1:_(s32) = G_PTRTOINT %0:_(p0) 151 152G_BITCAST 153^^^^^^^^^ 154 155Reinterpret a value as a new type. This is usually done without 156changing any bits but this is not always the case due a sublety in the 157definition of the :ref:`LLVM-IR Bitcast Instruction <i_bitcast>`. It 158is allowed to bitcast between pointers with the same size, but 159different address spaces. 160 161.. code-block:: none 162 163 %1:_(s64) = G_BITCAST %0:_(<2 x s32>) 164 165G_ADDRSPACE_CAST 166^^^^^^^^^^^^^^^^ 167 168Convert a pointer to an address space to a pointer to another address space. 169 170.. code-block:: none 171 172 %1:_(p1) = G_ADDRSPACE_CAST %0:_(p0) 173 174.. caution:: 175 176 :ref:`i_addrspacecast` doesn't mention what happens if the cast is simply 177 invalid (i.e. if the address spaces are disjoint). 178 179Scalar Operations 180----------------- 181 182G_EXTRACT 183^^^^^^^^^ 184 185Extract a register of the specified size, starting from the block given by 186index. This will almost certainly be mapped to sub-register COPYs after 187register banks have been selected. 188 189G_INSERT 190^^^^^^^^ 191 192Insert a smaller register into a larger one at the specified bit-index. 193 194G_MERGE_VALUES 195^^^^^^^^^^^^^^ 196 197Concatenate multiple registers of the same size into a wider register. 198The input operands are always ordered from lowest bits to highest: 199 200.. code-block:: none 201 202 %0:(s32) = G_MERGE_VALUES %bits_0_7:(s8), %bits_8_15:(s8), 203 %bits_16_23:(s8), %bits_24_31:(s8) 204 205G_UNMERGE_VALUES 206^^^^^^^^^^^^^^^^ 207 208Extract multiple registers of the specified size, starting from blocks given by 209indexes. This will almost certainly be mapped to sub-register COPYs after 210register banks have been selected. 211The output operands are always ordered from lowest bits to highest: 212 213.. code-block:: none 214 215 %bits_0_7:(s8), %bits_8_15:(s8), 216 %bits_16_23:(s8), %bits_24_31:(s8) = G_UNMERGE_VALUES %0:(s32) 217 218G_BSWAP 219^^^^^^^ 220 221Reverse the order of the bytes in a scalar. 222 223.. code-block:: none 224 225 %1:_(s32) = G_BSWAP %0:_(s32) 226 227G_BITREVERSE 228^^^^^^^^^^^^ 229 230Reverse the order of the bits in a scalar. 231 232.. code-block:: none 233 234 %1:_(s32) = G_BITREVERSE %0:_(s32) 235 236Integer Operations 237------------------- 238 239G_ADD, G_SUB, G_MUL, G_AND, G_OR, G_XOR, G_SDIV, G_UDIV, G_SREM, G_UREM 240^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 241 242These each perform their respective integer arithmetic on a scalar. 243 244.. code-block:: none 245 246 %2:_(s32) = G_ADD %0:_(s32), %1:_(s32) 247 248G_SADDSAT, G_UADDSAT, G_SSUBSAT, G_USUBSAT 249^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 250 251Signed and unsigned addition and subtraction with saturation. 252 253.. code-block:: none 254 255 %2:_(s32) = G_SADDSAT %0:_(s32), %1:_(s32) 256 257G_SHL, G_LSHR, G_ASHR 258^^^^^^^^^^^^^^^^^^^^^ 259 260Shift the bits of a scalar left or right inserting zeros (sign-bit for G_ASHR). 261 262G_ICMP 263^^^^^^ 264 265Perform integer comparison producing non-zero (true) or zero (false). It's 266target specific whether a true value is 1, ~0U, or some other non-zero value. 267 268G_SELECT 269^^^^^^^^ 270 271Select between two values depending on a zero/non-zero value. 272 273.. code-block:: none 274 275 %5:_(s32) = G_SELECT %4(s1), %6, %2 276 277G_PTR_ADD 278^^^^^^^^^ 279 280Add a scalar offset in addressible units to a pointer. Addressible units are 281typically bytes but this may vary between targets. 282 283.. code-block:: none 284 285 %1:_(p0) = G_PTR_ADD %0:_(p0), %1:_(s32) 286 287.. caution:: 288 289 There are currently no in-tree targets that use this with addressable units 290 not equal to 8 bit. 291 292G_PTRMASK 293^^^^^^^^^^ 294 295Zero out an arbitrary mask of bits of a pointer. The mask type must be 296an integer, and the number of vector elements must match for all 297operands. This corresponds to `i_intr_llvm_ptrmask`. 298 299.. code-block:: none 300 301 %2:_(p0) = G_PTRMASK %0, %1 302 303G_SMIN, G_SMAX, G_UMIN, G_UMAX 304^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 305 306Take the minimum/maximum of two values. 307 308.. code-block:: none 309 310 %5:_(s32) = G_SMIN %6, %2 311 312G_UADDO, G_SADDO, G_USUBO, G_SSUBO, G_SMULO, G_UMULO 313^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 314 315Perform the requested arithmetic and produce a carry output in addition to the 316normal result. 317 318.. code-block:: none 319 320 %3:_(s32), %4:_(s1) = G_UADDO %0, %1 321 322G_UADDE, G_SADDE, G_USUBE, G_SSUBE 323^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 324 325Perform the requested arithmetic and consume a carry input in addition to the 326normal input. Also produce a carry output in addition to the normal result. 327 328.. code-block:: none 329 330 %4:_(s32), %5:_(s1) = G_UADDE %0, %1, %3:_(s1) 331 332G_UMULH, G_SMULH 333^^^^^^^^^^^^^^^^ 334 335Multiply two numbers at twice the incoming bit width (signed) and return 336the high half of the result. 337 338.. code-block:: none 339 340 %3:_(s32) = G_UMULH %0, %1 341 342G_CTLZ, G_CTTZ, G_CTPOP 343^^^^^^^^^^^^^^^^^^^^^^^ 344 345Count leading zeros, trailing zeros, or number of set bits. 346 347.. code-block:: none 348 349 %2:_(s33) = G_CTLZ_ZERO_UNDEF %1 350 %2:_(s33) = G_CTTZ_ZERO_UNDEF %1 351 %2:_(s33) = G_CTPOP %1 352 353G_CTLZ_ZERO_UNDEF, G_CTTZ_ZERO_UNDEF 354^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 355 356Count leading zeros or trailing zeros. If the value is zero then the result is 357undefined. 358 359.. code-block:: none 360 361 %2:_(s33) = G_CTLZ_ZERO_UNDEF %1 362 %2:_(s33) = G_CTTZ_ZERO_UNDEF %1 363 364Floating Point Operations 365------------------------- 366 367G_FCMP 368^^^^^^ 369 370Perform floating point comparison producing non-zero (true) or zero 371(false). It's target specific whether a true value is 1, ~0U, or some other 372non-zero value. 373 374G_FNEG 375^^^^^^ 376 377Floating point negation. 378 379G_FPEXT 380^^^^^^^ 381 382Convert a floating point value to a larger type. 383 384G_FPTRUNC 385^^^^^^^^^ 386 387Convert a floating point value to a narrower type. 388 389G_FPTOSI, G_FPTOUI, G_SITOFP, G_UITOFP 390^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 391 392Convert between integer and floating point. 393 394G_FABS 395^^^^^^ 396 397Take the absolute value of a floating point value. 398 399G_FCOPYSIGN 400^^^^^^^^^^^ 401 402Copy the value of the first operand, replacing the sign bit with that of the 403second operand. 404 405G_FCANONICALIZE 406^^^^^^^^^^^^^^^ 407 408See :ref:`i_intr_llvm_canonicalize`. 409 410G_FMINNUM 411^^^^^^^^^ 412 413Perform floating-point minimum on two values. 414 415In the case where a single input is a NaN (either signaling or quiet), 416the non-NaN input is returned. 417 418The return value of (FMINNUM 0.0, -0.0) could be either 0.0 or -0.0. 419 420G_FMAXNUM 421^^^^^^^^^ 422 423Perform floating-point maximum on two values. 424 425In the case where a single input is a NaN (either signaling or quiet), 426the non-NaN input is returned. 427 428The return value of (FMAXNUM 0.0, -0.0) could be either 0.0 or -0.0. 429 430G_FMINNUM_IEEE 431^^^^^^^^^^^^^^ 432 433Perform floating-point minimum on two values, following the IEEE-754 2008 434definition. This differs from FMINNUM in the handling of signaling NaNs. If one 435input is a signaling NaN, returns a quiet NaN. 436 437G_FMAXNUM_IEEE 438^^^^^^^^^^^^^^ 439 440Perform floating-point maximum on two values, following the IEEE-754 2008 441definition. This differs from FMAXNUM in the handling of signaling NaNs. If one 442input is a signaling NaN, returns a quiet NaN. 443 444G_FMINIMUM 445^^^^^^^^^^ 446 447NaN-propagating minimum that also treat -0.0 as less than 0.0. While 448FMINNUM_IEEE follow IEEE 754-2008 semantics, FMINIMUM follows IEEE 754-2018 449draft semantics. 450 451G_FMAXIMUM 452^^^^^^^^^^ 453 454NaN-propagating maximum that also treat -0.0 as less than 0.0. While 455FMAXNUM_IEEE follow IEEE 754-2008 semantics, FMAXIMUM follows IEEE 754-2018 456draft semantics. 457 458G_FADD, G_FSUB, G_FMUL, G_FDIV, G_FREM 459^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 460 461Perform the specified floating point arithmetic. 462 463G_FMA 464^^^^^ 465 466Perform a fused multiply add (i.e. without the intermediate rounding step). 467 468G_FMAD 469^^^^^^ 470 471Perform a non-fused multiply add (i.e. with the intermediate rounding step). 472 473G_FPOW 474^^^^^^ 475 476Raise the first operand to the power of the second. 477 478G_FEXP, G_FEXP2 479^^^^^^^^^^^^^^^ 480 481Calculate the base-e or base-2 exponential of a value 482 483G_FLOG, G_FLOG2, G_FLOG10 484^^^^^^^^^^^^^^^^^^^^^^^^^ 485 486Calculate the base-e, base-2, or base-10 respectively. 487 488G_FCEIL, G_FCOS, G_FSIN, G_FSQRT, G_FFLOOR, G_FRINT, G_FNEARBYINT 489^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 490 491These correspond to the standard C functions of the same name. 492 493G_INTRINSIC_TRUNC 494^^^^^^^^^^^^^^^^^ 495 496Returns the operand rounded to the nearest integer not larger in magnitude than the operand. 497 498G_INTRINSIC_ROUND 499^^^^^^^^^^^^^^^^^ 500 501Returns the operand rounded to the nearest integer. 502 503Vector Specific Operations 504-------------------------- 505 506G_CONCAT_VECTORS 507^^^^^^^^^^^^^^^^ 508 509Concatenate two vectors to form a longer vector. 510 511G_BUILD_VECTOR, G_BUILD_VECTOR_TRUNC 512^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 513 514Create a vector from multiple scalar registers. No implicit 515conversion is performed (i.e. the result element type must be the 516same as all source operands) 517 518The _TRUNC version truncates the larger operand types to fit the 519destination vector elt type. 520 521G_INSERT_VECTOR_ELT 522^^^^^^^^^^^^^^^^^^^ 523 524Insert an element into a vector 525 526G_EXTRACT_VECTOR_ELT 527^^^^^^^^^^^^^^^^^^^^ 528 529Extract an element from a vector 530 531G_SHUFFLE_VECTOR 532^^^^^^^^^^^^^^^^ 533 534Concatenate two vectors and shuffle the elements according to the mask operand. 535The mask operand should be an IR Constant which exactly matches the 536corresponding mask for the IR shufflevector instruction. 537 538Memory Operations 539----------------- 540 541G_LOAD, G_SEXTLOAD, G_ZEXTLOAD 542^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 543 544Generic load. Expects a MachineMemOperand in addition to explicit 545operands. If the result size is larger than the memory size, the 546high bits are undefined, sign-extended, or zero-extended respectively. 547 548Only G_LOAD is valid if the result is a vector type. If the result is larger 549than the memory size, the high elements are undefined (i.e. this is not a 550per-element, vector anyextload) 551 552G_INDEXED_LOAD 553^^^^^^^^^^^^^^ 554 555Generic indexed load. Combines a GEP with a load. $newaddr is set to $base + $offset. 556If $am is 0 (post-indexed), then the value is loaded from $base; if $am is 1 (pre-indexed) 557then the value is loaded from $newaddr. 558 559G_INDEXED_SEXTLOAD 560^^^^^^^^^^^^^^^^^^ 561 562Same as G_INDEXED_LOAD except that the load performed is sign-extending, as with G_SEXTLOAD. 563 564G_INDEXED_ZEXTLOAD 565^^^^^^^^^^^^^^^^^^ 566 567Same as G_INDEXED_LOAD except that the load performed is zero-extending, as with G_ZEXTLOAD. 568 569G_STORE 570^^^^^^^ 571 572Generic store. Expects a MachineMemOperand in addition to explicit 573operands. If the stored value size is greater than the memory size, 574the high bits are implicitly truncated. If this is a vector store, the 575high elements are discarded (i.e. this does not function as a per-lane 576vector, truncating store) 577 578G_INDEXED_STORE 579^^^^^^^^^^^^^^^ 580 581Combines a store with a GEP. See description of G_INDEXED_LOAD for indexing behaviour. 582 583G_ATOMIC_CMPXCHG_WITH_SUCCESS 584^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 585 586Generic atomic cmpxchg with internal success check. Expects a 587MachineMemOperand in addition to explicit operands. 588 589G_ATOMIC_CMPXCHG 590^^^^^^^^^^^^^^^^ 591 592Generic atomic cmpxchg. Expects a MachineMemOperand in addition to explicit 593operands. 594 595G_ATOMICRMW_XCHG, G_ATOMICRMW_ADD, G_ATOMICRMW_SUB, G_ATOMICRMW_AND, G_ATOMICRMW_NAND, G_ATOMICRMW_OR, G_ATOMICRMW_XOR, G_ATOMICRMW_MAX, G_ATOMICRMW_MIN, G_ATOMICRMW_UMAX, G_ATOMICRMW_UMIN, G_ATOMICRMW_FADD, G_ATOMICRMW_FSUB 596^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 597 598Generic atomicrmw. Expects a MachineMemOperand in addition to explicit 599operands. 600 601G_FENCE 602^^^^^^^ 603 604.. caution:: 605 606 I couldn't find any documentation on this at the time of writing. 607 608Control Flow 609------------ 610 611G_PHI 612^^^^^ 613 614Implement the φ node in the SSA graph representing the function. 615 616.. code-block:: none 617 618 %1(s8) = G_PHI %7(s8), %bb.0, %3(s8), %bb.1 619 620G_BR 621^^^^ 622 623Unconditional branch 624 625G_BRCOND 626^^^^^^^^ 627 628Conditional branch 629 630G_BRINDIRECT 631^^^^^^^^^^^^ 632 633Indirect branch 634 635G_BRJT 636^^^^^^ 637 638Indirect branch to jump table entry 639 640G_JUMP_TABLE 641^^^^^^^^^^^^ 642 643.. caution:: 644 645 I found no documentation for this instruction at the time of writing. 646 647G_INTRINSIC, G_INTRINSIC_W_SIDE_EFFECTS 648^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 649 650Call an intrinsic 651 652The _W_SIDE_EFFECTS version is considered to have unknown side-effects and 653as such cannot be reordered across other side-effecting instructions. 654 655.. note:: 656 657 Unlike SelectionDAG, there is no _VOID variant. Both of these are permitted 658 to have zero, one, or multiple results. 659 660Variadic Arguments 661------------------ 662 663G_VASTART 664^^^^^^^^^ 665 666.. caution:: 667 668 I found no documentation for this instruction at the time of writing. 669 670G_VAARG 671^^^^^^^ 672 673.. caution:: 674 675 I found no documentation for this instruction at the time of writing. 676 677Other Operations 678---------------- 679 680G_DYN_STACKALLOC 681^^^^^^^^^^^^^^^^ 682 683Dynamically realigns the stack pointer to the specified size and alignment. 684An alignment value of `0` or `1` mean no specific alignment. 685 686.. code-block:: none 687 688 %8:_(p0) = G_DYN_STACKALLOC %7(s64), 32 689