[llvm-commits] CVS: llvm/www/docs/ProgrammersManual.html

Joel Stanley jstanley at cs.uiuc.edu
Wed Sep 11 17:33:01 PDT 2002

Changes in directory llvm/www/docs:

ProgrammersManual.html updated: 1.20 -> 1.21

Log message:

- Added content to use-def/def-use section
- Added content to subsection "Creating and inserting new Instructions"

Diffs of the changes:

Index: llvm/www/docs/ProgrammersManual.html
diff -u llvm/www/docs/ProgrammersManual.html:1.20 llvm/www/docs/ProgrammersManual.html:1.21
--- llvm/www/docs/ProgrammersManual.html:1.20	Wed Sep 11 15:50:04 2002
+++ llvm/www/docs/ProgrammersManual.html	Wed Sep 11 17:32:24 2002
@@ -34,9 +34,12 @@
     <li><a href="#simplechanges">Making simple changes</a>
-      <li>Creating and inserting new <tt>Instruction</tt>s
-      <li>Deleting <tt>Instruction</tt>s
-      <li>Replacing an <tt>Instruction</tt> with another <tt>Value</tt>
+      <li><a href="#schanges_creating">Creating and inserting new
+		  <tt>Instruction</tt>s</a>
+      <li><a href="#schanges_deleting">Deleting
+		  <tt>Instruction</tt>s</a> 
+      <li><a href="#schanges_replacing">Replacing an
+		  <tt>Instruction</tt> with another <tt>Value</tt></a>
     <li>Working with the Control Flow Graph
@@ -269,7 +272,7 @@
 <dd>The <tt>cast_or_null<></tt> operator works just like the
 <tt>cast<></tt> operator, except that it allows for a null pointer as an
-argument (which it then propogates).  This can sometimes be useful, allowing you
+argument (which it then propagates).  This can sometimes be useful, allowing you
 to combine several null checks into one.<p>
@@ -277,7 +280,7 @@
 <dd>The <tt>dyn_cast_or_null<></tt> operator works just like the
 <tt>dyn_cast<></tt> operator, except that it allows for a null pointer as
-an argument (which it then propogates).  This can sometimes be useful, allowing
+an argument (which it then propagates).  This can sometimes be useful, allowing
 you to combine several null checks into one.<p>
@@ -286,7 +289,7 @@
 or not.  To add support for these templates, you simply need to add
 <tt>classof</tt> static methods to the class you are interested casting to.
 Describing this is currently outside the scope of this document, but there are
-lots of examples in the LLVM sourcebase.<p>
+lots of examples in the LLVM source base.<p>
@@ -576,7 +579,7 @@
 Instruction* pi = ...;
 for(User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {
-    Value* v = i->get();
+    Value* v = *i;
@@ -594,6 +597,116 @@
 <a name="simplechanges">Making simple changes</a>
+There are some primitive transformation operations present in the LLVM
+infrastructure that are worth knowing about.  When performing
+transformations, it's fairly common to manipulate the contents of
+basic blocks.  This section describes some of the common methods for
+doing so and gives example code.
+</ul><h4><a name="schanges_creating"><hr size=0>Creating and inserting
+    new <tt>Instruction</tt>s</h4><ul> 
+<i>Instantiating Instructions</i>
+<p>Creation of <tt>Instruction</tt>s is straightforward: simply call the
+constructor for the kind of instruction to instantiate and provide the
+necessary parameters.  For example, an <tt>AllocaInst</tt> only
+<i>requires</i> a (const-ptr-to) <tt>Type</tt>.  Thus:
+<pre>AllocaInst* ai = new AllocaInst(Type::IntTy);</pre> 
+will create an <tt>AllocaInst</tt> instance that represents the
+allocation of one integer in the current stack frame, at runtime.
+Each <tt>Instruction</tt> subclass is likely to have varying default
+parameters which change the semantics of the instruction, so refer to
+the <a href="/doxygen/classInstruction.h">doxygen documentation for
+the subclass of Instruction</a> that you're interested in
+<p><i>Naming values</i></p>
+It is very useful to name the values of instructions when you're able
+to, as this facilitates the debugging of your transformations.  If you
+end up looking at generated LLVM machine code, you definitely want to
+have logical names associated with the results of instructions!  By
+supplying a value for the <tt>Name</tt> (default) parameter of the
+<tt>Instruction</tt> constructor, you associate a logical name with
+the result of the instruction's execution at runtime.  For example,
+say that I'm writing a transformation that dynamically allocates space
+for an integer on the stack, and that integer is going to be used as
+some kind of index by some other code.  To accomplish this, I place an
+<tt>AllocaInst</tt> at the first point in the first
+<tt>BasicBlock</tt> of some <tt>Function</tt>, and I'm intending to
+use it within the same <tt>Function</tt>.  I might do:
+<pre>AllocaInst* pa = new AllocaInst(Type::IntTy, 0, "indexLoc");</pre>
+where <tt>indexLoc</tt> is now the logical name of the instruction's
+execution value, which is a pointer to an integer on the runtime
+<p><i>Inserting instructions</i></p>
+There are essentially two ways to insert an <tt>Instruction</tt> into
+an existing sequence of instructions that form a <tt>BasicBlock</tt>:
+<li>Insertion into an explicit instruction list
+<p>Given a <tt>BasicBlock* pb</tt>, an <tt>Instruction* pi</tt> within
+that <tt>BasicBlock</tt>, and a newly-created instruction
+we wish to insert before <tt>*pi</tt>, we do the following:
+BasicBlock* pb = ...;
+Instruction* pi = ...;
+Instruction* newInst = new Instruction(...);
+pb->getInstList().insert(pi, newInst); // inserts newInst before pi in pb
+<li>Insertion into an implicit instruction list
+<tt>Instruction</tt> instances that are already in
+<tt>BasicBlock</tt>s are implicitly associated with an existing
+instruction list: the instruction list of the enclosing basic block.
+Thus, we could have accomplished the same thing as the above code
+without being given a <tt>BasicBlock</tt> by doing:
+Instruction* pi = ...;
+Instruction* newInst = new Instruction(...);
+pi->getParent()->getInstList().insert(pi, newInst);
+In fact, this sequence of steps occurs so frequently that the
+<tt>Instruction</tt> class and <tt>Instruction</tt>-derived classes
+provide constructors which take (as a default parameter) a pointer to
+an <tt>Instruction</tt> which the newly-created <tt>Instruction</tt>
+should precede.  That is, <tt>Instruction</tt> constructors are
+capable of inserting the newly-created instance into the
+<tt>BasicBlock</tt> of a provided instruction, immediately before that
+instruction.  Using an <tt>Instruction</tt> constructor with a
+<tt>insertBefore</tt> (default) parameter, the above code becomes:
+Instruction* pi = ...;
+Instruction* newInst = new Instruction(..., pi);
+which is much cleaner, especially if you're creating a lot of
+instructions and adding them to <tt>BasicBlock</tt>s.
+</ul><h4><a name="schanges_deleting"><hr size=0>Deleting
+    <tt>Instruction</tt>s</h4><ul>
+</ul><h4><a name="schanges_replacing"><hr size=0>Replacing an
+    <tt>Instruction</tt> with another <tt>Value</tt></h4><ul>
 <!-- Value::replaceAllUsesWith
   Point out: include/llvm/Transforms/Utils/
@@ -602,7 +715,6 @@
 <!-- *********************************************************************** -->
 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
@@ -1428,6 +1540,6 @@
 <a href="mailto:sabre at nondot.org">Chris Lattner</a></address>
 <!-- Created: Tue Aug  6 15:00:33 CDT 2002 -->
 <!-- hhmts start -->
-Last modified: Wed Sep 11 15:48:49 CDT 2002
+Last modified: Wed Sep 11 17:31:03 CDT 2002
 <!-- hhmts end -->

More information about the llvm-commits mailing list