[commit: ghc] wip/libdw-prof: users-guide: Document statistical profiler eventlog records (363af65)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : wip/libdw-prof
Link       : http://ghc.haskell.org/trac/ghc/changeset/363af65dafc894065aeb63be18b2b15947702ea4/ghc

>---------------------------------------------------------------

commit 363af65dafc894065aeb63be18b2b15947702ea4
Author: Ben Gamari <ben at smart-cactus.org>
Date:   Tue Dec 6 11:04:40 2016 -0500

    users-guide: Document statistical profiler eventlog records


>---------------------------------------------------------------

363af65dafc894065aeb63be18b2b15947702ea4
 docs/users_guide/eventlog-formats.rst | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/docs/users_guide/eventlog-formats.rst b/docs/users_guide/eventlog-formats.rst
index 8d53f92..b826ad6 100644
--- a/docs/users_guide/eventlog-formats.rst
+++ b/docs/users_guide/eventlog-formats.rst
@@ -103,3 +103,38 @@ A variable-length event encoding a heap sample broken down by,
    * ``Word8``: Profile ID
    * ``Word64``: heap residency in bytes
    * ``String``: type or closure description, or module name
+
+
+.. _statistical-profiler-formats:
+
+Statistical profiler formats
+----------------------------
+
+Samples
+~~~~~~~
+
+A block of samples from statistical profiling. A sample consists of a sample
+value (e.g. an instruction pointer address) and a weight (e.g. how many times
+the sample pointer was seen).
+
+ * ``EVENT_STAT_PROF_SAMPLES`` (variable length)
+   * ``Word8``: Capability number
+   * ``Word8``: Sample trigger type
+   * ``Word8``: Sample value type
+   * Encoded samples
+
+The samples themselves are represented with a compressed encoding. Each sample
+is represented by,
+
+ * ``Word8``: Sample and weight encoding type
+   * top 4-bits: Sample encoding type
+     * ``0x0``: 8-bit positive offset to previous address
+     * ``0x1``: 8-bit negative offset to previous address
+     * ``0x4``: 32-bit positive offset to previous address
+     * ``0x5``: 32-bit negative offset to previous address
+     * ``0xf``: direct encoding
+   * bottom 4-bits: weight encoding type
+     * ``0``: ``weight == 1``
+     * ``1``: weight encoded as ``Word8``
+     * ``2``: weight encoded as ``Word16``
+     * ``4``: weight encoded as ``Word32``