Re: VM02 Beta 1

[David Schmenk <dschmenk@YUCH.gmail.com>]

... I'm having a bad text-formatting day.  I'll try that README again:

VM02 Java capable Virtual Machine for Apple II 
==============================================

Introduction:
-------------
VM02 is a Java compatible environment for the Apple II series of 
computers. Most basic features of a Java VM are implemented to allow 
direct execution of standard Java class files.  However, in order to fit 
in the constraints of a 64K, 8 bit, 1 MHz computer, some aspects of a 
JVM have been reduced or removed.

What is implemented:
- Standard Java class file loading and execution.
- Full object inheritence
- Multithreading (4 threads max by default)
- Exception handling - Arrays up to 15 dimension
- 32 bit integers and single precision floating point
- Garbage collection
- Finalizers
- Software and hardware implemented timing
- Device drivers for common hardware

What is missing:
- 64 bit data types unimplemented
- Standard class library missing or limited implementation
- Lots of memory

Running VM02:
-------------
VM02 is run by executing the JAVA.SYSTEM file.  You must start 
JAVA.SYSTEM from the prefix where it exists.  This is required to find 
the class base path to the support classes.  Parameter passing is 
supported if your shell implements it. If no paramter is passed in and a 
file named STARTUP exits, it will be loaded as the initial class. 
Otherwise, you will be greeted with with a prompt to type in the class 
name to execute.  You can start classes in other directories by typing 
in the fully qualified path. Class filenames under ProDOS are missing 
the ".class" suffix due to limited filename lengths.  For example, to 
execute the Hello.class file on the VM02.SAMPLES volume, with VM02 you 
would type:

/VM02.SAMPLES/HELLO

at the "Main class:" prompt.  You would see this:

Main class:/VM02.SAMPLES/HELLO

and then VM02 would attempt to find and load the class file.  If an 
error occurs along the way, you will get an Unhandled Exception message, 
probably because the file (or superclass file) was not found.  The 
preferred directory structure is to place all classes as subdirectories 
of the main VM02 directory.

Implementation of VM02:
-----------------------
VM02 is implemented from scratch in 6502 assembly, optimized for the 
6502 and Apple II platform.  The entire VM fits in about 20K of RAM. 
This leaves about 30K of RAM available for data and code.  Not a lot, 
but Java was defined for small platforms so you can get some reasonable 
programs even in such a small space.  A high-resolution graphics page is 
available for use with small programs.  Performance is acceptable for a 
1 MHz, 8 bit CPU.  On par with the UCSD p-System VM used in Apple 
Pascal.  All features of the Apple II are made available through either 
specific classes, a low-level class that can call ROM routines, or both. 
 There is a device driver architecture that currently supports 80 
column cards, the Super Serial card, and the Apple Mouse card.

As noted earlier, class filenames are missing the ".class" suffix. 
System classes are in the JAVA/* subdirectories.  Apple II specific 
classes are found in the APPLE2/ directory.

Developing for VM02:
--------------------
There isn't a native Java compiler for the Apple II (yet).  All Java 
source must be cross-developed on a capable computer.  The resulting 
class file needs to be transferred to an Apple or emulator using any 
number of available tools. One way is to use a tool like a2tools, 
AppleCommander, or CiderPress to copy the class file to a .DSK disk 
image file.  The disk image can be run directly from an emulator or 
copied to real hardware with ADT or ADTPro.  To compile against the 
Apple II specific classes, either download the source package (you will 
also need cc65, the 6502 C compiler package) or copy the APPLE2/ 
directory contents and rename the files with mixed case and add the 
.class suffix.

The sample classes:
-------------------
Included with VM02 are sample classes that show off the capabilites of 
the environment.  They can be executed from the samples disk or copied 
to another location.

HELLO - A simple text entry program
HELLOWORLD - sample multi-threaded program
MOIRE - Hires example, requires AppleSoft in ROM
HIRESDEMO - Another hires demo
RODSCOLORS - Lores demo
SIMPLEPONG - Lores demo with paddle input
TERMINAL - Simple terminal program using the SSC
LIST - list a text file to the screen
P8 - ProDOS example
APPLE2/MOUSE - AppleMouse class with interactive test

Beta1 release:
--------------
This represents the first Beta release of VM02. All the VM functionality 
is in place.  Some support classes may be extended or implemented to add 
compiler features or improve compatibility.  This is pretty solid for 
small programs but Java is a large and rich environment.  No doubt there 
will be many issues crop up.

Known issues:
-------------
Currently two know issues are exist; the StringBuilder class has 
problems that cause string concatentation to freak out. I'll be looking 
into this shortly. In the mean time, try alternative methods (like 
individial print() calls to print a compound message).  The Super Serial 
Card driver has problems with XON/XOFF flow control.  It might be a 
problem with my USB serial dongle.  I tried hardware flow control, which 
worked except charaters would get truncated when it halted the receiver. 
 XON/XOFF should work, but doesn't on my setup. I'll try to connect to 
a real serial port on a Linux box to see if it works any better.

Dave Schmenk...