Diff for /gforth/Attic/gforth.ds between versions 1.43 and 1.48

version 1.43, 1997/02/01 14:59:30 version 1.48, 1997/04/10 15:00:06
Line 3 Line 3
 @comment %**start of header (This is for running Texinfo on a region.)  @comment %**start of header (This is for running Texinfo on a region.)
 @setfilename gforth.info  @setfilename gforth.info
 @settitle Gforth Manual  @settitle Gforth Manual
   @dircategory GNU programming tools
   @direntry
   * Gforth: (gforth).             A fast interpreter for the Forth language.
   @end direntry
 @comment @setchapternewpage odd  @comment @setchapternewpage odd
 @comment %**end of header (This is for running Texinfo on a region.)  @comment %**end of header (This is for running Texinfo on a region.)
   
Line 99  personal machines. This manual correspon Line 103  personal machines. This manual correspon
 * Concept Index::               A menu covering many topics  * Concept Index::               A menu covering many topics
 @end menu  @end menu
   
 @node License, Preface, Top, Top  @node License, Goals, Top, Top
 @unnumbered GNU GENERAL PUBLIC LICENSE  @unnumbered GNU GENERAL PUBLIC LICENSE
 @center Version 2, June 1991  @center Version 2, June 1991
   
Line 492  library.  If this is what you want to do Line 496  library.  If this is what you want to do
 Public License instead of this License.  Public License instead of this License.
   
 @iftex  @iftex
 @node    Preface, Goals, License, Top  
 @comment node-name,     next,           previous, up  
 @unnumbered Preface  @unnumbered Preface
 @cindex Preface  @cindex Preface
 This manual documents Gforth. The reader is expected to know  This manual documents Gforth. The reader is expected to know
Line 501  Forth. This manual is primarily a refere Line 503  Forth. This manual is primarily a refere
 for introductory material.  for introductory material.
 @end iftex  @end iftex
   
 @node    Goals, Other Books, Preface, Top  @node    Goals, Other Books, License, Top
 @comment node-name,     next,           previous, up  @comment node-name,     next,           previous, up
 @chapter Goals of Gforth  @chapter Goals of Gforth
 @cindex Goals  @cindex Goals
Line 566  can also get it from Global Engineering Line 568  can also get it from Global Engineering
 for publication is available electronically and for free in some MS Word  for publication is available electronically and for free in some MS Word
 format, and it has been converted to HTML. Some pointers to these  format, and it has been converted to HTML. Some pointers to these
 versions can be found through  versions can be found through
 @*@file{http://www.complang.tuwien.ac.at/projects/forth.html}.  @*@url{http://www.complang.tuwien.ac.at/projects/forth.html}.
   
 @cindex introductory book  @cindex introductory book
 @cindex book, introductory  @cindex book, introductory
Line 1371  The index of the innermost loop can be a Line 1373  The index of the innermost loop can be a
 of the next loop with @code{j}, and the index of the third loop with  of the next loop with @code{j}, and the index of the third loop with
 @code{k}.  @code{k}.
   
   doc-i
   doc-j
   doc-k
   
 The loop control data are kept on the return stack, so there are some  The loop control data are kept on the return stack, so there are some
 restrictions on mixing return stack accesses and counted loop  restrictions on mixing return stack accesses and counted loop
 words. E.g., if you put values on the return stack outside the loop, you  words. E.g., if you put values on the return stack outside the loop, you
Line 1607  implemented the ANS Forth locals wordset Line 1613  implemented the ANS Forth locals wordset
 The ideas in this section have also been published in the paper  The ideas in this section have also been published in the paper
 @cite{Automatic Scoping of Local Variables} by M. Anton Ertl, presented  @cite{Automatic Scoping of Local Variables} by M. Anton Ertl, presented
 at EuroForth '94; it is available at  at EuroForth '94; it is available at
 @*@file{http://www.complang.tuwien.ac.at/papers/ertl94l.ps.gz}.  @*@url{http://www.complang.tuwien.ac.at/papers/ertl94l.ps.gz}.
   
 @menu  @menu
 * Gforth locals::                 * Gforth locals::               
Line 4392  convention, we use the extension @code{. Line 4398  convention, we use the extension @code{.
 * Image File Background::          Why have image files?  * Image File Background::          Why have image files?
 * Non-Relocatable Image Files::    don't always work.  * Non-Relocatable Image Files::    don't always work.
 * Data-Relocatable Image Files::   are better.  * Data-Relocatable Image Files::   are better.
 * Fully Relocatable Image Files::  are hard to create.  * Fully Relocatable Image Files::  better yet.
 * Stack and Dictionary Sizes::     Setting the default sizes for an image.  * Stack and Dictionary Sizes::     Setting the default sizes for an image.
 * Running Image Files::            @code{gforth -i @var{file}} or @var{file}.  * Running Image Files::            @code{gforth -i @var{file}} or @var{file}.
 * Modifying the Startup Sequence:: and turnkey applications.  * Modifying the Startup Sequence:: and turnkey applications.
Line 4403  convention, we use the extension @code{. Line 4409  convention, we use the extension @code{.
 @cindex image file background  @cindex image file background
   
 Our Forth system consists not only of primitives, but also of  Our Forth system consists not only of primitives, but also of
 definitions written in Forth. Since the Forth compiler itself belongs  definitions written in Forth. Since the Forth compiler itself belongs to
 to those definitions, it is not possible to start the system with the  those definitions, it is not possible to start the system with the
 primitives and the Forth source alone. Therefore we provide the Forth  primitives and the Forth source alone. Therefore we provide the Forth
 code as an image file in nearly executable form. At the start of the  code as an image file in nearly executable form. At the start of the
 system a C routine loads the image file into memory, sets up the  system a C routine loads the image file into memory, optionally
 memory (stacks etc.) according to information in the image file, and  relocates the addresses, then sets up the memory (stacks etc.) according
 starts executing Forth code.  to information in the image file, and starts executing Forth code.
   
 The image file variants represent different compromises between the  The image file variants represent different compromises between the
 goals of making it easy to generate image files and making them  goals of making it easy to generate image files and making them
Line 4422  files are data relocatable without furth Line 4428  files are data relocatable without furth
 (one addition per memory access).  (one addition per memory access).
   
 @cindex relocation at load-time  @cindex relocation at load-time
 Our loader performs relocation at image load time. The loader also has  By contrast, our loader performs relocation at image load time. The
 to replace tokens standing for primitive calls with the appropriate  loader also has to replace tokens standing for primitive calls with the
 code-field addresses (or code addresses in the case of direct  appropriate code-field addresses (or code addresses in the case of
 threading).  direct threading).
   
 There are three kinds of image files, with different degrees of  There are three kinds of image files, with different degrees of
 relocatability: non-relocatable, data-relocatable, and fully relocatable  relocatability: non-relocatable, data-relocatable, and fully relocatable
Line 4444  cannot represent @code{ALLOCATE}d memory Line 4450  cannot represent @code{ALLOCATE}d memory
 them). And the contents of the stacks are not represented, either.  them). And the contents of the stacks are not represented, either.
   
 @item  @item
 The only kinds of relocation supported are: the addition of the same  The only kinds of relocation supported are: adding the same offset to
 offset to all cells that represent data addresses; and the replacement of  all cells that represent data addresses; and replacing special tokens
 special tokens with code addresses.  with code addresses or with pieces of machine code.
   
 If any complex computations involving addresses are performed, the  If any complex computations involving addresses are performed, the
 results cannot be represented in the image file. Several applications that  results cannot be represented in the image file. Several applications that
Line 4467  startup.@footnote{In my opinion, though, Line 4473  startup.@footnote{In my opinion, though,
 using a doubly-linked list (whatever implementation).}  using a doubly-linked list (whatever implementation).}
   
 @item  @item
   The code addresses of run-time routines like @code{docol:} cannot be
   represented in the image file (because their tokens would be replaced by
   machine code in direct threaded implementations). As a workaround,
   compute these addresses at run-time with @code{>code-address} from the
   executions tokens of appropriate words (see the definitions of
   @code{docol:} and friends in @file{kernel.fs}).
   
   @item
 On many architectures addresses are represented in machine code in some  On many architectures addresses are represented in machine code in some
 shifted or mangled form. You cannot put @code{CODE} words that contain  shifted or mangled form. You cannot put @code{CODE} words that contain
 absolute addresses in this form in a relocatable image file. Workarounds  absolute addresses in this form in a relocatable image file. Workarounds
Line 4499  doc-savesystem Line 4513  doc-savesystem
 @cindex data-relocatable image files  @cindex data-relocatable image files
 @cindex image files, data-relocatable  @cindex image files, data-relocatable
   
 @cindex @file{gforth.fi}, relocatability  
 These files contain relocatable data addresses, but fixed code addresses  These files contain relocatable data addresses, but fixed code addresses
 (instead of tokens). They are specific to the executable (i.e.,  (instead of tokens). They are specific to the executable (i.e.,
 @file{gforth} file) they were created with. E.g., the image  @file{gforth} file) they were created with. For direct threading on some
 @code{gforth.fi} is a data-relocatable image file.  architectures (e.g., the i386), data-relocatable images do not work. You
   get a data-relocatable image, if you use @file{gforth-makeimage} with a
   Gforth binary that is not doubly indirect threaded (@pxref{Fully
   Relocatable Image Files}).
   
   @node Fully Relocatable Image Files, Stack and Dictionary Sizes, Data-Relocatable Image Files, Image Files
   @section Fully Relocatable Image Files
   @cindex fully relocatable image files
   @cindex image files, fully relocatable
   
   @cindex @file{kern*.fi}, relocatability
   @cindex @file{gforth.fi}, relocatability
   These image files have relocatable data addresses, and tokens for code
   addresses. They can be used with different binaries (e.g., with and
   without debugging) on the same machine, and even across machines with
   the same data formats (byte order, cell size, floating point
   format). However, they are usually specific to the version of Gforth
   they were created with. The files @file{gforth.fi} and @file{kernl*.fi}
   are fully relocatable.
   
   There are two ways to create a fully relocatable image file:
   
   @menu
   * gforth-makeimage::            The normal way
   * cross.fs::                    The hard way
   @end menu
   
   @node gforth-makeimage, cross.fs, Fully Relocatable Image Files, Fully Relocatable Image Files
   @subsection @file{gforth-makeimage}
 @cindex @file{comp-image.fs}  @cindex @file{comp-image.fs}
 You can create a data-relocatable image file by creating two  @cindex @file{gforth-makeimage}
 non-relocatable image files for different base addresses and processing  
 them with @file{comp-image.fs}, which generates the relocation  
 information by comparing the images.  
   
 After loading @file{comp-image.fs}, you can invoke the word  
 @code{comp-image}, which reads the names of the two input files and the  
 name of the output file from the input stream. This program also  
 produces some output on the standard output: It displays the offset  
 (i.e., the difference between the base addresses of the images);  
 moreover, for each cell that cannot be represented correctly in the  
 image files, it displays a line like the following one:  
   
   You will usually use @file{gforth-makeimage}. If you want to create an
   image @var{file} that contains everything you would load by invoking
   Gforth with @code{gforth @var{options}}, you simply say
 @example  @example
      78DC         BFFFFA50         BFFFFA40  gforth-makeimage @var{file} @var{options}
 @end example  @end example
   
 This means that at offset $78dc from @code{forthstart}, one input image  
 contains $bffffa50, and the other contains $bffffa40. Since these cells  
 cannot be represented correctly in the output image, you should examine  
 these places in the dictionary and verify that these cells are dead  
 (i.e., not read before they are written).  
   
 E.g., if you want to create an image @file{asm.fi} that has the file  E.g., if you want to create an image @file{asm.fi} that has the file
 @file{asm.fs} loaded in addition to the usual stuff, you could do it  @file{asm.fs} loaded in addition to the usual stuff, you could do it
 like this:  like this:
   
 @example  @example
 gforth --clear-dictionary asm.fs "savesystem asm.fi1 bye"  gforth-makeimage asm.fi asm.fs
 gforth --clear-dictionary --offset-image asm.fs "savesystem asm.fi2 bye"  
 gforth -m 100000 comp-image.fs -e "comp-image asm.fi1 asm.fi2 asm.fi bye"  
 @end example  @end example
   
 @cindex --clear-dictionary, creating image files  @file{gforth-makeimage} works like this: It produces two non-relocatable
 @cindex --offset-image, creating image files  images for different addresses and then compares them. Its output
 The flag @code{--clear-dictionary} ensures that the dictionary memory is  reflects this: first you see the output (if any) of the two Gforth
 cleared at the start (so you won't see @code{comp-image} messages about  invocations that produce the nonrelocatable image files, then you see
 spurious differences). The flag @code{--offset-image} loads the image at  the output of the comparing program: It displays the offset used for
 a small offset from its normal position, ensuring that the resulting  data addresses and the offset used for code addresses;
 nonrelocatable images have different bases (otherwise @code{comp-image}  moreover, for each cell that cannot be represented correctly in the
 cannot work).  image files, it displays a line like the following one:
   
 @node Fully Relocatable Image Files, Stack and Dictionary Sizes, Data-Relocatable Image Files, Image Files  @example
 @section Fully Relocatable Image Files       78DC         BFFFFA50         BFFFFA40
 @cindex fully relocatable image files  @end example
 @cindex image files, fully relocatable  
   
 @cindex @file{kern*.fi}, relocatability  This means that at offset $78dc from @code{forthstart}, one input image
 These image files have relocatable data addresses, and tokens for code  contains $bffffa50, and the other contains $bffffa40. Since these cells
 addresses. They are still a bit machine dependent with respect to the  cannot be represented correctly in the output image, you should examine
 size and format (byte order, floating point format) of their data. The  these places in the dictionary and verify that these cells are dead
 @file{kernlxxx.fi} files are fully relocatable.  (i.e., not read before they are written).
   
   @cindex @code{savesystem} during @file{gforth-makeimage}
   @cindex @code{bye} during @file{gforth-makeimage}
   @cindex doubly indirect threaded code
   @cindex environment variable @code{GFORTHD}
   @cindex @code{GFORTHD} environment variable
   @cindex @code{gforth-ditc}
   There are a few wrinkles: After processing the passed @var{options}, the
   words @code{savesystem} and @code{bye} must be visible. A special doubly
   indirect threaded version of the @file{gforth} executable is used for
   creating the nonrelocatable images; you can pass the exact filename of
   this executable through the environment variable @code{GFORTHD}
   (default: @file{gforth-ditc}); if you pass a version that is not doubly
   indirect threaded, you will not get a fully relocatable image, but a
   data-relocatable image (because there is no code address offset).
   
   @node cross.fs,  , gforth-makeimage, Fully Relocatable Image Files
   @subsection @file{cross.fs}
   @cindex @file{cross.fs}
 @cindex cross-compiler  @cindex cross-compiler
 @cindex metacompiler  @cindex metacompiler
 At present a fully relocatable image file can only be produced by  
 @code{cross}, a batch compiler that accepts a Forth-like programming  You can also use @code{cross}, a batch compiler that accepts a Forth-like
 language. This @code{cross} language has to be documented  programming language. This @code{cross} language has to be documented
 yet.  yet.
   
 @cindex target compiler  @cindex target compiler
 @code{cross} not only allows the programmer to create fully relocatable  @code{cross} also allows you to create image files for machines with
 image files, but also to create image files for machines with different  different data sizes and data formats than the one used for generating
 data sizes and data formats than the one used for generating the image  the image file. You can also use it to create an application image that
 file. This convenience is bought with restrictions and inconveniences in  does not contain a Forth compiler. These features are bought with
 programming. E.g., addresses have to be stored in memory with special  restrictions and inconveniences in programming. E.g., addresses have to
 words (@code{A!}, @code{A,}, etc.) in order to make the code  be stored in memory with special words (@code{A!}, @code{A,}, etc.) in
 relocatable.  order to make the code relocatable.
   
   
 @node Stack and Dictionary Sizes, Running Image Files, Fully Relocatable Image Files, Image Files  @node Stack and Dictionary Sizes, Running Image Files, Fully Relocatable Image Files, Image Files
 @section Stack and Dictionary Sizes  @section Stack and Dictionary Sizes
Line 4583  relocatable. Line 4625  relocatable.
   
 If you invoke Gforth with a command line flag for the size  If you invoke Gforth with a command line flag for the size
 (@pxref{Invoking Gforth}), the size you specify is stored in the  (@pxref{Invoking Gforth}), the size you specify is stored in the
 dictionary. If you save the dictionary with @code{savesystem}, this size  dictionary. If you save the dictionary with @code{savesystem} or create
 will become the default for the resulting image file. E.g., the  an image with @file{gforth-makeimage}, this size will become the default
 following will create a non-relocatable version of gforth.fi with a 1MB  for the resulting image file. E.g., the following will create a
 dictionary:  fully relocatable version of gforth.fi with a 1MB dictionary:
   
 @example  @example
 gforth -m 1M -e "savesystem gforth1M.fi bye"  gforth-makeimage gforth.fi -m 1M
 @end example  @end example
   
 In other words, if you want to set the default size for the dictionary  In other words, if you want to set the default size for the dictionary
 and the stacks of an image, just invoke Gforth with the appropriate  and the stacks of an image, just invoke @file{gforth-makeimage} with the
 options when creating the image. When creating a data-relocatable image,  appropriate options when creating the image.
 you have to use the same size options for both @code{savesystem}s.  
   
 @cindex stack size, cache-friendly  @cindex stack size, cache-friendly
 Note: For cache-friendly behaviour (i.e., good performance), you should  Note: For cache-friendly behaviour (i.e., good performance), you should
Line 4620  gforth -i @var{image} Line 4661  gforth -i @var{image}
 @cindex executable image file  @cindex executable image file
 @cindex image files, executable  @cindex image files, executable
 If your operating system supports starting scripts with a line of the  If your operating system supports starting scripts with a line of the
 form @code{#! ...}, you can make your image file executable, and you'll  form @code{#! ...}, you just have to type the image file name to start
 just have to type the image file name to start Gforth with this image  Gforth with this image file (note that the file extension @code{.fi} is
 file (note that the file extension @code{.fi} is just a convention).  just a convention). I.e., to run Gforth with the image file @var{image},
   you can just type @var{image} instead of @code{gforth -i @var{image}}.
 I.e., in most Unix systems, you just have to make the image file  
 @var{image} executable with  
   
 @example  
 chmod +x @var{image}  
 @end example  
   
 and then you can invoke it by simply typing @var{image} instead of  doc-#!
 @code{gforth -i @var{image}}.  
   
 @node Modifying the Startup Sequence,  , Running Image Files, Image Files  @node Modifying the Startup Sequence,  , Running Image Files, Image Files
 @section Modifying the Startup Sequence  @section Modifying the Startup Sequence
Line 4646  deferred word Line 4680  deferred word
 doc-'cold  doc-'cold
   
 @code{'cold} is invoked just before the image-specific command line  @code{'cold} is invoked just before the image-specific command line
 processing (by default, loading files and evaluating (@code{-e}) strings  processing (by default, loading files and evaluating (@code{-e}) strings)
 starts.  starts.
   
 A sequence for adding your initialization usually looks like this:  A sequence for adding your initialization usually looks like this:
Line 4664  You can make a turnkey image by letting Line 4698  You can make a turnkey image by letting
 (your turnkey application) that never returns; instead, it exits Gforth  (your turnkey application) that never returns; instead, it exits Gforth
 via @code{bye} or @code{throw}.  via @code{bye} or @code{throw}.
   
   @cindex command-line arguments, access
   @cindex arguments on the command line, access
   You can access the (image-specific) command-line arguments through the
   variables @code{argc} and @code{argv}. @code{arg} provides conventient
   access to @code{argv}.
   
   doc-argc
   doc-argv
   doc-arg
   
   If @code{'cold} exits normally, Gforth processes the command-line
   arguments as files to be loaded and strings to be evaluated.  Therefore,
   @code{'cold} should remove the arguments it has used in this case.
   
 @c ******************************************************************  @c ******************************************************************
 @node Engine, Bugs, Image Files, Top  @node Engine, Bugs, Image Files, Top
 @chapter Engine  @chapter Engine
Line 4677  The ideas in this section have also been Line 4725  The ideas in this section have also been
 @cite{ANS fig/GNU/??? Forth} (in German) by Bernd Paysan, presented at  @cite{ANS fig/GNU/??? Forth} (in German) by Bernd Paysan, presented at
 the Forth-Tagung '93 and @cite{A Portable Forth Engine} by M. Anton  the Forth-Tagung '93 and @cite{A Portable Forth Engine} by M. Anton
 Ertl, presented at EuroForth '93; the latter is available at  Ertl, presented at EuroForth '93; the latter is available at
 @*@file{http://www.complang.tuwien.ac.at/papers/ertl93.ps.Z}.  @*@url{http://www.complang.tuwien.ac.at/papers/ertl93.ps.Z}.
   
 @menu  @menu
 * Portability::                   * Portability::                 
Line 5157  predictive value for the performance of Line 5205  predictive value for the performance of
 In @cite{Translating Forth to Efficient C} by M. Anton Ertl and Martin  In @cite{Translating Forth to Efficient C} by M. Anton Ertl and Martin
 Maierhofer (presented at EuroForth '95), an indirect threaded version of  Maierhofer (presented at EuroForth '95), an indirect threaded version of
 Gforth is compared with Win32Forth, NT Forth, PFE, and ThisForth; that  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  version of Gforth is 2%@minus{}8% slower on a 486 than the direct
 used here. The paper available at  threaded version used here. The paper available at
 @*@file{http://www.complang.tuwien.ac.at/papers/ertl&maierhofer95.ps.gz};  @*@url{http://www.complang.tuwien.ac.at/papers/ertl&maierhofer95.ps.gz};
 it also contains numbers for some native code systems. You can find a  it also contains numbers for some native code systems. You can find a
 newer version of these measurements at  newer version of these measurements at
 @file{http://www.complang.tuwien.ac.at/forth/performance.html}. You can  @url{http://www.complang.tuwien.ac.at/forth/performance.html}. You can
 find numbers for Gforth on various machines in @file{Benchres}.  find numbers for Gforth on various machines in @file{Benchres}.
   
 @node Bugs, Origin, Engine, Top  @node Bugs, Origin, Engine, Top
Line 5172  find numbers for Gforth on various machi Line 5220  find numbers for Gforth on various machi
 Known bugs are described in the file BUGS in the Gforth distribution.  Known bugs are described in the file BUGS in the Gforth distribution.
   
 If you find a bug, please send a bug report to  If you find a bug, please send a bug report to
 @code{bug-gforth@@gnu.ai.mit.edu}. A bug report should  @email{bug-gforth@@gnu.ai.mit.edu}. A bug report should
 describe the Gforth version used (it is announced at the start of an  describe the Gforth version used (it is announced at the start of an
 interactive Gforth session), the machine and operating system (on Unix  interactive Gforth session), the machine and operating system (on Unix
 systems you can use @code{uname -a} to produce this information), the  systems you can use @code{uname -a} to produce this information), the

Removed from v.1.43  
changed lines
  Added in v.1.48


FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>