JaysOS 0.2 & Waba VM for the Gameboy Advance

by Justin Armstrong <ja at badpint.org> 3 May 2003

jaysos screenshot

CHANGE HISTORY

Release 0.2.1  18 September 2002

* moved all static data into IWRAM, EWRAM is now
  used entirely for the heap
* line drawing is now clipped to inside the window

Release 0.2.0  9 August 2002

* Now has a malloc
* Threads can now have "thread local storage".
* Threads can now have a destructor callback function,
  that runs when the thread dies to carry out any needed cleanup.
  Mainly used to delete thread local storage.
* Added a printf and more handy libc functions (from NetBSD mostly)
* Rolled in Damian Yerrick's GBFS
* Added an "alarm" (aka "timer") mechanism, which
  allows a callback to be registered to run at some point
  in the future.
* Breakout and Life allocate their locals from
  the heap, and so you can have multiple instances
  running.
* Added a few more shell commands
* Renamed gbacrt0.s to lowlevel.s because it
  contains a variety of asm code and not just the
  setup code you'd expect to find in a crt0.s
* Ported the Waba VM to Jaysos
  - Waba (http://waba.sourceforge.net) is an unofficial
    Java VM and set of class libraries.
    Information on the waba port is in the file waba/README.jaysos

1. INTRODUCTION

1.1 WHAT IS IT?

JaysOS is a "toy OS" that runs on the Gameboy Advance.
It provides preemptive threads, semaphores,  condition variables, and message queues.

I've included 3 fairly lame demo "apps": a breakout game,
a version of Conway's Life, and a cpu usage displaying app.

As of 0.2, it also includes a port of the Waba VM for Java bytecodes.
Waba comes with a few interesting demo applets you can try out.

JaysOS apps interact with the world using the "UI Manager", which is in charge of
* keeping track of window sizes
* running a redraw thread
* dispatching events to message queues

There is also a "shell" app, which works over a serial connection (e.g. MBV2 cable),
and allows you to control what is going on using simple commands.

As the ARM7TDMI has no MMU, JaysOS can't provide seperate address spaces for "tasks" like
in a real OS.

Another limitation of JaysOS is the lack of proper system calls.
In most OSes, user apps communicate with the kernel through software interrupts.
Unfortunately in the GBA the BIOS traps all software interrupts and handles them itself, so
they can't be used to call into JaysOS.  Apps have to call kernel functions directly.

As of version 0.2.0, there is a heap manager, but it is only used by the apps. 
The kernel itself uses only statically allocated data structures.

Static memory allocation means a lot of things are fixed in JaysOS.
There is a maximum of 32 threads for instance. 

1.2 WHAT IS THE POINT OF THIS?

None really, other than my own amusement and education.

JaysOS is not meant to be useful or to represent my idea of how a real OS should work.
Design decisions were made based on whatever I felt like having a go at that day.
(note to potential employers: in real life I don't do this ;)

Hopefully it might serve as a basic introduction to operating systems, or as a simple threading system for GBA apps, or you might even be able to use parts of it for embedded applications.  I've tried to make the code as simple as possible.

Feel free to steal any bits of code that might be useful to you.

2. TRYING IT OUT

2.1 Controlling The Apps

You control the apps running under JaysOS with the buttons on the front of the GBA.
The Start button pauses/unpauses apps that support pause (Life and Breakout)

The Breakout app works like you'd expect - move the bat left and right
and try to keep the ball in motion.
I haven't bothered to implement different levels, score or anything fancy.

The only control the Life app has is the A button, which can be used to restart
the simulation with a random arrangement of cells.

As you can only control one window at a time, the UI Manager has the
concept of an "active window".
The active window is the only one which receives button events.
The active window is drawn with a blue border.

You can change the active window by using the buttons on the top of the GBA marked "L" and "R".




The Life app window is active
The Breakout window is active

2.2. The Shell

(No emulators simulate the serial port, so you will
need a real GBA for this!)

I have only tested it with the MBV2 cable, but i would imagine it works
similarly with homebrew serial cables too.

Set up your terminal software to 9600 8N1 ANSI mode.

(I've used it with minicom on linux and Zterm on MacOS X - using a keyspan USB->serial adapter)

Turn on the GBA.
If you are using the MBV2 type "C" (on your PC) a few times
while the Gameboy logo is displaying until it prints "Coded by Jeff Frohwein".
That is actually coming from the MBV2 and is nothing to do with me. 
Now type "U" until you see a message welcoming you to JaysOS.  
If it doesn't work try "rebooting" your GBA and trying again.

2.2.1 Recognised Commands:

You can type "help" to get a list of recognised commands.
Currently this is
ps - list all threads running  
queues - list all msg queues registered with the UI Mgr
kill <queue_name> - sends a MSG_QUIT to the specified msg queue
mem - show the heap statistics
ls - list all files in the GBFS archive
print <path_to_text_file> - dumps to the terminal the contents of the specified file
breakout - start a game of breakout
life - start Conway's Life
stats - starts an app that displays some statistics
waba <path_to_classfile> - start the Waba VM (see waba/README.jaysos)
uname - prints the version
uptime - prints the time elapsed since the GBA was switched on


2.2.2 Example usage:



1. After the demo starts, 4 apps are running:
Life, Breakout, Stats and Waba running ImageView



2. The "queues" command shows the msg queues registered
with the UI Manager: "life4, "breakout5", "waba" and "stats".
We kill the Breakout app with the command
"kill breakout5".  Now there are only three apps running



3. "kill stats" and "kill life" leave only the Life app
running.


4. "waba CoreTest/CoreTest" starts waba running
the CoreTest applet.


You get the idea...


If you don't have a serial link, you can try running different combinations
of apps by changing which ones are started in main.c and recompiling.

3. Waba

Waba is an unofficial implementation of a Java VM, originally written by
Rick Wild of Wabasoft.  It is small, simple and highly portable. It uses
its own class libraries which are similar to, but not compatible with,
"official" Sun standards (like J2ME).
See waba.sourceforge.net and www.wabasoft.com for more on Waba.

Waba is started from the JaysOS shell with the command "waba" followed by
the path to the main classfile (not including the ".class")
Try these:
waba CoreTest/CoreTest
waba ImageSplit/ImageSplit
waba PocketWatch/PocketWatch
waba ImageView/ImageView

You can only have one instance of waba running at a time.
Waba can be stopped with the command:
kill waba


The README tells you everything you need to know.

4. Further details

See the included README.

5. Download

here

6. Links

Wilhem Meignan has developed a derivative of JaysOS, called ISOS, for his robotics projects.
Check it out! http://wilhem.meignan.free.fr/