libguile/frames.h

   1 /* Copyright (C) 2001, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc.
   2  * *
   3  * This library is free software; you can redistribute it and/or
   4  * modify it under the terms of the GNU Lesser General Public License
   5  * as published by the Free Software Foundation; either version 3 of
   6  * the License, or (at your option) any later version.
   7  *
   8  * This library is distributed in the hope that it will be useful, but
   9  * WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11  * Lesser General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public
  14  * License along with this library; if not, write to the Free Software
  15  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  16  * 02110-1301 USA
  17  */
  18
  19 #ifndef _SCM_FRAMES_H_
  20 #define _SCM_FRAMES_H_
  21
  22 #include <libguile.h>
  23 #include "programs.h"
  24
  25 \f
  26 /* Stack frames
  27    ------------
  28
  29    It's a little confusing, but there are two representations of frames
  30    in this file: frame pointers, and Scheme objects wrapping those frame
  31    pointers.  The former uses the SCM_FRAME macro prefix, the latter
  32    SCM_VM_FRAME prefix.
  33
  34    The confusing thing is that only Scheme frame objects have functions
  35    that use them, and they use the lower-case scm_frame prefix.
  36
  37
  38    Stack frame layout
  39    ------------------
  40
  41    /------------------\
  42    | Local N-1        | <- sp
  43    | ...              |
  44    | Local 1          |
  45    | Local 0          | <- fp = SCM_FRAME_LOCALS_ADDRESS (fp)
  46    +==================+
  47    | Return address   |
  48    | Dynamic link     | <- fp - 2 = SCM_FRAME_LOWER_ADDRESS (fp)
  49    +==================+
  50    |                  | <- fp - 3 = SCM_FRAME_PREVIOUS_SP (fp)
  51
  52    The calling convention is that a caller prepares a stack frame
  53    consisting of the saved FP and the return address, followed by the
  54    procedure and then the arguments to the call, in order.  Thus in the
  55    beginning of a call, the procedure being called is in slot 0, the
  56    first argument is in slot 1, and the SP points to the last argument.
  57    The number of arguments, including the procedure, is thus SP - FP +
  58    1.
  59
  60    After ensuring that the correct number of arguments have been passed,
  61    a function will set the stack pointer to point to the last local
  62    slot.  This lets a function allocate the temporary space that it
  63    needs once in the beginning of the call, instead of pushing and
  64    popping the stack pointer during the call's extent.
  65
  66    When a program returns, it returns its values in the slots starting
  67    from local 1, as if the values were arguments to a tail call.  We
  68    start from 1 instead of 0 for the convenience of the "values" builtin
  69    function, which can just leave its arguments in place.
  70
  71    The callee resets the stack pointer to point to the last value.  In
  72    this way the caller knows how many values there are: it's the number
  73    of words between the stack pointer and the slot at which the caller
  74    placed the procedure.
  75
  76    After checking that the number of values returned is appropriate, the
  77    caller shuffles the values around (if needed), and resets the stack
  78    pointer back to its original value from before the call.  */
  79
  80
  81 \f
  82
  83 /* This structure maps to the contents of a VM stack frame.  It can
  84    alias a frame directly.  */
  85 struct scm_vm_frame
  86 {
  87   SCM *dynamic_link;
  88   scm_t_uint32 *return_address;
  89   SCM locals[1]; /* Variable-length */
  90 };
  91
  92 #define SCM_FRAME_LOWER_ADDRESS(fp)     (((SCM *) (fp)) - 2)
  93 #define SCM_FRAME_STRUCT(fp)                            \
  94   ((struct scm_vm_frame *) SCM_FRAME_LOWER_ADDRESS (fp))
  95 #define SCM_FRAME_LOCALS_ADDRESS(fp)    (SCM_FRAME_STRUCT (fp)->locals)
  96
  97 #define SCM_FRAME_PREVIOUS_SP(fp)       (((SCM *) (fp)) - 3)
  98
  99 #define SCM_FRAME_RETURN_ADDRESS(fp)            \
 100   (SCM_FRAME_STRUCT (fp)->return_address)
 101 #define SCM_FRAME_SET_RETURN_ADDRESS(fp, ra)    \
 102   SCM_FRAME_STRUCT (fp)->return_address = (ra)
 103 #define SCM_FRAME_DYNAMIC_LINK(fp)              \
 104   (SCM_FRAME_STRUCT (fp)->dynamic_link)
 105 #define SCM_FRAME_SET_DYNAMIC_LINK(fp, dl)      \
 106   SCM_FRAME_DYNAMIC_LINK (fp) = (dl)
 107 #define SCM_FRAME_LOCAL(fp,i)                   \
 108   (SCM_FRAME_STRUCT (fp)->locals[i])
 109
 110 #define SCM_FRAME_NUM_LOCALS(fp, sp)            \
 111   ((sp) + 1 - &SCM_FRAME_LOCAL (fp, 0))
 112
 113 /* Currently (November 2013) we keep the procedure and arguments in
 114    their slots for the duration of the procedure call, regardless of
 115    whether the values are live or not.  This allows for backtraces that
 116    show the closure and arguments.  We may allow the compiler to relax
 117    this restriction in the future, if the user so desires.  This would
 118    conserve stack space and make GC more precise.  We would need better
 119    debugging information to do that, however.
 120
 121    Even now there is an exception to the rule that slot 0 holds the
 122    procedure, which is in the case of tail calls.  The compiler will
 123    emit code that shuffles the new procedure and arguments into position
 124    before performing the tail call, so there is a window in which
 125    SCM_FRAME_PROGRAM does not correspond to the program being executed.
 126
 127    The moral of the story is to use the IP in a frame to determine what
 128    procedure is being called.  It is only appropriate to use
 129    SCM_FRAME_PROGRAM in the prologue of a procedure call, when you know
 130    it must be there.  */
 131
 132 #define SCM_FRAME_PROGRAM(fp) (SCM_FRAME_LOCAL (fp, 0))
 133
 134 \f
 135 /*
 136  * Heap frames
 137  */
 138
 139 #ifdef BUILDING_LIBGUILE
 140
 141 struct scm_frame
 142 {
 143   void *stack_holder;
 144   scm_t_ptrdiff fp_offset;
 145   scm_t_ptrdiff sp_offset;
 146   scm_t_uint32 *ip;
 147 };
 148
 149 enum scm_vm_frame_kind
 150   {
 151     SCM_VM_FRAME_KIND_VM,
 152     SCM_VM_FRAME_KIND_CONT
 153   };
 154
 155 #define SCM_VM_FRAME_P(x)       (SCM_HAS_TYP7 (x, scm_tc7_frame))
 156 #define SCM_VM_FRAME_KIND(x)    ((enum scm_vm_frame_kind) (SCM_CELL_WORD_0 (x) >> 8))
 157 #define SCM_VM_FRAME_DATA(x)    ((struct scm_frame *)SCM_CELL_WORD_1 (x))
 158 #define SCM_VM_FRAME_STACK_HOLDER(f)    SCM_VM_FRAME_DATA (f)->stack_holder
 159 #define SCM_VM_FRAME_FP_OFFSET(f)       SCM_VM_FRAME_DATA (f)->fp_offset
 160 #define SCM_VM_FRAME_SP_OFFSET(f)       SCM_VM_FRAME_DATA (f)->sp_offset
 161 #define SCM_VM_FRAME_FP(f)      (SCM_VM_FRAME_FP_OFFSET (f) + scm_i_frame_stack_base (f))
 162 #define SCM_VM_FRAME_SP(f)      (SCM_VM_FRAME_SP_OFFSET (f) + scm_i_frame_stack_base (f))
 163 #define SCM_VM_FRAME_IP(f)      SCM_VM_FRAME_DATA (f)->ip
 164 #define SCM_VM_FRAME_OFFSET(f)  scm_i_frame_offset (f)
 165 #define SCM_VALIDATE_VM_FRAME(p,x)      SCM_MAKE_VALIDATE (p, x, VM_FRAME_P)
 166
 167 SCM_INTERNAL SCM* scm_i_frame_stack_base (SCM frame);
 168 SCM_INTERNAL scm_t_ptrdiff scm_i_frame_offset (SCM frame);
 169
 170 SCM_INTERNAL SCM scm_c_make_frame (enum scm_vm_frame_kind vm_frame_kind,
 171                                    void *stack_holder, scm_t_ptrdiff fp_offset,
 172                                    scm_t_ptrdiff sp_offset, scm_t_uint32 *ip);
 173
 174 #endif
 175
 176 SCM_API SCM scm_frame_p (SCM obj);
 177 SCM_API SCM scm_frame_procedure (SCM frame);
 178 SCM_API SCM scm_frame_arguments (SCM frame);
 179 SCM_API SCM scm_frame_source (SCM frame);
 180 SCM_API SCM scm_frame_num_locals (SCM frame);
 181 SCM_API SCM scm_frame_local_ref (SCM frame, SCM index);
 182 SCM_API SCM scm_frame_local_set_x (SCM frame, SCM index, SCM val);
 183 SCM_API SCM scm_frame_address (SCM frame);
 184 SCM_API SCM scm_frame_stack_pointer (SCM frame);
 185 SCM_API SCM scm_frame_instruction_pointer (SCM frame);
 186 SCM_API SCM scm_frame_return_address (SCM frame);
 187 SCM_API SCM scm_frame_dynamic_link (SCM frame);
 188 SCM_API SCM scm_frame_previous (SCM frame);
 189
 190 SCM_INTERNAL void scm_i_frame_print (SCM frame, SCM port,
 191                                      scm_print_state *pstate);
 192 SCM_INTERNAL void scm_init_frames (void);
 193
 194 #endif /* _SCM_FRAMES_H_ */
 195
 196 /*
 197   Local Variables:
 198   c-file-style: "gnu"
 199   End:
 200 */