More updates to objectsize intrinsic docs.

[oota-llvm.git] / docs / FAQ.html

diff --git a/docs/FAQ.html b/docs/FAQ.html
index 400e7c4f9c508cc50a4fa8a77aafe65ea07d4c2a..d62ffd715ab8fcaa9e94418e50e121ec448716ce 100644 (file)
--- 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="#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>
   </ol>
   </li>
 </ol>


@@ -426,7 +430,7 @@ Stop.
 </div>
 
 <div class="question">
 </div>
 
 <div class="question">

-<p><a href="srcdir-objdir">When I compile LLVM-GCC with srcdir == objdir, it
+<p><a name="srcdir-objdir">When I compile LLVM-GCC with srcdir == objdir, it

    fails. Why?</a></p>
 </div>
 
    fails. Why?</a></p>
 </div>
 


@@ -681,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
 <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>
 
    standard C++ libraries.</p>
 </div>
 


@@ -696,11 +700,11 @@ 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
    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
 
 <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

-   a constant immediately, thus hardwaring a platform-specific detail.</p>
+   a constant immediately, thus hard-wiring a platform-specific detail.</p>

 
 <p>Also, since many platforms define their ABIs in terms of C, and since LLVM is
    lower-level than C, front-ends currently must emit platform-specific IR in
 
 <p>Also, since many platforms define their ABIs in terms of C, and since LLVM is
    lower-level than C, front-ends currently must emit platform-specific IR in


@@ -780,6 +784,143 @@ int X() { int i; return i; }
    value specified for it.</p>
 </div>
 
    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>
 <!-- *********************************************************************** -->
 
 <hr>