--- gforth/doc/vmgen.texi	2002/08/22 20:07:33	1.17
+++ gforth/doc/vmgen.texi	2003/02/23 21:17:00	1.21
@@ -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
@@ -605,6 +606,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 +709,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' ('on'|'off')
 @end example
 
 Note that the syntax of this code is not checked thoroughly (there are
@@ -732,13 +735,15 @@ 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 )
 @end example
 
 An @var{item-size} takes three cells on the stack.
@@ -972,7 +977,7 @@ contents.
 
 
 @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
@@ -1030,7 +1035,65 @@ does not check these restrictions, they
 interpreter.
 
 @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
+
+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 +1163,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}.
@@ -1723,7 +1786,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 +1809,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).