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: |