Add comments for StgCse and Unarise

This just improves docmentation for the fix to Trac #15300

2 files changed, 18 insertions, 0 deletions

diff --git a/compiler/simplStg/SimplStg.hs b/compiler/simplStg/SimplStg.hs
index 36bf5101d6..830dd19aea 100644
--- a/compiler/simplStg/SimplStg.hs
+++ b/compiler/simplStg/SimplStg.hs
@@ -40,6 +40,8 @@ stg2stg dflags binds
         ; stg_linter False "Pre-unarise" binds
         ; let un_binds = unarise us binds
         ; stg_linter True "Unarise" un_binds
+         -- Important that unarisation comes first
+         -- See Note [StgCse after unarisation] in StgCse
 
         ; dumpIfSet_dyn dflags Opt_D_dump_stg "STG syntax:"
                         (pprStgTopBindings un_binds)
diff --git a/compiler/simplStg/StgCse.hs b/compiler/simplStg/StgCse.hs
index 1ae1213960..2caf006e3f 100644
--- a/compiler/simplStg/StgCse.hs
+++ b/compiler/simplStg/StgCse.hs
@@ -67,7 +67,23 @@ and nothing stops us from transforming that to
     foo [e] = case e of b { Left [n] -> …
                           , Right [x] -> b}
 
+
+Note [StgCse after unarisation]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Consider two unboxed sum terms:
+
+    (# 1 | #) :: (# Int | Int# #)
+    (# 1 | #) :: (# Int | Int  #)
+
+These two terms are not equal as they unarise to different unboxed
+tuples. However if we run StgCse before Unarise, it'll think the two
+terms (# 1 | #) are equal, and replace one of these with a binder to
+the other. That's bad -- Trac #15300.
+
+Solution: do unarise first.
+
 -}
+
 module StgCse (stgCse) where
 
 import GhcPrelude