Implement .rel relocation for R_ARM_ABS32 in MCJIT.
[oota-llvm.git] / docs / ExtendingLLVM.html
index 234a1543f71c26f666d808647d94e437b7edc706..99e209b89403027305729cee2082bdeeb0bad93c 100644 (file)
@@ -2,15 +2,16 @@
                       "http://www.w3.org/TR/html4/strict.dtd">
 <html>
 <head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   <title>Extending LLVM: Adding instructions, intrinsics, types, etc.</title>
-  <link rel="stylesheet" href="llvm.css" type="text/css">
+  <link rel="stylesheet" href="_static/llvm.css" type="text/css">
 </head>
 
 <body>
 
-<div class="doc_title">
+<h1>
   Extending LLVM: Adding instructions, intrinsics, types, etc.
-</div>
+</h1>
 
 <ol>
   <li><a href="#introduction">Introduction and Warning</a></li>
 </div>
 
 <!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
   <a name="introduction">Introduction and Warning</a>
-</div>
+</h2>
 <!-- *********************************************************************** -->
 
-<div class="doc_text">
+<div>
 
 <p>During the course of using LLVM, you may wish to customize it for your
 research project or for experimentation. At this point, you may realize that
@@ -53,9 +54,9 @@ different passes that you intend to use with your extension, and there are
 <em>many</em> LLVM analyses and transformations, so it may be quite a bit of
 work.</p>
 
-<p>Adding an <a href="#intrinsic">intrinsic function</a> is easier than adding
-an instruction, and is transparent to optimization passes which treat it as an
-unanalyzable function.  If your added functionality can be expressed as a
+<p>Adding an <a href="#intrinsic">intrinsic function</a> is far easier than
+adding an instruction, and is transparent to optimization passes.  If your added
+functionality can be expressed as a
 function call, an intrinsic function is the method of choice for LLVM
 extension.</p>
 
@@ -68,12 +69,12 @@ effort by doing so.</p>
 </div>
 
 <!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
   <a name="intrinsic">Adding a new intrinsic function</a>
-</div>
+</h2>
 <!-- *********************************************************************** -->
 
-<div class="doc_text">
+<div>
 
 <p>Adding a new intrinsic function to LLVM is much easier than adding a new
 instruction.  Almost all extensions to LLVM should start as an intrinsic
@@ -85,8 +86,12 @@ function and then be turned into an instruction if warranted.</p>
     what the restrictions are.  Talk to other people about it so that you are
     sure it's a good idea.</li>
 
-<li><tt>llvm/include/llvm/Intrinsics.td</tt>:
-    Add an entry for your intrinsic.</li>
+<li><tt>llvm/include/llvm/Intrinsics*.td</tt>:
+    Add an entry for your intrinsic.  Describe its memory access characteristics
+    for optimization (this controls whether it will be DCE'd, CSE'd, etc). Note
+    that any intrinsic using the <tt>llvm_int_ty</tt> type for an argument will
+    be deemed by <tt>tblgen</tt> as overloaded and the corresponding suffix 
+    will be required on the intrinsic's name.</li>
 
 <li><tt>llvm/lib/Analysis/ConstantFolding.cpp</tt>: If it is possible to 
     constant fold your intrinsic, add support to it in the 
@@ -100,48 +105,25 @@ function and then be turned into an instruction if warranted.</p>
 support for it.  Generally you must do the following steps:</p>
 
 <dl>
-<dt>Add support to the C backend in <tt>lib/Target/CBackend/</tt></dt>
-
-<dd>Depending on the intrinsic, there are a few ways to implement this.  For
-most intrinsics, it makes sense to add code to lower your intrinsic in 
-<tt>LowerIntrinsicCall</tt> in <tt>lib/CodeGen/IntrinsicLowering.cpp</tt>.
-Second, if it makes sense to lower the intrinsic to an expanded sequence of C 
-code in all cases, just emit the expansion in <tt>visitCallInst</tt> in
-<tt>Writer.cpp</tt>.  If the intrinsic has some way to express it with GCC 
-(or any other compiler) extensions, it can be conditionally supported based on 
-the compiler compiling the CBE output (see <tt>llvm.prefetch</tt> for an 
-example).  
-Third, if the intrinsic really has no way to be lowered, just have the code 
-generator emit code that prints an error message and calls abort if executed.
-</dd>
-
-<dl>
-<dt>Add support to the SelectionDAG Instruction Selector in 
-<tt>lib/CodeGen/SelectionDAG/</tt></dt>
 
-<dd>Since most targets in LLVM use the SelectionDAG framework for generating
-code, you will likely need to add support for your intrinsic there as well.
-This is usually accomplished by adding a new node, and then teaching the
-SelectionDAG code how to handle that node.  To do this, follow the steps in
-the <a href="#sdnode">Adding a new SelectionDAG node</a> section.</dd>
+<dt>Add support to the .td file for the target(s) of your choice in 
+   <tt>lib/Target/*/*.td</tt>.</dt>
 
-<dl>
-<dt>Once you have added the new node, add code to 
-<tt>SelectionDAG/SelectionDAGISel.cpp</tt> to recognize the intrinsic.  In most
-cases, the intrinsic will just be turned into the node you just added.  For an
-example of this, see how <tt>visitIntrinsicCall</tt> handles 
-<tt>Intrinsic::ctpop_*</tt>.
-</dt>
+<dd>This is usually a matter of adding a pattern to the .td file that matches
+    the intrinsic, though it may obviously require adding the instructions you
+    want to generate as well.  There are lots of examples in the PowerPC and X86
+    backend to follow.</dd>
+</dl>
 
 </div>
 
 <!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
   <a name="sdnode">Adding a new SelectionDAG node</a>
-</div>
+</h2>
 <!-- *********************************************************************** -->
 
-<div class="doc_text">
+<div>
 
 <p>As with intrinsics, adding a new SelectionDAG node to LLVM is much easier
 than adding a new instruction.  New nodes are often added to help represent
@@ -152,7 +134,7 @@ cases, new nodes have been added to allow many targets to perform a common task
 complicated behavior in a single node (rotate).</p>
 
 <ol>
-<li><tt>include/llvm/CodeGen/SelectionDAGNodes.h</tt>:
+<li><tt>include/llvm/CodeGen/ISDOpcodes.h</tt>:
     Add an enum value for the new SelectionDAG node.</li>
 <li><tt>lib/CodeGen/SelectionDAG/SelectionDAG.cpp</tt>:
     Add code to print the node to <tt>getOperationName</tt>.  If your new node
@@ -226,14 +208,14 @@ complicated behavior in a single node (rotate).</p>
 </div>
 
 <!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
   <a name="instruction">Adding a new instruction</a>
-</div>
+</h2>
 <!-- *********************************************************************** -->
 
-<div class="doc_text">
+<div>
 
-<p><span class="doc_warning">WARNING: adding instructions changes the bytecode
+<p><span class="doc_warning">WARNING: adding instructions changes the bitcode
 format, and it will take some effort to maintain compatibility with
 the previous version.</span> Only add an instruction if it is absolutely
 necessary.</p>
@@ -256,8 +238,8 @@ necessary.</p>
     add the grammar on how your instruction can be read and what it will
     construct as a result</li>
 
-<li><tt>llvm/lib/Bytecode/Reader/Reader.cpp</tt>:
-    add a case for your instruction and how it will be parsed from bytecode</li>
+<li><tt>llvm/lib/Bitcode/Reader/Reader.cpp</tt>:
+    add a case for your instruction and how it will be parsed from bitcode</li>
 
 <li><tt>llvm/lib/VMCore/Instruction.cpp</tt>:
     add a case for how your instruction will be printed out to assembly</li>
@@ -283,25 +265,23 @@ to understand this new instruction.</p>
 
 
 <!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
   <a name="type">Adding a new type</a>
-</div>
+</h2>
 <!-- *********************************************************************** -->
 
-<div class="doc_text">
+<div>
 
-<p><span class="doc_warning">WARNING: adding new types changes the bytecode
+<p><span class="doc_warning">WARNING: adding new types changes the bitcode
 format, and will break compatibility with currently-existing LLVM
 installations.</span> Only add new types if it is absolutely necessary.</p>
 
-</div>
-
 <!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
   <a name="fund_type">Adding a fundamental type</a>
-</div>
+</h3>
 
-<div class="doc_text">
+<div>
 
 <ol>
 
@@ -323,11 +303,11 @@ installations.</span> Only add new types if it is absolutely necessary.</p>
 </div>
 
 <!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
   <a name="derived_type">Adding a derived type</a>
-</div>
+</h3>
 
-<div class="doc_text">
+<div>
 
 <ol>
 <li><tt>llvm/include/llvm/Type.h</tt>:
@@ -353,12 +333,12 @@ bool TypesEqual(const Type *Ty, const Type *Ty2,
 <li><tt>llvm/lib/AsmReader/Lexer.l</tt>:
     add ability to parse in the type from text assembly</li>
 
-<li><tt>llvm/lib/ByteCode/Writer/Writer.cpp</tt>:
-    modify <tt>void BytecodeWriter::outputType(const Type *T)</tt> to serialize
+<li><tt>llvm/lib/BitCode/Writer/Writer.cpp</tt>:
+    modify <tt>void BitcodeWriter::outputType(const Type *T)</tt> to serialize
     your type</li>
 
-<li><tt>llvm/lib/ByteCode/Reader/Reader.cpp</tt>:
-    modify <tt>const Type *BytecodeReader::ParseType()</tt> to read your data
+<li><tt>llvm/lib/BitCode/Reader/Reader.cpp</tt>:
+    modify <tt>const Type *BitcodeReader::ParseType()</tt> to read your data
     type</li> 
 
 <li><tt>llvm/lib/VMCore/AsmWriter.cpp</tt>:
@@ -379,16 +359,18 @@ void calcTypeName(const Type *Ty,
 
 </div>
 
+</div>
+
 <!-- *********************************************************************** -->
 
 <hr>
 <address>
   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
-  src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+  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" alt="Valid HTML 4.01!" /></a>
+  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>
+  <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a>
   <br>
   Last modified: $Date$
 </address>