[llvm-commits] [llvm] r143134 - in /llvm/trunk/docs: GetElementPtr.html LangRef.html

[Peter Collingbourne]

Author: pcc
Date: Thu Oct 27 14:19:07 2011
New Revision: 143134

URL: http://llvm.org/viewvc/llvm-project?rev=143134&view=rev
Log:
Document tbaa metadata in LangRef (documentation largely based on
comments at top of TypeBasedAliasAnalysis.cpp).

Modified:
    llvm/trunk/docs/GetElementPtr.html
    llvm/trunk/docs/LangRef.html

Modified: llvm/trunk/docs/GetElementPtr.html
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/GetElementPtr.html?rev=143134&r1=143133&r2=143134&view=diff
==============================================================================
--- llvm/trunk/docs/GetElementPtr.html (original)
+++ llvm/trunk/docs/GetElementPtr.html Thu Oct 27 14:19:07 2011
@@ -594,10 +594,10 @@
      because LLVM has no restrictions on mixing types in addressing, loads or
      stores.</p>
 
-  <p>It would be possible to add special annotations to the IR, probably using
-     metadata, to describe a different type system (such as the C type system),
-     and do type-based aliasing on top of that. This is a much bigger
-     undertaking though.</p>
+  <p>LLVM's type-based alias analysis pass uses metadata to describe a different
+     type system (such as the C type system), and performs type-based aliasing
+     on top of that.  Further details are in the
+     <a href="LangRef.html#tbaa">language reference</a>.</p>
 
 </div>
 

Modified: llvm/trunk/docs/LangRef.html
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/LangRef.html?rev=143134&r1=143133&r2=143134&view=diff
==============================================================================
--- llvm/trunk/docs/LangRef.html (original)
+++ llvm/trunk/docs/LangRef.html Thu Oct 27 14:19:07 2011
@@ -100,7 +100,11 @@
   <li><a href="#othervalues">Other Values</a>
     <ol>
       <li><a href="#inlineasm">Inline Assembler Expressions</a></li>
-      <li><a href="#metadata">Metadata Nodes and Metadata Strings</a></li>
+      <li><a href="#metadata">Metadata Nodes and Metadata Strings</a>
+        <ol>
+          <li><a href="#tbaa">'<tt>tbaa</tt>' Metadata</a></li>
+        </ol>
+      </li>
     </ol>
   </li>
   <li><a href="#intrinsic_globals">Intrinsic Global Variables</a>
@@ -2915,6 +2919,53 @@
 </pre>
 </div>
 
+<p>More information about specific metadata nodes recognized by the optimizers
+   and code generator is found below.</p>
+
+<h4>
+  <a name="tbaa">'<tt>tbaa</tt>' Metadata</a>
+</h4>
+
+<div>
+
+<p>In LLVM IR, memory does not have types, so LLVM's own type system is not
+   suitable for doing TBAA. Instead, metadata is added to the IR to describe
+   a type system of a higher level language. This can be used to implement
+   typical C/C++ TBAA, but it can also be used to implement custom alias
+   analysis behavior for other languages.</p>
+
+<p>The current metadata format is very simple. TBAA metadata nodes have up to
+   three fields, e.g.:</p>
+
+<div class="doc_code">
+<pre>
+!0 = metadata !{ metadata !"an example type tree" }
+!1 = metadata !{ metadata !"int", metadata !0 }
+!2 = metadata !{ metadata !"float", metadata !0 }
+!3 = metadata !{ metadata !"const float", metadata !2, i64 1 }
+</pre>
+</div>
+
+<p>The first field is an identity field. It can be any value, usually
+   a metadata string, which uniquely identifies the type. The most important
+   name in the tree is the name of the root node. Two trees with
+   different root node names are entirely disjoint, even if they
+   have leaves with common names.</p>
+
+<p>The second field identifies the type's parent node in the tree, or
+   is null or omitted for a root node. A type is considered to alias
+   all of its descendants and all of its ancestors in the tree. Also,
+   a type is considered to alias all types in other trees, so that
+   bitcode produced from multiple front-ends is handled conservatively.</p>
+
+<p>If the third field is present, it's an integer which if equal to 1
+   indicates that the type is "constant" (meaning
+   <tt>pointsToConstantMemory</tt> should return true; see
+   <a href="AliasAnalysis.html#OtherItfs">other useful
+   <tt>AliasAnalysis</tt> methods</a>).</p>
+
+</div>
+
 </div>
 
 </div>