Using the TPDE Codegen Backend in LLVM ORC

Tue, 30 Sep 2025 10:00:00 +0000

TPDE is a single-pass compiler backend for LLVM that was open-sourced earlier this year by researchers at TUM. The comprehensive documentation walks you through integrating TPDE into custom builds of Clang and Flang. Currently, it supports LLVM 19 and LLVM 20 release versions.

Integration in LLVM ORC JIT

TPDE’s primary strength lies in delivering low-latency code generation while maintaining reasonable -O0 code quality — making it an ideal choice for a baseline JIT compiler. LLVM’s On-Request Compilation (ORC) framework provides a set of libraries for building JIT compilers for LLVM IR. While ORC uses LLVM’s built-in backends by default, its flexible architecture makes it straightforward to swap in TPDE instead!

Let’s say we use the LLJITBuilder interface to instantiate an off-the-shelf JIT:

ExitOnError ExitOnErr;
auto Builder = LLJITBuilder();
std::unique_ptr<LLJIT> JIT = ExitOnErr(Builder.create());

The builder offers several extension points to customize the JIT instance it creates. To integrate TPDE, we’ll override the CreateCompileFunction member, which defines how LLVM IR gets compiled into machine code:

Builder.CreateCompileFunction = [](JITTargetMachineBuilder JTMB)
    -> Expected<std::unique_ptr<IRCompileLayer::IRCompiler>> {
  return std::make_unique<TPDECompiler>(JTMB);
};

To use TPDE in this context, we need to wrap it in a class that’s compatible with ORC’s interface:

class TPDECompiler : public IRCompileLayer::IRCompiler {
public:
  TPDECompiler(JITTargetMachineBuilder JTMB)
      : IRCompiler(irManglingOptionsFromTargetOptions(JTMB.getOptions())) {
    Compiler = tpde_llvm::LLVMCompiler::create(JTMB.getTargetTriple());
    assert(Compiler != nullptr && "Unknown architecture");
  }

  Expected<std::unique_ptr<MemoryBuffer>> operator()(Module &M) override;

private:
  std::unique_ptr<tpde_llvm::LLVMCompiler> Compiler;
  std::vector<std::unique_ptr<std::vector<uint8_t>>> Buffers;
};

In the constructor, we initialize TPDE with a target triple (like x86_64-pc-linux-gnu). TPDE currently works on ELF-based systems and supports both 64-bit Intel and ARM architectures (x86_64 and aarch64). For now let’s assume that’s all we need. Now let’s implement the actual wrapper code:

Expected<std::unique_ptr<MemoryBuffer>> TPDECompiler::operator()(Module &M) {
  Buffers.push_back(std::make_unique<std::vector<uint8_t>>());
  std::vector<uint8_t> &B = *Buffers.back();

  if (!Compiler->compile_to_elf(M, B)) {
    std::string Msg;
    raw_string_ostream(Msg) << "TPDE failed to compile: " << M.getName();
    return createStringError(std::move(Msg), inconvertibleErrorCode());
  }

  StringRef BufferRef{reinterpret_cast<char *>(B.data()), B.size()};
  return MemoryBuffer::getMemBuffer(BufferRef, "", false);
}

Here’s what’s happening: we create a new buffer B to store the compiled binary code, then pass both the buffer and the module M to TPDE for compilation. If TPDE fails, we bail out with an error. On success, we wrap the result in a MemoryBuffer and return it. (Note: LLVM still uses char pointers for binary buffers and the three-way definition of char in the C Standard falls on our feet sometimes, but it’s difficult to change in a mature codebase like LLVM.)

For the basic integration this is it! No need to patch LLVM — this works with official release versions. We can compile simple LLVM IR code already:

> cat 01-basic.ll 
; ModuleID = 'test.ll'
source_filename = "test.ll"

define i32 @main() {
entry:
  %1 = call i32 @custom_entry()
  %2 = sub i32 %1, 123
  ret i32 %2
}

define i32 @custom_entry() {
entry:
  ret i32 123
}

I’ve created a complete working demo on GitHub that you can try out. The code in the repo handles a few more details that we’ll explore shortly. Here’s what the output looks like:

> ./tpde-orc 01-basic.ll 
Loaded module: 01-basic.ll
Executing main()
Program returned: 0

> ./tpde-orc 01-basic.ll --entrypoint custom_entry
Loaded module: 01-basic.ll
Executing custom_entry()
Program returned: 123

We can see an impressive 20x speedup with TPDE compared to built-in LLVM codegen for 100 repetitions with a large self-contained module that was generated with csmith:

> ./build/tpde-orc --par 1 tpde-orc/03-csmith-tpde.ll
...
Compile-time was: 329 ms

> ./build/tpde-orc --par 1 tpde-orc/03-csmith-tpde.ll --llvm
...
Compile-time was: 6796 ms

Please note: This is not a benchmark! It’s just one example on one machine with one possible implementation. The implementation isn’t tuned to the limit and the example might not be representative.

My original post showed slower compile-times on both sides. I addressed some feedback and the TPDE case got a lot faster, so I updated the numbers. It’s worth mentioning that it’s not really fair to compare against LLVM like that, because the off-the-shelf ORC JIT uses optimization level -O2. I changed that to -O0 and TPDE speedup comes down to 12x:

> ./build/tpde-orc --par 1 tpde-orc/03-csmith-tpde.ll --llvm
...
Compile-time was: 4060 ms

LLJITBuilder has a Catch

While LLJITBuilder is convenient, it comes with a minor trade-off. The interface incorporates standard LLVM components including TargetRegistry, which is perfectly reasonable for most use cases. However, this creates a dependency we might not want: the built-in LLVM target backend must be initialized first via InitializeNativeTarget(). This means we still need to ship the LLVM backend, even though TPDE could theoretically replace it entirely.

If you want to avoid this dependency, you’ll need to set up your ORC JIT manually. For inspiration on this approach, check out how the tpde-lli tool implements it. Before diving into that rabbit hole though, let’s explore another important aspect!

Implementing a LLVM Fallback

One reason why TPDE is so fast and compact is that it focuses on the most common use cases rather than covering every edge case in the LLVM instruction set. The documentation provides this guideline:

Code generated by Clang (-O0/-O1) will typically compile; -O2 and higher will typically fail due to unsupported vector operations.

When your code includes advanced features like vector operations or non-trivial floating-point types, TPDE won’t be able to handle it. In these cases, we need a fallback to LLVM. Since this scenario is quite common in real-world applications, most tools will include both backends (and we can keep using LLJITBuilder). Implementing the fallback is straightforward using ORC’s CompileUtils:

@@ -29,7 +29,8 @@ static cl::opt<std::string> EntryPoint("entrypoint",
 class TPDECompiler : public IRCompileLayer::IRCompiler {
 public:
   TPDECompiler(JITTargetMachineBuilder JTMB)
-      : IRCompiler(irManglingOptionsFromTargetOptions(JTMB.getOptions())) {
+      : IRCompiler(irManglingOptionsFromTargetOptions(JTMB.getOptions())),
+        JTMB(std::move(JTMB)) {
     Compiler = tpde_llvm::LLVMCompiler::create(JTMB.getTargetTriple());
     assert(Compiler != nullptr && "Unknown architecture");
   }
@@ -37,9 +38,9 @@ Expected<std::unique_ptr<MemoryBuffer>> TPDECompiler::operator()(Module &M) {
   std::vector<uint8_t> &B = *Buffers.back();
 
   if (!Compiler->compile_to_elf(M, B)) {
-    std::string Msg;
-    raw_string_ostream(Msg) << "TPDE failed to compile: " << M.getName();
-    return createStringError(std::move(Msg), inconvertibleErrorCode());
+    errs() << "Falling back to LLVM for module: " << M.getName() << "\n";
+    auto TM = ExitOnErr(JTMB.createTargetMachine());
+    return SimpleCompiler(*TM)(M);
   }
 
   StringRef BufferRef{reinterpret_cast<char *>(B.data()), B.size()};
@@ -50,6 +51,7 @@ public:
 private:
   std::unique_ptr<tpde_llvm::LLVMCompiler> Compiler;
   std::vector<std::unique_ptr<std::vector<uint8_t>>> Buffers;
+  JITTargetMachineBuilder JTMB;
 };
 
 int main(int argc, char *argv[]) {

Let’s test our fallback mechanism with the following IR file that uses an unsupported type:

@const_val = global bfloat 0xR4248

define i32 @main() {
entry:
  %c = load bfloat, ptr @const_val
  %i = fptosi bfloat %c to i32
  ret i32 %i
}

Here’s what happens when we run it:

> ./tpde-orc 02-bfloat.ll
Loaded module: 02-bfloat.ll
[2025-09-25 12:54:03.076] [error] unsupported type: bfloat
[2025-09-25 12:54:03.076] [error] Failed to compile function main
Falling back to LLVM for module: 02-bfloat.ll
Executing main()
Program returned: 50

In this implementation, we create a new SimpleCompiler instance for each fallback case. While this adds some overhead, it’s acceptable since we’re already on the slow path. The key assumption is that most code in your workload will successfully compile with TPDE — if that’s not the case, then TPDE might not be the right choice in the first place. Interestingly, this approach has a valuable side-effect that becomes important in the next section: it’s inherently thread-safe!

Adding Concurrent Compilation Support

ORC JIT has built-in support for concurrent compilation. This is neat, but it requires attention when customizing the JIT. Our current setup uses a single TPDECompiler instance, but TPDE’s compile_to_elf() method isn’t thread-safe. Enabling concurrent compilation would cause multiple threads to call this method simultaneously, leading to failures.

How can we solve this? One option would be creating a new tpde_llvm::LLVMCompiler instance for each compilation job, but that adds an overhead of O(#jobs) — not ideal for our fast path. Essentially, we want to avoid calling into compile_to_elf() while there is another call in-flight on the same thread. We can achieve this easily by making the TPDECompiler instance thread-local, reducing the overhead to just O(#threads):

@@ -32,7 +32,6 @@ public:
   TPDECompiler(JITTargetMachineBuilder JTMB)
       : IRCompiler(irManglingOptionsFromTargetOptions(JTMB.getOptions())),
         JTMB(std::move(JTMB)) {
-    Compiler = tpde_llvm::LLVMCompiler::create(JTMB.getTargetTriple());
     assert(Compiler != nullptr && "Unknown architecture");
   }
 
@@ -50,11 +49,14 @@ public:
   }
 
 private:
-  std::unique_ptr<tpde_llvm::LLVMCompiler> Compiler;
+  static thread_local std::unique_ptr<tpde_llvm::LLVMCompiler> Compiler;
   std::vector<std::unique_ptr<std::vector<uint8_t>>> Buffers;
   JITTargetMachineBuilder JTMB;
 };
 
+thread_local std::unique_ptr<tpde_llvm::LLVMCompiler> TPDECompiler::Compiler =
+    tpde_llvm::LLVMCompiler::create(Triple(LLVM_HOST_TRIPLE));
+
 int main(int argc, char *argv[]) {
   InitLLVM X(argc, argv);
   cl::ParseCommandLineOptions(argc, argv, "TPDE ORC JIT Compiler\n");

We also need to guard access to our underlying buffers:

@@ -35,15 +35,19 @@ public:
   }
 
   Expected<std::unique_ptr<MemoryBuffer>> operator()(Module &M) override {
-    Buffers.push_back(std::make_unique<std::vector<uint8_t>>());
-    std::vector<uint8_t> *B = *Buffers.back().get();
+    std::vector<uint8_t> *B;
+    {
+      std::lock_guard<std::mutex> Lock(BuffersAccess);
+      Buffers.push_back(std::make_unique<std::vector<uint8_t>>());
+      B = Buffers.back().get();
+    }
 
     if (!Compiler->compile_to_elf(M, *B)) {
       errs() << "Falling back to LLVM for module: " << M.getName() << "\n";
@@ -50,6 +54,7 @@ public:
 private:
   static thread_local std::unique_ptr<tpde_llvm::LLVMCompiler> Compiler;
   std::vector<std::unique_ptr<std::vector<uint8_t>>> Buffers;
+  std::mutex BuffersAccess;
   JITTargetMachineBuilder JTMB;
 };

With thread safety handled, we can now enable concurrent compilation:

@@ -27,6 +27,10 @@ static cl::opt<std::string> EntryPoint("entrypoint",
                                       cl::desc("Entry point function name"),
                                       cl::init("main"));

+static cl::opt<unsigned>
+    Threads("par", cl::desc("Compile csmith code on N threads concurrently"),
+            cl::init(0));
+
class TPDECompiler : public IRCompileLayer::IRCompiler {
public:
@@ -65,6 +65,8 @@ int main(int argc, char *argv[]) {
       -> Expected<std::unique_ptr<IRCompileLayer::IRCompiler>> {
     return std::make_unique<TPDECompiler>(JTMB);
   };
+  Builder.SupportConcurrentCompilation = true;
+  Builder.NumCompileThreads = Threads;
   std::unique_ptr<LLJIT> JIT = ExitOnErr(Builder.create());
 
   ThreadSafeModule TSM(std::move(Mod), std::move(Context));

Exercising Concurrent Lookup

It needs a lot more support code to actually exercise concurrent compilation and do basic performance measurements. The complete sample project on GitHub has one possible implementation: after loading the input module, it creates 100 duplicates of it with different entry-point names and issues a single JIT lookup for all the entry-points at once. Here’s a simplified version of how this works:

SymbolMap SymMap;
SymbolLookupSet EntryPoints = addDuplicates(JIT, Mod);

outs() << "Compiling " << EntryPoints.size() << " modules on " << Threads
        << " threads in parallel\n";

using namespace std::chrono;
auto ES = JIT->getExecutionSession();
auto SO = makeJITDylibSearchOrder({JIT->getMainJITDylib()});
auto Start = steady_clock::now();
{
  // Lookup all entry-points at once to execise concurrent compilation
  SymMap = ExitOnErr(ES.lookup(SO, EntryPoints));
}
auto End = steady_clock::now();
auto Elapsed = duration_cast<milliseconds>(End - Start);

outs() << "Compile-time was: " << Elapsed.count() << " ms\n";

Compile-times for our csmith example drop from ~2200ms to just ~740ms when utilizing 8 threads in parallel:

> ./tpde-orc --par 8 tpde-orc/03-csmith-tpde.ll
Load module: tpde-orc/03-csmith-tpde.ll
Compiling 100 modules on 8 threads in parallel
...
Compile-time was: 737 ms

Et voilà!

Let’s wrap it up and appreciate the remarkable complexity that LLVM effortlessly handles in our little example. We parse a well-defined, human-readable representation of Turing-complete programs generated from various general-purpose languages like C++, Fortran, Rust, Swift, Julia, and Zig.

LLVM’s composable JIT engine seamlessly manages these parsed modules, automatically resolving symbols and dependencies. It compiles machine code in the native object format on-demand for multiple platforms and CPU architectures, while giving us complete control over the optimization pipeline, code generator (like our TPDE integration) and many more components. The engine then links everything into an executable form — all in-memory and without external tools or platform-specific dynamic library tricks! It’s really impressive that we can simply enable compilation on N threads in parallel and have it “just work” :-)

Follow-up: After revisiting the single-threaded compile-times, the multi-threading result is rather disappointing. Digging deeper, there seem to be two important reasons why this is so slow:

If we enable concurrent compilation, LLJIT activates a mechanism that makes sure the workload can actually be processed in parallel. This requires modules to live in distinct LLVM contexts and LLJIT clones all modules before dispatch. This is very expensive and actually dominates compile-times. The mechanism wouldn’t be necessary in our case here. As long as we keep using LLJITBuilder though, we cannot disable it, because the API gives no access to LLJIT’s InitHelperTransformLayer, which is responsible for the cloning.
The DynamicThreadPoolTaskDispatcher has a catch: It only pools compile jobs, but keeps spawning new threads for everything else, which is the majority of Tasks it dispatches in our examples. Respectively, O(#threads) is larger than O(#jobs) so that the thread-local compiler setup even slows down our multi-threading case! That’s a pity and it caused issues in real-world projects already. Right now, implementing a custom task dispatcher downstream seems to be the best solution. This is how JuliaLang fixed it: julia#58950. Lang Hames, the author of ORC, wants to address this issue in his upcoming presentation at the US LLVM Developers’ Meeting in October.
Last but not least, my post inspired Alexis Engelke, one of the TPDE authors, to sketch on a TPDE layer for ORC upstream. This is a pretty good idea indeed!

Native binary obfuscation in clang-repl

Thu, 29 Aug 2024 10:00:00 +0000

[TL;DR] Check the PoC and skip to conclusions

Background

Obfuscation is a technique for making code more difficult to understand. It has its origins in source-distributed languages like JavaScript and evolved in close relation to minification since the 2000s.

More recently, mature tools for decompilation and binary analysis have become widely available. 2019 marked a turning point when NSA open-sourced Ghidra. Combined with automation toolkits like Joern, vulnerability analysis for binary-distributed software (and even device firmware) has made great strides. As a consequence, anti-tampering solutions for native toolchains are gaining traction. Obfuscation plays an important role, because it raises the bar for attackers, e.g. to identify sensitive parts in the code through pattern matching.

Obfuscation can be implemented as a post-link step: Lift binary code to an intermediate-representation (like LLVM IR), transform it and lower the result back to binary. Trail of Bits’ McSema and Remill are well-known binary lifters. Meta’s BOLT uses the same approach for post-link optimizations. It doesn’t have to be like that though.

Obfuscation as compiler pass

Compilers run a lot of transformations when they translate source code to binary. We call them passes. There are analysis passes (e.g. reaching definitions, alias, branch probabilities), optimization passes (inlining, loop unrolling), elimination passes (dead-code, loops), allocation passes (registers, stack slots), instruction selection passes (isel, inst-combine) and many more. In clang we can dump them with the -fdebug-pass-structure option – give it a try and if you feel lucky, check -O3!

➜ clang -c hello.c -o /dev/null -O2 -fdebug-pass-structure

The New Pass Manager in LLVM provides a comfortable way for compilers to inject additional passes into the codegen pipeline. We call them out-of-tree passes, because they are not part of the original distribution (unlike in-tree passes that are built-in). Clang provides the command-line option -fpass-plugin and expects a shared library that registers new passes in the transformation pipeline (API docs, LLVM example plugin).

obfuscator.re / O-MVLL

O-MVLL uses pass injection to implement obfuscation at compile-time. It was built by Romain Thomas and got open-sourced in 2022 as a framework to develop, tune and show-case obfuscation techniques. The project is maintained by Build38 and I helped building some infrastructure for it in 2023.

O-MVLL provides a Python configuration API that allows users to select and paramterize transformations for specific use-cases. I added a new API callback recently, that exposes actual IR-level changes to Python. The following script enables the Arithmetic Obfuscation pass and dumps a diff for each applied transformation:

import omvll
from functools import lru_cache
from difflib import unified_diff

class MyConfig(omvll.ObfuscationConfig):
    def __init__(self):
        super().__init__()
    def obfuscate_arithmetic(self, mod, func):
        return omvll.ArithmeticOpt(rounds=2)
    def report_diff(self, pass_name: str, original: str, obfuscated: str):
        print(pass_name, "applied obfuscation:")
        green = '\x1b[38;5;16;48;5;2m'
        red = '\x1b[38;5;16;48;5;1m'
        end = '\x1b[0m'
        diff = unified_diff(original.splitlines(), obfuscated.splitlines(),
                            'original', 'obfuscated', lineterm='')
        for line in diff:
            m = line[0:1]
            if m == "+":
                print(green + line + end)
            elif m == "-":
                print(red + line + end)
            else:
                print(line)

@lru_cache(maxsize=1)
def omvll_get_config() -> omvll.ObfuscationConfig:
    return MyConfig()

Let’s consider a minimal C++ example with an XOR operation in the printf parameter:

#include <cstdio>
int main(int argc, char *argv[]) {
  printf("%d\n", argc ^ 123);
  return 0;
}

We can easily see how the obfuscator outlines the operation and replaces it with an equivalent, more complex expression:

➜ clang++ -O1 -fpass-plugin=/path/to/libOMVLL.so -o xor-example -c xor-example.cpp
omvll::Arithmetic applied obfuscation:
--- original
+++ obfuscated
@@ -9,16 +9,45 @@
 ; Function Attrs: mustprogress norecurse uwtable
 define dso_local noundef i32 @main(i32 noundef %argc, ptr noundef %argv) #0 {
 entry:
-  %xor = xor i32 %argc, 123
-  %call = call i32 (ptr, ...) @printf(ptr noundef @.str, i32 noundef %xor)
+  %0 = call i32 @__omvll_mba(i32 %argc, i32 123)
+  %call = call i32 (ptr, ...) @printf(ptr noundef @.str, i32 noundef %0)
   ret i32 0
 }
 
 ; Function Attrs: nofree nounwind
 declare noundef i32 @printf(ptr nocapture noundef readonly, ...) #1
 
+; Function Attrs: alwaysinline optnone
+define private i32 @__omvll_mba(i32 %0, i32 %1) #2 {
+entry:
+  %2 = add i32 %0, %1
+  %3 = add i32 %2, 1
+  %4 = xor i32 %0, -1
+  %5 = xor i32 %1, -1
+  %6 = or i32 %4, %5
+  %7 = add i32 %3, %6
+  %8 = or i32 %0, %1
+  %9 = add i32 %0, %1
+  %10 = or i32 %0, %1
+  %11 = sub i32 %9, %10
+  %12 = and i32 %0, %1
+  %13 = sub i32 0, %11
+  %14 = xor i32 %7, %13
+  %15 = sub i32 0, %11
+  %16 = and i32 %7, %15
+  %17 = mul i32 2, %16
+  %18 = add i32 %14, %17
+  %19 = sub i32 %7, %11
+  %20 = or i32 %0, %1
+  %21 = and i32 %0, %1
+  %22 = sub i32 %20, %21
+  %23 = xor i32 %0, %1
+  ret i32 %18
+}
+
 attributes #0 = { mustprogress norecurse uwtable "min-legal-vector-width"="0" "no-trapping-math"="true" "stack-protector-buffer-size"="8" "target-cpu"="x86-64" "target-features"="+cmov,+cx8,+fxsr,+mmx,+sse,+sse2,+x87" "tune-cpu"="generic" }
 attributes #1 = { nofree nounwind "no-trapping-math"="true" "stack-protector-buffer-size"="8" "target-cpu"="x86-64" "target-features"="+cmov,+cx8,+fxsr,+mmx,+sse,+sse2,+x87" "tune-cpu"="generic" }
+attributes #2 = { alwaysinline optnone }
 
 !llvm.module.flags = !{!0, !1, !2, !3}
 !llvm.ident = !{!4}

The new code doesn’t contain the one single XOR operation anymore. Potential attackers need to invest more effort to uncover it. In this simple case, we can get the same insight like this:

➜ clang++ -O1 -S -emit-llvm xor-example.cpp -o original.ll
➜ clang++ -O1 -S -emit-llvm xor-example.cpp -o obfuscated.ll -fpass-plugin=/path/to/libOMVLL.so
➜ diff -u original.ll obfuscated.ll

But the the script-based approach has a few advantages already:

If multiple obfuscations are applied, we can see each individual step and not only the sum of all transformations.
We can enable/disable/fine-tune subsequent obfuscations based on actual transformations.

Interactive C++ with obfuscations

The outstanding benefit of the script-based approach is the ability to use it in tools that don’t write their outputs to files on disk! In particular, this is interesting for clang-repl, the interactive C++ interpreter in upstream LLVM. It uses the clang frontend internally and supports the same options (with a -Xcc prefix), including -fpass-plugin:

➜ clang-repl -Xcc -O1 -Xcc -fpass-plugin=/path/to/libOMVLL.so
clang-repl> #include <cstdio>
clang-repl> int a = 1;
clang-repl> printf("%d\n", a^123);
omvll::Arithmetic applied obfuscation:
--- original
+++ obfuscated
@@ -11,8 +11,8 @@
 define internal void @__stmts__0() #0 {
 entry:
   %0 = load i32, ptr @a, align 4, !tbaa !5
-  %xor = xor i32 %0, 123
-  %call = call i32 (ptr, ...) @printf(ptr noundef @.str, i32 noundef %xor)
+  %1 = call i32 @__omvll_mba(i32 %0, i32 123)
+  %call = call i32 (ptr, ...) @printf(ptr noundef @.str, i32 noundef %1)
   ret void
 }
 
@@ -26,9 +26,38 @@
   ret void
 }
 
+; Function Attrs: alwaysinline optnone
+define private i32 @__omvll_mba(i32 %0, i32 %1) #3 {
+entry:
+  %2 = add i32 %0, %1
+  %3 = add i32 %2, 1
+  %4 = xor i32 %0, -1
+  %5 = xor i32 %1, -1
+  %6 = or i32 %4, %5
+  %7 = add i32 %3, %6
+  %8 = or i32 %0, %1
+  %9 = add i32 %0, %1
+  %10 = or i32 %0, %1
+  %11 = sub i32 %9, %10
+  %12 = and i32 %0, %1
+  %13 = sub i32 0, %11
+  %14 = xor i32 %7, %13
+  %15 = sub i32 0, %11
+  %16 = and i32 %7, %15
+  %17 = mul i32 2, %16
+  %18 = add i32 %14, %17
+  %19 = sub i32 %7, %11
+  %20 = or i32 %0, %1
+  %21 = and i32 %0, %1
+  %22 = sub i32 %20, %21
+  %23 = xor i32 %0, %1
+  ret i32 %18
+}
+
 attributes #0 = { "min-legal-vector-width"="0" }
 attributes #1 = { nofree nounwind "no-trapping-math"="true" "stack-protector-buffer-size"="8" "target-cpu"="x86-64" "target-features"="+cmov,+cx8,+fxsr,+mmx,+sse,+sse2,+x87" "tune-cpu"="generic" }
 attributes #2 = { uwtable "min-legal-vector-width"="0" "no-trapping-math"="true" "stack-protector-buffer-size"="8" "target-cpu"="x86-64" "target-features"="+cmov,+cx8,+fxsr,+mmx,+sse,+sse2,+x87" "tune-cpu"="generic" }
+attributes #3 = { alwaysinline optnone }
 
 !llvm.module.flags = !{!0, !1, !2, !3}
 !llvm.ident = !{!4}

122
clang-repl>

Limitations in the PoC

Pass implementations in OMVLL use LLVM’s bare C++ interfaces, so that the version it links must match the one in the target compiler exactly. O-MVLL was built for LLVM 14 and just recently moved on to LLVM 16. clang-repl is still under development and works best with very recent versions of LLVM.

For the proof-of-concept in this post, I had to do a partial upgrade of O-MVLL to LLVM 18. It’s just enough to run the demo, so please don’t expect other obfuscation passes to work yet.

Conclusions and future work

In the race between protection techniques and reverse engineering, the accessibility of tools for exploration plays a crucial role. This PoC might inspire some form of obfuscation workbench. My Docker image is probably not the ideal distribution method. (It was the fastest for sure!) Jupyter notebooks provide a much better user experience and they are very popular in scientific communities. xeus-clang-repl is a Jupyter implementation for C++ with Python interop and might serve as a basis.

O-MVLL provides a nice framework for exploring obfuscation techniques. The extensible Python API is flexible and powerful. However, I imagine that tinkering with O-MVLL is still difficult for security experts. We have to implement obfuscations in C++ and build the plugin from source. The plugin shared library and the target compiler must be ABI-compatible. This is very easy to break and quite complicated to debug. The version locking is likely to remain an issue for the foreseeable future. We can use the prebuilt deps packages from the upstream CI, but this limits us to the target compilers supported on current mainline (Android NDK r26d and Xcode 15.2 at the time of writing this post).

Another way to solve the build problem seems interesting: Why not extend the script API in a way that allows implementing entire obfuscations in Python? For performance reasons, it’s certainly not suitable for use in production, but for experimentation that seems acceptable. It could reuse existing bindings like Numba’s llvmlite. Key requirements are indeed similar: “Numba and many JIT compilers do not need a full LLVM API. Only the IR builder, optimizer, and JIT compiler APIs are necessary. The IR builder is pure Python code and decoupled from LLVM’s frequently-changing C++ APIs.”

Thanks for reading! Please ping me, if any of this triggers your interest!

LLVM Projects in 2023 Google Summer of Code

Mon, 20 Mar 2023 08:00:00 +0000

The LLVM Compiler Infrastructure as been accepted again as a mentoring organisation for Google Summer of Code 2023 (GSoC). This is a great opportunity for students and other eligible people to gain substantial development experience with LLVM in a short period of time!

The application period for contributors is starting today and ends on 4 April 2023. Please find the full list of projects on llvm.org. In the following I want to provide more details on the projects I am mentoring and highlight a few others that caught my interest.

Out-of-process execution for clang-repl

clang-repl is an interactive C++ command line (REPL). It’s based on Clang and the ORC/JITLink infrastructure and it aims to implement to core functionality of CERN’s Cling in upstream LLVM.

Right now clang-repl can execute user code only its own process. This has a number of drawbacks and limits its applications. It’s the goal of this GSoC project to implement an out-of-process execution model in clang-repl. LLVM’s underlying ORC and JITLink libraries provide most of the basic functionality already. Now, we need to teach clang-repl to generate code that makes use of it and extend RPC features where necessary.

Applicants need a good understanding of C++ and basic assembly debugging skills. Experience with RPC and generation of LLVM IR code is a plus, but not strictly required.

Get in touch with us in the Discourse topic or in the #jit channel of the LLVM Discord server.

JITLink new backends

LLVM’s JITLink library links and loads static build artifacts for immediate execution. We can use clang to compile source code into an object file and execute it right away with the llvm-jitlink tool.

JITLink runs generic link steps and uses dedicated backends for target- and object-format-specific operations. This includes resolution of relocations, registration of exception handlers and preparation of thread-local storage. There is good support for a number of formats and platforms already, but we aren’t done yet. The goal of this GSoC project is to complete one of the existing implementations or add an entirely new one. In particular, we are thinking about AArch32 (skeleton is in review), BPF and PowerPC (both new).

Applicants need intermediate knowledge of both, C++ and target assembly. They will go through the target ABI documentation (like this for AArch32) and implement missing relocation types in their JITLink backend, populate GOT and PLT and add ORC Runtime support for advanced features.

Get in touch with us in the Discourse topic or in the #jit channel of the LLVM Discord server.

Patch based test coverage for quick test feedback

Regression tests are a fundamental part of any serious software engineering, but test suites keep growing and we rarely invest time to sort them out:

Running all the tests gets increasingly time-consuming. It would be very useful if we could figure out what tests are actually affected by a given change in the code-base. In practice, this should be possible in many situations. The goal of this GSoC project is to extend LLVM’s llvm-lit test driver tool to record coverage information and feed them back in. (I guess in a first step limited to subsequent runs on the same system?) As mentioned by the mentor, applicants don’t need compiler experience, but knowledge in Python, data processing and diff processing. I assume experience with llvm-lit is a plus, but not strictly required.

Addressing Rust optimization failures

While the LLVM codegen backends and opimization pipelines aim to be language agnostic, they have been developed with a focus on C++ and it is not a surprise that they are not a perfect fit (yet) for IR code generated from other languages. Rust is a notable example here. The goal of this GSoC project is to find and mitigate missing optimization opportunities. Applicants will likely have a deep dive into the LLVM optimizer and learn a lot about the involved tooling. Prior knowlegde of C++, LLVM IR and Rust is required.

Improving compile times

One unfortunate drawback from the continuous growth of LLVM’s code-base is that compile-time is getting a few percent slower with every release. The goal of this GSoC project is to help mitigate that. Applicants will review profiling information to identify bottlenecks and try to improve the underlying code structures to reduce overhead. Prior knowledge of C++ and profiling tools will be necessary.

Remote C++ live coding on Raspberry Pi with ez-clang-linux

Mon, 06 Feb 2023 21:00:00 +0000

ez-clang is a C++ REPL for bare-metal embedded devices. Serial connections to such devices can be hairy. Hosted remote devices are usually much easier to handle and might help with experimentation and development. In release 0.0.6 ez-clang gained a reference implementation for Linux-based remotes, that can now be connected via the pycfg layer.

In Python it’s easy to set up a socket connection to another device via TCP. If we find a 32-bit ARM device that runs Linux, then we just have to port our remote endpoint there and connect it to the TCP socket. Well, no need to search for long, of course Raspberry Pi Models 2 and 3b are both a great fit. Model 2 features a Cortex-A7 (ARMv7a instruction set) and Model 3b a Cortex-A53 with ARMv8a. While ARMv8a is in-fact a 64-bit instruction set, it does provide user-space compatibility with ARMv7a. This is what we want for ez-clang! We install 32-bit Raspbian and are ready to go.

The screencast shows how to SSH into a Raspberry Pi Model 3b and configure it as a ez-clang remote. The relevant steps are:

Checkout the ez-clang-linux repository
Configure with CMake and build the ez-clang-linux-socket target with Ninja. You can keep the default system toolchain or use your own one. There are no special requirements here.
Use the ez-clang-linux-socket.service file produced by CMake to configure Systemd so that the executable is auto-restarted infinitely. This is great because we don’t need to implement session handling on our own. Each connection will automatically get its own process and on disconnect it simply shuts down.

On our host machine we can just start ez-clang now and connect to the respective IP and port. In my local network it looks like this when running with docker:

> docker run -it echtzeit/ez-clang:0.0.6 --connect=raspi32@192.168.1.105:10819
Welcome to ez-clang, your friendly remote C++ REPL. Type `.q` to exit.
Connected: TCP -> raspi32 (arm-none-eabi @ cortex-a53)
raspi32>.q
>

On the remote we can inspect the RPC traffic from this (minimal) session with journalctl:

> journalctl --user -u ez-clang-linux-socket.service --follow
systemd[629]: Started Permanent ez-clang-linux remote host service.
ez-clang-linux-socket[26884]: Listening on port 10819
ez-clang-linux-socket[26884]: Connected
ez-clang-linux-socket[26884]: Send ->
ez-clang-linux-socket[26884]:   6a 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
ez-clang-linux-socket[26884]: Send ->
ez-clang-linux-socket[26884]:   05 00 00 00 00 00 00 00 30 2e 30 2e 36 00 30 aa 00 00 00 00 00 00 80 00 00 00 00 00 00 01 00 00 00 00 00 00 00 15 00 00 00 00 00 00 00 5f 5f 65 7a 5f 63 6c 61 6e 67 5f 72 70 63 5f 6c 6f 6f 6b 75 70 74 26 01 00 00 00 00 00
ez-clang-linux-socket[26884]: Receive <-
ez-clang-linux-socket[26884]:   47 00 00 00 00 00 00 00 03 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00 74 26 01 00 00 00 00 00
ez-clang-linux-socket[26884]: Receive <-
ez-clang-linux-socket[26884]:   01 00 00 00 00 00 00 00 17 00 00 00 00 00 00 00 5f 5f 65 7a 5f 63 6c 61 6e 67 5f 72 65 70 6f 72 74 5f 76 61 6c 75 65
ez-clang-linux-socket[26884]: Send ->
ez-clang-linux-socket[26884]:   31 00 00 00 00 00 00 00 02 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
ez-clang-linux-socket[26884]: Send ->
ez-clang-linux-socket[26884]:   00 01 00 00 00 00 00 00 00 c0 2b 01 00 00 00 00 00
ez-clang-linux-socket[26884]: Receive <-
ez-clang-linux-socket[26884]:   20 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
ez-clang-linux-socket[26884]: Send ->
ez-clang-linux-socket[26884]:   21 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
ez-clang-linux-socket[26884]: Send ->
ez-clang-linux-socket[26884]:   00
ez-clang-linux-socket[26884]: Receive <-
ez-clang-linux-socket[26884]:   20 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
ez-clang-linux-socket[26884]: Exiting
systemd[629]: ez-clang-linux-socket.service: Succeeded.
systemd[629]: ez-clang-linux-socket.service: Scheduled restart job, restart counter is at 1.
systemd[629]: Stopped Permanent ez-clang-linux remote host service.
systemd[629]: Started Permanent ez-clang-linux remote host service.

Voilà!

With these few steps we can start and run C++ code on Raspberry Pi on the fly! While keeping in mind, of course, that the ez-clang project is still in a very experimental state ;-)

ez-clang Python Device Configuration Layer

Fri, 03 Feb 2023 22:00:00 +0000

ez-clang is a C++ REPL for bare-metal embedded devices. In release 0.0.6 it gained a Python Device Configuration Layer (pycfg) that allows users to connect their own devices.

Elements of a device script

As before we specify the target device in the --connect parameter, e.g.:

ez-clang --connect=teensylc@/dev/ttyACM0
ez-clang --connect=raspi32@192.168.0.100:20000
ez-clang --connect=lm3s811@qemu

The scan() function will parse this string and load the respective device script. The Script class implements the interface between ez-clang and Python. Compatible device scripts define the following freestanding functions.

accept() checks whether the provided info matches the device. The first candidate script that returns a non-Null value here will be choosen. The type of the info parameter depends on the selected transport type. For serial transport we get a serial.tools.list_ports_linux.SysFS object and will probably check the hwid field (example for TeensyLC).

def accept(info: Any) -> Any

connect() establishes the raw connection to the device and returns a serializer for it. The serializer has a standard implementation, that can typically be reused (example for TeensyLC).

def connect(info: Any, ez_clang_api.Host, ez_clang_api.Device) -> ez.repl.Serializer

setup() configures the ez_clang_api.Device and adds it to the ez_clang_api.Host. This is the core function for device configuration. We read the setup message from the device, initialize endpoints, set CPU, target triple and code buffer (memory range available for JITed code) as well as header search paths and compiler flags. Examples: TeensyLC, Arduino Due, Raspberry Pi (Socket), LM3S811 (QEMU).

def setup(stream: ez.repl.Serializer, ez_clang_api.Host, ez_clang_api.Device) -> bool

call() allows invoking the RPC function endpoint on the device with the parameters in data. As in the last release, built-in endpoints are lookup, commit, execute and memory.read.cstr (see binary interface docs).

def call(endpoint: str, data: dict) -> dict

disconnect() shuts down the session and closes the device connection.

def disconnect() -> bool

Host and Device interfaces

These interfaces describe specific properties for the host and the device respectively. They are both implemented in C++ inside ez-clang and not formally documented yet. For testing, however, we mock these types and the mocks can be used as an informal documentation for now.

Install

Clone the repository and install dependencies:

> git clone https://github.com/echtzeit-dev/ez-clang-pycfg
> python3 --version
Python 3.8.10
> cd ez-clang-pycfg
> python3 -m pip install -e .share
> python3 -m pip install -r requirements.txt

Testing

One major benefit of pycfg is that connectivity testing and debugging can be done in Python. This is a lot easier and quicker than C++ and it allows for better isolation. Each target device implementation comes with a test suite that covers all relevant connectivity features (example for Arduino Due).

The run_all.py script is for batch testing. It uploads a fresh firmware and runs all tests in sequence:

> python3 due/test/run_all.py
Found compatible device at /dev/ttyACM2
Device unique identifier: 7503130343135130F0A0
Uploading firmware: /usr/lib/ez-clang/0.0.6/firmware/due/firmware.bin
Running tests from /usr/lib/ez-clang/0.0.6/pycfg/due/test
Selecting 8 out of 9 discovered tests
  [basics] connect ........................................ 4.51s
  [basics] setup .......................................... 4.52s
  [basics] connect_setup_repeat ........................... 9.02s
  [endpoints] ez.rpc.lookup ............................... 9.07s
  [endpoints] ez.rpc.commit ............................... 5.46s
  [endpoints] ez.rpc.execute .............................. 5.02s
  [endpoints] memory.read.cstr ............................ 5.43s
  [recovery] replace_firmware ............................. 19.96s

Testing Time: 88.65s
  Disabled: 1
  Excluded: 0
  Failed  : 0
  Passed  : 8

SUCCESS

The individual tests are self-contained and can be executed as standalone Python scripts. The output shows the serialized RPC traffic:

> python3 due/test/00-basics/01-connect.py
Found compatible device at /dev/ttyACM2
Connect <-
  6a 00 00 00 00 00 00 00
  00 00 00 00 00 00 00 00
  00 00 00 00 00 00 00 00
  00 00 00 00 00 00 00 00
  05 00 00 00 00 00 00 00 30 2e 30 2e 35 50 1a 07 20 00 00 00 00
  b0 61 01 00 00 00 00 00 01 00 00 00 00 00 00 00 15 00 00 00 00
  00 00 00 5f 5f 65 7a 5f 63 6c 61 6e 67 5f 72 70 63 5f 6c 6f 6f
  6b 75 70 19 05 08 00 00 00 00 00
Disconnect ->
  20 00 00 00 00 00 00 00
  01 00 00 00 00 00 00 00
  01 00 00 00 00 00 00 00
  00 00 00 00 00 00 00 00
Disconnect <-
  21 00 00 00 00 00 00 00
  01 00 00 00 00 00 00 00
  00 00 00 00 00 00 00 00
  00 00 00 00 00 00 00 00
  00

Run in ez-clang

In order to use new or modified scripts with ez-clang, just mount the repo folder in docker with the -v parameter:

> docker run -it -v $(pwd)/ez-clang-pycfg:/lib/ez-clang/0.0.6/pycfg echtzeit/ez-clang:0.0.6 --connect=raspi32@192.168.1.105:10819

Debugging in ez-clang

We can also debug scripts when they run in ez-clang. For that we have debugpy hooks at the start of each device script:

if ez_clang_api.Host.debugPython(__debug__):
    import debugpy
    debugpy.listen(('0.0.0.0', 5678))
    ez.io.note("Python API waiting for debugger. Attach to 0.0.0.0:5678 to proceed.")
    debugpy.wait_for_client()
    debugpy.breakpoint()

They get enabled by passing the --rpc-debug-python flag to ez-clang. Additionally we have to forward the debug port from the docker container to the host with the -p parameter:

> docker run --rm -p 5678:5678 -it echtzeit/ez-clang:0.0.6 --connect=raspi32@192.168.1.105:10819 --rpc-debug-python
Welcome to ez-clang, your friendly remote C++ REPL. Type `.q` to exit.
Python API waiting for debugger. Attach to 0.0.0.0:5678 to proceed.

Now any appropriate debugger should be able to attach, e.g. vscode with a launch configuration like this:

{
  "name": "ez-clang-pycfg attach",
  "type": "python",
  "request": "attach",
  "connect": { "host": "localhost", "port": 5678 },
  "pathMappings": [{
    "localRoot": "${workspaceFolder}/ez-clang-pycfg",
    "remoteRoot": "/usr/lib/ez-clang/0.0.6/pycfg"
  }],
}

Voilà!

GDB JIT Interface 101

Sun, 27 Nov 2022 10:00:00 +0000

LLVM’s JIT libraries allow to link and load static build artifacts at runtime. We can play with object files in a JIT session without having to link them into a static executable. That’s great — as long as everything works as expected.

If something goes wrong, we face a little extra effort to inspect our code with a debugger. Mainstream debuggers scan executable and shared library files on disk to collect their symbols and debug info. And they know how to intercept shared library events like dlopen() and dlclose(). When we compile and link code in-memory, however, and load it on the fly, there is not much they can do. In order to debug such code we have to collaborate.

There is a surprising amount of things that can go wrong when debugging JITed code. This article explains debug info registration at runtime and tries to give assistance on what to check when things go south.

GDB JIT Interface

In 2009 GDB introduced an ingenious way for executables to register new code at runtime: JIT Compilation Interface docs. It’s kind of a loose standard with a single version so far. Other debuggers like LLDB picked it up later on. The interface relies on two symbols:

__jit_debug_descriptor has type jit_descriptor and implements a linked list of jit_code_entry items. Our program adds items here for any new code that the debugger should know about.
__jit_debug_register_code is an empty function that our program calls in order to signal the debugger to process new list items.

Debuggers that implement the interface apply special handling for those symbols. At launch they check for the __jit_debug_register_code symbol and set a breakpoint that triggers the JIT registration hook: When it hits, the debugger walks the list in __jit_debug_descriptor for new items, reads them from process memory and extracts debug info.

An application that uses the interface will add new items to the __jit_debug_descriptor list whenever it emits new code. Each such item refers to an in-memory object file. Once the list is up to date, the application calls its own __jit_debug_register_code knowing that a debugger might interrupt execution and process the debug sections of the in-memory objects.

There was an attempt to add a more advanced JIT interface in GDB that involves GDB-side plugins, but the approach didn’t gain enough momentum as it seems (given that even V8 still uses the original interface).

LLDB Support

In 2014 LLDB gained an initial implementation for the GDB JIT interface which was first released as part of LLDB 3.5. However, the feature silently broke during the 6.0 development cycle since we had no good test for it. I managed to fix it a little later with two patches: The original registration bug in 2019 and source-level debugging in 2020.

LLDB fully supports the GDB JIT interface for ELF object files again since release 12.

LLVM JIT support

At the time of writing, LLVM comes with two different JIT-linker implementations: RuntimeDyLD and JITLink. RuntimeDyLD was designed as a dynamic loader for LLVM’s monolithic MCJIT implementation. As it grew into a fully fledged cross-platform JIT-linker, it surpassed the limits of its architecture and became increasingly harder to maintain and extend (for different code models, EH registration, TLS support, etc.). With the rise of LLVM’s composable ORC JIT libraries, JITLink came up as a replacement for RuntimeDyLD and today it is set to become the default JIT-linker for most LLVM target platforms.

RuntimeDyLD provides a JITEventListener interface for clients to run actions when new code is loaded or unloaded. Debug object registration is implemented in the GDBRegistrationListener. JITLink provides a much more comprehensive plugin interface, which allows to hook into the linking process at various stages. In early 2021, I implemented a simple DebugObjectManagerPlugin for JITLink that works for ELF objects in both cases, in-process and out-of-process JITing. Later that year the GDBJITDebugInfoRegistrationPlugin for MachO support landed upstream.

In-memory object files

The LLVM JIT libraries work with position-independent code. In principle, relocations for in-memory objects can be resolved on either side, the JIT or the debugger. It appears reasonable, however, to leave it to the debugger, because debug sections contain loads of relocations and the debugger can defer the task until it eventually needs to access the data. In order to resolve relocations, the debugger must know the load address in target memory for each allocated section. For that purpose the DebugObjectManagerPlugin collects section load addresses at link-time and writes them to the sh_addr field in the respective section headers (and leaves the object untouched otherwise).

Troubleshooting

There is a surprising amount of things that can go wrong when debugging JITed code. In order to check what we can do in such cases, we will use a minimal test executable to compare results against:

#include "stdint.h"

struct jit_descriptor {
  uint32_t version;
  uint32_t action_flag;
  void *relevant_entry;
  void *first_entry;
};

// External global symbol for debuggers to obtain debug info at runtime.
struct jit_descriptor __jit_debug_descriptor = {1, 0, nullptr, nullptr};

// Debuggers put a special breakpoint in this function. The noinline and the asm
// prevent calls to this function from being optimized out.
__attribute__((noinline)) void __jit_debug_register_code() {
  asm volatile("" ::: "memory");
}

int main() {
  __jit_debug_register_code(); // Trap into the debugger's JIT registration
  return 0;
}

1. Are we running LLDB version 12+?

Check the version and upgrade to a more recent one if necessary:

> lldb --version
lldb version 15.0.2
> lldb
(lldb) version
lldb version 15.0.2

2. Does our platform disable the JIT debug hook by default?

Apple platforms prefer to disable the JIT debug hook in LLDB by default, while everyone else wants to have it default enabled. As a compromise the setting is now platform-dependent and reading it doesn’t tell us anything:

(lldb) settings show plugin.jit-loader.gdb.enable
plugin.jit-loader.gdb.enable (enum) = default

In case of uncertainty turn it on explicitly:

(lldb) settings set plugin.jit-loader.gdb.enable on
(lldb) settings show plugin.jit-loader.gdb.enable
plugin.jit-loader.gdb.enable (enum) = on

3. Print logs from the JIT category to see what’s going on

Dump status info for important steps. For our demo executable, the output should look like this:

(lldb) b main
(lldb) log enable lldb jit
(lldb) r
lldb-15          JITLoaderGDB::SetJITBreakpoint looking for JIT register hook
lldb-15          JITLoaderGDB::SetJITBreakpoint looking for JIT register hook
lldb-15          JITLoaderGDB::SetJITBreakpoint looking for JIT register hook
lldb-15          JITLoaderGDB::SetJITBreakpoint setting JIT breakpoint
Process 2363705 launched: '/path/to/test' (x86_64)
Process 2363705 stopped
* thread #1, name = 'test', stop reason = breakpoint 1.1
    frame #0: 0x000055555555514f test`main at test.cpp:51:3
   48   } // extern "C"
   49
   50   int main() {
-> 51     __jit_debug_register_code();
   52     return 0;
   53   }
(lldb) n
intern-state     JITLoaderGDB::JITDebugBreakpointHit hit JIT breakpoint
Process 2363705 stopped
* thread #1, name = 'test', stop reason = step over
    frame #0: 0x0000555555555154 test`main at test.cpp:52:3
   49
   50   int main() {
   51     __jit_debug_register_code();
-> 52     return 0;
   53   }
(lldb) c
Process 2363705 resuming
Process 2363705 exited with status = 0 (0x00000000)

4. Can LLDB see our JIT interface symbols?

For our demo executable, the symbols are in the symbol table of the binary:

> nm test | grep __jit_debug_
0000000000004028 D __jit_debug_descriptor
0000000000001130 T __jit_debug_register_code

In LLDB we can look it up right away:

(lldb) target create "test"
Current executable set to '/path/to/test' (x86_64).
(lldb) image lookup -s __jit_debug_descriptor
1 symbols match '__jit_debug_descriptor' in /path/to/test:
        Address: test[0x0000000000004028] (test.PT_LOAD[3]..data + 16)
        Summary: __jit_debug_descriptor
(lldb) image lookup -s __jit_debug_register_code
1 symbols match '__jit_debug_register_code' in /path/to/test:
        Address: test[0x0000000000001130] (test.PT_LOAD[1]..text + 240)
        Summary: test`::__jit_debug_register_code() at test.cpp:40

It’s not always as easy though! Looking at lli from the official LLVM 15 release, the symbols are in the LLVM shared library that lli links against! This is why we won’t find them in LLDB before the executable launched and actually resolved its load-time libraries:

> lldb-15 -- lli-15
(lldb) target create "lli-15"
Current executable set to '/usr/bin/lli-15' (x86_64).
(lldb) image lookup -s __jit_debug_descriptor
(lldb) image lookup -s __jit_debug_register_code
(lldb) b main
Breakpoint 1: where = lli-15`main, address = 0x00000000000169c0
(lldb) r
Process 2364389 launched: '/usr/bin/lli-15' (x86_64)
Process 2364389 stopped
* thread #1, name = 'lli-15', stop reason = breakpoint 1.1
    frame #0: 0x000055555556a9c0 lli-15`main
lli-15`main:
->  0x55555556a9c0 <+0>: push   rbp
    0x55555556a9c1 <+1>: push   r15
    0x55555556a9c3 <+3>: push   r14
    0x55555556a9c5 <+5>: push   r13
(lldb) image lookup -s __jit_debug_descriptor
1 symbols match '__jit_debug_descriptor' in /usr/lib/llvm-15/lib/libLLVM-15.so.1:
        Address: libLLVM-15.so.1[0x0000000006f0e1f8] (libLLVM-15.so.1.PT_LOAD[1]..data + 255592)
        Summary: __jit_debug_descriptor
(lldb) image lookup -s __jit_debug_register_code
1 symbols match '__jit_debug_register_code' in /usr/lib/llvm-15/lib/libLLVM-15.so.1:
        Address: libLLVM-15.so.1[0x0000000002a54420] (libLLVM-15.so.1.PT_LOAD[0]..text + 30459296)
        Summary: libLLVM-15.so.1`__jit_debug_register_code

Moreover shared libraries contain “undefined” U records for external symbols and this triggered a bug in LLDB’s JITLoaderGDB. If we linked against such a shared library and LLDB encountered it before the one with the actual definition, LLDB failed to resolve __jit_debug_register_code. The issue should be fixed in the upcoming LLDB release 16. We can stop in main() and lookup the symbol manually to check for this case, e.g. in a BUILD_SHARED_LIBS build of mainline LLVM:

> lldb-15 -- /path/to/llvm-project/build/bin/lli
(lldb) b main
(lldb) run --version
(lldb) image lookup -s __jit_debug_register_code
1 symbols match '__jit_debug_register_code' in /path/to/llvm-project/build/lib/libLLVMExecutionEngine.so.16git:
        Name: __jit_debug_register_code
        Value: 0x0000000000000000

1 symbols match '__jit_debug_register_code' in /path/to/llvm-project/build/lib/libLLVMOrcTargetProcess.so.16git:
        Address: libLLVMOrcTargetProcess.so.16git[0x000000000000fa5a] (libLLVMOrcTargetProcess.so.16git.PT_LOAD[1]..text + 20058)
        Summary: libLLVMOrcTargetProcess.so.16git`__jit_debug_register_code

6. Does our JITed code contain debug info?

We can check for DI meta data in LLVM IR code and for debug sections in object files:

> clang -S -emit-llvm -g -o - test_foo.c | grep "\!DI" | wc -l
9
> clang -S -emit-llvm -o - test_foo.c | grep "\!DI" | wc -l
0
> clang -c -g -o - test_foo.c | llvm-objdump -h - | grep debug | wc -l
11
> clang -c -o - test_foo.c | llvm-objdump -h - | grep debug | wc -l
0

We can break on both, functions and source locations if we have debug info. Otherwise we can only break on functions and only get disassembly:

 1 location added to breakpoint 1
 Process 1625659 stopped
 * thread #1, name = 'lli', stop reason = breakpoint 1.1
-    frame #0: 0x00007ffff70d0004 JIT(0x56e4e0)`foo
-JIT(0x56e4e0)`foo:
-->  0x7ffff70d1000 <+0>: mov    eax, 0x2a
-    0x7ffff70d1005 <+5>: ret
-    0x7ffff70d1006:      add    byte ptr [rax], al
-    0x7ffff70d1008:      add    byte ptr [rax], al
+    frame #0: 0x00007ffff70d0004 JIT(0x56e4e0)`foo at test_foo.c:4:10
+   1    static int some_value = 42;
+   2
+   3    int foo() {
+-> 4      return some_value;
+   5    }

7. Does LLVM OrcJIT support debugging for your platform?

As of 2022 the DebugObjectManagerPlugin covers ELF on all matching platforms. (I never tested it outside of 64-bit x86 systems but it might actually work!) There are upstream tests in LLVM and LLDB and the plugin is wired up in both tools, lli and llvm-jitlink. There is an example for debugging out-of-process and a test for it upstream.

The GDBJITDebugInfoRegistrationPlugin implements debug support for MachO on Apple systems. Right now it doesn’t appear to get tested and it’s only wired up in llvm-jitlink.

EuroLLVM 2022 Trip Report

Sun, 15 May 2022 06:00:00 +0000

The EuroLLVM conference happened again in person last week in London. It’s been a blast and two very intense days for me. Even though preparations have been slightly last minute, it was totally worth all the effort. After a two years break it was great to see old and new colleagues again in person and at the same time meet so many new developers who joined the community in the meantime.

The collective expertise in the audience remains to be the outstanding quality of the LLVM conferences. Presentations, discussions and round tables are on a level of technical excellence unequaled by any other conference I’ve seen. All recordings from the conference are published on the LLVM Youtube channel. Here is a summary of my personal highlights from the conference.

Finding Missed Optimizations Through the Lens of Dead Code Elimination

Day 2 started with a keynote that made big waves. Theodoros Theodoridis from ETH Zürich presented a nouvelle approach to utilize dead code elimination as an indicator for misbehaviors in optimization passes: recording, slides, abstract. The tool augments source input with extra function calls and measures success by checking whether these calls are still present in compiled output. Comparing of results between different versions of Clang is a great way to find regressions. Furthermore, the approach is not concerned with details like intermediate representations and thus also allows to compare against other compilers like GCC.

That said, the potential for automation is amazing: A script can drive generation of input with Csmith, instrumentation, compilation and result comparison. Differences indicate misbehaviors and they get checked against a database of known and previously found issues, before the input is reduced with C-Reduce. Outputs are almost complete bug reports, all without human interference!

ez-clang C++ REPL for bare-metal embedded devices

Naturally, presenting my very own project was a highlight for me as well: recording, slides, abstract. And it’s been a first-timer in terms of setup. When doing a live demo with an early-stage experimental tool that closely interacts with external hardware, things can go wrong in any possible way.

So I had to prepare. I brought my development board, a camera, loads of cables and a backup for everything. When submitting the talk, I asked to get scheduled after a break so I had enough time to set up and double-check. There are still so many more details, the spotlights on stage, reflections in the glass on the table and the resolution of the projector that made it hard for the audience to see the LED blink. However, both presentation and demo worked out pretty well! Please find the recording here:

Round tables

Round tables are a great way to gather people for informal discussions on a defined topic. I scheduled two round tables beforehand, JIT and Embedded development with LLVM/Clang.

The JIT round table went as usual: A handful of attendees with very specific use-cases and almost no overlap. We talked about the state of ORC, JITLink, MCJIT and RuntimeDyLd. We shared tipps and best practices and discussed portation road-maps from MCJIT to ORCv1 and ORCv2. As always I pointed out the convenience of the #JIT channel on LLVM’s discord server for quick questions and discussions online.

The Embedded development with LLVM/Clang round table was a surprise for me. The embedded ecosystem is dominated by GCC and so there is usually not too much interest in LLVM anywhere online. On-site on the conference, however, I found myself with 30 people awaiting moderation. Targeted discussions are hard with a group of this size. After a small introduction and general topics, we collected common interests and split up into smaller groups: Clang multilib support, LLDB on embedded devices, size optimizations in Clang and the current state of standard library support. The last two even spawned their own follow-up round tables in the course of the conference.

I visited a few more round tables, like LLDB which was held by my former colleagues Jonas and Raffael. The dominating topic was debugging of optimized code. The Formal Verification round table discussed SMT solvers and on the Freestanding libc++ round table, we concluded to make one of the libc++ downstream adaptions public in order to identify their potential for upstreaming.

All in all the conference was a great experience. As always, the atmosphere is welcoming and attendees diverse. I am very much looking forward to EuroLLVM 2023 in Paris next year!

Porting Cling to LLVM 13 and ORCv2

Wed, 27 Oct 2021 11:30:00 +0000

Cling is a Clang-based C++ interpreter developed by CERN as part of the high-energy physics data analysis project ROOT. It built against LLVM 5 since 2015 and was ported to LLVM 9 last year. With this latest official version it still uses LLVM’s now deprecated ORCv1 JIT libraries. ORCv2 evolved in parallel to its predecessor since LLVM 7 and introduced a complete redesign of the JIT API. It’s one of the breaking changes in LLVM that cling hasn’t caught up with yet.

Updating an external dependency can be a major effort for any project. LLVM bears a high risk here, because the C++ APIs don’t offer any guarantees for stability across release versions. Furthermore, cling maintains it’s own set of downstream modifications on LLVM’s release/9.x branch. Here is an interactive visualization:

Strategy

Cling’s downstream patches for LLVM won’t apply anymore if the code was modified upstream. We will get merge conflicts when rebasing it. The majority of conflicts are plain mix-and-match exercises: Find the colliding commit(s) and adopt the change in the downstream patch. However, there will be non-obvious side effects from time to time. We’d be more confident in our conflict resolutions, if we could run a smoke test that exercised the modified code. Unfortunately, Cling won’t compile until we finished rebasing onto the new version and also fixed Cling’s usage of the new API!

Eventually, we want to bring Cling’s downstream patches to LLVM’s most recent release branch. But the distance from release 9 is huge. Upstream LLVM is subject to change, permanently. There’s 73k commits in between the two releases:

➜ git clone https://github.com/weliveindetail/llvm-project
➜ cd llvm-project
➜ git log --oneline $(git merge-base release/9.x release/13.x)..release/13.x | wc -l
73303

Trying to do this in a single step bears the risk of ending up with runtime failures, that will be hard to nail down to a specific patch. Instead, it’s common practice to go from one release version to the next. In each iteration we will follow a simple plan:

Rebase Cling’s downstream patches to the next release. Solve each conflict on a best effort basis and make sure the affected LLVM libraries compile.
Build Cling against the new LLVM libraries. Each compiler error indicates an API change. For now we fix one after the other in the Cling code. Maybe we have to add further downstream patches in LLVM as well.
Run a smoke test once Cling compiles and links. Each bug that didn’t exist in the previous version, was likely introduced by us. Fix it and amend the changes to the respective commit(s).
Sort out the Cling API fixes into meaningful commits and track them on a new branch. Don’t skip this! A clean history is key for future iterations.

Rebase to the next LLVM release version

In our first iteration we go from release/9.x to release/10.x:

➜ cd llvm-project
➜ git checkout cling-09
➜ git fetch origin release/9.x release/10.x
➜ git log --oneline release/9.x..HEAD
497d28c58a51 Allow interfaces to operate on in-memory buffers ...
...
5c50e7430981 Enable unicode output on terminals.
➜ git checkout -b cling-10
➜ git rebase release/10.x

This is mostly straightforward, here is the rebased set of commits. There is one additional patch that fixes the shared libraries build in upstream LLVM (libLLVMExtensions didn’t link against libLLVMSupport and thus missed definitions for LLVM_ENABLE_ABI_BREAKING_CHECKS). Quick hacks like this can be useful, because we can’t fix the world while rebasing. Make sure to mark commits as such!

Now that our downstream LLVM does compile, we can fix Cling’s usage of the API. This is a search-intensive task. An editor or IDE with reference search and efficient code navigation makes a big difference. I’ve been using vscode with the clangd plugin. It’s good for plain text and regex search. For search in CMake files I use my own version of ag (The Silver Searcher).

The number of changes is fairly small. It contains another hack which is useful to suppress all compiler warnings in Cling. Adopting API changes means that we compile and scan through the output over and over again. Any warning that pops up on the way will cause additional fuzz and slow down the process. We can deal with them later.

Once we tested the intermediate state and sorted out changes, we can start the next iteration.

Skipping release/12.x

Sometimes it’s worth skipping a release. In case of Cling LLVM 12 is a good candidate, because it had removed the ORCv1 JIT libraries (for good reasons) while the ORCv2 API was still quite unstable: The public ORCv2 API (left/top) saw 4.7K insertions/deletions during that time! For comparison, it had only 2K insertions/deletions in the LLVM 11 cycle (right/bottom).

There was a moderate risk, that reimplementing Cling’s IncrementalJIT for LLVM 12 would cause a large refactor in the next iteration. For me this justified a bigger rebase step from 11 directly to 13.

In the end, it didn’t matter much, because the basic ORCv2 replacement uses the API on a pretty high level. Looking back, an alternative strategy might have been better: Reimplement the IncrementalJIT based on LLVM 11 (where ORCv1 was still present) and then move on to the next versions as usual.

IncrementalJIT ORCv2 replacement

The rebase plan works very well until Cling’s downstream patches arrive on release/13.x. Step 2 of this last iteration is more difficult. In order to get Cling to build against the new LLVM libraries, we would need to reimplement the entire IncrementalJIT against the ORCv2 API.

This ORCv2 replacement is a big effort and we’re better off with a version that’s incomplete but executable. For that we first adopt all non-JIT API changes and comment out the old IncrementalJIT until Cling compiles and links again. Next we setup an ORCv2 replacement class with stub functions that fit the existing interface. Note that we have to keep including the old IncrementalJIT.h, because other components in Cling are using some of its type definitions.

From here on we can run Cling in a debugger again. We can put breakpoints in our stubs and run commands in Cling until they hit. This is a very convenient way to reimplement the existing semantics, because we can inspect the relevant states at runtime!

In the constructor we create a basic greedy llvm::orc::LLJIT instance. The addModule() function wraps an incoming llvm::Module in a llvm::orc::ThreadSafeModule and passes it on to the LLJIT. The existing interface is not prepared to propagate LLVM’s rich recoverable errors. If we get an error, we log it to stderr and stick to the existing interface semantics. The getSymbolAddress() function does a simple lookup in the JIT, while lookupSymbol() appears to be used only to inject symbols for existing function addresses (like __cxa_atexit and __dso_handle). It runs a lookup beforehand to make sure the symbol doesn’t exist and it records the injected symbols in a map.

Cling has its own little runtime library. It’s used when we assign existing values or print them out. In order to get it to work, we have to implement host process lookup. With that we can evaluate simple expressions already!

Basic transaction rollback

Cling’s .undo command rolls back the JITed program to the state of the previous expression. The implementation in cling::TransactionUnloader makes some assumptions about the way IncrementalJIT works. In particular, it expects to find the transaction’s llvm::Module in a map of “non-pending” modules. I guess this design has historic reasons: With ORCv1 modules could only be unloaded once the JIT pipeline had finished processing them. ORCv2 removed that restriction and allows any module to be unloaded, independent of its materialization state. Because fixing TransactionUnloader is not our goal, we hack the system and report any module as non-pending immediately.

Now we can add resource tracking to our LLJIT and implement removeModule() for basic code unloading. The patch adds a callback to our IRCompileLayer, which transfers back ownership of processed modules to IncrementalJIT, so we can hand it out to the caller of removeModule(). But there is a final hurdle: We must extract the llvm::Module from the received llvm::orc::ThreadSafeModule and LLVM’s upstream API doesn’t allow this (for good reasons). We’d like to keep it simple for now, so we add a new downstream patch that does it.

Voilà!

This way we got Cling to work with LLVM 13 and ORCv2. What is left are a few non-functional cleanup steps, like removing ORCv1 types from function signatures and removing the now unused ORCv1 IncrementalJIT. Here is the final set of changes in Cling and in Cling’s LLVM version.

The resulting Cling is a best-effort version. I didn’t go and investigate test-suite failures. It’s good enough to produce the initial screenshot on macOS, but it doesn’t support the full feature-set yet. For now I didn’t look at other platforms. Linux will be a low-hanging fruit, Windows is a different story. There was one API change where I didn’t find a solution quickly, so I left a note and skipped it. It causes a number of issues, like failing .undo commands in non-trivial cases. I am sure there are more problems that I didn’t spot, but from here on we can iterate.

Thanks for reading! Here is how to build our new version of Cling in debug mode:

➜ git clone https://github.com/weliveindetail/llvm-project
➜ git -C llvm-project checkout cling-13
➜ git clone https://github.com/weliveindetail/cling llvm-project/llvm/tools/cling
➜ git -C llvm-project/llvm/tools/cling checkout cling-13
➜ ln -s ../../clang llvm-project/llvm/tools/clang
➜ mkdir build
➜ cmake -S "llvm-project/llvm" -B "build" -GNinja -DBUILD_SHARED_LIBS=On -DLLVM_ENABLE_PROJECTS=clang -DLLVM_EXTERNAL_PROJECTS=cling -DLLVM_TARGETS_TO_BUILD="ARM;NVPTX;X86"
➜ ninja -C build cling
➜ build/bin/cling --version
1.0~dev
LLVM (http://llvm.org/):
  LLVM version 13.0.0
  DEBUG build with assertions.
  Default target: x86_64-apple-darwin20.6.0
  Host CPU: skylake

Stop warning markers from polluting vscode minimap

Wed, 20 Oct 2021 16:00:00 +0000

clangd and other plugins tremendously increase efficiency when working with C++ in Visual Studio Code (vscode), but more plugins means more warnings and not everything is configurable. The above screenshot shows how a load of clang-tidy warning highlights from clangd clashes with the highlights for our search results in the minimap. This is going to slow down search-intensive tasks.

Ideally we fixed the warnings altogether or we adjusted the project’s clang-tidy settings so they won’t show up anymore. However, we all know these situations where we don’t have the time right now to deal with such things. So what else can we do? Disable warnings in clangd? Unfortunately that doesn’t seem possible:

To the rescue, there is a way to change highlight colors globally in vscode! So we can make warnings transparent in the minimap and in the overview-ruler:

{
  "workbench.colorCustomizations": {
    "minimap.warningHighlight": "#00000000",
    "editorOverviewRuler.warningForeground": "#00000000",
  },
}

Voilà!

We still see the warning squiggles in the editor, but they don’t pollute the minimap anymore.

Diffing Clang AST dumps

Fri, 03 Sep 2021 16:00:00 +0000

Clang makes it easy to dump the AST, but searching for differences in two given AST dumps is a little tricky. A short Python script can fix most of it. Let’s have a look at an example.

Here is the AST for a function with a plain C++11 lambda:

➜ clang++ -fsyntax-only -fno-color-diagnostics -Xclang -ast-dump plain.cpp 1>plain.ast
➜ cat plain.ast
TranslationUnitDecl 0x7f8916040008 <<invalid sloc>> <invalid sloc>
`-FunctionDecl 0x7f891607bc28 <plain.cpp:1:1, line:4:1> line:1:5 main 'int (int, char **)'
  |-ParmVarDecl 0x7f891607b9c0 <col:10, col:14> col:14 used argc 'int'
  |-ParmVarDecl 0x7f891607bb08 <col:20, col:31> col:26 argv 'char **':'char **'
  `-CompoundStmt 0x7f89160a9ba8 <col:34, line:4:1>
    |-DeclStmt 0x7f89160a9a20 <line:2:3, col:46>
    | `-VarDecl 0x7f891607bd88 <col:3, col:45> col:8 used lambda '(lambda at plain.cpp:2:17)':'(lambda at plain.cpp:2:17)' cinit
    |   `-ExprWithCleanups 0x7f89160a9a08 <col:17, col:45> '(lambda at plain.cpp:2:17)':'(lambda at plain.cpp:2:17)'
    |     `-CXXConstructExpr 0x7f89160a99d8 <col:17, col:45> '(lambda at plain.cpp:2:17)':'(lambda at plain.cpp:2:17)' 'void ((lambda at plain.cpp:2:17) &&) noexcept' elidable
    |       `-MaterializeTemporaryExpr 0x7f89160a9970 <col:17, col:45> '(lambda at plain.cpp:2:17)' xvalue
    |         `-LambdaExpr 0x7f891607c4c8 <col:17, col:45> '(lambda at plain.cpp:2:17)'
    |           |-CXXRecordDecl 0x7f891607bed0 <col:17> col:17 implicit class definition
    |           | |-DefinitionData lambda pass_in_registers empty standard_layout trivially_copyable can_const_default_init
    |           | | |-DefaultConstructor defaulted_is_constexpr
    |           | | |-CopyConstructor simple trivial has_const_param implicit_has_const_param
    |           | | |-MoveConstructor exists simple trivial
    |           | | |-CopyAssignment trivial has_const_param needs_implicit implicit_has_const_param
    |           | | |-MoveAssignment
    |           | | `-Destructor simple irrelevant trivial
    |           | |-CXXMethodDecl 0x7f891607c018 <col:28, col:45> col:17 used operator() 'int (int) const' inline
    |           | | |-ParmVarDecl 0x7f891607be08 <col:20, col:24> col:24 used argc 'int'
    |           | | `-CompoundStmt 0x7f891607c118 <col:30, col:45>
    |           | |   `-ReturnStmt 0x7f891607c108 <col:32, col:39>
    |           | |     `-ImplicitCastExpr 0x7f891607c0f0 <col:39> 'int' <LValueToRValue>
    |           | |       `-DeclRefExpr 0x7f891607c0d0 <col:39> 'int' lvalue ParmVar 0x7f891607be08 'argc' 'int'
    |           | |-CXXConversionDecl 0x7f891607c358 <col:17, col:45> col:17 implicit operator int (*)(int) 'int (*() const noexcept)(int)' inline
    |           | |-CXXMethodDecl 0x7f891607c408 <col:17, col:45> col:17 implicit __invoke 'int (int)' static inline
    |           | | `-ParmVarDecl 0x7f891607c2f0 <col:20, col:24> col:24 argc 'int'
    |           | |-CXXDestructorDecl 0x7f891607c4f0 <col:17> col:17 implicit referenced ~ 'void () noexcept' inline default trivial
    |           | |-CXXConstructorDecl 0x7f89160a9600 <col:17> col:17 implicit constexpr  'void (const (lambda at plain.cpp:2:17) &)' inline default trivial noexcept-unevaluated 0x7f89160a9600
    |           | | `-ParmVarDecl 0x7f89160a9730 <col:17> col:17 'const (lambda at plain.cpp:2:17) &'
    |           | `-CXXConstructorDecl 0x7f89160a97d0 <col:17> col:17 implicit used constexpr  'void ((lambda at plain.cpp:2:17) &&) noexcept' inline default trivial
    |           |   |-ParmVarDecl 0x7f89160a9900 <col:17> col:17 '(lambda at plain.cpp:2:17) &&'
    |           |   `-CompoundStmt 0x7f89160a99c8 <col:17>
    |           `-CompoundStmt 0x7f891607c118 <col:30, col:45>
    |             `-ReturnStmt 0x7f891607c108 <col:32, col:39>
    |               `-ImplicitCastExpr 0x7f891607c0f0 <col:39> 'int' <LValueToRValue>
    |                 `-DeclRefExpr 0x7f891607c0d0 <col:39> 'int' lvalue ParmVar 0x7f891607be08 'argc' 'int'
    `-ReturnStmt 0x7f89160a9b98 <line:3:3, col:21>
      `-CXXOperatorCallExpr 0x7f89160a9b58 <col:10, col:21> 'int' '()'
        |-ImplicitCastExpr 0x7f89160a9ad8 <col:16, col:21> 'int (*)(int) const' <FunctionToPointerDecay>
        | `-DeclRefExpr 0x7f89160a9a78 <col:16, col:21> 'int (int) const' lvalue CXXMethod 0x7f891607c018 'operator()' 'int (int) const'
        |-ImplicitCastExpr 0x7f89160a9b28 <col:10> 'const (lambda at plain.cpp:2:17)' lvalue <NoOp>
        | `-DeclRefExpr 0x7f89160a9a38 <col:10> '(lambda at plain.cpp:2:17)':'(lambda at plain.cpp:2:17)' lvalue Var 0x7f891607bd88 'lambda' '(lambda at plain.cpp:2:17)':'(lambda at plain.cpp:2:17)'
        `-ImplicitCastExpr 0x7f89160a9b40 <col:17> 'int' <LValueToRValue>
          `-DeclRefExpr 0x7f89160a9a58 <col:17> 'int' lvalue ParmVar 0x7f891607b9c0 'argc' 'int'

And the corresponding source code:

int main(int argc, char *argv[]) {
  auto lambda = [](int argc) { return argc; };
  return lambda(argc);
}

Here is an equivalent implementation that uses a C++14 generic lambda instead:

int main(int argc, char *argv[]) {
  auto lambda = [](auto argc) { return argc; };
  return lambda(argc);
}

Now let’s try to fingure out what parts of the AST changed:

➜ clang++ -fsyntax-only -fno-color-diagnostics -Xclang -ast-dump -std=c++14 generic.cpp 1>generic.ast
➜ diff -u plain.ast generic.ast | wc -l
     101

Well, for now the diff doesn’t help much:

--- plain.ast	2021-09-03 11:50 +0200
+++ generic.ast	2021-09-03 11:50 +0200
@@ -1,46 +1,58 @@
-TranslationUnitDecl 0x7f9492040008 <<invalid sloc>> <invalid sloc>
-`-FunctionDecl 0x7f949207bc28 <plain.cpp:1:1, line:4:1> line:1:5 main 'int (int, char **)'
-  |-ParmVarDecl 0x7f949207b9c0 <col:10, col:14> col:14 used argc 'int'
-  |-ParmVarDecl 0x7f949207bb08 <col:20, col:31> col:26 argv 'char **':'char **'
-  `-CompoundStmt 0x7f94920a9d58 <col:34, line:4:1>
-    |-DeclStmt 0x7f94920a9b90 <line:2:3, col:46>
-    | `-VarDecl 0x7f949207bd88 <col:3, col:45> col:8 used lambda '(lambda at plain.cpp:2:17)':'(lambda at plain.cpp:2:17)' cinit
-    |   `-ExprWithCleanups 0x7f94920a9b78 <col:17, col:45> '(lambda at plain.cpp:2:17)':'(lambda at plain.cpp:2:17)'
-    |     `-CXXConstructExpr 0x7f94920a9b48 <col:17, col:45> '(lambda at plain.cpp:2:17)':'(lambda at plain.cpp:2:17)' 'void ((lambda at plain.cpp:2:17) &&) noexcept' elidable
-    |       `-MaterializeTemporaryExpr 0x7f94920a9ae0 <col:17, col:45> '(lambda at plain.cpp:2:17)' xvalue
-    |         `-LambdaExpr 0x7f949207c6d8 <col:17, col:45> '(lambda at plain.cpp:2:17)'
-    |           |-CXXRecordDecl 0x7f949207bef8 <col:17> col:17 implicit class definition
-    |           | |-DefinitionData lambda pass_in_registers empty standard_layout trivially_copyable can_const_default_init
+TranslationUnitDecl 0x7f8fde840008 <<invalid sloc>> <invalid sloc>
+`-FunctionDecl 0x7f8fde87bc28 <generic.cpp:1:1, line:4:1> line:1:5 main 'int (int, char **)'
+  |-ParmVarDecl 0x7f8fde87b9c0 <col:10, col:14> col:14 used argc 'int'
+  |-ParmVarDecl 0x7f8fde87bb08 <col:20, col:31> col:26 argv 'char **':'char **'
+  `-CompoundStmt 0x7f8fde88c228 <col:34, line:4:1>
+    |-DeclStmt 0x7f8fde88bc10 <line:2:3, col:47>
+    | `-VarDecl 0x7f8fde87bd88 <col:3, col:46> col:8 used lambda '(lambda at generic.cpp:2:17)':'(lambda at generic.cpp:2:17)' cinit
+    |   `-ExprWithCleanups 0x7f8fde88bbf8 <col:17, col:46> '(lambda at generic.cpp:2:17)':'(lambda at generic.cpp:2:17)'
+    |     `-CXXConstructExpr 0x7f8fde88bbc8 <col:17, col:46> '(lambda at generic.cpp:2:17)':'(lambda at generic.cpp:2:17)' 'void ((lambda at generic.cpp:2:17) &&) noexcept' elidable
+    |       `-MaterializeTemporaryExpr 0x7f8fde88bb60 <col:17, col:46> '(lambda at generic.cpp:2:17)' xvalue
+    |         `-LambdaExpr 0x7f8fde88b578 <col:17, col:46> '(lambda at generic.cpp:2:17)'
+    |           |-CXXRecordDecl 0x7f8fde87c048 <col:17> col:17 implicit class definition
+    |           | |-DefinitionData generic lambda pass_in_registers empty standard_layout trivially_copyable can_const_default_init
     |           | | |-DefaultConstructor defaulted_is_constexpr
     |           | | |-CopyConstructor simple trivial has_const_param implicit_has_const_param
     |           | | |-MoveConstructor exists simple trivial
 ...

Challenges

For Clang it’s efficient to identify AST nodes by their memory address. Almost all lines in our diff represent a AST node and thus contain an address. That’s why they never match: addresses are not deterministic. Some are referred to in subsequent lines, but most of them are not. We can drop the solo ones and replace the others with a simple incremental ID. This eliminates the major source of conflicts, but for now it only reduces our diff by 9 lines:

➜ astpp plain.ast --process node-ids > plain1.ast
➜ astpp generic.ast --process node-ids > generic1.ast
➜ diff -u plain1.ast generic1.ast | wc -l
      92

Another source of conflicts that we are not really interested in are source locations: varying file names as well as line- and column-numbers. We can drop them altogether and make sure they don’t leave artifacts like brackets or whitespace. It cuts our diff by an additional 27 lines:

➜ astpp plain.ast --process node-ids source-locs > plain2.ast
➜ astpp generic.ast --process node-ids source-locs > generic2.ast
➜ diff -u plain2.ast generic2.ast | wc -l
      65

Running the script without the explicit --process parameter runs both steps and additionally trims trailing whitespace.

Voilà!

The result gives some good insight what has changed in the AST:

--- plain.out.ast	2021-09-03 11:50 +0200
+++ generic.out.ast	2021-09-03 11:50 +0200
@@ -10,36 +10,48 @@
     |       `-MaterializeTemporaryExpr '(lambda at  )' xvalue
     |         `-LambdaExpr '(lambda at  )'
     |           |-CXXRecordDecl implicit class definition
-    |           | |-DefinitionData lambda pass_in_registers empty standard_layout trivially_copyable can_const_default_init
+    |           | |-DefinitionData generic lambda pass_in_registers empty standard_layout trivially_copyable can_const_default_init
     |           | | |-DefaultConstructor defaulted_is_constexpr
     |           | | |-CopyConstructor simple trivial has_const_param implicit_has_const_param
     |           | | |-MoveConstructor exists simple trivial
     |           | | |-CopyAssignment trivial has_const_param needs_implicit implicit_has_const_param
     |           | | |-MoveAssignment
     |           | | `-Destructor simple irrelevant trivial
-    |           | |-CXXMethodDecl ID0003 used operator() 'int (int) const' inline
-    |           | | |-ParmVarDecl ID0004 used argc 'int'
-    |           | | `-CompoundStmt ID0005
-    |           | |   `-ReturnStmt ID0006
-    |           | |     `-ImplicitCastExpr ID0007 'int' <LValueToRValue>
-    |           | |       `-DeclRefExpr ID0008 'int' lvalue ParmVar ID0004 'argc' 'int'
-    |           | |-CXXConversionDecl implicit operator int (*)(int) 'int (*() const noexcept)(int)' inline
-    |           | |-CXXMethodDecl implicit __invoke 'int (int)' static inline
-    |           | | `-ParmVarDecl argc 'int'
+    |           | |-FunctionTemplateDecl operator()
+    |           | | |-TemplateTypeParmDecl ID0003 implicit class depth 0 index 0 argc:auto
+    |           | | |-CXXMethodDecl operator() 'auto (auto) const' inline
+    |           | | | |-ParmVarDecl ID0004 referenced argc 'auto'
+    |           | | | `-CompoundStmt ID0005
+    |           | | |   `-ReturnStmt ID0006
+    |           | | |     `-DeclRefExpr ID0007 'auto' lvalue ParmVar ID0004 'argc' 'auto'
+    |           | | `-CXXMethodDecl ID0008 used operator() 'int (int) const' inline
+    |           | |   |-TemplateArgument type 'int'
+    |           | |   | `-BuiltinType  'int'
+    |           | |   |-ParmVarDecl ID0009 used argc 'int':'int'
+    |           | |   `-CompoundStmt
+    |           | |     `-ReturnStmt
+    |           | |       `-ImplicitCastExpr 'int':'int' <LValueToRValue>
+    |           | |         `-DeclRefExpr 'int':'int' lvalue ParmVar ID0009 'argc' 'int':'int'
+    |           | |-FunctionTemplateDecl implicit operator auto (*)(type-parameter-0-0)
+    |           | | |-TemplateTypeParmDecl ID0003 implicit class depth 0 index 0 argc:auto
+    |           | | `-CXXConversionDecl implicit operator auto (*)(type-parameter-0-0) 'auto (*() const noexcept)(auto)' inline
+    |           | |-FunctionTemplateDecl implicit __invoke
+    |           | | |-TemplateTypeParmDecl ID0003 implicit class depth 0 index 0 argc:auto
+    |           | | `-CXXMethodDecl implicit __invoke 'auto (auto)' static inline
+    |           | |   `-ParmVarDecl argc 'auto'
     |           | |-CXXDestructorDecl implicit referenced ~ 'void () noexcept' inline default trivial
-    |           | |-CXXConstructorDecl ID0009 implicit constexpr  'void (const (lambda at  ) &)' inline default trivial noexcept-unevaluated ID0009
+    |           | |-CXXConstructorDecl ID0010 implicit constexpr  'void (const (lambda at  ) &)' inline default trivial noexcept-unevaluated ID0010
     |           | | `-ParmVarDecl 'const (lambda at  ) &'
     |           | `-CXXConstructorDecl implicit used constexpr  'void ((lambda at  ) &&) noexcept' inline default trivial
     |           |   |-ParmVarDecl '(lambda at  ) &&'
     |           |   `-CompoundStmt
     |           `-CompoundStmt ID0005
     |             `-ReturnStmt ID0006
-    |               `-ImplicitCastExpr ID0007 'int' <LValueToRValue>
-    |                 `-DeclRefExpr ID0008 'int' lvalue ParmVar ID0004 'argc' 'int'
+    |               `-DeclRefExpr ID0007 'auto' lvalue ParmVar ID0004 'argc' 'auto'
     `-ReturnStmt
       `-CXXOperatorCallExpr 'int':'int' '()'
         |-ImplicitCastExpr 'int (*)(int) const' <FunctionToPointerDecay>
-        | `-DeclRefExpr 'int (int) const' lvalue CXXMethod ID0003 'operator()' 'int (int) const'
+        | `-DeclRefExpr 'int (int) const' lvalue CXXMethod ID0008 'operator()' 'int (int) const'
         |-ImplicitCastExpr 'const (lambda at  )' lvalue <NoOp>
         | `-DeclRefExpr '(lambda at  )':'(lambda at  )' lvalue Var ID0002 'lambda' '(lambda at  )':'(lambda at  )'
         `-ImplicitCastExpr 'int' <LValueToRValue>