[commit: ghc] master: Comments (about the stack overflow check) only (4fa1efe)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/4fa1efe3f1feab103f11fbddc08bccf924ef4ef1/ghc

>---------------------------------------------------------------

commit 4fa1efe3f1feab103f11fbddc08bccf924ef4ef1
Author: Simon Peyton Jones <simonpj at microsoft.com>
Date:   Fri Oct 18 13:04:33 2013 +0100

    Comments (about the stack overflow check) only


>---------------------------------------------------------------

4fa1efe3f1feab103f11fbddc08bccf924ef4ef1
 compiler/codeGen/StgCmmHeap.hs |   38 +++++++++++++++++++++++---------------
 1 file changed, 23 insertions(+), 15 deletions(-)

diff --git a/compiler/codeGen/StgCmmHeap.hs b/compiler/codeGen/StgCmmHeap.hs
index 1d1100c..7710b6f 100644
--- a/compiler/codeGen/StgCmmHeap.hs
+++ b/compiler/codeGen/StgCmmHeap.hs
@@ -535,24 +535,32 @@ heapStackCheckGen stk_hwm mb_bytes
 
 -- Note [Single stack check]
 -- ~~~~~~~~~~~~~~~~~~~~~~~~~
---
 -- When compiling a function we can determine how much stack space it will
 -- use. We therefore need to perform only a single stack check at the beginning
--- of a function to see if we have enough stack space. Instead of referring
--- directly to Sp - as we used to do in the past - the code generator uses
--- (old + 0) in the stack check. Stack layout phase turns (old + 0) into Sp.
+-- of a function to see if we have enough stack space.
+--
+-- The check boils down to comparing Sp+N with SpLim, where N is the
+-- amount of stack space needed.  *BUT* at this stage of the pipeline
+-- we are not supposed to refer to Sp itself, because the stack is not
+-- yet manifest, so we don't quite know where Sp pointing.
+
+-- So instead of referring directly to Sp - as we used to do in the
+-- past - the code generator uses (old + 0) in the stack check. That
+-- is the address of the first word of the old area, so if we add N
+-- we'll get the address of highest used word.
 --
--- The idea here is that, while we need to perform only one stack check for
--- each function, we could in theory place more stack checks later in the
--- function. They would be redundant, but not incorrect (in a sense that they
--- should not change program behaviour). We need to make sure however that a
--- stack check inserted after incrementing the stack pointer checks for a
--- respectively smaller stack space. This would not be the case if the code
--- generator produced direct references to Sp. By referencing (old + 0) we make
--- sure that we always check for a correct amount of stack: when converting
--- (old + 0) to Sp the stack layout phase takes into account changes already
--- made to stack pointer. The idea for this change came from observations made
--- while debugging #8275.
+-- This makes the check robust.  For example, while we need to perform
+-- only one stack check for each function, we could in theory place
+-- more stack checks later in the function. They would be redundant,
+-- but not incorrect (in a sense that they should not change program
+-- behaviour). We need to make sure however that a stack check
+-- inserted after incrementing the stack pointer checks for a
+-- respectively smaller stack space. This would not be the case if the
+-- code generator produced direct references to Sp. By referencing
+-- (old + 0) we make sure that we always check for a correct amount of
+-- stack: when converting (old + 0) to Sp the stack layout phase takes
+-- into account changes already made to stack pointer. The idea for
+-- this change came from observations made while debugging #8275.
 
 do_checks :: Maybe CmmExpr    -- Should we check the stack?
           -> Bool       -- Should we check for preemption?