Skip to content
An LLVM pass to profile dynamic LLVM IR instructions and runtime values
Branch: master
Clone or download
xyzsam Print a more helpful message when encountering an unhandled type.
This makes us print a readable type name, rather than the integral value
of the TypeID.

Change-Id: I64e26146c55668e0c70fdac33a48333d283da3dc
Latest commit ae526a3 Jan 31, 2018

LLVM IR Trace Profiler (LLVM-Tracer) 1.2

LLVM-Tracer is an LLVM instrumentation pass to print out a dynamic LLVM IR trace, including dynamic register values and memory addresses.

If you use LLVM-Tracer in your research, please cite:

ISA-Independent Workload Characterization and its Implications for Specialized Architectures, Yakun Sophia Shao and David Brooks, International Symposium on Performance Analysis of Systems and Software (ISPASS), April 2013


  1. LLVM 3.4 and Clang 3.4 64-bit or LLVM 3.5 and Clang 3.5 64-bit
  2. GCC 4.7 or newer for C++11 features.
  3. CMake 2.8.12 or newer.


Breaking changes from v1.1 to v1.2:

  • CMake is no longer optional. LLVM-Tracer only supports CMake for building. This is because of a new Clangtool component (under ast-pass/) which requires CMake.
  • LLVM-Tracer will install all built files to the subdirectories bin/ and lib/ instead of full-trace/ and profile-func/. The BUILD_ON_SOURCE option has been removed.

CMake is a configure tool which allows you to do out-of-source build. LLVM-Tracer requires CMake newer than 2.8.12. By default, CMake searches for LLVM 3.4.

  1. Set LLVM_HOME to where you installed LLVM

    export LLVM_HOME=/path/to/your/llvm/installation
  2. Clone LLVM-Tracer.

    git clone
    cd LLVM-Tracer/
  3. Configure with CMake and build LLVM-Tracer source code.

    If you have LLVM installed:

    mkdir build/
    cd build
    cmake ..
    make install

    If you want CMake to install LLVM for you (CAUTION: takes an hour!):

    mkdir build/
    cd build
    cmake .. -DLLVM_ROOT=/where/to/install/LLVM -DAUTOINSTALL=TRUE
    make install
  4. (Optional) Try running triad example, which is built by CMake.

    cd /path/to/build/LLVM-Tracer/
    ctest -V
  5. Available CMake settings

    -DLLVM_ROOT=/where/your/llvm/install   (default : $LLVM_HOME)
      You may denote the path of LLVM to find/install by this option. if
      this option is not defined, environment variable LLVM_HOME will be
    -DLLVM_RECOMMEND_VERSION="3.4", "3.5"    (default : 3.4)
      LLVM-Tracer supports both LLVM 3.4 and 3.5. It uses LLVM 3.4 by
      default, but you can manually specify the LLVM version to use.
      By this option, CMake scripts will automatically download, build and
      install LLVM for you if finds no LLVM installation. Using this
      function requires tar-1.22 or newer to extract xz format.
      The default installation path is under /your/build_dir/lib/llvm-3.x.
      You can manually define the installation path by
      The default installation version will be 3.4. You can define
      the installation version by -DLLVM_RECOMMEND_VERSION="3.5" or "3.4".
      This auto install script will try to use the latest patch version
      according to cmake-scripts/AutoInstall/LLVMPatchVersion.cmake
    -DCMAKE_BUILD_TYPE=None,Debug,Release    (default : None)
      You can choose one from three of bulid types.


After you build LLVM-Tracer, you can use example triad programs in the example directory to test LLVM-Tracer.

Example program: triad

  1. Go to /your/path/to/LLVM-Tracer/example/triad

  2. Run LLVM-Tracer to generate a dynamic LLVM IR trace a. LLVM-Tracer tracks regions of interest inside a program. In the triad example, we want to analyze the triad kernel instead of the setup and initialization work done in main. To tell LLVM-Tracer the functions we are interested in, set the enviroment variable WORKLOAD to be the top-level function name:

    export WORKLOAD=triad

    If you have multiple functions, separate them with commas.

    export WORKLOAD=md,md_kernel

    LLVM-Tracer will trace them differently based on the -trace-all-callees flag, which can be specified to the opt command (see step d).

    • If this flag is specified, then any function called by any function in the WORKLOAD variable will be traced. This is a simple way to trace multiple "top-level" functions at once.
    • If this flag is not specified, then only functions in the WORKLOAD variable will be traced.

    b. Generate the source code labelmap.

    export TRACER_HOME=/your/path/to/LLVM-Tracer
    ${TRACER_HOME}/bin/get-labeled-stmts triad.c -- -I${LLVM_HOME}/lib/clang/3.4/include

    c. Generate LLVM IR:

    clang -g -O1 -S -fno-slp-vectorize -fno-vectorize -fno-unroll-loops -fno-inline -emit-llvm -o triad.llvm triad.c

    d. Run LLVM-Tracer pass. Before you run, make sure you already built LLVM-Tracer and have set the environment variable TRACER_HOME to where you put LLVM-Tracer code.

    opt -S -load=${TRACER_HOME}/full-trace/ -fulltrace -labelmapwriter [-trace-all-callees] triad.llvm -o triad-opt.llvm
    llvm-link -o full.llvm triad-opt.llvm ${TRACER_HOME}/profile-func/trace_logger.llvm

    The -trace-all-callees flag is optional and defaults to false.

    e. Generate machine code:

    llc -filetype=asm -o full.s full.llvm
    gcc -fno-inline -o triad-instrumented full.s

    f. Run binary. It will generate a file called dynamic_trace under current directory.


    g. There is a script provided which performs all of these operations.

    python $TRACER_HOME/example/triad triad

triad is part of the SHOC benchmark suite. We provide a version of SHOC that is ready to be used with LLVM-Tracer. Please go to Aladdin and look under the SHOC directory.

Sophia Shao, Sam Xi, and Emma Wang

You can’t perform that action at this time.