-
Notifications
You must be signed in to change notification settings - Fork 28
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #152 from tttturtle-russ/master
collect: llvm doc
- Loading branch information
Showing
2 changed files
with
1,171 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,299 @@ | ||
--- | ||
status: collected | ||
title: "Writing an LLVM Pass" | ||
author: Linux Kernel Community | ||
collector: tttturtle-russ | ||
collected_date: 20240807 | ||
link: https://github.com/llvm/llvm-project/blob/main/llvm/docs/WritingAnLLVMNewPMPass.rst | ||
--- | ||
# Writing an LLVM Pass | ||
|
||
::: program | ||
opt | ||
::: | ||
|
||
::: {.contents local=""} | ||
::: | ||
|
||
## Introduction \-\-- What is a pass? | ||
|
||
:::: warning | ||
::: title | ||
Warning | ||
::: | ||
|
||
This document deals with the new pass manager. LLVM uses the legacy pass | ||
manager for the codegen pipeline. For more details, see | ||
`WritingAnLLVMPass`{.interpreted-text role="doc"} and | ||
`NewPassManager`{.interpreted-text role="doc"}. | ||
:::: | ||
|
||
The LLVM pass framework is an important part of the LLVM system, because | ||
LLVM passes are where most of the interesting parts of the compiler | ||
exist. Passes perform the transformations and optimizations that make up | ||
the compiler, they build the analysis results that are used by these | ||
transformations, and they are, above all, a structuring technique for | ||
compiler code. | ||
|
||
Unlike passes under the legacy pass manager where the pass interface is | ||
defined via inheritance, passes under the new pass manager rely on | ||
concept-based polymorphism, meaning there is no explicit interface (see | ||
comments in `PassManager.h` for more details). All LLVM passes inherit | ||
from the CRTP mix-in `PassInfoMixin<PassT>`. The pass should have a | ||
`run()` method which returns a `PreservedAnalyses` and takes in some | ||
unit of IR along with an analysis manager. For example, a function pass | ||
would have a | ||
`PreservedAnalyses run(Function &F, FunctionAnalysisManager &AM);` | ||
method. | ||
|
||
We start by showing you how to construct a pass, from setting up the | ||
build, creating the pass, to executing and testing it. Looking at | ||
existing passes is always a great way to learn details. | ||
|
||
## Quick Start \-\-- Writing hello world | ||
|
||
Here we describe how to write the \"hello world\" of passes. The | ||
\"HelloWorld\" pass is designed to simply print out the name of | ||
non-external functions that exist in the program being compiled. It does | ||
not modify the program at all, it just inspects it. | ||
|
||
The code below already exists; feel free to create a pass with a | ||
different name alongside the HelloWorld source files. | ||
|
||
### Setting up the build {#writing-an-llvm-npm-pass-build} | ||
|
||
First, configure and build LLVM as described in | ||
`GettingStarted`{.interpreted-text role="doc"}. | ||
|
||
Next, we will reuse an existing directory (creating a new directory | ||
involves messing around with more CMake files than we want). For this | ||
example, we\'ll use `llvm/lib/Transforms/Utils/HelloWorld.cpp`, which | ||
has already been created. If you\'d like to create your own pass, add a | ||
new source file into `llvm/lib/Transforms/Utils/CMakeLists.txt` | ||
(assuming you want your pass in the `Transforms/Utils` directory. | ||
|
||
Now that we have the build set up for a new pass, we need to write the | ||
code for the pass itself. | ||
|
||
### Basic code required {#writing-an-llvm-npm-pass-basiccode} | ||
|
||
Now that the build is setup for a new pass, we just have to write it. | ||
|
||
First we need to define the pass in a header file. We\'ll create | ||
`llvm/include/llvm/Transforms/Utils/HelloWorld.h`. The file should | ||
contain the following boilerplate: | ||
|
||
``` c++ | ||
#ifndef LLVM_TRANSFORMS_HELLONEW_HELLOWORLD_H | ||
#define LLVM_TRANSFORMS_HELLONEW_HELLOWORLD_H | ||
|
||
#include "llvm/IR/PassManager.h" | ||
|
||
namespace llvm { | ||
|
||
class HelloWorldPass : public PassInfoMixin<HelloWorldPass> { | ||
public: | ||
PreservedAnalyses run(Function &F, FunctionAnalysisManager &AM); | ||
}; | ||
|
||
} // namespace llvm | ||
|
||
#endif // LLVM_TRANSFORMS_HELLONEW_HELLOWORLD_H | ||
``` | ||
|
||
This creates the class for the pass with a declaration of the `run()` | ||
method which actually runs the pass. Inheriting from | ||
`PassInfoMixin<PassT>` sets up some more boilerplate so that we don\'t | ||
have to write it ourselves. | ||
|
||
Our class is in the `llvm` namespace so that we don\'t pollute the | ||
global namespace. | ||
|
||
Next we\'ll create `llvm/lib/Transforms/Utils/HelloWorld.cpp`, starting | ||
with | ||
|
||
``` c++ | ||
#include "llvm/Transforms/Utils/HelloWorld.h" | ||
``` | ||
|
||
\... to include the header file we just created. | ||
|
||
``` c++ | ||
using namespace llvm; | ||
``` | ||
|
||
\... is required because the functions from the include files live in | ||
the llvm namespace. This should only be done in non-header files. | ||
|
||
Next we have the pass\'s `run()` definition: | ||
|
||
``` c++ | ||
PreservedAnalyses HelloWorldPass::run(Function &F, | ||
FunctionAnalysisManager &AM) { | ||
errs() << F.getName() << "\n"; | ||
return PreservedAnalyses::all(); | ||
} | ||
``` | ||
\... which simply prints out the name of the function to stderr. The | ||
pass manager will ensure that the pass will be run on every function in | ||
a module. The `PreservedAnalyses` return value says that all analyses | ||
(e.g. dominator tree) are still valid after this pass since we didn\'t | ||
modify any functions. | ||
That\'s it for the pass itself. Now in order to \"register\" the pass, | ||
we need to add it to a couple places. Add the following to | ||
`llvm/lib/Passes/PassRegistry.def` in the `FUNCTION_PASS` section | ||
``` c++ | ||
FUNCTION_PASS("helloworld", HelloWorldPass()) | ||
``` | ||
|
||
\... which adds the pass under the name \"helloworld\". | ||
|
||
`llvm/lib/Passes/PassRegistry.def` is #include\'d into | ||
`llvm/lib/Passes/PassBuilder.cpp` multiple times for various reasons. | ||
Since it constructs our pass, we need to also add the proper #include in | ||
`llvm/lib/Passes/PassBuilder.cpp`: | ||
|
||
``` c++ | ||
#include "llvm/Transforms/Utils/HelloWorld.h" | ||
``` | ||
|
||
This should be all the code necessary for our pass, now it\'s time to | ||
compile and run it. | ||
|
||
### Running a pass with `opt` | ||
|
||
Now that you have a brand new shiny pass, we can build | ||
`opt`{.interpreted-text role="program"} and use it to run some LLVM IR | ||
through the pass. | ||
|
||
``` console | ||
$ ninja -C build/ opt | ||
# or whatever build system/build directory you are using | ||
|
||
$ cat /tmp/a.ll | ||
define i32 @foo() { | ||
%a = add i32 2, 3 | ||
ret i32 %a | ||
} | ||
|
||
define void @bar() { | ||
ret void | ||
} | ||
|
||
$ build/bin/opt -disable-output /tmp/a.ll -passes=helloworld | ||
foo | ||
bar | ||
``` | ||
|
||
Our pass ran and printed the names of functions as expected! | ||
|
||
### Testing a pass | ||
|
||
Testing our pass is important to prevent future regressions. We\'ll add | ||
a lit test at `llvm/test/Transforms/Utils/helloworld.ll`. See | ||
`TestingGuide`{.interpreted-text role="doc"} for more information on | ||
testing. | ||
|
||
``` llvm | ||
$ cat llvm/test/Transforms/Utils/helloworld.ll | ||
; RUN: opt -disable-output -passes=helloworld %s 2>&1 | FileCheck %s | ||
; CHECK: {{^}}foo{{$}} | ||
define i32 @foo() { | ||
%a = add i32 2, 3 | ||
ret i32 %a | ||
} | ||
; CHECK-NEXT: {{^}}bar{{$}} | ||
define void @bar() { | ||
ret void | ||
} | ||
$ ninja -C build check-llvm | ||
# runs our new test alongside all other llvm lit tests | ||
``` | ||
|
||
## FAQs | ||
|
||
### Required passes | ||
|
||
A pass that defines a static `isRequired()` method that returns true is | ||
a required pass. For example: | ||
|
||
``` c++ | ||
class HelloWorldPass : public PassInfoMixin<HelloWorldPass> { | ||
public: | ||
PreservedAnalyses run(Function &F, FunctionAnalysisManager &AM); | ||
|
||
static bool isRequired() { return true; } | ||
}; | ||
``` | ||
A required pass is a pass that may not be skipped. An example of a | ||
required pass is `AlwaysInlinerPass`, which must always be run to | ||
preserve `alwaysinline` semantics. Pass managers are required since they | ||
may contain other required passes. | ||
An example of how a pass can be skipped is the `optnone` function | ||
attribute, which specifies that optimizations should not be run on the | ||
function. Required passes will still be run on `optnone` functions. | ||
For more implementation details, see | ||
`PassInstrumentation::runBeforePass()`. | ||
### Registering passes as plugins | ||
LLVM provides a mechanism to register pass plugins within various tools | ||
like `clang` or `opt`. A pass plugin can add passes to default | ||
optimization pipelines or to be manually run via tools like `opt`. For | ||
more information, see `NewPassManager`{.interpreted-text role="doc"}. | ||
Create a CMake project at the root of the repo alongside other projects. | ||
This project must contain the following minimal `CMakeLists.txt`: | ||
``` cmake | ||
add_llvm_pass_plugin(MyPassName source.cpp) | ||
``` | ||
|
||
See the definition of `add_llvm_pass_plugin` for more CMake details. | ||
|
||
The pass must provide at least one of two entry points for the new pass | ||
manager, one for static registration and one for dynamically loaded | ||
plugins: | ||
|
||
- `llvm::PassPluginLibraryInfo get##Name##PluginInfo();` | ||
- `extern "C" ::llvm::PassPluginLibraryInfo llvmGetPassPluginInfo() LLVM_ATTRIBUTE_WEAK;` | ||
|
||
Pass plugins are compiled and linked dynamically by default. Setting | ||
`LLVM_${NAME}_LINK_INTO_TOOLS` to `ON` turns the project into a | ||
statically linked extension. | ||
|
||
For an in-tree example, see `llvm/examples/Bye/`. | ||
|
||
To make `PassBuilder` aware of statically linked pass plugins: | ||
|
||
``` c++ | ||
// Declare plugin extension function declarations. | ||
#define HANDLE_EXTENSION(Ext) llvm::PassPluginLibraryInfo get##Ext##PluginInfo(); | ||
#include "llvm/Support/Extension.def" | ||
|
||
... | ||
|
||
// Register plugin extensions in PassBuilder. | ||
#define HANDLE_EXTENSION(Ext) get##Ext##PluginInfo().RegisterPassBuilderCallbacks(PB); | ||
#include "llvm/Support/Extension.def" | ||
``` | ||
To make `PassBuilder` aware of dynamically linked pass plugins: | ||
``` c++ | ||
// Load plugin dynamically. | ||
auto Plugin = PassPlugin::Load(PathToPlugin); | ||
if (!Plugin) | ||
report_error(); | ||
// Register plugin extensions in PassBuilder. | ||
Plugin.registerPassBuilderCallbacks(PB); | ||
``` |
Oops, something went wrong.