Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

2    Using Palm OS Garnet Simulator

Testing with Palm OS® Garnet Simulator

Palm OS® Garnet, Release 5.4

This chapter provides guidance and reference information that will help you use Palm OS® Garnet Simulator.

Installing Palm OS Garnet Simulator ^TOP^

Palm OS Garnet Simulator consists of the following:

  • The executable file: PalmSim.EXE
  • A ROM file
  • The DLLs required by the ROM file

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 ^TOP^

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 ^TOP^

You can supply the session parameters for Palm OS Garnet Simulator as command line options. For example:

PalmSim.EXE -rom:Simulator_Full_EFIGS_Release.rom

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  

Option Syntax

Parameter Values

-68kdebuggerport: [host:port|None]

host - The name of the host used for the 68K debugger.

port - The port used for the 68K debugger.

Example:

-68KDebuggerPort: localhost:2000

For more information, see "Communication>Communication Ports."

-68kdebuggerporttype:type

type - The type of port used for the 68K debugger. The default is TCP/IP.

For more information, see "Communication>Communication Ports."

-additionalports:COMx

COMx - Additional communications ports.

For more information, see "Communication>Communication Ports."

-allowedscreendepths:mask

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."

-alwaysontop:[on|off]

Indicates whether the Simulator window should stay in front of other windows on the desktop. The default is off.

For more information, see "Display>Always on Top."

-appcreator:xxxx

xxxx - A four-character Creator ID indicating the application to start.

For more information, see Chapter 2, "Using AppCreator to Start an Application,".

-autoload:[filename|directory]

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."

-autorunandquit:[filename|
directory]

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."

-autorun:[filename|directory]

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."

-bitdepth:[1|2|4|8|16]

The screen bit depth. The default is 8.

For more information, see "Display>Allowed Screen Depths."

-cradleport:COMx

COMx - The communications port used to talk to the cradle.

For more information, see "Communication>Communication Ports."

-cradleporttype:type

type - The type of port used for communication with the cradle. The default is Standard RS-232.

For more information, see "Communication>Communication Ports."

-directscreenaccess:[on|off]

Indicates whether the installed applications have access to the LCD screen buffer. The default is off.

For more information, see "Display>Allow Direct Screen Access."

-dllpath:directories

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 PALMSOURCE_SIM_PATH environment variable (described in "Installing Applications").

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.

-dyn:size

size - An integer value indicating the amount of dynamic heap to emulate during the session, specified in kilobytes. The default is 512.

For more information, see "Memory>Dynamic Heap Size."

-extendedmemorychecks:[on|off]

Indicates whether PACE should do extended checks of applications' use of system memory. The default is off.

For more information, see "PACE."

-hassilkscreen: [on|off]

Indicates whether the display screen has a dynamic input area. The default is off.

For more information, see "Display>Resolution."

-infraredport:[COMx|None]

COMx - The communications port used for infrared.

For more information, see "Communication>Communication Ports."

-infraredporttype:type

type - The type of port used for infrared communication.

For more information, see "Communication>Communication Ports."

-ram:size

size - An integer value indicating the amount of RAM to emulate during the session, specified in kilobytes. The default is 8192.

For more information, see "Memory>RAM Size."

-redirectnetlibcalls:[on|off]

Indicates whether you want to redirect NetLib calls to the host machine's TCP/IP stack. The default is off.

For more information, see "Communication>Redirect NetLib Calls to Host TCP/IP."

-rom:romname

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.

-screendensity: [72|108|144]

Sets the density of the display screen. The default is 108.

For more information, see "Display>Resolution."

-screenheight: [160|220 |240|320|480]

Sets the height of the display screen. The default is 240.

For more information, see "Display>Resolution."

-screenwidth: [160|240|320]

Sets the width of the display screen. The default is 240.

For more information, see "Display>Resolution."

-skipcalibration:[on|off]

Used to skip the digitizer calibration step during the boot sequence. The default is on.

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 storagesnapshotfile option to reload it when Simulator restarts after a hard reset.

For more information, see "Storage Menu".

-sound:[on|off]

Activates or deactivates sound output. The default is off.

For more information, see "Enable Sound."

-stayonincradle:[on|off]

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 on.

-storageprotection:[on|off]

Activates or deactivates write protection for the storage memory. The default is off.

For more information, see "Memory>Storage Is Write-Protected."

-storagesnapshotfile:ssfname

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".

-tracetarget:[machine|
file|stderr]

machine - The identifier of the machine to which you want traces redirected. For example:

-tracetarget: tcp:localhost:25998

file - The file to which you want traces redirected. For example:

-tracetarget:file:myfile.txt

stderr - Redirects trace output to standard error.

-usehostbatteryinfo:[on|off]

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 off.

For more information, see "Battery."

-windoworiginx:integer

integer - Specifies Simulator's horizontal distance from the left of the screen when the window is opened. The default is 0.

-windoworiginy:integer

integer - Specifies Simulator's vertical distance from the top of the screen when the window is opened. The default is 0.

-zoom:[1|2|3|4]

The magnification level. The default is 1.

For more information, see "Display>Magnification."

Using the Initialization File ^TOP^

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 ^TOP^

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 the palmsim.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 ^TOP^

This section provides an overview how to use Palm OS Garnet Simulator.

Palm OS Garnet Simulator Display ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

To have Simulator load a specific storage snapshot file at startup or upon hard reset, you can either:

  • Set the storagesnapshotfile value in the palmsim.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 ^TOP^

Palm OS Garnet Simulator supports the following communication functions.

Performing a HotSync Operation ^TOP^

You can perform a HotSync® operation through serial connection, through IrDA, or through TCP/IP.

HotSync Operation with Two Serial Ports

  1. Connect the serial ports with a NULL serial cable.
  2. Set the properties for the HotSync application to perform a local HotSync operation with one of the serial ports.
  3. 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

  1. 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.
  2. Using the Simulator menu Settings>Communication> Communication Ports, set the cradle's port to TCP/IP bound to localhost:6420.
  3. In the HotSync settings for the host computer, enable Network Hotsync.
  4. 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 ^TOP^

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 ^TOP^

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.

NOTE: Simulator supports Metrowerks CodeWarrior for Palm OS Version 7 and later.

Using Gremlins ^TOP^

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 ^TOP^

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 ^TOP^

Use this drop-down list to select the first application the Gremlins are to run.

Random Seed ^TOP^

Use the From entry field to set the seed for the Gremlin pseudo-random number generator.


NOTE: The To entry field is not yet supported.

Events ^TOP^

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.


NOTE: The Switch after entry field is not yet supported.

Control ^TOP^

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 ^TOP^

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.