ret’ Instruction¶ret <type> <value> ; Return a value from a non-void functionret void ; Return from void functionThe ‘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.
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.
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.
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 2br’ Instruction¶br i1 <cond>, label <iftrue>, label <iffalse>br label <dest> ; Unconditional branchThe ‘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.
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.
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.
Test: %cond = icmp eq i32 %a, %b br i1 %cond, label %IfEqual, label %IfUnequalIfEqual: ret i32 1IfUnequal: ret i32 0switch’ Instruction¶switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]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.
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.
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.
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.
; 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 ]indirectbr’ Instruction¶indirectbr ptr <address>, [ label <dest1>, label <dest2>, ... ]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.
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.
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.
This is typically implemented with a jump through a register.
indirectbr ptr %Addr, [ label %bb1, label %bb2, label %bb3 ]invoke’ Instruction¶<result> = invoke [cconv] [ret attrs] [addrspace(<num>)] <ty>|<fnty> <fnptrval>(<function args>) [fn attrs] [operand bundles] to label <normal label> unwind label <exception label>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.
This instruction requires several arguments:
zeroext’, ‘signext’, and ‘inreg’ attributesare valid here.ty’: the type of the call instruction itself which is also thetype of the return value. Functions that return no value are markedvoid.fnty’: shall be the signature of the function being invoked. Theargument types must match the types implied by this signature. Thistype can be omitted if the function is not varargs.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.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.normal label’: the label reached when the called functionexecutes a ‘ret’ instruction.exception label’: the label reached when a callee returns viathe resume instruction or other exception handlingmechanism.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.
%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 setcallbr’ Instruction¶<result> = callbr [cconv] [ret attrs] [addrspace(<num>)] <ty>|<fnty> <fnptrval>(<function args>) [fn attrs] [operand bundles] to label <fallthrough label> [indirect labels]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.
This instruction requires several arguments:
zeroext’, ‘signext’, and ‘inreg’ attributesare valid here.ty’: the type of the call instruction itself which is also thetype of the return value. Functions that return no value are markedvoid.fnty’: shall be the signature of the function being called. Theargument types must match the types implied by this signature. Thistype can be omitted if the function is not varargs.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.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.fallthrough label’: the label reached when the inline assembly’sexecution exits the bottom.indirect labels’: the labels reached when a callee transfers controlto a location other than the ‘fallthrough label’. Label constraintsrefer to these destinations.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 only tothe ‘fallthrough’ block, not to 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.
; "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]resume’ Instruction¶resume <type> <value>The ‘resume’ instruction is a terminator instruction that has nosuccessors.
The ‘resume’ instruction requires one argument, which must have thesame type as the result of any ‘landingpad’ instruction in the samefunction.
The ‘resume’ instruction resumes propagation of an existing(in-flight) exception whose unwinding was interrupted with alandingpad instruction.
resume { ptr, i32 } %exncatchswitch’ Instruction¶<resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind to caller<resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind label <default>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.
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.
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.
dispatch1: %cs1 = catchswitch within none [label %handler0, label %handler1] unwind to callerdispatch2: %cs2 = catchswitch within %parenthandler [label %handler0] unwind label %cleanupcatchret’ Instruction¶catchret from <token> to label <normal>The ‘catchret’ instruction is a terminator instruction that has asingle successor.
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.
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.
catchret from %catch to label %continuecleanupret’ Instruction¶cleanupret from <value> unwind label <continue>cleanupret from <value> unwind to callerThe ‘cleanupret’ instruction is a terminator instruction that hasan optional successor.
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.
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.
cleanupret from %cleanup unwind to callercleanupret from %cleanup unwind label %continueunreachable’ Instruction¶unreachableThe ‘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.
The ‘unreachable’ instruction has no defined semantics.
fneg’ Instruction¶<result> = fneg [fast-math flags]* <ty> <op1> ; yields ty:resultThe ‘fneg’ instruction returns the negation of its operand.
The argument to the ‘fneg’ instruction must be afloating-point or vector offloating-point values.
The value produced is a copy of the operand with its sign bit flipped.This instruction can also take any number of fast-mathflags, which are optimization hints to enable otherwiseunsafe floating-point optimizations:
<result> = fneg float %val ; yields float:result = -%varadd’ Instruction¶<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:resultThe ‘add’ instruction returns the sum of its two operands.
The two arguments to the ‘add’ instruction must beinteger or vector of integer values. Botharguments must have identical types.
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.
<result> = add i32 4, %var ; yields i32:result = 4 + %varfadd’ Instruction¶<result> = fadd [fast-math flags]* <ty> <op1>, <op2> ; yields ty:resultThe ‘fadd’ instruction returns the sum of its two operands.
The two arguments to the ‘fadd’ instruction must befloating-point or vector offloating-point values. Both arguments must have identical types.
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:
<result> = fadd float 4.0, %var ; yields float:result = 4.0 + %varsub’ Instruction¶<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:resultThe ‘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.
The two arguments to the ‘sub’ instruction must beinteger or vector of integer values. Botharguments must have identical types.
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.
<result> = sub i32 4, %var ; yields i32:result = 4 - %var<result> = sub i32 0, %val ; yields i32:result = -%varfsub’ Instruction¶<result> = fsub [fast-math flags]* <ty> <op1>, <op2> ; yields ty:resultThe ‘fsub’ instruction returns the difference of its two operands.
The two arguments to the ‘fsub’ instruction must befloating-point or vector offloating-point values. Both arguments must have identical types.
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:
<result> = fsub float 4.0, %var ; yields float:result = 4.0 - %var<result> = fsub float -0.0, %val ; yields float:result = -%varmul’ Instruction¶<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:resultThe ‘mul’ instruction returns the product of its two operands.
The two arguments to the ‘mul’ instruction must beinteger or vector of integer values. Botharguments must have identical types.
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.
<result> = mul i32 4, %var ; yields i32:result = 4 * %varfmul’ Instruction¶<result> = fmul [fast-math flags]* <ty> <op1>, <op2> ; yields ty:resultThe ‘fmul’ instruction returns the product of its two operands.
The two arguments to the ‘fmul’ instruction must befloating-point or vector offloating-point values. Both arguments must have identical types.
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:
<result> = fmul float 4.0, %var ; yields float:result = 4.0 * %varudiv’ Instruction¶<result> = udiv <ty> <op1>, <op2> ; yields ty:result<result> = udiv exact <ty> <op1>, <op2> ; yields ty:resultThe ‘udiv’ instruction returns the quotient of its two operands.
The two arguments to the ‘udiv’ instruction must beinteger or vector of integer values. Botharguments must have identical types.
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”).
<result> = udiv i32 4, %var ; yields i32:result = 4 / %varsdiv’ Instruction¶<result> = sdiv <ty> <op1>, <op2> ; yields ty:result<result> = sdiv exact <ty> <op1>, <op2> ; yields ty:resultThe ‘sdiv’ instruction returns the quotient of its two operands.
The two arguments to the ‘sdiv’ instruction must beinteger or vector of integer values. Botharguments must have identical types.
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.
<result> = sdiv i32 4, %var ; yields i32:result = 4 / %varfdiv’ Instruction¶<result> = fdiv [fast-math flags]* <ty> <op1>, <op2> ; yields ty:resultThe ‘fdiv’ instruction returns the quotient of its two operands.
The two arguments to the ‘fdiv’ instruction must befloating-point or vector offloating-point values. Both arguments must have identical types.
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:
<result> = fdiv float 4.0, %var ; yields float:result = 4.0 / %varurem’ Instruction¶<result> = urem <ty> <op1>, <op2> ; yields ty:resultThe ‘urem’ instruction returns the remainder from the unsigneddivision of its two arguments.
The two arguments to the ‘urem’ instruction must beinteger or vector of integer values. Botharguments must have identical types.
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.
<result> = urem i32 4, %var ; yields i32:result = 4 % %varsrem’ Instruction¶<result> = srem <ty> <op1>, <op2> ; yields ty:resultThe ‘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.
The two arguments to the ‘srem’ instruction must beinteger or vector of integer values. Botharguments must have identical types.
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.)
<result> = srem i32 4, %var ; yields i32:result = 4 % %varfrem’ Instruction¶<result> = frem [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result