version 1.8, 2002/08/08 19:20:26
|
version 1.10, 2002/08/13 19:33:38
|
Line 1
|
Line 1
|
|
\input texinfo @c -*-texinfo-*- |
|
@comment %**start of header |
|
@setfilename vmgen.info |
@include version.texi |
@include version.texi |
|
@settitle Vmgen (Gforth @value{VERSION}) |
|
@c @syncodeindex pg cp |
|
@comment %**end of header |
|
@copying |
|
This manual is for Vmgen |
|
(version @value{VERSION}, @value{UPDATED}), |
|
the virtual machine interpreter generator |
|
|
|
Copyright @copyright{} 2002 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 |
|
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 |
|
license is included in the section entitled ``GNU Free Documentation |
|
License.'' |
|
|
|
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify |
|
this GNU Manual, like GNU software. Copies published by the Free |
|
Software Foundation raise funds for GNU development.'' |
|
@end quotation |
|
@end copying |
|
|
|
@dircategory GNU programming tools |
|
@direntry |
|
* vmgen: (vmgen). Interpreter generator |
|
@end direntry |
|
|
|
@titlepage |
|
@title Vmgen |
|
@subtitle for Gforth version @value{VERSION}, @value{UPDATED} |
|
@author M. Anton Ertl (@email{anton@mips.complang.tuwien.ac.at}) |
|
@page |
|
@vskip 0pt plus 1filll |
|
@insertcopying |
|
@end titlepage |
|
|
|
@contents |
|
|
|
@ifnottex |
|
@node Top, Introduction, (dir), (dir) |
|
@top Vmgen |
|
|
|
@insertcopying |
|
@end ifnottex |
|
|
|
@menu |
|
* Introduction:: What can Vmgen do for you? |
|
* Why interpreters?:: Advantages and disadvantages |
|
* Concepts:: VM interpreter background |
|
* Invoking vmgen:: |
|
* Example:: |
|
* Input File Format:: |
|
* Using the generated code:: |
|
* Changes:: from earlier versions |
|
* Contact:: Bug reporting etc. |
|
* Copying This Manual:: Manual License |
|
* Index:: |
|
|
|
@detailmenu |
|
--- The Detailed Node Listing --- |
|
|
|
Concepts |
|
|
|
* Front end and VM interpreter:: Modularizing an interpretive system |
|
* Data handling:: Stacks, registers, immediate arguments |
|
* Dispatch:: From one VM instruction to the next |
|
|
|
Example |
|
|
|
* Example overview:: |
|
* Using profiling to create superinstructions:: |
|
|
|
Input File Format |
|
|
|
* Input File Grammar:: |
|
* Simple instructions:: |
|
* Superinstructions:: |
|
|
|
Simple instructions |
|
|
|
* C Code Macros:: Macros recognized by Vmgen |
|
* C Code restrictions:: Vmgen makes assumptions about C code |
|
|
|
Using the generated code |
|
|
|
* VM engine:: Executing VM code |
|
* VM instruction table:: |
|
* VM code generation:: Creating VM code (in the front-end) |
|
* Peephole optimization:: Creating VM superinstructions |
|
* VM disassembler:: for debugging the front end |
|
* VM profiler:: for finding worthwhile superinstructions |
|
|
|
Copying This Manual |
|
|
|
* GNU Free Documentation License:: License for copying this manual. |
|
|
|
@end detailmenu |
|
@end menu |
|
|
@c @ifnottex |
@c @ifnottex |
This file documents vmgen (Gforth @value{VERSION}). |
This file documents Vmgen (Gforth @value{VERSION}). |
|
|
|
@c ************************************************************ |
|
@node Introduction, Why interpreters?, Top, Top |
@chapter Introduction |
@chapter Introduction |
|
|
Vmgen is a tool for writing efficient interpreters. It takes a simple |
Vmgen is a tool for writing efficient interpreters. It takes a simple |
Line 101 we will implement new features if someon
|
Line 207 we will implement new features if someon
|
list above is not exhaustive. |
list above is not exhaustive. |
|
|
@c ********************************************************************* |
@c ********************************************************************* |
|
@node Why interpreters?, Concepts, Introduction, Top |
@chapter Why interpreters? |
@chapter Why interpreters? |
|
|
Interpreters are a popular language implementation technique because |
Interpreters are a popular language implementation technique because |
Line 129 Vmgen makes it even easier to implement
|
Line 236 Vmgen makes it even easier to implement
|
techniques for building efficient interpreters. |
techniques for building efficient interpreters. |
|
|
@c ******************************************************************** |
@c ******************************************************************** |
|
@node Concepts, Invoking vmgen, Why interpreters?, Top |
@chapter Concepts |
@chapter Concepts |
|
|
|
@menu |
|
* Front end and VM interpreter:: Modularizing an interpretive system |
|
* Data handling:: Stacks, registers, immediate arguments |
|
* Dispatch:: From one VM instruction to the next |
|
@end menu |
|
|
@c -------------------------------------------------------------------- |
@c -------------------------------------------------------------------- |
@section Front-end and virtual machine interpreter |
@node Front end and VM interpreter, Data handling, Concepts, Concepts |
|
@section Front end and VM interpreter |
|
|
@cindex front-end |
@cindex front-end |
Interpretive systems are typically divided into a @emph{front end} that |
Interpretive systems are typically divided into a @emph{front end} that |
Line 164 Vmgen currently has no special support f
|
Line 279 Vmgen currently has no special support f
|
information in the instruction descriptions can be helpful, and we are |
information in the instruction descriptions can be helpful, and we are |
open for feature requests and suggestions. |
open for feature requests and suggestions. |
|
|
|
@c -------------------------------------------------------------------- |
|
@node Data handling, Dispatch, Front end and VM interpreter, Concepts |
@section Data handling |
@section Data handling |
|
|
@cindex stack machine |
@cindex stack machine |
Line 202 harder, but might be possible (contact u
|
Line 319 harder, but might be possible (contact u
|
@c reference counting might be possible by including counting code in |
@c reference counting might be possible by including counting code in |
@c the conversion macros. |
@c the conversion macros. |
|
|
|
@c -------------------------------------------------------------------- |
|
@node Dispatch, , Data handling, Concepts |
@section Dispatch |
@section Dispatch |
|
|
Understanding this section is probably not necessary for using vmgen, |
Understanding this section is probably not necessary for using vmgen, |
Line 235 as values}).
|
Line 354 as values}).
|
@end table |
@end table |
|
|
@c ************************************************************* |
@c ************************************************************* |
|
@node Invoking vmgen, Example, Concepts, Top |
@chapter Invoking vmgen |
@chapter Invoking vmgen |
|
|
The usual way to invoke vmgen is as follows: |
The usual way to invoke vmgen is as follows: |
Line 271 Print version and exit
|
Line 391 Print version and exit
|
@c env vars GFORTHDIR GFORTHDATADIR |
@c env vars GFORTHDIR GFORTHDATADIR |
|
|
@c **************************************************************** |
@c **************************************************************** |
|
@node Example, Input File Format, Invoking vmgen, Top |
@chapter Example |
@chapter Example |
|
|
|
@menu |
|
* Example overview:: |
|
* Using profiling to create superinstructions:: |
|
@end menu |
|
|
|
@c -------------------------------------------------------------------- |
|
@node Example overview, Using profiling to create superinstructions, Example, Example |
@section Example overview |
@section Example overview |
|
|
There are two versions of the same example for using vmgen: |
There are two versions of the same example for using vmgen: |
Line 342 check}. You can run run mini programs l
|
Line 470 check}. You can run run mini programs l
|
|
|
To learn about the options, type @samp{./mini -h}. |
To learn about the options, type @samp{./mini -h}. |
|
|
|
@c -------------------------------------------------------------------- |
|
@node Using profiling to create superinstructions, , Example overview, Example |
@section Using profiling to create superinstructions |
@section Using profiling to create superinstructions |
|
|
I have not added rules for this in the @file{Makefile} (there are many |
I have not added rules for this in the @file{Makefile} (there are many |
Line 392 preceed larger superinstructions.
|
Line 522 preceed larger superinstructions.
|
Now you can create a version of mini with superinstructions by just |
Now you can create a version of mini with superinstructions by just |
saying @samp{make} |
saying @samp{make} |
|
|
|
|
@c *************************************************************** |
@c *************************************************************** |
|
@node Input File Format, Using the generated code, Example, Top |
@chapter Input File Format |
@chapter Input File Format |
|
|
Vmgen takes as input a file containing specifications of virtual machine |
Vmgen takes as input a file containing specifications of virtual machine |
Line 400 instructions. This file usually has a n
|
Line 532 instructions. This file usually has a n
|
|
|
Most examples are taken from the example in @file{vmgen-ex}. |
Most examples are taken from the example in @file{vmgen-ex}. |
|
|
|
@menu |
|
* Input File Grammar:: |
|
* Simple instructions:: |
|
* Superinstructions:: |
|
@end menu |
|
|
|
@c -------------------------------------------------------------------- |
|
@node Input File Grammar, Simple instructions, Input File Format, Input File Format |
@section Input File Grammar |
@section Input File Grammar |
|
|
The grammar is in EBNF format, with @code{@var{a}|@var{b}} meaning |
The grammar is in EBNF format, with @code{@var{a}|@var{b}} meaning |
Line 440 Vmgen understands a few extensions beyon
|
Line 580 Vmgen understands a few extensions beyon
|
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}. |
|
|
@subsection |
@subsection Eval escapes |
@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 |
vmgen reads the line. If you do not know (and do not want to learn) |
vmgen reads the line. If you do not know (and do not want to learn) |
Line 472 stack-prefix ( stack "prefix" -- )
|
Line 612 stack-prefix ( stack "prefix" -- )
|
@end example |
@end example |
|
|
|
|
|
@c -------------------------------------------------------------------- |
|
@node Simple instructions, Superinstructions, Input File Grammar, Input File Format |
@section Simple instructions |
@section Simple instructions |
|
|
We will use the following simple VM instruction description as example: |
We will use the following simple VM instruction description as example: |
Line 548 arguments can only appear to the left of
|
Line 690 arguments can only appear to the left of
|
If there are multiple instruction stream arguments, the leftmost is the |
If there are multiple instruction stream arguments, the leftmost is the |
first one (just as the intuition suggests). |
first one (just as the intuition suggests). |
|
|
@subsubsection C Code Macros |
@menu |
|
* C Code Macros:: Macros recognized by Vmgen |
|
* C Code restrictions:: Vmgen makes assumptions about C code |
|
@end menu |
|
|
|
@c -------------------------------------------------------------------- |
|
@node C Code Macros, C Code restrictions, Simple instructions, Simple instructions |
|
@subsection C Code Macros |
|
|
Vmgen recognizes the following strings in the C code part of simple |
Vmgen recognizes the following strings in the C code part of simple |
instructions: |
instructions: |
Line 605 presence of these strings; vmgen will no
|
Line 754 presence of these strings; vmgen will no
|
a C preprocessor macro. |
a C preprocessor macro. |
|
|
|
|
@subsubsection C Code restrictions |
@c -------------------------------------------------------------------- |
|
@node C Code restrictions, , C Code Macros, Simple instructions |
|
@subsection C Code restrictions |
|
|
Vmgen generates code and performs some optimizations under the |
Vmgen generates code and performs some optimizations under the |
assumption that the user-supplied C code does not access the stack |
assumption that the user-supplied C code does not access the stack |
Line 656 macros can be implemented in several way
|
Line 807 macros can be implemented in several way
|
contents. |
contents. |
|
|
|
|
|
@c -------------------------------------------------------------------- |
|
@node Superinstructions, , Simple instructions, Input File Format |
@section Superinstructions |
@section Superinstructions |
|
|
Note: don't invest too much work in (static) superinstructions; a future |
Note: don't invest too much work in (static) superinstructions; a future |
Line 710 not be used as component at all. Vmgen
|
Line 863 not be used as component at all. Vmgen
|
restrictions, they just result in bugs in your interpreter. |
restrictions, they just result in bugs in your interpreter. |
|
|
@c ******************************************************************** |
@c ******************************************************************** |
|
@node Using the generated code, Changes, Input File Format, Top |
@chapter Using the generated code |
@chapter Using the generated code |
|
|
The easiest way to create a working VM interpreter with vmgen is |
The easiest way to create a working VM interpreter with vmgen is |
probably to start with one of the examples, and modify it for your |
probably to start with one of the examples, and modify it for your |
purposes. This chapter is just the reference manual for the macros |
purposes. This chapter is just the reference manual for the macros |
etc. used by the generated code, and the other context expected by the |
etc. used by the generated code, the other context expected by the |
generated code, and what you can do with the various generated files. |
generated code, and what you can do with the various generated files. |
|
|
|
@menu |
|
* VM engine:: Executing VM code |
|
* VM instruction table:: |
|
* VM code generation:: Creating VM code (in the front-end) |
|
* Peephole optimization:: Creating VM superinstructions |
|
* VM disassembler:: for debugging the front end |
|
* VM profiler:: for finding worthwhile superinstructions |
|
@end menu |
|
|
|
@c -------------------------------------------------------------------- |
|
@node VM engine, VM instruction table, Using the generated code, Using the generated code |
@section VM engine |
@section VM engine |
|
|
The VM engine is the VM interpreter that executes the VM code. It is |
The VM engine is the VM interpreter that executes the VM code. It is |
Line 749 threaded-code dispatch this should just
|
Line 913 threaded-code dispatch this should just
|
@var{label}}. In either case @var{label} is usually the @var{inst_name} |
@var{label}}. In either case @var{label} is usually the @var{inst_name} |
with some prefix or suffix to avoid naming conflicts. |
with some prefix or suffix to avoid naming conflicts. |
|
|
|
@item LABEL2(@var{inst_name}) |
|
This will be used for dynamic superinstructions; at the moment, this |
|
should expand to nothing. |
|
|
@item NAME(@var{inst_name_string}) |
@item NAME(@var{inst_name_string}) |
Called on entering a VM instruction with a string containing the name of |
Called on entering a VM instruction with a string containing the name of |
the VM instruction as parameter. In normal execution this should be a |
the VM instruction as parameter. In normal execution this should be a |
Line 874 basic type of the stack.
|
Line 1042 basic type of the stack.
|
@end table |
@end table |
|
|
|
|
@section{VM instruction table} |
@c -------------------------------------------------------------------- |
|
@node VM instruction table, VM code generation, VM engine, Using the generated code |
|
@section VM instruction table |
|
|
For threaded code we also need to produce a table containing the labels |
For threaded code we also need to produce a table containing the labels |
of all VM instructions. This is needed for VM code generation |
of all VM instructions. This is needed for VM code generation |
Line 914 address is taken with @samp{&&} (@pxref{
|
Line 1084 address is taken with @samp{&&} (@pxref{
|
@end table |
@end table |
|
|
|
|
|
@c -------------------------------------------------------------------- |
|
@node VM code generation, Peephole optimization, VM instruction table, Using the generated code |
@section VM code generation |
@section VM code generation |
|
|
Vmgen generates VM code generation functions in @file{@var{name}-gen.i} |
Vmgen generates VM code generation functions in @file{@var{name}-gen.i} |
Line 979 superinstruction at the branch), and bec
|
Line 1151 superinstruction at the branch), and bec
|
themselves to the profiler. |
themselves to the profiler. |
|
|
|
|
|
@c -------------------------------------------------------------------- |
|
@node Peephole optimization, VM disassembler, VM code generation, Using the generated code |
@section Peephole optimization |
@section Peephole optimization |
|
|
You need peephole optimization only if you want to use |
You need peephole optimization only if you want to use |
Line 1007 instruction to branch to), you have to c
|
Line 1181 instruction to branch to), you have to c
|
(@pxref{VM code generation}) at branch targets. |
(@pxref{VM code generation}) at branch targets. |
|
|
|
|
|
@c -------------------------------------------------------------------- |
|
@node VM disassembler, VM profiler, Peephole optimization, Using the generated code |
@section VM disassembler |
@section VM disassembler |
|
|
A VM code disassembler is optional for an interpretive system, but |
A VM code disassembler is optional for an interpretive system, but |
Line 1040 VM instruction table.
|
Line 1216 VM instruction table.
|
@end table |
@end table |
|
|
|
|
|
@c -------------------------------------------------------------------- |
|
@node VM profiler, , VM disassembler, Using the generated code |
@section VM profiler |
@section VM profiler |
|
|
The VM profiler is designed for getting execution and occurence counts |
The VM profiler is designed for getting execution and occurence counts |
Line 1117 it uses variables and functions defined
|
Line 1295 it uses variables and functions defined
|
plus @code{VM_IS_INST} already defined for the VM disassembler |
plus @code{VM_IS_INST} already defined for the VM disassembler |
(@pxref{VM disassembler}). |
(@pxref{VM disassembler}). |
|
|
|
|
|
@c ********************************************************** |
|
@node Changes, Contact, Using the generated code, Top |
@chapter Changes |
@chapter Changes |
|
|
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 |
Line 1142 Also some new macros have to be defined,
|
Line 1323 Also some new macros have to be defined,
|
@code{LABEL}; some macros have to be defined in new contexts, e.g., |
@code{LABEL}; some macros have to be defined in new contexts, e.g., |
@code{VM_IS_INST} is now also needed in the disassembler. |
@code{VM_IS_INST} is now also needed in the disassembler. |
|
|
|
@node Contact, Copying This Manual, Changes, Top |
@chapter Contact |
@chapter Contact |
|
|
|
@node Copying This Manual, Index, Contact, Top |
|
@appendix Copying This Manual |
|
|
|
@menu |
|
* GNU Free Documentation License:: License for copying this manual. |
|
@end menu |
|
|
|
@include fdl.texi |
|
|
|
|
|
@node Index, , Copying This Manual, Top |
|
@unnumbered Index |
|
|
|
@printindex cp |
|
|
|
@bye |