Return to README CVS log

Up to [gforth] / gforth / vmgen-ex2

Annotation of gforth/vmgen-ex2/README, revision 1.1

1.1     ! anton       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: