Return to README CVS log

Up to [gforth] / gforth / vmgen-ex

Annotation of gforth/vmgen-ex/README, revision 1.3

1.1       anton       1: This directory contains a working example for using vmgen.  It's a
1.2       anton       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: 
1.3     ! anton       9: Ignore the warnings.  You can check that it works with
1.2       anton      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: 
1.3     ! anton      74: make fib.prof test.prof #takes a few seconds
1.2       anton      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: