# Palm OS Emulator User's Manual

#### Version 2.0

###

Table of Contents

- 1.0 Palm OS Emulator
  - 1.1 What is the Palm OS Emulator?
  - 1.2 Palm OS Emulator Features
  - 1.3 The Palm OS Emulator Package
  - 1.4 How To Get a ROM File
  - 1.5 Running The Emulator
- 2.0 Using the Palm OS Emulator
  - 2.1 The Emulator Display
  - 2.2 Hardware Buttons
  - 2.3 HotSyncing
  - 2.4 Loading Applications
  - 2.4 How To Test Software
- 3.0 Debugging
  - 3.1 Gremlins
  - 3.2 Source Level Debugging

###

1 Palm OS Emulator

#### 1.1 What is the Palm OS Emulator?

The Palm OS Emulator is a "hardware emulator". A "hardware emulator" is an application that pretends to be just like a piece of hardware. In this case, the Palm OS Emulator is an application that acts just like the hardware used in the 3Com / Palm Computing family of Palm OS connected organizers (Pilot 1000, Pilot 5000, PalmPilot Personal, PalmPilot Professional, Palm III, etc.). With it, you can run Palm OS applications directly on your Windows or Macintosh personal computers.

The Palm OS Emulator is an application on which to safely test Palm OS software without risking the data on your personal device. Towards this end, the Palm OS Emulator is enhanced beyond a standard device to call attention to unsafe software behavior (be it intentional or accidental). Software which runs fine on the Palm OS Emulator will generally run safely on Palm OS devices. Software that results in warnings or errors from the Palm OS Emulator but seems to run OK on devices almost always has a real problem. Usually users will notice some strange behavior from their device but they won't know what application causes the problem. The Palm OS Emulator makes it clear what is wrong in a safe environment.

The Palm OS Emulator is a great way to verify that software safely operates without risking your personal data. An application which cannot load or handle Gremlins playing with it is likely to cause users problems which range from soft resets to full data loss. It is important for users and developers to avoid software which needs device resets. The Palm OS Emulator has three qualities which makes it a great software tester. It is great because it allows problems to be found without risking a user's data. It is great because it is simple for users and developers to use. And it is great because it makes it clear what's wrong, which is a time saver if you are suspicious of an application and are trying to track a problem down.

#### 1.2 Palm OS Emulator Features

The Palm OS Emulator has a number of features for accurate emulation of the Palm Computing hardware platform:

- Palm device lookalike display (it looks like a real Palm device attached to your monitor!)
- Mouse pointer simulates the Palm pen
- Silkscreen and Graffiti area
- Hardware buttons (on/off, application buttons, up/down, reset, HotSync)
- Zoom display and optional backlighting for better readability
- Configurable memory card size (up to 8 MB)
- Communications port emulation for HotSyncing and modem communications
- Speaker emulation
- Keyboard mapping so you can enter text with your PC keyboard
- Display frames per second control

It also has a number of features that extend standard Palm OS behavior in order to detect unsafe application and to help debug them:

- Gremlins, an automated testing facility
- Detection of applications which access the Palm OS device in incompatible ways
- Integration with the Metrowerks source-level debugger

#### 1.3 The Palm OS Emulator Package

The Palm OS Emulator package includes the following files:

File | Description
--- | ---
Emulator.exe (Windows) Emulator (Macintosh) | Main Palm OS Emulator program.
Guide.html | Palm OS Emulator documentation (this file).
Notes.txt | Change history of the Palm OS Emulator
ROM Transfer.prc | Palm OS program to send the Palm.ROM file to your desktop
13hewgil.pdf | Article by Greg Hewgill on the genesis of Copilot.
12rollin.pdf | Article by Palm Computing on current status and future direction of the Palm OS Emulator.
Debugger.html | Developer-level document describing the API that can be used by exnternal debuggers to interoperate with the Palm OS Emulator.

The Palm OS Emulator requires either Windows 95 or Windows NT to run (it is a multithreaded 32-bit program), or a Macintosh with System 7.5 or later. The Palm OS Emulator will not run on Windows 3.1, even with Win32s installed.

#### 1.4 How To Get a ROM File

Since the Palm OS Emulator emulates the Palm Computing Platform hardware, all components of the hardware must be present. This includes a ROM image file, which is not shiped with the Emulator. There are two ways to get a ROM image:

- Go to the Palm Developer Web site and download one of the debug ROM images.
- Use the ROM Transfer.prc Palm OS application. Install this application on your Palm device, invoke the "Download ROM" menu item from within the Palm OS Emulator, and follow the instructions.

#### 1.5 Running The Emulator

After you've obtained a ROM image, place it in the same directory as the Emulator, ensure that its name starts with "ROM." or ends with ".ROM" or " ROM", and launch the Emulator. The Emulator will search for and load the ROM file you've saved. You will then be presented with the familiar "Pilot", "PalmPilot", or "Palm III" splash screen, quickly to be replaced by the General preference panel.

###

2 Using the Palm OS Emulator

#### 2.1 The Emulator Display

The Palm OS Emulator display looks much like a real Palm OS device. If you have used a real Pilot (1000 or 5000), PalmPilot (Personal or Professional), or Palm III, the operation of the Palm OS Emulator will be obvious.

Palm OS Emulator-specific features are available via menu items. If you are using Windows, press the right mouse button anywhere in the Emulator window (for keyboard users, the F10 key will work too). If you are using a Macintosh, you know where to find the menubar.

TBD: menu descriptions

#### 2.2 Hardware Buttons

The hardware buttons (on/off, the four application buttons, up, and down) are simulated on the emulator display window. They are activated by clicking on the button image. Holding down the mouse button is the same as holding down the corresponding Palm OS device button.

The buttons are also simulated on the desktop keyboard as follows:

Pilot button | Desktop key
--- | ---
On/off | Esc
Date Book | F1
Address | F2
To Do List | F3
Memo Pad | F4
Up | Page Up
Down | Page Down

An additional keyboard feature is that you can type on your desktop keyboard, and characters you type will be automatically inserted into the Palm OS event queue. This means that you can enter data with your keyboard instead of trying to do Graffiti strokes with your mouse (which is harder than it sounds).

#### 2.3 HotSyncing

The Palm OS Emulator includes support for emulating the Palm device serial port connection. This is achieved by mapping Palm OS serial port operations to a real communications port on the desktop computer. To perform a HotSync operation, you would connect two serial ports on the back of your machine together with a LapLink (or other null modem) cable. For example, the HotSync application would be communicating on COM1, and the Palm OS Emulator would be communicating on COM2. They would communicate through the null modem cable, and perform a HotSync operation just like a real Palm device would.

If you have just two serial ports and one of them is in use with a serial mouse, you can still HotSync with the Palm OS Emulator. You will first need to disable your mouse and restart Windows, this will allow you to use the serial port. Connect your serial ports together with a null modem cable. Start the Palm OS Emulator, and press F10 to get the menu, then H. This will start a HotSync operation. When it is completed, exit the Palm OS Emulator, reenable your mouse, and restart Windows again.

> Tip: The first time you perform a HotSync operation with the Palm OS Emulator, the HotSync application will ask you to select a user name. It's probably best to create a new user account with a different name for the Palm OS Emulator.

> Tip: The Palm HotSync application (that runs on the desktop computer) is CPU intensive. This is fine when talking to a real Palm device, since the two devices are not trying to share the same CPU, but causes the Palm OS Emulator to run more slowly and sometimes the HotSync operation fails. A trick to help this is to click on the Palm OS Emulator window after the HotSync process starts; this brings the Palm OS Emulator back to the foreground and lets it use more of the CPU time. The whole process works better when you do this.

#### 2.4 Loading Applications

The Palm OS Emulator supports loading applications directly into the emulated RAM without going through a HotSync operation. This is simple, fast, and makes the compile-load-test cycle much easier.

Windows:
  To load an application in Windows, right-click on the emulator window and select the "Load Application..." menu item. This is a cascading menu item allowing you to select from a list of recently loaded application, or allowing you to select a new one from you hard disk. You are are allowed to load both application (.prc) and database (.pdb) files.
Mac:
  To load an application on the Macintosh, select the "Load Application..." menu item from the File menu. Select the application or database file you wish to load from the dialog box that appears.

When you select a file to load, it will immediately be loaded into the emulated RAM if possible. Any existing application or database with the same identifier will automatically be deleted before the new version is loaded (if you're trying to replace an application that is currently running, the Palm OS will let you know).

#### 2.5 How to test software

One of the main uses of the Palm OS Emulator is to test software before downloading it onto an actual hardware device. This section covers the steps involved in doing that:

1. Get the latest version of the Palm OS Emulator. Newer versions of the Palm OS Emulator check for more types of problems and give clearer problem reports.
2. Get the latest version of a Palm OS Debug ROM. Newer versions of Palm OS Debug ROMs have better and more thorough checks for invalid application behaviour. Also, Debug ROMs are better than the ROMs which run on devices. Debug ROMs have extra code to detect problems which are omitted from device ROMs in the interest of speed and space savings.
3. Get the latest version of an application to test. Authors normally are very good about releasing fixed versions of apps so that their users don't have to reset their devices or risk their data.
4. Run the Palm OS Emulator and load the application as outlined in section 2.4.
5. There are different ways to test the program. The simplest way is to go to the Palm OS Emulator's Gremlin menu and select New. Select the application to test and press the OK button. Gremlins is an automatic software tester. It tries all the user-interface in an application over and over again trying to get the application to break. Watch Gremlins play with the software. Software which crashes within five or ten minutes is quite unsafe. The application should really be able to run for several hours and ideally overnight or even over the weekend. Be sure to try different Gremlin numbers. They test the software differently. For more info on how Gremins works and what it does, read the Gremlins section. Report any problems and the steps to reproduce to the software author.

If you have a specific idea of what's wrong with an application, simply go to the Launcher, load the application, and try out the suspect functionality. Report any problems and the steps to reproduce them to the software author.

###

3.0 Debugging

#### 3.1 Gremlins

Gremlins is an automated tester. It randomly generates pen and key input to walkthrough all user-interface features. Gremlins essentially plays fair, meaning that it only uses an application as a user could. If Gremlins can crash an application, some user somewhere will too.

As mentioned, Gremlins randomly makes up pen and keyboard input. There are 1000 different gremlins. Each one has it's own, unique sequence of input. Each Gremlin will always repeat the same sequence of input when activated. To repeat a crash, repeat the Gremlin from the same program state. If the program is in a different state, then Gremlins will not repeat. Gremlins will tap on the buttons currently visible will cause a different series of actions.

Gremlins will run and run, abusing an application as well as it can. The recommended time for an application to run is for an application's full lifespan. For an application which creates data, this means until the device is full. For devices with small memory sizes, this is about a million events. For applications which can't fill up the device, fewer Gremlins are normally needed to fully exercise them.

Gremlins recognizes the Palm OS user-interface a little bit to allow it to focus in on user-interface features which exercise application functionality. Gremlins pays much more attention to buttons, lists, text fields and menus than to labels and blank areas. If a program is using a region of the screen for it's own custom control, placing a user-interface gadget over the area will cause Gremlins to focus on that area as well.

The only known thing that Gremlins does which users can't is Gremlins notices user-interface which is located off the edge of the screen. Such user-interface isn't recommend for Palm OS. Instead, user-interface which shouldn't be visible should be set not usable or hidden with the FrmHideObject API call.

#### 3.2 Source Level Debugging

The Palm OS Emulator supports an interface that external debuggers can use in order to debug running application. Currently, Metrowerks has a beta version of a PilotPlugin that can be used to develop and debug Palm OS application. To use this plug-in:

1. Remove the original plug-in from its current location ("...: Metrowerks CodeWarrior:(Helper Apps): Debugger Plugins:" on your Macintosh or "...\CodeWarrior\bin\Plugins\Debugger\" on your PC). Copy the new plug-in to the old plug-in's original location. Note: merely renaming the old plug-in is not guaranteed to make MWDebug ignore it.
2. Start the emulator and wait for the splash screen to be replace by the General Preference panel.
3. Launch MWDebug.
4. Select "Preferences" from the "Edit" menu.
5. Select the "Palm OS" tab in the Preferences window.
6. Select a Target of "Palm OS Emulator".
7. Launch the CodeWarrior IDE and and write your program (go on...we'll wait...)
8. When you compile your application, make sure that all debugging options are turned on. This means making sure there are dots in the "Debugger Info" column of the project window (the column with the "bug" icon in the column header) and that you have selected the "Enable Debugger" menu item (so that it now reads "Disable Debugger").
9. After building your application, debug it by choosing the "Debug" menu item, or clicking on the project window button with the right-arrow icon in it. You can also debug an application directly from the debugger by using the "Open" menu item to select a ".psym" file.
10. MWDebug will take over, downloading your application and stopping it at the first line of PilotMain. Now debug as normal.

From then on, the debugging cycle is exactly the same as if you were debugging on the actual device. You can single-step, set breakpoints, break on exceptions, execute DbgBreak(), etc.