Romeo: The Palm ROM Discombobulator

By Monica Chew and Rob Johnson

With Romeo, you can construct custom PalmOS ROM images with extra applications of your choice and without any of the default applications that you never use. This can be extremely useful if your Palm doesn't have much RAM, or if you are deploying an application to, say, a sales team and want to make it as user-proof as possible. There's almost 600K of unused space on a typical Palm ROM, and you can be taking advantage of it.

News

Patches for Non-EZ ROMs, old small ROMs, and Japanese ROMs Released	May 29, 2001
You may have noticed the bug that romeo doesn't set up boot pointers in the small ROM correctly. This patch fixes that problem. To use the fix, you will need to pass the correct card header version of the small ROM to romeo during the assembly stage. To check which card header version you have, run romeo -h my.rom and look for the line in the small ROM info that gives the card header version (not the same as Version). There is a new -S flag so you can specify which version you need (before, it defaulted to header version 4 when assembling PalmOS 3.5 and higher). Another option that you might need is the -n option, for non-ez ROMs. Previously, reassembling non-ez Palms didn't work. To check if you have a non-ez Palm, just look at the flag information in the large ROM card header. The last option is the -L "JP" option for Japanese ROMs. If you have a ROM which is not Japanese or US/English, please mail the output of romeo -N to mmc@cs.berkeley.edu. In summary, try the following command if romeo hasn't been working for you: romeo -a <PalmOS version> -l <large ROM prcs>/* -s <small ROM prcs>* -o new.rom [-n] [-S <version> ] [-L <"JP"\|"US">]
Romeo 0.5.0 Released	March 17, 2001
This is the intial release of Romeo. It now satisfies all the authors' basic needs, and seems quite stable. Although it is listed as alpha-quality, we believe it is in beta (we're just covering our behinds in case we're wrong). It currently supports all ROM and Palm versions we know of, and never crashes.

How Does it Work?

To use Romeo, you'll need a ROM image to customize. The best way to get this is with pi-getrom from the pilot-link toolset, which is included with most distributions. You'll also want to use Pose, the PalmOS emulator, to test your new ROM before flashing it onto your Palm with osflash. Pose can be found in most distributions, too, but you'll probably need to download and compile osflash yourself. Note: osflash 1.5 is not quite compatible with Romeo. The author has accepted patches fixing the incompatibility, but until he releases them, you need to use this patched version.

Romeo can perform a myriad of actions. The following tutorial takes you through the process of building a custom ROM step-by-step.

Backup your Palm. After flashing your new ROM onto your Palm, you will have to do a hard reset, which will erase everything on your Palm.

Download Romeo from the Sourceforge page and install it on your system (compile from source, or install an rpm or deb file).

Get the ROM off your Palm using pi-getrom. Here's an example (assuming /dev/pilot is a link to the serial port your HotSync cable is connected to):

% pi-getrom /dev/pilot pilot.rom

You should now have a file called pilot.rom. This is your ROM image.

Romeo can generate a lot of files, so you might want to create some directories for its output:

% mkdir prcs.small
% mkdir prcs.big

The Palm ROM is little more than a collection of PRC files. Romeo reads in the ROM and outputs all its constituent PRCs. Similarly, you can give Romeo a list of PRCs and it will contruct a ROM containing them. The ROM is also divided into two regions: the small ROM and the large ROM. You should never make any changes to the small ROM, but you need to take it apart and put it together again in order to create a ROM that osflash will accept. Hopefully, this inconvenience will be removed in the future. To take apart the small ROM:

% cd prcs.small
% romeo -xsi ../pilot.rom

The -xsi means "extract the PRCs in the small ROM from input file ../pilot.rom." To get the large ROM PRCs,

% cd ../prcs.big
% romeo -xli ../pilot.rom

I'll leave it to the reader to decipher "-xli."

Now suppose you never use the Expense application and the built-in Calculator. We'll delete it and build a ROM without it.

% rm Expense* Calculator*
% cd ..

Suppose also that you'd like to never be without your favorite document reader, GutenPalm, which you have as GutenPalm.prc. You've also decided that EasyCalc (which requires MathLib.prc) is just way better than the default Calculator, and GPLed to boot. To assemble a new ROM with these changes, type

% romeo -a 3.50 -s prcs.small/* -l prcs.big/* GutenPalm.prc Easy*.prc MathLib.prc -o custom.rom

The -a option is for assembling new ROMs and takes an optional PalmOS version argument, which defaults to 3.50. The -s option tells Romeo to build a small ROM including the indicated files. The -l option adds a large ROM region to the assembled file, and includes the files listed afterwards. The -o gives the output image file name.

Before flashing this new ROM onto your Palm, you should definitely check that it works under Pose. A ROM that doesn't boot or crashes Pose will definitely not work on your Palm. So go run pose with your new ROM right now. I'll wait.

Now you need to flash this new ROM onto your Palm. First convert it to a PDB file using the os2pdb utility that comes with osflash

% os2pdb custom.rom

If os2pdb gives you an error or warning, do not use the resulting pdb! It will break your palm. Then transfer the resulting file, custom.pdb, to your pilot

% pilot-xfer -i custom.pdb

Finally, use the OS Flash Palm utility to flash your new ROM onto your Palm. Do not ignore any warnings that osflash gives you! Ignoring the warnings will break your Palm, guaranteed. (We made this mistake, and wrote this page as a consequence). If you get a warning, send us email so we can sort out the incompatibility. When this is finished, you will definitely need to do a hard reset on your Palm, and restore all your old settings and applications.

Romeo's other features

Romeo has lots of other features, too. You can modify ROMs in place, although this isn't as well supported. You can dump an incredible amount of information about your ROM, which is good for learning the structure of PalmOS ROMs. You can similarly dump heaps of info about PRC and PDB files.

Frequently Asked Questions

Question: Can this destroy my Palm?
Answer: Yes. Yes it can. Extracting the ROM and building the custom ROM image are safe, but flashing the new ROM onto your Palm can leave it unusable if the flashing operation stops early or if your ROM image is invalid. Fortunately, osflash does not flash the small ROM area on your Palm. If you discover that your Palm fails to work after flashing it, there is a long, tedious way to recover.

Question: How many times can you flash a Palm ROM?
Answer: Supposedly, hundreds of thousands of times. I've flashed mine twice as of this writing.

Question: What versions of PalmOS does Romeo support?
Answer: All of them that we know of, 1.0 through 3.5. Romeo even supports ROMs that have been modified by FlashPro. Romeo builds cleaner ROMs than FlashPro and, in fact, FlashPro ROMs are broken!

Question: What Palm hardware does Romeo support?
Answer: All that we know of. Of course, osflash must support your Palm for Romeo to be most useful.

Question: What happens if I burn an application into my ROM and then a new version comes out?
Answer: If you install the new version as normal, it will be used instead of the ROM version, although it will take up RAM as usual.

Question: How many of the default PalmOS PRCs can I leave out and still have a working ROM?
Answer: I'm not sure. You can leave out any of the standard applications (memo, todo, calendar, mail, address book, etc). The Palm VII comes with a whole host of wireless applications that you can remove if you don't use them. If you decide that you need them, you can always just install them later! Some PRCs are required though. As a general rule, if you don't know what it is, you should leave it in. There are some things worth mentioning specifically:

The Preferences program has several plugins: Buttons.prc, Digitizer.prc, etc. If you leave these out, the ROM will work in Pose. On my Palm, though, the Preferences program would not run without the Digitizer installed (and presumably any of the others). Even worse, it would hang during the initial setup trying to run the Digitizer Panel to calibrate itself. Since these are all pretty small, it may not be worth the risk of leaving them out. I would love to hear from anyone who does more experiments in this area.
My Palm comes with Cmd-nettrace.prc and Cmd-ping.prc. You can probably leave these out, but I haven't checked.
You might be able to leave out the various "NetIF" PRCs if you don't use networking, but I haven't checked, since I do use networking.
You have to leave in Setup.prc.

Question: Can I store PDBs in my ROM?
Answer: Yes, but they will be immutable. Sometimes this is fine. For example, some games store their graphics and sound files in a seperate PDB. You can safely put this file in your ROM. You probably don't want to put the game's high scores table in ROM, though.

Question: Why don't my ROM applications show up in some lists (such as the beaming list)?
Answer: Good question.