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.

1 files changed, 58 insertions, 0 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.