-------------------------------------------------------------------------------

			      PilotForth

      Copyright (C) 1997, Ivan A. Curtis.  All rights reserved.

			       based on
 C-FORTH: a portable, C-coded figFORTH interpreter by Allan Pratt April 1985.

 This program may not be redistibuted in part or in whole without this
 Copyright Message being included at the top of each file.

   This is free software, licensed under the GNU Public License V2.
		  See the file COPYING for details.

-------------------------------------------------------------------------------

1) NOTICE

README for PilotForth v0.1

This is a very early version of PilotForth, a forth system for the US
Robotics Pilot handheld computer. Please do not distribute this
version indiscriminately. It is not yet ready for general distribution
to end users. I am making this release for people interested in
contributing to the development.

If you are interested in contributing, please contact me (Ivan Curtis)
via email icurtis@radlogic.com.au

I will co-ordinate the effort and keep a central up-to-date code
reference.

2) CURRENT STATUS

Here is where the project is with this release:

The application consists of 1 Pilot resource and 2 databases.

Forth.prc is the resource file, and contains the user interface,
execution engine, primitives and memory/block management routines.

VocabDB.pdb is a pilot database containing the initial vocabulary.
Most of the system is written in FORTH in terms of a (relatively)
small number of primitives. The bootstrap compiler 'nf' is used to
compile this vocabulary.

BlockDB.pdb is a pilot database containing the disk blocks which can
be accessed by the program.

The Makefile in the bootstrap directory describes pretty well how
these databases are made.
 
AT THIS STAGE IT WOULD BE GOOD TO READ forth.doc IN THE bootstrap
DIRECTORY. This is the documentation file for the original c-forth
system. Some of it no longer applies, but it is mostly pretty
accurate.

3) COMPILING & RUNNING

I am currently developing using prc-tools-0.4.1, although I intend to
change to 0.4.2 real soon.

The file conio.c replaces conio.c in libc. It implements an
un-buffered putchar().

Other than that, you will probably need to touch some of the paths in
the Makefile. Then a make all should make the .prc (and the .pdb files
in the bootstrap directory).

4) PROBLEMS

4.1) ENDIANNESS

That perennial problem. I use a little Endian system, so when
forth.core is built, it is not binary compatible with what the pilot
expects. buildpdb has a switch which allows one to swap bytes in words
to take care of this. If your system is BIG Endian, you don't want the
swap.

I think buildpdb will create the header OK regardless of the type of
system it is run on.

4.2) SPEED

The interpreter is slooow... This is fundamentally due to the
DmWrite() system call, which bounds checks every write to a database
record.

One thing that must be done is to move the stacks and keyboard buffers
out of the database and into dynamic memory, to allow them to be
directly written to.

4.3) WORDSIZE

All memory in c-forth is 16-bits wide (YES EVEN characters!). So C@ is
the same as @. This will mean changing some of your existing forth
code...

5) THINGS TO BE DONE

5.1) Move the stacks etc. into dynamic memory. I will be working on
this next, so no need for anyone else to start this.

5.2) A simple editor for the block database so that it could be edited
on the pilot would be nice. I originally thought of using ordinary
memos in a particular category, but these suffer from the fact that
they are not a fixed size. It should be possible to build a simple
editor in a few K.

5.3) fix fth_callot so that is allows the dictionary to grow.

5.4) More robust error handling. Allowing errors to re-enter ABORT
would be nice.

5.5) Testing. I do not have much forth programming experience (to be
honest, almost none), so I do not have a pile of forth code lying
about to test on this.

Ivan Curtis (icurtis@radlogic.com.au)
Adelaide, South Australia 16-May-1997
