LLVM Programmer's Manual

You may have noticed that the previous example was a bit +

+
Treating calls and invokes the +same way

You may have noticed that the previous example was a bit oversimplified in that it did not deal with call sites generated by 'invoke' instructions. In this, and in other situations, you may find -that you want to treat CallInsts and InvokeInsts the -same way, even though their most-specific common base class is -Instruction, which includes lots of less closely-related -things. For these cases, LLVM provides a handy wrapper class called CallSite -. It is essentially a wrapper around an Instruction -pointer, with some methods that provide functionality common to -CallInsts and InvokeInsts.

This class is supposed to have "value semantics". So it should be +that you want to treat CallInsts and InvokeInsts +the same way, even though their most-specific common base class is Instruction, +which includes lots of less closely-related things. For these cases, +LLVM provides a handy wrapper class called CallSite . +It is essentially a wrapper around an Instruction pointer, +with some methods that provide functionality common to CallInsts +and InvokeInsts.

This class is supposed to have "value semantics". So it should be passed by value, not by reference; it should not be dynamically allocated or deallocated using operator new or operator delete. It is efficiently copyable, assignable and constructable, with costs equivalents to that of a bare pointer. (You will notice, if you look at its definition, that it has only a single data member.)

Iterating over def-use & -use-def chains

- +

+
Iterating over def-use & +use-def chains

- -Instantiating Instructions - -

User

Value

User

Value

def-use

Function*

F

foo

use

foo

def-use

F

-Function* F = ...;
-
-for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i) {
-    if (Instruction *Inst = dyn_cast<Instruction>(*i)) {
-        cerr << "F is used in instruction:\n";
-        cerr << *Inst << "\n";
-    }
-}
-

User

Value

def-use

Function*

F

foo

use

foo

def-use

F

Function* F = ...;

for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i) {
    if (Instruction *Inst = dyn_cast<Instruction>(*i)) {
        cerr << "F is used in instruction:\n";
        cerr << *Inst << "\n";
    }
}

User Class

Value

User

use-def

Instruction

User

Instruction

-Instruction* pi = ...;
-
-for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {
-    Value* v = *i;
-    ...
-}
-

Value

User

use-def

Instruction

User

Instruction

Instruction* pi = ...;

for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {
    Value* v = *i;
    ...
}

- -Making simple changes -

- +--> +

Making simple +changes

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. - - -

Creating and inserting - new `Instruction`s

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);

- +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. +

+
Creating and inserting new `Instruction`s

Instantiating Instructions

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);

AllocaInst

Instruction

doxygen documentation for -the subclass of Instruction

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");

Instruction

doxygen documentation for the +subclass of Instruction

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");

indexLoc

Inserting instructions

-There are essentially two ways to insert an Instruction into -an existing sequence of instructions that form a BasicBlock: -

Insertion into an explicit instruction list - -
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
-
```
-
- -
Insertion into an implicit instruction list -
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);
-
```
+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:
+
- Insertion into an explicit instruction list +
  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
```
  +
- Insertion into an implicit instruction list +
  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. -
  -
  -
- - -

Deleting -`Instruction`s

- -Deleting an instruction from an existing sequence of instructions that form a

BasicBlock

- -For example:

- -

-  Instruction *I = .. ;
-  BasicBlock *BB = I->getParent();
-  BB->getInstList().erase(I);
-

- +instructions and adding them to BasicBlocks. +

Replacing an - `Instruction` with another `Value`

Replacing individual instructions

-Including "llvm/Transforms/Utils/BasicBlockUtils.h" permits use of two very useful replace functions: -ReplaceInstWithValue and ReplaceInstWithInst. - +

+
Deleting `Instruction`s

ReplaceInstWithValue - -
This function replaces all uses (within a basic block) of a given -instruction with a value, and then removes the original instruction. -The following example illustrates the replacement of the result of a -particular AllocaInst that allocates memory for a single -integer with an null pointer to an integer.
- -
```
-AllocaInst* instToReplace = ...;
-BasicBlock::iterator ii(instToReplace);
-ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii,
-                     Constant::getNullValue(PointerType::get(Type::IntTy)));
-
```
- -
ReplaceInstWithInst - -
This function replaces a particular instruction with another -instruction. The following example illustrates the replacement of one -AllocaInst with another.
- -
```
-AllocaInst* instToReplace = ...;
-BasicBlock::iterator ii(instToReplace);
-ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii,
-                    new AllocaInst(Type::IntTy, 0, "ptrToReplacedInt"));
-
```
- +Deleting an instruction from an existing sequence of instructions that +form a BasicBlock is very +straightforward. First, you must have a pointer to the instruction that +you wish to delete. Second, you need to obtain the pointer to that +instruction's basic block. You use the pointer to the basic block to +get its list of instructions and then use the erase function to remove +your instruction. +
For example:
+

+
```
  Instruction *I = .. ;
  BasicBlock *BB = I->getParent();
  BB->getInstList().erase(I);
```
+

Replacing multiple uses of Users and - Values

Value::replaceAllUsesWith

User::replaceUsesOfWith

User Class

-The Core LLVM Class Hierarchy Reference -

+--> + + + + + + + +

The Core LLVM Class +Hierarchy Reference

include/llvm/

lib/VMCore

- - - -

- -The Value class -

#include "llvm/Value.h"

- - -The Value class is the most important class in LLVM Source base. It -represents a typed value that may be used (among other things) as an operand to -an instruction. There are many different types of Values, such as Constants, Arguments, and even Instructions and Functions are Values.

- -A particular Value may be used many times in the LLVM representation -for a program. For example, an incoming argument to a function (represented -with an instance of the Argument class) is "used" by -every instruction in the function that references the argument. To keep track -of this relationship, the Value class keeps a list of all of the Users that is using it (the User class is a base class for all nodes in the LLVM -graph that can refer to Values). This use list is how LLVM represents -def-use information in the program, and is accessible through the use_* -methods, shown below.

- -Because LLVM is a typed representation, every LLVM Value is typed, and -this Type is available through the getType() -method. In addition, all LLVM values can be named. The -"name" of the Value is symbolic string printed in the LLVM code:

- -The name of this instruction is "foo". NOTE that the name of any value -may be missing (an empty string), so names should ONLY be used for -debugging (making the source code easier to read, debugging printouts), they -should not be used to keep track of values or map between them. For this -purpose, use a std::map of pointers to the Value itself -instead.

-   %foo = add int 1, 2
-

- -One important aspect of LLVM is that there is no distinction between an SSA -variable and the operation that produces it. Because of this, any reference to -the value produced by an instruction (or the value available as an incoming -argument, for example) is represented as a direct pointer to the class that -represents this value. Although this may take some getting used to, it -simplifies the representation and makes it easier to manipulate.

- - - -

Important Public Members of -the `Value` class

Value::use_iterator - Typedef for iterator over the use-list
- Value::use_const_iterator - - Typedef for const_iterator over the use-list
- unsigned use_size() - Returns the number of users of the value.
+The Core LLVM classes are the primary means of representing the program +being inspected or transformed. The core LLVM classes are defined in +header files in the include/llvm/ directory, and implemented in +the lib/VMCore directory. +

+ + + + + + + +

The Value class

+ #include "

llvm/Value.h"

The name of this instruction is "foo". NOTE +that the name of any value may be missing (an empty string), so names +should ONLY be used for debugging (making the source code easier +to read, debugging printouts), they should not be used to keep track of +values or map between them. For this purpose, use a std::map +of pointers to the Value itself instead.

The Value class is the most important class in the LLVM +Source base. It represents a typed value that may be used (among other +things) as an operand to an instruction. There are many different types +of Values, such as Constants,Arguments. Even Instructions +and Functions are Values.

A particular Value may be used many times in the LLVM +representation for a program. For example, an incoming argument to a +function (represented with an instance of the Argument +class) is "used" by every instruction in the function that references +the argument. To keep track of this relationship, the Value +class keeps a list of all of the Users +that is using it (the User class is a base +class for all nodes in the LLVM graph that can refer to Values). +This use list is how LLVM represents def-use information in the +program, and is accessible through the use_* methods, shown +below.

Because LLVM is a typed representation, every LLVM Value +is typed, and this Type is available through the getType() +method. In addition, all LLVM values can be named. The "name" of the Value +is a symbolic string printed in the LLVM code:

   %foo = add int 1, 2

One important aspect of LLVM is that there is no distinction +between an SSA variable and the operation that produces it. Because of +this, any reference to the value produced by an instruction (or the +value available as an incoming argument, for example) is represented as +a direct pointer to the class that represents this value. Although +this may take some getting used to, it simplifies the representation +and makes it easier to manipulate.

+
Important Public Members of the `Value` +class

Value::use_iterator - Typedef for iterator over the +use-list
+ Value::use_const_iterator - Typedef for const_iterator over +the use-list
+ unsigned use_size() - Returns the number of users of the +value.
bool use_empty() - Returns true if there are no users.
- use_iterator use_begin() - - Get an iterator to the start of the use-list.
- use_iterator use_end() - - Get an iterator to the end of the use-list.
- User *use_back() - - Returns the last element in the list.
- -These methods are the interface to access the def-use information in LLVM. As with all other iterators in LLVM, the naming conventions follow the conventions defined by the STL.
- -
Type *getType() const
-This method returns the Type of the Value. - -
bool hasName() const
+ use_iterator use_begin() - Get an iterator to the start of +the use-list.
+ use_iterator use_end() - Get an iterator to the end of the +use-list.
+ User *use_back() - Returns the last +element in the list. +
These methods are the interface to access the def-use +information in LLVM. As with all other iterators in LLVM, the naming +conventions follow the conventions defined by the STL.
+

+
Type *getType() const +
This method returns the Type of the Value.
+
bool hasName() const
std::string getName() const
- void setName(const std::string &Name)
- -This family of methods is used to access and assign a name to a Value, -be aware of the precaution above.
- - -
void replaceAllUsesWith(Value *V)
- -This method traverses the use list of a Value changing all Users of the current value to refer to "V" -instead. For example, if you detect that an instruction always produces a -constant value (for example through constant folding), you can replace all uses -of the instruction with the constant like this:
- -
```
-  Inst->replaceAllUsesWith(ConstVal);
-
```
- - - - -

- -The User class -

#include "llvm/User.h"

void setName(const std::string &Name)

This family of methods is used to access and assign a name to a Value, +be aware of the precaution above.

void replaceAllUsesWith(Value *V) +
This method traverses the use list of a Value changing +all Users of the current value to refer to "V" +instead. For example, if you detect that an instruction always +produces a constant value (for example through constant folding), you +can replace all uses of the instruction with the constant like this:
+

+
```
  Inst->replaceAllUsesWith(ConstVal);
```
+

+

+ + + + + + + +

The User class

#include "llvm/User.h"

User Class

- -The User class exposes the operand list in two ways: through an index -access interface and through an iterator based interface.

- - -The User class is the common base class of all LLVM nodes that may -refer to Values. It exposes a list of "Operands" -that are all of the Values that the User is -referring to. The User class itself is a subclass of -Value.

- -The operands of a User point directly to the LLVM Value that it refers to. Because LLVM uses Static -Single Assignment (SSA) form, there can only be one definition referred to, -allowing this direct connection. This connection provides the use-def -information in LLVM.

- - -

Important Public Members of -the `User` class

- -

Value *getOperand(unsigned i)
- unsigned getNumOperands()

- -These two methods expose the operands of the User in a convenient form -for direct access.

- -

User::op_iterator - Typedef for iterator over the operand list
- User::op_const_iterator - use_iterator op_begin() - - Get an iterator to the start of the operand list.
- use_iterator op_end() - - Get an iterator to the end of the operand list.

- -Together, these methods make up the iterator based interface to the operands of -a User.

- - - - -

- -The Instruction class -

- -#include "

llvm/Instruction.h"

Instruction Class

User

- -The Instruction class is the common base class for all LLVM -instructions. It provides only a few methods, but is a very commonly used -class. The primary data tracked by the Instruction class itself is the -opcode (instruction type) and the parent BasicBlock the Instruction is embedded -into. To represent a specific type of instruction, one of many subclasses of -Instruction are used.

- -Because the Instruction class subclasses the User class, its operands can be accessed in the same -way as for other Users (with the -getOperand()/getNumOperands() and -op_begin()/op_end() methods).

- -An important file for the Instruction class is the -llvm/Instruction.def file. This file contains some meta-data about the -various different types of instructions in LLVM. It describes the enum values -that are used as opcodes (for example Instruction::Add and -Instruction::SetLE), as well as the concrete sub-classes of -Instruction that implement the instruction (for example BinaryOperator and SetCondInst). Unfortunately, the use of macros in -this file confused doxygen, so these enum values don't show up correctly in the -doxygen output.

- - - -

Important Public Members of -the `Instruction` class

BasicBlock *getParent()
- -Returns the BasicBlock that this -Instruction is embedded into.
- -
bool mayWriteToMemory()
- -Returns true if the instruction writes to memory, i.e. it is a call, -free, invoke, or store.
- -
unsigned getOpcode()
- -Returns the opcode for the Instruction.
- -
Instruction *clone() const
- -Returns another instance of the specified instruction, identical in all ways to -the original except that the instruction has no parent (ie it's not embedded -into a BasicBlock), and it has no name.
- - - - - - - -

- -The BasicBlock class -

#include "llvm/BasicBlock.h"

The User class is the common base class of all LLVM nodes +that may refer to Values. It exposes a +list of "Operands" that are all of the Values +that the User is referring to. The User class itself is a +subclass of Value.

The operands of a User point directly to the LLVM Value that it refers to. Because LLVM uses +Static Single Assignment (SSA) form, there can only be one definition +referred to, allowing this direct connection. This connection provides +the use-def information in LLVM.

+
Important Public Members of the `User` +class

User

Value *getOperand(unsigned i)
+ unsigned getNumOperands() +
These two methods expose the operands of the User in a +convenient form for direct access.
+

+
User::op_iterator - Typedef for iterator over the operand +list
+ User::op_const_iterator use_iterator op_begin() - +Get an iterator to the start of the operand list.
+ use_iterator op_end() - Get an iterator to the end of the +operand list. +
Together, these methods make up the iterator based interface to +the operands of a User.
+

+

+ + + + + + + +

The Instruction +class

#include "

llvm/Instruction.h"

Instruction +Class

User

The Instruction class is the common base class for all +LLVM instructions. It provides only a few methods, but is a very +commonly used class. The primary data tracked by the Instruction +class itself is the opcode (instruction type) and the parent BasicBlock the Instruction is +embedded into. To represent a specific type of instruction, one of many +subclasses of Instruction are used.

Because the Instruction class subclasses the User class, its operands can be accessed in +the same way as for other Users (with the getOperand()/getNumOperands() +and op_begin()/op_end() methods).

An important file for the Instruction class is the llvm/Instruction.def +file. This file contains some meta-data about the various different +types of instructions in LLVM. It describes the enum values that are +used as opcodes (for example Instruction::Add and Instruction::SetLE), +as well as the concrete sub-classes of Instruction that +implement the instruction (for example BinaryOperator +and SetCondInst). Unfortunately, +the use of macros in this file confuses doxygen, so these enum values +don't show up correctly in the doxygen +output.

+
Important Public Members of the `Instruction` +class

BasicBlock *getParent() +
Returns the BasicBlock that +this Instruction is embedded into.
+

+
bool mayWriteToMemory() +
Returns true if the instruction writes to memory, i.e. it is a call,free,invoke, +or store.
+

+
unsigned getOpcode() +
Returns the opcode for the Instruction.
+

+
Instruction *clone() const +
Returns another instance of the specified instruction, identical +in all ways to the original except that the instruction has no parent +(ie it's not embedded into a BasicBlock), +and it has no name
+

+ + + + + + + +

The BasicBlock +class

#include "llvm/BasicBlock.h"

BasicBlock Class

- - -This class represents a single entry multiple exit section of the code, commonly -known as a basic block by the compiler community. The BasicBlock class -maintains a list of Instructions, which form -the body of the block. Matching the language definition, the last element of -this list of instructions is always a terminator instruction (a subclass of the -TerminatorInst class).

- -In addition to tracking the list of instructions that make up the block, the -BasicBlock class also keeps track of the Function that it is embedded into.

- -Note that BasicBlocks themselves are Values, because they are referenced by instructions -like branches and can go in the switch tables. BasicBlocks have type -label.

- - - -

Important Public Members of -the `BasicBlock` class

BasicBlock(const std::string &Name = "", Function *Parent = 0)
- -The BasicBlock constructor is used to create new basic blocks for -insertion into a function. The constructor simply takes a name for the new -block, and optionally a Function to insert it -into. If the Parent parameter is specified, the new -BasicBlock is automatically inserted at the end of the specified Function, if not specified, the BasicBlock must be -manually inserted into the Function.
- -
BasicBlock::iterator - Typedef for instruction list iterator
+Superclass: Value +
This class represents a single entry multiple exit section of the +code, commonly known as a basic block by the compiler community. The BasicBlock +class maintains a list of Instructions, +which form the body of the block. Matching the language definition, +the last element of this list of instructions is always a terminator +instruction (a subclass of the TerminatorInst +class).
+
In addition to tracking the list of instructions that make up the +block, the BasicBlock class also keeps track of the Function that it is embedded into.
+
Note that BasicBlocks themselves are Values, +because they are referenced by instructions like branches and can go in +the switch tables. BasicBlocks have type label.
+

+

+
Important Public Members of the `BasicBlock` +class

BasicBlock(const std::string &Name = "", Function *Parent = 0) +
The BasicBlock constructor is used to create new basic +blocks for insertion into a function. The constructor optionally takes +a name for the new block, and a Function +to insert it into. If the Parent parameter is specified, the +new BasicBlock is automatically inserted at the end of the +specified Function, if not specified, +the BasicBlock must be manually inserted into the Function.
+

+
BasicBlock::iterator - Typedef for instruction list +iterator
BasicBlock::const_iterator - Typedef for const_iterator.
- begin(), end(), front(), back(), - size(), empty(), rbegin(), rend()
- -These methods and typedefs are forwarding functions that have the same semantics -as the standard library methods of the same names. These methods expose the -underlying instruction list of a basic block in a way that is easy to -manipulate. To get the full complement of container operations (including -operations to update the list), you must use the getInstList() -method.
- -
BasicBlock::InstListType &getInstList()
- -This method is used to get access to the underlying container that actually -holds the Instructions. This method must be used when there isn't a forwarding -function in the BasicBlock class for the operation that you would like -to perform. Because there are no forwarding functions for "updating" -operations, you need to use this if you want to update the contents of a -BasicBlock.
- -
Function *getParent()
- -Returns a pointer to Function the block is -embedded into, or a null pointer if it is homeless.
- -
TerminatorInst *getTerminator()
- -Returns a pointer to the terminator instruction that appears at the end of the -BasicBlock. If there is no terminator instruction, or if the last -instruction in the block is not a terminator, then a null pointer is -returned.
- - - -

- -The GlobalValue class -

#include "llvm/GlobalValue.h"

GlobalValue Class

User

- -Global values (GlobalVariables or Functions) are the only LLVM values that are -visible in the bodies of all Functions. -Because they are visible at global scope, they are also subject to linking with -other globals defined in different translation units. To control the linking -process, GlobalValues know their linkage rules. Specifically, -GlobalValues know whether they have internal or external linkage.

- -If a GlobalValue has internal linkage (equivalent to being -static in C), it is not visible to code outside the current translation -unit, and does not participate in linking. If it has external linkage, it is -visible to external code, and does participate in linking. In addition to -linkage information, GlobalValues keep track of which Module they are currently part of.

- -Because GlobalValues are memory objects, they are always referred to by -their address. As such, the Type of a global is -always a pointer to its contents. This is explained in the LLVM Language -Reference Manual.

- - - -

Important Public Members of -the `GlobalValue` class

bool hasInternalLinkage() const
+ begin(), end(), front(), back(),size(),empty(),rbegin(),rend() +-STL style functions for accessing the instruction list. +

These methods and typedefs are forwarding functions that have +the same semantics as the standard library methods of the same names. +These methods expose the underlying instruction list of a basic block in +a way that is easy to manipulate. To get the full complement of +container operations (including operations to update the list), you must +use the getInstList() method.

BasicBlock::InstListType &getInstList() +

This method is used to get access to the underlying container +that actually holds the Instructions. This method must be used when +there isn't a forwarding function in the BasicBlock class for +the operation that you would like to perform. Because there are no +forwarding functions for "updating" operations, you need to use this if +you want to update the contents of a BasicBlock.

Function *getParent() +
Returns a pointer to Function +the block is embedded into, or a null pointer if it is homeless.
+

+
TerminatorInst *getTerminator() +
Returns a pointer to the terminator instruction that appears at +the end of the BasicBlock. If there is no terminator +instruction, or if the last instruction in the block is not a +terminator, then a null pointer is returned.
+

+

+ + + + + + + +

The GlobalValue +class

#include "llvm/GlobalValue.h"

GlobalValue +Class

User

Global values (GlobalVariables +or Functions) are the only LLVM +values that are visible in the bodies of all Functions. +Because they are visible at global scope, they are also subject to +linking with other globals defined in different translation units. To +control the linking process, GlobalValues know their linkage +rules. Specifically, GlobalValues know whether they have +internal or external linkage, as defined by the LinkageTypes enumerator.

If a GlobalValue has internal linkage (equivalent to +being static in C), it is not visible to code outside the +current translation unit, and does not participate in linking. If it +has external linkage, it is visible to external code, and does +participate in linking. In addition to linkage information, GlobalValues +keep track of which Module they are +currently part of.

Because GlobalValues are memory objects, they are always +referred to by their address. As such, the Type +of a global is always a pointer to its contents. It is important to +remember this when using the GetElementPtrInst +instruction because this pointer must be dereferenced first. For +example, if you have a GlobalVariable +(a subclass of GlobalValue) +that is an array of 24 ints, type [24 +x int], then the GlobalVariable +is a pointer to that array. Although the address of the first element of +this array and the value of the GlobalVariable +are the same, they have different types. The GlobalVariable's type is [24 x int]. The first element's +type is int. Because of +this, accessing a global value requires you to dereference the pointer +with GetElementPtrInst +first, then its elements can be accessed. This is explained in +the LLVM Language Reference Manual.

+
Important Public Members of the `GlobalValue` +class

bool hasInternalLinkage() const
bool hasExternalLinkage() const
- void setInternalLinkage(bool HasInternalLinkage)
- -These methods manipulate the linkage characteristics of the -GlobalValue.
- -
Module *getParent()
- -This returns the Module that the GlobalValue is -currently embedded into.
- - - - -

- -The Function class -

#include "llvm/Function.h"

void setInternalLinkage(bool HasInternalLinkage)

These methods manipulate the linkage characteristics of the GlobalValue.

Module *getParent() +
This returns the Module that the +GlobalValue is currently embedded into.
+

+

+ + + + + + + +

The Function +class

#include "llvm/Function.h"

Function Class

GlobalValue

User

- -The Function class represents a single procedure in LLVM. It is -actually one of the more complex classes in the LLVM heirarchy because it must -keep track of a large amount of data. The Function class keeps track -of a list of BasicBlocks, a list of formal Arguments, and a SymbolTable.

- -The list of BasicBlocks is the most commonly -used part of Function objects. The list imposes an implicit ordering -of the blocks in the function, which indicate how the code will be layed out by -the backend. Additionally, the first BasicBlock is the implicit entry node for the -Function. It is not legal in LLVM explicitly branch to this initial -block. There are no implicit exit nodes, and in fact there may be multiple exit -nodes from a single Function. If the BasicBlock list is empty, this indicates that -the Function is actually a function declaration: the actual body of the -function hasn't been linked in yet.

- -In addition to a list of BasicBlocks, the -Function class also keeps track of the list of formal Arguments that the function receives. This -container manages the lifetime of the Argument -nodes, just like the BasicBlock list does for -the BasicBlocks.

- -The SymbolTable is a very rarely used LLVM -feature that is only used when you have to look up a value by name. Aside from -that, the SymbolTable is used internally to -make sure that there are not conflicts between the names of Instructions, BasicBlocks, or Arguments in the function body.

- - - -

Important Public Members of -the `Function` class

Function(const FunctionType *Ty, bool isInternal, const std::string &N = "")
- -Constructor used when you need to create new Functions to add the the -program. The constructor must specify the type of the function to create and -whether or not it should start out with internal or external linkage.
- -
bool isExternal()
- -Return whether or not the Function has a body defined. If the function -is "external", it does not have a body, and thus must be resolved by linking -with a function defined in a different translation unit.
- - -
Function::iterator - Typedef for basic block list iterator
+ href="#User">User, Value +
The Function class represents a single procedure in LLVM. +It is actually one of the more complex classes in the LLVM heirarchy +because it must keep track of a large amount of data. The Function +class keeps track of a list of BasicBlocks, +a list of formal Arguments, and a SymbolTable.
+
The list of BasicBlocks is the +most commonly used part of Function objects. The list imposes +an implicit ordering of the blocks in the function, which indicate how +the code will be layed out by the backend. Additionally, the first BasicBlock is the implicit entry node +for the Function. It is not legal in LLVM to explicitly +branch to this initial block. There are no implicit exit nodes, and in +fact there may be multiple exit nodes from a single Function. +If the BasicBlock list is empty, +this indicates that the Function is actually a function +declaration: the actual body of the function hasn't been linked in yet.
+
In addition to a list of BasicBlocks, +the Function class also keeps track of the list of formal Arguments that the function receives. +This container manages the lifetime of the Argument +nodes, just like the BasicBlock list +does for the BasicBlocks.
+
The SymbolTable is a very +rarely used LLVM feature that is only used when you have to look up a +value by name. Aside from that, the SymbolTable +is used internally to make sure that there are not conflicts between the +names of Instructions, BasicBlocks, or Arguments +in the function body.
+

+

+
Important Public Members of the `Function` +class

Function(const FunctionType +*Ty, bool isInternal, const std::string &N = "", Module* Parent = 0) +
Constructor used when you need to create new Functions +to add the the program. The constructor must specify the type of the +function to create and whether or not it should start out with internal +or external linkage. The FunctionType argument specifies the +formal arguments and return value for the function. The same FunctionType +value can be used to create multiple functions. The Parent argument specifies the +Module in which the function is defined. If this argument is provided, +the function will automatically be inserted into that module's list of +functions.
+

+
bool isExternal() +
Return whether or not the Function has a body defined. +If the function is "external", it does not have a body, and thus must be +resolved by linking with a function defined in a different translation +unit.
+

+
Function::iterator - Typedef for basic block list iterator
Function::const_iterator - Typedef for const_iterator.
- begin(), end(), front(), back(), - size(), empty(), rbegin(), rend()
- -These are forwarding methods that make it easy to access the contents of a -Function object's BasicBlock -list.
- -
Function::BasicBlockListType &getBasicBlockList()
- -Returns the list of BasicBlocks. This is -necessary to use when you need to update the list or perform a complex action -that doesn't have a forwarding method.
- - -
Function::aiterator - Typedef for the argument list iterator
+ begin(), end(), front(), back(),size(),empty(),rbegin(),rend() +
These are forwarding methods that make it easy to access the +contents of a Function object's BasicBlock +list.
+

+
Function::BasicBlockListType &getBasicBlockList() +
Returns the list of BasicBlocks. +This is necessary to use when you need to update the list or perform a +complex action that doesn't have a forwarding method.
+

+
Function::aiterator - Typedef for the argument list +iterator
Function::const_aiterator - Typedef for const_iterator.
- abegin(), aend(), afront(), aback(), - asize(), aempty(), arbegin(), arend()
- -These are forwarding methods that make it easy to access the contents of a -Function object's Argument list.
- -
Function::ArgumentListType &getArgumentList()
- -Returns the list of Arguments. This is -necessary to use when you need to update the list or perform a complex action -that doesn't have a forwarding method.
- - - -
BasicBlock &getEntryBlock()
- -Returns the entry BasicBlock for the -function. Because the entry block for the function is always the first block, -this returns the first block of the Function.
- -
Type *getReturnType()
- FunctionType *getFunctionType()
- -This traverses the Type of the Function + abegin(), aend(), afront(), aback(),asize(),aempty(),arbegin(),arend() +
These are forwarding methods that make it easy to access the +contents of a Function object's Argument +list.
+

+
Function::ArgumentListType &getArgumentList() +
Returns the list of Arguments. +This is necessary to use when you need to update the list or perform a +complex action that doesn't have a forwarding method.
+

+
BasicBlock &getEntryBlock() +
Returns the entry BasicBlock +for the function. Because the entry block for the function is always +the first block, this returns the first block of the Function.
+

+
Type *getReturnType()
+ FunctionType *getFunctionType() +
This traverses the Type of the Function and returns the return type of the function, or the FunctionType of the actual function.
- -
SymbolTable *getSymbolTable()
- -Return a pointer to the SymbolTable for this -Function.
- - - - -

- -The GlobalVariable class -

#include "llvm/GlobalVariable.h"

GlobalVariable Class

GlobalValue

User

- -Global variables are represented with the (suprise suprise) -GlobalVariable class. Like functions, GlobalVariables are -also subclasses of GlobalValue, and as such -are always referenced by their address (global values must live in memory, so -their "name" refers to their address). Global variables may have an initial -value (which must be a Constant), and if they -have an initializer, they may be marked as "constant" themselves (indicating -that their contents never change at runtime).

- - - -

Important Public Members of the -`GlobalVariable` class

GlobalVariable(const Type *Ty, bool isConstant, bool -isInternal, Constant *Initializer = 0, const std::string -&Name = "")
- -Create a new global variable of the specified type. If isConstant is -true then the global variable will be marked as unchanging for the program, and -if isInternal is true the resultant global variable will have internal -linkage. Optionally an initializer and name may be specified for the global variable as well.
- - -
bool isConstant() const
- -Returns true if this is a global variable is known not to be modified at -runtime.
- - -
bool hasInitializer()
- -Returns true if this GlobalVariable has an intializer.
- - -
Constant *getInitializer()
- -Returns the intial value for a GlobalVariable. It is not legal to call -this method if there is no initializer.
- - - -

- -The Module class -

#include "llvm/Module.h"

Module Class

- -The Module class represents the top level structure present in LLVM -programs. An LLVM module is effectively either a translation unit of the -original program or a combination of several translation units merged by the -linker. The Module class keeps track of a list of Functions, a list of GlobalVariables, and a SymbolTable. Additionally, it contains a few -helpful member functions that try to make common operations easy.

- - - -

Important Public Members of the -`Module` class

Module::iterator - Typedef for function list iterator
- Module::const_iterator - Typedef for const_iterator.
- begin(), end(), front(), back(), - size(), empty(), rbegin(), rend()
- -These are forwarding methods that make it easy to access the contents of a -Module object's Function -list.
- -
Module::FunctionListType &getFunctionList()
- -Returns the list of Functions. This is -necessary to use when you need to update the list or perform a complex action -that doesn't have a forwarding method.
- - -
- -
Module::giterator - Typedef for global variable list iterator
- Module::const_giterator - Typedef for const_iterator.
- gbegin(), gend(), gfront(), gback(), - gsize(), gempty(), grbegin(), grend()
- -These are forwarding methods that make it easy to access the contents of a -Module object's GlobalVariable -list.
- -
Module::GlobalListType &getGlobalList()
- -Returns the list of GlobalVariables. -This is necessary to use when you need to update the list or perform a complex -action that doesn't have a forwarding method.
- - - -
- -
SymbolTable *getSymbolTable()
- -Return a reference to the SymbolTable for -this Module.
- - - -
- -
Function *getFunction(const std::string &Name, const FunctionType *Ty)
- -Look up the specified function in the Module SymbolTable. If it does not exist, return -null.
- - -
Function *getOrInsertFunction(const std::string - &Name, const FunctionType *T)
- -Look up the specified function in the Module SymbolTable. If it does not exist, add an -external declaration for the function and return it.
- - -
std::string getTypeName(const Type *Ty)
- -If there is at least one entry in the SymbolTable for the specified Type, return it. Otherwise return the empty -string.
- - -
bool addTypeName(const std::string &Name, const Type -*Ty)
- -Insert an entry in the SymbolTable mapping -Name to Ty. If there is already an entry for this name, true -is returned and the SymbolTable is not -modified.
- - - -

- -The Constant class and subclasses -

- - - -

Important Public Methods

bool isConstantExpr(): Returns true if it is a ConstantExpr - - -
-Important Subclasses of Constant
- -
-
ConstantSInt : This subclass of Constant represents a signed integer constant. -
-
int64_t getValue() const: Returns the underlying value of this constant. + href="#FunctionType">FunctionType of the actual function.
+

+
+
SymbolTable *getSymbolTable() +
Return a pointer to the SymbolTable +for this Function.
+

+

-
ConstantUInt : This class represents an unsigned integer. + + + + + + + +
The GlobalVariable +class

-
uint64_t getValue() const: Returns the underlying value of this constant. + #include "llvm/GlobalVariable.h"
+doxygen info: GlobalVariable +Class
+Superclasses: GlobalValue, User, Value +
Global variables are represented with the (suprise suprise) GlobalVariable +class. Like functions, GlobalVariables are also subclasses of GlobalValue, and as such are always +referenced by their address (global values must live in memory, so their +"name" refers to their address). See GlobalValue for more on +this. Global variables may have an initial value (which must be a Constant), and if they have an +initializer, they may be marked as "constant" themselves (indicating +that their contents never change at runtime).
+

-
ConstantFP : This class represents a floating point constant. +
+
Important Public Members of the GlobalVariable +class

-
double getValue() const: Returns the underlying value of this constant. +
GlobalVariable(const Type *Ty, +bool isConstant, LinkageTypes& Linkage, Constant +*Initializer = 0, const std::string &Name = "", Module* Parent = 0) +
Create a new global variable of the specified type. If isConstant +is true then the global variable will be marked as unchanging for the +program. The Linkage parameter specifies the type of linkage (internal, +external, weak, linkonce, appending) for the variable. If the linkage +is InternalLinkage, WeakLinkage, or LinkOnceLinkage, then the +resultant global variable will have internal linkage. AppendingLinkage +concatenates together all instances (in different translation units) of +the variable into a single variable but is only applicable to arrays. + See the LLVM Language +Reference for further details on linkage types. Optionally an +initializer, a name, and the module to put the variable into may be +specified for the global variable as well.
+

+
+
bool isConstant() const +
Returns true if this is a global variable that is known not to +be modified at runtime.
+

+
+
bool hasInitializer() +
Returns true if this GlobalVariable has an intializer.
+

+
+
Constant *getInitializer() +
Returns the intial value for a GlobalVariable. It is +not legal to call this method if there is no initializer.
+

+

-
ConstantBool : This represents a boolean constant. + + + + + + + +
The Module class

-
bool getValue() const: Returns the underlying value of this constant. + #include "llvm/Module.h"
+doxygen info: Module Class +
The Module class represents the top level structure +present in LLVM programs. An LLVM module is effectively either a +translation unit of the original program or a combination of several +translation units merged by the linker. The Module class keeps +track of a list of Functions, a list +of GlobalVariables, and a SymbolTable. Additionally, it +contains a few helpful member functions that try to make common +operations easy.
+

-
ConstantArray : This represents a constant array. +
+
Important Public Members of the Module +class

-
const std::vector<Use> &getValues() const: Returns a Vecotr of component constants that makeup this array. +
Module::Module( std::string +name = "" )

-
ConstantStruct : This represents a constant struct. +
Constructing a Module +is easy. You can optionally provide a name for it (probably based on the +name of the translation unit).

-
const std::vector<Use> &getValues() const: Returns a Vecotr of component constants that makeup this array. +
Module::iterator - Typedef for function list iterator
+ Module::const_iterator - Typedef for const_iterator.
+ begin(), end(), front(), back(),size(),empty(),rbegin(),rend() +
These are forwarding methods that make it easy to access the +contents of a Module object's Function +list.
+

+
+
Module::FunctionListType &getFunctionList() +
Returns the list of Functions. +This is necessary to use when you need to update the list or perform a +complex action that doesn't have a forwarding method.
+

+

+
Module::giterator - Typedef for global variable list +iterator
+ Module::const_giterator - Typedef for const_iterator.
+ gbegin(), gend(), gfront(), gback(),gsize(),gempty(),grbegin(),grend() +
These are forwarding methods that make it easy to access the +contents of a Module object's GlobalVariable +list.
+

+
+
Module::GlobalListType &getGlobalList() +
Returns the list of GlobalVariables. +This is necessary to use when you need to update the list or perform a +complex action that doesn't have a forwarding method.
+

+

+
SymbolTable *getSymbolTable() +
Return a reference to the SymbolTable +for this Module.
+

+

+
Function *getFunction(const +std::string &Name, const FunctionType +*Ty) +
Look up the specified function in the Module SymbolTable. If it does not exist, +return null.
+

+
+
Function *getOrInsertFunction(const +std::string &Name, const FunctionType *T) +
Look up the specified function in the Module SymbolTable. If it does not exist, +add an external declaration for the function and return it.
+

+
+
std::string getTypeName(const Type *Ty) +
If there is at least one entry in the SymbolTable +for the specified Type, return it. +Otherwise return the empty string.
+

+
+
bool addTypeName(const std::string &Name, const Type *Ty) +
Insert an entry in the SymbolTable +mapping Name to Ty. If there is already an entry for +this name, true is returned and the SymbolTable +is not modified.
+

+

-
ConstantPointerRef : This represents a constant pointer value that is initialized to point to a global value, which lies at a constant fixed address. + + + + + + + +
The Constant +class and subclasses

-
GlobalValue *getValue(): Returns the global value to which this pointer is pointing to. -
+Constant represents a base class for different types of constants. It +is subclassed by ConstantBool, ConstantInt, ConstantSInt, ConstantUInt, +ConstantArray etc for representing the various types of Constants. +

- - - -

- -The Type class and Derived Types -

- -Type as noted earlier is also a subclass of a Value class. Any primitive -type (like int, short etc) in LLVM is an instance of Type Class. All -other types are instances of subclasses of type like FunctionType, -ArrayType etc. DerivedType is the interface for all such dervied types -including FunctionType, ArrayType, PointerType, StructType. Types can have -names. They can be recursive (StructType). There exists exactly one instance -of any type structure at a time. This allows using pointer equality of Type *s for comparing types. - - -

Important Public Methods