README for matrix-report.pl
===========================

This program processes perf.data files to produce a matrix profile
in HTML format. The resulting HTML uses Javascript and CSS so requires
a reasonably modern web browser to view.

How to use
==========

Perf record must be run with --all-cpus. For example:

    $ perf record --all-cpus <testcommand>
    $ perl .../matrix-report.pl --input perf.data --output report.html

Command line interface
======================

    --report-interval <number of seconds per timeslot> [default: 1]
       * this option selects the time represented by each row in
         the output matrix.
    --sample-interval <perf sample interval> 
    --sample-frequency <perf sample frequency>         [default: automatic]
       * can be used if matrix-report.pl does not correctly determine
         the perf sampling frequency
    --min-task-cpu <%age>                              [default: 1]
       * tasks below this %age CPU usage are hidden from the default
         display
    --output <path>                                    [default: stdout]
       * filename to generate output
    --input <path>
       * path to perf.data file
    --perf <path>                                      [default: perf]
       * name of perf binary to use for analysing perf.data file

Interpreting output
===================

Each column shows the activity on a particular CPU. Each row represents
the behaviour of the system for a slice of time while the profile data
was collected.

If a thread is selected in the top menu, then all cells in the matrix where
that thread used CPU are highlighted.

When the mouse pointer hovers over a cell in the matrix a profile is displayed
showing which symbols were consuming CPU time on that CPU in that time slice.