Diff for /gforth/doc/vmgen.texi between versions 1.15 and 1.19

version 1.15, 2002/08/20 16:59:01 version 1.19, 2002/09/01 15:15:07
Line 85  Input File Format Line 85  Input File Format
 * Input File Grammar::            * Input File Grammar::          
 * Simple instructions::           * Simple instructions::         
 * Superinstructions::             * Superinstructions::           
   * Store Optimization::          
 * Register Machines::           How to define register VM instructions  * Register Machines::           How to define register VM instructions
   
   Input File Grammar
   
   * Eval escapes::                what follows \E
   
 Simple instructions  Simple instructions
   
 * C Code Macros::               Macros recognized by Vmgen  * C Code Macros::               Macros recognized by Vmgen
Line 601  Most examples are taken from the example Line 606  Most examples are taken from the example
 * Input File Grammar::            * Input File Grammar::          
 * Simple instructions::           * Simple instructions::         
 * Superinstructions::             * Superinstructions::           
   * Store Optimization::          
 * Register Machines::           How to define register VM instructions  * Register Machines::           How to define register VM instructions
 @end menu  @end menu
   
Line 683  Vmgen understands a few extensions beyon Line 689  Vmgen understands a few extensions beyon
 these extensions are only useful for building Gforth.  You can find a  these extensions are only useful for building Gforth.  You can find a
 description of the format used for Gforth in @file{prim}.  description of the format used for Gforth in @file{prim}.
   
   @menu
   * Eval escapes::                what follows \E
   @end menu
   
   @node Eval escapes,  , Input File Grammar, Input File Grammar
 @subsection Eval escapes  @subsection Eval escapes
 @cindex escape to Forth  @cindex escape to Forth
 @cindex eval escape  @cindex eval escape
Line 698  text according to the following grammar; Line 709  text according to the following grammar;
 Forth you need for using Vmgen:  Forth you need for using Vmgen:
   
 @example  @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  stack-decl: 'stack ' ident ident ident
 type-prefix-decl:   type-prefix-decl: 
     's" ' string '" ' ('single'|'double') ident 'type-prefix' ident      's" ' string '" ' ('single'|'double') ident 'type-prefix' ident
 stack-prefix-decl:  ident 'stack-prefix' string  stack-prefix-decl:  ident 'stack-prefix' string
   set-flag: 'store-optimization' ('on'|'off')
 @end example  @end example
   
 Note that the syntax of this code is not checked thoroughly (there are  Note that the syntax of this code is not checked thoroughly (there are
Line 723  are: Line 735  are:
 @findex single  @findex single
 @findex double  @findex double
 @findex stack-prefix  @findex stack-prefix
   @findex store-optimization
 @example  @example
 stack        ( "name" "pointer" "type" -- )  stack              ( "name" "pointer" "type" -- )
              ( name execution: -- stack )                     ( name execution: -- stack )
 type-prefix  ( addr u item-size stack "prefix" -- )  type-prefix        ( addr u item-size stack "prefix" -- )
 single       ( -- item-size )  single             ( -- item-size )
 double       ( -- item-size )  double             ( -- item-size )
 stack-prefix ( stack "prefix" -- )  stack-prefix       ( stack "prefix" -- )
   store-optimization ( -- addr )
 @end example  @end example
   
 An @var{item-size} takes three cells on the stack.  An @var{item-size} takes three cells on the stack.
Line 963  contents. Line 977  contents.
   
   
 @c --------------------------------------------------------------------  @c --------------------------------------------------------------------
 @node Superinstructions, Register Machines, Simple instructions, Input File Format  @node Superinstructions, Store Optimization, Simple instructions, Input File Format
 @section Superinstructions  @section Superinstructions
 @cindex superinstructions, defining  @cindex superinstructions, defining
 @cindex defining superinstructions  @cindex defining superinstructions
Line 1021  does not check these restrictions, they Line 1035  does not check these restrictions, they
 interpreter.  interpreter.
   
 @c -------------------------------------------------------------------  @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  @section Register Machines
 @cindex Register VM  @cindex Register VM
 @cindex Superinstructions for register VMs  @cindex Superinstructions for register VMs
Line 1101  defining its direct prefix (e.g., @code{ Line 1173  defining its direct prefix (e.g., @code{
 If you are using a preprocessor (e.g., @command{m4}) to generate Vmgen  If you are using a preprocessor (e.g., @command{m4}) to generate Vmgen
 input code, you may want to create @code{#line} directives (aka sync  input code, you may want to create @code{#line} directives (aka sync
 lines).  This error indicates that such a line is not in th syntax  lines).  This error indicates that such a line is not in th syntax
 expected by Vmgen (this should not happen).  expected by Vmgen (this should not happen; please report the offending
   line in a bug report).
   
 @cindex @code{syntax error, wrong char} error  @cindex @code{syntax error, wrong char} error
 @cindex syntax error, wrong char  @cindex syntax error, wrong char
 A syntax error.  Note that Vmgen is sometimes anal retentive about white  A syntax error.  If you do not see right away where the error is, it may
 space, especially about newlines.  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
   line ends the VM instruction)?  If you used brace-delimited C code, did
   you put the delimiting braces (and only those) at the start of the line,
   without preceding white space?  Did you forget a delimiting brace?
   
 @cindex @code{too many stacks} error  @cindex @code{too many stacks} error
 @item too many stacks  @item too many stacks
 Vmgen currently supports 4 stacks; if you need more, let us know.  Vmgen currently supports 3 stacks (plus the instruction stream); if you
   need more, let us know.
   
 @cindex @code{unknown prefix} error  @cindex @code{unknown prefix} error
 @item unknown prefix  @item unknown prefix
Line 1731  please let us know. Line 1809  please let us know.
 @chapter Changes  @chapter Changes
 @cindex Changes from old versions  @cindex Changes from old versions
   
   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).
   
   There is the vmgen-ex2 variant of the vmgen-ex example; the new
   variant uses a union type instead of lots of casting.
   
   Both variants of the example can now be compiled with an ANSI C compiler
   (using switch dispatch and losing quite a bit of performance); tested
   with @command{lcc}.
   
 Users of the gforth-0.5.9-20010501 version of Vmgen need to change  Users of the gforth-0.5.9-20010501 version of Vmgen need to change
 several things in their source code to use the current version.  I  several things in their source code to use the current version.  I
 recommend keeping the gforth-0.5.9-20010501 version until you have  recommend keeping the gforth-0.5.9-20010501 version until you have
Line 1765  Also some new macros have to be defined, Line 1860  Also some new macros have to be defined,
 @node Contact, Copying This Manual, Changes, Top  @node Contact, Copying This Manual, Changes, Top
 @chapter Contact  @chapter Contact
   
   To report a bug, use
   @url{https://savannah.gnu.org/bugs/?func=addbug&group_id=2672}.
   
   For discussion on Vmgen (e.g., how to use it), use the mailing list
   @email{bug-vmgen@@mail.freesoftware.fsf.org} (use
   @url{http://mail.gnu.org/mailman/listinfo/help-vmgen} to subscribe).
   
   You can find vmgen information at
   @url{http://www.complang.tuwien.ac.at/anton/vmgen/}.
   
 @c ***********************************************************  @c ***********************************************************
 @node Copying This Manual, Index, Contact, Top  @node Copying This Manual, Index, Contact, Top
 @appendix Copying This Manual  @appendix Copying This Manual

Removed from v.1.15  
changed lines
  Added in v.1.19


FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>