llvm/docs/GlobalISel/GenericOpcode.rst

   1
   2 .. _gmir-opcodes:
   3
   4 Generic 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
  15 Constants
  16 ---------
  17
  18 G_IMPLICIT_DEF
  19 ^^^^^^^^^^^^^^
  20
  21 An undefined value.
  22
  23 .. code-block:: none
  24
  25   %0:_(s32) = G_IMPLICIT_DEF
  26
  27 G_CONSTANT
  28 ^^^^^^^^^^
  29
  30 An integer constant.
  31
  32 .. code-block:: none
  33
  34   %0:_(s32) = G_CONSTANT i32 1
  35
  36 G_FCONSTANT
  37 ^^^^^^^^^^^
  38
  39 A floating point constant.
  40
  41 .. code-block:: none
  42
  43   %0:_(s32) = G_FCONSTANT float 1.0
  44
  45 G_FRAME_INDEX
  46 ^^^^^^^^^^^^^
  47
  48 The address of an object in the stack frame.
  49
  50 .. code-block:: none
  51
  52   %1:_(p0) = G_FRAME_INDEX %stack.0.ptr0
  53
  54 G_GLOBAL_VALUE
  55 ^^^^^^^^^^^^^^
  56
  57 The address of a global value.
  58
  59 .. code-block:: none
  60
  61   %0(p0) = G_GLOBAL_VALUE @var_local
  62
  63 G_BLOCK_ADDR
  64 ^^^^^^^^^^^^
  65
  66 The address of a basic block.
  67
  68 .. code-block:: none
  69
  70   %0:_(p0) = G_BLOCK_ADDR blockaddress(@test_blockaddress, %ir-block.block)
  71
  72 G_CONSTANT_POOL
  73 ^^^^^^^^^^^^^^^
  74
  75 The address of an object in the constant pool.
  76
  77 .. code-block:: none
  78
  79   %0:_(p0) = G_CONSTANT_POOL %const.0
  80
  81 Integer Extension and Truncation
  82 --------------------------------
  83
  84 G_ANYEXT
  85 ^^^^^^^^
  86
  87 Extend the underlying scalar type of an operation, leaving the high bits
  88 unspecified.
  89
  90 .. code-block:: none
  91
  92   %1:_(s32) = G_ANYEXT %0:_(s16)
  93
  94 G_SEXT
  95 ^^^^^^
  96
  97 Sign extend the underlying scalar type of an operation, copying the sign bit
  98 into the newly-created space.
  99
 100 .. code-block:: none
 101
 102   %1:_(s32) = G_SEXT %0:_(s16)
 103
 104 G_SEXT_INREG
 105 ^^^^^^^^^^^^
 106
 107 Sign extend the value from an arbitrary bit position, copying the sign bit
 108 into all bits above it. This is equivalent to a shl + ashr pair with an
 109 appropriate shift amount. $sz is an immediate (MachineOperand::isImm()
 110 returns true) to allow targets to have some bitwidths legal and others
 111 lowered. This opcode is particularly useful if the target has sign-extension
 112 instructions that are cheaper than the constituent shifts as the optimizer is
 113 able to make decisions on whether it's better to hang on to the G_SEXT_INREG
 114 or to lower it and optimize the individual shifts.
 115
 116 .. code-block:: none
 117
 118   %1:_(s32) = G_SEXT_INREG %0:_(s32), 16
 119
 120 G_ZEXT
 121 ^^^^^^
 122
 123 Zero extend the underlying scalar type of an operation, putting zero bits
 124 into the newly-created space.
 125
 126 .. code-block:: none
 127
 128   %1:_(s32) = G_ZEXT %0:_(s16)
 129
 130 G_TRUNC
 131 ^^^^^^^
 132
 133 Truncate the underlying scalar type of an operation. This is equivalent to
 134 G_EXTRACT for scalar types, but acts elementwise on vectors.
 135
 136 .. code-block:: none
 137
 138   %1:_(s16) = G_TRUNC %0:_(s32)
 139
 140 Type Conversions
 141 ----------------
 142
 143 G_INTTOPTR
 144 ^^^^^^^^^^
 145
 146 Convert an integer to a pointer.
 147
 148 .. code-block:: none
 149
 150   %1:_(p0) = G_INTTOPTR %0:_(s32)
 151
 152 G_PTRTOINT
 153 ^^^^^^^^^^
 154
 155 Convert a pointer to an integer.
 156
 157 .. code-block:: none
 158
 159   %1:_(s32) = G_PTRTOINT %0:_(p0)
 160
 161 G_BITCAST
 162 ^^^^^^^^^
 163
 164 Reinterpret a value as a new type. This is usually done without
 165 changing any bits but this is not always the case due a subtlety in the
 166 definition of the :ref:`LLVM-IR Bitcast Instruction <i_bitcast>`. It
 167 is allowed to bitcast between pointers with the same size, but
 168 different address spaces.
 169
 170 .. code-block:: none
 171
 172   %1:_(s64) = G_BITCAST %0:_(<2 x s32>)
 173
 174 G_ADDRSPACE_CAST
 175 ^^^^^^^^^^^^^^^^
 176
 177 Convert a pointer to an address space to a pointer to another address space.
 178
 179 .. code-block:: none
 180
 181   %1:_(p1) = G_ADDRSPACE_CAST %0:_(p0)
 182
 183 .. caution::
 184
 185   :ref:`i_addrspacecast` doesn't mention what happens if the cast is simply
 186   invalid (i.e. if the address spaces are disjoint).
 187
 188 Scalar Operations
 189 -----------------
 190
 191 G_EXTRACT
 192 ^^^^^^^^^
 193
 194 Extract a register of the specified size, starting from the block given by
 195 index. This will almost certainly be mapped to sub-register COPYs after
 196 register banks have been selected.
 197
 198 .. code-block:: none
 199
 200   %3:_(s32) = G_EXTRACT %2:_(s64), 32
 201
 202 G_INSERT
 203 ^^^^^^^^
 204
 205 Insert a smaller register into a larger one at the specified bit-index.
 206
 207 .. code-block:: none
 208
 209   %2:_(s64) = G_INSERT %0:(_s64), %1:_(s32), 0
 210
 211 G_MERGE_VALUES
 212 ^^^^^^^^^^^^^^
 213
 214 Concatenate multiple registers of the same size into a wider register.
 215 The input operands are always ordered from lowest bits to highest:
 216
 217 .. code-block:: none
 218
 219   %0:(s32) = G_MERGE_VALUES %bits_0_7:(s8), %bits_8_15:(s8),
 220                             %bits_16_23:(s8), %bits_24_31:(s8)
 221
 222 G_UNMERGE_VALUES
 223 ^^^^^^^^^^^^^^^^
 224
 225 Extract multiple registers of the specified size, starting from blocks given by
 226 indexes. This will almost certainly be mapped to sub-register COPYs after
 227 register banks have been selected.
 228 The output operands are always ordered from lowest bits to highest:
 229
 230 .. code-block:: none
 231
 232   %bits_0_7:(s8), %bits_8_15:(s8),
 233       %bits_16_23:(s8), %bits_24_31:(s8) = G_UNMERGE_VALUES %0:(s32)
 234
 235 G_BSWAP
 236 ^^^^^^^
 237
 238 Reverse the order of the bytes in a scalar.
 239
 240 .. code-block:: none
 241
 242   %1:_(s32) = G_BSWAP %0:_(s32)
 243
 244 G_BITREVERSE
 245 ^^^^^^^^^^^^
 246
 247 Reverse the order of the bits in a scalar.
 248
 249 .. code-block:: none
 250
 251   %1:_(s32) = G_BITREVERSE %0:_(s32)
 252
 253 G_SBFX, G_UBFX
 254 ^^^^^^^^^^^^^^
 255
 256 Extract a range of bits from a register.
 257
 258 The source operands are registers as follows:
 259
 260 - Source
 261 - The least-significant bit for the extraction
 262 - The width of the extraction
 263
 264 The least-significant bit (lsb) and width operands are in the range:
 265
 266 ::
 267
 268       0 <= lsb < lsb + width <= source bitwidth, where all values are unsigned
 269
 270 G_SBFX sign-extends the result, while G_UBFX zero-extends the result.
 271
 272 .. code-block:: none
 273
 274   ; Extract 5 bits starting at bit 1 from %x and store them in %a.
 275   ; Sign-extend the result.
 276   ;
 277   ; Example:
 278   ; %x = 0...0000[10110]1 ---> %a = 1...111111[10110]
 279   %lsb_one = G_CONSTANT i32 1
 280   %width_five = G_CONSTANT i32 5
 281   %a:_(s32) = G_SBFX %x, %lsb_one, %width_five
 282
 283   ; Extract 3 bits starting at bit 2 from %x and store them in %b. Zero-extend
 284   ; the result.
 285   ;
 286   ; Example:
 287   ; %x = 1...11111[100]11 ---> %b = 0...00000[100]
 288   %lsb_two = G_CONSTANT i32 2
 289   %width_three = G_CONSTANT i32 3
 290   %b:_(s32) = G_UBFX %x, %lsb_two, %width_three
 291
 292 Integer Operations
 293 -------------------
 294
 295 G_ADD, G_SUB, G_MUL, G_AND, G_OR, G_XOR, G_SDIV, G_UDIV, G_SREM, G_UREM
 296 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 297
 298 These each perform their respective integer arithmetic on a scalar.
 299
 300 .. code-block:: none
 301
 302   %dst:_(s32) = G_ADD %src0:_(s32), %src1:_(s32)
 303
 304 The above example adds %src1 to %src0 and stores the result in %dst.
 305
 306 G_SDIVREM, G_UDIVREM
 307 ^^^^^^^^^^^^^^^^^^^^
 308
 309 Perform integer division and remainder thereby producing two results.
 310
 311 .. code-block:: none
 312
 313   %div:_(s32), %rem:_(s32) = G_SDIVREM %0:_(s32), %1:_(s32)
 314
 315 G_SADDSAT, G_UADDSAT, G_SSUBSAT, G_USUBSAT, G_SSHLSAT, G_USHLSAT
 316 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 317
 318 Signed and unsigned addition, subtraction and left shift with saturation.
 319
 320 .. code-block:: none
 321
 322   %2:_(s32) = G_SADDSAT %0:_(s32), %1:_(s32)
 323
 324 G_SHL, G_LSHR, G_ASHR
 325 ^^^^^^^^^^^^^^^^^^^^^
 326
 327 Shift the bits of a scalar left or right inserting zeros (sign-bit for G_ASHR).
 328
 329 G_ROTR, G_ROTL
 330 ^^^^^^^^^^^^^^
 331
 332 Rotate the bits right (G_ROTR) or left (G_ROTL).
 333
 334 G_ICMP
 335 ^^^^^^
 336
 337 Perform integer comparison producing non-zero (true) or zero (false). It's
 338 target specific whether a true value is 1, ~0U, or some other non-zero value.
 339
 340 G_SELECT
 341 ^^^^^^^^
 342
 343 Select between two values depending on a zero/non-zero value.
 344
 345 .. code-block:: none
 346
 347   %5:_(s32) = G_SELECT %4(s1), %6, %2
 348
 349 G_PTR_ADD
 350 ^^^^^^^^^
 351
 352 Add a scalar offset in addressible units to a pointer. Addressible units are
 353 typically bytes but this may vary between targets.
 354
 355 .. code-block:: none
 356
 357   %1:_(p0) = G_PTR_ADD %0:_(p0), %1:_(s32)
 358
 359 .. caution::
 360
 361   There are currently no in-tree targets that use this with addressable units
 362   not equal to 8 bit.
 363
 364 G_PTRMASK
 365 ^^^^^^^^^^
 366
 367 Zero out an arbitrary mask of bits of a pointer. The mask type must be
 368 an integer, and the number of vector elements must match for all
 369 operands. This corresponds to `i_intr_llvm_ptrmask`.
 370
 371 .. code-block:: none
 372
 373   %2:_(p0) = G_PTRMASK %0, %1
 374
 375 G_SMIN, G_SMAX, G_UMIN, G_UMAX
 376 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 377
 378 Take the minimum/maximum of two values.
 379
 380 .. code-block:: none
 381
 382   %5:_(s32) = G_SMIN %6, %2
 383
 384 G_ABS
 385 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 386
 387 Take the absolute value of a signed integer. The absolute value of the minimum
 388 negative value (e.g. the 8-bit value `0x80`) is defined to be itself.
 389
 390 .. code-block:: none
 391
 392   %1:_(s32) = G_ABS %0
 393
 394 G_UADDO, G_SADDO, G_USUBO, G_SSUBO, G_SMULO, G_UMULO
 395 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 396
 397 Perform the requested arithmetic and produce a carry output in addition to the
 398 normal result.
 399
 400 .. code-block:: none
 401
 402   %3:_(s32), %4:_(s1) = G_UADDO %0, %1
 403
 404 G_UADDE, G_SADDE, G_USUBE, G_SSUBE
 405 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 406
 407 Perform the requested arithmetic and consume a carry input in addition to the
 408 normal input. Also produce a carry output in addition to the normal result.
 409
 410 .. code-block:: none
 411
 412   %4:_(s32), %5:_(s1) = G_UADDE %0, %1, %3:_(s1)
 413
 414 G_UMULH, G_SMULH
 415 ^^^^^^^^^^^^^^^^
 416
 417 Multiply two numbers at twice the incoming bit width (unsigned or signed) and
 418 return the high half of the result.
 419
 420 .. code-block:: none
 421
 422   %3:_(s32) = G_UMULH %0, %1
 423
 424 G_CTLZ, G_CTTZ, G_CTPOP
 425 ^^^^^^^^^^^^^^^^^^^^^^^
 426
 427 Count leading zeros, trailing zeros, or number of set bits.
 428
 429 .. code-block:: none
 430
 431   %2:_(s33) = G_CTLZ_ZERO_UNDEF %1
 432   %2:_(s33) = G_CTTZ_ZERO_UNDEF %1
 433   %2:_(s33) = G_CTPOP %1
 434
 435 G_CTLZ_ZERO_UNDEF, G_CTTZ_ZERO_UNDEF
 436 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 437
 438 Count leading zeros or trailing zeros. If the value is zero then the result is
 439 undefined.
 440
 441 .. code-block:: none
 442
 443   %2:_(s33) = G_CTLZ_ZERO_UNDEF %1
 444   %2:_(s33) = G_CTTZ_ZERO_UNDEF %1
 445
 446 Floating Point Operations
 447 -------------------------
 448
 449 G_FCMP
 450 ^^^^^^
 451
 452 Perform floating point comparison producing non-zero (true) or zero
 453 (false). It's target specific whether a true value is 1, ~0U, or some other
 454 non-zero value.
 455
 456 G_FNEG
 457 ^^^^^^
 458
 459 Floating point negation.
 460
 461 G_FPEXT
 462 ^^^^^^^
 463
 464 Convert a floating point value to a larger type.
 465
 466 G_FPTRUNC
 467 ^^^^^^^^^
 468
 469 Convert a floating point value to a narrower type.
 470
 471 G_FPTOSI, G_FPTOUI, G_SITOFP, G_UITOFP
 472 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 473
 474 Convert between integer and floating point.
 475
 476 G_FABS
 477 ^^^^^^
 478
 479 Take the absolute value of a floating point value.
 480
 481 G_FCOPYSIGN
 482 ^^^^^^^^^^^
 483
 484 Copy the value of the first operand, replacing the sign bit with that of the
 485 second operand.
 486
 487 G_FCANONICALIZE
 488 ^^^^^^^^^^^^^^^
 489
 490 See :ref:`i_intr_llvm_canonicalize`.
 491
 492 G_IS_FPCLASS
 493 ^^^^^^^^^^^^
 494
 495 Tests if the first operand, which must be floating-point scalar or vector, has
 496 floating-point class specified by the second operand. Returns non-zero (true)
 497 or zero (false). It's target specific whether a true value is 1, ~0U, or some
 498 other non-zero value. If the first operand is a vector, the returned value is a
 499 vector of the same length.
 500
 501 G_FMINNUM
 502 ^^^^^^^^^
 503
 504 Perform floating-point minimum on two values.
 505
 506 In the case where a single input is a NaN (either signaling or quiet),
 507 the non-NaN input is returned.
 508
 509 The return value of (FMINNUM 0.0, -0.0) could be either 0.0 or -0.0.
 510
 511 G_FMAXNUM
 512 ^^^^^^^^^
 513
 514 Perform floating-point maximum on two values.
 515
 516 In the case where a single input is a NaN (either signaling or quiet),
 517 the non-NaN input is returned.
 518
 519 The return value of (FMAXNUM 0.0, -0.0) could be either 0.0 or -0.0.
 520
 521 G_FMINNUM_IEEE
 522 ^^^^^^^^^^^^^^
 523
 524 Perform floating-point minimum on two values, following the IEEE-754 2008
 525 definition. This differs from FMINNUM in the handling of signaling NaNs. If one
 526 input is a signaling NaN, returns a quiet NaN.
 527
 528 G_FMAXNUM_IEEE
 529 ^^^^^^^^^^^^^^
 530
 531 Perform floating-point maximum on two values, following the IEEE-754 2008
 532 definition. This differs from FMAXNUM in the handling of signaling NaNs. If one
 533 input is a signaling NaN, returns a quiet NaN.
 534
 535 G_FMINIMUM
 536 ^^^^^^^^^^
 537
 538 NaN-propagating minimum that also treat -0.0 as less than 0.0. While
 539 FMINNUM_IEEE follow IEEE 754-2008 semantics, FMINIMUM follows IEEE 754-2018
 540 draft semantics.
 541
 542 G_FMAXIMUM
 543 ^^^^^^^^^^
 544
 545 NaN-propagating maximum that also treat -0.0 as less than 0.0. While
 546 FMAXNUM_IEEE follow IEEE 754-2008 semantics, FMAXIMUM follows IEEE 754-2018
 547 draft semantics.
 548
 549 G_FADD, G_FSUB, G_FMUL, G_FDIV, G_FREM
 550 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 551
 552 Perform the specified floating point arithmetic.
 553
 554 G_FMA
 555 ^^^^^
 556
 557 Perform a fused multiply add (i.e. without the intermediate rounding step).
 558
 559 G_FMAD
 560 ^^^^^^
 561
 562 Perform a non-fused multiply add (i.e. with the intermediate rounding step).
 563
 564 G_FPOW
 565 ^^^^^^
 566
 567 Raise the first operand to the power of the second.
 568
 569 G_FEXP, G_FEXP2
 570 ^^^^^^^^^^^^^^^
 571
 572 Calculate the base-e or base-2 exponential of a value
 573
 574 G_FLOG, G_FLOG2, G_FLOG10
 575 ^^^^^^^^^^^^^^^^^^^^^^^^^
 576
 577 Calculate the base-e, base-2, or base-10 respectively.
 578
 579 G_FCEIL, G_FCOS, G_FSIN, G_FSQRT, G_FFLOOR, G_FRINT, G_FNEARBYINT
 580 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 581
 582 These correspond to the standard C functions of the same name.
 583
 584 G_INTRINSIC_TRUNC
 585 ^^^^^^^^^^^^^^^^^
 586
 587 Returns the operand rounded to the nearest integer not larger in magnitude than the operand.
 588
 589 G_INTRINSIC_ROUND
 590 ^^^^^^^^^^^^^^^^^
 591
 592 Returns the operand rounded to the nearest integer.
 593
 594 G_LROUND, G_LLROUND
 595 ^^^^^^^^^^^^^^^^^^^
 596
 597 Returns the source operand rounded to the nearest integer with ties away from
 598 zero.
 599
 600 See the LLVM LangRef entry on '``llvm.lround.*'`` for details on behaviour.
 601
 602 .. code-block:: none
 603
 604   %rounded_32:_(s32) = G_LROUND %round_me:_(s64)
 605   %rounded_64:_(s64) = G_LLROUND %round_me:_(s64)
 606
 607 Vector Specific Operations
 608 --------------------------
 609
 610 G_CONCAT_VECTORS
 611 ^^^^^^^^^^^^^^^^
 612
 613 Concatenate two vectors to form a longer vector.
 614
 615 G_BUILD_VECTOR, G_BUILD_VECTOR_TRUNC
 616 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 617
 618 Create a vector from multiple scalar registers. No implicit
 619 conversion is performed (i.e. the result element type must be the
 620 same as all source operands)
 621
 622 The _TRUNC version truncates the larger operand types to fit the
 623 destination vector elt type.
 624
 625 G_INSERT_VECTOR_ELT
 626 ^^^^^^^^^^^^^^^^^^^
 627
 628 Insert an element into a vector
 629
 630 G_EXTRACT_VECTOR_ELT
 631 ^^^^^^^^^^^^^^^^^^^^
 632
 633 Extract an element from a vector
 634
 635 G_SHUFFLE_VECTOR
 636 ^^^^^^^^^^^^^^^^
 637
 638 Concatenate two vectors and shuffle the elements according to the mask operand.
 639 The mask operand should be an IR Constant which exactly matches the
 640 corresponding mask for the IR shufflevector instruction.
 641
 642 Vector Reduction Operations
 643 ---------------------------
 644
 645 These operations represent horizontal vector reduction, producing a scalar result.
 646
 647 G_VECREDUCE_SEQ_FADD, G_VECREDUCE_SEQ_FMUL
 648 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 649
 650 The SEQ variants perform reductions in sequential order. The first operand is
 651 an initial scalar accumulator value, and the second operand is the vector to reduce.
 652
 653 G_VECREDUCE_FADD, G_VECREDUCE_FMUL
 654 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 655
 656 These reductions are relaxed variants which may reduce the elements in any order.
 657
 658 G_VECREDUCE_FMAX, G_VECREDUCE_FMIN, G_VECREDUCE_FMAXIMUM, G_VECREDUCE_FMINIMUM
 659 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 660
 661 FMIN/FMAX/FMINIMUM/FMAXIMUM nodes can have flags, for NaN/NoNaN variants.
 662
 663
 664 Integer/bitwise reductions
 665 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 666
 667 * G_VECREDUCE_ADD
 668 * G_VECREDUCE_MUL
 669 * G_VECREDUCE_AND
 670 * G_VECREDUCE_OR
 671 * G_VECREDUCE_XOR
 672 * G_VECREDUCE_SMAX
 673 * G_VECREDUCE_SMIN
 674 * G_VECREDUCE_UMAX
 675 * G_VECREDUCE_UMIN
 676
 677 Integer reductions may have a result type larger than the vector element type.
 678 However, the reduction is performed using the vector element type and the value
 679 in the top bits is unspecified.
 680
 681 Memory Operations
 682 -----------------
 683
 684 G_LOAD, G_SEXTLOAD, G_ZEXTLOAD
 685 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 686
 687 Generic load. Expects a MachineMemOperand in addition to explicit
 688 operands. If the result size is larger than the memory size, the
 689 high bits are undefined, sign-extended, or zero-extended respectively.
 690
 691 Only G_LOAD is valid if the result is a vector type. If the result is larger
 692 than the memory size, the high elements are undefined (i.e. this is not a
 693 per-element, vector anyextload)
 694
 695 Unlike in SelectionDAG, atomic loads are expressed with the same
 696 opcodes as regular loads. G_LOAD, G_SEXTLOAD and G_ZEXTLOAD may all
 697 have atomic memory operands.
 698
 699 G_INDEXED_LOAD
 700 ^^^^^^^^^^^^^^
 701
 702 Generic indexed load. Combines a GEP with a load. $newaddr is set to $base + $offset.
 703 If $am is 0 (post-indexed), then the value is loaded from $base; if $am is 1 (pre-indexed)
 704 then the value is loaded from $newaddr.
 705
 706 G_INDEXED_SEXTLOAD
 707 ^^^^^^^^^^^^^^^^^^
 708
 709 Same as G_INDEXED_LOAD except that the load performed is sign-extending, as with G_SEXTLOAD.
 710
 711 G_INDEXED_ZEXTLOAD
 712 ^^^^^^^^^^^^^^^^^^
 713
 714 Same as G_INDEXED_LOAD except that the load performed is zero-extending, as with G_ZEXTLOAD.
 715
 716 G_STORE
 717 ^^^^^^^
 718
 719 Generic store. Expects a MachineMemOperand in addition to explicit
 720 operands. If the stored value size is greater than the memory size,
 721 the high bits are implicitly truncated. If this is a vector store, the
 722 high elements are discarded (i.e. this does not function as a per-lane
 723 vector, truncating store)
 724
 725 G_INDEXED_STORE
 726 ^^^^^^^^^^^^^^^
 727
 728 Combines a store with a GEP. See description of G_INDEXED_LOAD for indexing behaviour.
 729
 730 G_ATOMIC_CMPXCHG_WITH_SUCCESS
 731 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 732
 733 Generic atomic cmpxchg with internal success check. Expects a
 734 MachineMemOperand in addition to explicit operands.
 735
 736 G_ATOMIC_CMPXCHG
 737 ^^^^^^^^^^^^^^^^
 738
 739 Generic atomic cmpxchg. Expects a MachineMemOperand in addition to explicit
 740 operands.
 741
 742 G_ATOMICRMW_XCHG, G_ATOMICRMW_ADD, G_ATOMICRMW_SUB, G_ATOMICRMW_AND,
 743 G_ATOMICRMW_NAND, G_ATOMICRMW_OR, G_ATOMICRMW_XOR, G_ATOMICRMW_MAX,
 744 G_ATOMICRMW_MIN, G_ATOMICRMW_UMAX, G_ATOMICRMW_UMIN, G_ATOMICRMW_FADD,
 745 G_ATOMICRMW_FSUB, G_ATOMICRMW_FMAX, G_ATOMICRMW_FMIN
 746 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 747
 748 Generic atomicrmw. Expects a MachineMemOperand in addition to explicit
 749 operands.
 750
 751 G_FENCE
 752 ^^^^^^^
 753
 754 Generic fence. The first operand is the memory ordering. The second operand is
 755 the syncscope.
 756
 757 See the LLVM LangRef entry on the '``fence'`` instruction for more details.
 758
 759 G_MEMCPY
 760 ^^^^^^^^
 761
 762 Generic memcpy. Expects two MachineMemOperands covering the store and load
 763 respectively, in addition to explicit operands.
 764
 765 G_MEMCPY_INLINE
 766 ^^^^^^^^^^^^^^^
 767
 768 Generic inlined memcpy. Like G_MEMCPY, but it is guaranteed that this version
 769 will not be lowered as a call to an external function. Currently the size
 770 operand is required to evaluate as a constant (not an immediate), though that is
 771 expected to change when llvm.memcpy.inline is taught to support dynamic sizes.
 772
 773 G_MEMMOVE
 774 ^^^^^^^^^
 775
 776 Generic memmove. Similar to G_MEMCPY, but the source and destination memory
 777 ranges are allowed to overlap.
 778
 779 G_MEMSET
 780 ^^^^^^^^
 781
 782 Generic memset. Expects a MachineMemOperand in addition to explicit operands.
 783
 784 G_BZERO
 785 ^^^^^^^
 786
 787 Generic bzero. Expects a MachineMemOperand in addition to explicit operands.
 788
 789 Control Flow
 790 ------------
 791
 792 G_PHI
 793 ^^^^^
 794
 795 Implement the φ node in the SSA graph representing the function.
 796
 797 .. code-block:: none
 798
 799   %dst(s8) = G_PHI %src1(s8), %bb.<id1>, %src2(s8), %bb.<id2>
 800
 801 G_BR
 802 ^^^^
 803
 804 Unconditional branch
 805
 806 .. code-block:: none
 807
 808   G_BR %bb.<id>
 809
 810 G_BRCOND
 811 ^^^^^^^^
 812
 813 Conditional branch
 814
 815 .. code-block:: none
 816
 817   G_BRCOND %condition, %basicblock.<id>
 818
 819 G_BRINDIRECT
 820 ^^^^^^^^^^^^
 821
 822 Indirect branch
 823
 824 .. code-block:: none
 825
 826   G_BRINDIRECT %src(p0)
 827
 828 G_BRJT
 829 ^^^^^^
 830
 831 Indirect branch to jump table entry
 832
 833 .. code-block:: none
 834
 835   G_BRJT %ptr(p0), %jti, %idx(s64)
 836
 837 G_JUMP_TABLE
 838 ^^^^^^^^^^^^
 839
 840 Generates a pointer to the address of the jump table specified by the source
 841 operand. The source operand is a jump table index.
 842 G_JUMP_TABLE can be used in conjunction with G_BRJT to support jump table
 843 codegen with GlobalISel.
 844
 845 .. code-block:: none
 846
 847   %dst:_(p0) = G_JUMP_TABLE %jump-table.0
 848
 849 The above example generates a pointer to the source jump table index.
 850
 851 G_INVOKE_REGION_START
 852 ^^^^^^^^^^^^^^^^^^^^^
 853
 854 A marker instruction that acts as a pseudo-terminator for regions of code that may
 855 throw exceptions. Being a terminator, it prevents code from being inserted after
 856 it during passes like legalization. This is needed because calls to exception
 857 throw routines do not return, so no code that must be on an executable path must
 858 be placed after throwing.
 859
 860 G_INTRINSIC, G_INTRINSIC_CONVERGENT
 861 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 862
 863 Call an intrinsic that has no side-effects.
 864
 865 The _CONVERGENT variant corresponds to an LLVM IR intrinsic marked `convergent`.
 866
 867 .. note::
 868
 869   Unlike SelectionDAG, there is no _VOID variant. Both of these are permitted
 870   to have zero, one, or multiple results.
 871
 872 G_INTRINSIC_W_SIDE_EFFECTS, G_INTRINSIC_CONVERGENT_W_SIDE_EFFECTS
 873 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 874
 875 Call an intrinsic that is considered to have unknown side-effects and as such
 876 cannot be reordered across other side-effecting instructions.
 877
 878 The _CONVERGENT variant corresponds to an LLVM IR intrinsic marked `convergent`.
 879
 880 .. note::
 881
 882   Unlike SelectionDAG, there is no _VOID variant. Both of these are permitted
 883   to have zero, one, or multiple results.
 884
 885 Variadic Arguments
 886 ------------------
 887
 888 G_VASTART
 889 ^^^^^^^^^
 890
 891 .. caution::
 892
 893   I found no documentation for this instruction at the time of writing.
 894
 895 G_VAARG
 896 ^^^^^^^
 897
 898 .. caution::
 899
 900   I found no documentation for this instruction at the time of writing.
 901
 902 Other Operations
 903 ----------------
 904
 905 G_DYN_STACKALLOC
 906 ^^^^^^^^^^^^^^^^
 907
 908 Dynamically realigns the stack pointer to the specified size and alignment.
 909 An alignment value of `0` or `1` means no specific alignment.
 910
 911 .. code-block:: none
 912
 913   %8:_(p0) = G_DYN_STACKALLOC %7(s64), 32
 914
 915 Optimization Hints
 916 ------------------
 917
 918 These instructions do not correspond to any target instructions. They act as
 919 hints for various combines.
 920
 921 G_ASSERT_SEXT, G_ASSERT_ZEXT
 922 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 923
 924 This signifies that the contents of a register were previously extended from a
 925 smaller type.
 926
 927 The smaller type is denoted using an immediate operand. For scalars, this is the
 928 width of the entire smaller type. For vectors, this is the width of the smaller
 929 element type.
 930
 931 .. code-block:: none
 932
 933   %x_was_zexted:_(s32) = G_ASSERT_ZEXT %x(s32), 16
 934   %y_was_zexted:_(<2 x s32>) = G_ASSERT_ZEXT %y(<2 x s32>), 16
 935
 936   %z_was_sexted:_(s32) = G_ASSERT_SEXT %z(s32), 8
 937
 938 G_ASSERT_SEXT and G_ASSERT_ZEXT act like copies, albeit with some restrictions.
 939
 940 The source and destination registers must
 941
 942 - Be virtual
 943 - Belong to the same register class
 944 - Belong to the same register bank
 945
 946 It should always be safe to
 947
 948 - Look through the source register
 949 - Replace the destination register with the source register
 950
 951
 952 Miscellaneous
 953 -------------
 954
 955 G_CONSTANT_FOLD_BARRIER
 956 ^^^^^^^^^^^^^^^^^^^^^^^
 957
 958 This operation is used as an opaque barrier to prevent constant folding. Combines
 959 and other transformations should not look through this. These have no other
 960 semantics and can be safely eliminated if a target chooses.