Phoinix, the free Gameboy emulator for PalmOS

by Bodo Wenzel
Home (downloads)
F. A. Q.
Old news
Compatibility of...
  free cartridges
  commercial cartridges
  colour games
How to...
  use the emulator
  convert cartridges
  make cartridges run ==>
  get in touch
  the history
  the future
  the playability testing
  skipping frames
  some accessories
  limits and extensions
Thank you for the cookies

This site is kindly hosted by SourceForge Logo

How to make cartridges run

As Phoinix just emulates a real machine, and does this not really perfectly, some games need patches. Some patches are mandatory to make a game run, others are only to correct graphical flaws, for example.

On this page: - IPS (International Patching System) - Available patches - Rana

IPS (International Patching System)

This patching system was suggested by several people, so I'll give it a try. The worst is the lack of checks for patching the correct ROM and for an unbroken patch file. You may find several tools for all common systems by asking your favourite web searcher.

Some time ago I found this fine Java application named "JIPS" at, and it looks fine.

Important note: Please apply patches before you convert the game for Phoinix. The provided IPS files don't work on the PDB files!

Last update: 2007-02-15

Available patches

If your problem is not addressed here, you may like to consult the mailing list for users.

The table shows only the patches for the changed functions. Since the checksum of the patched games changes, it has to be patched also. These bytes are not listed.

Name, sorted
(Link to IPS file)
Address Old values New values Comment
Banks n/a n/a n/a The MBC1 has to be switched into the correct mode (4/32). In the source file "banks.c" add the line "*(unsigned char *)0x6000 = 1;" after the line "ENABLE_RAM_MBC1;".
F1 Race 00:0028 FF FF FF FF 66 A7 18 04 There were no turns.
00:0030 FF FF FF FF FF FF FF FF F5 6C CB A7 CB A4 8C 07
00:0038 FF FF FF FF FF 65 6F F1 8C C9
00:00F3 FF FF FF FF FF FF FF FF 57 7C CB A7 4A CB A1 81
00:00FB FF FF FF FF FF 07 4F 19 7D C9
01:4CB2 86 EF
01:4CB6 F5 E5
8C F7
F5 E5
57 19 7D CD F3 00
F5 C5
GB Demo 00:002D 20 38 Again the interrupt system. Speed has its costs :-}
Harmony 00:0030 00 00 00 3E 80 C9 Phoinix interrupt system is too simple for this game. The screen flickers heavily without this patch.
F3 F0 18 05
00:1612 AF F7
Kirby 2 00:0070 FF FF FF FF FF FF FF FF 76 FB F5 3E 28 3D 20 FD No more blank screen, the game runs now. It was some tricky interrupt handling :-}
00:0078 FF FF FF FF F1 C3 46 03
00:034B 76 FB 18 F7 C3 70 00 00
Madden 95 00:0051 18 91 00 C3 E4 FF MANDATORY!
The old code jumps the 0000H/0FFFFH limit with a relative branch, that isn't emulated.
Metroid II 02:407C D0 00 Using power-ups let the game freeze.
02:4099 D0 00
Millipede/Centipede 00:0040 18 B8 00 C3 FA FF MANDATORY!
The old code jumps the 0000H/0FFFFH limit with a relative branch, that isn't emulated.
00:0048 18 A7 00 C3 F1 FF
00:0050 18 A5 00 C3 F7 FF
00:0058 18 9A 00 C3 F4 FF
Mortal Combat 3 00:0CC0 31 44 FF FA FC C0 57 FA F0 44 B9 20 FB FA FC C0 MANDATORY! Otherwise you'll lose all your data!
Tricky SP handling...
00:0CC8 FB C0 5F 21 87 44 F0 44 E0 43 FA FB C0 E0 42 3E
00:0CD0 B9 20 FB D5 E5 21 FD C0 33 E0 41 3E 87 E0 40 00
00:0CD8 2A 66 6F F9 00 00 00 00
Pinball Dreams 00:0E12 3E 02 18 07 Sound is switched off completely, making it run a bit faster and independent of the "Music" option.
PokéMon Red (1 MByte version) 0D:7282 88 87 Correct scrolling on the title screen and start of fight.
0F:40BC 40 3F
Qix Each:
F3 F0 18 0B Suppressed flashing text in game graphics on level change / game over.
R-Type 2 00:0971 80 7F Top line of status scrolled with background.
Sonic 6 00:3A65 0E 41 18 0A Once more the simplified interrupt system of Phoinix; it produced a white top line on the status.
Starfisher 00:0080 00 00 00 00 00 00 7B BE D0 FE 05 C9 MANDATORY!
The original game has a buffer overflow bug. The patch limits the number of enemies to five.
00:0AD1 7B BE DA BF 0A CD 80 00 38 E9
Tabaluga (German version) (several)     Note: far too many changes to show here, sorry.
Texts are shown with spaces, and the player sprite is correct.
Tetris 00:02F0 28 76 Runs much faster.
Tetris 2 00:23BD CD C3 Not necessary; the developers made a harmless error.
Ultima - Runes of Virtue (US version) 00:0008 FF FF FF FF FF 2B 70 2B 71 C9 Graphics were garbled.
00:0018 FF FF FF FF FF 2B 72 2B 73 C9
01:4A81 31 21
01:4A9B C5 CF
01:4AB9 C5 CF
01:4ABD 31 21
01:4AE6 31 21
01:4AFE C5 CF
01:4B19 C5 CF
01:4B1B 31 21
Work Master 2 Demo 00:003B FF FF FF FF FF F0 44 3D 47 C9 Show correct font and graphics.
00:0068 D5 62
00:0B2E F0 44 47 CD 3B 00
Wonderworm 00:0149 08 00 Corrects the entry of the RAM size.
Zelda, Link's awakening 01:6DF0 20 28 Title "rolls" better.
Zoomar V3 00:0147 03 13 With the correct MBC entry this demo is also animated.

Rana Rana icon.

Rana overview.

Rana (Latin for frog, guess why this name was chosen) is a graphical "front-end" application that talks to Phoinix and shows things from the Gameboy's point of view. It is written in Java, just because I wanted to learn that language and to make it run on every reasonable system. I tried it with success on my Linux box and a Windows 2000 desktop system.

What are the reasons for Rana? Well, it is so difficult (and it has always been) to investigate why some games are not emulated correctly. For few problems solutions are found, mostly patches to work around the dirty tricks of the GB programmers. Rana reduces the effort to find such patches greatly!

The drawing at the right shows roughly how Rana should work:

  1. It launches the GDB (GNU Debugger) for PalmOS and communicates with it via the standard input and output channels. The GDB doesn't know anything about Gameboys, but it knows all about the handheld and Phoinix running on it.
  2. The GDB talks via TCP/IP to the POSE (Palm OS Emulator) which runs on the local computer.
  3. In POSE runs Phoinix; when it is launched, GDB gains control and waits for the emulation to be started.
  4. Phoinix emulates the Game Under Investigation. Rana commands GDB to send all relevant stuff which is then evaluated by Rana.

Rana screenshot.

A screenshot of an early version Rana is linked by the thumbnail picture. Click on it to see the full screenshot (33 KB). It shows a saved state of the game "SQRXZ" with the screen buffer, CPU and input/output registers, the tiles, cartridge data, and a disassembly view.

Rana has two modes, a pure view on saved states, and a control mode for live sessions. Here is a short list of its features:

  • Loads any of Phoinix' PDB files with saved states.
  • Views for all important data: CPU registers, cartridge properties, memory in different formats (disassembly, stack, hex dump, input/output, video), screen buffer.
  • Multiple memory views (disassembly and hex dump).
  • GDB console, mostly used while developing Rana.
  • Virtually unlimited number of breakpoints, single stepping, resume, and suspend of a live session.
  • Adjustable options.
  • It should also work with a real device, but I didn't try it yet.

If you like to try this program, download the Rana executable and/or the Rana sources.


The game's ROM file must be present on your PC to be loaded into Rana. The path to the ROM must be entered in the Preferences.

Note: All of the following prerequisites are only necessary for live sessions. To look into saved states you don't need them.

Rana connects to the GNU debugger GDB for 68K programs on PalmOS, known as "m68k-palmos-gdb" in its multi-section version. This can be obtained through the internet if you search for "multi section gdb overbeek" which should reveal the correct download site.

You don't need to endanger your precious data on your Palm. Please obtain and install POSE (the Palm OS Emulator) which you should find on Palm's site.

Additionally you need the linked executable of Phoinix (the ELF file before the transforming to PRC) and its source files. The source files are available at the project at SourceForge and the ELF file is created when you build Phoinix with the prc-tools. If you ask nicely, I might provide the files ;-)

On the target (POSE or the device) you need Phoinix and the game under investigation installed.

Viewing saved states

Rana can load saved states that are stored in PDB files. Phoinix stores the emulation state (if setup to do so) and the preferences of each game in files named "Phoinix-XXXXXXXX" where XXXXXXXX is the game CRC code. Additionally the emulation state is saved in "Phoinix-Crash" when a runtime occurs.

To view such a state select "Open" from the "File" menu. After the load several views can be opened to see the data.

Live sessions

Choose "Launch" from the "File" menu. Rana launches the GDB, and waits for you to launch Phoinix in POSE. Then again it waits for you to launch the game in Phoinix.

After launching the game it is suspended. You can single step or resume the execution. After each stop of the execution a lot of data are transmitted to Rana and all views are updated.