[Git][ghc/ghc][wip/ghc-debug] 2 commits: Add documentation to StgStack

[David Eichmann]

David Eichmann pushed to branch wip/ghc-debug at Glasgow Haskell Compiler / GHC


Commits:
f7890ab3 by David Eichmann at 2020-09-25T20:04:48+01:00
Add documentation to StgStack

- - - - -
8edefcf9 by David Eichmann at 2020-09-25T20:07:04+01:00
Remove unneeded local variables in unpackClosure# primop

- - - - -


2 changed files:

- includes/rts/storage/TSO.h
- rts/PrimOps.cmm


Changes:

=====================================
includes/rts/storage/TSO.h
=====================================
@@ -242,10 +242,23 @@ typedef struct StgTSO_ {
 
 typedef struct StgStack_ {
     StgHeader  header;
-    StgWord32  stack_size;     // stack size in *words*
-    StgWord8   dirty;          // non-zero => dirty
+
+    /* Size of the `stack` field in *words*. This is unaffected by how much of
+     * the stack space is used nor if more stack space is liked to by an
+     * UNDERFLOW_FRAME.
+     */
+    StgWord32  stack_size;
+
+    StgWord32  dirty;          // non-zero => dirty
     StgWord8   marking;        // non-zero => someone is currently marking the stack
-    StgPtr     sp;             // current stack pointer
+
+    /* Pointer to the "top" of the stack i.e. the most recently written address.
+     * The stack is filled downwards, so the "top" of the stack starts with `sp
+     * = stack + stack_size` and is decremented as the stack fills with data.
+     * The memory in `stack` strictly less than `sp` is free stack space.
+     * See comment on "Invariants" below.
+     */
+    StgPtr     sp;
     StgWord    stack[];
 } StgStack;
 


=====================================
rts/PrimOps.cmm
=====================================
@@ -2371,11 +2371,11 @@ stg_unpackClosurezh ( P_ closure )
     clos = UNTAG(closure);
 
     W_ len;
-    // The array returned is the raw data for the entire closure.
+    // The array returned, dat_arr, is the raw data for the entire closure.
     // The length is variable based upon the closure type, ptrs, and non-ptrs
     (len) = foreign "C" heap_view_closureSize(clos "ptr");
 
-    W_ ptrs_arr_sz, ptrs_arr_cards, dat_arr_sz;
+    W_ dat_arr_sz;
 
     dat_arr_sz = SIZEOF_StgArrBytes + WDS(len);
     ("ptr" dat_arr) = ccall allocateMightFail(MyCapability() "ptr", BYTES_TO_WDS(dat_arr_sz));
@@ -2396,7 +2396,7 @@ for:
 
     W_ ptrArray;
 
-    // Follow the pointers
+    // Collect pointers.
     ("ptr" ptrArray) = foreign "C" heap_view_closurePtrs(MyCapability() "ptr", clos "ptr");
 
     return (info, dat_arr, ptrArray);



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/8e097c8edfcae9c83f10d69af032d34fd2f950dc...8edefcf9c5389f259567998484f22111ac598945

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/8e097c8edfcae9c83f10d69af032d34fd2f950dc...8edefcf9c5389f259567998484f22111ac598945
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20200925/79f54ebb/attachment-0001.html>