======================================================================== Release Notes for the Palm OS Emulator Copyright 1998-1999 Palm Computing, Inc. - A 3Com Company Please send bug reports, comments, suggestions, etc. to devsupp@palm.com ======================================================================== Welcome to the Palm OS Emulator, v2.1! These are the release notes for the Palm OS Emulator (formerly known as Copilot). We have much planned for the Palm OS Emulator. For descriptions of some of the changes to appear in future releases, see the ERS (Engineering Resource Specification -- or something like that) at: See also a couple of Emulator-related articles that appeared in the May/June 1998 issue of the Handheld Systems Journal (www.cdpubs.com -- also included with the Palm OS Emulator in PDF form). If you want to build the Palm OS Emulator, you will need Visual C++ 5.0 on Windows, and CodeWarrior Pro 4 on the Mac. Please send comments, suggestions, and bug reports to devsupp@palm.com. Notes on the version number: ---------------------------- Palm Computing uses the following numbering scheme for versioning its products. The version number has the following format: ..[dab] The "dab" appearing after the bug fix revision indicates the pre-release stage of the product. The "d" means that it is currently under development. Once all features have been added and it has undergone enough testing to ensure that it is not DOA, its pre-release stage is advanced to "alpha", and the version number is suffixed with "a". Once all known critical bugs (crashers or bugs that prevent meaningful work) are fixed, the pre-release stage is advanced to "beta", and the version number is suffixed with a "b". Finally, after all designated bugs have been fixed, the product is released, and the version number no longer includes a pre-release designation. This version of the Palm OS Emulator is 2.1d28. This means that the product is missing some features, and there may be some pretty embarrassing bugs in it. Even so, during its development stage, the Palm OS Emulator has been in constant use by the Palm OS engineering team in the development of future versions of the Palm OS. Thus, it should be pretty stable for use by 3rd party developers. Notes on the Debug version: --------------------------- Some Palm OS Emulator releases include a Debug version (indicated by its having "Debug" appended to its name). This version of the Emulator is not really meant to be used during your day-to-day work. Instead, it is possible that it could be used to track down bugs in the Emulator itself. If, while using the Release (normal) version of the Emulator, you encounter some abnormal behavior that looks like an Emulator problem and not one with your Palm OS application, then you can try performing the same steps with the Debug version. It is possible that the Debug version (which is built with a lot of internal checking and calls to assert()) will report some information useful when reporting the problem back to Palm Computing. Because of all the additional checking, etc., that the Debug version adds, it runs very slowly. For this reason, you will probably want to always run the Release version. Notes on the Profile version: ----------------------------- Some Palm OS Emulator releases include a profiling version (indicated by its having "Profile" appended to its name). This version of the emulator allows users to turn profiling on and off, and to save the results to disk in a format compatible with the CodeWarrior Profile application, or in a tab-delimited text file suitable for spreadsheets. Because the extra code involved with profiling an application slows down all program execution (even when profiling isn't currently being used), profiling support is provided only in this special version. If you don't intend to profile your application, you should use the normal version of the emulator. Missing Features: ----------------- The following is a list of features that we expect to have implemented by final, but currently aren't implemented. Please don't submit bugs about their lack, even if they are documented in the ERS. * IR support. * All disabled items in Debug Options except uninitialized memory checking. Known Bugs ---------- * Neil needs to receive cmdInitDatabase when his app is installed. * You can't reliably change the time with the Preferences App. The time is generally synched with the host PC time. * It's not a good idea to load applications while the Launcher (the "Applications" application) is running. If the program you're loading doesn't already exist, it won't show up in the list of installed application until you quit and restart Launcher. If the application you're loading _does_ already exist, the Launcher won't refresh it's list, and will end up with a stale reference to the version you'd just replaced, leading to a Launcher crash. * We've seen one case where MacEmulator will draw the LCD area with a white background in single-scale mode instead of green. The cause of this problem appears to be with an out-of-date driver for a video acceleration board. Unless this is an issue for you, we probably won't try to figure out a workaround. * When working with an external debugger, make sure the ROM is awake (and not sleeping with a blank screen). Otherwise, communication between the two applications will not occur. ======================================================================== REVISION HISTORY Starting in 2.1d25 (and backdated to 2.1d24) I'm giving credit to the person or people responsible for convincing me to fix a bug or add a feature, in some cases even providing the source code for the bug or feature. These people's names appear in []'s. See the file Credits.html for a list of people who have submitted actual changes to the project. ======================================================================== Changes for 2.1d28 (5/21/99) ---------------------------- * Interim internal release dates: 2.1d27.1 - 5/17/99 * Windows: Added command line options: -psf : emulator loads the specified .psf file on startup. -rom : specifies the ROM image file to use. -ram : specifies the amount of RAM to emulate (in K). Valid sizes are 128, 256, 512, 1024, 2048, 4096, and 8192. -device : specifies the device to emulate. Valid types are pilot, palmpilot, palmiii, palmiiix, palmv, and palmvii. -silkscreen : specifies the silkscreen to use. Valid types are english and japanese. Case is NOT significant. Examples: Emulator -psf C:\Data\Session.psf Emulator -ROM C:\ROMs\3.0\debug.rom -RAM 1024 -Device PalmIII -Silkscreen English Startup rules are now as follows: 1 If the Caps Lock key is toggled in the ON position, always bring up the New/Open/... dialog. 2 Scan the command line for startup parameters. If an error occurs trying to scan the command line, the error is reported and the user is presented with the New/Open/... dialog. 3 Use the .psf file if one is specified. If an error occurs trying to load the file, the error is reported and the user is presented with the New/Open/... dialog. 4 If any of -rom, -ram, -device, or -silkscreen are specified, try to start a new session based on those values. If all are specified, the new session is automatically created. If any of those four values are missing, the "New Configuration" dialog is displayed. If the user cancels the dialog, or if there is an error creating the new session, any error is reported and the user is presented with the New/Open/... dialog. 5 If no command line options are specified, try re-opening the last saved .psf file (this step is skipped if the user last created a new session, but did NOT save that session to a file). If an error occurs trying to load the file, the error is reported and the user is presented with the New/Open/... dialog. 6 Try creating a new session based on the settings the user last specified when creating a session. If there is an error creating the new session, the error is reported and the user is presented with the New/Open/... dialog. 7 Finally, if all else fails, present the user with the New/Open/... dialog. Steps 1, 5, 6, and 7 describe the old startup rules. Steps 2, 3, and 4 are new. [Steve Haneman] * See that problem where I said that saving a session file could take up to 15 seconds or even longer? And see where I said I didn't know why? Well, it's because I'm an idiot. Under certain circumstances, Poser could get into a state where it would save the same session file several times in a row. Normally it would take a 1/2 second to save a file. But if it decided to save the same file 30 times in a row, that would take 15 seconds... * Fixed some more synchronization problems on SMP machines. * Force the Log####.txt files to be stored in the Poser directory instead of whatever directory happens to be the current one. Changes for 2.1d27 (5/7/99) --------------------------- * Interim internal release dates: 2.1d26.1 - ??? 2.1d26.2 - ??? 2.1d26.3 - ??? 2.1d26.4 - 3/25/99 2.1d26.5 - 4/1/99 2.1d26.6 - ??? 2.1d26.7 - ??? 2.1d26.8 - 4/27/99 2.1d26.9 - 4/29/99 2.1d26.10 - 5/5/99 * Added special messages for accessing NULL and for trying to access the A5 register (in order to access global variables or make inter- segment jumps) when A5 is not set up for the application trying to use it. [Roger Flores, Ken Krugler] * Better tracking of the current application. Now, if errors occur during an "action code" sequence, the application executing is reported, not the "main", "real" application that has the stack, A5, etc. [Roger Flores] * Fixed problem with installed Palm OS files and .psf files not getting added to the MRU lists if the list was empty. [Scott Johnson] * Fixed problem with MRU lists getting too long. [John Kinast] * In our SysUIAppSwitch patch, release any leftover command parameter blocks (if any). [Catherine White] * Fixed problem with the Escape key used to wake up a sleeping device also showing up in the event queue. [Daniel McCarty] * Added support for Escape, F1-F4, page up/down to Mac version. * Added special checks and error messages for SANE Math calling sequences. [Steve Lemke] * Rolled in Adam's fixes to conditional breakpoints. [Adam Dingle] * Fixed problems with NetLibSocketAddr. [Adam Dingle] * Converted to VC++ 6.0. * Fixed problem with getting names of library routines in the profiling system. [Adam Dingle] * Made Profile/Initialize implicit. [Adam Dingle] * Added explicit parent node information to profiling output text file. [Adam Dingle] * Fixed problem with recursive routines recursing too deep in the profile output functions. * The workaround for the old FindSaveFindStr bug didn't always work; it would sometimes still let the bug emerge. Made a small tweak to keep it suppressed. * Turned off stack overflow checking facility. It would occasionally cause the emulator to walk the dynamic heap when the heap was in an inconsistant state, resulting in spurious "...regular checkup..." error messages. [The IBM guys: Paul Silagi, Chunk Bazil, Mike Nagy] * Added support for the contrast button on Palm Vs. The button is on the right-hand side of the display graphic, opposite from the power button. You can't see it, but clicking on it brings up the contrast dialog. The dialog itself has no visual effect yet. [Ron Flax] * Breakpoints are now preserved across reboots. [Steve Lemke] * Totally rewrote the way (a) tailpatches and (b) soft breakpoints are handled. Previously, Poser would get control by handling special opcodes written into emulated memory: TRAP $D for tailpatches and TRAP $0 for soft breakpoints. However, there were problems with this approach. For one thing, what would happen if we needed to write a TRAP $D and TRAP $0 to the same memory location. You couldn't do it. There was no way, for example, to use PalmDebugger to set a breakpoint just after a call to a system function that Poser tailpatched. Also, Adam Dingle pointed out a problem with the actual routines involved: on very rare occasions, if an interrupt occured just after one of those TRAP $Ds or TRAP $0s were executed, then the next opcode executed would be the one that originally resided at that location, an NOT the first opcode in the interrupt routine. Anyway, this whole mess has been replaced with a new mechanism that doesn't alter the emulated RAM or ROM. [Steve Lemke, Adam Dingle and the IBM guys: Paul Silagi, Chunk Bazil, Mike Nagy] * Sped up performance by 20%. But since the previous change slowed things down by 13%, that's not as great as it first sounds. * Poser now ignores soft breakpoints (those installed by PalmDebugger) it encounters when it calls into the ROM for it own, nefarious, "between the cycles" purposes. [Steve Lemke] * Fixed problems trying to re-establish a sockets connection after it's been broken when the external debugger quit. [Ron Marianetti] * When asked for a ROM, .psf, .prc, etc., file, set the initial directory to the last directory used for that file type. * Allow multiple .prc file selection in the Open File dialog on Windows. * ROMs with invalid header checksums now generate a non-fatal warning instead of a fatal error. [Paul Dugas] * Allow for zero-length objects appearing at the end of .pdb files. [Christopher Hunt] * Massive spring cleaning of sources. Now all major sub-systems have a consistant interface for creating new sessions, resetting sessions, saving sessions, loading sessions, and disposing of sessions. Also, a lot of naming and scoping inconsistancies were taken care of. Also, namespaces were forsaken in favor of classes with static member functions; the CodeWarrior and VC++ browsers didn't handle namespaces too well. * In line with the above, .psf files are now compressed, taking as little as 15K for one that was normally 1 Meg. Note: the time it takes to compress an image can vary wildly, sometimes being nearly instantaneous, and sometimes taking upwards of 15 seconds. I'm not sure why the difference occurs... * Also in line with the source code spring cleaning, the entire emulator state is now saved to the session files. When loaded from the session files, the entire emulator state is restored. This means that you are returned right back to where you were when you created the session file; you do not have to go through the process of rebooting the "device". * Only heed the "Continue Past Warnings" option if a Gremlin is actually running. [Scott Johnson] * Added support for the "dead battery" pin on Port D on EZ devices. This should cut down the number of low-battery warnings on those devices. [Jesse Donaldson] * Don't insert keyboard or mouse events if stopped in the debugger or if the main emulator window is not active. * Added support for 4-bit LCD mode on EZ's. Found and fixed a long- standing bug where the emulated copy of the LCD display might not get updated if the lcdPageWidth register was updated. * If the emulated serial port was open and a reset occured, close the host serial port. * On the Mac, session files contain references to their associated ROM files via aliases. On Windows, the references are stored as full pathnames. This is old news. What's new is that if either of these mechanisms fails to find the ROM file, Poser now looks first in the same directory as the session file for a ROM file with the same name, and if that fails looks in Poser's own directory for a ROM file with the same name. * When reporting a corrupted heap, display also the address of the chunk header. [Adam Dingle] * Implemented Part I of Gremlin Hordes: You can now periodically have the complete emulator state saved while a Gremlin is running. This state can be reloaded, and the Gremlin restarted. This feature is controlled via a new setting in the New Gremlin dialog. There is now an editable item called Snapshot Frequency. The number entered here is the number of events that should occur between the time snapshots are taken. The default value is 10,000 events. By setting this value to zero, you turn off the snapshot feature. Snapshots are saved in a single directory in the Poser directory. The name of the directory is "GremlinStates_####", where #### is a value ensuring the directory name's uniqueness. Snapshots are saved in this directory with the name Event##########, where ########## is the event number at which the snapshot was taken. Snapshots are merely session files, so they can be reloaded at any time, just like regular session files. Since snapshots are taken while a Gremlin is running, the Gremlin is automatically turned off when the snapshot is reloaded. However, Poser displays the Gremlin Control window when the snapshot is loaded, allowing you to resume the Gremlin if you want. [Roger Flores] * Fixed a bug in the Gremlins facility that validates forms and form objects before trying to manipulate any of them. A call to FrmGetObjectType would occassionally return garbage, leading the rest of the function astray. [Scott Maxwell] * Added UNIX release. [Ben Williamson, David Creemer] * Fixed serial port not working on EZ devices (a pin moved from port F to port D during hardware development, and I missed it). [Florent Pillet] * Don't validate form objects and their sizes on Palm OS 1.0 devices. The built-in applications don't appear to follow the rules. [Andrew Ball] * Rolled in Adam's conditional breakpoint enhancements. [Adam Dingle] "A register reference in a conditional breakpoint expression can use either a direct (i.e. "d5") or indirect (e.g. "12(a6)") addressing mode. Furthermore, a register expression can be suffixed with either ".b", ".w" or ".l" to indicate that the expression to be compared is either a byte, a word or a long. An an example, "12(a6).w == 1000" compares the two bytes at memory location (a6 + 12) to the value 1000. "d4.b == 100" compares the low byte of the d4 register to the value 100. "I have found this enhancement to be extremely useful for breaking into the debugger when a local variable (typically referenced off the a6 register in code built by CodeWarrior) has a certain value." * Fixed problem with running on dual-processor Windows boxes. [TBD] * There is now a "white paper" on Poser usage at the following URL: Changes for 2.1d26 (2/26/99) ---------------------------- * On the Mac, we were saving the device type to the .psf file twice. On Windows, we weren't saving the country type at all. [Waddah Kudaimi] * System call logging now also gets the names of library functions, and attempts to make a better stab at "dispatch" system functions (where a single dispatch code sub-dispatches to a suite of other functions, as with the Floating Point Manager). [Ken Krugler] * Sped up debugger communications via sockets by 20x. [Ron Marianetti, Mark Corry] * Added conditional breakpoints. This is bolted on for now, but should eventually be merged more seamlessly. It also only appears in the Windows version for now, but will be rolled over to the Mac in the next release. Changes provided by Adam Dingle of AvantGo. From Adam's release notes: New debugging features I've posted several messages recently to the palm-dev-forum mailing list in which I've pointed out several limitations of the debugger in CodeWarrior for PalmOS: it doesn't support data breakpoints ("watchpoints") and its conditional breakpoint implementation is very slow. To work around these limitations, I've added both data breakpoints and fast conditional breakpoints to the 2.0b3 emulator. A data breakpoint allows you to monitor a range of memory addresses for writes. When any code tries to write to the addresses you've monitored, execution will immediately break into the debugger. This can be extremely useful when you know that a certain data structure is being corrupted somewhere in your program, but you don't know where it is happening. To set a data breakpoint in the modified emulator, first launch the emulator, then start the debugger in CodeWarrior. In the emulator, choose the "Breakpoints" menu item. A dialog window will pop up; select the "Enabled" check box, then enter a start address and a number of bytes to monitor. The address and number of bytes may be either hex ("0x89abc") or decimal ("12345"). As an example, if the start address is 0x10000 and the number of bytes is 8, then any write to addresses 0x10000 through 0x10007 will break into the CodeWarrior debugger. Conditional breakpoints allow you to break when execution reaches a given address, but only when a certain condition is true. CodeWarrior for PalmOS supports conditional breakpoints, but its implementation is so slow as to be practically useless. As I pointed out in an earlier post to the palm-dev-forum list, in the CodeWarrior debugger, each iteration past a conditional breakpoint takes about 0.3 second, so you have to wait for an eternity if you have to iterate hundreds or thousands of times until the break condition is true (as is often the case in debugging). The modified emulator allows you to set conditional breakpoints with virtually zero overhead. To set conditional breakpoints, first launch the emulator, then start the CodeWarrior debugger. When you are stopped in the debugger, choose the "Breakpoints" menu item in the emulator. A dialog window will pop up which will allow you to set up to 6 conditional breakpoints. To set a breakpoint, choose a breakpoint slot and press the "Edit" button. A window will pop up where you can enter an address and a condition. The address can be either hex ("0x2468ace2") or decimal. Typically, you will determine the address where you want to break by selecting the "mixed" view in CodeWarrior to see a mix of source and assembly code. The condition you specify must be of the form " ", where is one of the 68000 registers D0...D7 or A0...A7 is ==, !=, <, >, <=, or >=. (Important: for now, all comparisons are UNSIGNED. This means that you can't use a condition such as "D0 < 0", which will always be false). is a hex or decimal constant By choosing the "mixed" view in CodeWarrior, you can see which 68000 registers represent which local variables in your program, and so you can construct an appropriate break condition involving a register. * Exposed Palm IIIx and Palm V support. * Fixed problem with ROM Transfer on EZ devices. [Yoshiyuki Kubo] * Relaxed form-object-validation rules to allow for zero-sized gadgets and tables. [Roger Flores] * Fixed bug in AutoRunAndQuit mechanism where Poser would quit when a sub-launched application would quit, not when the application-of- interest would quit. [Steve Haneman] * NetLibDmReceive should really work this time. [Doug Morrison] Changes for 2.1d25 (2/16/99) ---------------------------- * Different method for checking whether or not a library function is implemented. Poser still only checks known (i.e., Palm Computing) libraries, but now instead of using a hardcoded table, it takes advantage of the fact that the "open library" function appears right after the dispatch table. [Tim Wiegman, Adam Hampson] * Added WDEF project to Mac Poser project. Changed the way the outline region is calculated (should be more accurate now). * Added support for internal faster trap dispatching mechanism. The major effect of this is that Poser can now support non-debug Palm VII ROMs again. [Bob Ebert] * Added support for Autorun and AutorunAndQuit directories. These directories are like the Autoload directory. Applications in Autorun are loaded, and then one is chosen to be executed (by convention chosen to be the last file in the directory). Applications in AutorunAndQuit are loaded, and then one is chosen to be executed in the same way. When that application quits, Poser quits. If there are files in both Autorun and AutorunAndQuit, the last file in AutorunAndQuit is chosen for execution. The files in those directories can also contain launchable documents such as .PQAs. [Steve Haneman] * Centered the LCD on the Windows version. [Scott Johnson] * Better logging facilities. Here's what we've got so far: - Error Messages: undefined and unimplemented. - Warning Messages: If a dialog comes up that can be dismissed by clicking on the Continue button, this option causes the message to be logged. - Misc Gremlin Info: undefined. - Assembly Opcodes: unimplemented. Will eventually log assembly- level trace information (registers, PC, opcodes, etc.) - Posted events: events entered into the system by calls to EvtAddEventToQueue, EvtAddUniqueEventToQueue, EvtEnqueuePenPoint, and EvtEnqueueKey. - Received events: events returned by EvtGetEvent, EvtGetPen, and EvtGetSysEvent, - System calls: calls to Palm OS functions. - Application calls: unimplemented. Calls to functions in your own application. In order for this to work, the name of the function needs to be stored in memory following the function itself. CodeWarrior supports this convention, gcc currently does not. - Serial Activity: serial port being opened and closed, changes in serial port settings. - Serial Data: data being transmitted and sent. - NetLib Activity: calls to NetLib functions, parameter values and return values. - NetLib Data: data being transmitted and sent. - ExgMgr Activity: unimplemented. You get the idea... - ExgMgr Data: You get the idea... - High-level Debugger Activity: messages received from an external debugger and the replies sent back. - High-level Debugger data: details of the messages sent back and forth. Not all packets currently display all their data when this mode is turned on. - Low-Level Debugger Activity: trace of the low-level mechanisms that receive raw data from external debuggers and the raw data being sent back. - Low-Level Debugger Data: dumps of the raw data being sent back and forth. These options are presented in a dialog box with two tabs: Normal and Gremlins. The first tab contains options which are active during normal emulator use. The second tab contains options which are active when using Gremlins. Along with this new dialog, the Debug Options and New Gremlins dialogs have also been changed. The logging checkboxes have been removed from Debug Options (along with some currently unused checkboxes). The logging checkboxes in the New Gremlins dialog have been replaced with a "Logging Options..." button that brings up the Logging Options dialog. A new checkbox ("Continue Past Warnings") has been added to the New Gremlins dialog that controls what happens when a non-fatal error dialog is displayed; if possible, these error dialogs will automatically be dismissed if this option is checked. For performance reasons, all logged information is stored in an internal memory buffer. Additionally, only the most recent information is kept. After a certain threshhold, old information is discarded. The amount of information kept is initially 1Meg, but that can be changed by calling HostSetLogFileSize. The in-memory buffer is flushed on the following occassions: - The application quits. - An error is displayed. - A new Gremlin is started. - An exception occurs. Logged data is written to a file named "Log####.txt", where #### is a number ensuring the file name's uniqueness. Contents of the log file are of the form: