Creation of Instructions is straightforward: simply call the +constructor for the kind of instruction to instantiate and provide the +necessary parameters. For example, an AllocaInst only +requires a (const-ptr-to) Type. Thus: + +
AllocaInst* ai = new AllocaInst(Type::IntTy);+ +will create an AllocaInst instance that represents the +allocation of one integer in the current stack frame, at runtime. +Each Instruction subclass is likely to have varying default +parameters which change the semantics of the instruction, so refer to +the doxygen documentation for +the subclass of Instruction that you're interested in +instantiating. + +
Naming values
+ ++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 Name (default) parameter of the +Instruction 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 +AllocaInst at the first point in the first +BasicBlock of some Function, and I'm intending to +use it within the same Function. I might do: + +
AllocaInst* pa = new AllocaInst(Type::IntTy, 0, "indexLoc");+ +where indexLoc is now the logical name of the instruction's +execution value, which is a pointer to an integer on the runtime +stack. + + +
Inserting instructions
+ ++There are essentially two ways to insert an Instruction into +an existing sequence of instructions that form a BasicBlock: +
Given a BasicBlock* pb, an Instruction* pi within +that BasicBlock, and a newly-created instruction +we wish to insert before *pi, we do the following: + +
+BasicBlock* pb = ...; +Instruction* pi = ...; +Instruction* newInst = new Instruction(...); +pb->getInstList().insert(pi, newInst); // inserts newInst before pi in pb ++ + +
+Instruction instances that are already in +BasicBlocks 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 BasicBlock 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 +Instruction class and Instruction-derived classes +provide constructors which take (as a default parameter) a pointer to +an Instruction which the newly-created Instruction +should precede. That is, Instruction constructors are +capable of inserting the newly-created instance into the +BasicBlock of a provided instruction, immediately before that +instruction. Using an Instruction constructor with a +insertBefore (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 BasicBlocks. + + + + + +
| @@ -1428,6 +1540,6 @@ pointer to the parent Function. Chris Lattner -Last modified: Wed Sep 11 15:48:49 CDT 2002 +Last modified: Wed Sep 11 17:31:03 CDT 2002 |