--- gforth/doc/vmgen.texi	2002/08/22 20:07:33	1.17
+++ gforth/doc/vmgen.texi	2003/03/01 22:39:16	1.23
@@ -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 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -27,7 +27,7 @@ Software Foundation raise funds for GNU
 @end quotation
 @end copying
 
-@dircategory GNU programming tools
+@dircategory Software development
 @direntry
 * Vmgen: (vmgen).               Interpreter generator
 @end direntry
@@ -85,6 +85,7 @@ Input File Format
 * Input File Grammar::          
 * Simple instructions::         
 * Superinstructions::           
+* Store Optimization::          
 * Register Machines::           How to define register VM instructions
 
 Input File Grammar
@@ -95,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
 
@@ -605,6 +607,7 @@ Most examples are taken from the example
 * Input File Grammar::          
 * Simple instructions::         
 * Superinstructions::           
+* Store Optimization::          
 * Register Machines::           How to define register VM instructions
 @end menu
 
@@ -707,12 +710,13 @@ text according to the following grammar;
 Forth you need for using Vmgen:
 
 @example
-text: stack-decl|type-prefix-decl|stack-prefix-decl
+text: stack-decl|type-prefix-decl|stack-prefix-decl|set-flag
 
 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'|'include-skipped-insts') ('on'|'off')
 @end example
 
 Note that the syntax of this code is not checked thoroughly (there are
@@ -732,13 +736,16 @@ are:
 @findex single
 @findex double
 @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" -- )
+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.
@@ -798,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
@@ -841,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 --------------------------------------------------------------------
@@ -910,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
@@ -970,9 +977,36 @@ 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, Register Machines, Simple instructions, Input File Format
+@node Superinstructions, Store Optimization, Simple instructions, Input File Format
 @section Superinstructions
 @cindex superinstructions, defining
 @cindex defining superinstructions
@@ -1029,8 +1063,77 @@ 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 Register Machines,  , Superinstructions, Input File Format
+@node  Store Optimization, Register Machines, Superinstructions, Input File Format
+@section Store Optimization
+@cindex store optimization
+@cindex optimization, stack stores
+@cindex stack stores, optimization
+@cindex eliminating stack stores
+
+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.
+
+What does it do?  Consider an instruction like
+
+@example
+dup ( n -- n n )
+@end example
+
+For simplicity, also assume that we are not caching the top-of-stack in
+a register.  Now, the C code for dup first loads @code{n} from the
+stack, and then stores it twice to the stack, one time to the address
+where it came from; that time is unnecessary, but gcc does not optimize
+it away, so vmgen can do it instead (if you turn on the store
+optimization).
+
+Vmgen uses the stack item's name to determine if the stack item contains
+the same value as it did at the start.  Therefore, if you use the store
+optimization, you have to ensure that stack items that have the same
+name on input and output also have the same value, and are not changed
+in the C code you supply.  I.e., the following code could fail if you
+turn on the store optimization:
+
+@example
+add1 ( n -- n )
+n++;
+@end example
+
+Instead, you have to use different names, i.e.:
+
+@example
+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
+\E store-optimization on
+@end example
+
+at the start of the file.  You can turn this optimization on or off
+between any two VM instruction descriptions.  For turning it off again,
+you can use
+
+@example
+\E store-optimization off
+@end example
+
+@c -------------------------------------------------------------------
+@node Register Machines,  , Store Optimization, Input File Format
 @section Register Machines
 @cindex Register VM
 @cindex Superinstructions for register VMs
@@ -1100,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}.
@@ -1114,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
@@ -1133,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.
@@ -1323,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
@@ -1723,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?
@@ -1746,7 +1855,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).