diff options
Diffstat (limited to 'perf2cfg/README.md')
| -rw-r--r-- | perf2cfg/README.md | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/perf2cfg/README.md b/perf2cfg/README.md new file mode 100644 index 00000000..85cbc455 --- /dev/null +++ b/perf2cfg/README.md @@ -0,0 +1,121 @@ +# perf2cfg + +perf2cfg annotates a control-flow graph (CFG) file with profiling information +from simpleperf data files. A CFG file can be generated by the Android Runtime +compiler using the `--dump-cfg=<cfg-file>` option. The tool outputs an +annotated CFG file with the following added information: +- Methods are annotated with their contribution relative to the total profile. +- Basic blocks and assembly instructions are annotated with their contribution + relative to the method profile. +- Basic blocks are colored according to their contribution to the method + profile. + +The tool does not modify any input files and assumes the input CFG file can be +parsed by c1visualizer. The input files must have all been generated for the +same architecture. + +## Usage + +``` +usage: perf2cfg [-h|--help] --cfg CFG --perf-data PERF_DATA [PERF_DATA ...] + [--output-file OUTPUT_FILE] [-e|--events EVENTS] + [--primary-event PRIMARY_EVENT] + +Annotates a CFG file with profiling information from simpleperf data files. + +optional arguments: + -h, --help Show this help message and exit. + --output-file OUTPUT_FILE + A path to the output CFG file. + -e EVENTS, --events EVENTS + A comma-separated list of events only to use for + annotating a CFG (default: use all events found in + perf data). An error is reported if the events are not + present in perf data. + --primary-event PRIMARY_EVENT + The event to be used for basic blocks hotness analysis + (default: cpu-cycles). Basic blocks are color + highlighted according to their hotness. An error is + reported if the primary event is not present in perf + data. + +required arguments: + --cfg CFG The CFG file to annotate. + --perf-data PERF_DATA [PERF_DATA ...] + The perf data files to extract information from. +``` + +### Examples + +Annotate a CFG file: +``` +perf2cfg --cfg art.cfg --perf-data perf.data +``` + +Annotate a CFG file with multiple simpleperf data files: +``` +perf2cfg --cfg art.cfg \ + --perf-data perf_event1.data perf_event2.data perf_event3.data +``` + +Color basic blocks according to cache-misses events: +``` +perf2cfg --cfg art.cfg --perf-data perf.data \ + --primary-event cache-misses +``` + +Display a subset of events from the simpleperf data file: +``` +perf2cfg --cfg art.cfg --perf-data perf.data \ + --events cpu-cycles,cache-misses +``` + +## Method annotations + +Once the annotated CFG file has been opened in c1visualizer, method annotations +can be seen by enabling the "Show Package Names" and "Sort List of +Compilations" options in the top-left "Compiled Methods" panel. + +## Basic block coloring + +perf2cfg implements basic block coloring by adding specific flags to the output +CFG file. These flags have the following names and meanings: +- `LO` (low): the basic block is responsible for 1 to 10% of its method primary + event. +- `MO` (moderate): for 10 to 30%. +- `CO` (considerable): for 30 to 50% +- `HI` (high): for 50 to 100%. + +To use this feature, custom flags have to be defined in c1visualizer: +1. Open c1visualizer. +2. Click on the "Tools" menu entry and "Options" to open the options window. +3. Click on the "Control Flow Graph" button if it isn't already selected. +4. On the right of the "Flags" list, click on the "New" button. +5. Enter "LO" in the text field and press "OK". +6. Select the newly created flag in the list and click on the color picker + button. +7. Select an appropriate color and press "OK". +8. Repeat steps 4 to 7 for the remaining flags (MO, CO, and HI). + +Alternatively, flags can be defined by editing a properties file located at: +`~/.c1visualizer/dev/config/Preferences/at/ssw/visualizer/cfg/options/CfgPreferences.properties`. +The directory hierarchy and the file itself might have to be created. + +Replace the file contents with the following line to use a yellow to red +gradient: +``` +flagsPreference=LO(255,210,0);MO(253,155,5);CO(253,100,5);HI(245,40,5) +``` + +For colorblind people, this green gradient can be used as an alternative: +``` +flagsPreference=LO(235,235,50);MO(210,210,40);CO(185,185,25);HI(155,155,15) +``` + +## Hacking + +A diagram of the finite state machine used to parse the input CFG file can be +generated with the following command (requires Graphviz): +``` +dot -Tpng doc/FSM.dot -o doc/FSM.png +``` |