Java4gba : Java Virtual Machine for GBA by Torlus
=================================================

More precisely : Java4gba, a Sun's CLDC 1.1 RI KVM port for GBA by Torlus (http://heliscar.com/greg/)

This is an early port of Sun's KVM Java Virtual Machine for GBA. 
KVM is the Java VM you may find in mobile phones for running "Java games".

If you are unfamiliar with J2ME (Java 2 Micro Edition), here is a small explanation about its 
architecture (roughly).

   KVM <------------  CLDC 1.1 <------------------ MIDP 2.0 <------------------ Java Game
    |                   |                              |                            |
 the virtual        limited set of            more advanced set               running on top
 machine            java classes              of classes featuring            of MIDP
                                              graphics, sound...
                    
This small work is only about CLDC, which means that there is nothing about graphics,
sound, or whatever. You can only do some plain console output. Sorry, guys :)
However, it brings to GBA almost all Java interesting features like Exceptions, Threading, 
Monitors...

You will find some examples that illustrate these Java features. Just run the examples.bat 
script to build some example ROMs (you don't necessarily need a Java compiler, but it is 
recommended, especially if you want to play with the VM :))

Well some details about this port :
- It has been compiled with "ROMizing" option, which means that all CLDC classes are already 
  in the VM, so you don't need to add them in your GBFS file (see about GBFS below)
- It has been compiled with KNI and float support, but the float support is broken. I still
  haven't tested the KNI part.
- The VM heap size is 64K.
- It uses GBFS, a GBA file system implementation by Damian Yerrick.
- JAR support has been compiled in, but at the moment, you can't use it (see below).
- I had to disable the class verifier, which unexpectedly fails (even on "standard" platforms)
  when verifying some classes that perfectly works. I'll try to dig a bit around that.
- Source code will be available, as soon as I clean it up (especially for having a good
  separation between everyone's stuff, as all code snippets are under different licenses)
- In the code, almost all architecture-related stuff has been isolated. That means that it 
  has basic implementations for about everything that you would expect from your operating
  system, or C library (memory allocation, file system...) functions. That also means that
  you can virtually port it on every kind of architecture.

Some functions come from code of Justin Armstrong's JaysOS.
JaysOS is a mini-OS for GBA, that comes with a port of Waba virtual machine.
The main difference between Java4gba and JaysOS is that JaysOS provides underlying functions
allowing multiple programs (C or Waba ones) to run. Here Java4gba is only the Java Virtual Machine.
JaysOS allow multiple executions of single-threaded Waba VMs (Waba doesn't support threading
at the moment... hmm I think I just have found my next project idea :)), although Java4gba runs
"alone" but provides Java threading. Well maybe Java4gba could run on JaysOS too, and we'll get
the best of both works :)
    
About GBFS (and how to use it with the VM):
===========================================

GBFS is a GBA file system implementation by Damian Yerrick. Basically, you create an
archive containing your classes files, with the "gbfs.exe" tool provided, and you
just append it to the "kvm.bin" file, to create your ROM (see the examples.bat file).

So the basic steps to test your own Java programs are :

- Compile them with a java compiler

    Ex : javac OneClass.java
         javac OtherClass.java
         javac MyMainClass.java

- Create a GBFS archive with the .class files generated.

  IMPORTANT : the first class in the GBFS archive must be the one that contains
  the "main" function !!! ( protoype : public static void main(String [] args) )

    Ex : gbfs.exe MyGBFSArchive.gbfs MyMainClass.class OneClass.class OtherClass.class

- Finally append to the "kvm.bin" file, the GBFS archive you've just created, into a new
  file that will be your final ROM.

    Ex : copy /b kvm.bin + MyGBFSArchive.gbfs MyJavaROM.bin

IMPORTANT : GBFS has some limitations :
- The file names should not exceed 23 characters (".class" extension included)
- There is no support for directories.

What's Coming Next ?
====================

This project is a preamble work for some other stuff I plan to do. But this stuff won't be
for GBA. As Justin said, I also think that Java for GBA isn't really a good idea.
So don't expect a MIDP port for GBA (from me)...

But there are a few things I will certainly do on this project in the next weeks :
- Enhance (or replace) GBFS in order to have longer file names and support for directories, and
  then support for JAR files could be easily added.
- Add a small set of GBA-specific classes (for example, basic sprite & background handling).
  They will show how the VM can interact with the underlying system.
- Have a look at float support.

Source code will follow as soon as possible. I think it can be a not-too-bad example of how to 
begin a Java port to other handheld gaming devices, more powerful, and for which such a work 
may be interesting... Maybe GP32, or upcoming handheld devices ?

Hope you'll like it.

Torlus.



Credits
=======

- Damian Yerrick for his GBFS.
- Justin Armstrong for his JaysOS.

Links
=====

 - Sun's pages about J2ME : http://java.sun.com/j2me/index.jsp
 - Justin Armstrong's JaysOS : http://www.badpint.org/jaysos/
 - Damian Yerrick's home : http://www.pineight.com/
 - My own site : http://heliscar.com/greg/ 

