profiler documentation

2 files changed, 183 insertions, 0 deletions

diff --git a/doc/estp.txt b/doc/estp.txt
new file mode 100644
index 000000000..a3cbee516
--- /dev/null
+++ b/doc/estp.txt
@@ -0,0 +1,180 @@
+============================================

+  Embedded Stack Trace Profiler User Guide

+============================================

+

+:Author: Andreas Rumpf

+:Version: |nimrodversion|

+

+

+Nimrod comes with a platform independent profiler -

+the `Embedded Stack Trace Profiler`:idx: (`ESTP`:idx:). The profiler 
+is *embedded* into your executable. To activate the profiler you need to do: 
+
+* compile your program with the ``--profiler:on --stackTrace:on`` command 
+  line options
+* import the ``nimprof`` module
+* run your program as usual.
+
+You can in fact look at ``nimprof``'s source code to see how to implement 
+your own profiler.
+

+The setting ``--profiler:on`` defines the conditional symbol ``profiler``.

+

+After your program has finished the profiler will create a 
+file ``profile_resultsX.txt``(where ``X`` is a previously unused number) 
+containing the profiling results.
+
+Since the profiler works by examining stack traces, it's essential that
+the option ``--stackTrace:on`` is active! Unfortunately this means that a 
+profiling build is much slower than a release build.
+
+
+Example results file
+====================
+
+The results file lists stack traces ordered by significance. 
+
+The following example file has been generated by profiling the Nimrod compiler
+itself: It shows that in total 4.1% of the runtime has been spent 
+in ``crcFromRope`` or its children.
+
+In general the stack traces show you immediately where the problem is because
+the trace acts like an explanation; in traditional profilers you can only find
+expensive leaf functions easily but the *reason* why they are invoked 
+often remains mysterious.
+
+::
+  total executions of each stack trace:
+  Entry: 0/3391 Calls: 84/4160 = 2.0% [sum: 84; 84/4160 = 2.0%]
+    newCrcFromRopeAux
+    crcFromRope
+    writeRopeIfNotEqual
+    shouldRecompile
+    writeModule
+    myClose
+    closePasses
+    processModule
+    CompileModule
+    CompileProject
+    CommandCompileToC
+    MainCommand
+    HandleCmdLine
+    nimrod
+  Entry: 1/3391 Calls: 46/4160 = 1.1% [sum: 130; 130/4160 = 3.1%]
+    updateCrc32
+    newCrcFromRopeAux
+    crcFromRope
+    writeRopeIfNotEqual
+    shouldRecompile
+    writeModule
+    myClose
+    closePasses
+    processModule
+    CompileModule
+    CompileProject
+    CommandCompileToC
+    MainCommand
+    HandleCmdLine
+    nimrod
+  Entry: 2/3391 Calls: 41/4160 = 0.99% [sum: 171; 171/4160 = 4.1%]
+    updateCrc32
+    updateCrc32
+    newCrcFromRopeAux
+    crcFromRope
+    writeRopeIfNotEqual
+    shouldRecompile
+    writeModule
+    myClose
+    closePasses
+    processModule
+    CompileModule
+    CompileProject
+    CommandCompileToC
+    MainCommand
+    HandleCmdLine
+    nimrod
+  Entry: 3/3391 Calls: 41/4160 = 0.99% [sum: 212; 212/4160 = 5.1%]
+    crcFromFile
+    writeRopeIfNotEqual
+    shouldRecompile
+    writeModule
+    myClose
+    closePasses
+    processModule
+    CompileModule
+    CompileProject
+    CommandCompileToC
+    MainCommand
+    HandleCmdLine
+    nimrod
+  Entry: 4/3391 Calls: 41/4160 = 0.99% [sum: 253; 253/4160 = 6.1%]
+    updateCrc32
+    crcFromFile
+    writeRopeIfNotEqual
+    shouldRecompile
+    writeModule
+    myClose
+    closePasses
+    processModule
+    CompileModule
+    CompileProject
+    CommandCompileToC
+    MainCommand
+    HandleCmdLine
+    nimrod
+  Entry: 5/3391 Calls: 32/4160 = 0.77% [sum: 285; 285/4160 = 6.9%]
+    pop
+    newCrcFromRopeAux
+    crcFromRope
+    writeRopeIfNotEqual
+    shouldRecompile
+    writeModule
+    myClose
+    closePasses
+    processModule
+    CompileModule
+    CompileProject
+    CommandCompileToC
+    MainCommand
+    HandleCmdLine
+    nimrod
+  Entry: 6/3391 Calls: 17/4160 = 0.41% [sum: 302; 302/4160 = 7.3%]
+    doOperation
+    forAllChildrenAux
+    pop
+    newCrcFromRopeAux
+    crcFromRope
+    writeRopeIfNotEqual
+    shouldRecompile
+    writeModule
+    myClose
+    closePasses
+    processModule
+    CompileModule
+    CompileProject
+    CommandCompileToC
+    MainCommand
+    HandleCmdLine
+    ...
+    nimrod
+  Entry: 7/3391 Calls: 14/4160 = 0.34% [sum: 316; 316/4160 = 7.6%]
+    Contains
+    isAccessible
+    interiorAllocatedPtr
+    gcMark
+    markStackAndRegisters
+    collectCTBody
+    collectCT
+    rawNewObj
+    newObj
+    newNode
+    copyTree
+    matchesAux
+    matches
+    resolveOverloads
+    semOverloadedCall
+    semOverloadedCallAnalyseEffects
+    ...
+    CommandCompileToC
+    MainCommand
+    HandleCmdLine
diff --git a/doc/tools.txt b/doc/tools.txt
index bd79745f6..ae739e778 100755
--- a/doc/tools.txt
+++ b/doc/tools.txt
@@ -15,3 +15,6 @@ The standard distribution ships with the following tools:
 
 - | `endb <endb.html>`_
   | Nimrod's slow platform independent embedded debugger.
+
+- | `estp <estp.html>`_
+  | Nimrod's slow platform independent embedded stack trace profiler.