llvmSlides/IR API by wjf.md · li-qingan/csDocs

% 与LLVM IR相关的LLVM类及它们的一些用法
% 吴系风
% 2022年1月25日

# 模块（llvm::Module）

llvm::Module表示一个模块，就是一个载入内存中的LLVM IR文件。

可以通过函数（llvm::Function）对象如下的方法，获取它所在的模块：

```c++
Module* getParent()
```

------

# 上下文（llvm::LLVMContext）

llvm::LLVMContext代表了一个LLVM的上下文。

可以通过函数（llvm::Function）对象如下的方法，获取它的上下文：

```c++
LLVMContext& Function::getContext()	const
```

------

# 类型llvm::Type（及其子类）

可以通过如llvm::Type如下的静态函数获取类型对象：

## 空类型

```c++
static Type* getVoidTy (LLVMContext& C)
```

## 标签类型

```c++
static Type* getLabelTy (LLVMContext& C)
```

## 整数类型

```c++
static IntegerType* getInt1Ty (LLVMContext& C)
static IntegerType* getInt8Ty (LLVMContext& C)
static IntegerType* getInt16Ty (LLVMContext& C)
static IntegerType* getInt32Ty (LLVMContext& C)
static IntegerType* getInt64Ty (LLVMContext& C)
static IntegerType* getInt128Ty (LLVMContext& C)
```

## 浮点数类型

```c++
static Type* getHalfTy (LLVMContext& C)
static Type* getBFloatTy (LLVMContext& C)
static Type* getFloatTy (LLVMContext& C) 
static Type* getDoubleTy (LLVMContext& C)
```

## 指针类型

其中，参数AS的含义为address space（地址空间）。默认地址空间为0。

```c++
static PointerType* getHalfPtrTy (LLVMContext& C, unsigned AS=0)
static PointerType* getBFloatPtrTy (LLVMContext& C, unsigned AS=0)
static PointerType* getFloatPtrTy (LLVMContext& C, unsigned AS=0)
static PointerType* getDoublePtrTy (LLVMContext& C, unsigned AS=0)
 
static PointerType* getInt1PtrTy (LLVMContext& C, unsigned AS=0)
static PointerType* getInt8PtrTy (LLVMContext& C, unsigned AS=0)
static PointerType* getInt16PtrTy (LLVMContext& C, unsigned AS=0)
static PointerType* getInt32PtrTy (LLVMContext& C, unsigned AS=0)
static PointerType* getInt64PtrTy (LLVMContext& C, unsigned AS=0)
```

## 函数类型

```c++
FunctionType* FunctionType::get(
    result, // Type* Result
    params, // ArrayRef<Type *> Params
    isVarArg // bool isVarArg 
);
```

------

# 值llvm::Value（子类包括函数llvm::Function、常数llvm::Constant、指令llvm::Instruction）

## 获取值的类型

```c++
Type* getType() const
```

## 读写该值的名称

通过如下方法，读写该值的名称：

```c++
StringRef getName() const
void setName(const Twine& Name)
```

## 遍历该值的使用者

通过如下方法，获取遍历该值用例（Use）的迭代器：

```c++
use_iterator use_begin()
use_iterator use_end()
```

如下所示：

```c++
// 上文定义了llvm::Value* value
for (auto it = value->use_begin(), end = value->use_end(); it != end; ++it) {
    llvm::Use& useReference = *it;
    llvm::User* user = useReference.getUser();
    // ...
}
```

指令（llvm::Instruction）为llvm::User的子类。

------

# 函数llvm::Function

## 创建函数

```
llvm::Function* function = llvm::Function::Create(
    ty, // FunctionType* Ty
    linkage, // LinkageTypes Linkage
    n, // const Twine& N = ""
    m // Module* M = nullptr
)
```

其中，参数linkage的类型为llvm::GlobalValue::LinkageTypes。这是一个枚举，包含如下的值（通常使用llvm::GlobalValue::LinkageTypes::ExternalLinkage）：

ExternalLinkage
: Externally visible function.

AvailableExternallyLinkage
: Available for inspection, not emission.

LinkOnceAnyLinkage
: Keep one copy of function when linking (inline).

LinkOnceODRLinkage
: Same, but only replaced by something equivalent.

WeakAnyLinkage
: Keep one copy of named function when linking (weak)

WeakODRLinkage
: Same, but only replaced by something equivalent.

AppendingLinkage
: Special purpose, only applies to global arrays.

InternalLinkage
: Rename collisions when linking (static functions).

PrivateLinkage
: Like Internal, but omit from symbol table.

ExternalWeakLinkage
: ExternalWeak linkage description.

CommonLinkage
: Tentative definitions.

## 遍历函数的基本块

可以通过如下的方法，获取遍历函数的基本块的迭代器：

```c++
iterator begin() 
iterator end()
```

因此，可以通过如下的for循环遍历函数的基本块：

```c++
// 在上文中定义了llvm::Function& functionReference
for (llvm::BasicBlock& basicBlockReference: functionReference) {
    // ...
}
```

获取函数基本块的数量：

```c++
size_t size() const
```

## 获取函数所在的模块

```c++
Module* getParent()
```

## 获取函数所在的上下文

```c++
LLVMContext& getContext() const
```

## 获取函数的参数

```c++
Argument* getArg(unsigned i) const
```

返回值的类型为llvm::Argument*。llvm::Argument是llvm::Value的子类。

------

# 基本块llvm::BasicBlock

## 创建基本块

```c++
llvm::BasicBlock* basicBlock = llvm::BasicBlock::Create(
    context, // LLVMContext& Context
    name, // const Twine& Name = ""
    parent, // Function* Parent = nullptr
    insertBefore // BasicBlock* InsertBefore = nullptr 
); 
```

如果在函数的末尾创建基本块，提供nullptr作为参数insertBefore的值。

## 获取基本块所在的函数

```c++
const Function* getParent() const
```

## 遍历基本块的前驱和后继

使用下列函数，需要引入头文件`llvm/IR/CFG.h`。

可以通过如下的全局函数，获取遍历基本块前驱的迭代器：

```c++
pred_iterator 	llvm::pred_begin(BasicBlock* BB)
pred_iterator 	llvm::pred_end (BasicBlock *BB)
```

可以通过如下的全局函数，获取遍历基本块后继的迭代器：

```c++
succ_iterator llvm::succ_begin(BasicBlock* BB)
succ_iterator llvm::succ_end(BasicBlock* BB)
```

如下所示：

```c++
// 在上文中定义了llvm::BasicBlock* basicBlock
for (auto it = llvm::pred_begin(basicBlock), end = llvm::pred_end(basicBlock); it != end; ++it) {
    llvm::BasicBlock* predecessor = *it;
    // ...
}
```

获取基本块前驱、后继的数量：

```c++
unsigned llvm::pred_size(const BasicBlock* BB)
unsigned llvm::succ_size(const BasicBlock* BB)
```

## 获取基本块所在的函数的上一个基本块

```c++
const BasicBlock* getPrevNode() const
```

如果该基本块是函数的第一个基本块，返回nullptr。

## 获取基本块所在的函数的下一个基本块

```c++
const BasicBlock* getNextNode() const
```

如果该基本块是函数的最后一个基本块，返回nullptr。

## 将基本块从原函数中移除，插入新函数中

### 将基本块从原函数中移除

```c++
void removeFromParent()
```

### 将基本块插入新函数中

```c++
void insertInto(
    parent, // Function* Parent,
    insertBefore // BasicBlock* InsertBefore=nullptr
)
```

如果将基本块插入新函数末尾，提供nullptr作为参数insertBefore的值。

------

# 常数llvm::Constant（及其子类）

## 创建常布尔值（`i1`类型的整数）

```c++
llvm::ConstantInt* boolValue = llvm::ConstantInt::getBool(
    context, // LLVMContext& Context
    v // bool V 
);
```

## 创建常整数

```c++
llvm::ConstantInt* constantInt = llvm::ConstantInt::get(
    ty, // IntegerType* Ty
    value, // uint64_t V
    isSigned // bool IsSigned = false 
);
```

------

# 指令llvm::Instruction（及其子类）

## 访问、修改操作数

获取已有的操作数的数目：

```c++
unsigned getNumOperands() const
```

访问、修改操作数：

```c++
Value* getOperand(unsigned i) const
void setOperand(unsigned i, Value* Val)
```

## 获取指令所在的基本块

```c++
const BasicBlock* llvm::Instruction::getParent() const
```

## 将指令从基本块中删除

```c++
SymbolTableList<Instruction>::iterator eraseFromParent()
```

返回指向后继指令的迭代器。

## 具体指令

### 二元运算llvm::BinaryOperator

#### 创建二元运算

```c++
llvm::BinaryOperator* binaryOperator = llvm::BinaryOperator::Create(
    op, // BinaryOps Op
    s1, // Value* S1
    s2, // Value* S2
    name, // const Twine & Name
    insertAtEnd // BasicBlock* InsertAtEnd
);
```

其中，参数op的类型为llvm::Instruction::BinaryOps。这是一个枚举，包含如下的值：

算数运算
: Add
: FAdd
: Sub
: FSub
: Mul
: FMul
: UDiv
: SDiv
: FDiv
: URem
: SRem
: FRem

逻辑运算
: Shl // Shift left  (logical)
: LShr // Shift right (logical)
: AShr // Shift right (arithmetic)
: And
: Or
: Xor

### cmp指令llvm::CmpInst

#### 创建cmp指令

```c++
llvm::CmpInst* cmpInst = llvm::CmpInst::Create(
    op, // OtherOps Op
    predicate, // Predicate predicate
    s1, // Value* S1
    s2, // Value* S2
    name, // const Twine& Name
    insertAtEnd // BasicBlock* Insert
);
```

其中：

参数op的类型为llvm::Instruction::OtherOps。这是一个枚举，包含如下的值：

ICmp
: 整数比较

FCmp:
: 浮点数比较

参数predicate的类型为llvm::CmpInst::Predicate。这是一个枚举，包含如下的值：

整数

ICMP_EQ 	
: 整数相等

ICMP_NE 	
: 整数不等

ICMP_UGT
: 无符号整数大于

ICMP_UGE
: 无符号整数大于等于

ICMP_ULT
: 无符号整数小于

ICMP_ULE 
: 无符号整数小于等于

ICMP_SGT
: 有符号整数大于

ICMP_SGE
: 有符号整数大于等于

ICMP_SLT
: 有符号整数小于

ICMP_SLE
: 有符号整数小于等于

浮点数

FCMP_ORD
: 两个浮点数均不为nan

FCMP_OEQ
: 两个浮点数均不为nan，且s1 == s2

FCMP_ONE 	
: 两个浮点数均不为nan，且s1 != s2

FCMP_OGT
: 两个浮点数均不为nan，且s1 > s2

FCMP_OGE
: 两个浮点数均不为nan，且s1 >= s2

FCMP_OLT
: 两个浮点数均不为nan，且s1 < s2

FCMP_OLE
: 两个浮点数均不为nan，且s1 <= s2

FCMP_UNO
: 至少有一个浮点数为nan

FCMP_UEQ
: s1 == s2，或至少有一个浮点数为nan

FCMP_UNE
: s1 != s2，或至少有一个浮点数为nan

FCMP_UGT
: s1 > s2，或至少有一个浮点数为nan

FCMP_UGE
: s1 >= s2，或至少有一个浮点数为nan

FCMP_ULT
: s1 < s2，或至少有一个浮点数为nan

FCMP_ULE
: s1 <= s2，或至少有一个浮点数为nan

### alloca指令llvm::AllocaInst

#### 创建alloca指令

分配单个对象：

```c++
llvm::AllocaInst* allocaInst = new llvm::AllocaInst(
    ty, // Type * Ty
    addrSpace, // unsigned AddrSpace, Address space 0 is the default address space
    name, // const Twine& Name
    insertAtEnd // BasicBlock* InsertAtEnd
);
```

分配一个数组：

```c++
llvm::AllocaInst* allocaInst = new llvm::AllocaInst(
    ty, // Type * Ty
    addrSpace, // unsigned AddrSpace, Address space 0 is the default address space
    arraySize, // Value* ArraySize
    name, // const Twine& Name
    insertAtEnd // BasicBlock* InsertAtEnd
)
```

其中，参数addrSpace的含义为地址空间。默认地址空间为0。

### getelementptr指令llvm::GetElementPtrInst

#### 创建getelementptr指令

```c++
llvm::GetElementPtrInst* getElementPtrInst = llvm::GetElementPtrInst::Create(
    pointeeType, // Type* PointeeType
    ptr, // Value* Ptr
    idxList, // ArrayRef<Value *> IdxList
    nameStr, // const Twine& NameStr
    insertAtEnd // BasicBlock* InsertAtEnd
);
```

### load指令llvm::LoadInst

#### 创建load指令

```c++
llvm::LoadInst* loadInst = new llvm::LoadInst(
    ty, // Type * Ty
    ptr, // Value* Ptr
    nameStr, // const Twine& NameStr
    insertAtEnd // BasicBlock* InsertAtEnd
);
```

其中，参数ptr通常是getelementptr指令。

### store指令llvm::StoreInst

#### 创建store指令

```c++
llvm::StoreInst* storeInst = new llvm::StoreInst(
    val, // Value* Val
    ptr, // Value* Ptr
    insertAtEnd // BasicBlock* InsertAtEnd
);
```

其中，参数ptr通常是getelementptr指令。

### phi指令llvm::PHINode

#### 创建phi指令

```c++
llvm::PHINode* phiNode = llvm::PHINode::Create(
    ty, // Type* Ty
    numReservedValues, // unsigned NumReservedValues
    nameStr, // const Twine& NameStr
    insertAtEnd // BasicBlock* InsertAtEnd 
);
```

提供参数numReservedValues只是为所有的值和基本块分配空间，但是创建之后仍然需要插入值和基本块。

phi指令只能出现在基本快的头部。如下所示的LLVM IR将会报错`PHI nodes not grouped at top of basic block!`：

```
103:                                              ; preds = %13
  %104 = phi i8* [ %81, %13 ]
  %105 = getelementptr %0, %0* %0, i32 0, i32 0
  store i8* %104, i8** %105
  %106 = phi i64 [ %58, %13 ]
  %107 = getelementptr %0, %0* %0, i32 0, i32 1
  store i64 %106, i64* %107
  %108 = phi i64 [ %59, %13 ]
  %109 = getelementptr %0, %0* %0, i32 0, i32 2
  store i64 %108, i64* %109
  %110 = phi i64 [ %19, %13 ]
  %111 = getelementptr %0, %0* %0, i32 0, i32 3
  store i64 %110, i64* %111
  %112 = phi i8* [ %52, %13 ]
  %113 = getelementptr %0, %0* %0, i32 0, i32 4
  store i8* %112, i8** %113
  %114 = getelementptr %0, %0* %0, i32 0, i32 5
  store i8 0, i8* %114
  %115 = getelementptr %1, %1* %9, i32 0, i32 5
  store i1 true, i1* %115
  ret void
```

#### 插入新的值和基本块

```c++
void addIncoming(Value* V, BasicBlock* BB)
```

#### 访问、修改已有的值和基本块

获取已有的值和基本块的数目：

```c++
unsigned getNumIncomingValues() const
```

访问、修改值：

```c++
Value* getIncomingValue(unsigned i) const
void setIncomingValue(unsigned i, Value* V)
```

访问、修改基本块：

```c++
BasicBlock* getIncomingBlock(unsigned i) const
void setIncomingBlock(unsigned i, BasicBlock* BB)
```

### call指令llvm::CallInst

#### 创建call指令

```c++
llvm::CallInst* callInst = llvm::CallInst::Create(
    ty, // FunctionType* Ty
    f, // Value* F
    args, // ArrayRef< Value *> Args
    nameStr, // const Twine& NameStr
    insertAtEnd // BasicBlock* InsertAtEnd 
);
```

其中，参数ty为函数类型，参数f为函数本身（通常类型为llvm::Function *）。

### br指令llvm::BranchInst

#### 创建br指令

无条件分支

```c++
llvm::BranchInst* branchInst = llvm::BranchInst::Create(
    ifTrue, // BasicBlock* IfTrue
    insertAtEnd // BasicBlock* InsertAtEnd 
);
```

有条件分支

```c++
llvm::BranchInst* branchInst = llvm::BranchInst::Create(
    ifTrue, // BasicBlock* IfTrue
    ifFalse, // BasicBlock* ifFalse
    cond, // Value* Cond
    insertAtEnd // BasicBlock* InsertAtEnd 
);
```

### switch指令llvm::SwitchInst

#### 创建switch指令

```c++
llvm::SwitchInst* switchInst = llvm::SwitchInst::Create(
    value, // Value* value
    default, // BasicBlock* default
    numCases, // unsigned NumCases
    insertAtEnd // BasicBlock* insertAtEnd
);
```

提供参数numCases只是为所有的（非default）case分配空间，但是创建之后仍然需要插入（非default）case。

#### 插入（非default）case

```c++
void addCase(ConstantInt* OnVal, BasicBlock* Dest)
```

#### 遍历case

通过如下的方法，获取遍历所有case（含default）的迭代器：

```c++
CaseIt case_begin()
CaseIt case_end()
```

通过如下的方法，获取指向default case的迭代器：

```c++
CaseIt case_default()
```

CaseIt的完整类型为llvm::SwitchInst::CaseIt。它提供了如下的方法：

```c++
BasicBlock* getCaseSuccessor()
ConstantInt* getCaseValue()

void setSuccessor(BasicBlock* S)
void setValue(ConstantInt* V)
```

### ret指令llvm::ReturnInst

#### 创建ret指令

```c++
llvm::ReturnInst* returnInst = llvm::ReturnInst::Create(
    c, // LLVMContext& C
    retVal, // Value* retVal
    insertAtEnd // BasicBlock* InsertAtEnd 
);
```

如果要返回void，提供nullptr作为参数retVal的值。

li-qingan/csDocs

简介

发行版

贡献者

近期动态

li-qingan/csDocs .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

li-qingan/csDocs