                                Functracer

                        An Allocation Backtrace Tool

                  Copyright (C) 2008 by Nokia Corporation

Contents
--------
 0. Authors
 1. Introduction
 2. Where can I find it
 3. How does it work
 4. How to use
 5. Where does it work
 6. Bugs
 7. License


0. Authors
----------
Functracer has been developed by:

Anderson Lizardo <anderson.lizardo@indt.org.br>
Allan Bezerra <allan.bezerra@indt.org.br>
Bruna Moreira <bruna.moreira@indt.org.br>
Bruno Abinader <bruno.abinader@indt.org.br>
Ricardo Guimaraes <ricardo.guimaraes@indt.org.br>
Thiago Marcos P. Santos <thiago.santos@indt.org.br>

1. Introduction
---------------
Functracer is a debugging tool. It gets backtraces of all allocations done in
ARM/x86 processes. It works with optimized (-O2) code, where debugging symbols
are available either in the application  binaries themselves, or in separate
debug files.

2. Where can I find it
----------------------
FIXME: there is no website setup for it yet.

3. How does it work
-------------------
Using software breakpoints, just like GDB and ltrace. Breakpoints are inserted
on entrypoint of Glibc allocation functions (malloc, calloc and realloc) and
when one of them is called, the breakpoint is hit and the allocation address,
size and callchain backtrace are reported.

Two output files are created by Functracer in $HOME:
- allocs-PID.n.map: /proc/PID/maps of traced process
- allocs-PID.n.trace: allocation backtraces of traced process

For generating backtraces, libunwind[1] is used (see INSTALL for detailed 
compilation instructions).

4. How to use
--------------

Output from "functracer --help":

Usage: functracer [OPTION...] PROGRAM [ARGS...]
Run PROGRAM and track selected functions.

  -b, --free-backtraces      enable backtraces for free() function
  -d, --debug                maximum debug level
  -e, --track-function=FUNCTION   which function to track (NOT IMPLEMENTED)
  -f, --file                 use a file to save backtraces instead of dump to
                             stdout
  -l, --path=DIR             dump reports to a custom location (defaults to
                             homedir)
  -p, --track-pid=PID        which PID to track
  -r, --resolve-name         enable symbol name resolution
  -s, --start                enable tracking memory from beginning
  -t, --depth=NUMBER         maximum backtrace depth
  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

You can control the dumping of output files. To use it, just send SIGUSR1
to the tracked application (NOT functracer itself) to toggle the tracing on/off.
Tracing is not enabled by default on application start (use -s to enable this).
The control logic is:
  - If not tracing:
    - SIGUSR1 start tracing
  - If tracing:
    - SIGUSR1: stop tracing, dump backtraces and clear them

Internal symbol resolving in functracer (option "-r") has several limitations
compared to its postprocessor symbol resolving (functracer-postproc):
- it does not resolve source file name and line number.
- it does not do demangling for C++ symbol names (low-level symbol names into
  user-level names).

5. Where does it work
---------------------
It works with ELF based Linux systems running on x86 or ARM architecture.

6. Bugs
-------
- this version has a performance decrease due to several reading of /proc
  directory.
- functracer tries to serialize the threads, avoiding that allocation related
  breakpoints from multiple threads are caught by it at the same time.  Note
  that there are still some issues with allocation functions not being reported
  in the correct order.

To do:
- better documentation, source code comments
- testsuite framework infrastructure (just some basic tests are available)

7. License
----------
This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License version 2 as published by the Free
Software Foundation.
