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