--- gforth/doc/vmgen.texi 2002/08/28 21:46:59 1.18 +++ gforth/doc/vmgen.texi 2007/12/31 18:56:18 1.30 @@ -10,11 +10,11 @@ This manual is for Vmgen (version @value{VERSION}, @value{UPDATED}), the virtual machine interpreter generator -Copyright @copyright{} 2002 Free Software Foundation, Inc. +Copyright @copyright{} 2002,2003,2005 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 @@ -27,9 +27,9 @@ Software Foundation raise funds for GNU @end quotation @end copying -@dircategory GNU programming tools +@dircategory Software development @direntry -* Vmgen: (vmgen). Interpreter generator +* Vmgen: (vmgen). Virtual machine interpreter generator @end direntry @titlepage @@ -94,8 +94,10 @@ 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 Using the generated code @@ -715,7 +717,7 @@ stack-decl: 'stack ' ident ident ident type-prefix-decl: 's" ' string '" ' ('single'|'double') ident 'type-prefix' ident stack-prefix-decl: ident 'stack-prefix' string -set-flag: 'store-optimization' ('on'|'off') +set-flag: ('store-optimization'|'include-skipped-insts') ('on'|'off') @end example Note that the syntax of this code is not checked thoroughly (there are @@ -737,13 +739,14 @@ are: @findex stack-prefix @findex store-optimization @example -stack ( "name" "pointer" "type" -- ) - ( name execution: -- stack ) -type-prefix ( addr u item-size stack "prefix" -- ) -single ( -- item-size ) -double ( -- item-size ) -stack-prefix ( stack "prefix" -- ) -store-optimization ( -- addr ) +stack ( "name" "pointer" "type" -- ) + ( name execution: -- stack ) +type-prefix ( addr u item-size stack "prefix" -- ) +single ( -- item-size ) +double ( -- item-size ) +stack-prefix ( stack "prefix" -- ) +store-optimization ( -- addr ) +include-skipped-insts ( -- addr ) @end example An @var{item-size} takes three cells on the stack. @@ -803,14 +806,13 @@ Before we can use @code{data-stack} in t @cindex stack basic type @cindex basic type of a stack @cindex type of a stack, basic -@cindex stack growth direction This line defines the stack @code{data-stack}, which uses the stack pointer @code{sp}, and each item has the basic type @code{Cell}; other types have to fit into one or two @code{Cell}s (depending on whether the type is @code{single} or @code{double} wide), and are cast from and to Cells on accessing the @code{data-stack} with type cast macros -(@pxref{VM engine}). Stacks grow towards lower addresses in -Vmgen-erated interpreters. +(@pxref{VM engine}). By default, stacks grow towards lower addresses in +Vmgen-erated interpreters (@pxref{Stack growth direction}). @cindex stack prefix @cindex prefix, stack @@ -828,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 @@ -844,12 +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 @@ -904,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, @@ -915,7 +982,7 @@ a C preprocessor macro. @c -------------------------------------------------------------------- -@node C Code restrictions, , C Code Macros, Simple instructions +@node C Code restrictions, Stack growth direction, C Code Macros, Simple instructions @subsection C Code restrictions @cindex C code restrictions @cindex restrictions on C code @@ -975,6 +1042,33 @@ macros can be implemented in several way @samp{IP} points to the next instruction, and @samp{IPTOS} is its contents. +@c -------------------------------------------------------------------- +@node Stack growth direction, , C Code restrictions, Simple instructions +@subsection Stack growth direction +@cindex stack growth direction + +@cindex @code{stack-access-transform} +By default, the stacks grow towards lower addresses. You can change +this for a stack by setting the @code{stack-access-transform} field of +the stack to an xt @code{( itemnum -- index )} that performs the +appropriate index transformation. + +E.g., if you want to let @code{data-stack} grow towards higher +addresses, with the stack pointer always pointing just beyond the +top-of-stack, use this right after defining @code{data-stack}: + +@example +\E : sp-access-transform ( itemnum -- index ) negate 1- ; +\E ' sp-access-transform ' data-stack >body stack-access-transform ! +@end example + +This means that @code{sp-access-transform} will be used to generate +indexes for accessing @code{data-stack}. The definition of +@code{sp-access-transform} above transforms n into -n-1, e.g, 1 into -2. +This will access the 0th data-stack element (top-of-stack) at sp[-1], +the 1st at sp[-2], etc., which is the typical way upward-growing +stacks are used. If you need a different transform and do not know +enough Forth to program it, let me know. @c -------------------------------------------------------------------- @node Superinstructions, Store Optimization, Simple instructions, Input File Format @@ -1034,6 +1128,11 @@ accesses a stack pointer should not be u does not check these restrictions, they just result in bugs in your interpreter. +@cindex include-skipped-insts +The Vmgen flag @code{include-skipped-insts} influences superinstruction +code generation. Currently there is no support in the peephole +optimizer for both variations, so leave this flag alone for now. + @c ------------------------------------------------------------------- @node Store Optimization, Register Machines, Superinstructions, Input File Format @section Store Optimization @@ -1074,10 +1173,16 @@ n++; Instead, you have to use different names, i.e.: @example -add1 ( n1 -- n1 ) +add1 ( n1 -- n2 ) n2=n1+1; @end example +Similarly, the store optimization assumes that the stack pointer is only +changed by Vmgen-erated code. If your C code changes the stack pointer, +use different names in input and output stack items to avoid a (probably +wrong) store optimization, or turn the store optimization off for this +VM instruction. + To turn on the store optimization, write @example @@ -1163,7 +1268,7 @@ You have used an instruction-stream pref side). @cindex @code{prefix for this combination must be defined earlier} error -@item the prefix for this combination must be defined earlier +@item the prefix for this superinstruction must be defined earlier You have defined a superinstruction (e.g. @code{abc = a b c}) without defining its direct prefix (e.g., @code{ab = a b}), @xref{Superinstructions}. @@ -1177,7 +1282,7 @@ expected by Vmgen (this should not happe line in a bug report). @cindex @code{syntax error, wrong char} error -@cindex syntax error, wrong char +@item syntax error, wrong char A syntax error. If you do not see right away where the error is, it may be helpful to check the following: Did you put an empty line in a VM instruction where the C code is not delimited by braces (then the empty @@ -1196,7 +1301,7 @@ The stack item does not match any define away any stack prefix). You should either declare the type prefix you want for that stack item, or use a different type prefix -@item @code{unknown primitive} error +@cindex @code{unknown primitive} error @item unknown primitive You have used the name of a simple VM instruction in a superinstruction definition without defining the simple VM instruction first. @@ -1386,6 +1491,12 @@ type. For @samp{inst-stream}, the name plain r-value; typically it is a macro that abstracts away the differences between the various implementations of @code{NEXT_P*}. +@cindex IMM_ARG +@findex IMM_ARG +@item IMM_ARG(access,value) +Define this to expland to ``(access)''. This is just a placeholder for +future extensions. + @cindex top of stack caching @cindex stack caching @cindex TOS @@ -1415,6 +1526,13 @@ profiling. @item SUPER_CONTINUE This is just a hint to Vmgen and does nothing at the C level. +@findex MAYBE_UNUSED +@item MAYBE_UNUSED +This should be defined as @code{__attribute__((unused))} for gcc-2.7 and +higher. It suppresses the warnings about unused variables in the code +for superinstructions. You need to define this only if you are using +superinstructions. + @findex VM_DEBUG @item VM_DEBUG If this is defined, the tracing code will be compiled in (slower @@ -1592,7 +1710,7 @@ instruction instead of laying down @code The code for peephole optimization is in @file{vmgen-ex/peephole.c}. You can use this file almost verbatim. Vmgen generates -@file{@var{file}-peephole.i} which contains data for the peephoile +@file{@var{file}-peephole.i} which contains data for the peephole optimizer. @findex init_peeptable @@ -1786,7 +1904,7 @@ a major change, and it's ramifications a @chapter The future @cindex future ideas -We have a number of ideas for future versions of Gforth. However, there +We have a number of ideas for future versions of Vmgen. However, there are so many possible things to do that we would like some feedback from you. What are you doing with Vmgen, what features are you missing, and why? @@ -1809,7 +1927,13 @@ please let us know. @chapter Changes @cindex Changes from old versions -Use-visible changes between 0.5.9-20010501 and 0.5.9-20020822: +User-visible changes between 0.5.9-20020822 and 0.5.9-20020901: + +The store optimization is now disabled by default, but can be enabled by +the user (@pxref{Store Optimization}). Documentation for this +optimization is also new. + +User-visible changes between 0.5.9-20010501 and 0.5.9-20020822: There is now a manual (in info, HTML, Postscript, or plain text format). @@ -1872,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