Use two-page stacks
[akaros.git] / Documentation / profiling.txt
1 Akaros Profiling
2 ===========================
3
4 Contents:
5
6  (*) Perf
7      - Setup
8      - Example
9      - More Complicated Examples
10      - Differences From Linux
11
12  (*) mpstat
13
14
15 ===========================
16 PERF
17 ===========================
18 Akaros has limited support for perf_events.  perf is a tool which utilizes CPU
19 performance counters for performance monitoring and troubleshooting.
20
21 Akaros has its own version of perf, similar in spirit to Linux's perf, that
22 produces PERFILE2 ABI compliant perf.data files (if not, file a bug!).  The
23 kernel generates traces, under the direction of perf.  You then copy the traces
24 to a Linux host and process using Linux's perf.
25
26
27 SETUP
28 --------------------
29 To build Akaros's perf directly:
30
31 (linux)$ cd tools/dev-libs/elfutils ; make install; cd -
32 (linux)$ cd tools/dev-util/perf ; make install; cd -
33
34 Or to build it along with all apps:
35
36 (linux)$ make apps-install
37
38 You will also need suitable recent Linux perf for the reporting of the data
39 (something that understands PERFILE2 format).  Unpatched Linux 4.5 perf did the
40 trick.  You'll also want libelf and maybe other libraries on your Linux
41 machine.
42
43 First, install libelf according to your distro.  On ubuntu:
44 (linux) $ sudo apt-get install libelf-dev
45
46 Then try to just install perf using your Linux distro, and install any needed
47 dependencies.  On ubuntu, you can install linux-tools-common and whatever else
48 it asks for (something particular to your host kernel).
49
50 Linux perf changes a lot.  Newer versions are usually nicer.  I recommend
51 building one of them:  Download Linux source, then
52
53 (linux) $ cd tools/perf/
54 (linux) $ make
55
56 Then use your new perf binary.  This all is just installing a recent perf - it
57 has little to do with Akaros at this point.  If you run into incompatibilities
58 between our perf.data format and the latest Linux, file a bug.
59
60
61 BASIC EXAMPLE
62 --------------------
63 Perf on Akaros supports record, stat, and a few custom options.
64
65 You should be able to do the following:
66
67 / $ perf record ls
68
69 Then scp perf.data to Linux
70
71 (linux) $ scp AKAROS_MACHINE:perf.data .
72 (linux) $ perf report --kallsyms=obj/kern/ksyms.map --symfs=kern/kfs/
73
74 Perf will look on your host machine for the kernel symbol table and for
75 binaries.  We need to tell it kallsyms and symfs to override those settings.
76
77 It can be a hassle to type out the kallsyms and symfs, so we have a script that
78 will automate that.  Use scripts/perf in any place that you'd normally use
79 perf.  Set your $AKAROS_ROOT (default is ".") and optionally override $PERF_CMD
80 ("default is "perf").  For most people, this will just be:
81
82 (linux) $ ./scripts/perf report
83
84 The perf.data file is implied, so the above command is equivalent to:
85
86 (linux) $ ./scripts/perf report -i perf.data
87
88
89 MORE COMPLICATED EXAMPLES
90 --------------------
91 First, try perf --help for usage.  Then check out
92 https://perf.wiki.kernel.org/index.php/Tutorial.  We strive to be mostly
93 compatible with the usage of Linux perf.
94
95 perf stat runs a command and reports the count of events during the run of the
96 command.  perf record runs a command and outputs perf.data, which contains
97 backtrace samples from when the event counters overflowed.  For those familiar
98 with other perfmon systems, perf stat is like PAPI and perf record is like
99 Oprofile.
100
101 perf record and stat both track a set of events with the -e flag.  -e takes a
102 comma-separated list of events.  Events can be expressed in one of three forms:
103
104 - Generic events (called "pre-defined" events on Linux)
105 - Libpfm events
106 - Raw events
107
108 Linux's perf only takes Generic and Raw events, so the libpfm4 is an added
109 bonus.
110
111 Generic events consist of strings like "cycles" or "cache-misses".  Raw events
112 aresimple strings of the form "rXXX", where the X's are hex nibbles.  The hex
113 codes are passed directly to the PMU.  You can actually have 2-4 Xs on Akaros.
114
115 Libpfm events are strings that correspond to events specific to your machine.
116 Libpfm knows about PMU events for a given machine.  It figures out what machine
117 perf is running on and selects events that should be available.  Check out
118 http://perfmon2.sourceforge.net/ for more info.
119
120 To see the list of events available, use `perf list [regex]`, supplying an
121 optional search regex.  For example, on a Haswell:
122
123 / $ perf list unhalted_reference_cycles
124 #-----------------------------
125 IDX      : 37748738
126 PMU name : ix86arch (Intel X86 architectural PMU)
127 Name     : UNHALTED_REFERENCE_CYCLES
128 Equiv    : None
129 Flags    : None
130 Desc     : count reference clock cycles while the clock signal on the specific core is running. The reference clock operates at a fixed frequency, irrespective of c
131 ore frequency changes due to performance state transitions
132 Code     : 0x13c
133 Modif-00 : 0x00 : PMU : [k] : monitor at priv level 0 (boolean)
134 Modif-01 : 0x01 : PMU : [u] : monitor at priv level 1, 2, 3 (boolean)
135 Modif-02 : 0x02 : PMU : [e] : edge level (may require counter-mask >= 1) (boolean)
136 Modif-03 : 0x03 : PMU : [i] : invert (boolean)
137 Modif-04 : 0x04 : PMU : [c] : counter-mask in range [0-255] (integer)
138 Modif-05 : 0x05 : PMU : [t] : measure any thread (boolean)
139 #-----------------------------
140 IDX      : 322961409
141 PMU name : hsw_ep (Intel Haswell EP)
142 Name     : UNHALTED_REFERENCE_CYCLES
143 Equiv    : None
144 Flags    : None
145 Desc     : Unhalted reference cycles
146 Code     : 0x300
147 Modif-00 : 0x00 : PMU : [k] : monitor at priv level 0 (boolean)
148 Modif-01 : 0x01 : PMU : [u] : monitor at priv level 1, 2, 3 (boolean)
149 Modif-02 : 0x05 : PMU : [t] : measure any thread (boolean)
150
151 There are two different events for UNHALTED_REFERENCE_CYCLES (case
152 insensitive).  libpfm will select the most appropriate one.  You can override
153 this selection by specifying a PMU:
154
155 / $ perf stat -e ix86arch::UNHALTED_REFERENCE_CYCLES ls
156
157 Here's how to specify multiple events:
158
159 / $ perf record -e cycles,instructions ls
160
161 Events also take a set of modifiers.  For instance, you can specify running
162 counters only in kernel mode or user mode.  Modifiers are separated by a ':'.
163
164 This will track only user cycles (default is user and kernel):
165
166 / $ perf record -e cycles:u ls
167
168 To use a raw event, you need to know the event number.  You can either look in
169 your favorite copy of the SDM, or you can ask libpfm.  Though if you ask
170 libpfm, you might as well just use its string processing.  For example:
171
172 / $ perf list FLUSH
173 #-----------------------------
174 IDX      : 322961462
175 PMU name : hsw_ep (Intel Haswell EP)
176 Name     : TLB_FLUSH
177 Equiv    : None
178 Flags    : None
179 Desc     : TLB flushes
180 Code     : 0xbd
181 Umask-00 : 0x01 : PMU : [DTLB_THREAD] : None : Count number of DTLB flushes of thread-specific entries
182 Umask-01 : 0x20 : PMU : [STLB_ANY] : None : Count number of any STLB flushes
183 Modif-00 : 0x00 : PMU : [k] : monitor at priv level 0 (boolean)
184 Modif-01 : 0x01 : PMU : [u] : monitor at priv level 1, 2, 3 (boolean)
185 Modif-02 : 0x02 : PMU : [e] : edge level (may require counter-mask >= 1) (boolean)
186 Modif-03 : 0x03 : PMU : [i] : invert (boolean)
187 Modif-04 : 0x04 : PMU : [c] : counter-mask in range [0-255] (integer)
188 Modif-05 : 0x05 : PMU : [t] : measure any thread (boolean)
189 Modif-06 : 0x07 : PMU : [intx] : monitor only inside transactional memory region (boolean)
190 Modif-07 : 0x08 : PMU : [intxcp] : do not count occurrences inside aborted transactional memory region (boolean)
191
192 The raw code is 0xbd.  So the following are equivalent (but slightly buggy!):
193
194 / $ perf stat -e TLB_FLUSH ls
195 / $ perf stat -e rbd ls
196
197 If you actually run those, rbd will have zero hits, and TLB_FLUSH will give you
198 the error "Failed to parse event string TLB_FLUSH".
199
200 Some events actually rather particular to their Umasks, and TLB_FLUSH is one of
201 them.  TLB_FLUSH wants a Umask.  Umasks are selectors for specific sub-types of
202 events.  In the case of TLB_FLUSH, we can choose between DTLB_THREAD and
203 STLB_ANY.  Umasks are not always required - they just happen to be on my
204 Haswell for TLB_FLUSH.  That being said, we can ask for the event like so:
205
206 / $ perf stat -e TLB_FLUSH:STLB_ANY ls
207 / $ perf stat -e r20bd ls
208
209 Note that the Umask is placed before the Code.  These 16 bits are passed
210 directly to the PMU, and on Intel the format is "umask:event".
211
212 perf record is based on recording samples when event counters overflow.  The
213 number of events required to trigger a sample is referred to as the
214 sample_period.  You can set it with -c, e.g.
215
216 / $ perf record -c 10000 ls
217
218
219 DIFFERENCES FROM LINUX
220 --------------------
221 For the most part, Akaros perf is similar to Linux.  A few things are
222 different.
223
224 The biggest difference is that our perf does not follow processes around.  We
225 count events for cores, not processes.  You can specify certain cores, but not
226 certain processes.  Any options related to tracking specific processes are
227 unsupported.
228
229 The -F option (frequency) is loosely supported.  The kernel cannot adjust the
230 sampling count dynamically to meet a certain frequencey.  Instead, we guess
231 that -F is used with cycles, and pick a sample period that will generate
232 samples at the desired frequency if the core is unhalted.  YMMV.
233
234 Akaros currently supports only PMU events.  In the future, we may add events
235 like context-switches.
236
237
238 ===========================
239 mpstat
240 ===========================
241 Akaros has basic support for mpstat.  mpstat gives a high-level glance at where
242 each core is spending its time.
243
244 For starters, bind kprof somewhere.  The basic ifconfig script binds it to
245 /prof.
246
247 To see the CPU usage, cat mpstat:
248
249 / $ cat /prof/mpstat
250  CPU:             irq             kern              user                 idle
251    0: 1.707136 (  0%), 24.978659 (  0%), 0.162845 (  0%), 13856.233909 ( 99%)
252
253 To reset the count:
254
255 / $ echo reset > /prof/mpstat
256
257 To see the output for a particular command:
258
259 / $ echo reset > /prof/mpstat ; COMMAND ; cat /prof/mpstat