From GameBrew

AuthorJustin Armstrong
Last Updated2002/05/03
TypeOther apps

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

User guide


It includes 3 small 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.

The Shell

This was only tested with the MBV2 cable, but it should works similarly with homebrew serial cables too (no emulators simulate the serial port, so you will need a real GBA for this).

Set up your terminal software to 9600 8N1 ANSI mode (tested 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".

Now type "U" until you see a message welcoming you to JaysOS. If it doesn't work try "rebooting" your GBA and trying again.

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> - Send 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> - Dump to the terminal the contents of the specified file.
  • breakout - Start a game of breakout.
  • life - Start Conway's Life.
  • stats - Start an app that displays some statistics.
  • waba <path_to_classfile> - Start the Waba VM (see waba/README.jaysos).
  • uname - Print the version.
  • uptime - Print the time elapsed since the GBA was switched on.


Start - Pause/Unpause apps (Life and Breakout)

Left/Right - Move the bat (Breakout)

A - Start simulation (Life)

L/R - Change active window




Release 0.2.1 2002/09/18

  • 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 2002/08/09

  • 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 is an unofficial Java VM and set of class libraries. Information on the waba port is in the file waba/README.jaysos.


Jeff Frohwein for running, inventing the MBV2 cable, maintaining the FAQs, etc.

Forgotten for the VisualBoyAdvance emulator.

Adrian O'Grady for the "zx" font. His uart code was very useful too.

Damian Yerrick for GBFS.

Tom Happ for writing the CowBite Spec

All the people who figured out how the GBA works and then wrote it down.

Rick Wild for writing Waba, and everyone who hacked on it since.

External links