version 1.13, 2002/08/19 07:38:16
|
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 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 |
* 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 601 Most examples are taken from the example
|
Line 607 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 615 The grammar is in EBNF format, with @cod
|
Line 622 The grammar is in EBNF format, with @cod
|
of @var{c} and @code{[@var{d}]} meaning 0 or 1 repetitions of @var{d}. |
of @var{c} and @code{[@var{d}]} meaning 0 or 1 repetitions of @var{d}. |
|
|
@cindex free-format, not |
@cindex free-format, not |
|
@cindex newlines, significance in syntax |
Vmgen input is not free-format, so you have to take care where you put |
Vmgen input is not free-format, so you have to take care where you put |
spaces and especially newlines; it's not as bad as makefiles, though: |
newlines (and, in a few cases, white space). |
any sequence of spaces and tabs is equivalent to a single space. |
|
|
|
@example |
@example |
description: @{instruction|comment|eval-escape@} |
description: @{instruction|comment|eval-escape|c-escape@} |
|
|
instruction: simple-inst|superinst |
instruction: simple-inst|superinst |
|
|
simple-inst: ident ' (' stack-effect ' )' newline c-code newline newline |
simple-inst: ident '(' stack-effect ')' newline c-code newline newline |
|
|
stack-effect: @{ident@} ' --' @{ident@} |
stack-effect: @{ident@} '--' @{ident@} |
|
|
super-inst: ident ' =' ident @{ident@} |
super-inst: ident '=' ident @{ident@} |
|
|
comment: '\ ' text newline |
comment: '\ ' text newline |
|
|
eval-escape: '\E ' text newline |
eval-escape: '\E ' text newline |
|
|
|
c-escape: '\C ' text newline |
@end example |
@end example |
@c \+ \- \g \f \c |
@c \+ \- \g \f \c |
|
|
Note that the @code{\}s in this grammar are meant literally, not as |
Note that the @code{\}s in this grammar are meant literally, not as |
C-style encodings for non-printable characters. |
C-style encodings for non-printable characters. |
|
|
The C code in @code{simple-inst} must not contain empty lines (because |
There are two ways to delimit the C code in @code{simple-inst}: |
Vmgen would mistake that as the end of the simple-inst. The text in |
|
@code{comment} and @code{eval-escape} must not contain a newline. |
@itemize @bullet |
@code{Ident} must conform to the usual conventions of C identifiers |
|
(otherwise the C compiler would choke on the Vmgen output). |
@item |
|
If you start it with a @samp{@{} at the start of a line (i.e., not even |
|
white space before it), you have to end it with a @samp{@}} at the start |
|
of a line (followed by a newline). In this case you may have empty |
|
lines within the C code (typically used between variable definitions and |
|
statements). |
|
|
|
@item |
|
You do not start it with @samp{@{}. Then the C code ends at the first |
|
empty line, so you cannot have empty lines within this code. |
|
|
|
@end itemize |
|
|
|
The text in @code{comment}, @code{eval-escape} and @code{c-escape} must |
|
not contain a newline. @code{Ident} must conform to the usual |
|
conventions of C identifiers (otherwise the C compiler would choke on |
|
the Vmgen output), except that idents in @code{stack-effect} may have a |
|
stack prefix (for stack prefix syntax, @pxref{Eval escapes}). |
|
|
|
@cindex C escape |
|
@cindex @code{\C} |
|
@cindex conditional compilation of Vmgen output |
|
The @code{c-escape} passes the text through to each output file (without |
|
the @samp{\C}). This is useful mainly for conditional compilation |
|
(i.e., you write @samp{\C #if ...} etc.). |
|
|
|
@cindex sync lines |
|
@cindex @code{#line} |
|
In addition to the syntax given in the grammer, Vmgen also processes |
|
sync lines (lines starting with @samp{#line}), as produced by @samp{m4 |
|
-s} (@pxref{Invoking m4, , Invoking m4, m4.info, GNU m4}) and similar |
|
tools. This allows associating C compiler error messages with the |
|
original source of the C code. |
|
|
Vmgen understands a few extensions beyond the grammar given here, but |
Vmgen understands a few extensions beyond the grammar given here, but |
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 |
|
@cindex @code{\E} |
|
|
|
|
@c woanders? |
@c woanders? |
The text in @code{eval-escape} is Forth code that is evaluated when |
The text in @code{eval-escape} is Forth code that is evaluated when |
Line 665 text according to the following grammar;
|
Line 710 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'|'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 |
many other Forth program fragments that could be written in an |
many other Forth program fragments that could be written in an |
eval-escape). |
eval-escape). |
|
|
|
A stack prefix can contain letters, digits, or @samp{:}, and may start |
|
with an @samp{#}; e.g., in Gforth the return stack has the stack prefix |
|
@samp{R:}. This restriction is not checked during the stack prefix |
|
definition, but it is enforced by the parsing rules for stack items |
|
later. |
|
|
If you know Forth, the stack effects of the non-standard words involved |
If you know Forth, the stack effects of the non-standard words involved |
are: |
are: |
@findex stack |
@findex stack |
Line 684 are:
|
Line 736 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 xt1 xt2 n stack "prefix" -- ) |
type-prefix ( addr u item-size stack "prefix" -- ) |
single ( -- xt1 xt2 n ) |
single ( -- item-size ) |
double ( -- xt1 xt2 n ) |
double ( -- item-size ) |
stack-prefix ( stack "prefix" -- ) |
stack-prefix ( stack "prefix" -- ) |
|
store-optimization ( -- addr ) |
|
include-skipped-insts ( -- addr ) |
@end example |
@end example |
|
|
|
An @var{item-size} takes three cells on the stack. |
|
|
@c -------------------------------------------------------------------- |
@c -------------------------------------------------------------------- |
@node Simple instructions, Superinstructions, Input File Grammar, Input File Format |
@node Simple instructions, Superinstructions, Input File Grammar, Input File Format |
Line 749 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 792 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 861 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 921 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, 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 980 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 ------------------------------------------------------------------- |
|
@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 |
|
|
|
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 |
|
\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 ------------------------------------------------------------------- |
@c ------------------------------------------------------------------- |
@node Register Machines, , Superinstructions, Input File Format |
@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 1051 You have used an instruction-stream pref
|
Line 1203 You have used an instruction-stream pref
|
side). |
side). |
|
|
@cindex @code{prefix for this combination must be defined earlier} error |
@cindex @code{prefix for this combination must be defined earlier} error |
@item the prefix for this combination must be defined earlier |
@item the prefix for this superinstruction must be defined earlier |
You have defined a superinstruction (e.g. @code{abc = a b c}) without |
You have defined a superinstruction (e.g. @code{abc = a b c}) without |
defining its direct prefix (e.g., @code{ab = a b}), |
defining its direct prefix (e.g., @code{ab = a b}), |
@xref{Superinstructions}. |
@xref{Superinstructions}. |
Line 1061 defining its direct prefix (e.g., @code{
|
Line 1213 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 |
@item 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 1078 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 1268 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 1668 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? |
Line 1691 please let us know.
|
Line 1855 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 1725 Also some new macros have to be defined,
|
Line 1906 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 |