diff options
author | Joel Stanley <jstanley@cs.uiuc.edu> | 2002-09-11 22:32:24 +0000 |
---|---|---|
committer | Joel Stanley <jstanley@cs.uiuc.edu> | 2002-09-11 22:32:24 +0000 |
commit | 753eb71371c956f75ba9d69b41f0b93f88df4355 (patch) | |
tree | ae53550edde91ad991458eebc28473693725d5b3 /docs | |
parent | 01040b24e0b80e6fa4290887daed6fd796a51740 (diff) | |
download | llvm-753eb71371c956f75ba9d69b41f0b93f88df4355.tar.gz llvm-753eb71371c956f75ba9d69b41f0b93f88df4355.tar.bz2 llvm-753eb71371c956f75ba9d69b41f0b93f88df4355.tar.xz |
- Added content to use-def/def-use section
- Added content to subsection "Creating and inserting new Instructions"
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@3685 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs')
-rw-r--r-- | docs/ProgrammersManual.html | 130 |
1 files changed, 121 insertions, 9 deletions
diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index dbecb58235..3caeaa4f5f 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -34,9 +34,12 @@ </ul> <li><a href="#simplechanges">Making simple changes</a> <ul> - <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> </ul> <!-- <li>Working with the Control Flow Graph @@ -269,7 +272,7 @@ dispatch over the instruction type directly.<p> <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 @@ to combine several null checks into one.<p> <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> </dl> @@ -286,7 +289,7 @@ These five templates can be used with any classes, whether they have a v-table 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 @@ to iterate over all of the values that a particular instruction uses Instruction* pi = ...; for(User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) { - Value* v = i->get(); + Value* v = *i; ... } </pre> @@ -594,6 +597,116 @@ for(User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) { <a name="simplechanges">Making simple changes</a> </b></font></td></tr></table><ul> +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 +instantiating.</p> + +<p><i>Naming values</i></p> + +<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 +stack. +</p> + +<p><i>Inserting instructions</i></p> + +<p> +There are essentially two ways to insert an <tt>Instruction</tt> into +an existing sequence of instructions that form a <tt>BasicBlock</tt>: +<ul> +<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: + +<pre> +BasicBlock* pb = ...; +Instruction* pi = ...; +Instruction* newInst = new Instruction(...); +pb->getInstList().insert(pi, newInst); // inserts newInst before pi in pb +</pre> +</p> + +<li>Insertion into an implicit instruction list +<p> +<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: +<pre> +Instruction* pi = ...; +Instruction* newInst = new Instruction(...); +pi->getParent()->getInstList().insert(pi, newInst); +</pre> +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: +<pre> +Instruction* pi = ...; +Instruction* newInst = new Instruction(..., pi); +</pre> +which is much cleaner, especially if you're creating a lot of +instructions and adding them to <tt>BasicBlock</tt>s. +</p> +</p> + + +<!--_______________________________________________________________________--> +</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 User::replaceUsesOfWith Point out: include/llvm/Transforms/Utils/ @@ -602,7 +715,6 @@ for(User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) { --> - <!-- *********************************************************************** --> </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 @@ pointer to the parent Function. <a href="mailto:sabre@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 --> </font></body></html> |