Add -finfo-table-map which maps info tables to source positions

This new flag embeds a lookup table from the address of an info table
to information about that info table.

The main interface for consulting the map is the `lookupIPE` C function

> InfoProvEnt * lookupIPE(StgInfoTable *info)

The `InfoProvEnt` has the following structure:

> typedef struct InfoProv_{
>     char * table_name;
>     char * closure_desc;
>     char * ty_desc;
>     char * label;
>     char * module;
>     char * srcloc;
> } InfoProv;
>
> typedef struct InfoProvEnt_ {
>     StgInfoTable * info;
>     InfoProv prov;
>     struct InfoProvEnt_ *link;
> } InfoProvEnt;

The source positions are approximated in a similar way to the source
positions for DWARF debugging information. They are only approximate but
in our experience provide a good enough hint about where the problem
might be. It is therefore recommended to use this flag in conjunction
with `-g<n>` for more accurate locations.

The lookup table is also emitted into the eventlog when it is available
as it is intended to be used with the `-hi` profiling mode.

Using this flag will significantly increase the size of the resulting
object file but only by a factor of 2-3x in our experience.

3 files changed, 79 insertions, 2 deletions

diff --git a/docs/users_guide/debug-info.rst b/docs/users_guide/debug-info.rst
index e18f0287a4..ce640691a2 100644
--- a/docs/users_guide/debug-info.rst
+++ b/docs/users_guide/debug-info.rst
@@ -335,3 +335,61 @@ Further Reading
 For more information about the debug information produced by GHC see
 Peter Wortmann's PhD thesis, `*Profiling Optimized Haskell: Causal
 Analysis and Implementation* <http://etheses.whiterose.ac.uk/8321/>`__.
+
+
+Direct Mapping
+--------------
+
+In addition to the DWARF debug information, which can be used by many
+standard tools, there is also a GHC specific way to map info table pointers
+to a source location. This lookup table is generated by using the ``-finfo-table-map`` flag.
+
+
+.. ghc-flag:: -finfo-table-map
+    :shortdesc: Embed a lookup table in the generated binary which
+                maps the address of an info table to the source position
+                the closure originated from.
+    :type: dynamic
+    :category: debugging
+
+    :since: 9.2
+
+    This flag enables the generation of a table which maps the address of
+    an info table to an approximate source position of where that
+    info table statically originated from. If you
+    also want more precise information about constructor info tables then you
+    should also use :ghc-flag:`-fdistinct-constructor-tables`.
+
+    This flag will increase the binary size by quite a lot, depending on how
+    big your project is. For compiling a project the size of GHC the overhead was
+    about 200 megabytes.
+
+.. ghc-flag:: -fdistinct-constructor-tables
+    :shortdesc: Generate a fresh info table for each usage
+                of a data constructor.
+    :type: dynamic
+    :category: debugging
+
+    :since: 9.2
+
+    For every usage of a data constructor in the source program
+    a new info table will be created. This is useful for debugging
+    as if each usage has a unique info table then the info table map
+    and profiling modes can distinguish the allocation sites of
+    a data constructor.
+
+
+
+Querying the Info Table Map
+---------------------------
+
+If it is generated then the info table map can be used
+in two ways.
+
+1. The ``whereFrom`` function can be used to determine the source
+   position which we think a specific closure was created.
+2. The complete mapping is also dumped into the eventlog.
+
+If you are using gdb then you can use the ``lookupIPE`` function
+directly in order to find any information which is known
+about the info table for a specific closure.
diff --git a/docs/users_guide/eventlog-formats.rst b/docs/users_guide/eventlog-formats.rst
index e0f4430a3f..9ccd6bb2cf 100644
--- a/docs/users_guide/eventlog-formats.rst
+++ b/docs/users_guide/eventlog-formats.rst
@@ -598,6 +598,24 @@ A variable-length packet produced once for each cost centre,
 
      * bit 0: is the cost-centre a CAF?
 
+Info Table Provenance definitions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A message which describes an approximate source position for
+info tables. See :ghc-flag:`-finfo-table-map` for more information.
+
+.. event-type:: IPE
+
+   :tag: 169
+   :length: fixed
+   :field Word64: info table address
+   :field String: table name
+   :field String: closure type
+   :field String: type
+   :field String: source position label
+   :field String: source position module
+   :field String: source position location
+
 
 Sample event types
 ^^^^^^^^^^^^^^^^^^
diff --git a/docs/users_guide/profiling.rst b/docs/users_guide/profiling.rst
index 75569f6409..097d7d0de3 100644
--- a/docs/users_guide/profiling.rst
+++ b/docs/users_guide/profiling.rst
@@ -802,8 +802,9 @@ following RTS options select which break-down to use:
 
 .. rts-flag:: -hi
 
-    Break down the graph by the address of the info table of a closure. This
-    profiling mode is intended to be used with :ghc-flag:`-finfo-table-map`.
+    Break down the graph by the address of the info table of a closure. For this
+    to produce useful output the program must have been compiled with
+    :ghc-flag:`-finfo-table-map`.
 
 .. rts-flag:: -l
     :noindex: