--- gforth/doc/vmgen.texi 2002/08/19 07:38:16 1.13 +++ gforth/doc/vmgen.texi 2002/09/01 15:15:07 1.19 @@ -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,18 +709,25 @@ 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 many other Forth program fragments that could be written in an eval-escape). +A stack prefix can contain letters, digits, or @samp{:}, and may start +with an @samp{#}; e.g., in Gforth the return stack has the stack prefix +@samp{R:}. This restriction is not checked during the stack prefix +definition, but it is enforced by the parsing rules for stack items +later. + If you know Forth, the stack effects of the non-standard words involved are: @findex stack @@ -684,15 +735,18 @@ are: @findex single @findex double @findex stack-prefix +@findex store-optimization @example -stack ( "name" "pointer" "type" -- ) - ( name execution: -- stack ) -type-prefix ( addr u xt1 xt2 n stack "prefix" -- ) -single ( -- xt1 xt2 n ) -double ( -- xt1 xt2 n ) -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. @c -------------------------------------------------------------------- @node Simple instructions, Superinstructions, Input File Grammar, Input File Format @@ -923,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 @@ -981,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 @@ -1061,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 @@ -1691,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 @@ -1725,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