[llvm-commits] [llvm] r63502 - /llvm/trunk/docs/LangRef.html

[Chris Lattner]

Author: lattner
Date: Mon Feb  2 01:32:36 2009
New Revision: 63502

URL: http://llvm.org/viewvc/llvm-project?rev=63502&view=rev
Log:
Document type upreferences (PR3380), patch by Stein Roger Skafløtten
with enhancements and corrections by me.


Modified:
    llvm/trunk/docs/LangRef.html

Modified: llvm/trunk/docs/LangRef.html
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/LangRef.html?rev=63502&r1=63501&r2=63502&view=diff

==============================================================================
--- llvm/trunk/docs/LangRef.html (original)
+++ llvm/trunk/docs/LangRef.html Mon Feb  2 01:32:36 2009
@@ -55,6 +55,7 @@
           <li><a href="#t_opaque">Opaque Type</a></li>
         </ol>
       </li>
+      <li><a href="#t_uprefs">Type Up-references</a></li>
     </ol>
   </li>
   <li><a href="#constants">Constants</a>
@@ -722,7 +723,6 @@
 
 </div>
 
-
 <!-- ======================================================================= -->
 <div class="doc_subsection">
   <a name="globalvars">Global Variables</a>
@@ -1646,6 +1646,58 @@
 </table>
 </div>
 
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="t_uprefs">Type Up-references</a>
+</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>
+
+<pre>
+   { \2 * }                %x = type { %t* }
+   { \2 }*                 %y = type { %y }*
+   \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>
+
+<h5>Syntax:</h5>
+<pre>
+   \<level>
+</pre>
+
+<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>
+    <td class="left">Self-referential pointer.</td>
+  </tr>
+  <tr class="layout">
+    <td class="left"><tt>{ { \3*, i8 }, i32 }</tt></td>
+    <td class="left">Recursive structure where the upref refers to the out-most
+                     structure.</td>
+  </tr>
+</table>
+</div>
+
+</div>
+
 
 <!-- *********************************************************************** -->
 <div class="doc_section"> <a name="constants">Constants</a> </div>