Some fixes to SRT documentation

- reordered the 3 SRT implementation cases from the most general to the
  most specific one:
    USE_SRT_POINTER -> USE_SRT_OFFSET -> USE_INLINE_SRT_FIELD
- added requirements for each
- found and documented a confusion about "SRT inlining" not supported
  with MachO. (It is fixed in the following commit)

1 files changed, 50 insertions, 25 deletions

diff --git a/compiler/GHC/Cmm/Info/Build.hs b/compiler/GHC/Cmm/Info/Build.hs
index d450594ffe..4d5b277f52 100644
--- a/compiler/GHC/Cmm/Info/Build.hs
+++ b/compiler/GHC/Cmm/Info/Build.hs
@@ -113,55 +113,80 @@ The following things have SRTs:
 - Static thunks (THUNK), ie. CAFs
 - Continuations (RET_SMALL, etc.)
 
-In each case, the info table points to the SRT.  There are three ways which we
-may encode the location of the SRT in the info table, described below.
+In each case, the info table points to the SRT, if there is one.
 
-USE_SRT_OFFSET
---------------
-In this case we use the info->srt to encode whether or not there is an
-SRT and if so encode the offset to its location in info->f.srt_offset:
+- info->srt is 0 if there's no SRT
+- otherwise, there are three ways which we may encode the location of the SRT in
+  the info table, described below.
 
-- info->srt is 0 if there's no SRT, otherwise,
-- info->srt == 1 and info->f.srt_offset points to the SRT
+USE_SRT_POINTER
+---------------
+Most general implementation. Can always be used, but other ways are more efficient.
 
-e.g. for a FUN with an SRT:
+- info->srt is a pointer
 
-StgFunInfoTable       +------+
-  info->f.srt_offset  |  ------------> offset to SRT object
-StgStdInfoTable       +------+
+We encode an **absolute pointer** to the SRT in info->srt. e.g. for a FUN
+with an SRT:
+
+StgInfoTable          +------+
   info->layout.ptrs   | ...  |
   info->layout.nptrs  | ...  |
-  info->srt           |  1   |
+  info->srt           |  ------------> pointer to SRT object
   info->type          | ...  |
                       |------|
 
-USE_SRT_POINTER
----------------
-When tables-next-to-code isn't in use we rather encode an absolute pointer to
-the SRT in info->srt. e.g. for a FUN with an SRT:
+USE_SRT_OFFSET
+--------------
+Requires:
+  - tables-next-to-code enabled
+
+In this case we use the info->srt to encode whether or not there is an SRT and
+if so encode the offset to its location in info->f.srt_offset:
+
+- info->srt is a half-word
+- info->f.srt_offset is a 32-bit int
+- info->srt is 0 if there's no SRT, otherwise,
+- info->srt == 1 and info->f.srt_offset is a offset to the SRT, relative to the
+field address itself
+
+e.g. for a FUN with an SRT:
 
 StgFunInfoTable       +------+
-  info->f.srt_offset  |  ------------> pointer to SRT object
-StgStdInfoTable       +------+
+  info->f.srt_offset  |  ------------> offset to SRT object
+StgInfoTable          +------+
   info->layout.ptrs   | ...  |
   info->layout.nptrs  | ...  |
   info->srt           |  1   |
   info->type          | ...  |
                       |------|
+
 USE_INLINE_SRT_FIELD
 --------------------
-When using TNTC on x86_64 (and other platforms using the small memory model),
-we optimise the info table representation further.  The offset to the SRT can
+Requires:
+  - tables-next-to-code enabled
+  - 64-bit architecture
+  - small memory model
+
+Currently it is only enabled on x86_64 with TABLES_NEXT_TO_CODE.
+
+It is claimed that MachO doesn't support it due to #15169. However I believe
+that two kinds of SRT inlining have been confused:
+- inlining the SRT offset in the info->srt field
+  - should always be fine
+- inlining singleton SRT (i.e. SRT containing one reference)
+  - this can lead to a relative reference to an object external to the
+    compilation unit (c.f. #15169)
+
+We optimise the info table representation further.  The offset to the SRT can
 be stored in 32 bits (all code lives within a 2GB region in x86_64's small
 memory model), so we can save a word in the info table by storing the
 srt_offset in the srt field, which is half a word.
 
-On x86_64 with TABLES_NEXT_TO_CODE (except on MachO, due to #15169):
-
-- info->srt is zero if there's no SRT, otherwise:
+- info->srt is a half-word
+- info->srt is 0 if there's no SRT, otherwise:
 - info->srt is an offset from the info pointer to the SRT object
 
-StgStdInfoTable       +------+
+StgInfoTable          +------+
   info->layout.ptrs   |      |
   info->layout.nptrs  |      |
   info->srt           |  ------------> offset to SRT object