llvm-apx-analysis

A toolkit for testing whether LLVM/Clang actually emits Intel APX instructions in the situations where it should. Built for a software-security course focused on binary analysis and compiler fuzzing.

Intel APX (Advanced Performance Extensions) adds, among other things, 16 new general-purpose registers (r16–r31, the "EGPRs"), a no-flags ({nf}) instruction form, conditional-compare (ccmp), and push2/pop2. This project generates C code that should lower to those features, compiles it with an APX-aware Clang, and disassembles the result to check whether the compiler took the bait.

---

What it actually does

The working core is a differential / black-box testing pipeline:

1. Generate random C with CSmith and inject hand-written "archetype" functions designed to lower to a specific APX instruction (ndd_and, ccmp, push2/pop2).
2. Compile to an x86-64 object file with clang -O3 -target x86_64-apple-darwin -mapxf (cross-compiled from macOS/Apple Silicon).
3. Disassemble with llvm-objdump and scan the assembly for APX mnemonics (push2p/pop2p, ccmp, {nf}).
4. Scale the loop across all cores and triage cases where the expected instruction never appeared.

This is the part that produces real, reproducible measurements.

Module status

This repository grew from the core pipeline into several more ambitious experiments. Being upfront about what is production-quality vs. proof-of-concept:

Module	File	Status
CSmith driver + archetype injection	src/apx_fuzzer/csmith_driver.py	✅ Working
Archetype C generators	src/apx_fuzzer/archetypes.py	✅ Working
Compile + objdump APX scanner	src/apx_analyzer/objdump_parser.py	✅ Working
Parallel fuzzing harness	src/apx_fuzzer/evaluator_pool.py	✅ Working
Register-pressure CFG synthesizer	src/apx_fuzzer/cfg_synth.py	✅ Working
-Rpass optimization-remark bisector	src/apx_analyzer/bisection.py	✅ Working
GCC-vs-Clang differential	src/apx_analyzer/cross_compiler.py	⚠️ Working, needs gcc-14
RL register-allocation agent	src/apx_fuzzer/ml_isel_agent.py	🧪 Experimental — trains against a mock compiler stream (mock_llvm_client.py), not wired into LLVM
Z3 TableGen check	src/apx_analyzer/tablegen_sat.py	🧪 Experimental — runs over a toy sample_apx.td, not real LLVM TableGen
angr equivalence check	src/apx_analyzer/sym_verifier.py	🧪 Experimental — VEX cannot lift APX opcodes yet, so it can't verify APX binaries today
Intel PIN taint tracker	src/apx_execution/taint_runner.py	🧪 Experimental — requires Docker + Intel SDE/PIN environment
V8 JIT probe	src/apx_fuzzer/v8_jit_fuzzer.py	🧪 Experimental — requires a local d8 build
Out-of-tree LLVM/Clang C++ plugins	plugins/	🧱 Scaffolding — out-of-tree passes, not built by default
SwiftUI dashboard	ApxUI/	🧱 Optional macOS front-end

Note on the experimental modules: they are real, runnable code, but they exercise mocks, simplified models, or toolchains that do not yet support APX. Treat their output as scaffolding for future work, not as verified results.

---

Repository layout

bin/                 CLI entry point (apx-toolkit) and report generator
src/
  apx_fuzzer/        CSmith driver, archetypes, CFG synth, parallel harness, ML/JIT experiments
  apx_analyzer/      objdump scanner, GCC/Clang diff, bisection, angr & Z3 experiments
  apx_execution/     Intel PIN taint runner
archetypes/          Standalone C archetype samples (.c)
plugins/             Out-of-tree LLVM pass / Clang AST mutator / Intel PIN tool (C++)
ApxUI/               Native SwiftUI dashboard (optional)
tests/               unittest suite (archetypes, bisection)
GEMINI.md            Original project plan / design notes

Requirements

• macOS / Apple Silicon (paths assume Homebrew LLVM at /opt/homebrew/opt/llvm)
• LLVM/Clang with APX support — brew install llvm (needs a build whose -mapxf recognizes APX; check with clang --print-supported-extensions | grep apx)
• Python 3.9+
• Optional, per experimental module: gcc-14, torch, z3-solver, angr + claripy, Docker + Intel SDE/PIN, a local V8 d8 build.

CSmith is not vendored — it is cloned and built on demand.

Setup

# Clone and build CSmith into third_party/ (does not touch the rest of the toolchain)
make csmith

# Optional: install Python deps for the experimental modules
pip3 install torch numpy z3-solver angr claripy

Usage

The CLI wraps each stage:

# Full parallel fuzzing run (CSmith -> clang -mapxf -> objdump scan)
./bin/apx-toolkit fuzz

# Evaluate a single C file for APX emission
python3 src/apx_analyzer/objdump_parser.py path/to/file.c

# Synthesize a register-pressure stress program with K live values, then diff it
./bin/apx-toolkit synth 20
./bin/apx-toolkit cross synth_pressure.c

# Inspect optimization remarks for why an archetype did/didn't lower
python3 src/apx_analyzer/bisection.py path/to/file.c

Run ./bin/apx-toolkit -h for the full subcommand list.

Tests

make test        # or: python3 -m unittest discover tests/

Reproducing the report

bin/generate_report.py runs the pipeline end-to-end and writes thesis_research_report.md from the actual stdout of each stage. The committed report describes methodology and current status; regenerate it locally to capture live numbers from your own toolchain.

Status & limitations

• Results depend entirely on whether your local Clang build genuinely supports -mapxf emission; without it, the scanner will simply report no APX instructions.
• The experimental modules (ML/Z3/angr/PIN/V8) are research scaffolding — see the status table above before citing their output.
• Paths are currently hard-coded for Homebrew on Apple Silicon and would need generalizing for other platforms.