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:
This sets variable
CC to point to the gcc-slo C compiler.
This sets variable
CCC to point to the g++-slo C++ compiler.
INSTR_FLAG= -O3 -fno-inline -fslo-instrument
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.
Describes the default way to compile a .c-file into a .o-file, without instrumenting.
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 file contains all reuse information as measured by profiling the instrumented program.
Describes that the
example1.slo.zip file must contain the
BRD file, all source code files and all *_info files generated at compile time.
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.
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.
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.
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.