File: Guide.html

package info (click to toggle)
pose 3.0a3-3
links: PTS
area: contrib
in suites: potato
size: 15,500 kB
ctags: 20,548
sloc: ansic: 72,579; cpp: 50,198; perl: 1,336; python: 1,242; sh: 363; makefile: 290
file content (534 lines) | stat: -rw-r--r-- 19,797 bytes
<!--This file created 5/27/98 7:09 PM by Claris Home Page version 2.0-->
<HTML>
<HEAD>
   <TITLE>Palm OS Emulator User's Manual</TITLE>
   <META NAME=GENERATOR CONTENT="Claris Home Page 2.0">
   <X-SAS-WINDOW TOP=44 BOTTOM=861 LEFT=8 RIGHT=538>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
</HEAD>
<BODY>

<H1>Palm OS Emulator User's Manual</H1>

<H4>Version 2.0</H4>

<H3>
<HR>
Table of Contents</H3>

<UL>
   <LI><B>1.0 <A HREF="#copilot">Palm OS Emulator</A></B>
   
   <UL>
      <LI>1.1 <A HREF="#whatis">What is the Palm OS Emulator?</A>
      
      <LI>1.2 <A HREF="#features">Palm OS Emulator Features</A>
      
      <LI>1.3 <A HREF="#package">The Palm OS Emulator Package</A>
      
      <LI>1.4 <A HREF="#howtogetrom">How To Get a ROM File</A>
      
      <LI>1.5 <A HREF="#starting">Running The Emulator</A>
   </UL>
   
   <LI><B>2.0 <A HREF="#using">Using the Palm OS Emulator</A></B>
   
   <UL>
      <LI>2.1 <A HREF="#display">The Emulator Display</A>
      
      <LI>2.2 <A HREF="#buttons">Hardware Buttons</A>
      
      <LI>2.3 <A HREF="#hotsync">HotSyncing</A>
      
      <LI>2.4 <A HREF="#loadapp">Loading Applications</A>
      
      <LI>2.4 <A HREF="#test-software">How To Test Software</A>
   </UL>
   
   <LI><B>3.0 <A HREF="#debugging">Debugging</A></B>
   
   <UL>
      <LI>3.1 <A HREF="#gremlins">Gremlins</A>
      
      <LI>3.2 <A HREF="#source-debugging">Source Level Debugging</A>
   </UL>
</UL>

<H3>
<HR>
<A NAME="copilot"></A>1 Palm OS Emulator</H3>

<H4><A NAME="whatis"></A>1.1 What is the Palm OS Emulator?</H4>

<P>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
<A HREF="http://palm.3com.com/">3Com / Palm Computing</A> 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.</P>

<P>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.</P>

<P>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.
</P>

<H4><A NAME="features"></A>1.2 Palm OS Emulator Features</H4>

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

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

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

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

<H4><A NAME="package"></A>1.3 The Palm OS Emulator Package</H4>

<P>The Palm OS Emulator package includes the following files:</P>

<P><CENTER><TABLE BORDER=1 CELLSPACING=3 CELLPADDING=3 WIDTH="77%">
   <TR>
      <TH align=LEFT>
         <P ALIGN=LEFT>File
      </TH><TH align=LEFT>
         <P ALIGN=LEFT>Description
      </TH></TR>
   <TR>
      <TD VALIGN=top>
         <P>Emulator.exe (Windows)<BR>
         
         Emulator (Macintosh)
      </TD><TD VALIGN=top>
         <P>Main Palm OS Emulator program.
      </TD></TR>
   <TR>
      <TD VALIGN=top>
         <P>Guide.html
      </TD><TD VALIGN=top>
         <P>Palm OS Emulator documentation (this file).
      </TD></TR>
   <TR>
      <TD VALIGN=top>
         <P>Notes.txt
      </TD><TD VALIGN=top>
         <P>Change history of the Palm OS Emulator
      </TD></TR>
   <TR>
      <TD VALIGN=top>
         <P>ROM Transfer.prc
      </TD><TD VALIGN=top>
         <P>Palm OS program to send the Palm.ROM file to your desktop
      
      </TD></TR>
   <TR>
      <TD VALIGN=top>
         <P>13hewgil.pdf
      </TD><TD VALIGN=top>
         <P>Article by Greg Hewgill on the genesis of Copilot.
      </TD></TR>
   <TR>
      <TD VALIGN=top>
         <P>12rollin.pdf
      </TD><TD VALIGN=top>
         <P>Article by Palm Computing on current status and future
         direction of the Palm OS Emulator.
      </TD></TR>
   <TR>
      <TD VALIGN=top>
         <P>Debugger.html
      </TD><TD VALIGN=top>
         <P>Developer-level document describing the API that can be
         used by exnternal debuggers to interoperate with the Palm OS
         Emulator.
      </TD></TR>
</TABLE></CENTER></P>

<P>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.</P>

<H4><A NAME="howtogetrom"></A>1.4 How To Get a ROM File</H4>

<P>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:</P>

<UL>
   <LI>Go to the
   <A HREF="http://palm.3com.com/devzone/index.html">Palm Developer
   Web site</A> and download one of the
   <A HREF="http://palm.3com.com/devzone/rom3/debugrom.html">debug
   ROM images</A>.
   
   <LI>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.
</UL>

<H4><A NAME="starting"></A>1.5 Running The Emulator</H4>

<P>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.</P>

<H3>
<HR>
<A NAME="using"></A>2 Using the Palm OS Emulator</H3>

<H4><A NAME="display"></A>2.1 The Emulator Display</H4>

<P>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.</P>

<P>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.
</P>

<P><I>TBD: menu descriptions</I></P>

<H4><A NAME="buttons"></A>2.2 Hardware Buttons</H4>

<P>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.</P>

<P>The buttons are also simulated on the desktop keyboard as follows:
</P>

<P><CENTER><TABLE BORDER=1 CELLSPACING=3 CELLPADDING=3>
   <TR>
      <TH align=LEFT>
         <P ALIGN=LEFT>Pilot button&nbsp;
      </TH><TH align=LEFT>
         <P ALIGN=LEFT>Desktop key
      </TH></TR>
   <TR>
      <TD>
         <P>On/off
      </TD><TD>
         <P>Esc
      </TD></TR>
   <TR>
      <TD>
         <P>Date Book
      </TD><TD>
         <P>F1
      </TD></TR>
   <TR>
      <TD>
         <P>Address
      </TD><TD>
         <P>F2
      </TD></TR>
   <TR>
      <TD>
         <P>To Do List
      </TD><TD>
         <P>F3
      </TD></TR>
   <TR>
      <TD>
         <P>Memo Pad
      </TD><TD>
         <P>F4
      </TD></TR>
   <TR>
      <TD>
         <P>Up
      </TD><TD>
         <P>Page Up
      </TD></TR>
   <TR>
      <TD>
         <P>Down
      </TD><TD>
         <P>Page Down
      </TD></TR>
</TABLE></CENTER></P>

<P>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).</P>

<H4><A NAME="hotsync"></A>2.3 HotSyncing</H4>

<P>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.</P>

<P>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.</P>

<BLOCKQUOTE><P><B>Tip:</B> 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.</P>

<P><B>Tip:</B> 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.</P>
</BLOCKQUOTE>

<H4><A NAME="loadapp"></A>2.4 Loading Applications</H4>

<P>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.</P>

<DL>
   <DT>Windows:
   
   <DD>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.
   
   <DT>Mac:
   
   <DD>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.
</DL>

<P>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).</P>

<H4><A NAME="test-software"></A>2.5 How to test software</H4>

<P>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:</P>

<OL>
   <LI>Get the
   <A HREF="http://palm.3com.com/devzone/pose/seed.html">latest
   version of the Palm OS Emulator</A>. Newer versions of the Palm OS
   Emulator check for more types of problems and give clearer problem
   reports.
   
   <LI>Get the
   <A HREF="http://palm.3com.com/devzone/rom3/debugrom.html">latest
   version of a Palm OS Debug ROM</A>. 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.
   
   <LI>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.
   
   <LI>Run the Palm OS Emulator and load the application as outlined
   in section <A HREF="#loadapp">2.4</A>.
   
   <LI>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
   <A HREF="#gremlins">Gremlins section</A>. Report any problems and
   the steps to reproduce to the software author.
</OL>

<P>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.</P>

<H3>
<HR>
<A NAME="debugging"></A>3.0 Debugging</H3>

<H4><A NAME="gremlins"></A>3.1 Gremlins</H4>

<P>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.</P>

<P>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.</P>

<P>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.</P>

<P>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.</P>

<P>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.</P>

<H4><A NAME="source-debugging"></A>3.2 Source Level Debugging</H4>

<P>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:</P>

<OL>
   <LI><B>Remove</B> 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.
   <B>Note:</B> merely renaming the old plug-in is not guaranteed to
   make MWDebug ignore it.
   
   <LI>Start the emulator and wait for the splash screen to be
   replace by the General Preference panel.
   
   <LI>Launch MWDebug.
   
   <LI>Select "Preferences" from the "Edit" menu.
   
   <LI>Select the "Palm OS" tab in the Preferences window.
   
   <LI>Select a Target of "Palm OS Emulator".
   
   <LI>Launch the CodeWarrior IDE and and write your program (go
   on...we'll wait...)
   
   <LI>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").
   
   <LI>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.
   
   <LI>MWDebug will take over, downloading your application and
   stopping it at the first line of PilotMain. Now debug as normal.
</OL>

<P>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.</P>

<P>&nbsp;</P>
</BODY>
</HTML>