From ac70ac307e0e613f2cd33f3809eaa69e67ba4008 Mon Sep 17 00:00:00 2001 From: Andy Wingo Date: Sat, 15 Aug 2009 14:27:15 +0200 Subject: update docs for calling convention change * doc/ref/vm.texi: Update. --- doc/ref/vm.texi | 118 ++++++++++++++++++++++++++------------------------------ 1 file changed, 54 insertions(+), 64 deletions(-) diff --git a/doc/ref/vm.texi b/doc/ref/vm.texi index 59798d881..04a3b7949 100644 --- a/doc/ref/vm.texi +++ b/doc/ref/vm.texi @@ -159,17 +159,19 @@ The structure of the fixed part of an application frame is as follows: @example Stack - | | <- fp + bp->nargs + bp->nlocs + 3 - +------------------+ = SCM_FRAME_UPPER_ADDRESS (fp) - | Return address | - | MV return address| - | Dynamic link | <- fp + bp->nargs + bp->nlocs - | Local variable 1 | = SCM_FRAME_DATA_ADDRESS (fp) + | ... | + | Intermed. val. 0 | <- fp + bp->nargs + bp->nlocs = SCM_FRAME_UPPER_ADDRESS (fp) + +==================+ + | Local variable 1 | | Local variable 0 | <- fp + bp->nargs | Argument 1 | | Argument 0 | <- fp | Program | <- fp - 1 - +------------------+ = SCM_FRAME_LOWER_ADDRESS (fp) + +------------------+ + | Return address | + | MV return address| + | Dynamic link | <- fp - 4 = SCM_FRAME_DATA_ADDRESS (fp) = SCM_FRAME_LOWER_ADDRESS (fp) + +==================+ | | @end example @@ -649,32 +651,30 @@ closures. @node Procedural Instructions @subsubsection Procedural Instructions -@deffn Instruction return -Free the program's frame, returning the top value from the stack to -the current continuation. (The stack should have exactly one value on -it.) - -Specifically, the @code{sp} is decremented to one below the current -@code{fp}, the @code{ip} is reset to the current return address, the -@code{fp} is reset to the value of the current dynamic link, and then -the top item on the stack (formerly the procedure being applied) is -set to the returned value. +@deffn Instructions new-frame +Push a new frame on the stack, reserving space for the dynamic link, +return address, and the multiple-values return address. The frame +pointer is not yet updated, because the frame is not yet active -- it +has to be patched by a @code{call} instruction to get the return +address. @end deffn @deffn Instruction call nargs Call the procedure located at @code{sp[-nargs]} with the @var{nargs} arguments located from @code{sp[-nargs + 1]} to @code{sp[0]}. -For compiled procedures, this instruction sets up a new stack frame, -as described in @ref{Stack Layout}, and then dispatches to the first -instruction in the called procedure, relying on the called procedure -to return one value to the newly-created continuation. Because the new -frame pointer will point to sp[-nargs + 1], the arguments don't have -to be shuffled around -- they are already in place. +This instruction requires that a new frame be pushed on the stack +before the procedure, via @code{new-frame}. @xref{Stack Layout}, for +more information. It patches up that frame with the current @code{ip} +as the return address, then dispatches to the first instruction in the +called procedure, relying on the called procedure to return one value +to the newly-created continuation. Because the new frame pointer will +point to sp[-nargs + 1], the arguments don't have to be shuffled +around -- they are already in place. For non-compiled procedures (continuations, primitives, and -interpreted procedures), @code{call} will pop the procedure and -arguments off the stack, and push the result of calling +interpreted procedures), @code{call} will pop the frame, procedure, +and arguments off the stack, and push the result of calling @code{scm_apply}. @end deffn @@ -682,10 +682,10 @@ arguments off the stack, and push the result of calling Like @code{call}, but reusing the current continuation. This instruction implements tail calls as required by RnRS. -For compiled procedures, that means that @code{goto/args} reuses the -current frame instead of building a new one. The @code{goto/*} -instruction family is named as it is because tail calls are equivalent -to @code{goto}, along with relabeled variables. +For compiled procedures, that means that @code{goto/args} simply +shuffles down the procedure and arguments to the current stack frame. +The @code{goto/*} instruction family is named as it is because tail +calls are equivalent to @code{goto}, along with relabeled variables. For non-VM procedures, the result is the same, but the current VM invocation remains on the C stack. True tail calls are not currently @@ -708,15 +708,6 @@ These instructions are used in the implementation of multiple value returns, where the actual number of values is pushed on the stack. @end deffn -@deffn Instruction call/cc -@deffnx Instruction goto/cc -Capture the current continuation, and then call (or tail-call) the -procedure on the top of the stack, with the continuation as the -argument. - -Both the VM continuation and the C continuation are captured. -@end deffn - @deffn Instruction mv-call nargs offset Like @code{call}, except that a multiple-value continuation is created in addition to a single-value continuation. @@ -729,6 +720,18 @@ the stack to be the number of values, and below that values themselves, pushed separately. @end deffn +@deffn Instruction return +Free the program's frame, returning the top value from the stack to +the current continuation. (The stack should have exactly one value on +it.) + +Specifically, the @code{sp} is decremented to one below the current +@code{fp}, the @code{ip} is reset to the current return address, the +@code{fp} is reset to the value of the current dynamic link, and then +the top item on the stack (formerly the procedure being applied) is +set to the returned value. +@end deffn + @deffn Instruction return/values nvalues Return the top @var{nvalues} to the current continuation. @@ -763,6 +766,19 @@ be 1 (to indicate that one of the bindings was a rest argument). Signals an error if there is an insufficient number of values. @end deffn +@deffn Instruction call/cc +@deffnx Instruction goto/cc +Capture the current continuation, and then call (or tail-call) the +procedure on the top of the stack, with the continuation as the +argument. + +@code{call/cc} does not require a @code{new-frame} to be pushed on the +stack, as @code{call} does, because it needs to capture the stack +before the frame is pushed. + +Both the VM continuation and the C continuation are captured. +@end deffn + @node Data Control Instructions @subsubsection Data Control Instructions @@ -838,32 +854,6 @@ popping off those values and pushing on the resulting vector. @var{n} is a two-byte value, like in @code{vector}. @end deffn -@deffn Instruction mark -Pushes a special value onto the stack that other stack instructions -like @code{list-mark} can use. -@end deffn - -@deffn Instruction list-mark -Create a list from values from the stack, as in @code{list}, but -instead of knowing beforehand how many there will be, keep going until -we see a @code{mark} value. -@end deffn - -@deffn Instruction cons-mark -As the scheme procedure @code{cons*} is to the scheme procedure -@code{list}, so the instruction @code{cons-mark} is to the instruction -@code{list-mark}. -@end deffn - -@deffn Instruction vector-mark -Like @code{list-mark}, but makes a vector instead of a list. -@end deffn - -@deffn Instruction list-break -The opposite of @code{list}: pops a value, which should be a list, and -pushes its elements on the stack. -@end deffn - @node Miscellaneous Instructions @subsubsection Miscellaneous Instructions -- cgit v1.2.1