Diff for /gforth/doc/vmgen.texi between versions 1.20 and 1.24

version 1.20, 2002/09/22 09:00:05 version 1.24, 2003/03/02 13:12:33
Line 10  This manual is for Vmgen Line 10  This manual is for Vmgen
 (version @value{VERSION}, @value{UPDATED}),  (version @value{VERSION}, @value{UPDATED}),
 the virtual machine interpreter generator  the virtual machine interpreter generator
   
 Copyright @copyright{} 2002 Free Software Foundation, Inc.  Copyright @copyright{} 2002, 03 Free Software Foundation, Inc.
   
 @quotation  @quotation
 Permission is granted to copy, distribute and/or modify this document  Permission is granted to copy, distribute and/or modify this document
Line 27  Software Foundation raise funds for GNU Line 27  Software Foundation raise funds for GNU
 @end quotation  @end quotation
 @end copying  @end copying
   
 @dircategory GNU programming tools  @dircategory Software development
 @direntry  @direntry
 * Vmgen: (vmgen).               Interpreter generator  * Vmgen: (vmgen).               Virtual machine interpreter generator
 @end direntry  @end direntry
   
 @titlepage  @titlepage
Line 96  Simple instructions Line 96  Simple instructions
   
 * C Code Macros::               Macros recognized by Vmgen  * C Code Macros::               Macros recognized by Vmgen
 * C Code restrictions::         Vmgen makes assumptions about C code  * C Code restrictions::         Vmgen makes assumptions about C code
   * Stack growth direction::      is configurable per stack
   
 Using the generated code  Using the generated code
   
Line 715  stack-decl: 'stack ' ident ident ident Line 716  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')  set-flag: ('store-optimization'|'include-skipped-insts') ('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 737  are: Line 738  are:
 @findex stack-prefix  @findex stack-prefix
 @findex store-optimization  @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 )  store-optimization    ( -- addr )
   include-skipped-insts ( -- 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 803  Before we can use @code{data-stack} in t Line 805  Before we can use @code{data-stack} in t
 @cindex stack basic type  @cindex stack basic type
 @cindex basic type of a stack  @cindex basic type of a stack
 @cindex type of a stack, basic  @cindex type of a stack, basic
 @cindex stack growth direction  
 This line defines the stack @code{data-stack}, which uses the stack  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  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  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  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  Cells on accessing the @code{data-stack} with type cast macros
 (@pxref{VM engine}).  Stacks grow towards lower addresses in  (@pxref{VM engine}).  By default, stacks grow towards lower addresses in
 Vmgen-erated interpreters.  Vmgen-erated interpreters (@pxref{Stack growth direction}).
   
 @cindex stack prefix  @cindex stack prefix
 @cindex prefix, stack  @cindex prefix, stack
Line 846  first one (just as the intuition suggest Line 847  first one (just as the intuition suggest
 @menu  @menu
 * C Code Macros::               Macros recognized by Vmgen  * C Code Macros::               Macros recognized by Vmgen
 * C Code restrictions::         Vmgen makes assumptions about C code  * C Code restrictions::         Vmgen makes assumptions about C code
   * Stack growth direction::      is configurable per stack
 @end menu  @end menu
   
 @c --------------------------------------------------------------------  @c --------------------------------------------------------------------
Line 915  a C preprocessor macro. Line 917  a C preprocessor macro.
   
   
 @c --------------------------------------------------------------------  @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  @subsection C Code restrictions
 @cindex C code restrictions  @cindex C code restrictions
 @cindex restrictions on C code  @cindex restrictions on C code
Line 975  macros can be implemented in several way Line 977  macros can be implemented in several way
 @samp{IP} points to the next instruction, and @samp{IPTOS} is its  @samp{IP} points to the next instruction, and @samp{IPTOS} is its
 contents.  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 --------------------------------------------------------------------  @c --------------------------------------------------------------------
 @node Superinstructions, Store Optimization, Simple instructions, Input File Format  @node Superinstructions, Store Optimization, Simple instructions, Input File Format
Line 1034  accesses a stack pointer should not be u Line 1063  accesses a stack pointer should not be u
 does not check these restrictions, they just result in bugs in your  does not check these restrictions, they just result in bugs in your
 interpreter.  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 -------------------------------------------------------------------  @c -------------------------------------------------------------------
 @node  Store Optimization, Register Machines, Superinstructions, Input File Format  @node  Store Optimization, Register Machines, Superinstructions, Input File Format
 @section Store Optimization  @section Store Optimization
Line 1078  add1 ( n1 -- n1 ) Line 1112  add1 ( n1 -- n1 )
 n2=n1+1;  n2=n1+1;
 @end example  @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  To turn on the store optimization, write
   
 @example  @example
Line 1177  expected by Vmgen (this should not happe Line 1217  expected by Vmgen (this should not happe
 line in a bug report).  line in a bug report).
   
 @cindex @code{syntax error, wrong char} error  @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  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  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  instruction where the C code is not delimited by braces (then the empty
Line 1196  The stack item does not match any define Line 1236  The stack item does not match any define
 away any stack prefix).  You should either declare the type prefix you  away any stack prefix).  You should either declare the type prefix you
 want for that stack item, or use a different type prefix  want for that stack item, or use a different type prefix
   
 @item @code{unknown primitive} error  @cindex @code{unknown primitive} error
 @item unknown primitive  @item unknown primitive
 You have used the name of a simple VM instruction in a superinstruction  You have used the name of a simple VM instruction in a superinstruction
 definition without defining the simple VM instruction first.  definition without defining the simple VM instruction first.
Line 1386  type.  For @samp{inst-stream}, the name Line 1426  type.  For @samp{inst-stream}, the name
 plain r-value; typically it is a macro that abstracts away the  plain r-value; typically it is a macro that abstracts away the
 differences between the various implementations of @code{NEXT_P*}.  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 top of stack caching
 @cindex stack caching  @cindex stack caching
 @cindex TOS  @cindex TOS
Line 1786  a major change, and it's ramifications a Line 1832  a major change, and it's ramifications a
 @chapter The future  @chapter The future
 @cindex future ideas  @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  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  you.  What are you doing with Vmgen, what features are you missing, and
 why?  why?

Removed from v.1.20  
changed lines
  Added in v.1.24


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