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 subtlety 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, G_SSHLSAT, G_USHLSAT 249^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 250 251Signed and unsigned addition, subtraction and left shift 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_ABS 313^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 314 315Take the absolute value of a signed integer. The absolute value of the minimum 316negative value (e.g. the 8-bit value `0x80`) is defined to be itself. 317 318.. code-block:: none 319 320 %1:_(s32) = G_ABS %0 321 322G_UADDO, G_SADDO, G_USUBO, G_SSUBO, G_SMULO, G_UMULO 323^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 324 325Perform the requested arithmetic and produce a carry output in addition to the 326normal result. 327 328.. code-block:: none 329 330 %3:_(s32), %4:_(s1) = G_UADDO %0, %1 331 332G_UADDE, G_SADDE, G_USUBE, G_SSUBE 333^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 334 335Perform the requested arithmetic and consume a carry input in addition to the 336normal input. Also produce a carry output in addition to the normal result. 337 338.. code-block:: none 339 340 %4:_(s32), %5:_(s1) = G_UADDE %0, %1, %3:_(s1) 341 342G_UMULH, G_SMULH 343^^^^^^^^^^^^^^^^ 344 345Multiply two numbers at twice the incoming bit width (signed) and return 346the high half of the result. 347 348.. code-block:: none 349 350 %3:_(s32) = G_UMULH %0, %1 351 352G_CTLZ, G_CTTZ, G_CTPOP 353^^^^^^^^^^^^^^^^^^^^^^^ 354 355Count leading zeros, trailing zeros, or number of set bits. 356 357.. code-block:: none 358 359 %2:_(s33) = G_CTLZ_ZERO_UNDEF %1 360 %2:_(s33) = G_CTTZ_ZERO_UNDEF %1 361 %2:_(s33) = G_CTPOP %1 362 363G_CTLZ_ZERO_UNDEF, G_CTTZ_ZERO_UNDEF 364^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 365 366Count leading zeros or trailing zeros. If the value is zero then the result is 367undefined. 368 369.. code-block:: none 370 371 %2:_(s33) = G_CTLZ_ZERO_UNDEF %1 372 %2:_(s33) = G_CTTZ_ZERO_UNDEF %1 373 374Floating Point Operations 375------------------------- 376 377G_FCMP 378^^^^^^ 379 380Perform floating point comparison producing non-zero (true) or zero 381(false). It's target specific whether a true value is 1, ~0U, or some other 382non-zero value. 383 384G_FNEG 385^^^^^^ 386 387Floating point negation. 388 389G_FPEXT 390^^^^^^^ 391 392Convert a floating point value to a larger type. 393 394G_FPTRUNC 395^^^^^^^^^ 396 397Convert a floating point value to a narrower type. 398 399G_FPTOSI, G_FPTOUI, G_SITOFP, G_UITOFP 400^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 401 402Convert between integer and floating point. 403 404G_FABS 405^^^^^^ 406 407Take the absolute value of a floating point value. 408 409G_FCOPYSIGN 410^^^^^^^^^^^ 411 412Copy the value of the first operand, replacing the sign bit with that of the 413second operand. 414 415G_FCANONICALIZE 416^^^^^^^^^^^^^^^ 417 418See :ref:`i_intr_llvm_canonicalize`. 419 420G_FMINNUM 421^^^^^^^^^ 422 423Perform floating-point minimum 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 (FMINNUM 0.0, -0.0) could be either 0.0 or -0.0. 429 430G_FMAXNUM 431^^^^^^^^^ 432 433Perform floating-point maximum on two values. 434 435In the case where a single input is a NaN (either signaling or quiet), 436the non-NaN input is returned. 437 438The return value of (FMAXNUM 0.0, -0.0) could be either 0.0 or -0.0. 439 440G_FMINNUM_IEEE 441^^^^^^^^^^^^^^ 442 443Perform floating-point minimum on two values, following the IEEE-754 2008 444definition. This differs from FMINNUM in the handling of signaling NaNs. If one 445input is a signaling NaN, returns a quiet NaN. 446 447G_FMAXNUM_IEEE 448^^^^^^^^^^^^^^ 449 450Perform floating-point maximum on two values, following the IEEE-754 2008 451definition. This differs from FMAXNUM in the handling of signaling NaNs. If one 452input is a signaling NaN, returns a quiet NaN. 453 454G_FMINIMUM 455^^^^^^^^^^ 456 457NaN-propagating minimum that also treat -0.0 as less than 0.0. While 458FMINNUM_IEEE follow IEEE 754-2008 semantics, FMINIMUM follows IEEE 754-2018 459draft semantics. 460 461G_FMAXIMUM 462^^^^^^^^^^ 463 464NaN-propagating maximum that also treat -0.0 as less than 0.0. While 465FMAXNUM_IEEE follow IEEE 754-2008 semantics, FMAXIMUM follows IEEE 754-2018 466draft semantics. 467 468G_FADD, G_FSUB, G_FMUL, G_FDIV, G_FREM 469^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 470 471Perform the specified floating point arithmetic. 472 473G_FMA 474^^^^^ 475 476Perform a fused multiply add (i.e. without the intermediate rounding step). 477 478G_FMAD 479^^^^^^ 480 481Perform a non-fused multiply add (i.e. with the intermediate rounding step). 482 483G_FPOW 484^^^^^^ 485 486Raise the first operand to the power of the second. 487 488G_FEXP, G_FEXP2 489^^^^^^^^^^^^^^^ 490 491Calculate the base-e or base-2 exponential of a value 492 493G_FLOG, G_FLOG2, G_FLOG10 494^^^^^^^^^^^^^^^^^^^^^^^^^ 495 496Calculate the base-e, base-2, or base-10 respectively. 497 498G_FCEIL, G_FCOS, G_FSIN, G_FSQRT, G_FFLOOR, G_FRINT, G_FNEARBYINT 499^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 500 501These correspond to the standard C functions of the same name. 502 503G_INTRINSIC_TRUNC 504^^^^^^^^^^^^^^^^^ 505 506Returns the operand rounded to the nearest integer not larger in magnitude than the operand. 507 508G_INTRINSIC_ROUND 509^^^^^^^^^^^^^^^^^ 510 511Returns the operand rounded to the nearest integer. 512 513Vector Specific Operations 514-------------------------- 515 516G_CONCAT_VECTORS 517^^^^^^^^^^^^^^^^ 518 519Concatenate two vectors to form a longer vector. 520 521G_BUILD_VECTOR, G_BUILD_VECTOR_TRUNC 522^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 523 524Create a vector from multiple scalar registers. No implicit 525conversion is performed (i.e. the result element type must be the 526same as all source operands) 527 528The _TRUNC version truncates the larger operand types to fit the 529destination vector elt type. 530 531G_INSERT_VECTOR_ELT 532^^^^^^^^^^^^^^^^^^^ 533 534Insert an element into a vector 535 536G_EXTRACT_VECTOR_ELT 537^^^^^^^^^^^^^^^^^^^^ 538 539Extract an element from a vector 540 541G_SHUFFLE_VECTOR 542^^^^^^^^^^^^^^^^ 543 544Concatenate two vectors and shuffle the elements according to the mask operand. 545The mask operand should be an IR Constant which exactly matches the 546corresponding mask for the IR shufflevector instruction. 547 548Vector Reduction Operations 549--------------------------- 550 551These operations represent horizontal vector reduction, producing a scalar result. 552 553G_VECREDUCE_SEQ_FADD, G_VECREDUCE_SEQ_FMUL 554^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 555 556The SEQ variants perform reductions in sequential order. The first operand is 557an initial scalar accumulator value, and the second operand is the vector to reduce. 558 559G_VECREDUCE_FADD, G_VECREDUCE_FMUL 560^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 561 562These reductions are relaxed variants which may reduce the elements in any order. 563 564G_VECREDUCE_FMAX, G_VECREDUCE_FMIN 565^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 566 567FMIN/FMAX nodes can have flags, for NaN/NoNaN variants. 568 569 570Integer/bitwise reductions 571^^^^^^^^^^^^^^^^^^^^^^^^^^ 572 573* G_VECREDUCE_ADD 574* G_VECREDUCE_MUL 575* G_VECREDUCE_AND 576* G_VECREDUCE_OR 577* G_VECREDUCE_XOR 578* G_VECREDUCE_SMAX 579* G_VECREDUCE_SMIN 580* G_VECREDUCE_UMAX 581* G_VECREDUCE_UMIN 582 583Integer reductions may have a result type larger than the vector element type. 584However, the reduction is performed using the vector element type and the value 585in the top bits is unspecified. 586 587Memory Operations 588----------------- 589 590G_LOAD, G_SEXTLOAD, G_ZEXTLOAD 591^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 592 593Generic load. Expects a MachineMemOperand in addition to explicit 594operands. If the result size is larger than the memory size, the 595high bits are undefined, sign-extended, or zero-extended respectively. 596 597Only G_LOAD is valid if the result is a vector type. If the result is larger 598than the memory size, the high elements are undefined (i.e. this is not a 599per-element, vector anyextload) 600 601G_INDEXED_LOAD 602^^^^^^^^^^^^^^ 603 604Generic indexed load. Combines a GEP with a load. $newaddr is set to $base + $offset. 605If $am is 0 (post-indexed), then the value is loaded from $base; if $am is 1 (pre-indexed) 606then the value is loaded from $newaddr. 607 608G_INDEXED_SEXTLOAD 609^^^^^^^^^^^^^^^^^^ 610 611Same as G_INDEXED_LOAD except that the load performed is sign-extending, as with G_SEXTLOAD. 612 613G_INDEXED_ZEXTLOAD 614^^^^^^^^^^^^^^^^^^ 615 616Same as G_INDEXED_LOAD except that the load performed is zero-extending, as with G_ZEXTLOAD. 617 618G_STORE 619^^^^^^^ 620 621Generic store. Expects a MachineMemOperand in addition to explicit 622operands. If the stored value size is greater than the memory size, 623the high bits are implicitly truncated. If this is a vector store, the 624high elements are discarded (i.e. this does not function as a per-lane 625vector, truncating store) 626 627G_INDEXED_STORE 628^^^^^^^^^^^^^^^ 629 630Combines a store with a GEP. See description of G_INDEXED_LOAD for indexing behaviour. 631 632G_ATOMIC_CMPXCHG_WITH_SUCCESS 633^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 634 635Generic atomic cmpxchg with internal success check. Expects a 636MachineMemOperand in addition to explicit operands. 637 638G_ATOMIC_CMPXCHG 639^^^^^^^^^^^^^^^^ 640 641Generic atomic cmpxchg. Expects a MachineMemOperand in addition to explicit 642operands. 643 644G_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 645^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 646 647Generic atomicrmw. Expects a MachineMemOperand in addition to explicit 648operands. 649 650G_FENCE 651^^^^^^^ 652 653.. caution:: 654 655 I couldn't find any documentation on this at the time of writing. 656 657Control Flow 658------------ 659 660G_PHI 661^^^^^ 662 663Implement the φ node in the SSA graph representing the function. 664 665.. code-block:: none 666 667 %1(s8) = G_PHI %7(s8), %bb.0, %3(s8), %bb.1 668 669G_BR 670^^^^ 671 672Unconditional branch 673 674G_BRCOND 675^^^^^^^^ 676 677Conditional branch 678 679G_BRINDIRECT 680^^^^^^^^^^^^ 681 682Indirect branch 683 684G_BRJT 685^^^^^^ 686 687Indirect branch to jump table entry 688 689G_JUMP_TABLE 690^^^^^^^^^^^^ 691 692.. caution:: 693 694 I found no documentation for this instruction at the time of writing. 695 696G_INTRINSIC, G_INTRINSIC_W_SIDE_EFFECTS 697^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 698 699Call an intrinsic 700 701The _W_SIDE_EFFECTS version is considered to have unknown side-effects and 702as such cannot be reordered across other side-effecting instructions. 703 704.. note:: 705 706 Unlike SelectionDAG, there is no _VOID variant. Both of these are permitted 707 to have zero, one, or multiple results. 708 709Variadic Arguments 710------------------ 711 712G_VASTART 713^^^^^^^^^ 714 715.. caution:: 716 717 I found no documentation for this instruction at the time of writing. 718 719G_VAARG 720^^^^^^^ 721 722.. caution:: 723 724 I found no documentation for this instruction at the time of writing. 725 726Other Operations 727---------------- 728 729G_DYN_STACKALLOC 730^^^^^^^^^^^^^^^^ 731 732Dynamically realigns the stack pointer to the specified size and alignment. 733An alignment value of `0` or `1` mean no specific alignment. 734 735.. code-block:: none 736 737 %8:_(p0) = G_DYN_STACKALLOC %7(s64), 32 738