# ==========================================================================
# 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, his call frame is created and filled with
some valuable information.
Here it is the layout:


     OFFSET    BP-OFFSET   CONTENT
   ------------------------------------------------------------------
          0          -LS   Caller object
         PS -      -LS+1
          .  |         .   Parameters
         PE -	      -1
BP ->    LS -  	       0
          .  |         .   Locals
         LE -	   LE-LS
      .....
      .....
      .....
      .....
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 the callee is not discernible by looking at a call in source
code. 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
