Welcome to the Palm OS Emulator, v2.0!

These are the release note for the Palm OS Emulator (formerly known as
Copilot).  For Windows Copilot 1.0b9 and Macintosh Copilot 1.3 users,
the Palm OS Emulator may look much the same, but there have been a lot
of internal changes (see below).

We also have much planned for the Palm OS Emulator.  For descriptions of
some of the changes to appear in future releases, see the second half of
this document.  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).

When using this version of the Palm OS Emulator, keep in mind that the
UI is a little rough.  We have a revamped UI mapped out, but haven't had
time to implement it for this release.

If you want to build the Palm OS Emulator, you will need Visual C++ 5.0
on Windows, and CodeWarrior Pro 2 on the Mac.

	IMPORTANT: there is a PPC code generation in CW Pro 3 that
	prevents correct emulator execution.  If a signed 16 bit value is
	stored in a PPC register, and that value is shifted using the >>=
	operator, it is possible for bits from the upper 16 bits to be
	shifted into the lower 16 bits.  Until this bug is fixed, or until
	the exact characteristics of this bug can be defined and a
	workaround devised, use CW Pro 2 to build the emulator.

Please send comments, suggestions, and bug reports to devsupp@palm.com.


Known Bugs
----------
*	Florent reports getting "not enough memory to allocate RAM" error
	when starting _without_ a RAM file.

*	Neil needs to receive cmdInitDatabase when his app is installed.

*	There are problems downloading ROMs at 57.6K and 38.4K baud.  For
	now, use 28.8K on the Mac and 19.2K on Windows.

*	Keyboard events are entered into the Palm OS ROM only when other
	events are occuring.  One side-effect of this is that you can only
	enter text when the insertion point is blinking.

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

*	"I've noticed that if I try to load an app from the most recently
	loaded apps list and the app doesn't exist (because, say, I've
	renamed the file), the Emulator doesn't complain that it can't find
	the file."


Changes for 2.0b3
-----------------
*	Windows only: Added Greg's nifty Hyperlink controls to the About box.

*	Added Keith's Palm OS Emulator article from HHSJ.

*	Windows only: Added Greg's fixes to the serial emulation routines.

*	Fixed Headpatch::SysGremlins bug where it would read garbage from
	the stack when trying to get the selector parameter.

*	Got A-Trap breaks working ("atb" from the PalmDebugger).

*	Windows only: bumped number of recently loaded application from
	five to nine.

*	Fixed 1.0 ROM compatibility problem: the emulator was trying to call
	a function introduced in Palm OS 2.0 (PrefSetPreference).


Changes for 2.0b2
-----------------
*	Windows only: Fixed bug that would zap the version number in the
	system preferences when attempting to set the timeout value to be
	infinite.

*	Fixed bug that would cause the emulator try to access invalid memory
	if the emulated app tries to access invalid memory.

*	If an exception occurs that an external debugger should handle and
	there is no external debugger, instead show a dialog that reports
	the problem and forces the user to reset.

*	When getting application version string, look for ID's 1 and 1000.

*	Windows only: Fixed bug that would leave a debugger-related messaging
	event object signalled if there were no external debugger.


Changes for 2.0b1
-----------------
*	Prevent the device from ever going to sleep.  Letting it go to sleep
	is only annoying, and doesn't accomplish anything.  You can make the
	device go to sleep by setting the timeout value in the General
	Preference panel, but that setting will get reset back to "never" on
	any reset.

*	Mac only: Fixed problem that would cause the emulator to hang if
	you tried to open a console window from within MWDebug.

*	Got alarms working.

*	Mac only: Wasn't doing a "weak import" of AppearanceLib in non-debug
	version.

*	With regards to a change in 2.0d8, it's OK to load an application that
	already exists in ROM.  The RAM-based version will override the one
	that's in ROM.


Changes for 2.0d9
-----------------
*	The handling of DbgBreak was broken.

*	Allow application to resume after ErrDisplayFileLineMessage.  This
	is handy in cases where you're using ErrNonFatalDisplayIf to display
	warning messages and it's OK for the application to continue
	execution.

*	Accidentally turned off checksumming of post-2.0 ROMs; turned it
	back on.

*	Windows only: there was supposed to be a feature whereby holding
	down the caps-lock key when starting the emulator would cause it to
	bring up a Download/Browse/Quit dialog box.  However, the dialog box
	would actually come up if the caps-lock key had ever been toggled
	since the last time the emulator had been executed. Fixed.

*	Selecting "Gremlin/New..." while a gremlin is currently running
	will now switch to the new gremlin.

*	Fixed error message to say RAM instead of ROM when saving a RAM
	image file, and added an exception handler to deal with the ensuing
	thrown exception.


Changes for 2.0d8
-----------------
*	Added Greg's Copilot article from HHSJ.

*	Added updates to Guide.html from Roger.

*	Removed support for the 2.0 Debug ROM that offset the low-memory
	globals byte four bytes.  There were problems with that ROM that
	would cause it to crash.

*	Gremlins now latches into KeyCurrentState in order to randomly set
	the bits so that applications can respond to them.

*	The patched versions of SysFatalAlert and ErrDisplayFileLineMsg now
	display dialogs containing "Debug" and "Reset" buttons.  Clicking on
	"Debug" will simulate a bus error, which an external debugger will
	catch.  Clicking on "Reset" is the same as selecting the Reset menu
	item.

	NOTE: currently, clicking on the "Debug" button when there's no external
	debugger running will result in the ROM attempting to handle the
	simulated bus error.  If the ROM is a Debug ROM, it will attempt to
	contact a debugger over the seial port.  Since there is probably no
	such debugger listening on the serial port, the emulator will appear
	to hang with a blank screen.  Selecting the Reset menu item will
	restart the ROM.

*	Failures reported via SysFatalAlert and ErrDisplayFileLineMsg
	during application execution have more info for users to report. 
	The dialog has text along the lines of:

		SubHunt 2.0 has failed while running Gremlin 2 at 20,000 events.
		SubHunt complains "SubHunt.c: Line 100: Score too good." If
		this is the latest version of SubHunt, please report this to the
		application author.

	or:

		SubHunt 2.0 has failed.  PalmOS complains "Window.c: Line 100:
		Invalid Window."  If this is the latest version of SubHunt,
		please report this to the application author.

	NOTE: currently no effort is made to determine if the application or
	the PalmOS is generating the message.  This shortcoming will be
	addressed in a future version.

*	Use application name from 'tAIN' resource when generating the list
	of applications for the New Gremlin dialog box.

*	Reduced the 10% random pen tap chance in Gremlins to 2% (per
	Roger's recommendation).

*	Internal change: added "TrapIndex" inline function for converting a
	trap number (0xA000) to an index that can be used with the trap
	table. Standardized on its use all over.  This function converts by
	merely masking off the upper byte (which mirrors what the ROM does)
	instead of subtracting "sysTrapBase" from trap numbers (which fails
	because some applications appear to use trap numbers that don't have
	"A" in their upper nybble).

*	Internal change: we patch ROM system functions.  We also call ROM
	system functions.  Now, whenever we call a ROM system function, any
	trap patches made to that function are called (they didn't used to
	be).

*	Fixed emulator/debugger communications bug that occured when one
	would quit and then restart (needed to refresh -- not just flush --
	the handle to the other guy's window). (Windows only)

*	After the UI has been initialized, prevent even the ROM from
	writing to low-memory (except from HwrSleep, which patches out the
	exception vectors).

*	When trying to load an application that's already in ROM, warn with
	a specific error message instead of a generic one.


Changes for 2.0d7
-----------------
*	Gremlins now works better with "ill-formed" forms (forms with no
	"live" objects in them).  Gremlins will also now generate random
	taps 10% of the time instead of always trying to target form
	objects.

*	Turn off Gremlins on a reset or fatal system error.

*	Only the last 128K of Gremlins logging text will now be written to
	the logging file.

*	Added "Debug" button to the "Application so-and-so just made an
	invalid memory access" dialog.  Clicking on this button emulates a
	bus error. If an external debugger is running, it will be notified
	of this bus error.  If not, the emulated ROM will take over,
	displaying a Fatal Error dialog.

*	Fixed a bug where the emulator itself would cause a "The current
	application just accessed Palm OS Globals ..." to appear after
	downloading an application via MWDebug.


Changes for 2.0d6
-----------------
*	Added ROM Transfer project (for Mac).

*	Added Docs folder.

*	Added Plugins folder containing MWDebug plugins.

*	Tweaks to PCH file generation for CW Pro 3.

*	Added HotSync to Mac side.

	IMPORTANT: For both versions of the Emulator, HotSyncing has only
	been tested between two machines (in both cases, between a Mac and a
	PC). I don't know what performance is like when both the emulator
	and HotSync are running on the same machine.

*	Now enable and disable Gremlins menu items in WinEmulator.

*	Fixed bug in ROM Transfer.prc which would cause it to crash on Palm
	III's.

*	Fixed some bugs in RAM file management in Mac version.


Changes for 2.0d5
-----------------
*	Checksum the ROMs when they're loaded.  This checksum is used to (a)
	validate the ROM contents (for pre-3.0 ROMs, the checksum is checked
	against a hard-coded list of ROM checksums, for 3.0 ROMs and later,
	the checksum is checked against the checksum in the ROM header) and
	(b) determine if we're running the 2.0 debug ROM, which needs
	special hacks activated in order to run.

*	Allow *.* patterns when loading ROM and application files.

*	Support serial port emulation in WinEmulator (not in Mac, yet).

*	Added method for applications to call the emulator (see
	EmuTraps.h). Note that there currently is no method to see at
	runtime if an application is running under the emulator or not.

*	Tweaks to get Mac version to build under CWP R2 with CW4POS R4
	installed in it.

*	Backed out checksumming of pre-3.0 ROMs until I get get an accurate
	set of checksum numbers.


Changes for 2.0d4
-----------------
*	Reset auto-off timer when processing debugger packets.

*	Changed way tailpatches are implemented.  I used to set the return
	address of a system function I was tailpatching to point to a TRAP
	$E opcode (saving the original return address in an array in the
	emulator). This approach has the advantage of not modifying any
	opcodes in memory, and handles recursive system functions very well.
	Sadly, the critical flaw in this approach is that some operations
	need the real return address to be on the stack.  For instance, the
	TRAP $F handler (TrapDispatcher) in the ROM looks at the return
	address so that it can look up the $Axxx function selector.
	Therefore, the approach I now take is to write a TRAP $E into memory
	after the TRAP $F / $Axxx sequence, saving the overwritten opcode in
	a table. Recursive functions are handled by incrementing and
	decrementing a counter associated with that memory location.  When
	the counter gets back down to zero, the opcode is restored.

*	Added preliminary profiling stuff. Still disabled at this point.

*	Don't let the user enter pen and keyboard events if the CPU is
	stopped (for example, when it's in the debugger).

*	Don't run RPC commands from the debugger in TRACE mode (that is,
	run the commands, but turn trace mode off, first).

*	Respond better to a SysReset message from the debugger.

*	Remove tailpatch opcode when the CPU is reset.

*	In WinEmulator, restart the CPU after a screenshot only if it was
	running before we took the screenshot.

*	Fixed problems with synchronization between the UI thread and the
	CPU thread.  One way to trip up over the bug was to run Gremlins and
	at the same time click like crazy on the screen or hardware buttons.
	After a while, you'd get the dreaded "ATrap::DoCall returned and
	exception" dialog box.

*	Fixed Gremlins bug that would put it into an infinite loop if the
	top form had only frmBitmapObj, frmLineObj, frmFrameObj,
	frmRectangleObj, frmLabelObj, frmTitleObj, and/or frmPopupObj
	objects in it.  Games like SubHunt, HardBall, and Reptoids are
	examples of programs with such forms.

*	Changed the low-level mechanism for handling exceptions and
	entering the debugger.  With the old way, an exception would cause
	the main CPU loop to exit before the debugger was notified about the
	exception.  But if there were no external debugger to notify, there
	was no way to cleanly restart the CPU loop in order to have the
	emulated ROM handle the exception (either by trying to connect to a
	serial debugger, or by showing a fatal error dialog).  Now, the
	attempt to contact an external debugger is made before exiting the
	CPU loop.  If the attempt succeeds, the CPU loop is exited.  If the
	attempt fails, the normal exception handling process takes over
	(i.e., the appropriate vector from the low- memory exception table
	is loaded into the PC and execution continues).

*	Added support for 2.0.2 Debug ROMs (added minimal support for 68681
	serial access and account for different low-memory variable
	locations).

*	Removed support for ROM files with the pattern "ROM *". This
	pattern also matches the "ROM Transfer.prc" application, causing the
	emulator to try loading it if there are no other candicates.

*	For MacEmulator, save RAM files with the type '(Pi)RAM' and ROM
	files with the type '(Pi)ROM'.  Also, if untyped files are accessed
	as RAM or ROM files, they are changed to have the appropriate type.

*	Restarting and stepping of Gremlins in WinEmulator more reliable.

*	Better warning messages for applications that:

	-	Access low-memory directly
	-	Access system global variables directly
	-	Access the screen directly
	-	Access Dragonball registers directly


Changes for 2.0d3
-----------------
*	Lots of internal changes:

	-	Names changed from Foo_Bar format to Foo::Bar format (where Bar
		is a static member function of the Foo class).  This change
		makes it easier to look things up in a class browser.

	-	Handling of memory access errors codified.  All accesses are
		checked; any errors are reported through bottleneck functions;
		all accesses can be turned on/off with compile-time and/or
		runtime switches; added CEnableFullAccess class that allows
		internal functions full access to memory (i.e., turns off memory
		access checking) so that we can do things like set breakpoints
		in ROM.

	-	Added Palm copyrights to all files.

	-	Standardized on PowerPlant-style function header comments.

	-	Removed all mention of Pilot and Pilot-derivatives.

	-	Untemplatized some functions in UAE_Utils that didn't need to
		be templates.

	-	Sped up uae_memset by using long-word access.

	-	Changed way tail patches are implemented.  Previously, I'd write
		a TRAP $E opcode into memory after the TRAP $F/Axxx instruction
		sequence that would invoke the trap.  The problems with this
		approach is that (a) this wouldn't break on all returns from the
		function if it called itself recursively, and (b) it modified
		memory in a way that would need to be reversed on selected
		occassions (e.g., when we entered the debugger, or when RAM was
		saved to disk.  Instead, when a trap function is called that I
		wish to tail patch, I modify the return address from the
		function in such a way that I get control when the function
		exits (I save the old return address and replace it with a
		pointer to a TRAP $E opcode, which leads to a CPU exception
		which I catch in Software::ProcessException).

	-	Patched calls to SysDoze and SysSleep so we better know the
		state of the ROM/CPU.  We don't actually use this information,
		yet.

	-	Centralized all compile-time pre-processor symbols into
		Switches.h.

	-	Centralized all byteswapping into Byteswapping.h/.cpp.  Used a
		templatized Canonical() function on the Mac so that Canonical is
		zero-overhead no matter what type it's called with.

	-	Added internal diagnostic logging functions.

	-	Lots of timing tests to optimize memory access and core CPU
		emulation loop.

	-	Committed to "word-swapped" memory layout in x86-compatible
		systems.  Removed experimental alternative memory layout code.
		Look for WORDSWAP_MEMORY symbol for areas that are byte-order
		sensitive.

*	Fixed some bugs with external debugger hooks.

	-	Now support the same notion of "sockets" as the SerialLinkMgr.

	-	On some entries into the debugger, the PC would incorrectly be
		adjusted to point 2 bytes before the instruction causing the
		debugger entry instead of pointing right at the instruction.

	-	Finally added debugger hooks to WinEmulator (missing
		functionality's considered a "bug", right?).

*	Fixed bug where UAE would allocate a significant chunk of memory and
	then try using it without first checking that the allocation attempt
	succeeded. This would result in the Mac emulator freezing on startup
	when emulator a 4Meg device.

*	Fixed ROM Transfer.prc to download Palm III ROMs. Updated Mac
	"Download ROM" command to work with larger ROMs. Added "Download
	ROM" to Windows emulator.

*	On startup, if WinEmulator can't find a ROM, it will ask you to
	find one or download one.

*	On startup, if the capslock key is down, WinEmulator will _always_
	bring up the dialog asking you to find a ROM file or download one.

*	Removed "Backlight" and "Enter debugger on startup" properties from
	WinEmulator.

*	When looking for a ROM file, Emulator use the following search
	order:

	- The file you've explicitly specified in Properties (WinEmulator only).
	- The first file in the Emulator directory ending with ".ROM"
	- The first file in the Emulator directory ending with " ROM"
	- The first file in the Emulator directory starting with "ROM."
	- The first file in the Emulator directory starting with "ROM "

*	Fixed problem where mouse clicking wasn't working with 1.0 ROMs. I'm
	still not sure what the root of the problem is, but I've added a
	check for 1.0 ROMs and implemented a workaround.

*	In WinEmulator, RAM image is automatically saved to and read from a
	file based on the name of the ROM being used and the RAM size
	requested. The name of the RAM file is "<ROM file>.<RAM size>.RAM".
	In other words, the old Windows Copilot functionality is back (it
	was temporarily removed during the Grand Code Unification).

	The format of this RAM image file is a little different, however.
	There are chunks of data in this file, each tagged with an ID and a
	chunk size. For now, the only defined chunk is 'ram '. In the
	future, there will be chunks for register state, associated ROM
	version, etc.
	
	In MacEmulator, the file saving operation remains the same as in Mac
	Copilot, but the file format is the same as in WinEmulator.

*	Switched to new case graphics.


Changes for 2.0d2
-----------------
*	Fixed MacEmulator bug when switching between 1x and 2x screen
	sizes.

*	Fixed bug where loading an application would smash 4 random bytes
	of memory.

*	Sped up emulation on the Mac by 20% by streamlining some
	Mac-specific operations.

*	Sped up core emulation loop on both platforms by moving some
	not-oft-used functionality into some subroutines, thus simplifying
	the core loop.

*	Added hooks for external debugger.

*	Made Gremlins deterministic.

*	Ensured Gremlins did the same thing on both Mac and Windows.


Changes for 2.0d1
-----------------
*	Support for Palm OS 3.0:

	-	memChunk headers changed, so reliance on their format when
		loading applications has been removed.

	-	More complete support for Dragonball registers.

	-	Allow for 96K and 128K dynamic heaps.

*	Common source code base.

*	Refitted with latest UAE sources.

*	Can load .prc files larger than 64K.

*	Windows version is much smaller.

*	Mac version is much bigger (it's a FAT binary).

*	Removed built-in debugger.

*	Support grayscale mode.

*	Now emulates hardware method for turning on backlighting (holding
	down the power key).  Properties option is no longer needed.

*	Added screen shot command.

*	Added Gremlins. (Note that user input (typing, mousing) is disabled
	while Gremlins is running due to the incompatible ways in which they
	enter their events.)

*	Set the Palm OS date on startup.

*	Trap dispatcher is now run as native code instead of being
	emulated. This results in about a 10 - 12% speedup.

*	Auto-calibrate the pen on startup; no more digitizer screen.

*	InternetConfig-savvy About box on the Mac. Panel-savvy About box on
	Windows.

*	Gremlins can now confine itself to a single application.

*	Emulate MemSet, MemMove, and RctPtInRectangle with native code for
	15% performance increase.

*	While Gremlins is running, can optionally log to a text file:

	-	posted events
	-	received events
	-	system functions called
	-	time of execution.


To do
-----
*	In Software::ProcessRTS, check that the return address looks OK.
	This check will catch some places where the stack gets overwritten
	by applications being developed.

*	Allow Gremlins to run on multiple selected applications.

*	Allow logging of application functions in addition to system
	functions when running Gremlins.

*	Make sure Gremlins turns itself off in all appropriate
	circumstances (right now, I don't think we do that in the "prevented
	access" dialogs).

*	Update to latest UAE sources (we're using 0.6.9; it's now up to
	0.8.1).

*	Investigate using Aaron Giles' CPU emulation sources from MacMAME
	(they're written in optimized PPC assembly).

*	Look into using Asgard 68K emulator (in optimized PPC assembly).

*	"The simulators maps the functions keys F9 to F12 to the hard keys
	and Page Up and Page Down are the scroll keys.  For consistency this
	should be followed."

*	"Gremlins doesn't show the red trail of what it does.  This is
	actually a really important feature.  It lets you see what it's
	doing and is very valuable after a crash to see where gremlins was
	working.  Unless this is incredibly difficult should be added to the
	ToDo list.  This feature also makes Gremlin much more "fun" for
	users to watch and apply gremlins to their favorite (or least
	favorite) app."

*	"You might want the preferences to pop up the first time the
	emulator is run so the user knows they're there.  I'm not as sure
	about this idea."

*	"A feature suggestion which I believe would be very helpful to all
	developers: QuickSwitch ability to switch between different ROM/RAM
	images.  I frequencly want to test my app on OS 1.x, 2.x, and 3.x. 
	Right now, this involves renaming a bunch of ram/rom files.  It
	would be nice if this task were simplified to opening up the new rom
	file which would automatically open up the ram file associated with
	it."

*	"We should define a resource for contact info.  I forget the rules
	but I'll suggest something like 'info' at 1000 for contact info.  It
	is defined as an ASCII string to contain data for users to contact
	the app's author. A web address or an email address are good
	examples.  This issue needs to be raised to those who can do this."

*	"...a serial log would be real handy to some developers.  Some way
	to display data as ASCII would be helpful."

*	"I tested an app (Backgammon) in Poser using Gremlins.  It crashed
	with an address error.  I clicked OK.  Then I chose Stop from the
	Gremlins menu, and Poser hung.  Perhaps it was waiting to
	"communicate" with the Pilot somehow?  Anyway, it froze..."

*	Add Turnkey features so that developers can "publish" stand-alone
	demo versions of their applications.

*	Mac case graphics need new palettes to look right.

*	Fix LoadApplication to not call get_real_address.

*	Support IR.

*	White screen for Mac

*	Load ROMs via a "Load..." menu item

*	Prefer name over file ID in aliases in Mac version

*	Do stuff with drag & drop

*	Undo the machine state

*	Support Burr-Brown digitizer (and other Palm III hardware?)

*	Support ************.

*	Automated testing / scripting

*	Support drop-ins for cards

*	Roadmap generation

*	Menu item to pause/resume CPU.

*	Consider making the following calls native:

	- ScrCompressScanLine
	- ScrDeCompressScanLine
	- ScrCopyRectangle
	- ScrRectangleRoutine
	- ScrSendUpdateArea
	- MemSet
	- MemMove
	- StrXXX (StrLen)
	- RctPtInRectangle
	- TimGetTicks
	- FntCharsWidth
	- FntLineHeight
	- FntLineWidth
	- WinDisplayToWindowPt
	- WinWindowToDisplayPt
	- WinClipRectangle
	- PenRawToScreen
	- Others?

*	Save / restore complete state state.

*	Map sound functions.

*	Clipboard conversion.

*	Investigate these from Zilot:

	- Watch out for screen register change of content for page hit system ->
	  faster redraw.
	- Really optimized memory access. Nothing remains of copilot's one.
	- The emulated 68k can go up to 950000 instruction per second on my
	  8500/165!
	- Can't install app until Pilot has booted.

*	Have Copy menu item copy screen to clipboard. (only if Palm OS
	clipboard is empty).

*	Break on A-Traps.

*	Sync with or update from HotSync (NOT over a serial loopback
	cable).

*	Clear stack on RTS.

*	Call MemHeapSize to get size of heap to emulate.

*	Add a keyboard shortcut to enter Graffiti shortcuts.

*	Record other exceptions other than Trap F.

*	Show indentation level in ATrap log.

*	Show _all_ enqueued events, not just those posted by Gremlins.

*	Monitor chip selects. If they change, recalculate dynamic heap
	size.

*	The "Save RAM Changes?" dialog should have a Cancel button.

*	Look up system function names at runtime instead of hardcoding the
	list.

*	Give indication of what low-memory location was trashed by the
	application.

*	User fewer hardcoded values (like 160 for the screen size).

*	Add user-level logging (i.e., let the user add lines to their
	application that would send messages to a window or file).

	"One feature I've always wanted is the ability to print to a log
	file. Right now we use gcc to build our app, and debugging often
	consists of printf() combined with SysTaskDelay().  If there were a
	function apps running in Poser could call like:

		extern void PoserAppendToLog(char *str, int length);

	it would make our lives much happier."

*	Add Autoload directory:

	"<A developer> has a development tool that they are adapting such
	that the tool can create Palm applications.  They are planning to
	have a .prc that will act as a runtime engine, and then they will
	load what will likely be .pdb files that have all of the specifics
	for a particular application.  (Screen layouts, application logic,
	etc.) They would like to be able to press a button in their
	development tool and have that load the .pdb file into the emulator
	automatically, and start up the emulator."

*	Add a handier API for loading applications. (Other functionality,
	too?)

*	Candidates for e-traps:

	- Logging messages
	- Turning memory access checking on/off.

*	"I have a small feature request. Can I get the prc file open panel
	to do multiselect? Many times I need to reload one or two prcs as
	well as a couple of pdb files and it's a annoyance to have to load
	each one separately."

*	"Another little nit that bugs me about the older versions of
	Copilot was that if you were not running in realistic mode, and the
	emulator shut down, you couldn't turn it back on. I always thought
	that was silly."

*	"The gremlin functionality still bothers me because of it's interm
	state, so it causes me to still think about it.  One issue is I'd
	like the gremlin dialog to ideally have the right app selected.  I
	think we can do this by having Poser watch DmCreateDatabase for appl
	and panl databases, and to use the last one."

*	"The other thing is the screen updating.  As intern step before
	updating like the simulator, perhaps we can check to update the
	screen when EvtGetEvent is entered?  Most draw operations are
	"complete" before the program calls EvtGetEvent again.  Perhaps we
	should do the same for PenGetPoint."

*	Support the LCD width and height registers so that panning works.


--------------------------------------------------------------
Greg's source-review comments:

I was poking through the source and saw some areas where you had
indicated questions about what I was doing. None of these appear to be
very pressing questions, but here goes anyway...

lcd.cpp: PaintScreen: I don't remember exactly why I had different
drawing code for NT. I develop on NT, and I think I initially coded the
single StretchBlt, but for some reason (NT version or display driver or
something), it didn't work. So I did it the long way to work around
whatever it was and left the StretchBlt for 95 because it seemed to work
there. The StretchBlt may have a better chance of working with today's
NT versions, I haven't tried it (nor have I ever heard of the display
logic not working).

lcd.cpp: DoDisplayThread: The GetVersionEx code is usually quite
forgiving regarding the value of the dwOSVersionInfoSize field. Of
course this field should be set before calling the function (whoops),
but in many cases it seems to work anyway. The above NT-specific drawing
code did run when I wrote it, for what that's worth. :)

pilotcpu.cpp: CPU_init: Why call SetEvent(CpuStoppedEvent) when I could
have passed TRUE in the CreateEvent on the line above? Beats me.

pilotcpu.cpp: CPUStopper::CPUStopper: The warning message in this
function is the one that's most often quoted back to me in messages from
people asking for help with Copilot. Generally the problem is they've
got half a ROM file and the boot sequence hangs, at which time they
attempt to load an application. This message is sort of inappropriate at
this point, because it leads them to believe they should turn the
emulator "on" first. Not knowing how to do that, they click on the
nearest mailto: link and I hear about it. Perhaps Poser users will run
into this problem less often because of the better startup code, but
nevertheless I think this message could use a bit more explanation.

cpu_reg.cpp: Emulator::Execute: The exception handling overhead in VC++
is minimal, just a register save and branch when there are no exceptions
(just like CodeWarrior).

ram_rom.cpp: DBReg::tmr2StatusRead: Hmm, I don't update the TMR2 count
value. As with everything else that's missing in my DragonBall
emulation, it's probably because I never found anything that needed it.
If you know otherwise, by all means implement it. Also, the magic value
of 16 counts per status read seemed to be about right for the programmed
timer 1 frequency. It isn't likely to be right for timer 2.

ram_rom.cpp: DBReg::scrWrite: The odd logic I used was attempting to
follow the behaviour documented on page 2-6 of the DragonBall manual,
where for the top 3 bits, "Writing a 1 to this bit clears it while
writing a 0 has no effect." ... but I botched it up. What I should have
written was:

    db_SCR.x &= ~(value & 0xE0);

but somehow it didn't come out that way. Of course it doesn't matter one
way or the other in the grand scheme of things, but when I wrote that
particular line of code I had no idea how faithfully I needed to follow
the DragonBall specs.


--------------------------------------------------------------
Florent's source review comments:

Some notes on your PowerPlant usage:

*	In window #10020, you are using a "text" object (LTextEdit, I
	guess). This one disappears in the next version of PowerPlant. You
	should use an LTextEditView instead

*	I'm not sure using LGAxxx classes is a good idea. They are all
	going to vanish at some point in time. You should switch to Lxxx
	classes (LDialogBox instead of LGADialog, etc.)

*	In the "progress" window of the download rom, you use a private
	pane for the progress bar. You should use PowerPlant's LProgressBar,
	included in the new appearance controls of PowerPlant. The more
	standard classes you are using, the less maintenance you have to do
	on the Mac UI code.


--------------------------------------------------------------

Here's a cosmetic fix I'd like to see in Emulator (for Windows) -- add a
system menu and minimize/close buttons to the title bar, and a
right-click menu to the Emulator button in the Windows task bar.  The
menu would contain just the standard Move/Minimize/Close items.  Also
make sure Emulator responds to the

"Minimize All Windows" command from the Windows task bar menu. 
Currently it doesn't, so Emulator stays in view after everything else
mimimizes.

The title bar menu/buttons would be only for unrealistic mode.  In
realistic mode (the plastic case around the screen) the task bar menu
would be fine. I suspect this feature is fairly trivial to implement.

Ok ok, so I'm a neat freak about keeping my screen free of clutter!  :-)

-slj-


  
Suggestion for Emulator (Windows): add a maximize feature to zoom the
emulator screen to the largest possible size.  Detach the Graffiti area
from the main 160x160 screen, and zoom the main screen as big as
possible, then just put the Graffiti area (and hard buttons) next to it.
 On a 1024x768 screen this would allow a main screen of 640x640 with a
Graffiti area of 320x112.  The standard Mimimize menu item/button could
toggle into this mode. The existing 1X/2X zoom feature would stay the
same.

No I'm not blind!  This is for demos.  We do a fair amount of demoing
software on overhead projector monitor units at Oracle, and eventually
our product might be taught in training sessions on the same equipment.
So a big-screen version of Palm OS Emulator would be very nice for this.

*Much* better than the Windows CE Emulator being used down the hall. 
:-)

-slj-


--------------------------------------------------------------

*	Logging:

	- ATraps called
	- Other exceptions
	- Last few instructions
	- Memory access
	- Instruction cycles / profiling

*	Sanity checking (see also DTS list below):

	- Memory access
		- Low memory
			- Only ROM accesses low memory.
			- NO ONE accesses 0-7 after startup.
		- DRAM access
			- Make sure apps only write within memchunks.
		- SRAM access
			- no writes while protected.
			- do apps get direct access? Or do they have to
			  use DMRead / DMWrite.
		- ROM access
			- What are the rules here?
		- Dragonball access
			- No direct access from apps.

	- Traps
		- don't try to call a trap that doesn't exist

	- Parameter checking
		- NULL vs. not null
		- correctly formed structures
		- immediate values in correct ranges

	- Memory chunks
		- Memory leaks
			-	EZ way to do this is look for memory blocks with
				app's id tag.
		- don't write outside them
		- zap contents of new blocks
		- zap contents of free blocks
		- check the heap consistancy
		- check for locked handles
			- locked when they shouldn't be
			- unlocked when they should be
			- locked too many times.

	- Stack overflow

--------------------------------------------------------------

*	Don't overfill the stack

	Allocating large numbers of local variables (or extremely large ones)
	can result in hard-to-debug heap corruption. The stack is only about
	2k; be stingy with stack-based variables!

*	Directly accessing globals or hardware

	Global variables and their locations can also change; use the
	documented API functions or disable your application if it's run on
	anything but a tested version of the OS. Future devices might run on
	a different processor than the current one.

*	Making assumptions about the screen

	The location of the screen buffer, its size, and the number of pixels
	per bit aren't set in stone; they might well change. Don't hack
	around the windowing and drawing functions. If you are going to hack
	the hardware to that will circumvent the APIs, save the state and
	return the system to that saved state when you quit.

*	Allocating zero-length objects

	It's not valid to allocate a zero-byte buffer, or resize a buffer to
	zero bytes. Palm OS 2.0 and earlier releases allowed it, but future
	revisions of the OS might not permit zero-length objects.

*	Reading and writing to NULL (or low memory)

	Remember to check your calls to MemSet, MemMove, etc.. to make sure
	the pointers are non-NULL. (If you can do better validation than
	that, so much the better.)  Also validate that pointers your code
	obtains from some structure or API call are not NULL. Consider, in a
	debug build, overriding MemMove (and similar functions) with a
	#define to validate the parameters.

