QuickStart

Dependencies

In order to build you’ll need the following packages:

gcc (at least version 4.8)
binutils (at least version 2.26)
cmake (at least version 3.7)
perl

Tip

To avoid any version conflicts with existing packages installed in the system, we recommend to use Spack to manage the above packages and create a virtual environment to build and run DrCCTProf.

Build

Get source code from the github repository and build DrCCTProf:

$ git clone --recurse https://github.com/Xuhpclab/DrCCTProf.git
$ ./build.sh

Usage

To run DrCCTProf, one needs to use the following command:

x86_64

$ build/bin64/drrun -t <client tool> -- <application> [apllication args]

aarch64

$ build/bin64/drrun -unsafe_build_ldstex -t <client tool> -- <application> [apllication args]

Tip

DrCCTProf leverages DynamoRIO to analyze a program execution on the fly, so make sure <application> [apllication args] is specified in a way you actually run <application>. Don’t pass the source code file as <application>.

Internal client tools list

Name	Version	Features
instr_statistics_clean_call	release	A instruction counting tool that counts each instruction^*.
drcctlib_cct_only_clean_call	release	A tool that collects call path on each instruction^*.
drcctlib_instr_statistics_clean_call	release	A instruction counting tool that counts each instruction^*.
drcctlib_reuse_distance_client_cache	release	A reuse distance measurement tool.
drcctlib_cct_only	beta	(Code cache mode)A tool that collects call path on each instruction^*.
drcctlib_instr_statistics	beta	(Code cache mode) A instruction counting tool that counts each instruction^*.
drcctlib_reuse_distance	beta	(Code cache mode) A reuse distance measurement tool.

Example: instr_statistics_clean_call

In this example, you will write a simple program in C, compile it, and run it using instr_statistics_clean_call client. The client will display the top 200 instructions^* of the most execution frequency within their full call paths in the output file.

1. Create source file

Create a simple C program and save it as a file named sample.c.

#include <stdio.h>
static int exe_num = 0;
void moo() {
    for(int i = 0; i < 100; i++){
        exe_num ++;
    }
    return;     
}
void foo() {
    for(int i = 0; i < 10000; i++){
        moo();
    }
}
int main(){
    foo();
    for(int i = 0; i < 20000; i++){
        moo();
    }
    return 0;  
}

2. Compile your application

To generate an executable binary, compile your application with GCC Compiler.

$ gcc -g sample.c -o sample

Tip

If the executable is built with -g opinion, the client will show more information, such as source code line number and source file path.

3. Run application using client

Run the generated binary sample using instr_statistics_clean_call client.

$ build/bin64/drrun -t instr_statistics_clean_call -- ./sample

The client outputs:

NO. 1 PC 0x000000000040113a "add    eax, 0x01"
=>EXECUTION TIMES
2000000
=>BACK TRACE
#0   0x000000000040113a in moo at [../src/sample.c:5]
#1   0x000000000040119b in main at [../src/sample.c:17]
#2   0x00007fe41ff67f43 in __libc_start_main at [/build/eglibc-xkFqqE/eglibc-2.19/csu/libc-start.c:287]
#3   0x0000000000401074 in <noname> at [/build/eglibc-xkFqqE/eglibc-2.19/csu/libc-start.c:0]
#4   0x0000000000000000 in THREAD[0]_ROOT_CTXT at [ :0]
#5   0x0000000000000000 in PROCESS[22643]_ROOT_CTXT at [ :0]

...
...

NO. 7 PC 0x000000000040113a "add    eax, 0x01"
=>EXECUTION TIMES
1000000
=>BACK TRACE
#0   0x000000000040113a in moo at [../src/sample.c:5]
#1   0x0000000000401166 in foo at [../src/sample.c:11]
#2   0x0000000000401188 in main at [../src/sample.c:15]
#3   0x00007fe41ff67f43 in __libc_start_main at [/build/eglibc-xkFqqE/eglibc-2.19/csu/libc-start.c:287]
#4   0x0000000000401074 in <noname> at [/build/eglibc-xkFqqE/eglibc-2.19/csu/libc-start.c:0]
#5   0x0000000000000000 in THREAD[0]_ROOT_CTXT at [ :0]
#6   0x0000000000000000 in PROCESS[22643]_ROOT_CTXT at [ :0]

...
...

* Instructions of the same PC (program counter) may appear in different call paths.

Tip

Intepreting the text output: The client drcctlib_instr_statistics_clean_call counts each instruction and outputs its execution frequency as the metric, pc, assemble code, and full call path (like the backtrace shown in GDB). The full call path starts on the bottom with two dummy PROCESS_ROOT and THREAD_ROOT and ends on the top with the fuction that encloses the pc.