package Frame;

/**
 * Information about frames, gathered as part of the Tiger
 * compilation process.
 * <p>
 * This file is based on ``Modern Compiler Implementation in Java''
 * by Andrew Appel (Cambridge University Press, 1998).  This is referred 
 * to hereafter as ``the red book''.
 * <p>
 * This differs from the red book in a number of ways.  Here are some
 * of the more important ones:
 * <ul>
 * <li>Unlike the code in the red book, this does not provide a
 *     <code>string</code> method.  You should use the tree
 *     SEQ(LABEL(...), STRING(...)) instead.
 * <li>Unlike the code in the red book, this does not use
 *     the ASM module and instead uses sequences of instructions.
 * <li>Unlike the code in the red book, this does not include a
 *     <code>codegen</code> method, which is only necessary if
 *     we're generating assembly code.
 *</ul>
 * <p>
 * <strong>History</strong>
 * <dl>
 * <dt>4 December 1998 (version 0.1)
 * <dd>Built from examples in Appel's book.
 * <dt>7 December 1998 (version 0.2)
 * <dd>Added history
 * <dd>Updated types of procEntryExit{2,3} and codegen.
 * <dt>16 December 1998 (version 0.3)
 * <dd>Added descriptions of the various methods.
 * <dd>Dropped the <code>string</code> method.  Use 
 *     <code>Tree.String</code> instead.
 * <dd>Dropped the <code>codegen</code> method.
 * </dl>
 *
 * @author Samuel A. Rebelsky
 * @author Andrew Appel
 * @version 0.3 of 16 December 1998
 */

public abstract class Frame 
  implements Temp.TempMap {

  // +--------+--------------------------------------------------
  // | Fields |
  // +--------+

  /**
   * The ``accesses'' (instructions for accessing) the formal
   * parameters to the function represented by the current frame.
   * <p>
   * Red book, p. 141.
   */
  public AccessList formals;

  /**
   * The label associated with the frame.  Used when calling the
   * function.
   * <p>
   * Red book, p. 141.
   */
  public Temp.Label name;


  // +---------+-------------------------------------------------
  // | Methods |
  // +---------+

  /**
   * Build a new frame, given information about the parameters to
   * the function.  The booleans indicate whether or not the parameters
   * ``escape'' (if a boolean is true, the corresponding parameter
   * <em>must</em> be stored in the frame).
   * <p>
   * Red book, p. 141.
   */
  abstract public Frame newFrame(Temp.Label name,
                                 Util.BoolList formals);

  /**
   * Allocate a new local storage location, which might be a register
   * (temporary) or space in the current frame, or perhaps something
   * different (in some architectures).  As you allocate a new storage
   * location, indicate whether it must be stored in the frame or 
   * whether it can be stored wherever the compiler deems appropriate.
   * <p>
   * Red book, p. 143.
   */
  abstract public Access allocLocal(boolean escape);

  /**
   * Get the register used for the frame pointer.
   * <p>
   * Red book, p. 163.
   */
  abstract public Temp.Temp FP();

  /**
   * Get the size of the words on the current machine (in bytes).
   * <p>
   * Red book, p. 163.
   */
  abstract public int wordSize();

  /**
   * Generate the code to call an external function (one of the built-in 
   * functions).
   * <p>
   * Red book, p. 163.
   */
  abstract public Tree.Exp externalCall(String func, Tree.ExpList args);

  /**
   * A list of all the register names on the machine, which can be used
   * as ``colors'' for register allocation.  Not really needed except for
   * register allocation.
   * <p>
   * Red book, p. 270.
   */
  abstract public Temp.TempList registers();

  /**
   * Get the register used for the return value.
   * <p>
   * Red book, p. 176.
   */
  abstract public Temp.Temp RV();

  /**
   * Get the ``precolored temporary'' that stands for each register.
   * Used primarily for register allocation.
   * <p>
   * Red book, p. 270.
   */
  abstract public String tempMap(Temp.Temp temp);

  /**
   * Create the IRT for the start and end of the function.  This 
   * includes saving parameters and saving registers.  The paramter
   * is the body of the function.
   * <p>
   * Red book, pp. 176 and 271.
   */
  abstract public Tree.Stm procEntryExit1(Tree.Stm body);

  /**
   * Add ``sink'' instructions to the function body to tell the
   * register allocator that certain registers are live at 
   * procedure exit.  Not implemented in the current version.
   */
  abstract public Tree.StmList procEntryExit2(Tree.StmList body);

  /**
   * Add more wrapper code to the procedure to allocate space for
   * the frame and stuff.
   * <p>
   * Red book, pp. 176 and 271.
   */ 
  abstract public Tree.StmList procEntryExit3(Tree.StmList body);

} // class Frame