From bf1de52de5e1196f566d6b5d5fc3578e56dc4420 Mon Sep 17 00:00:00 2001
From: Robin Gareus <robin@gareus.org>
Date: Tue, 8 Jul 2014 00:22:40 +0200
Subject: [PATCH] update callgrind script and add some doc.

---
 doc/using_callgrind.txt | 49 +++++++++++++++++++++++++++++++++++++++++
 gtk2_ardour/arcall      | 10 ++++++++-
 2 files changed, 58 insertions(+), 1 deletion(-)
 create mode 100644 doc/using_callgrind.txt

diff --git a/doc/using_callgrind.txt b/doc/using_callgrind.txt
new file mode 100644
index 0000000000..b6196b00e0
--- /dev/null
+++ b/doc/using_callgrind.txt
@@ -0,0 +1,49 @@
+Profiling Ardour with Callgrind
+===============================
+
+Prerequisites
+-------------
+
+*  valgrind version 3.7.0 or later (current 3.9.0)
+*  kcachegrind 0.6 or later (current: 0.7.4)
+
+
+Basic Profiling
+---------------
+
+1.  Compile ardour with debug symbols [1].
+2.  `cd gtk2_ardour`
+3.  start ardour using `./arcall`
+
+Load a session, ideally use the 'Dummy' (non realtime) backend.
+
+The `arcall` script does not start profiling immediately,
+to start profiling, in a second terminal run
+
+4. `callgrind_control -i on`
+
+[do operations in Ardour that should be profiled]
+
+5. `callgrind_control -i off`
+
+6. quit ardour
+
+7. run  `kcachegrind calgringd.out.<PID>`
+
+NB. There will be multiple files calgringd.out.<PID>-<Thread-ID> for every run,
+only load the main file without the dash into
+
+8. clean-up: `rm calgringd.out.*`
+
+
+Advanced Usage
+--------------
+
+Edit gtk2_ardour/arcall, add/remove options as needed.
+see http://valgrind.org/docs/manual/cl-manual.html for further information.
+
+---
+
+[1] ideally an optimized built with debug-symbols (-g) is used for profiling,
+however the ardour wscript does not yet offer that configuration option.
+However, a default (non optimized build) does contain debug-symbols.
diff --git a/gtk2_ardour/arcall b/gtk2_ardour/arcall
index 703bc741fd..6045de3303 100755
--- a/gtk2_ardour/arcall
+++ b/gtk2_ardour/arcall
@@ -2,4 +2,12 @@
 . `dirname "$0"`/../build/gtk2_ardour/ardev_common_waf.sh
 LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
 export ARDOUR_RUNNING_UNDER_VALGRIND=TRUE
-exec valgrind  --error-limit=no --num-callers=50 --tool=callgrind $TOP/$EXECUTABLE --novst "$@"
+exec valgrind \
+	--error-limit=no --num-callers=50 \
+	--tool=callgrind \
+	--separate-callers=3 \
+	--separate-threads=yes \
+	--collect-systime=yes \
+	--collect-jumps=yes \
+	--instr-atstart=no \
+	$TOP/$EXECUTABLE --novst "$@"