Commit | Line | Data |
---|---|---|
840ec334 | 1 | /* Copyright (C) 2001, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc. |
560b9c25 AW |
2 | * * |
3 | * This library is free software; you can redistribute it and/or | |
53befeb7 NJ |
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. | |
ac99cb0c | 7 | * |
53befeb7 NJ |
8 | * This library is distributed in the hope that it will be useful, but |
9 | * WITHOUT ANY WARRANTY; without even the implied warranty of | |
560b9c25 AW |
10 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
11 | * Lesser General Public License for more details. | |
ac99cb0c | 12 | * |
560b9c25 AW |
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 | |
53befeb7 NJ |
15 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA |
16 | * 02110-1301 USA | |
560b9c25 | 17 | */ |
ac99cb0c KN |
18 | |
19 | #ifndef _SCM_FRAMES_H_ | |
20 | #define _SCM_FRAMES_H_ | |
21 | ||
22 | #include <libguile.h> | |
ac99cb0c KN |
23 | #include "programs.h" |
24 | ||
ac99cb0c | 25 | \f |
b636cdb0 AW |
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. | |
ac99cb0c | 36 | |
aa3f6951 | 37 | |
b636cdb0 AW |
38 | Stack frame layout |
39 | ------------------ | |
b6368dbb | 40 | |
b636cdb0 AW |
41 | /------------------\ |
42 | | Local N-1 | <- sp | |
03e6c165 | 43 | | ... | |
b636cdb0 AW |
44 | | Local 1 | |
45 | | Local 0 | <- fp = SCM_FRAME_LOCALS_ADDRESS (fp) | |
6c6a4439 | 46 | +==================+ |
b636cdb0 AW |
47 | | Return address | |
48 | | Dynamic link | <- fp - 2 = SCM_FRAME_LOWER_ADDRESS (fp) | |
03e6c165 | 49 | +==================+ |
b636cdb0 | 50 | | | <- fp - 3 = SCM_FRAME_PREVIOUS_SP (fp) |
b6368dbb | 51 | |
b636cdb0 AW |
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. | |
f8085163 | 59 | |
b636cdb0 AW |
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 | |
ac99cb0c | 82 | |
3e54fdfc AW |
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; | |
3e54fdfc | 88 | scm_t_uint8 *return_address; |
b636cdb0 | 89 | SCM locals[1]; /* Variable-length */ |
3e54fdfc AW |
90 | }; |
91 | ||
b636cdb0 | 92 | #define SCM_FRAME_LOWER_ADDRESS(fp) (((SCM *) (fp)) - 2) |
0fc9040f | 93 | #define SCM_FRAME_STRUCT(fp) \ |
b636cdb0 AW |
94 | ((struct scm_vm_frame *) SCM_FRAME_LOWER_ADDRESS (fp)) |
95 | #define SCM_FRAME_LOCALS_ADDRESS(fp) (SCM_FRAME_STRUCT (fp)->locals) | |
af988bbf | 96 | |
b636cdb0 | 97 | #define SCM_FRAME_PREVIOUS_SP(fp) (((SCM *) (fp)) - 3) |
ac99cb0c | 98 | |
3e54fdfc AW |
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) | |
3e54fdfc AW |
103 | #define SCM_FRAME_DYNAMIC_LINK(fp) \ |
104 | (SCM_FRAME_STRUCT (fp)->dynamic_link) | |
105 | #define SCM_FRAME_SET_DYNAMIC_LINK(fp, dl) \ | |
0fc9040f | 106 | SCM_FRAME_DYNAMIC_LINK (fp) = (dl) |
b636cdb0 AW |
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)) | |
ac99cb0c KN |
133 | |
134 | \f | |
510ca126 | 135 | |
f8085163 | 136 | /* FIXME: Replace SCM_FRAME_RETURN_ADDRESS with these. */ |
510ca126 AW |
137 | #define SCM_FRAME_RTL_RETURN_ADDRESS(fp) \ |
138 | ((scm_t_uint32 *) SCM_FRAME_RETURN_ADDRESS (fp)) | |
139 | #define SCM_FRAME_SET_RTL_RETURN_ADDRESS(fp, ip) \ | |
140 | SCM_FRAME_SET_RETURN_ADDRESS (fp, (scm_t_uint8 *) (ip)) | |
141 | ||
510ca126 | 142 | \f |
ac99cb0c | 143 | /* |
af988bbf | 144 | * Heap frames |
ac99cb0c KN |
145 | */ |
146 | ||
aa3f6951 | 147 | struct scm_frame |
b1b942b7 AW |
148 | { |
149 | SCM stack_holder; | |
150 | SCM *fp; | |
151 | SCM *sp; | |
2fb924f6 | 152 | scm_t_uint8 *ip; |
b1b942b7 AW |
153 | scm_t_ptrdiff offset; |
154 | }; | |
155 | ||
dc7da0be | 156 | #define SCM_VM_FRAME_P(x) (SCM_HAS_TYP7 (x, scm_tc7_frame)) |
6f3b0cc2 | 157 | #define SCM_VM_FRAME_DATA(x) ((struct scm_frame*)SCM_CELL_WORD_1 (x)) |
b1b942b7 AW |
158 | #define SCM_VM_FRAME_STACK_HOLDER(f) SCM_VM_FRAME_DATA(f)->stack_holder |
159 | #define SCM_VM_FRAME_FP(f) SCM_VM_FRAME_DATA(f)->fp | |
160 | #define SCM_VM_FRAME_SP(f) SCM_VM_FRAME_DATA(f)->sp | |
161 | #define SCM_VM_FRAME_IP(f) SCM_VM_FRAME_DATA(f)->ip | |
162 | #define SCM_VM_FRAME_OFFSET(f) SCM_VM_FRAME_DATA(f)->offset | |
163 | #define SCM_VALIDATE_VM_FRAME(p,x) SCM_MAKE_VALIDATE (p, x, VM_FRAME_P) | |
164 | ||
aa3f6951 AW |
165 | SCM_API SCM scm_c_make_frame (SCM stack_holder, SCM *fp, SCM *sp, |
166 | scm_t_uint8 *ip, scm_t_ptrdiff offset); | |
167 | SCM_API SCM scm_frame_p (SCM obj); | |
168 | SCM_API SCM scm_frame_procedure (SCM frame); | |
169 | SCM_API SCM scm_frame_arguments (SCM frame); | |
170 | SCM_API SCM scm_frame_source (SCM frame); | |
171 | SCM_API SCM scm_frame_num_locals (SCM frame); | |
172 | SCM_API SCM scm_frame_local_ref (SCM frame, SCM index); | |
173 | SCM_API SCM scm_frame_local_set_x (SCM frame, SCM index, SCM val); | |
2e30f398 | 174 | SCM_API SCM scm_frame_address (SCM frame); |
542f975e | 175 | SCM_API SCM scm_frame_stack_pointer (SCM frame); |
aa3f6951 AW |
176 | SCM_API SCM scm_frame_instruction_pointer (SCM frame); |
177 | SCM_API SCM scm_frame_return_address (SCM frame); | |
aa3f6951 | 178 | SCM_API SCM scm_frame_dynamic_link (SCM frame); |
93dbc31b | 179 | SCM_API SCM scm_frame_previous (SCM frame); |
560b9c25 | 180 | |
6f3b0cc2 AW |
181 | SCM_INTERNAL void scm_i_frame_print (SCM frame, SCM port, |
182 | scm_print_state *pstate); | |
560b9c25 | 183 | SCM_INTERNAL void scm_init_frames (void); |
ac99cb0c KN |
184 | |
185 | #endif /* _SCM_FRAMES_H_ */ | |
186 | ||
187 | /* | |
188 | Local Variables: | |
189 | c-file-style: "gnu" | |
190 | End: | |
191 | */ |