# ==========================================================================
# frame.txt
# ==========================================================================
# Description of call frames in elastiC.
# --------------------------------------------------------------------------
#   AUTHOR:  Marco Pantaleoni         E-mail: panta@elasticworld.org
#
#   Created: 23 Jul 1998
#
#   $Id$
# --------------------------------------------------------------------------
#    Copyright (C) 1998-1999 Marco Pantaleoni. All rights reserved.
#
#  The contents of this file are subject to the elastiC License version 1.0
#  (the "elastiC License"); you may not use this file except in compliance
#  with the elastiC License. You may obtain a copy of the elastiC License at
#  http://www.elasticworld.org/LICENSE
#
#  IN NO EVENT SHALL THE AUTHOR OR DISTRIBUTORS BE LIABLE TO ANY PARTY
#  FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
#  ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
#  DERIVATIVES THEREOF, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE
#  POSSIBILITY OF SUCH DAMAGE.
#
#  THE AUTHOR AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
#  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
#  FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.  THIS SOFTWARE
#  IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHOR AND DISTRIBUTORS HAVE
#  NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
#  MODIFICATIONS.
#
#  See the elastiC License for the specific language governing rights and
#  limitations under the elastiC License.
# ==========================================================================

1. LAYOUT OF A CALL FRAME
=========================

Before a routine is called, its call frame is created and filled with
some valuable information.
Here it is the layout:


     OFFSET    BP-OFFSET   CONTENT
   ------------------------------------------------------------------
          0        -nP-3   Caller object
          1        -nP-2   self
          2        -nP-1   at_class
         PS -        -nP   \
          .  |         .    | Parameters   (#: nP = PE - PS + 1)
         PE -	      -1   /
BP ->    LS -  	       0   \
          .  |         .    | Locals       (#: nL = LE - LS + 1)
         LE -	   LE-LS   /
      .....                \
      .....                 \
      .....                  | Temps
      .....                 /
SP -> .....                /

BP: Base pointer
SP: Stack pointer

Being a number, the PC is saved in another part of the stackframe (not
the object array).

At compile-time, the number of parameters to a function is unknown,
since there could be a variable number of arguments passed.
So at runtime the called function must use a BP (Base Pointer).
This BP is set in the stackframe at the moment of the call by the
caller.

2. RETURNING FROM A CALL
========================

The return value is pushed on the call frame (stack). The caller then
retrieves this value with a pop from the callee's stack, then discard
the callee's stack.


3. EXAMPLE OF CALL
==================

  BEFORE A CALL:

          arg1
          ...
          argN
      receiver


  AFTER A CALL:

        result
