                                functracer-postproc

                        Functracer Post-Processor Tool

                  Copyright (C) 2008, 2009 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. Potential reports/post-processors
 7. Bugs
 8. License


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

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>

1. Introduction
---------------
Funtracer-postproc is a post-processing tool. It generates detailed reports
from Functracer output data. For now, functracer-postproc generates the
following reports:

- List non-freed resource allocations (possible leaks).
- List freed resource allocations.

The reports above can be sorted by blocks count or total size.

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

3. How does it work
-------------------
functracer-postproc reads data from a file and creates a report with useful
information.

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

For a complete list of functracer-postproc options, see the manual page.

In addition, two aliases are available. functracer-postproc-reduce is the same
as functracer-postproc -l -c. functracer-postproc-resolve is the same  as
functracer-postproc -r.

functracer-postproc gives an error message and exits when using conflicting
options "-f" and"-l". Note that "functracer-postproc-reduce -f" is the same as
"functracer-postproc -c -f -l", so the error message is also shown.

To solve names properly in other environment (collect data in target and
post-processing it in PC), the new environment must have exactly the same
libraries and architecture from the data were generated.

When the name resolution ("-r" option) is not enabled, the functracer-postproc
output contains the trace header and all maps information. So, the user can
resolve names in next step. 

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

6. Potential resource reports/post-processors
----------------------------------------------

* addressmap:
  - resource type: memory
  - data: resource addresses & sizes
  - for: memory fragmentation analysis
  - needs freed-removal done

* histogram:
  - resource type: memory & objects
  - data: resource sizes
  - for: alloc overhead analysis
  - needs freed-removal done

* timeline:
  - resource type: memory, objects, FDs, threads, memops
  - data: resource timestamps & sizes
  - for: run-time behavior/performance analysis
  - needs non-processed functracer output!

* calltree:
  - resource type: memory, objects, FDs, memops
  - data: resource sizes, backtraces (and addresses)
  - for: analyzing resource usage
    - if only topmost addresses selected,
      also for fragmentation analysis
  - freed-removal and alloc joining already done speeds up
    calltree python script (won't be written in C)

A utility that creates addressmap, histogram and calltree snapshots from the
program run-time behaviour, would also use functracer output directly, but it
just splits it before feeding it to suitable post-processor.

7. Bugs
-------
- memory leak generated by bfd_read_nearest_line function on 'src/resolve.c'.

To do:
- Test-suite framework infrastructure.
- Multi-arch support.

8. 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.
