--- gforth/doc/vmgen.texi 2002/08/20 16:59:01 1.15 +++ gforth/doc/vmgen.texi 2002/08/28 21:46:59 1.18 @@ -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 @@ -683,6 +689,11 @@ Vmgen understands a few extensions beyon 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 @@ -698,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 @@ -723,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. @@ -963,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 @@ -1021,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 @@ -1101,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 @@ -1731,6 +1809,17 @@ please let us know. @chapter Changes @cindex Changes from old versions +Use-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 @@ -1765,6 +1854,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