lua instructions

readthedocs/lua_bytecode_reference.rst

@@ -12,6 +12,44 @@ Following copyrights are acknowledged:
     Version 0.1, 2006-03-13
 
 
+Lua Stack and Registers
+=======================
+Lua employs two stacks.
+The ``Callinfo`` stack tracks activation frames. 
+There is the secondary stack ``L->stack`` that is an array of ``TValue`` objects. 
+The ``Callinfo`` objects index into this array. Registers are basically slots in 
+the ``L->stack`` array.
+
+When a function is called - the stack is setup as follows::
+
+  stack
+  |            function reference
+  |  base->    var arg 1
+  |            ... 
+  |            var arg n
+  |            fixed arg 1
+  |            ...
+  |            fixed arg n
+  |            local 1
+  |            ...
+  |            local n
+  |  top->     
+  |  
+  V
+
+So ``top`` is just past the registers needed by the function. 
+The number of registers is determined based on locals and temporaries.
+
+The base of the stack is set to just past the function reference - i.e. on the first fixed 
+parameter or local.
+All register addressing is done as offset from ``base`` - so ``R(0)`` is at ``base+0`` on the stack. 
+
+.. figure:: Drawing_Lua_Stack.jpg
+   :alt: Drawing of Lua Stack
+
+   The figure shows how the stack is related to other Lua objects.
+
+
 '``OP_CALL``' instruction
 =========================
 
@@ -24,7 +62,7 @@ Syntax
 
 Performs a function call, with register R(A) holding the reference to the function object to be called. Parameters to the function are placed in the registers following R(A). If B is 1, the function has no parameters. If B is 2 or more, there are (B-1) parameters. If B >= 2, then upon entry to the called function, R(A+B-1) will become the ``base``. 
 
-If B is 0, the function parameters range from R(A+1) to the top of the stack. This form is used when the last expression in the parameter list is a function call, so the number of actual parameters is indeterminate. In this case, upon entry to the function, ``base`` is set to the register beyond the vararg section, which means that the varargs sit between the R(A) and ``base``.
+If B is 0, the function parameters range from R(A+1) to the top of the stack. This form is used when the last expression in the parameter list is a function call, so the number of actual parameters is indeterminate. In this case, upon entry to the function, ``base`` is set to the register beyond the vararg section, which means that the varargs sit between the R(A) and ``base`` (see `adjust_varargs()<http://www.lua.org/source/5.3/ldo.c.html#adjust_varargs>`_.
 
 Thus upon entry to a function ``base`` is always the location of the first fixed parameter if any or else ``local`` if any. The three possibilities are shown below.
 
@@ -38,8 +76,12 @@ Thus upon entry to a function ``base`` is always the location of the first fixed
   R(A+3)                               CI->base  [ fixed arg 1 ]   CI->base [ local 1    ]
   R(A+4)                                         [ local 1     ]
                                         
-Results returned by the function call is placed in a range of registers starting from R(A). If C is 1, no return results are saved. If C is 2 or more, (C-1) return values are saved. If C is 0, then multiple return results are saved, depending on the called function.
+Results returned by the function call is placed in a range of registers starting from R(A). If C is 1, no return results are saved. If C is 2 or more, (C-1) return values are saved. If C is 0, then multiple return results are saved. In this case the number of values to save is determined by one of following ways:
+
+* A C function returns an integer value indicating number of results returned so for C function calls
+  this is used (see the value of ``n`` passed to `luaD_poscall()<http://www.lua.org/source/5.3/ldo.c.html#luaD_poscall>`_ in `luaD_precall()<http://www.lua.org/source/5.3/ldo.c.html#luaD_precall>`_)
+* For Lua functions, the the results are saved by the called function's '``OP_RETURN``' instruction.
+
 
-CALL always updates the top of stack value. CALL, RETURN, VARARG and SETLIST can use multiple values (up to the top of the stack.)