Remove the BUILD_INFO_FILE variable
[akaros.git] / Documentation / profiling.txt
index 0216597..160a898 100644 (file)
 Akaros Profiling
 ===========================
 Akaros Profiling
 ===========================
-2015-07-15 Barret Rhoden (brho)
 
 
-Contents
----------------------------
-"Oprofile"
+Contents:
 
 
-"Oprofile"
----------------------------
-Akaros has a very basic sampling profiler, similar to oprofile.  The kernel
-generates traces, which you copy off the machine and process on Linux.
+ (*) Perf
+     - Setup
+     - Example
+     - Somewhat Outdated Notes
 
 
-To get started, make sure #K is mounted.  The basic ifconfig script will do
-this, as will:
+ (*) Old Oprofile Notes
 
 
-/ $ bind -a \#K /prof/
 
 
-You control the profiler with the kpctl file.  The general style is to start
-the events that trigger a sample, such as a timer tick, then you start and stop
-the profiling.  The distinction between the two steps is that one actually
-fires the events (e.g. the timer IRQ), and the other enables *collection* of profiling info when those events occur.
+===========================
+PERF
+===========================
+Akaros has limited support for perf_events.  perf is a tool which utilizes CPU
+performance counters for performance monitoring and troubleshooting.
 
 
-The optimer command takes the core id (or "all"), followed by "on" or "off".
-As with all good devices, if you echo garbage, in, you should get the usage as
-an errstr.  That'll be kept up to date more than documentation.
+Akaros has its own version of perf, similar in spirit to Linux's perf, that
+produces PERFILE2 ABI compliant perf.data files (if not, file a bug!).  The
+kernel generates traces, under the direction of perf.  You then copy the traces
+to a Linux host and process using Linux's perf.
+
+
+SETUP
+--------------------
+To build Akaros's perf directly:
+
+(linux)$ cd tools/profile/perf ; make ; cd -
+
+Or to build it along with all apps:
+
+(linux)$ make apps-install
+
+You will also need suitable recent Linux perf for the reporting of the data
+(something that understands PERFILE2 format).  Unpatched Linux 4.5 perf did the
+trick.  You'll also want libelf and maybe other libraries.
+
+First, install libelf according to your distro.  On ubuntu:
+(linux) $ sudo apt-get install libelf-dev
+
+Then try to just install perf using your Linux distro, and install any needed
+dependencies.  On ubuntu, you can install linux-tools-common and whatever else
+it asks for (something particular to your host kernel).
+
+If you get the following error when running perf record:
+
+       incompatible file format (rerun with -v to learn more)
+
+Then you'll need a newer version of perf.  Download Linux source, then
+
+(linux) $ cd tools/perf/
+(linux) $ make
+
+Then use your new perf binary.  This all is just installing a recent perf - it
+has little to do with Akaros at this point.  If you run into incompatibilities
+between our perf.data format and the latest Linux, file a bug.
+
+
+BASIC EXAMPLE
+--------------------
+You should be able to do the following:
+
+/ $ perf record -e 0x13c:0,int=1,icount=10000 -- /bin/hello
+
+Then scp perf.data to Linux
+
+(linux) $ perf report --kallsyms=obj/kern/ksyms.map --symfs=kern/kfs
+
+
+SOMEWHAT OUTDATED NOTES
+--------------------
+Its help screen reads like:
 
 
-/ $ echo garbage > /prof/kpctl
-echo failed: Unspecified, startclr|start|stop|clear|opstart|opstop|optimer
+Use: perf {list,cpucaps,record} [-mkecxh] -- CMD [ARGS ...]
+        list            Lists all the available events and their meaning.
+        cpucaps         Shows the system CPU capabilities in term of performance counters.
+        record           Setups the configured counters, runs CMD, and shows the values of the counters.
+Options:
+        -m PATH          Sets the path of the PERF file ('#arch/perf').
+        -k PATH          Sets the path of the KPROF control file ('/prof/kpctl').
+        -e EVENT_SPEC    Adds an event to be tracked.
+        -c CPUS_STR      Selects the CPU set on which the counters should be active.
+        -x EVENT_RX      Sets the event name regular expression for list.
+        -h               Displays this help screen.
 
 
-/ $ echo optimer garbage > /prof/kpctl
-echo failed: Unspecified, optimer [<0|1|..|n|all> <on|off>] [period USEC]
+To list the counters available for sampling, you can run the following command
+(note, it might be a very long output):
 
 
-Let's set up the timer on core 0:
+/ $ perf list
 
 
-/ $ echo optimer 0 on > /prof/kpctl
+Or, if you have some hint of what you are looking for (example, "FLUSH"), you
+can run:
 
 
-And then start oprofile system-wide.
+/ $ perf list -x FLUSH
 
 
-/ $ echo opstart > /prof/kpctl
-Enable tracing on 0
-Enable tracing on 1
-Enable tracing on 2
-Enable tracing on 3
-Enable tracing on 4
-Enable tracing on 5
-Enable tracing on 6
-Enable tracing on 7
+The -x parameter accepts regular expression syntax.
+To get information about how many counters, and their bit size, are available in
+the system, you can run:
 
 
-Run whatever command you want, then stop the profiler.
+/ $ perf cpucaps
 
 
-/ $ foo
-/ $ echo opstop > /prof/kpctl
-Core 0 has data
-After qibwrite in oprofile_cpubuf_flushone, opq len 303080
+Which produces an output like:
 
 
-Might as well turn off the timers:
-/ $ echo optimer all off > /prof/kpctl
+PERF.version             = 2
+PERF.proc_arch_events    = 7
+PERF.bits_x_counter      = 48
+PERF.counters_x_proc     = 4
+PERF.bits_x_fix_counter  = 48
+PERF.fix_counters_x_proc = 3
 
 
-Now we need to extract the trace.  The easiest way is via 9p.
-/ $ cat /prof/kpoprofile > trace
-/ $ cp trace /mnt/
+You need to specify the list of CPUs where the counters will be active, and the
+CMD passed as `perf` parameter will be run onto.
+The format of the CPUS_STR is as follow:
 
 
-Once the trace has been read from kpoprofile, it cannot be read again.  The
-read drains the kernel's trace buffer.
+  [[!]{all,I[.J]+,N-M}][:...]
 
 
-The trace that the kernel generates is in an Akaros-specific format.  There is
-a go program at tools/profile/op2.go that translates from the Akaros format to
-pprof format.  You could run this on Akaros, since we support Go programs, but
-since we don't have a port of pprof, it's easier to do it all in Linux.
+Where:
+  all    = Enable all CPUs
+  llall  = Enable all low latency CPUs
+  I.J.K  = Enable CPUs I, J, and K
+  N-M    = Enable CPUs from N to M, included
 
 
-So now we're in linux, and say our 9p ufs server is rooted at mnt/netroot/.  Run op2:
+Examples:
+  0.2.4:8-19
+  all:!2.4.8
 
 
-(linux) $ op2 < mnt/netroot/trace > trace-pp
+Setting up an event, either for simple reading, or for sampling, requires
+providing the event coordinates (of which, the output emitted by the commands
+above, will help).
+The event coordinates come as event ID and event mask couple.
+They can either be specified by numeric values (example, 0xbd:0x20), or by
+their name (TLB_FLUSH:STLB_ANY).
+The format of the -e event specification is as follow:
+
+  {EVENT_ID:MASK,EVENT_NAME:MASK_NAME}[,os[={0,1}]][,usr[={0,1}]]
+    [,int[={0,1}]][,invcmsk[={0,1}]][,cmask=MASK][,icount=COUNT]
+
+With the following meaning:
+
+  os     = Should the counter tick when in ring 0 (default 1)
+  usr    = Should the counter tick when in ring 1,2,3 (default 1)
+  int    = Should counter overflow interrupt based sampling be enabled (default 0)
+  icount = After how many increments in the counter value, the sampling
+           interrupt should trigger (default 0 - not allowed if int==1)
+
+After the double hyphen (--), follow the command, and its arguments, to be
+executed while the sampling is happening.
+In most cases this could simply be a `sleep` (embedded perf command).
+Example:
+
+/ $ perf record -e TLB_FLUSH:STLB_ANY,int=1,icount=20 -- sleep 10
+
+When the command run by `perf` exits, the configured counter values are shown.
+If used as counter overflow interrupt sampling, the tracing data will be in
+the usual /prof/kpdata file.
+
+===========================
+OLD OPROFILE (probably broken)
+===========================
+
+To get started, make sure #K is mounted.  The basic ifconfig script will do
+this, as will:
+
+/ $ bind -a \#K /prof/
+
+You control the profiler with the kpctl file.  The general style is to start
+the events that trigger a sample, such as a timer tick, then you start and stop
+the profiling.  The distinction between the two steps is that one actually
+fires the events (e.g. the timer IRQ), and the other enables *collection*
+of profiling info when those events occur.
+
+Aside from timer based sampling, the Akaros `perf` tool allows to sample by
+catching performance counter overflows.
+
+The profiler accepts a few configuration options.  There is a queue size limit
+of 64MB by default, and it is used as circular buffer, so old data will be
+dropped.
+
+To change its value:
+
+/ $ echo prof_qlimit SIZE_KB > /prof/kpctl
+
+This should be run before starting the profiler.
+
+It is possible to configure the timer period, which defaults to 1000us, though
+it is not suggested to move too far from the default:
+
+/ $ echo timer period 1000 > /prof/kpctl
+
+
+The timer command takes the core id (or "all"), followed by "on" or "off".
+As with all good devices, if you echo garbage, in, you should get the usage as
+an errstr.  That'll be kept up to date more than documentation.
 
 
-To get a sense for what the trace holds, you might want to start with looking at the raw addresses to distinguish between the kernel and the user.
+For profiling, besides the counters overflow sampling handled by the `perf`
+utility, you need to enable timers:
 
 
-(linux) $ pprof --addresses trace-pp
-PPROF> top
-       (shows some addresses)
+/ $ echo timer all on > /prof/kpctl
 
 
-Say the majority of the addresses are user addresses:
+And then start the Akaros profiler system-wide.
 
 
-(linux) $ pprof obj/tests/foo trace-pp
-PPROF> top
-       (shows some functions)
+/ $ echo start > /prof/kpctl
 
 
-Or you can visualize things:
-(linux) $ pprof --evince obj/tests/foo trace-pp
+Run whatever command you want the sampling to be based on, then stop timers
+and profiler:
 
 
-The visualization is not of much user for user programs, since the kernel does
-not record backtraces for userspace by default.  It's a little dangerous at the
-moment.  In the future, we may have an op option to control whether or not the
-kernel attempts a backtrace.
+/ $ my_test_program ...
+/ $ echo stop > /prof/kpctl
+/ $ echo timer all off > /prof/kpctl
 
 
-For more info on pprof, check out:
-http://gperftools.googlecode.com/svn/trunk/doc/cpuprofile.html
+The trace will be then available in the /prof/kpdata file.
+The data will be available until the next start of the profiler.