version 1.21, 2003/02/23 21:17:00
|
version 1.33, 2008/10/08 20:54:09
|
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,2003,2005,2007 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 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 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 |
|
|
Using the generated code |
Using the generated code |
|
|
Line 329 instructions. Another option is to use
|
Line 331 instructions. Another option is to use
|
for the virtual machine; we believe that using a stack architecture is |
for the virtual machine; we believe that using a stack architecture is |
usually both simpler and faster. |
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. |
significantly more complex to implement than a stack machine architecture. |
|
|
Vmgen has special support and optimizations for stack VMs, making their |
Vmgen has special support and optimizations for stack VMs, making their |
Line 715 stack-decl: 'stack ' ident ident ident
|
Line 717 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 739 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 806 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 828 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 844 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 |
@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 |
|
|
|
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 |
@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 904 if (branch_condition) @{
|
Line 966 if (branch_condition) @{
|
SUPER_CONTINUE; |
SUPER_CONTINUE; |
@end example |
@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 |
@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 915 a C preprocessor macro.
|
Line 986 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 1046 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 1132 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 1042 interpreter.
|
Line 1145 interpreter.
|
@cindex stack stores, optimization |
@cindex stack stores, optimization |
@cindex eliminating stack stores |
@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 |
for Gforth) puts additional requirements on the instruction descriptions |
and is therefore disabled by default. |
and is therefore disabled by default. |
|
|
Line 1074 n++;
|
Line 1177 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 |
|
|
|
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 1286 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 1305 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 1495 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 1415 profiling.
|
Line 1530 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 1592 instruction instead of laying down @code
|
Line 1714 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 1878 You can find vmgen information at
|
Line 2000 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 |
|
|
|
|