diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/CodingStandards.html | 65 | ||||
| -rw-r--r-- | docs/CompilerDriver.html | 29 | ||||
| -rw-r--r-- | docs/FAQ.html | 143 | ||||
| -rw-r--r-- | docs/ReleaseNotes-2.6.html | 11 | ||||
| -rw-r--r-- | docs/TableGenFundamentals.html | 5 | ||||
| -rw-r--r-- | docs/WritingAnLLVMPass.html | 15 |
6 files changed, 253 insertions, 15 deletions
diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html index 84ca8fa9..cf91110 100644 --- a/docs/CodingStandards.html +++ b/docs/CodingStandards.html @@ -50,6 +50,8 @@ <li><a href="#ll_ns_std">Do not use 'using namespace std'</a></li> <li><a href="#ll_virtual_anch">Provide a virtual method anchor for 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_avoidendl">Avoid <tt>std::endl</tt></a></li> </ol></li> @@ -661,6 +663,67 @@ increasing link times.</p> </div> +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="ll_end">Don't evaluate end() every time through a loop</a> +</div> + +<div class="doc_text"> + +<p>Because C++ doesn't have a standard "foreach" loop (though it can be emulated +with macros and may be coming in C++'0x) we end up writing a lot of loops that +manually iterate from begin to end on a variety of containers or through other +data structures. One common mistake is to write a loop in this style:</p> + +<div class="doc_code"> +<pre> + BasicBlock *BB = ... + for (BasicBlock::iterator I = BB->begin(); I != <b>BB->end()</b>; ++I) + ... use I ... +</pre> +</div> + +<p>The problem with this construct is that it evaluates "<tt>BB->end()</tt>" +every time through the loop. Instead of writing the loop like this, we strongly +prefer loops to be written so that they evaluate it once before the loop starts. +A convenient way to do this is like so:</p> + +<div class="doc_code"> +<pre> + BasicBlock *BB = ... + for (BasicBlock::iterator I = BB->begin(), E = <b>BB->end()</b>; I != E; ++I) + ... use I ... +</pre> +</div> + +<p>The observant may quickly point out that these two loops may have different +semantics: if the container (a basic block in this case) is being mutated, then +"<tt>BB->end()</tt>" may change its value every time through the loop and the +second loop may not in fact be correct. If you actually do depend on this +behavior, please write the loop in the first form and add a comment indicating +that you did it intentionally.</p> + +<p>Why do we prefer the second form (when correct)? Writing the loop in the +first form has two problems: First it may be less efficient than evaluating it +at the start of the loop. In this case, the cost is probably minor: a few extra +loads every time through the loop. However, if the base expression is more +complex, then the cost can rise quickly. I've seen loops where the end +expression was actually something like: "<tt>SomeMap[x]->end()</tt>" and map +lookups really aren't cheap. By writing it in the second form consistently, you +eliminate the issue entirely and don't even have to think about it.</p> + +<p>The second (even bigger) issue is that writing the loop in the first form +hints to the reader that the loop is mutating the container (a fact that a +comment would handily confirm!). If you write the loop in the second form, it +is immediately obvious without even looking at the body of the loop that the +container isn't being modified, which makes it easier to read the code and +understand what it does.</p> + +<p>While the second form of the loop is a few extra keystrokes, we do strongly +prefer it.</p> + +</div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> @@ -744,7 +807,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-03-23 05:53:34 +0100 (Mon, 23 Mar 2009) $ + Last modified: $Date: 2009-06-30 08:27:54 +0200 (Tue, 30 Jun 2009) $ </address> </body> diff --git a/docs/CompilerDriver.html b/docs/CompilerDriver.html index e79ec5c..6b531c4 100644 --- a/docs/CompilerDriver.html +++ b/docs/CompilerDriver.html @@ -37,6 +37,7 @@ The ReST source lives in the directory 'tools/llvmc/doc'. --> <li><a class="reference internal" href="#hooks-and-environment-variables" id="id17">Hooks and environment variables</a></li> <li><a class="reference internal" href="#how-plugins-are-loaded" id="id18">How plugins are loaded</a></li> <li><a class="reference internal" href="#debugging" id="id19">Debugging</a></li> +<li><a class="reference internal" href="#conditioning-on-the-executable-name" id="id20">Conditioning on the executable name</a></li> </ul> </li> </ul> @@ -94,9 +95,8 @@ $ llvmc --linker=c++ hello.o $ ./a.out hello </pre> -<p>By default, LLVMC uses <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> to compile the source code. It is -also possible to choose the work-in-progress <tt class="docutils literal"><span class="pre">clang</span></tt> compiler with -the <tt class="docutils literal"><span class="pre">-clang</span></tt> option.</p> +<p>By default, LLVMC uses <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> to compile the source code. It is also +possible to choose the <tt class="docutils literal"><span class="pre">clang</span></tt> compiler with the <tt class="docutils literal"><span class="pre">-clang</span></tt> option.</p> </div> <div class="section" id="predefined-options"> <h1><a class="toc-backref" href="#id6">Predefined options</a></h1> @@ -633,6 +633,27 @@ be performed at compile-time because the plugins can load code dynamically. When invoked with <tt class="docutils literal"><span class="pre">--check-graph</span></tt>, <tt class="docutils literal"><span class="pre">llvmc</span></tt> doesn't perform any compilation tasks and returns the number of encountered errors as its status code.</p> +</div> +<div class="section" id="conditioning-on-the-executable-name"> +<h2><a class="toc-backref" href="#id20">Conditioning on the executable name</a></h2> +<p>For now, the executable name (the value passed to the driver in <tt class="docutils literal"><span class="pre">argv[0]</span></tt>) is +accessible only in the C++ code (i.e. hooks). Use the following code:</p> +<pre class="literal-block"> +namespace llvmc { +extern const char* ProgramName; +} + +std::string MyHook() { +//... +if (strcmp(ProgramName, "mydriver") == 0) { + //... + +} +</pre> +<p>In general, you're encouraged not to make the behaviour dependent on the +executable file name, and use command-line switches instead. See for example how +the <tt class="docutils literal"><span class="pre">Base</span></tt> plugin behaves when it needs to choose the correct linker options +(think <tt class="docutils literal"><span class="pre">g++</span></tt> vs. <tt class="docutils literal"><span class="pre">gcc</span></tt>).</p> <hr /> <address> <a href="http://jigsaw.w3.org/css-validator/check/referer"> @@ -645,7 +666,7 @@ errors as its status code.</p> <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-25 20:21:10 +0200 (Thu, 25 Jun 2009) $ +Last modified: $Date: 2009-06-30 02:16:43 +0200 (Tue, 30 Jun 2009) $ </address></div> </div> </div> diff --git a/docs/FAQ.html b/docs/FAQ.html index eae612c..9fd8928 100644 --- a/docs/FAQ.html +++ b/docs/FAQ.html @@ -124,6 +124,10 @@ <li><a href="#undef">What is this "<tt>undef</tt>" thing that shows up in my code?</a></li> + + <li><a href="#callconvwrong">Why does instcombine + simplifycfg turn + a call to a function with a mismatched calling convention into "unreachable"? + Why not make the verifier reject it?</a></li> </ol> </li> </ol> @@ -780,6 +784,143 @@ int X() { int i; return i; } value specified for it.</p> </div> +<!--=========================================================================--> + +<div class="question"> +<p><a name="callconvwrong">Why does instcombine + simplifycfg turn + a call to a function with a mismatched calling convention into "unreachable"? + Why not make the verifier reject it?</a></p> +</div> + +<div class="answer"> +<p>This is a common problem run into by authors of front-ends that are using +custom calling conventions: you need to make sure to set the right calling +convention on both the function and on each call to the function. For example, +this code:</p> + +<pre class="doc_code"> +define fastcc void @foo() { + ret void +} +define void @bar() { + call void @foo( ) + ret void +} +</pre> + +<p>Is optimized to:</p> + +<pre class="doc_code"> +define fastcc void @foo() { + ret void +} +define void @bar() { + unreachable +} +</pre> + +<p>... with "opt -instcombine -simplifycfg". This often bites people because +"all their code disappears". Setting the calling convention on the caller and +callee is required for indirect calls to work, so people often ask why not make +the verifier reject this sort of thing.</p> + +<p>The answer is that this code has undefined behavior, but it is not illegal. +If we made it illegal, then every transformation that could potentially create +this would have to ensure that it doesn't, and there is valid code that can +create this sort of construct (in dead code). The sorts of things that can +cause this to happen are fairly contrived, but we still need to accept them. +Here's an example:</p> + +<pre class="doc_code"> +define fastcc void @foo() { + ret void +} +define internal void @bar(void()* %FP, i1 %cond) { + br i1 %cond, label %T, label %F +T: + call void %FP() + ret void +F: + call fastcc void %FP() + ret void +} +define void @test() { + %X = or i1 false, false + call void @bar(void()* @foo, i1 %X) + ret void +} +</pre> + +<p>In this example, "test" always passes @foo/false into bar, which ensures that + it is dynamically called with the right calling conv (thus, the code is + perfectly well defined). If you run this through the inliner, you get this + (the explicit "or" is there so that the inliner doesn't dead code eliminate + a bunch of stuff): +</p> + +<pre class="doc_code"> +define fastcc void @foo() { + ret void +} +define void @test() { + %X = or i1 false, false + br i1 %X, label %T.i, label %F.i +T.i: + call void @foo() + br label %bar.exit +F.i: + call fastcc void @foo() + br label %bar.exit +bar.exit: + ret void +} +</pre> + +<p>Here you can see that the inlining pass made an undefined call to @foo with + the wrong calling convention. We really don't want to make the inliner have + to know about this sort of thing, so it needs to be valid code. In this case, + dead code elimination can trivially remove the undefined code. However, if %X + was an input argument to @test, the inliner would produce this: +</p> + +<pre class="doc_code"> +define fastcc void @foo() { + ret void +} + +define void @test(i1 %X) { + br i1 %X, label %T.i, label %F.i +T.i: + call void @foo() + br label %bar.exit +F.i: + call fastcc void @foo() + br label %bar.exit +bar.exit: + ret void +} +</pre> + +<p>The interesting thing about this is that %X <em>must</em> be false for the +code to be well-defined, but no amount of dead code elimination will be able to +delete the broken call as unreachable. However, since instcombine/simplifycfg +turns the undefined call into unreachable, we end up with a branch on a +condition that goes to unreachable: a branch to unreachable can never happen, so +"-inline -instcombine -simplifycfg" is able to produce:</p> + +<pre class="doc_code"> +define fastcc void @foo() { + ret void +} +define void @test(i1 %X) { +F.i: + call fastcc void @foo() + ret void +} +</pre> + +</div> + <!-- *********************************************************************** --> <hr> @@ -790,7 +931,7 @@ int X() { int i; return 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-04-10 22:48:27 +0200 (Fri, 10 Apr 2009) $ + Last modified: $Date: 2009-06-30 19:10:19 +0200 (Tue, 30 Jun 2009) $ </address> </body> diff --git a/docs/ReleaseNotes-2.6.html b/docs/ReleaseNotes-2.6.html index ddf3db4..64084cd 100644 --- a/docs/ReleaseNotes-2.6.html +++ b/docs/ReleaseNotes-2.6.html @@ -419,7 +419,7 @@ it run faster:</p> <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> @@ -433,6 +433,13 @@ from the previous release.</p> API changes are:</p> <ul> +<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> </ul> @@ -770,7 +777,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-06-24 23:26:42 +0200 (Wed, 24 Jun 2009) $ + Last modified: $Date: 2009-07-02 18:48:38 +0200 (Thu, 02 Jul 2009) $ </address> </body> diff --git a/docs/TableGenFundamentals.html b/docs/TableGenFundamentals.html index 48c60b9..568b572 100644 --- a/docs/TableGenFundamentals.html +++ b/docs/TableGenFundamentals.html @@ -411,7 +411,8 @@ which case the user must specify it explicitly.</dd> <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. </dd> +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> <dt><tt>!subst(a, b, c)</tt></dt> @@ -781,7 +782,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-09 20:31:17 +0200 (Tue, 09 Jun 2009) $ + Last modified: $Date: 2009-06-29 22:05:29 +0200 (Mon, 29 Jun 2009) $ </address> </body> diff --git a/docs/WritingAnLLVMPass.html b/docs/WritingAnLLVMPass.html index b1b2c78..dd8b41d 100644 --- a/docs/WritingAnLLVMPass.html +++ b/docs/WritingAnLLVMPass.html @@ -491,10 +491,15 @@ 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 functions. Because nothing is known about the behavior of <tt>ModulePass</tt> -subclasses, no optimization can be done for their execution. A module pass -can use function level passes (e.g. dominators) using getAnalysis interface -<tt> getAnalysis<DominatorTree>(Function)</tt>, if the function pass -does not require any module passes. </p> +subclasses, no optimization can be done for their execution.</p> + +<p>A module pass can use function level passes (e.g. dominators) using +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 +analysis ran, e.g. in the case of dominators you should only ask for the +DominatorTree for function definitions, not declarations.</p> <p>To write a correct <tt>ModulePass</tt> subclass, derive from <tt>ModulePass</tt> and overload the <tt>runOnModule</tt> method with the @@ -1821,7 +1826,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-06-15 18:22:49 +0000 (Mon, 15 Jun 2009) $ + Last modified: $Date: 2009-07-02 01:38:44 +0200 (Thu, 02 Jul 2009) $ </address> </body> |
