Return to README CVS log

Up to [gforth] / gforth / vmgen-ex2

vmgen-related changes:
in prims2x:
  Conversion macros for single items now take 2 arguments
  Converting from two items to a type has changed order
  argument printing for disassembler disabled (for now)
  disassembler now also uses VM_IS_INST
in Gforth and vmgen-ex: adapted to work with changed prims2x
new: vmgen-ex2: uses union for Cell instead of casting (lots of
   changes compared to vmgen-ex)

    1: This directory contains a working example for using vmgen.  It's a
    2: small Modula-2-like programming language.
    3: 
    4: You can build the example by first installing Gforth and then saying,
    5: in this directory:
    6: 
    7: make
    8: 
    9: Ignore the warnings.  You can check that it works with
   10: 
   11: make check
   12: 
   13: You can run mini programs like this:
   14: 
   15: ./mini fib.mini
   16: 
   17: To learn about the options, type
   18: 
   19: ./mini -h
   20: 
   21: The files in this directory are:
   22: 
   23: Makefile
   24: README
   25: disasm.c		wrapper file
   26: engine.c		wrapper file
   27: peephole.c		wrapper file
   28: profile.c		wrapper file
   29: mini-inst.vmg		simple VM instructions
   30: mini-super.vmg		superinstructions (empty at first)
   31: mini.h			common declarations
   32: mini.l			scanner
   33: mini.y			front end (parser, VM code generator)
   34: support.c		main() and other support functions
   35: fib.mini		example mini program
   36: simple.mini		example mini program
   37: test.mini		example mini program (tests everything)
   38: test.out		test.mini output
   39: stat.awk		script for aggregating profile information
   40: peephole-blacklist	list of instructions not allowed in superinstructions
   41: seq2rule.awk		script for creating superinstructions
   42: 
   43: For your own interpreter, you would typically copy the following files
   44: and change little, if anything:
   45: 
   46: disasm.c		wrapper file
   47: engine.c		wrapper file
   48: peephole.c		wrapper file
   49: profile.c		wrapper file
   50: stat.awk		script for aggregating profile information
   51: seq2rule.awk		script for creating superinstructions
   52: 
   53: You would typically change much in or replace the following files:
   54: 
   55: Makefile
   56: mini-inst.vmg		simple VM instructions
   57: mini.h			common declarations
   58: mini.l			scanner
   59: mini.y			front end (parser, VM code generator)
   60: support.c		main() and other support functions
   61: peephole-blacklist	list of instructions not allowed in superinstructions
   62: 
   63: 
   64: Using profiling to create superinstructions:
   65: 
   66: I have not added rules for this in the Makefile (there are many
   67: options for selecting superinstructions, and I did not want to
   68: hardcode one into the Makefile), but there are some supporting
   69: scripts, and here's an example:
   70: 
   71: Suppose you want to use fib.mini and test.mini as training programs,
   72: you get the profiles like this:
   73: 
   74: make fib.prof test.prof #takes a few seconds
   75: 
   76: You can aggregate these profiles with stat.awk:
   77: 
   78: awk -f stat.awk fib.prof test.prof
   79: 
   80: The result contains lines like:
   81: 
   82:       2      16        36910041 loadlocal lit
   83: 
   84: This means that the sequence "loadlocal lit" statically occurs a total
   85: of 16 times in 2 profiles, with a dynamic execution count of 36910041.
   86: 
   87: The numbers can be used in various ways to select superinstructions.
   88: E.g., if you just want to select all sequences with a dynamic
   89: execution count exceeding 10000, you would use the following pipeline:
   90: 
   91: awk -f stat.awk fib.prof test.prof|
   92: awk '$3>=10000'|                #select sequences
   93: fgrep -v -f peephole-blacklist| #eliminate wrong instructions
   94: awk -f seq2rule.awk|          #transform sequences into superinstruction rules
   95: sort -k 3 >mini-super.vmg       #sort sequences
   96: 
   97: The peephole-blacklist contains all instructions where stack caching
   98: might lead to problems (for mini: call, return); the sort step is
   99: necessary because currently the superinstructions containing all
  100: sequence prefixes must precede a superinstruction of length >2.
  101: 
  102: Now you can create a version of mini with superinstructions by just saying
  103: 
  104: make
  105: 
  106: Before you generate new profiles for creating superinstructions, you
  107: have to again create a version of mini without superinstructions:
  108: 
  109: echo >mini-super.vmg
  110: make
  111: