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

version 1.24, 2003/03/02 13:12:33 version 1.30, 2007/12/31 18:56:18
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, 03 Free Software Foundation, Inc.  Copyright @copyright{} 2002,2003,2005 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
 under the terms of the GNU Free Documentation License, Version 1.1 or  under the terms of the GNU Free Documentation License, Version 1.2 or
 any later version published by the Free Software Foundation; with no  any later version published by the Free Software Foundation; with no
 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''  Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
 and with the Back-Cover Texts as in (a) below.  A copy of the  and with the Back-Cover Texts as in (a) below.  A copy of the
Line 94  Input File Grammar Line 94  Input File Grammar
   
 Simple instructions  Simple instructions
   
   * Explicit stack access::       If the C code accesses a stack pointer
 * 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  * Stack growth direction::      is configurable per stack
Line 829  name.  Stack prefixes are defined like t Line 830  name.  Stack prefixes are defined like t
   
 @example  @example
 \E inst-stream stack-prefix #  \E inst-stream stack-prefix #
   \E data-stack  stack-prefix S:
 @end example  @end example
   
 This definition defines that the stack prefix @code{#} specifies the  This definition defines that the stack prefix @code{#} specifies the
Line 845  If there are multiple instruction stream Line 847  If there are multiple instruction stream
 first one (just as the intuition suggests).  first one (just as the intuition suggests).
   
 @menu  @menu
   * Explicit stack access::       If the C code accesses a stack pointer
 * 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  * Stack growth direction::      is configurable per stack
 @end menu  @end menu
   
 @c --------------------------------------------------------------------  @c --------------------------------------------------------------------
 @node C Code Macros, C Code restrictions, Simple instructions, Simple instructions  @node  Explicit stack access, C Code Macros, Simple instructions, Simple instructions
   @subsection Explicit stack access
   @cindex stack access, explicit
   @cindex Stack pointer access
   @cindex explicit stack access
   
   Not all stack effects can be specified using the stack effect
   specifications above.  For VM instructions that have other stack
   effects, you can specify them explicitly by accessing the stack
   pointer in the C code; however, you have to notify Vmgen of such
   explicit stack accesses, otherwise Vmgens optimizations could conflict
   with your explicit stack accesses.
   
   You notify Vmgen by putting @code{...} with the appropriate stack
   prefix into the stack comment.  Then the VM instruction will first
   take the other stack items specified in the stack effect into C
   variables, then make sure that all other stack items for that stack
   are in memory, and that the stack pointer for the stack points to the
   top-of-stack (by default, unless you change the stack access
   transformation: @pxref{Stack growth direction}).
   
   The general rule is: If you mention a stack pointer in the C code of a
   VM instruction, you should put a @code{...} for that stack in the stack
   effect.
   
   Consider this example:
   
   @example
   return ( #iadjust S:... target afp i1 -- i2 )
   SET_IP(target);
   sp = (Cell *)(((char *)sp)+iadjust);
   fp = afp;
   i2=i1;
   @end example
   
   First the variables @code{target afp i1} are popped off the stack,
   then the stack pointer @code{sp} is set correctly for the new stack
   depth, then the C code changes the stack depth and does other things,
   and finally @code{i2} is pushed on the stack with the new depth.
   
   The position of the @code{...} within the stack effect does not
   matter.  You can use several @code{...}s, for different stacks, and
   also several for the same stack (that has no additional effect).  If
   you use @code{...} without a stack prefix, this specifies all the
   stacks except the instruction stream.
   
   You cannot use @code{...} for the instruction stream, but that is not
   necessary: At the start of the C code, @code{IP} points to the start
   of the next VM instruction (i.e., right beyond the end of the current
   VM instruction), and you can change the instruction pointer with
   @code{SET_IP} (@pxref{VM engine}).
   
   
   @c --------------------------------------------------------------------
   @node C Code Macros, C Code restrictions, Explicit stack access, Simple instructions
 @subsection C Code Macros  @subsection C Code Macros
 @cindex macros recognized by Vmgen  @cindex macros recognized by Vmgen
 @cindex basic block, VM level  @cindex basic block, VM level
Line 906  if (branch_condition) @{ Line 963  if (branch_condition) @{
 SUPER_CONTINUE;  SUPER_CONTINUE;
 @end example  @end example
   
   @item VM_JUMP
   @findex VM_JUMP
   @code{VM_JUMP(target)} is equivalent to @code{goto *(target)}, but
   allows Vmgen to do dynamic superinstructions and replication.  You
   still need to say @code{SUPER_END}.  Also, the goto only happens at
   the end (wherever the VM_JUMP is).  Essentially, this just suppresses
   much of the ordinary dispatch mechanism.
   
 @end table  @end table
   
 Note that Vmgen is not smart about C-level tokenization, comments,  Note that Vmgen is not smart about C-level tokenization, comments,
Line 1108  n++; Line 1173  n++;
 Instead, you have to use different names, i.e.:  Instead, you have to use different names, i.e.:
   
 @example  @example
 add1 ( n1 -- n1 )  add1 ( n1 -- n2 )
 n2=n1+1;  n2=n1+1;
 @end example  @end example
   
Line 1461  profiling. Line 1526  profiling.
 @item SUPER_CONTINUE  @item SUPER_CONTINUE
 This is just a hint to Vmgen and does nothing at the C level.  This is just a hint to Vmgen and does nothing at the C level.
   
   @findex MAYBE_UNUSED
   @item MAYBE_UNUSED
   This should be defined as @code{__attribute__((unused))} for gcc-2.7 and
   higher.  It suppresses the warnings about unused variables in the code
   for superinstructions.  You need to define this only if you are using
   superinstructions.
   
 @findex VM_DEBUG  @findex VM_DEBUG
 @item VM_DEBUG  @item VM_DEBUG
 If this is defined, the tracing code will be compiled in (slower  If this is defined, the tracing code will be compiled in (slower
Line 1638  instruction instead of laying down @code Line 1710  instruction instead of laying down @code
   
 The code for peephole optimization is in @file{vmgen-ex/peephole.c}.  The code for peephole optimization is in @file{vmgen-ex/peephole.c}.
 You can use this file almost verbatim.  Vmgen generates  You can use this file almost verbatim.  Vmgen generates
 @file{@var{file}-peephole.i} which contains data for the peephoile  @file{@var{file}-peephole.i} which contains data for the peephole
 optimizer.  optimizer.
   
 @findex init_peeptable  @findex init_peeptable
Line 1924  You can find vmgen information at Line 1996  You can find vmgen information at
 * GNU Free Documentation License::  License for copying this manual.  * GNU Free Documentation License::  License for copying this manual.
 @end menu  @end menu
   
   @node GNU Free Documentation License,  , Copying This Manual, Copying This Manual
   @appendixsec GNU Free Documentation License
 @include fdl.texi  @include fdl.texi
   
   

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


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