Improve documentation surrounding libffi and adjustorswip/ghci-libffi-dep

8 files changed, 34 insertions, 2 deletions

diff --git a/hadrian/src/Rules/Libffi.hs b/hadrian/src/Rules/Libffi.hs
index 86238c30a4..d629110c40 100644
--- a/hadrian/src/Rules/Libffi.hs
+++ b/hadrian/src/Rules/Libffi.hs
@@ -13,8 +13,25 @@ import Settings.Builders.Common
 import Target
 import Utilities
 
-{- Note [Libffi indicating inputs]
+{-
+Note [Uses of libffi in GHC]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+GHC uses libffi for two things:
 
+ * it is always used to perform foreign calls in interpreted code. This is
+   implemented in "GHCi.FFI" in the `ghci` library). N.B. it is *not* used for
+   foreign calls in compiled code, which are rather handled by the code generator.
+
+ * it is used by some platforms for "adjustors" used to setup calls into
+   Haskell from `foreign export`s. This is implemented in `rts/Adjustor.c`; see
+   Note [Adjustors] in that file.
+
+   Note that on some platforms (e.g. x86-64) we use our own home-grown
+   adjustors logic instead of libffi. Consequently, the RTS's dependency on
+   libffi is conditional on 'Oracles.Settings.useLibFFIForAdjustors'.
+
+Note [Libffi indicating inputs]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 First see https://gitlab.haskell.org/ghc/ghc/wikis/Developing-Hadrian for an
 explanation of "indicating input". Part of the definition is copied here for
 your convenience:
diff --git a/libffi/ghc.mk b/libffi/ghc.mk
index a127612a29..72422d0584 100644
--- a/libffi/ghc.mk
+++ b/libffi/ghc.mk
@@ -10,6 +10,7 @@
 #
 # -----------------------------------------------------------------------------
 
+# See Note [Uses of libffi in GHC] in hadrian's Rules.Libffi
 
 libffi_STAMP_STATIC_CONFIGURE = libffi/stamp.ffi.static.configure
 libffi_STAMP_STATIC_BUILD     = libffi/stamp.ffi.static.build
diff --git a/libraries/ghci/GHCi/FFI.hsc b/libraries/ghci/GHCi/FFI.hsc
index 74c9e175b1..8399994eb4 100644
--- a/libraries/ghci/GHCi/FFI.hsc
+++ b/libraries/ghci/GHCi/FFI.hsc
@@ -2,6 +2,8 @@
 --
 -- libffi bindings
 --
+-- See Note [Uses of libffi in GHC] in hadrian's Rules.Libffi
+--
 -- (c) The University of Glasgow 2008
 --
 -----------------------------------------------------------------------------
diff --git a/libraries/ghci/ghci.cabal.in b/libraries/ghci/ghci.cabal.in
index 90e2a06fd9..044a6ee7e8 100644
--- a/libraries/ghci/ghci.cabal.in
+++ b/libraries/ghci/ghci.cabal.in
@@ -58,6 +58,7 @@ library
             GHCi.StaticPtrTable
             GHCi.TH
 
+    -- See Note [Uses of libffi in GHC] in hadrian's Rules.Libffi
     include-dirs: @FFIIncludeDir@
     extra-libraries: ffi
 
diff --git a/rts/Adjustor.c b/rts/Adjustor.c
index 767a9ce9b7..7f01d189a0 100644
--- a/rts/Adjustor.c
+++ b/rts/Adjustor.c
@@ -5,7 +5,9 @@
  *
  * ---------------------------------------------------------------------------*/
 
-/* A little bit of background...
+/*
+Note [Adjustors]
+~~~~~~~~~~~~~~~~
 
 An adjustor thunk is a dynamically allocated code snippet that allows
 Haskell closures to be viewed as C function pointers.
@@ -34,6 +36,11 @@ An adjustor thunk differs from a C function pointer in one respect: when
 the code is through with it, it has to be freed in order to release Haskell
 and C resources. Failure to do so will result in memory leaks on both the C and
 Haskell side.
+
+How we implement adjustors is platform dependent (specifically determined by
+USE_LIBFFI_FOR_ADJUSTORS). On PowerPC, x86-64 and i386 we use a home-grown
+adjustor implementation. On all other platforms we rather use libffi. Also see
+Note [Uses of libffi in GHC] in hadrian's Rules.Libffi.
 */
 
 #include "PosixSource.h"
diff --git a/rts/AdjustorAsm.S b/rts/AdjustorAsm.S
index 2795b83b63..67dd77bc9d 100644
--- a/rts/AdjustorAsm.S
+++ b/rts/AdjustorAsm.S
@@ -1,5 +1,7 @@
 #include "../includes/ghcconfig.h"
 
+// See Note [Adjustors] in rts/Adjustor.c
+
 /* ******************************** PowerPC ******************************** */
 
 #if defined(powerpc_HOST_ARCH) || defined(powerpc64_HOST_ARCH)
diff --git a/rts/ghc.mk b/rts/ghc.mk
index 73a65824ba..69e194c1d3 100644
--- a/rts/ghc.mk
+++ b/rts/ghc.mk
@@ -378,6 +378,7 @@ rts_CC_OPTS += -DNOSMP
 rts_HC_OPTS += -optc-DNOSMP
 endif
 
+# See Note [Adjustors] in rts/Adjustor.c
 ifeq "$(UseLibFFIForAdjustors)" "YES"
 rts_CC_OPTS += -DUSE_LIBFFI_FOR_ADJUSTORS
 endif
diff --git a/rts/rts.cabal.in b/rts/rts.cabal.in
index 872a9e3493..0a1ad97d2b 100644
--- a/rts/rts.cabal.in
+++ b/rts/rts.cabal.in
@@ -10,6 +10,7 @@ flag librt
   default: @CabalHaveLibrt@
 flag libdl
   default: @CabalHaveLibdl@
+-- See Note [Uses of libffi in GHC] in hadrian's Rules.Libffi
 flag ffi
   default: @CabalHaveLibffi@
 flag need-pthread