Annotation of gforth/doc/vmgen.texi, revision 1.14

1.10      anton       1: \input texinfo    @c -*-texinfo-*-
                      2: @comment %**start of header
                      3: @setfilename vmgen.info
1.1       anton       4: @include version.texi
1.10      anton       5: @settitle Vmgen (Gforth @value{VERSION})
                      6: @c @syncodeindex pg cp
                      7: @comment %**end of header
                      8: @copying
                      9: This manual is for Vmgen
                     10: (version @value{VERSION}, @value{UPDATED}),
                     11: the virtual machine interpreter generator
                     12: 
                     13: Copyright @copyright{} 2002 Free Software Foundation, Inc.
                     14: 
                     15: @quotation
                     16: Permission is granted to copy, distribute and/or modify this document
                     17: under the terms of the GNU Free Documentation License, Version 1.1 or
                     18: any later version published by the Free Software Foundation; with no
                     19: Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
                     20: and with the Back-Cover Texts as in (a) below.  A copy of the
                     21: license is included in the section entitled ``GNU Free Documentation
                     22: License.''
                     23: 
                     24: (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
                     25: this GNU Manual, like GNU software.  Copies published by the Free
                     26: Software Foundation raise funds for GNU development.''
                     27: @end quotation
                     28: @end copying
                     29: 
                     30: @dircategory GNU programming tools
                     31: @direntry
1.11      anton      32: * Vmgen: (vmgen).               Interpreter generator
1.10      anton      33: @end direntry
                     34: 
                     35: @titlepage
                     36: @title Vmgen
                     37: @subtitle for Gforth version @value{VERSION}, @value{UPDATED}
1.11      anton      38: @author M. Anton Ertl (@email{anton@@mips.complang.tuwien.ac.at})
1.10      anton      39: @page
                     40: @vskip 0pt plus 1filll
                     41: @insertcopying
                     42: @end titlepage
                     43: 
                     44: @contents
                     45: 
                     46: @ifnottex
                     47: @node Top, Introduction, (dir), (dir)
                     48: @top Vmgen
                     49: 
                     50: @insertcopying
                     51: @end ifnottex
                     52: 
                     53: @menu
                     54: * Introduction::                What can Vmgen do for you?
                     55: * Why interpreters?::           Advantages and disadvantages
                     56: * Concepts::                    VM interpreter background
1.11      anton      57: * Invoking Vmgen::              
1.10      anton      58: * Example::                     
                     59: * Input File Format::           
1.13      anton      60: * Error messages::              reported by Vmgen
1.10      anton      61: * Using the generated code::    
1.13      anton      62: * Hints::                       VM archictecture, efficiency
                     63: * The future::                  
1.10      anton      64: * Changes::                     from earlier versions
                     65: * Contact::                     Bug reporting etc.
                     66: * Copying This Manual::         Manual License
                     67: * Index::                       
                     68: 
                     69: @detailmenu
                     70:  --- The Detailed Node Listing ---
                     71: 
                     72: Concepts
                     73: 
                     74: * Front end and VM interpreter::  Modularizing an interpretive system
                     75: * Data handling::               Stacks, registers, immediate arguments
                     76: * Dispatch::                    From one VM instruction to the next
                     77: 
                     78: Example
                     79: 
                     80: * Example overview::            
                     81: * Using profiling to create superinstructions::  
                     82: 
                     83: Input File Format
                     84: 
                     85: * Input File Grammar::          
                     86: * Simple instructions::         
                     87: * Superinstructions::           
1.11      anton      88: * Register Machines::           How to define register VM instructions
1.10      anton      89: 
                     90: Simple instructions
                     91: 
                     92: * C Code Macros::               Macros recognized by Vmgen
                     93: * C Code restrictions::         Vmgen makes assumptions about C code
                     94: 
                     95: Using the generated code
                     96: 
                     97: * VM engine::                   Executing VM code
                     98: * VM instruction table::        
                     99: * VM code generation::          Creating VM code (in the front-end)
                    100: * Peephole optimization::       Creating VM superinstructions
                    101: * VM disassembler::             for debugging the front end
                    102: * VM profiler::                 for finding worthwhile superinstructions
                    103: 
1.13      anton     104: Hints
                    105: 
                    106: * Floating point::              and stacks
                    107: 
1.10      anton     108: Copying This Manual
                    109: 
                    110: * GNU Free Documentation License::  License for copying this manual.
                    111: 
                    112: @end detailmenu
                    113: @end menu
1.1       anton     114: 
                    115: @c @ifnottex
1.11      anton     116: @c This file documents Vmgen (Gforth @value{VERSION}).
1.1       anton     117: 
1.10      anton     118: @c ************************************************************
                    119: @node Introduction, Why interpreters?, Top, Top
1.2       anton     120: @chapter Introduction
1.1       anton     121: 
                    122: Vmgen is a tool for writing efficient interpreters.  It takes a simple
                    123: virtual machine description and generates efficient C code for dealing
                    124: with the virtual machine code in various ways (in particular, executing
                    125: it).  The run-time efficiency of the resulting interpreters is usually
                    126: within a factor of 10 of machine code produced by an optimizing
                    127: compiler.
                    128: 
1.11      anton     129: The interpreter design strategy supported by Vmgen is to divide the
1.1       anton     130: interpreter into two parts:
                    131: 
                    132: @itemize @bullet
                    133: 
                    134: @item The @emph{front end} takes the source code of the language to be
                    135: implemented, and translates it into virtual machine code.  This is
                    136: similar to an ordinary compiler front end; typically an interpreter
                    137: front-end performs no optimization, so it is relatively simple to
                    138: implement and runs fast.
                    139: 
                    140: @item The @emph{virtual machine interpreter} executes the virtual
                    141: machine code.
                    142: 
                    143: @end itemize
                    144: 
                    145: Such a division is usually used in interpreters, for modularity as well
1.6       anton     146: as for efficiency.  The virtual machine code is typically passed between
                    147: front end and virtual machine interpreter in memory, like in a
1.1       anton     148: load-and-go compiler; this avoids the complexity and time cost of
                    149: writing the code to a file and reading it again.
                    150: 
                    151: A @emph{virtual machine} (VM) represents the program as a sequence of
                    152: @emph{VM instructions}, following each other in memory, similar to real
                    153: machine code.  Control flow occurs through VM branch instructions, like
                    154: in a real machine.
                    155: 
1.12      anton     156: @cindex functionality features overview
1.11      anton     157: In this setup, Vmgen can generate most of the code dealing with virtual
1.1       anton     158: machine instructions from a simple description of the virtual machine
1.11      anton     159: instructions (@pxref{Input File Format}), in particular:
1.1       anton     160: 
1.13      anton     161: @table @strong
1.1       anton     162: 
                    163: @item VM instruction execution
                    164: 
                    165: @item VM code generation
                    166: Useful in the front end.
                    167: 
                    168: @item VM code decompiler
                    169: Useful for debugging the front end.
                    170: 
                    171: @item VM code tracing
                    172: Useful for debugging the front end and the VM interpreter.  You will
                    173: typically provide other means for debugging the user's programs at the
                    174: source level.
                    175: 
                    176: @item VM code profiling
1.12      anton     177: Useful for optimizing the VM interpreter with superinstructions
1.11      anton     178: (@pxref{VM profiler}).
1.1       anton     179: 
                    180: @end table
                    181: 
1.13      anton     182: To create parts of the interpretive system that do not deal with VM
                    183: instructions, you have to use other tools (e.g., @command{bison}) and/or
                    184: hand-code them.
                    185: 
1.12      anton     186: @cindex efficiency features overview
1.11      anton     187: @noindent
                    188: Vmgen supports efficient interpreters though various optimizations, in
1.1       anton     189: particular
                    190: 
1.11      anton     191: @itemize @bullet
1.1       anton     192: 
                    193: @item Threaded code
                    194: 
                    195: @item Caching the top-of-stack in a register
                    196: 
                    197: @item Combining VM instructions into superinstructions
                    198: 
                    199: @item
                    200: Replicating VM (super)instructions for better BTB prediction accuracy
                    201: (not yet in vmgen-ex, but already in Gforth).
                    202: 
                    203: @end itemize
                    204: 
1.12      anton     205: @cindex speed for JVM
1.11      anton     206: As a result, Vmgen-based interpreters are only about an order of
                    207: magnitude slower than native code from an optimizing C compiler on small
1.1       anton     208: benchmarks; on large benchmarks, which spend more time in the run-time
1.2       anton     209: system, the slowdown is often less (e.g., the slowdown of a
                    210: Vmgen-generated JVM interpreter over the best JVM JIT compiler we
                    211: measured is only a factor of 2-3 for large benchmarks; some other JITs
                    212: and all other interpreters we looked at were slower than our
                    213: interpreter).
1.1       anton     214: 
                    215: VMs are usually designed as stack machines (passing data between VM
1.11      anton     216: instructions on a stack), and Vmgen supports such designs especially
1.12      anton     217: well; however, you can also use Vmgen for implementing a register VM
                    218: (@pxref{Register Machines}) and still benefit from most of the advantages
                    219: offered by Vmgen.
1.1       anton     220: 
1.2       anton     221: There are many potential uses of the instruction descriptions that are
                    222: not implemented at the moment, but we are open for feature requests, and
1.13      anton     223: we will consider new features if someone asks for them; so the feature
1.2       anton     224: list above is not exhaustive.
1.1       anton     225: 
1.2       anton     226: @c *********************************************************************
1.10      anton     227: @node Why interpreters?, Concepts, Introduction, Top
1.2       anton     228: @chapter Why interpreters?
1.12      anton     229: @cindex interpreters, advantages
                    230: @cindex advantages of interpreters
                    231: @cindex advantages of vmgen
1.2       anton     232: 
                    233: Interpreters are a popular language implementation technique because
                    234: they combine all three of the following advantages:
                    235: 
1.11      anton     236: @itemize @bullet
1.2       anton     237: 
                    238: @item Ease of implementation
                    239: 
                    240: @item Portability
                    241: 
                    242: @item Fast edit-compile-run cycle
                    243: 
                    244: @end itemize
                    245: 
1.12      anton     246: Vmgen makes it even easier to implement interpreters.
                    247: 
                    248: @cindex speed of interpreters
1.2       anton     249: The main disadvantage of interpreters is their run-time speed.  However,
                    250: there are huge differences between different interpreters in this area:
                    251: the slowdown over optimized C code on programs consisting of simple
                    252: operations is typically a factor of 10 for the more efficient
                    253: interpreters, and a factor of 1000 for the less efficient ones (the
                    254: slowdown for programs executing complex operations is less, because the
                    255: time spent in libraries for executing complex operations is the same in
                    256: all implementation strategies).
                    257: 
1.12      anton     258: Vmgen supports techniques for building efficient interpreters.
1.2       anton     259: 
                    260: @c ********************************************************************
1.11      anton     261: @node Concepts, Invoking Vmgen, Why interpreters?, Top
1.2       anton     262: @chapter Concepts
                    263: 
1.10      anton     264: @menu
                    265: * Front end and VM interpreter::  Modularizing an interpretive system
                    266: * Data handling::               Stacks, registers, immediate arguments
                    267: * Dispatch::                    From one VM instruction to the next
                    268: @end menu
                    269: 
1.2       anton     270: @c --------------------------------------------------------------------
1.10      anton     271: @node Front end and VM interpreter, Data handling, Concepts, Concepts
                    272: @section Front end and VM interpreter
1.12      anton     273: @cindex modularization of interpreters
1.2       anton     274: 
                    275: @cindex front-end
                    276: Interpretive systems are typically divided into a @emph{front end} that
                    277: parses the input language and produces an intermediate representation
                    278: for the program, and an interpreter that executes the intermediate
                    279: representation of the program.
                    280: 
                    281: @cindex virtual machine
                    282: @cindex VM
1.12      anton     283: @cindex VM instruction
1.2       anton     284: @cindex instruction, VM
1.12      anton     285: @cindex VM branch instruction
                    286: @cindex branch instruction, VM
                    287: @cindex VM register
                    288: @cindex register, VM
                    289: @cindex opcode, VM instruction
                    290: @cindex immediate argument, VM instruction
1.2       anton     291: For efficient interpreters the intermediate representation of choice is
                    292: virtual machine code (rather than, e.g., an abstract syntax tree).
                    293: @emph{Virtual machine} (VM) code consists of VM instructions arranged
                    294: sequentially in memory; they are executed in sequence by the VM
1.12      anton     295: interpreter, but VM branch instructions can change the control flow and
                    296: are used for implementing control structures.  The conceptual similarity
                    297: to real machine code results in the name @emph{virtual machine}.
                    298: Various terms similar to terms for real machines are used; e.g., there
                    299: are @emph{VM registers} (like the instruction pointer and stack
                    300: pointer(s)), and the VM instruction consists of an @emph{opcode} and
                    301: @emph{immediate arguments}.
1.2       anton     302: 
1.11      anton     303: In this framework, Vmgen supports building the VM interpreter and any
1.2       anton     304: other component dealing with VM instructions.  It does not have any
                    305: support for the front end, apart from VM code generation support.  The
                    306: front end can be implemented with classical compiler front-end
1.3       anton     307: techniques, supported by tools like @command{flex} and @command{bison}.
1.2       anton     308: 
                    309: The intermediate representation is usually just internal to the
                    310: interpreter, but some systems also support saving it to a file, either
                    311: as an image file, or in a full-blown linkable file format (e.g., JVM).
                    312: Vmgen currently has no special support for such features, but the
                    313: information in the instruction descriptions can be helpful, and we are
1.13      anton     314: open to feature requests and suggestions.
1.3       anton     315: 
1.10      anton     316: @c --------------------------------------------------------------------
                    317: @node Data handling, Dispatch, Front end and VM interpreter, Concepts
1.3       anton     318: @section Data handling
                    319: 
                    320: @cindex stack machine
                    321: @cindex register machine
                    322: Most VMs use one or more stacks for passing temporary data between VM
                    323: instructions.  Another option is to use a register machine architecture
1.13      anton     324: for the virtual machine; we believe that using a stack architecture is
                    325: usually both simpler and faster.
                    326: 
                    327: however, this option is slower or
1.3       anton     328: significantly more complex to implement than a stack machine architecture.
                    329: 
                    330: Vmgen has special support and optimizations for stack VMs, making their
                    331: implementation easy and efficient.
                    332: 
1.11      anton     333: You can also implement a register VM with Vmgen (@pxref{Register
                    334: Machines}), and you will still profit from most Vmgen features.
1.3       anton     335: 
                    336: @cindex stack item size
                    337: @cindex size, stack items
                    338: Stack items all have the same size, so they typically will be as wide as
                    339: an integer, pointer, or floating-point value.  Vmgen supports treating
                    340: two consecutive stack items as a single value, but anything larger is
                    341: best kept in some other memory area (e.g., the heap), with pointers to
                    342: the data on the stack.
                    343: 
                    344: @cindex instruction stream
                    345: @cindex immediate arguments
                    346: Another source of data is immediate arguments VM instructions (in the VM
                    347: instruction stream).  The VM instruction stream is handled similar to a
1.11      anton     348: stack in Vmgen.
1.3       anton     349: 
                    350: @cindex garbage collection
                    351: @cindex reference counting
1.12      anton     352: Vmgen has no built-in support for, nor restrictions against
                    353: @emph{garbage collection}.  If you need garbage collection, you need to
                    354: provide it in your run-time libraries.  Using @emph{reference counting}
                    355: is probably harder, but might be possible (contact us if you are
                    356: interested).
1.3       anton     357: @c reference counting might be possible by including counting code in 
                    358: @c the conversion macros.
                    359: 
1.10      anton     360: @c --------------------------------------------------------------------
                    361: @node Dispatch,  , Data handling, Concepts
1.6       anton     362: @section Dispatch
1.12      anton     363: @cindex Dispatch of VM instructions
                    364: @cindex main interpreter loop
1.6       anton     365: 
1.11      anton     366: Understanding this section is probably not necessary for using Vmgen,
1.6       anton     367: but it may help.  You may want to skip it now, and read it if you find statements about dispatch methods confusing.
                    368: 
                    369: After executing one VM instruction, the VM interpreter has to dispatch
1.11      anton     370: the next VM instruction (Vmgen calls the dispatch routine @samp{NEXT}).
1.6       anton     371: Vmgen supports two methods of dispatch:
                    372: 
1.13      anton     373: @table @strong
1.6       anton     374: 
                    375: @item switch dispatch
1.12      anton     376: @cindex switch dispatch
1.6       anton     377: In this method the VM interpreter contains a giant @code{switch}
                    378: statement, with one @code{case} for each VM instruction.  The VM
1.12      anton     379: instruction opcodes are represented by integers (e.g., produced by an
                    380: @code{enum}) in the VM code, and dispatch occurs by loading the next
                    381: opcode, @code{switch}ing on it, and continuing at the appropriate
                    382: @code{case}; after executing the VM instruction, the VM interpreter
                    383: jumps back to the dispatch code.
1.6       anton     384: 
                    385: @item threaded code
1.12      anton     386: @cindex threaded code
                    387: This method represents a VM instruction opcode by the address of the
                    388: start of the machine code fragment for executing the VM instruction.
1.6       anton     389: Dispatch consists of loading this address, jumping to it, and
                    390: incrementing the VM instruction pointer.  Typically the threaded-code
                    391: dispatch code is appended directly to the code for executing the VM
                    392: instruction.  Threaded code cannot be implemented in ANSI C, but it can
1.11      anton     393: be implemented using GNU C's labels-as-values extension (@pxref{Labels
                    394: as Values, , Labels as Values, gcc.info, GNU C Manual}).
1.6       anton     395: 
1.13      anton     396: @c call threading
1.6       anton     397: @end table
                    398: 
1.12      anton     399: Threaded code can be twice as fast as switch dispatch, depending on the
                    400: interpreter, the benchmark, and the machine.
                    401: 
1.3       anton     402: @c *************************************************************
1.11      anton     403: @node Invoking Vmgen, Example, Concepts, Top
                    404: @chapter Invoking Vmgen
1.12      anton     405: @cindex Invoking Vmgen
1.3       anton     406: 
1.11      anton     407: The usual way to invoke Vmgen is as follows:
1.3       anton     408: 
                    409: @example
1.13      anton     410: vmgen @var{inputfile}
1.3       anton     411: @end example
                    412: 
1.13      anton     413: Here @var{inputfile} is the VM instruction description file, which
                    414: usually ends in @file{.vmg}.  The output filenames are made by taking
                    415: the basename of @file{inputfile} (i.e., the output files will be created
                    416: in the current working directory) and replacing @file{.vmg} with
                    417: @file{-vm.i}, @file{-disasm.i}, @file{-gen.i}, @file{-labels.i},
                    418: @file{-profile.i}, and @file{-peephole.i}.  E.g., @command{vmgen
                    419: hack/foo.vmg} will create @file{foo-vm.i}, @file{foo-disasm.i},
                    420: @file{foo-gen.i}, @file{foo-labels.i}, @file{foo-profile.i} and
                    421: @file{foo-peephole.i}.
1.3       anton     422: 
1.11      anton     423: The command-line options supported by Vmgen are
1.3       anton     424: 
                    425: @table @option
                    426: 
                    427: @cindex -h, command-line option
                    428: @cindex --help, command-line option
                    429: @item --help
                    430: @itemx -h
                    431: Print a message about the command-line options
                    432: 
                    433: @cindex -v, command-line option
                    434: @cindex --version, command-line option
                    435: @item --version
                    436: @itemx -v
                    437: Print version and exit
                    438: @end table
                    439: 
                    440: @c env vars GFORTHDIR GFORTHDATADIR
                    441: 
1.5       anton     442: @c ****************************************************************
1.11      anton     443: @node Example, Input File Format, Invoking Vmgen, Top
1.5       anton     444: @chapter Example
1.12      anton     445: @cindex example of a Vmgen-based interpreter
1.5       anton     446: 
1.10      anton     447: @menu
                    448: * Example overview::            
                    449: * Using profiling to create superinstructions::  
                    450: @end menu
                    451: 
                    452: @c --------------------------------------------------------------------
                    453: @node Example overview, Using profiling to create superinstructions, Example, Example
1.5       anton     454: @section Example overview
1.12      anton     455: @cindex example overview
                    456: @cindex @file{vmgen-ex}
                    457: @cindex @file{vmgen-ex2}
1.5       anton     458: 
1.11      anton     459: There are two versions of the same example for using Vmgen:
1.5       anton     460: @file{vmgen-ex} and @file{vmgen-ex2} (you can also see Gforth as
                    461: example, but it uses additional (undocumented) features, and also
                    462: differs in some other respects).  The example implements @emph{mini}, a
                    463: tiny Modula-2-like language with a small JavaVM-like virtual machine.
1.12      anton     464: 
1.5       anton     465: The difference between the examples is that @file{vmgen-ex} uses many
                    466: casts, and @file{vmgen-ex2} tries to avoids most casts and uses unions
1.12      anton     467: instead.  In the rest of this manual we usually mention just files in
                    468: @file{vmgen-ex}; if you want to use unions, use the equivalent file in
                    469: @file{vmgen-ex2}.
                    470: @cindex unions example
                    471: @cindex casts example
1.5       anton     472: 
                    473: The files provided with each example are:
1.12      anton     474: @cindex example files
1.5       anton     475: 
                    476: @example
                    477: Makefile
                    478: README
                    479: disasm.c           wrapper file
                    480: engine.c           wrapper file
                    481: peephole.c         wrapper file
                    482: profile.c          wrapper file
                    483: mini-inst.vmg      simple VM instructions
                    484: mini-super.vmg     superinstructions (empty at first)
                    485: mini.h             common declarations
                    486: mini.l             scanner
                    487: mini.y             front end (parser, VM code generator)
                    488: support.c          main() and other support functions
                    489: fib.mini           example mini program
                    490: simple.mini        example mini program
                    491: test.mini          example mini program (tests everything)
                    492: test.out           test.mini output
                    493: stat.awk           script for aggregating profile information
                    494: peephole-blacklist list of instructions not allowed in superinstructions
                    495: seq2rule.awk       script for creating superinstructions
                    496: @end example
                    497: 
                    498: For your own interpreter, you would typically copy the following files
                    499: and change little, if anything:
1.12      anton     500: @cindex wrapper files
1.5       anton     501: 
                    502: @example
                    503: disasm.c           wrapper file
                    504: engine.c           wrapper file
                    505: peephole.c         wrapper file
                    506: profile.c          wrapper file
                    507: stat.awk           script for aggregating profile information
                    508: seq2rule.awk       script for creating superinstructions
                    509: @end example
                    510: 
1.11      anton     511: @noindent
1.5       anton     512: You would typically change much in or replace the following files:
                    513: 
                    514: @example
                    515: Makefile
                    516: mini-inst.vmg      simple VM instructions
                    517: mini.h             common declarations
                    518: mini.l             scanner
                    519: mini.y             front end (parser, VM code generator)
                    520: support.c          main() and other support functions
                    521: peephole-blacklist list of instructions not allowed in superinstructions
                    522: @end example
                    523: 
                    524: You can build the example by @code{cd}ing into the example's directory,
1.12      anton     525: and then typing @code{make}; you can check that it works with @code{make
1.5       anton     526: check}.  You can run run mini programs like this:
                    527: 
                    528: @example
                    529: ./mini fib.mini
                    530: @end example
                    531: 
1.12      anton     532: To learn about the options, type @code{./mini -h}.
1.5       anton     533: 
1.10      anton     534: @c --------------------------------------------------------------------
                    535: @node Using profiling to create superinstructions,  , Example overview, Example
1.5       anton     536: @section Using profiling to create superinstructions
1.12      anton     537: @cindex profiling example
                    538: @cindex superinstructions example
1.5       anton     539: 
                    540: I have not added rules for this in the @file{Makefile} (there are many
                    541: options for selecting superinstructions, and I did not want to hardcode
                    542: one into the @file{Makefile}), but there are some supporting scripts, and
                    543: here's an example:
                    544: 
                    545: Suppose you want to use @file{fib.mini} and @file{test.mini} as training
                    546: programs, you get the profiles like this:
                    547: 
                    548: @example
                    549: make fib.prof test.prof #takes a few seconds
                    550: @end example
                    551: 
                    552: You can aggregate these profiles with @file{stat.awk}:
                    553: 
                    554: @example
                    555: awk -f stat.awk fib.prof test.prof
                    556: @end example
                    557: 
                    558: The result contains lines like:
                    559: 
                    560: @example
                    561:       2      16        36910041 loadlocal lit
                    562: @end example
                    563: 
                    564: This means that the sequence @code{loadlocal lit} statically occurs a
                    565: total of 16 times in 2 profiles, with a dynamic execution count of
                    566: 36910041.
                    567: 
                    568: The numbers can be used in various ways to select superinstructions.
                    569: E.g., if you just want to select all sequences with a dynamic
                    570: execution count exceeding 10000, you would use the following pipeline:
                    571: 
                    572: @example
                    573: awk -f stat.awk fib.prof test.prof|
                    574: awk '$3>=10000'|                #select sequences
                    575: fgrep -v -f peephole-blacklist| #eliminate wrong instructions
1.12      anton     576: awk -f seq2rule.awk|  #transform sequences into superinstruction rules
1.5       anton     577: sort -k 3 >mini-super.vmg       #sort sequences
                    578: @end example
                    579: 
                    580: The file @file{peephole-blacklist} contains all instructions that
                    581: directly access a stack or stack pointer (for mini: @code{call},
                    582: @code{return}); the sort step is necessary to ensure that prefixes
1.13      anton     583: precede larger superinstructions.
1.5       anton     584: 
                    585: Now you can create a version of mini with superinstructions by just
                    586: saying @samp{make}
                    587: 
1.10      anton     588: 
1.3       anton     589: @c ***************************************************************
1.13      anton     590: @node Input File Format, Error messages, Example, Top
1.3       anton     591: @chapter Input File Format
1.12      anton     592: @cindex input file format
                    593: @cindex format, input file
1.3       anton     594: 
                    595: Vmgen takes as input a file containing specifications of virtual machine
                    596: instructions.  This file usually has a name ending in @file{.vmg}.
                    597: 
1.5       anton     598: Most examples are taken from the example in @file{vmgen-ex}.
1.3       anton     599: 
1.10      anton     600: @menu
                    601: * Input File Grammar::          
                    602: * Simple instructions::         
                    603: * Superinstructions::           
1.11      anton     604: * Register Machines::           How to define register VM instructions
1.10      anton     605: @end menu
                    606: 
                    607: @c --------------------------------------------------------------------
                    608: @node Input File Grammar, Simple instructions, Input File Format, Input File Format
1.3       anton     609: @section Input File Grammar
1.12      anton     610: @cindex grammar, input file
                    611: @cindex input file grammar
1.3       anton     612: 
                    613: The grammar is in EBNF format, with @code{@var{a}|@var{b}} meaning
                    614: ``@var{a} or @var{b}'', @code{@{@var{c}@}} meaning 0 or more repetitions
                    615: of @var{c} and @code{[@var{d}]} meaning 0 or 1 repetitions of @var{d}.
                    616: 
1.12      anton     617: @cindex free-format, not
1.3       anton     618: Vmgen input is not free-format, so you have to take care where you put
                    619: spaces and especially newlines; it's not as bad as makefiles, though:
                    620: any sequence of spaces and tabs is equivalent to a single space.
                    621: 
                    622: @example
1.11      anton     623: description: @{instruction|comment|eval-escape@}
1.3       anton     624: 
                    625: instruction: simple-inst|superinst
                    626: 
1.12      anton     627: simple-inst: ident ' (' stack-effect ' )' newline c-code newline newline
1.3       anton     628: 
1.12      anton     629: stack-effect: @{ident@} ' --' @{ident@}
1.3       anton     630: 
1.12      anton     631: super-inst: ident ' =' ident @{ident@}  
1.3       anton     632: 
1.12      anton     633: comment:      '\ '  text newline
1.3       anton     634: 
1.13      anton     635: eval-escape:  '\E ' text newline
1.3       anton     636: @end example
                    637: @c \+ \- \g \f \c
                    638: 
                    639: Note that the @code{\}s in this grammar are meant literally, not as
1.5       anton     640: C-style encodings for non-printable characters.
1.3       anton     641: 
                    642: The C code in @code{simple-inst} must not contain empty lines (because
1.11      anton     643: Vmgen would mistake that as the end of the simple-inst.  The text in
1.3       anton     644: @code{comment} and @code{eval-escape} must not contain a newline.
                    645: @code{Ident} must conform to the usual conventions of C identifiers
1.11      anton     646: (otherwise the C compiler would choke on the Vmgen output).
1.3       anton     647: 
                    648: Vmgen understands a few extensions beyond the grammar given here, but
                    649: these extensions are only useful for building Gforth.  You can find a
                    650: description of the format used for Gforth in @file{prim}.
                    651: 
1.10      anton     652: @subsection Eval escapes
1.12      anton     653: @cindex escape to Forth
                    654: @cindex eval escape
                    655: 
1.13      anton     656: 
                    657: 
1.3       anton     658: @c woanders?
                    659: The text in @code{eval-escape} is Forth code that is evaluated when
1.13      anton     660: Vmgen reads the line.  You will normally use this feature to define
                    661: stacks and types.
                    662: 
                    663: If you do not know (and do not want to learn) Forth, you can build the
                    664: text according to the following grammar; these rules are normally all
                    665: Forth you need for using Vmgen:
1.3       anton     666: 
                    667: @example
                    668: text: stack-decl|type-prefix-decl|stack-prefix-decl
                    669: 
1.12      anton     670: stack-decl: 'stack ' ident ident ident
1.3       anton     671: type-prefix-decl: 
1.12      anton     672:     's" ' string '" ' ('single'|'double') ident 'type-prefix' ident
                    673: stack-prefix-decl:  ident 'stack-prefix' string
1.3       anton     674: @end example
                    675: 
                    676: Note that the syntax of this code is not checked thoroughly (there are
1.13      anton     677: many other Forth program fragments that could be written in an
                    678: eval-escape).
1.3       anton     679: 
1.14    ! anton     680: A stack prefix can contain letters, digits, or @samp{:}, and may start
        !           681: with an @samp{#}; e.g., in Gforth the return stack has the stack prefix
        !           682: @samp{R:}.  This restriction is not checked during the stack prefix
        !           683: definition, but it is enforced by the parsing rules for stack items
        !           684: later.
        !           685: 
1.3       anton     686: If you know Forth, the stack effects of the non-standard words involved
                    687: are:
1.12      anton     688: @findex stack
                    689: @findex type-prefix
                    690: @findex single
                    691: @findex double
                    692: @findex stack-prefix
1.3       anton     693: @example
                    694: stack        ( "name" "pointer" "type" -- )
                    695:              ( name execution: -- stack )
1.14    ! anton     696: type-prefix  ( addr u item-size stack "prefix" -- )
        !           697: single       ( -- item-size )
        !           698: double       ( -- item-size )
1.3       anton     699: stack-prefix ( stack "prefix" -- )
                    700: @end example
                    701: 
1.14    ! anton     702: An @var{item-size} takes three cells on the stack.
1.5       anton     703: 
1.10      anton     704: @c --------------------------------------------------------------------
                    705: @node Simple instructions, Superinstructions, Input File Grammar, Input File Format
1.3       anton     706: @section Simple instructions
1.12      anton     707: @cindex simple VM instruction
                    708: @cindex instruction, simple VM
1.3       anton     709: 
                    710: We will use the following simple VM instruction description as example:
                    711: 
                    712: @example
                    713: sub ( i1 i2 -- i )
                    714: i = i1-i2;
                    715: @end example
                    716: 
                    717: The first line specifies the name of the VM instruction (@code{sub}) and
                    718: its stack effect (@code{i1 i2 -- i}).  The rest of the description is
                    719: just plain C code.
                    720: 
                    721: @cindex stack effect
1.12      anton     722: @cindex effect, stack
1.3       anton     723: The stack effect specifies that @code{sub} pulls two integers from the
1.12      anton     724: data stack and puts them in the C variables @code{i1} and @code{i2}
                    725: (with the rightmost item (@code{i2}) taken from the top of stack;
                    726: intuition: if you push @code{i1}, then @code{i2} on the stack, the
                    727: resulting stack picture is @code{i1 i2}) and later pushes one integer
                    728: (@code{i}) on the data stack (the rightmost item is on the top
                    729: afterwards).
                    730: 
                    731: @cindex prefix, type
                    732: @cindex type prefix
                    733: @cindex default stack of a type prefix
1.3       anton     734: How do we know the type and stack of the stack items?  Vmgen uses
                    735: prefixes, similar to Fortran; in contrast to Fortran, you have to
                    736: define the prefix first:
                    737: 
                    738: @example
                    739: \E s" Cell"   single data-stack type-prefix i
                    740: @end example
                    741: 
                    742: This defines the prefix @code{i} to refer to the type @code{Cell}
                    743: (defined as @code{long} in @file{mini.h}) and, by default, to the
                    744: @code{data-stack}.  It also specifies that this type takes one stack
                    745: item (@code{single}).  The type prefix is part of the variable name.
                    746: 
1.12      anton     747: @cindex stack definition
                    748: @cindex defining a stack
1.3       anton     749: Before we can use @code{data-stack} in this way, we have to define it:
                    750: 
                    751: @example
                    752: \E stack data-stack sp Cell
                    753: @end example
                    754: @c !! use something other than Cell
                    755: 
1.12      anton     756: @cindex stack basic type
                    757: @cindex basic type of a stack
                    758: @cindex type of a stack, basic
                    759: @cindex stack growth direction
1.3       anton     760: This line defines the stack @code{data-stack}, which uses the stack
                    761: pointer @code{sp}, and each item has the basic type @code{Cell}; other
                    762: types have to fit into one or two @code{Cell}s (depending on whether the
1.12      anton     763: type is @code{single} or @code{double} wide), and are cast from and to
                    764: Cells on accessing the @code{data-stack} with type cast macros
1.11      anton     765: (@pxref{VM engine}).  Stacks grow towards lower addresses in
                    766: Vmgen-erated interpreters.
1.3       anton     767: 
1.12      anton     768: @cindex stack prefix
                    769: @cindex prefix, stack
1.3       anton     770: We can override the default stack of a stack item by using a stack
                    771: prefix.  E.g., consider the following instruction:
                    772: 
                    773: @example
                    774: lit ( #i -- i )
                    775: @end example
                    776: 
                    777: The VM instruction @code{lit} takes the item @code{i} from the
1.5       anton     778: instruction stream (indicated by the prefix @code{#}), and pushes it on
1.3       anton     779: the (default) data stack.  The stack prefix is not part of the variable
                    780: name.  Stack prefixes are defined like this:
                    781: 
                    782: @example
                    783: \E inst-stream stack-prefix #
                    784: @end example
                    785: 
1.5       anton     786: This definition defines that the stack prefix @code{#} specifies the
1.3       anton     787: ``stack'' @code{inst-stream}.  Since the instruction stream behaves a
                    788: little differently than an ordinary stack, it is predefined, and you do
                    789: not need to define it.
                    790: 
1.12      anton     791: @cindex instruction stream
1.3       anton     792: The instruction stream contains instructions and their immediate
                    793: arguments, so specifying that an argument comes from the instruction
                    794: stream indicates an immediate argument.  Of course, instruction stream
                    795: arguments can only appear to the left of @code{--} in the stack effect.
                    796: If there are multiple instruction stream arguments, the leftmost is the
                    797: first one (just as the intuition suggests).
                    798: 
1.10      anton     799: @menu
                    800: * C Code Macros::               Macros recognized by Vmgen
                    801: * C Code restrictions::         Vmgen makes assumptions about C code
                    802: @end menu
                    803: 
                    804: @c --------------------------------------------------------------------
                    805: @node C Code Macros, C Code restrictions, Simple instructions, Simple instructions
                    806: @subsection C Code Macros
1.12      anton     807: @cindex macros recognized by Vmgen
                    808: @cindex basic block, VM level
1.5       anton     809: 
                    810: Vmgen recognizes the following strings in the C code part of simple
                    811: instructions:
                    812: 
1.12      anton     813: @table @code
1.5       anton     814: 
                    815: @item SET_IP
1.12      anton     816: @findex SET_IP
1.11      anton     817: As far as Vmgen is concerned, a VM instruction containing this ends a VM
1.5       anton     818: basic block (used in profiling to delimit profiled sequences).  On the C
                    819: level, this also sets the instruction pointer.
                    820: 
                    821: @item SUPER_END
1.12      anton     822: @findex SUPER_END
                    823: This ends a basic block (for profiling), even if the instruction
                    824: contains no @code{SET_IP}.
1.5       anton     825: 
1.13      anton     826: @item INST_TAIL;
                    827: @findex INST_TAIL;
                    828: Vmgen replaces @samp{INST_TAIL;} with code for ending a VM instruction and
                    829: dispatching the next VM instruction.  Even without a @samp{INST_TAIL;} this
1.12      anton     830: happens automatically when control reaches the end of the C code.  If
                    831: you want to have this in the middle of the C code, you need to use
1.13      anton     832: @samp{INST_TAIL;}.  A typical example is a conditional VM branch:
1.5       anton     833: 
                    834: @example
1.11      anton     835: if (branch_condition) @{
1.13      anton     836:   SET_IP(target); INST_TAIL;
1.11      anton     837: @}
1.5       anton     838: /* implicit tail follows here */
                    839: @end example
                    840: 
1.13      anton     841: In this example, @samp{INST_TAIL;} is not strictly necessary, because there
1.5       anton     842: is another one implicitly after the if-statement, but using it improves
                    843: branch prediction accuracy slightly and allows other optimizations.
                    844: 
                    845: @item SUPER_CONTINUE
1.12      anton     846: @findex SUPER_CONTINUE
1.5       anton     847: This indicates that the implicit tail at the end of the VM instruction
                    848: dispatches the sequentially next VM instruction even if there is a
                    849: @code{SET_IP} in the VM instruction.  This enables an optimization that
                    850: is not yet implemented in the vmgen-ex code (but in Gforth).  The
                    851: typical application is in conditional VM branches:
                    852: 
                    853: @example
1.11      anton     854: if (branch_condition) @{
1.13      anton     855:   SET_IP(target); INST_TAIL; /* now this INST_TAIL is necessary */
1.11      anton     856: @}
1.5       anton     857: SUPER_CONTINUE;
                    858: @end example
                    859: 
                    860: @end table
                    861: 
1.11      anton     862: Note that Vmgen is not smart about C-level tokenization, comments,
1.5       anton     863: strings, or conditional compilation, so it will interpret even a
                    864: commented-out SUPER_END as ending a basic block (or, e.g.,
1.13      anton     865: @samp{RESET_IP;} as @samp{SET_IP;}).  Conversely, Vmgen requires the literal
1.11      anton     866: presence of these strings; Vmgen will not see them if they are hiding in
1.5       anton     867: a C preprocessor macro.
                    868: 
                    869: 
1.10      anton     870: @c --------------------------------------------------------------------
                    871: @node C Code restrictions,  , C Code Macros, Simple instructions
                    872: @subsection C Code restrictions
1.12      anton     873: @cindex C code restrictions
                    874: @cindex restrictions on C code
                    875: @cindex assumptions about C code
                    876: 
                    877: @cindex accessing stack (pointer)
                    878: @cindex stack pointer, access
                    879: @cindex instruction pointer, access
1.5       anton     880: Vmgen generates code and performs some optimizations under the
                    881: assumption that the user-supplied C code does not access the stack
                    882: pointers or stack items, and that accesses to the instruction pointer
                    883: only occur through special macros.  In general you should heed these
                    884: restrictions.  However, if you need to break these restrictions, read
                    885: the following.
                    886: 
                    887: Accessing a stack or stack pointer directly can be a problem for several
                    888: reasons: 
1.12      anton     889: @cindex stack caching, restriction on C code
                    890: @cindex superinstructions, restrictions on components
1.5       anton     891: 
1.11      anton     892: @itemize @bullet
1.5       anton     893: 
                    894: @item
1.12      anton     895: Vmgen optionally supports caching the top-of-stack item in a local
                    896: variable (that is allocated to a register).  This is the most frequent
                    897: source of trouble.  You can deal with it either by not using
                    898: top-of-stack caching (slowdown factor 1-1.4, depending on machine), or
                    899: by inserting flushing code (e.g., @samp{IF_spTOS(sp[...] = spTOS);}) at
                    900: the start and reloading code (e.g., @samp{IF_spTOS(spTOS = sp[0])}) at
                    901: the end of problematic C code.  Vmgen inserts a stack pointer update
                    902: before the start of the user-supplied C code, so the flushing code has
                    903: to use an index that corrects for that.  In the future, this flushing
                    904: may be done automatically by mentioning a special string in the C code.
1.5       anton     905: @c sometimes flushing and/or reloading unnecessary
                    906: 
                    907: @item
1.11      anton     908: The Vmgen-erated code loads the stack items from stack-pointer-indexed
1.5       anton     909: memory into variables before the user-supplied C code, and stores them
                    910: from variables to stack-pointer-indexed memory afterwards.  If you do
                    911: any writes to the stack through its stack pointer in your C code, it
1.13      anton     912: will not affect the variables, and your write may be overwritten by the
1.5       anton     913: stores after the C code.  Similarly, a read from a stack using a stack
                    914: pointer will not reflect computations of stack items in the same VM
                    915: instruction.
                    916: 
                    917: @item
                    918: Superinstructions keep stack items in variables across the whole
                    919: superinstruction.  So you should not include VM instructions, that
1.12      anton     920: access a stack or stack pointer, as components of superinstructions
                    921: (@pxref{VM profiler}).
1.5       anton     922: 
                    923: @end itemize
                    924: 
                    925: You should access the instruction pointer only through its special
                    926: macros (@samp{IP}, @samp{SET_IP}, @samp{IPTOS}); this ensure that these
                    927: macros can be implemented in several ways for best performance.
                    928: @samp{IP} points to the next instruction, and @samp{IPTOS} is its
                    929: contents.
                    930: 
                    931: 
1.10      anton     932: @c --------------------------------------------------------------------
1.11      anton     933: @node Superinstructions, Register Machines, Simple instructions, Input File Format
1.3       anton     934: @section Superinstructions
1.12      anton     935: @cindex superinstructions, defining
                    936: @cindex defining superinstructions
1.5       anton     937: 
1.8       anton     938: Note: don't invest too much work in (static) superinstructions; a future
1.11      anton     939: version of Vmgen will support dynamic superinstructions (see Ian
1.8       anton     940: Piumarta and Fabio Riccardi, @cite{Optimizing Direct Threaded Code by
                    941: Selective Inlining}, PLDI'98), and static superinstructions have much
1.12      anton     942: less benefit in that context (preliminary results indicate only a factor
                    943: 1.1 speedup).
1.8       anton     944: 
1.5       anton     945: Here is an example of a superinstruction definition:
                    946: 
                    947: @example
                    948: lit_sub = lit sub
                    949: @end example
                    950: 
                    951: @code{lit_sub} is the name of the superinstruction, and @code{lit} and
                    952: @code{sub} are its components.  This superinstruction performs the same
                    953: action as the sequence @code{lit} and @code{sub}.  It is generated
                    954: automatically by the VM code generation functions whenever that sequence
1.11      anton     955: occurs, so if you want to use this superinstruction, you just need to
                    956: add this definition (and even that can be partially automatized,
                    957: @pxref{VM profiler}).
1.5       anton     958: 
1.12      anton     959: @cindex prefixes of superinstructions
1.5       anton     960: Vmgen requires that the component instructions are simple instructions
1.11      anton     961: defined before superinstructions using the components.  Currently, Vmgen
1.5       anton     962: also requires that all the subsequences at the start of a
                    963: superinstruction (prefixes) must be defined as superinstruction before
                    964: the superinstruction.  I.e., if you want to define a superinstruction
                    965: 
                    966: @example
1.12      anton     967: foo4 = load add sub mul
1.5       anton     968: @end example
                    969: 
1.12      anton     970: you first have to define @code{load}, @code{add}, @code{sub} and
                    971: @code{mul}, plus
1.5       anton     972: 
                    973: @example
1.12      anton     974: foo2 = load add
                    975: foo3 = load add sub
1.5       anton     976: @end example
                    977: 
                    978: Here, @code{sumof4} is the longest prefix of @code{sumof5}, and @code{sumof3}
                    979: is the longest prefix of @code{sumof4}.
                    980: 
1.11      anton     981: Note that Vmgen assumes that only the code it generates accesses stack
1.5       anton     982: pointers, the instruction pointer, and various stack items, and it
                    983: performs optimizations based on this assumption.  Therefore, VM
1.12      anton     984: instructions where your C code changes the instruction pointer should
                    985: only be used as last component; a VM instruction where your C code
                    986: accesses a stack pointer should not be used as component at all.  Vmgen
                    987: does not check these restrictions, they just result in bugs in your
                    988: interpreter.
1.5       anton     989: 
1.12      anton     990: @c -------------------------------------------------------------------
1.11      anton     991: @node Register Machines,  , Superinstructions, Input File Format
                    992: @section Register Machines
1.12      anton     993: @cindex Register VM
                    994: @cindex Superinstructions for register VMs
                    995: @cindex tracing of register VMs
1.11      anton     996: 
                    997: If you want to implement a register VM rather than a stack VM with
                    998: Vmgen, there are two ways to do it: Directly and through
                    999: superinstructions.
                   1000: 
                   1001: If you use the direct way, you define instructions that take the
                   1002: register numbers as immediate arguments, like this:
                   1003: 
                   1004: @example
                   1005: add3 ( #src1 #src2 #dest -- )
                   1006: reg[dest] = reg[src1]+reg[src2];
                   1007: @end example
                   1008: 
1.12      anton    1009: A disadvantage of this method is that during tracing you only see the
                   1010: register numbers, but not the register contents.  Actually, with an
                   1011: appropriate definition of @code{printarg_src} (@pxref{VM engine}), you
                   1012: can print the values of the source registers on entry, but you cannot
                   1013: print the value of the destination register on exit.
                   1014: 
1.11      anton    1015: If you use superinstructions to define a register VM, you define simple
                   1016: instructions that use a stack, and then define superinstructions that
                   1017: have no overall stack effect, like this:
                   1018: 
                   1019: @example
                   1020: loadreg ( #src -- n )
                   1021: n = reg[src];
                   1022: 
                   1023: storereg ( n #dest -- )
                   1024: reg[dest] = n;
                   1025: 
                   1026: adds ( n1 n2 -- n )
                   1027: n = n1+n2;
                   1028: 
                   1029: add3 = loadreg loadreg adds storereg
                   1030: @end example
                   1031: 
                   1032: An advantage of this method is that you see the values and not just the
1.12      anton    1033: register numbers in tracing.  A disadvantage of this method is that
1.11      anton    1034: currently you cannot generate superinstructions directly, but only
                   1035: through generating a sequence of simple instructions (we might change
                   1036: this in the future if there is demand).
                   1037: 
                   1038: Could the register VM support be improved, apart from the issues
                   1039: mentioned above?  It is hard to see how to do it in a general way,
                   1040: because there are a number of different designs that different people
                   1041: mean when they use the term @emph{register machine} in connection with
                   1042: VM interpreters.  However, if you have ideas or requests in that
                   1043: direction, please let me know (@pxref{Contact}).
                   1044: 
1.5       anton    1045: @c ********************************************************************
1.13      anton    1046: @node Error messages, Using the generated code, Input File Format, Top
                   1047: @chapter Error messages
                   1048: @cindex error messages
                   1049: 
                   1050: These error messages are created by Vmgen:
                   1051: 
                   1052: @table @code
                   1053: 
                   1054: @cindex @code{# can only be on the input side} error
                   1055: @item # can only be on the input side
                   1056: You have used an instruction-stream prefix (usually @samp{#}) after the
                   1057: @samp{--} (the output side); you can only use it before (the input
                   1058: side).
                   1059: 
                   1060: @cindex @code{prefix for this combination must be defined earlier} error
                   1061: @item the prefix for this combination must be defined earlier
                   1062: You have defined a superinstruction (e.g. @code{abc = a b c}) without
                   1063: defining its direct prefix (e.g., @code{ab = a b}),
                   1064: @xref{Superinstructions}.
                   1065: 
                   1066: @cindex @code{sync line syntax} error
                   1067: @item sync line syntax
                   1068: If you are using a preprocessor (e.g., @command{m4}) to generate Vmgen
                   1069: input code, you may want to create @code{#line} directives (aka sync
                   1070: lines).  This error indicates that such a line is not in th syntax
                   1071: expected by Vmgen (this should not happen).
                   1072: 
                   1073: @cindex @code{syntax error, wrong char} error
                   1074: @cindex syntax error, wrong char
                   1075: A syntax error.  Note that Vmgen is sometimes anal retentive about white
                   1076: space, especially about newlines.
                   1077: 
                   1078: @cindex @code{too many stacks} error
                   1079: @item too many stacks
                   1080: Vmgen currently supports 4 stacks; if you need more, let us know.
                   1081: 
                   1082: @cindex @code{unknown prefix} error
                   1083: @item unknown prefix
                   1084: The stack item does not match any defined type prefix (after stripping
                   1085: away any stack prefix).  You should either declare the type prefix you
                   1086: want for that stack item, or use a different type prefix
                   1087: 
                   1088: @item @code{unknown primitive} error
                   1089: @item unknown primitive
                   1090: You have used the name of a simple VM instruction in a superinstruction
                   1091: definition without defining the simple VM instruction first.
                   1092: 
                   1093: @end table
                   1094: 
                   1095: In addition, the C compiler can produce errors due to code produced by
                   1096: Vmgen; e.g., you need to define type cast functions.
                   1097: 
                   1098: @c ********************************************************************
                   1099: @node Using the generated code, Hints, Error messages, Top
1.5       anton    1100: @chapter Using the generated code
1.12      anton    1101: @cindex generated code, usage
                   1102: @cindex Using vmgen-erated code
1.5       anton    1103: 
1.11      anton    1104: The easiest way to create a working VM interpreter with Vmgen is
1.12      anton    1105: probably to start with @file{vmgen-ex}, and modify it for your purposes.
1.13      anton    1106: This chapter explains what the various wrapper and generated files do.
                   1107: It also contains reference-manual style descriptions of the macros,
                   1108: variables etc. used by the generated code, and you can skip that on
                   1109: first reading.
1.5       anton    1110: 
1.10      anton    1111: @menu
                   1112: * VM engine::                   Executing VM code
                   1113: * VM instruction table::        
                   1114: * VM code generation::          Creating VM code (in the front-end)
                   1115: * Peephole optimization::       Creating VM superinstructions
                   1116: * VM disassembler::             for debugging the front end
                   1117: * VM profiler::                 for finding worthwhile superinstructions
                   1118: @end menu
1.6       anton    1119: 
1.10      anton    1120: @c --------------------------------------------------------------------
                   1121: @node VM engine, VM instruction table, Using the generated code, Using the generated code
1.5       anton    1122: @section VM engine
1.12      anton    1123: @cindex VM instruction execution
                   1124: @cindex engine
                   1125: @cindex executing VM code
                   1126: @cindex @file{engine.c}
                   1127: @cindex @file{-vm.i} output file
1.5       anton    1128: 
                   1129: The VM engine is the VM interpreter that executes the VM code.  It is
                   1130: essential for an interpretive system.
                   1131: 
1.6       anton    1132: Vmgen supports two methods of VM instruction dispatch: @emph{threaded
                   1133: code} (fast, but gcc-specific), and @emph{switch dispatch} (slow, but
                   1134: portable across C compilers); you can use conditional compilation
                   1135: (@samp{defined(__GNUC__)}) to choose between these methods, and our
                   1136: example does so.
                   1137: 
                   1138: For both methods, the VM engine is contained in a C-level function.
                   1139: Vmgen generates most of the contents of the function for you
                   1140: (@file{@var{name}-vm.i}), but you have to define this function, and
                   1141: macros and variables used in the engine, and initialize the variables.
                   1142: In our example the engine function also includes
                   1143: @file{@var{name}-labels.i} (@pxref{VM instruction table}).
                   1144: 
1.12      anton    1145: @cindex tracing VM code
1.13      anton    1146: @cindex superinstructions and tracing
1.12      anton    1147: In addition to executing the code, the VM engine can optionally also
                   1148: print out a trace of the executed instructions, their arguments and
                   1149: results.  For superinstructions it prints the trace as if only component
                   1150: instructions were executed; this allows to introduce new
                   1151: superinstructions while keeping the traces comparable to old ones
                   1152: (important for regression tests).
                   1153: 
                   1154: It costs significant performance to check in each instruction whether to
                   1155: print tracing code, so we recommend producing two copies of the engine:
                   1156: one for fast execution, and one for tracing.  See the rules for
                   1157: @file{engine.o} and @file{engine-debug.o} in @file{vmgen-ex/Makefile}
                   1158: for an example.
                   1159: 
1.6       anton    1160: The following macros and variables are used in @file{@var{name}-vm.i}:
1.5       anton    1161: 
                   1162: @table @code
                   1163: 
1.12      anton    1164: @findex LABEL
1.5       anton    1165: @item LABEL(@var{inst_name})
                   1166: This is used just before each VM instruction to provide a jump or
1.11      anton    1167: @code{switch} label (the @samp{:} is provided by Vmgen).  For switch
1.13      anton    1168: dispatch this should expand to @samp{case @var{label}:}; for
                   1169: threaded-code dispatch this should just expand to @samp{@var{label}:}.
1.12      anton    1170: In either case @var{label} is usually the @var{inst_name} with some
                   1171: prefix or suffix to avoid naming conflicts.
1.5       anton    1172: 
1.12      anton    1173: @findex LABEL2
1.9       anton    1174: @item LABEL2(@var{inst_name})
                   1175: This will be used for dynamic superinstructions; at the moment, this
                   1176: should expand to nothing.
                   1177: 
1.12      anton    1178: @findex NAME
1.5       anton    1179: @item NAME(@var{inst_name_string})
                   1180: Called on entering a VM instruction with a string containing the name of
1.13      anton    1181: the VM instruction as parameter.  In normal execution this should be
                   1182: expand to nothing, but for tracing this usually prints the name, and
                   1183: possibly other information (several VM registers in our example).
1.5       anton    1184: 
1.12      anton    1185: @findex DEF_CA
1.5       anton    1186: @item DEF_CA
                   1187: Usually empty.  Called just inside a new scope at the start of a VM
                   1188: instruction.  Can be used to define variables that should be visible
                   1189: during every VM instruction.  If you define this macro as non-empty, you
                   1190: have to provide the finishing @samp{;} in the macro.
                   1191: 
1.12      anton    1192: @findex NEXT_P0
                   1193: @findex NEXT_P1
                   1194: @findex NEXT_P2
1.5       anton    1195: @item NEXT_P0 NEXT_P1 NEXT_P2
                   1196: The three parts of instruction dispatch.  They can be defined in
                   1197: different ways for best performance on various processors (see
                   1198: @file{engine.c} in the example or @file{engine/threaded.h} in Gforth).
1.12      anton    1199: @samp{NEXT_P0} is invoked right at the start of the VM instruction (but
1.5       anton    1200: after @samp{DEF_CA}), @samp{NEXT_P1} right after the user-supplied C
                   1201: code, and @samp{NEXT_P2} at the end.  The actual jump has to be
1.13      anton    1202: performed by @samp{NEXT_P2} (if you would do it earlier, important parts
                   1203: of the VM instruction would not be executed).
1.5       anton    1204: 
                   1205: The simplest variant is if @samp{NEXT_P2} does everything and the other
                   1206: macros do nothing.  Then also related macros like @samp{IP},
                   1207: @samp{SET_IP}, @samp{IP}, @samp{INC_IP} and @samp{IPTOS} are very
                   1208: straightforward to define.  For switch dispatch this code consists just
1.12      anton    1209: of a jump to the dispatch code (@samp{goto next_inst;} in our example);
1.5       anton    1210: for direct threaded code it consists of something like
1.11      anton    1211: @samp{(@{cfa=*ip++; goto *cfa;@})}.
1.5       anton    1212: 
1.12      anton    1213: Pulling code (usually the @samp{cfa=*ip++;}) up into @samp{NEXT_P1}
1.5       anton    1214: usually does not cause problems, but pulling things up into
                   1215: @samp{NEXT_P0} usually requires changing the other macros (and, at least
                   1216: for Gforth on Alpha, it does not buy much, because the compiler often
                   1217: manages to schedule the relevant stuff up by itself).  An even more
                   1218: extreme variant is to pull code up even further, into, e.g., NEXT_P1 of
                   1219: the previous VM instruction (prefetching, useful on PowerPCs).
                   1220: 
1.12      anton    1221: @findex INC_IP
1.5       anton    1222: @item INC_IP(@var{n})
1.8       anton    1223: This increments @code{IP} by @var{n}.
                   1224: 
1.12      anton    1225: @findex SET_IP
1.8       anton    1226: @item SET_IP(@var{target})
                   1227: This sets @code{IP} to @var{target}.
1.5       anton    1228: 
1.12      anton    1229: @cindex type cast macro
                   1230: @findex vm_@var{A}2@var{B}
1.5       anton    1231: @item vm_@var{A}2@var{B}(a,b)
                   1232: Type casting macro that assigns @samp{a} (of type @var{A}) to @samp{b}
                   1233: (of type @var{B}).  This is mainly used for getting stack items into
                   1234: variables and back.  So you need to define macros for every combination
                   1235: of stack basic type (@code{Cell} in our example) and type-prefix types
                   1236: used with that stack (in both directions).  For the type-prefix type,
                   1237: you use the type-prefix (not the C type string) as type name (e.g.,
                   1238: @samp{vm_Cell2i}, not @samp{vm_Cell2Cell}).  In addition, you have to
1.12      anton    1239: define a vm_@var{X}2@var{X} macro for the stack's basic type @var{X}
                   1240: (used in superinstructions).
1.5       anton    1241: 
1.12      anton    1242: @cindex instruction stream, basic type
1.5       anton    1243: The stack basic type for the predefined @samp{inst-stream} is
                   1244: @samp{Cell}.  If you want a stack with the same item size, making its
                   1245: basic type @samp{Cell} usually reduces the number of macros you have to
                   1246: define.
                   1247: 
1.12      anton    1248: @cindex unions in type cast macros
                   1249: @cindex casts in type cast macros
                   1250: @cindex type casting between floats and integers
1.5       anton    1251: Here our examples differ a lot: @file{vmgen-ex} uses casts in these
                   1252: macros, whereas @file{vmgen-ex2} uses union-field selection (or
1.12      anton    1253: assignment to union fields).  Note that casting floats into integers and
                   1254: vice versa changes the bit pattern (and you do not want that).  In this
                   1255: case your options are to use a (temporary) union, or to take the address
                   1256: of the value, cast the pointer, and dereference that (not always
                   1257: possible, and sometimes expensive).
1.5       anton    1258: 
1.12      anton    1259: @findex vm_two@var{A}2@var{B}
                   1260: @findex vm_@var{B}2two@var{A}
1.5       anton    1261: @item vm_two@var{A}2@var{B}(a1,a2,b)
                   1262: @item vm_@var{B}2two@var{A}(b,a1,a2)
1.12      anton    1263: Type casting between two stack items (@code{a1}, @code{a2}) and a
1.5       anton    1264: variable @code{b} of a type that takes two stack items.  This does not
1.12      anton    1265: occur in our small examples, but you can look at Gforth for examples
                   1266: (see @code{vm_twoCell2d} in @file{engine/forth.h}).
1.5       anton    1267: 
1.12      anton    1268: @cindex stack pointer definition
                   1269: @cindex instruction pointer definition
1.5       anton    1270: @item @var{stackpointer}
                   1271: For each stack used, the stackpointer name given in the stack
                   1272: declaration is used.  For a regular stack this must be an l-expression;
                   1273: typically it is a variable declared as a pointer to the stack's basic
                   1274: type.  For @samp{inst-stream}, the name is @samp{IP}, and it can be a
                   1275: plain r-value; typically it is a macro that abstracts away the
1.12      anton    1276: differences between the various implementations of @code{NEXT_P*}.
1.5       anton    1277: 
1.12      anton    1278: @cindex top of stack caching
                   1279: @cindex stack caching
                   1280: @cindex TOS
                   1281: @findex IPTOS
1.5       anton    1282: @item @var{stackpointer}TOS
                   1283: The top-of-stack for the stack pointed to by @var{stackpointer}.  If you
                   1284: are using top-of-stack caching for that stack, this should be defined as
                   1285: variable; if you are not using top-of-stack caching for that stack, this
                   1286: should be a macro expanding to @samp{@var{stackpointer}[0]}.  The stack
                   1287: pointer for the predefined @samp{inst-stream} is called @samp{IP}, so
                   1288: the top-of-stack is called @samp{IPTOS}.
                   1289: 
1.12      anton    1290: @findex IF_@var{stackpointer}TOS
1.5       anton    1291: @item IF_@var{stackpointer}TOS(@var{expr})
                   1292: Macro for executing @var{expr}, if top-of-stack caching is used for the
                   1293: @var{stackpointer} stack.  I.e., this should do @var{expr} if there is
                   1294: top-of-stack caching for @var{stackpointer}; otherwise it should do
                   1295: nothing.
                   1296: 
1.12      anton    1297: @findex SUPER_END
1.8       anton    1298: @item SUPER_END
                   1299: This is used by the VM profiler (@pxref{VM profiler}); it should not do
                   1300: anything in normal operation, and call @code{vm_count_block(IP)} for
                   1301: profiling.
                   1302: 
1.12      anton    1303: @findex SUPER_CONTINUE
1.8       anton    1304: @item SUPER_CONTINUE
1.11      anton    1305: This is just a hint to Vmgen and does nothing at the C level.
1.8       anton    1306: 
1.12      anton    1307: @findex VM_DEBUG
1.5       anton    1308: @item VM_DEBUG
                   1309: If this is defined, the tracing code will be compiled in (slower
                   1310: interpretation, but better debugging).  Our example compiles two
                   1311: versions of the engine, a fast-running one that cannot trace, and one
                   1312: with potential tracing and profiling.
                   1313: 
1.12      anton    1314: @findex vm_debug
1.5       anton    1315: @item vm_debug
                   1316: Needed only if @samp{VM_DEBUG} is defined.  If this variable contains
                   1317: true, the VM instructions produce trace output.  It can be turned on or
                   1318: off at any time.
                   1319: 
1.12      anton    1320: @findex vm_out
1.5       anton    1321: @item vm_out
                   1322: Needed only if @samp{VM_DEBUG} is defined.  Specifies the file on which
                   1323: to print the trace output (type @samp{FILE *}).
                   1324: 
1.12      anton    1325: @findex printarg_@var{type}
1.5       anton    1326: @item printarg_@var{type}(@var{value})
                   1327: Needed only if @samp{VM_DEBUG} is defined.  Macro or function for
                   1328: printing @var{value} in a way appropriate for the @var{type}.  This is
                   1329: used for printing the values of stack items during tracing.  @var{Type}
                   1330: is normally the type prefix specified in a @code{type-prefix} definition
                   1331: (e.g., @samp{printarg_i}); in superinstructions it is currently the
                   1332: basic type of the stack.
                   1333: 
                   1334: @end table
                   1335: 
1.6       anton    1336: 
1.10      anton    1337: @c --------------------------------------------------------------------
                   1338: @node VM instruction table, VM code generation, VM engine, Using the generated code
                   1339: @section VM instruction table
1.12      anton    1340: @cindex instruction table
                   1341: @cindex opcode definition
                   1342: @cindex labels for threaded code
                   1343: @cindex @code{vm_prim}, definition
                   1344: @cindex @file{-labels.i} output file
1.6       anton    1345: 
                   1346: For threaded code we also need to produce a table containing the labels
                   1347: of all VM instructions.  This is needed for VM code generation
                   1348: (@pxref{VM code generation}), and it has to be done in the engine
                   1349: function, because the labels are not visible outside.  It then has to be
                   1350: passed outside the function (and assigned to @samp{vm_prim}), to be used
                   1351: by the VM code generation functions.
                   1352: 
                   1353: This means that the engine function has to be called first to produce
                   1354: the VM instruction table, and later, after generating VM code, it has to
                   1355: be called again to execute the generated VM code (yes, this is ugly).
                   1356: In our example program, these two modes of calling the engine function
                   1357: are differentiated by the value of the parameter ip0 (if it equals 0,
                   1358: then the table is passed out, otherwise the VM code is executed); in our
                   1359: example, we pass the table out by assigning it to @samp{vm_prim} and
                   1360: returning from @samp{engine}.
                   1361: 
1.12      anton    1362: In our example (@file{vmgen-ex/engine.c}), we also build such a table for
                   1363: switch dispatch; this is mainly done for uniformity.
1.6       anton    1364: 
                   1365: For switch dispatch, we also need to define the VM instruction opcodes
                   1366: used as case labels in an @code{enum}.
                   1367: 
                   1368: For both purposes (VM instruction table, and enum), the file
1.11      anton    1369: @file{@var{name}-labels.i} is generated by Vmgen.  You have to define
1.6       anton    1370: the following macro used in this file:
1.5       anton    1371: 
1.12      anton    1372: @table @code
1.5       anton    1373: 
1.12      anton    1374: @findex INST_ADDR
1.5       anton    1375: @item INST_ADDR(@var{inst_name})
                   1376: For switch dispatch, this is just the name of the switch label (the same
1.6       anton    1377: name as used in @samp{LABEL(@var{inst_name})}), for both uses of
                   1378: @file{@var{name}-labels.i}.  For threaded-code dispatch, this is the
                   1379: address of the label defined in @samp{LABEL(@var{inst_name})}); the
1.11      anton    1380: address is taken with @samp{&&} (@pxref{Labels as Values, , Labels as
                   1381: Values, gcc.info, GNU C Manual}).
1.5       anton    1382: 
                   1383: @end table
                   1384: 
                   1385: 
1.10      anton    1386: @c --------------------------------------------------------------------
                   1387: @node VM code generation, Peephole optimization, VM instruction table, Using the generated code
1.6       anton    1388: @section VM code generation
1.12      anton    1389: @cindex VM code generation
                   1390: @cindex code generation, VM
                   1391: @cindex @file{-gen.i} output file
1.6       anton    1392: 
                   1393: Vmgen generates VM code generation functions in @file{@var{name}-gen.i}
                   1394: that the front end can call to generate VM code.  This is essential for
                   1395: an interpretive system.
                   1396: 
1.12      anton    1397: @findex gen_@var{inst}
1.11      anton    1398: For a VM instruction @samp{x ( #a b #c -- d )}, Vmgen generates a
1.6       anton    1399: function with the prototype
                   1400: 
                   1401: @example
                   1402: void gen_x(Inst **ctp, a_type a, c_type c)
                   1403: @end example
                   1404: 
                   1405: The @code{ctp} argument points to a pointer to the next instruction.
                   1406: @code{*ctp} is increased by the generation functions; i.e., you should
                   1407: allocate memory for the code to be generated beforehand, and start with
                   1408: *ctp set at the start of this memory area.  Before running out of
                   1409: memory, allocate a new area, and generate a VM-level jump to the new
1.12      anton    1410: area (this overflow handling is not implemented in our examples).
1.6       anton    1411: 
1.12      anton    1412: @cindex immediate arguments, VM code generation
1.6       anton    1413: The other arguments correspond to the immediate arguments of the VM
                   1414: instruction (with their appropriate types as defined in the
                   1415: @code{type_prefix} declaration.
                   1416: 
                   1417: The following types, variables, and functions are used in
                   1418: @file{@var{name}-gen.i}:
                   1419: 
1.12      anton    1420: @table @code
1.6       anton    1421: 
1.12      anton    1422: @findex Inst
1.6       anton    1423: @item Inst
                   1424: The type of the VM instruction; if you use threaded code, this is
                   1425: @code{void *}; for switch dispatch this is an integer type.
                   1426: 
1.12      anton    1427: @cindex @code{vm_prim}, use
1.6       anton    1428: @item vm_prim
                   1429: The VM instruction table (type: @code{Inst *}, @pxref{VM instruction table}).
                   1430: 
1.12      anton    1431: @findex gen_inst
1.6       anton    1432: @item gen_inst(Inst **ctp, Inst i)
                   1433: This function compiles the instruction @code{i}.  Take a look at it in
                   1434: @file{vmgen-ex/peephole.c}.  It is trivial when you don't want to use
                   1435: superinstructions (just the last two lines of the example function), and
                   1436: slightly more complicated in the example due to its ability to use
                   1437: superinstructions (@pxref{Peephole optimization}).
                   1438: 
1.12      anton    1439: @findex genarg_@var{type_prefix}
1.6       anton    1440: @item genarg_@var{type_prefix}(Inst **ctp, @var{type} @var{type_prefix})
                   1441: This compiles an immediate argument of @var{type} (as defined in a
                   1442: @code{type-prefix} definition).  These functions are trivial to define
                   1443: (see @file{vmgen-ex/support.c}).  You need one of these functions for
                   1444: every type that you use as immediate argument.
                   1445: 
                   1446: @end table
                   1447: 
1.12      anton    1448: @findex BB_BOUNDARY
1.6       anton    1449: In addition to using these functions to generate code, you should call
                   1450: @code{BB_BOUNDARY} at every basic block entry point if you ever want to
                   1451: use superinstructions (or if you want to use the profiling supported by
1.12      anton    1452: Vmgen; but this support is also useful mainly for selecting
                   1453: superinstructions).  If you use @code{BB_BOUNDARY}, you should also
                   1454: define it (take a look at its definition in @file{vmgen-ex/mini.y}).
1.6       anton    1455: 
                   1456: You do not need to call @code{BB_BOUNDARY} after branches, because you
                   1457: will not define superinstructions that contain branches in the middle
                   1458: (and if you did, and it would work, there would be no reason to end the
                   1459: superinstruction at the branch), and because the branches announce
                   1460: themselves to the profiler.
                   1461: 
                   1462: 
1.10      anton    1463: @c --------------------------------------------------------------------
                   1464: @node Peephole optimization, VM disassembler, VM code generation, Using the generated code
1.6       anton    1465: @section Peephole optimization
1.12      anton    1466: @cindex peephole optimization
                   1467: @cindex superinstructions, generating
                   1468: @cindex @file{peephole.c}
                   1469: @cindex @file{-peephole.i} output file
1.6       anton    1470: 
                   1471: You need peephole optimization only if you want to use
                   1472: superinstructions.  But having the code for it does not hurt much if you
                   1473: do not use superinstructions.
                   1474: 
                   1475: A simple greedy peephole optimization algorithm is used for
                   1476: superinstruction selection: every time @code{gen_inst} compiles a VM
1.12      anton    1477: instruction, it checks if it can combine it with the last VM instruction
1.6       anton    1478: (which may also be a superinstruction resulting from a previous peephole
                   1479: optimization); if so, it changes the last instruction to the combined
                   1480: instruction instead of laying down @code{i} at the current @samp{*ctp}.
                   1481: 
                   1482: The code for peephole optimization is in @file{vmgen-ex/peephole.c}.
                   1483: You can use this file almost verbatim.  Vmgen generates
                   1484: @file{@var{file}-peephole.i} which contains data for the peephoile
                   1485: optimizer.
                   1486: 
1.12      anton    1487: @findex init_peeptable
1.6       anton    1488: You have to call @samp{init_peeptable()} after initializing
                   1489: @samp{vm_prim}, and before compiling any VM code to initialize data
                   1490: structures for peephole optimization.  After that, compiling with the VM
                   1491: code generation functions will automatically combine VM instructions
                   1492: into superinstructions.  Since you do not want to combine instructions
                   1493: across VM branch targets (otherwise there will not be a proper VM
                   1494: instruction to branch to), you have to call @code{BB_BOUNDARY}
                   1495: (@pxref{VM code generation}) at branch targets.
                   1496: 
                   1497: 
1.10      anton    1498: @c --------------------------------------------------------------------
                   1499: @node VM disassembler, VM profiler, Peephole optimization, Using the generated code
1.6       anton    1500: @section VM disassembler
1.12      anton    1501: @cindex VM disassembler
                   1502: @cindex disassembler, VM code
                   1503: @cindex @file{disasm.c}
                   1504: @cindex @file{-disasm.i} output file
1.6       anton    1505: 
                   1506: A VM code disassembler is optional for an interpretive system, but
                   1507: highly recommended during its development and maintenance, because it is
                   1508: very useful for detecting bugs in the front end (and for distinguishing
                   1509: them from VM interpreter bugs).
                   1510: 
                   1511: Vmgen supports VM code disassembling by generating
                   1512: @file{@var{file}-disasm.i}.  This code has to be wrapped into a
1.12      anton    1513: function, as is done in @file{vmgen-ex/disasm.c}.  You can use this file
1.6       anton    1514: almost verbatim.  In addition to @samp{vm_@var{A}2@var{B}(a,b)},
                   1515: @samp{vm_out}, @samp{printarg_@var{type}(@var{value})}, which are
                   1516: explained above, the following macros and variables are used in
                   1517: @file{@var{file}-disasm.i} (and you have to define them):
                   1518: 
1.12      anton    1519: @table @code
1.6       anton    1520: 
                   1521: @item ip
                   1522: This variable points to the opcode of the current VM instruction.
                   1523: 
1.12      anton    1524: @cindex @code{IP}, @code{IPTOS} in disassmbler
1.6       anton    1525: @item IP IPTOS
                   1526: @samp{IPTOS} is the first argument of the current VM instruction, and
                   1527: @samp{IP} points to it; this is just as in the engine, but here
                   1528: @samp{ip} points to the opcode of the VM instruction (in contrast to the
                   1529: engine, where @samp{ip} points to the next cell, or even one further).
                   1530: 
1.12      anton    1531: @findex VM_IS_INST
1.6       anton    1532: @item VM_IS_INST(Inst i, int n)
                   1533: Tests if the opcode @samp{i} is the same as the @samp{n}th entry in the
                   1534: VM instruction table.
                   1535: 
                   1536: @end table
                   1537: 
                   1538: 
1.10      anton    1539: @c --------------------------------------------------------------------
                   1540: @node VM profiler,  , VM disassembler, Using the generated code
1.7       anton    1541: @section VM profiler
1.12      anton    1542: @cindex VM profiler
                   1543: @cindex profiling for selecting superinstructions
                   1544: @cindex superinstructions and profiling
                   1545: @cindex @file{profile.c}
                   1546: @cindex @file{-profile.i} output file
1.7       anton    1547: 
                   1548: The VM profiler is designed for getting execution and occurence counts
                   1549: for VM instruction sequences, and these counts can then be used for
                   1550: selecting sequences as superinstructions.  The VM profiler is probably
1.8       anton    1551: not useful as profiling tool for the interpretive system.  I.e., the VM
1.7       anton    1552: profiler is useful for the developers, but not the users of the
1.8       anton    1553: interpretive system.
1.7       anton    1554: 
1.8       anton    1555: The output of the profiler is: for each basic block (executed at least
                   1556: once), it produces the dynamic execution count of that basic block and
                   1557: all its subsequences; e.g.,
1.7       anton    1558: 
1.8       anton    1559: @example
                   1560:        9227465  lit storelocal 
                   1561:        9227465  storelocal branch 
                   1562:        9227465  lit storelocal branch 
                   1563: @end example
1.7       anton    1564: 
1.8       anton    1565: I.e., a basic block consisting of @samp{lit storelocal branch} is
                   1566: executed 9227465 times.
1.6       anton    1567: 
1.12      anton    1568: @cindex @file{stat.awk}
                   1569: @cindex @file{seq2rule.awk}
1.8       anton    1570: This output can be combined in various ways.  E.g.,
1.12      anton    1571: @file{vmgen-ex/stat.awk} adds up the occurences of a given sequence wrt
1.8       anton    1572: dynamic execution, static occurence, and per-program occurence.  E.g.,
1.3       anton    1573: 
1.8       anton    1574: @example
                   1575:       2      16        36910041 loadlocal lit 
                   1576: @end example
1.2       anton    1577: 
1.12      anton    1578: @noindent
1.8       anton    1579: indicates that the sequence @samp{loadlocal lit} occurs in 2 programs,
                   1580: in 16 places, and has been executed 36910041 times.  Now you can select
                   1581: superinstructions in any way you like (note that compile time and space
                   1582: typically limit the number of superinstructions to 100--1000).  After
                   1583: you have done that, @file{vmgen/seq2rule.awk} turns lines of the form
1.11      anton    1584: above into rules for inclusion in a Vmgen input file.  Note that this
1.8       anton    1585: script does not ensure that all prefixes are defined, so you have to do
                   1586: that in other ways.  So, an overall script for turning profiles into
                   1587: superinstructions can look like this:
1.2       anton    1588: 
1.8       anton    1589: @example
                   1590: awk -f stat.awk fib.prof test.prof|
                   1591: awk '$3>=10000'|                #select sequences
                   1592: fgrep -v -f peephole-blacklist| #eliminate wrong instructions
                   1593: awk -f seq2rule.awk|            #turn into superinstructions
                   1594: sort -k 3 >mini-super.vmg       #sort sequences
                   1595: @end example
1.2       anton    1596: 
1.8       anton    1597: Here the dynamic count is used for selecting sequences (preliminary
                   1598: results indicate that the static count gives better results, though);
1.12      anton    1599: the third line eliminates sequences containing instructions that must not
1.8       anton    1600: occur in a superinstruction, because they access a stack directly.  The
                   1601: dynamic count selection ensures that all subsequences (including
                   1602: prefixes) of longer sequences occur (because subsequences have at least
                   1603: the same count as the longer sequences); the sort in the last line
                   1604: ensures that longer superinstructions occur after their prefixes.
                   1605: 
1.12      anton    1606: But before using this, you have to have the profiler.  Vmgen supports its
1.8       anton    1607: creation by generating @file{@var{file}-profile.i}; you also need the
                   1608: wrapper file @file{vmgen-ex/profile.c} that you can use almost verbatim.
                   1609: 
1.12      anton    1610: @cindex @code{SUPER_END} in profiling
                   1611: @cindex @code{BB_BOUNDARY} in profiling
1.8       anton    1612: The profiler works by recording the targets of all VM control flow
                   1613: changes (through @code{SUPER_END} during execution, and through
                   1614: @code{BB_BOUNDARY} in the front end), and counting (through
                   1615: @code{SUPER_END}) how often they were targeted.  After the program run,
                   1616: the numbers are corrected such that each VM basic block has the correct
1.12      anton    1617: count (entering a block without executing a branch does not increase the
                   1618: count, and the correction fixes that), then the subsequences of all
                   1619: basic blocks are printed.  To get all this, you just have to define
                   1620: @code{SUPER_END} (and @code{BB_BOUNDARY}) appropriately, and call
                   1621: @code{vm_print_profile(FILE *file)} when you want to output the profile
                   1622: on @code{file}.
1.8       anton    1623: 
1.12      anton    1624: @cindex @code{VM_IS_INST} in profiling
                   1625: The @file{@var{file}-profile.i} is similar to the disassembler file, and
1.8       anton    1626: it uses variables and functions defined in @file{vmgen-ex/profile.c},
                   1627: plus @code{VM_IS_INST} already defined for the VM disassembler
                   1628: (@pxref{VM disassembler}).
                   1629: 
1.13      anton    1630: @c **********************************************************
                   1631: @node Hints, The future, Using the generated code, Top
                   1632: @chapter Hints
                   1633: @cindex hints
                   1634: 
                   1635: @menu
                   1636: * Floating point::              and stacks
                   1637: @end menu
                   1638: 
                   1639: @c --------------------------------------------------------------------
                   1640: @node Floating point,  , Hints, Hints
                   1641: @section Floating point
                   1642: 
                   1643: How should you deal with floating point values?  Should you use the same
                   1644: stack as for integers/pointers, or a different one?  This section
                   1645: discusses this issue with a view on execution speed.
                   1646: 
                   1647: The simpler approach is to use a separate floating-point stack.  This
                   1648: allows you to choose FP value size without considering the size of the
                   1649: integers/pointers, and you avoid a number of performance problems.  The
                   1650: main downside is that this needs an FP stack pointer (and that may not
                   1651: fit in the register file on the 386 arhitecture, costing some
                   1652: performance, but comparatively little if you take the other option into
                   1653: account).  If you use a separate FP stack (with stack pointer @code{fp}),
                   1654: using an fpTOS is helpful on most machines, but some spill the fpTOS
                   1655: register into memory, and fpTOS should not be used there.
                   1656: 
                   1657: The other approach is to share one stack (pointed to by, say, @code{sp})
                   1658: between integer/pointer and floating-point values.  This is ok if you do
                   1659: not use @code{spTOS}.  If you do use @code{spTOS}, the compiler has to
                   1660: decide whether to put that variable into an integer or a floating point
                   1661: register, and the other type of operation becomes quite expensive on
                   1662: most machines (because moving values between integer and FP registers is
                   1663: quite expensive).  If a value of one type has to be synthesized out of
                   1664: two values of the other type (@code{double} types), things are even more
                   1665: interesting.
                   1666: 
                   1667: One way around this problem would be to not use the @code{spTOS}
                   1668: supported by Vmgen, but to use explicit top-of-stack variables (one for
                   1669: integers, one for FP values), and having a kind of accumulator+stack
                   1670: architecture (e.g., Ocaml bytecode uses this approach); however, this is
                   1671: a major change, and it's ramifications are not completely clear.
1.10      anton    1672: 
                   1673: @c **********************************************************
1.13      anton    1674: @node The future, Changes, Hints, Top
                   1675: @chapter The future
                   1676: @cindex future ideas
                   1677: 
                   1678: We have a number of ideas for future versions of Gforth.  However, there
                   1679: are so many possible things to do that we would like some feedback from
                   1680: you.  What are you doing with Vmgen, what features are you missing, and
                   1681: why?
                   1682: 
                   1683: One idea we are thinking about is to generate just one @file{.c} file
                   1684: instead of letting you copy and adapt all the wrapper files (you would
                   1685: still have to define stuff like the type-specific macros, and stack
                   1686: pointers etc. somewhere).  The advantage would be that, if we change the
                   1687: wrapper files between versions, you would not need to integrate your
                   1688: changes and our changes to them; Vmgen would also be easier to use for
                   1689: beginners.  The main disadvantage of that is that it would reduce the
                   1690: flexibility of Vmgen a little (well, those who like flexibility could
                   1691: still patch the resulting @file{.c} file, like they are now doing for
                   1692: the wrapper files).  In any case, if you are doing things to the wrapper
                   1693: files that would cause problems in a generated-@file{.c}-file approach,
                   1694: please let us know.
                   1695: 
                   1696: @c **********************************************************
                   1697: @node Changes, Contact, The future, Top
1.8       anton    1698: @chapter Changes
1.12      anton    1699: @cindex Changes from old versions
1.8       anton    1700: 
1.11      anton    1701: Users of the gforth-0.5.9-20010501 version of Vmgen need to change
1.8       anton    1702: several things in their source code to use the current version.  I
                   1703: recommend keeping the gforth-0.5.9-20010501 version until you have
                   1704: completed the change (note that you can have several versions of Gforth
                   1705: installed at the same time).  I hope to avoid such incompatible changes
                   1706: in the future.
1.2       anton    1707: 
1.8       anton    1708: The required changes are:
                   1709: 
                   1710: @table @code
1.13      anton    1711: 
                   1712: @cindex @code{TAIL;}, changes
                   1713: @item TAIL;
                   1714: has been renamed into @code{INST_TAIL;} (less chance of an accidental
                   1715: match).
1.2       anton    1716: 
1.12      anton    1717: @cindex @code{vm_@var{A}2@var{B}}, changes
1.8       anton    1718: @item vm_@var{A}2@var{B}
                   1719: now takes two arguments.
                   1720: 
1.12      anton    1721: @cindex @code{vm_two@var{A}2@var{B}}, changes
1.8       anton    1722: @item vm_two@var{A}2@var{B}(b,a1,a2);
                   1723: changed to vm_two@var{A}2@var{B}(a1,a2,b) (note the absence of the @samp{;}).
                   1724: 
                   1725: @end table
1.2       anton    1726: 
1.8       anton    1727: Also some new macros have to be defined, e.g., @code{INST_ADDR}, and
                   1728: @code{LABEL}; some macros have to be defined in new contexts, e.g.,
                   1729: @code{VM_IS_INST} is now also needed in the disassembler.
1.4       anton    1730: 
1.12      anton    1731: @c *********************************************************
1.10      anton    1732: @node Contact, Copying This Manual, Changes, Top
1.8       anton    1733: @chapter Contact
1.4       anton    1734: 
1.12      anton    1735: @c ***********************************************************
1.10      anton    1736: @node Copying This Manual, Index, Contact, Top
                   1737: @appendix Copying This Manual
                   1738: 
                   1739: @menu
                   1740: * GNU Free Documentation License::  License for copying this manual.
                   1741: @end menu
                   1742: 
                   1743: @include fdl.texi
                   1744: 
                   1745: 
                   1746: @node Index,  , Copying This Manual, Top
                   1747: @unnumbered Index
                   1748: 
                   1749: @printindex cp
                   1750: 
                   1751: @bye

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>