Dream 48/Amiga_Dream_48.iso/Atari/forth/forst.zoo/forst/forst.doc

Text File | 1990-12-10 | 16KB | 375 lines

                                USING ForST


This file should be read in conjunction with BULLETIN.DOC, which provides
a much more concise overview of the system.


ForST

ForST is a generic 68000 subroutine-threaded, 32-bit Forth with
significant optimisation of compiled code.  Compiled code compares very
favourably with that from other 68000 compilers.  An overview of the system
is given in a five-part series of articles in Forth Dimensions (starting
Vol XII/2).  Since the original articles were written (mid-1989), the
system has been modified to include:

        Headers with links and a flag field (ffa) to direct
          code optimisation
        Register variables as an improved means of local variable
          storage (about 30% faster and significantly smaller code
          than with memory local variables)
        Optimisation with two edges, leading to a further reduction of
          about 20% in execution time.
        Better access to operating system functions and I/O redirection.
        Construction of code primitives by high-level access to
          hardware registers, rather than by using an assembler.

Because of the policy of providing a generic system, ForST does not
use the special features of the GEM environment.  Rather, it has been
constructed with an eye to porting to other 68000 command-line systems.


The files

Two executable files are provided in the root directory:

        1. FORST.TOS, which is assembled from FORST.S.  This file has
           the headers used by the DevPac monitor.

        2. FORSTX.TOS, which is created by the following sequence:
                a. Double click on FORST.TOS in the usual way;
                b. When ForST has signed on, type:
                   macros load a:\lib\util.s
                c. When the prompt appears again, type:
                   cd a:\lib ( to log into the lib folder)
                   load ldfloats.s ( to load f-point package)
                d. When prompted, type:
                   load redir.s  ( for redirection words)
                d. When prompted again, type:
                   save a:\forstx.tos

        3. Exit (when you wish) to the desktop with SYSTEM

In the SOURCE directory are all the assembly source files needed to
reassemble the basic ForST system.  An overview is given in the
BULLETIN.DOC file.  These files are in the public domain ONLY for
non-profit use, and provided that acknowledgement is made of their
origin.

In the LIB directory are a number of system utilities and enhancements,
which illustrate the use of the extended Forth style and register/local
variables.  Not all will approve of them, I know.  These files are
placed in the public domain on the sole condition that their origin be
acknowledged.

The util.s file contains many of the convenience words you will need:

        a: b: c: d: and e: to set the logged disk
        dir (= dir *.*) or (eg) dir a:\lib\*.s etc
        ren <oldname> <newname>
        del <filename>
        copy, ucopy, lcopy <fromname> <toname>
        cd <pathname>  (includes . and ..)
        words (list available words)
        macwords (list available macros)
        what <wordname> (information about the word)


Using ForST

ForST can be used as a fairly standard Forth.  The code that it compiles
can be controlled by CALLS (to compile subroutine-threaded code) and
MACROS (to expand macro words and optimise where possible).  To check
compiled code, a crude hex dump of any word can be obtained with

        wd <wordname>

which waits for a series of keystrokes, and quits on <ESC>.

        what <wordname>

gives some basic information, extracted from the word's header.  It is
a little naive, especially with DEFERed and VECTORed words (in Part 5
of the Forth Dimensions series).  The word length given is based on the
number of 16-bit cells, modulo $400, and may not be accurate for very
long definitions.

Experience with ForST has shown that source code in the standard Forth style
gives rather poor object code.  It is much better to use register (best) or
local variables and, in any case, I feel that the source code is much more
intelligible.  The register version of the sieve benchmark executes 100
iterations in just over 25 seconds, while nearly 60 seconds are required with
the standard Forth source.  The object code is about 10% smaller,too.  The
source file is in the LIB directory.

The register and local variables are the most controversial part of ForST.  I
simply ask that others give them a try.  A number of examples are provided
in the LIB directory.  I am not particularly happy with the declaration
syntax:

        3 regargs source dest #chars

but it is difficult to do much better with the simple standard Forth
input parsing.  (Look at an approach to a more powerful parser in the ForST
source file XPARSE.S.)


Integer and floating point (real) arithmetic

After ldfloats.s has been loaded, you will have the option of integer
or real arithmetic, using the familiar arithmetic words:
        +, -, *, /, mod, abs, negate
as well as number and . (dot).  INT and FIX round a real number to an
integer value IN REAL FORMAT.  Forth kludge words like +!, 2+, */, etc.
work only with integers.  ADDTO is also a strictly integer operation.

You can select which mode you want with INTEGERS and REALS.  This is
very convenient, (look at the file TRIG.S) but I caution you that you must
not feed a real to a loop counter - it knows only about integers - and you
could find yourself in a near-infinite loop.  And if you try to feed a
real number as a count of ARGS or LOCALS, the compiler will become very
confused.  To get around this problem, when you are in REALS mode, you can
preface a number with the cast INTEGER, or (vice-versa) with REAL when you
are in INTEGER mode (see ForST file VECTORS.S).


System vectoring

The arithmetic modes illustrate vectoring of a number of words.  The vectors
are at the top of the assembly source file SHELL.S.  The above arithmetic
words are, in fact, VECTORed words with compile-time bindings (cf DEFERed
words with run-time bindings, described in Part 5 of the FD series) and can
be used to enhance the system.  A new definition of WORD is provided (in
ForST source file XPARSE.S).  It can be installed into the ForST system by

        HEAD NEWWORD IS WORD

AND its performance is scarcely distinguishable from that of the original
system word.


Environments

The present version of ForST allows command line re-entry (by pressing
the UP arrow BEFORE any other key).  The line can be traversed with LEFT
and RIGHT arrows (to either end with ctrl-arrows) and back space is
permitted anywhere in the line.  This simplifies the correction and
re-entry of a command line.  The assembly source is in SHELL.S and EXPECT.S.

ForST offers a pretty fair command-line environment, but there is one thing
missing: an editor.  I have to confess that I'm bored with writing editors
(I wrote several in the early days of Forth for the Tandy Color Computer),
and that I am impatient with bad ones.  In any case, I have a philosophical
thing about ignoring good tools which are already available.

I have been using ForST for months from inside the excellent DevPac 2
editor shell and find it pretty convenient to flip between editing and
testing operations.  Even better is the Tempus 2 editor, which handles
four open files and provides a really good shell.  Protext can also be
used, but stops key autorepeat and plays around with the screen display.
Many other shells can be tried: the Beckemeyer MT C-Shell is great, if
you like a CLI, and the Megamax Laser C shell also works (but is rather
unstable).  One thing is certain: Forth will not be accepted until it
can be shown to work with other software.  This is a case in point.

Another way to this end is

        RUN <filename> <switches>

is provided to allow running of other programs from inside ForST.  I have
enjoyed using Unix utilities, such as grep, inside ForST.  This will work
only for non-GEM ('vanilla') programs.  The assembly source for RUN is in
FILES.S.

I have experimented with using the STWRITER ELITE editor from inside ForST,
but it is not a convenient solution to the editor problem because, to get
ASCII files, it is necessary to print text to a file, rather than just
save it.  (The main problem is a small header with 'DO' in it.)


Registers and their use

        1. System registers:

        a4:     stack frame pointer (for locals)
        a5:     code base pointer (all addresses are
                reckoned as OFFSETS from this value
                as explained below)
        a6:     data stack pointer
        a7:     return stack pointer
        d6:     loop counter (gives I for DO ... LOOP
                and used to hold the comparison value
                in a CASE construct)
        d7:     loop limit (gives I')

2. Registers for user variables:

        These are described in Part 4 of the Forth Dimensions
        ForST series.  The compiler generates code to save
        and restore them as necessary.  The registers are
        allocated in a fixed order:

                a3, a2, d5, d4, d3, d2

3. Scratch registers:

                d0, d1, a0, a1

        These are used in Forth primitives, and are available
        for low-level use.  It is the user's responsibility
        to look after their house keeping.  Their advantage
        is that they are not automatically saved and restored,
        and tighter code can be generated.  Examples are given
        in the ForST file REGS.S.


Addresses

Because ForST is assembled in PC-relative code, and will operate
anywhere in memory, all internal addresses are stored as offsets from
the base address in register A5.  OS> converts an offset to an address
and >OS does the opposite.

CP (code pointer) and HP (header pointer) are two system variables
which contain offsets and, for convenience, the actual addresses are
given by HERE and THERE, respectively.

Internal addresses should always be stored as offsets.  Otherwise, if
code is saved and reloaded in a different location, they will be
incorrect.  A permanent external address, such as a ROM location, can
be handled in the usual way.


Headers

These are described in Part 4 of the FD articles and field address
conversions are carried out by the word WHAT (used as WHAT <word name>.
Note that the cfa is returned by  HEAD <name> and the code address by
 ' <name>.  Because the headers are disposable, there is no way to
determine the cfa from the code address.  Of course, the cfa and pfa
contain address OFFSETS.  The ForST code for WHAT is in file WHAT.S.
It is not elegant, but pretty much describes the header fields.

Headers can, and should, be shed when they are no longer needed, but
remember to include a dummy word (like TASK) to subsequently allow you
to remove the associated code when you are finished with it.  Heads of
individual words can be removed by HIDE <word name>.  This complements
FROM, KEEP and PUBLIC (an example of their use is in the file LDFLOATS.S).


Saving the code image

The code and headers can be saved at any time by SAVE <filename>.  (The
file name can include a path on the presently logged disk.)  Before
doing this, you may want to adjust the amount of work space and space
for the return stack and heads by altering the values in WORK, STACK
and HEADS.  Look at the assembly files VARS.S and GLOBALS.S for all
the system variables.


Crashes

The TOS system is very robust and you will very rarely have to
reset, unless you are in the habit of doing quite crazy things.
If you try to access protected memory (addresses 0 - $7ff), or fetch
or store a word or long word at an odd address, you will be thrown
back to the desktop.  ForST has not included protective code to let
you do these (unnecessary) things: it would slow everything down too
much.  Two bombs mean you are tying to access protected memory; three
bombs mean you are trying to access an odd memory location for a two-
byte or four-byte value and four mean that you are trying to execute
garbage code.


I/O redirection

This is available from words in REDIR.S:

        1. file> <filename> will get input from a file, but it is simpler
           and safer to use load <filename>

        2. console> resets to input from the keyboard after using file>

        3. more usefully, output can be directed to a disk file by

           a. >file <filename>, whereby output intended for the vdu is
              sent to the file; or better

           b. >tee <filename>, whereby output is sent to BOTH the vdu
              and the file.

           c. >console, which closes the open output file and returns
              output to the console.
           This is useful for getting a file of available words:
              >tee words.lst  words  >console
           Another example is:
              >tee dir.hex <cr> (open the output file)
              dump dir <cr> (dump the word 'dir')
              <now keep a key depressed until $4E75 (RTS) is printed,
               then press (ESC)>
              >console <cr> (close file)
              print dir.hex  (to printer)

        4. print <filename> sends a file to the printer.  The same
           result can be obtained with:
              copy <filename> prn:
           In this case, the copy is made to a temporary file, which
           is then sent to the printer.
           (The 'hardware files' are PRN:, CON: and AUX:)


Forth source code files

Apart from internal nuts-and-bolts details, ForST can be used very much
like 16-bit Forths.  Illustrative source files of extended Forth style
are provided.  They have a .S extension, because the editors I have used
(DevPac and Assempro) like their files that way, but .FTH would probably
be a better choice.  All the files provided (from DevPac) include tabs
and will look a little strange with Assempro (which expands tabs to spaces).

Any editor can be used, provided it can generate vanilla ASCII files.
The built-in version of WORD converts all tabs, carriage returns, line
feeds and nulls to spaces to provide maximum compatibility (see SHELL.S
file).  Automatic conversion is made to upper case.

Full source is provided.  I would appreciate criticism (constructive
is preferred!) and suggestions.  I hope that the comments will go a
fair way towards providing the documentation that I am too lazy to write.
There are quite a few words which have not had their headers included,
but these can be added quite easily (but be sure that they are assembled
into DATA space).

In the main, related code has been localised.  I/O, for example, has
been confined to IO.S and FILES.S.  An overview of the particular files
is in BULLETIN.S and a glossary of new words in GLOSSARY.LST.  It should
be pretty easy to adapt ForST to other 68000 systems.

Using the DevPac ST2 assembler, the basic ForST system can be reassembled
very quickly (about 20 seconds from a hard disk and 60 from a floppy).
This just has to beat the gymnastics of metacompilation.  I used the
cheaper Assempro system earlier in development.  It is acceptable, but
much slower and makes testing difficult - and there are a few file
incompatibilities.


Feedback

I would be delighted to hear from users.  Callers from outside
Australia please remember that Sydney time is 9 to 11 hours ahead of
GMT (depending on time of year).  I am very grumpy when woken in the
middle of the night.  On this basis, the best time to call is 9 am
to 11 am, GMT.




Good luck,

John Redmond,
23 Mirool Street,
West Ryde,
NSW 2114,
Australia.
Phone [phone].