--- gforth/doc/vmgen.texi 2003/02/23 21:17:00 1.21 +++ gforth/doc/vmgen.texi 2008/11/01 22:19:30 1.34 @@ -10,11 +10,11 @@ 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,2003,2005,2007,2008 Free Software Foundation, Inc. @quotation 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 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 @@ -27,9 +27,9 @@ Software Foundation raise funds for GNU @end quotation @end copying -@dircategory GNU programming tools +@dircategory Software development @direntry -* Vmgen: (vmgen). Interpreter generator +* Vmgen: (vmgen). Virtual machine interpreter generator @end direntry @titlepage @@ -94,8 +94,10 @@ Input File Grammar Simple instructions +* Explicit stack access:: If the C code accesses a stack pointer * 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 @@ -329,7 +331,7 @@ instructions. Another option is to use for the virtual machine; we believe that using a stack architecture is usually both simpler and faster. -however, this option is slower or +However, this option is slower or significantly more complex to implement than a stack machine architecture. Vmgen has special support and optimizations for stack VMs, making their @@ -715,7 +717,7 @@ 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') +set-flag: ('store-optimization'|'include-skipped-insts') ('on'|'off') @end example Note that the syntax of this code is not checked thoroughly (there are @@ -737,13 +739,14 @@ are: @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" -- ) -store-optimization ( -- addr ) +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. @@ -803,14 +806,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 @@ -828,6 +830,7 @@ name. Stack prefixes are defined like t @example \E inst-stream stack-prefix # +\E data-stack stack-prefix S: @end example This definition defines that the stack prefix @code{#} specifies the @@ -844,12 +847,71 @@ If there are multiple instruction stream first one (just as the intuition suggests). @menu +* Explicit stack access:: If the C code accesses a stack pointer * 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 -------------------------------------------------------------------- -@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 + +This feature is not needed and not supported in the 0.6.2 version of +vmgen that is documented here (and that is invoked by default). + +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 @cindex macros recognized by Vmgen @cindex basic block, VM level @@ -904,6 +966,15 @@ if (branch_condition) @{ SUPER_CONTINUE; @end example +@c !! uncomment for post-0.6.2 docs +@c @item VM_JUMP +@c @findex VM_JUMP +@c @code{VM_JUMP(target)} is equivalent to @code{goto *(target)}, but +@c allows Vmgen to do dynamic superinstructions and replication. You +@c still need to say @code{SUPER_END}. Also, the goto only happens at +@c the end (wherever the VM_JUMP is). Essentially, this just suppresses +@c much of the ordinary dispatch mechanism. + @end table Note that Vmgen is not smart about C-level tokenization, comments, @@ -915,7 +986,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 @@ -975,6 +1046,33 @@ 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, Store Optimization, Simple instructions, Input File Format @@ -1034,6 +1132,11 @@ 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 Store Optimization, Register Machines, Superinstructions, Input File Format @section Store Optimization @@ -1042,7 +1145,7 @@ interpreter. @cindex stack stores, optimization @cindex eliminating stack stores -This minor optimization (0.6\%--0.8\% reduction in executed instructions +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. @@ -1074,10 +1177,16 @@ n++; Instead, you have to use different names, i.e.: @example -add1 ( n1 -- n1 ) +add1 ( n1 -- n2 ) 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 @@ -1177,7 +1286,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 @@ -1196,7 +1305,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. @@ -1386,6 +1495,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 @@ -1415,6 +1530,13 @@ profiling. @item SUPER_CONTINUE 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 @item VM_DEBUG If this is defined, the tracing code will be compiled in (slower @@ -1592,7 +1714,7 @@ instruction instead of laying down @code The code for peephole optimization is in @file{vmgen-ex/peephole.c}. 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. @findex init_peeptable @@ -1878,6 +2000,8 @@ You can find vmgen information at * GNU Free Documentation License:: License for copying this manual. @end menu +@node GNU Free Documentation License, , Copying This Manual, Copying This Manual +@appendixsec GNU Free Documentation License @include fdl.texi