Minimizing LLVM IR with llvm-reduce

The Interestingness Test: Your Guide for llvm-reduce

As we touched on last time, llvm-reduce operates on a simple principle: you provide it with a script, called an interestingness test, that determines if a given IR file is still "interesting"—that is, if it still triggers the bug. The script must exit with a status code of 0 if the bug is present, and a non-zero code otherwise.

The simplest script for a crash looks like this, where ! inverts the exit code of the crashing command:

#!/bin/bash
# interesting-crash.sh




# Run the crashing command on the input file ($1) provided by llvm-reduce.
# Redirect stderr to /dev/null to keep the output clean.
# '!' makes the script exit 0 (interesting) if opt crashes (non-zero exit code).
! /path/to/your/build/bin/opt -passes=gvn -disable-output "$1" 2>/dev/null

However, this simple approach has a weakness. Sometimes, a reduction can simplify the code in a way that triggers a different bug in the same pass. llvm-reduce will happily follow this new path, leaving you with a minimal reproducer for a bug you weren't trying to fix.

Making Your Test More Specific

To avoid this, you should make your interestingness test as specific as possible. The best way to do this is to check for the unique assertion message or error output associated with your bug.

#!/bin/bash
# interesting-specific-crash.sh




# Run the command, pipe its stderr (2>&1) to stdout, and grep for the specific message.
# grep exits 0 if the pattern is found, which is exactly what llvm-reduce wants.
/path/to/your/build/bin/opt -passes=gvn -disable-output "$1" 2>&1 | grep -q "Value *not* dominated by definition"

The -q flag tells grep to be quiet and simply exit with the appropriate status code. This is the most common and robust way to test for crashes.

Handling Compiler Hangs

What if the bug isn't a crash, but an infinite loop or a task with extreme computational complexity that causes the compiler to hang? You can still use llvm-reduce by creating an interestingness test based on a timeout.

The script would look like this:

#!/bin/bash
# interesting-hang.sh




# The 'timeout' command runs a program for a maximum duration.
# If the command exceeds the time limit (e.g., 5 seconds), timeout kills it
# and exits with a special status code (often 124).
# We want to treat a timeout as "interesting", so we check for this.

timeout 5 /path/to/your/build/bin/opt -passes=some-slow-pass -disable-output "$1" &>/dev/null




# If the process timed out (exit code 124), it's interesting (exit 0).
# Otherwise, it's not interesting (exit 1).
if [ $? -eq 124 ]; then
  exit 0
else
  exit 1
fi

This script defines "interesting" as any IR file that causes the pass to run for more than 5 seconds. Be warned: this method can be slow, as every successful reduction step will take at least 5 seconds.

Peeking Under the Hood: Delta Passes

llvm-reduce is not just randomly deleting lines. It applies a series of structured transformations, called delta passes or "deltas," to minimize the IR. Each delta knows how to perform a specific kind of reduction, such as:

• Deleting a function.
• Removing instructions.
• Replacing a global variable with a constant.
• Simplifying function signatures.
• Merging basic blocks.

You can see the list of all available delta passes by running:
llvm-reduce --print-delta-passes

Understanding deltas is key to troubleshooting tricky reductions.

A Critical Pitfall: llvm-reduce Crashing Itself

Internally, llvm-reduce uses a small set of LLVM passes (function(sroa,instcombine,gvn,simplifycfg,...)) to clean up the IR after applying a delta. This can be a problem. If you are trying to reduce a bug in, say, instcombine, then llvm-reduce itself will crash when it tries to use instcombine for its internal cleanup.

The solution is to tell llvm-reduce not to use its internal IR passes.

The command to disable these internal passes is:
llvm-reduce --test=interesting.sh --skip-delta-passes=ir-passes my_bug.ll

You can also be more selective and run only a specific set of deltas with --delta-passes=... or skip specific ones with --skip-delta-passes=.... This gives you fine-grained control over the reduction process, which can be useful if a particular delta is being counterproductive.

Example Walkthrough

Let's consolidate this with a practical example. Imagine opt -passes=instcombine is crashing on a large file bug.ll with the assertion message "Assertion II->hasOneUse() failed."

1. Create the Interestingness Script (test.sh): We make it specific by grep-ing for the assertion.

   
   
   
   #!/bin/bash
   /path/to/llvm/bin/opt -passes=instcombine -disable-output "$1" 2>&1 | grep -q "Assertion \`II->hasOneUse()\` failed"
   

   Make it executable: chmod +x test.sh.

2. Run llvm-reduce: We start the reduction.

   llvm-reduce --test=./test.sh bug.ll -o reduced.ll
   

3. Troubleshoot: llvm-reduce crashes! The bug is in instcombine, and llvm-reduce uses instcombine internally. This is the classic pitfall.

4. Refine the Command: We run it again, but this time we tell llvm-reduce not to use its internal IR passes.

   llvm-reduce --test=./test.sh --skip-delta-passes=ir-passes bug.ll -o reduced.ll
   

5. Success: llvm-reduce runs to completion and produces reduced.ll, a minimal file that triggers the assertion.

6. Final Cleanup (Optional but Recommended): The resulting IR might have ugly names (%123). We can clean it up for the final bug report and test case.

   opt -S -passes=strip,metarenamer reduced.ll -o final_test.ll
   

   The strip pass removes debug metadata, and metarenamer gives everything clean, canonical names (%0, %1, etc.), making the test case much more readable.

Conclusion

You have now moved beyond a surface-level understanding of llvm-reduce and can wield it as a powerful, precise tool for bug isolation. You know not only how to use it but also how its internal mechanisms work and how to control them when things go wrong.

Key Takeaways:

• An interestingness test is a script that exits with code 0 if a file triggers a bug.
• Make your test specific by using grep or FileCheck on the exact error message to avoid reducing to a different bug.
• Compiler hangs can be reduced by using the timeout command in your test script.
• llvm-reduce uses delta passes to perform structured reductions. You can see them with --print-delta-passes.
• If llvm-reduce crashes, it's likely because the bug is in a pass that llvm-reduce itself uses. The fix is to use --skip-delta-passes=ir-passes.
• Clean up your final minimized IR with opt -passes=strip,metarenamer to create a professional test case.

In our next lesson, we'll address another critical part of the bug-fixing lifecycle. Now that you have a minimal, reproducible test case, the next question is: when did this bug appear? We will learn to use git bisect to automatically search the project's history and pinpoint the exact commit that introduced a regression.