perf: Remove the perf_patch
[akaros.git] / Documentation / profiling.txt
1 Akaros Profiling
2 ===========================
3
4 Contents:
5
6  (*) Perf
7      - Setup
8      - Example
9      - Somewhat Outdated Notes
10
11  (*) Old Oprofile Notes
12
13
14 ===========================
15 PERF
16 ===========================
17 Akaros has limited support for perf_events.  perf is a tool which utilizes CPU
18 performance counters for performance monitoring and troubleshooting.
19
20 Akaros has its own version of perf, similar in spirit to Linux's perf, that
21 produces PERFILE2 ABI compliant perf.data files (if not, file a bug!).  The
22 kernel generates traces, under the direction of perf.  You then copy the traces
23 to a Linux host and process using Linux's perf.
24
25
26 SETUP
27 --------------------
28 To build Akaros's perf directly:
29
30 (linux)$ cd tools/profile/perf ; make ; cd -
31
32 Or to build it along with all apps:
33
34 (linux)$ make apps-install
35
36 You will also need suitable recent Linux perf for the reporting of the data
37 (something that understands PERFILE2 format).  Unpatched Linux 4.5 perf did the
38 trick.  You'll also want libelf and maybe other libraries.
39
40 First, install libelf according to your distro.  On ubuntu:
41 (linux) $ sudo apt-get install libelf-dev
42
43 Then try to just install perf using your Linux distro, and install any needed
44 dependencies.  On ubuntu, you can install linux-tools-common and whatever else
45 it asks for (something particular to your host kernel).
46
47 If you get the following error when running perf record:
48
49         incompatible file format (rerun with -v to learn more)
50
51 Then you'll need a newer version of perf.  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 You should be able to do the following:
64
65 / $ perf record -e 0x13c:0,int=1,icount=10000 -- /bin/hello
66
67 Then scp perf.data to Linux
68
69 (linux) $ perf report --kallsyms=obj/kern/ksyms.map --symfs=kern/kfs
70
71
72 SOMEWHAT OUTDATED NOTES
73 --------------------
74 Its help screen reads like:
75
76 Use: perf {list,cpucaps,record} [-mkecxh] -- CMD [ARGS ...]
77         list            Lists all the available events and their meaning.
78         cpucaps         Shows the system CPU capabilities in term of performance counters.
79         record           Setups the configured counters, runs CMD, and shows the values of the counters.
80 Options:
81         -m PATH          Sets the path of the PERF file ('#arch/perf').
82         -k PATH          Sets the path of the KPROF control file ('/prof/kpctl').
83         -e EVENT_SPEC    Adds an event to be tracked.
84         -c CPUS_STR      Selects the CPU set on which the counters should be active.
85         -x EVENT_RX      Sets the event name regular expression for list.
86         -h               Displays this help screen.
87
88 To list the counters available for sampling, you can run the following command
89 (note, it might be a very long output):
90
91 / $ perf list
92
93 Or, if you have some hint of what you are looking for (example, "FLUSH"), you
94 can run:
95
96 / $ perf list -x FLUSH
97
98 The -x parameter accepts regular expression syntax.
99 To get information about how many counters, and their bit size, are available in
100 the system, you can run:
101
102 / $ perf cpucaps
103
104 Which produces an output like:
105
106 PERF.version             = 2
107 PERF.proc_arch_events    = 7
108 PERF.bits_x_counter      = 48
109 PERF.counters_x_proc     = 4
110 PERF.bits_x_fix_counter  = 48
111 PERF.fix_counters_x_proc = 3
112
113 You need to specify the list of CPUs where the counters will be active, and the
114 CMD passed as `perf` parameter will be run onto.
115 The format of the CPUS_STR is as follow:
116
117   [[!]{all,I[.J]+,N-M}][:...]
118
119 Where:
120   all    = Enable all CPUs
121   llall  = Enable all low latency CPUs
122   I.J.K  = Enable CPUs I, J, and K
123   N-M    = Enable CPUs from N to M, included
124
125 Examples:
126   0.2.4:8-19
127   all:!2.4.8
128
129 Setting up an event, either for simple reading, or for sampling, requires
130 providing the event coordinates (of which, the output emitted by the commands
131 above, will help).
132 The event coordinates come as event ID and event mask couple.
133 They can either be specified by numeric values (example, 0xbd:0x20), or by
134 their name (TLB_FLUSH:STLB_ANY).
135 The format of the -e event specification is as follow:
136
137   {EVENT_ID:MASK,EVENT_NAME:MASK_NAME}[,os[={0,1}]][,usr[={0,1}]]
138     [,int[={0,1}]][,invcmsk[={0,1}]][,cmask=MASK][,icount=COUNT]
139
140 With the following meaning:
141
142   os     = Should the counter tick when in ring 0 (default 1)
143   usr    = Should the counter tick when in ring 1,2,3 (default 1)
144   int    = Should counter overflow interrupt based sampling be enabled (default 0)
145   icount = After how many increments in the counter value, the sampling
146            interrupt should trigger (default 0 - not allowed if int==1)
147
148 After the double hyphen (--), follow the command, and its arguments, to be
149 executed while the sampling is happening.
150 In most cases this could simply be a `sleep` (embedded perf command).
151 Example:
152
153 / $ perf record -e TLB_FLUSH:STLB_ANY,int=1,icount=20 -- sleep 10
154
155 When the command run by `perf` exits, the configured counter values are shown.
156 If used as counter overflow interrupt sampling, the tracing data will be in
157 the usual /prof/kpdata file.
158
159 ===========================
160 OLD OPROFILE (probably broken)
161 ===========================
162
163 To get started, make sure #K is mounted.  The basic ifconfig script will do
164 this, as will:
165
166 / $ bind -a \#K /prof/
167
168 You control the profiler with the kpctl file.  The general style is to start
169 the events that trigger a sample, such as a timer tick, then you start and stop
170 the profiling.  The distinction between the two steps is that one actually
171 fires the events (e.g. the timer IRQ), and the other enables *collection*
172 of profiling info when those events occur.
173
174 Aside from timer based sampling, the Akaros `perf` tool allows to sample by
175 catching performance counter overflows.
176
177 The profiler accepts a few configuration options.  There is a queue size limit
178 of 64MB by default, and it is used as circular buffer, so old data will be
179 dropped.
180
181 To change its value:
182
183 / $ echo prof_qlimit SIZE_KB > /prof/kpctl
184
185 This should be run before starting the profiler.
186
187 It is possible to configure the timer period, which defaults to 1000us, though
188 it is not suggested to move too far from the default:
189
190 / $ echo timer period 1000 > /prof/kpctl
191
192
193 The timer command takes the core id (or "all"), followed by "on" or "off".
194 As with all good devices, if you echo garbage, in, you should get the usage as
195 an errstr.  That'll be kept up to date more than documentation.
196
197 For profiling, besides the counters overflow sampling handled by the `perf`
198 utility, you need to enable timers:
199
200 / $ echo timer all on > /prof/kpctl
201
202 And then start the Akaros profiler system-wide.
203
204 / $ echo start > /prof/kpctl
205
206 Run whatever command you want the sampling to be based on, then stop timers
207 and profiler:
208
209 / $ my_test_program ...
210 / $ echo stop > /prof/kpctl
211 / $ echo timer all off > /prof/kpctl
212
213 The trace will be then available in the /prof/kpdata file.
214 The data will be available until the next start of the profiler.