--- gforth/doc/vmgen.texi 2002/08/20 07:59:01 1.14 +++ gforth/doc/vmgen.texi 2003/02/23 21:17:00 1.21 @@ -85,8 +85,13 @@ Input File Format * Input File Grammar:: * Simple instructions:: * Superinstructions:: +* Store Optimization:: * Register Machines:: How to define register VM instructions +Input File Grammar + +* Eval escapes:: what follows \E + Simple instructions * C Code Macros:: Macros recognized by Vmgen @@ -601,6 +606,7 @@ Most examples are taken from the example * Input File Grammar:: * Simple instructions:: * Superinstructions:: +* Store Optimization:: * Register Machines:: How to define register VM instructions @end menu @@ -615,45 +621,83 @@ The grammar is in EBNF format, with @cod of @var{c} and @code{[@var{d}]} meaning 0 or 1 repetitions of @var{d}. @cindex free-format, not +@cindex newlines, significance in syntax Vmgen input is not free-format, so you have to take care where you put -spaces and especially newlines; it's not as bad as makefiles, though: -any sequence of spaces and tabs is equivalent to a single space. +newlines (and, in a few cases, white space). @example -description: @{instruction|comment|eval-escape@} +description: @{instruction|comment|eval-escape|c-escape@} instruction: simple-inst|superinst -simple-inst: ident ' (' stack-effect ' )' newline c-code newline newline +simple-inst: ident '(' stack-effect ')' newline c-code newline newline -stack-effect: @{ident@} ' --' @{ident@} +stack-effect: @{ident@} '--' @{ident@} -super-inst: ident ' =' ident @{ident@} +super-inst: ident '=' ident @{ident@} comment: '\ ' text newline eval-escape: '\E ' text newline + +c-escape: '\C ' text newline @end example @c \+ \- \g \f \c Note that the @code{\}s in this grammar are meant literally, not as C-style encodings for non-printable characters. -The C code in @code{simple-inst} must not contain empty lines (because -Vmgen would mistake that as the end of the simple-inst. The text in -@code{comment} and @code{eval-escape} must not contain a newline. -@code{Ident} must conform to the usual conventions of C identifiers -(otherwise the C compiler would choke on the Vmgen output). +There are two ways to delimit the C code in @code{simple-inst}: + +@itemize @bullet + +@item +If you start it with a @samp{@{} at the start of a line (i.e., not even +white space before it), you have to end it with a @samp{@}} at the start +of a line (followed by a newline). In this case you may have empty +lines within the C code (typically used between variable definitions and +statements). + +@item +You do not start it with @samp{@{}. Then the C code ends at the first +empty line, so you cannot have empty lines within this code. + +@end itemize + +The text in @code{comment}, @code{eval-escape} and @code{c-escape} must +not contain a newline. @code{Ident} must conform to the usual +conventions of C identifiers (otherwise the C compiler would choke on +the Vmgen output), except that idents in @code{stack-effect} may have a +stack prefix (for stack prefix syntax, @pxref{Eval escapes}). + +@cindex C escape +@cindex @code{\C} +@cindex conditional compilation of Vmgen output +The @code{c-escape} passes the text through to each output file (without +the @samp{\C}). This is useful mainly for conditional compilation +(i.e., you write @samp{\C #if ...} etc.). + +@cindex sync lines +@cindex @code{#line} +In addition to the syntax given in the grammer, Vmgen also processes +sync lines (lines starting with @samp{#line}), as produced by @samp{m4 +-s} (@pxref{Invoking m4, , Invoking m4, m4.info, GNU m4}) and similar +tools. This allows associating C compiler error messages with the +original source of the C code. Vmgen understands a few extensions beyond the grammar given here, but these extensions are only useful for building Gforth. You can find a description of the format used for Gforth in @file{prim}. +@menu +* Eval escapes:: what follows \E +@end menu + +@node Eval escapes, , Input File Grammar, Input File Grammar @subsection Eval escapes @cindex escape to Forth @cindex eval escape - - +@cindex @code{\E} @c woanders? The text in @code{eval-escape} is Forth code that is evaluated when @@ -665,12 +709,13 @@ text according to the following grammar; Forth you need for using Vmgen: @example -text: stack-decl|type-prefix-decl|stack-prefix-decl +text: stack-decl|type-prefix-decl|stack-prefix-decl|set-flag stack-decl: 'stack ' ident ident ident type-prefix-decl: 's" ' string '" ' ('single'|'double') ident 'type-prefix' ident stack-prefix-decl: ident 'stack-prefix' string +set-flag: 'store-optimization' ('on'|'off') @end example Note that the syntax of this code is not checked thoroughly (there are @@ -690,13 +735,15 @@ are: @findex single @findex double @findex stack-prefix +@findex store-optimization @example -stack ( "name" "pointer" "type" -- ) - ( name execution: -- stack ) -type-prefix ( addr u item-size stack "prefix" -- ) -single ( -- item-size ) -double ( -- item-size ) -stack-prefix ( stack "prefix" -- ) +stack ( "name" "pointer" "type" -- ) + ( name execution: -- stack ) +type-prefix ( addr u item-size stack "prefix" -- ) +single ( -- item-size ) +double ( -- item-size ) +stack-prefix ( stack "prefix" -- ) +store-optimization ( -- addr ) @end example An @var{item-size} takes three cells on the stack. @@ -930,7 +977,7 @@ contents. @c -------------------------------------------------------------------- -@node Superinstructions, Register Machines, Simple instructions, Input File Format +@node Superinstructions, Store Optimization, Simple instructions, Input File Format @section Superinstructions @cindex superinstructions, defining @cindex defining superinstructions @@ -988,7 +1035,65 @@ does not check these restrictions, they interpreter. @c ------------------------------------------------------------------- -@node Register Machines, , Superinstructions, Input File Format +@node Store Optimization, Register Machines, Superinstructions, Input File Format +@section Store Optimization +@cindex store optimization +@cindex optimization, stack stores +@cindex stack stores, optimization +@cindex eliminating stack stores + +This minor optimization (0.6\%--0.8\% reduction in executed instructions +for Gforth) puts additional requirements on the instruction descriptions +and is therefore disabled by default. + +What does it do? Consider an instruction like + +@example +dup ( n -- n n ) +@end example + +For simplicity, also assume that we are not caching the top-of-stack in +a register. Now, the C code for dup first loads @code{n} from the +stack, and then stores it twice to the stack, one time to the address +where it came from; that time is unnecessary, but gcc does not optimize +it away, so vmgen can do it instead (if you turn on the store +optimization). + +Vmgen uses the stack item's name to determine if the stack item contains +the same value as it did at the start. Therefore, if you use the store +optimization, you have to ensure that stack items that have the same +name on input and output also have the same value, and are not changed +in the C code you supply. I.e., the following code could fail if you +turn on the store optimization: + +@example +add1 ( n -- n ) +n++; +@end example + +Instead, you have to use different names, i.e.: + +@example +add1 ( n1 -- n1 ) +n2=n1+1; +@end example + +To turn on the store optimization, write + +@example +\E store-optimization on +@end example + +at the start of the file. You can turn this optimization on or off +between any two VM instruction descriptions. For turning it off again, +you can use + +@example +\E store-optimization off +@end example + +@c ------------------------------------------------------------------- +@node Register Machines, , Store Optimization, Input File Format @section Register Machines @cindex Register VM @cindex Superinstructions for register VMs @@ -1058,7 +1163,7 @@ You have used an instruction-stream pref side). @cindex @code{prefix for this combination must be defined earlier} error -@item the prefix for this combination must be defined earlier +@item the prefix for this superinstruction must be defined earlier You have defined a superinstruction (e.g. @code{abc = a b c}) without defining its direct prefix (e.g., @code{ab = a b}), @xref{Superinstructions}. @@ -1068,16 +1173,22 @@ defining its direct prefix (e.g., @code{ If you are using a preprocessor (e.g., @command{m4}) to generate Vmgen input code, you may want to create @code{#line} directives (aka sync lines). This error indicates that such a line is not in th syntax -expected by Vmgen (this should not happen). +expected by Vmgen (this should not happen; please report the offending +line in a bug report). @cindex @code{syntax error, wrong char} error @cindex syntax error, wrong char -A syntax error. Note that Vmgen is sometimes anal retentive about white -space, especially about newlines. +A syntax error. If you do not see right away where the error is, it may +be helpful to check the following: Did you put an empty line in a VM +instruction where the C code is not delimited by braces (then the empty +line ends the VM instruction)? If you used brace-delimited C code, did +you put the delimiting braces (and only those) at the start of the line, +without preceding white space? Did you forget a delimiting brace? @cindex @code{too many stacks} error @item too many stacks -Vmgen currently supports 4 stacks; if you need more, let us know. +Vmgen currently supports 3 stacks (plus the instruction stream); if you +need more, let us know. @cindex @code{unknown prefix} error @item unknown prefix @@ -1675,7 +1786,7 @@ a major change, and it's ramifications a @chapter The future @cindex future ideas -We have a number of ideas for future versions of Gforth. However, there +We have a number of ideas for future versions of Vmgen. However, there are so many possible things to do that we would like some feedback from you. What are you doing with Vmgen, what features are you missing, and why? @@ -1698,6 +1809,23 @@ please let us know. @chapter Changes @cindex Changes from old versions +User-visible changes between 0.5.9-20020822 and 0.5.9-20020901: + +The store optimization is now disabled by default, but can be enabled by +the user (@pxref{Store Optimization}). Documentation for this +optimization is also new. + +User-visible changes between 0.5.9-20010501 and 0.5.9-20020822: + +There is now a manual (in info, HTML, Postscript, or plain text format). + +There is the vmgen-ex2 variant of the vmgen-ex example; the new +variant uses a union type instead of lots of casting. + +Both variants of the example can now be compiled with an ANSI C compiler +(using switch dispatch and losing quite a bit of performance); tested +with @command{lcc}. + Users of the gforth-0.5.9-20010501 version of Vmgen need to change several things in their source code to use the current version. I recommend keeping the gforth-0.5.9-20010501 version until you have @@ -1732,6 +1860,16 @@ Also some new macros have to be defined, @node Contact, Copying This Manual, Changes, Top @chapter Contact +To report a bug, use +@url{https://savannah.gnu.org/bugs/?func=addbug&group_id=2672}. + +For discussion on Vmgen (e.g., how to use it), use the mailing list +@email{bug-vmgen@@mail.freesoftware.fsf.org} (use +@url{http://mail.gnu.org/mailman/listinfo/help-vmgen} to subscribe). + +You can find vmgen information at +@url{http://www.complang.tuwien.ac.at/anton/vmgen/}. + @c *********************************************************** @node Copying This Manual, Index, Contact, Top @appendix Copying This Manual