X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FLangRef.html;h=f8ca2879c44743480160fe5e97cf9469706d9096;hb=b9a31a15f9ee8d4eff5bb0fec3dbfde54121af56;hp=94ef37b97a7e79ef39daef4c30182d96225c32b3;hpb=0c46a7d66688c6e38d59d17e302b8bcd354b04c5;p=oota-llvm.git diff --git a/docs/LangRef.html b/docs/LangRef.html index 94ef37b97a7..f8ca2879c44 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -24,7 +24,7 @@
LLVM identifiers come in two basic types: global and local. Global identifiers (functions, global variables) begin with the @ character. Local identifiers (register names, types) begin with the % character. Additionally, - there are three different formats for identifiers, for different purposes: + there are three different formats for identifiers, for different purposes:
Aliases can have only external, internal and weak -linkages. +linkages.
@@ -750,8 +751,9 @@ an optional linkage type, an optional calling convention, a return type, an optional parameter attribute for the return type, a function name, a (possibly empty) argument list (each with optional -parameter attributes), an optional section, an -optional alignment, an optional garbage collector name, +parameter attributes), optional +function attributes, an optional section, +an optional alignment, an optional garbage collector name, an opening curly brace, a list of basic blocks, and a closing curly brace. LLVM function declarations consist of the "declare" keyword, an @@ -784,6 +786,18 @@ to whatever it feels convenient. If an explicit alignment is specified, the function is forced to have at least that much alignment. All alignments must be a power of 2. +declare i32 @printf(i8* noalias , ...) -declare i32 @atoi(i8 zeroext*) +declare i32 @atoi(i8 zeroext) +declare signext i8 @returns_signed_char()
Currently, only the following parameter attributes are defined:
When LLVM is determining the alignment for a given type, it uses the -following rules: +following rules:
TODO: The format of the asm and constraints string still need to be documented here. Constraints on what can be done (e.g. duplication, moving, etc -need to be documented). +need to be documented). This is probably best done by reference to another +document that covers inline asm from a holistic perspective.
@@ -1888,27 +1923,30 @@ the 'invoke' instruction, the 'ret <type> <value> ; Return a value from a non-void function ++ ret <type> <value> ; Return a value from a non-void function ret void ; Return from void function - ret <type> <value>, <type> <value> ; Return two values from a non-void functionOverview:
-The 'ret' instruction is used to return control flow (and a -value) from a function back to the caller.
+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 value(s) and then causes control flow, and one that just causes +returns a value and then causes control flow, and one that just causes control flow to occur.
Arguments:
-The 'ret' instruction may return zero, one or multiple values. -The type of each return value must be a 'first -class' type. Note that a function is not well -formed if there exists a 'ret' instruction inside of the -function that returns values that do not match the return type of the -function.
+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 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:
@@ -1919,16 +1957,14 @@ 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. If the instruction returns multiple values then these -values can only be accessed through a 'getresult -' instruction. +return value.Example:
ret i32 5 ; Return an integer value of 5 ret void ; Return from a void function - ret i32 4, i8 2 ; Return two values 4 and 2 + ret { i32, i8 } { i32 4, i8 2 } ; Return an aggregate of values 4 and 2
- <result> = invoke [cconv] <ptr to function ty> <function ptr val>(<function args>) + <result> = invoke [cconv] [ret attrs] <ptr to function ty> <function ptr val>(<function args>) [fn attrs] to label <normal label> unwind label <exception label>@@ -2038,9 +2074,7 @@ function, with the possibility of control flow transfer to either the "ret" instruction, control flow will return to the "normal" label. If the callee (or any indirect callees) returns with the "unwind" instruction, control is interrupted and -continued at the dynamically nearest "exception" label. If the callee function -returns multiple values then individual return values are only accessible through -a 'getresult' instruction. +continued at the dynamically nearest "exception" label.
- <result> = getelementptr <ty>* <ptrval>{, <ty> <idx>}* + <result> = getelementptr <pty>* <ptrval>{, <ty> <idx>}*
The 'getelementptr' instruction is used to get the address of a -subelement of an aggregate data structure.
+subelement of an aggregate data structure. It performs address calculation only +and does not access memory.This instruction takes a list of integer operands that indicate what -elements of the aggregate object to index to. The actual types of the arguments -provided depend on the type of the first pointer argument. The -'getelementptr' instruction is used to index down through the type -levels of a structure or to a specific index in an array. When indexing into a -structure, only i32 integer constants are allowed. When indexing -into an array or pointer, only integers of 32 or 64 bits are allowed; 32-bit -values will be sign extended to 64-bits if required.
+The first argument is always a pointer, and forms the basis of the +calculation. 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 first 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 (packed) structure, only i32 integer +constants are allowed. When indexing into an array, pointer or vector, +only integers of 32 or 64 bits are allowed (also non-constants). 32-bit values +will be sign extended to 64-bits if required.
For example, let's consider a C code fragment and how it gets compiled to LLVM:
@@ -3340,13 +3392,6 @@ entry:The index types specified for the 'getelementptr' instruction depend -on the pointer type that is being indexed into. Pointer -and array types can use a 32-bit or 64-bit -integer type but the value will always be sign extended -to 64-bits. Structure and packed -structure types require i32 constants.
-In the example above, the first index is indexing into the '%ST*' type, which is a pointer, yielding a '%ST' = '{ i32, double, %RT }' type, a structure. The second index indexes into the third element of @@ -3386,7 +3431,11 @@ FAQ.
; yields [12 x i8]*:aptr - %aptr = getelementptr {i32, [12 x i8]}* %sptr, i64 0, i32 1 + %aptr = getelementptr {i32, [12 x i8]}* %saptr, i64 0, i32 1 + ; yields i8*:vptr + %vptr = getelementptr {i32, <2 x i8>}* %svptr, i64 0, i32 1, i32 1 + ; yields i8*:eptr + %eptr = getelementptr [12 x i8]* %aptr, i64 0, i32 1
%X = uitofp i32 257 to float ; yields float:257.0 - %Y = uitofp i8 -1 to double ; yields double:255.0 + %Y = uitofp i8 -1 to double ; yields double:255.0@@ -3722,7 +3771,7 @@ the value cannot fit in the floating point value, the results are undefined.
%X = sitofp i32 257 to float ; yields float:257.0 - %Y = sitofp i8 -1 to double ; yields double:-1.0 + %Y = sitofp i8 -1 to double ; yields double:-1.0@@ -3744,7 +3793,7 @@ the integer type ty2.
The 'ptrtoint' instruction takes a value to cast, which must be a pointer value, and a type to cast it to -ty2, which must be an integer type. +ty2, which must be an integer type.
The 'ptrtoint' instruction converts value to integer type @@ -3780,7 +3829,7 @@ a pointer type, ty2.
The 'inttoptr' instruction takes an integer value to cast, and a type to cast it to, which must be a -pointer type. +pointer type.
The 'inttoptr' instruction converts value to type @@ -3838,7 +3887,7 @@ other types, use the inttoptr or
%X = bitcast i8 255 to i8 ; yields i8 :-1 %Y = bitcast i32* %x to sint* ; yields sint*:%x - %Z = bitcast <2xint> %V to i64; ; yields i64: %V + %Z = bitcast <2 x int> %V to i64; ; yields i64: %V@@ -3854,7 +3903,7 @@ instructions, which defy better classification.
<result> = icmp <cond> <ty> <op1>, <op2> ; yields {i1} or {<N x i1>}:result +<result> = icmp <cond> <ty> <op1>, <op2> ; yields {i1} or {<N x i1>}:resultOverview:
The 'icmp' instruction returns a boolean value or @@ -3864,6 +3913,7 @@ of its two integer, integer vector, or pointer operands.
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 code are: +
- eq: equal
- ne: not equal
@@ -3884,12 +3934,13 @@ They must also be identical types.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: +
- eq: yields true if the operands are equal, false otherwise. No sign interpretation is necessary or performed.
- ne: yields true if the operands are unequal, - false otherwise. No sign interpretation is necessary or performed. + false otherwise. No sign interpretation is necessary or performed.
- ugt: interprets the operands as unsigned values and yields true if op1 is greater than op2.
- uge: interprets the operands as unsigned values and yields @@ -3930,12 +3981,12 @@ Otherwise, the result is an i1.
<result> = fcmp <cond> <ty> <op1>, <op2> ; yields {i1} or {<N x i1>}:result +<result> = fcmp <cond> <ty> <op1>, <op2> ; yields {i1} or {<N x i1>}:resultOverview:
The 'fcmp' instruction returns a boolean value or vector of boolean values based on comparison -of its operands. +of its operands.
If the operands are floating point scalars, then the result type is a boolean (i1). @@ -3946,7 +3997,7 @@ 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 code are: +a value, just a keyword. The possible condition code are:
- false: no comparison, always returns false
- oeq: ordered and equal
@@ -3977,7 +4028,7 @@ 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: +always yields an i1 result, as follows:
- false: always yields false, regardless of operands.
- oeq: yields true if both operands are not a QNAN and @@ -4031,7 +4082,7 @@ element-wise comparison of its two integer vector operands.
Arguments:
The 'vicmp' 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 code are: +a value, just a keyword. The possible condition code are:
- eq: equal
- ne: not equal
@@ -4054,7 +4105,7 @@ identical type as the values being compared. The most significant bit in each element is 1 if the element-wise comparison evaluates to true, and is 0 otherwise. All other bits of the result are undefined. The condition codes are evaluated identically to the 'icmp' -instruction. +instruction.Example:
@@ -4077,7 +4128,7 @@ elements have the same width as the input elements.Arguments:
The 'vfcmp' 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 code are: +a value, just a keyword. The possible condition code are:
- false: no comparison, always returns false
- oeq: ordered and equal
@@ -4108,12 +4159,15 @@ having identical with to the width of the floating point elements. The most significant bit in each element is 1 if the element-wise comparison evaluates to true, and is 0 otherwise. All other bits of the result are undefined. The condition codes are evaluated identically to the -'fcmp' instruction. +'fcmp' instruction.Example:
- <result> = vfcmp oeq <2 x float> < float 4, float 0 >, < float 5, float 0 > ; yields: result=<2 x i32> < i32 0, i32 -1 > - <result> = vfcmp ult <2 x double> < double 1, double 2 >, < double 2, double 2> ; yields: result=<2 x i64> < i64 -1, i64 0 > + ; yields: result=<2 x i32> < i32 0, i32 -1 > + <result> = vfcmp oeq <2 x float> < float 4, float 0 >, < float 5, float 0 > + + ; yields: result=<2 x i64> < i64 -1, i64 0 > + <result> = vfcmp ult <2 x double> < double 1, double 2 >, < double 2, double 2>
<result> = select selty <cond>, <ty> <val1>, <ty> <val2> ; yields ty - selty is either i1 or {<N x i1>} + selty is either i1 or {<N x i1>}
- <result> = [tail] call [cconv] <ty> [<fnty>*] <fnptrval>(<param list>) + <result> = [tail] call [cconv] [ret attrs] <ty> [<fnty>*] <fnptrval>(<function args>) [fn attrs]
The optional "cconv" marker indicates which calling convention the call should use. If none is specified, the call defaults - to using C calling conventions. + to using C calling conventions.
The optional Parameter Attributes list for + return values. Only 'zeroext', 'signext', + and 'inreg' attributes are valid here.
+'ty': the type of the call instruction itself which is also the type of the return value. Functions that return no value are marked @@ -4269,6 +4330,11 @@ by element. indicates the function accepts a variable number of arguments, the extra arguments can be specified.
The optional function attributes list. Only + 'noreturn', 'nounwind', 'readonly' and + 'readnone' attributes are valid here.
+- <resultval> = getresult <type> <retval>, <index> -- -
The 'getresult' instruction is used to extract individual values -from a 'call' -or 'invoke' instruction that returns multiple -results.
- -The 'getresult' instruction takes a call or invoke value as its -first argument, or an undef value. The value must have structure type. The second argument is a constant -unsigned index value which must be in range for the number of values returned -by the call.
- -The 'getresult' instruction extracts the element identified by -'index' from the aggregate value.
- -- %struct.A = type { i32, i8 } - - %r = call %struct.A @foo() - %gr = getresult %struct.A %r, 0 ; yields i32:%gr - %gr1 = getresult %struct.A %r, 1 ; yields i8:%gr1 - add i32 %gr, 42 - add i8 %gr1, 41 -- -
declare void %llvm.va_start(i8* <arglist>)
The 'llvm.va_start' intrinsic initializes +
The 'llvm.va_start' intrinsic initializes *<arglist> for subsequent use by va_arg.
The argument is a pointer to a va_list element to initialize.
+The argument is a pointer to a va_list element to initialize.
The 'llvm.va_start' intrinsic works just like the va_start +
The 'llvm.va_start' intrinsic works just like the va_start macro available in C. In a target-dependent way, it initializes the va_list element to which the argument points, so that the next call to va_arg will produce the first variable argument passed to the function. @@ -5194,7 +5214,7 @@ this can be specified as the fourth argument, otherwise it should be set to 0 or
This is an overloaded intrinsic. You can use llvm.sqrt on any floating point or vector of floating point type. Not all targets support all -types however. +types however.
declare float @llvm.sqrt.f32(float %Val) declare double @llvm.sqrt.f64(double %Val) @@ -5238,7 +5258,7 @@ floating point number.Syntax:
This is an overloaded intrinsic. You can use llvm.powi on any floating point or vector of floating point type. Not all targets support all -types however. +types however.
declare float @llvm.powi.f32(float %Val, i32 %power) declare double @llvm.powi.f64(double %Val, i32 %power) @@ -5280,7 +5300,7 @@ unspecified sequence of rounding operations.Syntax:
This is an overloaded intrinsic. You can use llvm.sin on any floating point or vector of floating point type. Not all targets support all -types however. +types however.
declare float @llvm.sin.f32(float %Val) declare double @llvm.sin.f64(double %Val) @@ -5319,7 +5339,7 @@ conditions in the same way.Syntax:
This is an overloaded intrinsic. You can use llvm.cos on any floating point or vector of floating point type. Not all targets support all -types however. +types however.
declare float @llvm.cos.f32(float %Val) declare double @llvm.cos.f64(double %Val) @@ -5358,7 +5378,7 @@ conditions in the same way.Syntax:
This is an overloaded intrinsic. You can use llvm.pow on any floating point or vector of floating point type. Not all targets support all -types however. +types however.
declare float @llvm.pow.f32(float %Val, float %Power) declare double @llvm.pow.f64(double %Val, double %Power) @@ -5413,7 +5433,7 @@ These allow efficient code generation for some algorithms.Syntax:
This is an overloaded intrinsic function. You can use bswap on any integer -type that is an even number of bytes (i.e. BitWidth % 16 == 0). +type that is an even number of bytes (i.e. BitWidth % 16 == 0).
declare i16 @llvm.bswap.i16(i16 <id>) declare i32 @llvm.bswap.i32(i32 <id>) @@ -5452,7 +5472,7 @@ additional even-byte lengths (6 bytes, 8 bytes and more, respectively).Syntax:
This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit -width. Not all targets support all bit widths however. +width. Not all targets support all bit widths however.
declare i8 @llvm.ctpop.i8 (i8 <src>) declare i16 @llvm.ctpop.i16(i16 <src>) @@ -5491,7 +5511,7 @@ The 'llvm.ctpop' intrinsic counts the 1's in a variable.Syntax:
This is an overloaded intrinsic. You can use llvm.ctlz on any -integer bit width. Not all targets support all bit widths however. +integer bit width. Not all targets support all bit widths however.
declare i8 @llvm.ctlz.i8 (i8 <src>) declare i16 @llvm.ctlz.i16(i16 <src>) @@ -5534,7 +5554,7 @@ of src. For example, llvm.ctlz(i32 2) = 30.Syntax:
This is an overloaded intrinsic. You can use llvm.cttz on any -integer bit width. Not all targets support all bit widths however. +integer bit width. Not all targets support all bit widths however.
declare i8 @llvm.cttz.i8 (i8 <src>) declare i16 @llvm.cttz.i16(i16 <src>) @@ -5575,7 +5595,7 @@ of src. For example, llvm.cttz(2) = 1.Syntax:
This is an overloaded intrinsic. You can use llvm.part.select -on any integer bit width. +on any integer bit width.
declare i17 @llvm.part.select.i17 (i17 %val, i32 %loBit, i32 %hiBit) declare i29 @llvm.part.select.i29 (i29 %val, i32 %loBit, i32 %hiBit) @@ -5605,7 +5625,7 @@ only the %hiBit - %loBit bits set, as follows:
In reverse mode, a similar computation is made except that the bits are returned in the reverse order. So, for example, if X has the value @@ -5622,7 +5642,7 @@ returned in the reverse order. So, for example, if X has the value
This is an overloaded intrinsic. You can use llvm.part.set -on any integer bit width. +on any integer bit width.
declare i17 @llvm.part.set.i17.i9 (i17 %val, i9 %repl, i32 %lo, i32 %hi) declare i29 @llvm.part.set.i29.i9 (i29 %val, i9 %repl, i32 %lo, i32 %hi) @@ -5651,10 +5671,10 @@ up to that size.In forward mode, the bits between %lo and %hi (inclusive) are replaced with corresponding bits from %repl. That is the 0th bit in %repl replaces the %loth bit in %val and etc. up -to the %hith bit. +to the %hith bit.
In reverse mode, a similar computation is made except that the bits are reversed. That is, the 0th bit in %repl replaces the -%hi bit in %val and etc. down to the %loth bit. +%hi bit in %val and etc. down to the %loth bit.
Examples:
llvm.part.set(0xFFFF, 0, 4, 7) -> 0xFF0F @@ -5821,7 +5841,7 @@ i1 <device> )
@@ -6345,6 +6365,7 @@ This intrinsic allows annotations to be put on arbitrary expressions with arbitrary strings. This can be useful for special purpose optimizations that want to look for these annotations. These have no other defined use, they are ignored by code generation and optimization. +