--- gforth/Attic/gforth.ds 1995/11/15 17:29:07 1.24 +++ gforth/Attic/gforth.ds 1996/02/09 17:34:09 1.31 @@ -7,7 +7,7 @@ @comment %**end of header (This is for running Texinfo on a region.) @ifinfo -This file documents Gforth 0.1 +This file documents Gforth 0.2 Copyright @copyright{} 1995 Free Software Foundation, Inc. @@ -41,9 +41,10 @@ Copyright @copyright{} 1995 Free Softwar @sp 10 @center @titlefont{Gforth Manual} @sp 2 -@center for version 0.1 +@center for version 0.2 @sp 2 @center Anton Ertl +@center Bernd Paysan @sp 3 @center This manual is under construction @@ -76,7 +77,7 @@ Copyright @copyright{} 1995 Free Softwar @node Top, License, (dir), (dir) @ifinfo Gforth is a free implementation of ANS Forth available on many -personal machines. This manual corresponds to version 0.1. +personal machines. This manual corresponds to version 0.2. @end ifinfo @menu @@ -90,7 +91,7 @@ personal machines. This manual correspon * Emacs and Gforth:: The Gforth Mode * Internals:: Implementation details * Bugs:: How to report them -* Pedigree:: Ancestors of Gforth +* Origin:: Authors and ancestors of Gforth * Word Index:: An item for each Forth word * Node Index:: An item for each node @end menu @@ -1140,8 +1141,11 @@ system that only supplies @code{THEN} is Forth's @code{THEN} has the meaning 2b, whereas @code{THEN} in Pascal and many other programming languages has the meaning 3d.] -We also provide the words @code{?dup-if} and @code{?dup-0=-if}, so you -can avoid using @code{?dup}. +Gforth also provides the words @code{?dup-if} and @code{?dup-0=-if}, so +you can avoid using @code{?dup}. Using these alternatives is also more +efficient than using @code{?dup}. Definitions in plain standard Forth +for @code{ENDIF}, @code{?DUP-IF} and @code{?DUP-0=-IF} are provided in +@file{compat/control.fs}. @example @var{n} @@ -1233,13 +1237,7 @@ arithmetic). This behaviour is usually n Gforth offers @code{+DO} and @code{U+DO} (as replacements for @code{?DO}), which do not enter the loop if @var{start} is greater than @var{limit}; @code{+DO} is for signed loop parameters, @code{U+DO} for -unsigned loop parameters. These words can be implemented easily on -standard systems, so using them does not make your programs hard to -port; e.g.: -@example -: +DO ( compile-time: -- do-sys; run-time: n1 n2 -- ) - POSTPONE over POSTPONE min POSTPONE ?DO ; immediate -@end example +unsigned loop parameters. @code{LOOP} can be replaced with @code{@var{n} +LOOP}; this updates the index by @var{n} instead of by 1. The loop is terminated when the border @@ -1267,16 +1265,10 @@ between @var{limit+1} and @var{limit} is @code{ 0 0 -DO i . 1 -LOOP} prints nothing -Another alternative is @code{@var{n} S+LOOP}, where the negative -case behaves symmetrical to the positive case: - -@code{-2 0 -DO i . -1 S+LOOP} prints @code{0 -1} - -The loop is terminated when the border between @var{limit@minus{}sgn(n)} -and @var{limit} is crossed. Unfortunately, neither @code{-LOOP} nor -@code{S+LOOP} are part of the ANS Forth standard, and they are not easy -to implement using standard words. If you want to write standard -programs, just avoid counting down. +Unfortunately, @code{+DO}, @code{U+DO}, @code{-DO}, @code{U-DO} and +@code{-LOOP} are not in the ANS Forth standard. However, an +implementation for these words that uses only standard words is provided +in @file{compat/loops.fs}. @code{?DO} can also be replaced by @code{DO}. @code{DO} always enters the loop, independent of the loop parameters. Do not use @code{DO}, even @@ -1299,7 +1291,8 @@ This is the preferred loop of native cod lazy to optimize @code{?DO} loops properly. In Gforth, this loop iterates @var{n+1} times; @code{i} produces values starting with @var{n} and ending with 0. Other Forth systems may behave differently, even if -they support @code{FOR} loops. +they support @code{FOR} loops. To avoid problems, don't use @code{FOR} +loops. @node Arbitrary control structures, Calls and returns, Counted Loops, Control Structures @subsection Arbitrary control structures @@ -1335,6 +1328,12 @@ doc-else doc-while doc-repeat +Gforth adds some more control-structure words: + +doc-endif +doc-?dup-if +doc-?dup-0=-if + Counted loop words constitute a separate group of words: doc-?do @@ -1345,7 +1344,6 @@ doc-u-do doc-do doc-for doc-loop -doc-s+loop doc-+loop doc--loop doc-next @@ -1410,7 +1408,7 @@ while repeat @end example -That's much easier to read, isn't it? Of course, @code{BEGIN} and +That's much easier to read, isn't it? Of course, @code{REPEAT} and @code{WHILE} are predefined, so in this example it would not be necessary to define them. @@ -1735,8 +1733,8 @@ E.g., a definition using @code{TO} might : strcmp @{ addr1 u1 addr2 u2 -- n @} u1 u2 min 0 ?do - addr1 c@ addr2 c@ - ?dup - if + addr1 c@ addr2 c@ - + ?dup-if unloop exit then addr1 char+ TO addr1 @@ -1758,8 +1756,8 @@ are initialized with the right value for addr1 addr2 u1 u2 min 0 ?do @{ s1 s2 @} - s1 c@ s2 c@ - ?dup - if + s1 c@ s2 c@ - + ?dup-if unloop exit then s1 char+ s2 char+ @@ -1938,8 +1936,8 @@ name produces their value. Their value c Since this syntax is supported by Gforth directly, you need not do anything to use it. If you want to port a program using this syntax to -another ANS Forth system, use @file{anslocal.fs} to implement the syntax -on the other system. +another ANS Forth system, use @file{compat/anslocal.fs} to implement the +syntax on the other system. Note that a syntax shown in the standard, section A.13 looks similar, but is quite different in having the order of locals @@ -2088,9 +2086,9 @@ machine code), and for defining the the nature of Gforth poses a few problems: First of all. Gforth runs on several architectures, so it can provide no standard assembler. What's worse is that the register allocation not only depends on the processor, -but also on the gcc version and options used. +but also on the @code{gcc} version and options used. -The words Gforth offers encapsulate some system dependences (e.g., the +The words that Gforth offers encapsulate some system dependences (e.g., the header structure), so a system-independent assembler may be used in Gforth. If you do not have an assembler, you can compile machine code directly with @code{,} and @code{c,}. @@ -2108,10 +2106,42 @@ These words are rarely used. Therefore t which is usually not loaded (except @code{flush-icache}, which is always present). You can load them with @code{require code.fs}. +In the assembly code you will want to refer to the inner interpreter's +registers (e.g., the data stack pointer) and you may want to use other +registers for temporary storage. Unfortunately, the register allocation +is installation-dependent. + +The easiest solution is to use explicit register declarations +(@pxref{Explicit Reg Vars, , Variables in Specified Registers, gcc.info, +GNU C Manual}) for all of the inner interpreter's registers: You have to +compile Gforth with @code{-DFORCE_REG} (configure option +@code{--enable-force-reg}) and the appropriate declarations must be +present in the @code{machine.h} file (see @code{mips.h} for an example; +you can find a full list of all declarable register symbols with +@code{grep register engine.c}). If you give explicit registers to all +variables that are declared at the beginning of @code{engine()}, you +should be able to use the other caller-saved registers for temporary +storage. Alternatively, you can use the @code{gcc} option +@code{-ffixed-REG} (@pxref{Code Gen Options, , Options for Code +Generation Conventions, gcc.info, GNU C Manual}) to reserve a register +(however, this restriction on register allocation may slow Gforth +significantly). + +If this solution is not viable (e.g., because @code{gcc} does not allow +you to explicitly declare all the registers you need), you have to find +out by looking at the code where the inner interpreter's registers +reside and which registers can be used for temporary storage. You can +get an assembly listing of the engine's code with @code{make engine.s}. + +In any case, it is good practice to abstract your assembly code from the +actual register allocation. E.g., if the data stack pointer resides in +register @code{$17}, create an alias for this register called @code{sp}, +and use that in your assembly code. + Another option for implementing normal and defining words efficiently is: adding the wanted functionality to the source of Gforth. For normal words you just have to edit @file{primitives}, defining words (for fast -defined words) probably require changes in @file{engine.c}, +defined words) may require changes in @file{engine.c}, @file{kernal.fs}, @file{prims2x.fs}, and possibly @file{cross.fs}. @@ -2384,7 +2414,7 @@ characters is determined by the locale y @item division rounding: installation dependent. @code{s" floored" environment? drop .}. We leave -the choice to gcc (what to use for @code{/}) and to you (whether to use +the choice to @code{gcc} (what to use for @code{/}) and to you (whether to use @code{fm/mod}, @code{sm/rem} or simply @code{/}). @item values of @code{STATE} when true: @@ -2495,9 +2525,14 @@ The next invocation of a parsing word re Compiles a recursive call to the defining word not to the defined word. @item argument input source different than current input source for @code{RESTORE-INPUT}: -!!???If the argument input source is a valid input source then it gets -restored. Otherwise causes @code{-12 THROW}, which, unless caught, issues -the message "argument type mismatch" and aborts. +@code{-12 THROW}. Note that, once an input file is closed (e.g., because +the end of the file was reached), its source-id may be +reused. Therefore, restoring an input source specification referencing a +closed file may lead to unpredictable results instead of a @code{-12 +THROW}. + +In the future, Gforth may be able to retore input source specifications +from other than the current input soruce. @item data space containing definitions gets de-allocated: Deallocation with @code{allot} is not checked. This typically resuls in @@ -2569,14 +2604,17 @@ Not checked. As usual, you can expect me None. @item operator's terminal facilities available: -!!?? +After processing the command line, Gforth goes into interactive mode, +and you can give commands to Gforth interactively. The actual facilities +available depend on how you invoke Gforth. @item program data space available: @code{sp@ here - .} gives the space remaining for dictionary and data stack together. @item return stack space available: -!!?? +By default 16 KBytes. The default can be overridden with the @code{-r} +switch (@pxref{Invocation}) when Gforth starts up. @item stack space available: @code{sp@ here - .} gives the space remaining for dictionary and data @@ -2897,7 +2935,10 @@ System dependent; @code{REPRESENT} is im function @code{ecvt()} and inherits its behaviour in this respect. @item rounding or truncation of floating-point numbers: -What's the question?!! +System dependent; the rounding behaviour is inherited from the hosting C +compiler. IEEE-FP-based (i.e., most) systems by default round to +nearest, and break ties by rounding to even (i.e., such that the last +bit of the mantissa is 0). @item size of floating-point stack: @code{s" FLOATING-STACK" environment? drop .}. Can be changed at startup @@ -3199,7 +3240,10 @@ Also, if you @code{include} @file{etags. contains the definitions of all words defined afterwards. You can then find the source for a word using @kbd{M-.}. Note that emacs can use several tags files at the same time (e.g., one for the Gforth sources -and one for your program). +and one for your program, @pxref{Select Tags Table,,Selecting a Tags +Table,emacs, Emacs Manual}). The TAGS file for the preloaded words is +@file{$(datadir)/gforth/$(VERSION)/TAGS} (e.g., +@file{/usr/local/share/gforth/0.2/TAGS}). To get all these benefits, add the following lines to your @file{.emacs} file: @@ -3608,32 +3652,38 @@ Sieve benchmark on a 486DX2/66 than Gfor However, this potential advantage of assembly language implementations is not necessarily realized in complete Forth systems: We compared -Gforth (compiled with @code{gcc-2.6.3} and @code{-DFORCE_REG}) with -Win32Forth 1.2093 and LMI's NT Forth (Beta, May 1994), two systems -written in assembly, and with two systems written in C: PFE-0.9.11 -(compiled with @code{gcc-2.6.3} with the default configuration for -Linux: @code{-O2 -fomit-frame-pointer -DUSE_REGS}) and ThisForth Beta -(compiled with gcc-2.6.3 -O3 -fomit-frame-pointer). We benchmarked -Gforth, PFE and ThisForth on a 486DX2/66 under Linux. Kenneth O'Heskin -kindly provided the results for Win32Forth and NT Forth on a 486DX2/66 -with similar memory performance under Windows NT. +Gforth (direct threaded, compiled with @code{gcc-2.6.3} and +@code{-DFORCE_REG}) with Win32Forth 1.2093, LMI's NT Forth (Beta, May +1994) and Eforth (with and without peephole (aka pinhole) optimization +of the threaded code); all these systems were written in assembly +language. We also compared Gforth with three systems written in C: +PFE-0.9.11 (compiled with @code{gcc-2.6.3} with the default +configuration for Linux: @code{-O2 -fomit-frame-pointer -DUSE_REGS}), +ThisForth Beta (compiled with gcc-2.6.3 -O3 -fomit-frame-pointer; +ThisForth employs peephole optimization of the threaded code) and TILE +(compiled with @code{make opt}). We benchmarked Gforth, PFE, ThisForth +and TILE on a 486DX2/66 under Linux. Kenneth O'Heskin kindly provided +the results for Win32Forth and NT Forth on a 486DX2/66 with similar +memory performance under Windows NT. Marcel Hendrix ported Eforth to +Linux, then extended it to run the benchmarks, added the peephole +optimizer, ran the benchmarks and reported the results. We used four small benchmarks: the ubiquitous Sieve; bubble-sorting and matrix multiplication come from the Stanford integer benchmarks and have been translated into Forth by Martin Fraeman; we used the versions -included in the TILE Forth package; and a recursive Fibonacci number -computation for benchmarking calling performance. The following table shows -the time taken for the benchmarks scaled by the time taken by Gforth (in -other words, it shows the speedup factor that Gforth achieved over the -other systems). +included in the TILE Forth package, but with bigger data set sizes; and +a recursive Fibonacci number computation for benchmarking calling +performance. The following table shows the time taken for the benchmarks +scaled by the time taken by Gforth (in other words, it shows the speedup +factor that Gforth achieved over the other systems). @example -relative Win32- NT This- - time Gforth Forth Forth PFE Forth -sieve 1.00 1.30 1.07 1.67 2.98 -bubble 1.00 1.30 1.40 1.66 -matmul 1.00 1.40 1.29 2.24 -fib 1.00 1.44 1.26 1.82 2.82 +relative Win32- NT eforth This- + time Gforth Forth Forth eforth +opt PFE Forth TILE +sieve 1.00 1.39 1.14 1.39 0.85 1.78 3.18 8.58 +bubble 1.00 1.31 1.41 1.48 0.88 1.67 3.88 +matmul 1.00 1.47 1.35 1.46 1.16 2.36 4.09 +fib 1.00 1.52 1.34 1.22 1.13 1.93 2.99 4.30 @end example You may find the good performance of Gforth compared with the systems @@ -3645,12 +3695,18 @@ method for relocating the Forth image: l the actual addresses at run time, resulting in two address computations per NEXT (@pxref{System Architecture}). -The speedup of Gforth over PFE and ThisForth can be easily explained -with the self-imposed restriction to standard C (although the measured -implementation of PFE uses a GNU C extension: global register -variables), which makes efficient threading impossible. Moreover, -current C compilers have a hard time optimizing other aspects of the -ThisForth source. +Only Eforth with the peephole optimizer performs comparable to +Gforth. The speedups achieved with peephole optimization of threaded +code are quite remarkable. Adding a peephole optimizer to Gforth should +cause similar speedups. + +The speedup of Gforth over PFE, ThisForth and TILE can be easily +explained with the self-imposed restriction to standard C, which makes +efficient threading impossible (however, the measured implementation of +PFE uses a GNU C extension: @ref{Global Reg Vars, , Defining Global +Register Variables, gcc.info, GNU C Manual}). Moreover, current C +compilers have a hard time optimizing other aspects of the ThisForth +and the TILE source. Note that the performance of Gforth on 386 architecture processors varies widely with the version of @code{gcc} used. E.g., @code{gcc-2.5.8} @@ -3659,14 +3715,16 @@ machine registers by itself and would no register declarations, giving a 1.3 times slower engine (on a 486DX2/66 running the Sieve) than the one measured above. -The numbers in this section have also been published in the paper -@cite{Translating Forth to Efficient C} by M. Anton Ertl and Martin -Maierhofer, presented at EuroForth '95. It is available at +In @cite{Translating Forth to Efficient C} by M. Anton Ertl and Martin +Maierhofer (presented at EuroForth '95), an indirect threaded version of +Gforth is compared with Win32Forth, NT Forth, PFE, and ThisForth; that +version of Gforth is 2\%@minus{}8\% slower on a 486 than the version +used here. The paper available at @*@file{http://www.complang.tuwien.ac.at/papers/ertl&maierhofer95.ps.gz}; it also contains numbers for some native code systems. You can find numbers for Gforth on various machines in @file{Benchres}. -@node Bugs, Pedigree, Internals, Top +@node Bugs, Origin, Internals, Top @chapter Bugs Known bugs are described in the file BUGS in the Gforth distribution. @@ -3686,8 +3744,25 @@ For a thorough guide on reporting bugs r to Report Bugs, gcc.info, GNU C Manual}. -@node Pedigree, Word Index, Bugs, Top -@chapter Pedigree +@node Origin, Word Index, Bugs, Top +@chapter Authors and Ancestors of Gforth + +@section Authors and Contributors + +The Gforth project was started in mid-1992 by Bernd Paysan and Anton +Ertl. The third major author was Jens Wilke. Lennart Benschop (who was +one of Gforth's first users, in mid-1993) and Stuart Ramsden inspired us +with their continuous feedback. Lennart Benshop contributed +@file{glosgen.fs}, while Stuart Ramsden has been working on automatic +support for calling C libraries. Helpful comments also came from Paul +Kleinrubatscher, Christian Pirker, Dirk Zoller and Marcel Hendrix. + +Gforth also owes a lot to the authors of the tools we used (GCC, CVS, +and autoconf, among others), and to the creators of the Internet: Gforth +was developed across the Internet, and its authors have not met +physically yet. + +@section Pedigree Gforth descends from BigForth (1993) and fig-Forth. Gforth and PFE (by Dirk Zoller) will cross-fertilize each other. Of course, a significant @@ -3701,7 +3776,7 @@ VolksForth descends from F83. It was wri Pennemann, Georg Rehfeld and Dietrich Weineck for the C64 (called UltraForth there) in the mid-80s and ported to the Atari ST in 1986. -Laxen and Perry wrote F83 as a model implementation of the +Hennry Laxen and Mike Perry wrote F83 as a model implementation of the Forth-83 standard. !! Pedigree? When? A team led by Bill Ragsdale implemented fig-Forth on many processors in @@ -3714,7 +3789,8 @@ the 1802, and subsequently implemented o Z80. All earlier Forth systems were custom-made, usually by Charles Moore, -who discovered (as he puts it) Forth in the late 60s. +who discovered (as he puts it) Forth during the late 60s. The first full +Forth existed in 1971. A part of the information in this section comes from @cite{The Evolution of Forth} by Elizabeth D. Rather, Donald R. Colburn and Charles @@ -3722,7 +3798,7 @@ H. Moore, presented at the HOPL-II confe Notices 28(3), 1993. You can find more historical and genealogical information about Forth there. -@node Word Index, Node Index, Pedigree, Top +@node Word Index, Node Index, Origin, Top @chapter Word Index This index is as incomplete as the manual. Each word is listed with