LLVM程序员手册笔记——Important and useful LLVM APIs

 

Important and useful LLVM APIs

这部分主要介绍了一些需要知道并会经常用到的LLVM APIs。

The isa<>, cast<> and dyn_cast<> templates

Passing strings(the StringRef and Twine classes)

The DEBUG() macro and -debug option

The Statistic class & -stats option

Viewing graphs while debugging code

 

 

The isa<>, cast<> and dyn_cast<> templates

LLVM的源代码基础广泛使用了一种自定义形式的运行时类型信息。这些模板与C++的dynamic_cast<>操作符具有很多相似之处，但是没有它的一些障碍（这些缺点主要由于dynamic_cast<>只能处理具有虚函数表的类）。由于它们被经常使用，所以必须知道它们做了什么以及如何实现的。这些模板都在llvm/Support/Casting.h文件中定义（注：很少需要直接包含该头文件）。

isa<>:

isa<>操作符的作用很像java中的“instanceof”操作符。它根据一个引用或者指针是否指向一个指定类来返回true或者false。这对许多约束检查都非常有用。

cast<>:

cast<>操作符是“checked cast”操作。它将一个基类的指针或引用转换到子类，如果不是指定类型的实例，就会造成一个断言错误。当能确定一个指针或引用确实是某个类型时，才能使用cast<>。

这里有个isa<>和cast<>的例子：

static bool isLoopInvariant(const Value *V, const Loop *L) { if (isa<Constant>(V) || isa<Argument>(V) || isa<GlobalValue>(V)) return true; // Otherwise, it must be an instruction... return !L->contains(cast<Instruction>(V)->getParent()); }

注：不应该在使用isa<>检测后，再使用cast<>，这种情况下应该使用dyn_cast<>操作符。

dyn_cast<>:

dyn_cast<>操作符是“Checking cast”操作。检查一个操作数是否属于一个指定类型，如果是，返回指向该类型的指针（该操作符对引用无效）；如果不是，返回空指针。所以，它和C++中的dynamic_cast<>操作符很像，也应该用在同样的情况下。dyn_cast<>的经典用法是用在if语句或者其它的流控制语句中。

if (AllocationInst *AI = dyn_cast<AllocationInst>(Val)) { // ... }

上述形式的if语句有效地将isa<>和cast<>的调用组合到一条语句中，非常方便。

注：dyn_cast<>操作，象C++的dynamic_cast<>或者Java的instanceof操作符一样，可能被滥用。在实际中，不应该将大量的if/then/else块串在一起来检查大量类的不同变体。如果确实需要做这样一件事，使用InstVisitor类会更加清晰和有效地直接派遣到指令类型。

cast_or_null<>:

cast_or_null<>操作符的功能类似于cast<>操作符，只是它允许空指针作为参数。这样可以让将几个Null检查合并成一个，有时可能很有用。

dyn_cast_or_null<>:

dyn_cast_or_null<>操作符的功能和dyn_cast<>操作符相似，它也允许空指针作为参数。

无论一个类是否具有虚函数表，上述五个模板的可以在其中使用。为了支持这些模板，只需往想进行转换的类中添加名为classof的静态方法。关于这块的描述需要参看LLVM源代码中的实例。

Passing strings(the StringRef and Twine classes)

尽管LLVM不进行很多的字符串处理，但还是有一些重要的APIs使用了字符串。两个重要的例子：Value类，包含指令、函数的名字等；StringMap类，在LLVM和Clang中广泛使用。

有一些通用类，它们需要接受一些嵌入了空字符的字符串。所以，它们不能简单地使用const char*, 或者使用const std::string&需要程序进行一些不必要的堆分配。取而代之，很多LLVM APIs使用const StringRef&或const Twine&来进行高效地传输字符串。

The StringRef class

StringRef数据类型表示对一个常量字符串的引用(一个字符数组或者一个长度)，并支持std::string上可用一般操作，但是不需要堆分配。

可以隐式地使用一个null-terminated的C样式字符串(std::string)来构造，或者显式地使用字符指针和长度。例如，StringRef的find函数声明为：

iterator find(const StringRef &Key);

而程序员可以采用下面的任何一种形式：

Map.find("foo"); // Lookup "foo" Map.find(std::string("bar")); // Lookup "bar" Map.find(StringRef("/0baz", 4)); // Lookup "/0baz"

类似地，需要返回字符串的APIs会返回一个StringRef的实例。而它可以直接使用或者使用str成员函数转换成std::string.

应该会很少直接使用StringRef类，因为它包含了指向外部内存，而用它来存储对象并不是一直安全的(除非知道外部存储不会被释放)。

The Twine class

Twine类是APIs用来接受串联字符串的有效途径。例如，一个常见的LLVM范例是根据某个指令的名字加上后缀为新指令命名。

New = CmpInst::Create(..., SO->getName() + ".cmp");

Twine类是轻量级并且高效的rope，它指向临时的(在栈上分配的)对象。Twine类的实例可以是作为字符串(C strings, std::string, StringRef)加法结果隐式构造的。Twine类推迟了字符串的实际连接操作，直到连接结果的确需求，而这时可以直接高效地将结果存入字符数组中。这避免了在构建字符串连接临时对象时进行的不必要堆分配。

因为StringRef, Twine对象指向外部内存，这些内存应该从不被直接存储或者提及。它们应该只在意图定义一个能有效地接受连接字符串的函数时才出现。

The DEBUG() macro and -debug option

有时可能需要添加一系列的调试输出以及其他代码到实际的主线工作代码中。当主线代码能正常工作后，需要移除这些调试代码，但是将来可能又需要它们(譬如解决)。

由于上述原因，不会删除调试输出代码，但又不希望它们总是产生冗余信息。一种标准的折衷办法就是注释掉它们，使之可以在将来需要的时候再激活它们。

"llvm/Support/Debug.h"中提供了一个名为DEBUG()的宏，这是一种更好的处理方法。基本上，可以将任意代码添加到DEBUG宏中，这段代码只会在'opt'(或其他程序)在命令行中传递了‘-debug’参数时才会执行。

DEBUG(errs() << "I am here!/n");

然后这样使用：

$ opt < a.bc > /dev/null -mypass <no output> $ opt < a.bc > /dev/null -mypass -debug I am here!

使用DEBUG()宏代替自己酝酿的解决方案，可以为调试输出创建另一个命令行参数选项。

注：1.DEBUG()宏对优化的构建过程不可用，所以它们不会造成任何性能上的影响(也不会有任何副作用)。

      2.可以直接在gdb中进行开关，只需要在程序运行中“set DebugFlag=0”或者“set DebugFlag=1”。如果程序没有运行，可以使用-debug参数开始运行。 

Fine grained Debug info with DEBUG_TYPE and the -debug-only option

有时在打开-debug选项时，会产生过多的信息(譬如在调试代码生成器时)。如果需要对调试信息进行更精细的控制，可以定义DEBUG_TYPE宏和-debug-only选项。

#undef DEBUG_TYPE DEBUG(errs() << "No debug type/n"); #define DEBUG_TYPE "foo" DEBUG(errs() << "'foo' debug type/n"); #undef DEBUG_TYPE #define DEBUG_TYPE "bar" DEBUG(errs() << "'bar' debug type/n")); #undef DEBUG_TYPE #define DEBUG_TYPE "" DEBUG(errs() << "No debug type (2)/n");

然后这样使用：

$ opt < a.bc > /dev/null -mypass <no output> $ opt < a.bc > /dev/null -mypass -debug No debug type 'foo' debug type 'bar' debug type No debug type (2) $ opt < a.bc > /dev/null -mypass -debug-only=foo 'foo' debug type $ opt < a.bc > /dev/null -mypass -debug-only=bar 'bar' debug type

注：1.实际使用中，应该只在文件的顶端设置DEBUG_TYPE，以为整个模块指定调试类型(如果在#include "llvm/Support/Debug.h"前设置，就不需要丑陋的#undef's)。

      2.因为没有保证名字不发生冲突的机制，所以应该使用比“foo”和“bar”更形象的名字。如果两个不同的模块中，使用了同样名字，这两个开关都会被开启。 

即使设定了DEBUG_TYPE宏，也可以使用DEBUG_WITH_TYPE，但只对特定语句有效。需要额外的第一个参数，该参数为使用的类型。

DEBUG_WITH_TYPE("", errs() << "No debug type/n"); DEBUG_WITH_TYPE("foo", errs() << "'foo' debug type/n"); DEBUG_WITH_TYPE("bar", errs() << "'bar' debug type/n")); DEBUG_WITH_TYPE("", errs() << "No debug type (2)/n");

The Statistic class & -stats option

在"llvm/ADT/Statistic.h"文件中提供了名为statistic的类，该类用于记录LLVM编译器正在干什么以及各种优化的性能。这能帮助确定哪种优化使实际程序运行更快。

当对大程序进行处理时，会关注进行多少次特定的转换。当然可以人工观察，或者添加ad-hoc方法(指特为此功能实现的方法)，但这都是很痛苦的事情，而且对大程序并没有多少用。使用Statistic类可以非常轻松地记录这种信息，并计算这些信息并以和其他执行方案统一的方法输出。

1.如下定义统计宏：

#define DEBUG_TYPE "mypassname" // This goes before any #includes. STATISTIC(NumXForms, "The # of times I did stuff");

STATISTIC宏定义了一个静态变量，名字由第一个参数指定。而方案名称从DEBUG_TYPE宏而来，描述作为第二个参数。 定义的变量就如同无符号整形一般。

2.然后每进行一次转换，增加计数器：

++NumXForms; // I did stuff! 
3.使用"-stats"命令行参数输出收集到的统计信息：

$ opt -stats -mypassname < program.bc > /dev/null ... statistics output ...

4.对一个SPEC基准测试套的统计报告如下：

7646 bitcodewriter - Number of normal instructions 725 bitcodewriter - Number of oversized instructions 129996 bitcodewriter - Number of bitcode bytes written 2817 raise - Number of insts DCEd or constprop'd 3213 raise - Number of cast-of-self removed 5046 raise - Number of expression trees converted 75 raise - Number of other getelementptr's formed 138 raise - Number of load/store peepholes 42 deadtypeelim - Number of unused typenames removed from symtab 392 funcresolve - Number of varargs functions resolved 27 globaldce - Number of global variables removed 2 adce - Number of basic blocks removed 134 cee - Number of branches revectored 49 cee - Number of setcc instruction eliminated 532 gcse - Number of loads removed 2919 gcse - Number of instructions removed 86 indvars - Number of canonical indvars added 87 indvars - Number of aux indvars removed 25 instcombine - Number of dead inst eliminate 434 instcombine - Number of insts combined 248 licm - Number of load insts hoisted 1298 licm - Number of insts hoisted to a loop pre-header 3 licm - Number of insts hoisted to multiple loop preds (bad, no loop pre-header) 75 mem2reg - Number of alloca's promoted 1444 cfgsimplify - Number of blocks simplified

在这么多优化中，有输出统计信息的框架无疑是件好事。让方案符合这个框架，会使得它更易维护和使用。

Viewing graphs while debugging code

在LLVM中很多重要的数据结构都是图，例如由LLVM BasicBlock构成的控制流图，由MachineBasicBlock构成的控制流图，以及指令选择有向无环图。很多情况下，能即时显示这些图对调试编译器的有很大地帮助。

LLVM提供了几种在debug build下能实现上述功能的callback。例如调用了Function::viewCFG()方法，当前的LLVM工具将会弹出一个包含该函数控制流图的窗口，类似的方法还有Function::viewCFGOnly()(与前者相比，没有指令)、MachineFunction::viewCFG()、MachineFunction::viewCFGOnly()、SelectionDAG::viewGraph()。在GDB中，常用到类似于call DAG.viewGraph()的命令来弹出一个窗口。或者，可以在希望调试的代码位置加入这些调用。

让这个功能正常运转，需要一些配置。在X11的Unix系统上，安装graphviz工具包，并确保'dot'和'gv'在path环境变量中；在Mac OS/X上，下载并安装相应的Graphviz程序，并添加安装路径到环境变量中。这些工作完成后，重新运行LLVM configure脚本并重新build LLVM以激活功能。

SelectionDAG经过扩展，更易于定位复杂大图中感兴趣的结点。在gdb中，如果使用call DAG.setGraphColor(node, "color")，那么之后的call DAG.viewGraph将会以指定颜色高亮显式结点。通过call DAG.SetGraphAttrs(node, "attributes")还可以进行更加复杂的属性设置。还可以用call DAG.clearGraphAttrs()清除重置所有的图属性。