| 1 | /* Copyright (C) 2001, 2009, 2010, 2011, 2012, 2013, 2014 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 | \f |
| 114 | /* |
| 115 | * Heap frames |
| 116 | */ |
| 117 | |
| 118 | #ifdef BUILDING_LIBGUILE |
| 119 | |
| 120 | struct scm_frame |
| 121 | { |
| 122 | void *stack_holder; |
| 123 | scm_t_ptrdiff fp_offset; |
| 124 | scm_t_ptrdiff sp_offset; |
| 125 | scm_t_uint32 *ip; |
| 126 | }; |
| 127 | |
| 128 | enum scm_vm_frame_kind |
| 129 | { |
| 130 | SCM_VM_FRAME_KIND_VM, |
| 131 | SCM_VM_FRAME_KIND_CONT |
| 132 | }; |
| 133 | |
| 134 | #define SCM_VM_FRAME_P(x) (SCM_HAS_TYP7 (x, scm_tc7_frame)) |
| 135 | #define SCM_VM_FRAME_KIND(x) ((enum scm_vm_frame_kind) (SCM_CELL_WORD_0 (x) >> 8)) |
| 136 | #define SCM_VM_FRAME_DATA(x) ((struct scm_frame *)SCM_CELL_WORD_1 (x)) |
| 137 | #define SCM_VM_FRAME_STACK_HOLDER(f) SCM_VM_FRAME_DATA (f)->stack_holder |
| 138 | #define SCM_VM_FRAME_FP_OFFSET(f) SCM_VM_FRAME_DATA (f)->fp_offset |
| 139 | #define SCM_VM_FRAME_SP_OFFSET(f) SCM_VM_FRAME_DATA (f)->sp_offset |
| 140 | #define SCM_VM_FRAME_FP(f) (SCM_VM_FRAME_FP_OFFSET (f) + scm_i_frame_stack_base (f)) |
| 141 | #define SCM_VM_FRAME_SP(f) (SCM_VM_FRAME_SP_OFFSET (f) + scm_i_frame_stack_base (f)) |
| 142 | #define SCM_VM_FRAME_IP(f) SCM_VM_FRAME_DATA (f)->ip |
| 143 | #define SCM_VM_FRAME_OFFSET(f) scm_i_frame_offset (f) |
| 144 | #define SCM_VALIDATE_VM_FRAME(p,x) SCM_MAKE_VALIDATE (p, x, VM_FRAME_P) |
| 145 | |
| 146 | SCM_INTERNAL SCM* scm_i_frame_stack_base (SCM frame); |
| 147 | SCM_INTERNAL scm_t_ptrdiff scm_i_frame_offset (SCM frame); |
| 148 | |
| 149 | /* See notes in frames.c before using this. */ |
| 150 | SCM_INTERNAL SCM scm_c_frame_closure (enum scm_vm_frame_kind kind, |
| 151 | const struct scm_frame *frame); |
| 152 | |
| 153 | SCM_INTERNAL SCM scm_c_make_frame (enum scm_vm_frame_kind kind, |
| 154 | const struct scm_frame *frame); |
| 155 | |
| 156 | SCM_INTERNAL int scm_c_frame_previous (enum scm_vm_frame_kind kind, |
| 157 | struct scm_frame *frame); |
| 158 | |
| 159 | #endif |
| 160 | |
| 161 | SCM_API SCM scm_frame_p (SCM obj); |
| 162 | SCM_API SCM scm_frame_procedure (SCM frame); |
| 163 | SCM_API SCM scm_frame_call_representation (SCM frame); |
| 164 | SCM_API SCM scm_frame_arguments (SCM frame); |
| 165 | SCM_API SCM scm_frame_source (SCM frame); |
| 166 | SCM_API SCM scm_frame_num_locals (SCM frame); |
| 167 | SCM_API SCM scm_frame_local_ref (SCM frame, SCM index); |
| 168 | SCM_API SCM scm_frame_local_set_x (SCM frame, SCM index, SCM val); |
| 169 | SCM_API SCM scm_frame_address (SCM frame); |
| 170 | SCM_API SCM scm_frame_stack_pointer (SCM frame); |
| 171 | SCM_API SCM scm_frame_instruction_pointer (SCM frame); |
| 172 | SCM_API SCM scm_frame_return_address (SCM frame); |
| 173 | SCM_API SCM scm_frame_dynamic_link (SCM frame); |
| 174 | SCM_API SCM scm_frame_previous (SCM frame); |
| 175 | |
| 176 | SCM_INTERNAL void scm_i_frame_print (SCM frame, SCM port, |
| 177 | scm_print_state *pstate); |
| 178 | SCM_INTERNAL void scm_init_frames (void); |
| 179 | |
| 180 | #endif /* _SCM_FRAMES_H_ */ |
| 181 | |
| 182 | /* |
| 183 | Local Variables: |
| 184 | c-file-style: "gnu" |
| 185 | End: |
| 186 | */ |