PandaForth by Torlus (c) 2005 - http://torlus.com/
Based on Bradford J. Rodriguez's CamelForth for the Z80 (c) 1994

===============================================================================

0. Release notes for GP32 version
1. About Forth 
2. About PandaForth
3. Contents
4. Running PandaForth
5. Building PandaForth
6. Advanced topics
7. Credits

===============================================================================
0. Release notes for GP32 version
===============================================================================

The original port of PandaForth was for GBA, and used a multiboot cable. This
version uses USB, with the help of Harry Denholm (http://www.ishani.plus.com)
who provided an example of USB source code, and nicely allowed me to use it.

I must say that I've been a bit lazy concerning this port. I could have added
some extra features, like loading of source code from the SMC... I could also
have made a small demo but well, it is not the case. If you feel interested 
by such features, in the opportunity of really doing something with PandaForth,
maybe I could help.

If you don't care about Forth, but have downloaded this, two things can still 
be useful :
- The USB code. I modified Harry Denholm's code to handle bidirectionnal
  communication with PandaForth interpreter. The code is easy to understand,
  it might be useful if you have projects in mind that could use USB.
- The Makefile. It is based on WinterMute's ones, that are well-written and
  powerful. So this project is a rather good "template", using GamePark SDK,
  DevkitARM (and not one of those outdated toolchains you can find), showing
  how to compile automagically resources into your project, without batch 
  files, or whatever. 

===============================================================================
1. About Forth
===============================================================================

If you don't know what Forth is, http://www.forth.org/ is a good starting point.

Basically Forth is a stack-based language using "reverse polish" notation. 
It provides an interpreter which is able to be extended with new definitions. 

Unlike BASIC interpreters, new "definitions" (or "functions", Forth users 
generally talk about "words") are _compiled_ which means that there is no 
difference in performance between newly created words, and the original ones 
provided by the interpreter (except for those few written in assembly).

Forth is a kind of (unmanaged) virtual machine. Unlike Java virtual machines,
a Forth engine is very simple and will usually fit in less than 10Kb 
(yes, "ten. kilo. bytes." :)). For design considerations about Forth, I highly 
recommend Bradford J. Rodriguez's publications about them. 
Check his site at http://www.zetetics.com/bj/papers/.

===============================================================================
2. About PandaForth
===============================================================================

PandaForth is a Direct-Threaded-Code 32-bits Forth, written in ARM assembly. 
A few part of the source is in C, in order to use WinterMute's libgba functions, 
but not for Forth implementation itself. It should be not too far from ANS-Forth
compliance, for the wordset at least.

One of its funniest features is that you can use the interpreter directly from
your computer through USB, using a Windows application designed for it.

===============================================================================
3. Contents
===============================================================================

The archive contains the following folders :
source/                        PandaForth source (C,asm)
source/cam80-12                CamelForth for Z80
gpSDK/                         GamePark SDK
client/                        Source and binary for the Windows application
			       The Windows binary is called GP32DeMon.exe 
			       and can be found in /bin/Debug
				
At the root of the archive, you will find :
Makefile		       	Guess what?
PF4GP32.fxe			Ready to be installed on your GP32
                               
===============================================================================
4. Running PandaForth
===============================================================================

Start the FXE, then start GP32DeMon.exe. It should show up :

-=[ PandaForh ]=- by Torlus

This text comes from your GP32 :) Now you can use the interpreter, for instance
type WORDS followed by a carriage return, and you will get a list of available
Forth words of the system.

===============================================================================
5. Building PandaForth
===============================================================================

If you didn't unpack the archive to C:\GP32 as I suggested on my website, do it,
as some paths are absolute.

You will need to have the DevkitARM toolchain (I used r11), and MSYS. All these 
items can be found at WinterMute's site at http://www.devkit.tk/.
With a PATH variable properly set up (C:\DevkitARM_r11\bin;C:\msys at the 
beginning), you can run the "make" command to rebuild the current FXE.

===============================================================================
6. Advanced topics
===============================================================================

* Emedding resources.

To make some resources (bitmaps, etc.) available to PandaForth, a simple and dirty
way is to create a VARIABLE pointing to them, and use .incbin to include them.
Open the "PF.s" source file, and go at the end of it.
You will see the following lines :

8<-----------------------------------------------------------------------------
# last word from PFH.asm is COLD

.set lastword, link_COLD		/* last word */
8<-----------------------------------------------------------------------------

You can insert your declaration like this :

8<-----------------------------------------------------------------------------
# last word from PFH.asm is COLD

   head SMILE,3,"8=]",dovar,COLD
.incbin "C:/absolute/path/to/your/file.bin"
.align

.set lastword, link_SMILE		/* last word */
enddict:
8<-----------------------------------------------------------------------------

the "head" macro adds an entry to Forth dictionary. The parameters are :
- label name (a name which format is correct as a label name for the assembler)
  here : SMILE
- the length of your word (here :  8=] which is 3 characters long)
- the name that will be used within Forth (here :  8=] )
- the name of the previous label (here COLD, that was previously the last word).

The "lastword" definition needs also to be changed to point to link_SMILE.

In PandaForth, executing 8=] will push the address of the beginning of your 
resource onto the parameter stack.

This solution isn't very good, a better solution can be achieved by extending
PandaForth (see below).

* Extending PandaForth.

PandaForth is very close to CamelForth. I kept the BDOS word (CP/M function call),
which is hooked up to a C function called "service" (see the file "gpmain.c").
BDOS take two parameters : one "service number" and one parameter.

Two service numbers are currently defined :
- 6, used for reading and writing to the console (used by the interpreter).
- 1, that waits for a vblank interrupt.

It's easy to add new functions here. The return value of the function will be
available from Forth in the parameter stack.

===============================================================================
7. Credits
===============================================================================

Many thanks to :
- Bradford J. Rodriguez, for his CamelForth and articles about Forth.
    http://www.zetetics.com/bj/papers/
- Harry Denholm, for the USB code (both on GP32 and Windows)
    http://www.ishani.plus.com/
- WinterMute, for DevkitARM, libgba, xboo, and clean Makefile.
    http://www.devit.tk/

And greetings to people on EFNET #gp32dev !

Enjoy,

Torlus

