This chapter provides guidance and reference information that will help you use Palm OS® Garnet Simulator.
- "Installing Palm OS Garnet Simulator"
- "Starting Palm OS Garnet Simulator"
- "Specifying Command Line Arguments"
- "Using the Initialization File"
- "Loading ROM Images"
- "Running Palm OS Garnet Simulator"
- "Using Communication Functions"
- "Using External Debug Tools with Palm OS Garnet Simulator"
- "Using Gremlins"
- "Using the Host Control API"
Installing Palm OS Garnet Simulator
Palm OS Garnet Simulator consists of the following:
The ROM file is specific to Palm OS Garnet Simulator; the ROM file is not the same as ROM files used with Palm OS Emulator. ARM-based PRCs and 68K-based PRCs are embedded in this ROM file. However, ARM-based PRCs don't really contain code; rather, they reference external DLL files. As a result, there is at least one DLL per ARM-based application or shared library.
The DLLs required by the ROM file can be in the same directory as the executable file PalmSim.EXE
, or in the subfolder for the locale-specific ROM file (such as enUS
or jpJP
).
To use tracing functions with Palm OS Garnet Simulator, you need to have the files PalmTrace.DLL
and Reporter.EXE
in a directory included in the PATH
environment variable.
Starting Palm OS Garnet Simulator
To start Palm OS Garnet Simulator, run PalmSim.EXE
. The first time you start Palm OS Garnet Simulator, you are asked to select a ROM file.
You can also start Palm OS Garnet Simulator by dragging and dropping a Simulator ROM file onto the PalmSim.EXE
icon. (Note again that the Simulator ROM file is not the same as the ROM files used for Palm OS Emulator. You should not drop an Emulator ROM file on the PalmSim.EXE
icon.)
When Palm OS Garnet Simulator starts, the main window is displayed, as shown in Figure 2.1.
Figure 2.1 Palm OS Garnet Simulator's Main Window

Specifying Command Line Arguments
You can supply the session parameters for Palm OS Garnet Simulator as command line options. For example:
Table 2.1 shows the options that you can specify with the command line version of Palm OS Garnet Simulator.
NOTE: The command line options are not case sensitive, but the values specified for the options might be (for example, the four-character application creator ID for the
-appcreator
option).
Table 2.1 Command Line Options
host - The name of the host used for the 68K debugger. port - The port used for the 68K debugger. For more information, see "Communication>Communication Ports." |
|
type - The type of port used for the 68K debugger. The default is For more information, see "Communication>Communication Ports." |
|
COMx - Additional communications ports. For more information, see "Communication>Communication Ports." |
|
mask - A number representing the screen depths you want to allow. The default is a mask representing all possible depths. For more information, see "Display>Allowed Screen Depths." |
|
Indicates whether the Simulator window should stay in front of other windows on the desktop. The default is For more information, see "Display>Always on Top." |
|
xxxx - A four-character Creator ID indicating the application to start. For more information, see Chapter 2, "Using AppCreator to Start an Application,". |
|
filename - The PRC or PDB file that you want Palm OS Garnet Simulator to automatically load. directory - The directory containing the PRC and PDB files that you want Palm OS Garnet Simulator to automatically load. For more information on using AutoLoad, see "Using AutoRun, AutoLoad, and AutoRunAndQuit." |
|
filename - The PRC or PDB file that you want Palm OS Garnet Simulator to automatically run. directory - The directory containing the PRC and PDB files that you want Palm OS Garnet Simulator to automatically run. For more information on using AutoRunAndQuit, see "Using AutoRun, AutoLoad, and AutoRunAndQuit." |
|
filename - The PRC or PDB file that you want Palm OS Garnet Simulator to automatically run. directory - The directory containing the PRC and PDB files that you want Palm OS Garnet Simulator to automatically run. For more information on using AutoRun, see "Using AutoRun, AutoLoad, and AutoRunAndQuit." |
|
The screen bit depth. The default is For more information, see "Display>Allowed Screen Depths." |
|
COMx - The communications port used to talk to the cradle. For more information, see "Communication>Communication Ports." |
|
type - The type of port used for communication with the cradle. The default is For more information, see "Communication>Communication Ports." |
|
Indicates whether the installed applications have access to the LCD screen buffer. The default is For more information, see "Display>Allow Direct Screen Access." |
|
directories - A list of directories, separated by semicolons (;), that specify where you want Palm OS Garnet Simulator to look to find DLLs. This command line option is similar to the If you use both the environment variable and the command line option, Palm OS Garnet Simulator looks in the paths specified by the environment variable first. |
|
size - An integer value indicating the amount of dynamic heap to emulate during the session, specified in kilobytes. The default is For more information, see "Memory>Dynamic Heap Size." |
|
Indicates whether PACE should do extended checks of applications' use of system memory. The default is For more information, see "PACE." |
|
Indicates whether the display screen has a dynamic input area. The default is For more information, see "Display>Resolution." |
|
COMx - The communications port used for infrared. For more information, see "Communication>Communication Ports." |
|
type - The type of port used for infrared communication. For more information, see "Communication>Communication Ports." |
|
size - An integer value indicating the amount of RAM to emulate during the session, specified in kilobytes. The default is For more information, see "Memory>RAM Size." |
|
Indicates whether you want to redirect NetLib calls to the host machine's TCP/IP stack. The default is For more information, see "Communication>Redirect NetLib Calls to Host TCP/IP." |
|
romname - The name of the ROM file. If you do not specify a value for this option when you first start Simulator, Simulator opens a dialog box asking for you to specify a ROM file. If you do not specify a value for this option on subsequent uses of Simulator, Simulator loads the ROM file name from the initialization file. |
|
Sets the density of the display screen. The default is For more information, see "Display>Resolution." |
|
Sets the height of the display screen. The default is For more information, see "Display>Resolution." |
|
Sets the width of the display screen. The default is For more information, see "Display>Resolution." |
|
Used to skip the digitizer calibration step during the boot sequence. The default is This command line option only works with single locale PalmSource ROMs. Since EFIGS ROMs have different Welcome applications, this option may not work. To skip calibration with a multiple-locale ROM, use Storage>Save to save a storage snapshot file, then use the For more information, see "Storage Menu". |
|
Activates or deactivates sound output. The default is For more information, see "Enable Sound." |
|
Specifies the default value of the "Stay on in Cradle" option that appears in the Preferences application's General panel. This option prevents the simulated device from entering sleep mode after a few minutes of inactivity. The default is |
|
Activates or deactivates write protection for the storage memory. The default is For more information, see "Memory>Storage Is Write-Protected." |
|
ssfname - The name of the storage snapshot file (SSF), indicating the saved storage snapshot that you want Simulator to load at startup or upon hard reset. For more information, see "Storage Menu". |
|
machine - The identifier of the machine to which you want traces redirected. For example: file - The file to which you want traces redirected. For example: |
|
Indicates whether the changes in the host machine should be indicated in the battery state of the handheld (for example, when you want to have the battery state of a laptop computer mapped to the Palm OS Garnet Simulator display). The default is For more information, see "Battery." |
|
integer - Specifies Simulator's horizontal distance from the left of the screen when the window is opened. The default is |
|
integer - Specifies Simulator's vertical distance from the top of the screen when the window is opened. The default is |
|
The magnification level. The default is For more information, see "Display>Magnification." |
Using the Initialization File
The command line arguments can be set in the Simulator initialization file, palmsim.ini
. Any options specified on the command line will override the initialization file settings.
When you exit Simulator, the session's values are written to palmsim.ini
for the next time you start Simulator.
NOTE: The initialization file options use an equals sign (=) to separate the option from the value, rather than the colon character (:) used in the command line version. Also, boolean values in the initialization file are indicated using 0 and 1 rather than
off
and on
.
Listing 2.1 Sample palmsim.ini File
[Settings] ROM=C:\Palm OS Garnet Simulator\ROM\Simulator_Full_EFIGS_Release.rom RAM=4096 DYN=512 Sound=0 StorageProtection=1 Zoom=1 BitDepth=8 DebugThroughTCP=1 AlwaysOnTop=0 UseHostBatteryInfo=1 WindowOriginX=310 WindowOriginY=140 RedirectNetLibCalls=0 AllowedScreenDepths=32907 LastSilkScreen= AppCreator= CradlePort= CradlePortType=Standard RS-232 InfraredPort= InfraredPortType= 68KDebuggerPort=localhost:2000 68KDebuggerPortType=TCP/IP AdditionalPorts= TraceTarget=tcp:localhost:25998 GremlinsFromValue=0 GremlinsToValue=0 GremlinsSwitchAfter=0 GremlinsSwitchAfterValue=0 GremlinsStopAfter=0 GremlinsStopAfterValue=0 GremlinsSelectedApps= GremlinsFirstApp= GremlinsAllowScreenUpdates=1 GremlinsWindowOriginX=0 GremlinsWindowOriginY=0 LogErrorMessages=0 DirectScreenAccess=0 ExtendedMemoryChecks=1 LastStorageSnapshot=storage snapshot.ssf StorageSnapshotFile=mysnapshot.ssf ScreenDensity=108 ScreenWidth=240 ScreenHeight=240 HasSilkScreen=1 SkipCalibration=1 StayOnCradle=1 EventsFilter=7;25;26
Loading ROM Images
When you first run Palm OS Garnet Simulator, you can specify the ROM image filename using the -rom
command line option. If you do not specify a value for this option, Simulator opens a dialog box asking for you to specify a ROM file.
When you restart Simulator, it assumes you want to use the ROM file that you specified when you first started Simulator.
To run Simulator with a different ROM file, you can do one of the following:
- Change the
ROM
option value in thepalmsim.ini
file. - Specify a new value using the
-rom
command line option. - Hold down the Shift key when you start Simulator. Then, Simulator opens a dialog box asking for you to specify a ROM file.
- Drag and drop a ROM file onto the
PalmSim.EXE
icon.
NOTE: If you are running the Release version of Palm OS Garnet Simulator, you must use a Release version ROM file. If you are running the Debug version of Palm OS Garnet Simulator, you must use a Debug version ROM file.
Running Palm OS Garnet Simulator
This section provides an overview how to use Palm OS Garnet Simulator.
Palm OS Garnet Simulator Display
The Palm OS Garnet Simulator display looks very much like a real Palm Powered handheld device. You can use your mouse to perform actions that you perform with the stylus on handheld devices, and you can use the menus to access Palm OS Garnet Simulator functions.
Displaying Menu Items
Right-click (use mouse button 2) on the Palm OS Garnet Simulator screen display to access the menu items. The Palm OS Garnet Simulator menu displays, as shown in Figure 2.2.
Figure 2.2 The Palm OS Garnet Simulator Menu

For more information about the Palm OS Garnet Simulator menu items, see "Menu Reference Summary."
Entering Data
Palm OS Garnet Simulator supports handwriting recognition. You can draw characters using a mouse.
Palm OS Garnet Simulator also supports keyboard input. When a field is active, you can use the keyboard to enter text. You can also use keyboard equivalents for hardware buttons and other functions. For more information, see "Keyboard Equivalents Reference."
Installing Applications
To install Palm OS applications, you can either use the Install menu item or drag and drop files onto Simulator.
NOTE: Palm OS applications written for Palm OS 4 or earlier (68K applications) run in Palm OS Garnet Simulator without any changes.
However, if you are installing a Palm OS application that uses ARM-native code, you must recompile the ARM-native code into a Windows DLL. Palm OS Garnet Simulator recognizes a call to an ARM-native subroutine as a call into a DLL.
Place the DLL either in the Palm OS Garnet Simulator directory or in a directory specified by using the
-dllpath
command line option.
Using the Install Menu Item
Use Install>Database to open the Install Database dialog box. You can install a single PRC, PDB, or PQA file, or you can use Shift-click to select multiple databases for installation. You will receive a warning message if Palm OS Garnet Simulator cannot use a PRC, PDB, or PQA file.
Using Drag and Drop
Drag and drop PRC, PDB, and PQA files onto the Palm OS Garnet Simulator main window. You will receive a warning message if Palm OS Garnet Simulator cannot use a PRC, PDB, or PQA file.
Using AutoRun, AutoLoad, and AutoRunAndQuit
Palm OS Garnet Simulator also supports the AutoRun, AutoLoad and AutoRunAndQuit features that are available with Palm OS Emulator.
You can use these features either by using the command line options (-autorun
, -autoload
, -autorunandquit
) or by creating special directories.
For more information about command line options, see Table 2.1.
To use an AutoRun directory:
- Create a subdirectory of the Simulator directory called
AutoRun
. - Place the PRC, PDB, and PQA files that you want to automatically run in the
AutoRun
directory. - When you start Simulator, Simulator automatically loads the PRC, PDB, and PQA files.
To use AutoLoad or AutoRunAndQuit, follow the steps listed above using AutoLoad
or AutoRunAndQuit
as the directory name rather than AutoRun
.
Using AppCreator to Start an Application
To have Simulator switch to a specific application at startup, you can either set the AppCreator
value to the application's creator ID in the palmsim.ini
file, or you can specify the -AppCreator
command line argument. See "Specifying Command Line Arguments" for more information about command line arguments.
Starting Simulator with a Storage Snapshot File
To have Simulator load a specific storage snapshot file at startup or upon hard reset, you can either:
- Set the
storagesnapshotfile
value in thepalmsim.ini
file - Specify the
-StorageSnapshotFile
command line argument.
Note that the storage image size specified by the storage snapshot file must match the current storage size setting.
See "Specifying Command Line Arguments" for more information about command line arguments. For more information about storage snapshot files, see "Storage Menu".
Using Communication Functions
Palm OS Garnet Simulator supports the following communication functions.
Performing a HotSync Operation
You can perform a HotSync® operation through serial connection, through IrDA, or through TCP/IP.
HotSync Operation with Two Serial Ports
- Connect the serial ports with a
NULL
serial cable. - Set the properties for the HotSync application to perform a local HotSync operation with one of the serial ports.
- Using the Simulator menu Settings > Communication > Communication Ports, set the cradle's port to
Standard RS232
bound to the other serial communication port.
HotSync Operation with One Serial Port
- Select the Simulator menu Settings>Communication> Redirect NetLib calls to TCP/IP in order to redirect the NetLib calls to the host machine's TCP/IP stack.
- Using the Simulator menu Settings>Communication> Communication Ports, set the cradle's port to
TCP/IP
bound tolocalhost:6420
. - In the HotSync settings for the host computer, enable Network Hotsync.
- In the HotSync application in the simulation session, set the following settings:
- Tap Modem.
- Select Options>Modem Sync Prefs and tap Network. Tap OK to save the changes.
- Select Options>LANSync Preferences and tap LANSync. Tap OK to save the changes.
- Select Options>Primary PC Setup and enter
127.0.0.1
as the Primary PC Address. Tap OK to save the changes. - Select Options>Connection Setup and select Cradle/Cradle. Tap Done to save the changes.
- Tap Select Service to set your service preferences, and then tap Done.
Using External Debug Tools with Palm OS Garnet Simulator
Palm OS Garnet Simulator can be used with a 68K debugger to examine the state of the 68K emulated applications.
Using Palm OS Garnet Simulator with 68K Debuggers
Palm OS Garnet Simulator is a debug target, just as an actual device or Palm OS Emulator. You can use Palm Debugger, Metrowerks CodeWarrior Debugger, or any other debugger you are used to using with Palm OS Emulator.
Using Metrowerks CodeWarrior Debugger
For example, you can use Palm OS Garnet Simulator with Metrowerks CodeWarrior by following these steps:
- In Palm OS Garnet Simulator, select Settings>Communication> Redirect NetLib Calls to Host TCP/IP, as shown in Figure 2.3, in order to redirect the NetLib calls to the host machine's TCP/IP stack.
Figure 2.3 Redirect NetLib Calls to Host TCP/IP

- Also in Palm OS Garnet Simulator, select Settings> Communication>Communication Ports to bind the 68K debugger transport to
localhost:2000
, as shown in Figure 2.4.
Figure 2.4 Setting the 68K Debugger Transport Values

- In CodeWarrior, select Edit>Preferences to display the IDE Preferences dialog box, shown in Figure 2.5.
Figure 2.5 IDE Preferences Dialog Box

- Click PalmDebugger Settings in the IDE Preference Panels tree to display the PalmDebugger Settings panel.
- Set the Target selection to be Palm OS Emulator.
- Click Choose next to the Location entry field.
- Use the Choose File dialog box to select the
PalmSim.exe
executable. - Select the Use TCP/IP connection to emulator setting.
Figure 2.6 Setting the CodeWarrior IDE Preferences

- Click Apply or OK to set your new values so that Palm OS Garnet Simulator is used to run your application rather than Palm OS Emulator.
Using Gremlins
Palm OS Garnet Simulator's Gremlins testing is similar to the Gremlins testing provided by Palm OS Emulator.
To use Gremlins, use the Gremlins menu item to display the Gremlins dialog box, as shown in Figure 2.7. In this dialog box, you specify the characteristics of the Gremlins you want to use to test your application.
Figure 2.7 Gremlins Dialog Box

Applications & Panels
Use this multiple selection list to select the set of applications and OS panels that the Gremlins are to run. You can select a single application or panel, a group of applications and panels, or all applications and panels.
First Application
Use this drop-down list to select the first application the Gremlins are to run.
Random Seed
Use the From entry field to set the seed for the Gremlin pseudo-random number generator.
Events
Use the Stop after entry field to set the maximum number of events for each Gremlin. Simulator stops running each Gremlin after it posts this many events, or after it terminates with an error.
Control
This area allows you to start, step, and stop Gremlin testing. It also allows you to monitor Gremlin testing as it is happening.
Using the Host Control API
A subset of the host control API, as recognized by Palm OS Emulator, is supported in Palm OS Garnet Simulator:
- Standard C Library wrapper selectors
- Remote Procedure Call (RPC)
- External tracing tool support and all selectors required by
HostFS.prc
.
To determine whether a specific host control function is supported, use the HostIsSelectorImplemented
function.
For more information about the host control API, see Using Palm OS Emulator.