--- gforth/doc/vmgen.texi 2003/08/25 08:02:58 1.26 +++ gforth/doc/vmgen.texi 2008/08/08 20:56:14 1.32 @@ -10,11 +10,11 @@ This manual is for Vmgen (version @value{VERSION}, @value{UPDATED}), the virtual machine interpreter generator -Copyright @copyright{} 2002, 03,2003 Free Software Foundation, Inc. +Copyright @copyright{} 2002,2003,2005,2007 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the @@ -94,6 +94,7 @@ Input File Grammar Simple instructions +* Explicit stack access:: If the C code accesses a stack pointer * C Code Macros:: Macros recognized by Vmgen * C Code restrictions:: Vmgen makes assumptions about C code * Stack growth direction:: is configurable per stack @@ -330,7 +331,7 @@ instructions. Another option is to use for the virtual machine; we believe that using a stack architecture is usually both simpler and faster. -however, this option is slower or +However, this option is slower or significantly more complex to implement than a stack machine architecture. Vmgen has special support and optimizations for stack VMs, making their @@ -829,6 +830,7 @@ name. Stack prefixes are defined like t @example \E inst-stream stack-prefix # +\E data-stack stack-prefix S: @end example This definition defines that the stack prefix @code{#} specifies the @@ -845,13 +847,68 @@ If there are multiple instruction stream first one (just as the intuition suggests). @menu +* Explicit stack access:: If the C code accesses a stack pointer * C Code Macros:: Macros recognized by Vmgen * C Code restrictions:: Vmgen makes assumptions about C code * Stack growth direction:: is configurable per stack @end menu @c -------------------------------------------------------------------- -@node C Code Macros, C Code restrictions, Simple instructions, Simple instructions +@node Explicit stack access, C Code Macros, Simple instructions, Simple instructions +@subsection Explicit stack access +@cindex stack access, explicit +@cindex Stack pointer access +@cindex explicit stack access + +Not all stack effects can be specified using the stack effect +specifications above. For VM instructions that have other stack +effects, you can specify them explicitly by accessing the stack +pointer in the C code; however, you have to notify Vmgen of such +explicit stack accesses, otherwise Vmgens optimizations could conflict +with your explicit stack accesses. + +You notify Vmgen by putting @code{...} with the appropriate stack +prefix into the stack comment. Then the VM instruction will first +take the other stack items specified in the stack effect into C +variables, then make sure that all other stack items for that stack +are in memory, and that the stack pointer for the stack points to the +top-of-stack (by default, unless you change the stack access +transformation: @pxref{Stack growth direction}). + +The general rule is: If you mention a stack pointer in the C code of a +VM instruction, you should put a @code{...} for that stack in the stack +effect. + +Consider this example: + +@example +return ( #iadjust S:... target afp i1 -- i2 ) +SET_IP(target); +sp = (Cell *)(((char *)sp)+iadjust); +fp = afp; +i2=i1; +@end example + +First the variables @code{target afp i1} are popped off the stack, +then the stack pointer @code{sp} is set correctly for the new stack +depth, then the C code changes the stack depth and does other things, +and finally @code{i2} is pushed on the stack with the new depth. + +The position of the @code{...} within the stack effect does not +matter. You can use several @code{...}s, for different stacks, and +also several for the same stack (that has no additional effect). If +you use @code{...} without a stack prefix, this specifies all the +stacks except the instruction stream. + +You cannot use @code{...} for the instruction stream, but that is not +necessary: At the start of the C code, @code{IP} points to the start +of the next VM instruction (i.e., right beyond the end of the current +VM instruction), and you can change the instruction pointer with +@code{SET_IP} (@pxref{VM engine}). + + +@c -------------------------------------------------------------------- +@node C Code Macros, C Code restrictions, Explicit stack access, Simple instructions @subsection C Code Macros @cindex macros recognized by Vmgen @cindex basic block, VM level @@ -906,6 +963,14 @@ if (branch_condition) @{ SUPER_CONTINUE; @end example +@item VM_JUMP +@findex VM_JUMP +@code{VM_JUMP(target)} is equivalent to @code{goto *(target)}, but +allows Vmgen to do dynamic superinstructions and replication. You +still need to say @code{SUPER_END}. Also, the goto only happens at +the end (wherever the VM_JUMP is). Essentially, this just suppresses +much of the ordinary dispatch mechanism. + @end table Note that Vmgen is not smart about C-level tokenization, comments, @@ -1076,7 +1141,7 @@ optimizer for both variations, so leave @cindex stack stores, optimization @cindex eliminating stack stores -This minor optimization (0.6\%--0.8\% reduction in executed instructions +This minor optimization (0.6%--0.8% reduction in executed instructions for Gforth) puts additional requirements on the instruction descriptions and is therefore disabled by default. @@ -1108,7 +1173,7 @@ n++; Instead, you have to use different names, i.e.: @example -add1 ( n1 -- n1 ) +add1 ( n1 -- n2 ) n2=n1+1; @end example @@ -1931,6 +1996,8 @@ You can find vmgen information at * GNU Free Documentation License:: License for copying this manual. @end menu +@node GNU Free Documentation License, , Copying This Manual, Copying This Manual +@appendixsec GNU Free Documentation License @include fdl.texi