From adca61373aca92bfb62ed34704e8fee37461c730 Mon Sep 17 00:00:00 2001 From: Sayan Sivakumaran Date: Wed, 10 Dec 2025 07:30:10 -0600 Subject: [PATCH] Make sure newlines are present in LLVM IR documentation (#8289) --- etc/scripts/docenizers/docenizer-llvm.ts | 2 +- lib/asm-docs/generated/asm-docs-llvm.ts | 3687 +++++++++++++++++++++- 2 files changed, 3622 insertions(+), 67 deletions(-) diff --git a/etc/scripts/docenizers/docenizer-llvm.ts b/etc/scripts/docenizers/docenizer-llvm.ts index b12450a5e..c18dd03f6 100644 --- a/etc/scripts/docenizers/docenizer-llvm.ts +++ b/etc/scripts/docenizers/docenizer-llvm.ts @@ -77,7 +77,7 @@ for (const instruction of info) { console.log(` case '${instruction.name.toUpperCase()}':`); console.log(' return {'); console.log(` url: \`${instruction.url}\`,`); - console.log(` html: \`${instruction.html.replaceAll('\n', '').replaceAll('`', '\\`')}\`,`); + console.log(` html: \`${instruction.html.replaceAll('`', '\\`')}\`,`); console.log(` tooltip: \`${instruction.tooltip.replaceAll('\n', '').replaceAll('`', '\\`')}\`,`); console.log(' };'); } diff --git a/lib/asm-docs/generated/asm-docs-llvm.ts b/lib/asm-docs/generated/asm-docs-llvm.ts index ce1e3d2cc..fe4e8ed0f 100644 --- a/lib/asm-docs/generated/asm-docs-llvm.ts +++ b/lib/asm-docs/generated/asm-docs-llvm.ts @@ -6,397 +6,3952 @@ export function getAsmOpcode(opcode: string | undefined): AssemblyInstructionInf case 'RET': return { url: `https://llvm.org/docs/LangRef.html#ret-instruction`, - html: `

‘ret’ Instruction

Syntax:
ret <type> <value>       ; Return a value from a non-void functionret void                 ; Return from void function
Overview:

The ‘ret’ instruction is used to return control flow (and optionallya value) from a function back to the caller.

There are two forms of the ‘ret’ instruction: one that returns avalue and then causes control flow, and one that just causes controlflow to occur.

Arguments:

The ‘ret’ instruction optionally accepts a single argument, thereturn value. The type of the return value must be a ‘firstclass’ type.

A function is not well formed if it has a non-voidreturn type and contains a ‘ret’ instruction with no return value ora return value with a type that does not match its type, or if it has avoid return type and contains a ‘ret’ instruction with a returnvalue.

Semantics:

When the ‘ret’ instruction is executed, control flow returns back tothe calling function’s context. If the caller is a“call” instruction, execution continues at theinstruction after the call. If the caller was an“invoke” instruction, execution continues at thebeginning of the “normal” destination block. If the instruction returnsa value, that value shall set the call or invoke instruction’s returnvalue.

Example:
ret i32 5                       ; Return an integer value of 5ret void                        ; Return from a void functionret { i32, i8 } { i32 4, i8 2 } ; Return a struct of values 4 and 2
`, + html: `

‘ret’ Instruction

+
+
Syntax:
+
ret <type> <value>       ; Return a value from a non-void function
+ret void                 ; Return from void function
+
+
+
+
+
Overview:
+

The ‘ret’ instruction is used to return control flow (and optionally +a value) from a function back to the caller.

+

There are two forms of the ‘ret’ instruction: one that returns a +value and then causes control flow, and one that just causes control +flow to occur.

+
+
+
Arguments:
+

The ‘ret’ instruction optionally accepts a single argument, the +return value. The type of the return value must be a ‘first +class’ type.

+

A function is not well formed if it has a non-void +return type and contains a ‘ret’ instruction with no return value or +a return value with a type that does not match its type, or if it has a +void return type and contains a ‘ret’ instruction with a return +value.

+
+
+
Semantics:
+

When the ‘ret’ instruction is executed, control flow returns back to +the calling function’s context. If the caller is a +“call” instruction, execution continues at the +instruction after the call. If the caller was an +“invoke” instruction, execution continues at the +beginning of the “normal” destination block. If the instruction returns +a value, that value shall set the call or invoke instruction’s return +value.

+
+
+
Example:
+
ret i32 5                       ; Return an integer value of 5
+ret void                        ; Return from a void function
+ret { i32, i8 } { i32 4, i8 2 } ; Return a struct of values 4 and 2
+
+
+
+`, tooltip: `The ‘ret’ instruction is used to return control flow (and optionallya value) from a function back to the caller.There are two forms of the ‘ret’ instruction: one that returns avalue and then causes control flow, and one that just causes controlflow to occur.`, }; case 'BR': return { url: `https://llvm.org/docs/LangRef.html#br-instruction`, - html: `

‘br’ Instruction

Syntax:
br i1 <cond>, label <iftrue>, label <iffalse>br label <dest>          ; Unconditional branch
Overview:

The ‘br’ instruction is used to cause control flow to transfer to adifferent basic block in the current function. There are two forms ofthis instruction, corresponding to a conditional branch and anunconditional branch.

Arguments:

The conditional branch form of the ‘br’ instruction takes a single‘i1’ value and two ‘label’ values. The unconditional form of the‘br’ instruction takes a single ‘label’ value as a target.

Semantics:

Upon execution of a conditional ‘br’ instruction, the ‘i1’argument is evaluated. If the value is true, control flows to the‘iftrue’ label argument. If “cond” is false, control flowsto the ‘iffalse’ label argument.If ‘cond’ is poison or undef, this instruction has undefinedbehavior.

Example:
Test:  %cond = icmp eq i32 %a, %b  br i1 %cond, label %IfEqual, label %IfUnequalIfEqual:  ret i32 1IfUnequal:  ret i32 0
`, + html: `

‘br’ Instruction

+
+
Syntax:
+
br i1 <cond>, label <iftrue>, label <iffalse>
+br label <dest>          ; Unconditional branch
+
+
+
+
+
Overview:
+

The ‘br’ instruction is used to cause control flow to transfer to a +different basic block in the current function. There are two forms of +this instruction, corresponding to a conditional branch and an +unconditional branch.

+
+
+
Arguments:
+

The conditional branch form of the ‘br’ instruction takes a single +‘i1’ value and two ‘label’ values. The unconditional form of the +‘br’ instruction takes a single ‘label’ value as a target.

+
+
+
Semantics:
+

Upon execution of a conditional ‘br’ instruction, the ‘i1’ +argument is evaluated. If the value is true, control flows to the +‘iftrue’ label argument. If “cond” is false, control flows +to the ‘iffalse’ label argument. +If ‘cond’ is poison or undef, this instruction has undefined +behavior.

+
+
+
Example:
+
Test:
+  %cond = icmp eq i32 %a, %b
+  br i1 %cond, label %IfEqual, label %IfUnequal
+IfEqual:
+  ret i32 1
+IfUnequal:
+  ret i32 0
+
+
+
+`, tooltip: `The ‘br’ instruction is used to cause control flow to transfer to adifferent basic block in the current function. There are two forms ofthis instruction, corresponding to a conditional branch and anunconditional branch.`, }; case 'SWITCH': return { url: `https://llvm.org/docs/LangRef.html#switch-instruction`, - html: `

‘switch’ Instruction

Syntax:
switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
Overview:

The ‘switch’ instruction is used to transfer control flow to one ofseveral different places. It is a generalization of the ‘br’instruction, allowing a branch to occur to one of many possibledestinations.

Arguments:

The ‘switch’ instruction uses three parameters: an integercomparison value ‘value’, a default ‘label’ destination, and anarray of pairs of comparison value constants and ‘label’s. The tableis not allowed to contain duplicate constant entries.

Semantics:

The switch instruction specifies a table of values and destinations.When the ‘switch’ instruction is executed, this table is searchedfor the given value. If the value is found, control flow is transferredto the corresponding destination; otherwise, control flow is transferredto the default destination.If ‘value’ is poison or undef, this instruction has undefinedbehavior.

Implementation:

Depending on properties of the target machine and the particularswitch instruction, this instruction may be code generated indifferent ways. For example, it could be generated as a series ofchained conditional branches or with a lookup table.

Example:
; Emulate a conditional br instruction%Val = zext i1 %value to i32switch i32 %Val, label %truedest [ i32 0, label %falsedest ]; Emulate an unconditional br instructionswitch i32 0, label %dest [ ]; Implement a jump table:switch i32 %val, label %otherwise [ i32 0, label %onzero                                    i32 1, label %onone                                    i32 2, label %ontwo ]
`, + html: `

‘switch’ Instruction

+
+
Syntax:
+
switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
+
+
+
+
+
Overview:
+

The ‘switch’ instruction is used to transfer control flow to one of +several different places. It is a generalization of the ‘br’ +instruction, allowing a branch to occur to one of many possible +destinations.

+
+
+
Arguments:
+

The ‘switch’ instruction uses three parameters: an integer +comparison value ‘value’, a default ‘label’ destination, and an +array of pairs of comparison value constants and ‘label’s. The table +is not allowed to contain duplicate constant entries.

+
+
+
Semantics:
+

The switch instruction specifies a table of values and destinations. +When the ‘switch’ instruction is executed, this table is searched +for the given value. If the value is found, control flow is transferred +to the corresponding destination; otherwise, control flow is transferred +to the default destination. +If ‘value’ is poison or undef, this instruction has undefined +behavior.

+
+
+
Implementation:
+

Depending on properties of the target machine and the particular +switch instruction, this instruction may be code generated in +different ways. For example, it could be generated as a series of +chained conditional branches or with a lookup table.

+
+
+
Example:
+
; Emulate a conditional br instruction
+%Val = zext i1 %value to i32
+switch i32 %Val, label %truedest [ i32 0, label %falsedest ]
+
+; Emulate an unconditional br instruction
+switch i32 0, label %dest [ ]
+
+; Implement a jump table:
+switch i32 %val, label %otherwise [ i32 0, label %onzero
+                                    i32 1, label %onone
+                                    i32 2, label %ontwo ]
+
+
+
+`, tooltip: `The ‘switch’ instruction is used to transfer control flow to one ofseveral different places. It is a generalization of the ‘br’instruction, allowing a branch to occur to one of many possibledestinations.`, }; case 'INDIRECTBR': return { url: `https://llvm.org/docs/LangRef.html#indirectbr-instruction`, - html: `

‘indirectbr’ Instruction

Syntax:
indirectbr ptr <address>, [ label <dest1>, label <dest2>, ... ]
Overview:

The ‘indirectbr’ instruction implements an indirect branch to alabel within the current function, whose address is specified by“address”. Address must be derived from ablockaddress constant.

Arguments:

The ‘address’ argument is the address of the label to jump to. Therest of the arguments indicate the full set of possible destinationsthat the address may point to. Blocks are allowed to occur multipletimes in the destination list, though this isn’t particularly useful.

This destination list is required so that dataflow analysis has anaccurate understanding of the CFG.

Semantics:

Control transfers to the block specified in the address argument. Allpossible destination blocks must be listed in the label list, otherwisethis instruction has undefined behavior. This implies that jumps tolabels defined in other functions have undefined behavior as well.If ‘address’ is poison or undef, this instruction has undefinedbehavior.

Implementation:

This is typically implemented with a jump through a register.

Example:
indirectbr ptr %Addr, [ label %bb1, label %bb2, label %bb3 ]
`, + html: `

‘indirectbr’ Instruction

+
+
Syntax:
+
indirectbr ptr <address>, [ label <dest1>, label <dest2>, ... ]
+
+
+
+
+
Overview:
+

The ‘indirectbr’ instruction implements an indirect branch to a +label within the current function, whose address is specified by +“address”. Address must be derived from a +blockaddress constant.

+
+
+
Arguments:
+

The ‘address’ argument is the address of the label to jump to. The +rest of the arguments indicate the full set of possible destinations +that the address may point to. Blocks are allowed to occur multiple +times in the destination list, though this isn’t particularly useful.

+

This destination list is required so that dataflow analysis has an +accurate understanding of the CFG.

+
+
+
Semantics:
+

Control transfers to the block specified in the address argument. All +possible destination blocks must be listed in the label list, otherwise +this instruction has undefined behavior. This implies that jumps to +labels defined in other functions have undefined behavior as well. +If ‘address’ is poison or undef, this instruction has undefined +behavior.

+
+
+
Implementation:
+

This is typically implemented with a jump through a register.

+
+
+
Example:
+
indirectbr ptr %Addr, [ label %bb1, label %bb2, label %bb3 ]
+
+
+
+`, tooltip: `The ‘indirectbr’ instruction implements an indirect branch to alabel within the current function, whose address is specified by“address”. Address must be derived from ablockaddress constant.`, }; case 'INVOKE': return { url: `https://llvm.org/docs/LangRef.html#invoke-instruction`, - html: `

‘invoke’ Instruction

Syntax:
<result> = invoke [cconv] [ret attrs] [addrspace(<num>)] <ty>|<fnty> <fnptrval>(<function args>) [fn attrs]              [operand bundles] to label <normal label> unwind label <exception label>
Overview:

The ‘invoke’ instruction causes control to transfer to a specifiedfunction, with the possibility of control flow transfer to either the‘normal’ label or the ‘exception’ label. If the callee functionreturns with the “ret” instruction, control flow will return to the“normal” label. If the callee (or any indirect callees) returns via the“resume” instruction or other exception handlingmechanism, control is interrupted and continued at the dynamicallynearest “exception” label.

The ‘exception’ label is a landingpad for the exception. As such,‘exception’ label is required to have the“landingpad” instruction, which contains theinformation about the behavior of the program after unwinding happens,as its first non-PHI instruction. The restrictions on the“landingpad” instruction’s tightly couples it to the “invoke”instruction, so that the important information contained within the“landingpad” instruction can’t be lost through normal code motion.

Arguments:

This instruction requires several arguments:

  1. The optional “cconv” marker indicates which callingconvention the call should use. If none isspecified, the call defaults to using C calling conventions.

  2. The optional Parameter Attributes list for returnvalues. Only ‘zeroext’, ‘signext’, ‘noext’, and ‘inreg’attributes are valid here.

  3. The optional addrspace attribute can be used to indicate the address spaceof the called function. If it is not specified, the program address spacefrom the datalayout string will be used.

  4. ‘ty’: the type of the call instruction itself which is also thetype of the return value. Functions that return no value are markedvoid. The signature is computed based on the return type and argumenttypes.

  5. ‘fnty’: shall be the signature of the function being invoked. Theargument types must match the types implied by this signature. Thisis only required if the signature specifies a varargs type.

  6. ‘fnptrval’: An LLVM value containing a pointer to a function tobe invoked. In most cases, this is a direct function invocation, butindirect invoke’s are just as possible, calling an arbitrary pointerto function value.

  7. ‘function args’: argument list whose types match the functionsignature argument types and parameter attributes. All arguments mustbe of first class type. If the function signatureindicates the function accepts a variable number of arguments, theextra arguments can be specified.

  8. ‘normal label’: the label reached when the called functionexecutes a ‘ret’ instruction.

  9. ‘exception label’: the label reached when a callee returns viathe resume instruction or other exception handlingmechanism.

  10. The optional function attributes list.

  11. The optional operand bundles list.

Semantics:

This instruction is designed to operate as a standard ‘call’instruction in most regards. The primary difference is that itestablishes an association with a label, which is used by the runtimelibrary to unwind the stack.

This instruction is used in languages with destructors to ensure thatproper cleanup is performed in the case of either a longjmp or athrown exception. Additionally, this is important for implementation of‘catch’ clauses in high-level languages that support them.

For the purposes of the SSA form, the definition of the value returnedby the ‘invoke’ instruction is deemed to occur on the edge from thecurrent block to the “normal” label. If the callee unwinds then noreturn value is available.

Example:
%retval = invoke i32 @Test(i32 15) to label %Continue            unwind label %TestCleanup              ; i32:retval set%retval = invoke coldcc i32 %Testfnptr(i32 15) to label %Continue            unwind label %TestCleanup              ; i32:retval set
`, + html: `

‘invoke’ Instruction

+
+
Syntax:
+
<result> = invoke [cconv] [ret attrs] [addrspace(<num>)] <ty>|<fnty> <fnptrval>(<function args>) [fn attrs]
+              [operand bundles] to label <normal label> unwind label <exception label>
+
+
+
+
+
Overview:
+

The ‘invoke’ instruction causes control to transfer to a specified +function, with the possibility of control flow transfer to either the +‘normal’ label or the ‘exception’ label. If the callee function +returns with the “ret” instruction, control flow will return to the +“normal” label. If the callee (or any indirect callees) returns via the +“resume” instruction or other exception handling +mechanism, control is interrupted and continued at the dynamically +nearest “exception” label.

+

The ‘exception’ label is a landing +pad for the exception. As such, +‘exception’ label is required to have the +“landingpad” instruction, which contains the +information about the behavior of the program after unwinding happens, +as its first non-PHI instruction. The restrictions on the +“landingpad” instruction’s tightly couples it to the “invoke” +instruction, so that the important information contained within the +“landingpad” instruction can’t be lost through normal code motion.

+
+
+
Arguments:
+

This instruction requires several arguments:

+
    +

  1. The optional “cconv” marker indicates which calling +convention the call should use. If none is +specified, the call defaults to using C calling conventions.

    2. +

  2. The optional Parameter Attributes list for return +values. Only ‘zeroext’, ‘signext’, ‘noext’, and ‘inreg’ +attributes are valid here.

    3. +

  3. The optional addrspace attribute can be used to indicate the address space +of the called function. If it is not specified, the program address space +from the datalayout string will be used.

    4. +

  4. ‘ty’: the type of the call instruction itself which is also the +type of the return value. Functions that return no value are marked +void. The signature is computed based on the return type and argument +types.

    5. +

  5. ‘fnty’: shall be the signature of the function being invoked. The +argument types must match the types implied by this signature. This +is only required if the signature specifies a varargs type.

    6. +

  6. ‘fnptrval’: An LLVM value containing a pointer to a function to +be invoked. In most cases, this is a direct function invocation, but +indirect invoke’s are just as possible, calling an arbitrary pointer +to function value.

    7. +

  7. ‘function args’: argument list whose types match the function +signature argument types and parameter attributes. All arguments must +be of first class type. If the function signature +indicates the function accepts a variable number of arguments, the +extra arguments can be specified.

    8. +

  8. ‘normal label’: the label reached when the called function +executes a ‘ret’ instruction.

    9. +

  9. ‘exception label’: the label reached when a callee returns via +the resume instruction or other exception handling +mechanism.

    10. +

  10. The optional function attributes list.

    11. +

  11. The optional operand bundles list.

    12. +
+
+
+
Semantics:
+

This instruction is designed to operate as a standard ‘call’ +instruction in most regards. The primary difference is that it +establishes an association with a label, which is used by the runtime +library to unwind the stack.

+

This instruction is used in languages with destructors to ensure that +proper cleanup is performed in the case of either a longjmp or a +thrown exception. Additionally, this is important for implementation of +‘catch’ clauses in high-level languages that support them.

+

For the purposes of the SSA form, the definition of the value returned +by the ‘invoke’ instruction is deemed to occur on the edge from the +current block to the “normal” label. If the callee unwinds then no +return value is available.

+
+
+
Example:
+
%retval = invoke i32 @Test(i32 15) to label %Continue
+            unwind label %TestCleanup              ; i32:retval set
+%retval = invoke coldcc i32 %Testfnptr(i32 15) to label %Continue
+            unwind label %TestCleanup              ; i32:retval set
+
+
+
+`, tooltip: `The ‘invoke’ instruction causes control to transfer to a specifiedfunction, with the possibility of control flow transfer to either the‘normal’ label or the ‘exception’ label. If the callee functionreturns with the “ret” instruction, control flow will return to the“normal” label. If the callee (or any indirect callees) returns via the“resume” instruction or other exception handlingmechanism, control is interrupted and continued at the dynamicallynearest “exception” label.The ‘exception’ label is a landingpad for the exception. As such,‘exception’ label is required to have the“landingpad” instruction, which contains theinformation about the behavior of the program after unwinding happens,as its first non-PHI instruction. The restrictions on the“landingpad” instruction’s tightly couples it to the “invoke”instruction, so that the important information contained within the“landingpad” instruction can’t be lost through normal code motion.`, }; case 'CALLBR': return { url: `https://llvm.org/docs/LangRef.html#callbr-instruction`, - html: `

‘callbr’ Instruction

Syntax:
<result> = callbr [cconv] [ret attrs] [addrspace(<num>)] <ty>|<fnty> <fnptrval>(<function args>) [fn attrs]              [operand bundles] to label <fallthrough label> [indirect labels]
Overview:

The ‘callbr’ instruction causes control to transfer to a specifiedfunction, with the possibility of control flow transfer to either the‘fallthrough’ label or one of the ‘indirect’ labels.

This instruction should only be used to implement the “goto” feature of gccstyle inline assembly. Any other usage is an error in the IR verifier.

Note that in order to support outputs along indirect edges, LLVM may need tosplit critical edges, which may require synthesizing a replacement block forthe indirect labels. Therefore, the address of a label as seen by anothercallbr instruction, or for a blockaddress constant,may not be equal to the address provided for the same block to thisinstruction’s indirect labels operand. The assembly code may only transfercontrol to addresses provided via this instruction’s indirect labels.

On target architectures that implement branch target enforcement by requiringindirect (register-controlled) branch instructions to jump only to locationsmarked by a special instruction (such as AArch64 bti), the called code isexpected not to use such an indirect branch to transfer control to thelocations in indirect labels. Therefore, including a label in theindirect labels of a callbr does not require the compiler to put abti or equivalent instruction at the label.

Arguments:

This instruction requires several arguments:

  1. The optional “cconv” marker indicates which callingconvention the call should use. If none isspecified, the call defaults to using C calling conventions.

  2. The optional Parameter Attributes list for returnvalues. Only ‘zeroext’, ‘signext’, ‘noext’, and ‘inreg’attributes are valid here.

  3. The optional addrspace attribute can be used to indicate the address spaceof the called function. If it is not specified, the program address spacefrom the datalayout string will be used.

  4. ‘ty’: the type of the call instruction itself which is also thetype of the return value. Functions that return no value are markedvoid. The signature is computed based on the return type and argumenttypes.

  5. ‘fnty’: shall be the signature of the function being called. Theargument types must match the types implied by this signature. Thisis only required if the signature specifies a varargs type.

  6. ‘fnptrval’: An LLVM value containing a pointer to a function tobe called. In most cases, this is a direct function call, butother callbr’s are just as possible, calling an arbitrary pointerto function value.

  7. ‘function args’: argument list whose types match the functionsignature argument types and parameter attributes. All arguments mustbe of first class type. If the function signatureindicates the function accepts a variable number of arguments, theextra arguments can be specified.

  8. ‘fallthrough label’: the label reached when the inline assembly’sexecution exits the bottom.

  9. ‘indirect labels’: the labels reached when a callee transfers controlto a location other than the ‘fallthrough label’. Label constraintsrefer to these destinations.

  10. The optional function attributes list.

  11. The optional operand bundles list.

Semantics:

This instruction is designed to operate as a standard ‘call’instruction in most regards. The primary difference is that itestablishes an association with additional labels to define where controlflow goes after the call.

The output values of a ‘callbr’ instruction are available both in thethe ‘fallthrough’ block, and any ‘indirect’ blocks(s).

The only use of this today is to implement the “goto” feature of gcc inlineassembly where additional labels can be provided as locations for the inlineassembly to jump to.

Example:
; "asm goto" without output constraints.callbr void asm "", "r,!i"(i32 %x)            to label %fallthrough [label %indirect]; "asm goto" with output constraints.<result> = callbr i32 asm "", "=r,r,!i"(i32 %x)            to label %fallthrough [label %indirect]
`, + html: `

‘callbr’ Instruction

+
+
Syntax:
+
<result> = callbr [cconv] [ret attrs] [addrspace(<num>)] <ty>|<fnty> <fnptrval>(<function args>) [fn attrs]
+              [operand bundles] to label <fallthrough label> [indirect labels]
+
+
+
+
+
Overview:
+

The ‘callbr’ instruction causes control to transfer to a specified +function, with the possibility of control flow transfer to either the +‘fallthrough’ label or one of the ‘indirect’ labels.

+

This instruction should only be used to implement the “goto” feature of gcc +style inline assembly. Any other usage is an error in the IR verifier.

+

Note that in order to support outputs along indirect edges, LLVM may need to +split critical edges, which may require synthesizing a replacement block for +the indirect labels. Therefore, the address of a label as seen by another +callbr instruction, or for a blockaddress constant, +may not be equal to the address provided for the same block to this +instruction’s indirect labels operand. The assembly code may only transfer +control to addresses provided via this instruction’s indirect labels.

+

On target architectures that implement branch target enforcement by requiring +indirect (register-controlled) branch instructions to jump only to locations +marked by a special instruction (such as AArch64 bti), the called code is +expected not to use such an indirect branch to transfer control to the +locations in indirect labels. Therefore, including a label in the +indirect labels of a callbr does not require the compiler to put a +bti or equivalent instruction at the label.

+
+
+
Arguments:
+

This instruction requires several arguments:

+
    +

  1. The optional “cconv” marker indicates which calling +convention the call should use. If none is +specified, the call defaults to using C calling conventions.

    2. +

  2. The optional Parameter Attributes list for return +values. Only ‘zeroext’, ‘signext’, ‘noext’, and ‘inreg’ +attributes are valid here.

    3. +

  3. The optional addrspace attribute can be used to indicate the address space +of the called function. If it is not specified, the program address space +from the datalayout string will be used.

    4. +

  4. ‘ty’: the type of the call instruction itself which is also the +type of the return value. Functions that return no value are marked +void. The signature is computed based on the return type and argument +types.

    5. +

  5. ‘fnty’: shall be the signature of the function being called. The +argument types must match the types implied by this signature. This +is only required if the signature specifies a varargs type.

    6. +

  6. ‘fnptrval’: An LLVM value containing a pointer to a function to +be called. In most cases, this is a direct function call, but +other callbr’s are just as possible, calling an arbitrary pointer +to function value.

    7. +

  7. ‘function args’: argument list whose types match the function +signature argument types and parameter attributes. All arguments must +be of first class type. If the function signature +indicates the function accepts a variable number of arguments, the +extra arguments can be specified.

    8. +

  8. ‘fallthrough label’: the label reached when the inline assembly’s +execution exits the bottom.

    9. +

  9. ‘indirect labels’: the labels reached when a callee transfers control +to a location other than the ‘fallthrough label’. Label constraints +refer to these destinations.

    10. +

  10. The optional function attributes list.

    11. +

  11. The optional operand bundles list.

    12. +
+
+
+
Semantics:
+

This instruction is designed to operate as a standard ‘call’ +instruction in most regards. The primary difference is that it +establishes an association with additional labels to define where control +flow goes after the call.

+

The output values of a ‘callbr’ instruction are available both in the +the ‘fallthrough’ block, and any ‘indirect’ blocks(s).

+

The only use of this today is to implement the “goto” feature of gcc inline +assembly where additional labels can be provided as locations for the inline +assembly to jump to.

+
+
+
Example:
+
; "asm goto" without output constraints.
+callbr void asm "", "r,!i"(i32 %x)
+            to label %fallthrough [label %indirect]
+
+; "asm goto" with output constraints.
+<result> = callbr i32 asm "", "=r,r,!i"(i32 %x)
+            to label %fallthrough [label %indirect]
+
+
+
+`, tooltip: `The ‘callbr’ instruction causes control to transfer to a specifiedfunction, with the possibility of control flow transfer to either the‘fallthrough’ label or one of the ‘indirect’ labels.This instruction should only be used to implement the “goto” feature of gccstyle inline assembly. Any other usage is an error in the IR verifier.Note that in order to support outputs along indirect edges, LLVM may need tosplit critical edges, which may require synthesizing a replacement block forthe indirect labels. Therefore, the address of a label as seen by anothercallbr instruction, or for a blockaddress constant,may not be equal to the address provided for the same block to thisinstruction’s indirect labels operand. The assembly code may only transfercontrol to addresses provided via this instruction’s indirect labels.On target architectures that implement branch target enforcement by requiringindirect (register-controlled) branch instructions to jump only to locationsmarked by a special instruction (such as AArch64 bti), the called code isexpected not to use such an indirect branch to transfer control to thelocations in indirect labels. Therefore, including a label in theindirect labels of a callbr does not require the compiler to put abti or equivalent instruction at the label.`, }; case 'RESUME': return { url: `https://llvm.org/docs/LangRef.html#resume-instruction`, - html: `

‘resume’ Instruction

Syntax:
resume <type> <value>
Overview:

The ‘resume’ instruction is a terminator instruction that has nosuccessors.

Arguments:

The ‘resume’ instruction requires one argument, which must have thesame type as the result of any ‘landingpad’ instruction in the samefunction.

Semantics:

The ‘resume’ instruction resumes propagation of an existing(in-flight) exception whose unwinding was interrupted with alandingpad instruction.

Example:
resume { ptr, i32 } %exn
`, + html: `

‘resume’ Instruction

+
+
Syntax:
+
resume <type> <value>
+
+
+
+
+
Overview:
+

The ‘resume’ instruction is a terminator instruction that has no +successors.

+
+
+
Arguments:
+

The ‘resume’ instruction requires one argument, which must have the +same type as the result of any ‘landingpad’ instruction in the same +function.

+
+
+
Semantics:
+

The ‘resume’ instruction resumes propagation of an existing +(in-flight) exception whose unwinding was interrupted with a +landingpad instruction.

+
+
+
Example:
+
resume { ptr, i32 } %exn
+
+
+
+`, tooltip: `The ‘resume’ instruction is a terminator instruction that has nosuccessors.`, }; case 'CATCHSWITCH': return { url: `https://llvm.org/docs/LangRef.html#catchswitch-instruction`, - html: `

‘catchswitch’ Instruction

Syntax:
<resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind to caller<resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind label <default>
Overview:

The ‘catchswitch’ instruction is used by LLVM’s exception handling system to describe the set of possible catch handlersthat may be executed by the EH personality routine.

Arguments:

The parent argument is the token of the funclet that contains thecatchswitch instruction. If the catchswitch is not inside a funclet,this operand may be the token none.

The default argument is the label of another basic block beginning witheither a cleanuppad or catchswitch instruction. This unwind destinationmust be a legal target with respect to the parent links, as described inthe exception handling documentation.

The handlers are a nonempty list of successor blocks that each begin with acatchpad instruction.

Semantics:

Executing this instruction transfers control to one of the successors inhandlers, if appropriate, or continues to unwind via the unwind label ifpresent.

The catchswitch is both a terminator and a “pad” instruction, meaning thatit must be both the first non-phi instruction and last instruction in the basicblock. Therefore, it must be the only non-phi instruction in the block.

Example:
dispatch1:  %cs1 = catchswitch within none [label %handler0, label %handler1] unwind to callerdispatch2:  %cs2 = catchswitch within %parenthandler [label %handler0] unwind label %cleanup
`, + html: `

‘catchswitch’ Instruction

+
+
Syntax:
+
<resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind to caller
+<resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind label <default>
+
+
+
+
+
Overview:
+

The ‘catchswitch’ instruction is used by LLVM’s exception handling system to describe the set of possible catch handlers +that may be executed by the EH personality routine.

+
+
+
Arguments:
+

The parent argument is the token of the funclet that contains the +catchswitch instruction. If the catchswitch is not inside a funclet, +this operand may be the token none.

+

The default argument is the label of another basic block beginning with +either a cleanuppad or catchswitch instruction. This unwind destination +must be a legal target with respect to the parent links, as described in +the exception handling documentation.

+

The handlers are a nonempty list of successor blocks that each begin with a +catchpad instruction.

+
+
+
Semantics:
+

Executing this instruction transfers control to one of the successors in +handlers, if appropriate, or continues to unwind via the unwind label if +present.

+

The catchswitch is both a terminator and a “pad” instruction, meaning that +it must be both the first non-phi instruction and last instruction in the basic +block. Therefore, it must be the only non-phi instruction in the block.

+
+
+
Example:
+
dispatch1:
+  %cs1 = catchswitch within none [label %handler0, label %handler1] unwind to caller
+dispatch2:
+  %cs2 = catchswitch within %parenthandler [label %handler0] unwind label %cleanup
+
+
+
+`, tooltip: `The ‘catchswitch’ instruction is used by LLVM’s exception handling system to describe the set of possible catch handlersthat may be executed by the EH personality routine.`, }; case 'CATCHRET': return { url: `https://llvm.org/docs/LangRef.html#catchret-instruction`, - html: `

‘catchret’ Instruction

Syntax:
catchret from <token> to label <normal>
Overview:

The ‘catchret’ instruction is a terminator instruction that has asingle successor.

Arguments:

The first argument to a ‘catchret’ indicates which catchpad itexits. It must be a catchpad.The second argument to a ‘catchret’ specifies where control willtransfer to next.

Semantics:

The ‘catchret’ instruction ends an existing (in-flight) exception whoseunwinding was interrupted with a catchpad instruction. Thepersonality function gets a chance to execute arbitrarycode to, for example, destroy the active exception. Control then transfers tonormal.

The token argument must be a token produced by a catchpad instruction.If the specified catchpad is not the most-recently-entered not-yet-exitedfunclet pad (as described in the EH documentation),the catchret’s behavior is undefined.

Example:
catchret from %catch to label %continue
`, + html: `

‘catchret’ Instruction

+
+
Syntax:
+
catchret from <token> to label <normal>
+
+
+
+
+
Overview:
+

The ‘catchret’ instruction is a terminator instruction that has a +single successor.

+
+
+
Arguments:
+

The first argument to a ‘catchret’ indicates which catchpad it +exits. It must be a catchpad. +The second argument to a ‘catchret’ specifies where control will +transfer to next.

+
+
+
Semantics:
+

The ‘catchret’ instruction ends an existing (in-flight) exception whose +unwinding was interrupted with a catchpad instruction. The +personality function gets a chance to execute arbitrary +code to, for example, destroy the active exception. Control then transfers to +normal.

+

The token argument must be a token produced by a catchpad instruction. +If the specified catchpad is not the most-recently-entered not-yet-exited +funclet pad (as described in the EH documentation), +the catchret’s behavior is undefined.

+
+
+
Example:
+
catchret from %catch to label %continue
+
+
+
+`, tooltip: `The ‘catchret’ instruction is a terminator instruction that has asingle successor.`, }; case 'CLEANUPRET': return { url: `https://llvm.org/docs/LangRef.html#cleanupret-instruction`, - html: `

‘cleanupret’ Instruction

Syntax:
cleanupret from <value> unwind label <continue>cleanupret from <value> unwind to caller
Overview:

The ‘cleanupret’ instruction is a terminator instruction that hasan optional successor.

Arguments:

The ‘cleanupret’ instruction requires one argument, which indicateswhich cleanuppad it exits, and must be a cleanuppad.If the specified cleanuppad is not the most-recently-entered not-yet-exitedfunclet pad (as described in the EH documentation),the cleanupret’s behavior is undefined.

The ‘cleanupret’ instruction also has an optional successor, continue,which must be the label of another basic block beginning with either acleanuppad or catchswitch instruction. This unwind destination mustbe a legal target with respect to the parent links, as described in theexception handling documentation.

Semantics:

The ‘cleanupret’ instruction indicates to thepersonality function that onecleanuppad it transferred control to has ended.It transfers control to continue or unwinds out of the function.

Example:
cleanupret from %cleanup unwind to callercleanupret from %cleanup unwind label %continue
`, + html: `

‘cleanupret’ Instruction

+
+
Syntax:
+
cleanupret from <value> unwind label <continue>
+cleanupret from <value> unwind to caller
+
+
+
+
+
Overview:
+

The ‘cleanupret’ instruction is a terminator instruction that has +an optional successor.

+
+
+
Arguments:
+

The ‘cleanupret’ instruction requires one argument, which indicates +which cleanuppad it exits, and must be a cleanuppad. +If the specified cleanuppad is not the most-recently-entered not-yet-exited +funclet pad (as described in the EH documentation), +the cleanupret’s behavior is undefined.

+

The ‘cleanupret’ instruction also has an optional successor, continue, +which must be the label of another basic block beginning with either a +cleanuppad or catchswitch instruction. This unwind destination must +be a legal target with respect to the parent links, as described in the +exception handling documentation.

+
+
+
Semantics:
+

The ‘cleanupret’ instruction indicates to the +personality function that one +cleanuppad it transferred control to has ended. +It transfers control to continue or unwinds out of the function.

+
+
+
Example:
+
cleanupret from %cleanup unwind to caller
+cleanupret from %cleanup unwind label %continue
+
+
+
+`, tooltip: `The ‘cleanupret’ instruction is a terminator instruction that hasan optional successor.`, }; case 'UNREACHABLE': return { url: `https://llvm.org/docs/LangRef.html#unreachable-instruction`, - html: `

‘unreachable’ Instruction

Syntax:
unreachable
Overview:

The ‘unreachable’ instruction has no defined semantics. Thisinstruction is used to inform the optimizer that a particular portion ofthe code is not reachable. This can be used to indicate that the codeafter a no-return function cannot be reached, and other facts.

Semantics:

The ‘unreachable’ instruction has no defined semantics.

`, + html: `

‘unreachable’ Instruction

+
+
Syntax:
+
unreachable
+
+
+
+
+
Overview:
+

The ‘unreachable’ instruction has no defined semantics. This +instruction is used to inform the optimizer that a particular portion of +the code is not reachable. This can be used to indicate that the code +after a no-return function cannot be reached, and other facts.

+
+
+
Semantics:
+

The ‘unreachable’ instruction has no defined semantics.

+
+`, tooltip: `The ‘unreachable’ instruction has no defined semantics. Thisinstruction is used to inform the optimizer that a particular portion ofthe code is not reachable. This can be used to indicate that the codeafter a no-return function cannot be reached, and other facts.`, }; case 'FNEG': return { url: `https://llvm.org/docs/LangRef.html#fneg-instruction`, - html: `

‘fneg’ Instruction

Syntax:
<result> = fneg [fast-math flags]* <ty> <op1>   ; yields ty:result
Overview:

The ‘fneg’ instruction returns the negation of its operand.

Arguments:

The argument to the ‘fneg’ instruction must be afloating-point or vector offloating-point values.

Semantics:

The value produced is a copy of the operand with its sign bit flipped.The value is otherwise completely identical; in particular, if the input is aNaN, then the quiet/signaling bit and payload are perfectly preserved.

This instruction can also take any number of fast-mathflags, which are optimization hints to enable otherwiseunsafe floating-point optimizations:

Example:
<result> = fneg float %val          ; yields float:result = -%var
`, + html: `

‘fneg’ Instruction

+
+
Syntax:
+
<result> = fneg [fast-math flags]* <ty> <op1>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘fneg’ instruction returns the negation of its operand.

+
+
+
Arguments:
+

The argument to the ‘fneg’ instruction must be a +floating-point or vector of +floating-point values.

+
+
+
Semantics:
+

The value produced is a copy of the operand with its sign bit flipped. +The value is otherwise completely identical; in particular, if the input is a +NaN, then the quiet/signaling bit and payload are perfectly preserved.

+

This instruction can also take any number of fast-math +flags, which are optimization hints to enable otherwise +unsafe floating-point optimizations:

+
+
+
Example:
+
<result> = fneg float %val          ; yields float:result = -%var
+
+
+
+`, tooltip: `The ‘fneg’ instruction returns the negation of its operand.`, }; case 'ADD': return { url: `https://llvm.org/docs/LangRef.html#add-instruction`, - html: `

‘add’ Instruction

Syntax:
<result> = add <ty> <op1>, <op2>          ; yields ty:result<result> = add nuw <ty> <op1>, <op2>      ; yields ty:result<result> = add nsw <ty> <op1>, <op2>      ; yields ty:result<result> = add nuw nsw <ty> <op1>, <op2>  ; yields ty:result
Overview:

The ‘add’ instruction returns the sum of its two operands.

Arguments:

The two arguments to the ‘add’ instruction must beinteger or vector of integer values. Botharguments must have identical types.

Semantics:

The value produced is the integer sum of the two operands.

If the sum has unsigned overflow, the result returned is themathematical result modulo 2n, where n is the bit width ofthe result.

Because LLVM integers use a two’s complement representation, thisinstruction is appropriate for both signed and unsigned integers.

nuw and nsw stand for “No Unsigned Wrap” and “No Signed Wrap”,respectively. If the nuw and/or nsw keywords are present, theresult value of the add is a poison value ifunsigned and/or signed overflow, respectively, occurs.

Example:
<result> = add i32 4, %var          ; yields i32:result = 4 + %var
`, + html: `

‘add’ Instruction

+
+
Syntax:
+
<result> = add <ty> <op1>, <op2>          ; yields ty:result
+<result> = add nuw <ty> <op1>, <op2>      ; yields ty:result
+<result> = add nsw <ty> <op1>, <op2>      ; yields ty:result
+<result> = add nuw nsw <ty> <op1>, <op2>  ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘add’ instruction returns the sum of its two operands.

+
+
+
Arguments:
+

The two arguments to the ‘add’ instruction must be +integer or vector of integer values. Both +arguments must have identical types.

+
+
+
Semantics:
+

The value produced is the integer sum of the two operands.

+

If the sum has unsigned overflow, the result returned is the +mathematical result modulo 2n, where n is the bit width of +the result.

+

Because LLVM integers use a two’s complement representation, this +instruction is appropriate for both signed and unsigned integers.

+

nuw and nsw stand for “No Unsigned Wrap” and “No Signed Wrap”, +respectively. If the nuw and/or nsw keywords are present, the +result value of the add is a poison value if +unsigned and/or signed overflow, respectively, occurs.

+
+
+
Example:
+
<result> = add i32 4, %var          ; yields i32:result = 4 + %var
+
+
+
+`, tooltip: `The ‘add’ instruction returns the sum of its two operands.`, }; case 'FADD': return { url: `https://llvm.org/docs/LangRef.html#fadd-instruction`, - html: `

‘fadd’ Instruction

Syntax:
<result> = fadd [fast-math flags]* <ty> <op1>, <op2>   ; yields ty:result
Overview:

The ‘fadd’ instruction returns the sum of its two operands.

Arguments:

The two arguments to the ‘fadd’ instruction must befloating-point or vector offloating-point values. Both arguments must have identical types.

Semantics:

The value produced is the floating-point sum of the two operands.This instruction is assumed to execute in the default floating-pointenvironment.This instruction can also take any number of fast-mathflags, which are optimization hints to enable otherwiseunsafe floating-point optimizations:

Example:
<result> = fadd float 4.0, %var          ; yields float:result = 4.0 + %var
`, + html: `

‘fadd’ Instruction

+
+
Syntax:
+
<result> = fadd [fast-math flags]* <ty> <op1>, <op2>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘fadd’ instruction returns the sum of its two operands.

+
+
+
Arguments:
+

The two arguments to the ‘fadd’ instruction must be +floating-point or vector of +floating-point values. Both arguments must have identical types.

+
+
+
Semantics:
+

The value produced is the floating-point sum of the two operands. +This instruction is assumed to execute in the default floating-point +environment. +This instruction can also take any number of fast-math +flags, which are optimization hints to enable otherwise +unsafe floating-point optimizations:

+
+
+
Example:
+
<result> = fadd float 4.0, %var          ; yields float:result = 4.0 + %var
+
+
+
+`, tooltip: `The ‘fadd’ instruction returns the sum of its two operands.`, }; case 'SUB': return { url: `https://llvm.org/docs/LangRef.html#sub-instruction`, - html: `

‘sub’ Instruction

Syntax:
<result> = sub <ty> <op1>, <op2>          ; yields ty:result<result> = sub nuw <ty> <op1>, <op2>      ; yields ty:result<result> = sub nsw <ty> <op1>, <op2>      ; yields ty:result<result> = sub nuw nsw <ty> <op1>, <op2>  ; yields ty:result
Overview:

The ‘sub’ instruction returns the difference of its two operands.

Note that the ‘sub’ instruction is used to represent the ‘neg’instruction present in most other intermediate representations.

Arguments:

The two arguments to the ‘sub’ instruction must beinteger or vector of integer values. Botharguments must have identical types.

Semantics:

The value produced is the integer difference of the two operands.

If the difference has unsigned overflow, the result returned is themathematical result modulo 2n, where n is the bit width ofthe result.

Because LLVM integers use a two’s complement representation, thisinstruction is appropriate for both signed and unsigned integers.

nuw and nsw stand for “No Unsigned Wrap” and “No Signed Wrap”,respectively. If the nuw and/or nsw keywords are present, theresult value of the sub is a poison value ifunsigned and/or signed overflow, respectively, occurs.

Example:
<result> = sub i32 4, %var          ; yields i32:result = 4 - %var<result> = sub i32 0, %val          ; yields i32:result = -%var
`, + html: `

‘sub’ Instruction

+
+
Syntax:
+
<result> = sub <ty> <op1>, <op2>          ; yields ty:result
+<result> = sub nuw <ty> <op1>, <op2>      ; yields ty:result
+<result> = sub nsw <ty> <op1>, <op2>      ; yields ty:result
+<result> = sub nuw nsw <ty> <op1>, <op2>  ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘sub’ instruction returns the difference of its two operands.

+

Note that the ‘sub’ instruction is used to represent the ‘neg’ +instruction present in most other intermediate representations.

+
+
+
Arguments:
+

The two arguments to the ‘sub’ instruction must be +integer or vector of integer values. Both +arguments must have identical types.

+
+
+
Semantics:
+

The value produced is the integer difference of the two operands.

+

If the difference has unsigned overflow, the result returned is the +mathematical result modulo 2n, where n is the bit width of +the result.

+

Because LLVM integers use a two’s complement representation, this +instruction is appropriate for both signed and unsigned integers.

+

nuw and nsw stand for “No Unsigned Wrap” and “No Signed Wrap”, +respectively. If the nuw and/or nsw keywords are present, the +result value of the sub is a poison value if +unsigned and/or signed overflow, respectively, occurs.

+
+
+
Example:
+
<result> = sub i32 4, %var          ; yields i32:result = 4 - %var
+<result> = sub i32 0, %val          ; yields i32:result = -%var
+
+
+
+`, tooltip: `The ‘sub’ instruction returns the difference of its two operands.Note that the ‘sub’ instruction is used to represent the ‘neg’instruction present in most other intermediate representations.`, }; case 'FSUB': return { url: `https://llvm.org/docs/LangRef.html#fsub-instruction`, - html: `

‘fsub’ Instruction

Syntax:
<result> = fsub [fast-math flags]* <ty> <op1>, <op2>   ; yields ty:result
Overview:

The ‘fsub’ instruction returns the difference of its two operands.

Arguments:

The two arguments to the ‘fsub’ instruction must befloating-point or vector offloating-point values. Both arguments must have identical types.

Semantics:

The value produced is the floating-point difference of the two operands.This instruction is assumed to execute in the default floating-pointenvironment.This instruction can also take any number of fast-mathflags, which are optimization hints to enable otherwiseunsafe floating-point optimizations:

Example:
<result> = fsub float 4.0, %var           ; yields float:result = 4.0 - %var<result> = fsub float -0.0, %val          ; yields float:result = -%var
`, + html: `

‘fsub’ Instruction

+
+
Syntax:
+
<result> = fsub [fast-math flags]* <ty> <op1>, <op2>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘fsub’ instruction returns the difference of its two operands.

+
+
+
Arguments:
+

The two arguments to the ‘fsub’ instruction must be +floating-point or vector of +floating-point values. Both arguments must have identical types.

+
+
+
Semantics:
+

The value produced is the floating-point difference of the two operands. +This instruction is assumed to execute in the default floating-point +environment. +This instruction can also take any number of fast-math +flags, which are optimization hints to enable otherwise +unsafe floating-point optimizations:

+
+
+
Example:
+
<result> = fsub float 4.0, %var           ; yields float:result = 4.0 - %var
+<result> = fsub float -0.0, %val          ; yields float:result = -%var
+
+
+
+`, tooltip: `The ‘fsub’ instruction returns the difference of its two operands.`, }; case 'MUL': return { url: `https://llvm.org/docs/LangRef.html#mul-instruction`, - html: `

‘mul’ Instruction

Syntax:
<result> = mul <ty> <op1>, <op2>          ; yields ty:result<result> = mul nuw <ty> <op1>, <op2>      ; yields ty:result<result> = mul nsw <ty> <op1>, <op2>      ; yields ty:result<result> = mul nuw nsw <ty> <op1>, <op2>  ; yields ty:result
Overview:

The ‘mul’ instruction returns the product of its two operands.

Arguments:

The two arguments to the ‘mul’ instruction must beinteger or vector of integer values. Botharguments must have identical types.

Semantics:

The value produced is the integer product of the two operands.

If the result of the multiplication has unsigned overflow, the resultreturned is the mathematical result modulo 2n, where n is thebit width of the result.

Because LLVM integers use a two’s complement representation, and theresult is the same width as the operands, this instruction returns thecorrect result for both signed and unsigned integers. If a full product(e.g., i32 * i32 -> i64) is needed, the operands should besign-extended or zero-extended as appropriate to the width of the fullproduct.

nuw and nsw stand for “No Unsigned Wrap” and “No Signed Wrap”,respectively. If the nuw and/or nsw keywords are present, theresult value of the mul is a poison value ifunsigned and/or signed overflow, respectively, occurs.

Example:
<result> = mul i32 4, %var          ; yields i32:result = 4 * %var
`, + html: `

‘mul’ Instruction

+
+
Syntax:
+
<result> = mul <ty> <op1>, <op2>          ; yields ty:result
+<result> = mul nuw <ty> <op1>, <op2>      ; yields ty:result
+<result> = mul nsw <ty> <op1>, <op2>      ; yields ty:result
+<result> = mul nuw nsw <ty> <op1>, <op2>  ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘mul’ instruction returns the product of its two operands.

+
+
+
Arguments:
+

The two arguments to the ‘mul’ instruction must be +integer or vector of integer values. Both +arguments must have identical types.

+
+
+
Semantics:
+

The value produced is the integer product of the two operands.

+

If the result of the multiplication has unsigned overflow, the result +returned is the mathematical result modulo 2n, where n is the +bit width of the result.

+

Because LLVM integers use a two’s complement representation, and the +result is the same width as the operands, this instruction returns the +correct result for both signed and unsigned integers. If a full product +(e.g., i32 * i32 -> i64) is needed, the operands should be +sign-extended or zero-extended as appropriate to the width of the full +product.

+

nuw and nsw stand for “No Unsigned Wrap” and “No Signed Wrap”, +respectively. If the nuw and/or nsw keywords are present, the +result value of the mul is a poison value if +unsigned and/or signed overflow, respectively, occurs.

+
+
+
Example:
+
<result> = mul i32 4, %var          ; yields i32:result = 4 * %var
+
+
+
+`, tooltip: `The ‘mul’ instruction returns the product of its two operands.`, }; case 'FMUL': return { url: `https://llvm.org/docs/LangRef.html#fmul-instruction`, - html: `

‘fmul’ Instruction

Syntax:
<result> = fmul [fast-math flags]* <ty> <op1>, <op2>   ; yields ty:result
Overview:

The ‘fmul’ instruction returns the product of its two operands.

Arguments:

The two arguments to the ‘fmul’ instruction must befloating-point or vector offloating-point values. Both arguments must have identical types.

Semantics:

The value produced is the floating-point product of the two operands.This instruction is assumed to execute in the default floating-pointenvironment.This instruction can also take any number of fast-mathflags, which are optimization hints to enable otherwiseunsafe floating-point optimizations:

Example:
<result> = fmul float 4.0, %var          ; yields float:result = 4.0 * %var
`, + html: `

‘fmul’ Instruction

+
+
Syntax:
+
<result> = fmul [fast-math flags]* <ty> <op1>, <op2>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘fmul’ instruction returns the product of its two operands.

+
+
+
Arguments:
+

The two arguments to the ‘fmul’ instruction must be +floating-point or vector of +floating-point values. Both arguments must have identical types.

+
+
+
Semantics:
+

The value produced is the floating-point product of the two operands. +This instruction is assumed to execute in the default floating-point +environment. +This instruction can also take any number of fast-math +flags, which are optimization hints to enable otherwise +unsafe floating-point optimizations:

+
+
+
Example:
+
<result> = fmul float 4.0, %var          ; yields float:result = 4.0 * %var
+
+
+
+`, tooltip: `The ‘fmul’ instruction returns the product of its two operands.`, }; case 'UDIV': return { url: `https://llvm.org/docs/LangRef.html#udiv-instruction`, - html: `

‘udiv’ Instruction

Syntax:
<result> = udiv <ty> <op1>, <op2>         ; yields ty:result<result> = udiv exact <ty> <op1>, <op2>   ; yields ty:result
Overview:

The ‘udiv’ instruction returns the quotient of its two operands.

Arguments:

The two arguments to the ‘udiv’ instruction must beinteger or vector of integer values. Botharguments must have identical types.

Semantics:

The value produced is the unsigned integer quotient of the two operands.

Note that unsigned integer division and signed integer division aredistinct operations; for signed integer division, use ‘sdiv’.

Division by zero is undefined behavior. For vectors, if any elementof the divisor is zero, the operation has undefined behavior.

If the exact keyword is present, the result value of the udiv isa poison value if %op1 is not a multiple of %op2 (assuch, “((a udiv exact b) mul b) == a”).

Example:
<result> = udiv i32 4, %var          ; yields i32:result = 4 / %var
`, + html: `

‘udiv’ Instruction

+
+
Syntax:
+
<result> = udiv <ty> <op1>, <op2>         ; yields ty:result
+<result> = udiv exact <ty> <op1>, <op2>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘udiv’ instruction returns the quotient of its two operands.

+
+
+
Arguments:
+

The two arguments to the ‘udiv’ instruction must be +integer or vector of integer values. Both +arguments must have identical types.

+
+
+
Semantics:
+

The value produced is the unsigned integer quotient of the two operands.

+

Note that unsigned integer division and signed integer division are +distinct operations; for signed integer division, use ‘sdiv’.

+

Division by zero is undefined behavior. For vectors, if any element +of the divisor is zero, the operation has undefined behavior.

+

If the exact keyword is present, the result value of the udiv is +a poison value if %op1 is not a multiple of %op2 (as +such, “((a udiv exact b) mul b) == a”).

+
+
+
Example:
+
<result> = udiv i32 4, %var          ; yields i32:result = 4 / %var
+
+
+
+`, tooltip: `The ‘udiv’ instruction returns the quotient of its two operands.`, }; case 'SDIV': return { url: `https://llvm.org/docs/LangRef.html#sdiv-instruction`, - html: `

‘sdiv’ Instruction

Syntax:
<result> = sdiv <ty> <op1>, <op2>         ; yields ty:result<result> = sdiv exact <ty> <op1>, <op2>   ; yields ty:result
Overview:

The ‘sdiv’ instruction returns the quotient of its two operands.

Arguments:

The two arguments to the ‘sdiv’ instruction must beinteger or vector of integer values. Botharguments must have identical types.

Semantics:

The value produced is the signed integer quotient of the two operandsrounded towards zero.

Note that signed integer division and unsigned integer division aredistinct operations; for unsigned integer division, use ‘udiv’.

Division by zero is undefined behavior. For vectors, if any elementof the divisor is zero, the operation has undefined behavior.Overflow also leads to undefined behavior; this is a rare case, but canoccur, for example, by doing a 32-bit division of -2147483648 by -1.

If the exact keyword is present, the result value of the sdiv isa poison value if the result would be rounded.

Example:
<result> = sdiv i32 4, %var          ; yields i32:result = 4 / %var
`, + html: `

‘sdiv’ Instruction

+
+
Syntax:
+
<result> = sdiv <ty> <op1>, <op2>         ; yields ty:result
+<result> = sdiv exact <ty> <op1>, <op2>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘sdiv’ instruction returns the quotient of its two operands.

+
+
+
Arguments:
+

The two arguments to the ‘sdiv’ instruction must be +integer or vector of integer values. Both +arguments must have identical types.

+
+
+
Semantics:
+

The value produced is the signed integer quotient of the two operands +rounded towards zero.

+

Note that signed integer division and unsigned integer division are +distinct operations; for unsigned integer division, use ‘udiv’.

+

Division by zero is undefined behavior. For vectors, if any element +of the divisor is zero, the operation has undefined behavior. +Overflow also leads to undefined behavior; this is a rare case, but can +occur, for example, by doing a 32-bit division of -2147483648 by -1.

+

If the exact keyword is present, the result value of the sdiv is +a poison value if the result would be rounded.

+
+
+
Example:
+
<result> = sdiv i32 4, %var          ; yields i32:result = 4 / %var
+
+
+
+`, tooltip: `The ‘sdiv’ instruction returns the quotient of its two operands.`, }; case 'FDIV': return { url: `https://llvm.org/docs/LangRef.html#fdiv-instruction`, - html: `

‘fdiv’ Instruction

Syntax:
<result> = fdiv [fast-math flags]* <ty> <op1>, <op2>   ; yields ty:result
Overview:

The ‘fdiv’ instruction returns the quotient of its two operands.

Arguments:

The two arguments to the ‘fdiv’ instruction must befloating-point or vector offloating-point values. Both arguments must have identical types.

Semantics:

The value produced is the floating-point quotient of the two operands.This instruction is assumed to execute in the default floating-pointenvironment.This instruction can also take any number of fast-mathflags, which are optimization hints to enable otherwiseunsafe floating-point optimizations:

Example:
<result> = fdiv float 4.0, %var          ; yields float:result = 4.0 / %var
`, + html: `

‘fdiv’ Instruction

+
+
Syntax:
+
<result> = fdiv [fast-math flags]* <ty> <op1>, <op2>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘fdiv’ instruction returns the quotient of its two operands.

+
+
+
Arguments:
+

The two arguments to the ‘fdiv’ instruction must be +floating-point or vector of +floating-point values. Both arguments must have identical types.

+
+
+
Semantics:
+

The value produced is the floating-point quotient of the two operands. +This instruction is assumed to execute in the default floating-point +environment. +This instruction can also take any number of fast-math +flags, which are optimization hints to enable otherwise +unsafe floating-point optimizations:

+
+
+
Example:
+
<result> = fdiv float 4.0, %var          ; yields float:result = 4.0 / %var
+
+
+
+`, tooltip: `The ‘fdiv’ instruction returns the quotient of its two operands.`, }; case 'UREM': return { url: `https://llvm.org/docs/LangRef.html#urem-instruction`, - html: `

‘urem’ Instruction

Syntax:
<result> = urem <ty> <op1>, <op2>   ; yields ty:result
Overview:

The ‘urem’ instruction returns the remainder from the unsigneddivision of its two arguments.

Arguments:

The two arguments to the ‘urem’ instruction must beinteger or vector of integer values. Botharguments must have identical types.

Semantics:

This instruction returns the unsigned integer remainder of a division.This instruction always performs an unsigned division to get theremainder.

Note that unsigned integer remainder and signed integer remainder aredistinct operations; for signed integer remainder, use ‘srem’.

Taking the remainder of a division by zero is undefined behavior.For vectors, if any element of the divisor is zero, the operation hasundefined behavior.

Example:
<result> = urem i32 4, %var          ; yields i32:result = 4 % %var
`, + html: `

‘urem’ Instruction

+
+
Syntax:
+
<result> = urem <ty> <op1>, <op2>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘urem’ instruction returns the remainder from the unsigned +division of its two arguments.

+
+
+
Arguments:
+

The two arguments to the ‘urem’ instruction must be +integer or vector of integer values. Both +arguments must have identical types.

+
+
+
Semantics:
+

This instruction returns the unsigned integer remainder of a division. +This instruction always performs an unsigned division to get the +remainder.

+

Note that unsigned integer remainder and signed integer remainder are +distinct operations; for signed integer remainder, use ‘srem’.

+

Taking the remainder of a division by zero is undefined behavior. +For vectors, if any element of the divisor is zero, the operation has +undefined behavior.

+
+
+
Example:
+
<result> = urem i32 4, %var          ; yields i32:result = 4 % %var
+
+
+
+`, tooltip: `The ‘urem’ instruction returns the remainder from the unsigneddivision of its two arguments.`, }; case 'SREM': return { url: `https://llvm.org/docs/LangRef.html#srem-instruction`, - html: `

‘srem’ Instruction

Syntax:
<result> = srem <ty> <op1>, <op2>   ; yields ty:result
Overview:

The ‘srem’ instruction returns the remainder from the signeddivision of its two operands. This instruction can also takevector versions of the values in which case the elementsmust be integers.

Arguments:

The two arguments to the ‘srem’ instruction must beinteger or vector of integer values. Botharguments must have identical types.

Semantics:

This instruction returns the remainder of a division (where the resultis either zero or has the same sign as the dividend, op1), not themodulo operator (where the result is either zero or has the same signas the divisor, op2) of a value. For more information about thedifference, see The MathForum. For atable of how this is implemented in various languages, please seeWikipedia: modulooperation.

Note that signed integer remainder and unsigned integer remainder aredistinct operations; for unsigned integer remainder, use ‘urem’.

Taking the remainder of a division by zero is undefined behavior.For vectors, if any element of the divisor is zero, the operation hasundefined behavior.Overflow also leads to undefined behavior; this is a rare case, but canoccur, for example, by taking the remainder of a 32-bit division of-2147483648 by -1. (The remainder doesn’t actually overflow, but thisrule lets srem be implemented using instructions that return both theresult of the division and the remainder.)

Example:
<result> = srem i32 4, %var          ; yields i32:result = 4 % %var
`, + html: `

‘srem’ Instruction

+
+
Syntax:
+
<result> = srem <ty> <op1>, <op2>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘srem’ instruction returns the remainder from the signed +division of its two operands. This instruction can also take +vector versions of the values in which case the elements +must be integers.

+
+
+
Arguments:
+

The two arguments to the ‘srem’ instruction must be +integer or vector of integer values. Both +arguments must have identical types.

+
+
+
Semantics:
+

This instruction returns the remainder of a division (where the result +is either zero or has the same sign as the dividend, op1), not the +modulo operator (where the result is either zero or has the same sign +as the divisor, op2) of a value. For more information about the +difference, see The Math +Forum. For a +table of how this is implemented in various languages, please see +Wikipedia: modulo +operation.

+

Note that signed integer remainder and unsigned integer remainder are +distinct operations; for unsigned integer remainder, use ‘urem’.

+

Taking the remainder of a division by zero is undefined behavior. +For vectors, if any element of the divisor is zero, the operation has +undefined behavior. +Overflow also leads to undefined behavior; this is a rare case, but can +occur, for example, by taking the remainder of a 32-bit division of +-2147483648 by -1. (The remainder doesn’t actually overflow, but this +rule lets srem be implemented using instructions that return both the +result of the division and the remainder.)

+
+
+
Example:
+
<result> = srem i32 4, %var          ; yields i32:result = 4 % %var
+
+
+
+`, tooltip: `The ‘srem’ instruction returns the remainder from the signeddivision of its two operands. This instruction can also takevector versions of the values in which case the elementsmust be integers.`, }; case 'FREM': return { url: `https://llvm.org/docs/LangRef.html#frem-instruction`, - html: `

‘frem’ Instruction

Syntax:
<result> = frem [fast-math flags]* <ty> <op1>, <op2>   ; yields ty:result
Overview:

The ‘frem’ instruction returns the remainder from the division ofits two operands.

Note

The instruction is implemented as a call to libm’s ‘fmod’for some targets, and using the instruction may thus require linking libm.

Arguments:

The two arguments to the ‘frem’ instruction must befloating-point or vector offloating-point values. Both arguments must have identical types.

Semantics:

The value produced is the floating-point remainder of the two operands.This is the same output as a libm ‘fmod’ function, but without anypossibility of setting errno. The remainder has the same sign as thedividend.This instruction is assumed to execute in the default floating-pointenvironment.This instruction can also take any number of fast-mathflags, which are optimization hints to enable otherwiseunsafe floating-point optimizations:

Example:
<result> = frem float 4.0, %var          ; yields float:result = 4.0 % %var
`, + html: `

‘frem’ Instruction

+
+
Syntax:
+
<result> = frem [fast-math flags]* <ty> <op1>, <op2>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘frem’ instruction returns the remainder from the division of +its two operands.

+
+

Note

+

The instruction is implemented as a call to libm’s ‘fmod’ +for some targets, and using the instruction may thus require linking libm.

+
+
+
+
Arguments:
+

The two arguments to the ‘frem’ instruction must be +floating-point or vector of +floating-point values. Both arguments must have identical types.

+
+
+
Semantics:
+

The value produced is the floating-point remainder of the two operands. +This is the same output as a libm ‘fmod’ function, but without any +possibility of setting errno. The remainder has the same sign as the +dividend. +This instruction is assumed to execute in the default floating-point +environment. +This instruction can also take any number of fast-math +flags, which are optimization hints to enable otherwise +unsafe floating-point optimizations:

+
+
+
Example:
+
<result> = frem float 4.0, %var          ; yields float:result = 4.0 % %var
+
+
+
+`, tooltip: `The ‘frem’ instruction returns the remainder from the division ofits two operands.`, }; case 'SHL': return { url: `https://llvm.org/docs/LangRef.html#shl-instruction`, - html: `

‘shl’ Instruction

Syntax:
<result> = shl <ty> <op1>, <op2>           ; yields ty:result<result> = shl nuw <ty> <op1>, <op2>       ; yields ty:result<result> = shl nsw <ty> <op1>, <op2>       ; yields ty:result<result> = shl nuw nsw <ty> <op1>, <op2>   ; yields ty:result
Overview:

The ‘shl’ instruction returns the first operand shifted to the lefta specified number of bits.

Arguments:

Both arguments to the ‘shl’ instruction must be the sameinteger or vector of integer type.‘op2’ is treated as an unsigned value.

Semantics:

The value produced is op1 * 2op2 mod 2n,where n is the width of the result. If op2 is (statically ordynamically) equal to or larger than the number of bits inop1, this instruction returns a poison value.If the arguments are vectors, each vector element of op1 is shiftedby the corresponding shift amount in op2.

If the nuw keyword is present, then the shift produces a poisonvalue if it shifts out any non-zero bits.If the nsw keyword is present, then the shift produces a poisonvalue if it shifts out any bits that disagree with the resultant sign bit.

Example:
<result> = shl i32 4, %var   ; yields i32: 4 << %var<result> = shl i32 4, 2      ; yields i32: 16<result> = shl i32 1, 10     ; yields i32: 1024<result> = shl i32 1, 32     ; undefined<result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2>   ; yields: result=<2 x i32> < i32 2, i32 4>
`, + html: `

‘shl’ Instruction

+
+
Syntax:
+
<result> = shl <ty> <op1>, <op2>           ; yields ty:result
+<result> = shl nuw <ty> <op1>, <op2>       ; yields ty:result
+<result> = shl nsw <ty> <op1>, <op2>       ; yields ty:result
+<result> = shl nuw nsw <ty> <op1>, <op2>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘shl’ instruction returns the first operand shifted to the left +a specified number of bits.

+
+
+
Arguments:
+

Both arguments to the ‘shl’ instruction must be the same +integer or vector of integer type. +‘op2’ is treated as an unsigned value.

+
+
+
Semantics:
+

The value produced is op1 * 2op2 mod 2n, +where n is the width of the result. If op2 is (statically or +dynamically) equal to or larger than the number of bits in +op1, this instruction returns a poison value. +If the arguments are vectors, each vector element of op1 is shifted +by the corresponding shift amount in op2.

+

If the nuw keyword is present, then the shift produces a poison +value if it shifts out any non-zero bits. +If the nsw keyword is present, then the shift produces a poison +value if it shifts out any bits that disagree with the resultant sign bit.

+
+
+
Example:
+
<result> = shl i32 4, %var   ; yields i32: 4 << %var
+<result> = shl i32 4, 2      ; yields i32: 16
+<result> = shl i32 1, 10     ; yields i32: 1024
+<result> = shl i32 1, 32     ; undefined
+<result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2>   ; yields: result=<2 x i32> < i32 2, i32 4>
+
+
+
+`, tooltip: `The ‘shl’ instruction returns the first operand shifted to the lefta specified number of bits.`, }; case 'LSHR': return { url: `https://llvm.org/docs/LangRef.html#lshr-instruction`, - html: `

‘lshr’ Instruction

Syntax:
<result> = lshr <ty> <op1>, <op2>         ; yields ty:result<result> = lshr exact <ty> <op1>, <op2>   ; yields ty:result
Overview:

The ‘lshr’ instruction (logical shift right) returns the firstoperand shifted to the right a specified number of bits with zero fill.

Arguments:

Both arguments to the ‘lshr’ instruction must be the sameinteger or vector of integer type.‘op2’ is treated as an unsigned value.

Semantics:

This instruction always performs a logical shift right operation. Themost significant bits of the result will be filled with zero bits afterthe shift. If op2 is (statically or dynamically) equal to or largerthan the number of bits in op1, this instruction returns a poisonvalue. If the arguments are vectors, each vector elementof op1 is shifted by the corresponding shift amount in op2.

If the exact keyword is present, the result value of the lshr isa poison value if any of the bits shifted out are non-zero.

Example:
<result> = lshr i32 4, 1   ; yields i32:result = 2<result> = lshr i32 4, 2   ; yields i32:result = 1<result> = lshr i8  4, 3   ; yields i8:result = 0<result> = lshr i8 -2, 1   ; yields i8:result = 0x7F<result> = lshr i32 1, 32  ; undefined<result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2>   ; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1>
`, + html: `

‘lshr’ Instruction

+
+
Syntax:
+
<result> = lshr <ty> <op1>, <op2>         ; yields ty:result
+<result> = lshr exact <ty> <op1>, <op2>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘lshr’ instruction (logical shift right) returns the first +operand shifted to the right a specified number of bits with zero fill.

+
+
+
Arguments:
+

Both arguments to the ‘lshr’ instruction must be the same +integer or vector of integer type. +‘op2’ is treated as an unsigned value.

+
+
+
Semantics:
+

This instruction always performs a logical shift right operation. The +most significant bits of the result will be filled with zero bits after +the shift. If op2 is (statically or dynamically) equal to or larger +than the number of bits in op1, this instruction returns a poison +value. If the arguments are vectors, each vector element +of op1 is shifted by the corresponding shift amount in op2.

+

If the exact keyword is present, the result value of the lshr is +a poison value if any of the bits shifted out are non-zero.

+
+
+
Example:
+
<result> = lshr i32 4, 1   ; yields i32:result = 2
+<result> = lshr i32 4, 2   ; yields i32:result = 1
+<result> = lshr i8  4, 3   ; yields i8:result = 0
+<result> = lshr i8 -2, 1   ; yields i8:result = 0x7F
+<result> = lshr i32 1, 32  ; undefined
+<result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2>   ; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1>
+
+
+
+`, tooltip: `The ‘lshr’ instruction (logical shift right) returns the firstoperand shifted to the right a specified number of bits with zero fill.`, }; case 'ASHR': return { url: `https://llvm.org/docs/LangRef.html#ashr-instruction`, - html: `

‘ashr’ Instruction

Syntax:
<result> = ashr <ty> <op1>, <op2>         ; yields ty:result<result> = ashr exact <ty> <op1>, <op2>   ; yields ty:result
Overview:

The ‘ashr’ instruction (arithmetic shift right) returns the firstoperand shifted to the right a specified number of bits with signextension.

Arguments:

Both arguments to the ‘ashr’ instruction must be the sameinteger or vector of integer type.‘op2’ is treated as an unsigned value.

Semantics:

This instruction always performs an arithmetic shift right operation,The most significant bits of the result will be filled with the sign bitof op1. If op2 is (statically or dynamically) equal to or largerthan the number of bits in op1, this instruction returns a poisonvalue. If the arguments are vectors, each vector elementof op1 is shifted by the corresponding shift amount in op2.

If the exact keyword is present, the result value of the ashr isa poison value if any of the bits shifted out are non-zero.

Example:
<result> = ashr i32 4, 1   ; yields i32:result = 2<result> = ashr i32 4, 2   ; yields i32:result = 1<result> = ashr i8  4, 3   ; yields i8:result = 0<result> = ashr i8 -2, 1   ; yields i8:result = -1<result> = ashr i32 1, 32  ; undefined<result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3>   ; yields: result=<2 x i32> < i32 -1, i32 0>
`, + html: `

‘ashr’ Instruction

+
+
Syntax:
+
<result> = ashr <ty> <op1>, <op2>         ; yields ty:result
+<result> = ashr exact <ty> <op1>, <op2>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘ashr’ instruction (arithmetic shift right) returns the first +operand shifted to the right a specified number of bits with sign +extension.

+
+
+
Arguments:
+

Both arguments to the ‘ashr’ instruction must be the same +integer or vector of integer type. +‘op2’ is treated as an unsigned value.

+
+
+
Semantics:
+

This instruction always performs an arithmetic shift right operation, +The most significant bits of the result will be filled with the sign bit +of op1. If op2 is (statically or dynamically) equal to or larger +than the number of bits in op1, this instruction returns a poison +value. If the arguments are vectors, each vector element +of op1 is shifted by the corresponding shift amount in op2.

+

If the exact keyword is present, the result value of the ashr is +a poison value if any of the bits shifted out are non-zero.

+
+
+
Example:
+
<result> = ashr i32 4, 1   ; yields i32:result = 2
+<result> = ashr i32 4, 2   ; yields i32:result = 1
+<result> = ashr i8  4, 3   ; yields i8:result = 0
+<result> = ashr i8 -2, 1   ; yields i8:result = -1
+<result> = ashr i32 1, 32  ; undefined
+<result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3>   ; yields: result=<2 x i32> < i32 -1, i32 0>
+
+
+
+`, tooltip: `The ‘ashr’ instruction (arithmetic shift right) returns the firstoperand shifted to the right a specified number of bits with signextension.`, }; case 'AND': return { url: `https://llvm.org/docs/LangRef.html#and-instruction`, - html: `

‘and’ Instruction

Syntax:
<result> = and <ty> <op1>, <op2>   ; yields ty:result
Overview:

The ‘and’ instruction returns the bitwise logical and of its twooperands.

Arguments:

The two arguments to the ‘and’ instruction must beinteger or vector of integer values. Botharguments must have identical types.

Semantics:

The truth table used for the ‘and’ instruction is:

In0

In1

Out

0

0

0

0

1

0

1

0

0

1

1

1

Example:
<result> = and i32 4, %var         ; yields i32:result = 4 & %var<result> = and i32 15, 40          ; yields i32:result = 8<result> = and i32 4, 8            ; yields i32:result = 0
`, + html: `

‘and’ Instruction

+
+
Syntax:
+
<result> = and <ty> <op1>, <op2>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘and’ instruction returns the bitwise logical and of its two +operands.

+
+
+
Arguments:
+

The two arguments to the ‘and’ instruction must be +integer or vector of integer values. Both +arguments must have identical types.

+
+
+
Semantics:
+

The truth table used for the ‘and’ instruction is:

+ + + + + + + + + + + + + + + + + + + + + + + +

In0

In1

Out

0

0

0

0

1

0

1

0

0

1

1

1

+
+
+
Example:
+
<result> = and i32 4, %var         ; yields i32:result = 4 & %var
+<result> = and i32 15, 40          ; yields i32:result = 8
+<result> = and i32 4, 8            ; yields i32:result = 0
+
+
+
+`, tooltip: `The ‘and’ instruction returns the bitwise logical and of its twooperands.`, }; case 'OR': return { url: `https://llvm.org/docs/LangRef.html#or-instruction`, - html: `

‘or’ Instruction

Syntax:
<result> = or <ty> <op1>, <op2>   ; yields ty:result<result> = or disjoint <ty> <op1>, <op2>   ; yields ty:result
Overview:

The ‘or’ instruction returns the bitwise logical inclusive or of itstwo operands.

Arguments:

The two arguments to the ‘or’ instruction must beinteger or vector of integer values. Botharguments must have identical types.

Semantics:

The truth table used for the ‘or’ instruction is:

In0

In1

Out

0

0

0

0

1

1

1

0

1

1

1

1

disjoint means that for each bit, that bit is zero in at least one of theinputs. This allows the Or to be treated as an Add since no carry can occur fromany bit. If the disjoint keyword is present, the result value of the or is apoison value if both inputs have a one in the same bitposition. For vectors, only the element containing the bit is poison.

Example:
<result> = or i32 4, %var         ; yields i32:result = 4 | %var<result> = or i32 15, 40          ; yields i32:result = 47<result> = or i32 4, 8            ; yields i32:result = 12
`, + html: `

‘or’ Instruction

+
+
Syntax:
+
<result> = or <ty> <op1>, <op2>   ; yields ty:result
+<result> = or disjoint <ty> <op1>, <op2>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘or’ instruction returns the bitwise logical inclusive or of its +two operands.

+
+
+
Arguments:
+

The two arguments to the ‘or’ instruction must be +integer or vector of integer values. Both +arguments must have identical types.

+
+
+
Semantics:
+

The truth table used for the ‘or’ instruction is:

+ + + + + + + + + + + + + + + + + + + + + + + +

In0

In1

Out

0

0

0

0

1

1

1

0

1

1

1

1

+

disjoint means that for each bit, that bit is zero in at least one of the +inputs. This allows the Or to be treated as an Add since no carry can occur from +any bit. If the disjoint keyword is present, the result value of the or is a +poison value if both inputs have a one in the same bit +position. For vectors, only the element containing the bit is poison.

+
+
+
Example:
+
<result> = or i32 4, %var         ; yields i32:result = 4 | %var
+<result> = or i32 15, 40          ; yields i32:result = 47
+<result> = or i32 4, 8            ; yields i32:result = 12
+
+
+
+`, tooltip: `The ‘or’ instruction returns the bitwise logical inclusive or of itstwo operands.`, }; case 'XOR': return { url: `https://llvm.org/docs/LangRef.html#xor-instruction`, - html: `

‘xor’ Instruction

Syntax:
<result> = xor <ty> <op1>, <op2>   ; yields ty:result
Overview:

The ‘xor’ instruction returns the bitwise logical exclusive or ofits two operands. The xor is used to implement the “one’scomplement” operation, which is the “~” operator in C.

Arguments:

The two arguments to the ‘xor’ instruction must beinteger or vector of integer values. Botharguments must have identical types.

Semantics:

The truth table used for the ‘xor’ instruction is:

In0

In1

Out

0

0

0

0

1

1

1

0

1

1

1

0

Example:
<result> = xor i32 4, %var         ; yields i32:result = 4 ^ %var<result> = xor i32 15, 40          ; yields i32:result = 39<result> = xor i32 4, 8            ; yields i32:result = 12<result> = xor i32 %V, -1          ; yields i32:result = ~%V
`, + html: `

‘xor’ Instruction

+
+
Syntax:
+
<result> = xor <ty> <op1>, <op2>   ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘xor’ instruction returns the bitwise logical exclusive or of +its two operands. The xor is used to implement the “one’s +complement” operation, which is the “~” operator in C.

+
+
+
Arguments:
+

The two arguments to the ‘xor’ instruction must be +integer or vector of integer values. Both +arguments must have identical types.

+
+
+
Semantics:
+

The truth table used for the ‘xor’ instruction is:

+ + + + + + + + + + + + + + + + + + + + + + + +

In0

In1

Out

0

0

0

0

1

1

1

0

1

1

1

0

+
+
+
Example:
+
<result> = xor i32 4, %var         ; yields i32:result = 4 ^ %var
+<result> = xor i32 15, 40          ; yields i32:result = 39
+<result> = xor i32 4, 8            ; yields i32:result = 12
+<result> = xor i32 %V, -1          ; yields i32:result = ~%V
+
+
+
+`, tooltip: `The ‘xor’ instruction returns the bitwise logical exclusive or ofits two operands. The xor is used to implement the “one’scomplement” operation, which is the “~” operator in C.`, }; case 'EXTRACTELEMENT': return { url: `https://llvm.org/docs/LangRef.html#extractelement-instruction`, - html: `

‘extractelement’ Instruction

Syntax:
<result> = extractelement <n x <ty>> <val>, <ty2> <idx>  ; yields <ty><result> = extractelement <vscale x n x <ty>> <val>, <ty2> <idx> ; yields <ty>
Overview:

The ‘extractelement’ instruction extracts a single scalar elementfrom a vector at a specified index.

Arguments:

The first operand of an ‘extractelement’ instruction is a value ofvector type. The second operand is an index indicatingthe position from which to extract the element. The index may be avariable of any integer type, and will be treated as an unsigned integer.

Semantics:

The result is a scalar of the same type as the element type of val.Its value is the value at position idx of val. If idxexceeds the length of val for a fixed-length vector, the result is apoison value. For a scalable vector, if the valueof idx exceeds the runtime length of the vector, the result is apoison value.

Example:
<result> = extractelement <4 x i32> %vec, i32 0    ; yields i32
`, + html: `

‘extractelement’ Instruction

+
+
Syntax:
+
<result> = extractelement <n x <ty>> <val>, <ty2> <idx>  ; yields <ty>
+<result> = extractelement <vscale x n x <ty>> <val>, <ty2> <idx> ; yields <ty>
+
+
+
+
+
Overview:
+

The ‘extractelement’ instruction extracts a single scalar element +from a vector at a specified index.

+
+
+
Arguments:
+

The first operand of an ‘extractelement’ instruction is a value of +vector type. The second operand is an index indicating +the position from which to extract the element. The index may be a +variable of any integer type, and will be treated as an unsigned integer.

+
+
+
Semantics:
+

The result is a scalar of the same type as the element type of val. +Its value is the value at position idx of val. If idx +exceeds the length of val for a fixed-length vector, the result is a +poison value. For a scalable vector, if the value +of idx exceeds the runtime length of the vector, the result is a +poison value.

+
+
+
Example:
+
<result> = extractelement <4 x i32> %vec, i32 0    ; yields i32
+
+
+
+`, tooltip: `The ‘extractelement’ instruction extracts a single scalar elementfrom a vector at a specified index.`, }; case 'INSERTELEMENT': return { url: `https://llvm.org/docs/LangRef.html#insertelement-instruction`, - html: `

‘insertelement’ Instruction

Syntax:
<result> = insertelement <n x <ty>> <val>, <ty> <elt>, <ty2> <idx>    ; yields <n x <ty>><result> = insertelement <vscale x n x <ty>> <val>, <ty> <elt>, <ty2> <idx> ; yields <vscale x n x <ty>>
Overview:

The ‘insertelement’ instruction inserts a scalar element into avector at a specified index.

Arguments:

The first operand of an ‘insertelement’ instruction is a value ofvector type. The second operand is a scalar value whosetype must equal the element type of the first operand. The third operandis an index indicating the position at which to insert the value. Theindex may be a variable of any integer type, and will be treated as anunsigned integer.

Semantics:

The result is a vector of the same type as val. Its element valuesare those of val except at position idx, where it gets the valueelt. If idx exceeds the length of val for a fixed-length vector,the result is a poison value. For a scalable vector,if the value of idx exceeds the runtime length of the vector, the resultis a poison value.

Example:
<result> = insertelement <4 x i32> %vec, i32 1, i32 0    ; yields <4 x i32>
`, + html: `

‘insertelement’ Instruction

+
+
Syntax:
+
<result> = insertelement <n x <ty>> <val>, <ty> <elt>, <ty2> <idx>    ; yields <n x <ty>>
+<result> = insertelement <vscale x n x <ty>> <val>, <ty> <elt>, <ty2> <idx> ; yields <vscale x n x <ty>>
+
+
+
+
+
Overview:
+

The ‘insertelement’ instruction inserts a scalar element into a +vector at a specified index.

+
+
+
Arguments:
+

The first operand of an ‘insertelement’ instruction is a value of +vector type. The second operand is a scalar value whose +type must equal the element type of the first operand. The third operand +is an index indicating the position at which to insert the value. The +index may be a variable of any integer type, and will be treated as an +unsigned integer.

+
+
+
Semantics:
+

The result is a vector of the same type as val. Its element values +are those of val except at position idx, where it gets the value +elt. If idx exceeds the length of val for a fixed-length vector, +the result is a poison value. For a scalable vector, +if the value of idx exceeds the runtime length of the vector, the result +is a poison value.

+
+
+
Example:
+
<result> = insertelement <4 x i32> %vec, i32 1, i32 0    ; yields <4 x i32>
+
+
+
+`, tooltip: `The ‘insertelement’ instruction inserts a scalar element into avector at a specified index.`, }; case 'SHUFFLEVECTOR': return { url: `https://llvm.org/docs/LangRef.html#shufflevector-instruction`, - html: `

‘shufflevector’ Instruction

Syntax:
<result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask>    ; yields <m x <ty>><result> = shufflevector <vscale x n x <ty>> <v1>, <vscale x n x <ty>> v2, <vscale x m x i32> <mask>  ; yields <vscale x m x <ty>>
Overview:

The ‘shufflevector’ instruction constructs a permutation of elementsfrom two input vectors, returning a vector with the same element type asthe input and length that is the same as the shuffle mask.

Arguments:

The first two operands of a ‘shufflevector’ instruction are vectorswith the same type. The third argument is a shuffle mask vector constantwhose element type is i32. The mask vector elements must be constantintegers or poison values. The result of the instruction is a vectorwhose length is the same as the shuffle mask and whose element type is thesame as the element type of the first two operands.

Semantics:

The elements of the two input vectors are numbered from left to rightacross both of the vectors. For each element of the result vector, theshuffle mask selects an element from one of the input vectors to copyto the result. Non-negative elements in the mask represent an indexinto the concatenated pair of input vectors.

A poison element in the mask vector specifies that the resulting elementis poison.For backwards-compatibility reasons, LLVM temporarily also accepts undefmask elements, which will be interpreted the same way as poison elements.If the shuffle mask selects an undef element from one of the inputvectors, the resulting element is undef.

For scalable vectors, the only valid mask values at present arezeroinitializer, undef and poison, since we cannot write all indices asliterals for a vector with a length unknown at compile time.

Example:
<result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,                        <4 x i32> <i32 0, i32 4, i32 1, i32 5>  ; yields <4 x i32><result> = shufflevector <4 x i32> %v1, <4 x i32> poison,                        <4 x i32> <i32 0, i32 1, i32 2, i32 3>  ; yields <4 x i32> - Identity shuffle.<result> = shufflevector <8 x i32> %v1, <8 x i32> poison,                        <4 x i32> <i32 0, i32 1, i32 2, i32 3>  ; yields <4 x i32><result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,                        <8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 >  ; yields <8 x i32>
`, + html: `

‘shufflevector’ Instruction

+
+
Syntax:
+
<result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask>    ; yields <m x <ty>>
+<result> = shufflevector <vscale x n x <ty>> <v1>, <vscale x n x <ty>> v2, <vscale x m x i32> <mask>  ; yields <vscale x m x <ty>>
+
+
+
+
+
Overview:
+

The ‘shufflevector’ instruction constructs a permutation of elements +from two input vectors, returning a vector with the same element type as +the input and length that is the same as the shuffle mask.

+
+
+
Arguments:
+

The first two operands of a ‘shufflevector’ instruction are vectors +with the same type. The third argument is a shuffle mask vector constant +whose element type is i32. The mask vector elements must be constant +integers or poison values. The result of the instruction is a vector +whose length is the same as the shuffle mask and whose element type is the +same as the element type of the first two operands.

+
+
+
Semantics:
+

The elements of the two input vectors are numbered from left to right +across both of the vectors. For each element of the result vector, the +shuffle mask selects an element from one of the input vectors to copy +to the result. Non-negative elements in the mask represent an index +into the concatenated pair of input vectors.

+

A poison element in the mask vector specifies that the resulting element +is poison. +For backwards-compatibility reasons, LLVM temporarily also accepts undef +mask elements, which will be interpreted the same way as poison elements. +If the shuffle mask selects an undef element from one of the input +vectors, the resulting element is undef.

+

For scalable vectors, the only valid mask values at present are +zeroinitializer, undef and poison, since we cannot write all indices as +literals for a vector with a length unknown at compile time.

+
+
+
Example:
+
<result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
+                        <4 x i32> <i32 0, i32 4, i32 1, i32 5>  ; yields <4 x i32>
+<result> = shufflevector <4 x i32> %v1, <4 x i32> poison,
+                        <4 x i32> <i32 0, i32 1, i32 2, i32 3>  ; yields <4 x i32> - Identity shuffle.
+<result> = shufflevector <8 x i32> %v1, <8 x i32> poison,
+                        <4 x i32> <i32 0, i32 1, i32 2, i32 3>  ; yields <4 x i32>
+<result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
+                        <8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 >  ; yields <8 x i32>
+
+
+
+`, tooltip: `The ‘shufflevector’ instruction constructs a permutation of elementsfrom two input vectors, returning a vector with the same element type asthe input and length that is the same as the shuffle mask.`, }; case 'EXTRACTVALUE': return { url: `https://llvm.org/docs/LangRef.html#extractvalue-instruction`, - html: `

‘extractvalue’ Instruction

Syntax:
<result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}*
Overview:

The ‘extractvalue’ instruction extracts the value of a member fieldfrom an aggregate value.

Arguments:

The first operand of an ‘extractvalue’ instruction is a value ofstruct or array type. The other operands areconstant indices to specify which value to extract in a similar manneras indices in a ‘getelementptr’ instruction.

The major differences to getelementptr indexing are:

Semantics:

The result is the value at the position in the aggregate specified bythe index operands.

Example:
<result> = extractvalue {i32, float} %agg, 0    ; yields i32
`, + html: `

‘extractvalue’ Instruction

+
+
Syntax:
+
<result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}*
+
+
+
+
+
Overview:
+

The ‘extractvalue’ instruction extracts the value of a member field +from an aggregate value.

+
+
+
Arguments:
+

The first operand of an ‘extractvalue’ instruction is a value of +struct or array type. The other operands are +constant indices to specify which value to extract in a similar manner +as indices in a ‘getelementptr’ instruction.

+

The major differences to getelementptr indexing are:

+ +
+
+
Semantics:
+

The result is the value at the position in the aggregate specified by +the index operands.

+
+
+
Example:
+
<result> = extractvalue {i32, float} %agg, 0    ; yields i32
+
+
+
+`, tooltip: `The ‘extractvalue’ instruction extracts the value of a member fieldfrom an aggregate value.`, }; case 'INSERTVALUE': return { url: `https://llvm.org/docs/LangRef.html#insertvalue-instruction`, - html: `

‘insertvalue’ Instruction

Syntax:
<result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}*    ; yields <aggregate type>
Overview:

The ‘insertvalue’ instruction inserts a value into a member field inan aggregate value.

Arguments:

The first operand of an ‘insertvalue’ instruction is a value ofstruct or array type. The second operand isa first-class value to insert. The following operands are constantindices indicating the position at which to insert the value in asimilar manner as indices in a ‘extractvalue’ instruction. The valueto insert must have the same type as the value identified by theindices.

Semantics:

The result is an aggregate of the same type as val. Its value isthat of val except that the value at the position specified by theindices is that of elt.

Example:
%agg1 = insertvalue {i32, float} poison, i32 1, 0              ; yields {i32 1, float poison}%agg2 = insertvalue {i32, float} %agg1, float %val, 1          ; yields {i32 1, float %val}%agg3 = insertvalue {i32, {float}} poison, float %val, 1, 0    ; yields {i32 poison, {float %val}}
`, + html: `

‘insertvalue’ Instruction

+
+
Syntax:
+
<result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}*    ; yields <aggregate type>
+
+
+
+
+
Overview:
+

The ‘insertvalue’ instruction inserts a value into a member field in +an aggregate value.

+
+
+
Arguments:
+

The first operand of an ‘insertvalue’ instruction is a value of +struct or array type. The second operand is +a first-class value to insert. The following operands are constant +indices indicating the position at which to insert the value in a +similar manner as indices in a ‘extractvalue’ instruction. The value +to insert must have the same type as the value identified by the +indices.

+
+
+
Semantics:
+

The result is an aggregate of the same type as val. Its value is +that of val except that the value at the position specified by the +indices is that of elt.

+
+
+
Example:
+
%agg1 = insertvalue {i32, float} poison, i32 1, 0              ; yields {i32 1, float poison}
+%agg2 = insertvalue {i32, float} %agg1, float %val, 1          ; yields {i32 1, float %val}
+%agg3 = insertvalue {i32, {float}} poison, float %val, 1, 0    ; yields {i32 poison, {float %val}}
+
+
+
+`, tooltip: `The ‘insertvalue’ instruction inserts a value into a member field inan aggregate value.`, }; case 'ALLOCA': return { url: `https://llvm.org/docs/LangRef.html#alloca-instruction`, - html: `

‘alloca’ Instruction

Syntax:
<result> = alloca [inalloca] <type> [, <ty> <NumElements>] [, align <alignment>] [, addrspace(<num>)]     ; yields type addrspace(num)*:result
Overview:

The ‘alloca’ instruction allocates memory on the stack frame of thecurrently executing function, to be automatically released when thisfunction returns to its caller. If the address space is not explicitlyspecified, the default address space 0 is used.

Arguments:

The ‘alloca’ instruction allocates sizeof(<type>)*NumElementsbytes of memory on the runtime stack, returning a pointer of theappropriate type to the program. If “NumElements” is specified, it isthe number of elements allocated, otherwise “NumElements” is defaultedto be one.

If a constant alignment is specified, the value result of theallocation is guaranteed to be aligned to at least that boundary. Thealignment may not be greater than 1 << 32.

The alignment is only optional when parsing textual IR; for in-memory IR,it is always present. If not specified, the target can choose to align theallocation on any convenient boundary compatible with the type.

‘type’ may be any sized type.

Structs containing scalable vectors cannot be used in allocas unless allfields are the same scalable vector type (e.g., {<vscale x 2 x i32>,<vscale x 2 x i32>} contains the same type while {<vscale x 2 x i32>,<vscale x 2 x i64>} doesn’t).

Semantics:

Memory is allocated; a pointer is returned. The allocated memory isuninitialized, and loading from uninitialized memory produces an undefinedvalue. The operation itself is undefined if there is insufficient stackspace for the allocation.’alloca’d memory is automatically releasedwhen the function returns. The ‘alloca’ instruction is commonly usedto represent automatic variables that must have an address available. Whenthe function returns (either with the ret or resume instructions),the memory is reclaimed. Allocating zero bytes is legal, but the returnedpointer may not be unique. The order in which memory is allocated (ie.,which way the stack grows) is not specified.

Note that ‘alloca’ outside of the alloca address space from thedatalayout string is meaningful only if thetarget has assigned it a semantics. For targets that specify a non-zero allocaaddress space in the datalayout string, the allocaaddress space needs to be explicitly specified in the instruction if it is to beused.

If the returned pointer is used by llvm.lifetime.start,the returned object is initially dead.See llvm.lifetime.start andllvm.lifetime.end for the precise semantics oflifetime-manipulating intrinsics.

Example:
%ptr = alloca i32                             ; yields ptr%ptr = alloca i32, i32 4                      ; yields ptr%ptr = alloca i32, i32 4, align 1024          ; yields ptr%ptr = alloca i32, align 1024                 ; yields ptr
`, + html: `

‘alloca’ Instruction

+
+
Syntax:
+
<result> = alloca [inalloca] <type> [, <ty> <NumElements>] [, align <alignment>] [, addrspace(<num>)]     ; yields type addrspace(num)*:result
+
+
+
+
+
Overview:
+

The ‘alloca’ instruction allocates memory on the stack frame of the +currently executing function, to be automatically released when this +function returns to its caller. If the address space is not explicitly +specified, the default address space 0 is used.

+
+
+
Arguments:
+

The ‘alloca’ instruction allocates sizeof(<type>)*NumElements +bytes of memory on the runtime stack, returning a pointer of the +appropriate type to the program. If “NumElements” is specified, it is +the number of elements allocated, otherwise “NumElements” is defaulted +to be one.

+

If a constant alignment is specified, the value result of the +allocation is guaranteed to be aligned to at least that boundary. The +alignment may not be greater than 1 << 32.

+

The alignment is only optional when parsing textual IR; for in-memory IR, +it is always present. If not specified, the target can choose to align the +allocation on any convenient boundary compatible with the type.

+

‘type’ may be any sized type.

+

Structs containing scalable vectors cannot be used in allocas unless all +fields are the same scalable vector type (e.g., {<vscale x 2 x i32>, +<vscale x 2 x i32>} contains the same type while {<vscale x 2 x i32>, +<vscale x 2 x i64>} doesn’t).

+
+
+
Semantics:
+

Memory is allocated; a pointer is returned. The allocated memory is +uninitialized, and loading from uninitialized memory produces an undefined +value. The operation itself is undefined if there is insufficient stack +space for the allocation.’alloca’d memory is automatically released +when the function returns. The ‘alloca’ instruction is commonly used +to represent automatic variables that must have an address available. When +the function returns (either with the ret or resume instructions), +the memory is reclaimed. Allocating zero bytes is legal, but the returned +pointer may not be unique. The order in which memory is allocated (ie., +which way the stack grows) is not specified.

+

Note that ‘alloca’ outside of the alloca address space from the +datalayout string is meaningful only if the +target has assigned it a semantics. For targets that specify a non-zero alloca +address space in the datalayout string, the alloca +address space needs to be explicitly specified in the instruction if it is to be +used.

+

If the returned pointer is used by llvm.lifetime.start, +the returned object is initially dead. +See llvm.lifetime.start and +llvm.lifetime.end for the precise semantics of +lifetime-manipulating intrinsics.

+
+
+
Example:
+
%ptr = alloca i32                             ; yields ptr
+%ptr = alloca i32, i32 4                      ; yields ptr
+%ptr = alloca i32, i32 4, align 1024          ; yields ptr
+%ptr = alloca i32, align 1024                 ; yields ptr
+
+
+
+`, tooltip: `The ‘alloca’ instruction allocates memory on the stack frame of thecurrently executing function, to be automatically released when thisfunction returns to its caller. If the address space is not explicitlyspecified, the default address space 0 is used.`, }; case 'LOAD': return { url: `https://llvm.org/docs/LangRef.html#load-instruction`, - html: `

‘load’ Instruction

Syntax:
<result> = load [volatile] <ty>, ptr <pointer>[, align <alignment>][, !nontemporal !<nontemp_node>][, !invariant.load !<empty_node>][, !invariant.group !<empty_node>][, !nonnull !<empty_node>][, !dereferenceable !<deref_bytes_node>][, !dereferenceable_or_null !<deref_bytes_node>][, !align !<align_node>][, !noundef !<empty_node>]<result> = load atomic [volatile] <ty>, ptr <pointer> [syncscope("<target-scope>")] <ordering>, align <alignment> [, !invariant.group !<empty_node>]!<nontemp_node> = !{ i32 1 }!<empty_node> = !{}!<deref_bytes_node> = !{ i64 <dereferenceable_bytes> }!<align_node> = !{ i64 <value_alignment> }
Overview:

The ‘load’ instruction is used to read from memory.

Arguments:

The argument to the load instruction specifies the memory address from whichto load. The type specified must be a first class type ofknown size (i.e., not containing an opaque structural type). Ifthe load is marked as volatile, then the optimizer is not allowed tomodify the number or order of execution of this load with othervolatile operations.

If the load is marked as atomic, it takes an extra ordering and optional syncscope("<target-scope>") argument. Therelease and acq_rel orderings are not valid on load instructions.Atomic loads produce defined results when they may seemultiple atomic stores. The type of the pointee must be an integer, pointer,floating-point, or vector type whose bit width is a power of two greater thanor equal to eight. align must beexplicitly specified on atomic loads. Note: if the alignment is not greater orequal to the size of the <value> type, the atomic operation is likely torequire a lock and have poor performance. !nontemporal does not have anydefined semantics for atomic loads.

The optional constant align argument specifies the alignment of theoperation (that is, the alignment of the memory address). It is theresponsibility of the code emitter to ensure that the alignment information iscorrect. Overestimating the alignment results in undefined behavior.Underestimating the alignment may produce less efficient code. An alignment of1 is always safe. The maximum possible alignment is 1 << 32. An alignmentvalue higher than the size of the loaded type does not imply (without targetspecific knowledge) that memory up to the alignment value bytes can be safelyloaded without trapping.

The alignment is only optional when parsing textual IR; for in-memory IR, it isalways present. An omitted align argument means that the operation has theABI alignment for the target.

The optional !nontemporal metadata must reference a singlemetadata name <nontemp_node> corresponding to a metadata node with onei32 entry of value 1. The existence of the !nontemporalmetadata on the instruction tells the optimizer and code generatorthat this load is not expected to be reused in the cache. The codegenerator may select special instructions to save cache bandwidth, suchas the MOVNT instruction on x86.

The optional !invariant.load metadata must reference a singlemetadata name <empty_node> corresponding to a metadata node with noentries. If a load instruction tagged with the !invariant.loadmetadata is executed, the memory location referenced by the load hasto contain the same value at all points in the program where thememory location is dereferenceable; otherwise, the behavior isundefined.

The optional !invariant.group metadata must reference a single metadata name

<empty_node> corresponding to a metadata node with no entries.See invariant.group metadata invariant.group.

The optional !nonnull metadata must reference a singlemetadata name <empty_node> corresponding to a metadata node with noentries. The existence of the !nonnull metadata on theinstruction tells the optimizer that the value loaded is known tonever be null. If the value is null at runtime, a poison value is returnedinstead. This is analogous to the nonnull attribute on parameters andreturn values. This metadata can only be applied to loads of a pointer type.

The optional !dereferenceable metadata must reference a single metadataname <deref_bytes_node> corresponding to a metadata node with one i64entry.See dereferenceable metadata dereferenceable.

The optional !dereferenceable_or_null metadata must reference a singlemetadata name <deref_bytes_node> corresponding to a metadata node with onei64 entry.See dereferenceable_or_null metadata dereferenceable_or_null.

The optional !align metadata must reference a single metadata name<align_node> corresponding to a metadata node with one i64 entry.The existence of the !align metadata on the instruction tells theoptimizer that the value loaded is known to be aligned to a boundary specifiedby the integer value in the metadata node. The alignment must be a power of 2.This is analogous to the ‘’align’’ attribute on parameters and return values.This metadata can only be applied to loads of a pointer type. If the returnedvalue is not appropriately aligned at runtime, a poison value is returnedinstead.

The optional !noundef metadata must reference a single metadata name<empty_node> corresponding to a node with no entries. The existence of!noundef metadata on the instruction tells the optimizer that the valueloaded is known to be well defined.If the value isn’t well defined, the behavior is undefined. If the !noundefmetadata is combined with poison-generating metadata like !nonnull,violation of that metadata constraint will also result in undefined behavior.

Semantics:

The location of memory pointed to is loaded. If the value being loadedis of scalar type then the number of bytes read does not exceed theminimum number of bytes needed to hold all bits of the type. Forexample, loading an i24 reads at most three bytes. When loading avalue of a type like i20 with a size that is not an integral numberof bytes, the result is undefined if the value was not originallywritten using a store of the same type.If the value being loaded is of aggregate type, the bytes that correspond topadding may be accessed but are ignored, because it is impossible to observepadding from the loaded aggregate value.If <pointer> is not a well-defined value, the behavior is undefined.

Examples:
%ptr = alloca i32                               ; yields ptrstore i32 3, ptr %ptr                           ; yields void%val = load i32, ptr %ptr                       ; yields i32:val = i32 3
`, + html: `

‘load’ Instruction

+
+
Syntax:
+
<result> = load [volatile] <ty>, ptr <pointer>[, align <alignment>][, !nontemporal !<nontemp_node>][, !invariant.load !<empty_node>][, !invariant.group !<empty_node>][, !nonnull !<empty_node>][, !dereferenceable !<deref_bytes_node>][, !dereferenceable_or_null !<deref_bytes_node>][, !align !<align_node>][, !noundef !<empty_node>]
+<result> = load atomic [volatile] <ty>, ptr <pointer> [syncscope("<target-scope>")] <ordering>, align <alignment> [, !invariant.group !<empty_node>]
+!<nontemp_node> = !{ i32 1 }
+!<empty_node> = !{}
+!<deref_bytes_node> = !{ i64 <dereferenceable_bytes> }
+!<align_node> = !{ i64 <value_alignment> }
+
+
+
+
+
Overview:
+

The ‘load’ instruction is used to read from memory.

+
+
+
Arguments:
+

The argument to the load instruction specifies the memory address from which +to load. The type specified must be a first class type of +known size (i.e., not containing an opaque structural type). If +the load is marked as volatile, then the optimizer is not allowed to +modify the number or order of execution of this load with other +volatile operations.

+

If the load is marked as atomic, it takes an extra ordering and optional syncscope("<target-scope>") argument. The +release and acq_rel orderings are not valid on load instructions. +Atomic loads produce defined results when they may see +multiple atomic stores. The type of the pointee must be an integer, pointer, +floating-point, or vector type whose bit width is a power of two greater than +or equal to eight. align must be +explicitly specified on atomic loads. Note: if the alignment is not greater or +equal to the size of the <value> type, the atomic operation is likely to +require a lock and have poor performance. !nontemporal does not have any +defined semantics for atomic loads.

+

The optional constant align argument specifies the alignment of the +operation (that is, the alignment of the memory address). It is the +responsibility of the code emitter to ensure that the alignment information is +correct. Overestimating the alignment results in undefined behavior. +Underestimating the alignment may produce less efficient code. An alignment of +1 is always safe. The maximum possible alignment is 1 << 32. An alignment +value higher than the size of the loaded type does not imply (without target +specific knowledge) that memory up to the alignment value bytes can be safely +loaded without trapping.

+

The alignment is only optional when parsing textual IR; for in-memory IR, it is +always present. An omitted align argument means that the operation has the +ABI alignment for the target.

+

The optional !nontemporal metadata must reference a single +metadata name <nontemp_node> corresponding to a metadata node with one +i32 entry of value 1. The existence of the !nontemporal +metadata on the instruction tells the optimizer and code generator +that this load is not expected to be reused in the cache. The code +generator may select special instructions to save cache bandwidth, such +as the MOVNT instruction on x86.

+

The optional !invariant.load metadata must reference a single +metadata name <empty_node> corresponding to a metadata node with no +entries. If a load instruction tagged with the !invariant.load +metadata is executed, the memory location referenced by the load has +to contain the same value at all points in the program where the +memory location is dereferenceable; otherwise, the behavior is +undefined.

+
+
The optional !invariant.group metadata must reference a single metadata name

<empty_node> corresponding to a metadata node with no entries. +See invariant.group metadata invariant.group.

+
+
+

The optional !nonnull metadata must reference a single +metadata name <empty_node> corresponding to a metadata node with no +entries. The existence of the !nonnull metadata on the +instruction tells the optimizer that the value loaded is known to +never be null. If the value is null at runtime, a poison value is returned +instead. This is analogous to the nonnull attribute on parameters and +return values. This metadata can only be applied to loads of a pointer type.

+

The optional !dereferenceable metadata must reference a single metadata +name <deref_bytes_node> corresponding to a metadata node with one i64 +entry. +See dereferenceable metadata dereferenceable.

+

The optional !dereferenceable_or_null metadata must reference a single +metadata name <deref_bytes_node> corresponding to a metadata node with one +i64 entry. +See dereferenceable_or_null metadata dereferenceable_or_null.

+

The optional !align metadata must reference a single metadata name +<align_node> corresponding to a metadata node with one i64 entry. +The existence of the !align metadata on the instruction tells the +optimizer that the value loaded is known to be aligned to a boundary specified +by the integer value in the metadata node. The alignment must be a power of 2. +This is analogous to the ‘’align’’ attribute on parameters and return values. +This metadata can only be applied to loads of a pointer type. If the returned +value is not appropriately aligned at runtime, a poison value is returned +instead.

+

The optional !noundef metadata must reference a single metadata name +<empty_node> corresponding to a node with no entries. The existence of +!noundef metadata on the instruction tells the optimizer that the value +loaded is known to be well defined. +If the value isn’t well defined, the behavior is undefined. If the !noundef +metadata is combined with poison-generating metadata like !nonnull, +violation of that metadata constraint will also result in undefined behavior.

+
+
+
Semantics:
+

The location of memory pointed to is loaded. If the value being loaded +is of scalar type then the number of bytes read does not exceed the +minimum number of bytes needed to hold all bits of the type. For +example, loading an i24 reads at most three bytes. When loading a +value of a type like i20 with a size that is not an integral number +of bytes, the result is undefined if the value was not originally +written using a store of the same type. +If the value being loaded is of aggregate type, the bytes that correspond to +padding may be accessed but are ignored, because it is impossible to observe +padding from the loaded aggregate value. +If <pointer> is not a well-defined value, the behavior is undefined.

+
+
+
Examples:
+
%ptr = alloca i32                               ; yields ptr
+store i32 3, ptr %ptr                           ; yields void
+%val = load i32, ptr %ptr                       ; yields i32:val = i32 3
+
+
+
+`, tooltip: `The ‘load’ instruction is used to read from memory.`, }; case 'STORE': return { url: `https://llvm.org/docs/LangRef.html#store-instruction`, - html: `

‘store’ Instruction

Syntax:
store [volatile] <ty> <value>, ptr <pointer>[, align <alignment>][, !nontemporal !<nontemp_node>][, !invariant.group !<empty_node>]        ; yields voidstore atomic [volatile] <ty> <value>, ptr <pointer> [syncscope("<target-scope>")] <ordering>, align <alignment> [, !invariant.group !<empty_node>] ; yields void!<nontemp_node> = !{ i32 1 }!<empty_node> = !{}
Overview:

The ‘store’ instruction is used to write to memory.

Arguments:

There are two arguments to the store instruction: a value to store and anaddress at which to store it. The type of the <pointer> operand must be apointer to the first class type of the <value>operand. If the store is marked as volatile, then the optimizer is notallowed to modify the number or order of execution of this store with othervolatile operations. Only values of first class types of known size (i.e., not containing an opaquestructural type) can be stored.

If the store is marked as atomic, it takes an extra ordering and optional syncscope("<target-scope>") argument. Theacquire and acq_rel orderings aren’t valid on store instructions.Atomic loads produce defined results when they may seemultiple atomic stores. The type of the pointee must be an integer, pointer,floating-point, or vector type whose bit width is a power of two greater thanor equal to eight. align must beexplicitly specified on atomic stores. Note: if the alignment is not greater orequal to the size of the <value> type, the atomic operation is likely torequire a lock and have poor performance. !nontemporal does not have anydefined semantics for atomic stores.

The optional constant align argument specifies the alignment of theoperation (that is, the alignment of the memory address). It is theresponsibility of the code emitter to ensure that the alignment information iscorrect. Overestimating the alignment results in undefined behavior.Underestimating the alignment may produce less efficient code. An alignment of1 is always safe. The maximum possible alignment is 1 << 32. An alignmentvalue higher than the size of the stored type does not imply (without targetspecific knowledge) that memory up to the alignment value bytes can be safelyloaded without trapping.

The alignment is only optional when parsing textual IR; for in-memory IR, it isalways present. An omitted align argument means that the operation has theABI alignment for the target.

The optional !nontemporal metadata must reference a single metadataname <nontemp_node> corresponding to a metadata node with one i32 entryof value 1. The existence of the !nontemporal metadata on the instructiontells the optimizer and code generator that this load is not expected tobe reused in the cache. The code generator may select specialinstructions to save cache bandwidth, such as the MOVNT instruction onx86.

The optional !invariant.group metadata must reference asingle metadata name <empty_node>. See invariant.group metadata.

Semantics:

The contents of memory are updated to contain <value> at thelocation specified by the <pointer> operand. If <value> isof scalar type then the number of bytes written does not exceed theminimum number of bytes needed to hold all bits of the type. Forexample, storing an i24 writes at most three bytes. When writing avalue of a type like i20 with a size that is not an integral numberof bytes, it is unspecified what happens to the extra bits that do notbelong to the type, but they will typically be overwritten.If <value> is of aggregate type, padding is filled withundef.If <pointer> is not a well-defined value, the behavior is undefined.

Example:
%ptr = alloca i32                               ; yields ptrstore i32 3, ptr %ptr                           ; yields void%val = load i32, ptr %ptr                       ; yields i32:val = i32 3
`, + html: `

‘store’ Instruction

+
+
Syntax:
+
store [volatile] <ty> <value>, ptr <pointer>[, align <alignment>][, !nontemporal !<nontemp_node>][, !invariant.group !<empty_node>]        ; yields void
+store atomic [volatile] <ty> <value>, ptr <pointer> [syncscope("<target-scope>")] <ordering>, align <alignment> [, !invariant.group !<empty_node>] ; yields void
+!<nontemp_node> = !{ i32 1 }
+!<empty_node> = !{}
+
+
+
+
+
Overview:
+

The ‘store’ instruction is used to write to memory.

+
+
+
Arguments:
+

There are two arguments to the store instruction: a value to store and an +address at which to store it. The type of the <pointer> operand must be a +pointer to the first class type of the <value> +operand. If the store is marked as volatile, then the optimizer is not +allowed to modify the number or order of execution of this store with other +volatile operations. Only values of first class types of known size (i.e., not containing an opaque +structural type) can be stored.

+

If the store is marked as atomic, it takes an extra ordering and optional syncscope("<target-scope>") argument. The +acquire and acq_rel orderings aren’t valid on store instructions. +Atomic loads produce defined results when they may see +multiple atomic stores. The type of the pointee must be an integer, pointer, +floating-point, or vector type whose bit width is a power of two greater than +or equal to eight. align must be +explicitly specified on atomic stores. Note: if the alignment is not greater or +equal to the size of the <value> type, the atomic operation is likely to +require a lock and have poor performance. !nontemporal does not have any +defined semantics for atomic stores.

+

The optional constant align argument specifies the alignment of the +operation (that is, the alignment of the memory address). It is the +responsibility of the code emitter to ensure that the alignment information is +correct. Overestimating the alignment results in undefined behavior. +Underestimating the alignment may produce less efficient code. An alignment of +1 is always safe. The maximum possible alignment is 1 << 32. An alignment +value higher than the size of the stored type does not imply (without target +specific knowledge) that memory up to the alignment value bytes can be safely +loaded without trapping.

+

The alignment is only optional when parsing textual IR; for in-memory IR, it is +always present. An omitted align argument means that the operation has the +ABI alignment for the target.

+

The optional !nontemporal metadata must reference a single metadata +name <nontemp_node> corresponding to a metadata node with one i32 entry +of value 1. The existence of the !nontemporal metadata on the instruction +tells the optimizer and code generator that this load is not expected to +be reused in the cache. The code generator may select special +instructions to save cache bandwidth, such as the MOVNT instruction on +x86.

+

The optional !invariant.group metadata must reference a +single metadata name <empty_node>. See invariant.group metadata.

+
+
+
Semantics:
+

The contents of memory are updated to contain <value> at the +location specified by the <pointer> operand. If <value> is +of scalar type then the number of bytes written does not exceed the +minimum number of bytes needed to hold all bits of the type. For +example, storing an i24 writes at most three bytes. When writing a +value of a type like i20 with a size that is not an integral number +of bytes, it is unspecified what happens to the extra bits that do not +belong to the type, but they will typically be overwritten. +If <value> is of aggregate type, padding is filled with +undef. +If <pointer> is not a well-defined value, the behavior is undefined.

+
+
+
Example:
+
%ptr = alloca i32                               ; yields ptr
+store i32 3, ptr %ptr                           ; yields void
+%val = load i32, ptr %ptr                       ; yields i32:val = i32 3
+
+
+
+`, tooltip: `The ‘store’ instruction is used to write to memory.`, }; case 'FENCE': return { url: `https://llvm.org/docs/LangRef.html#fence-instruction`, - html: `

‘fence’ Instruction

Syntax:
fence [syncscope("<target-scope>")] <ordering>  ; yields void
Overview:

The ‘fence’ instruction is used to introduce happens-before edgesbetween operations.

Arguments:

‘fence’ instructions take an ordering argument whichdefines what synchronizes-with edges they add. They can only be givenacquire, release, acq_rel, and seq_cst orderings.

Semantics:

A fence A which has (at least) release ordering semanticssynchronizes with a fence B with (at least) acquire orderingsemantics if and only if there exist atomic operations X and Y, bothoperating on some atomic object M, such that A is sequenced before X, Xmodifies M (either directly or through some side effect of a sequenceheaded by X), Y is sequenced before B, and Y observes M. This provides ahappens-before dependency between A and B. Rather than an explicitfence, one (but not both) of the atomic operations X or Y mightprovide a release or acquire (resp.) ordering constraint andstill synchronize-with the explicit fence and establish thehappens-before edge.

A fence which has seq_cst ordering, in addition to having bothacquire and release semantics specified above, participates inthe global program order of other seq_cst operations and/orfences. Furthermore, the global ordering created by a seq_cstfence must be compatible with the individual total orders ofmonotonic (or stronger) memory accesses occurring before and aftersuch a fence. The exact semantics of this interaction are somewhatcomplicated, see the C++ standard’s [atomics.order] section for more details.

A fence instruction can also take an optional“syncscope” argument.

Example:
fence acquire                                        ; yields voidfence syncscope("singlethread") seq_cst              ; yields voidfence syncscope("agent") seq_cst                     ; yields void
`, + html: `

‘fence’ Instruction

+
+
Syntax:
+
fence [syncscope("<target-scope>")] <ordering>  ; yields void
+
+
+
+
+
Overview:
+

The ‘fence’ instruction is used to introduce happens-before edges +between operations.

+
+
+
Arguments:
+

‘fence’ instructions take an ordering argument which +defines what synchronizes-with edges they add. They can only be given +acquire, release, acq_rel, and seq_cst orderings.

+
+
+
Semantics:
+

A fence A which has (at least) release ordering semantics +synchronizes with a fence B with (at least) acquire ordering +semantics if and only if there exist atomic operations X and Y, both +operating on some atomic object M, such that A is sequenced before X, X +modifies M (either directly or through some side effect of a sequence +headed by X), Y is sequenced before B, and Y observes M. This provides a +happens-before dependency between A and B. Rather than an explicit +fence, one (but not both) of the atomic operations X or Y might +provide a release or acquire (resp.) ordering constraint and +still synchronize-with the explicit fence and establish the +happens-before edge.

+

A fence which has seq_cst ordering, in addition to having both +acquire and release semantics specified above, participates in +the global program order of other seq_cst operations and/or +fences. Furthermore, the global ordering created by a seq_cst +fence must be compatible with the individual total orders of +monotonic (or stronger) memory accesses occurring before and after +such a fence. The exact semantics of this interaction are somewhat +complicated, see the C++ standard’s [atomics.order] section for more details.

+

A fence instruction can also take an optional +“syncscope” argument.

+
+
+
Example:
+
fence acquire                                        ; yields void
+fence syncscope("singlethread") seq_cst              ; yields void
+fence syncscope("agent") seq_cst                     ; yields void
+
+
+
+`, tooltip: `The ‘fence’ instruction is used to introduce happens-before edgesbetween operations.`, }; case 'CMPXCHG': return { url: `https://llvm.org/docs/LangRef.html#cmpxchg-instruction`, - html: `

‘cmpxchg’ Instruction

Syntax:
cmpxchg [weak] [volatile] ptr <pointer>, <ty> <cmp>, <ty> <new> [syncscope("<target-scope>")] <success ordering> <failure ordering>[, align <alignment>] ; yields  { ty, i1 }
Overview:

The ‘cmpxchg’ instruction is used to atomically modify memory. Itloads a value in memory and compares it to a given value. If they areequal, it tries to store a new value into the memory.

Arguments:

There are three arguments to the ‘cmpxchg’ instruction: an addressto operate on, a value to compare to the value currently be at thataddress, and a new value to place at that address if the compared valuesare equal. The type of ‘<cmp>’ must be an integer or pointer type whosebit width is a power of two greater than or equal to eight.‘<cmp>’ and ‘<new>’ musthave the same type, and the type of ‘<pointer>’ must be a pointer tothat type. If the cmpxchg is marked as volatile, then theoptimizer is not allowed to modify the number or order of execution ofthis cmpxchg with other volatile operations.

The success and failure ordering arguments specify how thiscmpxchg synchronizes with other atomic operations. Both ordering parametersmust be at least monotonic, the failure ordering cannot be eitherrelease or acq_rel.

A cmpxchg instruction can also take an optional“syncscope” argument.

Note: if the alignment is not greater or equal to the size of the <value>type, the atomic operation is likely to require a lock and have poorperformance.

The alignment is only optional when parsing textual IR; for in-memory IR, it isalways present. If unspecified, the alignment is assumed to be equal to thesize of the ‘<value>’ type. Note that this default alignment assumption isdifferent from the alignment used for the load/store instructions when alignisn’t specified.

The pointer passed into cmpxchg must have alignment greater than orequal to the size in memory of the operand.

Semantics:

The contents of memory at the location specified by the ‘<pointer>’ operandis read and compared to ‘<cmp>’; if the values are equal, ‘<new>’ iswritten to the location. The original value at the location is returned,together with a flag indicating success (true) or failure (false).

If the cmpxchg operation is marked as weak then a spurious failure ispermitted: the operation may not write <new> even if the comparisonmatched.

If the cmpxchg operation is strong (the default), the i1 value is 1 if and onlyif the value loaded equals cmp.

A successful cmpxchg is a read-modify-write instruction for the purpose ofidentifying release sequences. A failed cmpxchg is equivalent to an atomicload with an ordering parameter determined the second ordering parameter.

Example:
entry:  %orig = load atomic i32, ptr %ptr unordered, align 4                      ; yields i32  br label %looploop:  %cmp = phi i32 [ %orig, %entry ], [%value_loaded, %loop]  %squared = mul i32 %cmp, %cmp  %val_success = cmpxchg ptr %ptr, i32 %cmp, i32 %squared acq_rel monotonic ; yields  { i32, i1 }  %value_loaded = extractvalue { i32, i1 } %val_success, 0  %success = extractvalue { i32, i1 } %val_success, 1  br i1 %success, label %done, label %loopdone:  ...
`, + html: `

‘cmpxchg’ Instruction

+
+
Syntax:
+
cmpxchg [weak] [volatile] ptr <pointer>, <ty> <cmp>, <ty> <new> [syncscope("<target-scope>")] <success ordering> <failure ordering>[, align <alignment>] ; yields  { ty, i1 }
+
+
+
+
+
Overview:
+

The ‘cmpxchg’ instruction is used to atomically modify memory. It +loads a value in memory and compares it to a given value. If they are +equal, it tries to store a new value into the memory.

+
+
+
Arguments:
+

There are three arguments to the ‘cmpxchg’ instruction: an address +to operate on, a value to compare to the value currently be at that +address, and a new value to place at that address if the compared values +are equal. The type of ‘<cmp>’ must be an integer or pointer type whose +bit width is a power of two greater than or equal to eight. +‘<cmp>’ and ‘<new>’ must +have the same type, and the type of ‘<pointer>’ must be a pointer to +that type. If the cmpxchg is marked as volatile, then the +optimizer is not allowed to modify the number or order of execution of +this cmpxchg with other volatile operations.

+

The success and failure ordering arguments specify how this +cmpxchg synchronizes with other atomic operations. Both ordering parameters +must be at least monotonic, the failure ordering cannot be either +release or acq_rel.

+

A cmpxchg instruction can also take an optional +“syncscope” argument.

+

Note: if the alignment is not greater or equal to the size of the <value> +type, the atomic operation is likely to require a lock and have poor +performance.

+

The alignment is only optional when parsing textual IR; for in-memory IR, it is +always present. If unspecified, the alignment is assumed to be equal to the +size of the ‘<value>’ type. Note that this default alignment assumption is +different from the alignment used for the load/store instructions when align +isn’t specified.

+

The pointer passed into cmpxchg must have alignment greater than or +equal to the size in memory of the operand.

+
+
+
Semantics:
+

The contents of memory at the location specified by the ‘<pointer>’ operand +is read and compared to ‘<cmp>’; if the values are equal, ‘<new>’ is +written to the location. The original value at the location is returned, +together with a flag indicating success (true) or failure (false).

+

If the cmpxchg operation is marked as weak then a spurious failure is +permitted: the operation may not write <new> even if the comparison +matched.

+

If the cmpxchg operation is strong (the default), the i1 value is 1 if and only +if the value loaded equals cmp.

+

A successful cmpxchg is a read-modify-write instruction for the purpose of +identifying release sequences. A failed cmpxchg is equivalent to an atomic +load with an ordering parameter determined the second ordering parameter.

+
+
+
Example:
+
entry:
+  %orig = load atomic i32, ptr %ptr unordered, align 4                      ; yields i32
+  br label %loop
+
+loop:
+  %cmp = phi i32 [ %orig, %entry ], [%value_loaded, %loop]
+  %squared = mul i32 %cmp, %cmp
+  %val_success = cmpxchg ptr %ptr, i32 %cmp, i32 %squared acq_rel monotonic ; yields  { i32, i1 }
+  %value_loaded = extractvalue { i32, i1 } %val_success, 0
+  %success = extractvalue { i32, i1 } %val_success, 1
+  br i1 %success, label %done, label %loop
+
+done:
+  ...
+
+
+
+`, tooltip: `The ‘cmpxchg’ instruction is used to atomically modify memory. Itloads a value in memory and compares it to a given value. If they areequal, it tries to store a new value into the memory.`, }; case 'ATOMICRMW': return { url: `https://llvm.org/docs/LangRef.html#atomicrmw-instruction`, - html: `

‘atomicrmw’ Instruction

Syntax:
atomicrmw [volatile] <operation> ptr <pointer>, <ty> <value> [syncscope("<target-scope>")] <ordering>[, align <alignment>]  ; yields ty
Overview:

The ‘atomicrmw’ instruction is used to atomically modify memory.

Arguments:

There are three arguments to the ‘atomicrmw’ instruction: anoperation to apply, an address whose value to modify, an argument to theoperation. The operation must be one of the following keywords:

For most of these operations, the type of ‘<value>’ must be an integertype whose bit width is a power of two greater than or equal to eight.For xchg, thismay also be a floating point or a pointer type with the same size constraintsas integers. For fadd/fsub/fmax/fmin/fmaximum/fminimum, this must be a floating-pointor fixed vector of floating-point type. The type of the ‘<pointer>’operand must be a pointer to that type. If the atomicrmw is markedas volatile, then the optimizer is not allowed to modify thenumber or order of execution of this atomicrmw with othervolatile operations.

Note: if the alignment is not greater or equal to the size of the <value>type, the atomic operation is likely to require a lock and have poorperformance.

The alignment is only optional when parsing textual IR; for in-memory IR, it isalways present. If unspecified, the alignment is assumed to be equal to thesize of the ‘<value>’ type. Note that this default alignment assumption isdifferent from the alignment used for the load/store instructions when alignisn’t specified.

An atomicrmw instruction can also take an optional“syncscope” argument.

Semantics:

The contents of memory at the location specified by the ‘<pointer>’operand are atomically read, modified, and written back. The originalvalue at the location is returned. The modification is specified by theoperation argument:

Example:
%old = atomicrmw add ptr %ptr, i32 1 acquire                        ; yields i32
`, + html: `

‘atomicrmw’ Instruction

+
+
Syntax:
+
atomicrmw [volatile] <operation> ptr <pointer>, <ty> <value> [syncscope("<target-scope>")] <ordering>[, align <alignment>]  ; yields ty
+
+
+
+
+
Overview:
+

The ‘atomicrmw’ instruction is used to atomically modify memory.

+
+
+
Arguments:
+

There are three arguments to the ‘atomicrmw’ instruction: an +operation to apply, an address whose value to modify, an argument to the +operation. The operation must be one of the following keywords:

+ +

For most of these operations, the type of ‘<value>’ must be an integer +type whose bit width is a power of two greater than or equal to eight. +For xchg, this +may also be a floating point or a pointer type with the same size constraints +as integers. For fadd/fsub/fmax/fmin/fmaximum/fminimum, this must be a floating-point +or fixed vector of floating-point type. The type of the ‘<pointer>’ +operand must be a pointer to that type. If the atomicrmw is marked +as volatile, then the optimizer is not allowed to modify the +number or order of execution of this atomicrmw with other +volatile operations.

+

Note: if the alignment is not greater or equal to the size of the <value> +type, the atomic operation is likely to require a lock and have poor +performance.

+

The alignment is only optional when parsing textual IR; for in-memory IR, it is +always present. If unspecified, the alignment is assumed to be equal to the +size of the ‘<value>’ type. Note that this default alignment assumption is +different from the alignment used for the load/store instructions when align +isn’t specified.

+

An atomicrmw instruction can also take an optional +“syncscope” argument.

+
+
+
Semantics:
+

The contents of memory at the location specified by the ‘<pointer>’ +operand are atomically read, modified, and written back. The original +value at the location is returned. The modification is specified by the +operation argument:

+ +
+
+
Example:
+
%old = atomicrmw add ptr %ptr, i32 1 acquire                        ; yields i32
+
+
+
+`, tooltip: `The ‘atomicrmw’ instruction is used to atomically modify memory.`, }; case 'GETELEMENTPTR': return { url: `https://llvm.org/docs/LangRef.html#getelementptr-instruction`, - html: `

‘getelementptr’ Instruction

Syntax:
<result> = getelementptr <ty>, ptr <ptrval>{, <ty> <idx>}*<result> = getelementptr inbounds <ty>, ptr <ptrval>{, <ty> <idx>}*<result> = getelementptr nusw <ty>, ptr <ptrval>{, <ty> <idx>}*<result> = getelementptr nuw <ty>, ptr <ptrval>{, <ty> <idx>}*<result> = getelementptr inrange(S,E) <ty>, ptr <ptrval>{, <ty> <idx>}*<result> = getelementptr <ty>, <N x ptr> <ptrval>, <vector index type> <idx>
Overview:

The ‘getelementptr’ instruction is used to get the address of asubelement of an aggregate data structure. It performsaddress calculation only and does not access memory. The instruction can alsobe used to calculate a vector of such addresses.

Arguments:

The first argument is always a type used as the basis for the calculations.The second argument is always a pointer or a vector of pointers, and is thebase address to start from. The remaining arguments are indicesthat indicate which of the elements of the aggregate object are indexed.The interpretation of each index is dependent on the type being indexedinto. The first index always indexes the pointer value given as thesecond argument, the second index indexes a value of the type pointed to(not necessarily the value directly pointed to, since the first indexcan be non-zero), etc. The first type indexed into must be a pointervalue, subsequent types can be arrays, vectors, and structs. Note thatsubsequent types being indexed into can never be pointers, since thatwould require loading the pointer before continuing calculation.

The type of each index argument depends on the type it is indexing into.When indexing into a (optionally packed) structure, only i32 integerconstants are allowed (when using a vector of indices they must allbe the same i32 integer constant). When indexing into an array,pointer or vector, integers of any width are allowed, and they are notrequired to be constant. These integers are treated as signed valueswhere relevant.

For example, let’s consider a C code fragment and how it gets compiledto LLVM:

struct RT {  char A;  int B[10][20];  char C;};struct ST {  int X;  double Y;  struct RT Z;};int *foo(struct ST *s) {  return &s[1].Z.B[5][13];}

The LLVM code generated by Clang is approximately:

%struct.RT = type { i8, [10 x [20 x i32]], i8 }%struct.ST = type { i32, double, %struct.RT }define ptr @foo(ptr %s) {entry:  %arrayidx = getelementptr inbounds %struct.ST, ptr %s, i64 1, i32 2, i32 1, i64 5, i64 13  ret ptr %arrayidx}
Semantics:

In the example above, the first index is indexing into the‘%struct.ST*’ type, which is a pointer, yielding a ‘%struct.ST’= ‘{ i32, double, %struct.RT }’ type, a structure. The second indexindexes into the third element of the structure, yielding a‘%struct.RT’ = ‘{ i8 , [10 x [20 x i32]], i8 }’ type, anotherstructure. The third index indexes into the second element of thestructure, yielding a ‘[10 x [20 x i32]]’ type, an array. The twodimensions of the array are subscripted into, yielding an ‘i32’type. The ‘getelementptr’ instruction returns a pointer to thiselement.

Note that it is perfectly legal to index partially through a structure,returning a pointer to an inner element. Because of this, the LLVM codefor the given testcase is equivalent to:

define ptr @foo(ptr %s) {  %t1 = getelementptr %struct.ST, ptr %s, i32 1  %t2 = getelementptr %struct.ST, ptr %t1, i32 0, i32 2  %t3 = getelementptr %struct.RT, ptr %t2, i32 0, i32 1  %t4 = getelementptr [10 x [20 x i32]], ptr %t3, i32 0, i32 5  %t5 = getelementptr [20 x i32], ptr %t4, i32 0, i32 13  ret ptr %t5}

The indices are first converted to offsets in the pointer’s index type. If thecurrently indexed type is a struct type, the struct offset corresponding to theindex is sign-extended or truncated to the pointer index type. Otherwise, theindex itself is sign-extended or truncated, and then multiplied by the typeallocation size (that is, the size rounded up to the ABI alignment) of thecurrently indexed type.

The offsets are then added to the low bits of the base address up to the indextype width, with silently-wrapping two’s complement arithmetic. If the pointersize is larger than the index size, this means that the bits outside the indextype width will not be affected.

The result value of the getelementptr may be outside the object pointedto by the base pointer. The result value may not necessarily be used to accessmemory though, even if it happens to point into allocated storage. See thePointer Aliasing Rules section for moreinformation.

The getelementptr instruction may have a number of attributes that imposeadditional rules. If any of the rules are violated, the result value is apoison value. In cases where the base is a vector ofpointers, the attributes apply to each computation element-wise.

For nusw (no unsigned signed wrap):

  • If the type of an index is larger than the pointer index type, thetruncation to the pointer index type preserves the signed value(trunc nsw).

  • The multiplication of an index by the type size does not wrap the pointerindex type in a signed sense (mul nsw).

  • The successive addition of each offset (without adding the base address)does not wrap the pointer index type in a signed sense (add nsw).

  • The successive addition of the current address, truncated to the pointerindex type and interpreted as an unsigned number, and each offset,interpreted as a signed number, does not wrap the pointer index type.

For nuw (no unsigned wrap):

  • If the type of an index is larger than the pointer index type, thetruncation to the pointer index type preserves the unsigned value(trunc nuw).

  • The multiplication of an index by the type size does not wrap the pointerindex type in an unsigned sense (mul nuw).

  • The successive addition of each offset (without adding the base address)does not wrap the pointer index type in an unsigned sense (add nuw).

  • The successive addition of the current address, truncated to the pointerindex type and interpreted as an unsigned number, and each offset, alsointerpreted as an unsigned number, does not wrap the pointer index type(add nuw).

For inbounds all rules of the nusw attribute apply. Additionally,if the getelementptr has any non-zero indices, the following rules apply:

  • The base pointer has an in bounds address of theallocated object that it isbased on. This means that it points into thatallocated object, or to its end. Note that the object does not have to belive anymore; being in-bounds of a deallocated object is sufficient.If the allocated object can grow, then the relevant size for being inbounds is the maximal size the object could have while satisfying theallocated object rules, not its current size.

  • During the successive addition of offsets to the address, the resultingpointer must remain in bounds of the allocated object at each step.

Note that getelementptr with all-zero indices is always considered to beinbounds, even if the base pointer does not point to an allocated object.As a corollary, the only pointer in bounds of the null pointer in the defaultaddress space is the null pointer itself.

If inbounds is present on a getelementptr instruction, the nuswattribute will be automatically set as well. For this reason, the nuswwill also not be printed in textual IR if inbounds is already present.

If the inrange(Start, End) attribute is present, loading from orstoring to any pointer derived from the getelementptr has undefinedbehavior if the load or store would access memory outside the half-open range[Start, End) from the getelementptr expression result. The result ofa pointer comparison or ptrtoint (including ptrtoint-like operationsinvolving memory) involving a pointer derived from a getelementptr withthe inrange keyword is undefined, with the exception of comparisonsin the case where both operands are in the closed range [Start, End].Note that the inrange keyword is currently only allowedin constant getelementptr expressions.

The getelementptr instruction is often confusing. For some more insightinto how it works, see the getelementptr FAQ.

Example:
%aptr = getelementptr {i32, [12 x i8]}, ptr %saptr, i64 0, i32 1%vptr = getelementptr {i32, <2 x i8>}, ptr %svptr, i64 0, i32 1, i32 1%eptr = getelementptr [12 x i8], ptr %aptr, i64 0, i32 1%iptr = getelementptr [10 x i32], ptr @arr, i16 0, i16 0
Vector of pointers:

The getelementptr returns a vector of pointers, instead of a single address,when one or more of its arguments is a vector. In such cases, all vectorarguments should have the same number of elements, and every scalar argumentwill be effectively broadcast into a vector during address calculation.

; All arguments are vectors:;   A[i] = ptrs[i] + offsets[i]*sizeof(i8)%A = getelementptr i8, <4 x i8*> %ptrs, <4 x i64> %offsets; Add the same scalar offset to each pointer of a vector:;   A[i] = ptrs[i] + offset*sizeof(i8)%A = getelementptr i8, <4 x ptr> %ptrs, i64 %offset; Add distinct offsets to the same pointer:;   A[i] = ptr + offsets[i]*sizeof(i8)%A = getelementptr i8, ptr %ptr, <4 x i64> %offsets; In all cases described above the type of the result is <4 x ptr>

The two following instructions are equivalent:

getelementptr  %struct.ST, <4 x ptr> %s, <4 x i64> %ind1,  <4 x i32> <i32 2, i32 2, i32 2, i32 2>,  <4 x i32> <i32 1, i32 1, i32 1, i32 1>,  <4 x i32> %ind4,  <4 x i64> <i64 13, i64 13, i64 13, i64 13>getelementptr  %struct.ST, <4 x ptr> %s, <4 x i64> %ind1,  i32 2, i32 1, <4 x i32> %ind4, i64 13

Let’s look at the C code, where the vector version of getelementptrmakes sense:

// Let's assume that we vectorize the following loop:double *A, *B; int *C;for (int i = 0; i < size; ++i) {  A[i] = B[C[i]];}
; get pointers for 8 elements from array B%ptrs = getelementptr double, ptr %B, <8 x i32> %C; load 8 elements from array B into A%A = call <8 x double> @llvm.masked.gather.v8f64.v8p0f64(     <8 x ptr> align 8 %ptrs, <8 x i1> %mask, <8 x double> %passthru)
`, + html: `

‘getelementptr’ Instruction

+
+
Syntax:
+
<result> = getelementptr <ty>, ptr <ptrval>{, <ty> <idx>}*
+<result> = getelementptr inbounds <ty>, ptr <ptrval>{, <ty> <idx>}*
+<result> = getelementptr nusw <ty>, ptr <ptrval>{, <ty> <idx>}*
+<result> = getelementptr nuw <ty>, ptr <ptrval>{, <ty> <idx>}*
+<result> = getelementptr inrange(S,E) <ty>, ptr <ptrval>{, <ty> <idx>}*
+<result> = getelementptr <ty>, <N x ptr> <ptrval>, <vector index type> <idx>
+
+
+
+
+
Overview:
+

The ‘getelementptr’ instruction is used to get the address of a +subelement of an aggregate data structure. It performs +address calculation only and does not access memory. The instruction can also +be used to calculate a vector of such addresses.

+
+
+
Arguments:
+

The first argument is always a type used as the basis for the calculations. +The second argument is always a pointer or a vector of pointers, and is the +base address to start from. The remaining arguments are indices +that indicate which of the elements of the aggregate object are indexed. +The interpretation of each index is dependent on the type being indexed +into. The first index always indexes the pointer value given as the +second argument, the second index indexes a value of the type pointed to +(not necessarily the value directly pointed to, since the first index +can be non-zero), etc. The first type indexed into must be a pointer +value, subsequent types can be arrays, vectors, and structs. Note that +subsequent types being indexed into can never be pointers, since that +would require loading the pointer before continuing calculation.

+

The type of each index argument depends on the type it is indexing into. +When indexing into a (optionally packed) structure, only i32 integer +constants are allowed (when using a vector of indices they must all +be the same i32 integer constant). When indexing into an array, +pointer or vector, integers of any width are allowed, and they are not +required to be constant. These integers are treated as signed values +where relevant.

+

For example, let’s consider a C code fragment and how it gets compiled +to LLVM:

+
struct RT {
+  char A;
+  int B[10][20];
+  char C;
+};
+struct ST {
+  int X;
+  double Y;
+  struct RT Z;
+};
+
+int *foo(struct ST *s) {
+  return &s[1].Z.B[5][13];
+}
+
+
+

The LLVM code generated by Clang is approximately:

+
%struct.RT = type { i8, [10 x [20 x i32]], i8 }
+%struct.ST = type { i32, double, %struct.RT }
+
+define ptr @foo(ptr %s) {
+entry:
+  %arrayidx = getelementptr inbounds %struct.ST, ptr %s, i64 1, i32 2, i32 1, i64 5, i64 13
+  ret ptr %arrayidx
+}
+
+
+
+
+
Semantics:
+

In the example above, the first index is indexing into the +‘%struct.ST*’ type, which is a pointer, yielding a ‘%struct.ST’ += ‘{ i32, double, %struct.RT }’ type, a structure. The second index +indexes into the third element of the structure, yielding a +‘%struct.RT’ = ‘{ i8 , [10 x [20 x i32]], i8 }’ type, another +structure. The third index indexes into the second element of the +structure, yielding a ‘[10 x [20 x i32]]’ type, an array. The two +dimensions of the array are subscripted into, yielding an ‘i32’ +type. The ‘getelementptr’ instruction returns a pointer to this +element.

+

Note that it is perfectly legal to index partially through a structure, +returning a pointer to an inner element. Because of this, the LLVM code +for the given testcase is equivalent to:

+
define ptr @foo(ptr %s) {
+  %t1 = getelementptr %struct.ST, ptr %s, i32 1
+  %t2 = getelementptr %struct.ST, ptr %t1, i32 0, i32 2
+  %t3 = getelementptr %struct.RT, ptr %t2, i32 0, i32 1
+  %t4 = getelementptr [10 x [20 x i32]], ptr %t3, i32 0, i32 5
+  %t5 = getelementptr [20 x i32], ptr %t4, i32 0, i32 13
+  ret ptr %t5
+}
+
+
+

The indices are first converted to offsets in the pointer’s index type. If the +currently indexed type is a struct type, the struct offset corresponding to the +index is sign-extended or truncated to the pointer index type. Otherwise, the +index itself is sign-extended or truncated, and then multiplied by the type +allocation size (that is, the size rounded up to the ABI alignment) of the +currently indexed type.

+

The offsets are then added to the low bits of the base address up to the index +type width, with silently-wrapping two’s complement arithmetic. If the pointer +size is larger than the index size, this means that the bits outside the index +type width will not be affected.

+

The result value of the getelementptr may be outside the object pointed +to by the base pointer. The result value may not necessarily be used to access +memory though, even if it happens to point into allocated storage. See the +Pointer Aliasing Rules section for more +information.

+

The getelementptr instruction may have a number of attributes that impose +additional rules. If any of the rules are violated, the result value is a +poison value. In cases where the base is a vector of +pointers, the attributes apply to each computation element-wise.

+

For nusw (no unsigned signed wrap):

+
+
    +

  • If the type of an index is larger than the pointer index type, the +truncation to the pointer index type preserves the signed value +(trunc nsw).

    • +

  • The multiplication of an index by the type size does not wrap the pointer +index type in a signed sense (mul nsw).

    • +

  • The successive addition of each offset (without adding the base address) +does not wrap the pointer index type in a signed sense (add nsw).

    • +

  • The successive addition of the current address, truncated to the pointer +index type and interpreted as an unsigned number, and each offset, +interpreted as a signed number, does not wrap the pointer index type.

    • +
+
+

For nuw (no unsigned wrap):

+
+
    +

  • If the type of an index is larger than the pointer index type, the +truncation to the pointer index type preserves the unsigned value +(trunc nuw).

    • +

  • The multiplication of an index by the type size does not wrap the pointer +index type in an unsigned sense (mul nuw).

    • +

  • The successive addition of each offset (without adding the base address) +does not wrap the pointer index type in an unsigned sense (add nuw).

    • +

  • The successive addition of the current address, truncated to the pointer +index type and interpreted as an unsigned number, and each offset, also +interpreted as an unsigned number, does not wrap the pointer index type +(add nuw).

    • +
+
+

For inbounds all rules of the nusw attribute apply. Additionally, +if the getelementptr has any non-zero indices, the following rules apply:

+
+
    +

  • The base pointer has an in bounds address of the +allocated object that it is +based on. This means that it points into that +allocated object, or to its end. Note that the object does not have to be +live anymore; being in-bounds of a deallocated object is sufficient. +If the allocated object can grow, then the relevant size for being in +bounds is the maximal size the object could have while satisfying the +allocated object rules, not its current size.

    • +

  • During the successive addition of offsets to the address, the resulting +pointer must remain in bounds of the allocated object at each step.

    • +
+
+

Note that getelementptr with all-zero indices is always considered to be +inbounds, even if the base pointer does not point to an allocated object. +As a corollary, the only pointer in bounds of the null pointer in the default +address space is the null pointer itself.

+

If inbounds is present on a getelementptr instruction, the nusw +attribute will be automatically set as well. For this reason, the nusw +will also not be printed in textual IR if inbounds is already present.

+

If the inrange(Start, End) attribute is present, loading from or +storing to any pointer derived from the getelementptr has undefined +behavior if the load or store would access memory outside the half-open range +[Start, End) from the getelementptr expression result. The result of +a pointer comparison or ptrtoint (including ptrtoint-like operations +involving memory) involving a pointer derived from a getelementptr with +the inrange keyword is undefined, with the exception of comparisons +in the case where both operands are in the closed range [Start, End]. +Note that the inrange keyword is currently only allowed +in constant getelementptr expressions.

+

The getelementptr instruction is often confusing. For some more insight +into how it works, see the getelementptr FAQ.

+
+
+
Example:
+
%aptr = getelementptr {i32, [12 x i8]}, ptr %saptr, i64 0, i32 1
+%vptr = getelementptr {i32, <2 x i8>}, ptr %svptr, i64 0, i32 1, i32 1
+%eptr = getelementptr [12 x i8], ptr %aptr, i64 0, i32 1
+%iptr = getelementptr [10 x i32], ptr @arr, i16 0, i16 0
+
+
+
+
+
Vector of pointers:
+

The getelementptr returns a vector of pointers, instead of a single address, +when one or more of its arguments is a vector. In such cases, all vector +arguments should have the same number of elements, and every scalar argument +will be effectively broadcast into a vector during address calculation.

+
; All arguments are vectors:
+;   A[i] = ptrs[i] + offsets[i]*sizeof(i8)
+%A = getelementptr i8, <4 x i8*> %ptrs, <4 x i64> %offsets
+
+; Add the same scalar offset to each pointer of a vector:
+;   A[i] = ptrs[i] + offset*sizeof(i8)
+%A = getelementptr i8, <4 x ptr> %ptrs, i64 %offset
+
+; Add distinct offsets to the same pointer:
+;   A[i] = ptr + offsets[i]*sizeof(i8)
+%A = getelementptr i8, ptr %ptr, <4 x i64> %offsets
+
+; In all cases described above the type of the result is <4 x ptr>
+
+
+

The two following instructions are equivalent:

+
getelementptr  %struct.ST, <4 x ptr> %s, <4 x i64> %ind1,
+  <4 x i32> <i32 2, i32 2, i32 2, i32 2>,
+  <4 x i32> <i32 1, i32 1, i32 1, i32 1>,
+  <4 x i32> %ind4,
+  <4 x i64> <i64 13, i64 13, i64 13, i64 13>
+
+getelementptr  %struct.ST, <4 x ptr> %s, <4 x i64> %ind1,
+  i32 2, i32 1, <4 x i32> %ind4, i64 13
+
+
+

Let’s look at the C code, where the vector version of getelementptr +makes sense:

+
// Let's assume that we vectorize the following loop:
+double *A, *B; int *C;
+for (int i = 0; i < size; ++i) {
+  A[i] = B[C[i]];
+}
+
+
+
; get pointers for 8 elements from array B
+%ptrs = getelementptr double, ptr %B, <8 x i32> %C
+; load 8 elements from array B into A
+%A = call <8 x double> @llvm.masked.gather.v8f64.v8p0f64(
+     <8 x ptr> align 8 %ptrs, <8 x i1> %mask, <8 x double> %passthru)
+
+
+
+`, tooltip: `The ‘getelementptr’ instruction is used to get the address of asubelement of an aggregate data structure. It performsaddress calculation only and does not access memory. The instruction can alsobe used to calculate a vector of such addresses.`, }; case 'TRUNC': return { url: `https://llvm.org/docs/LangRef.html#trunc-to-instruction`, - html: `

‘trunc .. to’ Instruction

Syntax:
<result> = trunc <ty> <value> to <ty2>             ; yields ty2<result> = trunc nsw <ty> <value> to <ty2>         ; yields ty2<result> = trunc nuw <ty> <value> to <ty2>         ; yields ty2<result> = trunc nuw nsw <ty> <value> to <ty2>     ; yields ty2
Overview:

The ‘trunc’ instruction truncates its operand to the type ty2.

Arguments:

The ‘trunc’ instruction takes a value to trunc, and a type to truncit to. Both types must be of integer types, or vectorsof the same number of integers. The bit size of the value must belarger than the bit size of the destination type, ty2. Equal sizedtypes are not allowed.

Semantics:

The ‘trunc’ instruction truncates the high order bits in valueand converts the remaining bits to ty2. Since the source size mustbe larger than the destination size, trunc cannot be a no-op cast.It will always truncate bits.

If the nuw keyword is present, and any of the truncated bits are non-zero,the result is a poison value. If the nsw keywordis present, and any of the truncated bits are not the same as the top bitof the truncation result, the result is a poison value.

Example:
%X = trunc i32 257 to i8                        ; yields i8:1%Y = trunc i32 123 to i1                        ; yields i1:true%Z = trunc i32 122 to i1                        ; yields i1:false%W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> ; yields <i8 8, i8 7>
`, + html: `

‘trunc .. to’ Instruction

+
+
Syntax:
+
<result> = trunc <ty> <value> to <ty2>             ; yields ty2
+<result> = trunc nsw <ty> <value> to <ty2>         ; yields ty2
+<result> = trunc nuw <ty> <value> to <ty2>         ; yields ty2
+<result> = trunc nuw nsw <ty> <value> to <ty2>     ; yields ty2
+
+
+
+
+
Overview:
+

The ‘trunc’ instruction truncates its operand to the type ty2.

+
+
+
Arguments:
+

The ‘trunc’ instruction takes a value to trunc, and a type to trunc +it to. Both types must be of integer types, or vectors +of the same number of integers. The bit size of the value must be +larger than the bit size of the destination type, ty2. Equal sized +types are not allowed.

+
+
+
Semantics:
+

The ‘trunc’ instruction truncates the high order bits in value +and converts the remaining bits to ty2. Since the source size must +be larger than the destination size, trunc cannot be a no-op cast. +It will always truncate bits.

+

If the nuw keyword is present, and any of the truncated bits are non-zero, +the result is a poison value. If the nsw keyword +is present, and any of the truncated bits are not the same as the top bit +of the truncation result, the result is a poison value.

+
+
+
Example:
+
%X = trunc i32 257 to i8                        ; yields i8:1
+%Y = trunc i32 123 to i1                        ; yields i1:true
+%Z = trunc i32 122 to i1                        ; yields i1:false
+%W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> ; yields <i8 8, i8 7>
+
+
+
+`, tooltip: `The ‘trunc’ instruction truncates its operand to the type ty2.`, }; case 'ZEXT': return { url: `https://llvm.org/docs/LangRef.html#zext-to-instruction`, - html: `

‘zext .. to’ Instruction

Syntax:
<result> = zext <ty> <value> to <ty2>             ; yields ty2
Overview:

The ‘zext’ instruction zero extends its operand to type ty2.

The nneg (non-negative) flag, if present, specifies that the operand isnon-negative. This property may be used by optimization passes to laterconvert the zext into a sext.

Arguments:

The ‘zext’ instruction takes a value to cast, and a type to cast itto. Both types must be of integer types, or vectors ofthe same number of integers. The bit size of the value must besmaller than the bit size of the destination type, ty2.

Semantics:

The zext fills the high order bits of the value with zero bitsuntil it reaches the size of the destination type, ty2.

When zero extending from i1, the result will always be either 0 or 1.

If the nneg flag is set, and the zext argument is negative, the resultis a poison value.

Example:
%X = zext i32 257 to i64              ; yields i64:257%Y = zext i1 true to i32              ; yields i32:1%Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>%a = zext nneg i8 127 to i16 ; yields i16 127%b = zext nneg i8 -1 to i16  ; yields i16 poison
`, + html: `

‘zext .. to’ Instruction

+
+
Syntax:
+
<result> = zext <ty> <value> to <ty2>             ; yields ty2
+
+
+
+
+
Overview:
+

The ‘zext’ instruction zero extends its operand to type ty2.

+

The nneg (non-negative) flag, if present, specifies that the operand is +non-negative. This property may be used by optimization passes to later +convert the zext into a sext.

+
+
+
Arguments:
+

The ‘zext’ instruction takes a value to cast, and a type to cast it +to. Both types must be of integer types, or vectors of +the same number of integers. The bit size of the value must be +smaller than the bit size of the destination type, ty2.

+
+
+
Semantics:
+

The zext fills the high order bits of the value with zero bits +until it reaches the size of the destination type, ty2.

+

When zero extending from i1, the result will always be either 0 or 1.

+

If the nneg flag is set, and the zext argument is negative, the result +is a poison value.

+
+
+
Example:
+
%X = zext i32 257 to i64              ; yields i64:257
+%Y = zext i1 true to i32              ; yields i32:1
+%Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>
+
+%a = zext nneg i8 127 to i16 ; yields i16 127
+%b = zext nneg i8 -1 to i16  ; yields i16 poison
+
+
+
+`, tooltip: `The ‘zext’ instruction zero extends its operand to type ty2.The nneg (non-negative) flag, if present, specifies that the operand isnon-negative. This property may be used by optimization passes to laterconvert the zext into a sext.`, }; case 'SEXT': return { url: `https://llvm.org/docs/LangRef.html#sext-to-instruction`, - html: `

‘sext .. to’ Instruction

Syntax:
<result> = sext <ty> <value> to <ty2>             ; yields ty2
Overview:

The ‘sext’ sign extends value to the type ty2.

Arguments:

The ‘sext’ instruction takes a value to cast, and a type to cast itto. Both types must be of integer types, or vectors ofthe same number of integers. The bit size of the value must besmaller than the bit size of the destination type, ty2.

Semantics:

The ‘sext’ instruction performs a sign extension by copying the signbit (highest order bit) of the value until it reaches the bit sizeof the type ty2.

When sign extending from i1, the extension always results in -1 or 0.

Example:
%X = sext i8  -1 to i16              ; yields i16   :65535%Y = sext i1 true to i32             ; yields i32:-1%Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>
`, + html: `

‘sext .. to’ Instruction

+
+
Syntax:
+
<result> = sext <ty> <value> to <ty2>             ; yields ty2
+
+
+
+
+
Overview:
+

The ‘sext’ sign extends value to the type ty2.

+
+
+
Arguments:
+

The ‘sext’ instruction takes a value to cast, and a type to cast it +to. Both types must be of integer types, or vectors of +the same number of integers. The bit size of the value must be +smaller than the bit size of the destination type, ty2.

+
+
+
Semantics:
+

The ‘sext’ instruction performs a sign extension by copying the sign +bit (highest order bit) of the value until it reaches the bit size +of the type ty2.

+

When sign extending from i1, the extension always results in -1 or 0.

+
+
+
Example:
+
%X = sext i8  -1 to i16              ; yields i16   :65535
+%Y = sext i1 true to i32             ; yields i32:-1
+%Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>
+
+
+
+`, tooltip: `The ‘sext’ sign extends value to the type ty2.`, }; case 'FPTRUNC': return { url: `https://llvm.org/docs/LangRef.html#fptrunc-to-instruction`, - html: `

‘fptrunc .. to’ Instruction

Syntax:
<result> = fptrunc [fast-math flags]* <ty> <value> to <ty2> ; yields ty2
Overview:

The ‘fptrunc’ instruction truncates value to type ty2.

Arguments:

The ‘fptrunc’ instruction takes a floating-pointvalue to cast and a floating-point type to cast it to.The size of value must be larger than the size of ty2. Thisimplies that fptrunc cannot be used to make a no-op cast.

Semantics:

The ‘fptrunc’ instruction casts a value from a largerfloating-point type to a smaller floating-point type.This instruction is assumed to execute in the default floating-pointenvironment.

NaN values follow the usual NaN behaviors, except that _if_ aNaN payload is propagated from the input (“Quieting NaN propagation” or“Unchanged NaN propagation” cases), then the low order bits of the NaN payloadwhich cannot fit in the resulting type are discarded. Note that if discardingthe low order bits leads to an all-0 payload, this cannot be represented as asignaling NaN (it would represent an infinity instead), so in that case“Unchanged NaN propagation” is not possible.

This instruction can also take any number of fast-mathflags, which are optimization hints to enable otherwiseunsafe floating-point optimizations.

Example:
%X = fptrunc double 16777217.0 to float    ; yields float:16777216.0%Y = fptrunc double 1.0E+300 to half       ; yields half:+infinity
`, + html: `

‘fptrunc .. to’ Instruction

+
+
Syntax:
+
<result> = fptrunc [fast-math flags]* <ty> <value> to <ty2> ; yields ty2
+
+
+
+
+
Overview:
+

The ‘fptrunc’ instruction truncates value to type ty2.

+
+
+
Arguments:
+

The ‘fptrunc’ instruction takes a floating-point +value to cast and a floating-point type to cast it to. +The size of value must be larger than the size of ty2. This +implies that fptrunc cannot be used to make a no-op cast.

+
+
+
Semantics:
+

The ‘fptrunc’ instruction casts a value from a larger +floating-point type to a smaller floating-point type. +This instruction is assumed to execute in the default floating-point +environment.

+

NaN values follow the usual NaN behaviors, except that _if_ a +NaN payload is propagated from the input (“Quieting NaN propagation” or +“Unchanged NaN propagation” cases), then the low order bits of the NaN payload +which cannot fit in the resulting type are discarded. Note that if discarding +the low order bits leads to an all-0 payload, this cannot be represented as a +signaling NaN (it would represent an infinity instead), so in that case +“Unchanged NaN propagation” is not possible.

+

This instruction can also take any number of fast-math +flags, which are optimization hints to enable otherwise +unsafe floating-point optimizations.

+
+
+
Example:
+
%X = fptrunc double 16777217.0 to float    ; yields float:16777216.0
+%Y = fptrunc double 1.0E+300 to half       ; yields half:+infinity
+
+
+
+`, tooltip: `The ‘fptrunc’ instruction truncates value to type ty2.`, }; case 'FPEXT': return { url: `https://llvm.org/docs/LangRef.html#fpext-to-instruction`, - html: `

‘fpext .. to’ Instruction

Syntax:
<result> = fpext [fast-math flags]* <ty> <value> to <ty2> ; yields ty2
Overview:

The ‘fpext’ extends a floating-point value to a larger floating-pointvalue.

Arguments:

The ‘fpext’ instruction takes a floating-pointvalue to cast, and a floating-point type to cast itto. The source type must be smaller than the destination type.

Semantics:

The ‘fpext’ instruction extends the value from a smallerfloating-point type to a larger floating-point type. The fpext cannot be used to make ano-op cast because it always changes bits. Use bitcast to make ano-op cast for a floating-point cast.

NaN values follow the usual NaN behaviors, except that _if_ aNaN payload is propagated from the input (“Quieting NaN propagation” or“Unchanged NaN propagation” cases), then it is copied to the high order bits ofthe resulting payload, and the remaining low order bits are zero.

This instruction can also take any number of fast-mathflags, which are optimization hints to enable otherwiseunsafe floating-point optimizations.

Example:
%X = fpext float 3.125 to double         ; yields double:3.125000e+00%Y = fpext double %X to fp128            ; yields fp128:0xL00000000000000004000900000000000
`, + html: `

‘fpext .. to’ Instruction

+
+
Syntax:
+
<result> = fpext [fast-math flags]* <ty> <value> to <ty2> ; yields ty2
+
+
+
+
+
Overview:
+

The ‘fpext’ extends a floating-point value to a larger floating-point +value.

+
+
+
Arguments:
+

The ‘fpext’ instruction takes a floating-point +value to cast, and a floating-point type to cast it +to. The source type must be smaller than the destination type.

+
+
+
Semantics:
+

The ‘fpext’ instruction extends the value from a smaller +floating-point type to a larger floating-point type. The fpext cannot be used to make a +no-op cast because it always changes bits. Use bitcast to make a +no-op cast for a floating-point cast.

+

NaN values follow the usual NaN behaviors, except that _if_ a +NaN payload is propagated from the input (“Quieting NaN propagation” or +“Unchanged NaN propagation” cases), then it is copied to the high order bits of +the resulting payload, and the remaining low order bits are zero.

+

This instruction can also take any number of fast-math +flags, which are optimization hints to enable otherwise +unsafe floating-point optimizations.

+
+
+
Example:
+
%X = fpext float 3.125 to double         ; yields double:3.125000e+00
+%Y = fpext double %X to fp128            ; yields fp128:0xL00000000000000004000900000000000
+
+
+
+`, tooltip: `The ‘fpext’ extends a floating-point value to a larger floating-pointvalue.`, }; case 'FPTOUI': return { url: `https://llvm.org/docs/LangRef.html#fptoui-to-instruction`, - html: `

‘fptoui .. to’ Instruction

Syntax:
<result> = fptoui <ty> <value> to <ty2>             ; yields ty2
Overview:

The ‘fptoui’ converts a floating-point value to its unsignedinteger equivalent of type ty2.

Arguments:

The ‘fptoui’ instruction takes a value to cast, which must be ascalar or vector floating-point value, and a type tocast it to ty2, which must be an integer type. Ifty is a vector floating-point type, ty2 must be a vector integertype with the same number of elements as ty

Semantics:

The ‘fptoui’ instruction converts its floating-point operand into the nearest (rounding towards zero)unsigned integer value. If the value cannot fit in ty2, the resultis a poison value.

Example:
%X = fptoui double 123.0 to i32      ; yields i32:123%Y = fptoui float 1.0E+300 to i1     ; yields undefined:1%Z = fptoui float 1.04E+17 to i8     ; yields undefined:1
`, + html: `

‘fptoui .. to’ Instruction

+
+
Syntax:
+
<result> = fptoui <ty> <value> to <ty2>             ; yields ty2
+
+
+
+
+
Overview:
+

The ‘fptoui’ converts a floating-point value to its unsigned +integer equivalent of type ty2.

+
+
+
Arguments:
+

The ‘fptoui’ instruction takes a value to cast, which must be a +scalar or vector floating-point value, and a type to +cast it to ty2, which must be an integer type. If +ty is a vector floating-point type, ty2 must be a vector integer +type with the same number of elements as ty

+
+
+
Semantics:
+

The ‘fptoui’ instruction converts its floating-point operand into the nearest (rounding towards zero) +unsigned integer value. If the value cannot fit in ty2, the result +is a poison value.

+
+
+
Example:
+
%X = fptoui double 123.0 to i32      ; yields i32:123
+%Y = fptoui float 1.0E+300 to i1     ; yields undefined:1
+%Z = fptoui float 1.04E+17 to i8     ; yields undefined:1
+
+
+
+`, tooltip: `The ‘fptoui’ converts a floating-point value to its unsignedinteger equivalent of type ty2.`, }; case 'FPTOSI': return { url: `https://llvm.org/docs/LangRef.html#fptosi-to-instruction`, - html: `

‘fptosi .. to’ Instruction

Syntax:
<result> = fptosi <ty> <value> to <ty2>             ; yields ty2
Overview:

The ‘fptosi’ instruction converts floating-pointvalue to type ty2.

Arguments:

The ‘fptosi’ instruction takes a value to cast, which must be ascalar or vector floating-point value, and a type tocast it to ty2, which must be an integer type. Ifty is a vector floating-point type, ty2 must be a vector integertype with the same number of elements as ty

Semantics:

The ‘fptosi’ instruction converts its floating-point operand into the nearest (rounding towards zero)signed integer value. If the value cannot fit in ty2, the resultis a poison value.

Example:
%X = fptosi double -123.0 to i32      ; yields i32:-123%Y = fptosi float 1.0E-247 to i1      ; yields undefined:1%Z = fptosi float 1.04E+17 to i8      ; yields undefined:1
`, + html: `

‘fptosi .. to’ Instruction

+
+
Syntax:
+
<result> = fptosi <ty> <value> to <ty2>             ; yields ty2
+
+
+
+
+
Overview:
+

The ‘fptosi’ instruction converts floating-point +value to type ty2.

+
+
+
Arguments:
+

The ‘fptosi’ instruction takes a value to cast, which must be a +scalar or vector floating-point value, and a type to +cast it to ty2, which must be an integer type. If +ty is a vector floating-point type, ty2 must be a vector integer +type with the same number of elements as ty

+
+
+
Semantics:
+

The ‘fptosi’ instruction converts its floating-point operand into the nearest (rounding towards zero) +signed integer value. If the value cannot fit in ty2, the result +is a poison value.

+
+
+
Example:
+
%X = fptosi double -123.0 to i32      ; yields i32:-123
+%Y = fptosi float 1.0E-247 to i1      ; yields undefined:1
+%Z = fptosi float 1.04E+17 to i8      ; yields undefined:1
+
+
+
+`, tooltip: `The ‘fptosi’ instruction converts floating-pointvalue to type ty2.`, }; case 'UITOFP': return { url: `https://llvm.org/docs/LangRef.html#uitofp-to-instruction`, - html: `

‘uitofp .. to’ Instruction

Syntax:
<result> = uitofp <ty> <value> to <ty2>             ; yields ty2
Overview:

The ‘uitofp’ instruction regards value as an unsigned integerand converts that value to the ty2 type.

The nneg (non-negative) flag, if present, specifies that theoperand is non-negative. This property may be used by optimizationpasses to later convert the uitofp into a sitofp.

Arguments:

The ‘uitofp’ instruction takes a value to cast, which must be ascalar or vector integer value, and a type to cast it toty2, which must be an floating-point type. Ifty is a vector integer type, ty2 must be a vector floating-pointtype with the same number of elements as ty

Semantics:

The ‘uitofp’ instruction interprets its operand as an unsignedinteger quantity and converts it to the corresponding floating-pointvalue. If the value cannot be exactly represented, it is rounded usingthe default rounding mode.

If the nneg flag is set, and the uitofp argument is negative,the result is a poison value.

Example:
%X = uitofp i32 257 to float         ; yields float:257.0%Y = uitofp i8 -1 to double          ; yields double:255.0%a = uitofp nneg i32 256 to i32      ; yields float:256.0%b = uitofp nneg i32 -256 to i32     ; yields i32 poison
`, + html: `

‘uitofp .. to’ Instruction

+
+
Syntax:
+
<result> = uitofp <ty> <value> to <ty2>             ; yields ty2
+
+
+
+
+
Overview:
+

The ‘uitofp’ instruction regards value as an unsigned integer +and converts that value to the ty2 type.

+

The nneg (non-negative) flag, if present, specifies that the +operand is non-negative. This property may be used by optimization +passes to later convert the uitofp into a sitofp.

+
+
+
Arguments:
+

The ‘uitofp’ instruction takes a value to cast, which must be a +scalar or vector integer value, and a type to cast it to +ty2, which must be an floating-point type. If +ty is a vector integer type, ty2 must be a vector floating-point +type with the same number of elements as ty

+
+
+
Semantics:
+

The ‘uitofp’ instruction interprets its operand as an unsigned +integer quantity and converts it to the corresponding floating-point +value. If the value cannot be exactly represented, it is rounded using +the default rounding mode.

+

If the nneg flag is set, and the uitofp argument is negative, +the result is a poison value.

+
+
+
Example:
+
%X = uitofp i32 257 to float         ; yields float:257.0
+%Y = uitofp i8 -1 to double          ; yields double:255.0
+
+%a = uitofp nneg i32 256 to i32      ; yields float:256.0
+%b = uitofp nneg i32 -256 to i32     ; yields i32 poison
+
+
+
+`, tooltip: `The ‘uitofp’ instruction regards value as an unsigned integerand converts that value to the ty2 type.The nneg (non-negative) flag, if present, specifies that theoperand is non-negative. This property may be used by optimizationpasses to later convert the uitofp into a sitofp.`, }; case 'SITOFP': return { url: `https://llvm.org/docs/LangRef.html#sitofp-to-instruction`, - html: `

‘sitofp .. to’ Instruction

Syntax:
<result> = sitofp <ty> <value> to <ty2>             ; yields ty2
Overview:

The ‘sitofp’ instruction regards value as a signed integer andconverts that value to the ty2 type.

Arguments:

The ‘sitofp’ instruction takes a value to cast, which must be ascalar or vector integer value, and a type to cast it toty2, which must be an floating-point type. Ifty is a vector integer type, ty2 must be a vector floating-pointtype with the same number of elements as ty

Semantics:

The ‘sitofp’ instruction interprets its operand as a signed integerquantity and converts it to the corresponding floating-point value. If thevalue cannot be exactly represented, it is rounded using the default roundingmode.

Example:
%X = sitofp i32 257 to float         ; yields float:257.0%Y = sitofp i8 -1 to double          ; yields double:-1.0
`, + html: `

‘sitofp .. to’ Instruction

+
+
Syntax:
+
<result> = sitofp <ty> <value> to <ty2>             ; yields ty2
+
+
+
+
+
Overview:
+

The ‘sitofp’ instruction regards value as a signed integer and +converts that value to the ty2 type.

+
+
+
Arguments:
+

The ‘sitofp’ instruction takes a value to cast, which must be a +scalar or vector integer value, and a type to cast it to +ty2, which must be an floating-point type. If +ty is a vector integer type, ty2 must be a vector floating-point +type with the same number of elements as ty

+
+
+
Semantics:
+

The ‘sitofp’ instruction interprets its operand as a signed integer +quantity and converts it to the corresponding floating-point value. If the +value cannot be exactly represented, it is rounded using the default rounding +mode.

+
+
+
Example:
+
%X = sitofp i32 257 to float         ; yields float:257.0
+%Y = sitofp i8 -1 to double          ; yields double:-1.0
+
+
+
+`, tooltip: `The ‘sitofp’ instruction regards value as a signed integer andconverts that value to the ty2 type.`, }; case 'PTRTOINT': return { url: `https://llvm.org/docs/LangRef.html#ptrtoint-to-instruction`, - html: `

‘ptrtoint .. to’ Instruction

Syntax:
<result> = ptrtoint <ty> <value> to <ty2>             ; yields ty2
Overview:

The ‘ptrtoint’ instruction converts the pointer or a vector ofpointers value to the integer (or vector of integers) type ty2.

Arguments:

The ‘ptrtoint’ instruction takes a value to cast, which must bea value of type pointer or a vector of pointers, and atype to cast it to ty2, which must be an integer ora vector of integers type.

Semantics:

The ‘ptrtoint’ instruction converts value to integer typety2 by interpreting all the pointer representation bits as an integer(equivalent to a bitcast) and either truncating or zero extending that valueto the size of the integer type.If value is smaller than ty2 then a zero extension is done. Ifvalue is larger than ty2 then a truncation is done. If they arethe same size, then nothing is done (no-op cast) other than a typechange.The ptrtoint always captures address and provenanceof the pointer argument.

Example:
%X = ptrtoint ptr %P to i8                         ; yields truncation on 32-bit architecture%Y = ptrtoint ptr %P to i64                        ; yields zero extension on 32-bit architecture%Z = ptrtoint <4 x ptr> %P to <4 x i64>; yields vector zero extension for a vector of addresses on 32-bit architecture
`, + html: `

‘ptrtoint .. to’ Instruction

+
+
Syntax:
+
<result> = ptrtoint <ty> <value> to <ty2>             ; yields ty2
+
+
+
+
+
Overview:
+

The ‘ptrtoint’ instruction converts the pointer or a vector of +pointers value to the integer (or vector of integers) type ty2.

+
+
+
Arguments:
+

The ‘ptrtoint’ instruction takes a value to cast, which must be +a value of type pointer or a vector of pointers, and a +type to cast it to ty2, which must be an integer or +a vector of integers type.

+
+
+
Semantics:
+

The ‘ptrtoint’ instruction converts value to integer type +ty2 by interpreting all the pointer representation bits as an integer +(equivalent to a bitcast) and either truncating or zero extending that value +to the size of the integer type. +If value is smaller than ty2 then a zero extension is done. If +value is larger than ty2 then a truncation is done. If they are +the same size, then nothing is done (no-op cast) other than a type +change. +The ptrtoint always captures address and provenance +of the pointer argument.

+
+
+
Example:
+
%X = ptrtoint ptr %P to i8                         ; yields truncation on 32-bit architecture
+%Y = ptrtoint ptr %P to i64                        ; yields zero extension on 32-bit architecture
+%Z = ptrtoint <4 x ptr> %P to <4 x i64>; yields vector zero extension for a vector of addresses on 32-bit architecture
+
+
+
+`, tooltip: `The ‘ptrtoint’ instruction converts the pointer or a vector ofpointers value to the integer (or vector of integers) type ty2.`, }; case 'PTRTOADDR': return { url: `https://llvm.org/docs/LangRef.html#ptrtoaddr-to-instruction`, - html: `

‘ptrtoaddr .. to’ Instruction

Syntax:
<result> = ptrtoaddr <ty> <value> to <ty2>             ; yields ty2
Overview:

The ‘ptrtoaddr’ instruction converts the pointer or a vector ofpointers value to the underlying integer address (or vector of addresses) oftype ty2. This is different from ptrtoint in that itonly operates on the index bits of the pointer and ignores all other bits, anddoes not capture the provenance of the pointer.

Arguments:

The ‘ptrtoaddr’ instruction takes a value to cast, which must bea value of type pointer or a vector of pointers, and atype to cast it to ty2, which must be must be the integertype (or vector of integers) matching the pointer index width of the addressspace of ty.

Semantics:

The ‘ptrtoaddr’ instruction converts value to integer type ty2 byinterpreting the lowest index-width pointer representation bits as an integer.If the address size and the pointer representation size are the same andvalue and ty2 are the same size, then nothing is done (no-op cast)other than a type change.

The ptrtoaddr instruction always captures the address but not the provenanceof the pointer argument.

Example:

This example assumes pointers in address space 1 are 64 bits in size with anaddress width of 32 bits (p1:64:64:64:32 datalayout string)

%X = ptrtoaddr ptr addrspace(1) %P to i32              ; extracts low 32 bits of pointer%Y = ptrtoaddr <4 x ptr addrspace(1)> %P to <4 x i32>  ; yields vector of low 32 bits for each pointer
`, + html: `

‘ptrtoaddr .. to’ Instruction

+
+
Syntax:
+
<result> = ptrtoaddr <ty> <value> to <ty2>             ; yields ty2
+
+
+
+
+
Overview:
+

The ‘ptrtoaddr’ instruction converts the pointer or a vector of +pointers value to the underlying integer address (or vector of addresses) of +type ty2. This is different from ptrtoint in that it +only operates on the index bits of the pointer and ignores all other bits, and +does not capture the provenance of the pointer.

+
+
+
Arguments:
+

The ‘ptrtoaddr’ instruction takes a value to cast, which must be +a value of type pointer or a vector of pointers, and a +type to cast it to ty2, which must be must be the integer +type (or vector of integers) matching the pointer index width of the address +space of ty.

+
+
+
Semantics:
+

The ‘ptrtoaddr’ instruction converts value to integer type ty2 by +interpreting the lowest index-width pointer representation bits as an integer. +If the address size and the pointer representation size are the same and +value and ty2 are the same size, then nothing is done (no-op cast) +other than a type change.

+

The ptrtoaddr instruction always captures the address but not the provenance +of the pointer argument.

+
+
+
Example:
+

This example assumes pointers in address space 1 are 64 bits in size with an +address width of 32 bits (p1:64:64:64:32 datalayout string)

+
%X = ptrtoaddr ptr addrspace(1) %P to i32              ; extracts low 32 bits of pointer
+%Y = ptrtoaddr <4 x ptr addrspace(1)> %P to <4 x i32>  ; yields vector of low 32 bits for each pointer
+
+
+
+`, tooltip: `The ‘ptrtoaddr’ instruction converts the pointer or a vector ofpointers value to the underlying integer address (or vector of addresses) oftype ty2. This is different from ptrtoint in that itonly operates on the index bits of the pointer and ignores all other bits, anddoes not capture the provenance of the pointer.`, }; case 'INTTOPTR': return { url: `https://llvm.org/docs/LangRef.html#inttoptr-to-instruction`, - html: `

‘inttoptr .. to’ Instruction

Syntax:
<result> = inttoptr <ty> <value> to <ty2>[, !dereferenceable !<deref_bytes_node>][, !dereferenceable_or_null !<deref_bytes_node>][, !nofree !<empty_node>]            ; yields ty2
Overview:

The ‘inttoptr’ instruction converts an integer value to apointer type, ty2.

Arguments:

The ‘inttoptr’ instruction takes an integer value tocast, and a type to cast it to, which must be a pointertype.

The optional !dereferenceable metadata must reference a single metadataname <deref_bytes_node> corresponding to a metadata node with one i64entry.See dereferenceable metadata.

The optional !dereferenceable_or_null metadata must reference a singlemetadata name <deref_bytes_node> corresponding to a metadata node with onei64 entry.See dereferenceable_or_null metadata.

The optional !nofree metadata must reference a single metadata name<empty_node> corresponding to a metadata node with no entries.The existence of the !nofree metadata on the instruction tells the optimizerthat the memory pointed by the pointer will not be freed after this point.

Semantics:

The ‘inttoptr’ instruction converts value to type ty2 byapplying either a zero extension or a truncation depending on the sizeof the integer value. If value is larger than the size of apointer then a truncation is done. If value is smaller than the sizeof a pointer then a zero extension is done. If they are the same size,nothing is done (no-op cast).The behavior is equivalent to a bitcast, however, the resulting value is notguaranteed to be dereferenceable (e.g., if the result type is anon-integral pointers).

Example:
%X = inttoptr i32 255 to ptr           ; yields zero extension on 64-bit architecture%Y = inttoptr i32 255 to ptr           ; yields no-op on 32-bit architecture%Z = inttoptr i64 0 to ptr             ; yields truncation on 32-bit architecture%Z = inttoptr <4 x i32> %G to <4 x ptr>; yields truncation of vector G to four pointers
`, + html: `

‘inttoptr .. to’ Instruction

+
+
Syntax:
+
<result> = inttoptr <ty> <value> to <ty2>[, !dereferenceable !<deref_bytes_node>][, !dereferenceable_or_null !<deref_bytes_node>][, !nofree !<empty_node>]            ; yields ty2
+
+
+
+
+
Overview:
+

The ‘inttoptr’ instruction converts an integer value to a +pointer type, ty2.

+
+
+
Arguments:
+

The ‘inttoptr’ instruction takes an integer value to +cast, and a type to cast it to, which must be a pointer +type.

+

The optional !dereferenceable metadata must reference a single metadata +name <deref_bytes_node> corresponding to a metadata node with one i64 +entry. +See dereferenceable metadata.

+

The optional !dereferenceable_or_null metadata must reference a single +metadata name <deref_bytes_node> corresponding to a metadata node with one +i64 entry. +See dereferenceable_or_null metadata.

+

The optional !nofree metadata must reference a single metadata name +<empty_node> corresponding to a metadata node with no entries. +The existence of the !nofree metadata on the instruction tells the optimizer +that the memory pointed by the pointer will not be freed after this point.

+
+
+
Semantics:
+

The ‘inttoptr’ instruction converts value to type ty2 by +applying either a zero extension or a truncation depending on the size +of the integer value. If value is larger than the size of a +pointer then a truncation is done. If value is smaller than the size +of a pointer then a zero extension is done. If they are the same size, +nothing is done (no-op cast). +The behavior is equivalent to a bitcast, however, the resulting value is not +guaranteed to be dereferenceable (e.g., if the result type is a +non-integral pointers).

+
+
+
Example:
+
%X = inttoptr i32 255 to ptr           ; yields zero extension on 64-bit architecture
+%Y = inttoptr i32 255 to ptr           ; yields no-op on 32-bit architecture
+%Z = inttoptr i64 0 to ptr             ; yields truncation on 32-bit architecture
+%Z = inttoptr <4 x i32> %G to <4 x ptr>; yields truncation of vector G to four pointers
+
+
+
+`, tooltip: `The ‘inttoptr’ instruction converts an integer value to apointer type, ty2.`, }; case 'BITCAST': return { url: `https://llvm.org/docs/LangRef.html#bitcast-to-instruction`, - html: `

‘bitcast .. to’ Instruction

Syntax:
<result> = bitcast <ty> <value> to <ty2>             ; yields ty2
Overview:

The ‘bitcast’ instruction converts value to type ty2 withoutchanging any bits.

Arguments:

The ‘bitcast’ instruction takes a value to cast, which must be anon-aggregate first class value, and a type to cast it to, which mustalso be a non-aggregate first class type. Thebit sizes of value and the destination type, ty2, must beidentical. If the source type is a pointer, the destination type mustalso be a pointer of the same size. This instruction supports bitwiseconversion of vectors to integers and to vectors of other types (aslong as they have the same size).

Semantics:

The ‘bitcast’ instruction converts value to type ty2. Itis always a no-op cast because no bits change with thisconversion. The conversion is done as if the value had been storedto memory and read back as type ty2. Pointer (or vector ofpointers) types may only be converted to other pointer (or vector ofpointers) types with the same address space through this instruction.To convert pointers to other types, use the inttoptror ptrtoint instructions first.

There is a caveat for bitcasts involving vector types in relation toendianness. For example bitcast <2 x i8> <value> to i16 puts element zeroof the vector in the least significant bits of the i16 for little-endian whileelement zero ends up in the most significant bits for big-endian.

Example:
%X = bitcast i8 255 to i8         ; yields i8 :-1%Y = bitcast i32* %x to i16*      ; yields i16*:%x%Z = bitcast <2 x i32> %V to i64; ; yields i64: %V (depends on endianness)%Z = bitcast <2 x i32*> %V to <2 x i64*> ; yields <2 x i64*>
`, + html: `

‘bitcast .. to’ Instruction

+
+
Syntax:
+
<result> = bitcast <ty> <value> to <ty2>             ; yields ty2
+
+
+
+
+
Overview:
+

The ‘bitcast’ instruction converts value to type ty2 without +changing any bits.

+
+
+
Arguments:
+

The ‘bitcast’ instruction takes a value to cast, which must be a +non-aggregate first class value, and a type to cast it to, which must +also be a non-aggregate first class type. The +bit sizes of value and the destination type, ty2, must be +identical. If the source type is a pointer, the destination type must +also be a pointer of the same size. This instruction supports bitwise +conversion of vectors to integers and to vectors of other types (as +long as they have the same size).

+
+
+
Semantics:
+

The ‘bitcast’ instruction converts value to type ty2. It +is always a no-op cast because no bits change with this +conversion. The conversion is done as if the value had been stored +to memory and read back as type ty2. Pointer (or vector of +pointers) types may only be converted to other pointer (or vector of +pointers) types with the same address space through this instruction. +To convert pointers to other types, use the inttoptr +or ptrtoint instructions first.

+

There is a caveat for bitcasts involving vector types in relation to +endianness. For example bitcast <2 x i8> <value> to i16 puts element zero +of the vector in the least significant bits of the i16 for little-endian while +element zero ends up in the most significant bits for big-endian.

+
+
+
Example:
+
%X = bitcast i8 255 to i8         ; yields i8 :-1
+%Y = bitcast i32* %x to i16*      ; yields i16*:%x
+%Z = bitcast <2 x i32> %V to i64; ; yields i64: %V (depends on endianness)
+%Z = bitcast <2 x i32*> %V to <2 x i64*> ; yields <2 x i64*>
+
+
+
+`, tooltip: `The ‘bitcast’ instruction converts value to type ty2 withoutchanging any bits.`, }; case 'ADDRSPACECAST': return { url: `https://llvm.org/docs/LangRef.html#addrspacecast-to-instruction`, - html: `

‘addrspacecast .. to’ Instruction

Syntax:
<result> = addrspacecast <pty> <ptrval> to <pty2>       ; yields pty2
Overview:

The ‘addrspacecast’ instruction converts ptrval from pty inaddress space n to type pty2 in address space m.

Arguments:

The ‘addrspacecast’ instruction takes a pointer or vector of pointer valueto cast and a pointer type to cast it to, which must have a differentaddress space.

Semantics:

The ‘addrspacecast’ instruction converts the pointer valueptrval to type pty2. It can be a no-op cast or a complexvalue modification, depending on the target and the address spacepair. Pointer conversions within the same address space must beperformed with the bitcast instruction. Note that if the addressspace conversion produces a dereferenceable result then both resultand operand refer to the same memory location. The conversion musthave no side effects, and must not capture the value of the pointer.

If the source is poison, the result ispoison.

If the source is not poison, and both source anddestination are integral pointers, and theresult pointer is dereferenceable, the cast is assumed to bereversible (i.e., casting the result back to the original address spaceshould yield the original bit pattern).

Which address space casts are supported depends on the target. Unsupportedaddress space casts return poison.

Example:
%X = addrspacecast ptr %x to ptr addrspace(1)%Y = addrspacecast ptr addrspace(1) %y to ptr addrspace(2)%Z = addrspacecast <4 x ptr> %z to <4 x ptr addrspace(3)>
`, + html: `

‘addrspacecast .. to’ Instruction

+
+
Syntax:
+
<result> = addrspacecast <pty> <ptrval> to <pty2>       ; yields pty2
+
+
+
+
+
Overview:
+

The ‘addrspacecast’ instruction converts ptrval from pty in +address space n to type pty2 in address space m.

+
+
+
Arguments:
+

The ‘addrspacecast’ instruction takes a pointer or vector of pointer value +to cast and a pointer type to cast it to, which must have a different +address space.

+
+
+
Semantics:
+

The ‘addrspacecast’ instruction converts the pointer value +ptrval to type pty2. It can be a no-op cast or a complex +value modification, depending on the target and the address space +pair. Pointer conversions within the same address space must be +performed with the bitcast instruction. Note that if the address +space conversion produces a dereferenceable result then both result +and operand refer to the same memory location. The conversion must +have no side effects, and must not capture the value of the pointer.

+

If the source is poison, the result is +poison.

+

If the source is not poison, and both source and +destination are integral pointers, and the +result pointer is dereferenceable, the cast is assumed to be +reversible (i.e., casting the result back to the original address space +should yield the original bit pattern).

+

Which address space casts are supported depends on the target. Unsupported +address space casts return poison.

+
+
+
Example:
+
%X = addrspacecast ptr %x to ptr addrspace(1)
+%Y = addrspacecast ptr addrspace(1) %y to ptr addrspace(2)
+%Z = addrspacecast <4 x ptr> %z to <4 x ptr addrspace(3)>
+
+
+
+`, tooltip: `The ‘addrspacecast’ instruction converts ptrval from pty inaddress space n to type pty2 in address space m.`, }; case 'ICMP': return { url: `https://llvm.org/docs/LangRef.html#icmp-instruction`, - html: `

‘icmp’ Instruction

Syntax:
<result> = icmp <cond> <ty> <op1>, <op2>   ; yields i1 or <N x i1>:result<result> = icmp samesign <cond> <ty> <op1>, <op2>   ; yields i1 or <N x i1>:result
Overview:

The ‘icmp’ instruction returns a boolean value or a vector ofboolean values based on comparison of its two integer, integer vector,pointer, or pointer vector operands.

Arguments:

The ‘icmp’ instruction takes three operands. The first operand isthe condition code indicating the kind of comparison to perform. It isnot a value, just a keyword. The possible condition codes are:

  1. eq: equal

  2. ne: not equal

  3. ugt: unsigned greater than

  4. uge: unsigned greater or equal

  5. ult: unsigned less than

  6. ule: unsigned less or equal

  7. sgt: signed greater than

  8. sge: signed greater or equal

  9. slt: signed less than

  10. sle: signed less or equal

The remaining two arguments must be integer orpointer or integer vector typed. Theymust also be identical types.

Semantics:

The ‘icmp’ compares op1 and op2 according to the conditioncode given as cond. The comparison performed always yields either ani1 or vector of i1 result, as follows:

  1. eq: yields true if the operands are equal, falseotherwise. No sign interpretation is necessary or performed.

  2. ne: yields true if the operands are unequal, falseotherwise. No sign interpretation is necessary or performed.

  3. ugt: interprets the operands as unsigned values and yieldstrue if op1 is greater than op2.

  4. uge: interprets the operands as unsigned values and yieldstrue if op1 is greater than or equal to op2.

  5. ult: interprets the operands as unsigned values and yieldstrue if op1 is less than op2.

  6. ule: interprets the operands as unsigned values and yieldstrue if op1 is less than or equal to op2.

  7. sgt: interprets the operands as signed values and yields trueif op1 is greater than op2.

  8. sge: interprets the operands as signed values and yields trueif op1 is greater than or equal to op2.

  9. slt: interprets the operands as signed values and yields trueif op1 is less than op2.

  10. sle: interprets the operands as signed values and yields trueif op1 is less than or equal to op2.

If the operands are pointer typed, the pointer valuesare compared as if they were integers.

If the operands are integer vectors, then they are compared element byelement. The result is an i1 vector with the same number of elementsas the values being compared. Otherwise, the result is an i1.

If the samesign keyword is present and the operands are not of thesame sign then the result is a poison value.

Example:
<result> = icmp eq i32 4, 5          ; yields: result=false<result> = icmp ne ptr %X, %X        ; yields: result=false<result> = icmp ult i16  4, 5        ; yields: result=true<result> = icmp sgt i16  4, 5        ; yields: result=false<result> = icmp ule i16 -4, 5        ; yields: result=false<result> = icmp sge i16  4, 5        ; yields: result=false
`, + html: `

‘icmp’ Instruction

+
+
Syntax:
+
<result> = icmp <cond> <ty> <op1>, <op2>   ; yields i1 or <N x i1>:result
+<result> = icmp samesign <cond> <ty> <op1>, <op2>   ; yields i1 or <N x i1>:result
+
+
+
+
+
Overview:
+

The ‘icmp’ instruction returns a boolean value or a vector of +boolean values based on comparison of its two integer, integer vector, +pointer, or pointer vector operands.

+
+
+
Arguments:
+

The ‘icmp’ instruction takes three operands. The first operand is +the condition code indicating the kind of comparison to perform. It is +not a value, just a keyword. The possible condition codes are:

+
    +

  1. eq: equal

    2. +

  2. ne: not equal

    3. +

  3. ugt: unsigned greater than

    4. +

  4. uge: unsigned greater or equal

    5. +

  5. ult: unsigned less than

    6. +

  6. ule: unsigned less or equal

    7. +

  7. sgt: signed greater than

    8. +

  8. sge: signed greater or equal

    9. +

  9. slt: signed less than

    10. +

  10. sle: signed less or equal

    11. +
+

The remaining two arguments must be integer or +pointer or integer vector typed. They +must also be identical types.

+
+
+
Semantics:
+

The ‘icmp’ compares op1 and op2 according to the condition +code given as cond. The comparison performed always yields either an +i1 or vector of i1 result, as follows:

+
    +

  1. eq: yields true if the operands are equal, false +otherwise. No sign interpretation is necessary or performed.

    2. +

  2. ne: yields true if the operands are unequal, false +otherwise. No sign interpretation is necessary or performed.

    3. +

  3. ugt: interprets the operands as unsigned values and yields +true if op1 is greater than op2.

    4. +

  4. uge: interprets the operands as unsigned values and yields +true if op1 is greater than or equal to op2.

    5. +

  5. ult: interprets the operands as unsigned values and yields +true if op1 is less than op2.

    6. +

  6. ule: interprets the operands as unsigned values and yields +true if op1 is less than or equal to op2.

    7. +

  7. sgt: interprets the operands as signed values and yields true +if op1 is greater than op2.

    8. +

  8. sge: interprets the operands as signed values and yields true +if op1 is greater than or equal to op2.

    9. +

  9. slt: interprets the operands as signed values and yields true +if op1 is less than op2.

    10. +

  10. sle: interprets the operands as signed values and yields true +if op1 is less than or equal to op2.

    11. +
+

If the operands are pointer typed, the pointer values +are compared as if they were integers.

+

If the operands are integer vectors, then they are compared element by +element. The result is an i1 vector with the same number of elements +as the values being compared. Otherwise, the result is an i1.

+

If the samesign keyword is present and the operands are not of the +same sign then the result is a poison value.

+
+
+
Example:
+
<result> = icmp eq i32 4, 5          ; yields: result=false
+<result> = icmp ne ptr %X, %X        ; yields: result=false
+<result> = icmp ult i16  4, 5        ; yields: result=true
+<result> = icmp sgt i16  4, 5        ; yields: result=false
+<result> = icmp ule i16 -4, 5        ; yields: result=false
+<result> = icmp sge i16  4, 5        ; yields: result=false
+
+
+
+`, tooltip: `The ‘icmp’ instruction returns a boolean value or a vector ofboolean values based on comparison of its two integer, integer vector,pointer, or pointer vector operands.`, }; case 'FCMP': return { url: `https://llvm.org/docs/LangRef.html#fcmp-instruction`, - html: `

‘fcmp’ Instruction

Syntax:
<result> = fcmp [fast-math flags]* <cond> <ty> <op1>, <op2>     ; yields i1 or <N x i1>:result
Overview:

The ‘fcmp’ instruction returns a boolean value or vector of booleanvalues based on comparison of its operands.

If the operands are floating-point scalars, then the result type is aboolean (i1).

If the operands are floating-point vectors, then the result type is avector of boolean with the same number of elements as the operands beingcompared.

Arguments:

The ‘fcmp’ instruction takes three operands. The first operand isthe condition code indicating the kind of comparison to perform. It isnot a value, just a keyword. The possible condition codes are:

  1. false: no comparison, always returns false

  2. oeq: ordered and equal

  3. ogt: ordered and greater than

  4. oge: ordered and greater than or equal

  5. olt: ordered and less than

  6. ole: ordered and less than or equal

  7. one: ordered and not equal

  8. ord: ordered (no nans)

  9. ueq: unordered or equal

  10. ugt: unordered or greater than

  11. uge: unordered or greater than or equal

  12. ult: unordered or less than

  13. ule: unordered or less than or equal

  14. une: unordered or not equal

  15. uno: unordered (either nans)

  16. true: no comparison, always returns true

Ordered means that neither operand is a QNAN while unordered meansthat either operand may be a QNAN.

Each of val1 and val2 arguments must be either a floating-point type or a vector of floating-point type.They must have identical types.

Semantics:

The ‘fcmp’ instruction compares op1 and op2 according to thecondition code given as cond. If the operands are vectors, then thevectors are compared element by element. Each comparison performedalways yields an i1 result, as follows:

  1. false: always yields false, regardless of operands.

  2. oeq: yields true if both operands are not a QNAN and op1is equal to op2.

  3. ogt: yields true if both operands are not a QNAN and op1is greater than op2.

  4. oge: yields true if both operands are not a QNAN and op1is greater than or equal to op2.

  5. olt: yields true if both operands are not a QNAN and op1is less than op2.

  6. ole: yields true if both operands are not a QNAN and op1is less than or equal to op2.

  7. one: yields true if both operands are not a QNAN and op1is not equal to op2.

  8. ord: yields true if both operands are not a QNAN.

  9. ueq: yields true if either operand is a QNAN or op1 isequal to op2.

  10. ugt: yields true if either operand is a QNAN or op1 isgreater than op2.

  11. uge: yields true if either operand is a QNAN or op1 isgreater than or equal to op2.

  12. ult: yields true if either operand is a QNAN or op1 isless than op2.

  13. ule: yields true if either operand is a QNAN or op1 isless than or equal to op2.

  14. une: yields true if either operand is a QNAN or op1 isnot equal to op2.

  15. uno: yields true if either operand is a QNAN.

  16. true: always yields true, regardless of operands.

The fcmp instruction can also optionally take any number offast-math flags, which are optimization hints to enableotherwise unsafe floating-point optimizations.

Any set of fast-math flags are legal on an fcmp instruction, but theonly flags that have any effect on its semantics are those that allowassumptions to be made about the values of input arguments; namelynnan, ninf, and reassoc. See Fast-Math Flags for more information.

Example:
<result> = fcmp oeq float 4.0, 5.0    ; yields: result=false<result> = fcmp one float 4.0, 5.0    ; yields: result=true<result> = fcmp olt float 4.0, 5.0    ; yields: result=true<result> = fcmp ueq double 1.0, 2.0   ; yields: result=false
`, + html: `

‘fcmp’ Instruction

+
+
Syntax:
+
<result> = fcmp [fast-math flags]* <cond> <ty> <op1>, <op2>     ; yields i1 or <N x i1>:result
+
+
+
+
+
Overview:
+

The ‘fcmp’ instruction returns a boolean value or vector of boolean +values based on comparison of its operands.

+

If the operands are floating-point scalars, then the result type is a +boolean (i1).

+

If the operands are floating-point vectors, then the result type is a +vector of boolean with the same number of elements as the operands being +compared.

+
+
+
Arguments:
+

The ‘fcmp’ instruction takes three operands. The first operand is +the condition code indicating the kind of comparison to perform. It is +not a value, just a keyword. The possible condition codes are:

+
    +

  1. false: no comparison, always returns false

    2. +

  2. oeq: ordered and equal

    3. +

  3. ogt: ordered and greater than

    4. +

  4. oge: ordered and greater than or equal

    5. +

  5. olt: ordered and less than

    6. +

  6. ole: ordered and less than or equal

    7. +

  7. one: ordered and not equal

    8. +

  8. ord: ordered (no nans)

    9. +

  9. ueq: unordered or equal

    10. +

  10. ugt: unordered or greater than

    11. +

  11. uge: unordered or greater than or equal

    12. +

  12. ult: unordered or less than

    13. +

  13. ule: unordered or less than or equal

    14. +

  14. une: unordered or not equal

    15. +

  15. uno: unordered (either nans)

    16. +

  16. true: no comparison, always returns true

    17. +
+

Ordered means that neither operand is a QNAN while unordered means +that either operand may be a QNAN.

+

Each of val1 and val2 arguments must be either a floating-point type or a vector of floating-point type. +They must have identical types.

+
+
+
Semantics:
+

The ‘fcmp’ instruction compares op1 and op2 according to the +condition code given as cond. If the operands are vectors, then the +vectors are compared element by element. Each comparison performed +always yields an i1 result, as follows:

+
    +

  1. false: always yields false, regardless of operands.

    2. +

  2. oeq: yields true if both operands are not a QNAN and op1 +is equal to op2.

    3. +

  3. ogt: yields true if both operands are not a QNAN and op1 +is greater than op2.

    4. +

  4. oge: yields true if both operands are not a QNAN and op1 +is greater than or equal to op2.

    5. +

  5. olt: yields true if both operands are not a QNAN and op1 +is less than op2.

    6. +

  6. ole: yields true if both operands are not a QNAN and op1 +is less than or equal to op2.

    7. +

  7. one: yields true if both operands are not a QNAN and op1 +is not equal to op2.

    8. +

  8. ord: yields true if both operands are not a QNAN.

    9. +

  9. ueq: yields true if either operand is a QNAN or op1 is +equal to op2.

    10. +

  10. ugt: yields true if either operand is a QNAN or op1 is +greater than op2.

    11. +

  11. uge: yields true if either operand is a QNAN or op1 is +greater than or equal to op2.

    12. +

  12. ult: yields true if either operand is a QNAN or op1 is +less than op2.

    13. +

  13. ule: yields true if either operand is a QNAN or op1 is +less than or equal to op2.

    14. +

  14. une: yields true if either operand is a QNAN or op1 is +not equal to op2.

    15. +

  15. uno: yields true if either operand is a QNAN.

    16. +

  16. true: always yields true, regardless of operands.

    17. +
+

The fcmp instruction can also optionally take any number of +fast-math flags, which are optimization hints to enable +otherwise unsafe floating-point optimizations.

+

Any set of fast-math flags are legal on an fcmp instruction, but the +only flags that have any effect on its semantics are those that allow +assumptions to be made about the values of input arguments; namely +nnan, ninf, and reassoc. See Fast-Math Flags for more information.

+
+
+
Example:
+
<result> = fcmp oeq float 4.0, 5.0    ; yields: result=false
+<result> = fcmp one float 4.0, 5.0    ; yields: result=true
+<result> = fcmp olt float 4.0, 5.0    ; yields: result=true
+<result> = fcmp ueq double 1.0, 2.0   ; yields: result=false
+
+
+
+`, tooltip: `The ‘fcmp’ instruction returns a boolean value or vector of booleanvalues based on comparison of its operands.If the operands are floating-point scalars, then the result type is aboolean (i1).If the operands are floating-point vectors, then the result type is avector of boolean with the same number of elements as the operands beingcompared.`, }; case 'PHI': return { url: `https://llvm.org/docs/LangRef.html#phi-instruction`, - html: `

‘phi’ Instruction

Syntax:
<result> = phi [fast-math-flags] <ty> [ <val0>, <label0>], ...
Overview:

The ‘phi’ instruction is used to implement the φ node in the SSAgraph representing the function.

Arguments:

The type of the incoming values is specified with the first type field.After this, the ‘phi’ instruction takes a list of pairs asarguments, with one pair for each predecessor basic block of the currentblock. Only values of first class type may be used asthe value arguments to the PHI node. Only labels may be used as thelabel arguments.

There must be no non-phi instructions between the start of a basic blockand the PHI instructions: i.e., PHI instructions must be first in a basicblock.

For the purposes of the SSA form, the use of each incoming value isdeemed to occur on the edge from the corresponding predecessor block tothe current block (but after any definition of an ‘invoke’instruction’s return value on the same edge).

The optional fast-math-flags marker indicates that the phi has oneor more fast-math-flags. These are optimization hintsto enable otherwise unsafe floating-point optimizations. Fast-math-flagsare only valid for phis that return supported floating-point types.

Semantics:

At runtime, the ‘phi’ instruction logically takes on the valuespecified by the pair corresponding to the predecessor basic block thatexecuted just prior to the current block.

Example:
Loop:       ; Infinite loop that counts from 0 on up...  %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]  %nextindvar = add i32 %indvar, 1  br label %Loop
`, + html: `

‘phi’ Instruction

+
+
Syntax:
+
<result> = phi [fast-math-flags] <ty> [ <val0>, <label0>], ...
+
+
+
+
+
Overview:
+

The ‘phi’ instruction is used to implement the φ node in the SSA +graph representing the function.

+
+
+
Arguments:
+

The type of the incoming values is specified with the first type field. +After this, the ‘phi’ instruction takes a list of pairs as +arguments, with one pair for each predecessor basic block of the current +block. Only values of first class type may be used as +the value arguments to the PHI node. Only labels may be used as the +label arguments.

+

There must be no non-phi instructions between the start of a basic block +and the PHI instructions: i.e., PHI instructions must be first in a basic +block.

+

For the purposes of the SSA form, the use of each incoming value is +deemed to occur on the edge from the corresponding predecessor block to +the current block (but after any definition of an ‘invoke’ +instruction’s return value on the same edge).

+

The optional fast-math-flags marker indicates that the phi has one +or more fast-math-flags. These are optimization hints +to enable otherwise unsafe floating-point optimizations. Fast-math-flags +are only valid for phis that return supported floating-point types.

+
+
+
Semantics:
+

At runtime, the ‘phi’ instruction logically takes on the value +specified by the pair corresponding to the predecessor basic block that +executed just prior to the current block.

+
+
+
Example:
+
Loop:       ; Infinite loop that counts from 0 on up...
+  %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
+  %nextindvar = add i32 %indvar, 1
+  br label %Loop
+
+
+
+`, tooltip: `The ‘phi’ instruction is used to implement the φ node in the SSAgraph representing the function.`, }; case 'SELECT': return { url: `https://llvm.org/docs/LangRef.html#select-instruction`, - html: `

‘select’ Instruction

Syntax:
<result> = select [fast-math flags] selty <cond>, <ty> <val1>, <ty> <val2>             ; yields tyselty is either i1 or {<N x i1>}
Overview:

The ‘select’ instruction is used to choose one value based on acondition, without IR-level branching.

Arguments:

The ‘select’ instruction requires an ‘i1’ value or a vector of ‘i1’values indicating the condition, and two values of the same firstclass type.

  1. The optional fast-math flags marker indicates that the select has one or morefast-math flags. These are optimization hints to enableotherwise unsafe floating-point optimizations. Fast-math flags are only validfor selects that return supported floating-point types. Note that the presence of value which would otherwise resultin poison does not cause the result to be poison if the value is on the non-selected arm.If fast-math flags are present, they are only applied to the result,not both arms.

Semantics:

If the condition is an i1 and it evaluates to 1, the instruction returnsthe first value argument; otherwise, it returns the second valueargument.

If the condition is a vector of i1, then the value arguments must bevectors of the same size, and the selection is done element by element.

If the condition is an i1 and the value arguments are vectors of thesame size, then an entire vector is selected.

Example:
%X = select i1 true, i8 17, i8 42                   ; yields i8:17%Y = select nnan i1 true, float 0.0, float NaN      ; yields float:0.0%Z = select nnan i1 false, float 0.0, float NaN     ; yields float:poison
`, + html: `

‘select’ Instruction

+
+
Syntax:
+
<result> = select [fast-math flags] selty <cond>, <ty> <val1>, <ty> <val2>             ; yields ty
+
+selty is either i1 or {<N x i1>}
+
+
+
+
+
Overview:
+

The ‘select’ instruction is used to choose one value based on a +condition, without IR-level branching.

+
+
+
Arguments:
+

The ‘select’ instruction requires an ‘i1’ value or a vector of ‘i1’ +values indicating the condition, and two values of the same first +class type.

+
    +

  1. The optional fast-math flags marker indicates that the select has one or more +fast-math flags. These are optimization hints to enable +otherwise unsafe floating-point optimizations. Fast-math flags are only valid +for selects that return supported floating-point types. Note that the presence of value which would otherwise result +in poison does not cause the result to be poison if the value is on the non-selected arm. +If fast-math flags are present, they are only applied to the result, +not both arms.

    2. +
+
+
+
Semantics:
+

If the condition is an i1 and it evaluates to 1, the instruction returns +the first value argument; otherwise, it returns the second value +argument.

+

If the condition is a vector of i1, then the value arguments must be +vectors of the same size, and the selection is done element by element.

+

If the condition is an i1 and the value arguments are vectors of the +same size, then an entire vector is selected.

+
+
+
Example:
+
%X = select i1 true, i8 17, i8 42                   ; yields i8:17
+%Y = select nnan i1 true, float 0.0, float NaN      ; yields float:0.0
+%Z = select nnan i1 false, float 0.0, float NaN     ; yields float:poison
+
+
+
+`, tooltip: `The ‘select’ instruction is used to choose one value based on acondition, without IR-level branching.`, }; case 'FREEZE': return { url: `https://llvm.org/docs/LangRef.html#freeze-instruction`, - html: `

‘freeze’ Instruction

Syntax:
<result> = freeze ty <val>    ; yields ty:result
Overview:

The ‘freeze’ instruction is used to stop propagation ofundef and poison values.

Arguments:

The ‘freeze’ instruction takes a single argument.

Semantics:

If the argument is undef or poison, ‘freeze’ returns anarbitrary, but fixed, value of type ‘ty’.Otherwise, this instruction is a no-op and returns the input argument.All uses of a value returned by the same ‘freeze’ instruction areguaranteed to always observe the same value, while different ‘freeze’instructions may yield different values.

While undef and poison pointers can be frozen, the result is anon-dereferenceable pointer. See thePointer Aliasing Rules section for more information.If an aggregate value or vector is frozen, the operand is frozen element-wise.The padding of an aggregate isn’t considered, since it isn’t visiblewithout storing it into memory and loading it with a different type.

Example:
%w = i32 undef%x = freeze i32 %w%y = add i32 %w, %w         ; undef%z = add i32 %x, %x         ; even number because all uses of %x observe                            ; the same value%x2 = freeze i32 %w%cmp = icmp eq i32 %x, %x2  ; can be true or false; example with vectors%v = <2 x i32> <i32 undef, i32 poison>%a = extractelement <2 x i32> %v, i32 0    ; undef%b = extractelement <2 x i32> %v, i32 1    ; poison%add = add i32 %a, %a                      ; undef%v.fr = freeze <2 x i32> %v                ; element-wise freeze%d = extractelement <2 x i32> %v.fr, i32 0 ; not undef%add.f = add i32 %d, %d                    ; even number; branching on frozen value%poison = add nsw i1 %k, undef   ; poison%c = freeze i1 %poisonbr i1 %c, label %foo, label %bar ; non-deterministic branch to %foo or %bar
`, + html: `

‘freeze’ Instruction

+
+
Syntax:
+
<result> = freeze ty <val>    ; yields ty:result
+
+
+
+
+
Overview:
+

The ‘freeze’ instruction is used to stop propagation of +undef and poison values.

+
+
+
Arguments:
+

The ‘freeze’ instruction takes a single argument.

+
+
+
Semantics:
+

If the argument is undef or poison, ‘freeze’ returns an +arbitrary, but fixed, value of type ‘ty’. +Otherwise, this instruction is a no-op and returns the input argument. +All uses of a value returned by the same ‘freeze’ instruction are +guaranteed to always observe the same value, while different ‘freeze’ +instructions may yield different values.

+

While undef and poison pointers can be frozen, the result is a +non-dereferenceable pointer. See the +Pointer Aliasing Rules section for more information. +If an aggregate value or vector is frozen, the operand is frozen element-wise. +The padding of an aggregate isn’t considered, since it isn’t visible +without storing it into memory and loading it with a different type.

+
+
+
Example:
+
%w = i32 undef
+%x = freeze i32 %w
+%y = add i32 %w, %w         ; undef
+%z = add i32 %x, %x         ; even number because all uses of %x observe
+                            ; the same value
+%x2 = freeze i32 %w
+%cmp = icmp eq i32 %x, %x2  ; can be true or false
+
+; example with vectors
+%v = <2 x i32> <i32 undef, i32 poison>
+%a = extractelement <2 x i32> %v, i32 0    ; undef
+%b = extractelement <2 x i32> %v, i32 1    ; poison
+%add = add i32 %a, %a                      ; undef
+
+%v.fr = freeze <2 x i32> %v                ; element-wise freeze
+%d = extractelement <2 x i32> %v.fr, i32 0 ; not undef
+%add.f = add i32 %d, %d                    ; even number
+
+; branching on frozen value
+%poison = add nsw i1 %k, undef   ; poison
+%c = freeze i1 %poison
+br i1 %c, label %foo, label %bar ; non-deterministic branch to %foo or %bar
+
+
+
+`, tooltip: `The ‘freeze’ instruction is used to stop propagation ofundef and poison values.`, }; case 'CALL': return { url: `https://llvm.org/docs/LangRef.html#call-instruction`, - html: `

‘call’ Instruction

Syntax:
<result> = [tail | musttail | notail ] call [fast-math flags] [cconv] [ret attrs] [addrspace(<num>)]           <ty>|<fnty> <fnptrval>(<function args>) [fn attrs] [ operand bundles ]
Overview:

The ‘call’ instruction represents a simple function call.

Arguments:

This instruction requires several arguments:

  1. The optional tail and musttail markers indicate that the optimizersshould perform tail call optimization. The tail marker is a hint thatcan be ignored. Themusttail marker means that the call must be tail call optimized in orderfor the program to be correct. This is true even in the presence ofattributes like “disable-tail-calls”. The musttail marker provides theseguarantees:

    • The call will not cause unbounded stack growth if it is part of arecursive cycle in the call graph.

    • Arguments with the inalloca orpreallocated attribute are forwarded in place.

    • If the musttail call appears in a function with the "thunk" attributeand the caller and callee both have varargs, then any unprototypedarguments in register or memory are forwarded to the callee. Similarly,the return value of the callee is returned to the caller’s caller, evenif a void return type is in use.

    Both markers imply that the callee does not access allocas, va_args, orbyval arguments from the caller. As an exception to that, an alloca or byvalargument may be passed to the callee as a byval argument, which can bedereferenced inside the callee. For example:

    declare void @take_byval(ptr byval(i64))declare void @take_ptr(ptr); Invalid (assuming @take_ptr dereferences the pointer), because %local; may be de-allocated before the call to @take_ptr.define void @invalid_alloca() {entry:  %local = alloca i64  tail call void @take_ptr(ptr %local)  ret void}; Valid, the byval attribute causes the memory allocated by %local to be; copied into @take_byval's stack frame.define void @byval_alloca() {entry:  %local = alloca i64  tail call void @take_byval(ptr byval(i64) %local)  ret void}; Invalid, because @use_global_va_list uses the variadic arguments from; @invalid_va_list.%struct.va_list = type { ptr }@va_list = external global %struct.va_listdefine void @use_global_va_list() {entry:  %arg = va_arg ptr @va_list, i64  ret void}define void @invalid_va_list(i32 %a, ...) {entry:  call void @llvm.va_start.p0(ptr @va_list)  tail call void @use_global_va_list()  ret void}; Valid, byval argument forwarded to tail call as another byval argument.define void @forward_byval(ptr byval(i64) %x) {entry:  tail call void @take_byval(ptr byval(i64) %x)  ret void}; Invalid (assuming @take_ptr dereferences the pointer), byval argument; passed to tail callee as non-byval ptr.define void @invalid_byval(ptr byval(i64) %x) {entry:  tail call void @take_ptr(ptr %x)  ret void}

    Calls marked musttail must obey the following additional rules:

    • The call must immediately precede a ret instruction,or a pointer bitcast followed by a ret instruction.

    • The ret instruction must return the (possibly bitcasted) valueproduced by the call, undef, or void.

    • The calling conventions of the caller and callee must match.

    • The callee must be varargs iff the caller is varargs. Bitcasting anon-varargs function to the appropriate varargs type is legal solong as the non-varargs prefixes obey the other rules.

    • The return type must not undergo automatic conversion to an sret pointer.

    In addition, if the calling convention is not swifttailcc or tailcc:

    • All ABI-impacting function attributes, such as sret, byval, inreg,returned, and inalloca, must match.

    • The caller and callee prototypes must match. Pointer types of parametersor return types do not differ in address space.

    On the other hand, if the calling convention is swifttailcc or tailcc:

    • Only these ABI-impacting attributes attributes are allowed: sret, byval,swiftself, and swiftasync.

    • Prototypes are not required to match.

    Tail call optimization for calls marked tail is guaranteed to occur ifthe following conditions are met:

    • Caller and callee both have the calling convention fastcc or tailcc.

    • The call is in tail position (ret immediately follows call and retuses value of call or is void).

    • Option -tailcallopt is enabled, llvm::GuaranteedTailCallOpt istrue, or the calling convention is tailcc.

    • Platform-specific constraints are met.

  2. The optional notail marker indicates that the optimizers should not addtail or musttail markers to the call. It is used to prevent tailcall optimization from being performed on the call.

  3. The optional fast-math flags marker indicates that the call has one or morefast-math flags, which are optimization hints to enableotherwise unsafe floating-point optimizations. Fast-math flags are only validfor calls that return supported floating-point types.

  4. The optional “cconv” marker indicates which callingconvention the call should use. If none isspecified, the call defaults to using C calling conventions. Thecalling convention of the call must match the calling convention ofthe target function, or else the behavior is undefined.

  5. The optional Parameter Attributes list for returnvalues. Only ‘zeroext’, ‘signext’, ‘noext’, and ‘inreg’attributes are valid here.

  6. The optional addrspace attribute can be used to indicate the address spaceof the called function. If it is not specified, the program address spacefrom the datalayout string will be used.

  7. ‘ty’: the type of the call instruction itself which is also thetype of the return value. Functions that return no value are markedvoid. The signature is computed based on the return type and argumenttypes.

  8. ‘fnty’: shall be the signature of the function being called. Theargument types must match the types implied by this signature. Thisis only required if the signature specifies a varargs type.

  9. ‘fnptrval’: An LLVM value containing a pointer to a function tobe called. In most cases, this is a direct function call, butindirect call’s are just as possible, calling an arbitrary pointerto function value.

  10. ‘function args’: argument list whose types match the functionsignature argument types and parameter attributes. All arguments mustbe of first class type. If the function signatureindicates the function accepts a variable number of arguments, theextra arguments can be specified.

  11. The optional function attributes list.

  12. The optional operand bundles list.

Semantics:

The ‘call’ instruction is used to cause control flow to transfer toa specified function, with its incoming arguments bound to the specifiedvalues. Upon a ‘ret’ instruction in the called function, controlflow continues with the instruction after the function call, and thereturn value of the function is bound to the result argument.

If the callee refers to an intrinsic function, the signature of the call mustmatch the signature of the callee. Otherwise, if the signature of the calldoes not match the signature of the called function, the behavior istarget-specific. For a significant mismatch, this likely results in undefinedbehavior. LLVM interprocedural optimizations generally only optimize callswhere the signature of the caller matches the signature of the callee.

Note that it is possible for the signatures to mismatch even if a call appearsto be a “direct” call, like call void @f().

Example:
%retval = call i32 @test(i32 %argc)call i32 (ptr, ...) @printf(ptr %msg, i32 12, i8 42)        ; yields i32%X = tail call i32 @foo()                                    ; yields i32%Y = tail call fastcc i32 @foo()  ; yields i32call void %foo(i8 signext 97)%struct.A = type { i32, i8 }%r = call %struct.A @foo()                        ; yields { i32, i8 }%gr = extractvalue %struct.A %r, 0                ; yields i32%gr1 = extractvalue %struct.A %r, 1               ; yields i8%Z = call void @foo() noreturn                    ; indicates that %foo never returns normally%ZZ = call zeroext i32 @bar()                     ; Return value is %zero extended

llvm treats calls to some functions with names and arguments that matchthe standard C99 library as being the C99 library functions, and mayperform optimizations or generate code for them under that assumption.This is something we’d like to change in the future to provide bettersupport for freestanding environments and non-C-based languages.

`, + html: `

‘call’ Instruction

+
+
Syntax:
+
<result> = [tail | musttail | notail ] call [fast-math flags] [cconv] [ret attrs] [addrspace(<num>)]
+           <ty>|<fnty> <fnptrval>(<function args>) [fn attrs] [ operand bundles ]
+
+
+
+
+
Overview:
+

The ‘call’ instruction represents a simple function call.

+
+
+
Arguments:
+

This instruction requires several arguments:

+
    +

  1. The optional tail and musttail markers indicate that the optimizers +should perform tail call optimization. The tail marker is a hint that +can be ignored. The +musttail marker means that the call must be tail call optimized in order +for the program to be correct. This is true even in the presence of +attributes like “disable-tail-calls”. The musttail marker provides these +guarantees:

    +
      +

    • The call will not cause unbounded stack growth if it is part of a +recursive cycle in the call graph.

      • +

    • Arguments with the inalloca or +preallocated attribute are forwarded in place.

      • +

    • If the musttail call appears in a function with the "thunk" attribute +and the caller and callee both have varargs, then any unprototyped +arguments in register or memory are forwarded to the callee. Similarly, +the return value of the callee is returned to the caller’s caller, even +if a void return type is in use.

      • +
    +

    Both markers imply that the callee does not access allocas, va_args, or +byval arguments from the caller. As an exception to that, an alloca or byval +argument may be passed to the callee as a byval argument, which can be +dereferenced inside the callee. For example:

    +
    declare void @take_byval(ptr byval(i64))
+declare void @take_ptr(ptr)
+
+; Invalid (assuming @take_ptr dereferences the pointer), because %local
+; may be de-allocated before the call to @take_ptr.
+define void @invalid_alloca() {
+entry:
+  %local = alloca i64
+  tail call void @take_ptr(ptr %local)
+  ret void
+}
+
+; Valid, the byval attribute causes the memory allocated by %local to be
+; copied into @take_byval's stack frame.
+define void @byval_alloca() {
+entry:
+  %local = alloca i64
+  tail call void @take_byval(ptr byval(i64) %local)
+  ret void
+}
+
+; Invalid, because @use_global_va_list uses the variadic arguments from
+; @invalid_va_list.
+%struct.va_list = type { ptr }
+@va_list = external global %struct.va_list
+define void @use_global_va_list() {
+entry:
+  %arg = va_arg ptr @va_list, i64
+  ret void
+}
+define void @invalid_va_list(i32 %a, ...) {
+entry:
+  call void @llvm.va_start.p0(ptr @va_list)
+  tail call void @use_global_va_list()
+  ret void
+}
+
+; Valid, byval argument forwarded to tail call as another byval argument.
+define void @forward_byval(ptr byval(i64) %x) {
+entry:
+  tail call void @take_byval(ptr byval(i64) %x)
+  ret void
+}
+
+; Invalid (assuming @take_ptr dereferences the pointer), byval argument
+; passed to tail callee as non-byval ptr.
+define void @invalid_byval(ptr byval(i64) %x) {
+entry:
+  tail call void @take_ptr(ptr %x)
+  ret void
+}
+
    +
    +

    Calls marked musttail must obey the following additional rules:

    +
      +

    • The call must immediately precede a ret instruction, +or a pointer bitcast followed by a ret instruction.

      • +

    • The ret instruction must return the (possibly bitcasted) value +produced by the call, undef, or void.

      • +

    • The calling conventions of the caller and callee must match.

      • +

    • The callee must be varargs iff the caller is varargs. Bitcasting a +non-varargs function to the appropriate varargs type is legal so +long as the non-varargs prefixes obey the other rules.

      • +

    • The return type must not undergo automatic conversion to an sret pointer.

      • +
    +

    In addition, if the calling convention is not swifttailcc or tailcc:

    +
      +

    • All ABI-impacting function attributes, such as sret, byval, inreg, +returned, and inalloca, must match.

      • +

    • The caller and callee prototypes must match. Pointer types of parameters +or return types do not differ in address space.

      • +
    +

    On the other hand, if the calling convention is swifttailcc or tailcc:

    +
      +

    • Only these ABI-impacting attributes attributes are allowed: sret, byval, +swiftself, and swiftasync.

      • +

    • Prototypes are not required to match.

      • +
    +

    Tail call optimization for calls marked tail is guaranteed to occur if +the following conditions are met:

    +
      +

    • Caller and callee both have the calling convention fastcc or tailcc.

      • +

    • The call is in tail position (ret immediately follows call and ret +uses value of call or is void).

      • +

    • Option -tailcallopt is enabled, llvm::GuaranteedTailCallOpt is +true, or the calling convention is tailcc.

      • +

    • Platform-specific constraints are met.

      • +
    +
    2. +

  2. The optional notail marker indicates that the optimizers should not add +tail or musttail markers to the call. It is used to prevent tail +call optimization from being performed on the call.

    3. +

  3. The optional fast-math flags marker indicates that the call has one or more +fast-math flags, which are optimization hints to enable +otherwise unsafe floating-point optimizations. Fast-math flags are only valid +for calls that return supported floating-point types.

    4. +

  4. The optional “cconv” marker indicates which calling +convention the call should use. If none is +specified, the call defaults to using C calling conventions. The +calling convention of the call must match the calling convention of +the target function, or else the behavior is undefined.

    5. +

  5. The optional Parameter Attributes list for return +values. Only ‘zeroext’, ‘signext’, ‘noext’, and ‘inreg’ +attributes are valid here.

    6. +

  6. The optional addrspace attribute can be used to indicate the address space +of the called function. If it is not specified, the program address space +from the datalayout string will be used.

    7. +

  7. ‘ty’: the type of the call instruction itself which is also the +type of the return value. Functions that return no value are marked +void. The signature is computed based on the return type and argument +types.

    8. +

  8. ‘fnty’: shall be the signature of the function being called. The +argument types must match the types implied by this signature. This +is only required if the signature specifies a varargs type.

    9. +

  9. ‘fnptrval’: An LLVM value containing a pointer to a function to +be called. In most cases, this is a direct function call, but +indirect call’s are just as possible, calling an arbitrary pointer +to function value.

    10. +

  10. ‘function args’: argument list whose types match the function +signature argument types and parameter attributes. All arguments must +be of first class type. If the function signature +indicates the function accepts a variable number of arguments, the +extra arguments can be specified.

    11. +

  11. The optional function attributes list.

    12. +

  12. The optional operand bundles list.

    13. +
+
+
+
Semantics:
+

The ‘call’ instruction is used to cause control flow to transfer to +a specified function, with its incoming arguments bound to the specified +values. Upon a ‘ret’ instruction in the called function, control +flow continues with the instruction after the function call, and the +return value of the function is bound to the result argument.

+

If the callee refers to an intrinsic function, the signature of the call must +match the signature of the callee. Otherwise, if the signature of the call +does not match the signature of the called function, the behavior is +target-specific. For a significant mismatch, this likely results in undefined +behavior. LLVM interprocedural optimizations generally only optimize calls +where the signature of the caller matches the signature of the callee.

+

Note that it is possible for the signatures to mismatch even if a call appears +to be a “direct” call, like call void @f().

+
+
+
Example:
+
%retval = call i32 @test(i32 %argc)
+call i32 (ptr, ...) @printf(ptr %msg, i32 12, i8 42)        ; yields i32
+%X = tail call i32 @foo()                                    ; yields i32
+%Y = tail call fastcc i32 @foo()  ; yields i32
+call void %foo(i8 signext 97)
+
+%struct.A = type { i32, i8 }
+%r = call %struct.A @foo()                        ; yields { i32, i8 }
+%gr = extractvalue %struct.A %r, 0                ; yields i32
+%gr1 = extractvalue %struct.A %r, 1               ; yields i8
+%Z = call void @foo() noreturn                    ; indicates that %foo never returns normally
+%ZZ = call zeroext i32 @bar()                     ; Return value is %zero extended
+
+
+

llvm treats calls to some functions with names and arguments that match +the standard C99 library as being the C99 library functions, and may +perform optimizations or generate code for them under that assumption. +This is something we’d like to change in the future to provide better +support for freestanding environments and non-C-based languages.

+
+`, tooltip: `The ‘call’ instruction represents a simple function call.`, }; case 'VA-ARG': return { url: `https://llvm.org/docs/LangRef.html#va-arg-instruction`, - html: `

‘va_arg’ Instruction

Syntax:
<resultval> = va_arg <va_list*> <arglist>, <argty>
Overview:

The ‘va_arg’ instruction is used to access arguments passed throughthe “variable argument” area of a function call. It is used to implementthe va_arg macro in C.

Arguments:

This instruction takes a va_list* value and the type of theargument. It returns a value of the specified argument type andincrements the va_list to point to the next argument. The actualtype of va_list is target specific.

Semantics:

The ‘va_arg’ instruction loads an argument of the specified typefrom the specified va_list and causes the va_list to point tothe next argument. For more information, see the variable argumenthandling Intrinsic Functions.

It is legal for this instruction to be called in a function which doesnot take a variable number of arguments, for example, the vfprintffunction.

va_arg is an LLVM instruction instead of an intrinsicfunction because it takes a type as an argument.

Example:

See the variable argument processing section.

Note that the code generator does not yet fully support va_arg on manytargets. Also, it does not currently support va_arg with aggregatetypes on any target.

`, + html: `

‘va_arg’ Instruction

+
+
Syntax:
+
<resultval> = va_arg <va_list*> <arglist>, <argty>
+
+
+
+
+
Overview:
+

The ‘va_arg’ instruction is used to access arguments passed through +the “variable argument” area of a function call. It is used to implement +the va_arg macro in C.

+
+
+
Arguments:
+

This instruction takes a va_list* value and the type of the +argument. It returns a value of the specified argument type and +increments the va_list to point to the next argument. The actual +type of va_list is target specific.

+
+
+
Semantics:
+

The ‘va_arg’ instruction loads an argument of the specified type +from the specified va_list and causes the va_list to point to +the next argument. For more information, see the variable argument +handling Intrinsic Functions.

+

It is legal for this instruction to be called in a function which does +not take a variable number of arguments, for example, the vfprintf +function.

+

va_arg is an LLVM instruction instead of an intrinsic +function because it takes a type as an argument.

+
+
+
Example:
+

See the variable argument processing section.

+

Note that the code generator does not yet fully support va_arg on many +targets. Also, it does not currently support va_arg with aggregate +types on any target.

+
+`, tooltip: `The ‘va_arg’ instruction is used to access arguments passed throughthe “variable argument” area of a function call. It is used to implementthe va_arg macro in C.`, }; case 'LANDINGPAD': return { url: `https://llvm.org/docs/LangRef.html#landingpad-instruction`, - html: `

‘landingpad’ Instruction

Syntax:
<resultval> = landingpad <resultty> <clause>+<resultval> = landingpad <resultty> cleanup <clause>*<clause> := catch <type> <value><clause> := filter <array constant type> <array constant>
Overview:

The ‘landingpad’ instruction is used by LLVM’s exception handlingsystem to specify that a basic blockis a landing pad — one where the exception lands, and corresponds to thecode found in the catch portion of a try/catch sequence. Itdefines values supplied by the personality function uponre-entry to the function. The resultval has the type resultty.

Arguments:

The optionalcleanup flag indicates that the landing pad block is a cleanup.

A clause begins with the clause type — catch or filter — andcontains the global variable representing the “type” that may be caughtor filtered respectively. Unlike the catch clause, the filterclause takes an array constant as its argument. Use“[0 x ptr] undef” for a filter which cannot throw. The‘landingpad’ instruction must contain at least one clause orthe cleanup flag.

Semantics:

The ‘landingpad’ instruction defines the values which are set by thepersonality function upon re-entry to the function, andtherefore the “result type” of the landingpad instruction. As withcalling conventions, how the personality function results arerepresented in LLVM IR is target specific.

The clauses are applied in order from top to bottom. If twolandingpad instructions are merged together through inlining, theclauses from the calling function are appended to the list of clauses.When the call stack is being unwound due to an exception being thrown,the exception is compared against each clause in turn. If it doesn’tmatch any of the clauses, and the cleanup flag is not set, thenunwinding continues further up the call stack.

The landingpad instruction has several restrictions:

Example:
;; A landing pad which can catch an integer.%res = landingpad { ptr, i32 }         catch ptr @_ZTIi;; A landing pad that is a cleanup.%res = landingpad { ptr, i32 }         cleanup;; A landing pad which can catch an integer and can only throw a double.%res = landingpad { ptr, i32 }         catch ptr @_ZTIi         filter [1 x ptr] [ptr @_ZTId]
`, + html: `

‘landingpad’ Instruction

+
+
Syntax:
+
<resultval> = landingpad <resultty> <clause>+
+<resultval> = landingpad <resultty> cleanup <clause>*
+
+<clause> := catch <type> <value>
+<clause> := filter <array constant type> <array constant>
+
+
+
+
+
Overview:
+

The ‘landingpad’ instruction is used by LLVM’s exception handling +system to specify that a basic block +is a landing pad — one where the exception lands, and corresponds to the +code found in the catch portion of a try/catch sequence. It +defines values supplied by the personality function upon +re-entry to the function. The resultval has the type resultty.

+
+
+
Arguments:
+

The optional +cleanup flag indicates that the landing pad block is a cleanup.

+

A clause begins with the clause type — catch or filter — and +contains the global variable representing the “type” that may be caught +or filtered respectively. Unlike the catch clause, the filter +clause takes an array constant as its argument. Use +“[0 x ptr] undef” for a filter which cannot throw. The +‘landingpad’ instruction must contain at least one clause or +the cleanup flag.

+
+
+
Semantics:
+

The ‘landingpad’ instruction defines the values which are set by the +personality function upon re-entry to the function, and +therefore the “result type” of the landingpad instruction. As with +calling conventions, how the personality function results are +represented in LLVM IR is target specific.

+

The clauses are applied in order from top to bottom. If two +landingpad instructions are merged together through inlining, the +clauses from the calling function are appended to the list of clauses. +When the call stack is being unwound due to an exception being thrown, +the exception is compared against each clause in turn. If it doesn’t +match any of the clauses, and the cleanup flag is not set, then +unwinding continues further up the call stack.

+

The landingpad instruction has several restrictions:

+ +
+
+
Example:
+
;; A landing pad which can catch an integer.
+%res = landingpad { ptr, i32 }
+         catch ptr @_ZTIi
+;; A landing pad that is a cleanup.
+%res = landingpad { ptr, i32 }
+         cleanup
+;; A landing pad which can catch an integer and can only throw a double.
+%res = landingpad { ptr, i32 }
+         catch ptr @_ZTIi
+         filter [1 x ptr] [ptr @_ZTId]
+
+
+
+`, tooltip: `The ‘landingpad’ instruction is used by LLVM’s exception handlingsystem to specify that a basic blockis a landing pad — one where the exception lands, and corresponds to thecode found in the catch portion of a try/catch sequence. Itdefines values supplied by the personality function uponre-entry to the function. The resultval has the type resultty.`, }; case 'CATCHPAD': return { url: `https://llvm.org/docs/LangRef.html#catchpad-instruction`, - html: `

‘catchpad’ Instruction

Syntax:
<resultval> = catchpad within <catchswitch> [<args>*]
Overview:

The ‘catchpad’ instruction is used by LLVM’s exception handlingsystem to specify that a basic blockbegins a catch handler — one where a personality routine attempts to transfercontrol to catch an exception.

Arguments:

The catchswitch operand must always be a token produced by acatchswitch instruction in a predecessor block. Thisensures that each catchpad has exactly one predecessor block, and it alwaysterminates in a catchswitch.

The args correspond to whatever information the personality routinerequires to determine if this is an appropriate handler for the exception. Controlwill transfer to the catchpad if this is the first appropriate handler forthe exception.

The resultval has the type token and is used to match thecatchpad to corresponding catchrets and other nested EHpads.

Semantics:

When the call stack is being unwound due to an exception being thrown, theexception is compared against the args. If it doesn’t match, control willnot reach the catchpad instruction. The representation of args isentirely target and personality function-specific.

Like the landingpad instruction, the catchpadinstruction must be the first non-phi of its parent basic block.

The meaning of the tokens produced and consumed by catchpad and other “pad”instructions is described in theWindows exception handling documentation.

When a catchpad has been “entered” but not yet “exited” (asdescribed in the EH documentation),it is undefined behavior to execute a call or invokethat does not carry an appropriate “funclet” bundle.

Example:
dispatch:  %cs = catchswitch within none [label %handler0] unwind to caller  ;; A catch block which can catch an integer.handler0:  %tok = catchpad within %cs [ptr @_ZTIi]
`, + html: `

‘catchpad’ Instruction

+
+
Syntax:
+
<resultval> = catchpad within <catchswitch> [<args>*]
+
+
+
+
+
Overview:
+

The ‘catchpad’ instruction is used by LLVM’s exception handling +system to specify that a basic block +begins a catch handler — one where a personality routine attempts to transfer +control to catch an exception.

+
+
+
Arguments:
+

The catchswitch operand must always be a token produced by a +catchswitch instruction in a predecessor block. This +ensures that each catchpad has exactly one predecessor block, and it always +terminates in a catchswitch.

+

The args correspond to whatever information the personality routine +requires to determine if this is an appropriate handler for the exception. Control +will transfer to the catchpad if this is the first appropriate handler for +the exception.

+

The resultval has the type token and is used to match the +catchpad to corresponding catchrets and other nested EH +pads.

+
+
+
Semantics:
+

When the call stack is being unwound due to an exception being thrown, the +exception is compared against the args. If it doesn’t match, control will +not reach the catchpad instruction. The representation of args is +entirely target and personality function-specific.

+

Like the landingpad instruction, the catchpad +instruction must be the first non-phi of its parent basic block.

+

The meaning of the tokens produced and consumed by catchpad and other “pad” +instructions is described in the +Windows exception handling documentation.

+

When a catchpad has been “entered” but not yet “exited” (as +described in the EH documentation), +it is undefined behavior to execute a call or invoke +that does not carry an appropriate “funclet” bundle.

+
+
+
Example:
+
dispatch:
+  %cs = catchswitch within none [label %handler0] unwind to caller
+  ;; A catch block which can catch an integer.
+handler0:
+  %tok = catchpad within %cs [ptr @_ZTIi]
+
+
+
+`, tooltip: `The ‘catchpad’ instruction is used by LLVM’s exception handlingsystem to specify that a basic blockbegins a catch handler — one where a personality routine attempts to transfercontrol to catch an exception.`, }; case 'CLEANUPPAD': return { url: `https://llvm.org/docs/LangRef.html#cleanuppad-instruction`, - html: `

‘cleanuppad’ Instruction

Syntax:
<resultval> = cleanuppad within <parent> [<args>*]
Overview:

The ‘cleanuppad’ instruction is used by LLVM’s exception handlingsystem to specify that a basic blockis a cleanup block — one where a personality routine attempts totransfer control to run cleanup actions.The args correspond to whatever additionalinformation the personality function requires toexecute the cleanup.The resultval has the type token and is used tomatch the cleanuppad to corresponding cleanuprets.The parent argument is the token of the funclet that contains thecleanuppad instruction. If the cleanuppad is not inside a funclet,this operand may be the token none.

Arguments:

The instruction takes a list of arbitrary values which are interpretedby the personality function.

Semantics:

When the call stack is being unwound due to an exception being thrown,the personality function transfers control to thecleanuppad with the aid of the personality-specific arguments.As with calling conventions, how the personality function results arerepresented in LLVM IR is target specific.

The cleanuppad instruction has several restrictions:

When a cleanuppad has been “entered” but not yet “exited” (asdescribed in the EH documentation),it is undefined behavior to execute a call or invokethat does not carry an appropriate “funclet” bundle.

Example:
%tok = cleanuppad within %cs []
`, + html: `

‘cleanuppad’ Instruction

+
+
Syntax:
+
<resultval> = cleanuppad within <parent> [<args>*]
+
+
+
+
+
Overview:
+

The ‘cleanuppad’ instruction is used by LLVM’s exception handling +system to specify that a basic block +is a cleanup block — one where a personality routine attempts to +transfer control to run cleanup actions. +The args correspond to whatever additional +information the personality function requires to +execute the cleanup. +The resultval has the type token and is used to +match the cleanuppad to corresponding cleanuprets. +The parent argument is the token of the funclet that contains the +cleanuppad instruction. If the cleanuppad is not inside a funclet, +this operand may be the token none.

+
+
+
Arguments:
+

The instruction takes a list of arbitrary values which are interpreted +by the personality function.

+
+
+
Semantics:
+

When the call stack is being unwound due to an exception being thrown, +the personality function transfers control to the +cleanuppad with the aid of the personality-specific arguments. +As with calling conventions, how the personality function results are +represented in LLVM IR is target specific.

+

The cleanuppad instruction has several restrictions:

+ +

When a cleanuppad has been “entered” but not yet “exited” (as +described in the EH documentation), +it is undefined behavior to execute a call or invoke +that does not carry an appropriate “funclet” bundle.

+
+
+
Example:
+
%tok = cleanuppad within %cs []
+
+
+
+`, tooltip: `The ‘cleanuppad’ instruction is used by LLVM’s exception handlingsystem to specify that a basic blockis a cleanup block — one where a personality routine attempts totransfer control to run cleanup actions.The args correspond to whatever additionalinformation the personality function requires toexecute the cleanup.The resultval has the type token and is used tomatch the cleanuppad to corresponding cleanuprets.The parent argument is the token of the funclet that contains thecleanuppad instruction. If the cleanuppad is not inside a funclet,this operand may be the token none.`, }; }