2018-03-05 11:33:57 +01:00
|
|
|
# Dotrace
|
|
|
|
|
|
|
|
|
|
Dotrace is a library which allows users to trace function calls during
|
|
|
|
|
the execution of a C program by utilizing GCCs `instrument-functions`
|
|
|
|
|
functionality. The execution generates a trace file containing
|
|
|
|
|
addresses. This trace file can then be decoded using the provided
|
|
|
|
|
`dotrace_decode.py` script.
|
|
|
|
|
|
|
|
|
|
## Dependencies
|
|
|
|
|
|
|
|
|
|
The tool has been tested with GCC version 6.4.0, but any more or less
|
|
|
|
|
recent version should work. The decoding scrip requires Python 3. It
|
|
|
|
|
was tested with version 3.6.4. Furthermore, the `addr2line` utility is
|
|
|
|
|
required by the decoding script. On many platforms this utility is part
|
|
|
|
|
of a `binutils` package.
|
|
|
|
|
|
|
|
|
|
Nix users can use the provided `default.nix` file with the `nix-shell`
|
|
|
|
|
command to get a shell with the packages required for decoding present.
|
|
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
|
|
|
|
First the program and `dotrace.c` must be compiled with the compilation
|
|
|
|
|
option `-finstrument-functions`. The provided `dotrace.h` should also
|
|
|
|
|
be available in the include paths of the compile.
|
|
|
|
|
|
|
|
|
|
Here is how to do this with the provided examples:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
> gcc -I. -finstrument-functions examples/example1.c dotrace.c
|
|
|
|
|
> ./a.out
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This generates a file `trace.out`:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
e 0x4006c0 0x7fe810ed07e0
|
|
|
|
|
e 0x400840 0x4006df
|
|
|
|
|
x 0x400840 0x4006df
|
|
|
|
|
x 0x4006c0 0x7fe810ed07e0
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This can then be decoded:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
> ./dotrace_decode.py -b a.out -t trace.out
|
|
|
|
|
Processing lines 1-4 [final block].
|
|
|
|
|
> cat trace.decoded
|
|
|
|
|
Enter main from ?? (??:0)
|
|
|
|
|
Enter square from main (??:?)
|
|
|
|
|
Exit square
|
|
|
|
|
Exit main
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The `dotrace_decode` script provides various command line arguments to
|
|
|
|
|
customize the output. This is especially helpful when comparing bigger
|
|
|
|
|
trace files.
|
|
|
|
|
|
|
|
|
|
The filename of the trace file can be changed by overwriting the
|
|
|
|
|
preprocessor variable `DOTRACE_FILE`.
|
|
|
|
|
|
|
|
|
|
Furthermore the two functions `dotrace_start` and `dotrace_stop`
|
|
|
|
|
provided in `dotrace.h` can be used to turn tracing on and off. The
|
|
|
|
|
calls to these functions is not traced. To have tracing turned off
|
|
|
|
|
at the start of the program the `DOTRACE_SUSPEND` must be set.
|
|
|
|
|
|
|
|
|
|
The provided `examples/example2.c` file uses this functionality. To compile
|
|
|
|
|
it run:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
> gcc -I. -finstrument-functions -DDOTRACE_SUSPEND examples/example2.c dotrace.c
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
After running the resulting program, the trace file contains only the
|
|
|
|
|
one call to the `square` function where tracing is activated.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## References
|
|
|
|
|
|
|
|
|
|
For a documentation of the instrumentation functionality provided by
|
|
|
|
|
GCC see the
|
|
|
|
|
[online documentation](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html).
|
|
|
|
|
|
|
|
|
|
The functionality of `dotrace` is heavily inspired by
|
|
|
|
|
[this](https://balau82.wordpress.com/2010/10/06/trace-and-profile-function-calls-with-gcc/)
|
|
|
|
|
blog post.
|
|
|
|
|
|
|
|
|
|
The [etrace](http://ndevilla.free.fr/etrace/) tool provides a similar
|
|
|
|
|
functionality, but has not been maintained for some years.
|
