Diff for /gforth/Attic/gforth.ds between versions 1.44 and 1.45

version 1.44, 1997/03/04 17:49:49 version 1.45, 1997/03/11 16:00:38
Line 4392  convention, we use the extension @code{. Line 4392  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 4403  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 4422  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 4471  The code addresses of run-time routines Line 4471  The code addresses of run-time routines
 represented in the image file (because their tokens would be replaced by  represented in the image file (because their tokens would be replaced by
 machine code in direct threaded implementations). As a workaround,  machine code in direct threaded implementations). As a workaround,
 compute these addresses at run-time with @code{>code-address} from the  compute these addresses at run-time with @code{>code-address} from the
 executions tokens of selected words (see the definitions of  executions tokens of appropriate words (see the definitions of
 @code{docol:} and friends in @file{kernel.fs}).  @code{docol:} and friends in @file{kernel.fs}).
   
 @item  @item
Line 4507  doc-savesystem Line 4507  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).
   
   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 4591  relocatable. Line 4613  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 4654  deferred word Line 4675  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:

Removed from v.1.44  
changed lines
  Added in v.1.45


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