doc update

docs/lua_internals_notes.rst

@@ -9,22 +9,24 @@ These are rough notes - once something useful is identified it will be documente
 -----------------------------
 
 ``L->top``
-  Appears to track the stack position where the next argument will be pushed (i.e. stack top).
+  Tracks the top of the stack but has another purpose as explained by Roberto:
 
-
-How is ``L->top`` updated
--------------------------
-
-``api_incr_top``
-  Macro defined in ``lapi.h`` - increments L->top, and checks that it doesn't go beyond ``L->ci->top`` (stack overflow). So then this indicates that ``L->top`` cannot go beyond ``L->ci->top``.
-
-  Primarily used in ``lapi.c`` but also in ``ldo.c``, ``ldebug.c`` and ``lstate.c``.
+    It is not only L->top that has a dual purpose; the stack has a dual
+    usage, due to the way that Lua uses a register-based VM. While inside
+    a Lua function, Lua preallocates in the stack all "registers" that the
+    function will eventually need. So, while running VM instructions in
+    one function, L->top points to the end of its activation record (stack
+    frame). When Lua enters or re-enters a Lua function, L->top must be
+    corrected to this frame, except when multiple returns are involved.
+    In that case, it is true that L->top is used to pass information
+    strictly between two consecutive VM instructions. (From either
+    OP_CALL/OP_VARARG to one of OP_CALL/OP_RETURN/OP_SETLIST.)
 
 
+OP_CALL
+-------------------------
+OP_CALL is assumed to only be used for Lua calling Lua - when a function
+is called via OP_CALL, then OP_RETURN must reset L->top to L->ci->top 
+if posD_call() returned non-zero value.
 
-Lua calls Lua via OP_CALL
-  When this happens, the OP_RETURN must reset L->top to L->ci->top if posD_call() returned non-zero value.
 
-  This can only happen when OP_CALL is involved and the target is a Lua function. 
-  Since an interpreted Lua function will be executed via luaV_execute() which doesn't reset L->top for external calls, we need to handle this.
-  If the Lua function was JITed then we also need to reset.