Remove the BUILD_INFO_FILE variable
[akaros.git] / Documentation / profiling.txt
index 92f1171..160a898 100644 (file)
 Akaros Profiling
 ===========================
 Akaros Profiling
 ===========================
-2015-07-15 Barret Rhoden (brho)
 
 
-Contents
----------------------------
-"Kprof"
+Contents:
 
 
-"Kprof"
----------------------------
-Akaros has a very basic sampling profiler, similar to oprofile.  The kernel
-generates traces, which you copy off the machine and process on Linux using
-Linux perf.
-First build the Akaros kernel:
+ (*) Perf
+     - Setup
+     - Example
+     - Somewhat Outdated Notes
 
 
-/ $ make && make xcc-headers-install && make apps-install
+ (*) Old Oprofile Notes
+
+
+===========================
+PERF
+===========================
+Akaros has limited support for perf_events.  perf is a tool which utilizes CPU
+performance counters for performance monitoring and troubleshooting.
+
+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:
+
+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.
+
+To list the counters available for sampling, you can run the following command
+(note, it might be a very long output):
+
+/ $ perf list
+
+Or, if you have some hint of what you are looking for (example, "FLUSH"), you
+can run:
+
+/ $ perf list -x FLUSH
+
+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:
+
+/ $ perf cpucaps
+
+Which produces an output like:
+
+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
+
+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:
+
+  [[!]{all,I[.J]+,N-M}][:...]
+
+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
+
+Examples:
+  0.2.4:8-19
+  all:!2.4.8
+
+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:
 
 To get started, make sure #K is mounted.  The basic ifconfig script will do
 this, as will:
@@ -26,81 +171,44 @@ 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.
 
 fires the events (e.g. the timer IRQ), and the other enables *collection*
 of profiling info when those events occur.
 
-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.
-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.
+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.
 To change its value:
 
 / $ echo prof_qlimit SIZE_KB > /prof/kpctl
 
 This should be run before starting the profiler.
-There is a limit of the maximum call strace dept, by default 16.
-To change it:
-
-/ $ echo prof_btdepth DEPTH > /prof/kpctl
 
 
-This should be run before starting the profiler as well.
 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
 
 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
 
-And then start the Akaros profiler system-wide.
-
-/ $ echo start > /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
-
-Run whatever command you want, then stop the profiler.
-
-/ $ foo
-/ $ echo stop > /prof/kpctl
-
-The trace will be then available in the /prof/kpdata file.
-The data will be available until the next start of the profiler.
-Then copy this on your dev box.
-The easiest way is via 9p:
-
-/ $ cp /prof/kpdata /mnt/
-
-Or by using the simple netcat (snc) utility.
-On your dev box:
-
-/ $ nc -l PORT > kpdata.data
-
-On Akaros:
-
-/ $ scn -s DEVBOX_IP -p PORT -i /prof/kpdata
 
 
-In order to process the Akaros kprof file, you need to convert it to the
-Linux perf one.
-You can do that, on your dev box, with:
+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.
 
 
-/ $ ./tools/profile/kprof2perf/kprof2perf-linux -k `pwd`/obj/kern/akaros-kernel-64b -i kpdata.data -o perf.data
+For profiling, besides the counters overflow sampling handled by the `perf`
+utility, you need to enable timers:
 
 
-You then need to build the Akaros specific Linux perf binary.
-First you need to install (if you have not already) libelf-dev:
+/ $ echo timer all on > /prof/kpctl
 
 
-\ $ sudo apt-get install libelf-dev
+And then start the Akaros profiler system-wide.
 
 
-Then pull the Linux kernel source code which is closer to the kernel
-version you are running in your dev box, and patch it:
+/ $ echo start > /prof/kpctl
 
 
-/ $ cd linux
-/ $ patch -p 1 < $AKAROS/tools/profile/kprof2perf/perf_patches/perf_patch.diff
-/ $ cd tools/perf
-/ $ make
+Run whatever command you want the sampling to be based on, then stop timers
+and profiler:
 
 
-Then you should be able to run Linux perf data analysis command on it:
-Example:
+/ $ my_test_program ...
+/ $ echo stop > /prof/kpctl
+/ $ echo timer all off > /prof/kpctl
 
 
-$ /PATH_TO/perf --root-dir $AKAROS/kern/kfs/ report -g -i perf.data
+The trace will be then available in the /prof/kpdata file.
+The data will be available until the next start of the profiler.