Palm OS Emulator 2.1, OS Emulator3.0 User Manual

Palm OS Emulator 2.1/3.0

Engineering Specification

Keith Rollin – x6290

7/24/1998

Palm Computing 1 Palm OS Emulator ERS

Table of Contents

1 INTRODUCTION 5

1.1 SUMMARY 5

1.2 GOALS 5

1.2.1 DEVELOPERS 5

1.2.2 END-USERS 5

2 PRODUCT DESCRIPTION 5

2.1 REQUIREMENTS 5

2.1.1 WINDOWS 5

2.1.2 MACINTOSH 6

2.2 WHAT IS AN EMULATOR? 6

2.3 TECHNICAL OVERVIEW 6

2.3.1 CPU 6

2.3.2 MEMORY 6

2.3.3 HARDWARE REGISTERS 7

3 USER INTERFACE 7

3.1 LAUNCH BEHAVIOR 7

3.1.1 ENTERING THE APPLICATION 7

3.1.2 CLOSING THE EMULATOR DOCUMENT 8

3.1.3 EXITING THE APPLICATION 8

3.1.4 SAVING SESSION STATE 8

3.2 “AUTOLOAD” DIRECTORY 9

3.3 LOADING APPLICATIONS & DATABASES 9

3.4 PREFERENCES 9

3.4.1 IMPLICIT PREFERENCES 10

3.5 DEBUG OPTIONS 10

3.5.1 MEMORY ACCESS 11

3.5.2 LOGGING 13

3.5.3 MEMORY BLOCKS 13

3.6 USER INTERACTION 14

3.6.1 MOUSE USED AS PEN 14

3.6.2 FUNCTION KEYS 14

3.6.3 TEXT ENTRY 14

3.7 DRAG & DROP 14

3.8 GREMLINS 15

3.9 PROFILING 16

3.10 ERROR HANDLING 16

3.10.1 HARDWARE REGISTER ACCESS 18

3.10.2 LOW-MEMORY ACCESS 18

3.10.3 SYSTEM VARIABLE ACCESS 19

3.10.4 SCREEN BUFFER ACCESS 19

Palm Computing 2 Palm OS Emulator ERS

3.10.5 MEMORY MANAGER DATA STRUCTURE ACCESS 20

3.10.6 UNLOCKED CHUNK ACCESS 20

3.10.7 LOW-STACK ACCESS 21

3.10.8 UNINITIALIZED STACK ACCESS 21

3.10.9 FREE CHUNK ACCESS 22

3.10.10 UNINITIALIZED CHUNK ACCESS 22

3.10.11 STORAGE HEAP ACCESS 23

3.10.12 STACK OVERFLOW 23

3.10.13 STACK ALMOST OVERFLOW 23

3.10.14 MEMORY MANAGER SEMAPHORE ACQUISITION TIME 24

3.10.15 INVALID HEAP 24

3.10.16 INVALID PROGRAM COUNTER 24

3.10.17 UNIMPLEMENTED TRAP 25

3.10.18 SYSFATALALERT 25

3.10.19 UNHANDLED EXCEPTION 25

3.11 SCRIPTING 26

3.11.1 USER API 27

3.12 SERIAL PORT EMULATION 29

3.13 SOUND EMULATION 29

3.14 AUTO-OFF 29

3.15 MENU COMMANDS 29

3.15.1 ABOUT PALM OS EMULATOR… 30

3.15.2 NEW… 30

3.15.3 OPEN 30

3.15.4 CLOSE 30

3.15.5 SAVE 30

3.15.6 SAVE AS… 30

3.15.7 SAVE SCREEN 31

3.15.8 INSTALL APPLICATION / DATABASE 31

3.15.9 HOTSYNC 31

3.15.10 RESET 31

3.15.11 TRANSFER ROM 31

3.15.12 GREMLINS 31

3.15.13 PROFILING 32

3.15.14 PREFERENCES… / PROPERTIES… 32

3.15.15 DEBUG OPTIONS… 32

3.15.16 QUIT / EXIT 32

3.15.17 EDIT MENU (MAC ONLY) 32

4 PROGRAMMER INTERFACE 33

4.1 “HOST” API 33

4.1.1 TYPES 33

4.1.2 CONSTANTS 33

4.1.3 FUNCTIONS 34

4.2 DEBUGGER API 35

5 DIFFERENCES BETWEEN 2.0 AND 2.1 35

Palm Computing 3 Palm OS Emulator ERS

5.1 CONSISTENCY BETWEEN PLATFORMS 35

5.2 BASIS ON SESSION FILES 35

5.3 “AUTOLOAD” DIRECTORY 35

5.4 DRAG & DROP 35

5.5 DRAGONBALLEZ EMULATION 35

5.6 MORE/BETTER ERROR DIALOGS 35

5.7 DEBUG OPTIONS DIALOG 35

5.8 SCRIPTING 35

5.9 “HOSTXXX” API 35

5.10 NETWORKING , IR, AND SERIAL EMULATION 35

Palm Computing 4 Palm OS Emulator ERS

1 Introduction

1.1 Summary

The Palm OS Emulator is an application for desktop computers that emulates the operations of Palm
Computing Platform hardware devices. With it, users can load ROM images, applications, and databases
and use them on their desktop computers.

1.2 Goals

The Palm OS Emulator meets the needs of two target audiences: developers and end-users.

1.2.1 Developers

Developers use the Palm OS Emulator to help develop, test, and debug their Palm OS application. Because
the Palm OS Emulator is completely equivalent to a Palm Computing Hardware device, it obviates the need
for downloading applications to a viewer device for testing. Instead, the developer can install their
application into the emulated environment and run and test it on the same desktop computer containing
their development tools.

Developers can also make use of extensive debugging facilities incorporated into the emulator. With the
emulator, developers can detect accesses to illegal ranges of memory (such as low-memory or the CPU’s
hardware registers), run Gremlins, etc. When errors are detected, developers can use debugging facilities
from external source-level debuggers to pinpoint the errors.

1.2.2 End-users

End-users use the Palm OS Emulator to evaluate 3rd party software. By installing prospective software into
the emulator, they can safely evaluate the software before installing it onto their hardware device, making
sure that it fulfills their needs and doesn’t do anything overtly bad (such as crash). They can also test the
application for compatibility, making sure that their application has a good chance of working with future
Palm OS versions or hardware devices.

2 Product Description

2.1 Requirements

2.1.1 Windows

• Windows 95 or better, Window NT 3.51 or better. Windows 3.x with Win32s cannot be used, as the

Palm OS Emulator makes use of multi-threading facilities that Win32s does not support.

• 200MHz Pentium processor or better recommended. Lesser processors may be used, but will suffer

from performance problems.

• Screen capable of greater than 640x480 resolution.

• 16 Meg RAM.

• 700K disk space, plus space for each ROM file (typically 512K, 1 Meg, 1.1 Meg, or 1.5 Meg), plus

space for each document file (typically a little larger than the amount of RAM being emulated).

Palm Computing 5 Palm OS Emulator ERS

2.1.2 Macintosh

• Mac OS 7.5 or later. Mac OS 8.0 or later recommended.

• 200MHz PowerPC processor. Lesser processors PowerPC may be used, but will suffer from

performance problems. 68K-based Macs are not supported, solely for the reason that a survey of
developers didn’t turn up anybody using them.

• 12” display or larger (15” display or larger to use 2x mode)

• 2.0 Meg RAM, plus 1 Meg of RAM for each Meg of emulated device RAM

• 1.4 Meg disk space, plus space for each ROM file (typically 512K, 1 Meg, 1.1 Meg, or 1.5 Meg), plus

space for each document file (typically a little larger than the amount of RAM being emulated).

2.2 What Is An Emulator?

In general, an emulator is a software application that makes one computer act like another computer. In the
case of the Palm OS Emulator, it is an application that allows a user to run Palm OS applications on
Windows or Macintosh desktop computers. The user acquires a ROM image (typically by downloading one
from their Palm OS device or from Palm’s developer Web pages), launches the emulator, and tells the
emulator to load that ROM image. The emulator will then “boot” that ROM image, with the result that the
user sees the same General Preferences panel that they would after resetting a Palm OS device. After that,
the user can install applications into the emulator, which they can then run in exactly the same way as if
they were running the application on an actual device.

2.3 Technical Overview

When a Palm OS device is being emulated, a number of different aspects of emulation are going on all at
the same time. The microprocessor (CPU) must be emulated, standard memory accesses must be emulated,
and accesses to special memory locations called hardware registers (which control other hardware attached
to the device, such as the LCD screen and serial ports) must be emulated.

2.3.1 CPU

Palm OS hardware devices currently make use of two similar CPUs: the MC68328 (Dragonball) and
MC68EZ328 (DragonballEZ). These CPUs are based on the MC68000 (the same one used in the original
Macintoshes), and use the same instruction set. The Palm OS Emulator can emulate both of these
processors. Which one it emulates is determined by the ROM image the user loads into the emulator.

Emulation at the CPU level is fairly simple. The Palm OS Emulator loads the ROM image and initializes a
virtual program counter (“PC”) to a well-defined location within that ROM image. The emulator proceeds
to “boot” the ROM by emulating the execution of machine language instructions (opcodes) starting at that
memory location. In turn, opcodes are read from memory, decoded, and the actions that would have
occurred in an actual CPU are mirrored in algorithms and data structures maintained by the emulator. For
example, if the opcode being emulated is supposed to result in two numbers being added together, the
emulator will know to fetch those two numbers, add them together, and store the result in the location
indicated by the opcode. In other words, what a microprocessor does in hardware, the emulator does in
software.

Other aspects of CPU emulation (interrupt handling, exception handling, sleep mode, etc.) are also fully
emulated.

2.3.2 Memory

The CPU works in conjunction with memory accessible via its external address bus. On Palm devices, there
are three types of memory to be accessed: ROM, RAM, and the memory-mapped hardware registers.

ROM memory is emulated by making use of the ROM image file that the emulator loaded. Whenever an
emulated opcode needs to fetch a value that falls in the range occupied by the ROM in an actual hardware
device, the emulator fetches the appropriate value from within the ROM image it loaded.

Palm Computing 6 Palm OS Emulator ERS

RAM memory is emulated similarly. When the emulator is started, it is told to emulate a device with a
specified amount of RAM installed (128K, 256K, 512K, 1 Meg, 2 Meg, 3 Meg, 4 Meg, or 8 Meg). The
emulator uses the host OS’s facilities to allocate a block of memory of the requested size to be used as a
“RAM buffer”. Whenever an emulated opcode needs to fetch a value that falls in the range occupied by
RAM in an actual hardware device, the emulator fetches the appropriate value from within the RAM buffer
instead.

2.3.3 Hardware Registers

Hardware registers are special memory locations that do magic things when read from or written to. When
an emulated process accesses a hardware register, the emulator detects which one, and attempts to emulate
the “magic functionality” to some extent. For instance, if the emulated process writes a value to the register
corresponding to the serial output port, the emulator redirects that byte to the host desktop computer’s serial
output port instead.

3 User Interface

3.1 Launch Behavior

3.1.1 Entering The Application

Users start the Palm OS Emulator by double-clicking on the application icon or one of its session document
icons.

If the application is started by double-clicking on its icon, it will attempt to perform some appropriate
startup action.

• If the user had saved a session document the previous time the emulator had been run, the emulator

will attempt to reload that document.

• If the user created a new session document during the previous session but didn’t save that document,

the emulator will create a document with the same settings.

• If either of those attempts fails (for instance, the previously used session document or ROM file cannot

be found), or this is the first time the user has used the emulator, or the user holds down the Caps Lock
key while starting the emulator, the user is presented with a “New Configuration”1 dialog box. The
user uses this dialog box to specify a new hardware/RAM/ROM configuration from which a new
document is created.

If the user double-clicks on a session document icon, the emulator attempts to restore the session recorded
in that file. This attempt may fail if the ROM image for the session can no longer be found. In that case, the

1

“New Document”?

Palm Computing 7 Palm OS Emulator ERS

session document can no longer be used; session documents can only be used in conjunction with the exact
same ROM image that created them.

If the user double-clicks on a ROM image icon, the emulator presents the user with the “New
Configuration” dialog box with the selected ROM file entered into the ROM File text slot.

3.1.2 Closing the Emulator Document

Closing the emulator window ends the emulation session. Depending on the preference settings, the user
may have the option to save the document, or the document may be automatically discarded or saved.

When no document is open, the user has few options available. They can create a new emulation session,
open a previously saved session, download a ROM, edit preference settings (Mac only), see the About box
(Mac only), or quit the emulator entirely.

On the Mac, these options are available from the menubar, which still exists even when there are no open
windows. On Windows, the menu commands are available only by right-clicking on the emulator window.
If there is no emulator window, there is nothing on which to right-click. Thus, if the user opts to close the
emulator window but not quit the application, they are presented with a dialog box containing buttons for
the commands available at that point.

23

3.1.3 Exiting The Application

When quitting the emulator, the user can be given the option to save their session to disk. Whether or not
this option is given to them is controlled by an application preference setting, where the user can specify
whether they always want the session saved, never want the session saved, or want to be asked if they want
the session saved.

3.1.4 Saving Session State

Session files are the “document” of the Palm OS Emulator. They store the configuration being emulated
during the session along with the data generated during the session (that is, a copy of the RAM created
during the session).

When a user starts up the emulator for the first time, they must define a particular configuration to emulate.
The parts of the configuration that need to be specified (either explicitly or implicitly) are:

• Hardware device (that is, Pilot, PalmPilot, Palm III, etc.)

2

We can modify this dialog box so that it allows the user to perform the same commands as on the Mac

when there is no emulator window open, thus taking care of those “Mac only” comments.

3

“Download” should probably be “Transfer” to match the menu item.

Palm Computing 8 Palm OS Emulator ERS

• RAM size

• ROM

Once this information is provided, the whole package can be saved to the session document. The session
document contains all of the information needed for the user to quit the emulator and later restart it at
exactly the same point where it was when he quit. In addition to the above information, the following is
saved to the session file:

• RAM contents

• CPU state

• Dragonball register state

• Date/time adjustment (Normally, the date and time of the emulated device are tied to the host

computer’s date/time services. However, the user may want to change the date and/or time to some
other setting for any number of reasons.)

Once a session file is saved, the user can re-open it just like they would any other document in any other
application.

3.2 “Autoload” Directory

If there is a directory named “Autoload” in the emulator’s directory when a configuration is defined or
loaded, all application and database files in that directory are automatically loaded at that time.

3.3 Loading Applications & Databases

Users can load (install) Palm OS application (.prc) and database (.pdb) files into the emulated Palm OS
environment. The file is loaded just like ones installed with Palm Install tool or the “import” command
from the PalmDebugger.

4

While the file is being loaded, a progress bar is displayed to the the user know how things are going; some
files (especially database files with lots of records) can take a while to load.

When multiple files are being loaded (usually because multiple .prc and/or .pdb files were dragged onto the
emulator), a second progress bar appears in the progress dialog indicating how many of the files have been
processed.

3.4 Preferences

The following options can be controlled from the Preferences / Properties dialog:

• Emulation serial port

• Screen size (1x or 2x)

4

Currently, there is a bug with the install process, in that the Palm OS Launcher application will crash if
the application being loaded is already loaded into the emulated device, and hence is being displayed by the
Launcher.

Palm Computing 9 Palm OS Emulator ERS

56

• Gray or white background

• Action to take when emulator window is closed (save the document, discard the document, or ask the

user)

3.4.1 Implicit preferences

The following pieces of information are specified in locations other than the Properties/Preferences dialog,
but nonetheless get saved to the registry/preferences file.

• Last specified hardware device.

• Last specified RAM size.

• Last specified ROM file.

• Last saved session document.

• Window location.

• Recent session files

• Recent .pdb/.prc files

3.5 Debug Options

The Palm OS Emulator performs a lot of behind-the-scenes work to ensure the correct operation of the
currently executing application. Not only does it emulate the CPU and other aspects of a hardware device,
but it also monitors the application’s actions, making sure that the application is “well-behaved”. When
transgressions of Palm’s programming guidelines are detected, the emulator presents the user with a dialog
describing what happened.

This monitoring is not strictly essential to the successful execution of the application, and can in fact slow
down the applications performance. Additionally, a user may know full well that the application they are
running is not strictly conforming to Palm’s programming guidelines, but may wish to run the application
anyway without any annoying dialogs.

For both of these reasons, the user can control what types of monitoring the emulator performs. The options
presented in the following dialog are emulator-wide (as opposed to being different for each session
document).

5

Also need a way to minimize the sucker, perhaps via the taskbar button.

6

One user has requested a “Maximize” option for presentation purposes. This option may not be a good
idea, as it would require non-integral scaling of the LCD bits. Profiling shows that LCD updating can take a
significant amount of time at times.

Palm Computing 10 Palm OS Emulator ERS

This dialog presents the user with three classes of “Debug Options”.

The first box contains options that control whether or not the emulator monitors the application’s access to
memory. For instance, the emulator can report when the application reads from or writes to low-memory or
causes a “stack overflow”. These options are not saved in the preferences file, and will always be turned
back on when you restart the emulator.

The second box controls what kinds of helpful debugging information the emulator writes to a “Log File”
on disk. This Log File contains descriptions of what the application was doing up to the point where the
logging was stopped. In addition to the five categories of information logged by the emulator itself,
application developers can write their applications to add their own logging information to the Log File.

The third box controls monitoring and manipulation of heap blocks (and one stack-related option thrown in
for no really great reason).

3.5.1 Memory Access

3.5.1.1 Low-memory Access

Enables / disables checking of low-memory access by applications / processes running in RAM. A low­memory access is defined as a read from or write to a memory location in the range 0x0000 – 0x00FF.

Palm Computing 11 Palm OS Emulator ERS