[gforth] / gforth / doc / vmgen.texi  

gforth: gforth/doc/vmgen.texi

Diff for /gforth/doc/vmgen.texi between version 1.9 and 1.10

version 1.9, Fri Aug 9 09:42:35 2002 UTC version 1.10, Tue Aug 13 19:33:38 2002 UTC
Line 1 
Line 1 
   \input texinfo    @c -*-texinfo-*-
   @comment %**start of header
   @setfilename vmgen.info
 @include version.texi  @include version.texi
   @settitle Vmgen (Gforth @value{VERSION})
   @c @syncodeindex pg cp
   @comment %**end of header
   @copying
   This manual is for Vmgen
   (version @value{VERSION}, @value{UPDATED}),
   the virtual machine interpreter generator
   
   Copyright @copyright{} 2002 Free Software Foundation, Inc.
   
   @quotation
   Permission is granted to copy, distribute and/or modify this document
   under the terms of the GNU Free Documentation License, Version 1.1 or
   any later version published by the Free Software Foundation; with no
   Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
   and with the Back-Cover Texts as in (a) below.  A copy of the
   license is included in the section entitled ``GNU Free Documentation
   License.''
   
   (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
   this GNU Manual, like GNU software.  Copies published by the Free
   Software Foundation raise funds for GNU development.''
   @end quotation
   @end copying
   
   @dircategory GNU programming tools
   @direntry
   * vmgen: (vmgen).               Interpreter generator
   @end direntry
   
   @titlepage
   @title Vmgen
   @subtitle for Gforth version @value{VERSION}, @value{UPDATED}
   @author M. Anton Ertl (@email{anton@mips.complang.tuwien.ac.at})
   @page
   @vskip 0pt plus 1filll
   @insertcopying
   @end titlepage
   
   @contents
   
   @ifnottex
   @node Top, Introduction, (dir), (dir)
   @top Vmgen
   
   @insertcopying
   @end ifnottex
   
   @menu
   * Introduction::                What can Vmgen do for you?
   * Why interpreters?::           Advantages and disadvantages
   * Concepts::                    VM interpreter background
   * Invoking vmgen::
   * Example::
   * Input File Format::
   * Using the generated code::
   * Changes::                     from earlier versions
   * Contact::                     Bug reporting etc.
   * Copying This Manual::         Manual License
   * Index::
   
   @detailmenu
    --- The Detailed Node Listing ---
   
   Concepts
   
   * Front end and VM interpreter::  Modularizing an interpretive system
   * Data handling::               Stacks, registers, immediate arguments
   * Dispatch::                    From one VM instruction to the next
   
   Example
   
   * Example overview::
   * Using profiling to create superinstructions::
   
   Input File Format
   
   * Input File Grammar::
   * Simple instructions::
   * Superinstructions::
   
   Simple instructions
   
   * C Code Macros::               Macros recognized by Vmgen
   * C Code restrictions::         Vmgen makes assumptions about C code
   
   Using the generated code
   
   * VM engine::                   Executing VM code
   * VM instruction table::
   * VM code generation::          Creating VM code (in the front-end)
   * Peephole optimization::       Creating VM superinstructions
   * VM disassembler::             for debugging the front end
   * VM profiler::                 for finding worthwhile superinstructions
   
   Copying This Manual
   
   * GNU Free Documentation License::  License for copying this manual.
   
   @end detailmenu
   @end menu
   
 @c @ifnottex  @c @ifnottex
 This file documents vmgen (Gforth @value{VERSION}).  This file documents Vmgen (Gforth @value{VERSION}).
   
   @c ************************************************************
   @node Introduction, Why interpreters?, Top, Top
 @chapter Introduction  @chapter Introduction
   
 Vmgen is a tool for writing efficient interpreters.  It takes a simple  Vmgen is a tool for writing efficient interpreters.  It takes a simple
Line 101 
Line 207 
 list above is not exhaustive.  list above is not exhaustive.
   
 @c *********************************************************************  @c *********************************************************************
   @node Why interpreters?, Concepts, Introduction, Top
 @chapter Why interpreters?  @chapter Why interpreters?
   
 Interpreters are a popular language implementation technique because  Interpreters are a popular language implementation technique because
Line 129 
Line 236 
 techniques for building efficient interpreters.  techniques for building efficient interpreters.
   
 @c ********************************************************************  @c ********************************************************************
   @node Concepts, Invoking vmgen, Why interpreters?, Top
 @chapter Concepts  @chapter Concepts
   
   @menu
   * Front end and VM interpreter::  Modularizing an interpretive system
   * Data handling::               Stacks, registers, immediate arguments
   * Dispatch::                    From one VM instruction to the next
   @end menu
   
 @c --------------------------------------------------------------------  @c --------------------------------------------------------------------
 @section Front-end and virtual machine interpreter  @node Front end and VM interpreter, Data handling, Concepts, Concepts
   @section Front end and VM interpreter
   
 @cindex front-end  @cindex front-end
 Interpretive systems are typically divided into a @emph{front end} that  Interpretive systems are typically divided into a @emph{front end} that
Line 164 
Line 279 
 information in the instruction descriptions can be helpful, and we are  information in the instruction descriptions can be helpful, and we are
 open for feature requests and suggestions.  open for feature requests and suggestions.
   
   @c --------------------------------------------------------------------
   @node Data handling, Dispatch, Front end and VM interpreter, Concepts
 @section Data handling  @section Data handling
   
 @cindex stack machine  @cindex stack machine
Line 202 
Line 319 
 @c reference counting might be possible by including counting code in  @c reference counting might be possible by including counting code in
 @c the conversion macros.  @c the conversion macros.
   
   @c --------------------------------------------------------------------
   @node Dispatch,  , Data handling, Concepts
 @section Dispatch  @section Dispatch
   
 Understanding this section is probably not necessary for using vmgen,  Understanding this section is probably not necessary for using vmgen,
Line 235 
Line 354 
 @end table  @end table
   
 @c *************************************************************  @c *************************************************************
   @node Invoking vmgen, Example, Concepts, Top
 @chapter Invoking vmgen  @chapter Invoking vmgen
   
 The usual way to invoke vmgen is as follows:  The usual way to invoke vmgen is as follows:
Line 271 
Line 391 
 @c env vars GFORTHDIR GFORTHDATADIR  @c env vars GFORTHDIR GFORTHDATADIR
   
 @c ****************************************************************  @c ****************************************************************
   @node Example, Input File Format, Invoking vmgen, Top
 @chapter Example  @chapter Example
   
   @menu
   * Example overview::
   * Using profiling to create superinstructions::
   @end menu
   
   @c --------------------------------------------------------------------
   @node Example overview, Using profiling to create superinstructions, Example, Example
 @section Example overview  @section Example overview
   
 There are two versions of the same example for using vmgen:  There are two versions of the same example for using vmgen:
Line 342 
Line 470 
   
 To learn about the options, type @samp{./mini -h}.  To learn about the options, type @samp{./mini -h}.
   
   @c --------------------------------------------------------------------
   @node Using profiling to create superinstructions,  , Example overview, Example
 @section Using profiling to create superinstructions  @section Using profiling to create superinstructions
   
 I have not added rules for this in the @file{Makefile} (there are many  I have not added rules for this in the @file{Makefile} (there are many
Line 392 
Line 522 
 Now you can create a version of mini with superinstructions by just  Now you can create a version of mini with superinstructions by just
 saying @samp{make}  saying @samp{make}
   
   
 @c ***************************************************************  @c ***************************************************************
   @node Input File Format, Using the generated code, Example, Top
 @chapter Input File Format  @chapter Input File Format
   
 Vmgen takes as input a file containing specifications of virtual machine  Vmgen takes as input a file containing specifications of virtual machine
Line 400 
Line 532 
   
 Most examples are taken from the example in @file{vmgen-ex}.  Most examples are taken from the example in @file{vmgen-ex}.
   
   @menu
   * Input File Grammar::
   * Simple instructions::
   * Superinstructions::
   @end menu
   
   @c --------------------------------------------------------------------
   @node Input File Grammar, Simple instructions, Input File Format, Input File Format
 @section Input File Grammar  @section Input File Grammar
   
 The grammar is in EBNF format, with @code{@var{a}|@var{b}} meaning  The grammar is in EBNF format, with @code{@var{a}|@var{b}} meaning
Line 440 
Line 580 
 these extensions are only useful for building Gforth.  You can find a  these extensions are only useful for building Gforth.  You can find a
 description of the format used for Gforth in @file{prim}.  description of the format used for Gforth in @file{prim}.
   
 @subsection  @subsection Eval escapes
 @c woanders?  @c woanders?
 The text in @code{eval-escape} is Forth code that is evaluated when  The text in @code{eval-escape} is Forth code that is evaluated when
 vmgen reads the line.  If you do not know (and do not want to learn)  vmgen reads the line.  If you do not know (and do not want to learn)
Line 472 
Line 612 
 @end example  @end example
   
   
   @c --------------------------------------------------------------------
   @node Simple instructions, Superinstructions, Input File Grammar, Input File Format
 @section Simple instructions  @section Simple instructions
   
 We will use the following simple VM instruction description as example:  We will use the following simple VM instruction description as example:
Line 548 
Line 690 
 If there are multiple instruction stream arguments, the leftmost is the  If there are multiple instruction stream arguments, the leftmost is the
 first one (just as the intuition suggests).  first one (just as the intuition suggests).
   
 @subsubsection C Code Macros  @menu
   * C Code Macros::               Macros recognized by Vmgen
   * C Code restrictions::         Vmgen makes assumptions about C code
   @end menu
   
   @c --------------------------------------------------------------------
   @node C Code Macros, C Code restrictions, Simple instructions, Simple instructions
   @subsection C Code Macros
   
 Vmgen recognizes the following strings in the C code part of simple  Vmgen recognizes the following strings in the C code part of simple
 instructions:  instructions:
Line 605 
Line 754 
 a C preprocessor macro.  a C preprocessor macro.
   
   
 @subsubsection C Code restrictions  @c --------------------------------------------------------------------
   @node C Code restrictions,  , C Code Macros, Simple instructions
   @subsection C Code restrictions
   
 Vmgen generates code and performs some optimizations under the  Vmgen generates code and performs some optimizations under the
 assumption that the user-supplied C code does not access the stack  assumption that the user-supplied C code does not access the stack
Line 656 
Line 807 
 contents.  contents.
   
   
   @c --------------------------------------------------------------------
   @node Superinstructions,  , Simple instructions, Input File Format
 @section Superinstructions  @section Superinstructions
   
 Note: don't invest too much work in (static) superinstructions; a future  Note: don't invest too much work in (static) superinstructions; a future
Line 710 
Line 863 
 restrictions, they just result in bugs in your interpreter.  restrictions, they just result in bugs in your interpreter.
   
 @c ********************************************************************  @c ********************************************************************
   @node Using the generated code, Changes, Input File Format, Top
 @chapter Using the generated code  @chapter Using the generated code
   
 The easiest way to create a working VM interpreter with vmgen is  The easiest way to create a working VM interpreter with vmgen is
 probably to start with one of the examples, and modify it for your  probably to start with one of the examples, and modify it for your
 purposes.  This chapter is just the reference manual for the macros  purposes.  This chapter is just the reference manual for the macros
 etc. used by the generated code, and the other context expected by the  etc. used by the generated code, the other context expected by the
 generated code, and what you can do with the various generated files.  generated code, and what you can do with the various generated files.
   
   @menu
   * VM engine::                   Executing VM code
   * VM instruction table::
   * VM code generation::          Creating VM code (in the front-end)
   * Peephole optimization::       Creating VM superinstructions
   * VM disassembler::             for debugging the front end
   * VM profiler::                 for finding worthwhile superinstructions
   @end menu
   
   @c --------------------------------------------------------------------
   @node VM engine, VM instruction table, Using the generated code, Using the generated code
 @section VM engine  @section VM engine
   
 The VM engine is the VM interpreter that executes the VM code.  It is  The VM engine is the VM interpreter that executes the VM code.  It is
Line 878 
Line 1042 
 @end table  @end table
   
   
 @section{VM instruction table}  @c --------------------------------------------------------------------
   @node VM instruction table, VM code generation, VM engine, Using the generated code
   @section VM instruction table
   
 For threaded code we also need to produce a table containing the labels  For threaded code we also need to produce a table containing the labels
 of all VM instructions.  This is needed for VM code generation  of all VM instructions.  This is needed for VM code generation
Line 918 
Line 1084 
 @end table  @end table
   
   
   @c --------------------------------------------------------------------
   @node VM code generation, Peephole optimization, VM instruction table, Using the generated code
 @section VM code generation  @section VM code generation
   
 Vmgen generates VM code generation functions in @file{@var{name}-gen.i}  Vmgen generates VM code generation functions in @file{@var{name}-gen.i}
Line 983 
Line 1151 
 themselves to the profiler.  themselves to the profiler.
   
   
   @c --------------------------------------------------------------------
   @node Peephole optimization, VM disassembler, VM code generation, Using the generated code
 @section Peephole optimization  @section Peephole optimization
   
 You need peephole optimization only if you want to use  You need peephole optimization only if you want to use
Line 1011 
Line 1181 
 (@pxref{VM code generation}) at branch targets.  (@pxref{VM code generation}) at branch targets.
   
   
   @c --------------------------------------------------------------------
   @node VM disassembler, VM profiler, Peephole optimization, Using the generated code
 @section VM disassembler  @section VM disassembler
   
 A VM code disassembler is optional for an interpretive system, but  A VM code disassembler is optional for an interpretive system, but
Line 1044 
Line 1216 
 @end table  @end table
   
   
   @c --------------------------------------------------------------------
   @node VM profiler,  , VM disassembler, Using the generated code
 @section VM profiler  @section VM profiler
   
 The VM profiler is designed for getting execution and occurence counts  The VM profiler is designed for getting execution and occurence counts
Line 1121 
Line 1295 
 plus @code{VM_IS_INST} already defined for the VM disassembler  plus @code{VM_IS_INST} already defined for the VM disassembler
 (@pxref{VM disassembler}).  (@pxref{VM disassembler}).
   
   
   @c **********************************************************
   @node Changes, Contact, Using the generated code, Top
 @chapter Changes  @chapter Changes
   
 Users of the gforth-0.5.9-20010501 version of vmgen need to change  Users of the gforth-0.5.9-20010501 version of vmgen need to change
Line 1146 
Line 1323 
 @code{LABEL}; some macros have to be defined in new contexts, e.g.,  @code{LABEL}; some macros have to be defined in new contexts, e.g.,
 @code{VM_IS_INST} is now also needed in the disassembler.  @code{VM_IS_INST} is now also needed in the disassembler.
   
   @node Contact, Copying This Manual, Changes, Top
 @chapter Contact  @chapter Contact
   
   @node Copying This Manual, Index, Contact, Top
   @appendix Copying This Manual
   
   @menu
   * GNU Free Documentation License::  License for copying this manual.
   @end menu
   
   @include fdl.texi
   
   
   @node Index,  , Copying This Manual, Top
   @unnumbered Index
   
   @printindex cp
   
   @bye

Generate output suitable for use with a patch program
Legend:
Removed from v.1.9  
changed lines
  Added in v.1.10
CVS Admin

Powered by ViewCVS 1.0-dev 		(Powered by ViewCVS)

ViewCVS and CVS Help