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-sloThis sets variable CC to point to the gcc-slo C compiler.
CCC=$(HOME)/gcc-slo/bin/g++-sloThis sets variable CCC to point to the g++-slo C++ compiler.
INSTR_FLAG= -O3 -fno-inline -fslo-instrumentThis 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 -lrdThis 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: %.cDescribes the default way to compile a .c-file into a .o-file, without instrumenting.
%.slo_instr_o: %.cDescribes 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.oDescribes the default way to create executable example1, without instrumentation
example1_slo_instr: example1.slo_instr_o make_vec.oDescribes 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_instrThe BRD file contains all reuse information as measured by profiling the instrumented program.
example1.slo.zip: BRDDescribes 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.