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

Please send bug reports, comments, suggestions, etc. to devsupp@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.0a6 (4/19/00)
----------------------------
*	(Unix) Support POSER_DIR environment variable.  If this variable
	exists, Poser uses it as the root for all files it uses (including
	preferences, Gremlin States, log files, and skin files).  Otherwise,
	it uses HOME.

*	External skin support.  A "skin" is something that defines the
	appearance of an application.  Palm OS Emulator uses skins for each
	device that it emulates.  Until this release, skins were built into
	Poser and couldn't be changed without recompiling the application. 
	Now, skins are stored in external files that Poser locates and uses.

	When starting up, Poser looks for a directory starting with the text
	"Skins" (that is, it may be "Skins", "Skins.Palm", "Skins.Personal",
	etc.).  Poser looks for all such directories in its own directory
	(that is, the directory in which it resides on Mac or Windows, or
	POSER_DIR on Unix), as well as that directory's parent and
	grandparent directories.

	For each such directory it finds, it scans the contents for files
	ending with ".skin".  These files are text files that describe the
	skin.  Associated with each .skin file are two graphics files that
	define the appearance of the skin (in single and double size mode).

	All of Poser's previously built-in images are now provided
	seperately in a Skin archive available on Poser's Web pages.  This
	archive includes a ReadMe.txt file that describes how to create your
	own skins.

*	Internal change: as part of the skin implementation, a number of
	file handling and streaming classes were replaced with a new, more
	consistant set.  The following classes:

		FileReference
		StreamHandle
			BufferHandle
			FileHandle
		PPStream
			ChunkStream

	Have been replaced with:

		EmDirRef
		EmFileRef
		EmStream
			EmStreamBlock
			EmStreamChunk
			EmStreamFile

	Testing note:

		All File I/O is affected by this change.  The following places
		need to be tested to make sure they're not broken:

			Reading
				AutoLoad, AutoRun, AutoRunAndQuit directories
				Files specified to be loaded via cmd line.
				Loading PDB, PRC, and PQA files.
				Loading skin files (.skin and .jpg files).
				Loading Preference file
				Loading PSF files
				Loading ROM files

			Writing/Creating
				Exporting PRC, PDB, and PQA files (both via the menu
					item and via HostExportFile).
				Saving screen shots.
				Saving PSF files
				Saving preferences
				Saving downloaded ROM file.
				Saving Logging files
				Saving Profile files.

*	Our patch to SndDoCmd now initializes the return value.  [David
	Slotter]

*	(Unix) AutoLoad, AutoRun, and AutoRunAndQuit directories now
	supported.

*	(Windows) Binder utility now merged into Poser directly (see the
	"Save Bound Emulator..." menu item).

	"Binding" Poser means to create a new version of Poser based on the
	settings in the currently running Poser.  A new executable is
	created that includes a ROM image, configuration settings, skins,
	and optionally a RAM image (the stuff that goes into a .psf file). 
	All of this information is taken from the current settings in the
	running Poser.  The result is a new Poser that is self-contained and
	runs stand-alone.

	When binding Poser, you'll be presented with two options:

		* Create a version that always creates a new session based on
		  the current emulator settings

		* Create a version that restores the current session

	Selecting the first option creates a version of Poser bound with a
	ROM image, configuration settings, and appropriate skins.  When
	launched, this version of Poser will always create a new session
	based on those settings.

	Selecting the second option creates a version of Poser that is also
	bound with a RAM image.  When launched, this version of Poser will
	always restore the state that is stored in that image.  This is
	effectively the same as reloading a .psf file.

	In both cases, Poser functionality is abbreviated.  Because much
	information is now specified by the bound items, menu items used to
	create, save, and load sessions and session files are removed.  And
	since bound Posers are intended to be used in demo, kiosk, or other
	closely controlled environments, most developer-related menu items
	are also removed.

*	Fixed a problem where NetLibReceivePB could return netErrParamErr
	instead of a more informative error code.  [Frank Yellin]

*	Fixed a problem where NetLibReceivePB where an in/out parameter
	passed to recvfrom was not initialized first.  [Frank Yellin]

*	When emulating NetLib calls by turning them into host TCP calls,
	and an error occurs, add a log message (if NetLib logging is turned
	on) that describes how the host error code is translated into a
	NetLib error code.

*	Implement the documented -skin and -silkscreen command-line
	options.

*	Got rid of problem that prevented Poser from running on Macs with
	more than 256 Meg of RAM (and which could have lead to problems on
	other platforms as well).

	Details:

	(First, some terminology.  In the discussion below, "host address
	space" refers to the memory that any Windows, Mac OS, or Unix
	application sees and manipulates.  "Emulated address space" refers
	to the memory that the Palm OS or a Palm OS application sees.  It is
	up to Poser to make the host address space look like emulated
	address space.)

	Poser emulates memory by allocating some buffers in the host's heap
	to "back" the various memory ranges utilized by the Palm OS.  For
	instance, it creates buffers to represent RAM, ROM, and the
	Dragonball registers. Whenever a memory access is performed, Poser
	determines which of these buffers is required, calculates the
	correct offset into that buffer, and fetches or stores as
	appropriate.  These buffers are used to create the illusion of the
	emulated address space.

	On occassion, it is necessary for Poser to magically make more
	memory "appear" to the emulated process.  That is, the emulated
	process needs to be granted access to memory other than that
	normally needed to emulate a true Palm OS environment.  A chief
	example of this is when loading a .prc file.  Poser performs the
	install process by creating the database, creating the records in
	the database, and then copying the record contents from the .prc
	file to the records in the database it created.  This copying is
	done by calling DmWrite.  But the source of the DmWrite is a buffer
	that Poser allocated to hold the contents of the .prc file.  This
	buffer is not one of the standard buffers Poser uses to emulate the
	any of the standard memory ranges that a Palm OS process can access.

	In order -- in this example -- for DmWrite to access the bytes in
	the file buffer Poser allocated, Poser temporarily "maps" arbitrary
	ranges into the emulated address space.  Ranges that are mapped in
	can be accessed by Palm OS processes.  However, this mapping did not
	undergo any address translation.  That is, if the buffer holding the
	.prc file happened to have been allocated at memory location
	0x01234560 by Windows, the Mac OS, Unix, or whatever, then Poser
	would map that buffer into memory location 0x01234560 in the Palm
	address space.

	This was OK, except when memory ranges mapped into the emulated
	space overlapped with standard memory ranges in the emulated space.
	For instance, on Macs with lots of RAM (greater than 256 Meg, at
	least), Poser could easily make a memory allocation that return an
	address > 0x10000000. If the buffer that was allocated were actually
	in the range 0x10C00000 - 0x10E00000 (or whatever the ROM range
	was), then when Poser attempted to "map in" that buffer, it would
	fail because of the overlap.

	Now, finally, this problem is fixed.  Poser now performs memory
	address translation.  Segments of memory mapped into the emulated
	address space are now mapped in so that they appear at 0x60000000 -
	0x6FFFFFFF.

*	When checking for the validity of calls to shared library
	functions, don't allow a refnum of zero.  Also, display a specific
	error message when an invalid library refnum is detected. [Frank
	Yellin]

*	(Unix) Fixed problem with crashing on Sparc systems when loading
	.prc files. [Frank Yellin]

*	Silently ignore a bug in an internal Palm OS 3.3 function
	(PrvConvertDepth1To2BW) that causes it to walk off the end of an
	allocated memory chunk by a single byte when reading from it.

*	Slightly more rigorous PC validation.  Previously, I'd just check
	to see if the PC were in a valid address space (RAM, ROM, Dragonball
	register, etc.).  Now only RAM or ROM addresses are allowed.  [Frank
	Yellin]

*	HostFFlush (HostLogFile()) now writes the log file to disk.

*	Re-hooked up the "Logging Options..." button in the New Gremlin
	dialog box.  In order to do this, utilized some cross-platform
	dialog handling routines that are slowly being phased in.  As a
	result of these new routines, the dialog box has been changed from a
	multi-panel dialog on Mac and Windows to a non-panel dialog box (as
	was on Unix).

*	(Unix) No longer hide and reshow the main window when establishing
	a new skin (either as part of the Skins dialog, or as part of
	loading/creating a session).  This process was an attemp to work-
	around an FLTK problem where the X frame window didn't properly
	resize itself.  This workaround didn't work, and another one has
	been put in place, so the old one's taken out.

*	(Unix) Change the filter button to use only lower-case suffixes. 
	With both upper and lowercase, the text in the filter button would
	overflow its bounds. [Jon Aslund]

*	(Unix) When opening a saved session file while a current session is
	already running, Poser would attempt to close the first session's
	thread twice, and then attempt to start the second session's thread
	twice.  This would often lead Poser to hang. Now each of those is
	done just once. [Jon Aslund]

*	(Unix) Instead of crashing, report errors that occur while creating
	a new session or loading an old one. [Jon Aslund]

*	(Unix) Added BSD/OS 4.1 support. [Bert Driehuis]

*	Allow TsmGlueGetFepMode and TsmGlueSetFepMode access to system
	globals.

*	(Windows) Fixed bug where creating a new session in Poser, quitting
	without saving, and then starting Poser using the -psf command line
	option would result in a new session being created again instead of
	loading the specified session file.

*	ROM Transfer project updated to use SDK 3.5.

*	Internal change: previously, when Poser had to manipulate data in
	Palm OS format, it used the structs in the Palm OS headers directly.
	However, that assumed that we could convince all the compilers used
	to build Poser to lay out those structs correctly (that is, with the
	same size and alignment as the 68K compiler used to build the Palm
	OS ROM and Palm OS applications).  This assumption is almost true,
	but not quite.  Therefore, with this release, a new mechanism for
	manipulating Palm OS structs is used.  This mechanism (see the
	EmPalmStructs.xxx files) allows Poser to access structs in a
	platform-, compiler-, and endian-independent fashion.

	Currently, this new mechanism is used only in the area of sending
	and receiving packets from external clients (debuggers and scripts).
	Eventually, it will be used in all aspects of Poser operation.  Once
	this switchover is complete, we'll be mostly independent of the Palm
	header files, and will probably be able to get rid of most of
	contents of the the Byteswapping.xxx files.

*	Fixed problem with our patch to NetLibReceive.  The exact problem
	being solved was one where NetLibReceive was called, received some
	data, the application modified that data in the buffer that received
	the data, and then call NetLibReceive again.  No bytes were
	available, but the contents of the buffer were updated with the
	contents of the previous receive, thus wiping out the modified
	buffer contents.  The application was relying on the buffer not
	changing, and so failed when it actually did.

*	Fixed problems with ROM Transfer not running on Palm OS 1.0.
	[Vladimir Amarante]

*	Fixed problem with trying to boot a ROM from a Palm V device that
	had originally been installed with Palm OS 3.1 but was lateer
	upgraded to Palm OS 3.3. [Douglas R. Shefsky]

*	(Windows) Fixed a problem with not reading the entire preferences
	file.

*	(Unix) Fixed problem with clicking in a non-active area of the
	window (that is, outside of any button or LCD area).

*	(Unix) Added ROM Transfer project (with prc-tools 2.0 compatible
	Makefile) and pre-built ROM Transfer.prc application that can
	be installed with something like pilot-xfer.

*	(Unix) Fixed problem that could lead to unexpected results when
	running certain dialogs after other certain dialogs (FLTK wasn't
	clearing out a reference to a widget in the first dialog,
	causing the second to crash).

*	(Unix) Remapped EINPROGRESS (as returned by sockets functions)
	to netErrWouldBlock instead of netErrSocketBusy (as NetMgr.h
	would suggest).  This change allows Network HotSync to work
	between a Unix box and a Windows box.
