========================================================================
News (latest changes) for the Palm OS Emulator
Copyright (c) 1999-2001 Palm, Inc. or its subsidiaries.
All rights reserved.

Please send bug reports, comments, suggestions, etc. to
<mailto:bug.reports@corp.palm.com>
========================================================================

========================================================================
	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.txt for a list of people who have submitted
	actual changes to the project.
========================================================================


Changes for 3.3 (xx/xx/01)
--------------------------
*	Added Visor Edge support.  [James Phillips]

*	Added HandEra 330 support.  [Dan Fahrion]

*	Better checking for invalid database names as .prc, .pdb, and .pqa
	files are installed.  Error message now also includes more text
	describing why the name is invalid.

*	When reporting invalid database dates when installing a file, now
	include the name of the file containing the database.  [David A.
	Desrosiers]

*	Better error message when reporting that a .prc, .pdb, and .pqa
	file cannot be installed because one of its resources or records is
	too large.

*	Removed feature of Gremlins which would turn the device off and on
	every once and a while.  The mechanism used to perform this could
	alter the emulated hardware timers and clocks, such that two runs of
	the same Gremlin number would result in different outcomes.

*	NOTE: the following new feature was added to this release and then
	disabled.  "Beaming" over TCP or serial worked only intermittently. 
	We'll try to get this working in a future release.  Until then, Mac
	and Windows users will see a disabled IR option in the Preferences
	dialog.  Original release note was as follows: Limited IR emulation.
	The user can choose to redirect IR data out the serial port or to
	another instance of Poser running on the same computer. Note that
	although TCP is used to exchange data between the to instances of
	Poser, exchanging data between Posers running on different computers
	is not supported.  The network latency and transmission times is
	greater than the timeout values used in IR communications, leading
	to broken connections.

*	Include preliminary plug-in support.  Current support extends to
	letting external plug-ins patch traps and access memory.  [Anthony
	Fishbeck]

*	Internal change: continuing work to remove Dragonball-specific
	assumptions from the source code in preparation for adding ARM
	support.

*	Added support for downloading ROMs over USB on Mac and Windows.

	On Windows, you must have Palm Desktop 4.0.1 installed in order to
	get the USB driver.  You must then make the library for the driver
	("USBPort.dll") available to Poser.  Either copy this library from
	Palm Desktop's directory to Poser's directory, or move it into the
	Windows system directory (thus making it available to all
	applications).

	On the Mac, you must have Palm Desktop 2.6.3 installed in order to
	get the USB driver.

	Note that the ROM Transfer application fails to work on Handspring
	devices, so unless someone figures out why, you can't download those
	ROMs.  And though you can download Sony CLIE ROMs, Palm's version of
	Poser doesn't emulate those devices, so performing that exercise is
	not very useful.  Which means that the addition of this feature is
	of most benefit to those with Palm m500s and m505s.

*	Support backlighting (two levels of brightness) for m505.

*	Report direct access to BitmapType data structures.

*	Report calls to functions that will no longer be available on
	future versions of Palm OS.  This list appears at the end of this
	note.

*	Corrected minimum RAM sizes for Palm m500 and m505 (was 2MB, now
	8MB).

*	(Mac) Added better support for transliterating characters exchanged
	between the host and Palm OS emulated clipboard.

*	(Windows) The popup menu would always appear on the primary monitor
	on a multi-monitor system.  [David Vaportrails]

*	Palm m500/m505 alarm LED is green, not red.

*	(Unix) GCC 3.0 support: added <ctype.h> where needed; no longer
	assume vector<T>::iterator is a pointer type; add exception
	specifications where needed; recognize that "map" is in the std
	namespace.  [John Marshall]

*	(Windows) Added "Stay On Top" checkbox to Skins dialog. [Jonathan
	Cox]

*	(Unix) Re-established X Windows window class (missing from Poser
	3.2).  [Chris Ridd]

*	(Unix) Link with OpenGL if it is installed (required by FLTK).
	[Holger Klawitter]

*	(Unix) SuSE 7.1 is rather pedantic and refuses to compile source
	code containing calls to tmpnam in it.  Therefore, on Unix, if
	mkstemp is available, use that instead.  Note that this mean that if
	you call HostTmpNam to get a temp file name, be warned that the file
	will already exist (but will still need to be opened).  [Holger
	Klawitter]

*	In Poser's implementations of NetLibSend, NetLibSendPB,
	NetLibReceive, NetLibReceivePB, and NetLibDmReceive (used when
	NetLib redirection is turned on), no longer try to be clever about
	when to call send vs. sendto or recv vs recvfrom.  Instead, always
	call sendto and recvfrom. That should provide the same
	characteristics as the Palm OS NetLib calls. [Gary Gorsline]

*	In order to support the various options in the Reset dialog, Poser
	emulates the pressing of the appropriate hard keys.  Pressing the
	key down worked fine, but Poser's determination of when to release
	the key wasn't always correct, and the Palm OS would sometimes fail
	to notice that the key was ever down.  Poser now tries a different
	approach that should be more definitive. [Mike McCollister]

*	Fixed profiling bug.  The memory cycles incurred fetching the
	opcodes were not being counted.

*	Fixed profiling bug.  Poser performs a lot of processing when
	system functions are called.  Some of this processing would access
	emulated memory, causing the cycles to do so to be counted against
	the running application.  This was incorrect.  Poser's operations
	should as transparent as possible and not show up on profiling data.

*	Added two HostControl functions:

		HostErr HostDbgSetDataBreak (UInt32 addr, UInt32 size)
		
			Configure Poser to enter an external debugger or display a
			message if the bytes starting at the given address and
			continuing for the given number of bytes are accessed in any
			way (either written two or read from).  The functionality
			here is the same that is provided in the Data Breakpoint
			section of the Breakpoints dialog.

		HostErr HostDbgClearDataBreak (void)

			Configure Poser to no longer enter an external debugger or
			display a message when the memory range specified in
			HostDbgDataBreak is accessed.

*	Added Gremlin Horde logging information: ROM version, ROM file
	name, RAM size, device name; statistics regarding the number of
	events each Gremlin was run for before generating an error; and
	error frequency and type statistics.

*	Rearranged New Horde dialog, and added Select All / Deselect
	capability for the Applications list, and a menu from which the
	application to be launched first can be selected.

*	Changed behavior of application switching -- SysUIAppSwitch is
	called on a random application from the list of applications
	selected in the New Horde dialog, rather than having a random button
	pressed.

*	Resuming a Horde run from a .psf file now terminates correctly, at
	the maximum depth originally specified, rather than at the next
	switching boundary, as before.

*	International Strict Checks (for checking multi-byte character
	display routines) is now a debugging option.

*	Stepping a halted Gremlin now behaves identically when running a
	single Gremlin or a Horde.

*	Files generated during Profiling now have unique names.

*	New warning displayed if comm port could not be opened on the host.

*	Added -pref command line option (-preference or -d can by used as
	synonyms).  This option changes preferences as stored in the
	preference file.  Its parameter has the form "key=value", and is
	treated the same way as the "key=value" lines found in the
	preference file.

*	Enabled the long-stillborn Logging Options for Warnings and Errors.
	Checking these options will log the text of message dialogs just
	before they are displayed.  You can then use this text in bug
	reports (or you can just use Ctrl-C or your platform's equivalent to
	copy the text from the dialog to the clipboard, as mentioned in a
	previous release note).

*	Added "ContinueOnWarnings" and "ExitOnErrors" preferences (along
	with UI for them in the Debug Options dialog).  If logging for
	warnings is enabled and ContinueOnWarnings is true, warning dialogs
	will be dismissed as if the user had pressed the Continue button. If
	logging for errors is enabled and ExitOnErrors is true, fatal error
	dialogs result in Poser exiting.

*	Added "SilentRunning" preference.  Setting this value to non-zero
	has the same effect as enabling the following separately controlled
	preferences: LogErrorMessages, LogWarningMessages,
	ContinueOnWarnings, and ExitOnErrors.
	
	Since it is not a good idea to set this option and forget it, Poser
	resets this preference to zero every time it starts up.  It resets
	the value *before* parsing the command line options, so using the
	-pref option to set it will work.

*	Added "DialogBeep" preference (along with UI for it in the Debug
	Options dialog).  Setting this value to non-zero causes Poser to
	beep every 2 seconds that a message dialog is displayed.  So as to
	not annoy your co-workers if you're not around to hear it, Poser
	will stop the beeping after 1 minute.

*	(Windows) If ExitOnErrors or SilentRunning is turned on, Poser
	exits with a status code of 2 if a fatal error had occurred at any
	time during execution, a status code of 1 if a warning had occurred
	any time during execution, and a status code of 0 if no errors or
	warnings occurred.

*	Changed the behavior of error handling when running a single
	Gremlin vs. running a Horde.  Originally, when there was only the
	ability to run a single Gremlin, Poser would display all warnings
	and errors as they occurred.  Later, when Hordes was added, it was
	felt that running multiple Gremlins was more of a "batch" operation,
	and so the user should not be bothered with error messages. Instead,
	if a Gremlin range was specified in the New Horde dialog, warnings
	and errors were logged to a file, the Gremlin resulting in the
	message was terminated, and Poser would switch to the next Gremlin.
	But if the user specified to run only a single Gremlin in the New
	Horde dialog, they'd get the original behavior of seeing error
	dialogs as they occurred.  Now, that behavior has been made
	consistent with the original behavior: by default, the user will see
	warnings and errors in dialogs as they occur.  If this is not
	desired, they can use the "ContinueOnWarnings" and "ExitOnErrors"
	preferences to log the messages instead.

*	Gremlins used to implicitly log error and warning messages.  Now
	that there is a UI for specifying whether or not to log messages,
	Gremlins no long automatically does that.  To support the change,
	Poser 3.3 will automatically turns on error and warning message
	logging for Gremlins the first time you run it.

*	(Mac, Windows) When loading or saving preferences, Poser now first
	looks for a preferences file in the same directory as itself.  If it
	finds that, it uses that as the preferences file.  Otherwise, it
	uses the old behavior of using the system's designated location for
	preference files.

*	Profiling fix: when converting cycle counts into time, make use of
	the actual CPU speed instead of assuming 16MHz.

*	(Windows) Fixed problem where a user could click on the Logging
	Options of the New Gremlin dialog multiple times, bringing up
	multiple Logging dialog boxes.

*	Indicate the active/inactive state of the Emulator's window by
	lightening it if it's inactive.

*	(Mac) Fixed many problems with calling HostGetFile, HostPutFile,
	etc.  Calling these functions would crash, and even if they worked,
	they wouldn't display any files, just folders.  [Hal Mueller]

*	Check for screen access in the storage heap.  The screen is not
	normally stored in the storage heap, but the hardware supports it
	and SuperWaba 2.0b3 puts it there. [Guilherme C. Hazan]

*	Fixed memory leak that could occur if an application running under
	Gremlins attempted to call SysUIAppSwitch in order to launch another
	application, that application took a command parameter block, and
	that application was not on the list of applications that could be
	run under Gremlins.  The command parameter block was leaked.

*	Added two new UI-less preferences: LogFileSize and LogDefaultDir.
	The former specifies the number of bytes that can be written to the
	log file before old bytes are discarded.  HostSetLogFileSize is
	still supported, but calling HostSetPreference will now do the same
	thing.  LogDefaultDir specifies where you want log files stored. If
	a Gremlin is running, log files will be stored in the Gremlin output
	file, as before.  But you can use LogDefaultDir to specify a
	directory for log files generated while not running Gremlins.  If
	this preference is not specified, log files are written to the
	Emulator directory, as before.  The existence of this preference and
	the -pref command-line option makes the old never-implemented
	-log_save_dir command-line option obsolete.

========================================================================

The following is a list of Palm OS traps that are not supported on future
OSes.  The list is broken into a number of different groups (which more or
less explains why the trap was not implemented).

Documented 'System Use Only' Traps
----------------------------------
AlmAlarmCallback
AlmCancelAll
AlmDisplayAlarm
AlmEnableNotification
AlmInit
AlmTimeChange
DmInit
EvtDequeueKeyEvent
EvtGetSysEvent
EvtInitialize
EvtSetKeyQueuePtr
EvtSetPenQueuePtr
EvtSysInit
ExgInit
FrmAddSpaceForObject
FtrInit
GrfFree
GrfInit
InsPtCheckBlink
InsPtInitialize
MemCardFormat
MemHandleFlags
MemHandleOwner
MemHandleResetLock
MemHeapFreeByOwnerID
MemHeapInit
MemInit
MemInitHeapTable
MemKernelInit
MemPtrFlags
MemPtrOwner
MemPtrResetLock
MemStoreInit
MemStoreSetInfo
PenClose
PenGetRawPen
PenOpen
PenRawToScreen
PenScreenToRaw
ScrCompressScanLine
ScrCopyRectangle
ScrDeCompressScanLine
ScrDrawChars
ScrDrawNotify
ScrLineRoutine
ScrRectangleRoutine
ScrScreenInfo
ScrSendUpdateArea
SlkProcessRPC
SlkSysPktDefaultResponse
SndInit
SysBatteryDialog
SysColdBoot
SysDoze
SysInit
SysLaunchConsole
SysNewOwnerID
SysReserved10Trap1
SysReserved31Trap1
SysSemaphoreSet
SysUILaunch
SysWantEvent
TimInit
UIInitialize
UIReset
WinAddWindow
WinRemoveWindow

Undocumented 'System Use Only' or 'HAL Use Only' Traps
------------------------------------------------------
These traps are routines in the HAL, documented in headers to be called by
Palm OS only, or I have spoken with the authors of those traps who
identified them as internal traps.

AttnAllowClose
AttnDoEmergencySpecialEffects
AttnEffectOfEvent
AttnEnableNotification
AttnHandleEvent
AttnIndicatorAllow
AttnIndicatorAllowed
AttnIndicatorCheckBlink
AttnIndicatorGetBlinkPattern
AttnIndicatorSetBlinkPattern
AttnIndicatorTicksTillNextBlink
AttnInitialize
BltCopyRectangle
BltDrawChars
BltFindIndexes
BltGetPixel
BltLineRoutine
BltPaintPixel
BltPaintPixels
BltRectangleRoutine
BltRoundedRectangle
BltRoundedRectangleFill
DayHandleEvent
DbgControl
DbgSerDrvClose
DbgSerDrvControl
DbgSerDrvOpen
DbgSerDrvReadChar
DbgSerDrvStatus
DbgSerDrvWriteChar
FlashInit
FntPrvGetFontList
HwrBacklightV33
HwrBattery
HwrBatteryLevel
HwrCalcDynamicHeapSize
HwrCursorV33
HwrCustom
HwrDebuggerEnter
HwrDebuggerExit
HwrDebugSelect
HwrDisplayDoze
HwrDisplayDrawBootScreen
HwrDisplayInit
HwrDisplayPalette
HwrDisplaySleep
HwrDisplayWake
HwrDockSignals
HwrDockStatus
HwrDoze
HwrFlashWrite
HwrGetRAMMapping
HwrGetSilkscreenID
HwrIdentifyFeatures
HwrInterruptsInit
HwrIRQ1Handler
HwrIRQ2Handler
HwrIRQ3Handler
HwrIRQ4Handler
HwrIRQ5Handler
HwrIRQ6Handler
HwrLCDBaseAddrV33
HwrLCDContrastV33
HwrLCDGetDepthV33
HwrModelInitStage2
HwrModelInitStage3
HwrModelSpecificInit
HwrNVPrefGet
HwrNVPrefSet
HwrPluggedIn
HwrPostDebugInit
HwrPreDebugInit
HwrResetNMI
HwrResetPWM
HwrSetCPUDutyCycle
HwrSetSystemClock
HwrSleep
HwrSoundOff
HwrSoundOn
HwrTimerInit
HwrWake
KeyBootKeys
KeyHandleInterrupt
KeyInit
MemHeapPtr
MemStoreSearch
OEMDispatch2
PalmPrivate3
ScrCompress
ScrDecompress
ScrGetColortable
ScrGetGrayPat
ScrPalette
ScrScreenInit
ScrScreenLock
ScrScreenUnlock
ScrUpdateScreenBitmap
SndInterruptSmfIrregardless
SndPlaySmfIrregardless
SndPlaySmfResourceIrregardless
SysFatalAlertInit
SysKernelClockTick
SysNotifyBroadcastFromInterrupt
SysNotifyInit
SysReserved30Trap1
SysReserved30Trap2
SysUnimplemented
TimGetAlarm
TimSetAlarm
UIColorInit
WinGetFirstWindow
WinMoveWindowAddr
WinPrvInitCanvas
WinScreenInit

Kernel Traps
------------
These traps are not implemented because 68K applications do not have access
to the kernel APIs.

SysEvGroupCreate
SysEvGroupRead
SysEvGroupSignal
SysEvGroupWait
SysKernelInfo
SysMailboxCreate
SysMailboxDelete
SysMailboxFlush
SysMailboxSend
SysMailboxWait
SysResSemaphoreCreate
SysResSemaphoreDelete
SysResSemaphoreRelease
SysResSemaphoreReserve
SysSemaphoreCreate
SysSemaphoreDelete
SysSemaphoreSignal
SysSemaphoreWait
SysTaskCreate
SysTaskDelete
SysTaskID
SysTaskResume
SysTaskSetTermProc
SysTaskSuspend
SysTaskSwitching
SysTaskTrigger
SysTaskUserInfoPtr
SysTaskWait
SysTaskWaitClr
SysTaskWake
SysTimerCreate
SysTimerDelete
SysTimerRead
SysTimerWrite
SysTranslateKernelErr

Obsolete Traps
--------------
These traps are not implemented because they are obsolete Palm OS 1.0 traps
(or an esoteric obsolete trap such as WiCmdV32).

FplAdd
FplAToF
FplBase10Info
FplDiv
FplFloatToLong
FplFloatToULong
FplFToA
FplLongToFloat
FplMul
FplSub
WiCmdV32

Ghost Traps
-----------
These traps were never implemented in Palm OS (although they appear in
CoreTraps.h), but they are listed for completeness.

ClipboardCheckIfItemExist
CtlValidatePointer
FrmSetCategoryTrigger
FrmSetLabel
MenuEraseMenu
SysUICleanup
WinDrawArc
WinDrawPolygon
WinEraseArc
WinErasePolygon
WinFillArc
WinFillPolygon
WinInvertArc
WinInvertPolygon
WinPaintArc
WinPaintPolygon

Unimplemented NOP Traps
-----------------------
These traps should not be called by applications.  Some third-party
applications call these traps and it is safer to treat them as NOPs for
backwards compatibility.

FplFree
FplInit
HwrTimerSleep
HwrTimerWake
PenSleep
PenWake
SerReceiveISP
SrmSleep
SrmWake
SysDisableInts
SysRestoreStatus
TimHandleInterrupt
TimSleep
TimWake
WinDisableWindow
WinEnableWindow
WinInitializeWindow

Unimplemented Rare Traps
------------------------
These traps all seem like traps that are only used internally by Palm OS or
by serial drivers or by OEM extensions, etc.  In other words, these are
traps that an application would not use.

ConGetS
ConPutS
DayDrawDays
DayDrawDaySelector
DbgCommSettings
DbgGetMessage
DlkControl
DlkDispatchRequest
DlkStartServer
DmMoveOpenDBContext
DmOpenDBWithLocale
FlashCompress
FlashErase
FlashProgram
IntlGetRoutineAddress
MemGetRomNVParams
MemNVParams
OEMDispatch
ResLoadForm
SerPrimeWakeupHandler
SerReceiveWindowClose
SerReceiveWindowOpen
SerSetWakeupHandler
SlkSetSocketListener
SrmOpenBackground
SrmPrimeWakeupHandler
SrmReceiveWindowClose
SrmReceiveWindowOpen
SrmSetWakeupHandler
SysNotifyBroadcast
SysNotifyBroadcastDeferred
SysNotifyDatabaseAdded
SysNotifyDatabaseRemoved
SysSetTrapAddress