• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# perf2cfg
2
3perf2cfg annotates a control-flow graph (CFG) file with profiling information
4from simpleperf data files. A CFG file can be generated by the Android Runtime
5compiler using the `--dump-cfg=<cfg-file>` option. The tool outputs an
6annotated CFG file with the following added information:
7- Methods are annotated with their contribution relative to the total profile.
8- Basic blocks and assembly instructions are annotated with their contribution
9  relative to the method profile.
10- Basic blocks are colored according to their contribution to the method
11  profile.
12
13The tool does not modify any input files and assumes the input CFG file can be
14parsed by c1visualizer. The input files must have all been generated for the
15same architecture.
16
17## Usage
18
19```
20usage: perf2cfg [-h|--help] --cfg CFG --perf-data PERF_DATA [PERF_DATA ...]
21                [--output-file OUTPUT_FILE] [-e|--events EVENTS]
22                [--primary-event PRIMARY_EVENT]
23
24Annotates a CFG file with profiling information from simpleperf data files.
25
26optional arguments:
27  -h, --help            Show this help message and exit.
28  --output-file OUTPUT_FILE
29                        A path to the output CFG file.
30  -e EVENTS, --events EVENTS
31                        A comma-separated list of events only to use for
32                        annotating a CFG (default: use all events found in
33                        perf data). An error is reported if the events are not
34                        present in perf data.
35  --primary-event PRIMARY_EVENT
36                        The event to be used for basic blocks hotness analysis
37                        (default: cpu-cycles). Basic blocks are color
38                        highlighted according to their hotness. An error is
39                        reported if the primary event is not present in perf
40                        data.
41
42required arguments:
43  --cfg CFG             The CFG file to annotate.
44  --perf-data PERF_DATA [PERF_DATA ...]
45                        The perf data files to extract information from.
46```
47
48### Examples
49
50Annotate a CFG file:
51```
52perf2cfg --cfg art.cfg --perf-data perf.data
53```
54
55Annotate a CFG file with multiple simpleperf data files:
56```
57perf2cfg --cfg art.cfg \
58    --perf-data perf_event1.data perf_event2.data perf_event3.data
59```
60
61Color basic blocks according to cache-misses events:
62```
63perf2cfg --cfg art.cfg --perf-data perf.data \
64    --primary-event cache-misses
65```
66
67Display a subset of events from the simpleperf data file:
68```
69perf2cfg --cfg art.cfg --perf-data perf.data \
70    --events cpu-cycles,cache-misses
71```
72
73## Method annotations
74
75Once the annotated CFG file has been opened in c1visualizer, method annotations
76can be seen by enabling the "Show Package Names" and "Sort List of
77Compilations" options in the top-left "Compiled Methods" panel.
78
79## Basic block coloring
80
81perf2cfg implements basic block coloring by adding specific flags to the output
82CFG file. These flags have the following names and meanings:
83- `LO` (low): the basic block is responsible for 1 to 10% of its method primary
84  event.
85- `MO` (moderate): for 10 to 30%.
86- `CO` (considerable): for 30 to 50%
87- `HI` (high): for 50 to 100%.
88
89To use this feature, custom flags have to be defined in c1visualizer:
901. Open c1visualizer.
912. Click on the "Tools" menu entry and "Options" to open the options window.
923. Click on the "Control Flow Graph" button if it isn't already selected.
934. On the right of the "Flags" list, click on the "New" button.
945. Enter "LO" in the text field and press "OK".
956. Select the newly created flag in the list and click on the color picker
96   button.
977. Select an appropriate color and press "OK".
988. Repeat steps 4 to 7 for the remaining flags (MO, CO, and HI).
99
100Alternatively, flags can be defined by editing a properties file located at:
101`~/.c1visualizer/dev/config/Preferences/at/ssw/visualizer/cfg/options/CfgPreferences.properties`.
102The directory hierarchy and the file itself might have to be created.
103
104Replace the file contents with the following line to use a yellow to red
105gradient:
106```
107flagsPreference=LO(255,210,0);MO(253,155,5);CO(253,100,5);HI(245,40,5)
108```
109
110For colorblind people, this green gradient can be used as an alternative:
111```
112flagsPreference=LO(235,235,50);MO(210,210,40);CO(185,185,25);HI(155,155,15)
113```
114
115## Hacking
116
117A diagram of the finite state machine used to parse the input CFG file can be
118generated with the following command (requires Graphviz):
119```
120dot -Tpng doc/FSM.dot -o doc/FSM.png
121```
122