Palm OS 5 simulator usage notes / brain dump Author: Patrick Porlan Last revision: December 7, 2001 Product revision: 5.0.0.3 ______________________________________________________________________________ 1- Foreword This documents summarizes the information that developers will need in order to take advantage of the Palm OS 5 simulation tools. ______________________________________________________________________________ 2- Introduction The goal of this tool is to enable developers to run and test their applications on a preliminary release of the upcoming Palm OS 5 to give them time to make their applications fully Palm OS 5 compatible. Since most of Palm OS 5 code is shared between the simulation and the actual ARM-based devices, running a Palm OS application in the simulator gives a significant glimpse on how this application will behave when run on an actual Palm OS 5, ARM-based device. The simulation itself is made of a set of Palm OS components either recompiled to run directly on ix86 processors or provided in 68000 form and executed through the Palm Application Compatibility Environment (PACE) which is included in Palm OS 5. Third-party applications run in PACE. ______________________________________________________________________________ 3- What's provided The ROM file is a special "x86" ROM that doesn't include code for the native Palm OS 5 components. It does include all Palm OS resources, data and 68000 components however. The executable file is the entry point for the simulation. It is responsible for booting up the Palm OS simulation and handling its UI. The DLLs are necessary simulation components but the developers should not have to worry about them. For the record, lets notice that they simulate the Palm OS components that will run natively on ARM processors - including PACE. ______________________________________________________________________________ 4- Key mapping The UI is vastly mouse (pen) driven. There are a few important keys to know however: esc -> power key page up -> up key page down -> down key F1 to F4 -> applicative hard keys F5 -> toggles cursor coordinates reporting on or off pause/attn-> simulates a shortcut .. stroke. The user can then *draw* a number or character sequence Control Keys: Control+A Displays the menu Control+C Command character Control+D Confirmation character. Control+E Displays the application launcher Control+F Displays the onscreen keyboard Control+I Jump to the Find Dialog Control+K Jump to the Calculator app Control+M Enters a linefeed character Control+N Jumps to the next field Control+P Jumps to the previous field Control+R Does a soft reset Contorl+Shift+R Does a hard reset Control+S Automatic off character Control+Pause Enters the 68K debugger The following shortcuts are not supported by the NT Simulator: Control+B Low battery warning Control+T Sets or unsets hard contrasts Control+U Turns backlighting on or off Most others keys can be used to input text while a field is active. ______________________________________________________________________________ 5- Resets The simulation typically performs a clean (hard) reset when it is started. Both soft and hard resets can be preformed through the simulator's menu, which is accessible through a right-click. This allows changing a variety of settings that are saved in a configuration file. ______________________________________________________________________________ 6- State information All state information is preserved through the PalmSim.ini file, which is located in the same folder as the PalmSim.exe executable. Nothing is stored in the registry. ROM - string - rom file name - ex: NTFull_enUS.rom - default: "" RAM - integer - RAM allocated to storage memory, in KB - ex: 1024 - default: 256 Sound - boolean - whether or not sound can be output - ex: on - default: off StorageProtection - boolean - whether or not attempts to corrupt the storage memory should raise a protection fault - ex: on - default: off, for speed reasons Zoom - integer - magnification level (from 1 to 4) - ex: 1 - default: 2 BitDepth - integer - boot depth used at boot-time, expressed in bits per pixel (1,2,4,8 or 16) - ex: 16 - default: 8 AppCreator - 4 characters sequence - creator of the application to start at reset - ex: lnch - default: (none) DebugThroughTCP - boolean - whether the communication with external 68K debuggers should go through tcp or serial link - ex: on - default: on AlwaysOnTop - boolean - whether the simulation window should always be at the top of the windows z-order - ex: off - default: off WindowOriginX - integer - x coordinate of the simulator window at startup time - ex: 10 - default: 0 WindowOriginY - integer - y coordinate of the simulator window at startup time - ex: 10 - default: 0 CradlePort - string - name of the comm port to use for serial communication (cradle connector) - ex:COM1 - default: first available serial port InfraredPort - string - name of the comm port to use for ir communication - ex:COM2 - default: None InfraredPortType - string - whether the IR device connected to the port to use for IR is the cradle, a jet-eye device, or something else - ex: JetEye device - default: (none) AdditionalPorts - string - comma-separated list of serial ports usable within the simulation - ex:COM3,COM4 - default: (none) TraceTarget - string - tracer type and target - ex: tcp:localhost:25598 or file:traces.txt LogErrorMessages - boolean - whether to log error messages to errorlog.txt - default: off ______________________________________________________________________________ 7- Command line All parameters that can be set through the configuration file can also be set through the command line. If a parameter is specified through the command line, the value stored in the configuration file is ignored and will actually be overwritten with the command-line specified value when the simulator quits. The keyword themselves are not case-sensitive but their values are. As an example, simulation.ini may contain the following line: AppCreator=lnch If the user specified -appcreator:memo in command-line, the 'memo' value will be used and retained for future runs of the simulator. ______________________________________________________________________________ 8- Switching ROMs Holding down the shift key when the simulation starts will display the ROM selection dialog, which is normally displayed only if no ROM has been specified in the configuration file or through the command line. This is not a troubleshooting mode however, and won't prevent the simulation from behaving inpredictably if simulation.ini is corrupted or contains inconsistent data. ______________________________________________________________________________ 9- Menu (under development) ______________________________________________________________________________ 10- AutoRun, AutoLoad, AutoRunAndQuit, drag & drop PRC, PDB and PQA files can be imported into the storage memory area through drag and drop, or special folders that can be created in the folder where the simulation binaries are located. ______________________________________________________________________________ 12- Skins No skin support is available in this release of the simulator. ______________________________________________________________________________ 11- Sessions The storage content can be saved for future reuse, but reloading a storage memory image this requires soft-resetting the device. This is not equivalent to POSE session files. ______________________________________________________________________________ 12- Storage viewer Holding shift while clicking on a database name will copy the content of this database as text in the clipboard, performing a concatenation of all its records. This is mainly useful for application that log strings into record databases. The record/resource dump is made of three columns: offset in record, hex data, ascii data. Holding the shift key when the record/resource is selected will cause the offset column to be filled with the absolute addresses of the data bytes instead of their offset in the record. ______________________________________________________________________________ 13- Miscellaneous Holding the shift key when the simulator's about dialog is invoked will print the simulator executable's construction date & time.