Phoinix, the free Gameboy emulator for PalmOS

Sitemap:
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
About...
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

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 http://zerosoft.zophar.net, 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.

Rana

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.

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.

Prerequisites

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.