diff options
Diffstat (limited to 'docs')
61 files changed, 8129 insertions, 5281 deletions
diff --git a/docs/BitCodeFormat.html b/docs/BitCodeFormat.html index df0a74d..e75887b 100644 --- a/docs/BitCodeFormat.html +++ b/docs/BitCodeFormat.html @@ -254,7 +254,7 @@ Blocks in a bitstream denote nested regions of the stream, and are identified by a content-specific id number (for example, LLVM IR uses an ID of 12 to represent function bodies). Block IDs 0-7 are reserved for <a href="#stdblocks">standard blocks</a> whose meaning is defined by Bitcode; block IDs 8 and greater are -application specific. Nested blocks capture the hierachical structure of the data +application specific. Nested blocks capture the hierarchical structure of the data encoded in it, and various properties are associated with blocks as the file is parsed. Block definitions allow the reader to efficiently skip blocks in constant time if the reader wants a summary of blocks, or if it wants to @@ -462,23 +462,23 @@ emitted as their code, followed by the extra data. <p>The possible operand encodings are:</p> <ol> -<li value="1">Fixed: The field should be emitted as +<li>Fixed: The field should be emitted as a <a href="#fixedwidth">fixed-width value</a>, whose width is specified by the operand's extra data.</li> -<li value="2">VBR: The field should be emitted as +<li>VBR: The field should be emitted as a <a href="#variablewidth">variable-width value</a>, whose width is specified by the operand's extra data.</li> -<li value="3">Array: This field is an array of values. The array operand +<li>Array: This field is an array of values. The array operand has no extra data, but expects another operand to follow it which indicates the element type of the array. When reading an array in an abbreviated record, the first integer is a vbr6 that indicates the array length, followed by the encoded elements of the array. An array may only occur as the last operand of an abbreviation (except for the one final operand that gives the array's type).</li> -<li value="4">Char6: This field should be emitted as +<li>Char6: This field should be emitted as a <a href="#char6">char6-encoded value</a>. This operand type takes no extra data.</li> -<li value="5">Blob: This field is emitted as a vbr6, followed by padding to a +<li>Blob: This field is emitted as a vbr6, followed by padding to a 32-bit boundary (for alignment) and an array of 8-bit objects. The array of bytes is further followed by tail padding to ensure that its total length is a multiple of 4 bytes. This makes it very efficient for the reader to @@ -755,7 +755,7 @@ LLVM IR is defined with the following blocks: src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> -Last modified: $Date: 2009-04-27 00:21:57 +0200 (Mon, 27 Apr 2009) $ +Last modified: $Date: 2009-10-12 16:46:08 +0200 (Mon, 12 Oct 2009) $ </address> </body> </html> diff --git a/docs/Bugpoint.html b/docs/Bugpoint.html index 7b26796..c89b4c5 100644 --- a/docs/Bugpoint.html +++ b/docs/Bugpoint.html @@ -216,6 +216,17 @@ non-obvious ways. Here are some hints and tips:<p> the list of specified optimizations to be randomized and applied to the program. This process will repeat until a bug is found or the user kills <tt>bugpoint</tt>. + +<li><p><tt>bugpoint</tt> does not understand the <tt>-O</tt> option + that is used to specify optimization level to <tt>opt</tt>. You + can use e.g.</p> + +<div class="doc_code"> +<p><tt>opt -O2 -debug-pass=Arguments foo.bc -disable-output</tt></p> +</div> + + <p>to get a list of passes that are used with <tt>-O2</tt> and + then pass this list to <tt>bugpoint</tt>.</p> </ol> @@ -232,7 +243,7 @@ non-obvious ways. Here are some hints and tips:<p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2008-12-11 18:34:48 +0100 (Thu, 11 Dec 2008) $ + Last modified: $Date: 2009-10-12 20:12:47 +0200 (Mon, 12 Oct 2009) $ </address> </body> diff --git a/docs/CMake.html b/docs/CMake.html index 1f50d39..25f4710 100644 --- a/docs/CMake.html +++ b/docs/CMake.html @@ -67,7 +67,7 @@ <ol> - <li><p><a href=http://www.cmake.org/cmake/resources/software.html>Download</a> + <li><p><a href="http://www.cmake.org/cmake/resources/software.html">Download</a> and install CMake. Version 2.6.2 is the minimum required.</p> <li><p>Open a shell. Your development tools must be reachable from this @@ -180,7 +180,7 @@ </div> <p>Variables are stored on the CMake cache. This is a file - named <it>CMakeCache.txt</it> on the root of the build + named <tt>CMakeCache.txt</tt> on the root of the build directory. Do not hand-edit it.</p> <p>Variables are listed here appending its type after a colon. It is @@ -250,6 +250,12 @@ to <i>X86</i>. On the other cases defaults to <i>all</i>. Example: <i>-DLLVM_TARGETS_TO_BUILD="X86;PowerPC;Alpha"</i>.</dd> + <dt><b>LLVM_BUILD_TOOLS</b>:BOOL</dt> + <dd>Build LLVM tools. Defaults to ON.</dd> + + <dt><b>LLVM_BUILD_EXAMPLES</b>:BOOL</dt> + <dd>Build LLVM examples. Defaults to ON.</dd> + <dt><b>LLVM_ENABLE_THREADS</b>:BOOL</dt> <dd>Build with threads support, if available. Defaults to ON.</dd> @@ -258,18 +264,21 @@ CMAKE_BUILD_TYPE is <i>Release</i>.</dd> <dt><b>LLVM_ENABLE_PIC</b>:BOOL</dt> - <dd>Add the <i>-fPIC</i> flag to the compiler command-line, if the - compiler supports this flag. Some systems, like Windows, does not - need this flag. Defaults to OFF.</dd> + <dd>Add the <i>-fPIC</i> flag for the compiler command-line, if the + compiler supports this flag. Some systems, like Windows, do not + need this flag. Defaults to ON.</dd> <dt><b>LLVM_BUILD_32_BITS</b>:BOOL</dt> <dd>Build 32-bits executables and libraries on 64-bits systems. This option is available only on some 64-bits unix systems. Defaults to OFF.</dd> - <dt><b>LLVM_PLO_FLAGS</b>:STRING</dt> - <dd>Extra flags for creating partially linked objects. Visual C++ - does not use this.</dd> + <dt><b>LLVM_TARGET_ARCH</b>:STRING</dt> + <dd>LLVM target to use for native code generation. This is required + for JIT generation. It defaults to "host", meaning that it shall + pick the architecture of the machine where LLVM is being built. If + you are cross-compiling, set it to the target architecture + name.</dd> <dt><b>LLVM_TABLEGEN</b>:STRING</dt> <dd>Full path to a native TableGen executable (usually @@ -309,6 +318,9 @@ <a href="http://www.vtk.org/Wiki/CMake_Cross_Compiling#Information_how_to_set_up_various_cross_compiling_toolchains">this section</a> for a quick solution.</p> +<p>Also see the <a href="#llvmvars">LLVM-specific variables</a> + section for variables used when cross-compiling.</p> + </div> <!-- *********************************************************************** --> @@ -337,26 +349,6 @@ </div> -<!-- ======================================================================= --> -<div class="doc_subsection"> - <a name="msvc">Microsoft Visual C++</a> -</div> - -<div class="doc_text"> - - <p>For linking the JIT into your executable, add</p> - - <div class="doc_code"> - <p><tt>/INCLUDE:_X86TargetMachineModule</tt></p> - </div> - - <p>to your linker options. This is required for adding the relevant - LLVM object code to the executable. Not doing this will result on - some methods returning NULL (<i>ExecutionEngine::create</i>, for - instance).</p> - -</div> - <!-- *********************************************************************** --> <hr> diff --git a/docs/CodeGenerator.html b/docs/CodeGenerator.html index 25101fc..d39de19 100644 --- a/docs/CodeGenerator.html +++ b/docs/CodeGenerator.html @@ -1380,9 +1380,9 @@ bool RegMapping_Fer::compatible_class(MachineFunction &mf, for <tt>RegisterClass</tt>, the last parameter of which is a list of registers. Just commenting some out is one simple way to avoid them being used. A more polite way is to explicitly exclude some registers from - the <i>allocation order</i>. See the definition of the <tt>GR</tt> register - class in <tt>lib/Target/IA64/IA64RegisterInfo.td</tt> for an example of this - (e.g., <tt>numReservedRegs</tt> registers are hidden.)</p> + the <i>allocation order</i>. See the definition of the <tt>GR8</tt> register + class in <tt>lib/Target/X86/X86RegisterInfo.td</tt> for an example of this. + </p> <p>Virtual registers are also denoted by integer numbers. Contrary to physical registers, different virtual registers never share the same number. The @@ -1616,9 +1616,9 @@ bool RegMapping_Fer::compatible_class(MachineFunction &mf, <div class="doc_code"> <pre> -$ llc -f -regalloc=simple file.bc -o sp.s; -$ llc -f -regalloc=local file.bc -o lc.s; -$ llc -f -regalloc=linearscan file.bc -o ln.s; +$ llc -regalloc=simple file.bc -o sp.s; +$ llc -regalloc=local file.bc -o lc.s; +$ llc -regalloc=linearscan file.bc -o ln.s; </pre> </div> @@ -1812,24 +1812,27 @@ define fastcc i32 @tailcaller(i32 %in1, i32 %in2) { <div class="doc_code"> <pre> -Base + [1,2,4,8] * IndexReg + Disp32 +SegmentReg: Base + [1,2,4,8] * IndexReg + Disp32 </pre> </div> -<p>In order to represent this, LLVM tracks no less than 4 operands for each +<p>In order to represent this, LLVM tracks no less than 5 operands for each memory operand of this form. This means that the "load" form of '<tt>mov</tt>' has the following <tt>MachineOperand</tt>s in this order:</p> <div class="doc_code"> <pre> -Index: 0 | 1 2 3 4 -Meaning: DestReg, | BaseReg, Scale, IndexReg, Displacement -OperandTy: VirtReg, | VirtReg, UnsImm, VirtReg, SignExtImm +Index: 0 | 1 2 3 4 5 +Meaning: DestReg, | BaseReg, Scale, IndexReg, Displacement Segment +OperandTy: VirtReg, | VirtReg, UnsImm, VirtReg, SignExtImm PhysReg </pre> </div> <p>Stores, and all other instructions, treat the four memory operands in the - same way and in the same order.</p> + same way and in the same order. If the segment register is unspecified + (regno = 0), then no segment override is generated. "Lea" operations do not + have a segment register specified, so they only have 4 operands for their + memory reference.</p> </div> @@ -2118,7 +2121,7 @@ MOVSX32rm16 -> movsx, 32-bit register, 16-bit memory <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-06-15 12:17:44 +0000 (Mon, 15 Jun 2009) $ + Last modified: $Date: 2009-10-10 23:30:55 +0200 (Sat, 10 Oct 2009) $ </address> </body> diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html index cf91110..f93e1ea 100644 --- a/docs/CodingStandards.html +++ b/docs/CodingStandards.html @@ -41,8 +41,12 @@ <li><a href="#hl_dontinclude">#include as Little as Possible</a></li> <li><a href="#hl_privateheaders">Keep "internal" Headers Private</a></li> - <li><a href="#ll_iostream"><tt>#include <iostream></tt> is - <em>forbidden</em></a></li> + <li><a href="#hl_earlyexit">Use Early Exits and 'continue' to Simplify + Code</a></li> + <li><a href="#hl_else_after_return">Don't use "else" after a + return</a></li> + <li><a href="#hl_predicateloops">Turn Predicate Loops into Predicate + Functions</a></li> </ol></li> <li><a href="#micro">The Low Level Issues</a> <ol> @@ -52,16 +56,27 @@ classes in headers</a></li> <li><a href="#ll_end">Don't evaluate end() every time through a loop</a></li> - <li><a href="#ll_preincrement">Prefer Preincrement</a></li> + <li><a href="#ll_iostream"><tt>#include <iostream></tt> is + <em>forbidden</em></a></li> <li><a href="#ll_avoidendl">Avoid <tt>std::endl</tt></a></li> + <li><a href="#ll_raw_ostream">Use <tt>raw_ostream</tt></a</li> </ol></li> + + <li><a href="#nano">Microscopic Details</a> + <ol> + <li><a href="#micro_spaceparen">Spaces Before Parentheses</a></li> + <li><a href="#micro_preincrement">Prefer Preincrement</a></li> + <li><a href="#micro_namespaceindent">Namespace Indentation</a></li> + <li><a href="#micro_anonns">Anonymous Namespaces</a></li> + </ol></li> + + </ol></li> <li><a href="#seealso">See Also</a></li> </ol> <div class="doc_author"> - <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and - <a href="mailto:void@nondot.org">Bill Wendling</a></p> + <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></p> </div> @@ -118,7 +133,9 @@ href="mailto:sabre@nondot.org">Chris</a>.</p> <div class="doc_text"> <p>Comments are one critical part of readability and maintainability. Everyone -knows they should comment, so should you. Although we all should probably +knows they should comment, so should you. When writing comments, write them as +English prose, which means they should use proper capitalization, punctuation, +etc. Although we all should probably comment our code more than we do, there are a few very critical places that documentation is very useful:</p> @@ -286,7 +303,7 @@ for debate.</p> <div class="doc_text"> <p>In all cases, prefer spaces to tabs in source files. People have different -prefered indentation levels, and different styles of indentation that they +preferred indentation levels, and different styles of indentation that they like... this is fine. What isn't is that different editors/viewers expand tabs out to different tab stops. This can cause your code to look completely unreadable, and it is not worth dealing with.</p> @@ -402,7 +419,8 @@ different symbols based on whether <tt>class</tt> or <tt>struct</tt> was used to declare the symbol. This can lead to problems at link time.</p> <p>So, the rule for LLVM is to always use the <tt>class</tt> keyword, unless -<b>all</b> members are public, in which case <tt>struct</tt> is allowed.</p> +<b>all</b> members are public and the type is a C++ "POD" type, in which case +<tt>struct</tt> is allowed.</p> </div> @@ -417,6 +435,7 @@ declare the symbol. This can lead to problems at link time.</p> <div class="doc_subsection"> <a name="macro">The High Level Issues</a> </div> +<!-- ======================================================================= --> <!-- _______________________________________________________________________ --> @@ -472,7 +491,7 @@ most cases, you simply don't need the definition of a class... and not <b>must</b> include all of the header files that you are using -- you can include them either directly or indirectly (through another header file). To make sure that you don't -accidently forget to include a header file in your module header, make sure to +accidentally forget to include a header file in your module header, make sure to include your module header <b>first</b> in the implementation file (as mentioned above). This way there won't be any hidden dependencies that you'll find out about later...</p> @@ -502,34 +521,256 @@ class itself... just make them private (or protected), and all is well.</p> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> - <a name="ll_iostream"><tt>#include <iostream></tt> is forbidden</a> + <a name="hl_earlyexit">Use Early Exits and 'continue' to Simplify Code</a> </div> <div class="doc_text"> -<p>The use of <tt>#include <iostream></tt> in library files is -hereby <b><em>forbidden</em></b>. The primary reason for doing this is to -support clients using LLVM libraries as part of larger systems. In particular, -we statically link LLVM into some dynamic libraries. Even if LLVM isn't used, -the static c'tors are run whenever an application start up that uses the dynamic -library. There are two problems with this:</p> +<p>When reading code, keep in mind how much state and how many previous +decisions have to be remembered by the reader to understand a block of code. +Aim to reduce indentation where possible when it doesn't make it more difficult +to understand the code. One great way to do this is by making use of early +exits and the 'continue' keyword in long loops. As an example of using an early +exit from a function, consider this "bad" code:</p> -<ol> - <li>The time to run the static c'tors impacts startup time of - applications—a critical time for GUI apps.</li> - <li>The static c'tors cause the app to pull many extra pages of memory off the - disk: both the code for the static c'tors in each <tt>.o</tt> file and the - small amount of data that gets touched. In addition, touched/dirty pages - put more pressure on the VM system on low-memory machines.</li> -</ol> +<div class="doc_code"> +<pre> +Value *DoSomething(Instruction *I) { + if (!isa<TerminatorInst>(I) && + I->hasOneUse() && SomeOtherThing(I)) { + ... some long code .... + } + + return 0; +} +</pre> +</div> -<p>Note that using the other stream headers (<tt><sstream></tt> for -example) is allowed normally, it is just <tt><iostream></tt> that is -causing problems.</p> +<p>This code has several problems if the body of the 'if' is large. When you're +looking at the top of the function, it isn't immediately clear that this +<em>only</em> does interesting things with non-terminator instructions, and only +applies to things with the other predicates. Second, it is relatively difficult +to describe (in comments) why these predicates are important because the if +statement makes it difficult to lay out the comments. Third, when you're deep +within the body of the code, it is indented an extra level. Finally, when +reading the top of the function, it isn't clear what the result is if the +predicate isn't true, you have to read to the end of the function to know that +it returns null.</p> + +<p>It is much preferred to format the code like this:</p> + +<div class="doc_code"> +<pre> +Value *DoSomething(Instruction *I) { + // Terminators never need 'something' done to them because, ... + if (isa<TerminatorInst>(I)) + return 0; + + // We conservatively avoid transforming instructions with multiple uses + // because goats like cheese. + if (!I->hasOneUse()) + return 0; + + // This is really just here for example. + if (!SomeOtherThing(I)) + return 0; + + ... some long code .... +} +</pre> +</div> + +<p>This fixes these problems. A similar problem frequently happens in for +loops. A silly example is something like this:</p> + +<div class="doc_code"> +<pre> + for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E; ++II) { + if (BinaryOperator *BO = dyn_cast<BinaryOperator>(II)) { + Value *LHS = BO->getOperand(0); + Value *RHS = BO->getOperand(1); + if (LHS != RHS) { + ... + } + } + } +</pre> +</div> -<p>The preferred replacement for stream functionality is the -<tt>llvm::raw_ostream</tt> class (for writing to output streams of various -sorts) and the <tt>llvm::MemoryBuffer</tt> API (for reading in files).</p> +<p>When you have very very small loops, this sort of structure is fine, but if +it exceeds more than 10-15 lines, it becomes difficult for people to read and +understand at a glance. +The problem with this sort of code is that it gets very nested very quickly, +meaning that the reader of the code has to keep a lot of context in their brain +to remember what is going immediately on in the loop, because they don't know +if/when the if conditions will have elses etc. It is strongly preferred to +structure the loop like this:</p> + +<div class="doc_code"> +<pre> + for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E; ++II) { + BinaryOperator *BO = dyn_cast<BinaryOperator>(II); + if (!BO) continue; + + Value *LHS = BO->getOperand(0); + Value *RHS = BO->getOperand(1); + if (LHS == RHS) continue; + } +</pre> +</div> + +<p>This has all the benefits of using early exits from functions: it reduces +nesting of the loop, it makes it easier to describe why the conditions are true, +and it makes it obvious to the reader that there is no "else" coming up that +they have to push context into their brain for. If a loop is large, this can +be a big understandability win.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="hl_else_after_return">Don't use "else" after a return</a> +</div> + +<div class="doc_text"> + +<p>For similar reasons above (reduction of indentation and easier reading), + please do not use "else" or "else if" after something that interrupts + control flow like return, break, continue, goto, etc. For example, this is + "bad":</p> + +<div class="doc_code"> +<pre> + case 'J': { + if (Signed) { + Type = Context.getsigjmp_bufType(); + if (Type.isNull()) { + Error = ASTContext::GE_Missing_sigjmp_buf; + return QualType(); + } else { + break; + } + } else { + Type = Context.getjmp_bufType(); + if (Type.isNull()) { + Error = ASTContext::GE_Missing_jmp_buf; + return QualType(); + } else { + break; + } + } + } + } +</pre> +</div> + +<p>It is better to write this something like:</p> + +<div class="doc_code"> +<pre> + case 'J': + if (Signed) { + Type = Context.getsigjmp_bufType(); + if (Type.isNull()) { + Error = ASTContext::GE_Missing_sigjmp_buf; + return QualType(); + } + } else { + Type = Context.getjmp_bufType(); + if (Type.isNull()) { + Error = ASTContext::GE_Missing_jmp_buf; + return QualType(); + } + } + break; +</pre> +</div> + +<p>Or better yet (in this case), as:</p> + +<div class="doc_code"> +<pre> + case 'J': + if (Signed) + Type = Context.getsigjmp_bufType(); + else + Type = Context.getjmp_bufType(); + + if (Type.isNull()) { + Error = Signed ? ASTContext::GE_Missing_sigjmp_buf : + ASTContext::GE_Missing_jmp_buf; + return QualType(); + } + break; +</pre> +</div> + +<p>The idea is to reduce indentation and the amount of code you have to keep + track of when reading the code.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="hl_predicateloops">Turn Predicate Loops into Predicate Functions</a> +</div> + +<div class="doc_text"> + +<p>It is very common to write small loops that just compute a boolean + value. There are a number of ways that people commonly write these, but an + example of this sort of thing is:</p> + +<div class="doc_code"> +<pre> + <b>bool FoundFoo = false;</b> + for (unsigned i = 0, e = BarList.size(); i != e; ++i) + if (BarList[i]->isFoo()) { + <b>FoundFoo = true;</b> + break; + } + + <b>if (FoundFoo) {</b> + ... + } +</pre> +</div> + +<p>This sort of code is awkward to write, and is almost always a bad sign. +Instead of this sort of loop, we strongly prefer to use a predicate function +(which may be <a href="#micro_anonns">static</a>) that uses +<a href="#hl_earlyexit">early exits</a> to compute the predicate. We prefer +the code to be structured like this: +</p> + + +<div class="doc_code"> +<pre> +/// ListContainsFoo - Return true if the specified list has an element that is +/// a foo. +static bool ListContainsFoo(const std::vector<Bar*> &List) { + for (unsigned i = 0, e = List.size(); i != e; ++i) + if (List[i]->isFoo()) + return true; + return false; +} +... + + <b>if (ListContainsFoo(BarList)) {</b> + ... + } +</pre> +</div> + +<p>There are many reasons for doing this: it reduces indentation and factors out +code which can often be shared by other code that checks for the same predicate. +More importantly, it <em>forces you to pick a name</em> for the function, and +forces you to write a comment for it. In this silly example, this doesn't add +much value. However, if the condition is complex, this can make it a lot easier +for the reader to understand the code that queries for this predicate. Instead +of being faced with the in-line details of how we check to see if the BarList +contains a foo, we can trust the function name and continue reading with better +locality.</p> </div> @@ -538,6 +779,7 @@ sorts) and the <tt>llvm::MemoryBuffer</tt> API (for reading in files).</p> <div class="doc_subsection"> <a name="micro">The Low Level Issues</a> </div> +<!-- ======================================================================= --> <!-- _______________________________________________________________________ --> @@ -548,7 +790,7 @@ sorts) and the <tt>llvm::MemoryBuffer</tt> API (for reading in files).</p> <div class="doc_text"> <p>Use the "<tt>assert</tt>" function to its fullest. Check all of your -preconditions and assumptions, you never know when a bug (not neccesarily even +preconditions and assumptions, you never know when a bug (not necessarily even yours) might be caught early by an assertion, which reduces debugging time dramatically. The "<tt><cassert></tt>" header file is probably already included by the header files you are using, so it doesn't cost anything to use @@ -724,10 +966,156 @@ prefer it.</p> </div> +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="ll_iostream"><tt>#include <iostream></tt> is forbidden</a> +</div> + +<div class="doc_text"> + +<p>The use of <tt>#include <iostream></tt> in library files is +hereby <b><em>forbidden</em></b>. The primary reason for doing this is to +support clients using LLVM libraries as part of larger systems. In particular, +we statically link LLVM into some dynamic libraries. Even if LLVM isn't used, +the static c'tors are run whenever an application start up that uses the dynamic +library. There are two problems with this:</p> + +<ol> + <li>The time to run the static c'tors impacts startup time of + applications—a critical time for GUI apps.</li> + <li>The static c'tors cause the app to pull many extra pages of memory off the + disk: both the code for the static c'tors in each <tt>.o</tt> file and the + small amount of data that gets touched. In addition, touched/dirty pages + put more pressure on the VM system on low-memory machines.</li> +</ol> + +<p>Note that using the other stream headers (<tt><sstream></tt> for +example) is not problematic in this regard (just <tt><iostream></tt>). +However, raw_ostream provides various APIs that are better performing for almost +every use than std::ostream style APIs, so you should just use it for new +code.</p> + +<p><b>New code should always +use <a href="#ll_raw_ostream"><tt>raw_ostream</tt></a> for writing, or +the <tt>llvm::MemoryBuffer</tt> API for reading files.</b></p> + +</div> + + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="ll_avoidendl">Avoid <tt>std::endl</tt></a> +</div> + +<div class="doc_text"> + +<p>The <tt>std::endl</tt> modifier, when used with iostreams outputs a newline +to the output stream specified. In addition to doing this, however, it also +flushes the output stream. In other words, these are equivalent:</p> + +<div class="doc_code"> +<pre> +std::cout << std::endl; +std::cout << '\n' << std::flush; +</pre> +</div> + +<p>Most of the time, you probably have no reason to flush the output stream, so +it's better to use a literal <tt>'\n'</tt>.</p> + +</div> + + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="ll_raw_ostream">Use <tt>raw_ostream</tt></a> +</div> + +<div class="doc_text"> + +<p>LLVM includes a lightweight, simple, and efficient stream implementation +in <tt>llvm/Support/raw_ostream.h</tt> which provides all of the common features +of <tt>std::ostream</tt>. All new code should use <tt>raw_ostream</tt> instead +of <tt>ostream</tt>.</p> + +<p>Unlike <tt>std::ostream</tt>, <tt>raw_ostream</tt> is not a template and can +be forward declared as <tt>class raw_ostream</tt>. Public headers should +generally not include the <tt>raw_ostream</tt> header, but use forward +declarations and constant references to <tt>raw_ostream</tt> instances.</p> + +</div> + + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="nano">Microscopic Details</a> +</div> +<!-- ======================================================================= --> + +<p>This section describes preferred low-level formatting guidelines along with +reasoning on why we prefer them.</p> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="micro_spaceparen">Spaces Before Parentheses</a> +</div> + +<div class="doc_text"> + +<p>We prefer to put a space before a parentheses only in control flow +statements, but not in normal function call expressions and function-like +macros. For example, this is good:</p> + +<div class="doc_code"> +<pre> + <b>if (</b>x) ... + <b>for (</b>i = 0; i != 100; ++i) ... + <b>while (</b>llvm_rocks) ... + + <b>somefunc(</b>42); + <b><a href="#ll_assert">assert</a>(</b>3 != 4 && "laws of math are failing me"); + + a = <b>foo(</b>42, 92) + <b>bar(</b>x); + </pre> +</div> + +<p>... and this is bad:</p> + +<div class="doc_code"> +<pre> + <b>if(</b>x) ... + <b>for(</b>i = 0; i != 100; ++i) ... + <b>while(</b>llvm_rocks) ... + + <b>somefunc (</b>42); + <b><a href="#ll_assert">assert</a> (</b>3 != 4 && "laws of math are failing me"); + + a = <b>foo (</b>42, 92) + <b>bar (</b>x); +</pre> +</div> + +<p>The reason for doing this is not completely arbitrary. This style makes + control flow operators stand out more, and makes expressions flow better. The + function call operator binds very tightly as a postfix operator. Putting + a space after a function name (as in the last example) makes it appear that + the code might bind the arguments of the left-hand-side of a binary operator + with the argument list of a function and the name of the right side. More + specifically, it is easy to misread the "a" example as:</p> + +<div class="doc_code"> +<pre> + a = foo <b>(</b>(42, 92) + bar<b>)</b> (x); +</pre> +</div> + +<p>... when skimming through the code. By avoiding a space in a function, we +avoid this misinterpretation.</p> + +</div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> - <a name="ll_preincrement">Prefer Preincrement</a> + <a name="micro_preincrement">Prefer Preincrement</a> </div> <div class="doc_text"> @@ -747,27 +1135,178 @@ get in the habit of always using preincrement, and you won't have a problem.</p> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> - <a name="ll_avoidendl">Avoid <tt>std::endl</tt></a> + <a name="micro_namespaceindent">Namespace Indentation</a> </div> <div class="doc_text"> -<p>The <tt>std::endl</tt> modifier, when used with iostreams outputs a newline -to the output stream specified. In addition to doing this, however, it also -flushes the output stream. In other words, these are equivalent:</p> +<p> +In general, we strive to reduce indentation where ever possible. This is useful +because we want code to <a href="#scf_codewidth">fit into 80 columns</a> without +wrapping horribly, but also because it makes it easier to understand the code. +Namespaces are a funny thing: they are often large, and we often desire to put +lots of stuff into them (so they can be large). Other times they are tiny, +because they just hold an enum or something similar. In order to balance this, +we use different approaches for small versus large namespaces. +</p> + +<p> +If a namespace definition is small and <em>easily</em> fits on a screen (say, +less than 35 lines of code), then you should indent its body. Here's an +example: +</p> <div class="doc_code"> <pre> -std::cout << std::endl; -std::cout << '\n' << std::flush; +namespace llvm { + namespace X86 { + /// RelocationType - An enum for the x86 relocation codes. Note that + /// the terminology here doesn't follow x86 convention - word means + /// 32-bit and dword means 64-bit. + enum RelocationType { + /// reloc_pcrel_word - PC relative relocation, add the relocated value to + /// the value already in memory, after we adjust it for where the PC is. + reloc_pcrel_word = 0, + + /// reloc_picrel_word - PIC base relative relocation, add the relocated + /// value to the value already in memory, after we adjust it for where the + /// PIC base is. + reloc_picrel_word = 1, + + /// reloc_absolute_word, reloc_absolute_dword - Absolute relocation, just + /// add the relocated value to the value already in memory. + reloc_absolute_word = 2, + reloc_absolute_dword = 3 + }; + } +} </pre> </div> -<p>Most of the time, you probably have no reason to flush the output stream, so -it's better to use a literal <tt>'\n'</tt>.</p> +<p>Since the body is small, indenting adds value because it makes it very clear +where the namespace starts and ends, and it is easy to take the whole thing in +in one "gulp" when reading the code. If the blob of code in the namespace is +larger (as it typically is in a header in the llvm or clang namespaces), do not +indent the code, and add a comment indicating what namespace is being closed. +For example:</p> +<div class="doc_code"> +<pre> +namespace llvm { +namespace knowledge { + +/// Grokable - This class represents things that Smith can have an intimate +/// understanding of and contains the data associated with it. +class Grokable { +... +public: + explicit Grokable() { ... } + virtual ~Grokable() = 0; + + ... + +}; + +} // end namespace knowledge +} // end namespace llvm +</pre> </div> +<p>Because the class is large, we don't expect that the reader can easily +understand the entire concept in a glance, and the end of the file (where the +namespaces end) may be a long ways away from the place they open. As such, +indenting the contents of the namespace doesn't add any value, and detracts from +the readability of the class. In these cases it is best to <em>not</em> indent +the contents of the namespace.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="micro_anonns">Anonymous Namespaces</a> +</div> + +<div class="doc_text"> + +<p>After talking about namespaces in general, you may be wondering about +anonymous namespaces in particular. +Anonymous namespaces are a great language feature that tells the C++ compiler +that the contents of the namespace are only visible within the current +translation unit, allowing more aggressive optimization and eliminating the +possibility of symbol name collisions. Anonymous namespaces are to C++ as +"static" is to C functions and global variables. While "static" is available +in C++, anonymous namespaces are more general: they can make entire classes +private to a file.</p> + +<p>The problem with anonymous namespaces is that they naturally want to +encourage indentation of their body, and they reduce locality of reference: if +you see a random function definition in a C++ file, it is easy to see if it is +marked static, but seeing if it is in an anonymous namespace requires scanning +a big chunk of the file.</p> + +<p>Because of this, we have a simple guideline: make anonymous namespaces as +small as possible, and only use them for class declarations. For example, this +is good:</p> + +<div class="doc_code"> +<pre> +<b>namespace {</b> + class StringSort { + ... + public: + StringSort(...) + bool operator<(const char *RHS) const; + }; +<b>} // end anonymous namespace</b> + +static void Helper() { + ... +} + +bool StringSort::operator<(const char *RHS) const { + ... +} + +</pre> +</div> + +<p>This is bad:</p> + + +<div class="doc_code"> +<pre> +<b>namespace {</b> +class StringSort { +... +public: + StringSort(...) + bool operator<(const char *RHS) const; +}; + +void Helper() { + ... +} + +bool StringSort::operator<(const char *RHS) const { + ... +} + +<b>} // end anonymous namespace</b> + +</pre> +</div> + + +<p>This is bad specifically because if you're looking at "Helper" in the middle +of a large C++ file, that you have no immediate way to tell if it is local to +the file. When it is marked static explicitly, this is immediately obvious. +Also, there is no reason to enclose the definition of "operator<" in the +namespace just because it was declared there. +</p> + +</div> + + <!-- *********************************************************************** --> <div class="doc_section"> @@ -807,7 +1346,7 @@ something.</p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-06-30 08:27:54 +0200 (Tue, 30 Jun 2009) $ + Last modified: $Date: 2009-10-12 16:46:08 +0200 (Mon, 12 Oct 2009) $ </address> </body> diff --git a/docs/CommandGuide/FileCheck.pod b/docs/CommandGuide/FileCheck.pod new file mode 100644 index 0000000..539f66f --- /dev/null +++ b/docs/CommandGuide/FileCheck.pod @@ -0,0 +1,65 @@ + +=pod + +=head1 NAME + +FileCheck - Flexible pattern matching file verifier + +=head1 SYNOPSIS + +B<FileCheck> I<match-filename> [I<--check-prefix=XXX>] [I<--strict-whitespace>] + +=head1 DESCRIPTION + +B<FileCheck> reads two files (one from standard input, and one specified on the +command line) and uses one to verify the other. This behavior is particularly +useful for the testsuite, which wants to verify that the output of some tool +(e.g. llc) contains the expected information (for example, a movsd from esp or +whatever is interesting). This is similar to using grep, but it is optimized +for matching multiple different inputs in one file in a specific order. + +The I<match-filename> file specifies the file that contains the patterns to +match. The file to verify is always read from standard input. + +The input and output of B<FileCheck> is beyond the scope of this short +introduction. Please see the I<TestingGuide> page in the LLVM documentation. + +=head1 OPTIONS + +=over + +=item B<--help> + +Print a summary of command line options. + +=item B<--check-prefix> I<prefix> + +FileCheck searches the contents of I<match-filename> for patterns to match. By +default, these patterns are prefixed with "CHECK:". If you'd like to use a +different prefix (e.g. because the same input file is checking multiple +different tool or options), the B<--check-prefix> argument allows you to specify +a specific prefix to match. + +=item B<--strict-whitespace> + +By default, FileCheck canonicalizes input horizontal whitespace (spaces and +tabs) which causes it to ignore these differences (a space will match a tab). +The --strict-whitespace argument disables this behavior. + +=item B<-version> + +Show the version number of this program. + +=back + +=head1 EXIT STATUS + +If B<FileCheck> verifies that the file matches the expected contents, it exits +with 0. Otherwise, if not, or if an error occurs, it will exit with a non-zero +value. + +=head1 AUTHORS + +Maintained by The LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/CommandGuide/Makefile b/docs/CommandGuide/Makefile index cf77e6a..3b65183 100644 --- a/docs/CommandGuide/Makefile +++ b/docs/CommandGuide/Makefile @@ -48,6 +48,12 @@ HTML := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_HTML_DIR)%.html, $(POD)) MAN := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_MAN_DIR)%.1, $(POD)) PS := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_PS_DIR)%.ps, $(POD)) +# The set of man pages we will not install +NO_INSTALL_MANS = $(DST_MAN_DIR)FileCheck.1 + +# The set of man pages that we will install +INSTALL_MANS = $(filter-out $(NO_INSTALL_MANS), $(MAN)) + .SUFFIXES: .SUFFIXES: .html .pod .1 .ps @@ -75,7 +81,7 @@ HTML_DIR := $(PROJ_docsdir)/html/CommandGuide MAN_DIR := $(PROJ_mandir)/man1 PS_DIR := $(PROJ_docsdir)/ps -install-local:: $(HTML) $(MAN) $(PS) +install-local:: $(HTML) $(INSTALL_MANS) $(PS) $(Echo) Installing HTML CommandGuide Documentation $(Verb) $(MKDIR) $(HTML_DIR) $(Verb) $(DataInstall) $(HTML) $(HTML_DIR) @@ -83,7 +89,7 @@ install-local:: $(HTML) $(MAN) $(PS) $(Verb) $(DataInstall) $(PROJ_SRC_DIR)/manpage.css $(HTML_DIR) $(Echo) Installing MAN CommandGuide Documentation $(Verb) $(MKDIR) $(MAN_DIR) - $(Verb) $(DataInstall) $(MAN) $(MAN_DIR) + $(Verb) $(DataInstall) $(INSTALL_MANS) $(MAN_DIR) $(Echo) Installing PS CommandGuide Documentation $(Verb) $(MKDIR) $(PS_DIR) $(Verb) $(DataInstall) $(PS) $(PS_DIR) diff --git a/docs/CommandGuide/index.html b/docs/CommandGuide/index.html index f05260b..f1046fa 100644 --- a/docs/CommandGuide/index.html +++ b/docs/CommandGuide/index.html @@ -128,6 +128,8 @@ options) arguments to the tool you are interested in.</p> <div class="doc_text"> <ul> +<li><a href="/cmds/FileCheck.html"><b>FileCheck</b></a> - + Flexible file verifier used extensively by the testing harness</li> <li><a href="/cmds/tblgen.html"><b>tblgen</b></a> - target description reader and generator</li> @@ -144,7 +146,7 @@ options) arguments to the tool you are interested in.</p> src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2008-12-11 18:12:52 +0100 (Thu, 11 Dec 2008) $ + Last modified: $Date: 2009-08-15 17:38:11 +0200 (Sat, 15 Aug 2009) $ </address> </body> diff --git a/docs/CommandGuide/lit.pod b/docs/CommandGuide/lit.pod new file mode 100644 index 0000000..a818302 --- /dev/null +++ b/docs/CommandGuide/lit.pod @@ -0,0 +1,222 @@ +=pod + +=head1 NAME + +lit - LLVM Integrated Tester + +=head1 SYNOPSIS + +B<lit> [I<options>] [I<tests>] + +=head1 DESCRIPTION + +B<lit> is a portable tool for executing LLVM and Clang style test suites, +summarizing their results, and providing indication of failures. B<lit> is +designed to be a lightweight testing tool with as simple a user interface as +possible. + +B<lit> should be run with one or more I<tests> to run specified on the command +line. Tests can be either individual test files or directories to search for +tests (see L<"TEST DISCOVERY">). + +Each specified test will be executed (potentially in parallel) and once all +tests have been run B<lit> will print summary information on the number of tests +which passed or failed (see L<"TEST STATUS RESULTS">). The B<lit> program will +execute with a non-zero exit code if any tests fail. + +By default B<lit> will use a succinct progress display and will only print +summary information for test failures. See L<"OUTPUT OPTIONS"> for options +controlling the B<lit> progress display and output. + +B<lit> also includes a number of options for controlling how tests are exected +(specific features may depend on the particular test format). See L<"EXECUTION +OPTIONS"> for more information. + +Finally, B<lit> also supports additional options for only running a subset of +the options specified on the command line, see L<"SELECTION OPTIONS"> for +more information. + +=head1 GENERAL OPTIONS + +=over + +=item B<-h>, B<--help> + +Show the B<lit> help message. + +=item B<-j> I<N>, B<--threads>=I<N> + +Run I<N> tests in parallel. By default, this is automatically chose to match the +number of detected available CPUs. + +=back + +=head1 OUTPUT OPTIONS + +=over + +=item B<-q>, B<--quiet> + +Suppress any output except for test failures. + +=item B<-s>, B<--succinct> + +Show less output, for example don't show information on tests that pass. + +=item B<-v>, B<--verbose> + +Show more information on test failures, for example the entire test output +instead of just the test result. + +=item B<--no-progress-bar> + +Do not use curses based progress bar. + +=back + +=head1 EXECUTION OPTIONS + +=over + +=item B<--path>=I<PATH> + +Specify an addition I<PATH> to use when searching for executables in tests. + +=item B<--vg> + +Run individual tests under valgrind (using the memcheck tool). The +I<--error-exitcode> argument for valgrind is used so that valgrind failures will +cause the program to exit with a non-zero status. + +=item B<--vg-arg>=I<ARG> + +When I<--vg> is used, specify an additional argument to pass to valgrind itself. + +=item B<--time-tests> + +Track the wall time individual tests take to execute and includes the results in +the summary output. This is useful for determining which tests in a test suite +take the most time to execute. Note that this option is most useful with I<-j +1>. + +=back + +=head1 SELECTION OPTIONS + +=over + +=item B<--max-tests>=I<N> + +Run at most I<N> tests and then terminate. + +=item B<--max-time>=I<N> + +Spend at most I<N> seconds (approximately) running tests and then terminate. + +=item B<--shuffle> + +Run the tests in a random order. + +=back + +=head1 ADDITIONAL OPTIONS + +=over + +=item B<--debug> + +Run B<lit> in debug mode, for debugging configuration issues and B<lit> itself. + +=item B<--show-suites> + +List the discovered test suites as part of the standard output. + +=item B<--no-tcl-as-sh> + +Run Tcl scripts internally (instead of converting to shell scripts). + +=back + +=head1 EXIT STATUS + +B<lit> will exit with an exit code of 1 if there are any FAIL or XPASS +results. Otherwise, it will exit with the status 0. Other exit codes used for +non-test related failures (for example a user error or an internal program +error). + +=head1 TEST DISCOVERY + +The inputs passed to B<lit> can be either individual tests, or entire +directories or hierarchies of tests to run. When B<lit> starts up, the first +thing it does is convert the inputs into a complete list of tests to run as part +of I<test discovery>. + +In the B<lit> model, every test must exist inside some I<test suite>. B<lit> +resolves the inputs specified on the command line to test suites by searching +upwards from the input path until it finds a I<lit.cfg> or I<lit.site.cfg> +file. These files serve as both a marker of test suites and as configuration +files which B<lit> loads in order to understand how to find and run the tests +inside the test suite. + +Once B<lit> has mapped the inputs into test suites it traverses the list of +inputs adding tests for individual files and recursively searching for tests in +directories. + +This behavior makes it easy to specify a subset of tests to run, while still +allowing the test suite configuration to control exactly how tests are +interpreted. In addition, B<lit> always identifies tests by the test suite they +are in, and their relative path inside the test suite. For appropriately +configured projects, this allows B<lit> to provide convenient and flexible +support for out-of-tree builds. + +=head1 TEST STATUS RESULTS + +Each test ultimately produces one of the following six results: + +=over + +=item B<PASS> + +The test succeeded. + +=item B<XFAIL> + +The test failed, but that is expected. This is used for test formats which allow +specifying that a test does not currently work, but wish to leave it in the test +suite. + +=item B<XPASS> + +The test succeeded, but it was expected to fail. This is used for tests which +were specified as expected to fail, but are now succeeding (generally because +the feautre they test was broken and has been fixed). + +=item B<FAIL> + +The test failed. + +=item B<UNRESOLVED> + +The test result could not be determined. For example, this occurs when the test +could not be run, the test itself is invalid, or the test was interrupted. + +=item B<UNSUPPORTED> + +The test is not supported in this environment. This is used by test formats +which can report unsupported tests. + +=back + +Depending on the test format tests may produce additional information about +their status (generally only for failures). See the L<Output|"LIT OUTPUT"> +section for more information. + +=head1 SEE ALSO + +L<valgrind(1)> + +=head1 AUTHOR + +Written by Daniel Dunbar and maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/CommandGuide/llc.pod b/docs/CommandGuide/llc.pod index eba7859..8adfb68 100644 --- a/docs/CommandGuide/llc.pod +++ b/docs/CommandGuide/llc.pod @@ -10,18 +10,19 @@ B<llc> [I<options>] [I<filename>] =head1 DESCRIPTION -The B<llc> command compiles LLVM bitcode into assembly language for a +The B<llc> command compiles LLVM source inputs into assembly language for a specified architecture. The assembly language output can then be passed through a native assembler and linker to generate a native executable. The choice of architecture for the output assembly code is automatically -determined from the input bitcode file, unless the B<-march> option is used to -override the default. +determined from the input file, unless the B<-march> option is used to override +the default. =head1 OPTIONS -If I<filename> is - or omitted, B<llc> reads LLVM bitcode from standard input. -Otherwise, it will read LLVM bitcode from I<filename>. +If I<filename> is - or omitted, B<llc> reads from standard input. Otherwise, it +will from I<filename>. Inputs can be in either the LLVM assembly language +format (.ll) or the LLVM bitcode format (.bc). If the B<-o> option is omitted, then B<llc> will send its output to standard output if the input is from standard input. If the B<-o> option specifies -, @@ -47,20 +48,15 @@ Generate code at different optimization levels. These correspond to the I<-O0>, I<-O1>, I<-O2>, I<-O3>, and I<-O4> optimization levels used by B<llvm-gcc> and B<clang>. -=item B<-f> - -Overwrite output files. By default, B<llc> will refuse to overwrite -an output file which already exists. - =item B<-mtriple>=I<target triple> -Override the target triple specified in the input bitcode file with the -specified string. +Override the target triple specified in the input file with the specified +string. =item B<-march>=I<arch> Specify the architecture for which to generate assembly, overriding the target -encoded in the bitcode file. See the output of B<llc --help> for a list of +encoded in the input file. See the output of B<llc --help> for a list of valid architectures. By default this is inferred from the target triple or autodetected to the current architecture. diff --git a/docs/CommandGuide/llvm-as.pod b/docs/CommandGuide/llvm-as.pod index 2befed1..045a924 100644 --- a/docs/CommandGuide/llvm-as.pod +++ b/docs/CommandGuide/llvm-as.pod @@ -46,9 +46,9 @@ suffix is appended. =item B<-f> -Force overwrite. Normally, B<llvm-as> will refuse to overwrite an -output file that already exists. With this option, B<llvm-as> -will overwrite the output file and replace it with new bitcode. +Enable binary output on terminals. Normally, B<llvm-as> will refuse to +write raw bitcode output if the output stream is a terminal. With this option, +B<llvm-as> will write raw bitcode regardless of the output device. =item B<--help> diff --git a/docs/CommandGuide/llvm-dis.pod b/docs/CommandGuide/llvm-dis.pod index 8df382d..2b83290 100644 --- a/docs/CommandGuide/llvm-dis.pod +++ b/docs/CommandGuide/llvm-dis.pod @@ -29,9 +29,9 @@ B<-o> option. =item B<-f> -Force overwrite. Normally, B<llvm-dis> will refuse to overwrite -an output file that already exists. With this option, B<llvm-dis> -will overwrite the output file. +Enable binary output on terminals. Normally, B<llvm-dis> will refuse to +write raw bitcode output if the output stream is a terminal. With this option, +B<llvm-dis> will write raw bitcode regardless of the output device. =item B<--help> diff --git a/docs/CommandGuide/llvm-extract.pod b/docs/CommandGuide/llvm-extract.pod index d916612..b62e8ae 100644 --- a/docs/CommandGuide/llvm-extract.pod +++ b/docs/CommandGuide/llvm-extract.pod @@ -28,9 +28,9 @@ unless the B<-o> option is specified (see below). =item B<-f> -Force overwrite. Normally, B<llvm-extract> will refuse to overwrite an -output file that already exists. With this option, B<llvm-extract> -will overwrite the output file and replace it with new bitcode. +Enable binary output on terminals. Normally, B<llvm-extract> will refuse to +write raw bitcode output if the output stream is a terminal. With this option, +B<llvm-extract> will write raw bitcode regardless of the output device. =item B<--func> I<function-name> @@ -45,6 +45,10 @@ Print a summary of command line options. Specify the output filename. If filename is "-" (the default), then B<llvm-extract> sends its output to standard output. +=item B<-S> + +Write output in LLVM intermediate language (instead of bitcode). + =back =head1 EXIT STATUS diff --git a/docs/CommandGuide/llvm-ld.pod b/docs/CommandGuide/llvm-ld.pod index 224939c..536ab0f 100644 --- a/docs/CommandGuide/llvm-ld.pod +++ b/docs/CommandGuide/llvm-ld.pod @@ -104,6 +104,12 @@ should be generated by the linker. By default, B<llvm-ld> generates a file named F<a.out> for compatibility with B<ld>. The output will be written to F<filename>. +=item B<-b> F<filename> + +This option can be used to override the output bitcode file name. By default, +the name of the bitcode output file is one more ".bc" suffix added to the name +specified by B<-o filename> option. + =item B<-l>F<name> This option specifies the F<name> of a library to search when resolving symbols diff --git a/docs/CommandGuide/llvm-link.pod b/docs/CommandGuide/llvm-link.pod index 5f4dcb6..e1a1267 100644 --- a/docs/CommandGuide/llvm-link.pod +++ b/docs/CommandGuide/llvm-link.pod @@ -33,14 +33,19 @@ the order in which they were specified on the command line. =item B<-f> -Overwrite output files. By default, B<llvm-link> will not overwrite an output -file if it already exists. +Enable binary output on terminals. Normally, B<llvm-link> will refuse to +write raw bitcode output if the output stream is a terminal. With this option, +B<llvm-link> will write raw bitcode regardless of the output device. =item B<-o> F<filename> Specify the output file name. If F<filename> is C<->, then B<llvm-link> will write its output to standard output. +=item B<-S> + +Write output in LLVM intermediate language (instead of bitcode). + =item B<-d> If specified, B<llvm-link> prints a human-readable version of the output diff --git a/docs/CommandGuide/llvmc.pod b/docs/CommandGuide/llvmc.pod index 97445ed..e3031e1 100644 --- a/docs/CommandGuide/llvmc.pod +++ b/docs/CommandGuide/llvmc.pod @@ -71,6 +71,12 @@ write files into the directory specified with the I<-o> option. The I<--save-temps=cwd> and I<--save-temps> switches are both synonyms for the default behaviour. +=item B<--temp-dir> I<directory> + +Store temporary files in the given directory. This directory is deleted on exit +unless I<--save-temps> is specified. If I<--save-temps=obj> is also specified, +I<--temp-dir> is given the precedence. + =item B<--help> Print a summary of command-line options and exit. diff --git a/docs/CommandGuide/opt.pod b/docs/CommandGuide/opt.pod index 75b7edd..d1d1db5 100644 --- a/docs/CommandGuide/opt.pod +++ b/docs/CommandGuide/opt.pod @@ -11,24 +11,25 @@ B<opt> [I<options>] [I<filename>] =head1 DESCRIPTION The B<opt> command is the modular LLVM optimizer and analyzer. It takes LLVM -bitcode as input, runs the specified optimizations or analyses on it, and then -outputs the optimized LLVM bitcode or the analysis results. The function of +source files as input, runs the specified optimizations or analyses on it, and then +outputs the optimized file or the analysis results. The function of B<opt> depends on whether the B<-analyze> option is given. -When B<-analyze> is specified, B<opt> performs various analyses of LLVM -bitcode. It will usually print the results on standard output, but in a few -cases, it will print output to standard error or generate a file with the -analysis output, which is usually done when the output is meant for another -program. +When B<-analyze> is specified, B<opt> performs various analyses of the input +source. It will usually print the results on standard output, but in a few +cases, it will print output to standard error or generate a file with the +analysis output, which is usually done when the output is meant for another +program. While B<-analyze> is I<not> given, B<opt> attempts to produce an optimized -bitcode file. The optimizations available via B<opt> depend upon what +output file. The optimizations available via B<opt> depend upon what libraries were linked into it as well as any additional libraries that have been loaded with the B<-load> option. Use the B<-help> option to determine what optimizations you can use. If I<filename> is omitted from the command line or is I<->, B<opt> reads its -input from standard input. The input must be an LLVM bitcode file. +input from standard input. Inputs can be in either the LLVM assembly language +format (.ll) or the LLVM bitcode format (.bc). If an output filename is not specified with the B<-o> option, B<opt> writes its output to the standard output. @@ -39,9 +40,9 @@ writes its output to the standard output. =item B<-f> -Force overwrite. Normally, B<opt> will refuse to overwrite an -output file that already exists. With this option, B<opt> will -overwrite the output file and replace it with new bitcode. +Enable binary output on terminals. Normally, B<opt> will refuse to +write raw bitcode output if the output stream is a terminal. With this option, +B<opt> will write raw bitcode regardless of the output device. =item B<-help> @@ -51,6 +52,10 @@ Print a summary of command line options. Specify the output filename. +=item B<-S> + +Write output in LLVM intermediate language (instead of bitcode). + =item B<-{passname}> B<opt> provides the ability to run any of LLVM's optimization or analysis passes diff --git a/docs/CommandLine.html b/docs/CommandLine.html index d6cf48c..7e6e2f2 100644 --- a/docs/CommandLine.html +++ b/docs/CommandLine.html @@ -331,13 +331,13 @@ OPTIONS: <div class="doc_text"> <p>In addition to input and output filenames, we would like the compiler example -to support three boolean flags: "<tt>-f</tt>" to force overwriting of the output -file, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for backwards -compatibility with some of our users. We can support these by declaring options -of boolean type like this:</p> +to support three boolean flags: "<tt>-f</tt>" to force writing binary output to +a terminal, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for +backwards compatibility with some of our users. We can support these by +declaring options of boolean type like this:</p> <div class="doc_code"><pre> -<a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Overwrite output files</i>")); +<a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable binary output on terminals</i>")); <a href="#cl::opt">cl::opt</a><bool> Quiet ("<i>quiet</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>")); <a href="#cl::opt">cl::opt</a><bool> Quiet2("<i>q</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"), <a href="#cl::Hidden">cl::Hidden</a>); </pre></div> @@ -378,7 +378,7 @@ library calls to parse the string value into the specified data type.</p> USAGE: compiler [options] <input file> OPTIONS: - <b>-f - Overwrite output files</b> + <b>-f - Enable binary output on terminals</b> -o - Override output filename <b>-quiet - Don't print informational messages</b> -help - display available options (--help-hidden for more) @@ -390,7 +390,7 @@ OPTIONS: USAGE: compiler [options] <input file> OPTIONS: - -f - Overwrite output files + -f - Enable binary output on terminals -o - Override output filename <b>-q - Don't print informational messages</b> -quiet - Don't print informational messages @@ -530,7 +530,7 @@ OPTIONS: -O1 - Enable trivial optimizations -O2 - Enable default optimizations -O3 - Enable expensive optimizations</b> - -f - Overwrite output files + -f - Enable binary output on terminals -help - display available options (--help-hidden for more) -o <filename> - Specify output filename -quiet - Don't print informational messages @@ -614,7 +614,7 @@ OPTIONS: =none - disable debug information =quick - enable quick debug information =detailed - enable detailed debug information</b> - -f - Overwrite output files + -f - Enable binary output on terminals -help - display available options (--help-hidden for more) -o <filename> - Specify output filename -quiet - Don't print informational messages @@ -1022,7 +1022,7 @@ files that use them. This is called the internal storage model.</p> code from the storage of the value parsed. For example, lets say that we have a '<tt>-debug</tt>' option that we would like to use to enable debug information across the entire body of our program. In this case, the boolean value -controlling the debug code should be globally accessable (in a header file, for +controlling the debug code should be globally accessible (in a header file, for example) yet the command line option processing code should not be exposed to all of these clients (requiring lots of .cpp files to #include <tt>CommandLine.h</tt>).</p> @@ -1107,7 +1107,7 @@ a command line option. Look <a href="#value_desc_example">here</a> for an example.</li> <li><a name="cl::init">The <b><tt>cl::init</tt></b></a> attribute specifies an -inital value for a <a href="#cl::opt">scalar</a> option. If this attribute is +initial value for a <a href="#cl::opt">scalar</a> option. If this attribute is not specified then the command line option value defaults to the value created by the default constructor for the type. <b>Warning</b>: If you specify both <b><tt>cl::init</tt></b> and <b><tt>cl::location</tt></b> for an option, @@ -1178,7 +1178,7 @@ href="#cl::list">cl::list</a></tt>. These modifiers give you the ability to tweak how options are parsed and how <tt>--help</tt> output is generated to fit your application well.</p> -<p>These options fall into five main catagories:</p> +<p>These options fall into five main categories:</p> <ol> <li><a href="#hiding">Hiding an option from <tt>--help</tt> output</a></li> @@ -1190,9 +1190,9 @@ your application well.</p> <li><a href="#misc">Miscellaneous option modifiers</a></li> </ol> -<p>It is not possible to specify two options from the same catagory (you'll get +<p>It is not possible to specify two options from the same category (you'll get a runtime error) to a single option, except for options in the miscellaneous -catagory. The CommandLine library specifies defaults for all of these settings +category. The CommandLine library specifies defaults for all of these settings that are the most useful in practice and the most common, which mean that you usually shouldn't have to worry about these.</p> @@ -1441,9 +1441,9 @@ string "<tt>-pos1 -foo -bar baz -pos2 -bork</tt>" would cause the "<tt>-foo -bar <li><a name="cl::Sink">The <b><tt>cl::Sink</tt></b></a> modifier is used to handle unknown options. If there is at least one option with -<b><tt>cl::Sink</tt></b></a> modifier specified, the parser passes +<tt>cl::Sink</tt> modifier specified, the parser passes unrecognized option strings to it as values instead of signaling an -error. As with <b><tt>cl::CommaSeparated</tt></b></a>, this modifier +error. As with <tt>cl::CommaSeparated</tt>, this modifier only makes sense with a <a href="#cl::list">cl::list</a> option.</li> </ul> @@ -1536,7 +1536,7 @@ not be available, it can't just look in <tt>argv[0]</tt>), the name of the environment variable to examine, the optional <a href="#description">additional extra text</a> to emit when the <tt>--help</tt> option is invoked, and the boolean -switch that controls whether <a href="#response">reponse files</a> +switch that controls whether <a href="#response">response files</a> should be read.</p> <p><tt>cl::ParseEnvironmentOptions</tt> will break the environment @@ -1883,7 +1883,7 @@ our example, we implement <tt>parse</tt> as:</p> default: <i>// Print an error message if unrecognized character!</i> - <b>return</b> O.error(": '" + Arg + "' value invalid for file size argument!"); + <b>return</b> O.error("'" + Arg + "' value invalid for file size argument!"); } } } @@ -1972,7 +1972,7 @@ tutorial.</p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-06-17 03:09:39 +0000 (Wed, 17 Jun 2009) $ + Last modified: $Date: 2009-10-12 16:46:08 +0200 (Mon, 12 Oct 2009) $ </address> </body> diff --git a/docs/CompilerDriver.html b/docs/CompilerDriver.html index 6b531c4..7a40a4d 100644 --- a/docs/CompilerDriver.html +++ b/docs/CompilerDriver.html @@ -114,6 +114,10 @@ delete them on exit. This option can also take an argument: the <tt class="docutils literal"><span class="pre">--save-temps=obj</span></tt> switch will write files into the directory specified with the <tt class="docutils literal"><span class="pre">-o</span></tt> option. The <tt class="docutils literal"><span class="pre">--save-temps=cwd</span></tt> and <tt class="docutils literal"><span class="pre">--save-temps</span></tt> switches are both synonyms for the default behaviour.</li> +<li><tt class="docutils literal"><span class="pre">--temp-dir</span> <span class="pre">DIRECTORY</span></tt> - Store temporary files in the given directory. This +directory is deleted on exit unless <tt class="docutils literal"><span class="pre">--save-temps</span></tt> is specified. If +<tt class="docutils literal"><span class="pre">--save-temps=obj</span></tt> is also specified, <tt class="docutils literal"><span class="pre">--temp-dir</span></tt> is given the +precedence.</li> <li><tt class="docutils literal"><span class="pre">--check-graph</span></tt> - Check the compilation for common errors like mismatched output/input language names, multiple default edges and cycles. Because of plugins, these checks can't be performed at compile-time. Exit with code zero @@ -303,13 +307,13 @@ separate option groups syntactically.</p> <tt class="docutils literal"><span class="pre">-std=c99</span></tt>. It is also allowed to use spaces instead of the equality sign: <tt class="docutils literal"><span class="pre">-std</span> <span class="pre">c99</span></tt>. At most one occurrence is allowed.</li> <li><tt class="docutils literal"><span class="pre">parameter_list_option</span></tt> - same as the above, but more than one option -occurence is allowed.</li> +occurrence is allowed.</li> <li><tt class="docutils literal"><span class="pre">prefix_option</span></tt> - same as the parameter_option, but the option name and argument do not have to be separated. Example: <tt class="docutils literal"><span class="pre">-ofile</span></tt>. This can be also specified as <tt class="docutils literal"><span class="pre">-o</span> <span class="pre">file</span></tt>; however, <tt class="docutils literal"><span class="pre">-o=file</span></tt> will be parsed incorrectly (<tt class="docutils literal"><span class="pre">=file</span></tt> will be interpreted as option value). At most one occurrence is allowed.</li> -<li><tt class="docutils literal"><span class="pre">prefix_list_option</span></tt> - same as the above, but more than one occurence of +<li><tt class="docutils literal"><span class="pre">prefix_list_option</span></tt> - same as the above, but more than one occurrence of the option is allowed; example: <tt class="docutils literal"><span class="pre">-lm</span> <span class="pre">-lpthread</span></tt>.</li> <li><tt class="docutils literal"><span class="pre">alias_option</span></tt> - a special option type for creating aliases. Unlike other option types, aliases are not allowed to have any properties besides the @@ -341,6 +345,11 @@ output.</li> special cases). Usage example: <tt class="docutils literal"><span class="pre">(parameter_list_option</span> <span class="pre">"foo",</span> <span class="pre">(multi_val</span> <span class="pre">3))</span></tt>. Only list options can have this attribute; you can, however, use the <tt class="docutils literal"><span class="pre">one_or_more</span></tt> and <tt class="docutils literal"><span class="pre">zero_or_one</span></tt> properties.</li> +<li><tt class="docutils literal"><span class="pre">init</span></tt> - this option has a default value, either a string (if it is a +parameter), or a boolean (if it is a switch; boolean constants are called +<tt class="docutils literal"><span class="pre">true</span></tt> and <tt class="docutils literal"><span class="pre">false</span></tt>). List options can't have this attribute. Usage +examples: <tt class="docutils literal"><span class="pre">(switch_option</span> <span class="pre">"foo",</span> <span class="pre">(init</span> <span class="pre">true))</span></tt>; <tt class="docutils literal"><span class="pre">(prefix_option</span> <span class="pre">"bar",</span> +<span class="pre">(init</span> <span class="pre">"baz"))</span></tt>.</li> <li><tt class="docutils literal"><span class="pre">extern</span></tt> - this option is defined in some other plugin, see below.</li> </ul> </blockquote> @@ -358,7 +367,8 @@ for. Example:</p> (switch_option "E", (extern)) ... </pre> -<p>See also the section on plugin <a class="reference internal" href="#priorities">priorities</a>.</p> +<p>If an external option has additional attributes besides 'extern', they are +ignored. See also the section on plugin <a class="reference internal" href="#priorities">priorities</a>.</p> </div> </div> <div class="section" id="conditional-evaluation"> @@ -428,15 +438,21 @@ user. Example: <tt class="docutils literal"><span class="pre">(not_empty</span> <span class="pre">"o")</span></tt>.</li> <li><tt class="docutils literal"><span class="pre">empty</span></tt> - The opposite of <tt class="docutils literal"><span class="pre">not_empty</span></tt>. Equivalent to <tt class="docutils literal"><span class="pre">(not</span> <span class="pre">(not_empty</span> <span class="pre">X))</span></tt>. Provided for convenience.</li> +<li><tt class="docutils literal"><span class="pre">single_input_file</span></tt> - Returns true if there was only one input file +provided on the command-line. Used without arguments: +<tt class="docutils literal"><span class="pre">(single_input_file)</span></tt>.</li> +<li><tt class="docutils literal"><span class="pre">multiple_input_files</span></tt> - Equivalent to <tt class="docutils literal"><span class="pre">(not</span> <span class="pre">(single_input_file))</span></tt> (the +case of zero input files is considered an error).</li> <li><tt class="docutils literal"><span class="pre">default</span></tt> - Always evaluates to true. Should always be the last test in the <tt class="docutils literal"><span class="pre">case</span></tt> expression.</li> -<li><tt class="docutils literal"><span class="pre">and</span></tt> - A standard logical combinator that returns true iff all -of its arguments return true. Used like this: <tt class="docutils literal"><span class="pre">(and</span> <span class="pre">(test1),</span> -<span class="pre">(test2),</span> <span class="pre">...</span> <span class="pre">(testN))</span></tt>. Nesting of <tt class="docutils literal"><span class="pre">and</span></tt> and <tt class="docutils literal"><span class="pre">or</span></tt> is allowed, -but not encouraged.</li> -<li><tt class="docutils literal"><span class="pre">or</span></tt> - Another logical combinator that returns true only if any -one of its arguments returns true. Example: <tt class="docutils literal"><span class="pre">(or</span> <span class="pre">(test1),</span> -<span class="pre">(test2),</span> <span class="pre">...</span> <span class="pre">(testN))</span></tt>.</li> +<li><tt class="docutils literal"><span class="pre">and</span></tt> - A standard binary logical combinator that returns true iff all of +its arguments return true. Used like this: <tt class="docutils literal"><span class="pre">(and</span> <span class="pre">(test1),</span> <span class="pre">(test2),</span> +<span class="pre">...</span> <span class="pre">(testN))</span></tt>. Nesting of <tt class="docutils literal"><span class="pre">and</span></tt> and <tt class="docutils literal"><span class="pre">or</span></tt> is allowed, but not +encouraged.</li> +<li><tt class="docutils literal"><span class="pre">or</span></tt> - A binary logical combinator that returns true iff any of its +arguments returns true. Example: <tt class="docutils literal"><span class="pre">(or</span> <span class="pre">(test1),</span> <span class="pre">(test2),</span> <span class="pre">...</span> <span class="pre">(testN))</span></tt>.</li> +<li><tt class="docutils literal"><span class="pre">not</span></tt> - Standard unary logical combinator that negates its +argument. Example: <tt class="docutils literal"><span class="pre">(not</span> <span class="pre">(or</span> <span class="pre">(test1),</span> <span class="pre">(test2),</span> <span class="pre">...</span> <span class="pre">(testN)))</span></tt>.</li> </ul> </li> </ul> @@ -666,7 +682,7 @@ the <tt class="docutils literal"><span class="pre">Base</span></tt> plugin behav <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br /> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br /> -Last modified: $Date: 2009-06-30 02:16:43 +0200 (Tue, 30 Jun 2009) $ +Last modified: $Date: 2009-10-12 16:46:08 +0200 (Mon, 12 Oct 2009) $ </address></div> </div> </div> diff --git a/docs/DebuggingJITedCode.html b/docs/DebuggingJITedCode.html new file mode 100644 index 0000000..92570f4 --- /dev/null +++ b/docs/DebuggingJITedCode.html @@ -0,0 +1,171 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <title>Debugging JITed Code With GDB</title> + <link rel="stylesheet" href="llvm.css" type="text/css"> +</head> +<body> + +<div class="doc_title">Debugging JITed Code With GDB</div> +<ol> + <li><a href="#introduction">Introduction</a></li> + <li><a href="#quickstart">Quickstart</a></li> + <li><a href="#example">Example with clang and lli</a></li> +</ol> +<div class="doc_author">Written by Reid Kleckner</div> + +<!--=========================================================================--> +<div class="doc_section"><a name="introduction">Introduction</a></div> +<!--=========================================================================--> +<div class="doc_text"> + +<p>Without special runtime support, debugging dynamically generated code with +GDB (as well as most debuggers) can be quite painful. Debuggers generally read +debug information from the object file of the code, but for JITed code, there is +no such file to look for. +</p> + +<p>Depending on the architecture, this can impact the debugging experience in +different ways. For example, on most 32-bit x86 architectures, you can simply +compile with -fno-omit-framepointer for GCC and -fdisable-fp-elim for LLVM. +When GDB creates a backtrace, it can properly unwind the stack, but the stack +frames owned by JITed code have ??'s instead of the appropriate symbol name. +However, on Linux x86_64 in particular, GDB relies on the DWARF CFA debug +information to unwind the stack, so even if you compile your program to leave +the frame pointer untouched, GDB will usually be unable to unwind the stack past +any JITed code stack frames. +</p> + +<p>In order to communicate the necessary debug info to GDB, an interface for +registering JITed code with debuggers has been designed and implemented for +GDB and LLVM. At a high level, whenever LLVM generates new machine code, it +also generates an object file in memory containing the debug information. LLVM +then adds the object file to the global list of object files and calls a special +function (__jit_debug_register_code) marked noinline that GDB knows about. When +GDB attaches to a process, it puts a breakpoint in this function and loads all +of the object files in the global list. When LLVM calls the registration +function, GDB catches the breakpoint signal, loads the new object file from +LLVM's memory, and resumes the execution. In this way, GDB can get the +necessary debug information. +</p> + +<p>At the time of this writing, LLVM only supports architectures that use ELF +object files and it only generates symbols and DWARF CFA information. However, +it would be easy to add more information to the object file, so we don't need to +coordinate with GDB to get better debug information. +</p> +</div> + +<!--=========================================================================--> +<div class="doc_section"><a name="quickstart">Quickstart</a></div> +<!--=========================================================================--> +<div class="doc_text"> + +<p>In order to debug code JITed by LLVM, you need to install a recent version +of GDB. The interface was added on 2009-08-19, so you need a snapshot of GDB +more recent than that. Either download a snapshot of GDB or checkout CVS as +instructed <a href="http://www.gnu.org/software/gdb/current/">here</a>. Here +are the commands for doing a checkout and building the code: +</p> + +<pre class="doc_code"> +$ cvs -z 3 -d :pserver:anoncvs@sourceware.org:/cvs/src co gdb +$ mv src gdb # You probably don't want this checkout called "src". +$ cd gdb +$ ./configure --prefix="$GDB_INSTALL" +$ make +$ make install +</pre> + +<p>You can then use -jit-emit-debug in the LLVM command line arguments to enable +the interface. +</p> +</div> + +<!--=========================================================================--> +<div class="doc_section"><a name="example">Example with clang and lli</a></div> +<!--=========================================================================--> +<div class="doc_text"> + +<p>For example, consider debugging running lli on the following C code in +foo.c: +</p> + +<pre class="doc_code"> +#include <stdio.h> + +void foo() { + printf("%d\n", *(int*)NULL); // Crash here +} + +void bar() { + foo(); +} + +void baz() { + bar(); +} + +int main(int argc, char **argv) { + baz(); +} +</pre> + +<p>Here are the commands to run that application under GDB and print the stack +trace at the crash: +</p> + +<pre class="doc_code"> +# Compile foo.c to bitcode. You can use either clang or llvm-gcc with this +# command line. Both require -fexceptions, or the calls are all marked +# 'nounwind' which disables DWARF CFA info. +$ clang foo.c -fexceptions -emit-llvm -c -o foo.bc + +# Run foo.bc under lli with -jit-emit-debug. If you built lli in debug mode, +# -jit-emit-debug defaults to true. +$ $GDB_INSTALL/gdb --args lli -jit-emit-debug foo.bc +... + +# Run the code. +(gdb) run +Starting program: /tmp/gdb/lli -jit-emit-debug foo.bc +[Thread debugging using libthread_db enabled] + +Program received signal SIGSEGV, Segmentation fault. +0x00007ffff7f55164 in foo () + +# Print the backtrace, this time with symbols instead of ??. +(gdb) bt +#0 0x00007ffff7f55164 in foo () +#1 0x00007ffff7f550f9 in bar () +#2 0x00007ffff7f55099 in baz () +#3 0x00007ffff7f5502a in main () +#4 0x00000000007c0225 in llvm::JIT::runFunction(llvm::Function*, + std::vector<llvm::GenericValue, + std::allocator<llvm::GenericValue> > const&) () +#5 0x00000000007d6d98 in + llvm::ExecutionEngine::runFunctionAsMain(llvm::Function*, + std::vector<std::string, + std::allocator<std::string> > const&, char const* const*) () +#6 0x00000000004dab76 in main () +</pre> +</div> + +<p>As you can see, GDB can correctly unwind the stack and has the appropriate +function names. +</p> + +<!-- *********************************************************************** --> +<hr> +<address> + <a href="http://jigsaw.w3.org/css-validator/check/referer"><img + src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a> + <a href="http://validator.w3.org/check/referer"><img + src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> + <a href="mailto:reid.kleckner@gmail.com">Reid Kleckner</a><br> + <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> + Last modified: $Date: 2009-01-01 23:10:51 -0800 (Thu, 01 Jan 2009) $ +</address> +</body> +</html> diff --git a/docs/DeveloperPolicy.html b/docs/DeveloperPolicy.html index 13a908e..4986606 100644 --- a/docs/DeveloperPolicy.html +++ b/docs/DeveloperPolicy.html @@ -99,7 +99,9 @@ <ol> <li>Make your patch against the Subversion trunk, not a branch, and not an old - version of LLVM. This makes it easy to apply the patch.</li> + version of LLVM. This makes it easy to apply the patch. For information + on how to check out SVN trunk, please see the <a + href="GettingStarted.html#checkout">Getting Started Guide</a>.</li> <li>Similarly, patches should be submitted soon after they are generated. Old patches may not apply correctly if the underlying code changes between the @@ -185,14 +187,18 @@ svn diff else. The current code owners are:</p> <ol> + <li><b>Evan Cheng</b>: Code generator and all targets.</li> + + <li><b>Doug Gregor</b>: Clang Basic, Lex, Parse, and Sema Libraries.</li> + <li><b>Anton Korobeynikov</b>: Exception handling, debug information, and Windows codegen.</li> - <li><b>Duncan Sands</b>: llvm-gcc 4.2.</li> - - <li><b>Evan Cheng</b>: Code generator and all targets.</li> + <li><b>Ted Kremenek</b>: Clang Static Analyzer.</li> - <li><b>Chris Lattner</b>: Everything else.</li> + <li><b>Chris Lattner</b>: Everything not covered by someone else.</li> + + <li><b>Duncan Sands</b>: llvm-gcc 4.2.</li> </ol> <p>Note that code ownership is completely different than reviewers: anyone can @@ -287,9 +293,12 @@ svn diff </ul> <p>We prefer for this to be handled before submission but understand that it - isn't possible to test all of this for every submission. Our nightly testing - infrastructure normally finds these problems. A good rule of thumb is to - check the nightly testers for regressions the day after your change.</p> + isn't possible to test all of this for every submission. Our build bots and + nightly testing infrastructure normally finds these problems. A good rule of + thumb is to check the nightly testers for regressions the day after your + change. Build bots will directly email you if a group of commits that + included yours caused a failure. You are expected to check the build bot + messages to see if they are your fault and, if so, fix the breakage.</p> <p>Commits that violate these quality standards (e.g. are very broken) may be reverted. This is necessary when the change blocks other developers from @@ -592,7 +601,7 @@ Changes</a></div> Written by the <a href="mailto:llvm-oversight@cs.uiuc.edu">LLVM Oversight Group</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-06-15 04:18:54 +0000 (Mon, 15 Jun 2009) $ + Last modified: $Date: 2009-10-10 23:37:16 +0200 (Sat, 10 Oct 2009) $ </address> </body> </html> diff --git a/docs/ExceptionHandling.html b/docs/ExceptionHandling.html index a03568f..0ca702f 100644 --- a/docs/ExceptionHandling.html +++ b/docs/ExceptionHandling.html @@ -3,8 +3,12 @@ <html> <head> <title>Exception Handling in LLVM</title> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> + <meta name="description" + content="Exception Handling in LLVM."> <link rel="stylesheet" href="llvm.css" type="text/css"> </head> + <body> <div class="doc_title">Exception Handling in LLVM</div> @@ -16,6 +20,7 @@ <li><a href="#introduction">Introduction</a> <ol> <li><a href="#itanium">Itanium ABI Zero-cost Exception Handling</a></li> + <li><a href="#sjlj">Setjmp/Longjmp Exception Handling</a></li> <li><a href="#overview">Overview</a></li> </ol></li> <li><a href="#codegen">LLVM Code Generation</a> @@ -33,6 +38,7 @@ <li><a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a></li> <li><a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a></li> <li><a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a></li> + <li><a href="#llvm_eh_sjlj_lsda"><tt>llvm.eh.sjlj.lsda</tt></a></li> </ol></li> <li><a href="#asm">Asm Table Formats</a> <ol> @@ -50,17 +56,17 @@ <!-- *********************************************************************** --> -<div class="doc_section"><a name="introduction">Introduction</a></div> +<div class="doc_section"><a name="introduction">Introduction</a></div> <!-- *********************************************************************** --> <div class="doc_text"> <p>This document is the central repository for all information pertaining to -exception handling in LLVM. It describes the format that LLVM exception -handling information takes, which is useful for those interested in creating -front-ends or dealing directly with the information. Further, this document -provides specific examples of what exception handling information is used for -C/C++.</p> + exception handling in LLVM. It describes the format that LLVM exception + handling information takes, which is useful for those interested in creating + front-ends or dealing directly with the information. Further, this document + provides specific examples of what exception handling information is used for + in C/C++.</p> </div> @@ -72,72 +78,108 @@ C/C++.</p> <div class="doc_text"> <p>Exception handling for most programming languages is designed to recover from -conditions that rarely occur during general use of an application. To that end, -exception handling should not interfere with the main flow of an -application's algorithm by performing checkpointing tasks such as saving -the current pc or register state.</p> + conditions that rarely occur during general use of an application. To that + end, exception handling should not interfere with the main flow of an + application's algorithm by performing checkpointing tasks, such as saving the + current pc or register state.</p> <p>The Itanium ABI Exception Handling Specification defines a methodology for -providing outlying data in the form of exception tables without inlining -speculative exception handling code in the flow of an application's main -algorithm. Thus, the specification is said to add "zero-cost" to the normal -execution of an application.</p> + providing outlying data in the form of exception tables without inlining + speculative exception handling code in the flow of an application's main + algorithm. Thus, the specification is said to add "zero-cost" to the normal + execution of an application.</p> <p>A more complete description of the Itanium ABI exception handling runtime -support of can be found at <a -href="http://www.codesourcery.com/cxx-abi/abi-eh.html">Itanium C++ ABI: -Exception Handling.</a> A description of the exception frame format can be found -at <a href="http://refspecs.freestandards.org/LSB_3.0.0/LSB-Core-generic/LSB- -Core-generic/ehframechpt.html">Exception Frames</a>, with details of the Dwarf -specification at <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">Dwarf 3 -Standard.</a> A description for the C++ exception table formats can be found at -<a href="http://www.codesourcery.com/cxx-abi/exceptions.pdf">Exception Handling -Tables.</a></p> + support of can be found at + <a href="http://www.codesourcery.com/cxx-abi/abi-eh.html">Itanium C++ ABI: + Exception Handling</a>. A description of the exception frame format can be + found at + <a href="http://refspecs.freestandards.org/LSB_3.0.0/LSB-Core-generic/LSB-Core-generic/ehframechpt.html">Exception + Frames</a>, with details of the DWARF 3 specification at + <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3 Standard</a>. + A description for the C++ exception table formats can be found at + <a href="http://www.codesourcery.com/cxx-abi/exceptions.pdf">Exception Handling + Tables</a>.</p> </div> <!-- ======================================================================= --> <div class="doc_subsection"> + <a name="sjlj">Setjmp/Longjmp Exception Handling</a> +</div> + +<div class="doc_text"> + +<p>Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics + <a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a> and + <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a> to + handle control flow for exception handling.</p> + +<p>For each function which does exception processing, be it try/catch blocks + or cleanups, that function registers itself on a global frame list. When + exceptions are being unwound, the runtime uses this list to identify which + functions need processing.<p> + +<p>Landing pad selection is encoded in the call site entry of the function + context. The runtime returns to the function via + <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a>, where + a switch table transfers control to the appropriate landing pad based on + the index stored in the function context.</p> + +<p>In contrast to DWARF exception handling, which encodes exception regions + and frame information in out-of-line tables, SJLJ exception handling + builds and removes the unwind frame context at runtime. This results in + faster exception handling at the expense of slower execution when no + exceptions are thrown. As exceptions are, by their nature, intended for + uncommon code paths, DWARF exception handling is generally preferred to + SJLJ.</p> +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> <a name="overview">Overview</a> </div> <div class="doc_text"> -<p>When an exception is thrown in llvm code, the runtime does a best effort to -find a handler suited to process the circumstance.</p> +<p>When an exception is thrown in LLVM code, the runtime does its best to find a + handler suited to processing the circumstance.</p> <p>The runtime first attempts to find an <i>exception frame</i> corresponding to -the function where the exception was thrown. If the programming language (ex. -C++) supports exception handling, the exception frame contains a reference to an -exception table describing how to process the exception. If the language (ex. -C) does not support exception handling or if the exception needs to be forwarded -to a prior activation, the exception frame contains information about how to -unwind the current activation and restore the state of the prior activation. -This process is repeated until the exception is handled. If the exception is -not handled and no activations remain, then the application is terminated with -an appropriate error message.</p> - -<p>Since different programming languages have different behaviors when handling -exceptions, the exception handling ABI provides a mechanism for supplying -<i>personalities.</i> An exception handling personality is defined by way of a -<i>personality function</i> (ex. for C++ <tt>__gxx_personality_v0</tt>) which -receives the context of the exception, an <i>exception structure</i> containing -the exception object type and value, and a reference to the exception table for -the current function. The personality function for the current compile unit is -specified in a <i>common exception frame</i>.</p> + the function where the exception was thrown. If the programming language + (e.g. C++) supports exception handling, the exception frame contains a + reference to an exception table describing how to process the exception. If + the language (e.g. C) does not support exception handling, or if the + exception needs to be forwarded to a prior activation, the exception frame + contains information about how to unwind the current activation and restore + the state of the prior activation. This process is repeated until the + exception is handled. If the exception is not handled and no activations + remain, then the application is terminated with an appropriate error + message.</p> + +<p>Because different programming languages have different behaviors when + handling exceptions, the exception handling ABI provides a mechanism for + supplying <i>personalities.</i> An exception handling personality is defined + by way of a <i>personality function</i> (e.g. <tt>__gxx_personality_v0</tt> + in C++), which receives the context of the exception, an <i>exception + structure</i> containing the exception object type and value, and a reference + to the exception table for the current function. The personality function + for the current compile unit is specified in a <i>common exception + frame</i>.</p> <p>The organization of an exception table is language dependent. For C++, an -exception table is organized as a series of code ranges defining what to do if -an exception occurs in that range. Typically, the information associated with a -range defines which types of exception objects (using C++ <i>type info</i>) that -are handled in that range, and an associated action that should take place. -Actions typically pass control to a <i>landing pad</i>.</p> + exception table is organized as a series of code ranges defining what to do + if an exception occurs in that range. Typically, the information associated + with a range defines which types of exception objects (using C++ <i>type + info</i>) that are handled in that range, and an associated action that + should take place. Actions typically pass control to a <i>landing + pad</i>.</p> -<p>A landing pad corresponds to the code found in the catch portion of a -try/catch sequence. When execution resumes at a landing pad, it receives the -exception structure and a selector corresponding to the <i>type</i> of exception -thrown. The selector is then used to determine which catch should actually -process the exception.</p> +<p>A landing pad corresponds to the code found in the <i>catch</i> portion of + a <i>try</i>/<i>catch</i> sequence. When execution resumes at a landing + pad, it receives the exception structure and a selector corresponding to + the <i>type</i> of exception thrown. The selector is then used to determine + which <i>catch</i> should actually process the exception.</p> </div> @@ -149,12 +191,12 @@ process the exception.</p> <div class="doc_text"> <p>At the time of this writing, only C++ exception handling support is available -in LLVM. So the remainder of this document will be somewhat C++-centric.</p> + in LLVM. So the remainder of this document will be somewhat C++-centric.</p> <p>From the C++ developers perspective, exceptions are defined in terms of the -<tt>throw</tt> and <tt>try/catch</tt> statements. In this section we will -describe the implementation of llvm exception handling in terms of C++ -examples.</p> + <tt>throw</tt> and <tt>try</tt>/<tt>catch</tt> statements. In this section + we will describe the implementation of LLVM exception handling in terms of + C++ examples.</p> </div> @@ -166,17 +208,17 @@ examples.</p> <div class="doc_text"> <p>Languages that support exception handling typically provide a <tt>throw</tt> -operation to initiate the exception process. Internally, a throw operation -breaks down into two steps. First, a request is made to allocate exception -space for an exception structure. This structure needs to survive beyond the -current activation. This structure will contain the type and value of the -object being thrown. Second, a call is made to the runtime to raise the -exception, passing the exception structure as an argument.</p> + operation to initiate the exception process. Internally, a throw operation + breaks down into two steps. First, a request is made to allocate exception + space for an exception structure. This structure needs to survive beyond the + current activation. This structure will contain the type and value of the + object being thrown. Second, a call is made to the runtime to raise the + exception, passing the exception structure as an argument.</p> -<p>In C++, the allocation of the exception structure is done by the -<tt>__cxa_allocate_exception</tt> runtime function. The exception raising is -handled by <tt>__cxa_throw</tt>. The type of the exception is represented using -a C++ RTTI type info structure.</p> +<p>In C++, the allocation of the exception structure is done by + the <tt>__cxa_allocate_exception</tt> runtime function. The exception + raising is handled by <tt>__cxa_throw</tt>. The type of the exception is + represented using a C++ RTTI structure.</p> </div> @@ -187,67 +229,84 @@ a C++ RTTI type info structure.</p> <div class="doc_text"> -<p>A call within the scope of a try statement can potentially raise an exception. -In those circumstances, the LLVM C++ front-end replaces the call with an -<tt>invoke</tt> instruction. Unlike a call, the invoke has two potential -continuation points; where to continue when the call succeeds as per normal, and -where to continue if the call raises an exception, either by a throw or the -unwinding of a throw.</p> - -<p>The term used to define a the place where an invoke continues after an -exception is called a <i>landing pad</i>. LLVM landing pads are conceptually -alternative function entry points where a exception structure reference and a type -info index are passed in as arguments. The landing pad saves the exception -structure reference and then proceeds to select the catch block that corresponds -to the type info of the exception object.</p> +<p>A call within the scope of a <i>try</i> statement can potentially raise an + exception. In those circumstances, the LLVM C++ front-end replaces the call + with an <tt>invoke</tt> instruction. Unlike a call, the <tt>invoke</tt> has + two potential continuation points: where to continue when the call succeeds + as per normal; and where to continue if the call raises an exception, either + by a throw or the unwinding of a throw.</p> -<p>Two llvm intrinsic functions are used convey information about the landing -pad to the back end.</p> +<p>The term used to define a the place where an <tt>invoke</tt> continues after + an exception is called a <i>landing pad</i>. LLVM landing pads are + conceptually alternative function entry points where an exception structure + reference and a type info index are passed in as arguments. The landing pad + saves the exception structure reference and then proceeds to select the catch + block that corresponds to the type info of the exception object.</p> -<p><a href="#llvm_eh_exception"><tt>llvm.eh.exception</tt></a> takes no -arguments and returns a pointer to the exception structure. This only returns a -sensible value if called after an invoke has branched to a landing pad. Due to -codegen limitations, it must currently be called in the landing pad itself.</p> +<p>Two LLVM intrinsic functions are used to convey information about the landing + pad to the back end.</p> -<p><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> takes a minimum of -three arguments. The first argument is the reference to the exception -structure. The second argument is a reference to the personality function to be -used for this try catch sequence. Each of the remaining arguments is either a -reference to the type info for a catch statement, -a <a href="#throw_filters">filter</a> expression, -or the number zero representing a <a href="#cleanups">cleanup</a>. -The exception is tested against the arguments sequentially from first to last. -The result of the <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> is a -positive number if the exception matched a type info, a negative number if it matched -a filter, and zero if it matched a cleanup. If nothing is matched, the behaviour of -the program is <a href="#restrictions">undefined</a>. -This only returns a sensible value if called after an invoke has branched to a -landing pad. Due to codegen limitations, it must currently be called in the -landing pad itself. -If a type info matched then the selector value is the index of the type info in -the exception table, which can be obtained using the -<a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic.</p> +<ol> + <li><a href="#llvm_eh_exception"><tt>llvm.eh.exception</tt></a> takes no + arguments and returns a pointer to the exception structure. This only + returns a sensible value if called after an <tt>invoke</tt> has branched + to a landing pad. Due to code generation limitations, it must currently + be called in the landing pad itself.</li> + + <li><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> takes a minimum + of three arguments. The first argument is the reference to the exception + structure. The second argument is a reference to the personality function + to be used for this <tt>try</tt>/<tt>catch</tt> sequence. Each of the + remaining arguments is either a reference to the type info for + a <tt>catch</tt> statement, a <a href="#throw_filters">filter</a> + expression, or the number zero (<tt>0</tt>) representing + a <a href="#cleanups">cleanup</a>. The exception is tested against the + arguments sequentially from first to last. The result of + the <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> is a + positive number if the exception matched a type info, a negative number if + it matched a filter, and zero if it matched a cleanup. If nothing is + matched, the behaviour of the program + is <a href="#restrictions">undefined</a>. This only returns a sensible + value if called after an <tt>invoke</tt> has branched to a landing pad. + Due to codegen limitations, it must currently be called in the landing pad + itself. If a type info matched, then the selector value is the index of + the type info in the exception table, which can be obtained using the + <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> + intrinsic.</li> +</ol> <p>Once the landing pad has the type info selector, the code branches to the -code for the first catch. The catch then checks the value of the type info -selector against the index of type info for that catch. Since the type info -index is not known until all the type info have been gathered in the backend, -the catch code will call the <a -href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic to -determine the index for a given type info. If the catch fails to match the -selector then control is passed on to the next catch. Note: Since the landing -pad will not be used if there is no match in the list of type info on the call -to <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>, then neither the -last catch nor <i>catch all</i> need to perform the the check against the -selector.</p> - -<p>Finally, the entry and exit of catch code is bracketed with calls to -<tt>__cxa_begin_catch</tt> and <tt>__cxa_end_catch</tt>. -<tt>__cxa_begin_catch</tt> takes a exception structure reference as an argument -and returns the value of the exception object. <tt>__cxa_end_catch</tt> -takes a exception structure reference as an argument. This function clears the -exception from the exception space. Note: a rethrow from within the catch may -replace this call with a <tt>__cxa_rethrow</tt>.</p> + code for the first catch. The catch then checks the value of the type info + selector against the index of type info for that catch. Since the type info + index is not known until all the type info have been gathered in the backend, + the catch code will call the + <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic + to determine the index for a given type info. If the catch fails to match + the selector then control is passed on to the next catch. Note: Since the + landing pad will not be used if there is no match in the list of type info on + the call to <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>, then + neither the last catch nor <i>catch all</i> need to perform the check + against the selector.</p> + +<p>Finally, the entry and exit of catch code is bracketed with calls + to <tt>__cxa_begin_catch</tt> and <tt>__cxa_end_catch</tt>.</p> + +<ul> + <li><tt>__cxa_begin_catch</tt> takes a exception structure reference as an + argument and returns the value of the exception object.</li> + + <li><tt>__cxa_end_catch</tt> takes no arguments. This function:<br><br> + <ol> + <li>Locates the most recently caught exception and decrements its handler + count,</li> + <li>Removes the exception from the "caught" stack if the handler count + goes to zero, and</li> + <li>Destroys the exception if the handler count goes to zero, and the + exception was not re-thrown by throw.</li> + </ol> + <p>Note: a rethrow from within the catch may replace this call with + a <tt>__cxa_rethrow</tt>.</p></li> +</ul> </div> @@ -258,16 +317,15 @@ replace this call with a <tt>__cxa_rethrow</tt>.</p> <div class="doc_text"> -<p>To handle destructors and cleanups in try code, control may not run directly -from a landing pad to the first catch. Control may actually flow from the -landing pad to clean up code and then to the first catch. Since the required -clean up for each invoke in a try may be different (ex., intervening -constructor), there may be several landing pads for a given try. If cleanups -need to be run, the number zero should be passed as the last -<a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> argument. -However for C++ a <tt>null i8*</tt> <a href="#restrictions">must</a> be passed -instead. -</p> +<p>To handle destructors and cleanups in <tt>try</tt> code, control may not run + directly from a landing pad to the first catch. Control may actually flow + from the landing pad to clean up code and then to the first catch. Since the + required clean up for each <tt>invoke</tt> in a <tt>try</tt> may be different + (e.g. intervening constructor), there may be several landing pads for a given + try. If cleanups need to be run, an <tt>i32 0</tt> should be passed as the + last <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> argument. + However, when using DWARF exception handling with C++, a <tt>i8* null</tt> + <a href="#restrictions">must</a> be passed instead.</p> </div> @@ -278,23 +336,23 @@ instead. <div class="doc_text"> -<p>C++ allows the specification of which exception types can be thrown from -a function. To represent this a top level landing pad may exist to filter out -invalid types. To express this in LLVM code the landing pad will call <a -href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>. The arguments are a -reference to the exception structure, a reference to the personality function, -the length of the filter expression (the number of type infos plus one), -followed by the type infos themselves. -<a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> will return a negative -value if the exception does not match any of the type infos. If no match is -found then a call to <tt>__cxa_call_unexpected</tt> should be made, otherwise -<tt>_Unwind_Resume</tt>. Each of these functions requires a reference to the -exception structure. Note that the most general form of an -<a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> call can contain -any number of type infos, filter expressions and cleanups (though having more -than one cleanup is pointless). The LLVM C++ front-end can generate such -<a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> calls due to inlining -creating nested exception handling scopes.</p> +<p>C++ allows the specification of which exception types can be thrown from a + function. To represent this a top level landing pad may exist to filter out + invalid types. To express this in LLVM code the landing pad will + call <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>. The + arguments are a reference to the exception structure, a reference to the + personality function, the length of the filter expression (the number of type + infos plus one), followed by the type infos themselves. + <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> will return a + negative value if the exception does not match any of the type infos. If no + match is found then a call to <tt>__cxa_call_unexpected</tt> should be made, + otherwise <tt>_Unwind_Resume</tt>. Each of these functions requires a + reference to the exception structure. Note that the most general form of an + <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> call can contain + any number of type infos, filter expressions and cleanups (though having more + than one cleanup is pointless). The LLVM C++ front-end can generate such + <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> calls due to + inlining creating nested exception handling scopes.</p> </div> @@ -306,23 +364,21 @@ creating nested exception handling scopes.</p> <div class="doc_text"> <p>The semantics of the invoke instruction require that any exception that -unwinds through an invoke call should result in a branch to the invoke's unwind -label. However such a branch will only happen if the -<a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> matches. -Thus in order to ensure correct operation, the front-end must only generate -<a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> calls that are -guaranteed to always match whatever exception unwinds through the invoke. -For most languages it is enough to pass zero, indicating the presence of -a <a href="#cleanups">cleanup</a>, as the last -<a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> argument. -However for C++ this is not sufficient, because the C++ personality function -will terminate the program if it detects that unwinding the exception only -results in matches with cleanups. For C++ a <tt>null i8*</tt> should -be passed as the last -<a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> argument instead. -This is interpreted as a catch-all by the C++ personality function, and will -always match. -</p> + unwinds through an invoke call should result in a branch to the invoke's + unwind label. However such a branch will only happen if the + <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> matches. Thus in + order to ensure correct operation, the front-end must only generate + <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> calls that are + guaranteed to always match whatever exception unwinds through the invoke. + For most languages it is enough to pass zero, indicating the presence of + a <a href="#cleanups">cleanup</a>, as the + last <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> argument. + However for C++ this is not sufficient, because the C++ personality function + will terminate the program if it detects that unwinding the exception only + results in matches with cleanups. For C++ a <tt>null i8*</tt> should be + passed as the last <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> + argument instead. This is interpreted as a catch-all by the C++ personality + function, and will always match.</p> </div> @@ -334,7 +390,8 @@ always match. <div class="doc_text"> <p>LLVM uses several intrinsic functions (name prefixed with "llvm.eh") to -provide exception handling information at various points in generated code.</p> + provide exception handling information at various points in generated + code.</p> </div> @@ -344,6 +401,7 @@ provide exception handling information at various points in generated code.</p> </div> <div class="doc_text"> + <pre> i8* %<a href="#llvm_eh_exception">llvm.eh.exception</a>( ) </pre> @@ -358,29 +416,29 @@ provide exception handling information at various points in generated code.</p> </div> <div class="doc_text"> + <pre> - i32 %<a href="#llvm_eh_selector">llvm.eh.selector.i32</a>(i8*, i8*, i8*, ...) - i64 %<a href="#llvm_eh_selector">llvm.eh.selector.i64</a>(i8*, i8*, i8*, ...) + i32 %<a href="#llvm_eh_selector">llvm.eh.selector</a>(i8*, i8*, i8*, ...) </pre> <p>This intrinsic is used to compare the exception with the given type infos, -filters and cleanups.</p> + filters and cleanups.</p> <p><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> takes a minimum of -three arguments. The first argument is the reference to the exception -structure. The second argument is a reference to the personality function to be -used for this try catch sequence. Each of the remaining arguments is either a -reference to the type info for a catch statement, -a <a href="#throw_filters">filter</a> expression, -or the number zero representing a <a href="#cleanups">cleanup</a>. -The exception is tested against the arguments sequentially from first to last. -The result of the <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> is a -positive number if the exception matched a type info, a negative number if it matched -a filter, and zero if it matched a cleanup. If nothing is matched, the behaviour of -the program is <a href="#restrictions">undefined</a>. -If a type info matched then the selector value is the index of the type info in -the exception table, which can be obtained using the -<a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic.</p> + three arguments. The first argument is the reference to the exception + structure. The second argument is a reference to the personality function to + be used for this try catch sequence. Each of the remaining arguments is + either a reference to the type info for a catch statement, + a <a href="#throw_filters">filter</a> expression, or the number zero + representing a <a href="#cleanups">cleanup</a>. The exception is tested + against the arguments sequentially from first to last. The result of + the <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> is a positive + number if the exception matched a type info, a negative number if it matched + a filter, and zero if it matched a cleanup. If nothing is matched, the + behaviour of the program is <a href="#restrictions">undefined</a>. If a type + info matched then the selector value is the index of the type info in the + exception table, which can be obtained using the + <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic.</p> </div> @@ -390,15 +448,15 @@ the exception table, which can be obtained using the </div> <div class="doc_text"> + <pre> - i32 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for.i32</a>(i8*) - i64 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for.i64</a>(i8*) + i32 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for</a>(i8*) </pre> <p>This intrinsic returns the type info index in the exception table of the -current function. This value can be used to compare against the result of <a -href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>. The single argument is -a reference to a type info.</p> + current function. This value can be used to compare against the result + of <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>. The single + argument is a reference to a type info.</p> </div> @@ -408,23 +466,47 @@ a reference to a type info.</p> </div> <div class="doc_text"> + <pre> i32 %<a href="#llvm_eh_sjlj_setjmp">llvm.eh.sjlj.setjmp</a>(i8*) </pre> -<p>The SJLJ exception handling uses this intrinsic to force register saving -for the current function and to store the address of the following instruction -for use as a destination address by <a href="#llvm_eh_sjlj_setjmp"> -<tt>llvm.eh.sjlj.longjmp</tt></a>. The buffer format and the overall functioning -of this intrinsic is compatible with the GCC <tt>__builtin_setjmp</tt> -implementation, allowing code built with the two compilers to interoperate.</p> +<p>The SJLJ exception handling uses this intrinsic to force register saving for + the current function and to store the address of the following instruction + for use as a destination address by <a href="#llvm_eh_sjlj_longjmp"> + <tt>llvm.eh.sjlj.longjmp</tt></a>. The buffer format and the overall + functioning of this intrinsic is compatible with the GCC + <tt>__builtin_setjmp</tt> implementation, allowing code built with the + two compilers to interoperate.</p> + +<p>The single parameter is a pointer to a five word buffer in which the calling + context is saved. The front end places the frame pointer in the first word, + and the target implementation of this intrinsic should place the destination + address for a + <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a> in the + second word. The following three words are available for use in a + target-specific manner.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsubsection"> + <a name="llvm_eh_sjlj_lsda">llvm.eh.sjlj.lsda</a> +</div> + +<div class="doc_text"> + +<pre> + i8* %<a href="#llvm_eh_sjlj_lsda">llvm.eh.sjlj.lsda</a>( ) +</pre> + +<p>Used for SJLJ based exception handling, the <a href="#llvm_eh_sjlj_lsda"> + <tt>llvm.eh.sjlj.lsda</tt></a> intrinsic returns the address of the Language + Specific Data Area (LSDA) for the current function. The SJLJ front-end code + stores this address in the exception handling function context for use by the + runtime.</p> -<p>The single parameter is a pointer to a five word buffer in which the -calling context is saved. The front end places the frame pointer in the -first word, and the target implementation of this intrinsic should place the -destination address for a <a href="#llvm_eh_sjlj_longjmp"><tt> -llvm.eh.sjlj.longjmp</tt></a> in the second word. The following three words -are available for use in a target-specific manner.</p> +</div> <!-- ======================================================================= --> <div class="doc_section"> @@ -434,7 +516,7 @@ are available for use in a target-specific manner.</p> <div class="doc_text"> <p>There are two tables that are used by the exception handling runtime to -determine which actions should take place when an exception is thrown.</p> + determine which actions should take place when an exception is thrown.</p> </div> @@ -446,11 +528,11 @@ determine which actions should take place when an exception is thrown.</p> <div class="doc_text"> <p>An exception handling frame <tt>eh_frame</tt> is very similar to the unwind -frame used by dwarf debug info. The frame contains all the information -necessary to tear down the current frame and restore the state of the prior -frame. There is an exception handling frame for each function in a compile -unit, plus a common exception handling frame that defines information common to -all functions in the unit.</p> + frame used by dwarf debug info. The frame contains all the information + necessary to tear down the current frame and restore the state of the prior + frame. There is an exception handling frame for each function in a compile + unit, plus a common exception handling frame that defines information common + to all functions in the unit.</p> <p>Todo - Table details here.</p> @@ -464,9 +546,9 @@ all functions in the unit.</p> <div class="doc_text"> <p>An exception table contains information about what actions to take when an -exception is thrown in a particular part of a function's code. There is -one exception table per function except leaf routines and functions that have -only calls to non-throwing functions will not need an exception table.</p> + exception is thrown in a particular part of a function's code. There is one + exception table per function except leaf routines and functions that have + only calls to non-throwing functions will not need an exception table.</p> <p>Todo - Table details here.</p> @@ -481,7 +563,7 @@ only calls to non-throwing functions will not need an exception table.</p> <ol> -<li><p>Testing/Testing/Testing.</p></li> + <li>Testing/Testing/Testing.</li> </ol> @@ -498,7 +580,7 @@ only calls to non-throwing functions will not need an exception table.</p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-05-14 17:44:15 +0200 (Thu, 14 May 2009) $ + Last modified: $Date: 2009-10-14 18:11:37 +0200 (Wed, 14 Oct 2009) $ </address> </body> diff --git a/docs/FAQ.html b/docs/FAQ.html index 9fd8928..0074638 100644 --- a/docs/FAQ.html +++ b/docs/FAQ.html @@ -685,7 +685,7 @@ Stop. <p>Also, there are a number of other limitations of the C backend that cause it to produce code that does not fully conform to the C++ ABI on most platforms. Some of the C++ programs in LLVM's test suite are known to fail - when compiled with the C back end because of ABI incompatiblities with + when compiled with the C back end because of ABI incompatibilities with standard C++ libraries.</p> </div> @@ -700,7 +700,7 @@ Stop. portable is by using the preprocessor to include platform-specific code. In practice, information about other platforms is lost after preprocessing, so the result is inherently dependent on the platform that the preprocessing was - targetting.</p> + targeting.</p> <p>Another example is <tt>sizeof</tt>. It's common for <tt>sizeof(long)</tt> to vary between platforms. In most C front-ends, <tt>sizeof</tt> is expanded to @@ -931,7 +931,7 @@ F.i: src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-06-30 19:10:19 +0200 (Tue, 30 Jun 2009) $ + Last modified: $Date: 2009-10-12 16:46:08 +0200 (Mon, 12 Oct 2009) $ </address> </body> diff --git a/docs/GCCFEBuildInstrs.html b/docs/GCCFEBuildInstrs.html index 9d2243f..873faa6 100644 --- a/docs/GCCFEBuildInstrs.html +++ b/docs/GCCFEBuildInstrs.html @@ -88,6 +88,7 @@ top-level <tt>README.LLVM</tt> file, adding ",ada" to EXTRALANGS, for example: are <a href="http://gcc.gnu.org/releases.html">gcc-4.2</a> and the 2005, 2006 and 2007 versions of the <a href="http://libre.adacore.com/">GNAT GPL Edition</a>. + <b>GNAT GPL 2008, gcc-4.3 and later will not work</b>. The LLVM parts of llvm-gcc are written in C++ so a C++ compiler is needed to build them. The rest of gcc is written in C. Some linux distributions provide a version of gcc that supports all @@ -271,7 +272,7 @@ More information is <a href="FAQ.html#license">available in the FAQ</a>. src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-04-27 13:21:35 +0200 (Mon, 27 Apr 2009) $ + Last modified: $Date: 2009-07-05 14:01:44 +0200 (Sun, 05 Jul 2009) $ </address> </body> diff --git a/docs/GarbageCollection.html b/docs/GarbageCollection.html index 562025f..a372f69 100644 --- a/docs/GarbageCollection.html +++ b/docs/GarbageCollection.html @@ -334,11 +334,11 @@ void visitGCRoots(void (*Visitor)(void **Root, const void *Meta)) { // For roots [0, NumMeta), the metadata pointer is in the FrameMap. for (unsigned e = R->Map->NumMeta; i != e; ++i) - Visitor(&R->Roots[i], R->Map->Meta[i]); + Visitor(&R->Roots[i], R->Map->Meta[i]); // For roots [NumMeta, NumRoots), the metadata pointer is null. for (unsigned e = R->Map->NumRoots; i != e; ++i) - Visitor(&R->Roots[i], NULL); + Visitor(&R->Roots[i], NULL); } }</pre></div> @@ -398,7 +398,7 @@ program.</p> </div> <div class="doc_code"><tt> - define <i>ty</i> @<i>name</i>(...) <u>gc "<i>name</i>"</u> { ... + define <i>ty</i> @<i>name</i>(...) <span style="text-decoration: underline">gc "<i>name</i>"</span> { ... </tt></div> <div class="doc_text"> @@ -1380,7 +1380,7 @@ Fergus Henderson. International Symposium on Memory Management 2002.</p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-05-13 20:02:09 +0200 (Wed, 13 May 2009) $ + Last modified: $Date: 2009-08-05 17:42:44 +0200 (Wed, 05 Aug 2009) $ </address> </body> diff --git a/docs/GetElementPtr.html b/docs/GetElementPtr.html index f4b096a..d5863e8 100644 --- a/docs/GetElementPtr.html +++ b/docs/GetElementPtr.html @@ -40,7 +40,7 @@ <div class="doc_text"> <p>This document seeks to dispel the mystery and confusion surrounding LLVM's GetElementPtr (GEP) instruction. Questions about the wiley GEP instruction are - probably the most frequently occuring questions once a developer gets down to + probably the most frequently occurring questions once a developer gets down to coding with LLVM. Here we lay out the sources of confusion and show that the GEP instruction is really quite simple. </p> @@ -303,13 +303,14 @@ idx3 = (char*) &MyVar + 8 </div> <p>In this example, <tt>idx1</tt> computes the address of the second integer - in the array that is in the structure in %MyVar, that is <tt>MyVar+4</tt>. The - type of <tt>idx1</tt> is <tt>i32*</tt>. However, <tt>idx2</tt> computes the - address of <i>the next</i> structure after <tt>%MyVar</tt>. The type of - <tt>idx2</tt> is <tt>{ [10 x i32] }*</tt> and its value is equivalent - to <tt>MyVar + 40</tt> because it indexes past the ten 4-byte integers - in <tt>MyVar</tt>. Obviously, in such a situation, the pointers don't - alias.</p> + in the array that is in the structure in <tt>%MyVar</tt>, that is + <tt>MyVar+4</tt>. The type of <tt>idx1</tt> is <tt>i32*</tt>. However, + <tt>idx2</tt> computes the address of <i>the next</i> structure after + <tt>%MyVar</tt>. The type of <tt>idx2</tt> is <tt>{ [10 x i32] }*</tt> and its + value is equivalent to <tt>MyVar + 40</tt> because it indexes past the ten + 4-byte integers in <tt>MyVar</tt>. Obviously, in such a situation, the + pointers don't alias.</p> + </div> <!-- *********************************************************************** --> @@ -364,7 +365,7 @@ idx3 = (char*) &MyVar + 8 <a href="http://validator.w3.org/check/referer"><img src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br/> - Last modified: $Date: 2008-12-11 19:23:24 +0100 (Thu, 11 Dec 2008) $ + Last modified: $Date: 2009-10-12 16:46:08 +0200 (Mon, 12 Oct 2009) $ </address> </body> </html> diff --git a/docs/GettingStarted.html b/docs/GettingStarted.html index 26a4688..8a8bce3 100644 --- a/docs/GettingStarted.html +++ b/docs/GettingStarted.html @@ -216,11 +216,21 @@ software you will need.</p> <th>Compilers</th> </tr> <tr> + <td>AuroraUX</td> + <td>x86<sup><a href="#pf_1">1</a></sup></td> + <td>GCC</td> +</tr> +<tr> <td>Linux</td> <td>x86<sup><a href="#pf_1">1</a></sup></td> <td>GCC</td> </tr> <tr> + <td>Linux</td> + <td>amd64</td> + <td>GCC</td> +</tr> +<tr> <td>Solaris</td> <td>V9 (Ultrasparc)</td> <td>GCC</td> @@ -239,7 +249,6 @@ software you will need.</p> <td>MacOS X<sup><a href="#pf_2">2</a>,<a href="#pf_9">9</a></sup></td> <td>x86</td> <td>GCC</td> - </tr> <tr> <td>Cygwin/Win32</td> @@ -248,14 +257,10 @@ software you will need.</p> </tr> <tr> <td>MinGW/Win32</td> - <td>x86<sup><a href="#pf_1">1</a>,<a href="#pf_6">6</a>,<a href="#pf_8">8</a></sup></td> + <td>x86<sup><a href="#pf_1">1</a>,<a href="#pf_6">6</a>, + <a href="#pf_8">8</a>, <a href="#pf_10">10</a></sup></td> <td>GCC 3.4.X, binutils 2.15</td> </tr> -<tr> - <td>Linux</td> - <td>amd64</td> - <td>GCC</td> -</tr> </table> <p>LLVM has partial support for the following platforms:</p> @@ -321,6 +326,11 @@ up</a></li> levels greater than 0 (i.e., <i>"-O1"</i> and higher). Add <i>OPTIMIZE_OPTION="-O0"</i> to the build command line if compiling for LLVM Release or bootstrapping the LLVM toolchain.</li> +<li><a name="pf_10">For MSYS/MinGW on Windows, be sure to install the MSYS + version of the perl package, and be sure it appears in your path + before any Windows-based versions such as Strawberry Perl and + ActivePerl, as these have Windows-specifics that will cause the + build to fail.</a></li> </ol> </div> @@ -410,19 +420,19 @@ href="GCCFEBuildInstrs.html">try to compile it</a> on your platform.</p> <tr> <td><a href="http://www.gnu.org/software/autoconf">GNU Autoconf</a></td> - <td>2.59</td> + <td>2.60</td> <td>Configuration script builder<sup><a href="#sf4">4</a></sup></td> </tr> <tr> <td><a href="http://www.gnu.org/software/automake">GNU Automake</a></td> - <td>1.9.2</td> + <td>1.9.6</td> <td>aclocal macro generator<sup><a href="#sf4">4</a></sup></td> </tr> <tr> <td><a href="http://savannah.gnu.org/projects/libtool">libtool</a></td> - <td>1.5.10</td> + <td>1.5.22</td> <td>Shared library manager<sup><a href="#sf4">4</a></sup></td> </tr> @@ -548,7 +558,10 @@ as the previous one. It appears to work with ENABLE_OPTIMIZED=0 (the default).</ <p><b>Cygwin GCC 4.3.2 20080827 (beta) 2</b>: Users <a href="http://llvm.org/PR4145">reported</a> various problems related with link errors when using this GCC version.</p> - +<p><b>Debian GCC 4.3.2 on X86</b>: Crashes building some files in LLVM 2.6.</p> +<p><b>GCC 4.3.3 (Debian 4.3.3-10) on ARM</b>: Miscompiles parts of LLVM 2.6 +when optimizations are turned on. The symptom is an infinite loop in +FoldingSetImpl::RemoveNode while running the code generator.</p> <p><b>GNU ld 2.16.X</b>. Some 2.16.X versions of the ld linker will produce very long warning messages complaining that some ".gnu.linkonce.t.*" symbol was defined in a discarded section. You can safely ignore these messages as they are @@ -1622,7 +1635,7 @@ out:</p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.x10sys.com/rspencer/">Reid Spencer</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-05-04 12:24:46 +0200 (Mon, 04 May 2009) $ + Last modified: $Date: 2009-09-27 06:56:27 +0200 (Sun, 27 Sep 2009) $ </address> </body> </html> diff --git a/docs/GettingStartedVS.html b/docs/GettingStartedVS.html index 809fda0..c002450 100644 --- a/docs/GettingStartedVS.html +++ b/docs/GettingStartedVS.html @@ -140,15 +140,15 @@ <li>If you used CMake, then the directory you created the project files, the root directory will have an <tt>llvm.sln</tt> file, just double-click on that to open Visual Studio.</li> - </ol></li> + </ul></li> <li>Build the LLVM Suite: - <ol> + <ul> <li>Simply build the solution.</li> <li>The Fibonacci project is a sample program that uses the JIT. Modify the project's debugging properties to provide a numeric command line argument. The program will print the corresponding fibonacci value.</li> - </ol></li> + </ul></li> </ol> @@ -411,7 +411,7 @@ out:</p> <a href="mailto:jeffc@jolt-lang.org">Jeff Cohen</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-04-03 22:32:13 +0200 (Fri, 03 Apr 2009) $ + Last modified: $Date: 2009-08-05 17:42:44 +0200 (Wed, 05 Aug 2009) $ </address> </body> </html> diff --git a/docs/GoldPlugin.html b/docs/GoldPlugin.html index b5148ab..77a417f 100644 --- a/docs/GoldPlugin.html +++ b/docs/GoldPlugin.html @@ -127,8 +127,9 @@ void foo4(void) { --- command lines --- $ llvm-gcc -flto a.c -c -o a.o # <-- a.o is LLVM bitcode file +$ ar q a.a a.o # <-- a.a is an archive with LLVM bitcode $ llvm-gcc b.c -c -o b.o # <-- b.o is native object file -$ llvm-gcc -use-gold-plugin a.o b.o -o main # <-- link with LLVMgold plugin +$ llvm-gcc -use-gold-plugin a.a b.o -o main # <-- link with LLVMgold plugin </pre> <p>Gold informs the plugin that foo3 is never referenced outside the IR, leading LLVM to delete that function. However, unlike in the diff --git a/docs/HistoricalNotes/2007-OriginalClangReadme.txt b/docs/HistoricalNotes/2007-OriginalClangReadme.txt new file mode 100644 index 0000000..611dc9d --- /dev/null +++ b/docs/HistoricalNotes/2007-OriginalClangReadme.txt @@ -0,0 +1,178 @@ +//===----------------------------------------------------------------------===// +// C Language Family Front-end +//===----------------------------------------------------------------------===// + Chris Lattner + +I. Introduction: + + clang: noun + 1. A loud, resonant, metallic sound. + 2. The strident call of a crane or goose. + 3. C-language family front-end toolkit. + + The world needs better compiler tools, tools which are built as libraries. This + design point allows reuse of the tools in new and novel ways. However, building + the tools as libraries isn't enough: they must have clean APIs, be as + decoupled from each other as possible, and be easy to modify/extend. This + requires clean layering, decent design, and avoiding tying the libraries to a + specific use. Oh yeah, did I mention that we want the resultant libraries to + be as fast as possible? :) + + This front-end is built as a component of the LLVM toolkit that can be used + with the LLVM backend or independently of it. In this spirit, the API has been + carefully designed as the following components: + + libsupport - Basic support library, reused from LLVM. + + libsystem - System abstraction library, reused from LLVM. + + libbasic - Diagnostics, SourceLocations, SourceBuffer abstraction, + file system caching for input source files. This depends on + libsupport and libsystem. + + libast - Provides classes to represent the C AST, the C type system, + builtin functions, and various helpers for analyzing and + manipulating the AST (visitors, pretty printers, etc). This + library depends on libbasic. + + + liblex - C/C++/ObjC lexing and preprocessing, identifier hash table, + pragma handling, tokens, and macros. This depends on libbasic. + + libparse - C (for now) parsing and local semantic analysis. This library + invokes coarse-grained 'Actions' provided by the client to do + stuff (e.g. libsema builds ASTs). This depends on liblex. + + libsema - Provides a set of parser actions to build a standardized AST + for programs. AST's are 'streamed' out a top-level declaration + at a time, allowing clients to use decl-at-a-time processing, + build up entire translation units, or even build 'whole + program' ASTs depending on how they use the APIs. This depends + on libast and libparse. + + librewrite - Fast, scalable rewriting of source code. This operates on + the raw syntactic text of source code, allowing a client + to insert and delete text in very large source files using + the same source location information embedded in ASTs. This + is intended to be a low-level API that is useful for + higher-level clients and libraries such as code refactoring. + + libanalysis - Source-level dataflow analysis useful for performing analyses + such as computing live variables. It also includes a + path-sensitive "graph-reachability" engine for writing + analyses that reason about different possible paths of + execution through source code. This is currently being + employed to write a set of checks for finding bugs in software. + + libcodegen - Lower the AST to LLVM IR for optimization & codegen. Depends + on libast. + + clang - An example driver, client of the libraries at various levels. + This depends on all these libraries, and on LLVM VMCore. + + This front-end has been intentionally built as a DAG of libraries, making it + easy to reuse individual parts or replace pieces if desired. For example, to + build a preprocessor, you take the Basic and Lexer libraries. If you want an + indexer, you take those plus the Parser library and provide some actions for + indexing. If you want a refactoring, static analysis, or source-to-source + compiler tool, it makes sense to take those plus the AST building and semantic + analyzer library. Finally, if you want to use this with the LLVM backend, + you'd take these components plus the AST to LLVM lowering code. + + In the future I hope this toolkit will grow to include new and interesting + components, including a C++ front-end, ObjC support, and a whole lot of other + things. + + Finally, it should be pointed out that the goal here is to build something that + is high-quality and industrial-strength: all the obnoxious features of the C + family must be correctly supported (trigraphs, preprocessor arcana, K&R-style + prototypes, GCC/MS extensions, etc). It cannot be used if it is not 'real'. + + +II. Usage of clang driver: + + * Basic Command-Line Options: + - Help: clang --help + - Standard GCC options accepted: -E, -I*, -i*, -pedantic, -std=c90, etc. + - To make diagnostics more gcc-like: -fno-caret-diagnostics -fno-show-column + - Enable metric printing: -stats + + * -fsyntax-only is currently the default mode. + + * -E mode works the same way as GCC. + + * -Eonly mode does all preprocessing, but does not print the output, + useful for timing the preprocessor. + + * -fsyntax-only is currently partially implemented, lacking some + semantic analysis (some errors and warnings are not produced). + + * -parse-noop parses code without building an AST. This is useful + for timing the cost of the parser without including AST building + time. + + * -parse-ast builds ASTs, but doesn't print them. This is most + useful for timing AST building vs -parse-noop. + + * -parse-ast-print pretty prints most expression and statements nodes. + + * -parse-ast-check checks that diagnostic messages that are expected + are reported and that those which are reported are expected. + + * -dump-cfg builds ASTs and then CFGs. CFGs are then pretty-printed. + + * -view-cfg builds ASTs and then CFGs. CFGs are then visualized by + invoking Graphviz. + + For more information on getting Graphviz to work with clang/LLVM, + see: http://llvm.org/docs/ProgrammersManual.html#ViewGraph + + +III. Current advantages over GCC: + + * Column numbers are fully tracked (no 256 col limit, no GCC-style pruning). + * All diagnostics have column numbers, includes 'caret diagnostics', and they + highlight regions of interesting code (e.g. the LHS and RHS of a binop). + * Full diagnostic customization by client (can format diagnostics however they + like, e.g. in an IDE or refactoring tool) through DiagnosticClient interface. + * Built as a framework, can be reused by multiple tools. + * All languages supported linked into same library (no cc1,cc1obj, ...). + * mmap's code in read-only, does not dirty the pages like GCC (mem footprint). + * LLVM License, can be linked into non-GPL projects. + * Full diagnostic control, per diagnostic. Diagnostics are identified by ID. + * Significantly faster than GCC at semantic analysis, parsing, preprocessing + and lexing. + * Defers exposing platform-specific stuff to as late as possible, tracks use of + platform-specific features (e.g. #ifdef PPC) to allow 'portable bytecodes'. + * The lexer doesn't rely on the "lexer hack": it has no notion of scope and + does not categorize identifiers as types or variables -- this is up to the + parser to decide. + +Potential Future Features: + + * Fine grained diag control within the source (#pragma enable/disable warning). + * Better token tracking within macros? (Token came from this line, which is + a macro argument instantiated here, recursively instantiated here). + * Fast #import with a module system. + * Dependency tracking: change to header file doesn't recompile every function + that texually depends on it: recompile only those functions that need it. + This is aka 'incremental parsing'. + + +IV. Missing Functionality / Improvements + +Lexer: + * Source character mapping. GCC supports ASCII and UTF-8. + See GCC options: -ftarget-charset and -ftarget-wide-charset. + * Universal character support. Experimental in GCC, enabled with + -fextended-identifiers. + * -fpreprocessed mode. + +Preprocessor: + * #assert/#unassert + * MSExtension: "L#param" stringizes to a wide string literal. + * Add support for -M* + +Traditional Preprocessor: + * Currently, we have none. :) + diff --git a/docs/HowToReleaseLLVM.html b/docs/HowToReleaseLLVM.html index 53945a5..d6ef416 100644 --- a/docs/HowToReleaseLLVM.html +++ b/docs/HowToReleaseLLVM.html @@ -10,14 +10,15 @@ <div class="doc_title">How To Release LLVM To The Public</div> <ol> <li><a href="#introduction">Introduction</a></li> + <li><a href="#criteria">Qualification Criteria</a></li> <li><a href="#introduction">Release Timeline</a></li> <li><a href="#process">Release Process</a></li> - <li><a href="#dist_targets">Distribution Targets</a></li> </ol> <div class="doc_author"> - <p>Written by <a href="mailto:rspencer@x10sys.com">Reid Spencer</a>, - <a href="mailto:criswell@cs.uiuc.edu">John Criswell</a>, - <a href="mailto:tonic@nondot.org">Tanya Lattner</a></p> + <p>Written by <a href="mailto:tonic@nondot.org">Tanya Lattner</a>, + <a href="mailto:rspencer@x10sys.com">Reid Spencer</a>, + <a href="mailto:criswell@cs.uiuc.edu">John Criswell</a> + </p> </div> <!-- *********************************************************************** --> @@ -26,32 +27,23 @@ <div class="doc_text"> <p> - This document collects information about successfully releasing LLVM to the - public. It is the release manager's guide to ensuring that a high quality + This document collects information about successfully releasing LLVM + (including subprojects llvm-gcc and Clang) to the public. + It is the release manager's responsibility to ensure that a high quality build of LLVM is released. </p> - - <p> - The following is the basic criteria for releasing LLVM: - </p> - - <ol> - <li>Successful configure and build.</li> - <li>Clean 'make check'.</li> - <li>No regressions in the testsuite from the previous release. This may - include performance regressions for major benchmarks.</li> - </ol> </div> <!-- *********************************************************************** --> <div class="doc_section"><a name="process">Release Timeline</a></div> <!-- *********************************************************************** --> <div class="doc_text"> -The release manager should attempt to have a release every 3-4 months because LLVM -does time based releases (instead of feature based). The release schedule should -be roughly as follows: + <p>LLVM is released on a time based schedule (currently every 6 months). We + do not have dot releases because of the nature of LLVM incremental + development philosophy. The release schedule is roughly as follows: + </p> <ol> -<li>Set code freeze and branch creation date for 3 months after last release +<li>Set code freeze and branch creation date for 6 months after last code freeze date. Announce release schedule to the LLVM community and update the website.</li> <li>Create release branch and begin release process. </li> <li>Send out pre-release for first round of testing. Testing will last 7-10 days. @@ -71,44 +63,76 @@ pre-release testing.</li> <div class="doc_section"><a name="process">Release Process</a></div> <!-- *********************************************************************** --> -<!-- ======================================================================= --> -<div class="doc_subsection"><a name="overview">Process Overview</a></div> <div class="doc_text"> <ol> + <li><a href="#release-admin">Release Administrative Tasks</a></li> + <ol> <li><a href="#branch">Create Release Branch</a></li> - <li><a href="#verchanges">Update LLVM Version </a></li> + <li><a href="#verchanges">Update Version Numbers</a></li> + </ol> + <li><a href="#release-build">Building the Release</a></li> + <ol> <li><a href="#dist">Build the LLVM Source Distributions</a></li> <li><a href="#build">Build LLVM</a></li> - <li><a href="#llvmgccbin">Build the LLVM GCC Binary Distribution</a></li> - <li><a href="#rpm">Build RPM Packages (optional)</a></li> - <li><a href="#check">Run 'make check'</a></li> - <li><a href="#test">Run LLVM Test Suite</a></li> - <li><a href="#prerelease">Pre-Release Testing</a></li> - <li><a href="#tag">Tag the LLVM Release Branch</a></li> + <li><a href="#llvmgccbin">Build the LLVM-GCC Binary Distribution</a></li> + <li><a href="#clangbin">Build the Clang Binary Distribution</a></li> + <li><a href="#target-build">Target Specific Build Details</a></li> + </ol> + + <li><a href="#release-qualify">Release Qualification Criteria</a></li> + <ol> + <li><a href="#llvm-qualify">Qualify LLVM</a></li> + <li><a href="#llvmgcc-qualify">Qualify LLVM-GCC</a></li> + <li><a href="#clang-qualify">Qualify Clang</a></li> + <li><a href="#targets">Specific Target Qualification Details</a></li> + </ol> + + <li><a href="#commTest">Community Testing</a></li> + <li><a href="#release-patch">Release Patch Rules</a></li> + + + <li><a href="#release-final">Release final tasks</a></li> + <ol> <li><a href="#updocs">Update Documentation</a></li> + <li><a href="#tag">Tag the LLVM Release Branch</a></li> <li><a href="#updemo">Update the LLVM Demo Page</a></li> <li><a href="#webupdates">Update the LLVM Website</a></li> <li><a href="#announce">Announce the Release</a></li> + </ol> </ol> </div> <!-- ======================================================================= --> -<div class="doc_subsection"><a name="branch">Create Release Branch</a></div> +<div class="doc_subsection"><a name="release-admin"> +Release Administrative Tasks</a></div> + +<div class="doc_text"> +This section describes a few administrative tasks that need to be done for the +release process to begin. Specifically, it involves creating the release branch, + resetting version numbers, and creating the release tarballs for the release + team to begin testing. +</div> + +<!-- ======================================================================= --> +<div class="doc_subsubsection"><a name="branch">Create Release Branch</a></div> <div class="doc_text"> <p>Branch the Subversion HEAD using the following procedure:</p> <ol> <li> - <p>Verify that the current Subversion HEAD is in decent shape by examining nightly - tester results.</p></li> + <p>Verify that the current Subversion HEAD is in decent shape by examining + nightly tester or buildbot results.</p></li> <li> <p>Request all developers to refrain from committing. Offenders get commit rights taken away (temporarily).</p></li> <li> - <p> Create the release branch for <tt>llvm</tt>, <tt>llvm-gcc4.2</tt>, and - the <tt>test-suite</tt>. The branch name will be <tt>release_XX</tt>, - where <tt>XX</tt> is the major and minor release numbers. These branches can - be created without checking out anything from subversion. + <p> Create the release branch for <tt>llvm</tt>, <tt>llvm-gcc4.2</tt>, + <tt>clang</tt>, and the <tt>test-suite</tt>. The branch name will be + <tt>release_XX</tt>,where <tt>XX</tt> is the major and minor release numbers. + <tt>Clang</tt> will have a different release number than <tt>llvm</tt>/ + <tt>llvm-gcc4</tt> since its first release was years later + (still deciding if this will be true or not). These branches + can be created without checking out anything from subversion. </p> <div class="doc_code"> @@ -119,6 +143,8 @@ svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk \ https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_<i>XX</i> svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \ https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XX</i> +svn copy https://llvm.org/svn/llvm-project/cfe/trunk \ + https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XX</i> </pre> </div> @@ -135,34 +161,36 @@ svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XX</i> svn co https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_<i>XX</i> svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XX</i> +svn co https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XX</i> </pre> </div></li> -</div> </ol> </div> <!-- ======================================================================= --> -<div class="doc_subsection"><a name="verchanges">Update LLVM Version</a></div> +<div class="doc_subsubsection"><a name="verchanges">Update LLVM Version</a></div> <div class="doc_text"> <p> After creating the LLVM release branch, update the release branches' autoconf/configure.ac version from X.Xsvn to just X.X. Update it on mainline as well to be the next version (X.X+1svn). Regenerated the configure script - for both. This must be done for both llvm and the test-suite. + for both. This must be done for both <tt>llvm</tt> and the + <tt>test-suite</tt>. </p> + <p>FIXME: Add a note about <tt>clang</tt>.</p> <p>In addition, the version number of all the Bugzilla components must be updated for the next release. </p> </div> <!-- ======================================================================= --> -<div class="doc_subsection"><a name="dist">Build the LLVM Source Distributions</a></div> +<div class="doc_subsubsection"><a name="dist">Build the LLVM Source Distributions</a></div> <div class="doc_text"> <p> - Create source distributions for LLVM, LLVM GCC, and the LLVM Test Suite by - exporting the source from Subversion and archiving it. This can be done with - the following commands: + Create source distributions for <tt>LLVM</tt>, <tt>LLVM-GCC</tt>, + <tt>clang</tt>, and the llvm <tt>test-suite</tt> by exporting the source from + Subversion and archiving it. This can be done with the following commands: </p> <div class="doc_code"> @@ -170,25 +198,43 @@ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XX</i> svn export https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XX</i> llvm-X.X svn export https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_<i>XX</i> llvm-gcc4.2-X.X.source svn export https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XX</i> llvm-test-X.X -tar -cvf - llvm-X.X | gzip > llvm-X.X.tar.gz -tar -cvf - llvm-test-X.X | gzip > llvm-test-X.X.tar.gz -tar -cvf - llvm-gcc4.2-X.X.source | gzip > llvm-gcc-4.2-X.X.source.tar.gz +svn export https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XX</i> clang-X.X +tar -czvf - llvm-X.X | gzip > llvm-X.X.tar.gz +tar -czvf - llvm-test-X.X | gzip > llvm-test-X.X.tar.gz +tar -czvf - llvm-gcc4.2-X.X.source | gzip > llvm-gcc-4.2-X.X.source.tar.gz +tar -czvf - clang-X.X | gzip > clang-X.X.tar.gz </pre> </div> </div> <!-- ======================================================================= --> -<div class="doc_subsection"><a name="build">Build LLVM</a></div> +<div class="doc_subsection"><a name="release-build"> +Building the Release</a></div> + +<div class="doc_text"> +The build of <tt>llvm</tt>, <tt>llvm-gcc</tt>, and <tt>clang</tt> must be free +of errors and warnings in both debug, release, and release-asserts builds. +If all builds are clean, then the release passes build qualification. + +<ol> +<li>debug: ENABLE_OPTIMIZED=0</li> +<li>release: ENABLE_OPTIMIZED=1</li> +<li>release-asserts: ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1</li> +</ol> +</div> + +<!-- ======================================================================= --> +<div class="doc_subsubsection"><a name="build">Build LLVM</a></div> <div class="doc_text"> <p> - Build both debug and release (optimized) versions of LLVM on all - platforms. Ensure the build is warning and error free on each platform. - Note that when building the LLVM GCC Binary, use a release build of LLVM. + Build both debug, release (optimized), and release-asserts versions of + LLVM on all supported platforms. Direction to build llvm are + <a href="http://llvm.org/docs/GettingStarted.html#quickstart">here</a>. </p> </div> <!-- ======================================================================= --> -<div class="doc_subsection"><a name="llvmgccbin">Build the LLVM GCC Binary Distribution</a></div> +<div class="doc_subsubsection"><a name="llvmgccbin">Build the LLVM GCC Binary Distribution</a></div> <div class="doc_text"> <p> Creating the LLVM GCC binary distribution (release/optimized) requires @@ -198,128 +244,202 @@ tar -cvf - llvm-gcc4.2-X.X.source | gzip > llvm-gcc-4.2-X.X.source.tar.gz <ol> <li> Build the LLVM GCC front-end by following the directions in the README.LLVM - file. Be sure to build with LLVM_VERSION_INFO=X.X, where X is the major and + file. The frontend must be compiled with c, c++, objc (mac only), + objc++ (mac only) and fortran support. </li> + <li>Please boostrap as well.</li> + <li>Be sure to build with LLVM_VERSION_INFO=X.X, where X is the major and minor release numbers. </li> <li> Copy the installation directory to a directory named for the specific target. For example on Red Hat Enterprise Linux, the directory would be named - <tt>llvm-gcc4.0-2.1-x86-linux-RHEL4</tt>. Archive and compress the new directory. + <tt>llvm-gcc4.2-2.6-x86-linux-RHEL4</tt>. Archive and compress the new directory. </li> </ol> </div> <!-- ======================================================================= --> -<div class="doc_subsection"><a name="check">Run 'make check'</a></div> +<div class="doc_subsubsection"><a name="clangbin">Build Clang +Binary Distribution</a></div> <div class="doc_text"> <p> - Using the newly built llvm-gcc and llvm, reconfigure llvm to locate llvm-gcc. - Run <tt>make check</tt> and ensure there are no unexpected failures. If there - are, resolve the failures or file a bug. If there is a fix commited to mainline, - merge back into the release branch, and restart testing by - <a href="#build">re-building LLVM</a> and <a href="#build">llvm-gcc</a>. If no - fix will be made, XFAIL the test and commit back to the release branch. + Creating the Clang binary distribution (debug/release/release-asserts) requires + performing the following steps for each supported platform: </p> + <ol> + <li> + Build clang according to the directions + <a href="http://clang.llvm.org/get_started.html">here</a>. + </li> + + <li>Build both a debug and release version of clang, but the binary + will be a release build.</lI> + + <li> + Package clang (details to follow). + </li> + </ol> +</div> + + +<!-- ======================================================================= --> +<div class="doc_subsubsection"><a name="target-build">Target Specific Build +Details</a></div> +<div class="doc_text"> <p> - Ensure that '<tt>make check</tt>' passes on all platforms for all targets. The - test suite must complete with "0 unexpected failures" before sending out the - pre-releases for testing. + The table below specifies which compilers are used for each arch/os combination + when qualifying the build of <tt>llvm</tt>, <tt>llvm-gcc</tt>, <tt>clang. + </tt></p> + + <p> + <table> + <tr><th>Architecture</th><th>OS</th><th>compiler</th></tr> + <tr><td>x86-32</td><td>Mac OS 10.5</td><td>gcc 4.0.1</td></tr> + <tr><td>x86-32</td><td>Linux</td><td>gcc 4.2.X, gcc 4.3.X</td></tr> + <tr><td>x86-32</td><td>FreeBSD</td><td>gcc 4.2.X</td></tr> + <tr><td>x86-32</td><td>mingw</td><td>gcc 3.4.5</td></tr> + <tr><td>x86-64</td><td>Mac OS 10.5</td><td>gcc 4.0.1</td></tr> + <tr><td>x86-64</td><td>Linux</td><td>gcc 4.2.X, gcc 4.3.X</td></tr> + <tr><td>x86-64</td><td>FreeBSD</td><td>gcc 4.2.X</td></tr> + + </table> </p> + </div> + +<!-- ======================================================================= --> +<div class="doc_subsection"><a name="release-qualify"> +Building the Release</a></div> + +<div class="doc_text"> + A release is qualified when it has no regressions from the previous + release (or baseline). Regressions are related to correctness only and not + performance at this time. <b>Regressions are new failures in the set of tests that + are used to qualify each product and only include things on the list. + Ultimately, there is no end to the number of possible bugs in a release. We + need a very concrete and definitive release criteria that ensures we have + monotonically improving quality on some metric. The metric we use is + described below. This doesn't mean that we don't care about other things, + but this are things that must be satisfied before a release can go out</b> +</div> + + <!-- ======================================================================= --> -<div class="doc_subsection"><a name="test">LLVM Test Suite</a></div> +<div class="doc_subsubsection"><a name="llvm-qualify">Qualify LLVM</a></div> <div class="doc_text"> <p> - Run the <tt>llvm-test</tt> suite and ensure there are no unacceptable - failures. Unacceptable failures are regression from the previous release - and (optionally) major performance regressions from the previous release. - If a regression is found a bug is filled, but the pre-releases may still go - out.</p> + LLVM is qualified when it has a clean dejagnu test run without a frontend and + it has no regressions when using either <tt>llvm-gcc</tt> or <tt>clang</tt> + with the <tt>test-suite</tt> from the previous release. +</p> </div> <!-- ======================================================================= --> -<div class="doc_subsection"><a name="rpm">Building RPM packages (optional)</a></div> +<div class="doc_subsubsection"><a name="llvmgcc-qualify">Qualify LLVM-GCC</a></div> <div class="doc_text"> <p> - You can, optionally, create source and binary RPM packages for LLVM. These may - make it easier to get LLVM into a distribution. This can be done with the - following commands: - </p> + <tt>LLVM-GCC</tt> is qualified when front-end specific tests in the + <tt>llvm</tt> dejagnu test suite all pass and there are no regressions in + the <tt>test-suite</tt>.</p> + <p>We do not use the gcc dejagnu test suite as release criteria.</p> +</div> -<div class="doc_code"> -<pre> -make dist # Build the distribution source tarball -make dist-check # Check that the source tarball can build itself. -cp llvm-M.m.tar.gz /usr/src/redhat/SOURCES # Required by rpmbuild -make srpm # for source rpm -make rpm # for binary rpm -</pre> +<!-- ======================================================================= --> +<div class="doc_subsubsection"><a name="clang-qualify">Qualify Clang</a></div> +<div class="doc_text"> + <tt>Clang</tt> is qualified when front-end specific tests in the + <tt>llvm</tt> dejagnu test suite all pass, clang's own test suite passes + cleanly, and there are no regressions in the <tt>test-suite</tt>.</p> </div> - <p> - First, use <tt>make dist</tt> to simply build the distribution. Any failures - need to be corrected (on the branch). Once <tt>make dist</tt> can be - successful, do <tt>make dist-check</tt>. This target will do the same thing as - the 'dist' target but also test that distribution to make sure it can build - itself and runs <tt>make check</tt> as well. This ensures that needed files - are not missing and that the src tarball can be successfully unpacked, built, - installed, and cleaned. Once you have a reliable tarball, you need to copy it - to the <tt>/usr/src/redhat/SOURCES</tt> directory which is a requirement of - the rpmbuild tool. The last two <tt>make</tt> invocations just run rpmbuild to - build either a source (<tt>srpm</tt>) or binary (<tt>rpm</tt>) RPM package. - </p> +<!-- ======================================================================= --> +<div class="doc_subsubsection"><a name="targets">Specific Target +Qualification Details</a></div> +<div class="doc_text"> + <p><table> + <tr><th>Architecture</th><th>OS</th><th>llvm-gcc baseline</th><th>clang baseline + </th><th>tests</th></tr> + <tr><td>x86-32</td><td>Mac OS 10.5</td><td>last release</td><td>none</td><td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr> + <tr><td>x86-32</td><td>Linux</td><td>last release</td><td>none</td><td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr> + <tr><td>x86-32</td><td>FreeBSD</td><td>none</td><td>none</td><td>llvm dejagnu, clang tests, test-suite</td></tr> + <tr><td>x86-32</td><td>mingw</td><td>last release</td><td>none</td><td>QT</td></tr> + <tr><td>x86-64</td><td>Mac OS 10.5</td><td>last release</td><td>none</td><td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr> + <tr><td>x86-64</td><td>Linux</td><td>last release</td><td>none</td><td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr> + <tr><td>x86-64</td><td>FreeBSD</td><td>none</td><td>none</td><td>llvm dejagnu, clang tests, test-suite</td></tr> + </table></p> </div> <!-- ======================================================================= --> -<div class="doc_subsection"><a name="prerelease">Pre-Release Testing</a></div> +<div class="doc_subsection"><a name="commTest">Community Testing</a></div> <div class="doc_text"> <p> Once all testing has been completed and appropriate bugs filed, the pre-release tar balls may be put on the website and the LLVM community is notified. Ask that all LLVM developers test the release in 2 ways:</p> <ol> - <li>Download llvm-X.X, llvm-test-X.X, and the appropriate llvm-gcc4 binary. - Run "make check" and the full llvm-test suite (make TEST=nightly report).<li> - <li>Download llvm-X.X, llvm-test-X.X, and the llvm-gcc4 source. Compile - everything. Run "make check" and the full llvm-test suite (make TEST=nightly + <li>Download llvm-X.X, llvm-test-X.X, and the appropriate llvm-gcc4 + and/or clang binary. Build LLVM. + Run "make check" and the full llvm-test suite (make TEST=nightly report).</li> + <li>Download llvm-X.X, llvm-test-X.X, and the llvm-gcc4 and/or clang source. + Compile everything. Run "make check" and the full llvm-test suite (make TEST=nightly report).</li> </ol> <p>Ask LLVM developers to submit the report and make check results to the list. - Verify that there are no regressions from the previous release. For - unsupported targets, verify that make check at least is clean.</p> + Attempt to verify that there are no regressions from the previous release. + The results are not used to qualify a release, but to spot other potential + problems. For unsupported targets, verify that make check at least is + clean.</p> - <p>The first round of pre-release testing will be the longest. During this time, - all regressions must be fixed before the second pre-release is created (repeat - steps 4-8).</p> + <p>During the first round of testing time, + all regressions must be fixed before the second pre-release is created.</p> - <p>If this is the second round of testing, this is only to ensure the bug fixes - previously merged in have not created new major problems. This is not the time - to solve additional and unrelated bugs. If no patches are merged in, the release - is determined to be ready and the release manager may move onto the next step.</p> + <p>If this is the second round of testing, this is only to ensure the bug + fixes previously merged in have not created new major problems. This is not + the time to solve additional and unrelated bugs. If no patches are merged in, + the release is determined to be ready and the release manager may move onto + the next step. + </p> </div> - <!-- ======================================================================= --> -<div class="doc_subsection"><a name="tag">Tag the Release Branch</a></div> +<div class="doc_subsection"><a name="release-patch">Release Patch Rules +</a></div> <div class="doc_text"> - <p>Tag the release branch using the following procedure:</p> -<div class="doc_code"> -<pre> -svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XX \ - https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XX</i> -svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX \ - https://llvm.org/svn/llvm-project/llvm-gcc-4.2/tags/RELEASE_<i>XX</i> -svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XX \ - https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XX</i> -</pre> + <p> + Below are the rules regarding patching the release branch.</p> + <p> + <li>Patches applied to the release branch are only applied by the release + manager.</li> + <li>During the first round of testing, patches that fix regressions or that + are small and relatively risk free (verified by the appropriate code owner) + are applied to the branch. Code owners are asked to be very conservative in + approving patches for the branch and we reserve the right to reject any patch + that does not fix a regression as previously defined.</li> + <li>During the remaining rounds of testing, only patches that fix regressions + may be applied.</li> + + </p> </div> + + +<!-- ======================================================================= --> +<div class="doc_subsection"><a name="release-final">Release Final Tasks +</a></div> +<div class="doc_text"> + <p> + The final stages of the release process involving taging the release branch, + updating documentation that refers to the release, and updating the demo + page.</p> + <p>FIXME: Add a note if anything needs to be done to the clang website. + Eventually the websites will be merged hopefully.</p> </div> + <!-- ======================================================================= --> -<div class="doc_subsection"><a name="updocs">Update Documentation</a></div> +<div class="doc_subsubsection"><a name="updocs">Update Documentation</a></div> <div class="doc_text"> <p> Review the documentation and ensure that it is up to date. The Release Notes @@ -332,6 +452,24 @@ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XX \ </div> <!-- ======================================================================= --> +<div class="doc_subsubsection"><a name="tag">Tag the Release Branch</a></div> +<div class="doc_text"> + <p>Tag the release branch using the following procedure:</p> +<div class="doc_code"> +<pre> +svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XX \ + https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XX</i> +svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX \ + https://llvm.org/svn/llvm-project/llvm-gcc-4.2/tags/RELEASE_<i>XX</i> +svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XX \ + https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XX</i> +</pre> +</div> +</div> + + + +<!-- ======================================================================= --> <div class="doc_subsection"><a name="updemo">Update the LLVM Demo Page</a></div> <div class="doc_text"> <p> @@ -341,7 +479,7 @@ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XX \ </div> <!-- ======================================================================= --> -<div class="doc_subsection"><a name="webupdates">Update the LLVM Website</a></div> +<div class="doc_subsubsection"><a name="webupdates">Update the LLVM Website</a></div> <div class="doc_text"> <p> The website must be updated before the release announcement is sent out. Here is @@ -349,7 +487,8 @@ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XX \ <ol> <li> Check out the <tt>website</tt> module from CVS. </li> <li> Create a new subdirectory X.X in the releases directory. </li> - <li> Commit the <tt>llvm</tt>, <tt>test-suite</tt>, <tt>llvm-gcc</tt> source, + <li> Commit the <tt>llvm</tt>, <tt>test-suite</tt>, <tt>llvm-gcc</tt> source, + <tt>clang source</tt>, <tt>clang binaries</tt>, and <tt>llvm-gcc</tt> binaries in this new directory. </li> <li> Copy and commit the <tt>llvm/docs</tt> and <tt>LICENSE.txt</tt> files into this new directory. The docs should be built with BUILD_FOR_WEBSITE=1.</li> @@ -360,232 +499,17 @@ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XX \ release documentation.</li> <li> Finally, update the main page (<tt>index.html</tt> and sidebar) to point to the new release and release announcement. Make sure this all gets - commited back into Subversion.</li> + committed back into Subversion.</li> </ol> </div> <!-- ======================================================================= --> -<div class="doc_subsection"><a name="announce">Announce the Release</a></div> +<div class="doc_subsubsection"><a name="announce">Announce the Release</a></div> <div class="doc_text"> <p>Have Chris send out the release announcement when everything is finished.</p> </div> <!-- *********************************************************************** --> -<div class="doc_section"><a name="dist_targets">Distribution Targets</a></div> -<!-- *********************************************************************** --> - -<!-- ======================================================================= --> -<div class="doc_subsection">Overview</div> -<div class="doc_text"> - <p> - The first thing you need to understand is that there are multiple make targets - to support this feature. Here's an overview, we'll delve into the details - later. - </p> - - <ul> - <li><b>distdir</b> - builds the distribution directory from which the - distribution will be packaged</li> - <li><b>dist</b> - builds each of the distribution tarballs (tar.gz, - tar.bzip2, .zip). These can be built individually as well, with separate - targets.</li> - <li><b>dist-check</b> - this is identical to <tt>dist</tt> but includes a - check on the distribution that ensures the tarball can: unpack - successfully, compile correctly, pass '<tt>make check</tt>', and pass - '<tt>make clean</tt>'.</li> - <li><b>dist-clean</b>- this just does a normal clean but also cleans up the - stuff generated by the other three <tt>dist</tt> targets (above).</li> - </ul> - - <p> - Okay, that's the basic functionality. When making a release, we want to ensure - that the tree you build the distribution from passes - <tt>dist-check</tt>. Beyond fixing the usual bugs, there is generally one - impediment to making the release in this fashion: missing files. The - <tt>dist-check</tt> process guards against that possibility. It will either - fail and that failure will indicate what's missing, or it will succeed meaning - that it has proved that the tarballs can actually succeed in building LLVM - correctly and that it passes <tt>make check</tt>. - </p> -</div> - -<!-- ======================================================================= --> - -<div class="doc_subsection">distdir</div> -<div class="doc_text"> - <p> - This target builds the distribution directory which is the directory from - which the tarballs are generated. The distribution directory has the same - name as the release, e.g. LLVM-1.7). This target goes through the following - process: - </p> - - <ol> - <li>First, if there was an old distribution directory (for the current - release), it is removed in its entirety and you see <tt>Removing old - LLVM-1.7</tt></li> - <li>Second, it issues a <tt>make all ENABLE_OPTIMIZED=3D1</tt> to ensure - that the everything in your tree can be built in release mode. Often - times there are discrepancies in building between debug and release - modes so it enforces release mode first. If that fails, the - <tt>distdir</tt> target fails too. This is preceded by the message - <tt>Making 'all' to verify build</tt>.</li> - <li>Next, it traverses your source tree and copies it to a new directory - that has the name of the release (<tt>LLVM-M.m</tt> in our current - case). This is the directory that will get tar'd. It contains all the - software that needs to be in the distribution. During the copying - process, it omits generated files, SVN directories, and any other - "cruft" that's in your build tree. This is done to eliminate the - possibility of huge distribution tarballs that include useless or - irrelevant stuff in them. This is the trickiest part of making the - distribution. Done manually you will either include stuff that - shouldn't be in the distribution or exclude stuff that should. This - step is preceded by the message <tt>Building Distribution Directory - LLVM-1.7</tt></li> - <li>The distribution directory is then traversed and all <tt>CVS</tt> or - <tt>.svn</tt> directories are removed. You see: <tt>Eliminating CVS/.svn - directories from distribution</tt></li> - <li>The recursive <tt>dist-hook</tt> target is executed. This gives each - directory a chance to modify the distribution in some way (more on this - below).</li> - <li>The distribution directory is traversed and the correct file - permissions and modes are set based on the type of file.</li> - </ol> - - <p> - To control the process of making the distribution directory correctly, each - Makefile can utilize two features: - </p> - - <ol> - <li><b><tt>EXTRA_DIST</tt></B> - this make variable specifies which files - it should distribute. By default, all source files are automatically - included for distribution as well as certain <tt>well known</tt> files - (see DistAlways variable in Makefile.rules for details). Each Makefile - specifies, via the <tt>EXTRA_DIST</tt> variable, which additional files - need to be distributed. Only those files that are needed to build LLVM - should be added to <tt>EXTRA_DIST</tt>. <tt>EXTRA_DIST</tt> contains a - list of file or directory names that should be distributed. For example, - the top level Makefile contains <tt>EXTRA_DIST := test llvm.spec - include</tt>. This means that in addition to regular things that are - distributed at the top level (<tt>CREDITS.txt, LICENSE.txt</tt>, etc.) - the distribution should contain the entire <tt>test</tt> and - <tt>include</tt> directories as well as the <tt>llvm.spec</tt> file.</li> - <li><b><tt>dist-hook</tt></B> - this make target can be used to alter the - content of the distribution directory. For example, in the top level - Makefile there is some logic to eliminate files in the <tt>include</tt> - subtree that are generated by the configure script. These should not be - distributed. Similarly, any <tt>dist-hook</tt> target found in any - directory can add or remove or modify things just before it gets - packaged. Any transformation is permitted. Generally, not much is - needed.</li> - </ol> - - <p> - You will see various messages if things go wrong: - </p> - - <ol> - <li>During the copying process, any files that are missing will be flagged - with: <tt>===== WARNING: Distribution Source 'dir/file' Not Found!</tt> - These must be corrected by either adding the file or removing it from - <tt>EXTRA_DIST</tt>.</li> - <li>If you build the distribution with <tt>VERBOSE=1</tt>, then you might - also see: <tt>Skipping non-existent 'dir/file'</tt> in certain cases - where it's okay to skip the file.</li> - <li>The target can fail if any of the things it does fail. Error messages - should indicate what went wrong.</li> - </ol> -</div> - -<!-- ======================================================================= --> -<div class="doc_subsection">dist</div> -<div class="doc_text"> - <p> - This target does exactly what <tt>distdir</tt> target does, but also includes - assembling the tarballs. There are actually four related targets here: - </p> - - <ul> - <li><b><tt>dist-gzip</tt></b>: package the gzipped distribution tar - file. The distribution directory is packaged into a single file ending - in <tt>.tar.gz</tt> which is gzip compressed.</li> - <li><b><tt>dist-bzip2</tt></b>: package the bzip2 distribution tar file. - The distribution directory is packaged into a single file ending in - <tt>.tar.bzip2</tt> which is bzip2 compressed.</li> - <li><b><tt>dist-zip</tt></b>: package the zip distribution file. The - distribution directory is packaged into a single file ending in - <tt>.zip</tt> which is zip compressed.</li> - <li><b><tt>dist</tt></b>: does all three, dist-gzip, dist-bzip2, - dist-zip</li> - </ul> -</div> - -<!-- ======================================================================= --> -<div class="doc_subsection">dist-check</div> -<div class="doc_text"> - <p> - This target checks the distribution. The basic idea is that it unpacks the - distribution tarball and ensures that it can build. It takes the following - actions: - </p> - - <ol> - <li>It depends on the <tt>dist-gzip</tt> target which, if it hasn't already - been built, builds the gzip tar bundle (see dist and distdir - above).</li> - <li>removes any pre-existing <tt>_distcheckdir</tt> at the top level.</li> - <li>creates a new <tt>_distcheckdir</tt> directory at the top level.</li> - <li>creates a <tt>build</tt> subdirectory and an <tt>install</tt> - subdirectory under <tt>_distcheckdir</tt>.</li> - <li>unzips and untars the release tarball into <tt>_distcheckdir</tt>, - creating <tt>LLVM-1.7</tt> directory (from the tarball).</li> - <li>in the build subdirectory, it configures with appropriate options to - build from the unpacked source tarball into the <tt>build</tt> directory - with installation in the <tt>install</tt> directory.</li> - <li>runs <tt>make all</tt></li> - <li>runs <tt>make </tt><tt>check</tt></li> - <li>runs <tt>make install</tt></li> - <li>runs <tt>make uninstall</tt></li> - <li>runs <tt>make dist</tt></li> - <li>runs <tt>make clean</tt></li> - <li>runs <tt>make dist-clean</tt></li> - </ol> - - <p> - If it can pass all that, the distribution will be deemed distribution worth y - and you will see: - </p> - - <pre>===== LLVM-1.7.tar.gz Ready For Distribution =====</pre> - - <p> - This means the tarball should then be tested on other platforms and have the - nightly test run against it. If those all pass, THEN it is ready for - distribution. - </p> - - <p> - A note about disk space: using <tt>dist-check</tt> will easily triple the - amount of disk space your build tree is using. You might want to check - available space before you begin. - </p> -</div> - -<!-- ======================================================================= --> -<div class="doc_subsection">dist-clean</div> -<div class="doc_text"> - <p> - In addition to doing a normal <tt>clean</tt>, this target will clean up the - files and directories created by the distribution targets. In particular the - distribution directory (<tt>LLVM-X.X</tt>), check directory - (<tt>_distcheckdir</tt>), and the various tarballs will be removed. You do - this after the release has shipped and you no longer need this stuff in your - build tree. - </p> -</div> - -<!-- *********************************************************************** --> <hr> <address> <a href="http://jigsaw.w3.org/css-validator/check/referer"><img @@ -594,7 +518,7 @@ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XX \ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a> <br> - Last modified: $Date: 2008-12-11 19:23:24 +0100 (Thu, 11 Dec 2008) $ + Last modified: $Date: 2009-10-12 16:46:08 +0200 (Mon, 12 Oct 2009) $ </address> </body> </html> diff --git a/docs/HowToSubmitABug.html b/docs/HowToSubmitABug.html index 2e6cc4f..2ac4575 100644 --- a/docs/HowToSubmitABug.html +++ b/docs/HowToSubmitABug.html @@ -60,7 +60,7 @@ more easily.</p> <p>Once you have a reduced test-case, go to <a href="http://llvm.org/bugs/enter_bug.cgi">the LLVM Bug Tracking System</a> and fill out the form with the necessary details (note that you don't -need to pick a catagory, just use the "new-bugs" catagory if you're not sure). +need to pick a category, just use the "new-bugs" category if you're not sure). The bug description should contain the following information:</p> @@ -183,12 +183,12 @@ to llvm-gcc (in addition to the options you already pass). Once your have foo.bc, one of the following commands should fail:</p> <ol> -<li><tt><b>llc</b> foo.bc -f</tt></li> -<li><tt><b>llc</b> foo.bc -f -relocation-model=pic</tt></li> -<li><tt><b>llc</b> foo.bc -f -relocation-model=static</tt></li> -<li><tt><b>llc</b> foo.bc -f -enable-eh</tt></li> -<li><tt><b>llc</b> foo.bc -f -relocation-model=pic -enable-eh</tt></li> -<li><tt><b>llc</b> foo.bc -f -relocation-model=static -enable-eh</tt></li> +<li><tt><b>llc</b> foo.bc</tt></li> +<li><tt><b>llc</b> foo.bc -relocation-model=pic</tt></li> +<li><tt><b>llc</b> foo.bc -relocation-model=static</tt></li> +<li><tt><b>llc</b> foo.bc -enable-eh</tt></li> +<li><tt><b>llc</b> foo.bc -relocation-model=pic -enable-eh</tt></li> +<li><tt><b>llc</b> foo.bc -relocation-model=static -enable-eh</tt></li> </ol> <p>If none of these crash, please follow the instructions for a @@ -320,7 +320,7 @@ the following:</p> <div class="doc_code"> <p><tt> -<b>llc</b> test.bc -o test.s -f<br> +<b>llc</b> test.bc -o test.s<br> <b>gcc</b> test.s safe.so -o test.llc<br> ./test.llc [program options] </tt></p> @@ -348,7 +348,7 @@ the following:</p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a> <br> - Last modified: $Date: 2009-04-05 02:41:19 +0200 (Sun, 05 Apr 2009) $ + Last modified: $Date: 2009-10-12 16:46:08 +0200 (Mon, 12 Oct 2009) $ </address> </body> diff --git a/docs/LangRef.html b/docs/LangRef.html index f229150..21e41d5 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -20,7 +20,24 @@ <li><a href="#highlevel">High Level Structure</a> <ol> <li><a href="#modulestructure">Module Structure</a></li> - <li><a href="#linkage">Linkage Types</a></li> + <li><a href="#linkage">Linkage Types</a> + <ol> + <li><a href="#linkage_private">'<tt>private</tt>' Linkage</a></li> + <li><a href="#linkage_linker_private">'<tt>linker_private</tt>' Linkage</a></li> + <li><a href="#linkage_internal">'<tt>internal</tt>' Linkage</a></li> + <li><a href="#linkage_available_externally">'<tt>available_externally</tt>' Linkage</a></li> + <li><a href="#linkage_linkonce">'<tt>linkonce</tt>' Linkage</a></li> + <li><a href="#linkage_common">'<tt>common</tt>' Linkage</a></li> + <li><a href="#linkage_weak">'<tt>weak</tt>' Linkage</a></li> + <li><a href="#linkage_appending">'<tt>appending</tt>' Linkage</a></li> + <li><a href="#linkage_externweak">'<tt>extern_weak</tt>' Linkage</a></li> + <li><a href="#linkage_linkonce_odr">'<tt>linkonce_odr</tt>' Linkage</a></li> + <li><a href="#linkage_weak">'<tt>weak_odr</tt>' Linkage</a></li> + <li><a href="#linkage_external">'<tt>externally visible</tt>' Linkage</a></li> + <li><a href="#linkage_dllimport">'<tt>dllimport</tt>' Linkage</a></li> + <li><a href="#linkage_dllexport">'<tt>dllexport</tt>' Linkage</a></li> + </ol> + </li> <li><a href="#callingconv">Calling Conventions</a></li> <li><a href="#namedtypes">Named Types</a></li> <li><a href="#globalvars">Global Variables</a></li> @@ -31,6 +48,7 @@ <li><a href="#gc">Garbage Collector Names</a></li> <li><a href="#moduleasm">Module-Level Inline Assembly</a></li> <li><a href="#datalayout">Data Layout</a></li> + <li><a href="#pointeraliasing">Pointer Aliasing Rules</a></li> </ol> </li> <li><a href="#typesystem">Type System</a> @@ -38,6 +56,7 @@ <li><a href="#t_classifications">Type Classifications</a></li> <li><a href="#t_primitive">Primitive Types</a> <ol> + <li><a href="#t_integer">Integer Type</a></li> <li><a href="#t_floating">Floating Point Types</a></li> <li><a href="#t_void">Void Type</a></li> <li><a href="#t_label">Label Type</a></li> @@ -46,7 +65,6 @@ </li> <li><a href="#t_derived">Derived Types</a> <ol> - <li><a href="#t_integer">Integer Type</a></li> <li><a href="#t_array">Array Type</a></li> <li><a href="#t_function">Function Type</a></li> <li><a href="#t_pointer">Pointer Type</a></li> @@ -74,6 +92,17 @@ <li><a href="#inlineasm">Inline Assembler Expressions</a></li> </ol> </li> + <li><a href="#intrinsic_globals">Intrinsic Global Variables</a> + <ol> + <li><a href="#intg_used">The '<tt>llvm.used</tt>' Global Variable</a></li> + <li><a href="#intg_compiler_used">The '<tt>llvm.compiler.used</tt>' + Global Variable</a></li> + <li><a href="#intg_global_ctors">The '<tt>llvm.global_ctors</tt>' + Global Variable</a></li> + <li><a href="#intg_global_dtors">The '<tt>llvm.global_dtors</tt>' + Global Variable</a></li> + </ol> + </li> <li><a href="#instref">Instruction Reference</a> <ol> <li><a href="#terminators">Terminator Instructions</a> @@ -155,8 +184,6 @@ <ol> <li><a href="#i_icmp">'<tt>icmp</tt>' Instruction</a></li> <li><a href="#i_fcmp">'<tt>fcmp</tt>' Instruction</a></li> - <li><a href="#i_vicmp">'<tt>vicmp</tt>' Instruction</a></li> - <li><a href="#i_vfcmp">'<tt>vfcmp</tt>' Instruction</a></li> <li><a href="#i_phi">'<tt>phi</tt>' Instruction</a></li> <li><a href="#i_select">'<tt>select</tt>' Instruction</a></li> <li><a href="#i_call">'<tt>call</tt>' Instruction</a></li> @@ -210,8 +237,6 @@ <li><a href="#int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic </a></li> <li><a href="#int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic </a></li> <li><a href="#int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic </a></li> - <li><a href="#int_part_select">'<tt>llvm.part.select.*</tt>' Intrinsic </a></li> - <li><a href="#int_part_set">'<tt>llvm.part.set.*</tt>' Intrinsic </a></li> </ol> </li> <li><a href="#int_overflow">Arithmetic with Overflow Intrinsics</a> @@ -248,6 +273,14 @@ <li><a href="#int_atomic_load_umin"><tt>llvm.atomic.load.umin</tt></a></li> </ol> </li> + <li><a href="#int_memorymarkers">Memory Use Markers</a> + <ol> + <li><a href="#int_lifetime_start"><tt>llvm.lifetime.start</tt></a></li> + <li><a href="#int_lifetime_end"><tt>llvm.lifetime.end</tt></a></li> + <li><a href="#int_invariant_start"><tt>llvm.invariant.start</tt></a></li> + <li><a href="#int_invariant_end"><tt>llvm.invariant.end</tt></a></li> + </ol> + </li> <li><a href="#int_general">General intrinsics</a> <ol> <li><a href="#int_var_annotation"> @@ -274,12 +307,13 @@ <!-- *********************************************************************** --> <div class="doc_text"> -<p>This document is a reference manual for the LLVM assembly language. -LLVM is a Static Single Assignment (SSA) based representation that provides -type safety, low-level operations, flexibility, and the capability of -representing 'all' high-level languages cleanly. It is the common code -representation used throughout all phases of the LLVM compilation -strategy.</p> + +<p>This document is a reference manual for the LLVM assembly language. LLVM is + a Static Single Assignment (SSA) based representation that provides type + safety, low-level operations, flexibility, and the capability of representing + 'all' high-level languages cleanly. It is the common code representation + used throughout all phases of the LLVM compilation strategy.</p> + </div> <!-- *********************************************************************** --> @@ -288,26 +322,24 @@ strategy.</p> <div class="doc_text"> -<p>The LLVM code representation is designed to be used in three -different forms: as an in-memory compiler IR, as an on-disk bitcode -representation (suitable for fast loading by a Just-In-Time compiler), -and as a human readable assembly language representation. This allows -LLVM to provide a powerful intermediate representation for efficient -compiler transformations and analysis, while providing a natural means -to debug and visualize the transformations. The three different forms -of LLVM are all equivalent. This document describes the human readable -representation and notation.</p> +<p>The LLVM code representation is designed to be used in three different forms: + as an in-memory compiler IR, as an on-disk bitcode representation (suitable + for fast loading by a Just-In-Time compiler), and as a human readable + assembly language representation. This allows LLVM to provide a powerful + intermediate representation for efficient compiler transformations and + analysis, while providing a natural means to debug and visualize the + transformations. The three different forms of LLVM are all equivalent. This + document describes the human readable representation and notation.</p> -<p>The LLVM representation aims to be light-weight and low-level -while being expressive, typed, and extensible at the same time. It -aims to be a "universal IR" of sorts, by being at a low enough level -that high-level ideas may be cleanly mapped to it (similar to how -microprocessors are "universal IR's", allowing many source languages to -be mapped to them). By providing type information, LLVM can be used as -the target of optimizations: for example, through pointer analysis, it -can be proven that a C automatic variable is never accessed outside of -the current function... allowing it to be promoted to a simple SSA -value instead of a memory location.</p> +<p>The LLVM representation aims to be light-weight and low-level while being + expressive, typed, and extensible at the same time. It aims to be a + "universal IR" of sorts, by being at a low enough level that high-level ideas + may be cleanly mapped to it (similar to how microprocessors are "universal + IR's", allowing many source languages to be mapped to them). By providing + type information, LLVM can be used as the target of optimizations: for + example, through pointer analysis, it can be proven that a C automatic + variable is never accessed outside of the current function... allowing it to + be promoted to a simple SSA value instead of a memory location.</p> </div> @@ -316,10 +348,10 @@ value instead of a memory location.</p> <div class="doc_text"> -<p>It is important to note that this document describes 'well formed' -LLVM assembly language. There is a difference between what the parser -accepts and what is considered 'well formed'. For example, the -following instruction is syntactically okay, but not well formed:</p> +<p>It is important to note that this document describes 'well formed' LLVM + assembly language. There is a difference between what the parser accepts and + what is considered 'well formed'. For example, the following instruction is + syntactically okay, but not well formed:</p> <div class="doc_code"> <pre> @@ -327,13 +359,13 @@ following instruction is syntactically okay, but not well formed:</p> </pre> </div> -<p>...because the definition of <tt>%x</tt> does not dominate all of -its uses. The LLVM infrastructure provides a verification pass that may -be used to verify that an LLVM module is well formed. This pass is -automatically run by the parser after parsing input assembly and by -the optimizer before it outputs bitcode. The violations pointed out -by the verifier pass indicate bugs in transformation passes or input to -the parser.</p> +<p>...because the definition of <tt>%x</tt> does not dominate all of its + uses. The LLVM infrastructure provides a verification pass that may be used + to verify that an LLVM module is well formed. This pass is automatically run + by the parser after parsing input assembly and by the optimizer before it + outputs bitcode. The violations pointed out by the verifier pass indicate + bugs in transformation passes or input to the parser.</p> + </div> <!-- Describe the typesetting conventions here. --> @@ -344,44 +376,47 @@ the parser.</p> <div class="doc_text"> - <p>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:</p> +<p>LLVM identifiers come in two basic types: global and local. Global + identifiers (functions, global variables) begin with the <tt>'@'</tt> + character. Local identifiers (register names, types) begin with + the <tt>'%'</tt> character. Additionally, there are three different formats + for identifiers, for different purposes:</p> <ol> <li>Named values are represented as a string of characters with their prefix. - For example, %foo, @DivisionByZero, %a.really.long.identifier. The actual - regular expression used is '<tt>[%@][a-zA-Z$._][a-zA-Z$._0-9]*</tt>'. - Identifiers which require other characters in their names can be surrounded - with quotes. Special characters may be escaped using "\xx" where xx is the - ASCII code for the character in hexadecimal. In this way, any character can - be used in a name value, even quotes themselves. + For example, <tt>%foo</tt>, <tt>@DivisionByZero</tt>, + <tt>%a.really.long.identifier</tt>. The actual regular expression used is + '<tt>[%@][a-zA-Z$._][a-zA-Z$._0-9]*</tt>'. Identifiers which require + other characters in their names can be surrounded with quotes. Special + characters may be escaped using <tt>"\xx"</tt> where <tt>xx</tt> is the + ASCII code for the character in hexadecimal. In this way, any character + can be used in a name value, even quotes themselves.</li> <li>Unnamed values are represented as an unsigned numeric value with their - prefix. For example, %12, @2, %44.</li> + prefix. For example, <tt>%12</tt>, <tt>@2</tt>, <tt>%44</tt>.</li> <li>Constants, which are described in a <a href="#constants">section about - constants</a>, below.</li> + constants</a>, below.</li> </ol> <p>LLVM requires that values start with a prefix for two reasons: Compilers -don't need to worry about name clashes with reserved words, and the set of -reserved words may be expanded in the future without penalty. Additionally, -unnamed identifiers allow a compiler to quickly come up with a temporary -variable without having to avoid symbol table conflicts.</p> + don't need to worry about name clashes with reserved words, and the set of + reserved words may be expanded in the future without penalty. Additionally, + unnamed identifiers allow a compiler to quickly come up with a temporary + variable without having to avoid symbol table conflicts.</p> <p>Reserved words in LLVM are very similar to reserved words in other -languages. There are keywords for different opcodes -('<tt><a href="#i_add">add</a></tt>', - '<tt><a href="#i_bitcast">bitcast</a></tt>', - '<tt><a href="#i_ret">ret</a></tt>', etc...), for primitive type names ('<tt><a -href="#t_void">void</a></tt>', '<tt><a href="#t_primitive">i32</a></tt>', etc...), -and others. These reserved words cannot conflict with variable names, because -none of them start with a prefix character ('%' or '@').</p> + languages. There are keywords for different opcodes + ('<tt><a href="#i_add">add</a></tt>', + '<tt><a href="#i_bitcast">bitcast</a></tt>', + '<tt><a href="#i_ret">ret</a></tt>', etc...), for primitive type names + ('<tt><a href="#t_void">void</a></tt>', + '<tt><a href="#t_primitive">i32</a></tt>', etc...), and others. These + reserved words cannot conflict with variable names, because none of them + start with a prefix character (<tt>'%'</tt> or <tt>'@'</tt>).</p> <p>Here is an example of LLVM code to multiply the integer variable -'<tt>%X</tt>' by 8:</p> + '<tt>%X</tt>' by 8:</p> <p>The easy way:</p> @@ -409,25 +444,23 @@ none of them start with a prefix character ('%' or '@').</p> </pre> </div> -<p>This last way of multiplying <tt>%X</tt> by 8 illustrates several -important lexical features of LLVM:</p> +<p>This last way of multiplying <tt>%X</tt> by 8 illustrates several important + lexical features of LLVM:</p> <ol> - <li>Comments are delimited with a '<tt>;</tt>' and go until the end of - line.</li> + line.</li> <li>Unnamed temporaries are created when the result of a computation is not - assigned to a named value.</li> + assigned to a named value.</li> <li>Unnamed temporaries are numbered sequentially</li> - </ol> <p>...and it also shows a convention that we follow in this document. When -demonstrating instructions, we will follow an instruction with a comment that -defines the type and name of value produced. Comments are shown in italic -text.</p> + demonstrating instructions, we will follow an instruction with a comment that + defines the type and name of value produced. Comments are shown in italic + text.</p> </div> @@ -441,12 +474,12 @@ text.</p> <div class="doc_text"> -<p>LLVM programs are composed of "Module"s, each of which is a -translation unit of the input programs. Each module consists of -functions, global variables, and symbol table entries. Modules may be -combined together with the LLVM linker, which merges function (and -global variable) definitions, resolves forward declarations, and merges -symbol table entries. Here is an example of the "hello world" module:</p> +<p>LLVM programs are composed of "Module"s, each of which is a translation unit + of the input programs. Each module consists of functions, global variables, + and symbol table entries. Modules may be combined together with the LLVM + linker, which merges function (and global variable) definitions, resolves + forward declarations, and merges symbol table entries. Here is an example of + the "hello world" module:</p> <div class="doc_code"> <pre><i>; Declare the string constant as a global constant...</i> @@ -454,32 +487,32 @@ symbol table entries. Here is an example of the "hello world" module:</p> href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00" <i>; [13 x i8]*</i> <i>; External declaration of the puts function</i> -<a href="#functionstructure">declare</a> i32 @puts(i8 *) <i>; i32(i8 *)* </i> +<a href="#functionstructure">declare</a> i32 @puts(i8 *) <i>; i32(i8 *)* </i> <i>; Definition of main function</i> -define i32 @main() { <i>; i32()* </i> +define i32 @main() { <i>; i32()* </i> <i>; Convert [13 x i8]* to i8 *...</i> %cast210 = <a - href="#i_getelementptr">getelementptr</a> [13 x i8]* @.LC0, i64 0, i64 0 <i>; i8 *</i> + href="#i_getelementptr">getelementptr</a> [13 x i8]* @.LC0, i64 0, i64 0 <i>; i8 *</i> <i>; Call puts function to write out the string to stdout...</i> <a - href="#i_call">call</a> i32 @puts(i8 * %cast210) <i>; i32</i> + href="#i_call">call</a> i32 @puts(i8 * %cast210) <i>; i32</i> <a href="#i_ret">ret</a> i32 0<br>}<br> </pre> </div> -<p>This example is made up of a <a href="#globalvars">global variable</a> -named "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" -function, and a <a href="#functionstructure">function definition</a> -for "<tt>main</tt>".</p> +<p>This example is made up of a <a href="#globalvars">global variable</a> named + "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function, and + a <a href="#functionstructure">function definition</a> for + "<tt>main</tt>".</p> -<p>In general, a module is made up of a list of global values, -where both functions and global variables are global values. Global values are -represented by a pointer to a memory location (in this case, a pointer to an -array of char, and a pointer to a function), and have one of the following <a -href="#linkage">linkage types</a>.</p> +<p>In general, a module is made up of a list of global values, where both + functions and global variables are global values. Global values are + represented by a pointer to a memory location (in this case, a pointer to an + array of char, and a pointer to a function), and have one of the + following <a href="#linkage">linkage types</a>.</p> </div> @@ -490,139 +523,126 @@ href="#linkage">linkage types</a>.</p> <div class="doc_text"> -<p> -All Global Variables and Functions have one of the following types of linkage: -</p> +<p>All Global Variables and Functions have one of the following types of + linkage:</p> <dl> - <dt><tt><b><a name="linkage_private">private</a></b></tt>: </dt> - - <dd>Global values with private linkage are only directly accessible by - objects in the current module. In particular, linking code into a module with - an private global value may cause the private to be renamed as necessary to - avoid collisions. Because the symbol is private to the module, all - references can be updated. This doesn't show up in any symbol table in the - object file. - </dd> + <dd>Global values with private linkage are only directly accessible by objects + in the current module. In particular, linking code into a module with an + private global value may cause the private to be renamed as necessary to + avoid collisions. Because the symbol is private to the module, all + references can be updated. This doesn't show up in any symbol table in the + object file.</dd> + + <dt><tt><b><a name="linkage_linker_private">linker_private</a></b></tt>: </dt> + <dd>Similar to private, but the symbol is passed through the assembler and + removed by the linker after evaluation. Note that (unlike private + symbols) linker_private symbols are subject to coalescing by the linker: + weak symbols get merged and redefinitions are rejected. However, unlike + normal strong symbols, they are removed by the linker from the final + linked image (executable or dynamic library).</dd> <dt><tt><b><a name="linkage_internal">internal</a></b></tt>: </dt> + <dd>Similar to private, but the value shows as a local symbol + (<tt>STB_LOCAL</tt> in the case of ELF) in the object file. This + corresponds to the notion of the '<tt>static</tt>' keyword in C.</dd> - <dd> Similar to private, but the value shows as a local symbol (STB_LOCAL in - the case of ELF) in the object file. This corresponds to the notion of the - '<tt>static</tt>' keyword in C. - </dd> - - <dt><tt><b><a name="available_externally">available_externally</a></b></tt>: - </dt> - + <dt><tt><b><a name="linkage_available_externally">available_externally</a></b></tt>: </dt> <dd>Globals with "<tt>available_externally</tt>" linkage are never emitted - into the object file corresponding to the LLVM module. They exist to - allow inlining and other optimizations to take place given knowledge of the - definition of the global, which is known to be somewhere outside the module. - Globals with <tt>available_externally</tt> linkage are allowed to be discarded - at will, and are otherwise the same as <tt>linkonce_odr</tt>. This linkage - type is only allowed on definitions, not declarations.</dd> + into the object file corresponding to the LLVM module. They exist to + allow inlining and other optimizations to take place given knowledge of + the definition of the global, which is known to be somewhere outside the + module. Globals with <tt>available_externally</tt> linkage are allowed to + be discarded at will, and are otherwise the same as <tt>linkonce_odr</tt>. + This linkage type is only allowed on definitions, not declarations.</dd> <dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt>: </dt> - <dd>Globals with "<tt>linkonce</tt>" linkage are merged with other globals of - the same name when linkage occurs. This is typically used to implement - inline functions, templates, or other code which must be generated in each - translation unit that uses it. Unreferenced <tt>linkonce</tt> globals are - allowed to be discarded. - </dd> - - <dt><tt><b><a name="linkage_common">common</a></b></tt>: </dt> - - <dd>"<tt>common</tt>" linkage is exactly the same as <tt>linkonce</tt> - linkage, except that unreferenced <tt>common</tt> globals may not be - discarded. This is used for globals that may be emitted in multiple - translation units, but that are not guaranteed to be emitted into every - translation unit that uses them. One example of this is tentative - definitions in C, such as "<tt>int X;</tt>" at global scope. - </dd> + the same name when linkage occurs. This is typically used to implement + inline functions, templates, or other code which must be generated in each + translation unit that uses it. Unreferenced <tt>linkonce</tt> globals are + allowed to be discarded.</dd> <dt><tt><b><a name="linkage_weak">weak</a></b></tt>: </dt> + <dd>"<tt>weak</tt>" linkage has the same merging semantics as + <tt>linkonce</tt> linkage, except that unreferenced globals with + <tt>weak</tt> linkage may not be discarded. This is used for globals that + are declared "weak" in C source code.</dd> + + <dt><tt><b><a name="linkage_common">common</a></b></tt>: </dt> + <dd>"<tt>common</tt>" linkage is most similar to "<tt>weak</tt>" linkage, but + they are used for tentative definitions in C, such as "<tt>int X;</tt>" at + global scope. + Symbols with "<tt>common</tt>" linkage are merged in the same way as + <tt>weak symbols</tt>, and they may not be deleted if unreferenced. + <tt>common</tt> symbols may not have an explicit section, + must have a zero initializer, and may not be marked '<a + href="#globalvars"><tt>constant</tt></a>'. Functions and aliases may not + have common linkage.</dd> - <dd>"<tt>weak</tt>" linkage is the same as <tt>common</tt> linkage, except - that some targets may choose to emit different assembly sequences for them - for target-dependent reasons. This is used for globals that are declared - "weak" in C source code. - </dd> <dt><tt><b><a name="linkage_appending">appending</a></b></tt>: </dt> - <dd>"<tt>appending</tt>" linkage may only be applied to global variables of - pointer to array type. When two global variables with appending linkage are - linked together, the two global arrays are appended together. This is the - LLVM, typesafe, equivalent of having the system linker append together - "sections" with identical names when .o files are linked. - </dd> + pointer to array type. When two global variables with appending linkage + are linked together, the two global arrays are appended together. This is + the LLVM, typesafe, equivalent of having the system linker append together + "sections" with identical names when .o files are linked.</dd> <dt><tt><b><a name="linkage_externweak">extern_weak</a></b></tt>: </dt> - - <dd>The semantics of this linkage follow the ELF object file model: the - symbol is weak until linked, if not linked, the symbol becomes null instead - of being an undefined reference. - </dd> - - <dt><tt><b><a name="linkage_linkonce">linkonce_odr</a></b></tt>: </dt> - <dt><tt><b><a name="linkage_weak">weak_odr</a></b></tt>: </dt> - <dd>Some languages allow differing globals to be merged, such as two - functions with different semantics. Other languages, such as <tt>C++</tt>, - ensure that only equivalent globals are ever merged (the "one definition - rule" - "ODR"). Such languages can use the <tt>linkonce_odr</tt> - and <tt>weak_odr</tt> linkage types to indicate that the global will only - be merged with equivalent globals. These linkage types are otherwise the - same as their non-<tt>odr</tt> versions. - </dd> + <dd>The semantics of this linkage follow the ELF object file model: the symbol + is weak until linked, if not linked, the symbol becomes null instead of + being an undefined reference.</dd> + + <dt><tt><b><a name="linkage_linkonce_odr">linkonce_odr</a></b></tt>: </dt> + <dt><tt><b><a name="linkage_weak_odr">weak_odr</a></b></tt>: </dt> + <dd>Some languages allow differing globals to be merged, such as two functions + with different semantics. Other languages, such as <tt>C++</tt>, ensure + that only equivalent globals are ever merged (the "one definition rule" - + "ODR"). Such languages can use the <tt>linkonce_odr</tt> + and <tt>weak_odr</tt> linkage types to indicate that the global will only + be merged with equivalent globals. These linkage types are otherwise the + same as their non-<tt>odr</tt> versions.</dd> <dt><tt><b><a name="linkage_external">externally visible</a></b></tt>:</dt> - <dd>If none of the above identifiers are used, the global is externally - visible, meaning that it participates in linkage and can be used to resolve - external symbol references. - </dd> + visible, meaning that it participates in linkage and can be used to + resolve external symbol references.</dd> </dl> - <p> - The next two types of linkage are targeted for Microsoft Windows platform - only. They are designed to support importing (exporting) symbols from (to) - DLLs (Dynamic Link Libraries). - </p> +<p>The next two types of linkage are targeted for Microsoft Windows platform + only. They are designed to support importing (exporting) symbols from (to) + DLLs (Dynamic Link Libraries).</p> - <dl> +<dl> <dt><tt><b><a name="linkage_dllimport">dllimport</a></b></tt>: </dt> - <dd>"<tt>dllimport</tt>" linkage causes the compiler to reference a function - or variable via a global pointer to a pointer that is set up by the DLL - exporting the symbol. On Microsoft Windows targets, the pointer name is - formed by combining <code>__imp_</code> and the function or variable name. - </dd> + or variable via a global pointer to a pointer that is set up by the DLL + exporting the symbol. On Microsoft Windows targets, the pointer name is + formed by combining <code>__imp_</code> and the function or variable + name.</dd> <dt><tt><b><a name="linkage_dllexport">dllexport</a></b></tt>: </dt> - <dd>"<tt>dllexport</tt>" linkage causes the compiler to provide a global - pointer to a pointer in a DLL, so that it can be referenced with the - <tt>dllimport</tt> attribute. On Microsoft Windows targets, the pointer - name is formed by combining <code>__imp_</code> and the function or variable - name. - </dd> - + pointer to a pointer in a DLL, so that it can be referenced with the + <tt>dllimport</tt> attribute. On Microsoft Windows targets, the pointer + name is formed by combining <code>__imp_</code> and the function or + variable name.</dd> </dl> -<p>For example, since the "<tt>.LC0</tt>" -variable is defined to be internal, if another module defined a "<tt>.LC0</tt>" -variable and was linked with this one, one of the two would be renamed, -preventing a collision. Since "<tt>main</tt>" and "<tt>puts</tt>" are -external (i.e., lacking any linkage declarations), they are accessible -outside of the current module.</p> -<p>It is illegal for a function <i>declaration</i> -to have any linkage type other than "externally visible", <tt>dllimport</tt> -or <tt>extern_weak</tt>.</p> +<p>For example, since the "<tt>.LC0</tt>" variable is defined to be internal, if + another module defined a "<tt>.LC0</tt>" variable and was linked with this + one, one of the two would be renamed, preventing a collision. Since + "<tt>main</tt>" and "<tt>puts</tt>" are external (i.e., lacking any linkage + declarations), they are accessible outside of the current module.</p> + +<p>It is illegal for a function <i>declaration</i> to have any linkage type + other than "externally visible", <tt>dllimport</tt> + or <tt>extern_weak</tt>.</p> + <p>Aliases can have only <tt>external</tt>, <tt>internal</tt>, <tt>weak</tt> -or <tt>weak_odr</tt> linkages.</p> + or <tt>weak_odr</tt> linkages.</p> + </div> <!-- ======================================================================= --> @@ -633,55 +653,48 @@ or <tt>weak_odr</tt> linkages.</p> <div class="doc_text"> <p>LLVM <a href="#functionstructure">functions</a>, <a href="#i_call">calls</a> -and <a href="#i_invoke">invokes</a> can all have an optional calling convention -specified for the call. The calling convention of any pair of dynamic -caller/callee must match, or the behavior of the program is undefined. The -following calling conventions are supported by LLVM, and more may be added in -the future:</p> + and <a href="#i_invoke">invokes</a> can all have an optional calling + convention specified for the call. The calling convention of any pair of + dynamic caller/callee must match, or the behavior of the program is + undefined. The following calling conventions are supported by LLVM, and more + may be added in the future:</p> <dl> <dt><b>"<tt>ccc</tt>" - The C calling convention</b>:</dt> - <dd>This calling convention (the default if no other calling convention is - specified) matches the target C calling conventions. This calling convention - supports varargs function calls and tolerates some mismatch in the declared - prototype and implemented declaration of the function (as does normal C). - </dd> + specified) matches the target C calling conventions. This calling + convention supports varargs function calls and tolerates some mismatch in + the declared prototype and implemented declaration of the function (as + does normal C).</dd> <dt><b>"<tt>fastcc</tt>" - The fast calling convention</b>:</dt> - <dd>This calling convention attempts to make calls as fast as possible - (e.g. by passing things in registers). This calling convention allows the - target to use whatever tricks it wants to produce fast code for the target, - without having to conform to an externally specified ABI (Application Binary - Interface). Implementations of this convention should allow arbitrary - <a href="CodeGenerator.html#tailcallopt">tail call optimization</a> to be - supported. This calling convention does not support varargs and requires the - prototype of all callees to exactly match the prototype of the function - definition. - </dd> + (e.g. by passing things in registers). This calling convention allows the + target to use whatever tricks it wants to produce fast code for the + target, without having to conform to an externally specified ABI + (Application Binary Interface). Implementations of this convention should + allow arbitrary <a href="CodeGenerator.html#tailcallopt">tail call + optimization</a> to be supported. This calling convention does not + support varargs and requires the prototype of all callees to exactly match + the prototype of the function definition.</dd> <dt><b>"<tt>coldcc</tt>" - The cold calling convention</b>:</dt> - <dd>This calling convention attempts to make code in the caller as efficient - as possible under the assumption that the call is not commonly executed. As - such, these calls often preserve all registers so that the call does not break - any live ranges in the caller side. This calling convention does not support - varargs and requires the prototype of all callees to exactly match the - prototype of the function definition. - </dd> + as possible under the assumption that the call is not commonly executed. + As such, these calls often preserve all registers so that the call does + not break any live ranges in the caller side. This calling convention + does not support varargs and requires the prototype of all callees to + exactly match the prototype of the function definition.</dd> <dt><b>"<tt>cc <<em>n</em>></tt>" - Numbered convention</b>:</dt> - <dd>Any calling convention may be specified by number, allowing - target-specific calling conventions to be used. Target specific calling - conventions start at 64. - </dd> + target-specific calling conventions to be used. Target specific calling + conventions start at 64.</dd> </dl> <p>More calling conventions can be added/defined on an as-needed basis, to -support pascal conventions or any other well-known target-independent -convention.</p> + support Pascal conventions or any other well-known target-independent + convention.</p> </div> @@ -692,37 +705,29 @@ convention.</p> <div class="doc_text"> -<p> -All Global Variables and Functions have one of the following visibility styles: -</p> +<p>All Global Variables and Functions have one of the following visibility + styles:</p> <dl> <dt><b>"<tt>default</tt>" - Default style</b>:</dt> - <dd>On targets that use the ELF object file format, default visibility means - that the declaration is visible to other - modules and, in shared libraries, means that the declared entity may be - overridden. On Darwin, default visibility means that the declaration is - visible to other modules. Default visibility corresponds to "external - linkage" in the language. - </dd> + that the declaration is visible to other modules and, in shared libraries, + means that the declared entity may be overridden. On Darwin, default + visibility means that the declaration is visible to other modules. Default + visibility corresponds to "external linkage" in the language.</dd> <dt><b>"<tt>hidden</tt>" - Hidden style</b>:</dt> - <dd>Two declarations of an object with hidden visibility refer to the same - object if they are in the same shared object. Usually, hidden visibility - indicates that the symbol will not be placed into the dynamic symbol table, - so no other module (executable or shared library) can reference it - directly. - </dd> + object if they are in the same shared object. Usually, hidden visibility + indicates that the symbol will not be placed into the dynamic symbol + table, so no other module (executable or shared library) can reference it + directly.</dd> <dt><b>"<tt>protected</tt>" - Protected style</b>:</dt> - <dd>On ELF, protected visibility indicates that the symbol will be placed in - the dynamic symbol table, but that references within the defining module will - bind to the local symbol. That is, the symbol cannot be overridden by another - module. - </dd> + the dynamic symbol table, but that references within the defining module + will bind to the local symbol. That is, the symbol cannot be overridden by + another module.</dd> </dl> </div> @@ -735,9 +740,8 @@ All Global Variables and Functions have one of the following visibility styles: <div class="doc_text"> <p>LLVM IR allows you to specify name aliases for certain types. This can make -it easier to read the IR and make the IR more condensed (particularly when -recursive types are involved). An example of a name specification is: -</p> + it easier to read the IR and make the IR more condensed (particularly when + recursive types are involved). An example of a name specification is:</p> <div class="doc_code"> <pre> @@ -745,19 +749,19 @@ recursive types are involved). An example of a name specification is: </pre> </div> -<p>You may give a name to any <a href="#typesystem">type</a> except "<a -href="t_void">void</a>". Type name aliases may be used anywhere a type is -expected with the syntax "%mytype".</p> +<p>You may give a name to any <a href="#typesystem">type</a> except + "<a href="t_void">void</a>". Type name aliases may be used anywhere a type + is expected with the syntax "%mytype".</p> <p>Note that type names are aliases for the structural type that they indicate, -and that you can therefore specify multiple names for the same type. This often -leads to confusing behavior when dumping out a .ll file. Since LLVM IR uses -structural typing, the name is not part of the type. When printing out LLVM IR, -the printer will pick <em>one name</em> to render all types of a particular -shape. This means that if you have code where two different source types end up -having the same LLVM type, that the dumper will sometimes print the "wrong" or -unexpected type. This is an important design point and isn't going to -change.</p> + and that you can therefore specify multiple names for the same type. This + often leads to confusing behavior when dumping out a .ll file. Since LLVM IR + uses structural typing, the name is not part of the type. When printing out + LLVM IR, the printer will pick <em>one name</em> to render all types of a + particular shape. This means that if you have code where two different + source types end up having the same LLVM type, that the dumper will sometimes + print the "wrong" or unexpected type. This is an important design point and + isn't going to change.</p> </div> @@ -769,48 +773,47 @@ change.</p> <div class="doc_text"> <p>Global variables define regions of memory allocated at compilation time -instead of run-time. Global variables may optionally be initialized, may have -an explicit section to be placed in, and may have an optional explicit alignment -specified. A variable may be defined as "thread_local", which means that it -will not be shared by threads (each thread will have a separated copy of the -variable). A variable may be defined as a global "constant," which indicates -that the contents of the variable will <b>never</b> be modified (enabling better -optimization, allowing the global data to be placed in the read-only section of -an executable, etc). Note that variables that need runtime initialization -cannot be marked "constant" as there is a store to the variable.</p> - -<p> -LLVM explicitly allows <em>declarations</em> of global variables to be marked -constant, even if the final definition of the global is not. This capability -can be used to enable slightly better optimization of the program, but requires -the language definition to guarantee that optimizations based on the -'constantness' are valid for the translation units that do not include the -definition. -</p> - -<p>As SSA values, global variables define pointer values that are in -scope (i.e. they dominate) all basic blocks in the program. Global -variables always define a pointer to their "content" type because they -describe a region of memory, and all memory objects in LLVM are -accessed through pointers.</p> - -<p>A global variable may be declared to reside in a target-specifc numbered -address space. For targets that support them, address spaces may affect how -optimizations are performed and/or what target instructions are used to access -the variable. The default address space is zero. The address space qualifier -must precede any other attributes.</p> + instead of run-time. Global variables may optionally be initialized, may + have an explicit section to be placed in, and may have an optional explicit + alignment specified. A variable may be defined as "thread_local", which + means that it will not be shared by threads (each thread will have a + separated copy of the variable). A variable may be defined as a global + "constant," which indicates that the contents of the variable + will <b>never</b> be modified (enabling better optimization, allowing the + global data to be placed in the read-only section of an executable, etc). + Note that variables that need runtime initialization cannot be marked + "constant" as there is a store to the variable.</p> + +<p>LLVM explicitly allows <em>declarations</em> of global variables to be marked + constant, even if the final definition of the global is not. This capability + can be used to enable slightly better optimization of the program, but + requires the language definition to guarantee that optimizations based on the + 'constantness' are valid for the translation units that do not include the + definition.</p> + +<p>As SSA values, global variables define pointer values that are in scope + (i.e. they dominate) all basic blocks in the program. Global variables + always define a pointer to their "content" type because they describe a + region of memory, and all memory objects in LLVM are accessed through + pointers.</p> + +<p>A global variable may be declared to reside in a target-specific numbered + address space. For targets that support them, address spaces may affect how + optimizations are performed and/or what target instructions are used to + access the variable. The default address space is zero. The address space + qualifier must precede any other attributes.</p> <p>LLVM allows an explicit section to be specified for globals. If the target -supports it, it will emit globals to the section specified.</p> + supports it, it will emit globals to the section specified.</p> <p>An explicit alignment may be specified for a global. If not present, or if -the alignment is set to zero, the alignment of the global is set by the target -to whatever it feels convenient. If an explicit alignment is specified, the -global is forced to have at least that much alignment. All alignments must be -a power of 2.</p> + the alignment is set to zero, the alignment of the global is set by the + target to whatever it feels convenient. If an explicit alignment is + specified, the global is forced to have at least that much alignment. All + alignments must be a power of 2.</p> -<p>For example, the following defines a global in a numbered address space with -an initializer, section, and alignment:</p> +<p>For example, the following defines a global in a numbered address space with + an initializer, section, and alignment:</p> <div class="doc_code"> <pre> @@ -828,74 +831,72 @@ an initializer, section, and alignment:</p> <div class="doc_text"> -<p>LLVM function definitions consist of the "<tt>define</tt>" keyord, -an optional <a href="#linkage">linkage type</a>, an optional -<a href="#visibility">visibility style</a>, an optional -<a href="#callingconv">calling convention</a>, a return type, an optional -<a href="#paramattrs">parameter attribute</a> for the return type, a function -name, a (possibly empty) argument list (each with optional -<a href="#paramattrs">parameter attributes</a>), optional -<a href="#fnattrs">function attributes</a>, an optional section, -an optional alignment, an optional <a href="#gc">garbage collector name</a>, -an opening curly brace, a list of basic blocks, and a closing curly brace. +<p>LLVM function definitions consist of the "<tt>define</tt>" keyord, an + optional <a href="#linkage">linkage type</a>, an optional + <a href="#visibility">visibility style</a>, an optional + <a href="#callingconv">calling convention</a>, a return type, an optional + <a href="#paramattrs">parameter attribute</a> for the return type, a function + name, a (possibly empty) argument list (each with optional + <a href="#paramattrs">parameter attributes</a>), optional + <a href="#fnattrs">function attributes</a>, an optional section, an optional + alignment, an optional <a href="#gc">garbage collector name</a>, an opening + curly brace, a list of basic blocks, and a closing curly brace.</p> -LLVM function declarations consist of the "<tt>declare</tt>" keyword, an -optional <a href="#linkage">linkage type</a>, an optional -<a href="#visibility">visibility style</a>, an optional -<a href="#callingconv">calling convention</a>, a return type, an optional -<a href="#paramattrs">parameter attribute</a> for the return type, a function -name, a possibly empty list of arguments, an optional alignment, and an optional -<a href="#gc">garbage collector name</a>.</p> +<p>LLVM function declarations consist of the "<tt>declare</tt>" keyword, an + optional <a href="#linkage">linkage type</a>, an optional + <a href="#visibility">visibility style</a>, an optional + <a href="#callingconv">calling convention</a>, a return type, an optional + <a href="#paramattrs">parameter attribute</a> for the return type, a function + name, a possibly empty list of arguments, an optional alignment, and an + optional <a href="#gc">garbage collector name</a>.</p> <p>A function definition contains a list of basic blocks, forming the CFG -(Control Flow Graph) for -the function. Each basic block may optionally start with a label (giving the -basic block a symbol table entry), contains a list of instructions, and ends -with a <a href="#terminators">terminator</a> instruction (such as a branch or -function return).</p> + (Control Flow Graph) for the function. Each basic block may optionally start + with a label (giving the basic block a symbol table entry), contains a list + of instructions, and ends with a <a href="#terminators">terminator</a> + instruction (such as a branch or function return).</p> <p>The first basic block in a function is special in two ways: it is immediately -executed on entrance to the function, and it is not allowed to have predecessor -basic blocks (i.e. there can not be any branches to the entry block of a -function). Because the block can have no predecessors, it also cannot have any -<a href="#i_phi">PHI nodes</a>.</p> + executed on entrance to the function, and it is not allowed to have + predecessor basic blocks (i.e. there can not be any branches to the entry + block of a function). Because the block can have no predecessors, it also + cannot have any <a href="#i_phi">PHI nodes</a>.</p> <p>LLVM allows an explicit section to be specified for functions. If the target -supports it, it will emit functions to the section specified.</p> + supports it, it will emit functions to the section specified.</p> <p>An explicit alignment may be specified for a function. If not present, or if -the alignment is set to zero, the alignment of the function is set by the target -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.</p> - - <h5>Syntax:</h5> + the alignment is set to zero, the alignment of the function is set by the + target 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.</p> +<h5>Syntax:</h5> <div class="doc_code"> -<tt> +<pre> define [<a href="#linkage">linkage</a>] [<a href="#visibility">visibility</a>] - [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>] - <ResultType> @<FunctionName> ([argument list]) - [<a href="#fnattrs">fn Attrs</a>] [section "name"] [align N] - [<a href="#gc">gc</a>] { ... } -</tt> + [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>] + <ResultType> @<FunctionName> ([argument list]) + [<a href="#fnattrs">fn Attrs</a>] [section "name"] [align N] + [<a href="#gc">gc</a>] { ... } +</pre> </div> </div> - <!-- ======================================================================= --> <div class="doc_subsection"> <a name="aliasstructure">Aliases</a> </div> + <div class="doc_text"> - <p>Aliases act as "second name" for the aliasee value (which can be either - function, global variable, another alias or bitcast of global value). Aliases - may have an optional <a href="#linkage">linkage type</a>, and an - optional <a href="#visibility">visibility style</a>.</p> - <h5>Syntax:</h5> +<p>Aliases act as "second name" for the aliasee value (which can be either + function, global variable, another alias or bitcast of global value). Aliases + may have an optional <a href="#linkage">linkage type</a>, and an + optional <a href="#visibility">visibility style</a>.</p> +<h5>Syntax:</h5> <div class="doc_code"> <pre> @<Name> = alias [Linkage] [Visibility] <AliaseeTy> @<Aliasee> @@ -904,21 +905,21 @@ define [<a href="#linkage">linkage</a>] [<a href="#visibility">visibility</a>] </div> - - <!-- ======================================================================= --> <div class="doc_subsection"><a name="paramattrs">Parameter Attributes</a></div> + <div class="doc_text"> - <p>The return type and each parameter of a function type may have a set of - <i>parameter attributes</i> associated with them. Parameter attributes are - used to communicate additional information about the result or parameters of - a function. Parameter attributes are considered to be part of the function, - not of the function type, so functions with different parameter attributes - can have the same function type.</p> - <p>Parameter attributes are simple keywords that follow the type specified. If - multiple parameter attributes are needed, they are space separated. For - example:</p> +<p>The return type and each parameter of a function type may have a set of + <i>parameter attributes</i> associated with them. Parameter attributes are + used to communicate additional information about the result or parameters of + a function. Parameter attributes are considered to be part of the function, + not of the function type, so functions with different parameter attributes + can have the same function type.</p> + +<p>Parameter attributes are simple keywords that follow the type specified. If + multiple parameter attributes are needed, they are space separated. For + example:</p> <div class="doc_code"> <pre> @@ -928,71 +929,72 @@ declare signext i8 @returns_signed_char() </pre> </div> - <p>Note that any attributes for the function result (<tt>nounwind</tt>, - <tt>readonly</tt>) come immediately after the argument list.</p> - - <p>Currently, only the following parameter attributes are defined:</p> - <dl> - <dt><tt>zeroext</tt></dt> - <dd>This indicates to the code generator that the parameter or return value - should be zero-extended to a 32-bit value by the caller (for a parameter) - or the callee (for a return value).</dd> - - <dt><tt>signext</tt></dt> - <dd>This indicates to the code generator that the parameter or return value - should be sign-extended to a 32-bit value by the caller (for a parameter) - or the callee (for a return value).</dd> - - <dt><tt>inreg</tt></dt> - <dd>This indicates that this parameter or return value should be treated - in a special target-dependent fashion during while emitting code for a - function call or return (usually, by putting it in a register as opposed - to memory, though some targets use it to distinguish between two different - kinds of registers). Use of this attribute is target-specific.</dd> - - <dt><tt><a name="byval">byval</a></tt></dt> - <dd>This indicates that the pointer parameter should really be passed by - value to the function. The attribute implies that a hidden copy of the - pointee is made between the caller and the callee, so the callee is unable - to modify the value in the callee. This attribute is only valid on LLVM - pointer arguments. It is generally used to pass structs and arrays by - value, but is also valid on pointers to scalars. The copy is considered to - belong to the caller not the callee (for example, - <tt><a href="#readonly">readonly</a></tt> functions should not write to - <tt>byval</tt> parameters). This is not a valid attribute for return - values. The byval attribute also supports specifying an alignment with the - align attribute. This has a target-specific effect on the code generator - that usually indicates a desired alignment for the synthesized stack - slot.</dd> - - <dt><tt>sret</tt></dt> - <dd>This indicates that the pointer parameter specifies the address of a - structure that is the return value of the function in the source program. - This pointer must be guaranteed by the caller to be valid: loads and stores - to the structure may be assumed by the callee to not to trap. This may only - be applied to the first parameter. This is not a valid attribute for - return values. </dd> - - <dt><tt>noalias</tt></dt> - <dd>This indicates that the pointer does not alias any global or any other - parameter. The caller is responsible for ensuring that this is the - case. On a function return value, <tt>noalias</tt> additionally indicates - that the pointer does not alias any other pointers visible to the - caller. For further details, please see the discussion of the NoAlias - response in - <a href="http://llvm.org/docs/AliasAnalysis.html#MustMayNo">alias - analysis</a>.</dd> - - <dt><tt>nocapture</tt></dt> - <dd>This indicates that the callee does not make any copies of the pointer - that outlive the callee itself. This is not a valid attribute for return - values.</dd> - - <dt><tt>nest</tt></dt> - <dd>This indicates that the pointer parameter can be excised using the - <a href="#int_trampoline">trampoline intrinsics</a>. This is not a valid - attribute for return values.</dd> - </dl> +<p>Note that any attributes for the function result (<tt>nounwind</tt>, + <tt>readonly</tt>) come immediately after the argument list.</p> + +<p>Currently, only the following parameter attributes are defined:</p> + +<dl> + <dt><tt>zeroext</tt></dt> + <dd>This indicates to the code generator that the parameter or return value + should be zero-extended to a 32-bit value by the caller (for a parameter) + or the callee (for a return value).</dd> + + <dt><tt>signext</tt></dt> + <dd>This indicates to the code generator that the parameter or return value + should be sign-extended to a 32-bit value by the caller (for a parameter) + or the callee (for a return value).</dd> + + <dt><tt>inreg</tt></dt> + <dd>This indicates that this parameter or return value should be treated in a + special target-dependent fashion during while emitting code for a function + call or return (usually, by putting it in a register as opposed to memory, + though some targets use it to distinguish between two different kinds of + registers). Use of this attribute is target-specific.</dd> + + <dt><tt><a name="byval">byval</a></tt></dt> + <dd>This indicates that the pointer parameter should really be passed by value + to the function. The attribute implies that a hidden copy of the pointee + is made between the caller and the callee, so the callee is unable to + modify the value in the callee. This attribute is only valid on LLVM + pointer arguments. It is generally used to pass structs and arrays by + value, but is also valid on pointers to scalars. The copy is considered + to belong to the caller not the callee (for example, + <tt><a href="#readonly">readonly</a></tt> functions should not write to + <tt>byval</tt> parameters). This is not a valid attribute for return + values. The byval attribute also supports specifying an alignment with + the align attribute. This has a target-specific effect on the code + generator that usually indicates a desired alignment for the synthesized + stack slot.</dd> + + <dt><tt>sret</tt></dt> + <dd>This indicates that the pointer parameter specifies the address of a + structure that is the return value of the function in the source program. + This pointer must be guaranteed by the caller to be valid: loads and + stores to the structure may be assumed by the callee to not to trap. This + may only be applied to the first parameter. This is not a valid attribute + for return values. </dd> + + <dt><tt>noalias</tt></dt> + <dd>This indicates that the pointer does not alias any global or any other + parameter. The caller is responsible for ensuring that this is the + case. On a function return value, <tt>noalias</tt> additionally indicates + that the pointer does not alias any other pointers visible to the + caller. For further details, please see the discussion of the NoAlias + response in + <a href="http://llvm.org/docs/AliasAnalysis.html#MustMayNo">alias + analysis</a>.</dd> + + <dt><tt>nocapture</tt></dt> + <dd>This indicates that the callee does not make any copies of the pointer + that outlive the callee itself. This is not a valid attribute for return + values.</dd> + + <dt><tt>nest</tt></dt> + <dd>This indicates that the pointer parameter can be excised using the + <a href="#int_trampoline">trampoline intrinsics</a>. This is not a valid + attribute for return values.</dd> +</dl> </div> @@ -1002,15 +1004,20 @@ declare signext i8 @returns_signed_char() </div> <div class="doc_text"> + <p>Each function may specify a garbage collector name, which is simply a -string.</p> + string:</p> -<div class="doc_code"><pre ->define void @f() gc "name" { ...</pre></div> +<div class="doc_code"> +<pre> +define void @f() gc "name" { ... +</pre> +</div> <p>The compiler declares the supported values of <i>name</i>. Specifying a -collector which will cause the compiler to alter its output in order to support -the named garbage collection algorithm.</p> + collector which will cause the compiler to alter its output in order to + support the named garbage collection algorithm.</p> + </div> <!-- ======================================================================= --> @@ -1020,14 +1027,13 @@ the named garbage collection algorithm.</p> <div class="doc_text"> -<p>Function attributes are set to communicate additional information about - a function. Function attributes are considered to be part of the function, - not of the function type, so functions with different parameter attributes - can have the same function type.</p> +<p>Function attributes are set to communicate additional information about a + function. Function attributes are considered to be part of the function, not + of the function type, so functions with different parameter attributes can + have the same function type.</p> - <p>Function attributes are simple keywords that follow the type specified. If - multiple attributes are needed, they are space separated. For - example:</p> +<p>Function attributes are simple keywords that follow the type specified. If + multiple attributes are needed, they are space separated. For example:</p> <div class="doc_code"> <pre> @@ -1039,80 +1045,89 @@ define void @f() optsize </div> <dl> -<dt><tt>alwaysinline</tt></dt> -<dd>This attribute indicates that the inliner should attempt to inline this -function into callers whenever possible, ignoring any active inlining size -threshold for this caller.</dd> - -<dt><tt>noinline</tt></dt> -<dd>This attribute indicates that the inliner should never inline this function -in any situation. This attribute may not be used together with the -<tt>alwaysinline</tt> attribute.</dd> - -<dt><tt>optsize</tt></dt> -<dd>This attribute suggests that optimization passes and code generator passes -make choices that keep the code size of this function low, and otherwise do -optimizations specifically to reduce code size.</dd> - -<dt><tt>noreturn</tt></dt> -<dd>This function attribute indicates that the function never returns normally. -This produces undefined behavior at runtime if the function ever does -dynamically return.</dd> - -<dt><tt>nounwind</tt></dt> -<dd>This function attribute indicates that the function never returns with an -unwind or exceptional control flow. If the function does unwind, its runtime -behavior is undefined.</dd> - -<dt><tt>readnone</tt></dt> -<dd>This attribute indicates that the function computes its result (or decides to -unwind an exception) based strictly on its arguments, without dereferencing any -pointer arguments or otherwise accessing any mutable state (e.g. memory, control -registers, etc) visible to caller functions. It does not write through any -pointer arguments (including <tt><a href="#byval">byval</a></tt> arguments) and -never changes any state visible to callers. This means that it cannot unwind -exceptions by calling the <tt>C++</tt> exception throwing methods, but could -use the <tt>unwind</tt> instruction.</dd> - -<dt><tt><a name="readonly">readonly</a></tt></dt> -<dd>This attribute indicates that the function does not write through any -pointer arguments (including <tt><a href="#byval">byval</a></tt> arguments) -or otherwise modify any state (e.g. memory, control registers, etc) visible to -caller functions. It may dereference pointer arguments and read state that may -be set in the caller. A readonly function always returns the same value (or -unwinds an exception identically) when called with the same set of arguments -and global state. It cannot unwind an exception by calling the <tt>C++</tt> -exception throwing methods, but may use the <tt>unwind</tt> instruction.</dd> - -<dt><tt><a name="ssp">ssp</a></tt></dt> -<dd>This attribute indicates that the function should emit a stack smashing -protector. It is in the form of a "canary"—a random value placed on the -stack before the local variables that's checked upon return from the function to -see if it has been overwritten. A heuristic is used to determine if a function -needs stack protectors or not. - -<br><br>If a function that has an <tt>ssp</tt> attribute is inlined into a function -that doesn't have an <tt>ssp</tt> attribute, then the resulting function will -have an <tt>ssp</tt> attribute.</dd> - -<dt><tt>sspreq</tt></dt> -<dd>This attribute indicates that the function should <em>always</em> emit a -stack smashing protector. This overrides the <tt><a href="#ssp">ssp</a></tt> -function attribute. - -If a function that has an <tt>sspreq</tt> attribute is inlined into a -function that doesn't have an <tt>sspreq</tt> attribute or which has -an <tt>ssp</tt> attribute, then the resulting function will have -an <tt>sspreq</tt> attribute.</dd> - -<dt><tt>noredzone</tt></dt> -<dd>This attribute indicates that the code generator should not use a -red zone, even if the target-specific ABI normally permits it. -</dd> - -<dt><tt>noimplicitfloat</tt></dt> -<dd>This attributes disables implicit floating point instructions.</dd> - + <dt><tt>alwaysinline</tt></dt> + <dd>This attribute indicates that the inliner should attempt to inline this + function into callers whenever possible, ignoring any active inlining size + threshold for this caller.</dd> + + <dt><tt>inlinehint</tt></dt> + <dd>This attribute indicates that the source code contained a hint that inlining + this function is desirable (such as the "inline" keyword in C/C++). It + is just a hint; it imposes no requirements on the inliner.</dd> + + <dt><tt>noinline</tt></dt> + <dd>This attribute indicates that the inliner should never inline this + function in any situation. This attribute may not be used together with + the <tt>alwaysinline</tt> attribute.</dd> + + <dt><tt>optsize</tt></dt> + <dd>This attribute suggests that optimization passes and code generator passes + make choices that keep the code size of this function low, and otherwise + do optimizations specifically to reduce code size.</dd> + + <dt><tt>noreturn</tt></dt> + <dd>This function attribute indicates that the function never returns + normally. This produces undefined behavior at runtime if the function + ever does dynamically return.</dd> + + <dt><tt>nounwind</tt></dt> + <dd>This function attribute indicates that the function never returns with an + unwind or exceptional control flow. If the function does unwind, its + runtime behavior is undefined.</dd> + + <dt><tt>readnone</tt></dt> + <dd>This attribute indicates that the function computes its result (or decides + to unwind an exception) based strictly on its arguments, without + dereferencing any pointer arguments or otherwise accessing any mutable + state (e.g. memory, control registers, etc) visible to caller functions. + It does not write through any pointer arguments + (including <tt><a href="#byval">byval</a></tt> arguments) and never + changes any state visible to callers. This means that it cannot unwind + exceptions by calling the <tt>C++</tt> exception throwing methods, but + could use the <tt>unwind</tt> instruction.</dd> + + <dt><tt><a name="readonly">readonly</a></tt></dt> + <dd>This attribute indicates that the function does not write through any + pointer arguments (including <tt><a href="#byval">byval</a></tt> + arguments) or otherwise modify any state (e.g. memory, control registers, + etc) visible to caller functions. It may dereference pointer arguments + and read state that may be set in the caller. A readonly function always + returns the same value (or unwinds an exception identically) when called + with the same set of arguments and global state. It cannot unwind an + exception by calling the <tt>C++</tt> exception throwing methods, but may + use the <tt>unwind</tt> instruction.</dd> + + <dt><tt><a name="ssp">ssp</a></tt></dt> + <dd>This attribute indicates that the function should emit a stack smashing + protector. It is in the form of a "canary"—a random value placed on + the stack before the local variables that's checked upon return from the + function to see if it has been overwritten. A heuristic is used to + determine if a function needs stack protectors or not.<br> +<br> + If a function that has an <tt>ssp</tt> attribute is inlined into a + function that doesn't have an <tt>ssp</tt> attribute, then the resulting + function will have an <tt>ssp</tt> attribute.</dd> + + <dt><tt>sspreq</tt></dt> + <dd>This attribute indicates that the function should <em>always</em> emit a + stack smashing protector. This overrides + the <tt><a href="#ssp">ssp</a></tt> function attribute.<br> +<br> + If a function that has an <tt>sspreq</tt> attribute is inlined into a + function that doesn't have an <tt>sspreq</tt> attribute or which has + an <tt>ssp</tt> attribute, then the resulting function will have + an <tt>sspreq</tt> attribute.</dd> + + <dt><tt>noredzone</tt></dt> + <dd>This attribute indicates that the code generator should not use a red + zone, even if the target-specific ABI normally permits it.</dd> + + <dt><tt>noimplicitfloat</tt></dt> + <dd>This attributes disables implicit floating point instructions.</dd> + + <dt><tt>naked</tt></dt> + <dd>This attribute disables prologue / epilogue emission for the function. + This can have very system-specific consequences.</dd> </dl> </div> @@ -1123,12 +1138,11 @@ red zone, even if the target-specific ABI normally permits it. </div> <div class="doc_text"> -<p> -Modules may contain "module-level inline asm" blocks, which corresponds to the -GCC "file scope inline asm" blocks. These blocks are internally concatenated by -LLVM and treated as a single unit, but may be separated in the .ll file if -desired. The syntax is very simple: -</p> + +<p>Modules may contain "module-level inline asm" blocks, which corresponds to + the GCC "file scope inline asm" blocks. These blocks are internally + concatenated by LLVM and treated as a single unit, but may be separated in + the <tt>.ll</tt> file if desired. The syntax is very simple:</p> <div class="doc_code"> <pre> @@ -1139,13 +1153,11 @@ module asm "more can go here" <p>The strings can contain any character by escaping non-printable characters. The escape sequence used is simply "\xx" where "xx" is the two digit hex code - for the number. -</p> + for the number.</p> + +<p>The inline asm code is simply printed to the machine code .s file when + assembly code is generated.</p> -<p> - The inline asm code is simply printed to the machine code .s file when - assembly code is generated. -</p> </div> <!-- ======================================================================= --> @@ -1154,46 +1166,65 @@ module asm "more can go here" </div> <div class="doc_text"> + <p>A module may specify a target specific data layout string that specifies how -data is to be laid out in memory. The syntax for the data layout is simply:</p> -<pre> target datalayout = "<i>layout specification</i>"</pre> -<p>The <i>layout specification</i> consists of a list of specifications -separated by the minus sign character ('-'). Each specification starts with a -letter and may include other information after the letter to define some -aspect of the data layout. The specifications accepted are as follows: </p> + data is to be laid out in memory. The syntax for the data layout is + simply:</p> + +<div class="doc_code"> +<pre> +target datalayout = "<i>layout specification</i>" +</pre> +</div> + +<p>The <i>layout specification</i> consists of a list of specifications + separated by the minus sign character ('-'). Each specification starts with + a letter and may include other information after the letter to define some + aspect of the data layout. The specifications accepted are as follows:</p> + <dl> <dt><tt>E</tt></dt> <dd>Specifies that the target lays out data in big-endian form. That is, the - bits with the most significance have the lowest address location.</dd> + bits with the most significance have the lowest address location.</dd> + <dt><tt>e</tt></dt> <dd>Specifies that the target lays out data in little-endian form. That is, - the bits with the least significance have the lowest address location.</dd> + the bits with the least significance have the lowest address + location.</dd> + <dt><tt>p:<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> <dd>This specifies the <i>size</i> of a pointer and its <i>abi</i> and - <i>preferred</i> alignments. All sizes are in bits. Specifying the <i>pref</i> - alignment is optional. If omitted, the preceding <tt>:</tt> should be omitted - too.</dd> + <i>preferred</i> alignments. All sizes are in bits. Specifying + the <i>pref</i> alignment is optional. If omitted, the + preceding <tt>:</tt> should be omitted too.</dd> + <dt><tt>i<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> <dd>This specifies the alignment for an integer type of a given bit - <i>size</i>. The value of <i>size</i> must be in the range [1,2^23).</dd> + <i>size</i>. The value of <i>size</i> must be in the range [1,2^23).</dd> + <dt><tt>v<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> <dd>This specifies the alignment for a vector type of a given bit - <i>size</i>.</dd> + <i>size</i>.</dd> + <dt><tt>f<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> <dd>This specifies the alignment for a floating point type of a given bit - <i>size</i>. The value of <i>size</i> must be either 32 (float) or 64 - (double).</dd> + <i>size</i>. The value of <i>size</i> must be either 32 (float) or 64 + (double).</dd> + <dt><tt>a<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> <dd>This specifies the alignment for an aggregate type of a given bit - <i>size</i>.</dd> + <i>size</i>.</dd> + <dt><tt>s<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> <dd>This specifies the alignment for a stack object of a given bit - <i>size</i>.</dd> + <i>size</i>.</dd> </dl> + <p>When constructing the data layout for a given target, LLVM starts with a -default set of specifications which are then (possibly) overriden by the -specifications in the <tt>datalayout</tt> keyword. The default specifications -are given in this list:</p> + default set of specifications which are then (possibly) overriden by the + specifications in the <tt>datalayout</tt> keyword. The default specifications + are given in this list:</p> + <ul> <li><tt>E</tt> - big endian</li> <li><tt>p:32:64:64</tt> - 32-bit pointers with 64-bit alignment</li> @@ -1210,22 +1241,80 @@ are given in this list:</p> <li><tt>a0:0:1</tt> - aggregates are 8-bit aligned</li> <li><tt>s0:64:64</tt> - stack objects are 64-bit aligned</li> </ul> -<p>When LLVM is determining the alignment for a given type, it uses the -following rules:</p> + +<p>When LLVM is determining the alignment for a given type, it uses the + following rules:</p> + <ol> <li>If the type sought is an exact match for one of the specifications, that - specification is used.</li> + specification is used.</li> + <li>If no match is found, and the type sought is an integer type, then the - smallest integer type that is larger than the bitwidth of the sought type is - used. If none of the specifications are larger than the bitwidth then the the - largest integer type is used. For example, given the default specifications - above, the i7 type will use the alignment of i8 (next largest) while both - i65 and i256 will use the alignment of i64 (largest specified).</li> + smallest integer type that is larger than the bitwidth of the sought type + is used. If none of the specifications are larger than the bitwidth then + the the largest integer type is used. For example, given the default + specifications above, the i7 type will use the alignment of i8 (next + largest) while both i65 and i256 will use the alignment of i64 (largest + specified).</li> + <li>If no match is found, and the type sought is a vector type, then the - largest vector type that is smaller than the sought vector type will be used - as a fall back. This happens because <128 x double> can be implemented - in terms of 64 <2 x double>, for example.</li> + largest vector type that is smaller than the sought vector type will be + used as a fall back. This happens because <128 x double> can be + implemented in terms of 64 <2 x double>, for example.</li> </ol> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="pointeraliasing">Pointer Aliasing Rules</a> +</div> + +<div class="doc_text"> + +<p>Any memory access must be done through a pointer value associated +with an address range of the memory access, otherwise the behavior +is undefined. Pointer values are associated with address ranges +according to the following rules:</p> + +<ul> + <li>A pointer value formed from a + <tt><a href="#i_getelementptr">getelementptr</a></tt> instruction + is associated with the addresses associated with the first operand + of the <tt>getelementptr</tt>.</li> + <li>An address of a global variable is associated with the address + range of the variable's storage.</li> + <li>The result value of an allocation instruction is associated with + the address range of the allocated storage.</li> + <li>A null pointer in the default address-space is associated with + no address.</li> + <li>A pointer value formed by an + <tt><a href="#i_inttoptr">inttoptr</a></tt> is associated with all + address ranges of all pointer values that contribute (directly or + indirectly) to the computation of the pointer's value.</li> + <li>The result value of a + <tt><a href="#i_bitcast">bitcast</a></tt> is associated with all + addresses associated with the operand of the <tt>bitcast</tt>.</li> + <li>An integer constant other than zero or a pointer value returned + from a function not defined within LLVM may be associated with address + ranges allocated through mechanisms other than those provided by + LLVM. Such ranges shall not overlap with any ranges of addresses + allocated by mechanisms provided by LLVM.</li> + </ul> + +<p>LLVM IR does not associate types with memory. The result type of a +<tt><a href="#i_load">load</a></tt> merely indicates the size and +alignment of the memory from which to load, as well as the +interpretation of the value. The first operand of a +<tt><a href="#i_store">store</a></tt> similarly only indicates the size +and alignment of the store.</p> + +<p>Consequently, type-based alias analysis, aka TBAA, aka +<tt>-fstrict-aliasing</tt>, is not applicable to general unadorned +LLVM IR. <a href="#metadata">Metadata</a> may be used to encode +additional information which specialized optimization passes may use +to implement type-based alias analysis.</p> + </div> <!-- *********************************************************************** --> @@ -1235,22 +1324,22 @@ following rules:</p> <div class="doc_text"> <p>The LLVM type system is one of the most important features of the -intermediate representation. Being typed enables a number of -optimizations to be performed on the intermediate representation directly, -without having to do -extra analyses on the side before the transformation. A strong type -system makes it easier to read the generated code and enables novel -analyses and transformations that are not feasible to perform on normal -three address code representations.</p> + intermediate representation. Being typed enables a number of optimizations + to be performed on the intermediate representation directly, without having + to do extra analyses on the side before the transformation. A strong type + system makes it easier to read the generated code and enables novel analyses + and transformations that are not feasible to perform on normal three address + code representations.</p> </div> <!-- ======================================================================= --> <div class="doc_subsection"> <a name="t_classifications">Type Classifications</a> </div> + <div class="doc_text"> -<p>The types fall into a few useful -classifications:</p> + +<p>The types fall into a few useful classifications:</p> <table border="1" cellspacing="0" cellpadding="4"> <tbody> @@ -1297,18 +1386,60 @@ classifications:</p> </tbody> </table> -<p>The <a href="#t_firstclass">first class</a> types are perhaps the -most important. Values of these types are the only ones which can be -produced by instructions, passed as arguments, or used as operands to -instructions.</p> +<p>The <a href="#t_firstclass">first class</a> types are perhaps the most + important. Values of these types are the only ones which can be produced by + instructions.</p> + </div> <!-- ======================================================================= --> <div class="doc_subsection"> <a name="t_primitive">Primitive Types</a> </div> <div class="doc_text"> + <p>The primitive types are the fundamental building blocks of the LLVM -system.</p> + system.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> <a name="t_integer">Integer Type</a> </div> + +<div class="doc_text"> + +<h5>Overview:</h5> +<p>The integer type is a very simple type that simply specifies an arbitrary + bit width for the integer type desired. Any bit width from 1 bit to + 2<sup>23</sup>-1 (about 8 million) can be specified.</p> + +<h5>Syntax:</h5> +<pre> + iN +</pre> + +<p>The number of bits the integer will occupy is specified by the <tt>N</tt> + value.</p> + +<h5>Examples:</h5> +<table class="layout"> + <tr class="layout"> + <td class="left"><tt>i1</tt></td> + <td class="left">a single-bit integer.</td> + </tr> + <tr class="layout"> + <td class="left"><tt>i32</tt></td> + <td class="left">a 32-bit integer.</td> + </tr> + <tr class="layout"> + <td class="left"><tt>i1942652</tt></td> + <td class="left">a really big integer of over 1 million bits.</td> + </tr> +</table> + +<p>Note that the code generator does not yet support large integer types to be + used as function return types. The specific limit on how large a return type + the code generator can currently handle is target-dependent; currently it's + often 64 bits for 32-bit targets and 128 bits for 64-bit targets.</p> </div> @@ -1316,60 +1447,65 @@ system.</p> <div class="doc_subsubsection"> <a name="t_floating">Floating Point Types</a> </div> <div class="doc_text"> - <table> - <tbody> - <tr><th>Type</th><th>Description</th></tr> - <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr> - <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr> - <tr><td><tt>fp128</tt></td><td>128-bit floating point value (112-bit mantissa)</td></tr> - <tr><td><tt>x86_fp80</tt></td><td>80-bit floating point value (X87)</td></tr> - <tr><td><tt>ppc_fp128</tt></td><td>128-bit floating point value (two 64-bits)</td></tr> - </tbody> - </table> + +<table> + <tbody> + <tr><th>Type</th><th>Description</th></tr> + <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr> + <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr> + <tr><td><tt>fp128</tt></td><td>128-bit floating point value (112-bit mantissa)</td></tr> + <tr><td><tt>x86_fp80</tt></td><td>80-bit floating point value (X87)</td></tr> + <tr><td><tt>ppc_fp128</tt></td><td>128-bit floating point value (two 64-bits)</td></tr> + </tbody> +</table> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_void">Void Type</a> </div> <div class="doc_text"> + <h5>Overview:</h5> <p>The void type does not represent any value and has no size.</p> <h5>Syntax:</h5> - <pre> void </pre> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_label">Label Type</a> </div> <div class="doc_text"> + <h5>Overview:</h5> <p>The label type represents code labels.</p> <h5>Syntax:</h5> - <pre> label </pre> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_metadata">Metadata Type</a> </div> <div class="doc_text"> + <h5>Overview:</h5> -<p>The metadata type represents embedded metadata. The only derived type that -may contain metadata is <tt>metadata*</tt> or a function type that returns or -takes metadata typed parameters, but not pointer to metadata types.</p> +<p>The metadata type represents embedded metadata. No derived types may be + created from metadata except for <a href="#t_function">function</a> + arguments. <h5>Syntax:</h5> - <pre> metadata </pre> + </div> @@ -1378,53 +1514,12 @@ takes metadata typed parameters, but not pointer to metadata types.</p> <div class="doc_text"> -<p>The real power in LLVM comes from the derived types in the system. -This is what allows a programmer to represent arrays, functions, -pointers, and other useful types. Note that these derived types may be -recursive: For example, it is possible to have a two dimensional array.</p> - -</div> - -<!-- _______________________________________________________________________ --> -<div class="doc_subsubsection"> <a name="t_integer">Integer Type</a> </div> - -<div class="doc_text"> - -<h5>Overview:</h5> -<p>The integer type is a very simple derived type that simply specifies an -arbitrary bit width for the integer type desired. Any bit width from 1 bit to -2^23-1 (about 8 million) can be specified.</p> - -<h5>Syntax:</h5> - -<pre> - iN -</pre> - -<p>The number of bits the integer will occupy is specified by the <tt>N</tt> -value.</p> - -<h5>Examples:</h5> -<table class="layout"> - <tr class="layout"> - <td class="left"><tt>i1</tt></td> - <td class="left">a single-bit integer.</td> - </tr> - <tr class="layout"> - <td class="left"><tt>i32</tt></td> - <td class="left">a 32-bit integer.</td> - </tr> - <tr class="layout"> - <td class="left"><tt>i1942652</tt></td> - <td class="left">a really big integer of over 1 million bits.</td> - </tr> -</table> - -<p>Note that the code generator does not yet support large integer types -to be used as function return types. The specific limit on how large a -return type the code generator can currently handle is target-dependent; -currently it's often 64 bits for 32-bit targets and 128 bits for 64-bit -targets.</p> +<p>The real power in LLVM comes from the derived types in the system. This is + what allows a programmer to represent arrays, functions, pointers, and other + useful types. Each of these types contain one or more element types which + may be a primitive type, or another derived type. For example, it is + possible to have a two dimensional array, using an array as the element type + of another array.</p> </div> @@ -1434,19 +1529,17 @@ targets.</p> <div class="doc_text"> <h5>Overview:</h5> - <p>The array type is a very simple derived type that arranges elements -sequentially in memory. The array type requires a size (number of -elements) and an underlying data type.</p> + sequentially in memory. The array type requires a size (number of elements) + and an underlying data type.</p> <h5>Syntax:</h5> - <pre> [<# elements> x <elementtype>] </pre> -<p>The number of elements is a constant integer value; elementtype may -be any type with a size.</p> +<p>The number of elements is a constant integer value; <tt>elementtype</tt> may + be any type with a size.</p> <h5>Examples:</h5> <table class="layout"> @@ -1479,45 +1572,44 @@ be any type with a size.</p> </tr> </table> -<p>Note that 'variable sized arrays' can be implemented in LLVM with a zero -length array. Normally, accesses past the end of an array are undefined in -LLVM (e.g. it is illegal to access the 5th element of a 3 element array). -As a special case, however, zero length arrays are recognized to be variable -length. This allows implementation of 'pascal style arrays' with the LLVM -type "{ i32, [0 x float]}", for example.</p> +<p>Note that 'variable sized arrays' can be implemented in LLVM with a zero + length array. Normally, accesses past the end of an array are undefined in + LLVM (e.g. it is illegal to access the 5th element of a 3 element array). As + a special case, however, zero length arrays are recognized to be variable + length. This allows implementation of 'pascal style arrays' with the LLVM + type "<tt>{ i32, [0 x float]}</tt>", for example.</p> -<p>Note that the code generator does not yet support large aggregate types -to be used as function return types. The specific limit on how large an -aggregate return type the code generator can currently handle is -target-dependent, and also dependent on the aggregate element types.</p> +<p>Note that the code generator does not yet support large aggregate types to be + used as function return types. The specific limit on how large an aggregate + return type the code generator can currently handle is target-dependent, and + also dependent on the aggregate element types.</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_function">Function Type</a> </div> + <div class="doc_text"> <h5>Overview:</h5> - -<p>The function type can be thought of as a function signature. It -consists of a return type and a list of formal parameter types. The -return type of a function type is a scalar type, a void type, or a struct type. -If the return type is a struct type then all struct elements must be of first -class types, and the struct must have at least one element.</p> +<p>The function type can be thought of as a function signature. It consists of + a return type and a list of formal parameter types. The return type of a + function type is a scalar type, a void type, or a struct type. If the return + type is a struct type then all struct elements must be of first class types, + and the struct must have at least one element.</p> <h5>Syntax:</h5> - <pre> - <returntype list> (<parameter list>) + <returntype> (<parameter list>) </pre> <p>...where '<tt><parameter list></tt>' is a comma-separated list of type -specifiers. Optionally, the parameter list may include a type <tt>...</tt>, -which indicates that the function takes a variable number of arguments. -Variable argument functions can access their arguments with the <a - href="#int_varargs">variable argument handling intrinsic</a> functions. -'<tt><returntype list></tt>' is a comma-separated list of -<a href="#t_firstclass">first class</a> type specifiers.</p> + specifiers. Optionally, the parameter list may include a type <tt>...</tt>, + which indicates that the function takes a variable number of arguments. + Variable argument functions can access their arguments with + the <a href="#int_varargs">variable argument handling intrinsic</a> + functions. '<tt><returntype></tt>' is a any type except + <a href="#t_label">label</a>.</p> <h5>Examples:</h5> <table class="layout"> @@ -1542,27 +1634,34 @@ Variable argument functions can access their arguments with the <a </td> </tr><tr class="layout"> <td class="left"><tt>{i32, i32} (i32)</tt></td> - <td class="left">A function taking an <tt>i32</tt>, returning two - <tt>i32</tt> values as an aggregate of type <tt>{ i32, i32 }</tt> + <td class="left">A function taking an <tt>i32</tt>, returning a + <a href="#t_struct">structure</a> containing two <tt>i32</tt> values </td> </tr> </table> </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_struct">Structure Type</a> </div> + <div class="doc_text"> + <h5>Overview:</h5> -<p>The structure type is used to represent a collection of data members -together in memory. The packing of the field types is defined to match -the ABI of the underlying processor. The elements of a structure may -be any type that has a size.</p> -<p>Structures are accessed using '<tt><a href="#i_load">load</a></tt> -and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a -field with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' -instruction.</p> +<p>The structure type is used to represent a collection of data members together + in memory. The packing of the field types is defined to match the ABI of the + underlying processor. The elements of a structure may be any type that has a + size.</p> + +<p>Structures are accessed using '<tt><a href="#i_load">load</a></tt> and + '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field with + the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p> + <h5>Syntax:</h5> -<pre> { <type list> }<br></pre> +<pre> + { <type list> } +</pre> + <h5>Examples:</h5> <table class="layout"> <tr class="layout"> @@ -1577,28 +1676,34 @@ instruction.</p> </tr> </table> -<p>Note that the code generator does not yet support large aggregate types -to be used as function return types. The specific limit on how large an -aggregate return type the code generator can currently handle is -target-dependent, and also dependent on the aggregate element types.</p> +<p>Note that the code generator does not yet support large aggregate types to be + used as function return types. The specific limit on how large an aggregate + return type the code generator can currently handle is target-dependent, and + also dependent on the aggregate element types.</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_pstruct">Packed Structure Type</a> </div> + <div class="doc_text"> + <h5>Overview:</h5> <p>The packed structure type is used to represent a collection of data members -together in memory. There is no padding between fields. Further, the alignment -of a packed structure is 1 byte. The elements of a packed structure may -be any type that has a size.</p> -<p>Structures are accessed using '<tt><a href="#i_load">load</a></tt> -and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a -field with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' -instruction.</p> + together in memory. There is no padding between fields. Further, the + alignment of a packed structure is 1 byte. The elements of a packed + structure may be any type that has a size.</p> + +<p>Structures are accessed using '<tt><a href="#i_load">load</a></tt> and + '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field with + the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p> + <h5>Syntax:</h5> -<pre> < { <type list> } > <br></pre> +<pre> + < { <type list> } > +</pre> + <h5>Examples:</h5> <table class="layout"> <tr class="layout"> @@ -1613,23 +1718,28 @@ instruction.</p> an <tt>i32</tt>.</td> </tr> </table> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_pointer">Pointer Type</a> </div> + <div class="doc_text"> + <h5>Overview:</h5> -<p>As in many languages, the pointer type represents a pointer or -reference to another object, which must live in memory. Pointer types may have -an optional address space attribute defining the target-specific numbered -address space where the pointed-to object resides. The default address space is -zero.</p> +<p>As in many languages, the pointer type represents a pointer or reference to + another object, which must live in memory. Pointer types may have an optional + address space attribute defining the target-specific numbered address space + where the pointed-to object resides. The default address space is zero.</p> -<p>Note that LLVM does not permit pointers to void (<tt>void*</tt>) nor does -it permit pointers to labels (<tt>label*</tt>). Use <tt>i8*</tt> instead.</p> +<p>Note that LLVM does not permit pointers to void (<tt>void*</tt>) nor does it + permit pointers to labels (<tt>label*</tt>). Use <tt>i8*</tt> instead.</p> <h5>Syntax:</h5> -<pre> <type> *<br></pre> +<pre> + <type> * +</pre> + <h5>Examples:</h5> <table class="layout"> <tr class="layout"> @@ -1649,33 +1759,31 @@ it permit pointers to labels (<tt>label*</tt>). Use <tt>i8*</tt> instead.</p> that resides in address space #5.</td> </tr> </table> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_vector">Vector Type</a> </div> + <div class="doc_text"> <h5>Overview:</h5> - -<p>A vector type is a simple derived type that represents a vector -of elements. Vector types are used when multiple primitive data -are operated in parallel using a single instruction (SIMD). -A vector type requires a size (number of -elements) and an underlying primitive data type. Vectors must have a power -of two length (1, 2, 4, 8, 16 ...). Vector types are -considered <a href="#t_firstclass">first class</a>.</p> +<p>A vector type is a simple derived type that represents a vector of elements. + Vector types are used when multiple primitive data are operated in parallel + using a single instruction (SIMD). A vector type requires a size (number of + elements) and an underlying primitive data type. Vectors must have a power + of two length (1, 2, 4, 8, 16 ...). Vector types are considered + <a href="#t_firstclass">first class</a>.</p> <h5>Syntax:</h5> - <pre> < <# elements> x <elementtype> > </pre> -<p>The number of elements is a constant integer value; elementtype may -be any integer or floating point type.</p> +<p>The number of elements is a constant integer value; elementtype may be any + integer or floating point type.</p> <h5>Examples:</h5> - <table class="layout"> <tr class="layout"> <td class="left"><tt><4 x i32></tt></td> @@ -1691,10 +1799,10 @@ be any integer or floating point type.</p> </tr> </table> -<p>Note that the code generator does not yet support large vector types -to be used as function return types. The specific limit on how large a -vector return type codegen can currently handle is target-dependent; -currently it's often a few times longer than a hardware vector register.</p> +<p>Note that the code generator does not yet support large vector types to be + used as function return types. The specific limit on how large a vector + return type codegen can currently handle is target-dependent; currently it's + often a few times longer than a hardware vector register.</p> </div> @@ -1703,26 +1811,24 @@ currently it's often a few times longer than a hardware vector register.</p> <div class="doc_text"> <h5>Overview:</h5> - <p>Opaque types are used to represent unknown types in the system. This -corresponds (for example) to the C notion of a forward declared structure type. -In LLVM, opaque types can eventually be resolved to any type (not just a -structure type).</p> + corresponds (for example) to the C notion of a forward declared structure + type. In LLVM, opaque types can eventually be resolved to any type (not just + a structure type).</p> <h5>Syntax:</h5> - <pre> opaque </pre> <h5>Examples:</h5> - <table class="layout"> <tr class="layout"> <td class="left"><tt>opaque</tt></td> <td class="left">An opaque type.</td> </tr> </table> + </div> <!-- ======================================================================= --> @@ -1731,12 +1837,13 @@ structure type).</p> </div> <div class="doc_text"> + <h5>Overview:</h5> -<p> -An "up reference" allows you to refer to a lexically enclosing type without -requiring it to have a name. For instance, a structure declaration may contain a -pointer to any of the types it is lexically a member of. Example of up -references (with their equivalent as named type declarations) include:</p> +<p>An "up reference" allows you to refer to a lexically enclosing type without + requiring it to have a name. For instance, a structure declaration may + contain a pointer to any of the types it is lexically a member of. Example + of up references (with their equivalent as named type declarations) + include:</p> <pre> { \2 * } %x = type { %x* } @@ -1744,24 +1851,20 @@ references (with their equivalent as named type declarations) include:</p> \1* %z = type %z* </pre> -<p> -An up reference is needed by the asmprinter for printing out cyclic types when -there is no declared name for a type in the cycle. Because the asmprinter does -not want to print out an infinite type string, it needs a syntax to handle -recursive types that have no names (all names are optional in llvm IR). -</p> +<p>An up reference is needed by the asmprinter for printing out cyclic types + when there is no declared name for a type in the cycle. Because the + asmprinter does not want to print out an infinite type string, it needs a + syntax to handle recursive types that have no names (all names are optional + in llvm IR).</p> <h5>Syntax:</h5> <pre> \<level> </pre> -<p> -The level is the count of the lexical type that is being referred to. -</p> +<p>The level is the count of the lexical type that is being referred to.</p> <h5>Examples:</h5> - <table class="layout"> <tr class="layout"> <td class="left"><tt>\1*</tt></td> @@ -1773,8 +1876,8 @@ The level is the count of the lexical type that is being referred to. structure.</td> </tr> </table> -</div> +</div> <!-- *********************************************************************** --> <div class="doc_section"> <a name="constants">Constants</a> </div> @@ -1783,7 +1886,7 @@ The level is the count of the lexical type that is being referred to. <div class="doc_text"> <p>LLVM has several different basic types of constants. This section describes -them all and their syntax.</p> + them all and their syntax.</p> </div> @@ -1794,118 +1897,103 @@ them all and their syntax.</p> <dl> <dt><b>Boolean constants</b></dt> - <dd>The two strings '<tt>true</tt>' and '<tt>false</tt>' are both valid - constants of the <tt><a href="#t_primitive">i1</a></tt> type. - </dd> + constants of the <tt><a href="#t_integer">i1</a></tt> type.</dd> <dt><b>Integer constants</b></dt> - - <dd>Standard integers (such as '4') are constants of the <a - href="#t_integer">integer</a> type. Negative numbers may be used with - integer types. - </dd> + <dd>Standard integers (such as '4') are constants of + the <a href="#t_integer">integer</a> type. Negative numbers may be used + with integer types.</dd> <dt><b>Floating point constants</b></dt> - <dd>Floating point constants use standard decimal notation (e.g. 123.421), - exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal - notation (see below). The assembler requires the exact decimal value of - a floating-point constant. For example, the assembler accepts 1.25 but - rejects 1.3 because 1.3 is a repeating decimal in binary. Floating point - constants must have a <a href="#t_floating">floating point</a> type. </dd> + exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal + notation (see below). The assembler requires the exact decimal value of a + floating-point constant. For example, the assembler accepts 1.25 but + rejects 1.3 because 1.3 is a repeating decimal in binary. Floating point + constants must have a <a href="#t_floating">floating point</a> type. </dd> <dt><b>Null pointer constants</b></dt> - <dd>The identifier '<tt>null</tt>' is recognized as a null pointer constant - and must be of <a href="#t_pointer">pointer type</a>.</dd> - + and must be of <a href="#t_pointer">pointer type</a>.</dd> </dl> -<p>The one non-intuitive notation for constants is the hexadecimal form -of floating point constants. For example, the form '<tt>double -0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) '<tt>double -4.5e+15</tt>'. The only time hexadecimal floating point constants are required -(and the only time that they are generated by the disassembler) is when a -floating point constant must be emitted but it cannot be represented as a -decimal floating point number in a reasonable number of digits. For example, -NaN's, infinities, and other -special values are represented in their IEEE hexadecimal format so that -assembly and disassembly do not cause any bits to change in the constants.</p> +<p>The one non-intuitive notation for constants is the hexadecimal form of + floating point constants. For example, the form '<tt>double + 0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) + '<tt>double 4.5e+15</tt>'. The only time hexadecimal floating point + constants are required (and the only time that they are generated by the + disassembler) is when a floating point constant must be emitted but it cannot + be represented as a decimal floating point number in a reasonable number of + digits. For example, NaN's, infinities, and other special values are + represented in their IEEE hexadecimal format so that assembly and disassembly + do not cause any bits to change in the constants.</p> + <p>When using the hexadecimal form, constants of types float and double are -represented using the 16-digit form shown above (which matches the IEEE754 -representation for double); float values must, however, be exactly representable -as IEE754 single precision. -Hexadecimal format is always used for long -double, and there are three forms of long double. The 80-bit -format used by x86 is represented as <tt>0xK</tt> -followed by 20 hexadecimal digits. -The 128-bit format used by PowerPC (two adjacent doubles) is represented -by <tt>0xM</tt> followed by 32 hexadecimal digits. The IEEE 128-bit -format is represented -by <tt>0xL</tt> followed by 32 hexadecimal digits; no currently supported -target uses this format. Long doubles will only work if they match -the long double format on your target. All hexadecimal formats are big-endian -(sign bit at the left).</p> + represented using the 16-digit form shown above (which matches the IEEE754 + representation for double); float values must, however, be exactly + representable as IEE754 single precision. Hexadecimal format is always used + for long double, and there are three forms of long double. The 80-bit format + used by x86 is represented as <tt>0xK</tt> followed by 20 hexadecimal digits. + The 128-bit format used by PowerPC (two adjacent doubles) is represented + by <tt>0xM</tt> followed by 32 hexadecimal digits. The IEEE 128-bit format + is represented by <tt>0xL</tt> followed by 32 hexadecimal digits; no + currently supported target uses this format. Long doubles will only work if + they match the long double format on your target. All hexadecimal formats + are big-endian (sign bit at the left).</p> + </div> <!-- ======================================================================= --> <div class="doc_subsection"> -<a name="aggregateconstants"> <!-- old anchor --> -<a name="complexconstants">Complex Constants</a></a> +<a name="aggregateconstants"></a> <!-- old anchor --> +<a name="complexconstants">Complex Constants</a> </div> <div class="doc_text"> + <p>Complex constants are a (potentially recursive) combination of simple -constants and smaller complex constants.</p> + constants and smaller complex constants.</p> <dl> <dt><b>Structure constants</b></dt> - <dd>Structure constants are represented with notation similar to structure - type definitions (a comma separated list of elements, surrounded by braces - (<tt>{}</tt>)). For example: "<tt>{ i32 4, float 17.0, i32* @G }</tt>", - where "<tt>@G</tt>" is declared as "<tt>@G = external global i32</tt>". Structure constants - must have <a href="#t_struct">structure type</a>, and the number and - types of elements must match those specified by the type. - </dd> + type definitions (a comma separated list of elements, surrounded by braces + (<tt>{}</tt>)). For example: "<tt>{ i32 4, float 17.0, i32* @G }</tt>", + where "<tt>@G</tt>" is declared as "<tt>@G = external global i32</tt>". + Structure constants must have <a href="#t_struct">structure type</a>, and + the number and types of elements must match those specified by the + type.</dd> <dt><b>Array constants</b></dt> - <dd>Array constants are represented with notation similar to array type - definitions (a comma separated list of elements, surrounded by square brackets - (<tt>[]</tt>)). For example: "<tt>[ i32 42, i32 11, i32 74 ]</tt>". Array - constants must have <a href="#t_array">array type</a>, and the number and - types of elements must match those specified by the type. - </dd> + definitions (a comma separated list of elements, surrounded by square + brackets (<tt>[]</tt>)). For example: "<tt>[ i32 42, i32 11, i32 74 + ]</tt>". Array constants must have <a href="#t_array">array type</a>, and + the number and types of elements must match those specified by the + type.</dd> <dt><b>Vector constants</b></dt> - <dd>Vector constants are represented with notation similar to vector type - definitions (a comma separated list of elements, surrounded by - less-than/greater-than's (<tt><></tt>)). For example: "<tt>< i32 42, - i32 11, i32 74, i32 100 ></tt>". Vector constants must have <a - href="#t_vector">vector type</a>, and the number and types of elements must - match those specified by the type. - </dd> + definitions (a comma separated list of elements, surrounded by + less-than/greater-than's (<tt><></tt>)). For example: "<tt>< i32 + 42, i32 11, i32 74, i32 100 ></tt>". Vector constants must + have <a href="#t_vector">vector type</a>, and the number and types of + elements must match those specified by the type.</dd> <dt><b>Zero initialization</b></dt> - <dd>The string '<tt>zeroinitializer</tt>' can be used to zero initialize a - value to zero of <em>any</em> type, including scalar and aggregate types. - This is often used to avoid having to print large zero initializers (e.g. for - large arrays) and is always exactly equivalent to using explicit zero - initializers. - </dd> + value to zero of <em>any</em> type, including scalar and aggregate types. + This is often used to avoid having to print large zero initializers + (e.g. for large arrays) and is always exactly equivalent to using explicit + zero initializers.</dd> <dt><b>Metadata node</b></dt> - <dd>A metadata node is a structure-like constant with - <a href="#t_metadata">metadata type</a>. For example: - "<tt>metadata !{ i32 0, metadata !"test" }</tt>". Unlike other constants - that are meant to be interpreted as part of the instruction stream, metadata - is a place to attach additional information such as debug info. - </dd> + <a href="#t_metadata">metadata type</a>. For example: "<tt>metadata !{ + i32 0, metadata !"test" }</tt>". Unlike other constants that are meant to + be interpreted as part of the instruction stream, metadata is a place to + attach additional information such as debug info.</dd> </dl> </div> @@ -1917,12 +2005,12 @@ constants and smaller complex constants.</p> <div class="doc_text"> -<p>The addresses of <a href="#globalvars">global variables</a> and <a -href="#functionstructure">functions</a> are always implicitly valid (link-time) -constants. These constants are explicitly referenced when the <a -href="#identifiers">identifier for the global</a> is used and always have <a -href="#t_pointer">pointer</a> type. For example, the following is a legal LLVM -file:</p> +<p>The addresses of <a href="#globalvars">global variables</a> + and <a href="#functionstructure">functions</a> are always implicitly valid + (link-time) constants. These constants are explicitly referenced when + the <a href="#identifiers">identifier for the global</a> is used and always + have <a href="#t_pointer">pointer</a> type. For example, the following is a + legal LLVM file:</p> <div class="doc_code"> <pre> @@ -1937,13 +2025,150 @@ file:</p> <!-- ======================================================================= --> <div class="doc_subsection"><a name="undefvalues">Undefined Values</a></div> <div class="doc_text"> - <p>The string '<tt>undef</tt>' is recognized as a type-less constant that has - no specific value. Undefined values may be of any type and be used anywhere - a constant is permitted.</p> - <p>Undefined values indicate to the compiler that the program is well defined - no matter what value is used, giving the compiler more freedom to optimize. - </p> +<p>The string '<tt>undef</tt>' can be used anywhere a constant is expected, and + indicates that the user of the value may receive an unspecified bit-pattern. + Undefined values may be of any type (other than label or void) and be used + anywhere a constant is permitted.</p> + +<p>Undefined values are useful because they indicate to the compiler that the + program is well defined no matter what value is used. This gives the + compiler more freedom to optimize. Here are some examples of (potentially + surprising) transformations that are valid (in pseudo IR):</p> + + +<div class="doc_code"> +<pre> + %A = add %X, undef + %B = sub %X, undef + %C = xor %X, undef +Safe: + %A = undef + %B = undef + %C = undef +</pre> +</div> + +<p>This is safe because all of the output bits are affected by the undef bits. +Any output bit can have a zero or one depending on the input bits.</p> + +<div class="doc_code"> +<pre> + %A = or %X, undef + %B = and %X, undef +Safe: + %A = -1 + %B = 0 +Unsafe: + %A = undef + %B = undef +</pre> +</div> + +<p>These logical operations have bits that are not always affected by the input. +For example, if "%X" has a zero bit, then the output of the 'and' operation will +always be a zero, no matter what the corresponding bit from the undef is. As +such, it is unsafe to optimize or assume that the result of the and is undef. +However, it is safe to assume that all bits of the undef could be 0, and +optimize the and to 0. Likewise, it is safe to assume that all the bits of +the undef operand to the or could be set, allowing the or to be folded to +-1.</p> + +<div class="doc_code"> +<pre> + %A = select undef, %X, %Y + %B = select undef, 42, %Y + %C = select %X, %Y, undef +Safe: + %A = %X (or %Y) + %B = 42 (or %Y) + %C = %Y +Unsafe: + %A = undef + %B = undef + %C = undef +</pre> +</div> + +<p>This set of examples show that undefined select (and conditional branch) +conditions can go "either way" but they have to come from one of the two +operands. In the %A example, if %X and %Y were both known to have a clear low +bit, then %A would have to have a cleared low bit. However, in the %C example, +the optimizer is allowed to assume that the undef operand could be the same as +%Y, allowing the whole select to be eliminated.</p> + + +<div class="doc_code"> +<pre> + %A = xor undef, undef + + %B = undef + %C = xor %B, %B + + %D = undef + %E = icmp lt %D, 4 + %F = icmp gte %D, 4 + +Safe: + %A = undef + %B = undef + %C = undef + %D = undef + %E = undef + %F = undef +</pre> +</div> + +<p>This example points out that two undef operands are not necessarily the same. +This can be surprising to people (and also matches C semantics) where they +assume that "X^X" is always zero, even if X is undef. This isn't true for a +number of reasons, but the short answer is that an undef "variable" can +arbitrarily change its value over its "live range". This is true because the +"variable" doesn't actually <em>have a live range</em>. Instead, the value is +logically read from arbitrary registers that happen to be around when needed, +so the value is not necessarily consistent over time. In fact, %A and %C need +to have the same semantics or the core LLVM "replace all uses with" concept +would not hold.</p> + +<div class="doc_code"> +<pre> + %A = fdiv undef, %X + %B = fdiv %X, undef +Safe: + %A = undef +b: unreachable +</pre> +</div> + +<p>These examples show the crucial difference between an <em>undefined +value</em> and <em>undefined behavior</em>. An undefined value (like undef) is +allowed to have an arbitrary bit-pattern. This means that the %A operation +can be constant folded to undef because the undef could be an SNaN, and fdiv is +not (currently) defined on SNaN's. However, in the second example, we can make +a more aggressive assumption: because the undef is allowed to be an arbitrary +value, we are allowed to assume that it could be zero. Since a divide by zero +has <em>undefined behavior</em>, we are allowed to assume that the operation +does not execute at all. This allows us to delete the divide and all code after +it: since the undefined operation "can't happen", the optimizer can assume that +it occurs in dead code. +</p> + +<div class="doc_code"> +<pre> +a: store undef -> %X +b: store %X -> undef +Safe: +a: <deleted> +b: unreachable +</pre> +</div> + +<p>These examples reiterate the fdiv example: a store "of" an undefined value +can be assumed to not have any effect: we can assume that the value is +overwritten with bits that happen to match what was already there. However, a +store "to" an undefined location could clobber arbitrary memory, therefore, it +has undefined behavior.</p> + </div> <!-- ======================================================================= --> @@ -1953,71 +2178,75 @@ file:</p> <div class="doc_text"> <p>Constant expressions are used to allow expressions involving other constants -to be used as constants. Constant expressions may be of any <a -href="#t_firstclass">first class</a> type and may involve any LLVM operation -that does not have side effects (e.g. load and call are not supported). The -following is the syntax for constant expressions:</p> + to be used as constants. Constant expressions may be of + any <a href="#t_firstclass">first class</a> type and may involve any LLVM + operation that does not have side effects (e.g. load and call are not + supported). The following is the syntax for constant expressions:</p> <dl> <dt><b><tt>trunc ( CST to TYPE )</tt></b></dt> - <dd>Truncate a constant to another type. The bit size of CST must be larger - than the bit size of TYPE. Both types must be integers.</dd> + <dd>Truncate a constant to another type. The bit size of CST must be larger + than the bit size of TYPE. Both types must be integers.</dd> <dt><b><tt>zext ( CST to TYPE )</tt></b></dt> - <dd>Zero extend a constant to another type. The bit size of CST must be - smaller or equal to the bit size of TYPE. Both types must be integers.</dd> + <dd>Zero extend a constant to another type. The bit size of CST must be + smaller or equal to the bit size of TYPE. Both types must be + integers.</dd> <dt><b><tt>sext ( CST to TYPE )</tt></b></dt> - <dd>Sign extend a constant to another type. The bit size of CST must be - smaller or equal to the bit size of TYPE. Both types must be integers.</dd> + <dd>Sign extend a constant to another type. The bit size of CST must be + smaller or equal to the bit size of TYPE. Both types must be + integers.</dd> <dt><b><tt>fptrunc ( CST to TYPE )</tt></b></dt> - <dd>Truncate a floating point constant to another floating point type. The - size of CST must be larger than the size of TYPE. Both types must be - floating point.</dd> + <dd>Truncate a floating point constant to another floating point type. The + size of CST must be larger than the size of TYPE. Both types must be + floating point.</dd> <dt><b><tt>fpext ( CST to TYPE )</tt></b></dt> - <dd>Floating point extend a constant to another type. The size of CST must be - smaller or equal to the size of TYPE. Both types must be floating point.</dd> + <dd>Floating point extend a constant to another type. The size of CST must be + smaller or equal to the size of TYPE. Both types must be floating + point.</dd> <dt><b><tt>fptoui ( CST to TYPE )</tt></b></dt> <dd>Convert a floating point constant to the corresponding unsigned integer - constant. TYPE must be a scalar or vector integer type. CST must be of scalar - or vector floating point type. Both CST and TYPE must be scalars, or vectors - of the same number of elements. If the value won't fit in the integer type, - the results are undefined.</dd> + constant. TYPE must be a scalar or vector integer type. CST must be of + scalar or vector floating point type. Both CST and TYPE must be scalars, + or vectors of the same number of elements. If the value won't fit in the + integer type, the results are undefined.</dd> <dt><b><tt>fptosi ( CST to TYPE )</tt></b></dt> <dd>Convert a floating point constant to the corresponding signed integer - constant. TYPE must be a scalar or vector integer type. CST must be of scalar - or vector floating point type. Both CST and TYPE must be scalars, or vectors - of the same number of elements. If the value won't fit in the integer type, - the results are undefined.</dd> + constant. TYPE must be a scalar or vector integer type. CST must be of + scalar or vector floating point type. Both CST and TYPE must be scalars, + or vectors of the same number of elements. If the value won't fit in the + integer type, the results are undefined.</dd> <dt><b><tt>uitofp ( CST to TYPE )</tt></b></dt> <dd>Convert an unsigned integer constant to the corresponding floating point - constant. TYPE must be a scalar or vector floating point type. CST must be of - scalar or vector integer type. Both CST and TYPE must be scalars, or vectors - of the same number of elements. If the value won't fit in the floating point - type, the results are undefined.</dd> + constant. TYPE must be a scalar or vector floating point type. CST must be + of scalar or vector integer type. Both CST and TYPE must be scalars, or + vectors of the same number of elements. If the value won't fit in the + floating point type, the results are undefined.</dd> <dt><b><tt>sitofp ( CST to TYPE )</tt></b></dt> <dd>Convert a signed integer constant to the corresponding floating point - constant. TYPE must be a scalar or vector floating point type. CST must be of - scalar or vector integer type. Both CST and TYPE must be scalars, or vectors - of the same number of elements. If the value won't fit in the floating point - type, the results are undefined.</dd> + constant. TYPE must be a scalar or vector floating point type. CST must be + of scalar or vector integer type. Both CST and TYPE must be scalars, or + vectors of the same number of elements. If the value won't fit in the + floating point type, the results are undefined.</dd> <dt><b><tt>ptrtoint ( CST to TYPE )</tt></b></dt> <dd>Convert a pointer typed constant to the corresponding integer constant - TYPE must be an integer type. CST must be of pointer type. The CST value is - zero extended, truncated, or unchanged to make it fit in TYPE.</dd> + <tt>TYPE</tt> must be an integer type. <tt>CST</tt> must be of pointer + type. The <tt>CST</tt> value is zero extended, truncated, or unchanged to + make it fit in <tt>TYPE</tt>.</dd> <dt><b><tt>inttoptr ( CST to TYPE )</tt></b></dt> - <dd>Convert a integer constant to a pointer constant. TYPE must be a - pointer type. CST must be of integer type. The CST value is zero extended, - truncated, or unchanged to make it fit in a pointer size. This one is - <i>really</i> dangerous!</dd> + <dd>Convert a integer constant to a pointer constant. TYPE must be a pointer + type. CST must be of integer type. The CST value is zero extended, + truncated, or unchanged to make it fit in a pointer size. This one is + <i>really</i> dangerous!</dd> <dt><b><tt>bitcast ( CST to TYPE )</tt></b></dt> <dd>Convert a constant, CST, to another TYPE. The constraints of the operands @@ -2025,16 +2254,14 @@ following is the syntax for constant expressions:</p> instruction</a>.</dd> <dt><b><tt>getelementptr ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt> - + <dt><b><tt>getelementptr inbounds ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt> <dd>Perform the <a href="#i_getelementptr">getelementptr operation</a> on - constants. As with the <a href="#i_getelementptr">getelementptr</a> - instruction, the index list may have zero or more indexes, which are required - to make sense for the type of "CSTPTR".</dd> + constants. As with the <a href="#i_getelementptr">getelementptr</a> + instruction, the index list may have zero or more indexes, which are + required to make sense for the type of "CSTPTR".</dd> <dt><b><tt>select ( COND, VAL1, VAL2 )</tt></b></dt> - - <dd>Perform the <a href="#i_select">select operation</a> on - constants.</dd> + <dd>Perform the <a href="#i_select">select operation</a> on constants.</dd> <dt><b><tt>icmp COND ( VAL1, VAL2 )</tt></b></dt> <dd>Performs the <a href="#i_icmp">icmp operation</a> on constants.</dd> @@ -2042,36 +2269,26 @@ following is the syntax for constant expressions:</p> <dt><b><tt>fcmp COND ( VAL1, VAL2 )</tt></b></dt> <dd>Performs the <a href="#i_fcmp">fcmp operation</a> on constants.</dd> - <dt><b><tt>vicmp COND ( VAL1, VAL2 )</tt></b></dt> - <dd>Performs the <a href="#i_vicmp">vicmp operation</a> on constants.</dd> - - <dt><b><tt>vfcmp COND ( VAL1, VAL2 )</tt></b></dt> - <dd>Performs the <a href="#i_vfcmp">vfcmp operation</a> on constants.</dd> - <dt><b><tt>extractelement ( VAL, IDX )</tt></b></dt> - - <dd>Perform the <a href="#i_extractelement">extractelement - operation</a> on constants.</dd> + <dd>Perform the <a href="#i_extractelement">extractelement operation</a> on + constants.</dd> <dt><b><tt>insertelement ( VAL, ELT, IDX )</tt></b></dt> - - <dd>Perform the <a href="#i_insertelement">insertelement - operation</a> on constants.</dd> - + <dd>Perform the <a href="#i_insertelement">insertelement operation</a> on + constants.</dd> <dt><b><tt>shufflevector ( VEC1, VEC2, IDXMASK )</tt></b></dt> - - <dd>Perform the <a href="#i_shufflevector">shufflevector - operation</a> on constants.</dd> + <dd>Perform the <a href="#i_shufflevector">shufflevector operation</a> on + constants.</dd> <dt><b><tt>OPCODE ( LHS, RHS )</tt></b></dt> - - <dd>Perform the specified operation of the LHS and RHS constants. OPCODE may - be any of the <a href="#binaryops">binary</a> or <a href="#bitwiseops">bitwise - binary</a> operations. The constraints on operands are the same as those for - the corresponding instruction (e.g. no bitwise operations on floating point - values are allowed).</dd> + <dd>Perform the specified operation of the LHS and RHS constants. OPCODE may + be any of the <a href="#binaryops">binary</a> + or <a href="#bitwiseops">bitwise binary</a> operations. The constraints + on operands are the same as those for the corresponding instruction + (e.g. no bitwise operations on floating point values are allowed).</dd> </dl> + </div> <!-- ======================================================================= --> @@ -2080,31 +2297,30 @@ following is the syntax for constant expressions:</p> <div class="doc_text"> -<p>Embedded metadata provides a way to attach arbitrary data to the -instruction stream without affecting the behaviour of the program. There are -two metadata primitives, strings and nodes. All metadata has the -<tt>metadata</tt> type and is identified in syntax by a preceding exclamation -point ('<tt>!</tt>'). -</p> +<p>Embedded metadata provides a way to attach arbitrary data to the instruction + stream without affecting the behaviour of the program. There are two + metadata primitives, strings and nodes. All metadata has the + <tt>metadata</tt> type and is identified in syntax by a preceding exclamation + point ('<tt>!</tt>').</p> <p>A metadata string is a string surrounded by double quotes. It can contain -any character by escaping non-printable characters with "\xx" where "xx" is -the two digit hex code. For example: "<tt>!"test\00"</tt>". -</p> + any character by escaping non-printable characters with "\xx" where "xx" is + the two digit hex code. For example: "<tt>!"test\00"</tt>".</p> <p>Metadata nodes are represented with notation similar to structure constants -(a comma separated list of elements, surrounded by braces and preceeded by an -exclamation point). For example: "<tt>!{ metadata !"test\00", i32 10}</tt>". -</p> + (a comma separated list of elements, surrounded by braces and preceded by an + exclamation point). For example: "<tt>!{ metadata !"test\00", i32 + 10}</tt>".</p> -<p>A metadata node will attempt to track changes to the values it holds. In -the event that a value is deleted, it will be replaced with a typeless -"<tt>null</tt>", such as "<tt>metadata !{null, i32 10}</tt>".</p> +<p>A metadata node will attempt to track changes to the values it holds. In the + event that a value is deleted, it will be replaced with a typeless + "<tt>null</tt>", such as "<tt>metadata !{null, i32 10}</tt>".</p> <p>Optimizations may rely on metadata to provide additional information about -the program that isn't available in the instructions, or that isn't easily -computable. Similarly, the code generator may expect a certain metadata format -to be used to express debugging information.</p> + the program that isn't available in the instructions, or that isn't easily + computable. Similarly, the code generator may expect a certain metadata + format to be used to express debugging information.</p> + </div> <!-- *********************************************************************** --> @@ -2118,14 +2334,14 @@ to be used to express debugging information.</p> <div class="doc_text"> -<p> -LLVM supports inline assembler expressions (as opposed to <a href="#moduleasm"> -Module-Level Inline Assembly</a>) through the use of a special value. This -value represents the inline assembler as a string (containing the instructions -to emit), a list of operand constraints (stored as a string), and a flag that -indicates whether or not the inline asm expression has side effects. An example -inline assembler expression is: -</p> +<p>LLVM supports inline assembler expressions (as opposed + to <a href="#moduleasm"> Module-Level Inline Assembly</a>) through the use of + a special value. This value represents the inline assembler as a string + (containing the instructions to emit), a list of operand constraints (stored + as a string), a flag that indicates whether or not the inline asm + expression has side effects, and a flag indicating whether the asm came + originally from an asm block. An example inline assembler + expression is:</p> <div class="doc_code"> <pre> @@ -2133,10 +2349,9 @@ i32 (i32) asm "bswap $0", "=r,r" </pre> </div> -<p> -Inline assembler expressions may <b>only</b> be used as the callee operand of -a <a href="#i_call"><tt>call</tt> instruction</a>. Thus, typically we have: -</p> +<p>Inline assembler expressions may <b>only</b> be used as the callee operand of + a <a href="#i_call"><tt>call</tt> instruction</a>. Thus, typically we + have:</p> <div class="doc_code"> <pre> @@ -2144,11 +2359,9 @@ a <a href="#i_call"><tt>call</tt> instruction</a>. Thus, typically we have: </pre> </div> -<p> -Inline asms with side effects not visible in the constraint list must be marked -as having side effects. This is done through the use of the -'<tt>sideeffect</tt>' keyword, like so: -</p> +<p>Inline asms with side effects not visible in the constraint list must be + marked as having side effects. This is done through the use of the + '<tt>sideeffect</tt>' keyword, like so:</p> <div class="doc_code"> <pre> @@ -2156,26 +2369,126 @@ call void asm sideeffect "eieio", ""() </pre> </div> +<p>Inline asms derived from asm blocks are similarly marked with the + '<tt>msasm</tt>' keyword:</p> + +<div class="doc_code"> +<pre> +call void asm msasm "eieio", ""() +</pre> +</div> + +<p>If both keywords appear the '<tt>sideeffect</tt>' keyword must come + first.</p> + <p>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). This is probably best done by reference to another -document that covers inline asm from a holistic perspective. -</p> + documented here. Constraints on what can be done (e.g. duplication, moving, + etc need to be documented). This is probably best done by reference to + another document that covers inline asm from a holistic perspective.</p> </div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="intrinsic_globals">Intrinsic Global Variables</a> +</div> +<!-- *********************************************************************** --> + +<p>LLVM has a number of "magic" global variables that contain data that affect +code generation or other IR semantics. These are documented here. All globals +of this sort should have a section specified as "<tt>llvm.metadata</tt>". This +section and all globals that start with "<tt>llvm.</tt>" are reserved for use +by LLVM.</p> + +<!-- ======================================================================= --> +<div class="doc_subsection"> +<a name="intg_used">The '<tt>llvm.used</tt>' Global Variable</a> +</div> + +<div class="doc_text"> + +<p>The <tt>@llvm.used</tt> global is an array with i8* element type which has <a +href="#linkage_appending">appending linkage</a>. This array contains a list of +pointers to global variables and functions which may optionally have a pointer +cast formed of bitcast or getelementptr. For example, a legal use of it is:</p> + +<pre> + @X = global i8 4 + @Y = global i32 123 + + @llvm.used = appending global [2 x i8*] [ + i8* @X, + i8* bitcast (i32* @Y to i8*) + ], section "llvm.metadata" +</pre> + +<p>If a global variable appears in the <tt>@llvm.used</tt> list, then the +compiler, assembler, and linker are required to treat the symbol as if there is +a reference to the global that it cannot see. For example, if a variable has +internal linkage and no references other than that from the <tt>@llvm.used</tt> +list, it cannot be deleted. This is commonly used to represent references from +inline asms and other things the compiler cannot "see", and corresponds to +"attribute((used))" in GNU C.</p> + +<p>On some targets, the code generator must emit a directive to the assembler or +object file to prevent the assembler and linker from molesting the symbol.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> +<a name="intg_compiler_used">The '<tt>llvm.compiler.used</tt>' Global Variable</a> +</div> + +<div class="doc_text"> + +<p>The <tt>@llvm.compiler.used</tt> directive is the same as the +<tt>@llvm.used</tt> directive, except that it only prevents the compiler from +touching the symbol. On targets that support it, this allows an intelligent +linker to optimize references to the symbol without being impeded as it would be +by <tt>@llvm.used</tt>.</p> + +<p>This is a rare construct that should only be used in rare circumstances, and +should not be exposed to source languages.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> +<a name="intg_global_ctors">The '<tt>llvm.global_ctors</tt>' Global Variable</a> +</div> + +<div class="doc_text"> + +<p>TODO: Describe this.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> +<a name="intg_global_dtors">The '<tt>llvm.global_dtors</tt>' Global Variable</a> +</div> + +<div class="doc_text"> + +<p>TODO: Describe this.</p> + +</div> + + <!-- *********************************************************************** --> <div class="doc_section"> <a name="instref">Instruction Reference</a> </div> <!-- *********************************************************************** --> <div class="doc_text"> -<p>The LLVM instruction set consists of several different -classifications of instructions: <a href="#terminators">terminator -instructions</a>, <a href="#binaryops">binary instructions</a>, -<a href="#bitwiseops">bitwise binary instructions</a>, <a - href="#memoryops">memory instructions</a>, and <a href="#otherops">other -instructions</a>.</p> +<p>The LLVM instruction set consists of several different classifications of + instructions: <a href="#terminators">terminator + instructions</a>, <a href="#binaryops">binary instructions</a>, + <a href="#bitwiseops">bitwise binary instructions</a>, + <a href="#memoryops">memory instructions</a>, and + <a href="#otherops">other instructions</a>.</p> </div> @@ -2185,25 +2498,29 @@ Instructions</a> </div> <div class="doc_text"> -<p>As mentioned <a href="#functionstructure">previously</a>, every -basic block in a program ends with a "Terminator" instruction, which -indicates which block should be executed after the current block is -finished. These terminator instructions typically yield a '<tt>void</tt>' -value: they produce control flow, not values (the one exception being -the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p> -<p>There are six different terminator instructions: the '<a - href="#i_ret"><tt>ret</tt></a>' instruction, the '<a href="#i_br"><tt>br</tt></a>' -instruction, the '<a href="#i_switch"><tt>switch</tt></a>' instruction, -the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction, the '<a - href="#i_unwind"><tt>unwind</tt></a>' instruction, and the '<a - href="#i_unreachable"><tt>unreachable</tt></a>' instruction.</p> +<p>As mentioned <a href="#functionstructure">previously</a>, every basic block + in a program ends with a "Terminator" instruction, which indicates which + block should be executed after the current block is finished. These + terminator instructions typically yield a '<tt>void</tt>' value: they produce + control flow, not values (the one exception being the + '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p> + +<p>There are six different terminator instructions: the + '<a href="#i_ret"><tt>ret</tt></a>' instruction, the + '<a href="#i_br"><tt>br</tt></a>' instruction, the + '<a href="#i_switch"><tt>switch</tt></a>' instruction, the + '<a href="#i_invoke"><tt>invoke</tt></a>' instruction, the + '<a href="#i_unwind"><tt>unwind</tt></a>' instruction, and the + '<a href="#i_unreachable"><tt>unreachable</tt></a>' instruction.</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_ret">'<tt>ret</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> <pre> ret <type> <value> <i>; Return a value from a non-void function</i> @@ -2211,38 +2528,35 @@ Instruction</a> </div> </pre> <h5>Overview:</h5> +<p>The '<tt>ret</tt>' instruction is used to return control flow (and optionally + a value) from a function back to the caller.</p> -<p>The '<tt>ret</tt>' instruction is used to return control flow (and -optionally a value) from a function back to the caller.</p> -<p>There are two forms of the '<tt>ret</tt>' instruction: one that -returns a value and then causes control flow, and one that just causes -control flow to occur.</p> +<p>There are two forms of the '<tt>ret</tt>' instruction: one that returns a + value and then causes control flow, and one that just causes control flow to + occur.</p> <h5>Arguments:</h5> +<p>The '<tt>ret</tt>' instruction optionally accepts a single argument, the + return value. The type of the return value must be a + '<a href="#t_firstclass">first class</a>' type.</p> -<p>The '<tt>ret</tt>' instruction optionally accepts a single argument, -the return value. The type of the return value must be a -'<a href="#t_firstclass">first class</a>' type.</p> - -<p>A function is not <a href="#wellformed">well formed</a> if -it it has a non-void return type and contains a '<tt>ret</tt>' -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 '<tt>ret</tt>' instruction with a return value.</p> +<p>A function is not <a href="#wellformed">well formed</a> if it it has a + non-void return type and contains a '<tt>ret</tt>' 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 '<tt>ret</tt>' instruction with a + return value.</p> <h5>Semantics:</h5> - -<p>When the '<tt>ret</tt>' instruction is executed, control flow -returns back to the calling function's context. If the caller is a "<a - href="#i_call"><tt>call</tt></a>" instruction, execution continues at -the instruction after the call. If the caller was an "<a - href="#i_invoke"><tt>invoke</tt></a>" 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.</p> +<p>When the '<tt>ret</tt>' instruction is executed, control flow returns back to + the calling function's context. If the caller is a + "<a href="#i_call"><tt>call</tt></a>" instruction, execution continues at the + instruction after the call. If the caller was an + "<a href="#i_invoke"><tt>invoke</tt></a>" 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.</p> <h5>Example:</h5> - <pre> ret i32 5 <i>; Return an integer value of 5</i> ret void <i>; Return from a void function</i> @@ -2260,73 +2574,83 @@ return value.</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_br">'<tt>br</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> br i1 <cond>, label <iftrue>, label <iffalse><br> br label <dest> <i>; Unconditional branch</i> +<pre> + br i1 <cond>, label <iftrue>, label <iffalse><br> br label <dest> <i>; Unconditional branch</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>br</tt>' 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.</p> +<p>The '<tt>br</tt>' 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.</p> + <h5>Arguments:</h5> -<p>The conditional branch form of the '<tt>br</tt>' instruction takes a -single '<tt>i1</tt>' value and two '<tt>label</tt>' values. The -unconditional form of the '<tt>br</tt>' instruction takes a single -'<tt>label</tt>' value as a target.</p> +<p>The conditional branch form of the '<tt>br</tt>' instruction takes a single + '<tt>i1</tt>' value and two '<tt>label</tt>' values. The unconditional form + of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>' value as a + target.</p> + <h5>Semantics:</h5> <p>Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>i1</tt>' -argument is evaluated. If the value is <tt>true</tt>, control flows -to the '<tt>iftrue</tt>' <tt>label</tt> argument. If "cond" is <tt>false</tt>, -control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.</p> + argument is evaluated. If the value is <tt>true</tt>, control flows to the + '<tt>iftrue</tt>' <tt>label</tt> argument. If "cond" is <tt>false</tt>, + control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.</p> + <h5>Example:</h5> -<pre>Test:<br> %cond = <a href="#i_icmp">icmp</a> eq i32 %a, %b<br> br i1 %cond, label %IfEqual, label %IfUnequal<br>IfEqual:<br> <a - href="#i_ret">ret</a> i32 1<br>IfUnequal:<br> <a href="#i_ret">ret</a> i32 0<br></pre> +<pre> +Test: + %cond = <a href="#i_icmp">icmp</a> eq i32 %a, %b + br i1 %cond, label %IfEqual, label %IfUnequal +IfEqual: + <a href="#i_ret">ret</a> i32 1 +IfUnequal: + <a href="#i_ret">ret</a> i32 0 +</pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_switch">'<tt>switch</tt>' Instruction</a> </div> <div class="doc_text"> -<h5>Syntax:</h5> +<h5>Syntax:</h5> <pre> switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ] </pre> <h5>Overview:</h5> - <p>The '<tt>switch</tt>' instruction is used to transfer control flow to one of -several different places. It is a generalization of the '<tt>br</tt>' -instruction, allowing a branch to occur to one of many possible -destinations.</p> - + several different places. It is a generalization of the '<tt>br</tt>' + instruction, allowing a branch to occur to one of many possible + destinations.</p> <h5>Arguments:</h5> - <p>The '<tt>switch</tt>' instruction uses three parameters: an integer -comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, and -an array of pairs of comparison value constants and '<tt>label</tt>'s. The -table is not allowed to contain duplicate constant entries.</p> + comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, + and an array of pairs of comparison value constants and '<tt>label</tt>'s. + The table is not allowed to contain duplicate constant entries.</p> <h5>Semantics:</h5> - <p>The <tt>switch</tt> instruction specifies a table of values and -destinations. When the '<tt>switch</tt>' instruction is executed, this -table is searched for the given value. If the value is found, control flow is -transfered to the corresponding destination; otherwise, control flow is -transfered to the default destination.</p> + destinations. When the '<tt>switch</tt>' 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.</p> <h5>Implementation:</h5> - <p>Depending on properties of the target machine and the particular -<tt>switch</tt> 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.</p> + <tt>switch</tt> 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.</p> <h5>Example:</h5> - <pre> <i>; Emulate a conditional br instruction</i> %Val = <a href="#i_zext">zext</a> i1 %value to i32 @@ -2340,6 +2664,7 @@ branches or with a lookup table.</p> i32 1, label %onone i32 2, label %ontwo ] </pre> + </div> <!-- _______________________________________________________________________ --> @@ -2350,79 +2675,72 @@ branches or with a lookup table.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = invoke [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>] <ptr to function ty> <function ptr val>(<function args>) [<a href="#fnattrs">fn attrs</a>] to label <normal label> unwind label <exception label> </pre> <h5>Overview:</h5> - <p>The '<tt>invoke</tt>' instruction causes control to transfer to a specified -function, with the possibility of control flow transfer to either the -'<tt>normal</tt>' label or the -'<tt>exception</tt>' label. If the callee function returns with the -"<tt><a href="#i_ret">ret</a></tt>" instruction, control flow will return to the -"normal" label. If the callee (or any indirect callees) returns with the "<a -href="#i_unwind"><tt>unwind</tt></a>" instruction, control is interrupted and -continued at the dynamically nearest "exception" label.</p> + function, with the possibility of control flow transfer to either the + '<tt>normal</tt>' label or the '<tt>exception</tt>' label. If the callee + function returns with the "<tt><a href="#i_ret">ret</a></tt>" instruction, + control flow will return to the "normal" label. If the callee (or any + indirect callees) returns with the "<a href="#i_unwind"><tt>unwind</tt></a>" + instruction, control is interrupted and continued at the dynamically nearest + "exception" label.</p> <h5>Arguments:</h5> - <p>This instruction requires several arguments:</p> <ol> - <li> - The optional "cconv" marker indicates which <a href="#callingconv">calling - convention</a> the call should use. If none is specified, the call defaults - to using C calling conventions. - </li> + <li>The optional "cconv" marker indicates which <a href="#callingconv">calling + convention</a> the call should use. If none is specified, the call + defaults to using C calling conventions.</li> <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for - return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', - and '<tt>inreg</tt>' attributes are valid here.</li> + return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and + '<tt>inreg</tt>' attributes are valid here.</li> <li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to - function value being invoked. In most cases, this is a direct function - invocation, but indirect <tt>invoke</tt>s are just as possible, branching off - an arbitrary pointer to function value. - </li> + function value being invoked. In most cases, this is a direct function + invocation, but indirect <tt>invoke</tt>s are just as possible, branching + off an arbitrary pointer to function value.</li> <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a - function to be invoked. </li> + function to be invoked. </li> <li>'<tt>function args</tt>': argument list whose types match the function - signature argument types. If the function signature indicates the function - accepts a variable number of arguments, the extra arguments can be - specified. </li> + signature argument types. If the function signature indicates the + function accepts a variable number of arguments, the extra arguments can + be specified.</li> <li>'<tt>normal label</tt>': the label reached when the called function - executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li> + executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li> <li>'<tt>exception label</tt>': the label reached when a callee returns with - the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li> + the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li> <li>The optional <a href="#fnattrs">function attributes</a> list. Only - '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and - '<tt>readnone</tt>' attributes are valid here.</li> + '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and + '<tt>readnone</tt>' attributes are valid here.</li> </ol> <h5>Semantics:</h5> - -<p>This instruction is designed to operate as a standard '<tt><a -href="#i_call">call</a></tt>' 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.</p> +<p>This instruction is designed to operate as a standard + '<tt><a href="#i_call">call</a></tt>' 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.</p> <p>This instruction is used in languages with destructors to ensure that proper -cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown -exception. Additionally, this is important for implementation of -'<tt>catch</tt>' clauses in high-level languages that support them.</p> + cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown + exception. Additionally, this is important for implementation of + '<tt>catch</tt>' clauses in high-level languages that support them.</p> -<p>For the purposes of the SSA form, the definition of the value -returned by the '<tt>invoke</tt>' 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.</p> +<p>For the purposes of the SSA form, the definition of the value returned by the + '<tt>invoke</tt>' 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.</p> <h5>Example:</h5> <pre> @@ -2431,8 +2749,8 @@ unwinds then no return value is available.</p> %retval = invoke <a href="#callingconv">coldcc</a> i32 %Testfnptr(i32 15) to label %Continue unwind label %TestCleanup <i>; {i32}:retval set</i> </pre> -</div> +</div> <!-- _______________________________________________________________________ --> @@ -2447,20 +2765,19 @@ Instruction</a> </div> </pre> <h5>Overview:</h5> - <p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow -at the first callee in the dynamic call stack which used an <a -href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call. This is -primarily used to implement exception handling.</p> + at the first callee in the dynamic call stack which used + an <a href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call. + This is primarily used to implement exception handling.</p> <h5>Semantics:</h5> - <p>The '<tt>unwind</tt>' instruction causes execution of the current function to -immediately halt. The dynamic call stack is then searched for the first <a -href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack. Once found, -execution continues at the "exceptional" destination block specified by the -<tt>invoke</tt> instruction. If there is no <tt>invoke</tt> instruction in the -dynamic call chain, undefined behavior results.</p> + immediately halt. The dynamic call stack is then searched for the + first <a href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack. + Once found, execution continues at the "exceptional" destination block + specified by the <tt>invoke</tt> instruction. If there is no <tt>invoke</tt> + instruction in the dynamic call chain, undefined behavior results.</p> + </div> <!-- _______________________________________________________________________ --> @@ -2476,29 +2793,31 @@ Instruction</a> </div> </pre> <h5>Overview:</h5> - <p>The '<tt>unreachable</tt>' 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.</p> + 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.</p> <h5>Semantics:</h5> - <p>The '<tt>unreachable</tt>' instruction has no defined semantics.</p> -</div> - +</div> <!-- ======================================================================= --> <div class="doc_subsection"> <a name="binaryops">Binary Operations</a> </div> + <div class="doc_text"> -<p>Binary operators are used to do most of the computation in a -program. They require two operands of the same type, execute an operation on them, and -produce a single value. The operands might represent -multiple data, as is the case with the <a href="#t_vector">vector</a> data type. -The result value has the same type as its operands.</p> + +<p>Binary operators are used to do most of the computation in a program. They + require two operands of the same type, execute an operation on them, and + produce a single value. The operands might represent multiple data, as is + the case with the <a href="#t_vector">vector</a> data type. The result value + has the same type as its operands.</p> + <p>There are several different binary operators:</p> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_add">'<tt>add</tt>' Instruction</a> @@ -2507,39 +2826,42 @@ The result value has the same type as its operands.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> - <result> = add <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = add <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = add nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = add nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = add nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - <p>The '<tt>add</tt>' instruction returns the sum of its two operands.</p> <h5>Arguments:</h5> - -<p>The two arguments to the '<tt>add</tt>' instruction must be <a - href="#t_integer">integer</a> or - <a href="#t_vector">vector</a> of integer values. Both arguments must - have identical types.</p> +<p>The two arguments to the '<tt>add</tt>' instruction must + be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of + integer values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the integer sum of the two operands.</p> -<p>If the sum has unsigned overflow, the result returned is the -mathematical result modulo 2<sup>n</sup>, where n is the bit width of -the result.</p> +<p>If the sum has unsigned overflow, the result returned is the mathematical + result modulo 2<sup>n</sup>, where n is the bit width of the result.</p> -<p>Because LLVM integers use a two's complement representation, this -instruction is appropriate for both signed and unsigned integers.</p> +<p>Because LLVM integers use a two's complement representation, this instruction + is appropriate for both signed and unsigned integers.</p> -<h5>Example:</h5> +<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap" + and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or + <tt>nsw</tt> keywords are present, the result value of the <tt>add</tt> + is undefined if unsigned and/or signed overflow, respectively, occurs.</p> +<h5>Example:</h5> <pre> <result> = add i32 4, %var <i>; yields {i32}:result = 4 + %var</i> </pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_fadd">'<tt>fadd</tt>' Instruction</a> @@ -2548,31 +2870,28 @@ instruction is appropriate for both signed and unsigned integers.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = fadd <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - <p>The '<tt>fadd</tt>' instruction returns the sum of its two operands.</p> <h5>Arguments:</h5> - <p>The two arguments to the '<tt>fadd</tt>' instruction must be -<a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of -floating point values. Both arguments must have identical types.</p> + <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of + floating point values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the floating point sum of the two operands.</p> <h5>Example:</h5> - <pre> <result> = fadd float 4.0, %var <i>; yields {float}:result = 4.0 + %var</i> </pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_sub">'<tt>sub</tt>' Instruction</a> @@ -2581,42 +2900,47 @@ floating point values. Both arguments must have identical types.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> - <result> = sub <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = sub <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = sub nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = sub nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = sub nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - <p>The '<tt>sub</tt>' instruction returns the difference of its two -operands.</p> + operands.</p> <p>Note that the '<tt>sub</tt>' instruction is used to represent the -'<tt>neg</tt>' instruction present in most other intermediate -representations.</p> + '<tt>neg</tt>' instruction present in most other intermediate + representations.</p> <h5>Arguments:</h5> - -<p>The two arguments to the '<tt>sub</tt>' instruction must be <a - href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of - integer values. Both arguments must have identical types.</p> +<p>The two arguments to the '<tt>sub</tt>' instruction must + be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of + integer values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the integer difference of the two operands.</p> <p>If the difference has unsigned overflow, the result returned is the -mathematical result modulo 2<sup>n</sup>, where n is the bit width of -the result.</p> + mathematical result modulo 2<sup>n</sup>, where n is the bit width of the + result.</p> + +<p>Because LLVM integers use a two's complement representation, this instruction + is appropriate for both signed and unsigned integers.</p> -<p>Because LLVM integers use a two's complement representation, this -instruction is appropriate for both signed and unsigned integers.</p> +<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap" + and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or + <tt>nsw</tt> keywords are present, the result value of the <tt>sub</tt> + is undefined if unsigned and/or signed overflow, respectively, occurs.</p> <h5>Example:</h5> <pre> <result> = sub i32 4, %var <i>; yields {i32}:result = 4 - %var</i> <result> = sub i32 0, %val <i>; yields {i32}:result = -%var</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -2627,28 +2951,24 @@ instruction is appropriate for both signed and unsigned integers.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = fsub <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - <p>The '<tt>fsub</tt>' instruction returns the difference of its two -operands.</p> + operands.</p> <p>Note that the '<tt>fsub</tt>' instruction is used to represent the -'<tt>fneg</tt>' instruction present in most other intermediate -representations.</p> + '<tt>fneg</tt>' instruction present in most other intermediate + representations.</p> <h5>Arguments:</h5> - -<p>The two arguments to the '<tt>fsub</tt>' instruction must be <a - <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> - of floating point values. Both arguments must have identical types.</p> +<p>The two arguments to the '<tt>fsub</tt>' instruction must be + <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of + floating point values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the floating point difference of the two operands.</p> <h5>Example:</h5> @@ -2656,6 +2976,7 @@ representations.</p> <result> = fsub float 4.0, %var <i>; yields {float}:result = 4.0 - %var</i> <result> = fsub float -0.0, %val <i>; yields {float}:result = -%var</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -2666,34 +2987,45 @@ representations.</p> <div class="doc_text"> <h5>Syntax:</h5> -<pre> <result> = mul <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = mul <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = mul nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = mul nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = mul nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>mul</tt>' instruction returns the product of its two -operands.</p> +<p>The '<tt>mul</tt>' instruction returns the product of its two operands.</p> <h5>Arguments:</h5> - -<p>The two arguments to the '<tt>mul</tt>' instruction must be <a -href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> +<p>The two arguments to the '<tt>mul</tt>' instruction must + be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of + integer values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the integer product of the two operands.</p> -<p>If the result of the multiplication has unsigned overflow, -the result returned is the mathematical result modulo -2<sup>n</sup>, where n is the bit width of the result.</p> -<p>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. <tt>i32</tt>x<tt>i32</tt>-><tt>i64</tt>) is needed, the operands -should be sign-extended or zero-extended as appropriate to the -width of the full product.</p> +<p>If the result of the multiplication has unsigned overflow, the result + returned is the mathematical result modulo 2<sup>n</sup>, where n is the bit + width of the result.</p> + +<p>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. <tt>i32</tt>x<tt>i32</tt>-><tt>i64</tt>) is needed, the operands should + be sign-extended or zero-extended as appropriate to the width of the full + product.</p> + +<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap" + and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or + <tt>nsw</tt> keywords are present, the result value of the <tt>mul</tt> + is undefined if unsigned and/or signed overflow, respectively, occurs.</p> + <h5>Example:</h5> -<pre> <result> = mul i32 4, %var <i>; yields {i32}:result = 4 * %var</i> +<pre> + <result> = mul i32 4, %var <i>; yields {i32}:result = 4 * %var</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -2704,140 +3036,170 @@ width of the full product.</p> <div class="doc_text"> <h5>Syntax:</h5> -<pre> <result> = fmul <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = fmul <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>fmul</tt>' instruction returns the product of its two -operands.</p> +<p>The '<tt>fmul</tt>' instruction returns the product of its two operands.</p> <h5>Arguments:</h5> - <p>The two arguments to the '<tt>fmul</tt>' instruction must be -<a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> -of floating point values. Both arguments must have identical types.</p> + <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of + floating point values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the floating point product of the two operands.</p> <h5>Example:</h5> -<pre> <result> = fmul float 4.0, %var <i>; yields {float}:result = 4.0 * %var</i> +<pre> + <result> = fmul float 4.0, %var <i>; yields {float}:result = 4.0 * %var</i> </pre> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_udiv">'<tt>udiv</tt>' Instruction </a></div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = udiv <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = udiv <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>udiv</tt>' instruction returns the quotient of its two -operands.</p> +<p>The '<tt>udiv</tt>' instruction returns the quotient of its two operands.</p> <h5>Arguments:</h5> - <p>The two arguments to the '<tt>udiv</tt>' instruction must be -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the unsigned integer quotient of the two operands.</p> + <p>Note that unsigned integer division and signed integer division are distinct -operations; for signed integer division, use '<tt>sdiv</tt>'.</p> + operations; for signed integer division, use '<tt>sdiv</tt>'.</p> + <p>Division by zero leads to undefined behavior.</p> + <h5>Example:</h5> -<pre> <result> = udiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i> +<pre> + <result> = udiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i> </pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_sdiv">'<tt>sdiv</tt>' Instruction </a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> <pre> - <result> = sdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = sdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = sdiv exact <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - -<p>The '<tt>sdiv</tt>' instruction returns the quotient of its two -operands.</p> +<p>The '<tt>sdiv</tt>' instruction returns the quotient of its two operands.</p> <h5>Arguments:</h5> - <p>The two arguments to the '<tt>sdiv</tt>' instruction must be -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + values. Both arguments must have identical types.</p> <h5>Semantics:</h5> -<p>The value produced is the signed integer quotient of the two operands rounded towards zero.</p> +<p>The value produced is the signed integer quotient of the two operands rounded + towards zero.</p> + <p>Note that signed integer division and unsigned integer division are distinct -operations; for unsigned integer division, use '<tt>udiv</tt>'.</p> + operations; for unsigned integer division, use '<tt>udiv</tt>'.</p> + <p>Division by zero leads to 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.</p> + undefined behavior; this is a rare case, but can occur, for example, by doing + a 32-bit division of -2147483648 by -1.</p> + +<p>If the <tt>exact</tt> keyword is present, the result value of the + <tt>sdiv</tt> is undefined if the result would be rounded or if overflow + would occur.</p> + <h5>Example:</h5> -<pre> <result> = sdiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i> +<pre> + <result> = sdiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i> </pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_fdiv">'<tt>fdiv</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> <pre> <result> = fdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> -<h5>Overview:</h5> -<p>The '<tt>fdiv</tt>' instruction returns the quotient of its two -operands.</p> +<h5>Overview:</h5> +<p>The '<tt>fdiv</tt>' instruction returns the quotient of its two operands.</p> <h5>Arguments:</h5> - <p>The two arguments to the '<tt>fdiv</tt>' instruction must be -<a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> -of floating point values. Both arguments must have identical types.</p> + <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of + floating point values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the floating point quotient of the two operands.</p> <h5>Example:</h5> - <pre> <result> = fdiv float 4.0, %var <i>; yields {float}:result = 4.0 / %var</i> </pre> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_urem">'<tt>urem</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = urem <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = urem <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>urem</tt>' instruction returns the remainder from the -unsigned division of its two arguments.</p> +<p>The '<tt>urem</tt>' instruction returns the remainder from the unsigned + division of its two arguments.</p> + <h5>Arguments:</h5> <p>The two arguments to the '<tt>urem</tt>' instruction must be -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + values. Both arguments must have identical types.</p> + <h5>Semantics:</h5> <p>This instruction returns the unsigned integer <i>remainder</i> of a division. -This instruction always performs an unsigned division to get the remainder.</p> + This instruction always performs an unsigned division to get the + remainder.</p> + <p>Note that unsigned integer remainder and signed integer remainder are -distinct operations; for signed integer remainder, use '<tt>srem</tt>'.</p> + distinct operations; for signed integer remainder, use '<tt>srem</tt>'.</p> + <p>Taking the remainder of a division by zero leads to undefined behavior.</p> + <h5>Example:</h5> -<pre> <result> = urem i32 4, %var <i>; yields {i32}:result = 4 % %var</i> +<pre> + <result> = urem i32 4, %var <i>; yields {i32}:result = 4 % %var</i> </pre> </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_srem">'<tt>srem</tt>' Instruction</a> @@ -2846,47 +3208,48 @@ distinct operations; for signed integer remainder, use '<tt>srem</tt>'.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = srem <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - -<p>The '<tt>srem</tt>' instruction returns the remainder from the -signed division of its two operands. This instruction can also take -<a href="#t_vector">vector</a> versions of the values in which case -the elements must be integers.</p> +<p>The '<tt>srem</tt>' instruction returns the remainder from the signed + division of its two operands. This instruction can also take + <a href="#t_vector">vector</a> versions of the values in which case the + elements must be integers.</p> <h5>Arguments:</h5> - <p>The two arguments to the '<tt>srem</tt>' instruction must be -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>This instruction returns the <i>remainder</i> of a division (where the result -has the same sign as the dividend, <tt>op1</tt>), not the <i>modulo</i> -operator (where the result has the same sign as the divisor, <tt>op2</tt>) of -a value. For more information about the difference, see <a - href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The -Math Forum</a>. For a table of how this is implemented in various languages, -please see <a href="http://en.wikipedia.org/wiki/Modulo_operation"> -Wikipedia: modulo operation</a>.</p> + has the same sign as the dividend, <tt>op1</tt>), not the <i>modulo</i> + operator (where the result has the same sign as the divisor, <tt>op2</tt>) of + a value. For more information about the difference, + see <a href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The + Math Forum</a>. For a table of how this is implemented in various languages, + please see <a href="http://en.wikipedia.org/wiki/Modulo_operation"> + Wikipedia: modulo operation</a>.</p> + <p>Note that signed integer remainder and unsigned integer remainder are -distinct operations; for unsigned integer remainder, use '<tt>urem</tt>'.</p> + distinct operations; for unsigned integer remainder, use '<tt>urem</tt>'.</p> + <p>Taking the remainder of a division by zero leads to 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.)</p> + 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.)</p> + <h5>Example:</h5> -<pre> <result> = srem i32 4, %var <i>; yields {i32}:result = 4 % %var</i> +<pre> + <result> = srem i32 4, %var <i>; yields {i32}:result = 4 % %var</i> </pre> </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_frem">'<tt>frem</tt>' Instruction</a> </div> @@ -2894,99 +3257,110 @@ and the remainder.)</p> <div class="doc_text"> <h5>Syntax:</h5> -<pre> <result> = frem <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = frem <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>frem</tt>' instruction returns the remainder from the -division of its two operands.</p> +<p>The '<tt>frem</tt>' instruction returns the remainder from the division of + its two operands.</p> + <h5>Arguments:</h5> <p>The two arguments to the '<tt>frem</tt>' instruction must be -<a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> -of floating point values. Both arguments must have identical types.</p> + <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of + floating point values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - -<p>This instruction returns the <i>remainder</i> of a division. -The remainder has the same sign as the dividend.</p> +<p>This instruction returns the <i>remainder</i> of a division. The remainder + has the same sign as the dividend.</p> <h5>Example:</h5> - <pre> <result> = frem float 4.0, %var <i>; yields {float}:result = 4.0 % %var</i> </pre> + </div> <!-- ======================================================================= --> <div class="doc_subsection"> <a name="bitwiseops">Bitwise Binary Operations</a> </div> + <div class="doc_text"> -<p>Bitwise binary operators are used to do various forms of -bit-twiddling in a program. They are generally very efficient -instructions and can commonly be strength reduced from other -instructions. They require two operands of the same type, execute an operation on them, -and produce a single value. The resulting value is the same type as its operands.</p> + +<p>Bitwise binary operators are used to do various forms of bit-twiddling in a + program. They are generally very efficient instructions and can commonly be + strength reduced from other instructions. They require two operands of the + same type, execute an operation on them, and produce a single value. The + resulting value is the same type as its operands.</p> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_shl">'<tt>shl</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = shl <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = shl <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - -<p>The '<tt>shl</tt>' instruction returns the first operand shifted to -the left a specified number of bits.</p> +<p>The '<tt>shl</tt>' instruction returns the first operand shifted to the left + a specified number of bits.</p> <h5>Arguments:</h5> - -<p>Both arguments to the '<tt>shl</tt>' instruction must be the same <a - href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -type. '<tt>op2</tt>' is treated as an unsigned value.</p> +<p>Both arguments to the '<tt>shl</tt>' instruction must be the + same <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of + integer type. '<tt>op2</tt>' is treated as an unsigned value.</p> <h5>Semantics:</h5> +<p>The value produced is <tt>op1</tt> * 2<sup><tt>op2</tt></sup> mod + 2<sup>n</sup>, where <tt>n</tt> is the width of the result. If <tt>op2</tt> + is (statically or dynamically) negative or equal to or larger than the number + of bits in <tt>op1</tt>, the result is undefined. If the arguments are + vectors, each vector element of <tt>op1</tt> is shifted by the corresponding + shift amount in <tt>op2</tt>.</p> -<p>The value produced is <tt>op1</tt> * 2<sup><tt>op2</tt></sup> mod 2<sup>n</sup>, -where n is the width of the result. If <tt>op2</tt> is (statically or dynamically) negative or -equal to or larger than the number of bits in <tt>op1</tt>, the result is undefined. -If the arguments are vectors, each vector element of <tt>op1</tt> is shifted by the -corresponding shift amount in <tt>op2</tt>.</p> - -<h5>Example:</h5><pre> +<h5>Example:</h5> +<pre> <result> = shl i32 4, %var <i>; yields {i32}: 4 << %var</i> <result> = shl i32 4, 2 <i>; yields {i32}: 16</i> <result> = shl i32 1, 10 <i>; yields {i32}: 1024</i> <result> = shl i32 1, 32 <i>; undefined</i> <result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2> <i>; yields: result=<2 x i32> < i32 2, i32 4></i> </pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_lshr">'<tt>lshr</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = lshr <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = lshr <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> -<p>The '<tt>lshr</tt>' instruction (logical shift right) returns the first -operand shifted to the right a specified number of bits with zero fill.</p> +<p>The '<tt>lshr</tt>' instruction (logical shift right) returns the first + operand shifted to the right a specified number of bits with zero fill.</p> <h5>Arguments:</h5> <p>Both arguments to the '<tt>lshr</tt>' instruction must be the same -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -type. '<tt>op2</tt>' is treated as an unsigned value.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + type. '<tt>op2</tt>' is treated as an unsigned value.</p> <h5>Semantics:</h5> - <p>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 <tt>op2</tt> is (statically or dynamically) equal to or larger than -the number of bits in <tt>op1</tt>, the result is undefined. If the arguments are -vectors, each vector element of <tt>op1</tt> is shifted by the corresponding shift -amount in <tt>op2</tt>.</p> + significant bits of the result will be filled with zero bits after the shift. + If <tt>op2</tt> is (statically or dynamically) equal to or larger than the + number of bits in <tt>op1</tt>, the result is undefined. If the arguments are + vectors, each vector element of <tt>op1</tt> is shifted by the corresponding + shift amount in <tt>op2</tt>.</p> <h5>Example:</h5> <pre> @@ -2997,6 +3371,7 @@ amount in <tt>op2</tt>.</p> <result> = lshr i32 1, 32 <i>; undefined</i> <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> <i>; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1></i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3005,25 +3380,27 @@ Instruction</a> </div> <div class="doc_text"> <h5>Syntax:</h5> -<pre> <result> = ashr <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = ashr <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> -<p>The '<tt>ashr</tt>' instruction (arithmetic shift right) returns the first -operand shifted to the right a specified number of bits with sign extension.</p> +<p>The '<tt>ashr</tt>' instruction (arithmetic shift right) returns the first + operand shifted to the right a specified number of bits with sign + extension.</p> <h5>Arguments:</h5> <p>Both arguments to the '<tt>ashr</tt>' instruction must be the same -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -type. '<tt>op2</tt>' is treated as an unsigned value.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + type. '<tt>op2</tt>' is treated as an unsigned value.</p> <h5>Semantics:</h5> -<p>This instruction always performs an arithmetic shift right operation, -The most significant bits of the result will be filled with the sign bit -of <tt>op1</tt>. If <tt>op2</tt> is (statically or dynamically) equal to or -larger than the number of bits in <tt>op1</tt>, the result is undefined. If the -arguments are vectors, each vector element of <tt>op1</tt> is shifted by the -corresponding shift amount in <tt>op2</tt>.</p> +<p>This instruction always performs an arithmetic shift right operation, The + most significant bits of the result will be filled with the sign bit + of <tt>op1</tt>. If <tt>op2</tt> is (statically or dynamically) equal to or + larger than the number of bits in <tt>op1</tt>, the result is undefined. If + the arguments are vectors, each vector element of <tt>op1</tt> is shifted by + the corresponding shift amount in <tt>op2</tt>.</p> <h5>Example:</h5> <pre> @@ -3034,6 +3411,7 @@ corresponding shift amount in <tt>op2</tt>.</p> <result> = ashr i32 1, 32 <i>; undefined</i> <result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3> <i>; yields: result=<2 x i32> < i32 -1, i32 0></i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3043,26 +3421,22 @@ Instruction</a> </div> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = and <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - -<p>The '<tt>and</tt>' instruction returns the bitwise logical and of -its two operands.</p> +<p>The '<tt>and</tt>' instruction returns the bitwise logical and of its two + operands.</p> <h5>Arguments:</h5> - <p>The two arguments to the '<tt>and</tt>' instruction must be -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + values. Both arguments must have identical types.</p> <h5>Semantics:</h5> <p>The truth table used for the '<tt>and</tt>' instruction is:</p> -<p> </p> -<div> + <table border="1" cellspacing="0" cellpadding="4"> <tbody> <tr> @@ -3092,7 +3466,7 @@ values. Both arguments must have identical types.</p> </tr> </tbody> </table> -</div> + <h5>Example:</h5> <pre> <result> = and i32 4, %var <i>; yields {i32}:result = 4 & %var</i> @@ -3102,22 +3476,26 @@ values. Both arguments must have identical types.</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_or">'<tt>or</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = or <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = or <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive -or of its two operands.</p> -<h5>Arguments:</h5> +<p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive or of its + two operands.</p> +<h5>Arguments:</h5> <p>The two arguments to the '<tt>or</tt>' instruction must be -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + values. Both arguments must have identical types.</p> + <h5>Semantics:</h5> <p>The truth table used for the '<tt>or</tt>' instruction is:</p> -<p> </p> -<div> + <table border="1" cellspacing="0" cellpadding="4"> <tbody> <tr> @@ -3147,34 +3525,40 @@ values. Both arguments must have identical types.</p> </tr> </tbody> </table> -</div> + <h5>Example:</h5> -<pre> <result> = or i32 4, %var <i>; yields {i32}:result = 4 | %var</i> +<pre> + <result> = or i32 4, %var <i>; yields {i32}:result = 4 | %var</i> <result> = or i32 15, 40 <i>; yields {i32}:result = 47</i> <result> = or i32 4, 8 <i>; yields {i32}:result = 12</i> </pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_xor">'<tt>xor</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = xor <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = xor <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive -or of its two operands. The <tt>xor</tt> is used to implement the -"one's complement" operation, which is the "~" operator in C.</p> +<p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive or of + its two operands. The <tt>xor</tt> is used to implement the "one's + complement" operation, which is the "~" operator in C.</p> + <h5>Arguments:</h5> <p>The two arguments to the '<tt>xor</tt>' instruction must be -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The truth table used for the '<tt>xor</tt>' instruction is:</p> -<p> </p> -<div> + <table border="1" cellspacing="0" cellpadding="4"> <tbody> <tr> @@ -3204,14 +3588,15 @@ values. Both arguments must have identical types.</p> </tr> </tbody> </table> -</div> -<p> </p> + <h5>Example:</h5> -<pre> <result> = xor i32 4, %var <i>; yields {i32}:result = 4 ^ %var</i> +<pre> + <result> = xor i32 4, %var <i>; yields {i32}:result = 4 ^ %var</i> <result> = xor i32 15, 40 <i>; yields {i32}:result = 39</i> <result> = xor i32 4, 8 <i>; yields {i32}:result = 12</i> <result> = xor i32 %V, -1 <i>; yields {i32}:result = ~%V</i> </pre> + </div> <!-- ======================================================================= --> @@ -3222,11 +3607,11 @@ values. Both arguments must have identical types.</p> <div class="doc_text"> <p>LLVM supports several instructions to represent vector operations in a -target-independent manner. These instructions cover the element-access and -vector-specific operations needed to process vectors effectively. While LLVM -does directly support these vector operations, many sophisticated algorithms -will want to use target-specific intrinsics to take full advantage of a specific -target.</p> + target-independent manner. These instructions cover the element-access and + vector-specific operations needed to process vectors effectively. While LLVM + does directly support these vector operations, many sophisticated algorithms + will want to use target-specific intrinsics to take full advantage of a + specific target.</p> </div> @@ -3238,43 +3623,33 @@ target.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = extractelement <n x <ty>> <val>, i32 <idx> <i>; yields <ty></i> </pre> <h5>Overview:</h5> - -<p> -The '<tt>extractelement</tt>' instruction extracts a single scalar -element from a vector at a specified index. -</p> +<p>The '<tt>extractelement</tt>' instruction extracts a single scalar element + from a vector at a specified index.</p> <h5>Arguments:</h5> - -<p> -The first operand of an '<tt>extractelement</tt>' instruction is a -value of <a href="#t_vector">vector</a> type. The second operand is -an index indicating the position from which to extract the element. -The index may be a variable.</p> +<p>The first operand of an '<tt>extractelement</tt>' instruction is a value + of <a href="#t_vector">vector</a> type. The second operand is an index + indicating the position from which to extract the element. The index may be + a variable.</p> <h5>Semantics:</h5> - -<p> -The result is a scalar of the same type as the element type of -<tt>val</tt>. Its value is the value at position <tt>idx</tt> of -<tt>val</tt>. If <tt>idx</tt> exceeds the length of <tt>val</tt>, the -results are undefined. -</p> +<p>The result is a scalar of the same type as the element type of + <tt>val</tt>. Its value is the value at position <tt>idx</tt> of + <tt>val</tt>. If <tt>idx</tt> exceeds the length of <tt>val</tt>, the + results are undefined.</p> <h5>Example:</h5> - <pre> %result = extractelement <4 x i32> %vec, i32 0 <i>; yields i32</i> </pre> -</div> +</div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> @@ -3284,42 +3659,32 @@ results are undefined. <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = insertelement <n x <ty>> <val>, <ty> <elt>, i32 <idx> <i>; yields <n x <ty>></i> </pre> <h5>Overview:</h5> - -<p> -The '<tt>insertelement</tt>' instruction inserts a scalar -element into a vector at a specified index. -</p> - +<p>The '<tt>insertelement</tt>' instruction inserts a scalar element into a + vector at a specified index.</p> <h5>Arguments:</h5> - -<p> -The first operand of an '<tt>insertelement</tt>' instruction is a -value of <a href="#t_vector">vector</a> 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.</p> +<p>The first operand of an '<tt>insertelement</tt>' instruction is a value + of <a href="#t_vector">vector</a> 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.</p> <h5>Semantics:</h5> - -<p> -The result is a vector of the same type as <tt>val</tt>. Its -element values are those of <tt>val</tt> except at position -<tt>idx</tt>, where it gets the value <tt>elt</tt>. If <tt>idx</tt> -exceeds the length of <tt>val</tt>, the results are undefined. -</p> +<p>The result is a vector of the same type as <tt>val</tt>. Its element values + are those of <tt>val</tt> except at position <tt>idx</tt>, where it gets the + value <tt>elt</tt>. If <tt>idx</tt> exceeds the length of <tt>val</tt>, the + results are undefined.</p> <h5>Example:</h5> - <pre> %result = insertelement <4 x i32> %vec, i32 1, i32 0 <i>; yields <4 x i32></i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3330,46 +3695,33 @@ exceeds the length of <tt>val</tt>, the results are undefined. <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask> <i>; yields <m x <ty>></i> </pre> <h5>Overview:</h5> - -<p> -The '<tt>shufflevector</tt>' 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. -</p> +<p>The '<tt>shufflevector</tt>' 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.</p> <h5>Arguments:</h5> +<p>The first two operands of a '<tt>shufflevector</tt>' instruction are vectors + with types that match each other. The third argument is a shuffle mask whose + element type is always 'i32'. 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.</p> -<p> -The first two operands of a '<tt>shufflevector</tt>' instruction are vectors -with types that match each other. The third argument is a shuffle mask whose -element type is always 'i32'. 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. -</p> - -<p> -The shuffle mask operand is required to be a constant vector with either -constant integer or undef values. -</p> +<p>The shuffle mask operand is required to be a constant vector with either + constant integer or undef values.</p> <h5>Semantics:</h5> - -<p> -The elements of the two input vectors are numbered from left to right across -both of the vectors. The shuffle mask operand specifies, for each element of -the result vector, which element of the two input vectors the result element -gets. The element selector may be undef (meaning "don't care") and the second -operand may be undef if performing a shuffle from only one vector. -</p> +<p>The elements of the two input vectors are numbered from left to right across + both of the vectors. The shuffle mask operand specifies, for each element of + the result vector, which element of the two input vectors the result element + gets. The element selector may be undef (meaning "don't care") and the + second operand may be undef if performing a shuffle from only one vector.</p> <h5>Example:</h5> - <pre> %result = shufflevector <4 x i32> %v1, <4 x i32> %v2, <4 x i32> <i32 0, i32 4, i32 1, i32 5> <i>; yields <4 x i32></i> @@ -3380,8 +3732,8 @@ operand may be undef if performing a shuffle from only one vector. %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 > <i>; yields <8 x i32></i> </pre> -</div> +</div> <!-- ======================================================================= --> <div class="doc_subsection"> @@ -3390,8 +3742,7 @@ operand may be undef if performing a shuffle from only one vector. <div class="doc_text"> -<p>LLVM supports several instructions for working with aggregate values. -</p> +<p>LLVM supports several instructions for working with aggregate values.</p> </div> @@ -3403,43 +3754,31 @@ operand may be undef if performing a shuffle from only one vector. <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}* </pre> <h5>Overview:</h5> - -<p> -The '<tt>extractvalue</tt>' instruction extracts the value of a struct field -or array element from an aggregate value. -</p> - +<p>The '<tt>extractvalue</tt>' instruction extracts the value of a struct field + or array element from an aggregate value.</p> <h5>Arguments:</h5> - -<p> -The first operand of an '<tt>extractvalue</tt>' instruction is a -value of <a href="#t_struct">struct</a> or <a href="#t_array">array</a> -type. The operands are constant indices to specify which value to extract -in a similar manner as indices in a -'<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction. -</p> +<p>The first operand of an '<tt>extractvalue</tt>' instruction is a value + of <a href="#t_struct">struct</a> or <a href="#t_array">array</a> type. The + operands are constant indices to specify which value to extract in a similar + manner as indices in a + '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p> <h5>Semantics:</h5> - -<p> -The result is the value at the position in the aggregate specified by -the index operands. -</p> +<p>The result is the value at the position in the aggregate specified by the + index operands.</p> <h5>Example:</h5> - <pre> %result = extractvalue {i32, float} %agg, 0 <i>; yields i32</i> </pre> -</div> +</div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> @@ -3449,46 +3788,35 @@ the index operands. <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = insertvalue <aggregate type> <val>, <ty> <val>, <idx> <i>; yields <n x <ty>></i> </pre> <h5>Overview:</h5> - -<p> -The '<tt>insertvalue</tt>' instruction inserts a value -into a struct field or array element in an aggregate. -</p> +<p>The '<tt>insertvalue</tt>' instruction inserts a value into a struct field or + array element in an aggregate.</p> <h5>Arguments:</h5> - -<p> -The first operand of an '<tt>insertvalue</tt>' instruction is a -value of <a href="#t_struct">struct</a> or <a href="#t_array">array</a> 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 -'<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction. -The value to insert must have the same type as the value identified -by the indices. -</p> +<p>The first operand of an '<tt>insertvalue</tt>' instruction is a value + of <a href="#t_struct">struct</a> or <a href="#t_array">array</a> 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 + '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction. The + value to insert must have the same type as the value identified by the + indices.</p> <h5>Semantics:</h5> - -<p> -The result is an aggregate of the same type as <tt>val</tt>. Its -value is that of <tt>val</tt> except that the value at the position -specified by the indices is that of <tt>elt</tt>. -</p> +<p>The result is an aggregate of the same type as <tt>val</tt>. Its value is + that of <tt>val</tt> except that the value at the position specified by the + indices is that of <tt>elt</tt>.</p> <h5>Example:</h5> - <pre> %result = insertvalue {i32, float} %agg, i32 1, 0 <i>; yields {i32, float}</i> </pre> + </div> @@ -3499,10 +3827,10 @@ specified by the indices is that of <tt>elt</tt>. <div class="doc_text"> -<p>A key design point of an SSA-based representation is how it -represents memory. In LLVM, no memory locations are in SSA form, which -makes things very simple. This section describes how to read, write, -allocate, and free memory in LLVM.</p> +<p>A key design point of an SSA-based representation is how it represents + memory. In LLVM, no memory locations are in SSA form, which makes things + very simple. This section describes how to read, write, allocate, and free + memory in LLVM.</p> </div> @@ -3514,39 +3842,33 @@ allocate, and free memory in LLVM.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = malloc <type>[, i32 <NumElements>][, align <alignment>] <i>; yields {type*}:result</i> </pre> <h5>Overview:</h5> - -<p>The '<tt>malloc</tt>' instruction allocates memory from the system -heap and returns a pointer to it. The object is always allocated in the generic -address space (address space zero).</p> +<p>The '<tt>malloc</tt>' instruction allocates memory from the system heap and + returns a pointer to it. The object is always allocated in the generic + address space (address space zero).</p> <h5>Arguments:</h5> - <p>The '<tt>malloc</tt>' instruction allocates -<tt>sizeof(<type>)*NumElements</tt> -bytes of memory from the operating system and returns 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. If not specified, or if -zero, the target can choose to align the allocation on any convenient boundary -compatible with the type.</p> + <tt>sizeof(<type>)*NumElements</tt> bytes of memory from the operating + system and returns 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. If not specified, or if zero, the target can choose to align + the allocation on any convenient boundary compatible with the type.</p> <p>'<tt>type</tt>' must be a sized type.</p> <h5>Semantics:</h5> - -<p>Memory is allocated using the system "<tt>malloc</tt>" function, and -a pointer is returned. The result of a zero byte allocation is undefined. The -result is null if there is insufficient memory available.</p> +<p>Memory is allocated using the system "<tt>malloc</tt>" function, and a + pointer is returned. The result of a zero byte allocation is undefined. The + result is null if there is insufficient memory available.</p> <h5>Example:</h5> - <pre> %array = malloc [4 x i8] <i>; yields {[%4 x i8]*}:array</i> @@ -3557,8 +3879,7 @@ result is null if there is insufficient memory available.</p> %array4 = malloc i32, align 1024 <i>; yields {i32*}:array4</i> </pre> -<p>Note that the code generator does not yet respect the - alignment value.</p> +<p>Note that the code generator does not yet respect the alignment value.</p> </div> @@ -3570,34 +3891,29 @@ result is null if there is insufficient memory available.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> free <type> <value> <i>; yields {void}</i> </pre> <h5>Overview:</h5> - -<p>The '<tt>free</tt>' instruction returns memory back to the unused -memory heap to be reallocated in the future.</p> +<p>The '<tt>free</tt>' instruction returns memory back to the unused memory heap + to be reallocated in the future.</p> <h5>Arguments:</h5> - -<p>'<tt>value</tt>' shall be a pointer value that points to a value -that was allocated with the '<tt><a href="#i_malloc">malloc</a></tt>' -instruction.</p> +<p>'<tt>value</tt>' shall be a pointer value that points to a value that was + allocated with the '<tt><a href="#i_malloc">malloc</a></tt>' instruction.</p> <h5>Semantics:</h5> - -<p>Access to the memory pointed to by the pointer is no longer defined -after this instruction executes. If the pointer is null, the operation -is a noop.</p> +<p>Access to the memory pointed to by the pointer is no longer defined after + this instruction executes. If the pointer is null, the operation is a + noop.</p> <h5>Example:</h5> - <pre> %array = <a href="#i_malloc">malloc</a> [4 x i8] <i>; yields {[4 x i8]*}:array</i> free [4 x i8]* %array </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3608,137 +3924,150 @@ is a noop.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = alloca <type>[, i32 <NumElements>][, align <alignment>] <i>; yields {type*}:result</i> </pre> <h5>Overview:</h5> - <p>The '<tt>alloca</tt>' instruction allocates memory on the stack frame of the -currently executing function, to be automatically released when this function -returns to its caller. The object is always allocated in the generic address -space (address space zero).</p> + currently executing function, to be automatically released when this function + returns to its caller. The object is always allocated in the generic address + space (address space zero).</p> <h5>Arguments:</h5> - -<p>The '<tt>alloca</tt>' instruction allocates <tt>sizeof(<type>)*NumElements</tt> -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. If not specified, or if -zero, the target can choose to align the allocation on any convenient boundary -compatible with the type.</p> +<p>The '<tt>alloca</tt>' instruction + allocates <tt>sizeof(<type>)*NumElements</tt> 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. If not specified, or if zero, the target can choose + to align the allocation on any convenient boundary compatible with the + type.</p> <p>'<tt>type</tt>' may be any sized type.</p> <h5>Semantics:</h5> - <p>Memory is allocated; a pointer is returned. The operation is undefined if -there is insufficient stack space for the allocation. '<tt>alloca</tt>'d -memory is automatically released when the function returns. The '<tt>alloca</tt>' -instruction is commonly used to represent automatic variables that must -have an address available. When the function returns (either with the <tt><a - href="#i_ret">ret</a></tt> or <tt><a href="#i_unwind">unwind</a></tt> -instructions), the memory is reclaimed. Allocating zero bytes -is legal, but the result is undefined.</p> + there is insufficient stack space for the allocation. '<tt>alloca</tt>'d + memory is automatically released when the function returns. The + '<tt>alloca</tt>' instruction is commonly used to represent automatic + variables that must have an address available. When the function returns + (either with the <tt><a href="#i_ret">ret</a></tt> + or <tt><a href="#i_unwind">unwind</a></tt> instructions), the memory is + reclaimed. Allocating zero bytes is legal, but the result is undefined.</p> <h5>Example:</h5> - <pre> %ptr = alloca i32 <i>; yields {i32*}:ptr</i> %ptr = alloca i32, i32 4 <i>; yields {i32*}:ptr</i> %ptr = alloca i32, i32 4, align 1024 <i>; yields {i32*}:ptr</i> %ptr = alloca i32, align 1024 <i>; yields {i32*}:ptr</i> </pre> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_load">'<tt>load</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = load <ty>* <pointer>[, align <alignment>]<br> <result> = volatile load <ty>* <pointer>[, align <alignment>]<br></pre> +<pre> + <result> = load <ty>* <pointer>[, align <alignment>] + <result> = volatile load <ty>* <pointer>[, align <alignment>] +</pre> + <h5>Overview:</h5> <p>The '<tt>load</tt>' instruction is used to read from memory.</p> + <h5>Arguments:</h5> -<p>The argument to the '<tt>load</tt>' instruction specifies the memory -address from which to load. The pointer must point to a <a - href="#t_firstclass">first class</a> type. If the <tt>load</tt> is -marked as <tt>volatile</tt>, then the optimizer is not allowed to modify -the number or order of execution of this <tt>load</tt> with other -volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt> -instructions. </p> -<p> -The optional constant "align" argument specifies the alignment of the operation -(that is, the alignment of the memory address). A value of 0 or an -omitted "align" argument means that the operation has the preferential -alignment for the target. It is the responsibility of the code emitter -to ensure that the alignment information is correct. Overestimating -the alignment results in an undefined behavior. Underestimating the -alignment may produce less efficient code. An alignment of 1 is always -safe. -</p> +<p>The argument to the '<tt>load</tt>' instruction specifies the memory address + from which to load. The pointer must point to + a <a href="#t_firstclass">first class</a> type. If the <tt>load</tt> is + marked as <tt>volatile</tt>, then the optimizer is not allowed to modify the + number or order of execution of this <tt>load</tt> with other + volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt> + instructions. </p> + +<p>The optional constant "align" argument specifies the alignment of the + operation (that is, the alignment of the memory address). A value of 0 or an + omitted "align" argument means that the operation has the preferential + alignment for the target. It is the responsibility of the code emitter to + ensure that the alignment information is correct. Overestimating the + alignment results in an undefined behavior. Underestimating the alignment may + produce less efficient code. An alignment of 1 is always safe.</p> + <h5>Semantics:</h5> -<p>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 -<tt>i24</tt> reads at most three bytes. When loading a value of a type like -<tt>i20</tt> 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.</p> +<p>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 + <tt>i24</tt> reads at most three bytes. When loading a value of a type like + <tt>i20</tt> 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.</p> + <h5>Examples:</h5> -<pre> %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i> - <a - href="#i_store">store</a> i32 3, i32* %ptr <i>; yields {void}</i> +<pre> + %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i> + <a href="#i_store">store</a> i32 3, i32* %ptr <i>; yields {void}</i> %val = load i32* %ptr <i>; yields {i32}:val = i32 3</i> </pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_store">'<tt>store</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> store <ty> <value>, <ty>* <pointer>[, align <alignment>] <i>; yields {void}</i> +<pre> + store <ty> <value>, <ty>* <pointer>[, align <alignment>] <i>; yields {void}</i> volatile store <ty> <value>, <ty>* <pointer>[, align <alignment>] <i>; yields {void}</i> </pre> + <h5>Overview:</h5> <p>The '<tt>store</tt>' instruction is used to write to memory.</p> + <h5>Arguments:</h5> -<p>There are two arguments to the '<tt>store</tt>' instruction: a value -to store and an address at which to store it. The type of the '<tt><pointer></tt>' -operand must be a pointer to the <a href="#t_firstclass">first class</a> type -of the '<tt><value></tt>' -operand. If the <tt>store</tt> is marked as <tt>volatile</tt>, then the -optimizer is not allowed to modify the number or order of execution of -this <tt>store</tt> with other volatile <tt>load</tt> and <tt><a - href="#i_store">store</a></tt> instructions.</p> -<p> -The optional constant "align" argument specifies the alignment of the operation -(that is, the alignment of the memory address). A value of 0 or an -omitted "align" argument means that the operation has the preferential -alignment for the target. It is the responsibility of the code emitter -to ensure that the alignment information is correct. Overestimating -the alignment results in an undefined behavior. Underestimating the -alignment may produce less efficient code. An alignment of 1 is always -safe. -</p> +<p>There are two arguments to the '<tt>store</tt>' instruction: a value to store + and an address at which to store it. The type of the + '<tt><pointer></tt>' operand must be a pointer to + the <a href="#t_firstclass">first class</a> type of the + '<tt><value></tt>' operand. If the <tt>store</tt> is marked + as <tt>volatile</tt>, then the optimizer is not allowed to modify the number + or order of execution of this <tt>store</tt> with other + volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt> + instructions.</p> + +<p>The optional constant "align" argument specifies the alignment of the + operation (that is, the alignment of the memory address). A value of 0 or an + omitted "align" argument means that the operation has the preferential + alignment for the target. It is the responsibility of the code emitter to + ensure that the alignment information is correct. Overestimating the + alignment results in an undefined behavior. Underestimating the alignment may + produce less efficient code. An alignment of 1 is always safe.</p> + <h5>Semantics:</h5> -<p>The contents of memory are updated to contain '<tt><value></tt>' -at the location specified by the '<tt><pointer></tt>' operand. -If '<tt><value></tt>' 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 <tt>i24</tt> writes at most -three bytes. When writing a value of a type like <tt>i20</tt> 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.</p> +<p>The contents of memory are updated to contain '<tt><value></tt>' at the + location specified by the '<tt><pointer></tt>' operand. If + '<tt><value></tt>' 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 <tt>i24</tt> writes at most three bytes. When + writing a value of a type like <tt>i20</tt> 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.</p> + <h5>Example:</h5> -<pre> %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i> +<pre> + %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i> store i32 3, i32* %ptr <i>; yields {void}</i> %val = <a href="#i_load">load</a> i32* %ptr <i>; yields {i32}:val = i32 3</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3747,38 +4076,39 @@ typically be overwritten.</p> </div> <div class="doc_text"> + <h5>Syntax:</h5> <pre> <result> = getelementptr <pty>* <ptrval>{, <ty> <idx>}* + <result> = getelementptr inbounds <pty>* <ptrval>{, <ty> <idx>}* </pre> <h5>Overview:</h5> - -<p> -The '<tt>getelementptr</tt>' 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.</p> +<p>The '<tt>getelementptr</tt>' 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.</p> <h5>Arguments:</h5> - <p>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.</p> + 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.</p> <p>The type of each index argument depends on the type it is indexing into. -When indexing into a (packed) structure, only <tt>i32</tt> integer -<b>constants</b> are allowed. When indexing into an array, pointer or vector, -integers of any width are allowed (also non-constants).</p> + When indexing into a (optionally packed) structure, only <tt>i32</tt> integer + <b>constants</b> are allowed. When indexing into an array, pointer or + vector, integers of any width are allowed, and they are not required to be + constant.</p> -<p>For example, let's consider a C code fragment and how it gets -compiled to LLVM:</p> +<p>For example, let's consider a C code fragment and how it gets compiled to + LLVM:</p> <div class="doc_code"> <pre> @@ -3806,7 +4136,7 @@ int *foo(struct ST *s) { %RT = <a href="#namedtypes">type</a> { i8 , [10 x [20 x i32]], i8 } %ST = <a href="#namedtypes">type</a> { i32, double, %RT } -define i32* %foo(%ST* %s) { +define i32* @foo(%ST* %s) { entry: %reg = getelementptr %ST* %s, i32 1, i32 2, i32 1, i32 5, i32 13 ret i32* %reg @@ -3815,23 +4145,22 @@ entry: </div> <h5>Semantics:</h5> - <p>In the example above, the first index is indexing into the '<tt>%ST*</tt>' -type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ i32, double, %RT -}</tt>' type, a structure. The second index indexes into the third element of -the structure, yielding a '<tt>%RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]], -i8 }</tt>' type, another structure. The third index indexes into the second -element of the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an -array. The two dimensions of the array are subscripted into, yielding an -'<tt>i32</tt>' type. The '<tt>getelementptr</tt>' instruction returns a pointer -to this element, thus computing a value of '<tt>i32*</tt>' type.</p> + type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ i32, double, %RT + }</tt>' type, a structure. The second index indexes into the third element + of the structure, yielding a '<tt>%RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]], + i8 }</tt>' type, another structure. The third index indexes into the second + element of the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an + array. The two dimensions of the array are subscripted into, yielding an + '<tt>i32</tt>' type. The '<tt>getelementptr</tt>' instruction returns a + pointer to this element, thus computing a value of '<tt>i32*</tt>' type.</p> -<p>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:</p> +<p>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:</p> <pre> - define i32* %foo(%ST* %s) { + define i32* @foo(%ST* %s) { %t1 = getelementptr %ST* %s, i32 1 <i>; yields %ST*:%t1</i> %t2 = getelementptr %ST* %t1, i32 0, i32 2 <i>; yields %RT*:%t2</i> %t3 = getelementptr %RT* %t2, i32 0, i32 1 <i>; yields [10 x [20 x i32]]*:%t3</i> @@ -3841,20 +4170,27 @@ the LLVM code for the given testcase is equivalent to:</p> } </pre> -<p>Note that it is undefined to access an array out of bounds: array -and pointer indexes must always be within the defined bounds of the -array type when accessed with an instruction that dereferences the -pointer (e.g. a load or store instruction). The one exception for -this rule is zero length arrays. These arrays are defined to be -accessible as variable length arrays, which requires access beyond the -zero'th element.</p> +<p>If the <tt>inbounds</tt> keyword is present, the result value of the + <tt>getelementptr</tt> is undefined if the base pointer is not an + <i>in bounds</i> address of an allocated object, or if any of the addresses + that would be formed by successive addition of the offsets implied by the + indices to the base address with infinitely precise arithmetic are not an + <i>in bounds</i> address of that allocated object. + The <i>in bounds</i> addresses for an allocated object are all the addresses + that point into the object, plus the address one byte past the end.</p> -<p>The getelementptr instruction is often confusing. For some more insight -into how it works, see <a href="GetElementPtr.html">the getelementptr -FAQ</a>.</p> +<p>If the <tt>inbounds</tt> keyword is not present, the offsets are added to + the base address with silently-wrapping two's complement arithmetic, and + the result value of the <tt>getelementptr</tt> 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 <a href="#pointeraliasing">Pointer Aliasing Rules</a> + section for more information.</p> -<h5>Example:</h5> +<p>The getelementptr instruction is often confusing. For some more insight into + how it works, see <a href="GetElementPtr.html">the getelementptr FAQ</a>.</p> +<h5>Example:</h5> <pre> <i>; yields [12 x i8]*:aptr</i> %aptr = getelementptr {i32, [12 x i8]}* %saptr, i64 0, i32 1 @@ -3865,15 +4201,19 @@ FAQ</a>.</p> <i>; yields i32*:iptr</i> %iptr = getelementptr [10 x i32]* @arr, i16 0, i16 0 </pre> + </div> <!-- ======================================================================= --> <div class="doc_subsection"> <a name="convertops">Conversion Operations</a> </div> + <div class="doc_text"> + <p>The instructions in this category are the conversion instructions (casting) -which all take a single operand and a type. They perform various bit conversions -on the operand.</p> + which all take a single operand and a type. They perform various bit + conversions on the operand.</p> + </div> <!-- _______________________________________________________________________ --> @@ -3888,24 +4228,22 @@ on the operand.</p> </pre> <h5>Overview:</h5> -<p> -The '<tt>trunc</tt>' instruction truncates its operand to the type <tt>ty2</tt>. -</p> +<p>The '<tt>trunc</tt>' instruction truncates its operand to the + type <tt>ty2</tt>.</p> <h5>Arguments:</h5> -<p> -The '<tt>trunc</tt>' instruction takes a <tt>value</tt> to trunc, which must -be an <a href="#t_integer">integer</a> type, and a type that specifies the size -and type of the result, which must be an <a href="#t_integer">integer</a> -type. The bit size of <tt>value</tt> must be larger than the bit size of -<tt>ty2</tt>. Equal sized types are not allowed.</p> +<p>The '<tt>trunc</tt>' instruction takes a <tt>value</tt> to trunc, which must + be an <a href="#t_integer">integer</a> type, and a type that specifies the + size and type of the result, which must be + an <a href="#t_integer">integer</a> type. The bit size of <tt>value</tt> must + be larger than the bit size of <tt>ty2</tt>. Equal sized types are not + allowed.</p> <h5>Semantics:</h5> -<p> -The '<tt>trunc</tt>' instruction truncates the high order bits in <tt>value</tt> -and converts the remaining bits to <tt>ty2</tt>. Since the source size must be -larger than the destination size, <tt>trunc</tt> cannot be a <i>no-op cast</i>. -It will always truncate bits.</p> +<p>The '<tt>trunc</tt>' instruction truncates the high order bits + in <tt>value</tt> and converts the remaining bits to <tt>ty2</tt>. Since the + source size must be larger than the destination size, <tt>trunc</tt> cannot + be a <i>no-op cast</i>. It will always truncate bits.</p> <h5>Example:</h5> <pre> @@ -3913,6 +4251,7 @@ It will always truncate bits.</p> %Y = trunc i32 123 to i1 <i>; yields i1:true</i> %Y = trunc i32 122 to i1 <i>; yields i1:false</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3928,19 +4267,19 @@ It will always truncate bits.</p> <h5>Overview:</h5> <p>The '<tt>zext</tt>' instruction zero extends its operand to type -<tt>ty2</tt>.</p> + <tt>ty2</tt>.</p> <h5>Arguments:</h5> <p>The '<tt>zext</tt>' instruction takes a value to cast, which must be of -<a href="#t_integer">integer</a> type, and a type to cast it to, which must -also be of <a href="#t_integer">integer</a> type. The bit size of the -<tt>value</tt> must be smaller than the bit size of the destination type, -<tt>ty2</tt>.</p> + <a href="#t_integer">integer</a> type, and a type to cast it to, which must + also be of <a href="#t_integer">integer</a> type. The bit size of the + <tt>value</tt> must be smaller than the bit size of the destination type, + <tt>ty2</tt>.</p> <h5>Semantics:</h5> <p>The <tt>zext</tt> fills the high order bits of the <tt>value</tt> with zero -bits until it reaches the size of the destination type, <tt>ty2</tt>.</p> + bits until it reaches the size of the destination type, <tt>ty2</tt>.</p> <p>When zero extending from i1, the result will always be either 0 or 1.</p> @@ -3949,6 +4288,7 @@ bits until it reaches the size of the destination type, <tt>ty2</tt>.</p> %X = zext i32 257 to i64 <i>; yields i64:257</i> %Y = zext i1 true to i32 <i>; yields i32:1</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3966,18 +4306,16 @@ bits until it reaches the size of the destination type, <tt>ty2</tt>.</p> <p>The '<tt>sext</tt>' sign extends <tt>value</tt> to the type <tt>ty2</tt>.</p> <h5>Arguments:</h5> -<p> -The '<tt>sext</tt>' instruction takes a value to cast, which must be of -<a href="#t_integer">integer</a> type, and a type to cast it to, which must -also be of <a href="#t_integer">integer</a> type. The bit size of the -<tt>value</tt> must be smaller than the bit size of the destination type, -<tt>ty2</tt>.</p> +<p>The '<tt>sext</tt>' instruction takes a value to cast, which must be of + <a href="#t_integer">integer</a> type, and a type to cast it to, which must + also be of <a href="#t_integer">integer</a> type. The bit size of the + <tt>value</tt> must be smaller than the bit size of the destination type, + <tt>ty2</tt>.</p> <h5>Semantics:</h5> -<p> -The '<tt>sext</tt>' instruction performs a sign extension by copying the sign -bit (highest order bit) of the <tt>value</tt> until it reaches the bit size of -the type <tt>ty2</tt>.</p> +<p>The '<tt>sext</tt>' instruction performs a sign extension by copying the sign + bit (highest order bit) of the <tt>value</tt> until it reaches the bit size + of the type <tt>ty2</tt>.</p> <p>When sign extending from i1, the extension always results in -1 or 0.</p> @@ -3986,6 +4324,7 @@ the type <tt>ty2</tt>.</p> %X = sext i8 -1 to i16 <i>; yields i16 :65535</i> %Y = sext i1 true to i32 <i>; yields i32:-1</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3996,34 +4335,34 @@ the type <tt>ty2</tt>.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = fptrunc <ty> <value> to <ty2> <i>; yields ty2</i> </pre> <h5>Overview:</h5> <p>The '<tt>fptrunc</tt>' instruction truncates <tt>value</tt> to type -<tt>ty2</tt>.</p> - + <tt>ty2</tt>.</p> <h5>Arguments:</h5> <p>The '<tt>fptrunc</tt>' instruction takes a <a href="#t_floating">floating - point</a> value to cast and a <a href="#t_floating">floating point</a> type to -cast it to. The size of <tt>value</tt> must be larger than the size of -<tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a -<i>no-op cast</i>.</p> + point</a> value to cast and a <a href="#t_floating">floating point</a> type + to cast it to. The size of <tt>value</tt> must be larger than the size of + <tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a + <i>no-op cast</i>.</p> <h5>Semantics:</h5> -<p> The '<tt>fptrunc</tt>' instruction truncates a <tt>value</tt> from a larger -<a href="#t_floating">floating point</a> type to a smaller -<a href="#t_floating">floating point</a> type. If the value cannot fit within -the destination type, <tt>ty2</tt>, then the results are undefined.</p> +<p>The '<tt>fptrunc</tt>' instruction truncates a <tt>value</tt> from a larger + <a href="#t_floating">floating point</a> type to a smaller + <a href="#t_floating">floating point</a> type. If the value cannot fit + within the destination type, <tt>ty2</tt>, then the results are + undefined.</p> <h5>Example:</h5> <pre> %X = fptrunc double 123.0 to float <i>; yields float:123.0</i> %Y = fptrunc double 1.0E+300 to float <i>; yields undefined</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4039,26 +4378,27 @@ the destination type, <tt>ty2</tt>, then the results are undefined.</p> <h5>Overview:</h5> <p>The '<tt>fpext</tt>' extends a floating point <tt>value</tt> to a larger -floating point value.</p> + floating point value.</p> <h5>Arguments:</h5> <p>The '<tt>fpext</tt>' instruction takes a -<a href="#t_floating">floating point</a> <tt>value</tt> to cast, -and a <a href="#t_floating">floating point</a> type to cast it to. The source -type must be smaller than the destination type.</p> + <a href="#t_floating">floating point</a> <tt>value</tt> to cast, and + a <a href="#t_floating">floating point</a> type to cast it to. The source + type must be smaller than the destination type.</p> <h5>Semantics:</h5> <p>The '<tt>fpext</tt>' instruction extends the <tt>value</tt> from a smaller -<a href="#t_floating">floating point</a> type to a larger -<a href="#t_floating">floating point</a> type. The <tt>fpext</tt> cannot be -used to make a <i>no-op cast</i> because it always changes bits. Use -<tt>bitcast</tt> to make a <i>no-op cast</i> for a floating point cast.</p> + <a href="#t_floating">floating point</a> type to a larger + <a href="#t_floating">floating point</a> type. The <tt>fpext</tt> cannot be + used to make a <i>no-op cast</i> because it always changes bits. Use + <tt>bitcast</tt> to make a <i>no-op cast</i> for a floating point cast.</p> <h5>Example:</h5> <pre> %X = fpext float 3.1415 to double <i>; yields double:3.1415</i> %Y = fpext float 1.0 to float <i>; yields float:1.0 (no-op)</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4074,21 +4414,20 @@ used to make a <i>no-op cast</i> because it always changes bits. Use <h5>Overview:</h5> <p>The '<tt>fptoui</tt>' converts a floating point <tt>value</tt> to its -unsigned integer equivalent of type <tt>ty2</tt>. -</p> + unsigned integer equivalent of type <tt>ty2</tt>.</p> <h5>Arguments:</h5> -<p>The '<tt>fptoui</tt>' instruction takes a value to cast, which must be a -scalar or vector <a href="#t_floating">floating point</a> value, and a type -to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> -type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a -vector integer type with the same number of elements as <tt>ty</tt></p> +<p>The '<tt>fptoui</tt>' instruction takes a value to cast, which must be a + scalar or vector <a href="#t_floating">floating point</a> value, and a type + to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> + type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a + vector integer type with the same number of elements as <tt>ty</tt></p> <h5>Semantics:</h5> -<p> The '<tt>fptoui</tt>' instruction converts its -<a href="#t_floating">floating point</a> operand into the nearest (rounding -towards zero) unsigned integer value. If the value cannot fit in <tt>ty2</tt>, -the results are undefined.</p> +<p>The '<tt>fptoui</tt>' instruction converts its + <a href="#t_floating">floating point</a> operand into the nearest (rounding + towards zero) unsigned integer value. If the value cannot fit + in <tt>ty2</tt>, the results are undefined.</p> <h5>Example:</h5> <pre> @@ -4096,6 +4435,7 @@ the results are undefined.</p> %Y = fptoui float 1.0E+300 to i1 <i>; yields undefined:1</i> %X = fptoui float 1.04E+17 to i8 <i>; yields undefined:1</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4111,21 +4451,21 @@ the results are undefined.</p> <h5>Overview:</h5> <p>The '<tt>fptosi</tt>' instruction converts -<a href="#t_floating">floating point</a> <tt>value</tt> to type <tt>ty2</tt>. -</p> + <a href="#t_floating">floating point</a> <tt>value</tt> to + type <tt>ty2</tt>.</p> <h5>Arguments:</h5> -<p> The '<tt>fptosi</tt>' instruction takes a value to cast, which must be a -scalar or vector <a href="#t_floating">floating point</a> value, and a type -to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> -type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a -vector integer type with the same number of elements as <tt>ty</tt></p> +<p>The '<tt>fptosi</tt>' instruction takes a value to cast, which must be a + scalar or vector <a href="#t_floating">floating point</a> value, and a type + to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> + type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a + vector integer type with the same number of elements as <tt>ty</tt></p> <h5>Semantics:</h5> <p>The '<tt>fptosi</tt>' instruction converts its -<a href="#t_floating">floating point</a> operand into the nearest (rounding -towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>, -the results are undefined.</p> + <a href="#t_floating">floating point</a> operand into the nearest (rounding + towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>, + the results are undefined.</p> <h5>Example:</h5> <pre> @@ -4133,6 +4473,7 @@ the results are undefined.</p> %Y = fptosi float 1.0E-247 to i1 <i>; yields undefined:1</i> %X = fptosi float 1.04E+17 to i8 <i>; yields undefined:1</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4148,25 +4489,27 @@ the results are undefined.</p> <h5>Overview:</h5> <p>The '<tt>uitofp</tt>' instruction regards <tt>value</tt> as an unsigned -integer and converts that value to the <tt>ty2</tt> type.</p> + integer and converts that value to the <tt>ty2</tt> type.</p> <h5>Arguments:</h5> <p>The '<tt>uitofp</tt>' instruction takes a value to cast, which must be a -scalar or vector <a href="#t_integer">integer</a> value, and a type to cast it -to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a> -type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector -floating point type with the same number of elements as <tt>ty</tt></p> + scalar or vector <a href="#t_integer">integer</a> value, and a type to cast + it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a> + type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector + floating point type with the same number of elements as <tt>ty</tt></p> <h5>Semantics:</h5> <p>The '<tt>uitofp</tt>' instruction interprets its operand as an unsigned -integer quantity and converts it to the corresponding floating point value. If -the value cannot fit in the floating point value, the results are undefined.</p> + integer quantity and converts it to the corresponding floating point + value. If the value cannot fit in the floating point value, the results are + undefined.</p> <h5>Example:</h5> <pre> %X = uitofp i32 257 to float <i>; yields float:257.0</i> %Y = uitofp i8 -1 to double <i>; yields double:255.0</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4181,26 +4524,27 @@ the value cannot fit in the floating point value, the results are undefined.</p> </pre> <h5>Overview:</h5> -<p>The '<tt>sitofp</tt>' instruction regards <tt>value</tt> as a signed -integer and converts that value to the <tt>ty2</tt> type.</p> +<p>The '<tt>sitofp</tt>' instruction regards <tt>value</tt> as a signed integer + and converts that value to the <tt>ty2</tt> type.</p> <h5>Arguments:</h5> <p>The '<tt>sitofp</tt>' instruction takes a value to cast, which must be a -scalar or vector <a href="#t_integer">integer</a> value, and a type to cast it -to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a> -type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector -floating point type with the same number of elements as <tt>ty</tt></p> + scalar or vector <a href="#t_integer">integer</a> value, and a type to cast + it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a> + type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector + floating point type with the same number of elements as <tt>ty</tt></p> <h5>Semantics:</h5> -<p>The '<tt>sitofp</tt>' instruction interprets its operand as a signed -integer quantity and converts it to the corresponding floating point value. If -the value cannot fit in the floating point value, the results are undefined.</p> +<p>The '<tt>sitofp</tt>' instruction interprets its operand as a signed integer + quantity and converts it to the corresponding floating point value. If the + value cannot fit in the floating point value, the results are undefined.</p> <h5>Example:</h5> <pre> %X = sitofp i32 257 to float <i>; yields float:257.0</i> %Y = sitofp i8 -1 to double <i>; yields double:-1.0</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4215,28 +4559,29 @@ the value cannot fit in the floating point value, the results are undefined.</p> </pre> <h5>Overview:</h5> -<p>The '<tt>ptrtoint</tt>' instruction converts the pointer <tt>value</tt> to -the integer type <tt>ty2</tt>.</p> +<p>The '<tt>ptrtoint</tt>' instruction converts the pointer <tt>value</tt> to + the integer type <tt>ty2</tt>.</p> <h5>Arguments:</h5> -<p>The '<tt>ptrtoint</tt>' instruction takes a <tt>value</tt> to cast, which -must be a <a href="#t_pointer">pointer</a> value, and a type to cast it to -<tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> type.</p> +<p>The '<tt>ptrtoint</tt>' instruction takes a <tt>value</tt> to cast, which + must be a <a href="#t_pointer">pointer</a> value, and a type to cast it to + <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> type.</p> <h5>Semantics:</h5> <p>The '<tt>ptrtoint</tt>' instruction converts <tt>value</tt> to integer type -<tt>ty2</tt> by interpreting the pointer value as an integer and either -truncating or zero extending that value to the size of the integer type. If -<tt>value</tt> is smaller than <tt>ty2</tt> then a zero extension is done. If -<tt>value</tt> is larger than <tt>ty2</tt> then a truncation is done. If they -are the same size, then nothing is done (<i>no-op cast</i>) other than a type -change.</p> + <tt>ty2</tt> by interpreting the pointer value as an integer and either + truncating or zero extending that value to the size of the integer type. If + <tt>value</tt> is smaller than <tt>ty2</tt> then a zero extension is done. If + <tt>value</tt> is larger than <tt>ty2</tt> then a truncation is done. If they + are the same size, then nothing is done (<i>no-op cast</i>) other than a type + change.</p> <h5>Example:</h5> <pre> %X = ptrtoint i32* %X to i8 <i>; yields truncation on 32-bit architecture</i> %Y = ptrtoint i32* %x to i64 <i>; yields zero extension on 32-bit architecture</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4251,21 +4596,21 @@ change.</p> </pre> <h5>Overview:</h5> -<p>The '<tt>inttoptr</tt>' instruction converts an integer <tt>value</tt> to -a pointer type, <tt>ty2</tt>.</p> +<p>The '<tt>inttoptr</tt>' instruction converts an integer <tt>value</tt> to a + pointer type, <tt>ty2</tt>.</p> <h5>Arguments:</h5> <p>The '<tt>inttoptr</tt>' instruction takes an <a href="#t_integer">integer</a> -value to cast, and a type to cast it to, which must be a -<a href="#t_pointer">pointer</a> type.</p> + value to cast, and a type to cast it to, which must be a + <a href="#t_pointer">pointer</a> type.</p> <h5>Semantics:</h5> <p>The '<tt>inttoptr</tt>' instruction converts <tt>value</tt> to type -<tt>ty2</tt> by applying either a zero extension or a truncation depending on -the size of the integer <tt>value</tt>. If <tt>value</tt> is larger than the -size of a pointer then a truncation is done. If <tt>value</tt> is smaller than -the size of a pointer then a zero extension is done. If they are the same size, -nothing is done (<i>no-op cast</i>).</p> + <tt>ty2</tt> by applying either a zero extension or a truncation depending on + the size of the integer <tt>value</tt>. If <tt>value</tt> is larger than the + size of a pointer then a truncation is done. If <tt>value</tt> is smaller + than the size of a pointer then a zero extension is done. If they are the + same size, nothing is done (<i>no-op cast</i>).</p> <h5>Example:</h5> <pre> @@ -4273,6 +4618,7 @@ nothing is done (<i>no-op cast</i>).</p> %X = inttoptr i32 255 to i32* <i>; yields no-op on 32-bit architecture</i> %Y = inttoptr i64 0 to i32* <i>; yields truncation on 32-bit architecture</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4287,29 +4633,27 @@ nothing is done (<i>no-op cast</i>).</p> </pre> <h5>Overview:</h5> - <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type -<tt>ty2</tt> without changing any bits.</p> + <tt>ty2</tt> without changing any bits.</p> <h5>Arguments:</h5> - -<p>The '<tt>bitcast</tt>' 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 <a href="#t_firstclass">first class</a> type. The bit sizes of -<tt>value</tt> -and the destination type, <tt>ty2</tt>, must be identical. If the source -type is a pointer, the destination type must also be a pointer. This -instruction supports bitwise conversion of vectors to integers and to vectors -of other types (as long as they have the same size).</p> +<p>The '<tt>bitcast</tt>' 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 <a href="#t_firstclass">first class</a> type. The bit sizes + of <tt>value</tt> and the destination type, <tt>ty2</tt>, must be + identical. If the source type is a pointer, the destination type must also be + a pointer. This instruction supports bitwise conversion of vectors to + integers and to vectors of other types (as long as they have the same + size).</p> <h5>Semantics:</h5> <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type -<tt>ty2</tt>. It is always a <i>no-op cast</i> because no bits change with -this conversion. The conversion is done as if the <tt>value</tt> had been -stored to memory and read back as type <tt>ty2</tt>. Pointer types may only be -converted to other pointer types with this instruction. To convert pointers to -other types, use the <a href="#i_inttoptr">inttoptr</a> or -<a href="#i_ptrtoint">ptrtoint</a> instructions first.</p> + <tt>ty2</tt>. It is always a <i>no-op cast</i> because no bits change with + this conversion. The conversion is done as if the <tt>value</tt> had been + stored to memory and read back as type <tt>ty2</tt>. Pointer types may only + be converted to other pointer types with this instruction. To convert + pointers to other types, use the <a href="#i_inttoptr">inttoptr</a> or + <a href="#i_ptrtoint">ptrtoint</a> instructions first.</p> <h5>Example:</h5> <pre> @@ -4317,31 +4661,40 @@ other types, use the <a href="#i_inttoptr">inttoptr</a> or %Y = bitcast i32* %x to sint* <i>; yields sint*:%x</i> %Z = bitcast <2 x int> %V to i64; <i>; yields i64: %V</i> </pre> + </div> <!-- ======================================================================= --> <div class="doc_subsection"> <a name="otherops">Other Operations</a> </div> + <div class="doc_text"> -<p>The instructions in this category are the "miscellaneous" -instructions, which defy better classification.</p> + +<p>The instructions in this category are the "miscellaneous" instructions, which + defy better classification.</p> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"><a name="i_icmp">'<tt>icmp</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = icmp <cond> <ty> <op1>, <op2> <i>; yields {i1} or {<N x i1>}:result</i> +<pre> + <result> = icmp <cond> <ty> <op1>, <op2> <i>; yields {i1} or {<N x i1>}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>icmp</tt>' instruction returns a boolean value or -a vector of boolean values based on comparison -of its two integer, integer vector, or pointer operands.</p> +<p>The '<tt>icmp</tt>' instruction returns a boolean value or a vector of + boolean values based on comparison of its two integer, integer vector, or + pointer operands.</p> + <h5>Arguments:</h5> <p>The '<tt>icmp</tt>' 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: -</p> + the condition code indicating the kind of comparison to perform. It is not a + value, just a keyword. The possible condition code are:</p> + <ol> <li><tt>eq</tt>: equal</li> <li><tt>ne</tt>: not equal </li> @@ -4354,48 +4707,63 @@ a value, just a keyword. The possible condition code are: <li><tt>slt</tt>: signed less than</li> <li><tt>sle</tt>: signed less or equal</li> </ol> + <p>The remaining two arguments must be <a href="#t_integer">integer</a> or -<a href="#t_pointer">pointer</a> -or integer <a href="#t_vector">vector</a> typed. -They must also be identical types.</p> + <a href="#t_pointer">pointer</a> or integer <a href="#t_vector">vector</a> + typed. They must also be identical types.</p> + <h5>Semantics:</h5> -<p>The '<tt>icmp</tt>' compares <tt>op1</tt> and <tt>op2</tt> according to -the condition code given as <tt>cond</tt>. The comparison performed always -yields either an <a href="#t_primitive"><tt>i1</tt></a> or vector of <tt>i1</tt> result, as follows: -</p> +<p>The '<tt>icmp</tt>' compares <tt>op1</tt> and <tt>op2</tt> according to the + condition code given as <tt>cond</tt>. The comparison performed always yields + either an <a href="#t_integer"><tt>i1</tt></a> or vector of <tt>i1</tt> + result, as follows:</p> + <ol> <li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal, - <tt>false</tt> otherwise. No sign interpretation is necessary or performed. - </li> + <tt>false</tt> otherwise. No sign interpretation is necessary or + performed.</li> + <li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal, - <tt>false</tt> otherwise. No sign interpretation is necessary or performed.</li> + <tt>false</tt> otherwise. No sign interpretation is necessary or + performed.</li> + <li><tt>ugt</tt>: interprets the operands as unsigned values and yields - <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li> + <li><tt>uge</tt>: interprets the operands as unsigned values and yields - <tt>true</tt> if <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is greater than or equal + to <tt>op2</tt>.</li> + <li><tt>ult</tt>: interprets the operands as unsigned values and yields - <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li> + <li><tt>ule</tt>: interprets the operands as unsigned values and yields - <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> + <li><tt>sgt</tt>: interprets the operands as signed values and yields - <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li> + <li><tt>sge</tt>: interprets the operands as signed values and yields - <tt>true</tt> if <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is greater than or equal + to <tt>op2</tt>.</li> + <li><tt>slt</tt>: interprets the operands as signed values and yields - <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li> + <li><tt>sle</tt>: interprets the operands as signed values and yields - <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> </ol> + <p>If the operands are <a href="#t_pointer">pointer</a> typed, the pointer -values are compared as if they were integers.</p> -<p>If the operands are integer vectors, then they are compared -element by element. The result is an <tt>i1</tt> vector with -the same number of elements as the values being compared. -Otherwise, the result is an <tt>i1</tt>. -</p> + values are compared as if they were integers.</p> + +<p>If the operands are integer vectors, then they are compared element by + element. The result is an <tt>i1</tt> vector with the same number of elements + as the values being compared. Otherwise, the result is an <tt>i1</tt>.</p> <h5>Example:</h5> -<pre> <result> = icmp eq i32 4, 5 <i>; yields: result=false</i> +<pre> + <result> = icmp eq i32 4, 5 <i>; yields: result=false</i> <result> = icmp ne float* %X, %X <i>; yields: result=false</i> <result> = icmp ult i16 4, 5 <i>; yields: result=true</i> <result> = icmp sgt i16 4, 5 <i>; yields: result=false</i> @@ -4411,25 +4779,30 @@ Otherwise, the result is an <tt>i1</tt>. <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"><a name="i_fcmp">'<tt>fcmp</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = fcmp <cond> <ty> <op1>, <op2> <i>; yields {i1} or {<N x i1>}:result</i> +<pre> + <result> = fcmp <cond> <ty> <op1>, <op2> <i>; yields {i1} or {<N x i1>}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>fcmp</tt>' instruction returns a boolean value -or vector of boolean values based on comparison -of its operands.</p> -<p> -If the operands are floating point scalars, then the result -type is a boolean (<a href="#t_primitive"><tt>i1</tt></a>). -</p> -<p>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.</p> +<p>The '<tt>fcmp</tt>' instruction returns a boolean value or vector of boolean + values based on comparison of its operands.</p> + +<p>If the operands are floating point scalars, then the result type is a boolean +(<a href="#t_integer"><tt>i1</tt></a>).</p> + +<p>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.</p> + <h5>Arguments:</h5> <p>The '<tt>fcmp</tt>' 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:</p> + the condition code indicating the kind of comparison to perform. It is not a + value, just a keyword. The possible condition code are:</p> + <ol> <li><tt>false</tt>: no comparison, always returns false</li> <li><tt>oeq</tt>: ordered and equal</li> @@ -4448,52 +4821,71 @@ a value, just a keyword. The possible condition code are:</p> <li><tt>uno</tt>: unordered (either nans)</li> <li><tt>true</tt>: no comparison, always returns true</li> </ol> + <p><i>Ordered</i> means that neither operand is a QNAN while -<i>unordered</i> means that either operand may be a QNAN.</p> -<p>Each of <tt>val1</tt> and <tt>val2</tt> arguments must be -either a <a href="#t_floating">floating point</a> type -or a <a href="#t_vector">vector</a> of floating point type. -They must have identical types.</p> + <i>unordered</i> means that either operand may be a QNAN.</p> + +<p>Each of <tt>val1</tt> and <tt>val2</tt> arguments must be either + a <a href="#t_floating">floating point</a> type or + a <a href="#t_vector">vector</a> of floating point type. They must have + identical types.</p> + <h5>Semantics:</h5> <p>The '<tt>fcmp</tt>' instruction compares <tt>op1</tt> and <tt>op2</tt> -according to the condition code given as <tt>cond</tt>. -If the operands are vectors, then the vectors are compared -element by element. -Each comparison performed -always yields an <a href="#t_primitive">i1</a> result, as follows:</p> + according to the condition code given as <tt>cond</tt>. If the operands are + vectors, then the vectors are compared element by element. Each comparison + performed always yields an <a href="#t_integer">i1</a> result, as + follows:</p> + <ol> <li><tt>false</tt>: always yields <tt>false</tt>, regardless of operands.</li> + <li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and - <tt>op1</tt> is equal to <tt>op2</tt>.</li> + <tt>op1</tt> is equal to <tt>op2</tt>.</li> + <li><tt>ogt</tt>: yields <tt>true</tt> if both operands are not a QNAN and - <tt>op1</tt> is greather than <tt>op2</tt>.</li> + <tt>op1</tt> is greather than <tt>op2</tt>.</li> + <li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and - <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li> + <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li> + <li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and - <tt>op1</tt> is less than <tt>op2</tt>.</li> + <tt>op1</tt> is less than <tt>op2</tt>.</li> + <li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and - <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> + <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> + <li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and - <tt>op1</tt> is not equal to <tt>op2</tt>.</li> + <tt>op1</tt> is not equal to <tt>op2</tt>.</li> + <li><tt>ord</tt>: yields <tt>true</tt> if both operands are not a QNAN.</li> + <li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or - <tt>op1</tt> is equal to <tt>op2</tt>.</li> + <tt>op1</tt> is equal to <tt>op2</tt>.</li> + <li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or - <tt>op1</tt> is greater than <tt>op2</tt>.</li> + <tt>op1</tt> is greater than <tt>op2</tt>.</li> + <li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or - <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li> + <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li> + <li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or - <tt>op1</tt> is less than <tt>op2</tt>.</li> + <tt>op1</tt> is less than <tt>op2</tt>.</li> + <li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or - <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> + <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> + <li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or - <tt>op1</tt> is not equal to <tt>op2</tt>.</li> + <tt>op1</tt> is not equal to <tt>op2</tt>.</li> + <li><tt>uno</tt>: yields <tt>true</tt> if either operand is a QNAN.</li> + <li><tt>true</tt>: always yields <tt>true</tt>, regardless of operands.</li> </ol> <h5>Example:</h5> -<pre> <result> = fcmp oeq float 4.0, 5.0 <i>; yields: result=false</i> +<pre> + <result> = fcmp oeq float 4.0, 5.0 <i>; yields: result=false</i> <result> = fcmp one float 4.0, 5.0 <i>; yields: result=true</i> <result> = fcmp olt float 4.0, 5.0 <i>; yields: result=true</i> <result> = fcmp ueq double 1.0, 2.0 <i>; yields: result=false</i> @@ -4506,143 +4898,41 @@ always yields an <a href="#t_primitive">i1</a> result, as follows:</p> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> - <a name="i_vicmp">'<tt>vicmp</tt>' Instruction</a> -</div> -<div class="doc_text"> -<h5>Syntax:</h5> -<pre> <result> = vicmp <cond> <ty> <op1>, <op2> <i>; yields {ty}:result</i> -</pre> -<h5>Overview:</h5> -<p>The '<tt>vicmp</tt>' instruction returns an integer vector value based on -element-wise comparison of its two integer vector operands.</p> -<h5>Arguments:</h5> -<p>The '<tt>vicmp</tt>' 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:</p> -<ol> - <li><tt>eq</tt>: equal</li> - <li><tt>ne</tt>: not equal </li> - <li><tt>ugt</tt>: unsigned greater than</li> - <li><tt>uge</tt>: unsigned greater or equal</li> - <li><tt>ult</tt>: unsigned less than</li> - <li><tt>ule</tt>: unsigned less or equal</li> - <li><tt>sgt</tt>: signed greater than</li> - <li><tt>sge</tt>: signed greater or equal</li> - <li><tt>slt</tt>: signed less than</li> - <li><tt>sle</tt>: signed less or equal</li> -</ol> -<p>The remaining two arguments must be <a href="#t_vector">vector</a> or -<a href="#t_integer">integer</a> typed. They must also be identical types.</p> -<h5>Semantics:</h5> -<p>The '<tt>vicmp</tt>' instruction compares <tt>op1</tt> and <tt>op2</tt> -according to the condition code given as <tt>cond</tt>. The comparison yields a -<a href="#t_vector">vector</a> of <a href="#t_integer">integer</a> result, of -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 <a href="#i_icmp">'<tt>icmp</tt>' -instruction</a>.</p> - -<h5>Example:</h5> -<pre> - <result> = vicmp eq <2 x i32> < i32 4, i32 0>, < i32 5, i32 0> <i>; yields: result=<2 x i32> < i32 0, i32 -1 ></i> - <result> = vicmp ult <2 x i8 > < i8 1, i8 2>, < i8 2, i8 2 > <i>; yields: result=<2 x i8> < i8 -1, i8 0 ></i> -</pre> -</div> - -<!-- _______________________________________________________________________ --> -<div class="doc_subsubsection"> - <a name="i_vfcmp">'<tt>vfcmp</tt>' Instruction</a> -</div> -<div class="doc_text"> -<h5>Syntax:</h5> -<pre> <result> = vfcmp <cond> <ty> <op1>, <op2></pre> -<h5>Overview:</h5> -<p>The '<tt>vfcmp</tt>' instruction returns an integer vector value based on -element-wise comparison of its two floating point vector operands. The output -elements have the same width as the input elements.</p> -<h5>Arguments:</h5> -<p>The '<tt>vfcmp</tt>' 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:</p> -<ol> - <li><tt>false</tt>: no comparison, always returns false</li> - <li><tt>oeq</tt>: ordered and equal</li> - <li><tt>ogt</tt>: ordered and greater than </li> - <li><tt>oge</tt>: ordered and greater than or equal</li> - <li><tt>olt</tt>: ordered and less than </li> - <li><tt>ole</tt>: ordered and less than or equal</li> - <li><tt>one</tt>: ordered and not equal</li> - <li><tt>ord</tt>: ordered (no nans)</li> - <li><tt>ueq</tt>: unordered or equal</li> - <li><tt>ugt</tt>: unordered or greater than </li> - <li><tt>uge</tt>: unordered or greater than or equal</li> - <li><tt>ult</tt>: unordered or less than </li> - <li><tt>ule</tt>: unordered or less than or equal</li> - <li><tt>une</tt>: unordered or not equal</li> - <li><tt>uno</tt>: unordered (either nans)</li> - <li><tt>true</tt>: no comparison, always returns true</li> -</ol> -<p>The remaining two arguments must be <a href="#t_vector">vector</a> of -<a href="#t_floating">floating point</a> typed. They must also be identical -types.</p> -<h5>Semantics:</h5> -<p>The '<tt>vfcmp</tt>' instruction compares <tt>op1</tt> and <tt>op2</tt> -according to the condition code given as <tt>cond</tt>. The comparison yields a -<a href="#t_vector">vector</a> of <a href="#t_integer">integer</a> result, with -an identical number of elements as the values being compared, and each element -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 -<a href="#i_fcmp">'<tt>fcmp</tt>' instruction</a>.</p> - -<h5>Example:</h5> -<pre> - <i>; yields: result=<2 x i32> < i32 0, i32 -1 ></i> - <result> = vfcmp oeq <2 x float> < float 4, float 0 >, < float 5, float 0 > - - <i>; yields: result=<2 x i64> < i64 -1, i64 0 ></i> - <result> = vfcmp ult <2 x double> < double 1, double 2 >, < double 2, double 2> -</pre> -</div> - -<!-- _______________________________________________________________________ --> -<div class="doc_subsubsection"> <a name="i_phi">'<tt>phi</tt>' Instruction</a> </div> <div class="doc_text"> <h5>Syntax:</h5> +<pre> + <result> = phi <ty> [ <val0>, <label0>], ... +</pre> -<pre> <result> = phi <ty> [ <val0>, <label0>], ...<br></pre> <h5>Overview:</h5> -<p>The '<tt>phi</tt>' instruction is used to implement the φ node in -the SSA graph representing the function.</p> -<h5>Arguments:</h5> - -<p>The type of the incoming values is specified with the first type -field. After this, the '<tt>phi</tt>' instruction takes a list of pairs -as arguments, with one pair for each predecessor basic block of the -current block. Only values of <a href="#t_firstclass">first class</a> -type may be used as the value arguments to the PHI node. Only labels -may be used as the label arguments.</p> - -<p>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.</p> +<p>The '<tt>phi</tt>' instruction is used to implement the φ node in the + SSA graph representing the function.</p> -<p>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 '<tt>invoke</tt>' -instruction's return value on the same edge).</p> +<h5>Arguments:</h5> +<p>The type of the incoming values is specified with the first type field. After + this, the '<tt>phi</tt>' instruction takes a list of pairs as arguments, with + one pair for each predecessor basic block of the current block. Only values + of <a href="#t_firstclass">first class</a> type may be used as the value + arguments to the PHI node. Only labels may be used as the label + arguments.</p> + +<p>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.</p> + +<p>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 '<tt>invoke</tt>' instruction's return + value on the same edge).</p> <h5>Semantics:</h5> - <p>At runtime, the '<tt>phi</tt>' instruction logically takes on the value -specified by the pair corresponding to the predecessor basic block that executed -just prior to the current block.</p> + specified by the pair corresponding to the predecessor basic block that + executed just prior to the current block.</p> <h5>Example:</h5> <pre> @@ -4651,6 +4941,7 @@ Loop: ; Infinite loop that counts from 0 on up... %nextindvar = add i32 %indvar, 1 br label %Loop </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4661,7 +4952,6 @@ Loop: ; Infinite loop that counts from 0 on up... <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = select <i>selty</i> <cond>, <ty> <val1>, <ty> <val2> <i>; yields ty</i> @@ -4669,38 +4959,25 @@ Loop: ; Infinite loop that counts from 0 on up... </pre> <h5>Overview:</h5> - -<p> -The '<tt>select</tt>' instruction is used to choose one value based on a -condition, without branching. -</p> +<p>The '<tt>select</tt>' instruction is used to choose one value based on a + condition, without branching.</p> <h5>Arguments:</h5> - -<p> -The '<tt>select</tt>' instruction requires an 'i1' value or -a vector of 'i1' values indicating the -condition, and two values of the same <a href="#t_firstclass">first class</a> -type. If the val1/val2 are vectors and -the condition is a scalar, then entire vectors are selected, not -individual elements. -</p> +<p>The '<tt>select</tt>' instruction requires an 'i1' value or a vector of 'i1' + values indicating the condition, and two values of the + same <a href="#t_firstclass">first class</a> type. If the val1/val2 are + vectors and the condition is a scalar, then entire vectors are selected, not + individual elements.</p> <h5>Semantics:</h5> +<p>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.</p> -<p> -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. -</p> -<p> -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. -</p> +<p>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.</p> <h5>Example:</h5> - <pre> %X = select i1 true, i8 17, i8 42 <i>; yields i8:17</i> </pre> @@ -4710,7 +4987,6 @@ by element. </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_call">'<tt>call</tt>' Instruction</a> @@ -4724,75 +5000,60 @@ by element. </pre> <h5>Overview:</h5> - <p>The '<tt>call</tt>' instruction represents a simple function call.</p> <h5>Arguments:</h5> - <p>This instruction requires several arguments:</p> <ol> - <li> - <p>The optional "tail" marker indicates whether the callee function accesses - any allocas or varargs in the caller. If the "tail" marker is present, the - function call is eligible for tail call optimization. Note that calls may - be marked "tail" even if they do not occur before a <a - href="#i_ret"><tt>ret</tt></a> instruction.</p> - </li> - <li> - <p>The optional "cconv" marker indicates which <a href="#callingconv">calling - convention</a> the call should use. If none is specified, the call defaults - to using C calling conventions.</p> - </li> + <li>The optional "tail" marker indicates whether the callee function accesses + any allocas or varargs in the caller. If the "tail" marker is present, + the function call is eligible for tail call optimization. Note that calls + may be marked "tail" even if they do not occur before + a <a href="#i_ret"><tt>ret</tt></a> instruction.</li> - <li> - <p>The optional <a href="#paramattrs">Parameter Attributes</a> list for - return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', - and '<tt>inreg</tt>' attributes are valid here.</p> - </li> + <li>The optional "cconv" marker indicates which <a href="#callingconv">calling + convention</a> the call should use. If none is specified, the call + defaults to using C calling conventions.</li> - <li> - <p>'<tt>ty</tt>': the type of the call instruction itself which is also - the type of the return value. Functions that return no value are marked - <tt><a href="#t_void">void</a></tt>.</p> - </li> - <li> - <p>'<tt>fnty</tt>': shall be the signature of the pointer to function - value being invoked. The argument types must match the types implied by - this signature. This type can be omitted if the function is not varargs - and if the function type does not return a pointer to a function.</p> - </li> - <li> - <p>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to - be invoked. In most cases, this is a direct function invocation, but - indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer - to function value.</p> - </li> - <li> - <p>'<tt>function args</tt>': argument list whose types match the - function signature argument types. All arguments must be of - <a href="#t_firstclass">first class</a> type. If the function signature - indicates the function accepts a variable number of arguments, the extra - arguments can be specified.</p> - </li> - <li> - <p>The optional <a href="#fnattrs">function attributes</a> list. Only - '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and - '<tt>readnone</tt>' attributes are valid here.</p> - </li> + <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for + return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and + '<tt>inreg</tt>' attributes are valid here.</li> + + <li>'<tt>ty</tt>': the type of the call instruction itself which is also the + type of the return value. Functions that return no value are marked + <tt><a href="#t_void">void</a></tt>.</li> + + <li>'<tt>fnty</tt>': shall be the signature of the pointer to function value + being invoked. The argument types must match the types implied by this + signature. This type can be omitted if the function is not varargs and if + the function type does not return a pointer to a function.</li> + + <li>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to + be invoked. In most cases, this is a direct function invocation, but + indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer + to function value.</li> + + <li>'<tt>function args</tt>': argument list whose types match the function + signature argument types. All arguments must be of + <a href="#t_firstclass">first class</a> type. If the function signature + indicates the function accepts a variable number of arguments, the extra + arguments can be specified.</li> + + <li>The optional <a href="#fnattrs">function attributes</a> list. Only + '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and + '<tt>readnone</tt>' attributes are valid here.</li> </ol> <h5>Semantics:</h5> - -<p>The '<tt>call</tt>' instruction is used to cause control flow to -transfer to a specified function, with its incoming arguments bound to -the specified values. Upon a '<tt><a href="#i_ret">ret</a></tt>' -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.</p> +<p>The '<tt>call</tt>' instruction is used to cause control flow to transfer to + a specified function, with its incoming arguments bound to the specified + values. Upon a '<tt><a href="#i_ret">ret</a></tt>' 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.</p> <h5>Example:</h5> - <pre> %retval = call i32 @test(i32 %argc) call i32 (i8 *, ...)* @printf(i8 * %msg, i32 12, i8 42) <i>; yields i32</i> @@ -4808,6 +5069,12 @@ function is bound to the result argument.</p> %ZZ = call zeroext i32 @bar() <i>; Return value is %zero extended</i> </pre> +<p>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 langauges.</p> + </div> <!-- _______________________________________________________________________ --> @@ -4818,47 +5085,41 @@ function is bound to the result argument.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <resultval> = va_arg <va_list*> <arglist>, <argty> </pre> <h5>Overview:</h5> - <p>The '<tt>va_arg</tt>' instruction is used to access arguments passed through -the "variable argument" area of a function call. It is used to implement the -<tt>va_arg</tt> macro in C.</p> + the "variable argument" area of a function call. It is used to implement the + <tt>va_arg</tt> macro in C.</p> <h5>Arguments:</h5> - -<p>This instruction takes a <tt>va_list*</tt> value and the type of -the argument. It returns a value of the specified argument type and -increments the <tt>va_list</tt> to point to the next argument. The -actual type of <tt>va_list</tt> is target specific.</p> +<p>This instruction takes a <tt>va_list*</tt> value and the type of the + argument. It returns a value of the specified argument type and increments + the <tt>va_list</tt> to point to the next argument. The actual type + of <tt>va_list</tt> is target specific.</p> <h5>Semantics:</h5> - -<p>The '<tt>va_arg</tt>' instruction loads an argument of the specified -type from the specified <tt>va_list</tt> and causes the -<tt>va_list</tt> to point to the next argument. For more information, -see the variable argument handling <a href="#int_varargs">Intrinsic -Functions</a>.</p> +<p>The '<tt>va_arg</tt>' instruction loads an argument of the specified type + from the specified <tt>va_list</tt> and causes the <tt>va_list</tt> to point + to the next argument. For more information, see the variable argument + handling <a href="#int_varargs">Intrinsic Functions</a>.</p> <p>It is legal for this instruction to be called in a function which does not -take a variable number of arguments, for example, the <tt>vfprintf</tt> -function.</p> + take a variable number of arguments, for example, the <tt>vfprintf</tt> + function.</p> -<p><tt>va_arg</tt> is an LLVM instruction instead of an <a -href="#intrinsics">intrinsic function</a> because it takes a type as an -argument.</p> +<p><tt>va_arg</tt> is an LLVM instruction instead of + an <a href="#intrinsics">intrinsic function</a> because it takes a type as an + argument.</p> <h5>Example:</h5> - <p>See the <a href="#int_varargs">variable argument processing</a> section.</p> -<p>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.</p> +<p>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.</p> </div> @@ -4869,45 +5130,45 @@ argument.</p> <div class="doc_text"> <p>LLVM supports the notion of an "intrinsic function". These functions have -well known names and semantics and are required to follow certain restrictions. -Overall, these intrinsics represent an extension mechanism for the LLVM -language that does not require changing all of the transformations in LLVM when -adding to the language (or the bitcode reader/writer, the parser, etc...).</p> + well known names and semantics and are required to follow certain + restrictions. Overall, these intrinsics represent an extension mechanism for + the LLVM language that does not require changing all of the transformations + in LLVM when adding to the language (or the bitcode reader/writer, the + parser, etc...).</p> <p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix. This -prefix is reserved in LLVM for intrinsic names; thus, function names may not -begin with this prefix. Intrinsic functions must always be external functions: -you cannot define the body of intrinsic functions. Intrinsic functions may -only be used in call or invoke instructions: it is illegal to take the address -of an intrinsic function. Additionally, because intrinsic functions are part -of the LLVM language, it is required if any are added that they be documented -here.</p> - -<p>Some intrinsic functions can be overloaded, i.e., the intrinsic represents -a family of functions that perform the same operation but on different data -types. Because LLVM can represent over 8 million different integer types, -overloading is used commonly to allow an intrinsic function to operate on any -integer type. One or more of the argument types or the result type can be -overloaded to accept any integer type. Argument types may also be defined as -exactly matching a previous argument's type or the result type. This allows an -intrinsic function which accepts multiple arguments, but needs all of them to -be of the same type, to only be overloaded with respect to a single argument or -the result.</p> - -<p>Overloaded intrinsics will have the names of its overloaded argument types -encoded into its function name, each preceded by a period. Only those types -which are overloaded result in a name suffix. Arguments whose type is matched -against another type do not. For example, the <tt>llvm.ctpop</tt> function can -take an integer of any width and returns an integer of exactly the same integer -width. This leads to a family of functions such as -<tt>i8 @llvm.ctpop.i8(i8 %val)</tt> and <tt>i29 @llvm.ctpop.i29(i29 %val)</tt>. -Only one type, the return type, is overloaded, and only one type suffix is -required. Because the argument's type is matched against the return type, it -does not require its own name suffix.</p> + prefix is reserved in LLVM for intrinsic names; thus, function names may not + begin with this prefix. Intrinsic functions must always be external + functions: you cannot define the body of intrinsic functions. Intrinsic + functions may only be used in call or invoke instructions: it is illegal to + take the address of an intrinsic function. Additionally, because intrinsic + functions are part of the LLVM language, it is required if any are added that + they be documented here.</p> + +<p>Some intrinsic functions can be overloaded, i.e., the intrinsic represents a + family of functions that perform the same operation but on different data + types. Because LLVM can represent over 8 million different integer types, + overloading is used commonly to allow an intrinsic function to operate on any + integer type. One or more of the argument types or the result type can be + overloaded to accept any integer type. Argument types may also be defined as + exactly matching a previous argument's type or the result type. This allows + an intrinsic function which accepts multiple arguments, but needs all of them + to be of the same type, to only be overloaded with respect to a single + argument or the result.</p> + +<p>Overloaded intrinsics will have the names of its overloaded argument types + encoded into its function name, each preceded by a period. Only those types + which are overloaded result in a name suffix. Arguments whose type is matched + against another type do not. For example, the <tt>llvm.ctpop</tt> function + can take an integer of any width and returns an integer of exactly the same + integer width. This leads to a family of functions such as + <tt>i8 @llvm.ctpop.i8(i8 %val)</tt> and <tt>i29 @llvm.ctpop.i29(i29 + %val)</tt>. Only one type, the return type, is overloaded, and only one type + suffix is required. Because the argument's type is matched against the return + type, it does not require its own name suffix.</p> <p>To learn how to add an intrinsic function, please see the -<a href="ExtendingLLVM.html">Extending LLVM Guide</a>. -</p> + <a href="ExtendingLLVM.html">Extending LLVM Guide</a>.</p> </div> @@ -4918,20 +5179,19 @@ does not require its own name suffix.</p> <div class="doc_text"> -<p>Variable argument support is defined in LLVM with the <a - href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three -intrinsic functions. These functions are related to the similarly -named macros defined in the <tt><stdarg.h></tt> header file.</p> +<p>Variable argument support is defined in LLVM with + the <a href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three + intrinsic functions. These functions are related to the similarly named + macros defined in the <tt><stdarg.h></tt> header file.</p> -<p>All of these functions operate on arguments that use a -target-specific value type "<tt>va_list</tt>". The LLVM assembly -language reference manual does not define what this type is, so all -transformations should be prepared to handle these functions regardless of -the type used.</p> +<p>All of these functions operate on arguments that use a target-specific value + type "<tt>va_list</tt>". The LLVM assembly language reference manual does + not define what this type is, so all transformations should be prepared to + handle these functions regardless of the type used.</p> <p>This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a> -instruction and the variable argument handling intrinsic functions are -used.</p> + instruction and the variable argument handling intrinsic functions are + used.</p> <div class="doc_code"> <pre> @@ -4970,25 +5230,27 @@ declare void @llvm.va_end(i8*) <div class="doc_text"> + <h5>Syntax:</h5> -<pre> declare void %llvm.va_start(i8* <arglist>)<br></pre> +<pre> + declare void %llvm.va_start(i8* <arglist>) +</pre> + <h5>Overview:</h5> -<p>The '<tt>llvm.va_start</tt>' intrinsic initializes -<tt>*<arglist></tt> for subsequent use by <tt><a -href="#i_va_arg">va_arg</a></tt>.</p> +<p>The '<tt>llvm.va_start</tt>' intrinsic initializes <tt>*<arglist></tt> + for subsequent use by <tt><a href="#i_va_arg">va_arg</a></tt>.</p> <h5>Arguments:</h5> - <p>The argument is a pointer to a <tt>va_list</tt> element to initialize.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt> -macro available in C. In a target-dependent way, it initializes the -<tt>va_list</tt> element to which the argument points, so that the next call to -<tt>va_arg</tt> will produce the first variable argument passed to the function. -Unlike the C <tt>va_start</tt> macro, this intrinsic does not need to know the -last argument of the function as the compiler can figure that out.</p> + macro available in C. In a target-dependent way, it initializes + the <tt>va_list</tt> element to which the argument points, so that the next + call to <tt>va_arg</tt> will produce the first variable argument passed to + the function. Unlike the C <tt>va_start</tt> macro, this intrinsic does not + need to know the last argument of the function as the compiler can figure + that out.</p> </div> @@ -4998,26 +5260,28 @@ last argument of the function as the compiler can figure that out.</p> </div> <div class="doc_text"> + <h5>Syntax:</h5> -<pre> declare void @llvm.va_end(i8* <arglist>)<br></pre> -<h5>Overview:</h5> +<pre> + declare void @llvm.va_end(i8* <arglist>) +</pre> +<h5>Overview:</h5> <p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>*<arglist></tt>, -which has been initialized previously with <tt><a href="#int_va_start">llvm.va_start</a></tt> -or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p> + which has been initialized previously + with <tt><a href="#int_va_start">llvm.va_start</a></tt> + or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p> <h5>Arguments:</h5> - <p>The argument is a pointer to a <tt>va_list</tt> to destroy.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt> -macro available in C. In a target-dependent way, it destroys the -<tt>va_list</tt> element to which the argument points. Calls to <a -href="#int_va_start"><tt>llvm.va_start</tt></a> and <a href="#int_va_copy"> -<tt>llvm.va_copy</tt></a> must be matched exactly with calls to -<tt>llvm.va_end</tt>.</p> + macro available in C. In a target-dependent way, it destroys + the <tt>va_list</tt> element to which the argument points. Calls + to <a href="#int_va_start"><tt>llvm.va_start</tt></a> + and <a href="#int_va_copy"> <tt>llvm.va_copy</tt></a> must be matched exactly + with calls to <tt>llvm.va_end</tt>.</p> </div> @@ -5029,30 +5293,26 @@ href="#int_va_start"><tt>llvm.va_start</tt></a> and <a href="#int_va_copy"> <div class="doc_text"> <h5>Syntax:</h5> - <pre> declare void @llvm.va_copy(i8* <destarglist>, i8* <srcarglist>) </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position -from the source argument list to the destination argument list.</p> + from the source argument list to the destination argument list.</p> <h5>Arguments:</h5> - <p>The first argument is a pointer to a <tt>va_list</tt> element to initialize. -The second argument is a pointer to a <tt>va_list</tt> element to copy from.</p> - + The second argument is a pointer to a <tt>va_list</tt> element to copy + from.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt> -macro available in C. In a target-dependent way, it copies the source -<tt>va_list</tt> element into the destination <tt>va_list</tt> element. This -intrinsic is necessary because the <tt><a href="#int_va_start"> -llvm.va_start</a></tt> intrinsic may be arbitrarily complex and require, for -example, memory allocation.</p> + macro available in C. In a target-dependent way, it copies the + source <tt>va_list</tt> element into the destination <tt>va_list</tt> + element. This intrinsic is necessary because + the <tt><a href="#int_va_start"> llvm.va_start</a></tt> intrinsic may be + arbitrarily complex and require, for example, memory allocation.</p> </div> @@ -5063,20 +5323,18 @@ example, memory allocation.</p> <div class="doc_text"> -<p> -LLVM support for <a href="GarbageCollection.html">Accurate Garbage +<p>LLVM support for <a href="GarbageCollection.html">Accurate Garbage Collection</a> (GC) requires the implementation and generation of these -intrinsics. -These intrinsics allow identification of <a href="#int_gcroot">GC roots on the -stack</a>, as well as garbage collector implementations that require <a -href="#int_gcread">read</a> and <a href="#int_gcwrite">write</a> barriers. -Front-ends for type-safe garbage collected languages should generate these -intrinsics to make use of the LLVM garbage collectors. For more details, see <a -href="GarbageCollection.html">Accurate Garbage Collection with LLVM</a>. -</p> +intrinsics. These intrinsics allow identification of <a href="#int_gcroot">GC +roots on the stack</a>, as well as garbage collector implementations that +require <a href="#int_gcread">read</a> and <a href="#int_gcwrite">write</a> +barriers. Front-ends for type-safe garbage collected languages should generate +these intrinsics to make use of the LLVM garbage collectors. For more details, +see <a href="GarbageCollection.html">Accurate Garbage Collection with +LLVM</a>.</p> -<p>The garbage collection intrinsics only operate on objects in the generic - address space (address space zero).</p> +<p>The garbage collection intrinsics only operate on objects in the generic + address space (address space zero).</p> </div> @@ -5088,33 +5346,29 @@ href="GarbageCollection.html">Accurate Garbage Collection with LLVM</a>. <div class="doc_text"> <h5>Syntax:</h5> - <pre> declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata) </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existence of a GC root to -the code generator, and allows some metadata to be associated with it.</p> + the code generator, and allows some metadata to be associated with it.</p> <h5>Arguments:</h5> - <p>The first argument specifies the address of a stack object that contains the -root pointer. The second pointer (which must be either a constant or a global -value address) contains the meta-data to be associated with the root.</p> + root pointer. The second pointer (which must be either a constant or a + global value address) contains the meta-data to be associated with the + root.</p> <h5>Semantics:</h5> - <p>At runtime, a call to this intrinsic stores a null pointer into the "ptrloc" -location. At compile-time, the code generator generates information to allow -the runtime to find the pointer at GC safe points. The '<tt>llvm.gcroot</tt>' -intrinsic may only be used in a function which <a href="#gc">specifies a GC -algorithm</a>.</p> + location. At compile-time, the code generator generates information to allow + the runtime to find the pointer at GC safe points. The '<tt>llvm.gcroot</tt>' + intrinsic may only be used in a function which <a href="#gc">specifies a GC + algorithm</a>.</p> </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a> @@ -5123,35 +5377,30 @@ algorithm</a>.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr) </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap -locations, allowing garbage collector implementations that require read -barriers.</p> + locations, allowing garbage collector implementations that require read + barriers.</p> <h5>Arguments:</h5> - <p>The second argument is the address to read from, which should be an address -allocated from the garbage collector. The first object is a pointer to the -start of the referenced object, if needed by the language runtime (otherwise -null).</p> + allocated from the garbage collector. The first object is a pointer to the + start of the referenced object, if needed by the language runtime (otherwise + null).</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load -instruction, but may be replaced with substantially more complex code by the -garbage collector runtime, as needed. The '<tt>llvm.gcread</tt>' intrinsic -may only be used in a function which <a href="#gc">specifies a GC -algorithm</a>.</p> + instruction, but may be replaced with substantially more complex code by the + garbage collector runtime, as needed. The '<tt>llvm.gcread</tt>' intrinsic + may only be used in a function which <a href="#gc">specifies a GC + algorithm</a>.</p> </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a> @@ -5160,46 +5409,39 @@ algorithm</a>.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2) </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap -locations, allowing garbage collector implementations that require write -barriers (such as generational or reference counting collectors).</p> + locations, allowing garbage collector implementations that require write + barriers (such as generational or reference counting collectors).</p> <h5>Arguments:</h5> - <p>The first argument is the reference to store, the second is the start of the -object to store it to, and the third is the address of the field of Obj to -store to. If the runtime does not require a pointer to the object, Obj may be -null.</p> + object to store it to, and the third is the address of the field of Obj to + store to. If the runtime does not require a pointer to the object, Obj may + be null.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store -instruction, but may be replaced with substantially more complex code by the -garbage collector runtime, as needed. The '<tt>llvm.gcwrite</tt>' intrinsic -may only be used in a function which <a href="#gc">specifies a GC -algorithm</a>.</p> + instruction, but may be replaced with substantially more complex code by the + garbage collector runtime, as needed. The '<tt>llvm.gcwrite</tt>' intrinsic + may only be used in a function which <a href="#gc">specifies a GC + algorithm</a>.</p> </div> - - <!-- ======================================================================= --> <div class="doc_subsection"> <a name="int_codegen">Code Generator Intrinsics</a> </div> <div class="doc_text"> -<p> -These intrinsics are provided by LLVM to expose special features that may only -be implemented with code generator support. -</p> + +<p>These intrinsics are provided by LLVM to expose special features that may + only be implemented with code generator support.</p> </div> @@ -5216,38 +5458,28 @@ be implemented with code generator support. </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.returnaddress</tt>' intrinsic attempts to compute a -target-specific value indicating the return address of the current function -or one of its callers. -</p> +<p>The '<tt>llvm.returnaddress</tt>' intrinsic attempts to compute a + target-specific value indicating the return address of the current function + or one of its callers.</p> <h5>Arguments:</h5> - -<p> -The argument to this intrinsic indicates which function to return the address -for. Zero indicates the calling function, one indicates its caller, etc. The -argument is <b>required</b> to be a constant integer value. -</p> +<p>The argument to this intrinsic indicates which function to return the address + for. Zero indicates the calling function, one indicates its caller, etc. + The argument is <b>required</b> to be a constant integer value.</p> <h5>Semantics:</h5> +<p>The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer + indicating the return address of the specified call frame, or zero if it + cannot be identified. The value returned by this intrinsic is likely to be + incorrect or 0 for arguments other than zero, so it should only be used for + debugging purposes.</p> -<p> -The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer indicating -the return address of the specified call frame, or zero if it cannot be -identified. The value returned by this intrinsic is likely to be incorrect or 0 -for arguments other than zero, so it should only be used for debugging purposes. -</p> +<p>Note that calling this intrinsic does not prevent function inlining or other + aggressive transformations, so the value returned may not be that of the + obvious source-language caller.</p> -<p> -Note that calling this intrinsic does not prevent function inlining or other -aggressive transformations, so the value returned may not be that of the obvious -source-language caller. -</p> </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a> @@ -5261,34 +5493,25 @@ source-language caller. </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.frameaddress</tt>' intrinsic attempts to return the -target-specific frame pointer value for the specified stack frame. -</p> +<p>The '<tt>llvm.frameaddress</tt>' intrinsic attempts to return the + target-specific frame pointer value for the specified stack frame.</p> <h5>Arguments:</h5> - -<p> -The argument to this intrinsic indicates which function to return the frame -pointer for. Zero indicates the calling function, one indicates its caller, -etc. The argument is <b>required</b> to be a constant integer value. -</p> +<p>The argument to this intrinsic indicates which function to return the frame + pointer for. Zero indicates the calling function, one indicates its caller, + etc. The argument is <b>required</b> to be a constant integer value.</p> <h5>Semantics:</h5> +<p>The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer + indicating the frame address of the specified call frame, or zero if it + cannot be identified. The value returned by this intrinsic is likely to be + incorrect or 0 for arguments other than zero, so it should only be used for + debugging purposes.</p> -<p> -The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer indicating -the frame address of the specified call frame, or zero if it cannot be -identified. The value returned by this intrinsic is likely to be incorrect or 0 -for arguments other than zero, so it should only be used for debugging purposes. -</p> +<p>Note that calling this intrinsic does not prevent function inlining or other + aggressive transformations, so the value returned may not be that of the + obvious source-language caller.</p> -<p> -Note that calling this intrinsic does not prevent function inlining or other -aggressive transformations, so the value returned may not be that of the obvious -source-language caller. -</p> </div> <!-- _______________________________________________________________________ --> @@ -5304,25 +5527,20 @@ source-language caller. </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.stacksave</tt>' intrinsic is used to remember the current state of -the function stack, for use with <a href="#int_stackrestore"> -<tt>llvm.stackrestore</tt></a>. This is useful for implementing language -features like scoped automatic variable sized arrays in C99. -</p> +<p>The '<tt>llvm.stacksave</tt>' intrinsic is used to remember the current state + of the function stack, for use + with <a href="#int_stackrestore"> <tt>llvm.stackrestore</tt></a>. This is + useful for implementing language features like scoped automatic variable + sized arrays in C99.</p> <h5>Semantics:</h5> - -<p> -This intrinsic returns a opaque pointer value that can be passed to <a -href="#int_stackrestore"><tt>llvm.stackrestore</tt></a>. When an -<tt>llvm.stackrestore</tt> intrinsic is executed with a value saved from -<tt>llvm.stacksave</tt>, it effectively restores the state of the stack to the -state it was in when the <tt>llvm.stacksave</tt> intrinsic executed. In -practice, this pops any <a href="#i_alloca">alloca</a> blocks from the stack -that were allocated after the <tt>llvm.stacksave</tt> was executed. -</p> +<p>This intrinsic returns a opaque pointer value that can be passed + to <a href="#int_stackrestore"><tt>llvm.stackrestore</tt></a>. When + an <tt>llvm.stackrestore</tt> intrinsic is executed with a value saved + from <tt>llvm.stacksave</tt>, it effectively restores the state of the stack + to the state it was in when the <tt>llvm.stacksave</tt> intrinsic executed. + In practice, this pops any <a href="#i_alloca">alloca</a> blocks from the + stack that were allocated after the <tt>llvm.stacksave</tt> was executed.</p> </div> @@ -5339,24 +5557,18 @@ that were allocated after the <tt>llvm.stacksave</tt> was executed. </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.stackrestore</tt>' intrinsic is used to restore the state of -the function stack to the state it was in when the corresponding <a -href="#int_stacksave"><tt>llvm.stacksave</tt></a> intrinsic executed. This is -useful for implementing language features like scoped automatic variable sized -arrays in C99. -</p> +<p>The '<tt>llvm.stackrestore</tt>' intrinsic is used to restore the state of + the function stack to the state it was in when the + corresponding <a href="#int_stacksave"><tt>llvm.stacksave</tt></a> intrinsic + executed. This is useful for implementing language features like scoped + automatic variable sized arrays in C99.</p> <h5>Semantics:</h5> - -<p> -See the description for <a href="#int_stacksave"><tt>llvm.stacksave</tt></a>. -</p> +<p>See the description + for <a href="#int_stacksave"><tt>llvm.stacksave</tt></a>.</p> </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a> @@ -5370,34 +5582,23 @@ See the description for <a href="#int_stacksave"><tt>llvm.stacksave</tt></a>. </pre> <h5>Overview:</h5> - - -<p> -The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to insert -a prefetch instruction if supported; otherwise, it is a noop. Prefetches have -no -effect on the behavior of the program but can change its performance -characteristics. -</p> +<p>The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to + insert a prefetch instruction if supported; otherwise, it is a noop. + Prefetches have no effect on the behavior of the program but can change its + performance characteristics.</p> <h5>Arguments:</h5> - -<p> -<tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the specifier -determining if the fetch should be for a read (0) or write (1), and -<tt>locality</tt> is a temporal locality specifier ranging from (0) - no -locality, to (3) - extremely local keep in cache. The <tt>rw</tt> and -<tt>locality</tt> arguments must be constant integers. -</p> +<p><tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the + specifier determining if the fetch should be for a read (0) or write (1), + and <tt>locality</tt> is a temporal locality specifier ranging from (0) - no + locality, to (3) - extremely local keep in cache. The <tt>rw</tt> + and <tt>locality</tt> arguments must be constant integers.</p> <h5>Semantics:</h5> - -<p> -This intrinsic does not modify the behavior of the program. In particular, -prefetches cannot trap and do not produce a value. On targets that support this -intrinsic, the prefetch can provide hints to the processor cache for better -performance. -</p> +<p>This intrinsic does not modify the behavior of the program. In particular, + prefetches cannot trap and do not produce a value. On targets that support + this intrinsic, the prefetch can provide hints to the processor cache for + better performance.</p> </div> @@ -5414,32 +5615,21 @@ performance. </pre> <h5>Overview:</h5> - - -<p> -The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program Counter -(PC) in a region of -code to simulators and other tools. The method is target specific, but it is -expected that the marker will use exported symbols to transmit the PC of the -marker. -The marker makes no guarantees that it will remain with any specific instruction -after optimizations. It is possible that the presence of a marker will inhibit -optimizations. The intended use is to be inserted after optimizations to allow -correlations of simulation runs. -</p> +<p>The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program + Counter (PC) in a region of code to simulators and other tools. The method + is target specific, but it is expected that the marker will use exported + symbols to transmit the PC of the marker. The marker makes no guarantees + that it will remain with any specific instruction after optimizations. It is + possible that the presence of a marker will inhibit optimizations. The + intended use is to be inserted after optimizations to allow correlations of + simulation runs.</p> <h5>Arguments:</h5> - -<p> -<tt>id</tt> is a numerical id identifying the marker. -</p> +<p><tt>id</tt> is a numerical id identifying the marker.</p> <h5>Semantics:</h5> - -<p> -This intrinsic does not modify the behavior of the program. Backends that do not -support this intrinisic may ignore it. -</p> +<p>This intrinsic does not modify the behavior of the program. Backends that do + not support this intrinisic may ignore it.</p> </div> @@ -5456,23 +5646,17 @@ support this intrinisic may ignore it. </pre> <h5>Overview:</h5> - - -<p> -The '<tt>llvm.readcyclecounter</tt>' intrinsic provides access to the cycle -counter register (or similar low latency, high accuracy clocks) on those targets -that support it. On X86, it should map to RDTSC. On Alpha, it should map to RPCC. -As the backing counters overflow quickly (on the order of 9 seconds on alpha), this -should only be used for small timings. -</p> +<p>The '<tt>llvm.readcyclecounter</tt>' intrinsic provides access to the cycle + counter register (or similar low latency, high accuracy clocks) on those + targets that support it. On X86, it should map to RDTSC. On Alpha, it + should map to RPCC. As the backing counters overflow quickly (on the order + of 9 seconds on alpha), this should only be used for small timings.</p> <h5>Semantics:</h5> - -<p> -When directly supported, reading the cycle counter should not modify any memory. -Implementations are allowed to either return a application specific value or a -system wide value. On backends without support, this is lowered to a constant 0. -</p> +<p>When directly supported, reading the cycle counter should not modify any + memory. Implementations are allowed to either return a application specific + value or a system wide value. On backends without support, this is lowered + to a constant 0.</p> </div> @@ -5482,12 +5666,11 @@ system wide value. On backends without support, this is lowered to a constant 0 </div> <div class="doc_text"> -<p> -LLVM provides intrinsics for a few important standard C library functions. -These intrinsics allow source-language front-ends to pass information about the -alignment of the pointer arguments to the code generator, providing opportunity -for more efficient code generation. -</p> + +<p>LLVM provides intrinsics for a few important standard C library functions. + These intrinsics allow source-language front-ends to pass information about + the alignment of the pointer arguments to the code generator, providing + opportunity for more efficient code generation.</p> </div> @@ -5499,11 +5682,12 @@ for more efficient code generation. <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use llvm.memcpy on any integer bit -width. Not all targets support all bit widths however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.memcpy</tt> on any + integer bit width. Not all targets support all bit widths however.</p> + <pre> declare void @llvm.memcpy.i8(i8 * <dest>, i8 * <src>, - i8 <len>, i32 <align>) + i8 <len>, i32 <align>) declare void @llvm.memcpy.i16(i8 * <dest>, i8 * <src>, i16 <len>, i32 <align>) declare void @llvm.memcpy.i32(i8 * <dest>, i8 * <src>, @@ -5513,44 +5697,31 @@ width. Not all targets support all bit widths however.</p> </pre> <h5>Overview:</h5> +<p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the + source location to the destination location.</p> -<p> -The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the source -location to the destination location. -</p> - -<p> -Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt> -intrinsics do not return a value, and takes an extra alignment argument. -</p> +<p>Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt> + intrinsics do not return a value, and takes an extra alignment argument.</p> <h5>Arguments:</h5> +<p>The first argument is a pointer to the destination, the second is a pointer + to the source. The third argument is an integer argument specifying the + number of bytes to copy, and the fourth argument is the alignment of the + source and destination locations.</p> -<p> -The first argument is a pointer to the destination, the second is a pointer to -the source. The third argument is an integer argument -specifying the number of bytes to copy, and the fourth argument is the alignment -of the source and destination locations. -</p> - -<p> -If the call to this intrinisic has an alignment value that is not 0 or 1, then -the caller guarantees that both the source and destination pointers are aligned -to that boundary. -</p> +<p>If the call to this intrinisic has an alignment value that is not 0 or 1, + then the caller guarantees that both the source and destination pointers are + aligned to that boundary.</p> <h5>Semantics:</h5> +<p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the + source location to the destination location, which are not allowed to + overlap. It copies "len" bytes of memory over. If the argument is known to + be aligned to some boundary, this can be specified as the fourth argument, + otherwise it should be set to 0 or 1.</p> -<p> -The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the source -location to the destination location, which are not allowed to overlap. It -copies "len" bytes of memory over. If the argument is known to be aligned to -some boundary, this can be specified as the fourth argument, otherwise it should -be set to 0 or 1. -</p> </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a> @@ -5560,10 +5731,11 @@ be set to 0 or 1. <h5>Syntax:</h5> <p>This is an overloaded intrinsic. You can use llvm.memmove on any integer bit -width. Not all targets support all bit widths however.</p> + width. Not all targets support all bit widths however.</p> + <pre> declare void @llvm.memmove.i8(i8 * <dest>, i8 * <src>, - i8 <len>, i32 <align>) + i8 <len>, i32 <align>) declare void @llvm.memmove.i16(i8 * <dest>, i8 * <src>, i16 <len>, i32 <align>) declare void @llvm.memmove.i32(i8 * <dest>, i8 * <src>, @@ -5573,45 +5745,33 @@ width. Not all targets support all bit widths however.</p> </pre> <h5>Overview:</h5> +<p>The '<tt>llvm.memmove.*</tt>' intrinsics move a block of memory from the + source location to the destination location. It is similar to the + '<tt>llvm.memcpy</tt>' intrinsic but allows the two memory locations to + overlap.</p> -<p> -The '<tt>llvm.memmove.*</tt>' intrinsics move a block of memory from the source -location to the destination location. It is similar to the -'<tt>llvm.memcpy</tt>' intrinsic but allows the two memory locations to overlap. -</p> - -<p> -Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt> -intrinsics do not return a value, and takes an extra alignment argument. -</p> +<p>Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt> + intrinsics do not return a value, and takes an extra alignment argument.</p> <h5>Arguments:</h5> +<p>The first argument is a pointer to the destination, the second is a pointer + to the source. The third argument is an integer argument specifying the + number of bytes to copy, and the fourth argument is the alignment of the + source and destination locations.</p> -<p> -The first argument is a pointer to the destination, the second is a pointer to -the source. The third argument is an integer argument -specifying the number of bytes to copy, and the fourth argument is the alignment -of the source and destination locations. -</p> - -<p> -If the call to this intrinisic has an alignment value that is not 0 or 1, then -the caller guarantees that the source and destination pointers are aligned to -that boundary. -</p> +<p>If the call to this intrinisic has an alignment value that is not 0 or 1, + then the caller guarantees that the source and destination pointers are + aligned to that boundary.</p> <h5>Semantics:</h5> +<p>The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the + source location to the destination location, which may overlap. It copies + "len" bytes of memory over. If the argument is known to be aligned to some + boundary, this can be specified as the fourth argument, otherwise it should + be set to 0 or 1.</p> -<p> -The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the source -location to the destination location, which may overlap. It -copies "len" bytes of memory over. If the argument is known to be aligned to -some boundary, this can be specified as the fourth argument, otherwise it should -be set to 0 or 1. -</p> </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_memset">'<tt>llvm.memset.*</tt>' Intrinsics</a> @@ -5621,10 +5781,11 @@ be set to 0 or 1. <h5>Syntax:</h5> <p>This is an overloaded intrinsic. You can use llvm.memset on any integer bit -width. Not all targets support all bit widths however.</p> + width. Not all targets support all bit widths however.</p> + <pre> declare void @llvm.memset.i8(i8 * <dest>, i8 <val>, - i8 <len>, i32 <align>) + i8 <len>, i32 <align>) declare void @llvm.memset.i16(i8 * <dest>, i8 <val>, i16 <len>, i32 <align>) declare void @llvm.memset.i32(i8 * <dest>, i8 <val>, @@ -5634,43 +5795,30 @@ width. Not all targets support all bit widths however.</p> </pre> <h5>Overview:</h5> +<p>The '<tt>llvm.memset.*</tt>' intrinsics fill a block of memory with a + particular byte value.</p> -<p> -The '<tt>llvm.memset.*</tt>' intrinsics fill a block of memory with a particular -byte value. -</p> - -<p> -Note that, unlike the standard libc function, the <tt>llvm.memset</tt> intrinsic -does not return a value, and takes an extra alignment argument. -</p> +<p>Note that, unlike the standard libc function, the <tt>llvm.memset</tt> + intrinsic does not return a value, and takes an extra alignment argument.</p> <h5>Arguments:</h5> +<p>The first argument is a pointer to the destination to fill, the second is the + byte value to fill it with, the third argument is an integer argument + specifying the number of bytes to fill, and the fourth argument is the known + alignment of destination location.</p> -<p> -The first argument is a pointer to the destination to fill, the second is the -byte value to fill it with, the third argument is an integer -argument specifying the number of bytes to fill, and the fourth argument is the -known alignment of destination location. -</p> - -<p> -If the call to this intrinisic has an alignment value that is not 0 or 1, then -the caller guarantees that the destination pointer is aligned to that boundary. -</p> +<p>If the call to this intrinisic has an alignment value that is not 0 or 1, + then the caller guarantees that the destination pointer is aligned to that + boundary.</p> <h5>Semantics:</h5> +<p>The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting + at the destination location. If the argument is known to be aligned to some + boundary, this can be specified as the fourth argument, otherwise it should + be set to 0 or 1.</p> -<p> -The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting at -the -destination location. If the argument is known to be aligned to some boundary, -this can be specified as the fourth argument, otherwise it should be set to 0 or -1. -</p> </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a> @@ -5679,9 +5827,10 @@ this can be specified as the fourth argument, otherwise it should be set to 0 or <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.sqrt</tt> on any -floating point or vector of floating point type. Not all targets support all -types however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.sqrt</tt> on any + floating point or vector of floating point type. Not all targets support all + types however.</p> + <pre> declare float @llvm.sqrt.f32(float %Val) declare double @llvm.sqrt.f64(double %Val) @@ -5691,28 +5840,21 @@ types however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.sqrt</tt>' intrinsics return the sqrt of the specified operand, -returning the same value as the libm '<tt>sqrt</tt>' functions would. Unlike -<tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined behavior for -negative numbers other than -0.0 (which allows for better optimization, because -there is no need to worry about errno being set). <tt>llvm.sqrt(-0.0)</tt> is -defined to return -0.0 like IEEE sqrt. -</p> +<p>The '<tt>llvm.sqrt</tt>' intrinsics return the sqrt of the specified operand, + returning the same value as the libm '<tt>sqrt</tt>' functions would. + Unlike <tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined + behavior for negative numbers other than -0.0 (which allows for better + optimization, because there is no need to worry about errno being + set). <tt>llvm.sqrt(-0.0)</tt> is defined to return -0.0 like IEEE sqrt.</p> <h5>Arguments:</h5> - -<p> -The argument and return value are floating point numbers of the same type. -</p> +<p>The argument and return value are floating point numbers of the same + type.</p> <h5>Semantics:</h5> +<p>This function returns the sqrt of the specified operand if it is a + nonnegative floating point number.</p> -<p> -This function returns the sqrt of the specified operand if it is a nonnegative -floating point number. -</p> </div> <!-- _______________________________________________________________________ --> @@ -5723,9 +5865,10 @@ floating point number. <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.powi</tt> on any -floating point or vector of floating point type. Not all targets support all -types however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.powi</tt> on any + floating point or vector of floating point type. Not all targets support all + types however.</p> + <pre> declare float @llvm.powi.f32(float %Val, i32 %power) declare double @llvm.powi.f64(double %Val, i32 %power) @@ -5735,26 +5878,19 @@ types however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.powi.*</tt>' intrinsics return the first operand raised to the -specified (positive or negative) power. The order of evaluation of -multiplications is not defined. When a vector of floating point type is -used, the second argument remains a scalar integer value. -</p> +<p>The '<tt>llvm.powi.*</tt>' intrinsics return the first operand raised to the + specified (positive or negative) power. The order of evaluation of + multiplications is not defined. When a vector of floating point type is + used, the second argument remains a scalar integer value.</p> <h5>Arguments:</h5> - -<p> -The second argument is an integer power, and the first is a value to raise to -that power. -</p> +<p>The second argument is an integer power, and the first is a value to raise to + that power.</p> <h5>Semantics:</h5> +<p>This function returns the first value raised to the second power with an + unspecified sequence of rounding operations.</p> -<p> -This function returns the first value raised to the second power with an -unspecified sequence of rounding operations.</p> </div> <!-- _______________________________________________________________________ --> @@ -5765,9 +5901,10 @@ unspecified sequence of rounding operations.</p> <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.sin</tt> on any -floating point or vector of floating point type. Not all targets support all -types however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.sin</tt> on any + floating point or vector of floating point type. Not all targets support all + types however.</p> + <pre> declare float @llvm.sin.f32(float %Val) declare double @llvm.sin.f64(double %Val) @@ -5777,23 +5914,17 @@ types however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.sin.*</tt>' intrinsics return the sine of the operand. -</p> +<p>The '<tt>llvm.sin.*</tt>' intrinsics return the sine of the operand.</p> <h5>Arguments:</h5> - -<p> -The argument and return value are floating point numbers of the same type. -</p> +<p>The argument and return value are floating point numbers of the same + type.</p> <h5>Semantics:</h5> +<p>This function returns the sine of the specified operand, returning the same + values as the libm <tt>sin</tt> functions would, and handles error conditions + in the same way.</p> -<p> -This function returns the sine of the specified operand, returning the -same values as the libm <tt>sin</tt> functions would, and handles error -conditions in the same way.</p> </div> <!-- _______________________________________________________________________ --> @@ -5804,9 +5935,10 @@ conditions in the same way.</p> <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.cos</tt> on any -floating point or vector of floating point type. Not all targets support all -types however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.cos</tt> on any + floating point or vector of floating point type. Not all targets support all + types however.</p> + <pre> declare float @llvm.cos.f32(float %Val) declare double @llvm.cos.f64(double %Val) @@ -5816,23 +5948,17 @@ types however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.cos.*</tt>' intrinsics return the cosine of the operand. -</p> +<p>The '<tt>llvm.cos.*</tt>' intrinsics return the cosine of the operand.</p> <h5>Arguments:</h5> - -<p> -The argument and return value are floating point numbers of the same type. -</p> +<p>The argument and return value are floating point numbers of the same + type.</p> <h5>Semantics:</h5> +<p>This function returns the cosine of the specified operand, returning the same + values as the libm <tt>cos</tt> functions would, and handles error conditions + in the same way.</p> -<p> -This function returns the cosine of the specified operand, returning the -same values as the libm <tt>cos</tt> functions would, and handles error -conditions in the same way.</p> </div> <!-- _______________________________________________________________________ --> @@ -5843,9 +5969,10 @@ conditions in the same way.</p> <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.pow</tt> on any -floating point or vector of floating point type. Not all targets support all -types however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.pow</tt> on any + floating point or vector of floating point type. Not all targets support all + types however.</p> + <pre> declare float @llvm.pow.f32(float %Val, float %Power) declare double @llvm.pow.f64(double %Val, double %Power) @@ -5855,39 +5982,29 @@ types however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.pow.*</tt>' intrinsics return the first operand raised to the -specified (positive or negative) power. -</p> +<p>The '<tt>llvm.pow.*</tt>' intrinsics return the first operand raised to the + specified (positive or negative) power.</p> <h5>Arguments:</h5> - -<p> -The second argument is a floating point power, and the first is a value to -raise to that power. -</p> +<p>The second argument is a floating point power, and the first is a value to + raise to that power.</p> <h5>Semantics:</h5> +<p>This function returns the first value raised to the second power, returning + the same values as the libm <tt>pow</tt> functions would, and handles error + conditions in the same way.</p> -<p> -This function returns the first value raised to the second power, -returning the -same values as the libm <tt>pow</tt> functions would, and handles error -conditions in the same way.</p> </div> - <!-- ======================================================================= --> <div class="doc_subsection"> <a name="int_manip">Bit Manipulation Intrinsics</a> </div> <div class="doc_text"> -<p> -LLVM provides intrinsics for a few important bit manipulation operations. -These allow efficient code generation for some algorithms. -</p> + +<p>LLVM provides intrinsics for a few important bit manipulation operations. + These allow efficient code generation for some algorithms.</p> </div> @@ -5900,7 +6017,8 @@ These allow efficient code generation for some algorithms. <h5>Syntax:</h5> <p>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).</p> + type that is an even number of bytes (i.e. BitWidth % 16 == 0).</p> + <pre> declare i16 @llvm.bswap.i16(i16 <id>) declare i32 @llvm.bswap.i32(i32 <id>) @@ -5908,25 +6026,20 @@ type that is an even number of bytes (i.e. BitWidth % 16 == 0).</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.bswap</tt>' family of intrinsics is used to byte swap integer -values with an even number of bytes (positive multiple of 16 bits). These are -useful for performing operations on data that is not in the target's native -byte order. -</p> +<p>The '<tt>llvm.bswap</tt>' family of intrinsics is used to byte swap integer + values with an even number of bytes (positive multiple of 16 bits). These + are useful for performing operations on data that is not in the target's + native byte order.</p> <h5>Semantics:</h5> - -<p> -The <tt>llvm.bswap.i16</tt> intrinsic returns an i16 value that has the high -and low byte of the input i16 swapped. Similarly, the <tt>llvm.bswap.i32</tt> -intrinsic returns an i32 value that has the four bytes of the input i32 -swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the returned -i32 will have its bytes in 3, 2, 1, 0 order. The <tt>llvm.bswap.i48</tt>, -<tt>llvm.bswap.i64</tt> and other intrinsics extend this concept to -additional even-byte lengths (6 bytes, 8 bytes and more, respectively). -</p> +<p>The <tt>llvm.bswap.i16</tt> intrinsic returns an i16 value that has the high + and low byte of the input i16 swapped. Similarly, + the <tt>llvm.bswap.i32</tt> intrinsic returns an i32 value that has the four + bytes of the input i32 swapped, so that if the input bytes are numbered 0, 1, + 2, 3 then the returned i32 will have its bytes in 3, 2, 1, 0 order. + The <tt>llvm.bswap.i48</tt>, <tt>llvm.bswap.i64</tt> and other intrinsics + extend this concept to additional even-byte lengths (6 bytes, 8 bytes and + more, respectively).</p> </div> @@ -5939,7 +6052,8 @@ additional even-byte lengths (6 bytes, 8 bytes and more, respectively). <h5>Syntax:</h5> <p>This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit -width. Not all targets support all bit widths however.</p> + width. Not all targets support all bit widths however.</p> + <pre> declare i8 @llvm.ctpop.i8(i8 <src>) declare i16 @llvm.ctpop.i16(i16 <src>) @@ -5949,24 +6063,16 @@ width. Not all targets support all bit widths however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.ctpop</tt>' family of intrinsics counts the number of bits set in a -value. -</p> +<p>The '<tt>llvm.ctpop</tt>' family of intrinsics counts the number of bits set + in a value.</p> <h5>Arguments:</h5> - -<p> -The only argument is the value to be counted. The argument may be of any -integer type. The return type must match the argument type. -</p> +<p>The only argument is the value to be counted. The argument may be of any + integer type. The return type must match the argument type.</p> <h5>Semantics:</h5> +<p>The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable.</p> -<p> -The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable. -</p> </div> <!-- _______________________________________________________________________ --> @@ -5977,8 +6083,9 @@ The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable. <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.ctlz</tt> on any -integer bit width. Not all targets support all bit widths however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.ctlz</tt> on any + integer bit width. Not all targets support all bit widths however.</p> + <pre> declare i8 @llvm.ctlz.i8 (i8 <src>) declare i16 @llvm.ctlz.i16(i16 <src>) @@ -5988,30 +6095,20 @@ integer bit width. Not all targets support all bit widths however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.ctlz</tt>' family of intrinsic functions counts the number of -leading zeros in a variable. -</p> +<p>The '<tt>llvm.ctlz</tt>' family of intrinsic functions counts the number of + leading zeros in a variable.</p> <h5>Arguments:</h5> - -<p> -The only argument is the value to be counted. The argument may be of any -integer type. The return type must match the argument type. -</p> +<p>The only argument is the value to be counted. The argument may be of any + integer type. The return type must match the argument type.</p> <h5>Semantics:</h5> +<p>The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant) + zeros in a variable. If the src == 0 then the result is the size in bits of + the type of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>.</p> -<p> -The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant) zeros -in a variable. If the src == 0 then the result is the size in bits of the type -of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>. -</p> </div> - - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic</a> @@ -6020,8 +6117,9 @@ of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>. <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.cttz</tt> on any -integer bit width. Not all targets support all bit widths however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.cttz</tt> on any + integer bit width. Not all targets support all bit widths however.</p> + <pre> declare i8 @llvm.cttz.i8 (i8 <src>) declare i16 @llvm.cttz.i16(i16 <src>) @@ -6031,130 +6129,17 @@ integer bit width. Not all targets support all bit widths however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.cttz</tt>' family of intrinsic functions counts the number of -trailing zeros. -</p> +<p>The '<tt>llvm.cttz</tt>' family of intrinsic functions counts the number of + trailing zeros.</p> <h5>Arguments:</h5> - -<p> -The only argument is the value to be counted. The argument may be of any -integer type. The return type must match the argument type. -</p> +<p>The only argument is the value to be counted. The argument may be of any + integer type. The return type must match the argument type.</p> <h5>Semantics:</h5> - -<p> -The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant) zeros -in a variable. If the src == 0 then the result is the size in bits of the type -of src. For example, <tt>llvm.cttz(2) = 1</tt>. -</p> -</div> - -<!-- _______________________________________________________________________ --> -<div class="doc_subsubsection"> - <a name="int_part_select">'<tt>llvm.part.select.*</tt>' Intrinsic</a> -</div> - -<div class="doc_text"> - -<h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.part.select</tt> -on any integer bit width.</p> -<pre> - declare i17 @llvm.part.select.i17 (i17 %val, i32 %loBit, i32 %hiBit) - declare i29 @llvm.part.select.i29 (i29 %val, i32 %loBit, i32 %hiBit) -</pre> - -<h5>Overview:</h5> -<p>The '<tt>llvm.part.select</tt>' family of intrinsic functions selects a -range of bits from an integer value and returns them in the same bit width as -the original value.</p> - -<h5>Arguments:</h5> -<p>The first argument, <tt>%val</tt> and the result may be integer types of -any bit width but they must have the same bit width. The second and third -arguments must be <tt>i32</tt> type since they specify only a bit index.</p> - -<h5>Semantics:</h5> -<p>The operation of the '<tt>llvm.part.select</tt>' intrinsic has two modes -of operation: forwards and reverse. If <tt>%loBit</tt> is greater than -<tt>%hiBits</tt> then the intrinsic operates in reverse mode. Otherwise it -operates in forward mode.</p> -<p>In forward mode, this intrinsic is the equivalent of shifting <tt>%val</tt> -right by <tt>%loBit</tt> bits and then ANDing it with a mask with -only the <tt>%hiBit - %loBit</tt> bits set, as follows:</p> -<ol> - <li>The <tt>%val</tt> is shifted right (LSHR) by the number of bits specified - by <tt>%loBits</tt>. This normalizes the value to the low order bits.</li> - <li>The <tt>%loBits</tt> value is subtracted from the <tt>%hiBits</tt> value - to determine the number of bits to retain.</li> - <li>A mask of the retained bits is created by shifting a -1 value.</li> - <li>The mask is ANDed with <tt>%val</tt> to produce the result.</li> -</ol> -<p>In reverse mode, a similar computation is made except that the bits are -returned in the reverse order. So, for example, if <tt>X</tt> has the value -<tt>i16 0x0ACF (101011001111)</tt> and we apply -<tt>part.select(i16 X, 8, 3)</tt> to it, we get back the value -<tt>i16 0x0026 (000000100110)</tt>.</p> -</div> - -<div class="doc_subsubsection"> - <a name="int_part_set">'<tt>llvm.part.set.*</tt>' Intrinsic</a> -</div> - -<div class="doc_text"> - -<h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.part.set</tt> -on any integer bit width.</p> -<pre> - 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) -</pre> - -<h5>Overview:</h5> -<p>The '<tt>llvm.part.set</tt>' family of intrinsic functions replaces a range -of bits in an integer value with another integer value. It returns the integer -with the replaced bits.</p> - -<h5>Arguments:</h5> -<p>The first argument, <tt>%val</tt>, and the result may be integer types of -any bit width, but they must have the same bit width. <tt>%val</tt> is the value -whose bits will be replaced. The second argument, <tt>%repl</tt> may be an -integer of any bit width. The third and fourth arguments must be <tt>i32</tt> -type since they specify only a bit index.</p> - -<h5>Semantics:</h5> -<p>The operation of the '<tt>llvm.part.set</tt>' intrinsic has two modes -of operation: forwards and reverse. If <tt>%lo</tt> is greater than -<tt>%hi</tt> then the intrinsic operates in reverse mode. Otherwise it -operates in forward mode.</p> - -<p>For both modes, the <tt>%repl</tt> value is prepared for use by either -truncating it down to the size of the replacement area or zero extending it -up to that size.</p> - -<p>In forward mode, the bits between <tt>%lo</tt> and <tt>%hi</tt> (inclusive) -are replaced with corresponding bits from <tt>%repl</tt>. That is the 0th bit -in <tt>%repl</tt> replaces the <tt>%lo</tt>th bit in <tt>%val</tt> and etc. up -to the <tt>%hi</tt>th bit.</p> - -<p>In reverse mode, a similar computation is made except that the bits are -reversed. That is, the <tt>0</tt>th bit in <tt>%repl</tt> replaces the -<tt>%hi</tt> bit in <tt>%val</tt> and etc. down to the <tt>%lo</tt>th bit.</p> - -<h5>Examples:</h5> - -<pre> - llvm.part.set(0xFFFF, 0, 4, 7) -> 0xFF0F - llvm.part.set(0xFFFF, 0, 7, 4) -> 0xFF0F - llvm.part.set(0xFFFF, 1, 7, 4) -> 0xFF8F - llvm.part.set(0xFFFF, F, 8, 3) -> 0xFFE7 - llvm.part.set(0xFFFF, 0, 3, 8) -> 0xFE07 -</pre> +<p>The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant) + zeros in a variable. If the src == 0 then the result is the size in bits of + the type of src. For example, <tt>llvm.cttz(2) = 1</tt>.</p> </div> @@ -6164,9 +6149,8 @@ reversed. That is, the <tt>0</tt>th bit in <tt>%repl</tt> replaces the </div> <div class="doc_text"> -<p> -LLVM provides intrinsics for some arithmetic with overflow operations. -</p> + +<p>LLVM provides intrinsics for some arithmetic with overflow operations.</p> </div> @@ -6178,9 +6162,8 @@ LLVM provides intrinsics for some arithmetic with overflow operations. <div class="doc_text"> <h5>Syntax:</h5> - <p>This is an overloaded intrinsic. You can use <tt>llvm.sadd.with.overflow</tt> -on any integer bit width.</p> + on any integer bit width.</p> <pre> declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b) @@ -6189,24 +6172,23 @@ on any integer bit width.</p> </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform -a signed addition of the two arguments, and indicate whether an overflow -occurred during the signed summation.</p> + a signed addition of the two arguments, and indicate whether an overflow + occurred during the signed summation.</p> <h5>Arguments:</h5> - <p>The arguments (%a and %b) and the first element of the result structure may -be of integer types of any bit width, but they must have the same bit width. The -second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt> -and <tt>%b</tt> are the two values that will undergo signed addition.</p> + be of integer types of any bit width, but they must have the same bit + width. The second element of the result structure must be of + type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will + undergo signed addition.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform -a signed addition of the two variables. They return a structure — the -first element of which is the signed summation, and the second element of which -is a bit specifying if the signed summation resulted in an overflow.</p> + a signed addition of the two variables. They return a structure — the + first element of which is the signed summation, and the second element of + which is a bit specifying if the signed summation resulted in an + overflow.</p> <h5>Examples:</h5> <pre> @@ -6226,9 +6208,8 @@ is a bit specifying if the signed summation resulted in an overflow.</p> <div class="doc_text"> <h5>Syntax:</h5> - <p>This is an overloaded intrinsic. You can use <tt>llvm.uadd.with.overflow</tt> -on any integer bit width.</p> + on any integer bit width.</p> <pre> declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b) @@ -6237,24 +6218,22 @@ on any integer bit width.</p> </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform -an unsigned addition of the two arguments, and indicate whether a carry occurred -during the unsigned summation.</p> + an unsigned addition of the two arguments, and indicate whether a carry + occurred during the unsigned summation.</p> <h5>Arguments:</h5> - <p>The arguments (%a and %b) and the first element of the result structure may -be of integer types of any bit width, but they must have the same bit width. The -second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt> -and <tt>%b</tt> are the two values that will undergo unsigned addition.</p> + be of integer types of any bit width, but they must have the same bit + width. The second element of the result structure must be of + type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will + undergo unsigned addition.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform -an unsigned addition of the two arguments. They return a structure — the -first element of which is the sum, and the second element of which is a bit -specifying if the unsigned summation resulted in a carry.</p> + an unsigned addition of the two arguments. They return a structure — + the first element of which is the sum, and the second element of which is a + bit specifying if the unsigned summation resulted in a carry.</p> <h5>Examples:</h5> <pre> @@ -6274,9 +6253,8 @@ specifying if the unsigned summation resulted in a carry.</p> <div class="doc_text"> <h5>Syntax:</h5> - <p>This is an overloaded intrinsic. You can use <tt>llvm.ssub.with.overflow</tt> -on any integer bit width.</p> + on any integer bit width.</p> <pre> declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b) @@ -6285,24 +6263,23 @@ on any integer bit width.</p> </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform -a signed subtraction of the two arguments, and indicate whether an overflow -occurred during the signed subtraction.</p> + a signed subtraction of the two arguments, and indicate whether an overflow + occurred during the signed subtraction.</p> <h5>Arguments:</h5> - <p>The arguments (%a and %b) and the first element of the result structure may -be of integer types of any bit width, but they must have the same bit width. The -second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt> -and <tt>%b</tt> are the two values that will undergo signed subtraction.</p> + be of integer types of any bit width, but they must have the same bit + width. The second element of the result structure must be of + type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will + undergo signed subtraction.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform -a signed subtraction of the two arguments. They return a structure — the -first element of which is the subtraction, and the second element of which is a bit -specifying if the signed subtraction resulted in an overflow.</p> + a signed subtraction of the two arguments. They return a structure — + the first element of which is the subtraction, and the second element of + which is a bit specifying if the signed subtraction resulted in an + overflow.</p> <h5>Examples:</h5> <pre> @@ -6322,9 +6299,8 @@ specifying if the signed subtraction resulted in an overflow.</p> <div class="doc_text"> <h5>Syntax:</h5> - <p>This is an overloaded intrinsic. You can use <tt>llvm.usub.with.overflow</tt> -on any integer bit width.</p> + on any integer bit width.</p> <pre> declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b) @@ -6333,24 +6309,23 @@ on any integer bit width.</p> </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform -an unsigned subtraction of the two arguments, and indicate whether an overflow -occurred during the unsigned subtraction.</p> + an unsigned subtraction of the two arguments, and indicate whether an + overflow occurred during the unsigned subtraction.</p> <h5>Arguments:</h5> - <p>The arguments (%a and %b) and the first element of the result structure may -be of integer types of any bit width, but they must have the same bit width. The -second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt> -and <tt>%b</tt> are the two values that will undergo unsigned subtraction.</p> + be of integer types of any bit width, but they must have the same bit + width. The second element of the result structure must be of + type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will + undergo unsigned subtraction.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform -an unsigned subtraction of the two arguments. They return a structure — the -first element of which is the subtraction, and the second element of which is a bit -specifying if the unsigned subtraction resulted in an overflow.</p> + an unsigned subtraction of the two arguments. They return a structure — + the first element of which is the subtraction, and the second element of + which is a bit specifying if the unsigned subtraction resulted in an + overflow.</p> <h5>Examples:</h5> <pre> @@ -6370,9 +6345,8 @@ specifying if the unsigned subtraction resulted in an overflow.</p> <div class="doc_text"> <h5>Syntax:</h5> - <p>This is an overloaded intrinsic. You can use <tt>llvm.smul.with.overflow</tt> -on any integer bit width.</p> + on any integer bit width.</p> <pre> declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b) @@ -6383,23 +6357,22 @@ on any integer bit width.</p> <h5>Overview:</h5> <p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform -a signed multiplication of the two arguments, and indicate whether an overflow -occurred during the signed multiplication.</p> + a signed multiplication of the two arguments, and indicate whether an + overflow occurred during the signed multiplication.</p> <h5>Arguments:</h5> - <p>The arguments (%a and %b) and the first element of the result structure may -be of integer types of any bit width, but they must have the same bit width. The -second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt> -and <tt>%b</tt> are the two values that will undergo signed multiplication.</p> + be of integer types of any bit width, but they must have the same bit + width. The second element of the result structure must be of + type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will + undergo signed multiplication.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform -a signed multiplication of the two arguments. They return a structure — -the first element of which is the multiplication, and the second element of -which is a bit specifying if the signed multiplication resulted in an -overflow.</p> + a signed multiplication of the two arguments. They return a structure — + the first element of which is the multiplication, and the second element of + which is a bit specifying if the signed multiplication resulted in an + overflow.</p> <h5>Examples:</h5> <pre> @@ -6419,9 +6392,8 @@ overflow.</p> <div class="doc_text"> <h5>Syntax:</h5> - <p>This is an overloaded intrinsic. You can use <tt>llvm.umul.with.overflow</tt> -on any integer bit width.</p> + on any integer bit width.</p> <pre> declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b) @@ -6430,26 +6402,23 @@ on any integer bit width.</p> </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform -a unsigned multiplication of the two arguments, and indicate whether an overflow -occurred during the unsigned multiplication.</p> + a unsigned multiplication of the two arguments, and indicate whether an + overflow occurred during the unsigned multiplication.</p> <h5>Arguments:</h5> - <p>The arguments (%a and %b) and the first element of the result structure may -be of integer types of any bit width, but they must have the same bit width. The -second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt> -and <tt>%b</tt> are the two values that will undergo unsigned -multiplication.</p> + be of integer types of any bit width, but they must have the same bit + width. The second element of the result structure must be of + type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will + undergo unsigned multiplication.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform -an unsigned multiplication of the two arguments. They return a structure — -the first element of which is the multiplication, and the second element of -which is a bit specifying if the unsigned multiplication resulted in an -overflow.</p> + an unsigned multiplication of the two arguments. They return a structure + — the first element of which is the multiplication, and the second + element of which is a bit specifying if the unsigned multiplication resulted + in an overflow.</p> <h5>Examples:</h5> <pre> @@ -6467,14 +6436,13 @@ overflow.</p> </div> <div class="doc_text"> -<p> -The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt> prefix), -are described in the <a -href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source Level -Debugging</a> document. -</p> -</div> +<p>The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt> + prefix), are described in + the <a href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source + Level Debugging</a> document.</p> + +</div> <!-- ======================================================================= --> <div class="doc_subsection"> @@ -6482,10 +6450,12 @@ Debugging</a> document. </div> <div class="doc_text"> -<p> The LLVM exception handling intrinsics (which all start with -<tt>llvm.eh.</tt> prefix), are described in the <a -href="ExceptionHandling.html#format_common_intrinsics">LLVM Exception -Handling</a> document. </p> + +<p>The LLVM exception handling intrinsics (which all start with + <tt>llvm.eh.</tt> prefix), are described in + the <a href="ExceptionHandling.html#format_common_intrinsics">LLVM Exception + Handling</a> document.</p> + </div> <!-- ======================================================================= --> @@ -6494,70 +6464,74 @@ Handling</a> document. </p> </div> <div class="doc_text"> -<p> - This intrinsic makes it possible to excise one parameter, marked with - the <tt>nest</tt> attribute, from a function. The result is a callable - function pointer lacking the nest parameter - the caller does not need - to provide a value for it. Instead, the value to use is stored in - advance in a "trampoline", a block of memory usually allocated - on the stack, which also contains code to splice the nest value into the - argument list. This is used to implement the GCC nested function address - extension. -</p> -<p> - For example, if the function is - <tt>i32 f(i8* nest %c, i32 %x, i32 %y)</tt> then the resulting function - pointer has signature <tt>i32 (i32, i32)*</tt>. It can be created as follows:</p> + +<p>This intrinsic makes it possible to excise one parameter, marked with + the <tt>nest</tt> attribute, from a function. The result is a callable + function pointer lacking the nest parameter - the caller does not need to + provide a value for it. Instead, the value to use is stored in advance in a + "trampoline", a block of memory usually allocated on the stack, which also + contains code to splice the nest value into the argument list. This is used + to implement the GCC nested function address extension.</p> + +<p>For example, if the function is + <tt>i32 f(i8* nest %c, i32 %x, i32 %y)</tt> then the resulting function + pointer has signature <tt>i32 (i32, i32)*</tt>. It can be created as + follows:</p> + +<div class="doc_code"> <pre> %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86 %tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0 %p = call i8* @llvm.init.trampoline( i8* %tramp1, i8* bitcast (i32 (i8* nest , i32, i32)* @f to i8*), i8* %nval ) %fp = bitcast i8* %p to i32 (i32, i32)* </pre> - <p>The call <tt>%val = call i32 %fp( i32 %x, i32 %y )</tt> is then equivalent - to <tt>%val = call i32 %f( i8* %nval, i32 %x, i32 %y )</tt>.</p> +</div> + +<p>The call <tt>%val = call i32 %fp( i32 %x, i32 %y )</tt> is then equivalent + to <tt>%val = call i32 %f( i8* %nval, i32 %x, i32 %y )</tt>.</p> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> <pre> -declare i8* @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>) + declare i8* @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>) </pre> + <h5>Overview:</h5> -<p> - This fills the memory pointed to by <tt>tramp</tt> with code - and returns a function pointer suitable for executing it. -</p> +<p>This fills the memory pointed to by <tt>tramp</tt> with code and returns a + function pointer suitable for executing it.</p> + <h5>Arguments:</h5> -<p> - The <tt>llvm.init.trampoline</tt> intrinsic takes three arguments, all - pointers. The <tt>tramp</tt> argument must point to a sufficiently large - and sufficiently aligned block of memory; this memory is written to by the - intrinsic. Note that the size and the alignment are target-specific - LLVM - currently provides no portable way of determining them, so a front-end that - generates this intrinsic needs to have some target-specific knowledge. - The <tt>func</tt> argument must hold a function bitcast to an <tt>i8*</tt>. -</p> +<p>The <tt>llvm.init.trampoline</tt> intrinsic takes three arguments, all + pointers. The <tt>tramp</tt> argument must point to a sufficiently large and + sufficiently aligned block of memory; this memory is written to by the + intrinsic. Note that the size and the alignment are target-specific - LLVM + currently provides no portable way of determining them, so a front-end that + generates this intrinsic needs to have some target-specific knowledge. + The <tt>func</tt> argument must hold a function bitcast to + an <tt>i8*</tt>.</p> + <h5>Semantics:</h5> -<p> - The block of memory pointed to by <tt>tramp</tt> is filled with target - dependent code, turning it into a function. A pointer to this function is - returned, but needs to be bitcast to an - <a href="#int_trampoline">appropriate function pointer type</a> - before being called. The new function's signature is the same as that of - <tt>func</tt> with any arguments marked with the <tt>nest</tt> attribute - removed. At most one such <tt>nest</tt> argument is allowed, and it must be - of pointer type. Calling the new function is equivalent to calling - <tt>func</tt> with the same argument list, but with <tt>nval</tt> used for the - missing <tt>nest</tt> argument. If, after calling - <tt>llvm.init.trampoline</tt>, the memory pointed to by <tt>tramp</tt> is - modified, then the effect of any later call to the returned function pointer is - undefined. -</p> +<p>The block of memory pointed to by <tt>tramp</tt> is filled with target + dependent code, turning it into a function. A pointer to this function is + returned, but needs to be bitcast to an <a href="#int_trampoline">appropriate + function pointer type</a> before being called. The new function's signature + is the same as that of <tt>func</tt> with any arguments marked with + the <tt>nest</tt> attribute removed. At most one such <tt>nest</tt> argument + is allowed, and it must be of pointer type. Calling the new function is + equivalent to calling <tt>func</tt> with the same argument list, but + with <tt>nval</tt> used for the missing <tt>nest</tt> argument. If, after + calling <tt>llvm.init.trampoline</tt>, the memory pointed to + by <tt>tramp</tt> is modified, then the effect of any later call to the + returned function pointer is undefined.</p> + </div> <!-- ======================================================================= --> @@ -6566,27 +6540,25 @@ declare i8* @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <n </div> <div class="doc_text"> -<p> - These intrinsic functions expand the "universal IR" of LLVM to represent - hardware constructs for atomic operations and memory synchronization. This - provides an interface to the hardware, not an interface to the programmer. It - is aimed at a low enough level to allow any programming models or APIs - (Application Programming Interfaces) which - need atomic behaviors to map cleanly onto it. It is also modeled primarily on - hardware behavior. Just as hardware provides a "universal IR" for source - languages, it also provides a starting point for developing a "universal" - atomic operation and synchronization IR. -</p> -<p> - These do <em>not</em> form an API such as high-level threading libraries, - software transaction memory systems, atomic primitives, and intrinsic - functions as found in BSD, GNU libc, atomic_ops, APR, and other system and - application libraries. The hardware interface provided by LLVM should allow - a clean implementation of all of these APIs and parallel programming models. - No one model or paradigm should be selected above others unless the hardware - itself ubiquitously does so. -</p> +<p>These intrinsic functions expand the "universal IR" of LLVM to represent + hardware constructs for atomic operations and memory synchronization. This + provides an interface to the hardware, not an interface to the programmer. It + is aimed at a low enough level to allow any programming models or APIs + (Application Programming Interfaces) which need atomic behaviors to map + cleanly onto it. It is also modeled primarily on hardware behavior. Just as + hardware provides a "universal IR" for source languages, it also provides a + starting point for developing a "universal" atomic operation and + synchronization IR.</p> + +<p>These do <em>not</em> form an API such as high-level threading libraries, + software transaction memory systems, atomic primitives, and intrinsic + functions as found in BSD, GNU libc, atomic_ops, APR, and other system and + application libraries. The hardware interface provided by LLVM should allow + a clean implementation of all of these APIs and parallel programming models. + No one model or paradigm should be selected above others unless the hardware + itself ubiquitously does so.</p> + </div> <!-- _______________________________________________________________________ --> @@ -6596,59 +6568,56 @@ declare i8* @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <n <div class="doc_text"> <h5>Syntax:</h5> <pre> -declare void @llvm.memory.barrier( i1 <ll>, i1 <ls>, i1 <sl>, i1 <ss>, -i1 <device> ) - + declare void @llvm.memory.barrier( i1 <ll>, i1 <ls>, i1 <sl>, i1 <ss>, i1 <device> ) </pre> + <h5>Overview:</h5> -<p> - The <tt>llvm.memory.barrier</tt> intrinsic guarantees ordering between - specific pairs of memory access types. -</p> +<p>The <tt>llvm.memory.barrier</tt> intrinsic guarantees ordering between + specific pairs of memory access types.</p> + <h5>Arguments:</h5> -<p> - The <tt>llvm.memory.barrier</tt> intrinsic requires five boolean arguments. - The first four arguments enables a specific barrier as listed below. The fith - argument specifies that the barrier applies to io or device or uncached memory. +<p>The <tt>llvm.memory.barrier</tt> intrinsic requires five boolean arguments. + The first four arguments enables a specific barrier as listed below. The + fith argument specifies that the barrier applies to io or device or uncached + memory.</p> + +<ul> + <li><tt>ll</tt>: load-load barrier</li> + <li><tt>ls</tt>: load-store barrier</li> + <li><tt>sl</tt>: store-load barrier</li> + <li><tt>ss</tt>: store-store barrier</li> + <li><tt>device</tt>: barrier applies to device and uncached memory also.</li> +</ul> -</p> - <ul> - <li><tt>ll</tt>: load-load barrier</li> - <li><tt>ls</tt>: load-store barrier</li> - <li><tt>sl</tt>: store-load barrier</li> - <li><tt>ss</tt>: store-store barrier</li> - <li><tt>device</tt>: barrier applies to device and uncached memory also.</li> - </ul> <h5>Semantics:</h5> -<p> - This intrinsic causes the system to enforce some ordering constraints upon - the loads and stores of the program. This barrier does not indicate - <em>when</em> any events will occur, it only enforces an <em>order</em> in - which they occur. For any of the specified pairs of load and store operations - (f.ex. load-load, or store-load), all of the first operations preceding the - barrier will complete before any of the second operations succeeding the - barrier begin. Specifically the semantics for each pairing is as follows: -</p> - <ul> - <li><tt>ll</tt>: All loads before the barrier must complete before any load - after the barrier begins.</li> - - <li><tt>ls</tt>: All loads before the barrier must complete before any - store after the barrier begins.</li> - <li><tt>ss</tt>: All stores before the barrier must complete before any - store after the barrier begins.</li> - <li><tt>sl</tt>: All stores before the barrier must complete before any - load after the barrier begins.</li> - </ul> -<p> - These semantics are applied with a logical "and" behavior when more than one - is enabled in a single memory barrier intrinsic. -</p> -<p> - Backends may implement stronger barriers than those requested when they do not - support as fine grained a barrier as requested. Some architectures do not - need all types of barriers and on such architectures, these become noops. -</p> +<p>This intrinsic causes the system to enforce some ordering constraints upon + the loads and stores of the program. This barrier does not + indicate <em>when</em> any events will occur, it only enforces + an <em>order</em> in which they occur. For any of the specified pairs of load + and store operations (f.ex. load-load, or store-load), all of the first + operations preceding the barrier will complete before any of the second + operations succeeding the barrier begin. Specifically the semantics for each + pairing is as follows:</p> + +<ul> + <li><tt>ll</tt>: All loads before the barrier must complete before any load + after the barrier begins.</li> + <li><tt>ls</tt>: All loads before the barrier must complete before any + store after the barrier begins.</li> + <li><tt>ss</tt>: All stores before the barrier must complete before any + store after the barrier begins.</li> + <li><tt>sl</tt>: All stores before the barrier must complete before any + load after the barrier begins.</li> +</ul> + +<p>These semantics are applied with a logical "and" behavior when more than one + is enabled in a single memory barrier intrinsic.</p> + +<p>Backends may implement stronger barriers than those requested when they do + not support as fine grained a barrier as requested. Some architectures do + not need all types of barriers and on such architectures, these become + noops.</p> + <h5>Example:</h5> <pre> %ptr = malloc i32 @@ -6659,50 +6628,48 @@ i1 <device> ) <i>; guarantee the above finishes</i> store i32 8, %ptr <i>; before this begins</i> </pre> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_atomic_cmp_swap">'<tt>llvm.atomic.cmp.swap.*</tt>' Intrinsic</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<p> - This is an overloaded intrinsic. You can use <tt>llvm.atomic.cmp.swap</tt> on - any integer bit width and for different address spaces. Not all targets - support all bit widths however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.cmp.swap</tt> on + any integer bit width and for different address spaces. Not all targets + support all bit widths however.</p> <pre> -declare i8 @llvm.atomic.cmp.swap.i8.p0i8( i8* <ptr>, i8 <cmp>, i8 <val> ) -declare i16 @llvm.atomic.cmp.swap.i16.p0i16( i16* <ptr>, i16 <cmp>, i16 <val> ) -declare i32 @llvm.atomic.cmp.swap.i32.p0i32( i32* <ptr>, i32 <cmp>, i32 <val> ) -declare i64 @llvm.atomic.cmp.swap.i64.p0i64( i64* <ptr>, i64 <cmp>, i64 <val> ) - + declare i8 @llvm.atomic.cmp.swap.i8.p0i8( i8* <ptr>, i8 <cmp>, i8 <val> ) + declare i16 @llvm.atomic.cmp.swap.i16.p0i16( i16* <ptr>, i16 <cmp>, i16 <val> ) + declare i32 @llvm.atomic.cmp.swap.i32.p0i32( i32* <ptr>, i32 <cmp>, i32 <val> ) + declare i64 @llvm.atomic.cmp.swap.i64.p0i64( i64* <ptr>, i64 <cmp>, i64 <val> ) </pre> + <h5>Overview:</h5> -<p> - This loads a value in memory and compares it to a given value. If they are - equal, it stores a new value into the memory. -</p> +<p>This loads a value in memory and compares it to a given value. If they are + equal, it stores a new value into the memory.</p> + <h5>Arguments:</h5> -<p> - The <tt>llvm.atomic.cmp.swap</tt> intrinsic takes three arguments. The result as - well as both <tt>cmp</tt> and <tt>val</tt> must be integer values with the - same bit width. The <tt>ptr</tt> argument must be a pointer to a value of - this integer type. While any bit width integer may be used, targets may only - lower representations they support in hardware. +<p>The <tt>llvm.atomic.cmp.swap</tt> intrinsic takes three arguments. The result + as well as both <tt>cmp</tt> and <tt>val</tt> must be integer values with the + same bit width. The <tt>ptr</tt> argument must be a pointer to a value of + this integer type. While any bit width integer may be used, targets may only + lower representations they support in hardware.</p> -</p> <h5>Semantics:</h5> -<p> - This entire intrinsic must be executed atomically. It first loads the value - in memory pointed to by <tt>ptr</tt> and compares it with the value - <tt>cmp</tt>. If they are equal, <tt>val</tt> is stored into the memory. The - loaded value is yielded in all cases. This provides the equivalent of an - atomic compare-and-swap operation within the SSA framework. -</p> -<h5>Examples:</h5> +<p>This entire intrinsic must be executed atomically. It first loads the value + in memory pointed to by <tt>ptr</tt> and compares it with the + value <tt>cmp</tt>. If they are equal, <tt>val</tt> is stored into the + memory. The loaded value is yielded in all cases. This provides the + equivalent of an atomic compare-and-swap operation within the SSA + framework.</p> +<h5>Examples:</h5> <pre> %ptr = malloc i32 store i32 4, %ptr @@ -6720,6 +6687,7 @@ declare i64 @llvm.atomic.cmp.swap.i64.p0i64( i64* <ptr>, i64 <cmp>, %memval2 = load i32* %ptr <i>; yields {i32}:memval2 = 8</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -6729,38 +6697,33 @@ declare i64 @llvm.atomic.cmp.swap.i64.p0i64( i64* <ptr>, i64 <cmp>, <div class="doc_text"> <h5>Syntax:</h5> -<p> - This is an overloaded intrinsic. You can use <tt>llvm.atomic.swap</tt> on any - integer bit width. Not all targets support all bit widths however.</p> -<pre> -declare i8 @llvm.atomic.swap.i8.p0i8( i8* <ptr>, i8 <val> ) -declare i16 @llvm.atomic.swap.i16.p0i16( i16* <ptr>, i16 <val> ) -declare i32 @llvm.atomic.swap.i32.p0i32( i32* <ptr>, i32 <val> ) -declare i64 @llvm.atomic.swap.i64.p0i64( i64* <ptr>, i64 <val> ) +<p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.swap</tt> on any + integer bit width. Not all targets support all bit widths however.</p> +<pre> + declare i8 @llvm.atomic.swap.i8.p0i8( i8* <ptr>, i8 <val> ) + declare i16 @llvm.atomic.swap.i16.p0i16( i16* <ptr>, i16 <val> ) + declare i32 @llvm.atomic.swap.i32.p0i32( i32* <ptr>, i32 <val> ) + declare i64 @llvm.atomic.swap.i64.p0i64( i64* <ptr>, i64 <val> ) </pre> + <h5>Overview:</h5> -<p> - This intrinsic loads the value stored in memory at <tt>ptr</tt> and yields - the value from memory. It then stores the value in <tt>val</tt> in the memory - at <tt>ptr</tt>. -</p> +<p>This intrinsic loads the value stored in memory at <tt>ptr</tt> and yields + the value from memory. It then stores the value in <tt>val</tt> in the memory + at <tt>ptr</tt>.</p> + <h5>Arguments:</h5> +<p>The <tt>llvm.atomic.swap</tt> intrinsic takes two arguments. Both + the <tt>val</tt> argument and the result must be integers of the same bit + width. The first argument, <tt>ptr</tt>, must be a pointer to a value of this + integer type. The targets may only lower integer representations they + support.</p> -<p> - The <tt>llvm.atomic.swap</tt> intrinsic takes two arguments. Both the - <tt>val</tt> argument and the result must be integers of the same bit width. - The first argument, <tt>ptr</tt>, must be a pointer to a value of this - integer type. The targets may only lower integer representations they - support. -</p> <h5>Semantics:</h5> -<p> - This intrinsic loads the value pointed to by <tt>ptr</tt>, yields it, and - stores <tt>val</tt> back into <tt>ptr</tt> atomically. This provides the - equivalent of an atomic swap operation within the SSA framework. +<p>This intrinsic loads the value pointed to by <tt>ptr</tt>, yields it, and + stores <tt>val</tt> back into <tt>ptr</tt> atomically. This provides the + equivalent of an atomic swap operation within the SSA framework.</p> -</p> <h5>Examples:</h5> <pre> %ptr = malloc i32 @@ -6779,6 +6742,7 @@ declare i64 @llvm.atomic.swap.i64.p0i64( i64* <ptr>, i64 <val> ) %stored2 = icmp eq i32 %result2, 8 <i>; yields {i1}:stored2 = true</i> %memval2 = load i32* %ptr <i>; yields {i32}:memval2 = 2</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -6786,37 +6750,34 @@ declare i64 @llvm.atomic.swap.i64.p0i64( i64* <ptr>, i64 <val> ) <a name="int_atomic_load_add">'<tt>llvm.atomic.load.add.*</tt>' Intrinsic</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<p> - This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.add</tt> on any - integer bit width. Not all targets support all bit widths however.</p> -<pre> -declare i8 @llvm.atomic.load.add.i8..p0i8( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.add.i16..p0i16( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.add.i32..p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.add.i64..p0i64( i64* <ptr>, i64 <delta> ) +<p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.add</tt> on + any integer bit width. Not all targets support all bit widths however.</p> +<pre> + declare i8 @llvm.atomic.load.add.i8..p0i8( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.add.i16..p0i16( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.add.i32..p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.add.i64..p0i64( i64* <ptr>, i64 <delta> ) </pre> + <h5>Overview:</h5> -<p> - This intrinsic adds <tt>delta</tt> to the value stored in memory at - <tt>ptr</tt>. It yields the original value at <tt>ptr</tt>. -</p> +<p>This intrinsic adds <tt>delta</tt> to the value stored in memory + at <tt>ptr</tt>. It yields the original value at <tt>ptr</tt>.</p> + <h5>Arguments:</h5> -<p> +<p>The intrinsic takes two arguments, the first a pointer to an integer value + and the second an integer value. The result is also an integer value. These + integer types can have any bit width, but they must all have the same bit + width. The targets may only lower integer representations they support.</p> - The intrinsic takes two arguments, the first a pointer to an integer value - and the second an integer value. The result is also an integer value. These - integer types can have any bit width, but they must all have the same bit - width. The targets may only lower integer representations they support. -</p> <h5>Semantics:</h5> -<p> - This intrinsic does a series of operations atomically. It first loads the - value stored at <tt>ptr</tt>. It then adds <tt>delta</tt>, stores the result - to <tt>ptr</tt>. It yields the original value stored at <tt>ptr</tt>. -</p> +<p>This intrinsic does a series of operations atomically. It first loads the + value stored at <tt>ptr</tt>. It then adds <tt>delta</tt>, stores the result + to <tt>ptr</tt>. It yields the original value stored at <tt>ptr</tt>.</p> <h5>Examples:</h5> <pre> @@ -6830,6 +6791,7 @@ declare i64 @llvm.atomic.load.add.i64..p0i64( i64* <ptr>, i64 <delta> <i>; yields {i32}:result3 = 10</i> %memval1 = load i32* %ptr <i>; yields {i32}:memval1 = 15</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -6837,38 +6799,36 @@ declare i64 @llvm.atomic.load.add.i64..p0i64( i64* <ptr>, i64 <delta> <a name="int_atomic_load_sub">'<tt>llvm.atomic.load.sub.*</tt>' Intrinsic</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<p> - This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.sub</tt> on - any integer bit width and for different address spaces. Not all targets - support all bit widths however.</p> -<pre> -declare i8 @llvm.atomic.load.sub.i8.p0i32( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.sub.i16.p0i32( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.sub.i32.p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.sub.i64.p0i32( i64* <ptr>, i64 <delta> ) +<p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.sub</tt> on + any integer bit width and for different address spaces. Not all targets + support all bit widths however.</p> +<pre> + declare i8 @llvm.atomic.load.sub.i8.p0i32( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.sub.i16.p0i32( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.sub.i32.p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.sub.i64.p0i32( i64* <ptr>, i64 <delta> ) </pre> + <h5>Overview:</h5> -<p> - This intrinsic subtracts <tt>delta</tt> to the value stored in memory at - <tt>ptr</tt>. It yields the original value at <tt>ptr</tt>. -</p> +<p>This intrinsic subtracts <tt>delta</tt> to the value stored in memory at + <tt>ptr</tt>. It yields the original value at <tt>ptr</tt>.</p> + <h5>Arguments:</h5> -<p> +<p>The intrinsic takes two arguments, the first a pointer to an integer value + and the second an integer value. The result is also an integer value. These + integer types can have any bit width, but they must all have the same bit + width. The targets may only lower integer representations they support.</p> - The intrinsic takes two arguments, the first a pointer to an integer value - and the second an integer value. The result is also an integer value. These - integer types can have any bit width, but they must all have the same bit - width. The targets may only lower integer representations they support. -</p> <h5>Semantics:</h5> -<p> - This intrinsic does a series of operations atomically. It first loads the - value stored at <tt>ptr</tt>. It then subtracts <tt>delta</tt>, stores the - result to <tt>ptr</tt>. It yields the original value stored at <tt>ptr</tt>. -</p> +<p>This intrinsic does a series of operations atomically. It first loads the + value stored at <tt>ptr</tt>. It then subtracts <tt>delta</tt>, stores the + result to <tt>ptr</tt>. It yields the original value stored + at <tt>ptr</tt>.</p> <h5>Examples:</h5> <pre> @@ -6882,6 +6842,7 @@ declare i64 @llvm.atomic.load.sub.i64.p0i32( i64* <ptr>, i64 <delta> <i>; yields {i32}:result3 = 2</i> %memval1 = load i32* %ptr <i>; yields {i32}:memval1 = -3</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -6890,67 +6851,61 @@ declare i64 @llvm.atomic.load.sub.i64.p0i32( i64* <ptr>, i64 <delta> <a name="int_atomic_load_nand">'<tt>llvm.atomic.load.nand.*</tt>' Intrinsic</a><br> <a name="int_atomic_load_or">'<tt>llvm.atomic.load.or.*</tt>' Intrinsic</a><br> <a name="int_atomic_load_xor">'<tt>llvm.atomic.load.xor.*</tt>' Intrinsic</a><br> - </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<p> - These are overloaded intrinsics. You can use <tt>llvm.atomic.load_and</tt>, - <tt>llvm.atomic.load_nand</tt>, <tt>llvm.atomic.load_or</tt>, and - <tt>llvm.atomic.load_xor</tt> on any integer bit width and for different - address spaces. Not all targets support all bit widths however.</p> -<pre> -declare i8 @llvm.atomic.load.and.i8.p0i8( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.and.i16.p0i16( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.and.i32.p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.and.i64.p0i64( i64* <ptr>, i64 <delta> ) +<p>These are overloaded intrinsics. You can + use <tt>llvm.atomic.load_and</tt>, <tt>llvm.atomic.load_nand</tt>, + <tt>llvm.atomic.load_or</tt>, and <tt>llvm.atomic.load_xor</tt> on any integer + bit width and for different address spaces. Not all targets support all bit + widths however.</p> +<pre> + declare i8 @llvm.atomic.load.and.i8.p0i8( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.and.i16.p0i16( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.and.i32.p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.and.i64.p0i64( i64* <ptr>, i64 <delta> ) </pre> <pre> -declare i8 @llvm.atomic.load.or.i8.p0i8( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.or.i16.p0i16( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.or.i32.p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.or.i64.p0i64( i64* <ptr>, i64 <delta> ) - + declare i8 @llvm.atomic.load.or.i8.p0i8( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.or.i16.p0i16( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.or.i32.p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.or.i64.p0i64( i64* <ptr>, i64 <delta> ) </pre> <pre> -declare i8 @llvm.atomic.load.nand.i8.p0i32( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.nand.i16.p0i32( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.nand.i32.p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.nand.i64.p0i32( i64* <ptr>, i64 <delta> ) - + declare i8 @llvm.atomic.load.nand.i8.p0i32( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.nand.i16.p0i32( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.nand.i32.p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.nand.i64.p0i32( i64* <ptr>, i64 <delta> ) </pre> <pre> -declare i8 @llvm.atomic.load.xor.i8.p0i32( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.xor.i16.p0i32( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.xor.i32.p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.xor.i64.p0i32( i64* <ptr>, i64 <delta> ) - + declare i8 @llvm.atomic.load.xor.i8.p0i32( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.xor.i16.p0i32( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.xor.i32.p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.xor.i64.p0i32( i64* <ptr>, i64 <delta> ) </pre> + <h5>Overview:</h5> -<p> - These intrinsics bitwise the operation (and, nand, or, xor) <tt>delta</tt> to - the value stored in memory at <tt>ptr</tt>. It yields the original value - at <tt>ptr</tt>. -</p> +<p>These intrinsics bitwise the operation (and, nand, or, xor) <tt>delta</tt> to + the value stored in memory at <tt>ptr</tt>. It yields the original value + at <tt>ptr</tt>.</p> + <h5>Arguments:</h5> -<p> +<p>These intrinsics take two arguments, the first a pointer to an integer value + and the second an integer value. The result is also an integer value. These + integer types can have any bit width, but they must all have the same bit + width. The targets may only lower integer representations they support.</p> - These intrinsics take two arguments, the first a pointer to an integer value - and the second an integer value. The result is also an integer value. These - integer types can have any bit width, but they must all have the same bit - width. The targets may only lower integer representations they support. -</p> <h5>Semantics:</h5> -<p> - These intrinsics does a series of operations atomically. They first load the - value stored at <tt>ptr</tt>. They then do the bitwise operation - <tt>delta</tt>, store the result to <tt>ptr</tt>. They yield the original - value stored at <tt>ptr</tt>. -</p> +<p>These intrinsics does a series of operations atomically. They first load the + value stored at <tt>ptr</tt>. They then do the bitwise + operation <tt>delta</tt>, store the result to <tt>ptr</tt>. They yield the + original value stored at <tt>ptr</tt>.</p> <h5>Examples:</h5> <pre> @@ -6966,8 +6921,8 @@ declare i64 @llvm.atomic.load.xor.i64.p0i32( i64* <ptr>, i64 <delta> <i>; yields {i32}:result3 = FF</i> %memval1 = load i32* %ptr <i>; yields {i32}:memval1 = F0</i> </pre> -</div> +</div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> @@ -6975,68 +6930,60 @@ declare i64 @llvm.atomic.load.xor.i64.p0i32( i64* <ptr>, i64 <delta> <a name="int_atomic_load_min">'<tt>llvm.atomic.load.min.*</tt>' Intrinsic</a><br> <a name="int_atomic_load_umax">'<tt>llvm.atomic.load.umax.*</tt>' Intrinsic</a><br> <a name="int_atomic_load_umin">'<tt>llvm.atomic.load.umin.*</tt>' Intrinsic</a><br> - </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<p> - These are overloaded intrinsics. You can use <tt>llvm.atomic.load_max</tt>, - <tt>llvm.atomic.load_min</tt>, <tt>llvm.atomic.load_umax</tt>, and - <tt>llvm.atomic.load_umin</tt> on any integer bit width and for different - address spaces. Not all targets - support all bit widths however.</p> -<pre> -declare i8 @llvm.atomic.load.max.i8.p0i8( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.max.i16.p0i16( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.max.i32.p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.max.i64.p0i64( i64* <ptr>, i64 <delta> ) +<p>These are overloaded intrinsics. You can use <tt>llvm.atomic.load_max</tt>, + <tt>llvm.atomic.load_min</tt>, <tt>llvm.atomic.load_umax</tt>, and + <tt>llvm.atomic.load_umin</tt> on any integer bit width and for different + address spaces. Not all targets support all bit widths however.</p> +<pre> + declare i8 @llvm.atomic.load.max.i8.p0i8( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.max.i16.p0i16( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.max.i32.p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.max.i64.p0i64( i64* <ptr>, i64 <delta> ) </pre> <pre> -declare i8 @llvm.atomic.load.min.i8.p0i8( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.min.i16.p0i16( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.min.i32..p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.min.i64..p0i64( i64* <ptr>, i64 <delta> ) - + declare i8 @llvm.atomic.load.min.i8.p0i8( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.min.i16.p0i16( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.min.i32..p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.min.i64..p0i64( i64* <ptr>, i64 <delta> ) </pre> <pre> -declare i8 @llvm.atomic.load.umax.i8.p0i8( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.umax.i16.p0i16( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.umax.i32.p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.umax.i64.p0i64( i64* <ptr>, i64 <delta> ) - + declare i8 @llvm.atomic.load.umax.i8.p0i8( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.umax.i16.p0i16( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.umax.i32.p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.umax.i64.p0i64( i64* <ptr>, i64 <delta> ) </pre> <pre> -declare i8 @llvm.atomic.load.umin.i8..p0i8( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.umin.i16.p0i16( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.umin.i32..p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.umin.i64..p0i64( i64* <ptr>, i64 <delta> ) - + declare i8 @llvm.atomic.load.umin.i8..p0i8( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.umin.i16.p0i16( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.umin.i32..p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.umin.i64..p0i64( i64* <ptr>, i64 <delta> ) </pre> + <h5>Overview:</h5> -<p> - These intrinsics takes the signed or unsigned minimum or maximum of - <tt>delta</tt> and the value stored in memory at <tt>ptr</tt>. It yields the - original value at <tt>ptr</tt>. -</p> +<p>These intrinsics takes the signed or unsigned minimum or maximum of + <tt>delta</tt> and the value stored in memory at <tt>ptr</tt>. It yields the + original value at <tt>ptr</tt>.</p> + <h5>Arguments:</h5> -<p> +<p>These intrinsics take two arguments, the first a pointer to an integer value + and the second an integer value. The result is also an integer value. These + integer types can have any bit width, but they must all have the same bit + width. The targets may only lower integer representations they support.</p> - These intrinsics take two arguments, the first a pointer to an integer value - and the second an integer value. The result is also an integer value. These - integer types can have any bit width, but they must all have the same bit - width. The targets may only lower integer representations they support. -</p> <h5>Semantics:</h5> -<p> - These intrinsics does a series of operations atomically. They first load the - value stored at <tt>ptr</tt>. They then do the signed or unsigned min or max - <tt>delta</tt> and the value, store the result to <tt>ptr</tt>. They yield - the original value stored at <tt>ptr</tt>. -</p> +<p>These intrinsics does a series of operations atomically. They first load the + value stored at <tt>ptr</tt>. They then do the signed or unsigned min or + max <tt>delta</tt> and the value, store the result to <tt>ptr</tt>. They + yield the original value stored at <tt>ptr</tt>.</p> <h5>Examples:</h5> <pre> @@ -7052,6 +6999,134 @@ declare i64 @llvm.atomic.load.umin.i64..p0i64( i64* <ptr>, i64 <delta&g <i>; yields {i32}:result3 = 8</i> %memval1 = load i32* %ptr <i>; yields {i32}:memval1 = 30</i> </pre> + +</div> + + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="int_memorymarkers">Memory Use Markers</a> +</div> + +<div class="doc_text"> + +<p>This class of intrinsics exists to information about the lifetime of memory + objects and ranges where variables are immutable.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="int_lifetime_start">'<tt>llvm.lifetime.start</tt>' Intrinsic</a> +</div> + +<div class="doc_text"> + +<h5>Syntax:</h5> +<pre> + declare void @llvm.lifetime.start(i64 <size>, i8* nocapture <ptr>) +</pre> + +<h5>Overview:</h5> +<p>The '<tt>llvm.lifetime.start</tt>' intrinsic specifies the start of a memory + object's lifetime.</p> + +<h5>Arguments:</h5> +<p>The first argument is a constant integer representing the size of the + object, or -1 if it is variable sized. The second argument is a pointer to + the object.</p> + +<h5>Semantics:</h5> +<p>This intrinsic indicates that before this point in the code, the value of the + memory pointed to by <tt>ptr</tt> is dead. This means that it is known to + never be used and has an undefined value. A load from the pointer that is + preceded by this intrinsic can be replaced with + <tt>'<a href="#undefvalues">undef</a>'</tt>.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="int_lifetime_end">'<tt>llvm.lifetime.end</tt>' Intrinsic</a> +</div> + +<div class="doc_text"> + +<h5>Syntax:</h5> +<pre> + declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>) +</pre> + +<h5>Overview:</h5> +<p>The '<tt>llvm.lifetime.end</tt>' intrinsic specifies the end of a memory + object's lifetime.</p> + +<h5>Arguments:</h5> +<p>The first argument is a constant integer representing the size of the + object, or -1 if it is variable sized. The second argument is a pointer to + the object.</p> + +<h5>Semantics:</h5> +<p>This intrinsic indicates that after this point in the code, the value of the + memory pointed to by <tt>ptr</tt> is dead. This means that it is known to + never be used and has an undefined value. Any stores into the memory object + following this intrinsic may be removed as dead. + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="int_invariant_start">'<tt>llvm.invariant.start</tt>' Intrinsic</a> +</div> + +<div class="doc_text"> + +<h5>Syntax:</h5> +<pre> + declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>) readonly +</pre> + +<h5>Overview:</h5> +<p>The '<tt>llvm.invariant.start</tt>' intrinsic specifies that the contents of + a memory object will not change.</p> + +<h5>Arguments:</h5> +<p>The first argument is a constant integer representing the size of the + object, or -1 if it is variable sized. The second argument is a pointer to + the object.</p> + +<h5>Semantics:</h5> +<p>This intrinsic indicates that until an <tt>llvm.invariant.end</tt> that uses + the return value, the referenced memory location is constant and + unchanging.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="int_invariant_end">'<tt>llvm.invariant.end</tt>' Intrinsic</a> +</div> + +<div class="doc_text"> + +<h5>Syntax:</h5> +<pre> + declare void @llvm.invariant.end({}* <start>, i64 <size>, i8* nocapture <ptr>) +</pre> + +<h5>Overview:</h5> +<p>The '<tt>llvm.invariant.end</tt>' intrinsic specifies that the contents of + a memory object are mutable.</p> + +<h5>Arguments:</h5> +<p>The first argument is the matching <tt>llvm.invariant.start</tt> intrinsic. + The second argument is a constant integer representing the size of the + object, or -1 if it is variable sized and the third argument is a pointer + to the object.</p> + +<h5>Semantics:</h5> +<p>This intrinsic indicates that the memory is mutable again.</p> + </div> <!-- ======================================================================= --> @@ -7060,8 +7135,10 @@ declare i64 @llvm.atomic.load.umin.i64..p0i64( i64* <ptr>, i64 <delta&g </div> <div class="doc_text"> -<p> This class of intrinsics is designed to be generic and has -no specific purpose. </p> + +<p>This class of intrinsics is designed to be generic and has no specific + purpose.</p> + </div> <!-- _______________________________________________________________________ --> @@ -7077,27 +7154,19 @@ no specific purpose. </p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.var.annotation</tt>' intrinsic -</p> +<p>The '<tt>llvm.var.annotation</tt>' intrinsic.</p> <h5>Arguments:</h5> - -<p> -The first argument is a pointer to a value, the second is a pointer to a -global string, the third is a pointer to a global string which is the source -file name, and the last argument is the line number. -</p> +<p>The first argument is a pointer to a value, the second is a pointer to a + global string, the third is a pointer to a global string which is the source + file name, and the last argument is the line number.</p> <h5>Semantics:</h5> +<p>This intrinsic allows annotation of local variables 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.</p> -<p> -This intrinsic allows annotation of local variables 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. -</p> </div> <!-- _______________________________________________________________________ --> @@ -7108,9 +7177,9 @@ generation and optimization. <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use '<tt>llvm.annotation</tt>' on -any integer bit width. -</p> +<p>This is an overloaded intrinsic. You can use '<tt>llvm.annotation</tt>' on + any integer bit width.</p> + <pre> declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32 <int> ) declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32 <int> ) @@ -7120,28 +7189,20 @@ any integer bit width. </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.annotation</tt>' intrinsic. -</p> +<p>The '<tt>llvm.annotation</tt>' intrinsic.</p> <h5>Arguments:</h5> - -<p> -The first argument is an integer value (result of some expression), -the second is a pointer to a global string, the third is a pointer to a global -string which is the source file name, and the last argument is the line number. -It returns the value of the first argument. -</p> +<p>The first argument is an integer value (result of some expression), the + second is a pointer to a global string, the third is a pointer to a global + string which is the source file name, and the last argument is the line + number. It returns the value of the first argument.</p> <h5>Semantics:</h5> +<p>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.</p> -<p> -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. -</p> </div> <!-- _______________________________________________________________________ --> @@ -7157,58 +7218,50 @@ are ignored by code generation and optimization. </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.trap</tt>' intrinsic -</p> +<p>The '<tt>llvm.trap</tt>' intrinsic.</p> <h5>Arguments:</h5> - -<p> -None -</p> +<p>None.</p> <h5>Semantics:</h5> +<p>This intrinsics is lowered to the target dependent trap instruction. If the + target does not have a trap instruction, this intrinsic will be lowered to + the call of the <tt>abort()</tt> function.</p> -<p> -This intrinsics is lowered to the target dependent trap instruction. If the -target does not have a trap instruction, this intrinsic will be lowered to the -call of the abort() function. -</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_stackprotector">'<tt>llvm.stackprotector</tt>' Intrinsic</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> <pre> -declare void @llvm.stackprotector( i8* <guard>, i8** <slot> ) - + declare void @llvm.stackprotector( i8* <guard>, i8** <slot> ) </pre> + <h5>Overview:</h5> -<p> - The <tt>llvm.stackprotector</tt> intrinsic takes the <tt>guard</tt> and stores - it onto the stack at <tt>slot</tt>. The stack slot is adjusted to ensure that - it is placed on the stack before local variables. -</p> +<p>The <tt>llvm.stackprotector</tt> intrinsic takes the <tt>guard</tt> and + stores it onto the stack at <tt>slot</tt>. The stack slot is adjusted to + ensure that it is placed on the stack before local variables.</p> + <h5>Arguments:</h5> -<p> - The <tt>llvm.stackprotector</tt> intrinsic requires two pointer arguments. The - first argument is the value loaded from the stack guard - <tt>@__stack_chk_guard</tt>. The second variable is an <tt>alloca</tt> that - has enough space to hold the value of the guard. -</p> +<p>The <tt>llvm.stackprotector</tt> intrinsic requires two pointer + arguments. The first argument is the value loaded from the stack + guard <tt>@__stack_chk_guard</tt>. The second variable is an <tt>alloca</tt> + that has enough space to hold the value of the guard.</p> + <h5>Semantics:</h5> -<p> - This intrinsic causes the prologue/epilogue inserter to force the position of - the <tt>AllocaInst</tt> stack slot to be before local variables on the - stack. This is to ensure that if a local variable on the stack is overwritten, - it will destroy the value of the guard. When the function exits, the guard on - the stack is checked against the original guard. If they're different, then - the program aborts by calling the <tt>__stack_chk_fail()</tt> function. -</p> +<p>This intrinsic causes the prologue/epilogue inserter to force the position of + the <tt>AllocaInst</tt> stack slot to be before local variables on the + stack. This is to ensure that if a local variable on the stack is + overwritten, it will destroy the value of the guard. When the function exits, + the guard on the stack is checked against the original guard. If they're + different, then the program aborts by calling the <tt>__stack_chk_fail()</tt> + function.</p> + </div> <!-- *********************************************************************** --> @@ -7221,7 +7274,7 @@ declare void @llvm.stackprotector( i8* <guard>, i8** <slot> ) <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-06-20 13:26:06 +0000 (Sat, 20 Jun 2009) $ + Last modified: $Date: 2009-10-13 23:56:55 +0200 (Tue, 13 Oct 2009) $ </address> </body> diff --git a/docs/LinkTimeOptimization.html b/docs/LinkTimeOptimization.html index c9d1e19..0934b47 100644 --- a/docs/LinkTimeOptimization.html +++ b/docs/LinkTimeOptimization.html @@ -166,7 +166,7 @@ $ llvm-gcc a.o main.o -o main # <-- standard link command without any modific provided by the linker on various platform are not unique. This means, this new tool needs to support all such features and platforms in one super tool or a separate tool per platform is required. This increases - maintance cost for link time optimizer significantly, which is not + maintenance cost for link time optimizer significantly, which is not necessary. This approach also requires staying synchronized with linker developements on various platforms, which is not the main focus of the link time optimizer. Finally, this approach increases end user's build time due @@ -189,7 +189,7 @@ $ llvm-gcc a.o main.o -o main # <-- standard link command without any modific user-supplied information, such as a list of exported symbols. LLVM optimizer collects control flow information, data flow information and knows much more about program structure from the optimizer's point of view. - Our goal is to take advantage of tight intergration between the linker and + Our goal is to take advantage of tight integration between the linker and the optimizer by sharing this information during various linking phases. </p> </div> @@ -382,7 +382,7 @@ of the native object files.</p> Devang Patel and Nick Kledzik<br> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2008-12-16 04:07:49 +0100 (Tue, 16 Dec 2008) $ + Last modified: $Date: 2009-10-12 16:46:08 +0200 (Mon, 12 Oct 2009) $ </address> </body> diff --git a/docs/MakefileGuide.html b/docs/MakefileGuide.html index 39a04f7..36a4725 100644 --- a/docs/MakefileGuide.html +++ b/docs/MakefileGuide.html @@ -261,7 +261,7 @@ <!-- ======================================================================= --> <div class="doc_subsubsection"><a name="BCModules">Bitcode Modules</a></div> <div class="doc_text"> - <p>In some situations, it is desireable to build a single bitcode module from + <p>In some situations, it is desirable to build a single bitcode module from a variety of sources, instead of an archive, shared library, or bitcode library. Bitcode modules can be specified in addition to any of the other types of libraries by defining the <a href="#MODULE_NAME">MODULE_NAME</a> @@ -626,6 +626,11 @@ <dd>If set to any value, causes a bitcode library (.bc) to be built.</dd> <dt><a name="CONFIG_FILES"><tt>CONFIG_FILES</tt></a></dt> <dd>Specifies a set of configuration files to be installed.</dd> + <dt><a name="DEBUG_SYMBOLS"><tt>DEBUG_SYMBOLS</tt></a></dt> + <dd>If set to any value, causes the build to include debugging + symbols even in optimized objects, libraries and executables. This + alters the flags specified to the compilers and linkers. Debugging + isn't fun in an optimized build, but it is possible.</dd> <dt><a name="DIRS"><tt>DIRS</tt></a></dt> <dd>Specifies a set of directories, usually children of the current directory, that should also be made using the same goal. These directories @@ -1016,7 +1021,7 @@ <a href="mailto:rspencer@x10sys.com">Reid Spencer</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-06-16 23:00:42 +0000 (Tue, 16 Jun 2009) $ + Last modified: $Date: 2009-10-12 16:46:08 +0200 (Mon, 12 Oct 2009) $ </address> </body> </html> diff --git a/docs/Passes.html b/docs/Passes.html index 5406be5..48f5adf 100644 --- a/docs/Passes.html +++ b/docs/Passes.html @@ -78,7 +78,6 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! <tr><td><a href="#anders-aa">-anders-aa</a></td><td>Andersen's Interprocedural Alias Analysis</td></tr> <tr><td><a href="#basicaa">-basicaa</a></td><td>Basic Alias Analysis (default AA impl)</td></tr> <tr><td><a href="#basiccg">-basiccg</a></td><td>Basic CallGraph Construction</td></tr> -<tr><td><a href="#basicvn">-basicvn</a></td><td>Basic Value Numbering (default GVN impl)</td></tr> <tr><td><a href="#codegenprepare">-codegenprepare</a></td><td>Optimize for code generation</td></tr> <tr><td><a href="#count-aa">-count-aa</a></td><td>Count Alias Analysis Query Responses</td></tr> <tr><td><a href="#debug-aa">-debug-aa</a></td><td>AA use debugger</td></tr> @@ -90,7 +89,6 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! <tr><td><a href="#globalsmodref-aa">-globalsmodref-aa</a></td><td>Simple mod/ref analysis for globals</td></tr> <tr><td><a href="#instcount">-instcount</a></td><td>Counts the various types of Instructions</td></tr> <tr><td><a href="#intervals">-intervals</a></td><td>Interval Partition Construction</td></tr> -<tr><td><a href="#load-vn">-load-vn</a></td><td>Load Value Numbering</td></tr> <tr><td><a href="#loops">-loops</a></td><td>Natural Loop Construction</td></tr> <tr><td><a href="#memdep">-memdep</a></td><td>Memory Dependence Analysis</td></tr> <tr><td><a href="#no-aa">-no-aa</a></td><td>No Alias Analysis (always returns 'may' alias)</td></tr> @@ -125,11 +123,9 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! <tr><td><a href="#deadtypeelim">-deadtypeelim</a></td><td>Dead Type Elimination</td></tr> <tr><td><a href="#die">-die</a></td><td>Dead Instruction Elimination</td></tr> <tr><td><a href="#dse">-dse</a></td><td>Dead Store Elimination</td></tr> -<tr><td><a href="#gcse">-gcse</a></td><td>Global Common Subexpression Elimination</td></tr> <tr><td><a href="#globaldce">-globaldce</a></td><td>Dead Global Elimination</td></tr> <tr><td><a href="#globalopt">-globalopt</a></td><td>Global Variable Optimizer</td></tr> <tr><td><a href="#gvn">-gvn</a></td><td>Global Value Numbering</td></tr> -<tr><td><a href="#gvnpre">-gvnpre</a></td><td>Global Value Numbering/Partial Redundancy Elimination</td></tr> <tr><td><a href="#indmemrem">-indmemrem</a></td><td>Indirect Malloc and Free Removal</td></tr> <tr><td><a href="#indvars">-indvars</a></td><td>Canonicalize Induction Variables</td></tr> <tr><td><a href="#inline">-inline</a></td><td>Function Integration/Inlining</td></tr> @@ -161,7 +157,6 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! <tr><td><a href="#mem2reg">-mem2reg</a></td><td>Promote Memory to Register</td></tr> <tr><td><a href="#memcpyopt">-memcpyopt</a></td><td>Optimize use of memcpy and friends</td></tr> <tr><td><a href="#mergereturn">-mergereturn</a></td><td>Unify function exit nodes</td></tr> -<tr><td><a href="#predsimplify">-predsimplify</a></td><td>Predicate Simplifier</td></tr> <tr><td><a href="#prune-eh">-prune-eh</a></td><td>Remove unused exception handling info</td></tr> <tr><td><a href="#raiseallocs">-raiseallocs</a></td><td>Raise allocations from calls to instructions</td></tr> <tr><td><a href="#reassociate">-reassociate</a></td><td>Reassociate expressions</td></tr> @@ -274,6 +269,12 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! located at <code>getNode(<var>F</var>) + CallReturnPos</code>. The arguments start at <code>getNode(<var>F</var>) + CallArgPos</code>. </p> + + <p> + Please keep in mind that the current andersen's pass has many known + problems and bugs. It should be considered "research quality". + </p> + </div> <!-------------------------------------------------------------------------- --> @@ -298,25 +299,6 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! <!-------------------------------------------------------------------------- --> <div class="doc_subsection"> - <a name="basicvn">Basic Value Numbering (default Value Numbering impl)</a> -</div> -<div class="doc_text"> - <p> - This is the default implementation of the <code>ValueNumbering</code> - interface. It walks the SSA def-use chains to trivially identify - lexically identical expressions. This does not require any ahead of time - analysis, so it is a very fast default implementation. - </p> - <p> - The ValueNumbering analysis passes are mostly deprecated. They are only used - by the <a href="#gcse">Global Common Subexpression Elimination pass</a>, which - is deprecated by the <a href="#gvn">Global Value Numbering pass</a> (which - does its value numbering on its own). - </p> -</div> - -<!-------------------------------------------------------------------------- --> -<div class="doc_subsection"> <a name="codegenprepare">Optimize for code generation</a> </div> <div class="doc_text"> @@ -455,28 +437,6 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! <!-------------------------------------------------------------------------- --> <div class="doc_subsection"> - <a name="load-vn">Load Value Numbering</a> -</div> -<div class="doc_text"> - <p> - This pass value numbers load and call instructions. To do this, it finds - lexically identical load instructions, and uses alias analysis to determine - which loads are guaranteed to produce the same value. To value number call - instructions, it looks for calls to functions that do not write to memory - which do not have intervening instructions that clobber the memory that is - read from. - </p> - - <p> - This pass builds off of another value numbering pass to implement value - numbering for non-load and non-call instructions. It uses Alias Analysis so - that it can disambiguate the load instructions. The more powerful these base - analyses are, the more powerful the resultant value numbering will be. - </p> -</div> - -<!-------------------------------------------------------------------------- --> -<div class="doc_subsection"> <a name="loops">Natural Loop Construction</a> </div> <div class="doc_text"> @@ -859,23 +819,6 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! <!-------------------------------------------------------------------------- --> <div class="doc_subsection"> - <a name="gcse">Global Common Subexpression Elimination</a> -</div> -<div class="doc_text"> - <p> - This pass is designed to be a very quick global transformation that - eliminates global common subexpressions from a function. It does this by - using an existing value numbering analysis pass to identify the common - subexpressions, eliminating them when possible. - </p> - <p> - This pass is deprecated by the <a href="#gvn">Global Value Numbering pass</a> - (which does a better job with its own value numbering). - </p> -</div> - -<!-------------------------------------------------------------------------- --> -<div class="doc_subsection"> <a name="globaldce">Dead Global Elimination</a> </div> <div class="doc_text"> @@ -906,35 +849,11 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! </div> <div class="doc_text"> <p> - This pass performs global value numbering to eliminate fully redundant - instructions. It also performs simple dead load elimination. - </p> - <p> - Note that this pass does the value numbering itself, it does not use the - ValueNumbering analysis passes. + This pass performs global value numbering to eliminate fully and partially + redundant instructions. It also performs redundant load elimination. </p> </div> -<!-------------------------------------------------------------------------- --> -<div class="doc_subsection"> - <a name="gvnpre">Global Value Numbering/Partial Redundancy Elimination</a> -</div> -<div class="doc_text"> - <p> - This pass performs a hybrid of global value numbering and partial redundancy - elimination, known as GVN-PRE. It performs partial redundancy elimination on - values, rather than lexical expressions, allowing a more comprehensive view - the optimization. It replaces redundant values with uses of earlier - occurences of the same value. While this is beneficial in that it eliminates - unneeded computation, it also increases register pressure by creating large - live ranges, and should be used with caution on platforms that are very - sensitive to register pressure. - </p> - <p> - Note that this pass does the value numbering itself, it does not use the - ValueNumbering analysis passes. - </p> -</div> <!-------------------------------------------------------------------------- --> <div class="doc_subsection"> @@ -1572,28 +1491,6 @@ if (X < 3) {</pre> <!-------------------------------------------------------------------------- --> <div class="doc_subsection"> - <a name="predsimplify">Predicate Simplifier</a> -</div> -<div class="doc_text"> - <p> - Path-sensitive optimizer. In a branch where <tt>x == y</tt>, replace uses of - <tt>x</tt> with <tt>y</tt>. Permits further optimization, such as the - elimination of the unreachable call: - </p> - -<blockquote><pre ->void test(int *p, int *q) -{ - if (p != q) - return; - - if (*p != *q) - foo(); // unreachable -}</pre></blockquote> -</div> - -<!-------------------------------------------------------------------------- --> -<div class="doc_subsection"> <a name="prune-eh">Remove unused exception handling info</a> </div> <div class="doc_text"> @@ -1647,7 +1544,7 @@ if (X < 3) {</pre> <p> This file demotes all registers to memory references. It is intented to be the inverse of <a href="#mem2reg"><tt>-mem2reg</tt></a>. By converting to - <tt>load</tt> instructions, the only values live accross basic blocks are + <tt>load</tt> instructions, the only values live across basic blocks are <tt>alloca</tt> instructions and <tt>load</tt> instructions before <tt>phi</tt> nodes. It is intended that this should make CFG hacking much easier. To make later hacking easier, the entry block is split into two, such @@ -1963,7 +1860,7 @@ if (X < 3) {</pre> <a href="mailto:rspencer@x10sys.com">Reid Spencer</a><br> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2008-12-11 18:34:48 +0100 (Thu, 11 Dec 2008) $ + Last modified: $Date: 2009-10-12 16:46:08 +0200 (Mon, 12 Oct 2009) $ </address> </body> diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index b45a60b..3234554 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -29,6 +29,13 @@ <ul> <li><a href="#isa">The <tt>isa<></tt>, <tt>cast<></tt> and <tt>dyn_cast<></tt> templates</a> </li> + <li><a href="#string_apis">Passing strings (the <tt>StringRef</tt> +and <tt>Twine</tt> classes)</a> + <ul> + <li><a href="#StringRef">The <tt>StringRef</tt> class</a> </li> + <li><a href="#Twine">The <tt>Twine</tt> class</a> </li> + </ul> + </li> <li><a href="#DEBUG">The <tt>DEBUG()</tt> macro and <tt>-debug</tt> option</a> <ul> @@ -79,6 +86,10 @@ option</a></li> <li><a href="#dss_map"><map></a></li> <li><a href="#dss_othermap">Other Map-Like Container Options</a></li> </ul></li> + <li><a href="#ds_string">String-like containers</a> + <!--<ul> + todo + </ul>--></li> <li><a href="#ds_bit">BitVector-like containers</a> <ul> <li><a href="#dss_bitvector">A dense bitvector</a></li> @@ -136,6 +147,7 @@ with another <tt>Value</tt></a> </li> </a></li> <li><a href="#shutdown">Ending execution with <tt>llvm_shutdown()</tt></a></li> <li><a href="#managedstatic">Lazy initialization with <tt>ManagedStatic</tt></a></li> + <li><a href="#llvmcontext">Achieving Isolation with <tt>LLVMContext</tt></a></li> </ul> </li> @@ -424,6 +436,107 @@ are lots of examples in the LLVM source base.</p> </div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="string_apis">Passing strings (the <tt>StringRef</tt> +and <tt>Twine</tt> classes)</a> +</div> + +<div class="doc_text"> + +<p>Although LLVM generally does not do much string manipulation, we do have +several important APIs which take strings. Two important examples are the +Value class -- which has names for instructions, functions, etc. -- and the +StringMap class which is used extensively in LLVM and Clang.</p> + +<p>These are generic classes, and they need to be able to accept strings which +may have embedded null characters. Therefore, they cannot simply take +a <tt>const char *</tt>, and taking a <tt>const std::string&</tt> requires +clients to perform a heap allocation which is usually unnecessary. Instead, +many LLVM APIs use a <tt>const StringRef&</tt> or a <tt>const +Twine&</tt> for passing strings efficiently.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="StringRef">The <tt>StringRef</tt> class</a> +</div> + +<div class="doc_text"> + +<p>The <tt>StringRef</tt> data type represents a reference to a constant string +(a character array and a length) and supports the common operations available +on <tt>std:string</tt>, but does not require heap allocation.</p> + +<p>It can be implicitly constructed using a C style null-terminated string, +an <tt>std::string</tt>, or explicitly with a character pointer and length. +For example, the <tt>StringRef</tt> find function is declared as:</p> + +<div class="doc_code"> + iterator find(const StringRef &Key); +</div> + +<p>and clients can call it using any one of:</p> + +<div class="doc_code"> +<pre> + Map.find("foo"); <i>// Lookup "foo"</i> + Map.find(std::string("bar")); <i>// Lookup "bar"</i> + Map.find(StringRef("\0baz", 4)); <i>// Lookup "\0baz"</i> +</pre> +</div> + +<p>Similarly, APIs which need to return a string may return a <tt>StringRef</tt> +instance, which can be used directly or converted to an <tt>std::string</tt> +using the <tt>str</tt> member function. See +"<tt><a href="/doxygen/classllvm_1_1StringRef_8h-source.html">llvm/ADT/StringRef.h</a></tt>" +for more information.</p> + +<p>You should rarely use the <tt>StringRef</tt> class directly, because it contains +pointers to external memory it is not generally safe to store an instance of the +class (unless you know that the external storage will not be freed).</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="Twine">The <tt>Twine</tt> class</a> +</div> + +<div class="doc_text"> + +<p>The <tt>Twine</tt> class is an efficient way for APIs to accept concatenated +strings. For example, a common LLVM paradigm is to name one instruction based on +the name of another instruction with a suffix, for example:</p> + +<div class="doc_code"> +<pre> + New = CmpInst::Create(<i>...</i>, SO->getName() + ".cmp"); +</pre> +</div> + +<p>The <tt>Twine</tt> class is effectively a +lightweight <a href="http://en.wikipedia.org/wiki/Rope_(computer_science)">rope</a> +which points to temporary (stack allocated) objects. Twines can be implicitly +constructed as the result of the plus operator applied to strings (i.e., a C +strings, an <tt>std::string</tt>, or a <tt>StringRef</tt>). The twine delays the +actual concatentation of strings until it is actually required, at which point +it can be efficiently rendered directly into a character array. This avoids +unnecessary heap allocation involved in constructing the temporary results of +string concatenation. See +"<tt><a href="/doxygen/classllvm_1_1Twine_8h-source.html">llvm/ADT/Twine.h</a></tt>" +for more information.</p> + +<p>As with a <tt>StringRef</tt>, <tt>Twine</tt> objects point to external memory +and should almost never be stored or mentioned directly. They are intended +solely for use when defining a function which should be able to efficiently +accept concatenated strings.</p> + +</div> + + <!-- ======================================================================= --> <div class="doc_subsection"> <a name="DEBUG">The <tt>DEBUG()</tt> macro and <tt>-debug</tt> option</a> @@ -448,7 +561,7 @@ tool) is run with the '<tt>-debug</tt>' command line argument:</p> <div class="doc_code"> <pre> -DOUT << "I am here!\n"; +DEBUG(errs() << "I am here!\n"); </pre> </div> @@ -493,16 +606,16 @@ option as follows:</p> <div class="doc_code"> <pre> -DOUT << "No debug type\n"; #undef DEBUG_TYPE +DEBUG(errs() << "No debug type\n"); #define DEBUG_TYPE "foo" -DOUT << "'foo' debug type\n"; +DEBUG(errs() << "'foo' debug type\n"); #undef DEBUG_TYPE #define DEBUG_TYPE "bar" -DOUT << "'bar' debug type\n"; +DEBUG(errs() << "'bar' debug type\n")); #undef DEBUG_TYPE #define DEBUG_TYPE "" -DOUT << "No debug type (2)\n"; +DEBUG(errs() << "No debug type (2)\n"); </pre> </div> @@ -534,6 +647,21 @@ on when the name is specified. This allows, for example, all debug information for instruction scheduling to be enabled with <tt>-debug-type=InstrSched</tt>, even if the source lives in multiple files.</p> +<p>The <tt>DEBUG_WITH_TYPE</tt> macro is also available for situations where you +would like to set <tt>DEBUG_TYPE</tt>, but only for one specific <tt>DEBUG</tt> +statement. It takes an additional first parameter, which is the type to use. For +example, the preceding example could be written as:</p> + + +<div class="doc_code"> +<pre> +DEBUG_WITH_TYPE("", errs() << "No debug type\n"); +DEBUG_WITH_TYPE("foo", errs() << "'foo' debug type\n"); +DEBUG_WITH_TYPE("bar", errs() << "'bar' debug type\n")); +DEBUG_WITH_TYPE("", errs() << "No debug type (2)\n"); +</pre> +</div> + </div> <!-- ======================================================================= --> @@ -726,6 +854,10 @@ access the container. Based on that, you should use:</p> iteration, but do not support efficient look-up based on a key. </li> +<li>a <a href="#ds_string">string</a> container is a specialized sequential + container or reference structure that is used for character or byte + arrays.</li> + <li>a <a href="#ds_bit">bit</a> container provides an efficient way to store and perform set operations on sets of numeric id's, while automatically eliminating duplicates. Bit containers require a maximum of 1 bit for each @@ -1399,6 +1531,20 @@ always better.</p> <!-- ======================================================================= --> <div class="doc_subsection"> + <a name="ds_string">String-like containers</a> +</div> + +<div class="doc_text"> + +<p> +TODO: const char* vs stringref vs smallstring vs std::string. Describe twine, +xref to #string_apis. +</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> <a name="ds_bit">Bit storage containers (BitVector, SparseBitVector)</a> </div> @@ -1508,7 +1654,7 @@ an example that prints the name of a <tt>BasicBlock</tt> and the number of for (Function::iterator i = func->begin(), e = func->end(); i != e; ++i) // <i>Print out the name of the basic block if it has one, and then the</i> // <i>number of instructions that it contains</i> - llvm::cerr << "Basic block (name=" << i->getName() << ") has " + errs() << "Basic block (name=" << i->getName() << ") has " << i->size() << " instructions.\n"; </pre> </div> @@ -1541,14 +1687,14 @@ a <tt>BasicBlock</tt>:</p> for (BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i) // <i>The next statement works since operator<<(ostream&,...)</i> // <i>is overloaded for Instruction&</i> - llvm::cerr << *i << "\n"; + errs() << *i << "\n"; </pre> </div> <p>However, this isn't really the best way to print out the contents of a <tt>BasicBlock</tt>! Since the ostream operators are overloaded for virtually anything you'll care about, you could have just invoked the print routine on the -basic block itself: <tt>llvm::cerr << *blk << "\n";</tt>.</p> +basic block itself: <tt>errs() << *blk << "\n";</tt>.</p> </div> @@ -1574,7 +1720,7 @@ small example that shows how to dump all instructions in a function to the stand // <i>F is a pointer to a Function instance</i> for (inst_iterator I = inst_begin(F), E = inst_end(F); I != E; ++I) - llvm::cerr << *I << "\n"; + errs() << *I << "\n"; </pre> </div> @@ -1653,7 +1799,7 @@ without actually obtaining it via iteration over some structure:</p> void printNextInstruction(Instruction* inst) { BasicBlock::iterator it(inst); ++it; // <i>After this line, it refers to the instruction after *inst</i> - if (it != inst->getParent()->end()) llvm::cerr << *it << "\n"; + if (it != inst->getParent()->end()) errs() << *it << "\n"; } </pre> </div> @@ -1771,8 +1917,8 @@ Function *F = ...; for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i) if (Instruction *Inst = dyn_cast<Instruction>(*i)) { - llvm::cerr << "F is used in instruction:\n"; - llvm::cerr << *Inst << "\n"; + errs() << "F is used in instruction:\n"; + errs() << *Inst << "\n"; } </pre> </div> @@ -2257,6 +2403,50 @@ and only if you know what you're doing! </p> </div> +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="llvmcontext">Achieving Isolation with <tt>LLVMContext</tt></a> +</div> + +<div class="doc_text"> +<p> +<tt>LLVMContext</tt> is an opaque class in the LLVM API which clients can use +to operate multiple, isolated instances of LLVM concurrently within the same +address space. For instance, in a hypothetical compile-server, the compilation +of an individual translation unit is conceptually independent from all the +others, and it would be desirable to be able to compile incoming translation +units concurrently on independent server threads. Fortunately, +<tt>LLVMContext</tt> exists to enable just this kind of scenario! +</p> + +<p> +Conceptually, <tt>LLVMContext</tt> provides isolation. Every LLVM entity +(<tt>Module</tt>s, <tt>Value</tt>s, <tt>Type</tt>s, <tt>Constant</tt>s, etc.) +in LLVM's in-memory IR belongs to an <tt>LLVMContext</tt>. Entities in +different contexts <em>cannot</em> interact with each other: <tt>Module</tt>s in +different contexts cannot be linked together, <tt>Function</tt>s cannot be added +to <tt>Module</tt>s in different contexts, etc. What this means is that is is +safe to compile on multiple threads simultaneously, as long as no two threads +operate on entities within the same context. +</p> + +<p> +In practice, very few places in the API require the explicit specification of a +<tt>LLVMContext</tt>, other than the <tt>Type</tt> creation/lookup APIs. +Because every <tt>Type</tt> carries a reference to its owning context, most +other entities can determine what context they belong to by looking at their +own <tt>Type</tt>. If you are adding new entities to LLVM IR, please try to +maintain this interface design. +</p> + +<p> +For clients that do <em>not</em> require the benefits of isolation, LLVM +provides a convenience API <tt>getGlobalContext()</tt>. This returns a global, +lazily initialized <tt>LLVMContext</tt> that may be used in situations where +isolation is not a concern. +</p> +</div> + <!-- *********************************************************************** --> <div class="doc_section"> <a name="advanced">Advanced Topics</a> @@ -2793,7 +2983,7 @@ the <tt>lib/VMCore</tt> directory.</p> <dt><tt>VectorType</tt></dt> <dd>Subclass of SequentialType for vector types. A vector type is similar to an ArrayType but is distinguished because it is - a first class type wherease ArrayType is not. Vector types are used for + a first class type whereas ArrayType is not. Vector types are used for vector operations and are usually small vectors of of an integer or floating point type.</dd> <dt><tt>StructType</tt></dt> @@ -3353,7 +3543,7 @@ Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a href="#Value"><tt>Value</tt></a></p> <p>The <tt>Function</tt> class represents a single procedure in LLVM. It is -actually one of the more complex classes in the LLVM heirarchy because it must +actually one of the more complex classes in the LLVM hierarchy because it must keep track of a large amount of data. The <tt>Function</tt> class keeps track of a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, a list of formal <a href="#Argument"><tt>Argument</tt></a>s, and a @@ -3362,7 +3552,7 @@ of a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, a list of formal <p>The list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s is the most commonly used part of <tt>Function</tt> objects. The list imposes an implicit ordering of the blocks in the function, which indicate how the code will be -layed out by the backend. Additionally, the first <a +laid out by the backend. Additionally, the first <a href="#BasicBlock"><tt>BasicBlock</tt></a> is the implicit entry node for the <tt>Function</tt>. It is not legal in LLVM to explicitly branch to this initial block. There are no implicit exit nodes, and in fact there may be multiple exit @@ -3492,7 +3682,7 @@ Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a></p> -<p>Global variables are represented with the (suprise suprise) +<p>Global variables are represented with the (surprise surprise) <tt>GlobalVariable</tt> class. Like functions, <tt>GlobalVariable</tt>s are also subclasses of <a href="#GlobalValue"><tt>GlobalValue</tt></a>, and as such are always referenced by their address (global values must live in memory, so their @@ -3542,7 +3732,7 @@ never change at runtime).</p> <li><tt><a href="#Constant">Constant</a> *getInitializer()</tt> - <p>Returns the intial value for a <tt>GlobalVariable</tt>. It is not legal + <p>Returns the initial value for a <tt>GlobalVariable</tt>. It is not legal to call this method if there is no initializer.</p></li> </ul> @@ -3664,7 +3854,7 @@ arguments. An argument has a pointer to the parent Function.</p> <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a> and <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-06-17 21:12:26 +0000 (Wed, 17 Jun 2009) $ + Last modified: $Date: 2009-10-12 16:46:08 +0200 (Mon, 12 Oct 2009) $ </address> </body> diff --git a/docs/Projects.html b/docs/Projects.html index 882ce2e..582c4e2 100644 --- a/docs/Projects.html +++ b/docs/Projects.html @@ -121,8 +121,8 @@ configure script with these commands: % ./AutoRegen.sh</tt></p> </div> -<p>You must be using Autoconf version 2.59 or later and your aclocal version -should 1.9 or later.</p></li> +<p>You must be using Autoconf version 2.59 or later and your aclocal version +should be 1.9 or later.</p></li> <li>Run <tt>configure</tt> in the directory in which you want to place object code. Use the following options to tell your project where it @@ -453,7 +453,7 @@ Mailing List</a>.</p> <a href="mailto:criswell@uiuc.edu">John Criswell</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a> <br> - Last modified: $Date: 2009-01-12 22:29:24 +0100 (Mon, 12 Jan 2009) $ + Last modified: $Date: 2009-08-13 22:08:52 +0200 (Thu, 13 Aug 2009) $ </address> </body> diff --git a/docs/ReleaseNotes.html b/docs/ReleaseNotes.html index b0165b05..8707052 100644 --- a/docs/ReleaseNotes.html +++ b/docs/ReleaseNotes.html @@ -4,17 +4,17 @@ <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <link rel="stylesheet" href="llvm.css" type="text/css"> - <title>LLVM 2.5 Release Notes</title> + <title>LLVM 2.6 Release Notes</title> </head> <body> -<div class="doc_title">LLVM 2.5 Release Notes</div> +<div class="doc_title">LLVM 2.6 Release Notes</div> <ol> <li><a href="#intro">Introduction</a></li> <li><a href="#subproj">Sub-project Status Update</a></li> - <li><a href="#externalproj">External Projects Using LLVM 2.5</a></li> - <li><a href="#whatsnew">What's New in LLVM 2.5?</a></li> + <li><a href="#externalproj">External Projects Using LLVM 2.6</a></li> + <li><a href="#whatsnew">What's New in LLVM 2.6?</a></li> <li><a href="GettingStarted.html">Installation Instructions</a></li> <li><a href="#portability">Portability and Supported Platforms</a></li> <li><a href="#knownproblems">Known Problems</a></li> @@ -34,7 +34,7 @@ <div class="doc_text"> <p>This document contains the release notes for the LLVM Compiler -Infrastructure, release 2.5. Here we describe the status of LLVM, including +Infrastructure, release 2.6. Here we describe the status of LLVM, including major improvements from the previous release and significant known problems. All LLVM releases may be downloaded from the <a href="http://llvm.org/releases/">LLVM releases web site</a>.</p> @@ -51,25 +51,37 @@ current one. To see the release notes for a specific release, please see the <a href="http://llvm.org/releases/">releases page</a>.</p> </div> - -<!-- Unfinished features in 2.5: - Machine LICM - Machine Sinking - target-specific intrinsics - gold lto plugin - pre-alloc splitter, strong phi elim - <tt>llc -enable-value-prop</tt>, propagation of value info - (sign/zero ext info) from one MBB to another - debug info for optimized code - interpreter + libffi + + +<!-- +Almost dead code. + include/llvm/Analysis/LiveValues.h => Dan + lib/Transforms/IPO/MergeFunctions.cpp => consider for 2.8. + llvm/Analysis/PointerTracking.h => Edwin wants this, consider for 2.8. +--> + + +<!-- Unfinished features in 2.6: + gcc plugin. + strong phi elim + variable debug info for optimized code postalloc scheduler: anti dependence breaking, hazard recognizer? - -initial support for debug line numbers when optimization enabled, not useful in - 2.5 but will be for 2.6. - + metadata + loop dependence analysis + ELF Writer? How stable? + <li>PostRA scheduler improvements, ARM adoption (David Goodwin).</li> + 2.7 supports the GDB 7.0 jit interfaces for debug info. + 2.7 eliminates ADT/iterator.h --> <!-- for announcement email: + Logo web page. + llvm devmtg + compiler_rt + KLEE web page at klee.llvm.org + Many new papers added to /pubs/ + Mention gcc plugin. + --> <!-- *********************************************************************** --> @@ -80,12 +92,11 @@ initial support for debug line numbers when optimization enabled, not useful in <div class="doc_text"> <p> -The LLVM 2.5 distribution currently consists of code from the core LLVM -repository —which roughly includes the LLVM optimizers, code generators -and supporting tools — and the llvm-gcc repository. In addition to this -code, the LLVM Project includes other sub-projects that are in development. The -two which are the most actively developed are the <a href="#clang">Clang -Project</a> and the <a href="#vmkit">VMKit Project</a>. +The LLVM 2.6 distribution currently consists of code from the core LLVM +repository (which roughly includes the LLVM optimizers, code generators +and supporting tools), the Clang repository and the llvm-gcc repository. In +addition to this code, the LLVM Project includes other sub-projects that are in +development. Here we include updates on these subprojects. </p> </div> @@ -99,37 +110,30 @@ Project</a> and the <a href="#vmkit">VMKit Project</a>. <div class="doc_text"> <p>The <a href="http://clang.llvm.org/">Clang project</a> is an effort to build -a set of new 'LLVM native' front-end technologies for the LLVM optimizer and -code generator. While Clang is not included in the LLVM 2.5 release, it is -continuing to make major strides forward in all areas. Its C and Objective-C -parsing and code generation support is now very solid. For example, it is -capable of successfully building many real-world applications for X86-32 -and X86-64, -including the <a href="http://wiki.freebsd.org/BuildingFreeBSDWithClang">FreeBSD -kernel</a> and <a href="http://gcc.gnu.org/gcc-4.2/">gcc 4.2</a>. C++ is also -making <a href="http://clang.llvm.org/cxx_status.html">incredible progress</a>, -and work on templates has recently started. If you are -interested in fast compiles and good diagnostics, we encourage you to try it out -by <a href="http://clang.llvm.org/get_started.html">building from mainline</a> -and reporting any issues you hit to the <a +a set of new 'LLVM native' front-end technologies for the C family of languages. +LLVM 2.6 is the first release to officially include Clang, and it provides a +production quality C and Objective-C compiler. If you are interested in <a +href="http://clang.llvm.org/performance.html">fast compiles</a> and +<a href="http://clang.llvm.org/diagnostics.html">good diagnostics</a>, we +encourage you to try it out. Clang currently compiles typical Objective-C code +3x faster than GCC and compiles C code about 30% faster than GCC at -O0 -g +(which is when the most pressure is on the frontend).</p> + +<p>In addition to supporting these languages, C++ support is also <a +href="http://clang.llvm.org/cxx_status.html">well under way</a>, and mainline +Clang is able to parse the libstdc++ 4.2 headers and even codegen simple apps. +If you are interested in Clang C++ support or any other Clang feature, we +strongly encourage you to get involved on the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">Clang front-end mailing list</a>.</p> -<p>In the LLVM 2.5 time-frame, the Clang team has made many improvements:</p> +<p>In the LLVM 2.6 time-frame, the Clang team has made many improvements:</p> <ul> -<li>Clang now has a new driver, which is focused on providing a GCC-compatible - interface.</li> -<li>The X86-64 ABI is now supported, including support for the Apple - 64-bit Objective-C runtime and zero cost exception handling.</li> -<li>Precompiled header support is now implemented.</li> -<li>Objective-C support is significantly improved beyond LLVM 2.4, supporting - many features, such as Objective-C Garbage Collection.</li> -<li>Variable length arrays are now fully supported.</li> -<li>C99 designated initializers are now fully supported.</li> -<li>Clang now includes all major compiler headers, including a - redesigned <i>tgmath.h</i> and several more intrinsic headers.</li> -<li>Many many bugs are fixed and many features have been added.</li> +<li>C and Objective-C support are now considered production quality.</li> +<li>AuroraUX, FreeBSD and OpenBSD are now supported.</li> +<li>Most of Objective-C 2.0 is now supported with the GNU runtime.</li> +<li>Many many bugs are fixed and lots of features have been added.</li> </ul> </div> @@ -140,19 +144,18 @@ list</a>.</p> <div class="doc_text"> -<p>Previously announced in the last LLVM release, the Clang project also +<p>Previously announced in the 2.4 and 2.5 LLVM releases, the Clang project also includes an early stage static source code analysis tool for <a href="http://clang.llvm.org/StaticAnalysis.html">automatically finding bugs</a> -in C and Objective-C programs. The tool performs a growing set of checks to find +in C and Objective-C programs. The tool performs checks to find bugs that occur on a specific path within a program.</p> -<p>In the LLVM 2.5 time-frame there have been many significant improvements to -the analyzer's core path simulation engine and machinery for generating -path-based bug reports to end-users. Particularly noteworthy improvements -include experimental support for full field-sensitivity and reasoning about heap -objects as well as an improved value-constraints subengine that does a much -better job of reasoning about inequality relationships (e.g., <tt>x > 2</tt>) -between variables and constants. +<p>In the LLVM 2.6 time-frame, the analyzer core has undergone several important +improvements and cleanups and now includes a new <em>Checker</em> interface that +is intended to eventually serve as a basis for domain-specific checks. Further, +in addition to generating HTML files for reporting analysis results, the +analyzer can now also emit bug reports in a structured XML format that is +intended to be easily readable by other programs.</p> <p>The set of checks performed by the static analyzer continues to expand, and future plans for the tool include full source-level inter-procedural analysis @@ -170,44 +173,191 @@ this project is encouraged to get involved!</p> <div class="doc_text"> <p> The <a href="http://vmkit.llvm.org/">VMKit project</a> is an implementation of -a JVM and a CLI Virtual Machines (Microsoft .NET is an -implementation of the CLI) using the Just-In-Time compiler of LLVM.</p> +a JVM and a CLI Virtual Machine (Microsoft .NET is an +implementation of the CLI) using LLVM for static and just-in-time +compilation.</p> -<p>Following LLVM 2.5, VMKit has its second release that you can find on its -<a href="http://vmkit.llvm.org/releases/">webpage</a>. The release includes +<p> +VMKit version 0.26 builds with LLVM 2.6 and you can find it on its +<a href="http://vmkit.llvm.org/releases/">web page</a>. The release includes bug fixes, cleanup and new features. The major changes are:</p> <ul> -<li>Ahead of Time compiler: compiles .class files to llvm .bc. VMKit uses this -functionality to native compile the standard classes (e.g. java.lang.String). -Users can compile AoT .class files into dynamic libraries and run them with the -help of VMKit.</li> +<li>A new llcj tool to generate shared libraries or executables of Java + files.</li> +<li>Cooperative garbage collection. </li> +<li>Fast subtype checking (paper from Click et al [JGI'02]). </li> +<li>Implementation of a two-word header for Java objects instead of the original + three-word header. </li> +<li>Better Java specification-compliance: division by zero checks, stack + overflow checks, finalization and references support. </li> -<li>New exception model: the dwarf exception model is very slow for -exception-intensive applications, so the JVM has had a new implementation of -exceptions which check at each function call if an exception happened. There is -a low performance penalty on applications without exceptions, but it is a big -gain for exception-intensive applications. For example the jack benchmark in -Spec JVM98 is 6x faster (performance gain of 83%).</li> +</ul> +</div> -<li>User-level management of thread stacks, so that thread local data access -at runtime is fast and portable. </li> -<li>Implementation of biased locking for faster object synchronizations at -runtime.</li> +<!--=========================================================================--> +<div class="doc_subsection"> +<a name="compiler-rt">compiler-rt: Compiler Runtime Library</a> +</div> -<li>New support for OSX/X64, Linux/X64 (with the Boehm GC) and Linux/ppc32.</li> +<div class="doc_text"> +<p> +The new LLVM <a href="http://compiler-rt.llvm.org/">compiler-rt project</a> +is a simple library that provides an implementation of the low-level +target-specific hooks required by code generation and other runtime components. +For example, when compiling for a 32-bit target, converting a double to a 64-bit +unsigned integer is compiled into a runtime call to the "__fixunsdfdi" +function. The compiler-rt library provides highly optimized implementations of +this and other low-level routines (some are 3x faster than the equivalent +libgcc routines).</p> -</ul> +<p> +All of the code in the compiler-rt project is available under the standard LLVM +License, a "BSD-style" license.</p> + +</div> + +<!--=========================================================================--> +<div class="doc_subsection"> +<a name="klee">KLEE: Symbolic Execution and Automatic Test Case Generator</a> </div> +<div class="doc_text"> +<p> +The new LLVM <a href="http://klee.llvm.org/">KLEE project</a> is a symbolic +execution framework for programs in LLVM bitcode form. KLEE tries to +symbolically evaluate "all" paths through the application and records state +transitions that lead to fault states. This allows it to construct testcases +that lead to faults and can even be used to verify algorithms. For more +details, please see the <a +href="http://llvm.org/pubs/2008-12-OSDI-KLEE.html">OSDI 2008 paper</a> about +KLEE.</p> + +</div> + +<!--=========================================================================--> +<div class="doc_subsection"> +<a name="dragonegg">DragonEgg: GCC-4.5 as an LLVM frontend</a> +</div> + +<div class="doc_text"> +<p> +The goal of <a href="http://dragonegg.llvm.org/">DragonEgg</a> is to make +gcc-4.5 act like llvm-gcc without requiring any gcc modifications whatsoever. +<a href="http://dragonegg.llvm.org/">DragonEgg</a> is a shared library (llvm.so) +that is loaded by gcc at runtime. It uses the new gcc plugin architecture to +disable the GCC optimizers and code generators, and schedule the LLVM optimizers +and code generators (or direct output of LLVM IR) instead. Currently only Linux +and Darwin are supported, and only on x86-32 and x86-64. It should be easy to +add additional unix-like architectures and other processor families. In theory +it should be possible to use <a href="http://dragonegg.llvm.org/">DragonEgg</a> +with any language supported by gcc, however only C and Fortran work well for the +moment. Ada and C++ work to some extent, while Java, Obj-C and Obj-C++ are so +far entirely untested. Since gcc-4.5 has not yet been released, neither has +<a href="http://dragonegg.llvm.org/">DragonEgg</a>. To build +<a href="http://dragonegg.llvm.org/">DragonEgg</a> you will need to check out the +development versions of <a href="http://gcc.gnu.org/svn.html/"> gcc</a>, +<a href="http://llvm.org/docs/GettingStarted.html#checkout">llvm</a> and +<a href="http://dragonegg.llvm.org/">DragonEgg</a> from their respective +subversion repositories, and follow the instructions in the +<a href="http://dragonegg.llvm.org/">DragonEgg</a> README. +</p> + +</div> + + +<!--=========================================================================--> +<div class="doc_subsection"> +<a name="mc">llvm-mc: Machine Code Toolkit</a> +</div> + +<div class="doc_text"> +<p> +The LLVM Machine Code (MC) Toolkit project is a (very early) effort to build +better tools for dealing with machine code, object file formats, etc. The idea +is to be able to generate most of the target specific details of assemblers and +disassemblers from existing LLVM target .td files (with suitable enhancements), +and to build infrastructure for reading and writing common object file formats. +One of the first deliverables is to build a full assembler and integrate it into +the compiler, which is predicted to substantially reduce compile time in some +scenarios. +</p> + +<p>In the LLVM 2.6 timeframe, the MC framework has grown to the point where it +can reliably parse and pretty print (with some encoding information) a +darwin/x86 .s file successfully, and has the very early phases of a Mach-O +assembler in progress. Beyond the MC framework itself, major refactoring of the +LLVM code generator has started. The idea is to make the code generator reason +about the code it is producing in a much more semantic way, rather than a +textual way. For example, the code generator now uses MCSection objects to +represent section assignments, instead of text strings that print to .section +directives.</p> + +<p>MC is an early and ongoing project that will hopefully continue to lead to +many improvements in the code generator and build infrastructure useful for many +other situations. +</p> + +</div> + + <!-- *********************************************************************** --> <div class="doc_section"> - <a name="externalproj">External Projects Using LLVM 2.5</a> + <a name="externalproj">External Open Source Projects Using LLVM 2.6</a> </div> <!-- *********************************************************************** --> +<div class="doc_text"> + +<p>An exciting aspect of LLVM is that it is used as an enabling technology for + a lot of other language and tools projects. This section lists some of the + projects that have already been updated to work with LLVM 2.6.</p> +</div> + + +<!--=========================================================================--> +<div class="doc_subsection"> +<a name="Rubinius">Rubinius</a> +</div> + +<div class="doc_text"> +<p><a href="http://github.com/evanphx/rubinius">Rubinius</a> is an environment +for running Ruby code which strives to write as much of the core class +implementation in Ruby as possible. Combined with a bytecode interpreting VM, it +uses LLVM to optimize and compile ruby code down to machine code. Techniques +such as type feedback, method inlining, and uncommon traps are all used to +remove dynamism from ruby execution and increase performance.</p> + +<p>Since LLVM 2.5, Rubinius has made several major leaps forward, implementing +a counter based JIT, type feedback and speculative method inlining. +</p> + +</div> + +<!--=========================================================================--> +<div class="doc_subsection"> +<a name="macruby">MacRuby</a> +</div> + +<div class="doc_text"> + +<p> +<a href="http://macruby.org">MacRuby</a> is an implementation of Ruby on top of +core Mac OS X technologies, such as the Objective-C common runtime and garbage +collector and the CoreFoundation framework. It is principally developed by +Apple and aims at enabling the creation of full-fledged Mac OS X applications. +</p> + +<p> +MacRuby uses LLVM for optimization passes, JIT and AOT compilation of Ruby +expressions. It also uses zero-cost DWARF exceptions to implement Ruby exception +handling.</p> + +</div> + + <!--=========================================================================--> <div class="doc_subsection"> <a name="pure">Pure</a> @@ -224,12 +374,8 @@ built-in list and matrix support (including list and matrix comprehensions) and an easy-to-use C interface. The interpreter uses LLVM as a backend to JIT-compile Pure programs to fast native code.</p> -<p>In addition to the usual algebraic data structures, Pure also has -MATLAB-style matrices in order to support numeric computations and signal -processing in an efficient way. Pure is mainly aimed at mathematical -applications right now, but it has been designed as a general purpose language. -The dynamic interpreter environment and the C interface make it possible to use -it as a kind of functional scripting language for many application areas. +<p>Pure versions 0.31 and later have been tested and are known to work with +LLVM 2.6 (and continue to work with older LLVM releases >= 2.3 as well). </p> </div> @@ -243,11 +389,11 @@ it as a kind of functional scripting language for many application areas. <p> <a href="http://www.dsource.org/projects/ldc">LDC</a> is an implementation of the D Programming Language using the LLVM optimizer and code generator. -The LDC project works great with the LLVM 2.5 release. General improvements in +The LDC project works great with the LLVM 2.6 release. General improvements in this cycle have included new inline asm constraint handling, better debug info -support, general bugfixes, and better x86-64 support. This has allowed -some major improvements in LDC, getting us much closer to being as +support, general bug fixes and better x86-64 support. This has allowed +some major improvements in LDC, getting it much closer to being as fully featured as the original DMD compiler from DigitalMars. </p> </div> @@ -258,142 +404,160 @@ fully featured as the original DMD compiler from DigitalMars. </div> <div class="doc_text"> -<p><a href="http://code.roadsend.com/rphp">Roadsend PHP</a> (rphp) is an open +<p> +<a href="http://code.roadsend.com/rphp">Roadsend PHP</a> (rphp) is an open source implementation of the PHP programming -language that uses LLVM for its optimizer, JIT, and static compiler. This is a +language that uses LLVM for its optimizer, JIT and static compiler. This is a reimplementation of an earlier project that is now based on LLVM.</p> </div> - -<!-- *********************************************************************** --> -<div class="doc_section"> - <a name="whatsnew">What's New in LLVM 2.5?</a> +<!--=========================================================================--> +<div class="doc_subsection"> +<a name="UnladenSwallow">Unladen Swallow</a> </div> -<!-- *********************************************************************** --> <div class="doc_text"> - -<p>This release includes a huge number of bug fixes, performance tweaks, and -minor improvements. Some of the major improvements and new features are listed -in this section. -</p> +<p> +<a href="http://code.google.com/p/unladen-swallow/">Unladen Swallow</a> is a +branch of <a href="http://python.org/">Python</a> intended to be fully +compatible and significantly faster. It uses LLVM's optimization passes and JIT +compiler.</p> </div> <!--=========================================================================--> <div class="doc_subsection"> -<a name="majorfeatures">Major New Features</a> +<a name="llvm-lua">llvm-lua</a> </div> <div class="doc_text"> +<p> +<a href="http://code.google.com/p/llvm-lua/">LLVM-Lua</a> uses LLVM to add JIT +and static compiling support to the Lua VM. Lua bytecode is analyzed to +remove type checks, then LLVM is used to compile the bytecode down to machine +code.</p> +</div> -<p>LLVM 2.5 includes several major new capabilities:</p> +<!--=========================================================================--> +<div class="doc_subsection"> +<a name="icedtea">IcedTea Java Virtual Machine Implementation</a> +</div> -<ul> -<li>LLVM 2.5 includes a brand new <a -href="http://en.wikipedia.org/wiki/XCore">XCore</a> backend.</li> +<div class="doc_text"> +<p> +<a href="http://icedtea.classpath.org/wiki/Main_Page">IcedTea</a> provides a +harness to build OpenJDK using only free software build tools and to provide +replacements for the not-yet free parts of OpenJDK. One of the extensions that +IcedTea provides is a new JIT compiler named <a +href="http://icedtea.classpath.org/wiki/ZeroSharkFaq">Shark</a> which uses LLVM +to provide native code generation without introducing processor-dependent +code. +</p> +</div> -<li>llvm-gcc now generally supports the GFortran front-end, and the precompiled -release binaries now support Fortran, even on Mac OS/X.</li> -<li>CMake is now used by the <a href="GettingStartedVS.html">LLVM build process -on Windows</a>. It automatically generates Visual Studio project files (and -more) from a set of simple text files. This makes it much easier to -maintain. In time, we'd like to standardize on CMake for everything.</li> -<li>LLVM 2.5 now uses (and includes) Google Test for unit testing.</li> +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="whatsnew">What's New in LLVM 2.6?</a> +</div> +<!-- *********************************************************************** --> -<li>The LLVM native code generator now supports arbitrary precision integers. -Types like <tt>i33</tt> have long been valid in the LLVM IR, but were previously -only supported by the interpreter. Note that the C backend still does not -support these.</li> +<div class="doc_text"> -<li>LLVM 2.5 no longer uses 'bison,' so it is easier to build on Windows.</li> -</ul> +<p>This release includes a huge number of bug fixes, performance tweaks and +minor improvements. Some of the major improvements and new features are listed +in this section. +</p> </div> - <!--=========================================================================--> <div class="doc_subsection"> -<a name="llvm-gcc">llvm-gcc 4.2 Improvements</a> +<a name="majorfeatures">Major New Features</a> </div> <div class="doc_text"> -<p>LLVM fully supports the llvm-gcc 4.2 front-end, which marries the GCC -front-ends and driver with the LLVM optimizer and code generator. It currently -includes support for the C, C++, Objective-C, Ada, and Fortran front-ends.</p> +<p>LLVM 2.6 includes several major new capabilities:</p> <ul> -<li>In this release, the GCC inliner is completely disabled. Previously the GCC -inliner was used to handle always-inline functions and other cases. This caused -problems with code size growth, and it is completely disabled in this -release.</li> - -<li>llvm-gcc (and LLVM in general) now support code generation for stack -canaries, which is an effective form of <a -href="http://en.wikipedia.org/wiki/Stack-smashing_protection">buffer overflow -protection</a>. llvm-gcc supports this with the <tt>-fstack-protector</tt> -command line option (just like GCC). In LLVM IR, you can request code -generation for stack canaries with function attributes. -</li> +<li>New <a href="#compiler-rt">compiler-rt</a>, <A href="#klee">KLEE</a> + and <a href="#mc">machine code toolkit</a> sub-projects.</li> +<li>Debug information now includes line numbers when optimizations are enabled. + This allows statistical sampling tools like OProfile and Shark to map + samples back to source lines.</li> +<li>LLVM now includes new experimental backends to support the MSP430, SystemZ + and BlackFin architectures.</li> +<li>LLVM supports a new <a href="GoldPlugin.html">Gold Linker Plugin</a> which + enables support for <a href="LinkTimeOptimization.html">transparent + link-time optimization</a> on ELF targets when used with the Gold binutils + linker.</li> +<li>LLVM now supports doing optimization and code generation on multiple + threads. Please see the <a href="ProgrammersManual.html#threading">LLVM + Programmer's Manual</a> for more information.</li> +<li>LLVM now has experimental support for <a + href="http://nondot.org/~sabre/LLVMNotes/EmbeddedMetadata.txt">embedded + metadata</a> in LLVM IR, though the implementation is not guaranteed to be + final and the .bc file format may change in future releases. Debug info + does not yet use this format in LLVM 2.6.</li> </ul> </div> - <!--=========================================================================--> <div class="doc_subsection"> <a name="coreimprovements">LLVM IR and Core Improvements</a> </div> <div class="doc_text"> -<p>LLVM IR has several new features that are used by our existing front-ends and -can be useful if you are writing a front-end for LLVM:</p> +<p>LLVM IR has several new features for better support of new targets and that +expose new optimization opportunities:</p> <ul> -<li>The <a href="LangRef.html#i_shufflevector">shufflevector</a> instruction -has been generalized to allow different shuffle mask width than its input -vectors. This allows you to use shufflevector to combine two -"<4 x float>" vectors into a "<8 x float>" for example.</li> - -<li>LLVM IR now supports new intrinsics for computing and acting on <a -href="LangRef.html#int_overflow">overflow of integer operations</a>. This allows -efficient code generation for languages that must trap or throw an exception on -overflow. While these intrinsics work on all targets, they only generate -efficient code on X86 so far.</li> - -<li>LLVM IR now supports a new <a href="LangRef.html#linkage">private -linkage</a> type to produce labels that are stripped by the assembler before it -produces a .o file (thus they are invisible to the linker).</li> - -<li>LLVM IR supports two new attributes for better alias analysis. The <a -href="LangRef.html#paramattrs">noalias</a> attribute can now be used on the -return value of a function to indicate that it returns new memory (e.g. -'malloc', 'calloc', etc). -The new <a href="LangRef.html#paramattrs">nocapture</a> attribute can be used -on pointer arguments to indicate that the function does not return the pointer, -store it in an object that outlives the call, or let the value of the pointer -escape from the function in any other way. -Note that it is the pointer itself that must not escape, not the value it -points to: loading a value out of the pointer is perfectly fine. -Many standard library functions (e.g. 'strlen', 'memcpy') have this property. -<!-- The simplifylibcalls pass applies these attributes to standard libc functions. --> -</li> - -<li>The parser for ".ll" files in lib/AsmParser is now completely rewritten as a -recursive descent parser. This parser produces better error messages (including -caret diagnostics), is less fragile (less likely to crash on strange things), -does not leak memory, is more efficient, and eliminates LLVM's last use of the -'bison' tool.</li> - -<li>Debug information representation and manipulation internals have been - consolidated to use a new set of classes in - <tt>llvm/Analysis/DebugInfo.h</tt>. These routines are more - efficient, robust, and extensible and replace the older mechanisms. - llvm-gcc, clang, and the code generator now use them to create and process - debug information.</li> - +<li>The <a href="LangRef.html#i_add">add</a>, <a + href="LangRef.html#i_sub">sub</a> and <a href="LangRef.html#i_mul">mul</a> + instructions have been split into integer and floating point versions (like + divide and remainder), introducing new <a + href="LangRef.html#i_fadd">fadd</a>, <a href="LangRef.html#i_fsub">fsub</a>, + and <a href="LangRef.html#i_fmul">fmul</a> instructions.</li> +<li>The <a href="LangRef.html#i_add">add</a>, <a + href="LangRef.html#i_sub">sub</a> and <a href="LangRef.html#i_mul">mul</a> + instructions now support optional "nsw" and "nuw" bits which indicate that + the operation is guaranteed to not overflow (in the signed or + unsigned case, respectively). This gives the optimizer more information and + can be used for things like C signed integer values, which are undefined on + overflow.</li> +<li>The <a href="LangRef.html#i_sdiv">sdiv</a> instruction now supports an + optional "exact" flag which indicates that the result of the division is + guaranteed to have a remainder of zero. This is useful for optimizing pointer + subtraction in C.</li> +<li>The <a href="LangRef.html#i_getelementptr">getelementptr</a> instruction now + supports arbitrary integer index values for array/pointer indices. This + allows for better code generation on 16-bit pointer targets like PIC16.</li> +<li>The <a href="LangRef.html#i_getelementptr">getelementptr</a> instruction now + supports an "inbounds" optimization hint that tells the optimizer that the + pointer is guaranteed to be within its allocated object.</li> +<li>LLVM now support a series of new linkage types for global values which allow + for better optimization and new capabilities: + <ul> + <li><a href="LangRef.html#linkage_linkonce">linkonce_odr</a> and + <a href="LangRef.html#linkage_weak">weak_odr</a> have the same linkage + semantics as the non-"odr" linkage types. The difference is that these + linkage types indicate that all definitions of the specified function + are guaranteed to have the same semantics. This allows inlining + templates functions in C++ but not inlining weak functions in C, + which previously both got the same linkage type.</li> + <li><a href="LangRef.html#linkage_available_externally">available_externally + </a> is a new linkage type that gives the optimizer visibility into the + definition of a function (allowing inlining and side effect analysis) + but that does not cause code to be generated. This allows better + optimization of "GNU inline" functions, extern templates, etc.</li> + <li><a href="LangRef.html#linkage_linker_private">linker_private</a> is a + new linkage type (which is only useful on Mac OS X) that is used for + some metadata generation and other obscure things.</li> + </ul></li> +<li>Finally, target-specific intrinsics can now return multiple values, which + is useful for modeling target operations with multiple results.</li> </ul> </div> @@ -405,27 +569,53 @@ does not leak memory, is more efficient, and eliminates LLVM's last use of the <div class="doc_text"> -<p>In addition to a large array of bug fixes and minor performance tweaks, this +<p>In addition to a large array of minor performance tweaks and bug fixes, this release includes a few major enhancements and additions to the optimizers:</p> <ul> -<li>The loop optimizer now improves floating point induction variables in -several ways, including adding shadow induction variables to avoid -"integer <-> floating point" conversions in loops when safe.</li> +<li>The <a href="Passes.html#scalarrepl">Scalar Replacement of Aggregates</a> + pass has many improvements that allow it to better promote vector unions, + variables which are memset, and much more strange code that can happen to + do bitfield accesses to register operations. An interesting change is that + it now produces "unusual" integer sizes (like i1704) in some cases and lets + other optimizers clean things up.</li> +<li>The <a href="Passes.html#loop-reduce">Loop Strength Reduction</a> pass now + promotes small integer induction variables to 64-bit on 64-bit targets, + which provides a major performance boost for much numerical code. It also + promotes shorts to int on 32-bit hosts, etc. LSR now also analyzes pointer + expressions (e.g. getelementptrs), as well as integers.</li> +<li>The <a href="Passes.html#gvn">GVN</a> pass now eliminates partial + redundancies of loads in simple cases.</li> +<li>The <a href="Passes.html#inline">Inliner</a> now reuses stack space when + inlining similar arrays from multiple callees into one caller.</li> +<li>LLVM includes a new experimental Static Single Information (SSI) + construction pass.</li> -<li>The "-mem2reg" pass is now much faster on code with large basic blocks.</li> +</ul> + +</div> -<li>The "-jump-threading" pass is more powerful: it is iterative - and handles threading based on values with fully and partially redundant - loads.</li> -<li>The "-memdep" memory dependence analysis pass (used by GVN and memcpyopt) is - both faster and more aggressive.</li> +<!--=========================================================================--> +<div class="doc_subsection"> +<a name="executionengine">Interpreter and JIT Improvements</a> +</div> -<li>The "-scalarrepl" scalar replacement of aggregates pass is more aggressive - about promoting unions to registers.</li> +<div class="doc_text"> +<ul> +<li>LLVM has a new "EngineBuilder" class which makes it more obvious how to + set up and configure an ExecutionEngine (a JIT or interpreter).</li> +<li>The JIT now supports generating more than 16M of code.</li> +<li>When configured with <tt>--with-oprofile</tt>, the JIT can now inform + OProfile about JIT'd code, allowing OProfile to get line number and function + name information for JIT'd functions.</li> +<li>When "libffi" is available, the LLVM interpreter now uses it, which supports + calling almost arbitrary external (natively compiled) functions.</li> +<li>Clients of the JIT can now register a 'JITEventListener' object to receive + callbacks when the JIT emits or frees machine code. The OProfile support + uses this mechanism.</li> </ul> </div> @@ -442,33 +632,55 @@ infrastructure, which allows us to implement more aggressive algorithms and make it run faster:</p> <ul> -<li>The <a href="WritingAnLLVMBackend.html">Writing an LLVM Compiler -Backend</a> document has been greatly expanded and is substantially more -complete.</li> - -<li>The SelectionDAG type legalization logic has been completely rewritten, is -now more powerful (it supports arbitrary precision integer types for example), -and is more correct in several corner cases. The type legalizer converts -operations on types that are not natively supported by the target machine into -equivalent code sequences that only use natively supported types. The old type -legalizer is still available (for now) and will be used if -<tt>-disable-legalize-types</tt> is passed to the code generator. -</li> -<li>The code generator now supports widening illegal vectors to larger legal -ones (for example, converting operations on <3 x float> to work on -<4 x float>) which is very important for common graphics -applications.</li> - -<li>The assembly printers for each target are now split out into their own -libraries that are separate from the main code generation logic. This reduces -the code size of JIT compilers by not requiring them to be linked in.</li> - -<li>The 'fast' instruction selection path (used at -O0 and for fast JIT - compilers) now supports accelerating codegen for code that uses exception - handling constructs.</li> - -<li>The optional PBQP register allocator now supports register coalescing.</li> +<li>The <tt>llc -asm-verbose</tt> option (exposed from llvm-gcc as <tt>-dA</tt> + and clang as <tt>-fverbose-asm</tt> or <tt>-dA</tt>) now adds a lot of + useful information in comments to + the generated .s file. This information includes location information (if + built with <tt>-g</tt>) and loop nest information.</li> +<li>The code generator now supports a new MachineVerifier pass which is useful + for finding bugs in targets and codegen passes.</li> +<li>The Machine LICM is now enabled by default. It hoists instructions out of + loops (such as constant pool loads, loads from read-only stubs, vector + constant synthesization code, etc.) and is currently configured to only do + so when the hoisted operation can be rematerialized.</li> +<li>The Machine Sinking pass is now enabled by default. This pass moves + side-effect free operations down the CFG so that they are executed on fewer + paths through a function.</li> +<li>The code generator now performs "stack slot coloring" of register spills, + which allows spill slots to be reused. This leads to smaller stack frames + in cases where there are lots of register spills.</li> +<li>The register allocator has many improvements to take better advantage of + commutable operations, various spiller peephole optimizations, and can now + coalesce cross-register-class copies.</li> +<li>Tblgen now supports multiclass inheritance and a number of new string and + list operations like <tt>!(subst)</tt>, <tt>!(foreach)</tt>, <tt>!car</tt>, + <tt>!cdr</tt>, <tt>!null</tt>, <tt>!if</tt>, <tt>!cast</tt>. + These make the .td files more expressive and allow more aggressive factoring + of duplication across instruction patterns.</li> +<li>Target-specific intrinsics can now be added without having to hack VMCore to + add them. This makes it easier to maintain out-of-tree targets.</li> +<li>The instruction selector is better at propagating information about values + (such as whether they are sign/zero extended etc.) across basic block + boundaries.</li> +<li>The SelectionDAG datastructure has new nodes for representing buildvector + and <a href="http://llvm.org/PR2957">vector shuffle</a> operations. This + makes operations and pattern matching more efficient and easier to get + right.</li> +<li>The Prolog/Epilog Insertion Pass now has experimental support for performing + the "shrink wrapping" optimization, which moves spills and reloads around in + the CFG to avoid doing saves on paths that don't need them.</li> +<li>LLVM includes new experimental support for writing ELF .o files directly + from the compiler. It works well for many simple C testcases, but doesn't + support exception handling, debug info, inline assembly, etc.</li> +<li>Targets can now specify register allocation hints through + <tt>MachineRegisterInfo::setRegAllocationHint</tt>. A regalloc hint consists + of hint type and physical register number. A hint type of zero specifies a + register allocation preference. Other hint type values are target specific + which are resolved by <tt>TargetRegisterInfo::ResolveRegAllocHint</tt>. An + example is the ARM target which uses register hints to request that the + register allocator provide an even / odd register pair to two virtual + registers.</li> </ul> </div> @@ -482,37 +694,33 @@ the code size of JIT compilers by not requiring them to be linked in.</li> </p> <ul> -<li>The <tt><a href="LangRef.html#int_returnaddress">llvm.returnaddress</a></tt> -intrinsic (which is used to implement <tt>__builtin_return_address</tt>) now -supports non-zero stack depths on X86.</li> - -<li>The X86 backend now supports code generation of vector shift operations -using SSE instructions.</li> - -<li>X86-64 code generation now takes advantage of red zone, unless the -<tt>-mno-red-zone</tt> option is specified.</li> - -<li>The X86 backend now supports using address space #256 in LLVM IR as a way of -performing memory references off the GS segment register. This allows a -front-end to take advantage of very low-level programming techniques when -targeting X86 CPUs. See <tt>test/CodeGen/X86/movgs.ll</tt> for a simple -example.</li> - -<li>The X86 backend now supports a <tt>-disable-mmx</tt> command line option to - prevent use of MMX even on chips that support it. This is important for cases - where code does not contain the proper <tt>llvm.x86.mmx.emms</tt> - intrinsics.</li> - -<li>The X86 JIT now detects the new Intel <a - href="http://en.wikipedia.org/wiki/Intel_Core_i7">Core i7</a> and <a - href="http://en.wikipedia.org/wiki/Intel_Atom">Atom</a> chips and - auto-configures itself appropriately for the features of these chips.</li> - -<li>The JIT now supports exception handling constructs on Linux/X86-64 and - Darwin/x86-64.</li> -<li>The JIT supports Thread Local Storage (TLS) on Linux/X86-32 but not yet on - X86-64.</li> +<li>SSE 4.2 builtins are now supported.</li> +<li>GCC-compatible soft float modes are now supported, which are typically used + by OS kernels.</li> +<li>X86-64 now models implicit zero extensions better, which allows the code + generator to remove a lot of redundant zexts. It also models the 8-bit "H" + registers as subregs, which allows them to be used in some tricky + situations.</li> +<li>X86-64 now supports the "local exec" and "initial exec" thread local storage + model.</li> +<li>The vector forms of the <a href="LangRef.html#i_icmp">icmp</a> and <a + href="LangRef.html#i_fcmp">fcmp</a> instructions now select to efficient + SSE operations.</li> +<li>Support for the win64 calling conventions have improved. The primary + missing feature is support for varargs function definitions. It seems to + work well for many win64 JIT purposes.</li> +<li>The X86 backend has preliminary support for <a + href="CodeGenerator.html#x86_memory">mapping address spaces to segment + register references</a>. This allows you to write GS or FS relative memory + accesses directly in LLVM IR for cases where you know exactly what you're + doing (such as in an OS kernel). There are some known problems with this + support, but it works in simple cases.</li> +<li>The X86 code generator has been refactored to move all global variable + reference logic to one place + (<tt>X86Subtarget::ClassifyGlobalReference</tt>) which + makes it easier to reason about.</li> + </ul> </div> @@ -527,70 +735,156 @@ example.</li> </p> <ul> -<li>Both direct and indirect load/stores work now.</li> -<li>Logical, bitwise and conditional operations now work for integer data -types.</li> -<li>Function calls involving basic types work now.</li> -<li>Support for integer arrays.</li> -<li>The compiler can now emit libcalls for operations not supported by m/c -instructions.</li> -<li>Support for both data and ROM address spaces.</li> +<li>Support for floating-point, indirect function calls, and + passing/returning aggregate types to functions. +<li>The code generator is able to generate debug info into output COFF files. +<li>Support for placing an object into a specific section or at a specific + address in memory.</li> </ul> <p>Things not yet supported:</p> <ul> -<li>Floating point.</li> -<li>Passing/returning aggregate types to and from functions.</li> <li>Variable arguments.</li> -<li>Indirect function calls.</li> <li>Interrupts/programs.</li> -<li>Debug info.</li> </ul> </div> +<!--=========================================================================--> +<div class="doc_subsection"> +<a name="ARM">ARM Target Improvements</a> +</div> + +<div class="doc_text"> +<p>New features of the ARM target include: +</p> + +<ul> + +<li>Preliminary support for processors, such as the Cortex-A8 and Cortex-A9, +that implement version v7-A of the ARM architecture. The ARM backend now +supports both the Thumb2 and Advanced SIMD (Neon) instruction sets.</li> + +<li>The AAPCS-VFP "hard float" calling conventions are also supported with the +<tt>-float-abi=hard</tt> flag.</li> + +<li>The ARM calling convention code is now tblgen generated instead of resorting + to C++ code.</li> +</ul> + +<p>These features are still somewhat experimental +and subject to change. The Neon intrinsics, in particular, may change in future +releases of LLVM. ARMv7 support has progressed a lot on top of tree since 2.6 +branched.</p> + + +</div> <!--=========================================================================--> <div class="doc_subsection"> -<a name="llvmc">Improvements in LLVMC</a> +<a name="OtherTarget">Other Target Specific Improvements</a> </div> <div class="doc_text"> -<p>New features include:</p> +<p>New features of other targets include: +</p> <ul> -<li>Beginning with LLVM 2.5, <tt>llvmc2</tt> is known as - just <tt>llvmc</tt>. The old <tt>llvmc</tt> driver was removed.</li> +<li>Mips now supports O32 Calling Convention.</li> +<li>Many improvements to the 32-bit PowerPC SVR4 ABI (used on powerpc-linux) + support, lots of bugs fixed.</li> +<li>Added support for the 64-bit PowerPC SVR4 ABI (used on powerpc64-linux). + Needs more testing.</li> +</ul> + +</div> + +<!--=========================================================================--> +<div class="doc_subsection"> +<a name="newapis">New Useful APIs</a> +</div> -<li>The Clang plugin was substantially improved and is now enabled - by default. The command <tt>llvmc --clang</tt> can be now used as a - synonym to <tt>ccc</tt>.</li> +<div class="doc_text"> -<li>There is now a <tt>--check-graph</tt> option, which is supposed to catch - common errors like multiple default edges, mismatched output/input language - names and cycles. In general, these checks can't be done at compile-time - because of the need to support plugins.</li> +<p>This release includes a number of new APIs that are used internally, which + may also be useful for external clients. +</p> -<li>Plugins are now more flexible and can refer to compilation graph nodes and - options defined in other plugins. To manage dependencies, a priority-sorting - mechanism was introduced. This change affects the TableGen file syntax. See the - documentation for details.</li> +<ul> +<li>New <a href="http://llvm.org/doxygen/PrettyStackTrace_8h-source.html"> + <tt>PrettyStackTrace</tt> class</a> allows crashes of llvm tools (and applications + that integrate them) to provide more detailed indication of what the + compiler was doing at the time of the crash (e.g. running a pass). + At the top level for each LLVM tool, it includes the command line arguments. + </li> +<li>New <a href="http://llvm.org/doxygen/StringRef_8h-source.html">StringRef</a> + and <a href="http://llvm.org/doxygen/Twine_8h-source.html">Twine</a> classes + make operations on character ranges and + string concatenation to be more efficient. <tt>StringRef</tt> is just a <tt>const + char*</tt> with a length, <tt>Twine</tt> is a light-weight rope.</li> +<li>LLVM has new <tt>WeakVH</tt>, <tt>AssertingVH</tt> and <tt>CallbackVH</tt> + classes, which make it easier to write LLVM IR transformations. <tt>WeakVH</tt> + is automatically drops to null when the referenced <tt>Value</tt> is deleted, + and is updated across a <tt>replaceAllUsesWith</tt> operation. + <tt>AssertingVH</tt> aborts the program if the + referenced value is destroyed while it is being referenced. <tt>CallbackVH</tt> + is a customizable class for handling value references. See <a + href="http://llvm.org/doxygen/ValueHandle_8h-source.html">ValueHandle.h</a> + for more information.</li> +<li>The new '<a href="http://llvm.org/doxygen/Triple_8h-source.html">Triple + </a>' class centralizes a lot of logic that reasons about target + triples.</li> +<li>The new '<a href="http://llvm.org/doxygen/ErrorHandling_8h-source.html"> + llvm_report_error()</a>' set of APIs allows tools to embed the LLVM + optimizer and backend and recover from previously unrecoverable errors.</li> +<li>LLVM has new abstractions for <a + href="http://llvm.org/doxygen/Atomic_8h-source.html">atomic operations</a> + and <a href="http://llvm.org/doxygen/RWMutex_8h-source.html">reader/writer + locks</a>.</li> +<li>LLVM has new <a href="http://llvm.org/doxygen/SourceMgr_8h-source.html"> + <tt>SourceMgr</tt> and <tt>SMLoc</tt> classes</a> which implement caret + diagnostics and basic include stack processing for simple parsers. It is + used by tablegen, llvm-mc, the .ll parser and FileCheck.</li> +</ul> -<li>Hooks can now be provided with arguments. The syntax is "<tt>$CALL(MyHook, - 'Arg1', 'Arg2', 'Arg3')</tt>".</li> -<li>A new option type: multi-valued option, for options that take more than one - argument (for example, "<tt>-foo a b c</tt>").</li> +</div> -<li>New option properties: '<tt>one_or_more</tt>', '<tt>zero_or_more</tt>', -'<tt>hidden</tt>' and '<tt>really_hidden</tt>'.</li> +<!--=========================================================================--> +<div class="doc_subsection"> +<a name="otherimprovements">Other Improvements and New Features</a> +</div> -<li>The '<tt>case</tt>' expression gained an '<tt>error</tt>' action and - an '<tt>empty</tt>' test (equivalent to "<tt>(not (not_empty ...))</tt>").</li> +<div class="doc_text"> +<p>Other miscellaneous features include:</p> -<li>Documentation now looks more consistent to the rest of the LLVM - docs. There is also a man page now.</li> +<ul> +<li>LLVM now includes a new internal '<a + href="http://llvm.org/cmds/FileCheck.html">FileCheck</a>' tool which allows + writing much more accurate regression tests that run faster. Please see the + <a href="TestingGuide.html#FileCheck">FileCheck section of the Testing + Guide</a> for more information.</li> +<li>LLVM profile information support has been significantly improved to produce +correct use counts, and has support for edge profiling with reduced runtime +overhead. Combined, the generated profile information is both more correct and +imposes about half as much overhead (2.6. from 12% to 6% overhead on SPEC +CPU2000).</li> +<li>The C bindings (in the llvm/include/llvm-c directory) include many newly + supported APIs.</li> +<li>LLVM 2.6 includes a brand new experimental LLVM bindings to the Ada2005 + programming language.</li> + +<li>The LLVMC driver has several new features: + <ul> + <li>Dynamic plugins now work on Windows.</li> + <li>New option property: init. Makes possible to provide default values for + options defined in plugins (interface to <tt>cl::init</tt>).</li> + <li>New example: Skeleton, shows how to create a standalone LLVMC-based + driver.</li> + <li>New example: mcc16, a driver for the PIC16 toolchain.</li> + </ul> +</li> </ul> @@ -605,13 +899,24 @@ instructions.</li> <div class="doc_text"> <p>If you're already an LLVM user or developer with out-of-tree changes based -on LLVM 2.4, this section lists some "gotchas" that you may run into upgrading +on LLVM 2.5, this section lists some "gotchas" that you may run into upgrading from the previous release.</p> <ul> - -<li>llvm-gcc defaults to <tt>-fno-math-errno</tt> on all X86 targets.</li> - +<li>The Itanium (IA64) backend has been removed. It was not actively supported + and had bitrotted.</li> +<li>The BigBlock register allocator has been removed, it had also bitrotted.</li> +<li>The C Backend (<tt>-march=c</tt>) is no longer considered part of the LLVM release +criteria. We still want it to work, but no one is maintaining it and it lacks +support for arbitrary precision integers and other important IR features.</li> + +<li>All LLVM tools now default to overwriting their output file, behaving more + like standard unix tools. Previously, this only happened with the '<tt>-f</tt>' + option.</li> +<li>LLVM build now builds all libraries as .a files instead of some + libraries as relinked .o files. This requires some APIs like + InitializeAllTargets.h. + </li> </ul> @@ -619,8 +924,82 @@ from the previous release.</p> API changes are:</p> <ul> -<li>Some deprecated interfaces to create <tt>Instruction</tt> subclasses, that - were spelled with lower case "create," have been removed.</li> +<li>All uses of <tt>hash_set</tt> and <tt>hash_map</tt> have been removed from + the LLVM tree and the wrapper headers have been removed.</li> +<li>The llvm/Streams.h and <tt>DOUT</tt> member of Debug.h have been removed. The + <tt>llvm::Ostream</tt> class has been completely removed and replaced with + uses of <tt>raw_ostream</tt>.</li> +<li>LLVM's global uniquing tables for <tt>Type</tt>s and <tt>Constant</tt>s have + been privatized into members of an <tt>LLVMContext</tt>. A number of APIs + now take an <tt>LLVMContext</tt> as a parameter. To smooth the transition + for clients that will only ever use a single context, the new + <tt>getGlobalContext()</tt> API can be used to access a default global + context which can be passed in any and all cases where a context is + required. +<li>The <tt>getABITypeSize</tt> methods are now called <tt>getAllocSize</tt>.</li> +<li>The <tt>Add</tt>, <tt>Sub</tt> and <tt>Mul</tt> operators are no longer + overloaded for floating-point types. Floating-point addition, subtraction + and multiplication are now represented with new operators <tt>FAdd</tt>, + <tt>FSub</tt> and <tt>FMul</tt>. In the <tt>IRBuilder</tt> API, + <tt>CreateAdd</tt>, <tt>CreateSub</tt>, <tt>CreateMul</tt> and + <tt>CreateNeg</tt> should only be used for integer arithmetic now; + <tt>CreateFAdd</tt>, <tt>CreateFSub</tt>, <tt>CreateFMul</tt> and + <tt>CreateFNeg</tt> should now be used for floating-point arithmetic.</li> +<li>The <tt>DynamicLibrary</tt> class can no longer be constructed, its functionality has + moved to static member functions.</li> +<li><tt>raw_fd_ostream</tt>'s constructor for opening a given filename now + takes an extra <tt>Force</tt> argument. If <tt>Force</tt> is set to + <tt>false</tt>, an error will be reported if a file with the given name + already exists. If <tt>Force</tt> is set to <tt>true</tt>, the file will + be silently truncated (which is the behavior before this flag was + added).</li> +<li><tt>SCEVHandle</tt> no longer exists, because reference counting is no + longer done for <tt>SCEV*</tt> objects, instead <tt>const SCEV*</tt> + should be used.</li> + +<li>Many APIs, notably <tt>llvm::Value</tt>, now use the <tt>StringRef</tt> +and <tt>Twine</tt> classes instead of passing <tt>const char*</tt> +or <tt>std::string</tt>, as described in +the <a href="ProgrammersManual.html#string_apis">Programmer's Manual</a>. Most +clients should be unaffected by this transition, unless they are used to +<tt>Value::getName()</tt> returning a string. Here are some tips on updating to +2.6: + <ul> + <li><tt>getNameStr()</tt> is still available, and matches the old + behavior. Replacing <tt>getName()</tt> calls with this is an safe option, + although more efficient alternatives are now possible.</li> + + <li>If you were just relying on <tt>getName()</tt> being able to be sent to + a <tt>std::ostream</tt>, consider migrating + to <tt>llvm::raw_ostream</tt>.</li> + + <li>If you were using <tt>getName().c_str()</tt> to get a <tt>const + char*</tt> pointer to the name, you can use <tt>getName().data()</tt>. + Note that this string (as before), may not be the entire name if the + name contains embedded null characters.</li> + + <li>If you were using <tt>operator +</tt> on the result of <tt>getName()</tt> and + treating the result as an <tt>std::string</tt>, you can either + use <tt>Twine::str</tt> to get the result as an <tt>std::string</tt>, or + could move to a <tt>Twine</tt> based design.</li> + + <li><tt>isName()</tt> should be replaced with comparison + against <tt>getName()</tt> (this is now efficient). + </ul> +</li> + +<li>The registration interfaces for backend Targets has changed (what was +previously <tt>TargetMachineRegistry</tt>). For backend authors, see the <a +href="WritingAnLLVMBackend.html#TargetRegistration">Writing An LLVM Backend</a> +guide. For clients, the notable API changes are: + <ul> + <li><tt>TargetMachineRegistry</tt> has been renamed + to <tt>TargetRegistry</tt>.</li> + + <li>Clients should move to using the <tt>TargetRegistry::lookupTarget()</tt> + function to find targets.</li> + </ul> +</li> </ul> </div> @@ -639,15 +1018,15 @@ API changes are:</p> <ul> <li>Intel and AMD machines (IA32, X86-64, AMD64, EMT-64) running Red Hat -Linux, Fedora Core and FreeBSD (and probably other unix-like systems).</li> + Linux, Fedora Core, FreeBSD and AuroraUX (and probably other unix-like + systems).</li> <li>PowerPC and X86-based Mac OS X systems, running 10.3 and above in 32-bit -and 64-bit modes.</li> + and 64-bit modes.</li> <li>Intel and AMD machines running on Win32 using MinGW libraries (native).</li> <li>Intel and AMD machines running on Win32 with the Cygwin libraries (limited support is available for native builds with Visual C++).</li> <li>Sun UltraSPARC workstations running Solaris 10.</li> <li>Alpha-based machines running Debian GNU/Linux.</li> -<li>Itanium-based (IA64) machines running Linux and HP-UX.</li> </ul> <p>The core LLVM infrastructure uses GNU autoconf to adapt itself @@ -670,6 +1049,21 @@ listed by component. If you run into a problem, please check the <a href="http://llvm.org/bugs/">LLVM bug database</a> and submit a bug if there isn't already one.</p> +<ul> +<li>The llvm-gcc bootstrap will fail with some versions of binutils (e.g. 2.15) + with a message of "<tt><a href="http://llvm.org/PR5004">Error: can not do 8 + byte pc-relative relocation</a></tt>" when building C++ code. We intend to + fix this on mainline, but a workaround for 2.6 is to upgrade to binutils + 2.17 or later.</li> + +<li>LLVM will not correctly compile on Solaris and/or OpenSolaris +using the stock GCC 3.x.x series 'out the box', +See: <a href="#brokengcc">Broken versions of GCC and other tools</a>. +However, A <a href="http://pkg.auroraux.org/GCC">Modern GCC Build</a> +for x86/x86-64 has been made available from the third party AuroraUX Project +that has been meticulously tested for bootstrapping LLVM & Clang.</li> +</ul> + </div> <!-- ======================================================================= --> @@ -687,9 +1081,11 @@ components, please contact us on the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVMdev list</a>.</p> <ul> -<li>The MSIL, IA64, Alpha, SPU, MIPS, and PIC16 backends are experimental.</li> +<li>The MSIL, Alpha, SPU, MIPS, PIC16, Blackfin, MSP430 and SystemZ backends are + experimental.</li> <li>The <tt>llc</tt> "<tt>-filetype=asm</tt>" (the default) is the only - supported value for this option.</li> + supported value for this option. The ELF writer is experimental.</li> +<li>The implementation of Andersen's Alias Analysis has many known bugs.</li> </ul> </div> @@ -744,14 +1140,14 @@ compilation, and lacks support for debug information.</li> <div class="doc_text"> <ul> +<li>Support for the Advanced SIMD (Neon) instruction set is still incomplete +and not well tested. Some features may not work at all, and the code quality +may be poor in some cases.</li> <li>Thumb mode works only on ARMv6 or higher processors. On sub-ARMv6 processors, thumb programs can crash or produce wrong results (<a href="http://llvm.org/PR1388">PR1388</a>).</li> <li>Compilation for ARM Linux OABI (old ABI) is supported but not fully tested. </li> -<li>There is a bug in QEMU-ARM (<= 0.9.0) which causes it to incorrectly - execute -programs compiled with LLVM. Please use more recent versions of QEMU.</li> </ul> </div> @@ -778,7 +1174,6 @@ programs compiled with LLVM. Please use more recent versions of QEMU.</li> <div class="doc_text"> <ul> -<li>The O32 ABI is not fully supported.</li> <li>64-bit MIPS targets are not supported yet.</li> </ul> @@ -801,21 +1196,6 @@ appropriate nops inserted to ensure restartability.</li> <!-- ======================================================================= --> <div class="doc_subsection"> - <a name="ia64-be">Known problems with the IA64 back-end</a> -</div> - -<div class="doc_text"> - -<ul> -<li>The Itanium backend is highly experimental and has a number of known - issues. We are looking for a maintainer for the Itanium backend. If you - are interested, please contact the LLVMdev mailing list.</li> -</ul> - -</div> - -<!-- ======================================================================= --> -<div class="doc_subsection"> <a name="c-be">Known problems with the C back-end</a> </div> @@ -841,10 +1221,6 @@ appropriate nops inserted to ensure restartability.</li> <div class="doc_text"> -<p>llvm-gcc does not currently support <a href="http://llvm.org/PR869">Link-Time -Optimization</a> on most platforms "out-of-the-box". Please inquire on the -LLVMdev mailing list if you are interested.</p> - <p>The only major language feature of GCC not supported by llvm-gcc is the <tt>__builtin_apply</tt> family of builtins. However, some extensions are only supported on some targets. For example, trampolines are only @@ -882,7 +1258,8 @@ itself, Qt, Mozilla, etc.</p> <div class="doc_text"> <ul> <li>Fortran support generally works, but there are still several unresolved bugs - in Bugzilla. Please see the tools/gfortran component for details.</li> + in <a href="http://llvm.org/bugs/">Bugzilla</a>. Please see the + tools/gfortran component for details.</li> </ul> </div> @@ -902,16 +1279,16 @@ which does support trampolines.</li> <li>The Ada front-end <a href="http://llvm.org/PR2007">fails to bootstrap</a>. This is due to lack of LLVM support for <tt>setjmp</tt>/<tt>longjmp</tt> style exception handling, which is used internally by the compiler. -Workaround: configure with --disable-bootstrap.</li> +Workaround: configure with <tt>--disable-bootstrap</tt>.</li> <li>The c380004, <a href="http://llvm.org/PR2010">c393010</a> and <a href="http://llvm.org/PR2421">cxg2021</a> ACATS tests fail (c380004 also fails with gcc-4.2 mainline). If the compiler is built with checks disabled then <a href="http://llvm.org/PR2010">c393010</a> causes the compiler to go into an infinite loop, using up all system memory.</li> <li>Some GCC specific Ada tests continue to crash the compiler.</li> -<li>The -E binder option (exception backtraces) +<li>The <tt>-E</tt> binder option (exception backtraces) <a href="http://llvm.org/PR1982">does not work</a> and will result in programs -crashing if an exception is raised. Workaround: do not use -E.</li> +crashing if an exception is raised. Workaround: do not use <tt>-E</tt>.</li> <li>Only discrete types <a href="http://llvm.org/PR1981">are allowed to start or finish at a non-byte offset</a> in a record. Workaround: do not pack records or use representation clauses that result in a field of a non-discrete type @@ -925,6 +1302,20 @@ ignored</a>.</li> </ul> </div> +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="ocaml-bindings">Known problems with the O'Caml bindings</a> +</div> + +<div class="doc_text"> + +<p>The <tt>Llvm.Linkage</tt> module is broken, and has incorrect values. Only +<tt>Llvm.Linkage.External</tt>, <tt>Llvm.Linkage.Available_externally</tt>, and +<tt>Llvm.Linkage.Link_once</tt> will be correct. If you need any of the other linkage +modes, you'll have to write an external C library in order to expose the +functionality. This has been fixed in the trunk.</p> +</div> + <!-- *********************************************************************** --> <div class="doc_section"> <a name="additionalinfo">Additional Information</a> @@ -957,7 +1348,7 @@ lists</a>.</p> src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-03-02 21:08:12 +0100 (Mon, 02 Mar 2009) $ + Last modified: $Date: 2009-10-13 19:48:04 +0200 (Tue, 13 Oct 2009) $ </address> </body> diff --git a/docs/SourceLevelDebugging.html b/docs/SourceLevelDebugging.html index e940e93..277b1e3 100644 --- a/docs/SourceLevelDebugging.html +++ b/docs/SourceLevelDebugging.html @@ -80,7 +80,7 @@ height="369"> debug information in LLVM. It describes the <a href="#format">actual format that the LLVM debug information</a> takes, which is useful for those interested in creating front-ends or dealing directly with the information. - Further, this document provides specifc examples of what debug information + Further, this document provides specific examples of what debug information for C/C++.</p> </div> @@ -122,8 +122,8 @@ height="369"> <p>The approach used by the LLVM implementation is to use a small set of <a href="#format_common_intrinsics">intrinsic functions</a> to define a mapping between LLVM program objects and the source-level objects. The - description of the source-level program is maintained in LLVM global - variables in an <a href="#ccxx_frontend">implementation-defined format</a> + description of the source-level program is maintained in LLVM metadata + in an <a href="#ccxx_frontend">implementation-defined format</a> (the C/C++ front-end currently uses working draft 7 of the <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3 standard</a>).</p> @@ -240,31 +240,21 @@ height="369"> <p>LLVM debugging information has been carefully designed to make it possible for the optimizer to optimize the program and debugging information without necessarily having to know anything about debugging information. In - particular, the global constant merging pass automatically eliminates - duplicated debugging information (often caused by header files), the global - dead code elimination pass automatically deletes debugging information for a - function if it decides to delete the function, and the linker eliminates - debug information when it merges <tt>linkonce</tt> functions.</p> + particular, te use of metadadta avoids duplicated dubgging information from + the beginning, and the global dead code elimination pass automatically + deletes debugging information for a function if it decides to delete the + function. </p> <p>To do this, most of the debugging information (descriptors for types, variables, functions, source files, etc) is inserted by the language - front-end in the form of LLVM global variables. These LLVM global variables - are no different from any other global variables, except that they have a web - of LLVM intrinsic functions that point to them. If the last references to a - particular piece of debugging information are deleted (for example, by the - <tt>-globaldce</tt> pass), the extraneous debug information will - automatically become dead and be removed by the optimizer.</p> + front-end in the form of LLVM metadata. </p> <p>Debug information is designed to be agnostic about the target debugger and debugging information representation (e.g. DWARF/Stabs/etc). It uses a - generic machine debug information pass to decode the information that - represents variables, types, functions, namespaces, etc: this allows for - arbitrary source-language semantics and type-systems to be used, as long as - there is a module written for the target debugger to interpret the - information. In addition, debug global variables are declared in - the <tt>"llvm.metadata"</tt> section. All values declared in this section - are stripped away after target debug information is constructed and before - the program object is emitted.</p> + generic pass to decode the information that represents variables, types, + functions, namespaces, etc: this allows for arbitrary source-language + semantics and type-systems to be used, as long as there is a module + written for the target debugger to interpret the information. </p> <p>To provide basic functionality, the LLVM debugger does have to make some assumptions about the source-level language being debugged, though it keeps @@ -288,9 +278,7 @@ height="369"> <div class="doc_text"> <p>In consideration of the complexity and volume of debug information, LLVM - provides a specification for well formed debug global variables. The - constant value of each of these globals is one of a limited set of - structures, known as debug descriptors.</p> + provides a specification for well formed debug descriptors. </p> <p>Consumers of LLVM debug information expect the descriptors for program objects to start in a canonical format, but the descriptors can include @@ -300,20 +288,17 @@ height="369"> way. Also, all debugging information objects start with a tag to indicate what type of object it is. The source-language is allowed to define its own objects, by using unreserved tag numbers. We recommend using with tags in - the range 0x1000 thru 0x2000 (there is a defined enum DW_TAG_user_base = + the range 0x1000 through 0x2000 (there is a defined enum DW_TAG_user_base = 0x1000.)</p> -<p>The fields of debug descriptors used internally by LLVM (MachineModuleInfo) +<p>The fields of debug descriptors used internally by LLVM are restricted to only the simple data types <tt>int</tt>, <tt>uint</tt>, - <tt>bool</tt>, <tt>float</tt>, <tt>double</tt>, <tt>i8*</tt> and - <tt>{ }*</tt>. References to arbitrary values are handled using a - <tt>{ }*</tt> and a cast to <tt>{ }*</tt> expression; typically - references to other field descriptors, arrays of descriptors or global - variables.</p> + <tt>bool</tt>, <tt>float</tt>, <tt>double</tt>, <tt>mdstring</tt> and + <tt>mdnode</tt>. </p> <div class="doc_code"> <pre> -%llvm.dbg.object.type = type { +!1 = metadata !{ uint, ;; A tag ... } @@ -326,8 +311,8 @@ height="369"> of tags are loosely bound to the tag values of DWARF information entries. However, that does not restrict the use of the information supplied to DWARF targets. To facilitate versioning of debug information, the tag is augmented - with the current debug version (LLVMDebugVersion = 4 << 16 or 0x40000 or - 262144.)</a></p> + with the current debug version (LLVMDebugVersion = 7 << 16 or 0x70000 or + 458752.)</a></p> <p>The details of the various descriptors follow.</p> @@ -342,17 +327,18 @@ height="369"> <div class="doc_code"> <pre> -%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = type { - i32, ;; Tag = 17 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_compile_unit) - { }*, ;; Compile unit anchor = cast = (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_units</a> to { }*) - i32, ;; DWARF language identifier (ex. DW_LANG_C89) - i8*, ;; Source file name - i8*, ;; Source file directory (includes trailing slash) - i8* ;; Producer (ex. "4.0.1 LLVM (LLVM research group)") - i1, ;; True if this is a main compile unit. - i1, ;; True if this is optimized. - i8*, ;; Flags - i32 ;; Runtime version +!0 = metadata !{ + i32, ;; Tag = 17 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> + ;; (DW_TAG_compile_unit) + i32, ;; Unused field. + i32, ;; DWARF language identifier (ex. DW_LANG_C89) + metadata, ;; Source file name + metadata, ;; Source file directory (includes trailing slash) + metadata ;; Producer (ex. "4.0.1 LLVM (LLVM research group)") + i1, ;; True if this is a main compile unit. + i1, ;; True if this is optimized. + metadata, ;; Flags + i32 ;; Runtime version } </pre> </div> @@ -388,19 +374,20 @@ height="369"> <div class="doc_code"> <pre> -%<a href="#format_global_variables">llvm.dbg.global_variable.type</a> = type { - i32, ;; Tag = 52 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_variable) - { }*, ;; Global variable anchor = cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_global_variables">llvm.dbg.global_variables</a> to { }*), - { }*, ;; Reference to context descriptor - i8*, ;; Name - i8*, ;; Display name (fully qualified C++ name) - i8*, ;; MIPS linkage name (for C++) - { }*, ;; Reference to compile unit where defined - i32, ;; Line number where defined - { }*, ;; Reference to type descriptor - i1, ;; True if the global is local to compile unit (static) - i1, ;; True if the global is defined in the compile unit (not extern) - { }* ;; Reference to the global variable +!1 = metadata !{ + i32, ;; Tag = 52 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> + ;; (DW_TAG_variable) + i32, ;; Unused field. + metadata, ;; Reference to context descriptor + metadata, ;; Name + metadata, ;; Display name (fully qualified C++ name) + metadata, ;; MIPS linkage name (for C++) + metadata, ;; Reference to compile unit where defined + i32, ;; Line number where defined + metadata, ;; Reference to type descriptor + i1, ;; True if the global is local to compile unit (static) + i1, ;; True if the global is defined in the compile unit (not extern) + { }* ;; Reference to the global variable } </pre> </div> @@ -419,18 +406,19 @@ provide details such as name, type and where the variable is defined.</p> <div class="doc_code"> <pre> -%<a href="#format_subprograms">llvm.dbg.subprogram.type</a> = type { - i32, ;; Tag = 46 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_subprogram) - { }*, ;; Subprogram anchor = cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_subprograms">llvm.dbg.subprograms</a> to { }*), - { }*, ;; Reference to context descriptor - i8*, ;; Name - i8*, ;; Display name (fully qualified C++ name) - i8*, ;; MIPS linkage name (for C++) - { }*, ;; Reference to compile unit where defined - i32, ;; Line number where defined - { }*, ;; Reference to type descriptor - i1, ;; True if the global is local to compile unit (static) - i1 ;; True if the global is defined in the compile unit (not extern) +!2 = metadata !{ + i32, ;; Tag = 46 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> + ;; (DW_TAG_subprogram) + i32, ;; Unused field. + metadata, ;; Reference to context descriptor + metadata, ;; Name + metadata, ;; Display name (fully qualified C++ name) + metadata, ;; MIPS linkage name (for C++) + metadata, ;; Reference to compile unit where defined + i32, ;; Line number where defined + metadata, ;; Reference to type descriptor + i1, ;; True if the global is local to compile unit (static) + i1 ;; True if the global is defined in the compile unit (not extern) } </pre> </div> @@ -450,9 +438,9 @@ provide details such as name, type and where the variable is defined.</p> <div class="doc_code"> <pre> -%<a href="#format_blocks">llvm.dbg.block</a> = type { - i32, ;; Tag = 13 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block) - { }* ;; Reference to context descriptor +!3 = metadata !{ + i32, ;; Tag = 13 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block) + metadata ;; Reference to context descriptor } </pre> </div> @@ -472,17 +460,18 @@ provide details such as name, type and where the variable is defined.</p> <div class="doc_code"> <pre> -%<a href="#format_basic_type">llvm.dbg.basictype.type</a> = type { - i32, ;; Tag = 36 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_base_type) - { }*, ;; Reference to context (typically a compile unit) - i8*, ;; Name (may be "" for anonymous types) - { }*, ;; Reference to compile unit where defined (may be NULL) - i32, ;; Line number where defined (may be 0) - i64, ;; Size in bits - i64, ;; Alignment in bits - i64, ;; Offset in bits - i32, ;; Flags - i32 ;; DWARF type encoding +!4 = metadata !{ + i32, ;; Tag = 36 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> + ;; (DW_TAG_base_type) + metadata, ;; Reference to context (typically a compile unit) + metadata, ;; Name (may be "" for anonymous types) + metadata, ;; Reference to compile unit where defined (may be NULL) + i32, ;; Line number where defined (may be 0) + i64, ;; Size in bits + i64, ;; Alignment in bits + i64, ;; Offset in bits + i32, ;; Flags + i32 ;; DWARF type encoding } </pre> </div> @@ -523,16 +512,16 @@ DW_ATE_unsigned_char = 8 <div class="doc_code"> <pre> -%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> = type { - i32, ;; Tag (see below) - { }*, ;; Reference to context - i8*, ;; Name (may be "" for anonymous types) - { }*, ;; Reference to compile unit where defined (may be NULL) - i32, ;; Line number where defined (may be 0) - i32, ;; Size in bits - i32, ;; Alignment in bits - i32, ;; Offset in bits - { }* ;; Reference to type derived from +!5 = metadata !{ + i32, ;; Tag (see below) + metadata, ;; Reference to context + metadata, ;; Name (may be "" for anonymous types) + metadata, ;; Reference to compile unit where defined (may be NULL) + i32, ;; Line number where defined (may be 0) + i32, ;; Size in bits + i32, ;; Alignment in bits + i32, ;; Offset in bits + metadata ;; Reference to type derived from } </pre> </div> @@ -591,19 +580,19 @@ DW_TAG_restrict_type = 55 <div class="doc_code"> <pre> -%<a href="#format_composite_type">llvm.dbg.compositetype.type</a> = type { - i32, ;; Tag (see below) - { }*, ;; Reference to context - i8*, ;; Name (may be "" for anonymous types) - { }*, ;; Reference to compile unit where defined (may be NULL) - i32, ;; Line number where defined (may be 0) - i64, ;; Size in bits - i64, ;; Alignment in bits - i64, ;; Offset in bits - i32, ;; Flags - { }*, ;; Reference to type derived from - { }*, ;; Reference to array of member descriptors - i32 ;; Runtime languages +!6 = metadata !{ + i32, ;; Tag (see below) + metadata, ;; Reference to context + metadata, ;; Name (may be "" for anonymous types) + metadata, ;; Reference to compile unit where defined (may be NULL) + i32, ;; Line number where defined (may be 0) + i64, ;; Size in bits + i64, ;; Alignment in bits + i64, ;; Offset in bits + i32, ;; Flags + metadata, ;; Reference to type derived from + metadata, ;; Reference to array of member descriptors + i32 ;; Runtime languages } </pre> </div> @@ -702,10 +691,11 @@ DW_TAG_inheritance = 28 <div class="doc_code"> <pre> -%<a href="#format_enumeration">llvm.dbg.enumerator.type</a> = type { - i32, ;; Tag = 40 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_enumerator) - i8*, ;; Name - i64 ;; Value +!6 = metadata !{ + i32, ;; Tag = 40 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> + ;; (DW_TAG_enumerator) + metadata, ;; Name + i64 ;; Value } </pre> </div> @@ -725,13 +715,13 @@ DW_TAG_inheritance = 28 <div class="doc_code"> <pre> -%<a href="#format_variables">llvm.dbg.variable.type</a> = type { - i32, ;; Tag (see below) - { }*, ;; Context - i8*, ;; Name - { }*, ;; Reference to compile unit where defined - i32, ;; Line number where defined - { }* ;; Type descriptor +!7 = metadata !{ + i32, ;; Tag (see below) + metadata, ;; Context + metadata, ;; Name + metadata, ;; Reference to compile unit where defined + i32, ;; Line number where defined + metadata ;; Type descriptor } </pre> </div> @@ -778,14 +768,14 @@ DW_TAG_return_variable = 258 <div class="doc_text"> <pre> - void %<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint, uint, { }* ) + void %<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint, uint, metadata) </pre> <p>This intrinsic is used to provide correspondence between the source file and the generated code. The first argument is the line number (base 1), second argument is the column number (0 if unknown) and the third argument the - source <tt>%<a href="#format_compile_units">llvm.dbg.compile_unit</a>*</tt> - cast to a <tt>{ }*</tt>. Code following a call to this intrinsic will + source <tt>%<a href="#format_compile_units">llvm.dbg.compile_unit</a>. + Code following a call to this intrinsic will have been defined in close proximity of the line, column and file. This information holds until the next call to <tt>%<a href="#format_common_stoppoint">lvm.dbg.stoppoint</a></tt>.</p> @@ -799,7 +789,7 @@ DW_TAG_return_variable = 258 <div class="doc_text"> <pre> - void %<a href="#format_common_func_start">llvm.dbg.func.start</a>( { }* ) + void %<a href="#format_common_func_start">llvm.dbg.func.start</a>( metadata ) </pre> <p>This intrinsic is used to link the debug information @@ -823,7 +813,7 @@ DW_TAG_return_variable = 258 <div class="doc_text"> <pre> - void %<a href="#format_common_region_start">llvm.dbg.region.start</a>( { }* ) + void %<a href="#format_common_region_start">llvm.dbg.region.start</a>( metadata ) </pre> <p>This intrinsic is used to define the beginning of a declarative scope (ex. @@ -843,7 +833,7 @@ DW_TAG_return_variable = 258 <div class="doc_text"> <pre> - void %<a href="#format_common_region_end">llvm.dbg.region.end</a>( { }* ) + void %<a href="#format_common_region_end">llvm.dbg.region.end</a>( metadata ) </pre> <p>This intrinsic is used to define the end of a declarative scope (ex. block) @@ -864,14 +854,14 @@ DW_TAG_return_variable = 258 <div class="doc_text"> <pre> - void %<a href="#format_common_declare">llvm.dbg.declare</a>( { } *, { }* ) + void %<a href="#format_common_declare">llvm.dbg.declare</a>( { } *, metadata ) </pre> <p>This intrinsic provides information about a local element (ex. variable.) The first argument is the alloca for the variable, cast to a <tt>{ }*</tt>. The second argument is the <tt>%<a href="#format_variables">llvm.dbg.variable</a></tt> containing - the description of the variable, also cast to a <tt>{ }*</tt>.</p> + the description of the variable. </p> </div> @@ -955,29 +945,29 @@ entry: ... - call void @<a href="#format_common_func_start">llvm.dbg.func.start</a>( %<a href="#format_subprograms">llvm.dbg.subprogram.type</a>* @llvm.dbg.subprogram ) + call void @<a href="#format_common_func_start">llvm.dbg.func.start</a>( metadata !0) - call void @<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint 2, uint 2, %<a href="#format_compile_units">llvm.dbg.compile_unit</a>* @llvm.dbg.compile_unit ) + call void @<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint 2, uint 2, metadata !1) call void @<a href="#format_common_declare">llvm.dbg.declare</a>({}* %X, ...) call void @<a href="#format_common_declare">llvm.dbg.declare</a>({}* %Y, ...) <i>;; Evaluate expression on line 2, assigning to X.</i> - call void @<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint 3, uint 2, %<a href="#format_compile_units">llvm.dbg.compile_unit</a>* @llvm.dbg.compile_unit ) + call void @<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint 3, uint 2, metadata !1) <i>;; Evaluate expression on line 3, assigning to Y.</i> call void @<a href="#format_common_stoppoint">llvm.region.start</a>() - call void @<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint 5, uint 4, %<a href="#format_compile_units">llvm.dbg.compile_unit</a>* @llvm.dbg.compile_unit ) + call void @<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint 5, uint 4, metadata !1) call void @<a href="#format_common_declare">llvm.dbg.declare</a>({}* %X, ...) <i>;; Evaluate expression on line 5, assigning to Z.</i> - call void @<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint 7, uint 2, %<a href="#format_compile_units">llvm.dbg.compile_unit</a>* @llvm.dbg.compile_unit ) + call void @<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint 7, uint 2, metadata !1) call void @<a href="#format_common_region_end">llvm.region.end</a>() - call void @<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint 9, uint 2, %<a href="#format_compile_units">llvm.dbg.compile_unit</a>* @llvm.dbg.compile_unit ) + call void @<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint 9, uint 2, metadata !1) call void @<a href="#format_common_region_end">llvm.region.end</a>() @@ -1097,50 +1087,35 @@ int main(int argc, char *argv[]) { <pre> ... ;; -;; Define types used. In this case we need one for compile unit anchors and one -;; for compile units. -;; -%<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { uint, uint } -%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = type { uint, { }*, uint, uint, i8*, i8*, i8* } -... -;; -;; Define the anchor for compile units. Note that the second field of the -;; anchor is 17, which is the same as the tag for compile units -;; (17 = DW_TAG_compile_unit.) -;; -%<a href="#format_compile_units">llvm.dbg.compile_units</a> = linkonce constant %<a href="#format_anchors">llvm.dbg.anchor.type</a> { uint 0, uint 17 }, section "llvm.metadata" - -;; ;; Define the compile unit for the source file "/Users/mine/sources/MySource.cpp". ;; -%<a href="#format_compile_units">llvm.dbg.compile_unit1</a> = internal constant %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> { - uint add(uint 17, uint 262144), - { }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_units</a> to { }*), - uint 1, - uint 1, - i8* getelementptr ([13 x i8]* %str1, i32 0, i32 0), - i8* getelementptr ([21 x i8]* %str2, i32 0, i32 0), - i8* getelementptr ([33 x i8]* %str3, i32 0, i32 0) }, section "llvm.metadata" - +!3 = metadata !{ + i32 458769, ;; Tag + i32 0, ;; Unused + i32 4, ;; Language Id + metadata !"MySource.cpp", + metadata !"/Users/mine/sources", + metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)", + i1 true, ;; Main Compile Unit + i1 false, ;; Optimized compile unit + metadata !"", ;; Compiler flags + i32 0} ;; Runtime version + ;; ;; Define the compile unit for the header file "/Users/mine/sources/MyHeader.h". ;; -%<a href="#format_compile_units">llvm.dbg.compile_unit2</a> = internal constant %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> { - uint add(uint 17, uint 262144), - { }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_units</a> to { }*), - uint 1, - uint 1, - i8* getelementptr ([11 x i8]* %str4, int 0, int 0), - i8* getelementptr ([21 x i8]* %str2, int 0, int 0), - i8* getelementptr ([33 x i8]* %str3, int 0, int 0) }, section "llvm.metadata" +!1 = metadata !{ + i32 458769, ;; Tag + i32 0, ;; Unused + i32 4, ;; Language Id + metadata !"MyHeader.h", + metadata !"/Users/mine/sources", + metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)", + i1 false, ;; Main Compile Unit + i1 false, ;; Optimized compile unit + metadata !"", ;; Compiler flags + i32 0} ;; Runtime version -;; -;; Define each of the strings used in the compile units. -;; -%str1 = internal constant [13 x i8] c"MySource.cpp\00", section "llvm.metadata"; -%str2 = internal constant [21 x i8] c"/Users/mine/sources/\00", section "llvm.metadata"; -%str3 = internal constant [33 x i8] c"4.0.1 LLVM (LLVM research group)\00", section "llvm.metadata"; -%str4 = internal constant [11 x i8] c"MyHeader.h\00", section "llvm.metadata"; ... </pre> </div> @@ -1167,65 +1142,51 @@ int MyGlobal = 100; <div class="doc_code"> <pre> ;; -;; Define types used. One for global variable anchors, one for the global -;; variable descriptor, one for the global's basic type and one for the global's -;; compile unit. -;; -%<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { uint, uint } -%<a href="#format_global_variables">llvm.dbg.global_variable.type</a> = type { uint, { }*, { }*, i8*, { }*, uint, { }*, bool, bool, { }*, uint } -%<a href="#format_basic_type">llvm.dbg.basictype.type</a> = type { uint, { }*, i8*, { }*, int, uint, uint, uint, uint } -%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = ... -... -;; ;; Define the global itself. ;; %MyGlobal = global int 100 ... ;; -;; Define the anchor for global variables. Note that the second field of the -;; anchor is 52, which is the same as the tag for global variables -;; (52 = DW_TAG_variable.) +;; List of debug info of globals ;; -%<a href="#format_global_variables">llvm.dbg.global_variables</a> = linkonce constant %<a href="#format_anchors">llvm.dbg.anchor.type</a> { uint 0, uint 52 }, section "llvm.metadata" +!llvm.dbg.gv = !{!0} ;; ;; Define the global variable descriptor. Note the reference to the global ;; variable anchor and the global variable itself. ;; -%<a href="#format_global_variables">llvm.dbg.global_variable</a> = internal constant %<a href="#format_global_variables">llvm.dbg.global_variable.type</a> { - uint add(uint 52, uint 262144), - { }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_global_variables">llvm.dbg.global_variables</a> to { }*), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([9 x i8]* %str1, int 0, int 0), - i8* getelementptr ([1 x i8]* %str2, int 0, int 0), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - uint 1, - { }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to { }*), - bool false, - bool true, - { }* cast (int* %MyGlobal to { }*) }, section "llvm.metadata" - +!0 = metadata !{ + i32 458804, ;; Tag + i32 0, ;; Unused + metadata !1, ;; Context + metadata !"MyGlobal", ;; Name + metadata !"MyGlobal", ;; Display Name + metadata !"MyGlobal", ;; Linkage Name + metadata !1, ;; Compile Unit + i32 1, ;; Line Number + metadata !2, ;; Type + i1 false, ;; Is a local variable + i1 true, ;; Is this a definition + i32* @MyGlobal ;; The global variable +} + ;; ;; Define the basic type of 32 bit signed integer. Note that since int is an ;; intrinsic type the source file is NULL and line 0. ;; -%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> { - uint add(uint 36, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([4 x i8]* %str3, int 0, int 0), - { }* null, - int 0, - uint 32, - uint 32, - uint 0, - uint 5 }, section "llvm.metadata" +!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"int", ;; Name + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 32, ;; Size in Bits + i64 32, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 5 ;; Encoding +} -;; -;; Define the names of the global variable and basic type. -;; -%str1 = internal constant [9 x i8] c"MyGlobal\00", section "llvm.metadata" -%str2 = internal constant [1 x i8] c"\00", section "llvm.metadata" -%str3 = internal constant [4 x i8] c"int\00", section "llvm.metadata" </pre> </div> @@ -1253,46 +1214,27 @@ int main(int argc, char *argv[]) { <div class="doc_code"> <pre> ;; -;; Define types used. One for subprogram anchors, one for the subprogram -;; descriptor, one for the global's basic type and one for the subprogram's -;; compile unit. -;; -%<a href="#format_subprograms">llvm.dbg.subprogram.type</a> = type { uint, { }*, { }*, i8*, { }*, bool, bool } -%<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { uint, uint } -%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = ... - -;; ;; Define the anchor for subprograms. Note that the second field of the ;; anchor is 46, which is the same as the tag for subprograms ;; (46 = DW_TAG_subprogram.) ;; -%<a href="#format_subprograms">llvm.dbg.subprograms</a> = linkonce constant %<a href="#format_anchors">llvm.dbg.anchor.type</a> { uint 0, uint 46 }, section "llvm.metadata" - -;; -;; Define the descriptor for the subprogram. TODO - more details. -;; -%<a href="#format_subprograms">llvm.dbg.subprogram</a> = internal constant %<a href="#format_subprograms">llvm.dbg.subprogram.type</a> { - uint add(uint 46, uint 262144), - { }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_subprograms">llvm.dbg.subprograms</a> to { }*), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([5 x i8]* %str1, int 0, int 0), - i8* getelementptr ([1 x i8]* %str2, int 0, int 0), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - uint 1, - { }* null, - bool false, - bool true }, section "llvm.metadata" - -;; -;; Define the name of the subprogram. -;; -%str1 = internal constant [5 x i8] c"main\00", section "llvm.metadata" -%str2 = internal constant [1 x i8] c"\00", section "llvm.metadata" - +!0 = metadata !{ + i32 458798, ;; Tag + i32 0, ;; Unused + metadata !1, ;; Context + metadata !"main", ;; Name + metadata !"main", ;; Display name + metadata !"main", ;; Linkage name + metadata !1, ;; Compile unit + i32 1, ;; Line number + metadata !2, ;; Type + i1 false, ;; Is local + i1 true ;; Is definition +} ;; ;; Define the subprogram itself. ;; -int %main(int %argc, i8** %argv) { +define i32 @main(i32 %argc, i8** %argv) { ... } </pre> @@ -1320,17 +1262,18 @@ int %main(int %argc, i8** %argv) { <div class="doc_code"> <pre> -%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> { - uint add(uint 36, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([5 x i8]* %str1, int 0, int 0), - { }* null, - int 0, - uint 32, - uint 32, - uint 0, - uint 2 }, section "llvm.metadata" -%str1 = internal constant [5 x i8] c"bool\00", section "llvm.metadata" +!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"bool", ;; Name + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 8, ;; Size in Bits + i64 8, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 2 ;; Encoding +} </pre> </div> @@ -1345,17 +1288,18 @@ int %main(int %argc, i8** %argv) { <div class="doc_code"> <pre> -%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> { - uint add(uint 36, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([5 x i8]* %str1, int 0, int 0), - { }* null, - int 0, - uint 8, - uint 8, - uint 0, - uint 6 }, section "llvm.metadata" -%str1 = internal constant [5 x i8] c"char\00", section "llvm.metadata" +!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"char", ;; Name + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 8, ;; Size in Bits + i64 8, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 6 ;; Encoding +} </pre> </div> @@ -1370,17 +1314,18 @@ int %main(int %argc, i8** %argv) { <div class="doc_code"> <pre> -%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> { - uint add(uint 36, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([14 x i8]* %str1, int 0, int 0), - { }* null, - int 0, - uint 8, - uint 8, - uint 0, - uint 8 }, section "llvm.metadata" -%str1 = internal constant [14 x i8] c"unsigned char\00", section "llvm.metadata" +!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"unsigned char", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 8, ;; Size in Bits + i64 8, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 8 ;; Encoding +} </pre> </div> @@ -1395,17 +1340,18 @@ int %main(int %argc, i8** %argv) { <div class="doc_code"> <pre> -%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> { - uint add(uint 36, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([10 x i8]* %str1, int 0, int 0), - { }* null, - int 0, - uint 16, - uint 16, - uint 0, - uint 5 }, section "llvm.metadata" -%str1 = internal constant [10 x i8] c"short int\00", section "llvm.metadata" +!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"short int", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 16, ;; Size in Bits + i64 16, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 5 ;; Encoding +} </pre> </div> @@ -1420,17 +1366,18 @@ int %main(int %argc, i8** %argv) { <div class="doc_code"> <pre> -%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> { - uint add(uint 36, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([19 x i8]* %str1, int 0, int 0), - { }* null, - int 0, - uint 16, - uint 16, - uint 0, - uint 7 }, section "llvm.metadata" -%str1 = internal constant [19 x i8] c"short unsigned int\00", section "llvm.metadata" +!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"short unsigned int", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 16, ;; Size in Bits + i64 16, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 7 ;; Encoding +} </pre> </div> @@ -1445,17 +1392,18 @@ int %main(int %argc, i8** %argv) { <div class="doc_code"> <pre> -%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> { - uint add(uint 36, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([4 x i8]* %str1, int 0, int 0), - { }* null, - int 0, - uint 32, - uint 32, - uint 0, - uint 5 }, section "llvm.metadata" -%str1 = internal constant [4 x i8] c"int\00", section "llvm.metadata" +!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"int", ;; Name + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 32, ;; Size in Bits + i64 32, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 5 ;; Encoding +} </pre></div> </div> @@ -1469,17 +1417,18 @@ int %main(int %argc, i8** %argv) { <div class="doc_code"> <pre> -%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> { - uint add(uint 36, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([13 x i8]* %str1, int 0, int 0), - { }* null, - int 0, - uint 32, - uint 32, - uint 0, - uint 7 }, section "llvm.metadata" -%str1 = internal constant [13 x i8] c"unsigned int\00", section "llvm.metadata" +!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"unsigned int", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 32, ;; Size in Bits + i64 32, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 7 ;; Encoding +} </pre> </div> @@ -1494,17 +1443,18 @@ int %main(int %argc, i8** %argv) { <div class="doc_code"> <pre> -%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> { - uint add(uint 36, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([14 x i8]* %str1, int 0, int 0), - { }* null, - int 0, - uint 64, - uint 64, - uint 0, - uint 5 }, section "llvm.metadata" -%str1 = internal constant [14 x i8] c"long long int\00", section "llvm.metadata" +!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"long long int", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 64, ;; Size in Bits + i64 64, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 5 ;; Encoding +} </pre> </div> @@ -1519,17 +1469,18 @@ int %main(int %argc, i8** %argv) { <div class="doc_code"> <pre> -%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> { - uint add(uint 36, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([23 x i8]* %str1, int 0, int 0), - { }* null, - int 0, - uint 64, - uint 64, - uint 0, - uint 7 }, section "llvm.metadata" -%str1 = internal constant [23 x 8] c"long long unsigned int\00", section "llvm.metadata" +!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"long long unsigned int", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 64, ;; Size in Bits + i64 64, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 7 ;; Encoding +} </pre> </div> @@ -1544,17 +1495,18 @@ int %main(int %argc, i8** %argv) { <div class="doc_code"> <pre> -%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> { - uint add(uint 36, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([6 x i8]* %str1, int 0, int 0), - { }* null, - int 0, - uint 32, - uint 32, - uint 0, - uint 4 }, section "llvm.metadata" -%str1 = internal constant [6 x i8] c"float\00", section "llvm.metadata" +!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"float", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 32, ;; Size in Bits + i64 32, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 4 ;; Encoding +} </pre> </div> @@ -1569,17 +1521,18 @@ int %main(int %argc, i8** %argv) { <div class="doc_code"> <pre> -%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> { - uint add(uint 36, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - 8* getelementptr ([7 x 8]* %str1, int 0, int 0), - { }* null, - int 0, - uint 64, - uint 64, - uint 0, - uint 4 }, section "llvm.metadata" -%str1 = internal constant [7 x 8] c"double\00", section "llvm.metadata" +!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"double",;; Name + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 64, ;; Size in Bits + i64 64, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 4 ;; Encoding +} </pre> </div> @@ -1607,60 +1560,64 @@ typedef const int *IntPtr; ;; ;; Define the typedef "IntPtr". ;; -%<a href="#format_derived_type">llvm.dbg.derivedtype1</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> { - uint add(uint 22, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([7 x 8]* %str1, int 0, int 0), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - int 1, - uint 0, - uint 0, - uint 0, - { }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype2</a> to { }*) }, section "llvm.metadata" -%str1 = internal constant [7 x 8] c"IntPtr\00", section "llvm.metadata" +!2 = metadata !{ + i32 458774, ;; Tag + metadata !1, ;; Context + metadata !"IntPtr", ;; Name + metadata !3, ;; Compile unit + i32 0, ;; Line number + i64 0, ;; Size in bits + i64 0, ;; Align in bits + i64 0, ;; Offset in bits + i32 0, ;; Flags + metadata !4 ;; Derived From type +} ;; ;; Define the pointer type. ;; -%<a href="#format_derived_type">llvm.dbg.derivedtype2</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> { - uint add(uint 15, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* null, - { }* null, - int 0, - uint 32, - uint 32, - uint 0, - { }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype3</a> to { }*) }, section "llvm.metadata" - +!4 = metadata !{ + i32 458767, ;; Tag + metadata !1, ;; Context + metadata !"", ;; Name + metadata !1, ;; Compile unit + i32 0, ;; Line number + i64 64, ;; Size in bits + i64 64, ;; Align in bits + i64 0, ;; Offset in bits + i32 0, ;; Flags + metadata !5 ;; Derived From type +} ;; ;; Define the const type. ;; -%<a href="#format_derived_type">llvm.dbg.derivedtype3</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> { - uint add(uint 38, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* null, - { }* null, - int 0, - uint 0, - uint 0, - uint 0, - { }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype1</a> to { }*) }, section "llvm.metadata" - +!5 = metadata !{ + i32 458790, ;; Tag + metadata !1, ;; Context + metadata !"", ;; Name + metadata !1, ;; Compile unit + i32 0, ;; Line number + i64 32, ;; Size in bits + i64 32, ;; Align in bits + i64 0, ;; Offset in bits + i32 0, ;; Flags + metadata !6 ;; Derived From type +} ;; ;; Define the int type. ;; -%<a href="#format_basic_type">llvm.dbg.basictype1</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> { - uint add(uint 36, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - 8* getelementptr ([4 x 8]* %str2, int 0, int 0), - { }* null, - int 0, - uint 32, - uint 32, - uint 0, - uint 5 }, section "llvm.metadata" -%str2 = internal constant [4 x 8] c"int\00", section "llvm.metadata" +!6 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"int", ;; Name + metadata !1, ;; Compile unit + i32 0, ;; Line number + i64 32, ;; Size in bits + i64 32, ;; Align in bits + i64 0, ;; Offset in bits + i32 0, ;; Flags + 5 ;; Encoding +} </pre> </div> @@ -1692,86 +1649,88 @@ struct Color { ;; ;; Define basic type for unsigned int. ;; -%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> { - uint add(uint 36, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([13 x i8]* %str1, int 0, int 0), - { }* null, - int 0, - uint 32, - uint 32, - uint 0, - uint 7 }, section "llvm.metadata" -%str1 = internal constant [13 x i8] c"unsigned int\00", section "llvm.metadata" - +!5 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"unsigned int", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 32, ;; Size in Bits + i64 32, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 7 ;; Encoding +} ;; ;; Define composite type for struct Color. ;; -%<a href="#format_composite_type">llvm.dbg.compositetype</a> = internal constant %<a href="#format_composite_type">llvm.dbg.compositetype.type</a> { - uint add(uint 19, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([6 x i8]* %str2, int 0, int 0), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - int 1, - uint 96, - uint 32, - uint 0, - { }* null, - { }* cast ([3 x { }*]* %llvm.dbg.array to { }*) }, section "llvm.metadata" -%str2 = internal constant [6 x i8] c"Color\00", section "llvm.metadata" +!2 = metadata !{ + i32 458771, ;; Tag + metadata !1, ;; Context + metadata !"Color", ;; Name + metadata !1, ;; Compile unit + i32 1, ;; Line number + i64 96, ;; Size in bits + i64 32, ;; Align in bits + i64 0, ;; Offset in bits + i32 0, ;; Flags + null, ;; Derived From + metadata !3, ;; Elements + i32 0 ;; Runtime Language +} ;; ;; Define the Red field. ;; -%<a href="#format_derived_type">llvm.dbg.derivedtype1</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> { - uint add(uint 13, uint 262144), - { }* null, - i8* getelementptr ([4 x i8]* %str3, int 0, int 0), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - int 2, - uint 32, - uint 32, - uint 0, - { }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to { }*) }, section "llvm.metadata" -%str3 = internal constant [4 x i8] c"Red\00", section "llvm.metadata" +!4 = metadata !{ + i32 458765, ;; Tag + metadata !1, ;; Context + metadata !"Red", ;; Name + metadata !1, ;; Compile Unit + i32 2, ;; Line number + i64 32, ;; Size in bits + i64 32, ;; Align in bits + i64 0, ;; Offset in bits + i32 0, ;; Flags + metadata !5 ;; Derived From type +} ;; ;; Define the Green field. ;; -%<a href="#format_derived_type">llvm.dbg.derivedtype2</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> { - uint add(uint 13, uint 262144), - { }* null, - i8* getelementptr ([6 x i8]* %str4, int 0, int 0), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - int 3, - uint 32, - uint 32, - uint 32, - { }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to { }*) }, section "llvm.metadata" -%str4 = internal constant [6 x i8] c"Green\00", section "llvm.metadata" +!6 = metadata !{ + i32 458765, ;; Tag + metadata !1, ;; Context + metadata !"Green", ;; Name + metadata !1, ;; Compile Unit + i32 3, ;; Line number + i64 32, ;; Size in bits + i64 32, ;; Align in bits + i64 32, ;; Offset in bits + i32 0, ;; Flags + metadata !5 ;; Derived From type +} ;; ;; Define the Blue field. ;; -%<a href="#format_derived_type">llvm.dbg.derivedtype3</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> { - uint add(uint 13, uint 262144), - { }* null, - i8* getelementptr ([5 x i8]* %str5, int 0, int 0), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - int 4, - uint 32, - uint 32, - uint 64, - { }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to { }*) }, section "llvm.metadata" -%str5 = internal constant [5 x 8] c"Blue\00", section "llvm.metadata" +!7 = metadata !{ + i32 458765, ;; Tag + metadata !1, ;; Context + metadata !"Blue", ;; Name + metadata !1, ;; Compile Unit + i32 4, ;; Line number + i64 32, ;; Size in bits + i64 32, ;; Align in bits + i64 64, ;; Offset in bits + i32 0, ;; Flags + metadata !5 ;; Derived From type +} ;; ;; Define the array of fields used by the composite type Color. ;; -%llvm.dbg.array = internal constant [3 x { }*] [ - { }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype1</a> to { }*), - { }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype2</a> to { }*), - { }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype3</a> to { }*) ], section "llvm.metadata" +!3 = metadata !{metadata !4, metadata !6, metadata !7} </pre> </div> @@ -1803,53 +1762,41 @@ enum Trees { ;; ;; Define composite type for enum Trees ;; -%<a href="#format_composite_type">llvm.dbg.compositetype</a> = internal constant %<a href="#format_composite_type">llvm.dbg.compositetype.type</a> { - uint add(uint 4, uint 262144), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - i8* getelementptr ([6 x i8]* %str1, int 0, int 0), - { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*), - int 1, - uint 32, - uint 32, - uint 0, - { }* null, - { }* cast ([3 x { }*]* %llvm.dbg.array to { }*) }, section "llvm.metadata" -%str1 = internal constant [6 x i8] c"Trees\00", section "llvm.metadata" +!2 = metadata !{ + i32 458756, ;; Tag + metadata !1, ;; Context + metadata !"Trees", ;; Name + metadata !1, ;; Compile unit + i32 1, ;; Line number + i64 32, ;; Size in bits + i64 32, ;; Align in bits + i64 0, ;; Offset in bits + i32 0, ;; Flags + null, ;; Derived From type + metadata !3, ;; Elements + i32 0 ;; Runtime language +} + +;; +;; Define the array of enumerators used by composite type Trees. +;; +!3 = metadata !{metadata !4, metadata !5, metadata !6} ;; ;; Define Spruce enumerator. ;; -%<a href="#format_enumeration">llvm.dbg.enumerator1</a> = internal constant %<a href="#format_enumeration">llvm.dbg.enumerator.type</a> { - uint add(uint 40, uint 262144), - i8* getelementptr ([7 x i8]* %str2, int 0, int 0), - int 100 }, section "llvm.metadata" -%str2 = internal constant [7 x i8] c"Spruce\00", section "llvm.metadata" +!4 = metadata !{i32 458792, metadata !"Spruce", i64 100} ;; ;; Define Oak enumerator. ;; -%<a href="#format_enumeration">llvm.dbg.enumerator2</a> = internal constant %<a href="#format_enumeration">llvm.dbg.enumerator.type</a> { - uint add(uint 40, uint 262144), - i8* getelementptr ([4 x i8]* %str3, int 0, int 0), - int 200 }, section "llvm.metadata" -%str3 = internal constant [4 x i8] c"Oak\00", section "llvm.metadata" +!5 = metadata !{i32 458792, metadata !"Oak", i64 200} ;; ;; Define Maple enumerator. ;; -%<a href="#format_enumeration">llvm.dbg.enumerator3</a> = internal constant %<a href="#format_enumeration">llvm.dbg.enumerator.type</a> { - uint add(uint 40, uint 262144), - i8* getelementptr ([6 x i8]* %str4, int 0, int 0), - int 300 }, section "llvm.metadata" -%str4 = internal constant [6 x i8] c"Maple\00", section "llvm.metadata" +!6 = metadata !{i32 458792, metadata !"Maple", i64 300} -;; -;; Define the array of enumerators used by composite type Trees. -;; -%llvm.dbg.array = internal constant [3 x { }*] [ - { }* cast (%<a href="#format_enumeration">llvm.dbg.enumerator.type</a>* %<a href="#format_enumeration">llvm.dbg.enumerator1</a> to { }*), - { }* cast (%<a href="#format_enumeration">llvm.dbg.enumerator.type</a>* %<a href="#format_enumeration">llvm.dbg.enumerator2</a> to { }*), - { }* cast (%<a href="#format_enumeration">llvm.dbg.enumerator.type</a>* %<a href="#format_enumeration">llvm.dbg.enumerator3</a> to { }*) ], section "llvm.metadata" </pre> </div> @@ -1866,7 +1813,7 @@ enum Trees { <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-06-26 03:49:18 +0200 (Fri, 26 Jun 2009) $ + Last modified: $Date: 2009-10-12 16:46:08 +0200 (Mon, 12 Oct 2009) $ </address> </body> diff --git a/docs/SystemLibrary.html b/docs/SystemLibrary.html index c4e85d1..aca7e5d 100644 --- a/docs/SystemLibrary.html +++ b/docs/SystemLibrary.html @@ -23,7 +23,6 @@ <li><a href="#nounused">No Unused Functionality</a></li> <li><a href="#virtuals">No Virtual Methods</a></li> <li><a href="#softerrors">Minimize Soft Errors</a></li> - <li><a href="#throw">Throw Only std::string</a></li> <li><a href="#throw_spec">No throw() Specifications</a></li> <li><a href="#organization">Code Organization</a></li> <li><a href="#semantics">Consistent Semantics</a></li> @@ -76,7 +75,7 @@ </div> <!-- ======================================================================= --> -<div class="doc_subsection"><a name="headers">Don't Inlcude System Headers</a> +<div class="doc_subsection"><a name="headers">Don't Include System Headers</a> </div> <div class="doc_text"> <p>Except in <tt>lib/System</tt>, no LLVM source code should directly @@ -211,8 +210,8 @@ "out of space", "bad disk sector", or "system call interrupted". We'll call the first group "<i>soft</i>" errors and the second group "<i>hard</i>" errors.<p> - <p>lib/System must always attempt to minimize soft errors and always just - throw a std::string on hard errors. This is a design requirement because the + <p>lib/System must always attempt to minimize soft errors. + This is a design requirement because the minimization of soft errors can affect the granularity and the nature of the interface. In general, if you find that you're wanting to throw soft errors, you must review the granularity of the interface because it is likely you're @@ -240,31 +239,6 @@ </div> <!-- ======================================================================= --> -<div class="doc_subsection"><a name="throw">Throw Only std::string</a></div> -<div class="doc_text"> - <p>If an error occurs that lib/System cannot handle, the only action taken by - lib/System is to throw an instance of std:string. The contents of the string - must explain both what happened and the context in which it happened. The - format of the string should be a (possibly empty) list of contexts each - terminated with a : and a space, followed by the error message, optionally - followed by a reason, and optionally followed by a suggestion.</p> - <p>For example, failure to open a file named "foo" could result in a message - like:</p> - <ul><li>foo: Unable to open file because it doesn't exist."</li></ul> - <p>The "foo:" part is the context. The "Unable to open file" part is the error - message. The "because it doesn't exist." part is the reason. This message has - no suggestion. Where possible, the implementation of lib/System should use - operating system specific facilities for converting the error code returned by - a system call into an error message. This will help to make the error message - more familiar to users of that type of operating system.</p> - <p>Note that this requirement precludes the throwing of any other exceptions. - For example, various C++ standard library functions can cause exceptions to be - thrown (e.g. out of memory situation). In all cases, if there is a possibility - that non-string exceptions could be thrown, the lib/System library must ensure - that the exceptions are translated to std::string form.</p> -</div> - -<!-- ======================================================================= --> <div class="doc_subsection"><a name="throw_spec">No throw Specifications</a> </div> <div class="doc_text"> @@ -273,7 +247,8 @@ compiler does not insert additional exception handling code into the interface functions. This is a performance consideration: lib/System functions are at the bottom of many call chains and as such can be frequently called. We - need them to be as efficient as possible.</p> + need them to be as efficient as possible. However, no routines in the + system library should actually throw exceptions.</p> </div> <!-- ======================================================================= --> @@ -338,7 +313,7 @@ <a href="mailto:rspencer@x10sys.com">Reid Spencer</a><br> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2008-12-11 18:34:48 +0100 (Thu, 11 Dec 2008) $ + Last modified: $Date: 2009-07-17 23:11:24 +0200 (Fri, 17 Jul 2009) $ </address> </body> </html> diff --git a/docs/TableGenFundamentals.html b/docs/TableGenFundamentals.html index 568b572..7ae1ca4 100644 --- a/docs/TableGenFundamentals.html +++ b/docs/TableGenFundamentals.html @@ -371,8 +371,8 @@ supported include:</p> <dd>string value</dd> <dt><tt>[{ ... }]</tt></dt> <dd>code fragment</dd> -<dt><tt>[ X, Y, Z ]<type></tt></dt> - <dd>list value. <type> is the type of the list +<dt><tt>[ X, Y, Z ]<type></tt></dt> + <dd>list value. <type> is the type of the list element and is usually optional. In rare cases, TableGen is unable to deduce the element type in which case the user must specify it explicitly.</dd> @@ -398,23 +398,16 @@ which case the user must specify it explicitly.</dd> <dd>a dag value. The first element is required to be a record definition, the remaining elements in the list may be arbitrary other values, including nested `<tt>dag</tt>' values.</dd> -<dt><tt>(implicit a)</tt></dt> - <dd>an implicitly defined physical register. This tells the dag instruction - selection emitter the input pattern's extra definitions matches implicit - physical register definitions.</dd> -<dt><tt>(parallel (a), (b))</tt></dt> - <dd>a list of dags specifying parallel operations which map to the same - instruction.</dd> <dt><tt>!strconcat(a, b)</tt></dt> <dd>A string value that is the result of concatenating the 'a' and 'b' strings.</dd> -<dt><tt>!cast<type>(a)</tt></dt> +<dt><tt>!cast<type>(a)</tt></dt> <dd>A symbol of type <em>type</em> obtained by looking up the string 'a' in the symbol table. If the type of 'a' does not match <em>type</em>, TableGen -aborts with an error. !cast<string> is a special case in that the argument must +aborts with an error. !cast<string> is a special case in that the argument must be an object defined by a 'def' construct.</dd> <dt><tt>!nameconcat<type>(a, b)</tt></dt> - <dd>Shorthand for !cast<type>(!strconcat(a, b))</dd> + <dd>Shorthand for !cast<type>(!strconcat(a, b))</dd> <dt><tt>!subst(a, b, c)</tt></dt> <dd>If 'a' and 'b' are of string type or are symbol references, substitute 'b' for 'a' in 'c.' This operation is analogous to $(subst) in GNU make.</dd> @@ -760,6 +753,25 @@ opened, as in the case with the <tt>CALL*</tt> instructions above.</p> </div> <!-- *********************************************************************** --> +<div class="doc_section"><a name="codegen">Code Generator backend info</a></div> +<!-- *********************************************************************** --> + +<p>Expressions used by code generator to describe instructions and isel +patterns:</p> + +<div class="doc_text"> + +<dt><tt>(implicit a)</tt></dt> + <dd>an implicitly defined physical register. This tells the dag instruction + selection emitter the input pattern's extra definitions matches implicit + physical register definitions.</dd> +<dt><tt>(parallel (a), (b))</tt></dt> + <dd>a list of dags specifying parallel operations which map to the same + instruction.</dd> + +</div> + +<!-- *********************************************************************** --> <div class="doc_section"><a name="backends">TableGen backends</a></div> <!-- *********************************************************************** --> @@ -782,7 +794,7 @@ This should highlight the APIs in <tt>TableGen/Record.h</tt>.</p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-06-29 22:05:29 +0200 (Mon, 29 Jun 2009) $ + Last modified: $Date: 2009-10-05 04:51:06 +0200 (Mon, 05 Oct 2009) $ </address> </body> diff --git a/docs/TestingGuide.html b/docs/TestingGuide.html index 32b16ca..4f05d77 100644 --- a/docs/TestingGuide.html +++ b/docs/TestingGuide.html @@ -29,6 +29,7 @@ <li><a href="#dgstructure">DejaGNU structure</a> <ul> <li><a href="#dgcustom">Writing new DejaGNU tests</a></li> + <li><a href="#FileCheck">The FileCheck utility</a></li> <li><a href="#dgvars">Variables and substitutions</a></li> <li><a href="#dgfeatures">Other features</a></li> </ul> @@ -448,7 +449,257 @@ negatives).</p> </div> <!-- _______________________________________________________________________ --> -<div class="doc_subsection"><a name="dgvars">Variables and substitutions</a></div> +<div class="doc_subsection"><a name="FileCheck">The FileCheck utility</a></div> +<!-- _______________________________________________________________________ --> + +<div class="doc_text"> + +<p>A powerful feature of the RUN: lines is that it allows any arbitrary commands + to be executed as part of the test harness. While standard (portable) unix + tools like 'grep' work fine on run lines, as you see above, there are a lot + of caveats due to interaction with Tcl syntax, and we want to make sure the + run lines are portable to a wide range of systems. Another major problem is + that grep is not very good at checking to verify that the output of a tools + contains a series of different output in a specific order. The FileCheck + tool was designed to help with these problems.</p> + +<p>FileCheck (whose basic command line arguments are described in <a + href="http://llvm.org/cmds/FileCheck.html">the FileCheck man page</a> is + designed to read a file to check from standard input, and the set of things + to verify from a file specified as a command line argument. A simple example + of using FileCheck from a RUN line looks like this:</p> + +<div class="doc_code"> +<pre> +; RUN: llvm-as < %s | llc -march=x86-64 | <b>FileCheck %s</b> +</pre> +</div> + +<p>This syntax says to pipe the current file ("%s") into llvm-as, pipe that into +llc, then pipe the output of llc into FileCheck. This means that FileCheck will +be verifying its standard input (the llc output) against the filename argument +specified (the original .ll file specified by "%s"). To see how this works, +lets look at the rest of the .ll file (after the RUN line):</p> + +<div class="doc_code"> +<pre> +define void @sub1(i32* %p, i32 %v) { +entry: +; <b>CHECK: sub1:</b> +; <b>CHECK: subl</b> + %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v) + ret void +} + +define void @inc4(i64* %p) { +entry: +; <b>CHECK: inc4:</b> +; <b>CHECK: incq</b> + %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1) + ret void +} +</pre> +</div> + +<p>Here you can see some "CHECK:" lines specified in comments. Now you can see +how the file is piped into llvm-as, then llc, and the machine code output is +what we are verifying. FileCheck checks the machine code output to verify that +it matches what the "CHECK:" lines specify.</p> + +<p>The syntax of the CHECK: lines is very simple: they are fixed strings that +must occur in order. FileCheck defaults to ignoring horizontal whitespace +differences (e.g. a space is allowed to match a tab) but otherwise, the contents +of the CHECK: line is required to match some thing in the test file exactly.</p> + +<p>One nice thing about FileCheck (compared to grep) is that it allows merging +test cases together into logical groups. For example, because the test above +is checking for the "sub1:" and "inc4:" labels, it will not match unless there +is a "subl" in between those labels. If it existed somewhere else in the file, +that would not count: "grep subl" matches if subl exists anywhere in the +file.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"><a +name="FileCheck-check-prefix">The FileCheck -check-prefix option</a></div> + +<div class="doc_text"> + +<p>The FileCheck -check-prefix option allows multiple test configurations to be +driven from one .ll file. This is useful in many circumstances, for example, +testing different architectural variants with llc. Here's a simple example:</p> + +<div class="doc_code"> +<pre> +; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \ +; RUN: | <b>FileCheck %s -check-prefix=X32</b> +; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \ +; RUN: | <b>FileCheck %s -check-prefix=X64</b> + +define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind { + %tmp1 = insertelement <4 x i32> %tmp, i32 %s, i32 1 + ret <4 x i32> %tmp1 +; <b>X32:</b> pinsrd_1: +; <b>X32:</b> pinsrd $1, 4(%esp), %xmm0 + +; <b>X64:</b> pinsrd_1: +; <b>X64:</b> pinsrd $1, %edi, %xmm0 +} +</pre> +</div> + +<p>In this case, we're testing that we get the expected code generation with +both 32-bit and 64-bit code generation.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"><a +name="FileCheck-CHECK-NEXT">The "CHECK-NEXT:" directive</a></div> + +<div class="doc_text"> + +<p>Sometimes you want to match lines and would like to verify that matches +happen on exactly consequtive lines with no other lines in between them. In +this case, you can use CHECK: and CHECK-NEXT: directives to specify this. If +you specified a custom check prefix, just use "<PREFIX>-NEXT:". For +example, something like this works as you'd expect:</p> + +<div class="doc_code"> +<pre> +define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) { + %tmp3 = load <2 x double>* %A, align 16 + %tmp7 = insertelement <2 x double> undef, double %B, i32 0 + %tmp9 = shufflevector <2 x double> %tmp3, + <2 x double> %tmp7, + <2 x i32> < i32 0, i32 2 > + store <2 x double> %tmp9, <2 x double>* %r, align 16 + ret void + +; <b>CHECK:</b> t2: +; <b>CHECK:</b> movl 8(%esp), %eax +; <b>CHECK-NEXT:</b> movapd (%eax), %xmm0 +; <b>CHECK-NEXT:</b> movhpd 12(%esp), %xmm0 +; <b>CHECK-NEXT:</b> movl 4(%esp), %eax +; <b>CHECK-NEXT:</b> movapd %xmm0, (%eax) +; <b>CHECK-NEXT:</b> ret +} +</pre> +</div> + +<p>CHECK-NEXT: directives reject the input unless there is exactly one newline +between it an the previous directive. A CHECK-NEXT cannot be the first +directive in a file.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"><a +name="FileCheck-CHECK-NOT">The "CHECK-NOT:" directive</a></div> + +<div class="doc_text"> + +<p>The CHECK-NOT: directive is used to verify that a string doesn't occur +between two matches (or the first match and the beginning of the file). For +example, to verify that a load is removed by a transformation, a test like this +can be used:</p> + +<div class="doc_code"> +<pre> +define i8 @coerce_offset0(i32 %V, i32* %P) { + store i32 %V, i32* %P + + %P2 = bitcast i32* %P to i8* + %P3 = getelementptr i8* %P2, i32 2 + + %A = load i8* %P3 + ret i8 %A +; <b>CHECK:</b> @coerce_offset0 +; <b>CHECK-NOT:</b> load +; <b>CHECK:</b> ret i8 +} +</pre> +</div> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"><a +name="FileCheck-Matching">FileCheck Pattern Matching Syntax</a></div> + +<div class="doc_text"> + +<p>The CHECK: and CHECK-NOT: directives both take a pattern to match. For most +uses of FileCheck, fixed string matching is perfectly sufficient. For some +things, a more flexible form of matching is desired. To support this, FileCheck +allows you to specify regular expressions in matching strings, surrounded by +double braces: <b>{{yourregex}}</b>. Because we want to use fixed string +matching for a majority of what we do, FileCheck has been designed to support +mixing and matching fixed string matching with regular expressions. This allows +you to write things like this:</p> + +<div class="doc_code"> +<pre> +; CHECK: movhpd <b>{{[0-9]+}}</b>(%esp), <b>{{%xmm[0-7]}}</b> +</pre> +</div> + +<p>In this case, any offset from the ESP register will be allowed, and any xmm +register will be allowed.</p> + +<p>Because regular expressions are enclosed with double braces, they are +visually distinct, and you don't need to use escape characters within the double +braces like you would in C. In the rare case that you want to match double +braces explicitly from the input, you can use something ugly like +<b>{{[{][{]}}</b> as your pattern.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"><a +name="FileCheck-Variables">FileCheck Variables</a></div> + +<div class="doc_text"> + +<p>It is often useful to match a pattern and then verify that it occurs again +later in the file. For codegen tests, this can be useful to allow any register, +but verify that that register is used consistently later. To do this, FileCheck +allows named variables to be defined and substituted into patterns. Here is a +simple example:</p> + +<div class="doc_code"> +<pre> +; CHECK: test5: +; CHECK: notw <b>[[REGISTER:%[a-z]+]]</b> +; CHECK: andw {{.*}}<b>[[REGISTER]]</b> +</pre> +</div> + +<p>The first check line matches a regex (<tt>%[a-z]+</tt>) and captures it into +the variables "REGISTER". The second line verifies that whatever is in REGISTER +occurs later in the file after an "andw". FileCheck variable references are +always contained in <tt>[[ ]]</tt> pairs, are named, and their names can be +formed with the regex "<tt>[a-zA-Z][a-zA-Z0-9]*</tt>". If a colon follows the +name, then it is a definition of the variable, if not, it is a use.</p> + +<p>FileCheck variables can be defined multiple times, and uses always get the +latest value. Note that variables are all read at the start of a "CHECK" line +and are all defined at the end. This means that if you have something like +"<tt>CHECK: [[XYZ:.*]]x[[XYZ]]</tt>" that the check line will read the previous +value of the XYZ variable and define a new one after the match is performed. If +you need to do something like this you can probably take advantage of the fact +that FileCheck is not actually line-oriented when it matches, this allows you to +define two separate CHECK lines that match on the same line. +</p> + + + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsection"><a name="dgvars">Variables and +substitutions</a></div> <!-- _______________________________________________________________________ --> <div class="doc_text"> <p>With a RUN line there are a number of substitutions that are permitted. In @@ -502,14 +753,6 @@ negatives).</p> <dd>The target triplet that corresponds to the current host machine (the one running the test cases). This should probably be called "host".<dd> - <dt><b>prcontext</b> (%prcontext)</dt> - <dd>Path to the prcontext tcl script that prints some context around a - line that matches a pattern. This isn't strictly necessary as the test suite - is run with its PATH altered to include the test/Scripts directory where - the prcontext script is located. Note that this script is similar to - <tt>grep -C</tt> but you should use the <tt>prcontext</tt> script because - not all platforms support <tt>grep -C</tt>.</dd> - <dt><b>llvmgcc</b> (%llvmgcc)</dt> <dd>The full path to the <tt>llvm-gcc</tt> executable as specified in the configured LLVM environment</dd> @@ -974,7 +1217,7 @@ know. Thanks!</p> John T. Criswell, Reid Spencer, and Tanya Lattner<br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-06-26 07:44:53 +0200 (Fri, 26 Jun 2009) $ + Last modified: $Date: 2009-09-27 10:01:44 +0200 (Sun, 27 Sep 2009) $ </address> </body> </html> diff --git a/docs/UsingLibraries.html b/docs/UsingLibraries.html index 7458eca..c6bcaf0 100644 --- a/docs/UsingLibraries.html +++ b/docs/UsingLibraries.html @@ -128,8 +128,6 @@ <td>Code generation for ARM architecture</td></tr> <tr><td>LLVMCBackend</td><td><tt>.o</tt></td> <td>'C' language code generator.</td></tr> - <tr><td>LLVMIA64</td><td><tt>.o</tt></td> - <td>Code generation for IA64 architecture</td></tr> <tr><td>LLVMPowerPC</td><td><tt>.o</tt></td> <td>Code generation for PowerPC architecture</td></tr> <tr><td>LLVMSparc</td><td><tt>.o</tt></td> @@ -356,14 +354,6 @@ <li>libLLVMSystem.a</li> <li>libLLVMTarget.a</li> </ul></dd> - <dt><b>LLVMIA64.o</b></dt><dd><ul> - <li>libLLVMCodeGen.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMSelectionDAG.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - </ul></dd> <dt><b>LLVMInterpreter.o</b></dt><dd><ul> <li>LLVMExecutionEngine.o</li> <li>libLLVMCodeGen.a</li> @@ -442,7 +432,7 @@ <a href="mailto:rspencer@x10sys.com">Reid Spencer</a> </address> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a> -<br>Last modified: $Date: 2008-12-11 19:23:24 +0100 (Thu, 11 Dec 2008) $ </div> +<br>Last modified: $Date: 2009-07-24 02:30:09 +0200 (Fri, 24 Jul 2009) $ </div> </body> </html> <!-- vim: sw=2 ts=2 ai diff --git a/docs/WritingAnLLVMBackend.html b/docs/WritingAnLLVMBackend.html index 8016283..5a95185 100644 --- a/docs/WritingAnLLVMBackend.html +++ b/docs/WritingAnLLVMBackend.html @@ -22,6 +22,7 @@ <li><a href="#Preliminaries">Preliminaries</a></li> </ul> <li><a href="#TargetMachine">Target Machine</a></li> + <li><a href="#TargetRegistration">Target Registration</a></li> <li><a href="#RegisterSet">Register Set and Register Classes</a> <ul> <li><a href="#RegisterDef">Defining a Register</a></li> @@ -422,21 +423,62 @@ SparcTargetMachine::SparcTargetMachine(const Module &M, const std::string &a alignment, and then ABI preferred alignment.</li> </ul> +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="TargetRegistration">Target Registration</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p> +You must also register your target with the <tt>TargetRegistry</tt>, which is +what other LLVM tools use to be able to lookup and use your target at +runtime. The <tt>TargetRegistry</tt> can be used directly, but for most targets +there are helper templates which should take care of the work for you.</p> + +<p> +All targets should declare a global <tt>Target</tt> object which is used to +represent the target during registration. Then, in the target's TargetInfo +library, the target should define that object and use +the <tt>RegisterTarget</tt> template to register the target. For example, the Sparc registration code looks like this: +</p> + +<div class="doc_code"> +<pre> +Target llvm::TheSparcTarget; + +extern "C" void LLVMInitializeSparcTargetInfo() { + RegisterTarget<Triple::sparc, /*HasJIT=*/false> + X(TheSparcTarget, "sparc", "Sparc"); +} +</pre> +</div> + <p> -You must also register your target using the <tt>RegisterTarget</tt> -template. (See the <tt>TargetMachineRegistry</tt> class.) For example, -in <tt>SparcTargetMachine.cpp</tt>, the target is registered with: +This allows the <tt>TargetRegistry</tt> to look up the target by name or by +target triple. In addition, most targets will also register additional features +which are available in separate libraries. These registration steps are +separate, because some clients may wish to only link in some parts of the target +-- the JIT code generator does not require the use of the assembler printer, for +example. Here is an example of registering the Sparc assembly printer: </p> <div class="doc_code"> <pre> -namespace { - // Register the target. - RegisterTarget<SparcTargetMachine>X("sparc", "SPARC"); +extern "C" void LLVMInitializeSparcAsmPrinter() { + RegisterAsmPrinter<SparcAsmPrinter> X(TheSparcTarget); } </pre> </div> +<p> +For more information, see +"<a href="/doxygen/TargetRegistry_8h-source.html">llvm/Target/TargetRegistry.h</a>". +</p> + </div> <!-- *********************************************************************** --> @@ -2038,8 +2080,8 @@ SparcTargetAsmInfo::SparcTargetAsmInfo(const SparcTargetMachine &TM) { <p> The X86 assembly printer implementation (<tt>X86TargetAsmInfo</tt>) is an -example where the target specific <tt>TargetAsmInfo</tt> class uses overridden -methods: <tt>ExpandInlineAsm</tt> and <tt>PreferredEHDataFormat</tt>. +example where the target specific <tt>TargetAsmInfo</tt> class uses an +overridden methods: <tt>ExpandInlineAsm</tt>. </p> <p> @@ -2122,9 +2164,7 @@ in <tt>XXXGenAsmWriter.inc</tt> contains an implementation of the The implementations of <tt>printDeclare</tt>, <tt>printImplicitDef</tt>, <tt>printInlineAsm</tt>, and <tt>printLabel</tt> in <tt>AsmPrinter.cpp</tt> are generally adequate for printing assembly and do not need to be -overridden. (<tt>printBasicBlockLabel</tt> is another method that is implemented -in <tt>AsmPrinter.cpp</tt> that may be directly used in an implementation of -<tt>XXXAsmPrinter</tt>.) +overridden. </p> <p> @@ -2523,7 +2563,7 @@ with assembler. <a href="http://www.woo.com">Mason Woo</a> and <a href="http://misha.brukman.net">Misha Brukman</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a> <br> - Last modified: $Date: 2009-04-05 02:44:06 +0200 (Sun, 05 Apr 2009) $ + Last modified: $Date: 2009-09-13 00:57:37 +0200 (Sun, 13 Sep 2009) $ </address> </body> diff --git a/docs/WritingAnLLVMPass.html b/docs/WritingAnLLVMPass.html index dd8b41d..218f8ef 100644 --- a/docs/WritingAnLLVMPass.html +++ b/docs/WritingAnLLVMPass.html @@ -179,7 +179,7 @@ source tree in the <tt>lib/Transforms/Hello</tt> directory.</p> <div class="doc_code"><pre> # Makefile for hello pass -# Path to top level of LLVM heirarchy +# Path to top level of LLVM hierarchy LEVEL = ../../.. # Name of the library to build @@ -223,12 +223,14 @@ Start out with:</p> <div class="doc_code"><pre> <b>#include</b> "<a href="http://llvm.org/doxygen/Pass_8h-source.html">llvm/Pass.h</a>" <b>#include</b> "<a href="http://llvm.org/doxygen/Function_8h-source.html">llvm/Function.h</a>" +<b>#include</b> "<a href="http://llvm.org/doxygen/raw__ostream_8h.html">llvm/Support/raw_ostream.h</a>" </pre></div> <p>Which are needed because we are writing a <tt><a -href="http://llvm.org/doxygen/classllvm_1_1Pass.html">Pass</a></tt>, and +href="http://llvm.org/doxygen/classllvm_1_1Pass.html">Pass</a></tt>, we are operating on <tt><a -href="http://llvm.org/doxygen/classllvm_1_1Function.html">Function</a></tt>'s.</p> +href="http://llvm.org/doxygen/classllvm_1_1Function.html">Function</a></tt>'s, +and we will be doing some printing.</p> <p>Next we have:</p> <div class="doc_code"><pre> @@ -273,7 +275,7 @@ avoid using expensive C++ runtime information.</p> <div class="doc_code"><pre> <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) { - llvm::cerr << "<i>Hello: </i>" << F.getName() << "\n"; + errs() << "<i>Hello: </i>" << F.getName() << "\n"; <b>return false</b>; } }; <i>// end of struct Hello</i> @@ -312,6 +314,7 @@ is supplied as fourth argument. </p> <div class="doc_code"><pre> <b>#include</b> "<a href="http://llvm.org/doxygen/Pass_8h-source.html">llvm/Pass.h</a>" <b>#include</b> "<a href="http://llvm.org/doxygen/Function_8h-source.html">llvm/Function.h</a>" +<b>#include</b> "<a href="http://llvm.org/doxygen/raw__ostream_8h.html">llvm/Support/raw_ostream.h</a>" <b>using namespace llvm;</b> @@ -322,7 +325,7 @@ is supplied as fourth argument. </p> Hello() : FunctionPass(&ID) {} <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) { - llvm::cerr << "<i>Hello: </i>" << F.getName() << "\n"; + errs() << "<i>Hello: </i>" << F.getName() << "\n"; <b>return false</b>; } }; @@ -450,7 +453,7 @@ available, from the most general to the most specific.</p> <p>When choosing a superclass for your Pass, you should choose the <b>most specific</b> class possible, while still being able to meet the requirements listed. This gives the LLVM Pass Infrastructure information necessary to -optimize how passes are run, so that the resultant compiler isn't unneccesarily +optimize how passes are run, so that the resultant compiler isn't unnecessarily slow.</p> </div> @@ -489,7 +492,7 @@ invalidated, and are never "run".</p> href="http://llvm.org/doxygen/classllvm_1_1ModulePass.html">ModulePass</a></tt>" class is the most general of all superclasses that you can use. Deriving from <tt>ModulePass</tt> indicates that your pass uses the entire program as a unit, -refering to function bodies in no predictable order, or adding and removing +referring to function bodies in no predictable order, or adding and removing functions. Because nothing is known about the behavior of <tt>ModulePass</tt> subclasses, no optimization can be done for their execution.</p> @@ -497,7 +500,7 @@ subclasses, no optimization can be done for their execution.</p> the getAnalysis interface <tt>getAnalysis<DominatorTree>(llvm::Function *)</tt> to provide the function to retrieve analysis result for, if the function pass does not require -any module passes. Note that this can only be done for functions for which the +any module or immutable passes. Note that this can only be done for functions for which the analysis ran, e.g. in the case of dominators you should only ask for the DominatorTree for function definitions, not declarations.</p> @@ -1826,7 +1829,7 @@ Despite that, we have kept the LLVM passes SMP ready, and you should too.</p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-07-02 01:38:44 +0200 (Thu, 02 Jul 2009) $ + Last modified: $Date: 2009-10-12 16:46:08 +0200 (Mon, 12 Oct 2009) $ </address> </body> diff --git a/docs/index.html b/docs/index.html index 00d48ae..36ed0e2 100644 --- a/docs/index.html +++ b/docs/index.html @@ -41,13 +41,13 @@ <ul> <li><a href="LangRef.html">LLVM Language Reference Manual</a> - Defines the LLVM intermediate representation.</li> -<li><a href="http://llvm.org/pubs/2006-04-25-GelatoLLVMIntro.html">Introduction to the LLVM Compiler Infrastructure</a> - Presentation describing LLVM.</li> +<li><a href="http://llvm.org/pubs/2008-10-04-ACAT-LLVM-Intro.html">Introduction to the LLVM Compiler </a> - Presentation describing LLVM.</li> <li><a href="http://llvm.org/pubs/2004-09-22-LCPCLLVMTutorial.html">The LLVM Compiler Framework and Infrastructure Tutorial</a> - Tutorial for writing passes, exploring the system.</li> <li><a href="http://llvm.org/pubs/2004-01-30-CGO-LLVM.html">LLVM: A Compilation Framework for Lifelong Program Analysis & Transformation</a> - Design overview.</li> <li><a href="http://llvm.org/pubs/2002-12-LattnerMSThesis.html">LLVM: An Infrastructure for -Multi-Stage Optimization</a> - More details (somewhat old now).</li> +Multi-Stage Optimization</a> - More details (quite old now).</li> <li><a href="GetElementPtr.html">GetElementPtr FAQ</a> - Answers to some very frequent questions about LLVM's most frequently misunderstood instruction.</li> </ul> @@ -233,6 +233,9 @@ the linker and its design</li> <li><a href="GoldPlugin.html">The LLVM gold plugin</a> - How to build your programs with link-time optimization on Linux.</li> + +<li><a href="DebuggingJITedCode.html">The GDB JIT interface</a> - How to debug +JITed code with GDB.</li> </ul> @@ -278,7 +281,7 @@ times each day, making it a high volume list.</li> src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-03-02 00:42:51 +0100 (Mon, 02 Mar 2009) $ + Last modified: $Date: 2009-09-21 04:34:59 +0200 (Mon, 21 Sep 2009) $ </address> </body></html> diff --git a/docs/re_format.7 b/docs/re_format.7 new file mode 100644 index 0000000..0c09287 --- /dev/null +++ b/docs/re_format.7 @@ -0,0 +1,756 @@ +.\" $OpenBSD: re_format.7,v 1.14 2007/05/31 19:19:30 jmc Exp $ +.\" +.\" Copyright (c) 1997, Phillip F Knaack. All rights reserved. +.\" +.\" Copyright (c) 1992, 1993, 1994 Henry Spencer. +.\" Copyright (c) 1992, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Henry Spencer. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)re_format.7 8.3 (Berkeley) 3/20/94 +.\" +.Dd $Mdocdate: May 31 2007 $ +.Dt RE_FORMAT 7 +.Os +.Sh NAME +.Nm re_format +.Nd POSIX regular expressions +.Sh DESCRIPTION +Regular expressions (REs), +as defined in +.St -p1003.1-2004 , +come in two forms: +basic regular expressions +(BREs) +and extended regular expressions +(EREs). +Both forms of regular expressions are supported +by the interfaces described in +.Xr regex 3 . +Applications dealing with regular expressions +may use one or the other form +(or indeed both). +For example, +.Xr ed 1 +uses BREs, +whilst +.Xr egrep 1 +talks EREs. +Consult the manual page for the specific application to find out which +it uses. +.Pp +POSIX leaves some aspects of RE syntax and semantics open; +.Sq ** +marks decisions on these aspects that +may not be fully portable to other POSIX implementations. +.Pp +This manual page first describes regular expressions in general, +specifically extended regular expressions, +and then discusses differences between them and basic regular expressions. +.Sh EXTENDED REGULAR EXPRESSIONS +An ERE is one** or more non-empty** +.Em branches , +separated by +.Sq \*(Ba . +It matches anything that matches one of the branches. +.Pp +A branch is one** or more +.Em pieces , +concatenated. +It matches a match for the first, followed by a match for the second, etc. +.Pp +A piece is an +.Em atom +possibly followed by a single** +.Sq * , +.Sq + , +.Sq ?\& , +or +.Em bound . +An atom followed by +.Sq * +matches a sequence of 0 or more matches of the atom. +An atom followed by +.Sq + +matches a sequence of 1 or more matches of the atom. +An atom followed by +.Sq ?\& +matches a sequence of 0 or 1 matches of the atom. +.Pp +A bound is +.Sq { +followed by an unsigned decimal integer, +possibly followed by +.Sq ,\& +possibly followed by another unsigned decimal integer, +always followed by +.Sq } . +The integers must lie between 0 and +.Dv RE_DUP_MAX +(255**) inclusive, +and if there are two of them, the first may not exceed the second. +An atom followed by a bound containing one integer +.Ar i +and no comma matches +a sequence of exactly +.Ar i +matches of the atom. +An atom followed by a bound +containing one integer +.Ar i +and a comma matches +a sequence of +.Ar i +or more matches of the atom. +An atom followed by a bound +containing two integers +.Ar i +and +.Ar j +matches a sequence of +.Ar i +through +.Ar j +(inclusive) matches of the atom. +.Pp +An atom is a regular expression enclosed in +.Sq () +(matching a part of the regular expression), +an empty set of +.Sq () +(matching the null string)**, +a +.Em bracket expression +(see below), +.Sq .\& +(matching any single character), +.Sq ^ +(matching the null string at the beginning of a line), +.Sq $ +(matching the null string at the end of a line), +a +.Sq \e +followed by one of the characters +.Sq ^.[$()|*+?{\e +(matching that character taken as an ordinary character), +a +.Sq \e +followed by any other character** +(matching that character taken as an ordinary character, +as if the +.Sq \e +had not been present**), +or a single character with no other significance (matching that character). +A +.Sq { +followed by a character other than a digit is an ordinary character, +not the beginning of a bound**. +It is illegal to end an RE with +.Sq \e . +.Pp +A bracket expression is a list of characters enclosed in +.Sq [] . +It normally matches any single character from the list (but see below). +If the list begins with +.Sq ^ , +it matches any single character +.Em not +from the rest of the list +(but see below). +If two characters in the list are separated by +.Sq - , +this is shorthand for the full +.Em range +of characters between those two (inclusive) in the +collating sequence, e.g.\& +.Sq [0-9] +in ASCII matches any decimal digit. +It is illegal** for two ranges to share an endpoint, e.g.\& +.Sq a-c-e . +Ranges are very collating-sequence-dependent, +and portable programs should avoid relying on them. +.Pp +To include a literal +.Sq ]\& +in the list, make it the first character +(following a possible +.Sq ^ ) . +To include a literal +.Sq - , +make it the first or last character, +or the second endpoint of a range. +To use a literal +.Sq - +as the first endpoint of a range, +enclose it in +.Sq [. +and +.Sq .] +to make it a collating element (see below). +With the exception of these and some combinations using +.Sq [ +(see next paragraphs), +all other special characters, including +.Sq \e , +lose their special significance within a bracket expression. +.Pp +Within a bracket expression, a collating element +(a character, +a multi-character sequence that collates as if it were a single character, +or a collating-sequence name for either) +enclosed in +.Sq [. +and +.Sq .] +stands for the sequence of characters of that collating element. +The sequence is a single element of the bracket expression's list. +A bracket expression containing a multi-character collating element +can thus match more than one character, +e.g. if the collating sequence includes a +.Sq ch +collating element, +then the RE +.Sq [[.ch.]]*c +matches the first five characters of +.Sq chchcc . +.Pp +Within a bracket expression, a collating element enclosed in +.Sq [= +and +.Sq =] +is an equivalence class, standing for the sequences of characters +of all collating elements equivalent to that one, including itself. +(If there are no other equivalent collating elements, +the treatment is as if the enclosing delimiters were +.Sq [. +and +.Sq .] . ) +For example, if +.Sq x +and +.Sq y +are the members of an equivalence class, +then +.Sq [[=x=]] , +.Sq [[=y=]] , +and +.Sq [xy] +are all synonymous. +An equivalence class may not** be an endpoint of a range. +.Pp +Within a bracket expression, the name of a +.Em character class +enclosed +in +.Sq [: +and +.Sq :] +stands for the list of all characters belonging to that class. +Standard character class names are: +.Bd -literal -offset indent +alnum digit punct +alpha graph space +blank lower upper +cntrl print xdigit +.Ed +.Pp +These stand for the character classes defined in +.Xr ctype 3 . +A locale may provide others. +A character class may not be used as an endpoint of a range. +.Pp +There are two special cases** of bracket expressions: +the bracket expressions +.Sq [[:<:]] +and +.Sq [[:>:]] +match the null string at the beginning and end of a word, respectively. +A word is defined as a sequence of +characters starting and ending with a word character +which is neither preceded nor followed by +word characters. +A word character is an +.Em alnum +character (as defined by +.Xr ctype 3 ) +or an underscore. +This is an extension, +compatible with but not specified by POSIX, +and should be used with +caution in software intended to be portable to other systems. +.Pp +In the event that an RE could match more than one substring of a given +string, +the RE matches the one starting earliest in the string. +If the RE could match more than one substring starting at that point, +it matches the longest. +Subexpressions also match the longest possible substrings, subject to +the constraint that the whole match be as long as possible, +with subexpressions starting earlier in the RE taking priority over +ones starting later. +Note that higher-level subexpressions thus take priority over +their lower-level component subexpressions. +.Pp +Match lengths are measured in characters, not collating elements. +A null string is considered longer than no match at all. +For example, +.Sq bb* +matches the three middle characters of +.Sq abbbc ; +.Sq (wee|week)(knights|nights) +matches all ten characters of +.Sq weeknights ; +when +.Sq (.*).* +is matched against +.Sq abc , +the parenthesized subexpression matches all three characters; +and when +.Sq (a*)* +is matched against +.Sq bc , +both the whole RE and the parenthesized subexpression match the null string. +.Pp +If case-independent matching is specified, +the effect is much as if all case distinctions had vanished from the +alphabet. +When an alphabetic that exists in multiple cases appears as an +ordinary character outside a bracket expression, it is effectively +transformed into a bracket expression containing both cases, +e.g.\& +.Sq x +becomes +.Sq [xX] . +When it appears inside a bracket expression, +all case counterparts of it are added to the bracket expression, +so that, for example, +.Sq [x] +becomes +.Sq [xX] +and +.Sq [^x] +becomes +.Sq [^xX] . +.Pp +No particular limit is imposed on the length of REs**. +Programs intended to be portable should not employ REs longer +than 256 bytes, +as an implementation can refuse to accept such REs and remain +POSIX-compliant. +.Pp +The following is a list of extended regular expressions: +.Bl -tag -width Ds +.It Ar c +Any character +.Ar c +not listed below matches itself. +.It \e Ns Ar c +Any backslash-escaped character +.Ar c +matches itself. +.It \&. +Matches any single character that is not a newline +.Pq Sq \en . +.It Bq Ar char-class +Matches any single character in +.Ar char-class . +To include a +.Ql \&] +in +.Ar char-class , +it must be the first character. +A range of characters may be specified by separating the end characters +of the range with a +.Ql - ; +e.g.\& +.Ar a-z +specifies the lower case characters. +The following literal expressions can also be used in +.Ar char-class +to specify sets of characters: +.Bd -unfilled -offset indent +[:alnum:] [:cntrl:] [:lower:] [:space:] +[:alpha:] [:digit:] [:print:] [:upper:] +[:blank:] [:graph:] [:punct:] [:xdigit:] +.Ed +.Pp +If +.Ql - +appears as the first or last character of +.Ar char-class , +then it matches itself. +All other characters in +.Ar char-class +match themselves. +.Pp +Patterns in +.Ar char-class +of the form +.Eo [. +.Ar col-elm +.Ec .]\& +or +.Eo [= +.Ar col-elm +.Ec =]\& , +where +.Ar col-elm +is a collating element, are interpreted according to +.Xr setlocale 3 +.Pq not currently supported . +.It Bq ^ Ns Ar char-class +Matches any single character, other than newline, not in +.Ar char-class . +.Ar char-class +is defined as above. +.It ^ +If +.Sq ^ +is the first character of a regular expression, then it +anchors the regular expression to the beginning of a line. +Otherwise, it matches itself. +.It $ +If +.Sq $ +is the last character of a regular expression, +it anchors the regular expression to the end of a line. +Otherwise, it matches itself. +.It [[:<:]] +Anchors the single character regular expression or subexpression +immediately following it to the beginning of a word. +.It [[:>:]] +Anchors the single character regular expression or subexpression +immediately following it to the end of a word. +.It Pq Ar re +Defines a subexpression +.Ar re . +Any set of characters enclosed in parentheses +matches whatever the set of characters without parentheses matches +(that is a long-winded way of saying the constructs +.Sq (re) +and +.Sq re +match identically). +.It * +Matches the single character regular expression or subexpression +immediately preceding it zero or more times. +If +.Sq * +is the first character of a regular expression or subexpression, +then it matches itself. +The +.Sq * +operator sometimes yields unexpected results. +For example, the regular expression +.Ar b* +matches the beginning of the string +.Qq abbb +(as opposed to the substring +.Qq bbb ) , +since a null match is the only leftmost match. +.It + +Matches the singular character regular expression +or subexpression immediately preceding it +one or more times. +.It ? +Matches the singular character regular expression +or subexpression immediately preceding it +0 or 1 times. +.Sm off +.It Xo +.Pf { Ar n , m No }\ \& +.Pf { Ar n , No }\ \& +.Pf { Ar n No } +.Xc +.Sm on +Matches the single character regular expression or subexpression +immediately preceding it at least +.Ar n +and at most +.Ar m +times. +If +.Ar m +is omitted, then it matches at least +.Ar n +times. +If the comma is also omitted, then it matches exactly +.Ar n +times. +.It \*(Ba +Used to separate patterns. +For example, +the pattern +.Sq cat\*(Badog +matches either +.Sq cat +or +.Sq dog . +.El +.Sh BASIC REGULAR EXPRESSIONS +Basic regular expressions differ in several respects: +.Bl -bullet -offset 3n +.It +.Sq \*(Ba , +.Sq + , +and +.Sq ?\& +are ordinary characters and there is no equivalent +for their functionality. +.It +The delimiters for bounds are +.Sq \e{ +and +.Sq \e} , +with +.Sq { +and +.Sq } +by themselves ordinary characters. +.It +The parentheses for nested subexpressions are +.Sq \e( +and +.Sq \e) , +with +.Sq ( +and +.Sq )\& +by themselves ordinary characters. +.It +.Sq ^ +is an ordinary character except at the beginning of the +RE or** the beginning of a parenthesized subexpression. +.It +.Sq $ +is an ordinary character except at the end of the +RE or** the end of a parenthesized subexpression. +.It +.Sq * +is an ordinary character if it appears at the beginning of the +RE or the beginning of a parenthesized subexpression +(after a possible leading +.Sq ^ ) . +.It +Finally, there is one new type of atom, a +.Em back-reference : +.Sq \e +followed by a non-zero decimal digit +.Ar d +matches the same sequence of characters matched by the +.Ar d Ns th +parenthesized subexpression +(numbering subexpressions by the positions of their opening parentheses, +left to right), +so that, for example, +.Sq \e([bc]\e)\e1 +matches +.Sq bb\& +or +.Sq cc +but not +.Sq bc . +.El +.Pp +The following is a list of basic regular expressions: +.Bl -tag -width Ds +.It Ar c +Any character +.Ar c +not listed below matches itself. +.It \e Ns Ar c +Any backslash-escaped character +.Ar c , +except for +.Sq { , +.Sq } , +.Sq \&( , +and +.Sq \&) , +matches itself. +.It \&. +Matches any single character that is not a newline +.Pq Sq \en . +.It Bq Ar char-class +Matches any single character in +.Ar char-class . +To include a +.Ql \&] +in +.Ar char-class , +it must be the first character. +A range of characters may be specified by separating the end characters +of the range with a +.Ql - ; +e.g.\& +.Ar a-z +specifies the lower case characters. +The following literal expressions can also be used in +.Ar char-class +to specify sets of characters: +.Bd -unfilled -offset indent +[:alnum:] [:cntrl:] [:lower:] [:space:] +[:alpha:] [:digit:] [:print:] [:upper:] +[:blank:] [:graph:] [:punct:] [:xdigit:] +.Ed +.Pp +If +.Ql - +appears as the first or last character of +.Ar char-class , +then it matches itself. +All other characters in +.Ar char-class +match themselves. +.Pp +Patterns in +.Ar char-class +of the form +.Eo [. +.Ar col-elm +.Ec .]\& +or +.Eo [= +.Ar col-elm +.Ec =]\& , +where +.Ar col-elm +is a collating element, are interpreted according to +.Xr setlocale 3 +.Pq not currently supported . +.It Bq ^ Ns Ar char-class +Matches any single character, other than newline, not in +.Ar char-class . +.Ar char-class +is defined as above. +.It ^ +If +.Sq ^ +is the first character of a regular expression, then it +anchors the regular expression to the beginning of a line. +Otherwise, it matches itself. +.It $ +If +.Sq $ +is the last character of a regular expression, +it anchors the regular expression to the end of a line. +Otherwise, it matches itself. +.It [[:<:]] +Anchors the single character regular expression or subexpression +immediately following it to the beginning of a word. +.It [[:>:]] +Anchors the single character regular expression or subexpression +immediately following it to the end of a word. +.It \e( Ns Ar re Ns \e) +Defines a subexpression +.Ar re . +Subexpressions may be nested. +A subsequent backreference of the form +.Pf \e Ns Ar n , +where +.Ar n +is a number in the range [1,9], expands to the text matched by the +.Ar n Ns th +subexpression. +For example, the regular expression +.Ar \e(.*\e)\e1 +matches any string consisting of identical adjacent substrings. +Subexpressions are ordered relative to their left delimiter. +.It * +Matches the single character regular expression or subexpression +immediately preceding it zero or more times. +If +.Sq * +is the first character of a regular expression or subexpression, +then it matches itself. +The +.Sq * +operator sometimes yields unexpected results. +For example, the regular expression +.Ar b* +matches the beginning of the string +.Qq abbb +(as opposed to the substring +.Qq bbb ) , +since a null match is the only leftmost match. +.Sm off +.It Xo +.Pf \e{ Ar n , m No \e}\ \& +.Pf \e{ Ar n , No \e}\ \& +.Pf \e{ Ar n No \e} +.Xc +.Sm on +Matches the single character regular expression or subexpression +immediately preceding it at least +.Ar n +and at most +.Ar m +times. +If +.Ar m +is omitted, then it matches at least +.Ar n +times. +If the comma is also omitted, then it matches exactly +.Ar n +times. +.El +.Sh SEE ALSO +.Xr ctype 3 , +.Xr regex 3 +.Sh STANDARDS +.St -p1003.1-2004 : +Base Definitions, Chapter 9 (Regular Expressions). +.Sh BUGS +Having two kinds of REs is a botch. +.Pp +The current POSIX spec says that +.Sq )\& +is an ordinary character in the absence of an unmatched +.Sq ( ; +this was an unintentional result of a wording error, +and change is likely. +Avoid relying on it. +.Pp +Back-references are a dreadful botch, +posing major problems for efficient implementations. +They are also somewhat vaguely defined +(does +.Sq a\e(\e(b\e)*\e2\e)*d +match +.Sq abbbd ? ) . +Avoid using them. +.Pp +POSIX's specification of case-independent matching is vague. +The +.Dq one case implies all cases +definition given above +is the current consensus among implementors as to the right interpretation. +.Pp +The syntax for word boundaries is incredibly ugly. diff --git a/docs/tutorial/JITTutorial1.html b/docs/tutorial/JITTutorial1.html index ac3958e..3b7b8de 100644 --- a/docs/tutorial/JITTutorial1.html +++ b/docs/tutorial/JITTutorial1.html @@ -107,7 +107,7 @@ first chunk of our <code>makeLLVMModule()</code>:</p> <pre> Module* makeLLVMModule() { // Module Construction - Module* mod = new Module("test"); + Module* mod = new Module("test", getGlobalContext()); </pre> </div> @@ -153,7 +153,7 @@ function will interoperate properly with C code, which is a good thing.</p> <div class="doc_code"> <pre> - BasicBlock* block = BasicBlock::Create("entry", mul_add); + BasicBlock* block = BasicBlock::Create(getGlobalContext(), "entry", mul_add); IRBuilder<> builder(block); </pre> </div> @@ -200,7 +200,7 @@ function will interoperate properly with C code, which is a good thing.</p> <a href="mailto:owen@apple.com">Owen Anderson</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2007-10-17 11:05:13 -0700 (Wed, 17 Oct 2007) $ + Last modified: $Date: 2009-07-21 11:05:13 -0700 (Tue, 21 Jul 2009) $ </address> </body> diff --git a/docs/tutorial/JITTutorial2.html b/docs/tutorial/JITTutorial2.html index c2483e4..504d965 100644 --- a/docs/tutorial/JITTutorial2.html +++ b/docs/tutorial/JITTutorial2.html @@ -100,11 +100,11 @@ Module* makeLLVMModule() { <div class="doc_code"> <pre> - BasicBlock* entry = BasicBlock::Create("entry", gcd); - BasicBlock* ret = BasicBlock::Create("return", gcd); - BasicBlock* cond_false = BasicBlock::Create("cond_false", gcd); - BasicBlock* cond_true = BasicBlock::Create("cond_true", gcd); - BasicBlock* cond_false_2 = BasicBlock::Create("cond_false", gcd); + BasicBlock* entry = BasicBlock::Create(getGlobalContext(), ("entry", gcd); + BasicBlock* ret = BasicBlock::Create(getGlobalContext(), ("return", gcd); + BasicBlock* cond_false = BasicBlock::Create(getGlobalContext(), ("cond_false", gcd); + BasicBlock* cond_true = BasicBlock::Create(getGlobalContext(), ("cond_true", gcd); + BasicBlock* cond_false_2 = BasicBlock::Create(getGlobalContext(), ("cond_false", gcd); </pre> </div> diff --git a/docs/tutorial/LangImpl2.html b/docs/tutorial/LangImpl2.html index 018d0be..5bcd0dd 100644 --- a/docs/tutorial/LangImpl2.html +++ b/docs/tutorial/LangImpl2.html @@ -84,7 +84,7 @@ public: class NumberExprAST : public ExprAST { double Val; public: - explicit NumberExprAST(double val) : Val(val) {} + NumberExprAST(double val) : Val(val) {} }; </pre> </div> @@ -107,7 +107,7 @@ in the basic form of the Kaleidoscope language: class VariableExprAST : public ExprAST { std::string Name; public: - explicit VariableExprAST(const std::string &name) : Name(name) {} + VariableExprAST(const std::string &name) : Name(name) {} }; /// BinaryExprAST - Expression class for a binary operator. @@ -333,9 +333,9 @@ static ExprAST *ParseIdentifierExpr() { ExprAST *Arg = ParseExpression(); if (!Arg) return 0; Args.push_back(Arg); - + if (CurTok == ')') break; - + if (CurTok != ',') return Error("Expected ')' or ',' in argument list"); getNextToken(); @@ -815,6 +815,7 @@ course.) To build this, just compile with:</p> <div class="doc_code"> <pre> #include <cstdio> +#include <cstdlib> #include <string> #include <map> #include <vector> @@ -832,7 +833,7 @@ enum Token { tok_def = -2, tok_extern = -3, // primary - tok_identifier = -4, tok_number = -5, + tok_identifier = -4, tok_number = -5 }; static std::string IdentifierStr; // Filled in if tok_identifier @@ -900,14 +901,14 @@ public: class NumberExprAST : public ExprAST { double Val; public: - explicit NumberExprAST(double val) : Val(val) {} + NumberExprAST(double val) : Val(val) {} }; /// VariableExprAST - Expression class for referencing a variable, like "a". class VariableExprAST : public ExprAST { std::string Name; public: - explicit VariableExprAST(const std::string &name) : Name(name) {} + VariableExprAST(const std::string &name) : Name(name) {} }; /// BinaryExprAST - Expression class for a binary operator. @@ -1003,9 +1004,9 @@ static ExprAST *ParseIdentifierExpr() { ExprAST *Arg = ParseExpression(); if (!Arg) return 0; Args.push_back(Arg); - + if (CurTok == ')') break; - + if (CurTok != ',') return Error("Expected ')' or ',' in argument list"); getNextToken(); @@ -1149,7 +1150,7 @@ static PrototypeAST *ParseExtern() { //===----------------------------------------------------------------------===// static void HandleDefinition() { - if (FunctionAST *F = ParseDefinition()) { + if (ParseDefinition()) { fprintf(stderr, "Parsed a function definition.\n"); } else { // Skip token for error recovery. @@ -1158,7 +1159,7 @@ static void HandleDefinition() { } static void HandleExtern() { - if (PrototypeAST *P = ParseExtern()) { + if (ParseExtern()) { fprintf(stderr, "Parsed an extern\n"); } else { // Skip token for error recovery. @@ -1168,7 +1169,7 @@ static void HandleExtern() { static void HandleTopLevelExpression() { // Evaluate a top-level expression into an anonymous function. - if (FunctionAST *F = ParseTopLevelExpr()) { + if (ParseTopLevelExpr()) { fprintf(stderr, "Parsed a top-level expr\n"); } else { // Skip token for error recovery. @@ -1206,7 +1207,9 @@ int main() { fprintf(stderr, "ready> "); getNextToken(); + // Run the main "interpreter loop" now. MainLoop(); + return 0; } </pre> diff --git a/docs/tutorial/LangImpl3.html b/docs/tutorial/LangImpl3.html index faf11d0..e3d2117 100644 --- a/docs/tutorial/LangImpl3.html +++ b/docs/tutorial/LangImpl3.html @@ -79,7 +79,7 @@ public: class NumberExprAST : public ExprAST { double Val; public: - explicit NumberExprAST(double val) : Val(val) {} + NumberExprAST(double val) : Val(val) {} <b>virtual Value *Codegen();</b> }; ... @@ -115,7 +115,7 @@ undeclared parameter):</p> Value *ErrorV(const char *Str) { Error(Str); return 0; } static Module *TheModule; -static IRBuilder<> Builder; +static IRBuilder<> Builder(getGlobalContext()); static std::map<std::string, Value*> NamedValues; </pre> </div> @@ -159,7 +159,7 @@ we'll do numeric literals:</p> <div class="doc_code"> <pre> Value *NumberExprAST::Codegen() { - return ConstantFP::get(APFloat(Val)); + return ConstantFP::get(getGlobalContext(), APFloat(Val)); } </pre> </div> @@ -170,7 +170,7 @@ internally (<tt>APFloat</tt> has the capability of holding floating point constants of <em>A</em>rbitrary <em>P</em>recision). This code basically just creates and returns a <tt>ConstantFP</tt>. Note that in the LLVM IR that constants are all uniqued together and shared. For this reason, the API -uses "the foo::get(..)" idiom instead of "new foo(..)" or "foo::Create(..)".</p> +uses "the Context.get..." idiom instead of "new foo(..)" or "foo::Create(..)".</p> <div class="doc_code"> <pre> @@ -183,7 +183,7 @@ Value *VariableExprAST::Codegen() { </div> <p>References to variables are also quite simple using LLVM. In the simple version -of Kaleidoscope, we assume that the variable has already been emited somewhere +of Kaleidoscope, we assume that the variable has already been emitted somewhere and its value is available. In practice, the only values that can be in the <tt>NamedValues</tt> map are function arguments. This code simply checks to see that the specified name is in the map (if not, an @@ -206,7 +206,8 @@ Value *BinaryExprAST::Codegen() { case '<': L = Builder.CreateFCmpULT(L, R, "cmptmp"); // Convert bool 0/1 to double 0.0 or 1.0 - return Builder.CreateUIToFP(L, Type::DoubleTy, "booltmp"); + return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()), + "booltmp"); default: return ErrorV("invalid binary operator"); } } @@ -307,8 +308,10 @@ bodies and external function declarations. The code starts with:</p> <pre> Function *PrototypeAST::Codegen() { // Make the function type: double(double,double) etc. - std::vector<const Type*> Doubles(Args.size(), Type::DoubleTy); - FunctionType *FT = FunctionType::get(Type::DoubleTy, Doubles, false); + std::vector<const Type*> Doubles(Args.size(), + Type::getDoubleTy(getGlobalContext())); + FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), + Doubles, false); Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule); </pre> @@ -320,10 +323,10 @@ really talks about the external interface for a function (not the value computed by an expression), it makes sense for it to return the LLVM Function it corresponds to when codegen'd.</p> -<p>The call to <tt>FunctionType::get</tt> creates +<p>The call to <tt>Context.get</tt> creates the <tt>FunctionType</tt> that should be used for a given Prototype. Since all function arguments in Kaleidoscope are of type double, the first line creates -a vector of "N" LLVM double types. It then uses the <tt>FunctionType::get</tt> +a vector of "N" LLVM double types. It then uses the <tt>Context.get</tt> method to create a function type that takes "N" doubles as arguments, returns one double as a result, and that is not vararg (the false parameter indicates this). Note that Types in LLVM are uniqued just like Constants are, so you @@ -359,7 +362,7 @@ definition of this function.</p> first, we want to allow 'extern'ing a function more than once, as long as the prototypes for the externs match (since all arguments have the same type, we just have to check that the number of arguments match). Second, we want to -allow 'extern'ing a function and then definining a body for it. This is useful +allow 'extern'ing a function and then defining a body for it. This is useful when defining mutually recursive functions.</p> <p>In order to implement this, the code above first checks to see if there is @@ -439,7 +442,7 @@ is an LLVM Function object that is ready to go for us.</p> <div class="doc_code"> <pre> // Create a new basic block to start insertion into. - BasicBlock *BB = BasicBlock::Create("entry", TheFunction); + BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction); Builder.SetInsertPoint(BB); if (Value *RetVal = Body->Codegen()) { @@ -461,9 +464,10 @@ block at this point. We'll fix this in <a href="LangImpl5.html">Chapter 5</a> : if (Value *RetVal = Body->Codegen()) { // Finish off the function. Builder.CreateRet(RetVal); - + // Validate the generated code, checking for consistency. verifyFunction(*TheFunction); + return TheFunction; } </pre> @@ -682,6 +686,7 @@ our makefile/command line about which options to use:</p> // See example below. #include "llvm/DerivedTypes.h" +#include "llvm/LLVMContext.h" #include "llvm/Module.h" #include "llvm/Analysis/Verifier.h" #include "llvm/Support/IRBuilder.h" @@ -704,7 +709,7 @@ enum Token { tok_def = -2, tok_extern = -3, // primary - tok_identifier = -4, tok_number = -5, + tok_identifier = -4, tok_number = -5 }; static std::string IdentifierStr; // Filled in if tok_identifier @@ -773,7 +778,7 @@ public: class NumberExprAST : public ExprAST { double Val; public: - explicit NumberExprAST(double val) : Val(val) {} + NumberExprAST(double val) : Val(val) {} virtual Value *Codegen(); }; @@ -781,7 +786,7 @@ public: class VariableExprAST : public ExprAST { std::string Name; public: - explicit VariableExprAST(const std::string &name) : Name(name) {} + VariableExprAST(const std::string &name) : Name(name) {} virtual Value *Codegen(); }; @@ -806,7 +811,8 @@ public: }; /// PrototypeAST - This class represents the "prototype" for a function, -/// which captures its argument names as well as if it is an operator. +/// which captures its name, and its argument names (thus implicitly the number +/// of arguments the function takes). class PrototypeAST { std::string Name; std::vector<std::string> Args; @@ -833,7 +839,7 @@ public: //===----------------------------------------------------------------------===// /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current -/// token the parser it looking at. getNextToken reads another token from the +/// token the parser is looking at. getNextToken reads another token from the /// lexer and updates CurTok with its results. static int CurTok; static int getNextToken() { @@ -881,9 +887,9 @@ static ExprAST *ParseIdentifierExpr() { ExprAST *Arg = ParseExpression(); if (!Arg) return 0; Args.push_back(Arg); - + if (CurTok == ')') break; - + if (CurTok != ',') return Error("Expected ')' or ',' in argument list"); getNextToken(); @@ -1027,13 +1033,13 @@ static PrototypeAST *ParseExtern() { //===----------------------------------------------------------------------===// static Module *TheModule; -static IRBuilder<> Builder; +static IRBuilder<> Builder(getGlobalContext()); static std::map<std::string, Value*> NamedValues; Value *ErrorV(const char *Str) { Error(Str); return 0; } Value *NumberExprAST::Codegen() { - return ConstantFP::get(APFloat(Val)); + return ConstantFP::get(getGlobalContext(), APFloat(Val)); } Value *VariableExprAST::Codegen() { @@ -1054,7 +1060,8 @@ Value *BinaryExprAST::Codegen() { case '<': L = Builder.CreateFCmpULT(L, R, "cmptmp"); // Convert bool 0/1 to double 0.0 or 1.0 - return Builder.CreateUIToFP(L, Type::DoubleTy, "booltmp"); + return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()), + "booltmp"); default: return ErrorV("invalid binary operator"); } } @@ -1080,8 +1087,10 @@ Value *CallExprAST::Codegen() { Function *PrototypeAST::Codegen() { // Make the function type: double(double,double) etc. - std::vector<const Type*> Doubles(Args.size(), Type::DoubleTy); - FunctionType *FT = FunctionType::get(Type::DoubleTy, Doubles, false); + std::vector<const Type*> Doubles(Args.size(), + Type::getDoubleTy(getGlobalContext())); + FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), + Doubles, false); Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule); @@ -1126,15 +1135,16 @@ Function *FunctionAST::Codegen() { return 0; // Create a new basic block to start insertion into. - BasicBlock *BB = BasicBlock::Create("entry", TheFunction); + BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction); Builder.SetInsertPoint(BB); if (Value *RetVal = Body->Codegen()) { // Finish off the function. Builder.CreateRet(RetVal); - + // Validate the generated code, checking for consistency. verifyFunction(*TheFunction); + return TheFunction; } @@ -1172,7 +1182,7 @@ static void HandleExtern() { } static void HandleTopLevelExpression() { - // Evaluate a top level expression into an anonymous function. + // Evaluate a top-level expression into an anonymous function. if (FunctionAST *F = ParseTopLevelExpr()) { if (Function *LF = F->Codegen()) { fprintf(stderr, "Read top-level expression:"); @@ -1190,7 +1200,7 @@ static void MainLoop() { fprintf(stderr, "ready> "); switch (CurTok) { case tok_eof: return; - case ';': getNextToken(); break; // ignore top level semicolons. + case ';': getNextToken(); break; // ignore top-level semicolons. case tok_def: HandleDefinition(); break; case tok_extern: HandleExtern(); break; default: HandleTopLevelExpression(); break; @@ -1198,8 +1208,6 @@ static void MainLoop() { } } - - //===----------------------------------------------------------------------===// // "Library" functions that can be "extern'd" from user code. //===----------------------------------------------------------------------===// @@ -1216,7 +1224,7 @@ double putchard(double X) { //===----------------------------------------------------------------------===// int main() { - TheModule = new Module("my cool jit"); + LLVMContext &Context = getGlobalContext(); // Install standard binary operators. // 1 is lowest precedence. @@ -1229,8 +1237,15 @@ int main() { fprintf(stderr, "ready> "); getNextToken(); + // Make the module, which holds all the code. + TheModule = new Module("my cool jit", Context); + + // Run the main "interpreter loop" now. MainLoop(); + + // Print out all of the generated code. TheModule->dump(); + return 0; } </pre> @@ -1248,7 +1263,7 @@ int main() { <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2007-10-17 11:05:13 -0700 (Wed, 17 Oct 2007) $ + Last modified: $Date: 2009-07-21 11:05:13 -0700 (Tue, 21 Jul 2009) $ </address> </body> </html> diff --git a/docs/tutorial/LangImpl4.html b/docs/tutorial/LangImpl4.html index 9a3bfd2..3188135 100644 --- a/docs/tutorial/LangImpl4.html +++ b/docs/tutorial/LangImpl4.html @@ -171,26 +171,30 @@ add a set of optimizations to run. The code looks like this:</p> <div class="doc_code"> <pre> - ExistingModuleProvider OurModuleProvider(TheModule); - FunctionPassManager OurFPM(&OurModuleProvider); - - // Set up the optimizer pipeline. Start with registering info about how the - // target lays out data structures. - OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData())); - // Do simple "peephole" optimizations and bit-twiddling optzns. - OurFPM.add(createInstructionCombiningPass()); - // Reassociate expressions. - OurFPM.add(createReassociatePass()); - // Eliminate Common SubExpressions. - OurFPM.add(createGVNPass()); - // Simplify the control flow graph (deleting unreachable blocks, etc). - OurFPM.add(createCFGSimplificationPass()); - - // Set the global so the code gen can use this. - TheFPM = &OurFPM; - - // Run the main "interpreter loop" now. - MainLoop(); + ExistingModuleProvider *OurModuleProvider = + new ExistingModuleProvider(TheModule); + + FunctionPassManager OurFPM(OurModuleProvider); + + // Set up the optimizer pipeline. Start with registering info about how the + // target lays out data structures. + OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData())); + // Do simple "peephole" optimizations and bit-twiddling optzns. + OurFPM.add(createInstructionCombiningPass()); + // Reassociate expressions. + OurFPM.add(createReassociatePass()); + // Eliminate Common SubExpressions. + OurFPM.add(createGVNPass()); + // Simplify the control flow graph (deleting unreachable blocks, etc). + OurFPM.add(createCFGSimplificationPass()); + + OurFPM.doInitialization(); + + // Set the global so the code gen can use this. + TheFPM = &OurFPM; + + // Run the main "interpreter loop" now. + MainLoop(); </pre> </div> @@ -205,7 +209,7 @@ requires a pointer to the <tt>Module</tt> (through the <tt>ModuleProvider</tt>) to construct itself. Once it is set up, we use a series of "add" calls to add a bunch of LLVM passes. The first pass is basically boilerplate, it adds a pass so that later optimizations know how the data structures in the program are -layed out. The "<tt>TheExecutionEngine</tt>" variable is related to the JIT, +laid out. The "<tt>TheExecutionEngine</tt>" variable is related to the JIT, which we will get to in the next section.</p> <p>In this case, we choose to add 4 optimization passes. The passes we chose @@ -298,8 +302,8 @@ by adding a global variable and a call in <tt>main</tt>:</p> ... int main() { .. - <b>// Create the JIT. - TheExecutionEngine = ExecutionEngine::create(TheModule);</b> + <b>// Create the JIT. This takes ownership of the module and module provider. + TheExecutionEngine = EngineBuilder(OurModuleProvider).create();</b> .. } </pre> @@ -320,7 +324,7 @@ top-level expression to look like this:</p> <div class="doc_code"> <pre> static void HandleTopLevelExpression() { - // Evaluate a top level expression into an anonymous function. + // Evaluate a top-level expression into an anonymous function. if (FunctionAST *F = ParseTopLevelExpr()) { if (Function *LF = F->Codegen()) { LF->dump(); // Dump the function for exposition purposes. @@ -330,7 +334,7 @@ static void HandleTopLevelExpression() { // Cast it to the right type (takes no arguments, returns a double) so we // can call it as a native function. - double (*FP)() = (double (*)())FPtr; + double (*FP)() = (double (*)())(intptr_t)FPtr; fprintf(stderr, "Evaluated to %f\n", FP());</b> } </pre> @@ -359,7 +363,7 @@ entry: <p>Well this looks like it is basically working. The dump of the function shows the "no argument function that always returns double" that we synthesize -for each top level expression that is typed in. This demonstrates very basic +for each top-level expression that is typed in. This demonstrates very basic functionality, but can we do more?</p> <div class="doc_code"> @@ -495,7 +499,7 @@ LLVM JIT and optimizer. To build this example, use: <div class="doc_code"> <pre> # Compile - g++ -g toy.cpp `llvm-config --cppflags --ldflags --libs core jit native` -O3 -o toy + g++ -g toy.cpp `llvm-config --cppflags --ldflags --libs core jit interpreter native` -O3 -o toy # Run ./toy </pre> @@ -512,11 +516,15 @@ at runtime.</p> <pre> #include "llvm/DerivedTypes.h" #include "llvm/ExecutionEngine/ExecutionEngine.h" +#include "llvm/ExecutionEngine/Interpreter.h" +#include "llvm/ExecutionEngine/JIT.h" +#include "llvm/LLVMContext.h" #include "llvm/Module.h" #include "llvm/ModuleProvider.h" #include "llvm/PassManager.h" #include "llvm/Analysis/Verifier.h" #include "llvm/Target/TargetData.h" +#include "llvm/Target/TargetSelect.h" #include "llvm/Transforms/Scalar.h" #include "llvm/Support/IRBuilder.h" #include <cstdio> @@ -538,7 +546,7 @@ enum Token { tok_def = -2, tok_extern = -3, // primary - tok_identifier = -4, tok_number = -5, + tok_identifier = -4, tok_number = -5 }; static std::string IdentifierStr; // Filled in if tok_identifier @@ -640,7 +648,8 @@ public: }; /// PrototypeAST - This class represents the "prototype" for a function, -/// which captures its argument names as well as if it is an operator. +/// which captures its name, and its argument names (thus implicitly the number +/// of arguments the function takes). class PrototypeAST { std::string Name; std::vector<std::string> Args; @@ -667,7 +676,7 @@ public: //===----------------------------------------------------------------------===// /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current -/// token the parser it looking at. getNextToken reads another token from the +/// token the parser is looking at. getNextToken reads another token from the /// lexer and updates CurTok with its results. static int CurTok; static int getNextToken() { @@ -715,9 +724,9 @@ static ExprAST *ParseIdentifierExpr() { ExprAST *Arg = ParseExpression(); if (!Arg) return 0; Args.push_back(Arg); - + if (CurTok == ')') break; - + if (CurTok != ',') return Error("Expected ')' or ',' in argument list"); getNextToken(); @@ -861,14 +870,14 @@ static PrototypeAST *ParseExtern() { //===----------------------------------------------------------------------===// static Module *TheModule; -static IRBuilder<> Builder; +static IRBuilder<> Builder(getGlobalContext()); static std::map<std::string, Value*> NamedValues; static FunctionPassManager *TheFPM; Value *ErrorV(const char *Str) { Error(Str); return 0; } Value *NumberExprAST::Codegen() { - return ConstantFP::get(APFloat(Val)); + return ConstantFP::get(getGlobalContext(), APFloat(Val)); } Value *VariableExprAST::Codegen() { @@ -889,7 +898,8 @@ Value *BinaryExprAST::Codegen() { case '<': L = Builder.CreateFCmpULT(L, R, "cmptmp"); // Convert bool 0/1 to double 0.0 or 1.0 - return Builder.CreateUIToFP(L, Type::DoubleTy, "booltmp"); + return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()), + "booltmp"); default: return ErrorV("invalid binary operator"); } } @@ -915,8 +925,10 @@ Value *CallExprAST::Codegen() { Function *PrototypeAST::Codegen() { // Make the function type: double(double,double) etc. - std::vector<const Type*> Doubles(Args.size(), Type::DoubleTy); - FunctionType *FT = FunctionType::get(Type::DoubleTy, Doubles, false); + std::vector<const Type*> Doubles(Args.size(), + Type::getDoubleTy(getGlobalContext())); + FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), + Doubles, false); Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule); @@ -961,7 +973,7 @@ Function *FunctionAST::Codegen() { return 0; // Create a new basic block to start insertion into. - BasicBlock *BB = BasicBlock::Create("entry", TheFunction); + BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction); Builder.SetInsertPoint(BB); if (Value *RetVal = Body->Codegen()) { @@ -1013,7 +1025,7 @@ static void HandleExtern() { } static void HandleTopLevelExpression() { - // Evaluate a top level expression into an anonymous function. + // Evaluate a top-level expression into an anonymous function. if (FunctionAST *F = ParseTopLevelExpr()) { if (Function *LF = F->Codegen()) { // JIT the function, returning a function pointer. @@ -1021,7 +1033,7 @@ static void HandleTopLevelExpression() { // Cast it to the right type (takes no arguments, returns a double) so we // can call it as a native function. - double (*FP)() = (double (*)())FPtr; + double (*FP)() = (double (*)())(intptr_t)FPtr; fprintf(stderr, "Evaluated to %f\n", FP()); } } else { @@ -1036,7 +1048,7 @@ static void MainLoop() { fprintf(stderr, "ready> "); switch (CurTok) { case tok_eof: return; - case ';': getNextToken(); break; // ignore top level semicolons. + case ';': getNextToken(); break; // ignore top-level semicolons. case tok_def: HandleDefinition(); break; case tok_extern: HandleExtern(); break; default: HandleTopLevelExpression(); break; @@ -1044,8 +1056,6 @@ static void MainLoop() { } } - - //===----------------------------------------------------------------------===// // "Library" functions that can be "extern'd" from user code. //===----------------------------------------------------------------------===// @@ -1062,6 +1072,9 @@ double putchard(double X) { //===----------------------------------------------------------------------===// int main() { + InitializeNativeTarget(); + LLVMContext &Context = getGlobalContext(); + // Install standard binary operators. // 1 is lowest precedence. BinopPrecedence['<'] = 10; @@ -1074,39 +1087,41 @@ int main() { getNextToken(); // Make the module, which holds all the code. - TheModule = new Module("my cool jit"); - - // Create the JIT. - TheExecutionEngine = ExecutionEngine::create(TheModule); + TheModule = new Module("my cool jit", Context); + + ExistingModuleProvider *OurModuleProvider = + new ExistingModuleProvider(TheModule); + + // Create the JIT. This takes ownership of the module and module provider. + TheExecutionEngine = EngineBuilder(OurModuleProvider).create(); + + FunctionPassManager OurFPM(OurModuleProvider); + + // Set up the optimizer pipeline. Start with registering info about how the + // target lays out data structures. + OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData())); + // Do simple "peephole" optimizations and bit-twiddling optzns. + OurFPM.add(createInstructionCombiningPass()); + // Reassociate expressions. + OurFPM.add(createReassociatePass()); + // Eliminate Common SubExpressions. + OurFPM.add(createGVNPass()); + // Simplify the control flow graph (deleting unreachable blocks, etc). + OurFPM.add(createCFGSimplificationPass()); + + OurFPM.doInitialization(); + + // Set the global so the code gen can use this. + TheFPM = &OurFPM; + + // Run the main "interpreter loop" now. + MainLoop(); + + TheFPM = 0; + + // Print out all of the generated code. + TheModule->dump(); - { - ExistingModuleProvider OurModuleProvider(TheModule); - FunctionPassManager OurFPM(&OurModuleProvider); - - // Set up the optimizer pipeline. Start with registering info about how the - // target lays out data structures. - OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData())); - // Do simple "peephole" optimizations and bit-twiddling optzns. - OurFPM.add(createInstructionCombiningPass()); - // Reassociate expressions. - OurFPM.add(createReassociatePass()); - // Eliminate Common SubExpressions. - OurFPM.add(createGVNPass()); - // Simplify the control flow graph (deleting unreachable blocks, etc). - OurFPM.add(createCFGSimplificationPass()); - - // Set the global so the code gen can use this. - TheFPM = &OurFPM; - - // Run the main "interpreter loop" now. - MainLoop(); - - TheFPM = 0; - - // Print out all of the generated code. - TheModule->dump(); - } // Free module provider (and thus the module) and pass manager. - return 0; } </pre> diff --git a/docs/tutorial/LangImpl5.html b/docs/tutorial/LangImpl5.html index bf96b46..f93b59b 100644 --- a/docs/tutorial/LangImpl5.html +++ b/docs/tutorial/LangImpl5.html @@ -288,8 +288,8 @@ into "t.ll" and run "<tt>llvm-as < t.ll | opt -analyze -view-cfg</tt>", <a href="../ProgrammersManual.html#ViewGraph">a window will pop up</a> and you'll see this graph:</p> -<center><img src="LangImpl5-cfg.png" alt="Example CFG" width="423" -height="315"></center> +<div style="text-align: center"><img src="LangImpl5-cfg.png" alt="Example CFG" width="423" +height="315"></div> <p>Another way to get this is to call "<tt>F->viewCFG()</tt>" or "<tt>F->viewCFGOnly()</tt>" (where F is a "<tt>Function*</tt>") either by @@ -364,7 +364,7 @@ Value *IfExprAST::Codegen() { // Convert condition to a bool by comparing equal to 0.0. CondV = Builder.CreateFCmpONE(CondV, - ConstantFP::get(APFloat(0.0)), + ConstantFP::get(getGlobalContext(), APFloat(0.0)), "ifcond"); </pre> </div> @@ -379,9 +379,9 @@ value as a 1-bit (bool) value.</p> // Create blocks for the then and else cases. Insert the 'then' block at the // end of the function. - BasicBlock *ThenBB = BasicBlock::Create("then", TheFunction); - BasicBlock *ElseBB = BasicBlock::Create("else"); - BasicBlock *MergeBB = BasicBlock::Create("ifcont"); + BasicBlock *ThenBB = BasicBlock::Create(getGlobalContext(), "then", TheFunction); + BasicBlock *ElseBB = BasicBlock::Create(getGlobalContext(), "else"); + BasicBlock *MergeBB = BasicBlock::Create(getGlobalContext(), "ifcont"); Builder.CreateCondBr(CondV, ThenBB, ElseBB); </pre> @@ -472,7 +472,8 @@ are emitted, we can finish up with the merge code:</p> // Emit merge block. TheFunction->getBasicBlockList().push_back(MergeBB); Builder.SetInsertPoint(MergeBB); - PHINode *PN = Builder.CreatePHI(Type::DoubleTy, "iftmp"); + PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), + "iftmp"); PN->addIncoming(ThenV, ThenBB); PN->addIncoming(ElseV, ElseBB); @@ -727,7 +728,7 @@ block, but remember that the body code itself could consist of multiple blocks // block. Function *TheFunction = Builder.GetInsertBlock()->getParent(); BasicBlock *PreheaderBB = Builder.GetInsertBlock(); - BasicBlock *LoopBB = BasicBlock::Create("loop", TheFunction); + BasicBlock *LoopBB = BasicBlock::Create(getGlobalContext(), "loop", TheFunction); // Insert an explicit fall through from the current block to the LoopBB. Builder.CreateBr(LoopBB); @@ -745,7 +746,7 @@ create an unconditional branch for the fall-through between the two blocks.</p> Builder.SetInsertPoint(LoopBB); // Start the PHI node with an entry for Start. - PHINode *Variable = Builder.CreatePHI(Type::DoubleTy, VarName.c_str()); + PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), VarName.c_str()); Variable->addIncoming(StartVal, PreheaderBB); </pre> </div> @@ -796,7 +797,7 @@ references to it will naturally find it in the symbol table.</p> if (StepVal == 0) return 0; } else { // If not specified, use 1.0. - StepVal = ConstantFP::get(APFloat(1.0)); + StepVal = ConstantFP::get(getGlobalContext(), APFloat(1.0)); } Value *NextVar = Builder.CreateAdd(Variable, StepVal, "nextvar"); @@ -815,7 +816,7 @@ will be the value of the loop variable on the next iteration of the loop.</p> // Convert condition to a bool by comparing equal to 0.0. EndCond = Builder.CreateFCmpONE(EndCond, - ConstantFP::get(APFloat(0.0)), + ConstantFP::get(getGlobalContext(), APFloat(0.0)), "loopcond"); </pre> </div> @@ -828,7 +829,7 @@ statement.</p> <pre> // Create the "after loop" block and insert it. BasicBlock *LoopEndBB = Builder.GetInsertBlock(); - BasicBlock *AfterBB = BasicBlock::Create("afterloop", TheFunction); + BasicBlock *AfterBB = BasicBlock::Create(getGlobalContext(), "afterloop", TheFunction); // Insert the conditional branch into the end of LoopEndBB. Builder.CreateCondBr(EndCond, LoopBB, AfterBB); @@ -856,7 +857,7 @@ the loop again and exiting the loop. Any future code is emitted in the NamedValues.erase(VarName); // for expr always returns 0.0. - return Constant::getNullValue(Type::DoubleTy); + return Constant::getNullValue(Type::getDoubleTy(getGlobalContext())); } </pre> </div> @@ -901,11 +902,15 @@ if/then/else and for expressions.. To build this example, use: <pre> #include "llvm/DerivedTypes.h" #include "llvm/ExecutionEngine/ExecutionEngine.h" +#include "llvm/ExecutionEngine/Interpreter.h" +#include "llvm/ExecutionEngine/JIT.h" +#include "llvm/LLVMContext.h" #include "llvm/Module.h" #include "llvm/ModuleProvider.h" #include "llvm/PassManager.h" #include "llvm/Analysis/Verifier.h" #include "llvm/Target/TargetData.h" +#include "llvm/Target/TargetSelect.h" #include "llvm/Transforms/Scalar.h" #include "llvm/Support/IRBuilder.h" #include <cstdio> @@ -1058,7 +1063,8 @@ public: }; /// PrototypeAST - This class represents the "prototype" for a function, -/// which captures its argument names as well as if it is an operator. +/// which captures its name, and its argument names (thus implicitly the number +/// of arguments the function takes). class PrototypeAST { std::string Name; std::vector<std::string> Args; @@ -1085,7 +1091,7 @@ public: //===----------------------------------------------------------------------===// /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current -/// token the parser it looking at. getNextToken reads another token from the +/// token the parser is looking at. getNextToken reads another token from the /// lexer and updates CurTok with its results. static int CurTok; static int getNextToken() { @@ -1133,9 +1139,9 @@ static ExprAST *ParseIdentifierExpr() { ExprAST *Arg = ParseExpression(); if (!Arg) return 0; Args.push_back(Arg); - + if (CurTok == ')') break; - + if (CurTok != ',') return Error("Expected ')' or ',' in argument list"); getNextToken(); @@ -1235,7 +1241,6 @@ static ExprAST *ParseForExpr() { return new ForExprAST(IdName, Start, End, Step, Body); } - /// primary /// ::= identifierexpr /// ::= numberexpr @@ -1352,14 +1357,14 @@ static PrototypeAST *ParseExtern() { //===----------------------------------------------------------------------===// static Module *TheModule; -static IRBuilder<> Builder; +static IRBuilder<> Builder(getGlobalContext()); static std::map<std::string, Value*> NamedValues; static FunctionPassManager *TheFPM; Value *ErrorV(const char *Str) { Error(Str); return 0; } Value *NumberExprAST::Codegen() { - return ConstantFP::get(APFloat(Val)); + return ConstantFP::get(getGlobalContext(), APFloat(Val)); } Value *VariableExprAST::Codegen() { @@ -1380,7 +1385,8 @@ Value *BinaryExprAST::Codegen() { case '<': L = Builder.CreateFCmpULT(L, R, "cmptmp"); // Convert bool 0/1 to double 0.0 or 1.0 - return Builder.CreateUIToFP(L, Type::DoubleTy, "booltmp"); + return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()), + "booltmp"); default: return ErrorV("invalid binary operator"); } } @@ -1410,16 +1416,16 @@ Value *IfExprAST::Codegen() { // Convert condition to a bool by comparing equal to 0.0. CondV = Builder.CreateFCmpONE(CondV, - ConstantFP::get(APFloat(0.0)), + ConstantFP::get(getGlobalContext(), APFloat(0.0)), "ifcond"); Function *TheFunction = Builder.GetInsertBlock()->getParent(); // Create blocks for the then and else cases. Insert the 'then' block at the // end of the function. - BasicBlock *ThenBB = BasicBlock::Create("then", TheFunction); - BasicBlock *ElseBB = BasicBlock::Create("else"); - BasicBlock *MergeBB = BasicBlock::Create("ifcont"); + BasicBlock *ThenBB = BasicBlock::Create(getGlobalContext(), "then", TheFunction); + BasicBlock *ElseBB = BasicBlock::Create(getGlobalContext(), "else"); + BasicBlock *MergeBB = BasicBlock::Create(getGlobalContext(), "ifcont"); Builder.CreateCondBr(CondV, ThenBB, ElseBB); @@ -1447,7 +1453,8 @@ Value *IfExprAST::Codegen() { // Emit merge block. TheFunction->getBasicBlockList().push_back(MergeBB); Builder.SetInsertPoint(MergeBB); - PHINode *PN = Builder.CreatePHI(Type::DoubleTy, "iftmp"); + PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), + "iftmp"); PN->addIncoming(ThenV, ThenBB); PN->addIncoming(ElseV, ElseBB); @@ -1479,7 +1486,7 @@ Value *ForExprAST::Codegen() { // block. Function *TheFunction = Builder.GetInsertBlock()->getParent(); BasicBlock *PreheaderBB = Builder.GetInsertBlock(); - BasicBlock *LoopBB = BasicBlock::Create("loop", TheFunction); + BasicBlock *LoopBB = BasicBlock::Create(getGlobalContext(), "loop", TheFunction); // Insert an explicit fall through from the current block to the LoopBB. Builder.CreateBr(LoopBB); @@ -1488,7 +1495,7 @@ Value *ForExprAST::Codegen() { Builder.SetInsertPoint(LoopBB); // Start the PHI node with an entry for Start. - PHINode *Variable = Builder.CreatePHI(Type::DoubleTy, VarName.c_str()); + PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), VarName.c_str()); Variable->addIncoming(StartVal, PreheaderBB); // Within the loop, the variable is defined equal to the PHI node. If it @@ -1509,7 +1516,7 @@ Value *ForExprAST::Codegen() { if (StepVal == 0) return 0; } else { // If not specified, use 1.0. - StepVal = ConstantFP::get(APFloat(1.0)); + StepVal = ConstantFP::get(getGlobalContext(), APFloat(1.0)); } Value *NextVar = Builder.CreateAdd(Variable, StepVal, "nextvar"); @@ -1520,12 +1527,12 @@ Value *ForExprAST::Codegen() { // Convert condition to a bool by comparing equal to 0.0. EndCond = Builder.CreateFCmpONE(EndCond, - ConstantFP::get(APFloat(0.0)), + ConstantFP::get(getGlobalContext(), APFloat(0.0)), "loopcond"); // Create the "after loop" block and insert it. BasicBlock *LoopEndBB = Builder.GetInsertBlock(); - BasicBlock *AfterBB = BasicBlock::Create("afterloop", TheFunction); + BasicBlock *AfterBB = BasicBlock::Create(getGlobalContext(), "afterloop", TheFunction); // Insert the conditional branch into the end of LoopEndBB. Builder.CreateCondBr(EndCond, LoopBB, AfterBB); @@ -1544,13 +1551,15 @@ Value *ForExprAST::Codegen() { // for expr always returns 0.0. - return Constant::getNullValue(Type::DoubleTy); + return Constant::getNullValue(Type::getDoubleTy(getGlobalContext())); } Function *PrototypeAST::Codegen() { // Make the function type: double(double,double) etc. - std::vector<const Type*> Doubles(Args.size(), Type::DoubleTy); - FunctionType *FT = FunctionType::get(Type::DoubleTy, Doubles, false); + std::vector<const Type*> Doubles(Args.size(), + Type::getDoubleTy(getGlobalContext())); + FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), + Doubles, false); Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule); @@ -1595,7 +1604,7 @@ Function *FunctionAST::Codegen() { return 0; // Create a new basic block to start insertion into. - BasicBlock *BB = BasicBlock::Create("entry", TheFunction); + BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction); Builder.SetInsertPoint(BB); if (Value *RetVal = Body->Codegen()) { @@ -1647,7 +1656,7 @@ static void HandleExtern() { } static void HandleTopLevelExpression() { - // Evaluate a top level expression into an anonymous function. + // Evaluate a top-level expression into an anonymous function. if (FunctionAST *F = ParseTopLevelExpr()) { if (Function *LF = F->Codegen()) { // JIT the function, returning a function pointer. @@ -1655,7 +1664,7 @@ static void HandleTopLevelExpression() { // Cast it to the right type (takes no arguments, returns a double) so we // can call it as a native function. - double (*FP)() = (double (*)())FPtr; + double (*FP)() = (double (*)())(intptr_t)FPtr; fprintf(stderr, "Evaluated to %f\n", FP()); } } else { @@ -1670,7 +1679,7 @@ static void MainLoop() { fprintf(stderr, "ready> "); switch (CurTok) { case tok_eof: return; - case ';': getNextToken(); break; // ignore top level semicolons. + case ';': getNextToken(); break; // ignore top-level semicolons. case tok_def: HandleDefinition(); break; case tok_extern: HandleExtern(); break; default: HandleTopLevelExpression(); break; @@ -1678,8 +1687,6 @@ static void MainLoop() { } } - - //===----------------------------------------------------------------------===// // "Library" functions that can be "extern'd" from user code. //===----------------------------------------------------------------------===// @@ -1696,6 +1703,9 @@ double putchard(double X) { //===----------------------------------------------------------------------===// int main() { + InitializeNativeTarget(); + LLVMContext &Context = getGlobalContext(); + // Install standard binary operators. // 1 is lowest precedence. BinopPrecedence['<'] = 10; @@ -1708,38 +1718,41 @@ int main() { getNextToken(); // Make the module, which holds all the code. - TheModule = new Module("my cool jit"); - - // Create the JIT. - TheExecutionEngine = ExecutionEngine::create(TheModule); + TheModule = new Module("my cool jit", Context); - { - ExistingModuleProvider OurModuleProvider(TheModule); - FunctionPassManager OurFPM(&OurModuleProvider); - - // Set up the optimizer pipeline. Start with registering info about how the - // target lays out data structures. - OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData())); - // Do simple "peephole" optimizations and bit-twiddling optzns. - OurFPM.add(createInstructionCombiningPass()); - // Reassociate expressions. - OurFPM.add(createReassociatePass()); - // Eliminate Common SubExpressions. - OurFPM.add(createGVNPass()); - // Simplify the control flow graph (deleting unreachable blocks, etc). - OurFPM.add(createCFGSimplificationPass()); - // Set the global so the code gen can use this. - TheFPM = &OurFPM; - - // Run the main "interpreter loop" now. - MainLoop(); - - TheFPM = 0; + ExistingModuleProvider *OurModuleProvider = + new ExistingModuleProvider(TheModule); + + // Create the JIT. This takes ownership of the module and module provider. + TheExecutionEngine = EngineBuilder(OurModuleProvider).create(); + + FunctionPassManager OurFPM(OurModuleProvider); + + // Set up the optimizer pipeline. Start with registering info about how the + // target lays out data structures. + OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData())); + // Do simple "peephole" optimizations and bit-twiddling optzns. + OurFPM.add(createInstructionCombiningPass()); + // Reassociate expressions. + OurFPM.add(createReassociatePass()); + // Eliminate Common SubExpressions. + OurFPM.add(createGVNPass()); + // Simplify the control flow graph (deleting unreachable blocks, etc). + OurFPM.add(createCFGSimplificationPass()); + + OurFPM.doInitialization(); + + // Set the global so the code gen can use this. + TheFPM = &OurFPM; + + // Run the main "interpreter loop" now. + MainLoop(); + + TheFPM = 0; + + // Print out all of the generated code. + TheModule->dump(); - // Print out all of the generated code. - TheModule->dump(); - } // Free module provider (and thus the module) and pass manager. - return 0; } </pre> diff --git a/docs/tutorial/LangImpl6.html b/docs/tutorial/LangImpl6.html index 44ad15b..f113e96 100644 --- a/docs/tutorial/LangImpl6.html +++ b/docs/tutorial/LangImpl6.html @@ -207,7 +207,7 @@ the prototype for a user-defined operator, we need to parse it:</p> static PrototypeAST *ParsePrototype() { std::string FnName; - <b>int Kind = 0; // 0 = identifier, 1 = unary, 2 = binary. + <b>unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary. unsigned BinaryPrecedence = 30;</b> switch (CurTok) { @@ -283,7 +283,8 @@ Value *BinaryExprAST::Codegen() { case '<': L = Builder.CreateFCmpULT(L, R, "cmptmp"); // Convert bool 0/1 to double 0.0 or 1.0 - return Builder.CreateUIToFP(L, Type::DoubleTy, "booltmp"); + return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()), + "booltmp"); <b>default: break;</b> } @@ -305,7 +306,7 @@ function call to it. Since user-defined operators are just built as normal functions (because the "prototype" boils down to a function with the right name) everything falls into place.</p> -<p>The final piece of code we are missing, is a bit of top level magic:</p> +<p>The final piece of code we are missing, is a bit of top-level magic:</p> <div class="doc_code"> <pre> @@ -321,7 +322,7 @@ Function *FunctionAST::Codegen() { BinopPrecedence[Proto->getOperatorName()] = Proto->getBinaryPrecedence();</b> // Create a new basic block to start insertion into. - BasicBlock *BB = BasicBlock::Create("entry", TheFunction); + BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction); Builder.SetInsertPoint(BB); if (Value *RetVal = Body->Codegen()) { @@ -438,7 +439,7 @@ with:</p> static PrototypeAST *ParsePrototype() { std::string FnName; - int Kind = 0; // 0 = identifier, 1 = unary, 2 = binary. + unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary. unsigned BinaryPrecedence = 30; switch (CurTok) { @@ -794,7 +795,6 @@ add variable mutation without building SSA in your front-end.</p> </div> - <!-- *********************************************************************** --> <div class="doc_section"><a name="code">Full Code Listing</a></div> <!-- *********************************************************************** --> @@ -821,11 +821,15 @@ if/then/else and for expressions.. To build this example, use: <pre> #include "llvm/DerivedTypes.h" #include "llvm/ExecutionEngine/ExecutionEngine.h" +#include "llvm/ExecutionEngine/Interpreter.h" +#include "llvm/ExecutionEngine/JIT.h" +#include "llvm/LLVMContext.h" #include "llvm/Module.h" #include "llvm/ModuleProvider.h" #include "llvm/PassManager.h" #include "llvm/Analysis/Verifier.h" #include "llvm/Target/TargetData.h" +#include "llvm/Target/TargetSelect.h" #include "llvm/Transforms/Scalar.h" #include "llvm/Support/IRBuilder.h" #include <cstdio> @@ -993,7 +997,8 @@ public: }; /// PrototypeAST - This class represents the "prototype" for a function, -/// which captures its argument names as well as if it is an operator. +/// which captures its name, and its argument names (thus implicitly the number +/// of arguments the function takes), as well as if it is an operator. class PrototypeAST { std::string Name; std::vector<std::string> Args; @@ -1033,7 +1038,7 @@ public: //===----------------------------------------------------------------------===// /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current -/// token the parser it looking at. getNextToken reads another token from the +/// token the parser is looking at. getNextToken reads another token from the /// lexer and updates CurTok with its results. static int CurTok; static int getNextToken() { @@ -1081,9 +1086,9 @@ static ExprAST *ParseIdentifierExpr() { ExprAST *Arg = ParseExpression(); if (!Arg) return 0; Args.push_back(Arg); - + if (CurTok == ')') break; - + if (CurTok != ',') return Error("Expected ')' or ',' in argument list"); getNextToken(); @@ -1183,7 +1188,6 @@ static ExprAST *ParseForExpr() { return new ForExprAST(IdName, Start, End, Step, Body); } - /// primary /// ::= identifierexpr /// ::= numberexpr @@ -1267,7 +1271,7 @@ static ExprAST *ParseExpression() { static PrototypeAST *ParsePrototype() { std::string FnName; - int Kind = 0; // 0 = identifier, 1 = unary, 2 = binary. + unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary. unsigned BinaryPrecedence = 30; switch (CurTok) { @@ -1357,14 +1361,14 @@ static PrototypeAST *ParseExtern() { //===----------------------------------------------------------------------===// static Module *TheModule; -static IRBuilder<> Builder; +static IRBuilder<> Builder(getGlobalContext()); static std::map<std::string, Value*> NamedValues; static FunctionPassManager *TheFPM; Value *ErrorV(const char *Str) { Error(Str); return 0; } Value *NumberExprAST::Codegen() { - return ConstantFP::get(APFloat(Val)); + return ConstantFP::get(getGlobalContext(), APFloat(Val)); } Value *VariableExprAST::Codegen() { @@ -1384,7 +1388,6 @@ Value *UnaryExprAST::Codegen() { return Builder.CreateCall(F, OperandV, "unop"); } - Value *BinaryExprAST::Codegen() { Value *L = LHS->Codegen(); Value *R = RHS->Codegen(); @@ -1397,7 +1400,8 @@ Value *BinaryExprAST::Codegen() { case '<': L = Builder.CreateFCmpULT(L, R, "cmptmp"); // Convert bool 0/1 to double 0.0 or 1.0 - return Builder.CreateUIToFP(L, Type::DoubleTy, "booltmp"); + return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()), + "booltmp"); default: break; } @@ -1435,16 +1439,16 @@ Value *IfExprAST::Codegen() { // Convert condition to a bool by comparing equal to 0.0. CondV = Builder.CreateFCmpONE(CondV, - ConstantFP::get(APFloat(0.0)), + ConstantFP::get(getGlobalContext(), APFloat(0.0)), "ifcond"); Function *TheFunction = Builder.GetInsertBlock()->getParent(); // Create blocks for the then and else cases. Insert the 'then' block at the // end of the function. - BasicBlock *ThenBB = BasicBlock::Create("then", TheFunction); - BasicBlock *ElseBB = BasicBlock::Create("else"); - BasicBlock *MergeBB = BasicBlock::Create("ifcont"); + BasicBlock *ThenBB = BasicBlock::Create(getGlobalContext(), "then", TheFunction); + BasicBlock *ElseBB = BasicBlock::Create(getGlobalContext(), "else"); + BasicBlock *MergeBB = BasicBlock::Create(getGlobalContext(), "ifcont"); Builder.CreateCondBr(CondV, ThenBB, ElseBB); @@ -1472,7 +1476,8 @@ Value *IfExprAST::Codegen() { // Emit merge block. TheFunction->getBasicBlockList().push_back(MergeBB); Builder.SetInsertPoint(MergeBB); - PHINode *PN = Builder.CreatePHI(Type::DoubleTy, "iftmp"); + PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), + "iftmp"); PN->addIncoming(ThenV, ThenBB); PN->addIncoming(ElseV, ElseBB); @@ -1504,7 +1509,7 @@ Value *ForExprAST::Codegen() { // block. Function *TheFunction = Builder.GetInsertBlock()->getParent(); BasicBlock *PreheaderBB = Builder.GetInsertBlock(); - BasicBlock *LoopBB = BasicBlock::Create("loop", TheFunction); + BasicBlock *LoopBB = BasicBlock::Create(getGlobalContext(), "loop", TheFunction); // Insert an explicit fall through from the current block to the LoopBB. Builder.CreateBr(LoopBB); @@ -1513,7 +1518,7 @@ Value *ForExprAST::Codegen() { Builder.SetInsertPoint(LoopBB); // Start the PHI node with an entry for Start. - PHINode *Variable = Builder.CreatePHI(Type::DoubleTy, VarName.c_str()); + PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), VarName.c_str()); Variable->addIncoming(StartVal, PreheaderBB); // Within the loop, the variable is defined equal to the PHI node. If it @@ -1534,7 +1539,7 @@ Value *ForExprAST::Codegen() { if (StepVal == 0) return 0; } else { // If not specified, use 1.0. - StepVal = ConstantFP::get(APFloat(1.0)); + StepVal = ConstantFP::get(getGlobalContext(), APFloat(1.0)); } Value *NextVar = Builder.CreateAdd(Variable, StepVal, "nextvar"); @@ -1545,12 +1550,12 @@ Value *ForExprAST::Codegen() { // Convert condition to a bool by comparing equal to 0.0. EndCond = Builder.CreateFCmpONE(EndCond, - ConstantFP::get(APFloat(0.0)), + ConstantFP::get(getGlobalContext(), APFloat(0.0)), "loopcond"); // Create the "after loop" block and insert it. BasicBlock *LoopEndBB = Builder.GetInsertBlock(); - BasicBlock *AfterBB = BasicBlock::Create("afterloop", TheFunction); + BasicBlock *AfterBB = BasicBlock::Create(getGlobalContext(), "afterloop", TheFunction); // Insert the conditional branch into the end of LoopEndBB. Builder.CreateCondBr(EndCond, LoopBB, AfterBB); @@ -1569,13 +1574,15 @@ Value *ForExprAST::Codegen() { // for expr always returns 0.0. - return Constant::getNullValue(Type::DoubleTy); + return Constant::getNullValue(Type::getDoubleTy(getGlobalContext())); } Function *PrototypeAST::Codegen() { // Make the function type: double(double,double) etc. - std::vector<const Type*> Doubles(Args.size(), Type::DoubleTy); - FunctionType *FT = FunctionType::get(Type::DoubleTy, Doubles, false); + std::vector<const Type*> Doubles(Args.size(), + Type::getDoubleTy(getGlobalContext())); + FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), + Doubles, false); Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule); @@ -1624,7 +1631,7 @@ Function *FunctionAST::Codegen() { BinopPrecedence[Proto->getOperatorName()] = Proto->getBinaryPrecedence(); // Create a new basic block to start insertion into. - BasicBlock *BB = BasicBlock::Create("entry", TheFunction); + BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction); Builder.SetInsertPoint(BB); if (Value *RetVal = Body->Codegen()) { @@ -1679,7 +1686,7 @@ static void HandleExtern() { } static void HandleTopLevelExpression() { - // Evaluate a top level expression into an anonymous function. + // Evaluate a top-level expression into an anonymous function. if (FunctionAST *F = ParseTopLevelExpr()) { if (Function *LF = F->Codegen()) { // JIT the function, returning a function pointer. @@ -1687,7 +1694,7 @@ static void HandleTopLevelExpression() { // Cast it to the right type (takes no arguments, returns a double) so we // can call it as a native function. - double (*FP)() = (double (*)())FPtr; + double (*FP)() = (double (*)())(intptr_t)FPtr; fprintf(stderr, "Evaluated to %f\n", FP()); } } else { @@ -1702,7 +1709,7 @@ static void MainLoop() { fprintf(stderr, "ready> "); switch (CurTok) { case tok_eof: return; - case ';': getNextToken(); break; // ignore top level semicolons. + case ';': getNextToken(); break; // ignore top-level semicolons. case tok_def: HandleDefinition(); break; case tok_extern: HandleExtern(); break; default: HandleTopLevelExpression(); break; @@ -1710,8 +1717,6 @@ static void MainLoop() { } } - - //===----------------------------------------------------------------------===// // "Library" functions that can be "extern'd" from user code. //===----------------------------------------------------------------------===// @@ -1735,6 +1740,9 @@ double printd(double X) { //===----------------------------------------------------------------------===// int main() { + InitializeNativeTarget(); + LLVMContext &Context = getGlobalContext(); + // Install standard binary operators. // 1 is lowest precedence. BinopPrecedence['<'] = 10; @@ -1747,38 +1755,41 @@ int main() { getNextToken(); // Make the module, which holds all the code. - TheModule = new Module("my cool jit"); - - // Create the JIT. - TheExecutionEngine = ExecutionEngine::create(TheModule); + TheModule = new Module("my cool jit", Context); + + ExistingModuleProvider *OurModuleProvider = + new ExistingModuleProvider(TheModule); + + // Create the JIT. This takes ownership of the module and module provider. + TheExecutionEngine = EngineBuilder(OurModuleProvider).create(); + + FunctionPassManager OurFPM(OurModuleProvider); + + // Set up the optimizer pipeline. Start with registering info about how the + // target lays out data structures. + OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData())); + // Do simple "peephole" optimizations and bit-twiddling optzns. + OurFPM.add(createInstructionCombiningPass()); + // Reassociate expressions. + OurFPM.add(createReassociatePass()); + // Eliminate Common SubExpressions. + OurFPM.add(createGVNPass()); + // Simplify the control flow graph (deleting unreachable blocks, etc). + OurFPM.add(createCFGSimplificationPass()); + + OurFPM.doInitialization(); + + // Set the global so the code gen can use this. + TheFPM = &OurFPM; + + // Run the main "interpreter loop" now. + MainLoop(); + + TheFPM = 0; + + // Print out all of the generated code. + TheModule->dump(); - { - ExistingModuleProvider OurModuleProvider(TheModule); - FunctionPassManager OurFPM(&OurModuleProvider); - - // Set up the optimizer pipeline. Start with registering info about how the - // target lays out data structures. - OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData())); - // Do simple "peephole" optimizations and bit-twiddling optzns. - OurFPM.add(createInstructionCombiningPass()); - // Reassociate expressions. - OurFPM.add(createReassociatePass()); - // Eliminate Common SubExpressions. - OurFPM.add(createGVNPass()); - // Simplify the control flow graph (deleting unreachable blocks, etc). - OurFPM.add(createCFGSimplificationPass()); - // Set the global so the code gen can use this. - TheFPM = &OurFPM; - - // Run the main "interpreter loop" now. - MainLoop(); - - TheFPM = 0; - - // Print out all of the generated code. - TheModule->dump(); - } // Free module provider (and thus the module) and pass manager. - return 0; } </pre> diff --git a/docs/tutorial/LangImpl7.html b/docs/tutorial/LangImpl7.html index f560648..ec07fa8 100644 --- a/docs/tutorial/LangImpl7.html +++ b/docs/tutorial/LangImpl7.html @@ -424,7 +424,8 @@ static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction, const std::string &VarName) { IRBuilder<> TmpB(&TheFunction->getEntryBlock(), TheFunction->getEntryBlock().begin()); - return TmpB.CreateAlloca(Type::DoubleTy, 0, VarName.c_str()); + return TmpB.CreateAlloca(Type::getDoubleTy(getGlobalContext()), 0, + VarName.c_str()); } </pre> </div> @@ -923,7 +924,7 @@ that we replace in OldBindings.</p> InitVal = Init->Codegen(); if (InitVal == 0) return 0; } else { // If not specified, use 0.0. - InitVal = ConstantFP::get(APFloat(0.0)); + InitVal = ConstantFP::get(getGlobalContext(), APFloat(0.0)); } AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName); @@ -1003,11 +1004,15 @@ variables and var/in support. To build this example, use: <pre> #include "llvm/DerivedTypes.h" #include "llvm/ExecutionEngine/ExecutionEngine.h" +#include "llvm/ExecutionEngine/Interpreter.h" +#include "llvm/ExecutionEngine/JIT.h" +#include "llvm/LLVMContext.h" #include "llvm/Module.h" #include "llvm/ModuleProvider.h" #include "llvm/PassManager.h" #include "llvm/Analysis/Verifier.h" #include "llvm/Target/TargetData.h" +#include "llvm/Target/TargetSelect.h" #include "llvm/Transforms/Scalar.h" #include "llvm/Support/IRBuilder.h" #include <cstdio> @@ -1192,7 +1197,8 @@ public: }; /// PrototypeAST - This class represents the "prototype" for a function, -/// which captures its argument names as well as if it is an operator. +/// which captures its name, and its argument names (thus implicitly the number +/// of arguments the function takes), as well as if it is an operator. class PrototypeAST { std::string Name; std::vector<std::string> Args; @@ -1234,7 +1240,7 @@ public: //===----------------------------------------------------------------------===// /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current -/// token the parser it looking at. getNextToken reads another token from the +/// token the parser is looking at. getNextToken reads another token from the /// lexer and updates CurTok with its results. static int CurTok; static int getNextToken() { @@ -1282,9 +1288,9 @@ static ExprAST *ParseIdentifierExpr() { ExprAST *Arg = ParseExpression(); if (!Arg) return 0; Args.push_back(Arg); - + if (CurTok == ')') break; - + if (CurTok != ',') return Error("Expected ')' or ',' in argument list"); getNextToken(); @@ -1429,7 +1435,6 @@ static ExprAST *ParseVarExpr() { return new VarExprAST(VarNames, Body); } - /// primary /// ::= identifierexpr /// ::= numberexpr @@ -1515,7 +1520,7 @@ static ExprAST *ParseExpression() { static PrototypeAST *ParsePrototype() { std::string FnName; - int Kind = 0; // 0 = identifier, 1 = unary, 2 = binary. + unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary. unsigned BinaryPrecedence = 30; switch (CurTok) { @@ -1605,7 +1610,7 @@ static PrototypeAST *ParseExtern() { //===----------------------------------------------------------------------===// static Module *TheModule; -static IRBuilder<> Builder; +static IRBuilder<> Builder(getGlobalContext()); static std::map<std::string, AllocaInst*> NamedValues; static FunctionPassManager *TheFPM; @@ -1617,12 +1622,12 @@ static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction, const std::string &VarName) { IRBuilder<> TmpB(&TheFunction->getEntryBlock(), TheFunction->getEntryBlock().begin()); - return TmpB.CreateAlloca(Type::DoubleTy, 0, VarName.c_str()); + return TmpB.CreateAlloca(Type::getDoubleTy(getGlobalContext()), 0, + VarName.c_str()); } - Value *NumberExprAST::Codegen() { - return ConstantFP::get(APFloat(Val)); + return ConstantFP::get(getGlobalContext(), APFloat(Val)); } Value *VariableExprAST::Codegen() { @@ -1645,7 +1650,6 @@ Value *UnaryExprAST::Codegen() { return Builder.CreateCall(F, OperandV, "unop"); } - Value *BinaryExprAST::Codegen() { // Special case '=' because we don't want to emit the LHS as an expression. if (Op == '=') { @@ -1665,7 +1669,6 @@ Value *BinaryExprAST::Codegen() { return Val; } - Value *L = LHS->Codegen(); Value *R = RHS->Codegen(); if (L == 0 || R == 0) return 0; @@ -1677,7 +1680,8 @@ Value *BinaryExprAST::Codegen() { case '<': L = Builder.CreateFCmpULT(L, R, "cmptmp"); // Convert bool 0/1 to double 0.0 or 1.0 - return Builder.CreateUIToFP(L, Type::DoubleTy, "booltmp"); + return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()), + "booltmp"); default: break; } @@ -1715,16 +1719,16 @@ Value *IfExprAST::Codegen() { // Convert condition to a bool by comparing equal to 0.0. CondV = Builder.CreateFCmpONE(CondV, - ConstantFP::get(APFloat(0.0)), + ConstantFP::get(getGlobalContext(), APFloat(0.0)), "ifcond"); Function *TheFunction = Builder.GetInsertBlock()->getParent(); // Create blocks for the then and else cases. Insert the 'then' block at the // end of the function. - BasicBlock *ThenBB = BasicBlock::Create("then", TheFunction); - BasicBlock *ElseBB = BasicBlock::Create("else"); - BasicBlock *MergeBB = BasicBlock::Create("ifcont"); + BasicBlock *ThenBB = BasicBlock::Create(getGlobalContext(), "then", TheFunction); + BasicBlock *ElseBB = BasicBlock::Create(getGlobalContext(), "else"); + BasicBlock *MergeBB = BasicBlock::Create(getGlobalContext(), "ifcont"); Builder.CreateCondBr(CondV, ThenBB, ElseBB); @@ -1752,7 +1756,8 @@ Value *IfExprAST::Codegen() { // Emit merge block. TheFunction->getBasicBlockList().push_back(MergeBB); Builder.SetInsertPoint(MergeBB); - PHINode *PN = Builder.CreatePHI(Type::DoubleTy, "iftmp"); + PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), + "iftmp"); PN->addIncoming(ThenV, ThenBB); PN->addIncoming(ElseV, ElseBB); @@ -1794,8 +1799,7 @@ Value *ForExprAST::Codegen() { // Make the new basic block for the loop header, inserting after current // block. - BasicBlock *PreheaderBB = Builder.GetInsertBlock(); - BasicBlock *LoopBB = BasicBlock::Create("loop", TheFunction); + BasicBlock *LoopBB = BasicBlock::Create(getGlobalContext(), "loop", TheFunction); // Insert an explicit fall through from the current block to the LoopBB. Builder.CreateBr(LoopBB); @@ -1821,7 +1825,7 @@ Value *ForExprAST::Codegen() { if (StepVal == 0) return 0; } else { // If not specified, use 1.0. - StepVal = ConstantFP::get(APFloat(1.0)); + StepVal = ConstantFP::get(getGlobalContext(), APFloat(1.0)); } // Compute the end condition. @@ -1836,12 +1840,11 @@ Value *ForExprAST::Codegen() { // Convert condition to a bool by comparing equal to 0.0. EndCond = Builder.CreateFCmpONE(EndCond, - ConstantFP::get(APFloat(0.0)), + ConstantFP::get(getGlobalContext(), APFloat(0.0)), "loopcond"); // Create the "after loop" block and insert it. - BasicBlock *LoopEndBB = Builder.GetInsertBlock(); - BasicBlock *AfterBB = BasicBlock::Create("afterloop", TheFunction); + BasicBlock *AfterBB = BasicBlock::Create(getGlobalContext(), "afterloop", TheFunction); // Insert the conditional branch into the end of LoopEndBB. Builder.CreateCondBr(EndCond, LoopBB, AfterBB); @@ -1857,7 +1860,7 @@ Value *ForExprAST::Codegen() { // for expr always returns 0.0. - return Constant::getNullValue(Type::DoubleTy); + return Constant::getNullValue(Type::getDoubleTy(getGlobalContext())); } Value *VarExprAST::Codegen() { @@ -1880,7 +1883,7 @@ Value *VarExprAST::Codegen() { InitVal = Init->Codegen(); if (InitVal == 0) return 0; } else { // If not specified, use 0.0. - InitVal = ConstantFP::get(APFloat(0.0)); + InitVal = ConstantFP::get(getGlobalContext(), APFloat(0.0)); } AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName); @@ -1906,11 +1909,12 @@ Value *VarExprAST::Codegen() { return BodyVal; } - Function *PrototypeAST::Codegen() { // Make the function type: double(double,double) etc. - std::vector<const Type*> Doubles(Args.size(), Type::DoubleTy); - FunctionType *FT = FunctionType::get(Type::DoubleTy, Doubles, false); + std::vector<const Type*> Doubles(Args.size(), + Type::getDoubleTy(getGlobalContext())); + FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), + Doubles, false); Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule); @@ -1959,7 +1963,6 @@ void PrototypeAST::CreateArgumentAllocas(Function *F) { } } - Function *FunctionAST::Codegen() { NamedValues.clear(); @@ -1972,12 +1975,12 @@ Function *FunctionAST::Codegen() { BinopPrecedence[Proto->getOperatorName()] = Proto->getBinaryPrecedence(); // Create a new basic block to start insertion into. - BasicBlock *BB = BasicBlock::Create("entry", TheFunction); + BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction); Builder.SetInsertPoint(BB); // Add all arguments to the symbol table and create their allocas. Proto->CreateArgumentAllocas(TheFunction); - + if (Value *RetVal = Body->Codegen()) { // Finish off the function. Builder.CreateRet(RetVal); @@ -2030,7 +2033,7 @@ static void HandleExtern() { } static void HandleTopLevelExpression() { - // Evaluate a top level expression into an anonymous function. + // Evaluate a top-level expression into an anonymous function. if (FunctionAST *F = ParseTopLevelExpr()) { if (Function *LF = F->Codegen()) { // JIT the function, returning a function pointer. @@ -2038,7 +2041,7 @@ static void HandleTopLevelExpression() { // Cast it to the right type (takes no arguments, returns a double) so we // can call it as a native function. - double (*FP)() = (double (*)())FPtr; + double (*FP)() = (double (*)())(intptr_t)FPtr; fprintf(stderr, "Evaluated to %f\n", FP()); } } else { @@ -2053,7 +2056,7 @@ static void MainLoop() { fprintf(stderr, "ready> "); switch (CurTok) { case tok_eof: return; - case ';': getNextToken(); break; // ignore top level semicolons. + case ';': getNextToken(); break; // ignore top-level semicolons. case tok_def: HandleDefinition(); break; case tok_extern: HandleExtern(); break; default: HandleTopLevelExpression(); break; @@ -2061,8 +2064,6 @@ static void MainLoop() { } } - - //===----------------------------------------------------------------------===// // "Library" functions that can be "extern'd" from user code. //===----------------------------------------------------------------------===// @@ -2086,6 +2087,9 @@ double printd(double X) { //===----------------------------------------------------------------------===// int main() { + InitializeNativeTarget(); + LLVMContext &Context = getGlobalContext(); + // Install standard binary operators. // 1 is lowest precedence. BinopPrecedence['='] = 2; @@ -2099,42 +2103,43 @@ int main() { getNextToken(); // Make the module, which holds all the code. - TheModule = new Module("my cool jit"); - - // Create the JIT. - TheExecutionEngine = ExecutionEngine::create(TheModule); + TheModule = new Module("my cool jit", Context); - { - ExistingModuleProvider OurModuleProvider(TheModule); - FunctionPassManager OurFPM(&OurModuleProvider); - - // Set up the optimizer pipeline. Start with registering info about how the - // target lays out data structures. - OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData())); - // Promote allocas to registers. - OurFPM.add(createPromoteMemoryToRegisterPass()); - // Do simple "peephole" optimizations and bit-twiddling optzns. - OurFPM.add(createInstructionCombiningPass()); - // Reassociate expressions. - OurFPM.add(createReassociatePass()); - // Eliminate Common SubExpressions. - OurFPM.add(createGVNPass()); - // Simplify the control flow graph (deleting unreachable blocks, etc). - OurFPM.add(createCFGSimplificationPass()); + ExistingModuleProvider *OurModuleProvider = + new ExistingModuleProvider(TheModule); - // Set the global so the code gen can use this. - TheFPM = &OurFPM; + // Create the JIT. This takes ownership of the module and module provider. + TheExecutionEngine = EngineBuilder(OurModuleProvider).create(); + + FunctionPassManager OurFPM(OurModuleProvider); + + // Set up the optimizer pipeline. Start with registering info about how the + // target lays out data structures. + OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData())); + // Promote allocas to registers. + OurFPM.add(createPromoteMemoryToRegisterPass()); + // Do simple "peephole" optimizations and bit-twiddling optzns. + OurFPM.add(createInstructionCombiningPass()); + // Reassociate expressions. + OurFPM.add(createReassociatePass()); + // Eliminate Common SubExpressions. + OurFPM.add(createGVNPass()); + // Simplify the control flow graph (deleting unreachable blocks, etc). + OurFPM.add(createCFGSimplificationPass()); + + OurFPM.doInitialization(); + + // Set the global so the code gen can use this. + TheFPM = &OurFPM; + + // Run the main "interpreter loop" now. + MainLoop(); + + TheFPM = 0; + + // Print out all of the generated code. + TheModule->dump(); - // Run the main "interpreter loop" now. - MainLoop(); - - TheFPM = 0; - - // Print out all of the generated code. - TheModule->dump(); - - } // Free module provider (and thus the module) and pass manager. - return 0; } </pre> diff --git a/docs/tutorial/OCamlLangImpl3.html b/docs/tutorial/OCamlLangImpl3.html index 9caae43..a598875 100644 --- a/docs/tutorial/OCamlLangImpl3.html +++ b/docs/tutorial/OCamlLangImpl3.html @@ -95,8 +95,8 @@ an undeclared parameter):</p> <pre> exception Error of string -let the_module = create_module "my cool jit" -let builder = builder () +let the_module = create_module (global_context ()) "my cool jit" +let builder = builder (global_context ()) let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10 </pre> </div> @@ -159,7 +159,7 @@ uses "the foo::get(..)" idiom instead of "new foo(..)" or "foo::Create(..)".</p> </div> <p>References to variables are also quite simple using LLVM. In the simple -version of Kaleidoscope, we assume that the variable has already been emited +version of Kaleidoscope, we assume that the variable has already been emitted somewhere and its value is available. In practice, the only values that can be in the <tt>Codegen.named_values</tt> map are function arguments. This code simply checks to see that the specified name is in the map (if not, an unknown @@ -323,7 +323,7 @@ code above.</p> first, we want to allow 'extern'ing a function more than once, as long as the prototypes for the externs match (since all arguments have the same type, we just have to check that the number of arguments match). Second, we want to -allow 'extern'ing a function and then definining a body for it. This is useful +allow 'extern'ing a function and then defining a body for it. This is useful when defining mutually recursive functions.</p> <div class="doc_code"> @@ -899,8 +899,9 @@ open Llvm exception Error of string -let the_module = create_module "my cool jit" -let builder = builder () +let context = global_context () +let the_module = create_module context "my cool jit" +let builder = builder context let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10 let rec codegen_expr = function diff --git a/docs/tutorial/OCamlLangImpl4.html b/docs/tutorial/OCamlLangImpl4.html index ffa85d5..26f2532 100644 --- a/docs/tutorial/OCamlLangImpl4.html +++ b/docs/tutorial/OCamlLangImpl4.html @@ -206,6 +206,8 @@ add a set of optimizations to run. The code looks like this:</p> (* Simplify the control flow graph (deleting unreachable blocks, etc). *) add_cfg_simplification the_fpm; + ignore (PassManager.initialize the_fpm); + (* Run the main "interpreter loop" now. *) Toplevel.main_loop the_fpm the_execution_engine stream; </pre> @@ -222,7 +224,7 @@ requires a pointer to the <tt>the_module</tt> (through the <tt>the_module_provider</tt>) to construct itself. Once it is set up, we use a series of "add" calls to add a bunch of LLVM passes. The first pass is basically boilerplate, it adds a pass so that later optimizations know how the -data structures in the program are layed out. The +data structures in the program are laid out. The "<tt>the_execution_engine</tt>" variable is related to the JIT, which we will get to in the next section.</p> @@ -795,8 +797,9 @@ open Llvm exception Error of string -let the_module = create_module "my cool jit" -let builder = builder () +let context = global_context () +let the_module = create_module context "my cool jit" +let builder = builder context let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10 let rec codegen_expr = function @@ -959,6 +962,8 @@ open Llvm_target open Llvm_scalar_opts let main () = + ignore (initialize_native_target ()); + (* Install standard binary operators. * 1 is the lowest precedence. *) Hashtbl.add Parser.binop_precedence '<' 10; @@ -991,6 +996,8 @@ let main () = (* Simplify the control flow graph (deleting unreachable blocks, etc). *) add_cfg_simplification the_fpm; + ignore (PassManager.initialize the_fpm); + (* Run the main "interpreter loop" now. *) Toplevel.main_loop the_fpm the_execution_engine stream; diff --git a/docs/tutorial/OCamlLangImpl5.html b/docs/tutorial/OCamlLangImpl5.html index 594a77d..f19e900 100644 --- a/docs/tutorial/OCamlLangImpl5.html +++ b/docs/tutorial/OCamlLangImpl5.html @@ -271,8 +271,8 @@ into "t.ll" and run "<tt>llvm-as < t.ll | opt -analyze -view-cfg</tt>", <a href="../ProgrammersManual.html#ViewGraph">a window will pop up</a> and you'll see this graph:</p> -<center><img src="LangImpl5-cfg.png" alt="Example CFG" width="423" -height="315"></center> +<div style="text-align: center"><img src="LangImpl5-cfg.png" alt="Example CFG" width="423" +height="315"></div> <p>Another way to get this is to call "<tt>Llvm_analysis.view_function_cfg f</tt>" or "<tt>Llvm_analysis.view_function_cfg_only f</tt>" (where <tt>f</tt> @@ -1200,8 +1200,9 @@ open Llvm exception Error of string -let the_module = create_module "my cool jit" -let builder = builder () +let context = global_context () +let the_module = create_module context "my cool jit" +let builder = builder context let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10 let rec codegen_expr = function @@ -1486,6 +1487,8 @@ open Llvm_target open Llvm_scalar_opts let main () = + ignore (initialize_native_target ()); + (* Install standard binary operators. * 1 is the lowest precedence. *) Hashtbl.add Parser.binop_precedence '<' 10; @@ -1518,6 +1521,8 @@ let main () = (* Simplify the control flow graph (deleting unreachable blocks, etc). *) add_cfg_simplification the_fpm; + ignore (PassManager.initialize the_fpm); + (* Run the main "interpreter loop" now. *) Toplevel.main_loop the_fpm the_execution_engine stream; diff --git a/docs/tutorial/OCamlLangImpl6.html b/docs/tutorial/OCamlLangImpl6.html index 780cab8..2edb22e 100644 --- a/docs/tutorial/OCamlLangImpl6.html +++ b/docs/tutorial/OCamlLangImpl6.html @@ -1173,8 +1173,9 @@ open Llvm exception Error of string -let the_module = create_module "my cool jit" -let builder = builder () +let context = global_context () +let the_module = create_module context "my cool jit" +let builder = builder context let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10 let rec codegen_expr = function @@ -1485,6 +1486,8 @@ open Llvm_target open Llvm_scalar_opts let main () = + ignore (initialize_native_target ()); + (* Install standard binary operators. * 1 is the lowest precedence. *) Hashtbl.add Parser.binop_precedence '<' 10; @@ -1517,6 +1520,8 @@ let main () = (* Simplify the control flow graph (deleting unreachable blocks, etc). *) add_cfg_simplification the_fpm; + ignore (PassManager.initialize the_fpm); + (* Run the main "interpreter loop" now. *) Toplevel.main_loop the_fpm the_execution_engine stream; diff --git a/docs/tutorial/OCamlLangImpl7.html b/docs/tutorial/OCamlLangImpl7.html index abda440..0776821 100644 --- a/docs/tutorial/OCamlLangImpl7.html +++ b/docs/tutorial/OCamlLangImpl7.html @@ -1384,14 +1384,15 @@ open Llvm exception Error of string -let the_module = create_module "my cool jit" -let builder = builder () +let context = global_context () +let the_module = create_module context "my cool jit" +let builder = builder context let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10 (* Create an alloca instruction in the entry block of the function. This * is used for mutable variables etc. *) let create_entry_block_alloca the_function var_name = - let builder = builder_at (instr_begin (entry_block the_function)) in + let builder = builder_at context (instr_begin (entry_block the_function)) in build_alloca double_type var_name builder let rec codegen_expr = function @@ -1815,6 +1816,8 @@ open Llvm_target open Llvm_scalar_opts let main () = + ignore (initialize_native_target ()); + (* Install standard binary operators. * 1 is the lowest precedence. *) Hashtbl.add Parser.binop_precedence '=' 2; @@ -1851,6 +1854,8 @@ let main () = (* Simplify the control flow graph (deleting unreachable blocks, etc). *) add_cfg_simplification the_fpm; + ignore (PassManager.initialize the_fpm); + (* Run the main "interpreter loop" now. *) Toplevel.main_loop the_fpm the_execution_engine stream; |
