Added new perf utility to access CPU counters from userspace
[akaros.git] / Documentation / profiling.txt
1 Akaros Profiling
2 ===========================
3 2015-07-15 Barret Rhoden (brho)
4
5 Contents
6 ---------------------------
7 "Kprof"
8
9 "Kprof"
10 ---------------------------
11 Akaros has a very basic sampling profiler, similar to oprofile.  The kernel
12 generates traces, which you copy off the machine and process on Linux using
13 Linux perf.
14 First build the Akaros kernel:
15
16 / $ make && make xcc-headers-install && make apps-install
17
18 To get started, make sure #K is mounted.  The basic ifconfig script will do
19 this, as will:
20
21 / $ bind -a \#K /prof/
22
23 You control the profiler with the kpctl file.  The general style is to start
24 the events that trigger a sample, such as a timer tick, then you start and stop
25 the profiling.  The distinction between the two steps is that one actually
26 fires the events (e.g. the timer IRQ), and the other enables *collection*
27 of profiling info when those events occur.
28 Aside from timer based sampling, the Akaros `perf` tool allows to sample by
29 catching performance counter overflows.
30 The profiler accepts a few configuration options.
31 There is a queue size limit of 64MB by default, and it is used as circular
32 buffer, so old data will be dropped.
33 To change its value:
34
35 / $ echo prof_qlimit SIZE_KB > /prof/kpctl
36
37 This should be run before starting the profiler.
38
39 It is possible to configure the timer period, which defaults to 1000us, though
40 it is not suggested to move too far from the default:
41
42 / $ echo timer period 1000 > /prof/kpctl
43
44
45                     Timer Base Profiling
46
47 The timer command takes the core id (or "all"), followed by "on" or "off".
48 As with all good devices, if you echo garbage, in, you should get the usage as
49 an errstr.  That'll be kept up to date more than documentation.
50
51 For profiling, besides the counters overflow sampling handled by the `perf`
52 utility, you need to enable timers:
53
54 / $ echo timer all on > /prof/kpctl
55
56 And then start the Akaros profiler system-wide.
57
58 / $ echo start > /prof/kpctl
59
60 Run whatever command you want the sampling to be based on, then stop timers
61 and profiler:
62
63 / $ my_test_program ...
64 / $ echo timer all off > /prof/kpctl
65 / $ echo stop > /prof/kpctl
66
67 The trace will be then available in the /prof/kpdata file.
68 The data will be available until the next start of the profiler.
69
70
71                     Akaros Perf Tool
72
73 The Akaros `perf` is a tool which allows to both programming and reading
74 the CPU performance counters, and enabling counter overflow interrupt based
75 tracing.
76 Its help screen reads like:
77
78 Use: perf {list,cpucaps,record} [-mkecxh] -- CMD [ARGS ...]
79         list            Lists all the available events and their meaning.
80         cpucaps         Shows the system CPU capabilities in term of performance counters.
81         record           Setups the configured counters, runs CMD, and shows the values of the counters.
82 Options:
83         -m PATH          Sets the path of the PERF file ('#arch/perf').
84         -k PATH          Sets the path of the KPROF control file ('/prof/kpctl').
85         -e EVENT_SPEC    Adds an event to be tracked.
86         -c CPUS_STR      Selects the CPU set on which the counters should be active.
87         -x EVENT_RX      Sets the event name regular expression for list.
88         -h               Displays this help screen.
89
90 To list the counters available for sampling, you can run the following command
91 (note, it might be a very long output):
92
93 / $ perf list
94
95 Or, if you have some hint of what you are looking for (example, "FLUSH"), you
96 can run:
97
98 / $ perf list -x FLUSH
99
100 The -x parameter accepts regular expression syntax.
101 To get information about how many counters, and their bit size, are available in
102 the system, you can run:
103
104 / $ perf cpucaps
105
106 Which produces an output like:
107
108 PERF.version             = 2
109 PERF.proc_arch_events    = 7
110 PERF.bits_x_counter      = 48
111 PERF.counters_x_proc     = 4
112 PERF.bits_x_fix_counter  = 48
113 PERF.fix_counters_x_proc = 3
114
115 You need to specify the list of CPUs where the counters will be active, and the
116 CMD passed as `perf` parameter will be run onto.
117 The format of the CPUS_STR is as follow:
118
119   [[!]{all,I[.J]+,N-M}][:...]
120
121 Where:
122   all    = Enable all CPUs
123   llall  = Enable all low latency CPUs
124   I.J.K  = Enable CPUs I, J, and K
125   N-M    = Enable CPUs from N to M, included
126
127 Examples:
128   0.2.4:8-19
129   all:!2.4.8
130
131 Setting up an event, either for simple reading, or for sampling, requires
132 providing the event coordinates (of which, the output emitted by the commands
133 above, will help).
134 The event coordinates come as event ID and event mask couple.
135 They can either be specified by numeric values (example, 0xbd:0x20), or by
136 their name (TLB_FLUSH:STLB_ANY).
137 The format of the -e event specification is as follow:
138
139   {EVENT_ID:MASK,EVENT_NAME:MASK_NAME}[,os[={0,1}]][,usr[={0,1}]]
140     [,int[={0,1}]][,invcmsk[={0,1}]][,cmask=MASK][,icount=COUNT]
141
142 With the following meaning:
143
144   os     = Should the counter tick when in ring 0 (default 1)
145   usr    = Should the counter tick when in ring 1,2,3 (default 1)
146   int    = Should counter overflow interrupt based sampling be enabled (default 0)
147   icount = After how many increments in the counter value, the sampling
148            interrupt should trigger (default 0 - not allowed if int==1)
149
150 After the double hyphen (--), follow the command, and its arguments, to be
151 executed while the sampling is happening.
152 In most cases this could simply be a `sleep` (embedded perf command).
153 Example:
154
155 / $ perf record -e TLB_FLUSH:STLB_ANY,int=1,icount=20 -- sleep 10
156
157 When the command run by `perf` exits, the configured counter values are shown.
158 If used as counter overflow interrupt sampling, the tracing data will be in
159 the usual /prof/kpdata file.
160
161
162
163                     Analyzing Profiler Data
164
165 The profiler tracing data generated in the /prof/kpdata file, needs to be copied
166 on your dev box.
167 The easiest way is via 9p:
168
169 / $ cp /prof/kpdata /mnt/
170
171 Or by using the simple netcat (snc) utility.
172 On your dev box:
173
174 / $ nc -l PORT > kpdata.data
175
176 On Akaros:
177
178 / $ scn -s DEVBOX_IP -p PORT -i /prof/kpdata
179
180 In order to process the Akaros kprof file, you need to convert it to the
181 Linux perf one.
182 You can do that, on your dev box, with:
183
184 / $ ./tools/profile/kprof2perf/kprof2perf-linux -k `pwd`/obj/kern/akaros-kernel-64b -i kpdata.data -o perf.data
185
186 You then need to build the Akaros specific Linux perf binary.
187 First you need to install (if you have not already) libelf-dev:
188
189 \ $ sudo apt-get install libelf-dev
190
191 Then pull the Linux kernel source code which is closer to the kernel
192 version you are running in your dev box, and patch it:
193
194 / $ cd linux
195 / $ patch -p 1 < $AKAROS/tools/profile/kprof2perf/perf_patches/perf_patch.diff
196 / $ cd tools/perf
197 / $ make
198
199 Then you should be able to run Linux perf data analysis command on it:
200 Example:
201
202 $ /PATH_TO/perf --root-dir $AKAROS/kern/kfs/ report -g -i perf.data