callgrind: initial notes

1 files changed, 76 insertions, 0 deletions

diff --git a/src/trace_profile/callgrind.md b/src/trace_profile/callgrind.md
new file mode 100644
index 0000000..1336a9e
--- /dev/null
+++ b/src/trace_profile/callgrind.md
@@ -0,0 +1,76 @@
+# callgrind
+
+Callgrind is a tracing profiler to record the function call history of a target
+program. It is part of the [valgrind][callgrind] tool suite.
+
+Profiling data is collected by instrumentation rather than sampling of the
+target program.
+
+Callgrind does not capture the actual time spent in a function but computes the
+cost of a function based on the instructions fetched (`Ir = Instruction read`).
+Therefore effects like slow IO are not reflected, which should be kept in mind
+when analyzing callgrind results.
+
+By default the profiler data is dumped when the target process is terminating,
+but [callgrind_control] allows for interactive control of callgrind.
+```bash
+# Run a program under callgrind.
+valgrind --tool=callgrind -- <prog>
+
+# Interactive control of callgrind.
+callgrind_control [opts]
+  opts:
+    -b ............. show current backtrace
+    -e ............. show current event counters
+    -s ............. show current stats
+    --dump[=file] .. dump current collection
+    -i=on|off ...... turn instrumentation on|off
+```
+
+Results can be analyzed by using one of the following tools
+- [callgrind_annotate] (cli)
+- [kcachegrind] (ui)
+
+The following is a collection of frequently used callgrind options.
+```bash
+valgrind --tool=callgrind [opts] -- <prog>
+  opts:
+    --callgrind-out-file=<file> .... output file, rather than callgrind.out.<pid>
+    --dump-instr=<yes|no> .......... annotation on instrucion level,
+                                     allows for asm annotations
+
+    --instr-atstart=<yes|no> ....... control if instrumentation is enabled from 
+                                     beginning of the program
+
+    --separate-threads=<yes|no> .... create separate output files per thread,
+                                     appends -<thread_id> to the output file
+```
+
+## Profile specific part of the target
+Programmatically enable/disable instrumentation using the macros defined in
+the callgrind header.
+```c
+#include <valgrind/callgrind.h>
+
+int main() {
+    // init ..
+
+    CALLGRIND_START_INSTRUMENTATION;
+    compute();
+    CALLGRIND_STOP_INSTRUMENTATION;
+
+    // shutdown ..
+}
+```
+> In this case, callgrind should be launched with `--instr-atstart=no`.
+
+Alternatively instrumentation can be controlled with `callgrind_control -i
+on/off`.
+
+The files [cg_example.cc](callgrind/cg_example.cc) and
+[Makefile](callgrind/Makefile) provide a full example.
+
+[callgrind]: https://valgrind.org/docs/manual/cl-manual.html
+[callgrind_annotate]: https://valgrind.org/docs/manual/cl-manual.html#cl-manual.callgrind_annotate-options
+[callgrind_control]: https://valgrind.org/docs/manual/cl-manual.html#cl-manual.callgrind_control-options
+[kcachegrind]: https://kcachegrind.github.io/html/Home.html