
                                  ZOG
                                  ----

       A ZPU Virtual machine running on the Parallax Propeller
                          micro-controller.                                      


What?    The ZPU is a 32 bit processor core architecture specified by ZyLin
         consultants for which there a number of HDL implementations
         for FPGA's.                                                

Why?     ZyLin have targeted the GCC C Compiler to the ZPU instruction set.
         ZOG makes it possible to use GCC for Propeller development.      
         All ZPU instructions are a single byte, which should work out     
         nicely when the code is placed in external RAM with an 8 bit bus. 

Credits: Based on an original idea by Toby Seckshund.                      
         Maths routines courtesy of Cluso and Parallax.                    
         Encouragement courtesy of Bill Henning and all on the Parallax    
         Propeller discussion forum.                                       

Author:  Michael Rychlik    

v0.1     09-02-2010 First draft, totally untested.

v0.2      18-02-2010 Tested and fixed up initial bugs.
                     Runs first test program compiled with GCC.
                     Has no I/O yet.    

v0.3      19-02-2010 Fixed mysterious "inversion of bit four of offset" problem
                     with LOADSP and STORESP.

v0.4      20-02-2010 Added primitive UART output such that the C run time
                     routine outbyte() works. Zog now says hello!

v0.8	  18-04-2010 Rewrote all the ZPU ops using optimizations as
                     suggested by Bill Henning. 

v0.9      15-04-2010 Added some optimizations (tailored to  FIBO :))
                     Added RC4 test (Fails just now)
                     Fixed PUSHSP op.

v0.11     09-05-2010 Changes endianess of bytecodes in zpu_memory
                     Adjusted read/write byte/word and instruction fetch inline with endianness
                     Fixed ADDSP.


v0.12     11-05-2010 The ZPU_EMULATE op now works. If it's ever needed.
                     Fixed MOD and DIV instructions.
                     Inlined read/write_byte
                     read/write_word are EMULLATED for now as their endiannes is not right yet.
                     ZPU memory is 20K bytes (Until we put SD and VM COG back in).

v0.13     14-05-2010 Fixed endiannes of strings output by SYS_write syscall.
                     Return a zero result from SYS_fstat syscall.

v0.14     08-06-2010 Take Bill Henning's VMCog into use for external RAM access.
                     Added #ifdef USE_VIRTUAL_MEMORY

v0.15     15-06-2010 Fixed zpu_addsp to work correctly with virtual mem read_long.
                     Added reading of a ZPU image from SD card file.
                     Runs dhrystone by default (dstone.bin)

v1.1      17-08-2010 Zog is now broken out into a spearate spin file with minimal spin code.
                     debug_zog.spin now contains the spin support for zog I/O via ports and SYSCALLS.
                     run_zog.spin is now a minimal zog loader with no I/O.

v1.2      17-08-2010 No changes here but all make files for ZPU executables now perform
                     and endianness swap on the binaries as byte swapping is not done here anymore.



Zog can run ZPU programs from HUB memory or from external RAM using Bill Hennings VMCog.
Has been tested on a TriBlade board (blade #2)

Set USE_VIRTUAL_MEMORY or USE_HUB_MEMORY to select HUB or external RAM useage.

External RAM execution is about 10 times slower.

Currently Zogs executable binary is included from a "file" statement. It uses a serial linkfor user interface so should work on any Propeller board with BST or other terminal program.

The "test.bin" file included in the ZPU memory area is created with
GCC for the ZPU.


Please see the Makefile included with Zog for how to build C programs
with GCC for the ZPU architecture that Zog can run.


Generally it goes like this:

First compile for the "phi" platform with size optimizations and "relaxed" linkage.

$ zpu-elf-gcc -Os -phi  -Wl,--relax -Wl,--gc-sections  -o test test.c

The extract the binary:

$ zpu-elf-objcopy -O binary test test.bin

Recerse the endianness of the binary file:

$ objcopy -I binary -O binary --reverse-bytes=4  test.bin

If you want to see what's in there disassemble with:

$ zpu-elf-objdump -d test

