3. Instrumenting programs using GCC-SLO

How to instrument your own programs with GCC-SLO is easiest explained by giving an example. Below, we'll show how to create example1.slo.zip, the example that is used for most of the screenshots in this manual. If you would like to follow these steps on your own computer, download example1.tar.gz at url http://slo.sourceforge.net/examples/example1.tar.gz, and unpack it. The file example1.slo.zip will be build by running GNU make. The contents of the Makefile is as follows:

  1 CC=$(HOME)/gcc-slo/bin/gcc-slo
    CCC=$(HOME)/gcc-slo/bin/g++-slo
    INSTR_FLAG= -O3 -fno-inline -fslo-instrument
    INSTR_LINK_OPTIONS= -static -lrd
  5 
    all: example1 example1.slo.zip
    
    clean:
            rm *.slo_instr_o *.o example1 example1_slo_instr *_info BRD example1.slo.zip
 10 
    %.o: %.c
            $(CC) -O2 -c -o $@ $<
    
    %.slo_instr_o: %.c
 15         $(CC) $(INSTR_FLAG) -c -o $@ $<
    
    example1: example1.o make_vec.o
            $(CC) -o $@ example1.o make_vec.o -lm
    
 20 example1_slo_instr: example1.slo_instr_o make_vec.o
            $(CCC) -o $@ example1.slo_instr_o make_vec.o $(INSTR_LINK_OPTIONS) -lm
    
    BRD: example1_slo_instr
            ./example1_slo_instr 1000
 25 
    example1.slo.zip: BRD
            zip $@ BRD example1.c example1.c.bb_info example1.c.function_info \
                   example1.c.memaccess_info
    

Below, the lines in the Makefile are explained one by one. Following this explanation shows how the example1.slo.zip is built step by step:

CC=$(HOME)/gcc-slo/bin/gcc-slo

This sets variable CC to point to the gcc-slo C compiler.

CCC=$(HOME)/gcc-slo/bin/g++-slo

This sets variable CCC to point to the g++-slo C++ compiler.

INSTR_FLAG= -O3 -fno-inline -fslo-instrument

This sets INSTR_FLAG to contain the optimization flags during instrumenting compilation. The flag -fslo-instrument has the effect that all memory accesses, function entries and exits and basic block transitions will be instrumented appropriately. Furthermore, at compile time, for each source code file, the .bb_info, .function_info and .memaccess_info will be generated. The options -O3 is the regular -O3 option of GCC. The option -fno-inline is necessary, since otherwise the instrumenter will not see function boundaries of functions that were inlined.

INSTR_LINK_OPTIONS= -static -lrd

This sets variable INSTR_LINK_OPTIONS to contain the necessary link time options for profiling applications. The option -lrd links library librd which contains the necessary code to measure reuses, their distances and all other necessary run-time measurement. Option -static makes sure that library librd is statically linked in the final executable.

%.o: %.c

Describes the default way to compile a .c-file into a .o-file, without instrumenting.

%.slo_instr_o: %.c

Describes how a .c-file can be compiled with the necessary instrumentation. Instead of generating a .o file, the filename ends in .slo_instr_o.

example1: example1.o make_vec.o

Describes the default way to create executable example1, without instrumentation

example1_slo_instr: example1.slo_instr_o make_vec.o

Describes how to compile example1_slo_instr, where all code in example1.c is instrumented. Note that the code in make_vec.c is not instrumented, since make_vec.o is used instead of make_vec.slo_instr_o. Usually, it is best to instrument all your source code files.

BRD: example1_slo_instr

The BRD file contains all reuse information as measured by profiling the instrumented program.

example1.slo.zip: BRD

Describes that the example1.slo.zip file must contain the BRD file, all source code files and all *_info files generated at compile time.

3.1. Environment variables

A number of environment variables influence the profiling process. To influence the characteristics that are measured, set the following environment variables before running the instrumented program.

RDLIB_MEASURE_TRUE_REUSE_DISTANCE

If this environment variable is set to a value different from 0, the distance between reuses is measured in terms of "reuse distance", i.e. the number of different data elements accessed between both reuses. Otherwise, the distance is measured by "reference distance" a.k.a. "time distance", which is the total number of accesses between both reuses. The measurement of "reference distance" is much faster than the measurement of "reuse distance". On the other hand, "reuse distance" has a clearer connection with cache behavior.

RDLIB_EXPORT_TRACE

If this variable is set, during profiling the trace of memory accesses will be saved to a file. The name of the file is the value that this variable is set to. The trace file is a binary file, consisting of a sequence of memory accesses. For each memory access, the following bytes are written to the trace. First, the address of the accessed address is written, which is sizeof(void*) bytes long. Next, an identifier for the instruction generating the memory access is written, which is sizeof(int) bytes long.

RDLIB_EXPORT_TRACE_FLUSH_AFTER_EACH_ACCESS

If this variable is set to a value different from 0, and RDLIB_EXPORT_TRACE is set, the memory access trace will be flushed to disk after each memory access. This slows down the tracing considerably, but can be handy for detecting bugs.