This directory contains a working example for using vmgen.  It's a
small Modula-2-like programming language.

You can build the example by first installing Gforth and then saying,
in this directory:

make

Ignore the warnings.  You can check that it works with

make check

You can run mini programs like this:

./mini fib.mini

To learn about the options, type

./mini -h

The files in this directory are:

Makefile
README
disasm.c		wrapper file
engine.c		wrapper file
peephole.c		wrapper file
profile.c		wrapper file
mini-inst.vmg		simple VM instructions
mini-super.vmg		superinstructions (empty at first)
mini.h			common declarations
mini.l			scanner
mini.y			front end (parser, VM code generator)
support.c		main() and other support functions
fib.mini		example mini program
simple.mini		example mini program
test.mini		example mini program (tests everything)
test.out		test.mini output
stat.awk		script for aggregating profile information
peephole-blacklist	list of instructions not allowed in superinstructions
seq2rule.awk		script for creating superinstructions

For your own interpreter, you would typically copy the following files
and change little, if anything:

disasm.c		wrapper file
engine.c		wrapper file
peephole.c		wrapper file
profile.c		wrapper file
stat.awk		script for aggregating profile information
seq2rule.awk		script for creating superinstructions

You would typically change much in or replace the following files:

Makefile
mini-inst.vmg		simple VM instructions
mini.h			common declarations
mini.l			scanner
mini.y			front end (parser, VM code generator)
support.c		main() and other support functions
peephole-blacklist	list of instructions not allowed in superinstructions


Using profiling to create superinstructions:

I have not added rules for this in the Makefile (there are many
options for selecting superinstructions, and I did not want to
hardcode one into the Makefile), but there are some supporting
scripts, and here's an example:

Suppose you want to use fib.mini and test.mini as training programs,
you get the profiles like this:

make fib.prof test.prof #takes a few seconds

You can aggregate these profiles with stat.awk:

awk -f stat.awk fib.prof test.prof

The result contains lines like:

      2      16        36910041 loadlocal lit

This means that the sequence "loadlocal lit" statically occurs a total
of 16 times in 2 profiles, with a dynamic execution count of 36910041.

The numbers can be used in various ways to select superinstructions.
E.g., if you just want to select all sequences with a dynamic
execution count exceeding 10000, you would use the following pipeline:

awk -f stat.awk fib.prof test.prof|
awk '$3>=10000'|                #select sequences
fgrep -v -f peephole-blacklist| #eliminate wrong instructions
awk -f seq2rule.awk|          #transform sequences into superinstruction rules
sort -k 3 >mini-super.vmg       #sort sequences

The peephole-blacklist contains all instructions where stack caching
might lead to problems (for mini: call, return); the sort step is
necessary because currently the superinstructions containing all
sequence prefixes must precede a superinstruction of length >2.

Now you can create a version of mini with superinstructions by just saying

make

Before you generate new profiles for creating superinstructions, you
have to again create a version of mini without superinstructions:

echo >mini-super.vmg
make