1 /* Copyright (C) 2001, 2009, 2010, 2011, 2012, 2013, 2014, 2015 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 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 +==================+ <- fp + 2 = SCM_FRAME_PREVIOUS_SP (fp) 43 | Dynamic link | 44 +------------------+ 45 | Return address | 46 +==================+ <- fp 47 | Local 0 | 48 +------------------+ 49 | Local 1 | 50 +------------------+ 51 | ... | 52 +------------------+ 53 | Local N-1 | 54 \------------------/ <- sp 55 56 The stack grows down. 57 58 The calling convention is that a caller prepares a stack frame 59 consisting of the saved FP and the return address, followed by the 60 procedure and then the arguments to the call, in order. Thus in the 61 beginning of a call, the procedure being called is in slot 0, the 62 first argument is in slot 1, and the SP points to the last argument. 63 The number of arguments, including the procedure, is thus FP - SP. 64 65 After ensuring that the correct number of arguments have been passed, 66 a function will set the stack pointer to point to the last local 67 slot. This lets a function allocate the temporary space that it 68 needs once in the beginning of the call, instead of pushing and 69 popping the stack pointer during the call's extent. 70 71 When a program returns, it returns its values in the slots starting 72 from local 1, as if the values were arguments to a tail call. We 73 start from 1 instead of 0 for the convenience of the "values" builtin 74 function, which can just leave its arguments in place. 75 76 The callee resets the stack pointer to point to the last value. In 77 this way the caller knows how many values there are: it's the number 78 of words between the stack pointer and the slot at which the caller 79 placed the procedure. 80 81 After checking that the number of values returned is appropriate, the 82 caller shuffles the values around (if needed), and resets the stack 83 pointer back to its original value from before the call. */ 84 85 86 87 88 /* Each element on the stack occupies the same amount of space. */ 89 union scm_vm_stack_element 90 { 91 scm_t_uintptr as_uint; 92 scm_t_uint32 *as_ip; 93 SCM as_scm; 94 double as_f64; 95 scm_t_uint64 as_u64; 96 scm_t_int64 as_s64; 97 98 /* For GC purposes. */ 99 void *as_ptr; 100 scm_t_bits as_bits; 101 }; 102 103 #define SCM_FRAME_PREVIOUS_SP(fp) ((fp) + 2) 104 #define SCM_FRAME_RETURN_ADDRESS(fp) ((fp)[0].as_ip) 105 #define SCM_FRAME_SET_RETURN_ADDRESS(fp, ra) ((fp)[0].as_ip = (ra)) 106 #define SCM_FRAME_DYNAMIC_LINK(fp) ((fp) + (fp)[1].as_uint) 107 #define SCM_FRAME_SET_DYNAMIC_LINK(fp, dl) ((fp)[1].as_uint = ((dl) - (fp))) 108 #define SCM_FRAME_SLOT(fp,i) ((fp) - (i) - 1) 109 #define SCM_FRAME_LOCAL(fp,i) (SCM_FRAME_SLOT (fp, i)->as_scm) 110 #define SCM_FRAME_NUM_LOCALS(fp, sp) ((fp) - (sp)) 111 112 113 /* 114 * Heap frames 115 */ 116 117 #ifdef BUILDING_LIBGUILE 118 119 struct scm_frame 120 { 121 void *stack_holder; 122 scm_t_ptrdiff fp_offset; 123 scm_t_ptrdiff sp_offset; 124 scm_t_uint32 *ip; 125 }; 126 127 enum scm_vm_frame_kind 128 { 129 SCM_VM_FRAME_KIND_VM, 130 SCM_VM_FRAME_KIND_CONT 131 }; 132 133 #define SCM_VM_FRAME_P(x) (SCM_HAS_TYP7 (x, scm_tc7_frame)) 134 #define SCM_VM_FRAME_KIND(x) ((enum scm_vm_frame_kind) (SCM_CELL_WORD_0 (x) >> 8)) 135 #define SCM_VM_FRAME_DATA(x) ((struct scm_frame *)SCM_CELL_WORD_1 (x)) 136 #define SCM_VM_FRAME_STACK_HOLDER(f) SCM_VM_FRAME_DATA (f)->stack_holder 137 #define SCM_VM_FRAME_FP_OFFSET(f) SCM_VM_FRAME_DATA (f)->fp_offset 138 #define SCM_VM_FRAME_SP_OFFSET(f) SCM_VM_FRAME_DATA (f)->sp_offset 139 #define SCM_VM_FRAME_FP(f) (scm_i_frame_stack_top (f) - SCM_VM_FRAME_FP_OFFSET (f)) 140 #define SCM_VM_FRAME_SP(f) (scm_i_frame_stack_top (f) - SCM_VM_FRAME_SP_OFFSET (f)) 141 #define SCM_VM_FRAME_IP(f) SCM_VM_FRAME_DATA (f)->ip 142 #define SCM_VALIDATE_VM_FRAME(p,x) SCM_MAKE_VALIDATE (p, x, VM_FRAME_P) 143 144 SCM_INTERNAL union scm_vm_stack_element* scm_i_frame_stack_top (SCM frame); 145 146 /* See notes in frames.c before using this. */ 147 SCM_INTERNAL SCM scm_c_frame_closure (enum scm_vm_frame_kind kind, 148 const struct scm_frame *frame); 149 150 SCM_INTERNAL SCM scm_c_make_frame (enum scm_vm_frame_kind kind, 151 const struct scm_frame *frame); 152 153 SCM_INTERNAL int scm_c_frame_previous (enum scm_vm_frame_kind kind, 154 struct scm_frame *frame); 155 156 #endif 157 158 SCM_API SCM scm_frame_p (SCM obj); 159 SCM_API SCM scm_frame_procedure_name (SCM frame); 160 SCM_API SCM scm_frame_call_representation (SCM frame); 161 SCM_API SCM scm_frame_arguments (SCM frame); 162 SCM_API SCM scm_frame_source (SCM frame); 163 SCM_API SCM scm_frame_address (SCM frame); 164 SCM_API SCM scm_frame_stack_pointer (SCM frame); 165 SCM_API SCM scm_frame_instruction_pointer (SCM frame); 166 SCM_API SCM scm_frame_return_address (SCM frame); 167 SCM_API SCM scm_frame_dynamic_link (SCM frame); 168 SCM_API SCM scm_frame_previous (SCM frame); 169 170 SCM_INTERNAL void scm_i_frame_print (SCM frame, SCM port, 171 scm_print_state *pstate); 172 SCM_INTERNAL void scm_init_frames (void); 173 174 #endif /* _SCM_FRAMES_H_ */ 175 176 /* 177 Local Variables: 178 c-file-style: "gnu" 179 End: 180 */ 181