--- gforth/doc/vmgen.texi 2002/09/01 15:15:07 1.19 +++ gforth/doc/vmgen.texi 2003/03/09 15:17:02 1.25 @@ -10,7 +10,7 @@ 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, 03,2003 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -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 @@ -96,6 +96,7 @@ Simple instructions * 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 +716,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 +738,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 +805,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 @@ -846,6 +847,7 @@ first one (just as the intuition suggest @menu * 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 -------------------------------------------------------------------- @@ -915,7 +917,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 +977,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 +1063,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 @@ -1078,6 +1112,12 @@ add1 ( n1 -- n1 ) 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 +1203,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 +1217,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 +1236,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 +1426,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 @@ -1786,7 +1832,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?