diff options
| author |  Benjamin Barenblat <bbarenblat@gmail.com> | 2021-11-23 23:13:26 -0500 |
|---|---|---|
| committer | Benjamin Barenblat <bbarenblat@gmail.com> | 2021-11-23 23:13:26 -0500 |
| commit | e5df1aafb6d1346207343ccb858fa373e6b86301 (patch) | |
| tree | fb26f0091dda7dd69d48d6b06169ea618332b99e /Docs | |
Check in the Palm OS Emulator, version 3.5 (2001). These files come from
the tarball present in the Debian archives [1]. The SHA-256 digest of
the tarball, c5e0d23424e88525bfba0ecdf0a432a8d93c885d04740df06a9eeee44e5f25e4,
matches the digest preserved in the FreeBSD ports tree [2], giving
further confidence that these files are as distributed by upstream.
[1] http://archive.debian.org/debian/pool/contrib/p/pose/
[2] https://svnweb.freebsd.org/ports/head/palm/pose/distinfo?revision=271305&view=markup&pathrev=282162
Diffstat (limited to 'Docs')
| -rw-r--r-- | Docs/12rollin.pdf | bin | 0 -> 67296 bytes | |||
| -rw-r--r-- | Docs/13hewgil.pdf | bin | 0 -> 41372 bytes | |||
| -rw-r--r-- | Docs/Debugger.html | 854 | ||||
| -rw-r--r-- | Docs/POSER Profiler.rtf | 522 | ||||
| -rw-r--r-- | Docs/UsingPalmOSEmulator.pdf | bin | 0 -> 1543509 bytes | |||
| -rw-r--r-- | Docs/_Bugs.txt | 116 | ||||
| -rw-r--r-- | Docs/_Building.txt | 153 | ||||
| -rw-r--r-- | Docs/_Contributing.txt | 176 | ||||
| -rw-r--r-- | Docs/_Credits.txt | 219 | ||||
| -rw-r--r-- | Docs/_GPL.txt | 340 | ||||
| -rw-r--r-- | Docs/_News.txt | 71 | ||||
| -rw-r--r-- | Docs/_OldNews.txt | 6094 | ||||
| -rw-r--r-- | Docs/_ReadMe.txt | 108 | ||||
| -rw-r--r-- | Docs/_ToDo.txt | 16 |
14 files changed, 8669 insertions, 0 deletions
diff --git a/Docs/12rollin.pdf b/Docs/12rollin.pdf Binary files differnew file mode 100644 index 0000000..91e45e6 --- /dev/null +++ b/Docs/12rollin.pdf diff --git a/Docs/13hewgil.pdf b/Docs/13hewgil.pdf Binary files differnew file mode 100644 index 0000000..e71e5c3 --- /dev/null +++ b/Docs/13hewgil.pdf diff --git a/Docs/Debugger.html b/Docs/Debugger.html new file mode 100644 index 0000000..88669cd --- /dev/null +++ b/Docs/Debugger.html @@ -0,0 +1,854 @@ +<HTML> +<!--This file created 3:45 AM 8/23/99 by Claris Home Page version 3.0--> +<HEAD> + <TITLE>Debugger</TITLE> + <META NAME=GENERATOR CONTENT="Claris Home Page 3.0"> + <X-CLARIS-WINDOW TOP=23 BOTTOM=859 LEFT=623 RIGHT=1234> + <X-CLARIS-TAGVIEW MODE=minimal> +<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"><META NAME="Author" CONTENT="Keith Rollin"> +</HEAD> +<BODY> +<H1><CENTER>Palm Debugger Protocol</CENTER></H1> + +<CENTER><TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="80%"> + <TR> + <TD> + <H3>Document Order</H3> + </TD> + <TD> + <H3>Alphabetical Order</H3> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Overview">Overview</A></P> + </TD> + <TD> + <P><A HREF="#Continue Command">Continue Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#State Command">State Command</A></P> + </TD> + <TD> + <P><A HREF="#Find Command">Find Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Read Memory Command">Read Memory + Command</A></P> + </TD> + <TD> + <P><A HREF="#Get Breakpoints Command">Get Breakpoints + Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Write Memory Command">Write Memory + Command</A></P> + </TD> + <TD> + <P><A HREF="#Get Routine Name Command">Get Routine Name + Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Single Step Command">Single Step + Command</A></P> + </TD> + <TD> + <P><A HREF="#Get Trap Breaks Command">Get Trap Breaks + Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Get Routine Name Command">Get Routine Name + Command</A></P> + </TD> + <TD> + <P><A HREF="#Get Trap Conditionals Command">Get Trap + Conditionals Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Read Registers Command">Read Registers + Command</A></P> + </TD> + <TD> + <P><A HREF="#Message Command">Message Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Write Registers Command">Write Registers + Command</A></P> + </TD> + <TD> + <P><A HREF="#Overview">Overview</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Continue Command">Continue Command</A></P> + </TD> + <TD> + <P><A HREF="#Read Memory Command">Read Memory + Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Get Breakpoints Command">Get Breakpoints + Command</A></P> + </TD> + <TD> + <P><A HREF="#Read Registers Command">Read Registers + Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Set Breakpoints Command">Set Breakpoints + Command</A></P> + </TD> + <TD> + <P><A HREF="#RPC Command">RPC Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Toggle Debugger Breaks Command">Toggle Debugger + Breaks Command</A></P> + </TD> + <TD> + <P><A HREF="#Set Breakpoints Command">Set Breakpoints + Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Get Trap Breaks Command">Get Trap Breaks + Command</A></P> + </TD> + <TD> + <P><A HREF="#Set Trap Breaks Command">Set Trap Breaks + Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Set Trap Breaks Command">Set Trap Breaks + Command</A></P> + </TD> + <TD> + <P><A HREF="#Set Trap Conditionals Command">Set Trap + Conditionals Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Find Command">Find Command</A></P> + </TD> + <TD> + <P><A HREF="#Single Step Command">Single Step + Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Message Command">Message Command</A></P> + </TD> + <TD> + <P><A HREF="#State Command">State Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#RPC Command">RPC Command</A></P> + </TD> + <TD> + <P><A HREF="#Toggle Debugger Breaks Command">Toggle Debugger + Breaks Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Get Trap Conditionals Command">Get Trap + Conditionals Command</A></P> + </TD> + <TD> + <P><A HREF="#Write Memory Command">Write Memory + Command</A></P> + </TD> + </TR> + <TR> + <TD> + <P><A HREF="#Set Trap Conditionals Command">Set Trap + Conditionals Command</A></P> + </TD> + <TD> + <P><A HREF="#Write Registers Command">Write Registers + Command</A></P> + </TD> + </TR> +</TABLE> +</CENTER> + +<H3><A NAME=Overview></A>Overview</H3> + +<P>In this document, "target" refers to the object being debugged. +This could be the Palm ROM, or Palm OS Emulator. "Host" refers +to the debugger, which could be either the Metrowerks debugger or the +Palm Debugger. The target side of the debugger communicates by +sending command packets to the user interface on the host side. +Basically, the target side acts as a slave to the host, carrying out +commands and reporting back results.</P> + +<P>The target side must be able to respond to some basic command +types sent from the host side. These are: get state, display memory, +set memory, single step, get routine name, display registers, set +registers, continue, set breakpoint, clear breakpoint, set a-trap, +clear a-trap, find, and remote procedure call. All high-level +commands that a user enters from the host side are broken down into +one or more of these basic target commands, which are then sent to +the target.</P> + +<P>A command packet can be a request packet, response packet, or +message packet. Request packets are sent from the host to the target +and must be answered by an appropriate response packet from the +target. Message packets are sent from either the target or the host +and merely report status information and do not require a response +from the recipient.</P> + +<P>There is no extensive protocol involved between the host and +target. Basically, the host sends a request packet and waits for a +response from the target, or a timeout. If a response is not detected +by the timeout period, the host does not retry the request but could +display a message to the user saying that the target is not +responding. Usually, if the target does not respond, it means either +that the target is currently executing code and has not encountered a +breakpoint, or that the target is so messed up that it can't even run +the debugger.</P> + +<P>Figure 1 shows the structure of request, response, and message +packets. <FONT FACE="Times">Basically, every packet consists of a +packet header, a variable length packet body, and a packet footer. +The maximim size of a packet body is 272 bytes. The packet header +starts with the key 24-bit value $BEEFED and includes packet header +information and a checksum of just the header itself. The packet +footer contains a 16-bit CRC of the header and body (not +footer).</FONT></P> + +<P><FONT FACE="Times">Following the 24-bit value $BEEFED at the start +of the packet header is a destination socket ID byte, a source socket +ID byte, a packet type byte, a 2 byte body size, a transaction ID +byte, and an 8 bit checksum of the header. The destination and source +socket IDs and the packet type bytes are always 0 for debugger +packets. The bodySize field is the number of bytes that are in the +body - which will depend on the particular command being sent. The +transaction ID is an 8 bit value that gets incremented every time a +command is sent from the host. In order for a response packet from +the target to be recognized by the host, its transaction ID must +match the transaction ID of the original request packet.</FONT></P> + +<P><FONT FACE="Times">The packet body starts with a command byte +immediately followed by a filler byte. </FONT>The command byte +encodes the particular command being sent or acknowledged. Request +packets always have the upper bit of the command byte clear, response +packets have the upper bit set. Each command has it's own specific +structure following the command and filler bytes. </P> + +<P> </P> + +<P><TT> +--------------------+<BR> + | $BE (1) |<BR> + | $EF (1) |<BR> + | $ED (1) |<BR> + | dest ID (1) | Header (10 bytes)<BR> + | src ID (1) |<BR> + | type (1) |<BR> + | bodySize (2) |<BR> + | transID (1) |<BR> + | checkSum (1) |<BR> + +--------------------+<BR> + | command (1) |<BR> + | filler (1) | Body (2-272 bytes)<BR> + | variable size data |<BR> + +--------------------+<BR> + | CRC (2) | Footer (2 bytes)<BR> + +--------------------+<BR> +</TT></P> + +<CENTER><B>Figure 1 - Structure of Packets</B></CENTER> + +<P> </P> + +<H3><A NAME="State Command"></A>State Command</H3> + +<P>Figure 2 shows the structure of the request and response bodies +for the state command. The host sends this command in order to +determine the current state of the target, including the current +program counter, the values of all the registers, the reason why the +target entered the debugger, the current breakpoints, and the name of +the routine that the program counter is in. The target will also send +a state response packet to the host whenever it encounters an +exception and enters the debugger - whether due to a breakpoint, bus +error, single step, etc. This is the only time a response packet is +sent to the host without a corresponding request packet from the +host.</P> + +<PRE><TT>#define sysPktStateCmd 0x00 +#define sysPktStateRsp 0x80</TT></PRE> + +<BLOCKQUOTE><PRE><I><TT>Max length of a routine name</TT></I></PRE></BLOCKQUOTE> + +<PRE><TT>#define sysPktMaxNameLen 32</TT></PRE> + +<BLOCKQUOTE><PRE><I><TT>Number of remote code words to send in the 'state response' packet</TT></I></PRE></BLOCKQUOTE> + +<PRE><TT>#define sysPktStateRspInstWords 15 +#define dbgNormalBreakpoints 5 +#define dbgTempBPIndex dbgNormalBreakpoints +#define dbgTotalBreakpoints (dbgTempBPIndex+1) +typedef struct BreakpointType +{ + Ptr addr; // address of breakpoint + Boolean enabled; // true if enabled + Boolean installed; // for alignment +} BreakpointType; + +typedef struct SysPktStateCmdType +{ + _sysPktBodyCommon; // Common Body header +} SysPktStateCmdCmdType;</TT></PRE> + +<BLOCKQUOTE><PRE><I><TT>Packet Body structure for the state command response packet</TT></I></PRE></BLOCKQUOTE> + +<PRE><TT>typedef struct SysPktStateRspType +{ + _sysPktBodyCommon; // Common Body header + Boolean resetted; // true if target has just reset + Word exceptionId; // exception which caused the + // debugger to be entered. + M68KregsType reg; // current remote registers. + Word inst[sysPktStateRspInstWords]; + // instruction buffer for + // code beginning at PC. + BreakpointType bp[dbgTotalBreakpoints]; // current breakpoints + void* startAddr; // start address of routine + void* endAddr; // end address of routine + char name[sysPktMaxNameLen]; // routine name (0 or more chars), + // immediately follows the address range. + Byte trapTableRev; // rev of trap table. Used to determine + // when host's trap table cache is invalid +} SysPktStateRspType;</TT></PRE> + +<CENTER><B>Figure 2 - State Command</B></CENTER> + +<P>The resetted field is non-zero if the target has reset itself +since the last time the debugger was entered. The host can use the +exceptionID field to determine why the debugger on the target was +entered because it contains the address of the exception vector: $8 +for a bus error, $7C for a non-maskable interrupt, etc. The 8 data +registers are stored in the packet body starting from D0. The 7 +address registers are stored starting from A0. The instruction buffer +contains the next 30 bytes of code starting from the current program +counter. The breakpoint list contains the list of the current +breakpoints on the device. This is a fixed length list of 6 +breakpoints - unused entries will have 0 in the enabled and installed +fields. The last breakpoint in the list (breakpoint #5) is used +exclusively for temporary breakpoints installed by the debugger for +implementing commands like GoTill (gt).</P> + +<P>The routineStart, routineEnd, and routineName fields contain the +starting and ending address and name of the current routine. The +target side of the debugger determines this information. A routine +name is placed at the end of every routine by the compiler and the +target side of the debugger scans forward and backwards from the +current program counter to determine this information.</P> + +<P> </P> + +<H3><A NAME="Read Memory Command"></A>Read Memory Command</H3> + +<P>Figure 3 shows the structure of the request and response bodies +for the read command. This command is sent by the host in order to +read memory on the target. It can return up to 256 bytes of data. The +size of the response body depends on the number of bytes requested in +the request packet.</P> + +<PRE><TT>#define sysPktReadMemCmd 0x01 +#define sysPktReadMemRsp 0x81 + +typedef struct SysPktReadMemCmdType +{ + _sysPktBodyCommon; // Common Body header + void* address; // Address to read + Word numBytes; // # of bytes to read +} SysPktReadMemCmdType; + +typedef struct SysPktReadMemRspType +{ + _sysPktBodyCommon; // Common Body header + // Byte data[?]; // variable size +} SysPktReadMemRspType;</TT></PRE> + +<CENTER><B>Figure 3 - Read Command</B></CENTER> + +<P> </P> + +<H3><A NAME="Write Memory Command"></A>Write Memory Command</H3> + +<P>Figure 4 shows the structure of the request and response bodies +for the write command. This command is sent by the host in order to +write memory on the target. It can write up to 256 bytes of data. The +size of the request packet depends on the number of bytes that need +to be written.</P> + +<PRE><TT>#define sysPktWriteMemCmd 0x02 +#define sysPktWriteMemRsp 0x82 + +typedef struct SysPktWriteMemCmdType +{ + _sysPktBodyCommon; // Common Body header + void* address; // Address to write + Word numBytes; // # of bytes to write + // Byte data[?]; // variable size data +} SysPktWriteMemCmdType; + +typedef struct SysPktWriteMemRspType +{ + _sysPktBodyCommon; // Common Body header +} SysPktWriteMemRspType;</TT></PRE> + +<CENTER><B>Figure 4 - Write Command</B></CENTER> + +<P> </P> + +<H3><A NAME="Single Step Command"></A>Single Step Command</H3> + +<P><STRIKE>Figure 5 shows the structure of the request and response +bodies for the singleStep command. This command is sent by the host +to tell the target to execute the next instruction. This command and +the continue command (see below) are unique in that they do not get a +respective response back from the target. The host relies on the fact +that when the target re-enters the debugger it will automatically +send a state response packet. In this case, the target will re-enter +the debugger immediately after executing the next +instruction.</STRIKE></P> + +<PRE><TT><STRIKE>#define sysPktSingleStepCmd 0x03</STRIKE></TT></PRE> + +<CENTER><B><STRIKE>Figure 5 - Single Step +Command</STRIKE></B></CENTER> + +<P>Note: there is no actual single step command implemented in either +the ROM or the Palm OS Emulator. Instead, this functionality is +performed by setting the trace bit in the Status Register and +executing a sysPktContinueCmd.</P> + +<P> </P> + +<H3><A NAME="Get Routine Name Command"></A>Get Routine Name +Command</H3> + +<P>Figure 6 shows the structure of the request and response bodies +for the getRoutineName command. The host sends this command to +determine which routine a particular address is in. It will return +the starting and ending address of the routine and the name. The name +of each routine is imbedded into the code when it's compiled and the +target can determine the starting and ending address and name of the +routine by scanning forwards and backwards in the code for this +information.</P> + +<PRE><TT>#define sysPktGetRtnNameCmd 0x04 +#define sysPktGetRtnNameRsp 0x84 + +typedef struct SysPktRtnNameCmdType +{ + _sysPktBodyCommon; // Common Body header + void* address; // -> address to query on +} SysPktRtnNameCmdType; + +typedef struct SysPktRtnNameRspType +{ + _sysPktBodyCommon; // Common Body header + void* address; // -> address to query on + void* startAddr; // <- start address of routine + void* endAddr; // <- end address of routine + char name[sysPktMaxNameLen]; // <- routine name, if any immediately + // follows the address range. + // The balance need not be sent. +} SysPktRtnNameRspType;</TT></PRE> + +<CENTER><B>Figure 6 - Get Routine Name Command</B></CENTER> + +<P>The address field in the response body is a copy of the address +sent in the request. The startAddr and endAddr fields are the +starting and ending address of the routine that includes address. The +name field is the 0 terminated name of the routine. If the target can +not determine which routine address is in, it will return 0 for the +first byte of the name in the response body and endAddr will contain +the last address that it scanned in trying to find out the routine +name. Subsequent getRoutineName calls should use the endAddr from the +previous call in order to look for more routines.</P> + +<P> </P> + +<H3><A NAME="Read Registers Command"></A>Read Registers Command</H3> + +<P>Figure 7 shows the structure of the request and response bodies +for the readRegisters command. This command is sent by the host to +get the value of each of the processor registers on the target. The 8 +data registers are stored in the packet body starting from D0. The 7 +address registers are stored starting from A0.</P> + +<PRE><TT>#define sysPktReadRegsCmd 0x05 +#define sysPktReadRegsRsp 0x85 + +typedef struct SysPktReadRegsCmdTyp +{ + _sysPktBodyCommon; // Common Body header +} SysPktReadRegsCmdType; + +typedef struct SysPktReadRegsRspType +{ + _sysPktBodyCommon; // Common Body header + M68KRegsType reg; // <- return registers +} SysPktReadRegsRspType;</TT></PRE> + +<CENTER><B>Figure 7 - Read Registers Command</B></CENTER> + +<P> </P> + +<H3><A NAME="Write Registers Command"></A>Write Registers +Command</H3> + +<P>Figure 8 shows the structure of the request and response bodies +for the writeRegisters command. This command is sent by the host to +set the value of each of the processor registers on the target. The 8 +data registers are stored in the packet body starting from D0. The 7 +address registers are stored starting from A0.</P> + +<PRE><TT>#define sysPktWriteRegsCmd 0x06 +#define sysPktWriteRegsRsp 0x86 + +typedef struct SysPktWriteRegsCmdType +{ + _sysPktBodyCommon; // Common Body header + M68KRegsType reg; // -> registers to write +} SysPktWriteRegsCmdType; + +typedef struct SysPktWriteRegsRspType +{ + _sysPktBodyCommon; // Common Body header +} SysPktWriteRegsRspType;</TT></PRE> + +<CENTER><B>Figure 8 - Write Registers Command</B></CENTER> + +<P> </P> + +<H3><A NAME="Continue Command"></A>Continue Command</H3> + +<P>Figure 9 shows the structure of the request and response bodies +for the continue command. This command is sent by the host to tell +the target to continue execution. This is usually sent as a result of +the user entering the Go (g) command. The debugger on the target will +not get re-entered again unless a breakpoint or other exception is +encountered. The target does not send a response to this command. If +the target does re-enter the debugger due to a subsequent exception, +it will send a state response packet to the host.</P> + +<PRE><TT>#define sysPktContinueCmd 0x07 + +typedef struct SysPktContinueCmdType +{ + _sysPktBodyCommon; // Common Body header + M68KregsType regs; // registers + Boolean stepSpy; // set true to do step spy + DWord ssAddr; // step spy address + DWord ssCount; // # of bytes + DWord ssCheckSum; // checksum +} SysPktContinueCmdType;</TT></PRE> + +<CENTER><B>Figure 9 - Continue Command</B></CENTER> + +<P> </P> + +<H3><A NAME="Get Breakpoints Command"></A>Get Breakpoints +Command</H3> + +<P>Figure 10 shows the structure of the request and response bodies +for the getBreakpoints command. This command is sent by the host to +get the current settings of all target breakpoints. The response body +has an array of 6 breakpoints in it. If the enabled field for a +particular breakpoint entry is 0, it means that breakpoint is +disabled. If the address field is 0, it means that breakpoint is not +used. The installed field is currently never used.</P> + +<PRE><TT>#define sysPktGetBreakpointsCmd 0x0B +#define sysPktGetBreakpointsRsp 0x8B + +typedef struct SysPktGetBreakpointsCmdType +{ + _sysPktBodyCommon; // Common Body header +} SysPktGetBreakpointsCmdType; + +typedef struct SysPktGetBreakpointsRspType +{ + _sysPktBodyCommon; // Common Body header + BreakpointType bp[dbgTotalBreakpoints]; +} SysPktGetBreakpointsRspType;</TT></PRE> + +<CENTER><B>Figure 10 - Get Breakpoints Command</B></CENTER> + +<P> </P> + +<H3><A NAME="Set Breakpoints Command"></A>Set Breakpoints +Command</H3> + +<P>Figure 11 shows the structure of the request and response bodies +for the setBreakpoints command. This command is sent by the host to +set the target breakpoints. The request body has an array of 6 +breakpoints in it. If the enabled field for a particular breakpoint +entry is 0, it means that breakpoint is disabled. If the address +field is 0, it means that breakpoint is not used.</P> + +<PRE><TT>#define sysPktSetBreakpointsCmd 0x0C +#define sysPktSetBreakpointsRsp 0x8C + +typedef struct SysPktSetTrapBreaksCmdType +{ + _sysPktBodyCommon; // Common Body header + Word trapBP[dbgTotalTrapBreaks]; +} SysPktSetTrapBreaksCmdType; + +typedef struct SysPktSetTrapBreaksRspType +{ + _sysPktBodyCommon; // Common Body header +} SysPktSetTrapBreaksRspType;</TT></PRE> + +<CENTER><B>Figure 11 - Set Breakpoints Command</B></CENTER> + +<P> </P> + +<H3><A NAME="Toggle Debugger Breaks Command"></A>Toggle Debugger +Breaks Command</H3> + +<P>Figure 12 shows the structure of the request and response bodies +for the toggleDbgBreaks command. This command is sent by the host to +enable or disable compiled-in breakpoints. A compiled in breakpoint +is a special TRAP instruction that gets compiled into the code with +the DbgBreak() and DbgSrcBreak() calls. The host can send this +command to tell the target whether or not to ignore these +breakpoints. The request toggles the state and the response returns +the new state (non-zero for enabled, 0 for disabled).</P> + +<PRE><TT>#define sysPktDbgBreakToggleCmd 0x0D +#define sysPktDbgBreakToggleRsp 0x8D + +typedef struct SysPktDbgBreakToggleCmdType +{ + _sysPktBodyCommon; // Common Body header +} SysPktDbgBreakToggleCmdType; + +typedef struct SysPktDbgBreakToggleRspType +{ + _sysPktBodyCommon; // Common Body header + Boolean newState; +} SysPktDbgBreakToggleRspType;</TT></PRE> + +<CENTER><B>Figure 12 - Toggle Debugger Breaks Command</B></CENTER> + +<P> </P> + +<H3><A NAME="Get Trap Breaks Command"></A>Get Trap Breaks +Command</H3> + +<P>Figure 13 shows the structure of the request and response bodies +for the getTrapBreaks command. The host sends this command to get the +current settings of all target trap breaks. The response body has an +array of 5 traps in it. If the trap field is 0, it means that trap +break is not used. Trap breaks are used to force the target to enter +the debugger when a particular system trap is called. Up to 5 trap +breaks can be set at any time.</P> + +<PRE>#define sysPktGetTrapBreaksCmd 0x10 +#define sysPktGetTrapBreaksRsp 0x90 + +typedef struct SysPktGetTrapBreaksCmdType +{ + _sysPktBodyCommon; // Common Body header +} SysPktGetTrapBreaksCmdType; + +typedef struct SysPktGetTrapBreaksRspType +{ + _sysPktBodyCommon; // Common Body header + Word trapBP[dbgTotalTrapBreaks]; +} SysPktGetTrapBreaksRspType;</PRE> + +<CENTER><B>Figure 13 - Get Trap Breaks Command</B></CENTER> + +<H3><A NAME="Set Trap Breaks Command"></A>Set Trap Breaks +Command</H3> + +<P>Figure 14 shows the structure of the request and response bodies +for the setTrapBreaks command. The host sends this command to set the +current settings of all target trap breaks. The request body has an +array of 5 traps in it. If the trap field is 0, it means that trap +break is not used. Trap breaks are used to force the target to enter +the debugger when a particular system trap is called. Up to 5 trap +breaks can be set at any time.</P> + +<PRE>#define sysPktSetTrapBreaksCmd 0x11 +#define sysPktSetTrapBreaksRsp 0x91 + +typedef struct SysPktSetTrapBreaksCmdType +{ + _sysPktBodyCommon; // Common Body header + Word trapBP[dbgTotalTrapBreaks]; +} SysPktSetTrapBreaksCmdType; + +typedef struct SysPktSetTrapBreaksRspType +{ + _sysPktBodyCommon; // Common Body header +} SysPktSetTrapBreaksRspType;</PRE> + +<CENTER><B>Figure 14 - Set Trap Breaks Command</B></CENTER> + +<H3><A NAME="Find Command"></A>Find Command</H3> + +<P>Figure 15 shows the structure of the request and response bodies +for the find command. This command is sent by the host to search for +data on the target. The firstAddr and lastAddr fields of the request +set the range of addresses to search through. The numBytes field +contains the number of bytes in the search string. If the +caseInsensitive byte is non-zero, a case-insensitive search will be +made. The variable length search string follows the caseInsensitive +field.</P> + +<P>In the response body, addrFound contains the address of the found +data. If the data was not found, the found field will be 0.</P> + +<PRE>#define sysPktFindCmd 0x13 +#define sysPktFindRsp 0x93 + +typedef struct SysPktFindCmdType +{ + _sysPktBodyCommon; // Common Body header + DWord firstAddr; // first address to search + DWord lastAddr; // last address to begin searching + Word numBytes; // number of data bytes to match + Boolean caseInsensitive; // if true, perform a case-insensitive search +} SysPktFindCmdType; + +typedef struct SysPktFindRspType +{ + _sysPktBodyCommon; // Common Body header + DWord addr; // address where data was found + Boolean found; // true if data was found +} SysPktFindRspType;</PRE> + +<CENTER><B>Figure 15 - Find Command</B></CENTER> + +<H3><A NAME="Message Command"></A>Message Command</H3> + +<P>Figure 16 shows the structure of the message packet body. This +packet is sent by the target to display a message on the host. +Debugger messages can be compiled into the source code through the +DbgMessage() call. They can be used by applications on Palm devices +for displaying application specific debugging messages during +execution. There is no response sent back from the host to the target +when it receives one of these packets.</P> + +<PRE>#define sysPktRemoteMsgCmd 0x7F + +typedef struct SysPktRemoteMsgCmdType +{ + _sysPktBodyCommon; // Common Body header + Byte text[1]; // variable length text goes here +} SysPktRemoteMsgCmdType;</PRE> + +<CENTER><B>Figure 16 - Message Command</B></CENTER> + +<H3><A NAME="RPC Command"></A>RPC Command</H3> + +<PRE>#define sysPktRPCCmd 0x0A +#define sysPktRPCRsp 0x8A + +typedef struct SysPktRPCParamInfo +{ + Byte byRef; // true if param is by reference + Byte size; // # of Bytes of paramData (must be even) + Word data[1]; // variable length array of paramData +} SysPktRPCParamType; + +typedef struct SysPktRPCType +{ + _sysPktBodyCommon; // Common Body header + Word trapWord; // which trap to execute + Dword resultD0; // result from D0 placed here + Dword resultA0; // result from A0 placed here + Word numParams; // how many parameters follow + + // Following is a variable length array of SysPktRPCParamType's + SysPktRPCParamType param[1]; +} SysPktRPCType;</PRE> + +<CENTER><B>Figure 17 - RPC Command</B></CENTER> + +<H3><A NAME="Get Trap Conditionals Command"></A>Get Trap Conditionals +Command (new in 3.0)</H3> + +<P>These are used to tell the debugger to conditionally break on a +trap depending on the value of the first word on the stack. They are +used when setting a-traps on library calls.</P> + +<PRE>#define sysPktGetTrapConditionsCmd 0x14 +#define sysPktGetTrapConditionsRsp 0x94 + +typedef struct SysPktGetTrapConditionsCmdType +{ + _sysPktBodyCommon; // Common Body header +} SysPktGetTrapConditionsCmdType; + +typedef struct SysPktGetTrapConditionsRspType +{ + _sysPktBodyCommon; // Common Body header + Word trapParam[dbgTotalTrapBreaks]; +} SysPktGetTrapConditionsRspType;</PRE> + +<CENTER><B>Figure 18 - Get Trap Conditionals Command</B></CENTER> + +<H3><A NAME="Set Trap Conditionals Command"></A>Set Trap Conditionals +Command (new in 3.0)</H3> + +<P>These are used to tell the debugger to conditionally break on a +trap depending on the value of the first word on the stack. They are +used when setting a-traps on library calls.</P> + +<PRE>#define sysPktSetTrapConditionsCmd 0x15 +#define sysPktSetTrapConditionsRsp 0x95 + +typedef struct SysPktSetTrapConditionsCmdType +{ + _sysPktBodyCommon; // Common Body header + Word trapParam[dbgTotalTrapBreaks]; +} SysPktSetTrapConditionsCmdType; + +typedef struct SysPktSetTrapConditionsRspType +{ + _sysPktBodyCommon; // Common Body header +} SysPktSetTrapConditionsRspType;</PRE> + +<CENTER><B>Figure 19 - Set Trap Conditionals Command</B></CENTER> + +<P> </P> +</BODY> +</HTML> diff --git a/Docs/POSER Profiler.rtf b/Docs/POSER Profiler.rtf new file mode 100644 index 0000000..e1de7df --- /dev/null +++ b/Docs/POSER Profiler.rtf @@ -0,0 +1,522 @@ +{\rtf1\mac \deff8\deflang1033{\fonttbl{\f1\fnil\fcharset2\fprq2 Symbol;}{\f3\fnil\fcharset77\fprq2 Courier;}{\f8\fnil\fcharset77\fprq2 Times;}{\f9\fnil\fcharset77\fprq2 Helvetica;}{\f48\fnil\fcharset77\fprq2 Monaco;}} +{\colortbl;\red0\green0\blue0;\red0\green0\blue212;\red2\green171\blue234;\red31\green183\blue20;\red242\green8\blue132;\red221\green8\blue6;\red252\green243\blue5;\red255\green255\blue255;\red0\green0\blue128;\red0\green128\blue128;\red0\green100\blue17; +\red128\green0\blue128;\red128\green0\blue0;\red128\green128\blue0;\red128\green128\blue128;\red192\green192\blue192;}{\stylesheet{\widctlpar \f8 \snext0 Normal;}{\s1\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl1\pndec\pnprev1\pnstart1\pnsp144 {\pntxta .}} +\b\f8\fs36 \sbasedon0\snext0 heading 1;}{\s2\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl2\pndec\pnprev1\pnstart1\pnsp144 }\b\i\f8\fs28 \sbasedon0\snext0 heading 2;}{\s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 +\sbasedon0\snext0 heading 3;}{\s4\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl4\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\i\f8 \sbasedon0\snext0 heading 4;}{\s5\sb240\sa60\widctlpar{\*\pn \pnlvl5\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\f9\fs22 +\sbasedon0\snext0 heading 5;}{\s6\sb240\sa60\widctlpar{\*\pn \pnlvl6\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\i\f9\fs22 \sbasedon0\snext0 heading 6;}{\s7\sb240\sa60\widctlpar{\*\pn \pnlvl7\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\f9\fs20 +\sbasedon0\snext0 heading 7;}{\s8\sb240\sa60\widctlpar{\*\pn \pnlvl8\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\i\f9\fs20 \sbasedon0\snext0 heading 8;}{\s9\sb240\sa60\widctlpar{\*\pn \pnlvl9\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\i\f9\fs18 +\sbasedon0\snext0 heading 9;}{\*\cs10 \additive Default Paragraph Font;}{\s15\li1200\widctlpar\tqr\tldot\tx11880 \f8\fs18 \sbasedon0\snext0 toc 8;}{\s16\li1000\widctlpar\tqr\tldot\tx11880 \f8\fs18 \sbasedon0\snext0 toc 7;}{ +\s17\li800\widctlpar\tqr\tldot\tx11880 \f8\fs18 \sbasedon0\snext0 toc 6;}{\s18\li600\widctlpar\tqr\tldot\tx11880 \f8\fs18 \sbasedon0\snext0 toc 5;}{\s19\li400\widctlpar\tqr\tldot\tx11880 \f8\fs18 \sbasedon0\snext0 toc 4;}{ +\s20\li200\widctlpar\tqr\tldot\tx11880 \i\f8 \sbasedon0\snext0 toc 3;}{\s21\widctlpar\tqr\tldot\tx11880 \scaps\f8 \sbasedon0\snext0 toc 2;}{\s22\sb120\sa120\widctlpar\tqr\tldot\tx11880 \b\caps\f8 \sbasedon0\snext0 toc 1;}{ +\s23\fi-240\li1680\widctlpar\tqr\tx5580 \f8\fs18 \sbasedon0\snext0 index 7;}{\s24\fi-240\li1440\widctlpar\tqr\tx5580 \f8\fs18 \sbasedon0\snext0 index 6;}{\s25\fi-240\li1200\widctlpar\tqr\tx5580 \f8\fs18 \sbasedon0\snext0 index 5;}{ +\s26\fi-240\li960\widctlpar\tqr\tx5580 \f8\fs18 \sbasedon0\snext0 index 4;}{\s27\fi-240\li720\widctlpar\tqr\tx5580 \f8\fs18 \sbasedon0\snext0 index 3;}{\s28\fi-240\li480\widctlpar\tqr\tx5580 \f8\fs18 \sbasedon0\snext0 index 2;}{ +\s29\fi-240\li240\widctlpar\tqr\tx5580 \f8\fs18 \sbasedon0\snext0 index 1;}{\s30\widctlpar\tqc\tx4320\tqr\tx8640 \f8 \sbasedon0\snext30 footer;}{\s31\widctlpar\tqc\tx4320\tqr\tx8640 \f8 \sbasedon0\snext31 header;}{\s32\li1400\widctlpar\tqr\tldot\tx11880 +\f8\fs18 \sbasedon0\snext0 toc 9;}{\s33\sb120\sa120\widctlpar \b\i\f8 \sbasedon0\snext29 index heading;}{\s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 +\f3\fs20 \sbasedon0\snext34 Code;}{\s35\fi-1710\li1710\widctlpar\box\brdrs\brdrw15\brsp20 \tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx1980\tx2160\tx2340\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \f48\fs18 \sbasedon34\snext35 +PsuedoCode;}{\s36\fi-1710\li1710\ri-3680\widctlpar\tx540\tx720\tx980\tx1080\tx1440\tx1800\tx1980\tx2160\tx2420\tx2520\tx2880\tx3240\tx3320\tx3600\tx3780\tx3960\tx4220\tx4680\tx5040\tx5400\tx5760 \f48\fs18 \sbasedon34\snext36 API Summary;}{ +\s37\fi-200\li1600\widctlpar\tqr\tldot\tx8640 \f8 \sbasedon0\snext0 index 8;}{\s38\fi-200\li1800\widctlpar\tqr\tldot\tx8640 \f8 \sbasedon0\snext0 index 9;}{\s39\fi-2700\li3060\widctlpar\tx1440\tx3060 \f8 \sbasedon0\snext39 Prototype;}{ +\s40\fi-240\li1920\widctlpar\tqr\tx5580 \f8\fs18 \sbasedon0\snext0 index 8;}{\s41\fi-240\li2160\widctlpar\tqr\tx5580 \f8\fs18 \sbasedon0\snext0 index 9;}{\s42\qc\sb240\sa120\widctlpar \b\f8\fs26 \sbasedon0\snext29 index heading;}{\s43\widctlpar \f8 +\sbasedon0\snext43 ading 2;}}{\info{\title Touchdown System Software Spec}{\subject Touchdown System Software}{\author Bob Ebert}{\keywords Touchdown System Software API}{\operator Bob Ebert}{\creatim\yr1998\mo6\dy10\hr15\min43} +{\revtim\yr1998\mo6\dy10\hr19\min4}{\version128}{\edmins143}{\nofpages0}{\nofwords0}{\nofchars0}{\vern49235}}\paperw14400\paperh18620\margl1440\margr1080 \widowctrl\ftnbj\aenddoc\hyphhotz0\sprstsp\otblrul\brkfrm\sprstsm\truncex\nolead\msmcap\hyphcaps0 +\fet0\sectd \sbknone\linex0\endnhere {\header \pard\plain \s31\nowidctlpar\tqc\tx4320\tqr\tx8640 \f8 {\i\ul Palm Computing Confidential\tab \tab For Internal Use Only +\par }}{\footer \pard\plain \s30\nowidctlpar\tqc\tx4320\tqr\tx8640 \f8 POSER Profiler\tab Page {\chpgn }\tab Last Revised: 6/10/98 +\par }{\*\pnseclvl1\pnucrm\pnstart1\pnindent720\pnhang{\pntxta .}}{\*\pnseclvl2\pnucltr\pnstart1\pnindent720\pnhang{\pntxta .}}{\*\pnseclvl3\pndec\pnstart1\pnindent720\pnhang{\pntxta .}}{\*\pnseclvl4\pnlcltr\pnstart1\pnindent720\pnhang{\pntxta )}}{\*\pnseclvl5 +\pndec\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}{\*\pnseclvl6\pnlcltr\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}{\*\pnseclvl7\pnlcrm\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}{\*\pnseclvl8\pnlcltr\pnstart1\pnindent720\pnhang +{\pntxtb (}{\pntxta )}}{\*\pnseclvl9\pnlcrm\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}{\pntext\pard\plain\b\fs36\cchs0 1.\tab}\pard\plain \s1\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl1\pndec\pnprev1\pnstart1\pnsp144 {\pntxta .}}\b\f8\fs36 Overview + +\par \pard\plain \widctlpar \f8 POSER\rquote s emulator can be used to profile the code that it\rquote +s executing. It does this by counting cycles while it simulates the opcodes, and watching for JSR/RTS and interrupt/RTE events. It dumps the resulting data to file that is compatible with the Metrowerks Profiler application for Macintosh. +\par \pard \widctlpar +\par {\pntext\pard\plain\b\fs36\cchs0 2.\tab}\pard\plain \s1\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl1\pndec\pnprev1\pnstart1\pnsp144 {\pntxta .}}\b\f8\fs36 Profiler Implementation +\par {\pntext\pard\plain\b\i\fs28\cchs0 2.1\tab}\pard\plain \s2\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl2\pndec\pnprev1\pnstart1\pnsp144 }\b\i\f8\fs28 UAE Changes +\par \pard\plain \widctlpar \f8 This section describes the profiling changes to the UAE sources. +\par +\par {\pntext\pard\plain\b\cchs0 2.1.1\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 Build68K +\par \pard\plain \widctlpar \f8 UAE is built into POSER in three stages. In the first stage, Build68K takes a text file called \ldblquote table68K\rdblquote containing information about the 68K opcodes and produces \ldblquote cpudefs.c\rdblquote +, a C source file with a compressed version of UAE specific information for each opcode. There are no profiling changes to this stage. In the third stage, the POSER sour +ces are combined with the sources produced by GenCPU to build the final executable. The profiling changes for POSER are described in the next section. +\par \pard \widctlpar +\par {\pntext\pard\plain\b\cchs0 2.1.2\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 GenCPU +\par \pard\plain \widctlpar \f8 +In the second stage, GenCPU is built from sources and the cpudefs.c file from state one. When run, GenCPU can produce functions to emulate each 68K Opcode. GenCPU has been modified to produce a table of read cycle, write cycle, and extra CPU cycles for +each opcode. In addition, some of the opcode functions (e.g. Bcc) include specific code to tell the profiler to increment the clock. +\par \pard \widctlpar +\par \pard \widctlpar +As GenCPU is running, it adds comments to each opcode function to indicate what the profiling numbers are for that opcode. (gen_opcode) The numbers are specific to the MC68000 processor, to match the MC68EC000 used in the Palm devices. The source for t +he data is the \ldblquote Motorola MC68000 8-/16-/32-Microprocessors User\rquote s Manual\rdblquote section 8. Read and write cycles are tracked seperately, as well as additional CPU-only cycles for each opcode. +\par \pard \widctlpar +\par \pard \widctlpar gen_opcode calls genaread and genastore for each opcode to read in arguments and write out results. These functions have been modified to accumulate read, write and extra CPU cycles for each operation. +\par \pard \widctlpar +\par \pard \widctlpar After calling gen_opcode, generate_func takes the accumulated read, write, and extra cycle counts for the opcode and produces data for a table that\rquote +s used by POSER. It also writes a comment after each code block with the expected (per the Motorola manual) and actual (per accumulated numbers) cycle counts for the function. This is hand +y because the resulting .c file with the opcode functions can be viewed to check the accuracy of the cycle counting. +\par \pard \widctlpar +\par {\pntext\pard\plain\b\cchs0 2.1.3\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 Inaccuracies +\par \pard\plain \widctlpar \f8 Here are some known inaccuracies with the current cycle counts. +\par +\par \pard \widctlpar JMP, JSR, RTS, RTE, and Bcc fall short by one read each, for 6 or 8 cycles each depending on ROM or RAM. I believe this is because the CPU does instruction prefetch, and so the times in Motorola\rquote +s tables actually include the time needed to fetch the next instruction, not the current instruction. PC-changing instr +uctions need to throw away the prefetched instruction and read in the real next instruction, so this takes an extra read cycle. POSER does not prefetch, so there\rquote +s no good way to account for this. (Since the next instruction may be in ROM or RAM, the actual CPU cycles taken may differ.) +\par \pard \widctlpar +\par \pard \widctlpar ANDSR, ORSR, MV2SR and other "SR" instructions are 2 reads short, for 12 or 16 cycles. I\rquote m not sure why this is, some implementation detail with how the CPU references the status register? +\par \pard \widctlpar +\par \pard \widctlpar MUL and DIV instructions are c +ounted as worst case. Both have unusual execution times which depend on the values being multiplied or divided. The DIV instructions is supposedly less than a 10% difference from best to worst case, for a range of 144-158 cycles for signed and 126-140 c +ycles for unsigned values. These are counted as 158 and 140 cycles (plus wait states and effective address calculation times.) The MUL operations take 38+2n cycles, where n is the number of 1\rquote +s in the memory value for MULU, and the number of 10 or 01 patterns in the memory value catenated with 0 (as the LSB). 70 is indicated as the max value, and that is what is used. +\par {\pntext\pard\plain\b\i\fs28\cchs0 2.2\tab}\pard\plain \s2\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl2\pndec\pnprev1\pnstart1\pnsp144 }\b\i\f8\fs28 POSER changes +\par \pard\plain \widctlpar \f8 Switches.h has a HAS_PROFILING switch, which must be non-zero to include profiling in an Emulator build. +\par +\par {\pntext\pard\plain\b\cchs0 2.2.1\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 CEumlatorApp.cpp +\par \pard\plain \widctlpar \f8 +CEmulatorApp .cpp contains a little bit of code that hooks the user interface up with the functions in Profiling.cpp. Changes are made in CEmulatorApp::ObeyCommand to responds to menu and key events generated by the user, and in CEmulatorApp::FindCommand +Status to makes sure the menu state is correct. The profiling menu is defined in Palm OS Emulator.ppob. +\par \pard \widctlpar +\par {\pntext\pard\plain\b\cchs0 2.2.2\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 CPU_REG.cpp +\par \pard\plain \widctlpar \f8 CPU_REG.cpp defines and loads the table of read, write, and extra cycles for each opcode. +\par +\par \pard \widctlpar +Emulator::Execute has been modified to count cycles as the opcode executes. Most of the cycle counting is done by the functions that read and write memory, but the extra CPU-only cycles are counted in Emulator::Execute. Emulator::Execute also sets and cl +ears a flag to tell the profiler to pay attention to cycles. This is necessary so that the emulator\rquote s internal use of the memory read/write functions (to draw the screen, call ROM traps, etc) are not charged against the running application. +\par \pard \widctlpar +\par \pard \widctlpar +CPU_REG.cpp also has some code controlled by the HAS_PROFILING_DEBUG flag to help debug the profiler. This code compares the actual cycles counted as the opcodes are executed to the ones specified as expected in the table. That is also done in Emulator: +:Execute. +\par \pard \widctlpar +\par Hardware::Initialize loads the table of cycle counts. +\par +\par \pard \widctlpar +Software::ProcessException is hooked in to the emulator opcodes to special case exceptions. It allows POSER to patch out the exception handlers and do its own thing. The profiler counts time spent in exceptions seperately from time spent in regular func +tions, so Software::ProcessException calls ProfleInterruptEnter to do this. If the emulator patched out the exception, the ProfileInterruptExit is also called here. If not, then the interrupt is not finished until the RTE opcode is executed, and Softwar +e::ProcessRTE handles this. +\par \pard \widctlpar +\par \pard \widctlpar +Software::ProcessJSR is called by the CPU emulator function for JSR opcodes. It calls ProfileFnEnter to start profiling for the new function. Similarly, Software::ProcessRTS calls ProfileFnExit to stop profiling for the function and return to the enclos +ing function. +\par \pard \widctlpar +\par \pard \widctlpar Software::ProcessTrap14 has been taken over to allow executing code to contol aspects of the emulator. Controlling the profiler is part of this, and there are \ldblquote E-traps\rdblquote to init, start, stop, dump, and cleanup pro +filing. +\par \pard \widctlpar +\par \pard \widctlpar Software::ProcessTrap15 creates a \ldblquote fake\rdblquote function call by calling ProfileFnEnter and ProfileFnExit. By using the trap number for the address, this allows the profiler to count \ldblquote F-traps\rdblquote + by trap number, which is handy for finding out which system traps ar +e used most often. Software::ProcessTrap15 also normally skips the emulated trap dispatcher, preferring instead to get the trap address and do the jump itself. This greatly improves performance when emulating normal code, since about 10% of the ti +me is spent in the trap dispatcher for common operations. When profiling, native dispatch is skipped, because we actually want to know what overhead the trap dispatcher is requiring. +\par \pard \widctlpar +\par {\pntext\pard\plain\b\cchs0 2.2.3\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 RAM_ROM.cpp +\par \pard\plain \widctlpar \f8 RAM_ROM.cpp implements reading and writing to memory for various memory banks. Because the Palm devices require wait states when accessing memory, it\rquote +s not enough to simply count reads and writes as 4 cycles each (which is the CPU overhead for them.) Palm devices use different wait states for different memory, a +nd quite possibly devices will have different wait state characteristics in the future. RAM_ROM.cpp counts this. +\par \pard \widctlpar +\par \pard \widctlpar +Each of the GetLong, GetWord, GetByte, SetLong, SetWord, and SetByte functions for each memory type calls either ProfileIncrementRead or ProfileIncrementWrite, passing in the number of read or write cycles and the number of wait states for that memory typ +e. (The wait states are #defined in Profiling.h) ProfileIncrementRead and ProfileIncrementWrite are inlined to improve performance in the emulator. +\par \pard \widctlpar +\par {\pntext\pard\plain\b\cchs0 2.2.4\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 TrapPatches.cpp +\par \pard\plain \widctlpar \f8 +TrapPatches.cpp turns off a couple of trap patches if the profiler is built into the emulator. Normally, these are patched out to improve performance by avoiding emulating the ROM routines. Some of the others should probably be turned off with the HAS_P +ROFILING switch as well, but they are required by the emulator itself. +\par \pard \widctlpar +\par {\pntext\pard\plain\b\i\fs28\cchs0 2.3\tab}\pard\plain \s2\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl2\pndec\pnprev1\pnstart1\pnsp144 }\b\i\f8\fs28 Profiling Code +\par \pard\plain \widctlpar \f8 Most of the profiling code is in Profiling.h and Profiling.cpp. This is the chunk that gathers and dumps the profiling data. +\par +\par {\pntext\pard\plain\b\cchs0 2.3.1\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 Accumulators and Flags +\par \pard\plain \widctlpar \f8 +gReadCycles, gWriteCycles, and gClockCycles contain the total number of read, write, and clocks that have passed since profiling was started. These globals are accessed from other modules through the inline functions in Profiling.h. +\par \pard \widctlpar +\par \pard \widctlpar +gProfilingEnabled, gProfilingOn, and gProfilingCounted are flags that indicate the current state of profiling affairs. Enabled indicates profiling buffers have been allocated and profiling is happening or could start or stop at any time. On indicates pr +ofiling data is currently being collected. Counted indicates that the current instructions as well as memory reads and writes should be added to the global read/write/cycle counts. +\par \pard \widctlpar +\par {\pntext\pard\plain\b\cchs0 2.3.2\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 Data Structures +\par \pard\plain \widctlpar \f8 The profiler uses two main data structures to accumulate data: a tree of function call records and a stack of currently in progress functions or interrupts. +\par \pard \widctlpar +\par \pard \widctlpar The tree is stored in memory using the same format as the Metrowerks profiler file, so dumping the output file is a simple matter of writing a memory block to disk. See A +ppendix B for the record format. Global variables contain the index of: the root of the tree, the record used for overflow tracking, the record used as the root for interrupt tracking, and the index of the next available record. +\par \pard \widctlpar +\par The stack is an array of the following records. Each element tracks a function or interrupt that is currently executing. +\par \pard\plain \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \f3\fs20 struct FnStackRecord \{ +\par \pard \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \tab int call;\tab \tab \tab \tab \tab \tab \tab \tab // fn data block for fn being called +\par \tab uaecptr returnAddress;\tab \tab \tab // return address aka (SP) to calling fn +\par \tab UInt64 cyclesAtEntry;\tab \tab \tab // cycle count when fn was called +\par \tab UInt64 cyclesAtInterrupt;\tab \tab // cycle count when fn was interrupted +\par \tab UInt64 cyclesInKids;\tab \tab \tab \tab // number of cycles spent in subroutines +\par \tab UInt64 cyclesInInterrupts;\tab \tab // number of cycles spent in interrupts +\par \}; +\par \pard\plain \widctlpar \f8 +\par A global variable holds the current top of the stack. +\par +\par \pard \widctlpar To handle interrupts, a separate stack is used that keeps track of the call stack record that matches the interrupt. A stack is necessary for this because interrupts can be interrupted. We allow up to 8 of these, but I\rquote +ve never seen more than 2 used. +\par \pard \widctlpar +\par {\pntext\pard\plain\b\cchs0 2.3.3\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 GetRoutineName +\par \pard\plain \widctlpar \f8 +GetRoutineName turns an address (or interrupt number or trap number) into a string representation for that function. It attempts to use the ROM.map data to find the function name, and if no match is found it steps through the instructions found at the ad +dress indicated until it finds the end of the function, then looks for the debug symbol. If the address was to a function in a code resource and the resource was moved, then the name will be i +ncorrect. GetRoutineName is completely responsible for turning an address into a name, and it will always return some string, even if passed an invalid address. +\par {\pntext\pard\plain\b\cchs0 2.3.4\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 Generating Function Names +\par \pard\plain \widctlpar \f8 +The functiosn InitStringTable, CleanupStringTable, and FindOrAddString do the work of creating the string table (as described in Appendix B) and then adding strings to it. RecursiveAddressToStrings traverses the tree of functions and changes the address +stored with each function record into an offset into the string table, which it is generating. That\rquote s a one-time operation, if you tried to do it twice you\rquote d get garbage. +\par {\pntext\pard\plain\b\cchs0 2.3.5\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 PopCallStackFn +\par \pard\plain \widctlpar \f8 +PopCallStackFn is used when a function or interrupt is being exited from. It updates the nodes in the tree to properly track call counts and time spent in interrupts and in children. It is called both during normal function or interrupt exit and by clea +nup code that\rquote s trying to keep the profiler\rquote s call stack in sync with the CPU\rquote s call stack. +\par {\pntext\pard\plain\b\cchs0 2.3.6\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 FindOrAddCall +\par \pard\plain \widctlpar \f8 FindOrAddCall is used when a f +unction or interrupt is being entered. It looks to see if the function has prevously been called from the current function or interrupt, and if so returns the existing record. If not, a new record is allocated, initialized, and plugged into the tree. + +\par {\pntext\pard\plain\b\cchs0 2.3.7\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 ProfileInit +\par \pard\plain \widctlpar \f8 ProfileInit allocates the stack and tree with the passed sizes, and initializes a bunch of other data structures. +\par {\pntext\pard\plain\b\cchs0 2.3.8\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 ProfileCleanup +\par \pard\plain \widctlpar \f8 ProfileCleanup frees the data structures allocated in ProfileInit +\par {\pntext\pard\plain\b\cchs0 2.3.9\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 ProfileStart +\par \pard\plain \widctlpar \f8 ProfileStart turns on the profiling flags. Currently it assumes that it is not called from within an interrupt, often is not the case. When invoked from the POSER UI, the CPU is often currently processing an interrupt. +\par {\pntext\pard\plain\b\cchs0 2.3.10\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 ProfileStop +\par \pard\plain \widctlpar \f8 ProfileStop turns off collection of profiling data. If there are functions currently on the profiling stack, they are popped. +\par {\pntext\pard\plain\b\cchs0 2.3.11\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 ProfileDump +\par \pard\plain \widctlpar \f8 ProfileDump reads in the ROM.map file, turns all the addresses in the call tree into real function names, generating the string table in the process, then dumps out the heade +r, tree, and stringtable to disk. This operation is destructive to the function tree, and cannot be done more than once. (It should probably call ProfileCleanup to make sure this doesn\rquote t happen.) +\par {\pntext\pard\plain\b\cchs0 2.3.12\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 ProfileFnEnter +\par \pard\plain \widctlpar \f8 ProfileFnEnter is called by the emulator when a JSR is executed, and at a couple of other places. It creates a record for the function (or reuses an existing record), and updates the profiler\rquote s call stack. +\par \pard \widctlpar +\par \pard \widctlpar ProfileFnEnter also supports a special profiling mode. If the profiler is built with PROFILE_ONE_FN on, then it\rquote +s assumed that whenever profiling has been initialized, you always want to start profiling when a specified function is entered, and stop profiling when that function is exited. That way you get profiling information for a particul +ar function no matter who it\rquote s called from. In this case, ProfileFnEnter may be called before ProfileStart has been called, and if it detects that the target function has been entered it will start profiling at that point. +\par {\pntext\pard\plain\b\cchs0 2.3.13\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 ProfileFnExit +\par \pard\plain \widctlpar \f8 ProfileFnExit is called by the emulator when an RTS is executed The Palm OS does some funny things such that there is not always an RTS for every JSR. To handle this, ProfileFnExit has to be smart +, so it keeps the return address when a function is called and compares it to the destination address for the RTS. Most of the time they match, and everything is fine, but when they don\rquote t one of two things may be happening: either a function +is being called not by using JSR, but rather by pushing the callee\rquote s address on the stack then executing an RTS, or a RTS has been skipped and the stack has been cleaned up by the executing code (the kernel does this.) +\par \pard \widctlpar +\par \pard \widctlpar +If the return address is not what we expected based on the profiling stack, then the first thing we do is walk up the stack looking to see if the address matches some higher function. If it does, the stack is popped up to the function we expect, and the +intervening functions are flagged as improperly exited. If no match was found, we assume it\rquote s a long jump disguised as an RTS, and call ProfileFnEnter instead. +\par \pard \widctlpar +\par \pard \widctlpar The profiler\rquote s call stack can (commonly) be popped to empty. This happens when the function that was executing when ProfileStart was called exits. If profiling is started from the PO +SER UI, this happens very often, so we do the best we can: create a new fake \ldblquote root\rdblquote for the call tree, representing the function we\rquote re return +ing to, and continue on. If profiling was started by the PROFILE_ONE_FN trick, then a pop to empty is considered exiting the target function, and profiling is turned off. +\par {\pntext\pard\plain\b\cchs0 2.3.14\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 ProfileInterruptEnter +\par \pard\plain \widctlpar \f8 ProfileInterruptEnter does almost the same thing as ProfileFnEnter. The difference is that the current call is added to the \ldblquote interrupt\rdblquote root rather than the currently executing function, and the profile +\rquote s call stack pointer is pushed onto the profiler\rquote s interrupt stack. +\par {\pntext\pard\plain\b\cchs0 2.3.15\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 ProfileInterruptExit +\par \pard\plain \widctlpar \f8 ProfileInterruptExit works much like ProfileFnExit, the calls stack\rquote s record for the interrupt \ldblquote function\rdblquote is popped. Unlike with RTS, RTE is reliably matched with an interrupt exit, so it\rquote +s not necessary to do the funny call stack searching. However, when the RTE executes it\rquote +s possible that there may still be some unmatched calls (JSRs) that were executed as part of processing the interrupt. (The kernel does this regularly.) So we make sure to pop all the functions off the profiler\rquote +s call stack until we get to the one indicated by the profiler\rquote s interrupt stack. +\par \pard \widctlpar +\par The Palm OS trap handler performs trap calls by pushing stuff on the CPU stack so that the RTE will jump to the real function (and then later be able to do an RTS from that fn to get back to the code that executed the TRAP interrupt.) + To handle this, the RTE destination is compared to the PC that was saved when the interrupt happened, and if they addresses don\rquote t match then ProfileFnEnter is called to track the \rdblquote fake\rdblquote function entry. +\par +\par {\pntext\pard\plain\b\fs36\cchs0 3.\tab}\pard\plain \s1\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl1\pndec\pnprev1\pnstart1\pnsp144 {\pntxta .}}\b\f8\fs36 Using the Profiler +\par {\pntext\pard\plain\b\i\fs28\cchs0 3.1\tab}\pard\plain \s2\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl2\pndec\pnprev1\pnstart1\pnsp144 }\b\i\f8\fs28 POSER UI +\par \pard\plain \widctlpar \f8 You actually don't have to do anything at all to set up your app for profiling. That's the beauty of having the emulator handle profiling--all the work can happen "between cycles" It\rquote +s a good idea to set the compiler switch so that the debug symbols get embedded in your code, otherwise you won't be able to identify your functions in the output. For the +ROM, debug symbols are not necessary if a ROM.map file is available. The ROM.map file will be used first, and if the function is not present then the debug symbols will be used. +\par \pard \widctlpar +\par To do a profiling run: +\par {\pntext\pard\plain\f1\cchs0 \'b7\tab}\pard \fi-360\li360\widctlpar{\*\pn \pnlvlblt\pnf1\pnstart1\pnindent360\pnhang{\pntxtb \'b7}}Launch the Mac version of the emulator. +\par {\pntext\pard\plain\f1\cchs0 \'b7\tab}Load the app or otherwise set up the situation to be profiled +\par {\pntext\pard\plain\f1\cchs0 \'b7\tab}Select "Start" from the profiling menu or press cmd-[ +\par {\pntext\pard\plain\f1\cchs0 \'b7\tab}Do the profiled thing +\par {\pntext\pard\plain\f1\cchs0 \'b7\tab}Select "Stop" from the profiling menu, or press cmd-] +\par {\pntext\pard\plain\f1\cchs0 \'b7\tab}Select "Dump" from the profiling menu, or press cmd-\\ +\par \pard \widctlpar +\par \pard \widctlpar You can start and stop more than once before dumping the results. The profile data gathered in each start/stop pair will be added into that gathered in previous pairs. +\par \pard \widctlpar +\par \pard \widctlpar When you dump the result, you'll find a file in the emulator directory called "POSER Profile Results". At the moment, you have to change the type and creator to 'proF' so the Metrowerks profile will open it. Once that\rquote +s done, just double-click it, or otherwise convince the "MW Profiler" app to open it. See Reading the Results below. +\par \pard \widctlpar +\par \pard \widctlpar When you profile this way, the profiler buffers are predefined in Profiling.h. Currently they\rquote +re set to 20000 functions with a max stack of 200 functions. That's enough to profile booting a ROM, and plenty for repetetive operations, but it quickly gets used up if you do gremlins. + (A few hundred gremlins will generate 20000 unique function calls.) +\par \pard \widctlpar +\par {\pntext\pard\plain\b\i\fs28\cchs0 3.2\tab}\pard\plain \s2\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl2\pndec\pnprev1\pnstart1\pnsp144 }\b\i\f8\fs28 From Your App +\par \pard\plain \widctlpar \f8 You can Init, Start, Stop, Dump, and Cleanup the POSER profiler from application code, much like you can for the Metrowerks profiler for Mac. To do this, #include \ldblquote EmuTraps.h\rdblquote and #include \ldblquote +EmuProfiling.h\rdblquote in the module that will control the profiler. (You might want to put EmuProfilingNOPs.c in the project for simulator builds only, so that the profiling functions will be stubbed out there.) The APIs are described below. +\par \pard \widctlpar +\par {\pntext\pard\plain\b\cchs0 3.2.1\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 ProfileInit +\par \pard\plain \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \f3\fs20 void ProfileInit(int maxCalls, int maxDepth) +\par \pard\plain \widctlpar \f8 \tab maxCalls - the number of function call buffers to allocate +\par \tab maxDepth - the number of stack frames to allocate +\par \pard \widctlpar This allocates the profile buffers within the POSER memory partition. It must be done prior to calling any other profiling function. +\par {\pntext\pard\plain\b\cchs0 3.2.2\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 ProfileStart +\par \pard\plain \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \f3\fs20 void ProfileStart() +\par \pard\plain \widctlpar \f8 Begin profiling at that point in the code. The instructions executed within the function that calls ProfileStart will appear in the result in a function body under the label \ldblquote partial\rdblquote +, as will any code executed by calling functions if ProfileStop is not called when the function that called ProfileStart exits. +\par {\pntext\pard\plain\b\cchs0 3.2.3\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 ProfileStop +\par \pard\plain \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \f3\fs20 void ProfileStop() +\par \pard\plain \widctlpar \f8 Stop profiling at that point in the code. In general, it\rquote +s a good idea to start and stop profiling at the same level, but that is not required. If you stop while nested deeper than where you started, all the functions still on the call stack will be pop +ped as if they had exited at the point ProfileStop was called. +\par {\pntext\pard\plain\b\cchs0 3.2.4\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 ProfileDump +\par \pard\plain \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \f3\fs20 void ProfileDump() +\par \pard\plain \widctlpar \f8 Dumps the accumulated results to a file called \ldblquote POSER Profile Results\rdblquote . (Future versions should allow you to pass the file name as an argument to ProfileDump.) +\par {\pntext\pard\plain\b\cchs0 3.2.5\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 ProfilePrint +\par \pard\plain \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \f3\fs20 void ProfilePrint() +\par \pard\plain \widctlpar \f8 A debugging function. Prints the profile results as text to POSER\rquote s Log file. Can be very slow. +\par {\pntext\pard\plain\b\cchs0 3.2.6\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 ProfileCleanup +\par \pard\plain \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \f3\fs20 void ProfileCleanup() +\par \pard\plain \widctlpar \f8 Free up the data structures allocated by ProfileInit. +\par +\par {\pntext\pard\plain\b\fs36\cchs0 4.\tab}\pard\plain \s1\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl1\pndec\pnprev1\pnstart1\pnsp144 {\pntxta .}}\b\f8\fs36 Reading the Results +\par \pard\plain \widctlpar \f8 The profiler dumps the results in a format compatible with Metrowerks profiler. This format was reverse engineered, and is incompletely described in Appendix B. +\par \pard \widctlpar +\par \pard \widctlpar +Times are all theoretically in millisecond for a 16.580608 MHz clock. The times are written to the output file as 64-bit integers of clocks, and a multiplier is applied to scale the result to milliseconds based on the clock speed. 5661.518 is a bit over + 5 1/2 seconds, and 1.255 is a bit over 1 1/4 milliseconds. (In theory at least, I'm still validating the data, if you see anything that strikes you as inaccurate, please tell me about it!) +\par \pard \widctlpar +\par \pard \widctlpar The header in the output file can be ignored. The Overhead field actually contains the number of cycles spent in interrupts, which should be identical to the +Children column for the interrupts block. +\par \pard \widctlpar +\par The first column contains the function name, with these special cases: +\par \pard \fi-1440\li2160\widctlpar functions\tab a top-level cover that includes all regular function calls +\par interrupts\tab a top-level node that includes all interrupts (except the ones POSEr has patched out) +\par \pard \fi-1440\li2160\widctlpar partial\tab means profiling was started in the middle of the function, so we don't have the address of the fn and consequently don't have a name. +\par overflow\tab a lump of all functions called when we're out of space to track more unique calls, where unique means called from the same path to the "root" of the call tree. +\par \pard \fi-1440\li2160\widctlpar unknown\tab a function for which no name could be found. Many functions in .prc files show up as unknown. +\par \pard \widctlpar +\par The rest of the names all take the form "Name $address.x" where: +\par Name- is the name of the function or trap. +\par address-For regular functions, the 4 byte address. +\par \tab -For traps, the 2 byte trap number. +\par \tab -For interrupts, the 1 byte interrupt number. +\par x- debugging info, indicating where the name information came from: +\par \tab 't' = trap names table built in POSER, +\par \tab 'm'= the ROM.Map file found in the same directory as POSER +\par \tab 'd'=the debug symbol appended to the function\rquote s instructions by the compiler +\par \tab 'i'=invalid address flag (usually due to POSERs implementation internals) +\par +\par The other columns are defined as follows. Note MINIMUM and STACK SPACE are NOT what you expect: +\par +\par {\b count} - the number of times the functions was called. +\par +\par {\b only} - time spent in the function, not counting child fns or interrupts. +\par +\par {\b %} (by only) - percentage of total profiling time spent in this fn/call. +\par +\par {\b +Children} - time spent in the function including child fns, but not including interrupts +\par +\par {\b %} (by +Children) - percentage of total profiling time spent in the fn and its kids +\par +\par {\b Average} - "Only" divided by "count" +\par +\par {\b Maximum} - the maximum time (in msec) spent in any 1 call to the fn. +\par +\par \pard \widctlpar {\b Minimum} - {\i NOT WHAT YOU EXPECT}. This is actually the time spent handling interrupts for calls to that particlular instance of that fn. Due to the way the "Summary" is calculated, this number won't be correct in summary views. + +\par \pard \widctlpar +\par \pard \widctlpar {\b Stack space} - {\i NOT WHAT YOU EXPECT} +. More of a trap/interrupt counter plus some debug info. The number in that field for a particular fn entry is incremented by 1 every time the fn is interrupted, by 10000 if the fn call is made by a faked up RTS instead of a JSR, and 1000 if the functio +n was executing when an RTS occurred that didn't return to it's called but instead returned to some fn farther up the call chain. Again, this will only be useful in the detail view, since the summary does some computation on it. +\par {\pntext\pard\plain\b\fs36\cchs0 5.\tab}\pard\plain \s1\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl1\pndec\pnprev1\pnstart1\pnsp144 {\pntxta .}}\b\f8\fs36 Appendix A - Profiling Includes +\par {\pntext\pard\plain\b\i\fs28\cchs0 5.1\tab}\pard\plain \s2\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl2\pndec\pnprev1\pnstart1\pnsp144 }\b\i\f8\fs28 EmuTraps.h +\par \pard\plain \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \f3\fs20 /********************************************************************* +\par \pard \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 * +\par * Copyright (c) 1998 +\par * 3Com/Palm Computing Division. All rights reserved. +\par * +\par * Redistribution and use in source and binary forms, with or without +\par * modification, are permitted provided that the following conditions +\par * are met: +\par * +\par * 1. Redistributions of source code must retain the above copyright +\par * notice, this list of conditions and the following disclaimer. +\par * +\par * 2. Redistributions in binary form must reproduce the above +\par * copyright notice, this list of conditions and the following +\par * disclaimer in the documentation and/or other materials provided +\par * with the distribution. +\par * +\par * 3. All advertising materials mentioning features or use of this +\par * software must display the following acknowledgement: +\par * +\par *\tab \tab This product includes software developed by 3Com and its +\par *\tab \tab contributors. +\par * +\par * 4. Neither 3Com nor the names of its contributors may be used to +\par * endorse or promote products derived from this software +\par * without specific prior written permission. +\par * +\par * THIS SOFTWARE IS PROVIDED BY THE 3COM AND CONTRIBUTORS ``AS IS'' +\par * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +\par * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A +\par * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 3COM OR +\par * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +\par * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +\par * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF +\par * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +\par * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +\par * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +\par * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY +\par * OF SUCH DAMAGE. +\par * +\par *******************************************************************/ +\par #pragma once +\par +\par #define\tab emuTrapBase\tab \tab \tab 0x0000 +\par +\par typedef enum \{ +\par \tab emuTrapProfileInit = emuTrapBase, +\par \tab emuTrapProfileStart, +\par \tab emuTrapProfileStop, +\par \tab emuTrapProfileDump, +\par \tab emuTrapProfileCleanup, +\par +\par \tab // WARNING!! LEAVE THIS ONE AT THE END AND ALWAYS ADD NEW TRAPS TO +\par \tab // THE END OF THE TRAP TABLE BUT RIGHT BEFORE THIS TRAP!!!!!!!!! +\par \tab emuTrapEmuReserved1, +\par \tab emuTrapEmuReserved2, +\par \tab emuTrapEmuReserved3, +\par \tab emuTrapEmuReserved4, +\par \tab +\par \tab emuTrapLastTrapNumber +\par \tab \} EmuTrapNumber; +\par +\par +\par #define emuTrapNum\tab \tab \tab \tab 0x0E\tab \tab // Emulator trap +\par +\par #define EMU_TRAP(trapNum) \\ +\par \tab TWOWORD_INLINE(m68kTrapInstr+emuTrapNum,trapNum) +\par +\par #define ASM_EMU_TRAP(trapNum)\tab \\ +\par \tab \tab \tab DC.W\tab m68kTrapInstr+emuTrapNum; \\ +\par \tab \tab \tab DC.W\tab trapNum +\par \pard \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 +\par {\pntext\pard\plain\b\i\fs28\cchs0 5.2\tab}\pard\plain \s2\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl2\pndec\pnprev1\pnstart1\pnsp144 }\b\i\f8\fs28 EmuProfiling.h +\par \pard\plain \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \f3\fs20 /********************************************************************* +\par \pard \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 * +\par * Copyright (c) 1998 +\par * 3Com/Palm Computing Division. All rights reserved. +\par * +\par * Redistribution and use in source and binary forms, with or without +\par * modification, are permitted provided that the following conditions +\par * are met: +\par \pard \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 * +\par \pard \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 * 1. Redistributions of source code must retain the above copyright +\par * notice, this list of conditions and the following disclaimer. +\par * +\par * 2. Redistributions in binary form must reproduce the above +\par * copyright notice, this list of conditions and the following +\par * disclaimer in the documentation and/or other materials provided +\par \pard \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 * with the distribution. +\par \pard \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 * +\par * 3. All advertising materials mentioning features or use of this +\par * software must display the following acknowledgement: +\par * +\par *\tab \tab This product includes software developed by 3Com and its +\par *\tab \tab contributors. +\par * +\par * 4. Neither 3Com nor the names of its contributors may be used to +\par * endorse or promote products derived from this software +\par * without specific prior written permission. +\par * +\par * THIS SOFTWARE IS PROVIDED BY THE 3COM AND CONTRIBUTORS ``AS IS'' +\par * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +\par * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A +\par * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 3COM OR +\par * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +\par * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +\par * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF +\par * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +\par * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +\par * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +\par * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY +\par * OF SUCH DAMAGE. +\par * +\par *******************************************************************/ +\par #pragma once +\par +\par #include "EmuTraps.h" +\par +\par void ProfileInit(int maxCalls, int maxDepth) +\par \tab \tab \tab EMU_TRAP(emuTrapProfileInit); +\par +\par void ProfileStart() +\par \tab \tab \tab EMU_TRAP(emuTrapProfileStart); +\par +\par void ProfileStop() +\par \tab \tab \tab EMU_TRAP(emuTrapProfileStop); +\par \pard \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 +\par \pard \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 void ProfileDump() +\par \tab \tab \tab EMU_TRAP(emuTrapProfileDump); +\par +\par void ProfileCleanup() +\par \tab \tab \tab EMU_TRAP(emuTrapProfileCleanup); +\par +\par \pard \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 +\par {\pntext\pard\plain\b\i\fs28\cchs0 5.3\tab}\pard\plain \s2\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl2\pndec\pnprev1\pnstart1\pnsp144 }\b\i\f8\fs28 EmuProfilingNOPs.c +\par \pard\plain \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \f3\fs20 // stub out the functions for simulator builds only +\par \pard \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 +\par void ProfileInit(int maxCalls, int maxDepth) \{return;\} +\par void ProfileStart() \{return;\} +\par void ProfileStop() \{return;\} +\par void ProfileDump() \{return;\} +\par void ProfilePrint() \{return;\} +\par void ProfileCleanup() \{return;\} +\par {\pntext\pard\plain\b\fs36\cchs0 6.\tab}\pard\plain \s1\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl1\pndec\pnprev1\pnstart1\pnsp144 {\pntxta .}}\b\f8\fs36 Appendix B - Metrowerks Profiler File Format +\par \pard\plain \widctlpar \f8 +The profile output file is composed of three sections. A header section of 0x200 bytes, then a section of FnCallRecord structures containing an array of function data, followed by a string table containing the names of each function. T +he functions are represented in a tree, where each node represents a given function when called from a particular path to the root of the tree. That is, if A calls C and B calls C, then there will be at least 2 records in the tree representing calls to C +, once when called from A and another when called from B. I say at least 2 because A and B themselves may be called from multiple places, and each unique version of A and B will also have a unique child node representing C. +\par {\pntext\pard\plain\b\cchs0 6.1.1\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 Header +\par \pard\plain \widctlpar \f8 The header section contai +ns things like the number of functions in the function data array, and offset to the start of the string table, the size of the string table, and the record number (array index) of the root node in the function tree. +\par \pard \widctlpar +\par \pard\plain \s34\fi-1714\li1714\keepn\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \f3\fs20 struct ProfFileHeader \{ +\par \pard \s34\fi-1714\li1714\keepn\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \tab UInt32\tab proF;\tab \tab \tab \tab \tab // 'proF' +\par \tab UInt32\tab version;\tab \tab \tab \tab // 0x00040002 +\par \tab UInt32\tab fnCount;\tab \tab \tab \tab // number of unique fns (records) in log +\par \tab UInt32\tab four;\tab \tab \tab \tab \tab // 0x00000004 +\par +\par \tab UInt32\tab zeros1;\tab \tab \tab \tab // 0x00000000 +\par \tab UInt32\tab zeros2;\tab \tab \tab \tab // 0x00000000 +\par \tab UInt32\tab unknown;\tab \tab \tab \tab // 0xB141A3A9\tab - maybe timebase data +\par \tab UInt32\tab recordsSize;\tab \tab // size of header plus size of data (or offset to string table) +\par \tab +\par \tab UInt32\tab stringTableSize;\tab // size of string table in bytes +\par \tab UInt64\tab overhead;\tab \tab \tab // count for overhead +\par \tab Int32\tab rootRec;\tab \tab \tab \tab \tab // record number of root of tree +\par \tab +\par \tab UInt32\tab sixtyfour1;\tab \tab \tab // 0x00000064 +\par \tab UInt32\tab sixtyfour2;\tab \tab \tab // 0x00000064 +\par \tab UInt32\tab countsPerTime; \tab // translation between counts at nodes and integers in column +\par \tab \tab \tab \tab \tab \tab \tab \tab \tab \tab \tab // 0x00FD0000 = 16.580608 MHz with display in seconds +\par \tab \tab \tab \tab \tab \tab \tab \tab \tab \tab \tab // 0x000040C4 = 16.580608 MHz with display in milliseconds +\par \pard \s34\fi-1714\li1714\keepn\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \tab UInt32\tab oddstuff0;\tab \tab \tab // seems like it can be 0, set by profiler tool itself + +\par \pard \s34\fi-1714\li1714\keepn\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \tab +\par \tab UInt32\tab oddstuff1;\tab \tab \tab // seems like it can be 0, set by profiler tool itself +\par \tab UInt32\tab oddstuff2;\tab \tab \tab // seems like it can be 0, set by profiler tool itself +\par \tab UInt32\tab oddstuff3;\tab \tab \tab // seems like it can be 0, set by profiler tool itself +\par \tab UInt32\tab oddstuff4;\tab \tab \tab // seems like it can be 0, set by profiler tool itself +\par +\par \pard \s34\fi-1714\li1714\keepn\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \tab Byte\tab unused[0x200 - 0x50];\tab // for 0x200 bytes +\par \pard \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \}; +\par \pard \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 +\par {\pntext\pard\plain\b\cchs0 6.1.2\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 Function Array +\par \pard\plain \widctlpar \f8 Following the header (starting + at offset 0x200 in the file) is an array of header.fnCount structs as defined below. Each struct represents a unique node in the tree. Most of these values are straightfoward, and appear in the results view representing what you expect. The sib and ki +d records determine the relationship to other functions in the tree. Children of a given node are found by looking at the node\rquote s kid field to find the first child, then look at the child\rquote +s sib field to find the adjacent nodes which are all considered children of the first kid\rquote s parent. If the sib or kid contain -1 then there are no sibling or children nodes. +\par \pard \widctlpar +\par \pard\plain \s34\fi-1714\li1714\keepn\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \f3\fs20 struct FnCallRecord \{ +\par \pard \s34\fi-1714\li1714\keepn\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 \tab UInt32\tab name;\tab \tab \tab \tab +// also offset from start of name table to this fn's name +\par \tab UInt32\tab entries;\tab \tab \tab // times function was called +\par \tab UInt64\tab cyclesSelf;\tab \tab // profiling data for this fn alone +\par \tab UInt64\tab cyclesPlusKids;\tab // profiling data for this fn with kids +\par \tab UInt64\tab cyclesMin;\tab \tab // profiling data for this fn alone, min +\par \tab UInt64\tab cyclesMax;\tab \tab // profiling data for this fn alone, max +\par \tab Int32\tab \tab sib;\tab \tab \tab \tab // record number of sib, -1 for no sibs +\par \tab Int32\tab \tab kid; \tab \tab \tab \tab // record number of kid, -1 for no kids +\par \tab UInt32\tab stackUsed;\tab \tab // bytes of stack used by fn, we use it to count unmatched returns +\par \}; +\par \pard \s34\fi-1710\li1710\widctlpar\tx360\tx720\tx1080\tx1440\tx1710\tx1800\tx2160\tx2520\tx2880\tx3240\tx3600\tx3960\tx4320\tx4680\tx5040\tx5400\tx5760 +\par {\pntext\pard\plain\b\cchs0 6.1.3\tab}\pard\plain \s3\sb240\sa60\keepn\widctlpar{\*\pn \pnlvl3\pndec\pnprev1\pnstart1\pnsp144 {\pntxtb .}}\b\f8 String Table +\par \pard\plain \widctlpar \f8 +After the array of function records is a string table. This table contains the names of all the functions in the profiling output. Each function name appears only once, and all the nodes that represent that function will refer to the same string. Order + of strings within the string table is not important. +\par \pard \widctlpar +\par \pard \widctlpar T +he table is stores as adjacent C strings. That is, the first byte of the table is the first byte of the first string, and subsequent bytes contain the rest of the first string until a NULL (0) byte appears. Immediately after the terminator is the first +byte of the next string. +\par }
\ No newline at end of file diff --git a/Docs/UsingPalmOSEmulator.pdf b/Docs/UsingPalmOSEmulator.pdf Binary files differnew file mode 100644 index 0000000..7e0ef9e --- /dev/null +++ b/Docs/UsingPalmOSEmulator.pdf diff --git a/Docs/_Bugs.txt b/Docs/_Bugs.txt new file mode 100644 index 0000000..8f31052 --- /dev/null +++ b/Docs/_Bugs.txt @@ -0,0 +1,116 @@ +======================================================================== +Bug List 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> +======================================================================== + +This document contains the list of known significant bugs in the Palm +OS Emulator. This list is not complete -- many insignificant or +low-runner bugs have been omitted just to keep up the signal to noise +ratio. + +* 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. + +* Selecting Pilot, PalmPilot, Palm III, or Palm VII as the device to + emulate always results in a PalmPilot being emulated. There are + very few side effects of this bug (for instance, a Pilot will now + indicate that it has backlighting) but fixing this problem will + probably cause more problems than it fixes (for instance, the Palm + VII OS would then think that it's on Palm VII hardware instead of + PalmPilot hardware and start trying to do Palm VII-specific things, + and crashing because there is little actual support for Palm VII + hardware). + +* When using NetLib redirection, NetLibSelect doesn't support the use + of sysFileDescStdIn or sysFileDescStdOut. + +* There is no IR emulation. + +* HotSync doesn't work on Visor devices. + +* Many operations will hang the emulator if performed when the + emulated power is off. These operations include -- but are not + limited to -- typing characters, clicking on the LCD area, running + Gremlins, and installing files. To be on the safe side, limit + yourself to clicking on the hard buttons and closing/quitting the + session. + +* Sound emulation doesn't work on the Mac. The facilities previously + used don't appear to be available under Carbon, and we haven't yet + found any alternatives. If you know about sound on the Mac, we + could use your help! + +* The English Output created by the minimization process is very + preliminary, rough, and incomplete. Some things to know: + + * Pen down-drag-up event sequences are reported as a series of + "Tap Pen" messages instead of "Press pen here, move to there, + and finally lift up". + + * The English output will likely contain many messages to "Tap + at x,y" instead of something more helpful like "Tap on button + called 'Foo'". That's because the code that determines what was + tapped on is incomplete. For instance, if the tap was on a menu + item, you'll get the generic tap message. + + * In the cases where a tap at a specific location can't be + related in terms for form objects or menu items, or where the + exact location in the form object is critical (for instance, in + the case of a scrollbar, where taps on the arrows are different + from taps on the main part of the scrollbar but are still + reported the same way), we hope to provide screen shots with + cross-hairs at the location you should tap. + + To address these shortcomings, you may want to do one of two things: + + * Help the Palm OS Emulator effort by modifying Poser's output + to be more accurate and expressive. The schedule for the next + release of Poser doesn't include time for Palm to address the + issues in-house. + + * Replay the events from the <Original_File>_Min.pev file. This + effectively carries out the steps described in the English + output. The drawback with this approach is that replaying + events also reloads the initial state that existed when the + events were generated. That is, you can't, say, start debugging + your application under CodeWarrior, replay the events until an + error occurs, and then break into the debugger. + + Enabling such a scenario may also be considered a third party + opportunity. + +* Certain versions of Windows (NT 4.0 and '95 for sure, don't know + about '98 or ME, but fixed in 2000 and XP) have a problem where they + can truncate the bottom of the Choose File common dialog. The amount + of this truncation (and even whether or not it occurs) is based on + the size an location of the topmost window when the dialog is + opened. If you are seeing this truncation, try moving the + underlying window or dialog up on the screen before opening the + Choose File dialog. + +* Single-stepping in Gremlins when there is no specified upper event + limit doesn't work. diff --git a/Docs/_Building.txt b/Docs/_Building.txt new file mode 100644 index 0000000..da10bfa --- /dev/null +++ b/Docs/_Building.txt @@ -0,0 +1,153 @@ +======================================================================== +Build Notes 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> +======================================================================== + +======================================================================== +Windows +======================================================================== +To build the Palm OS Emulator under Windows, you will need Visual C++ +6.0. The Emulator runs under Windows 95, Windows 98, Window ME, Windows +NT 4.0, Window 2000, and Windows XP, so you should be able to build +under those environments, too. + +To build, simply load the workspace (Emulator.dsw) or project +(Emulator.dsp) from the BuildWin directory, select the project target +(you'll mostly likely be interested in building "Win32 Release"), and +select the the "Build/Build Emulator.exe" menu item. For that target, +the resulting executable will end up in +".../BuildWin/Release/Emulator.exe". + +If you want to build the ROM Transfer Palm OS application, you will need +CodeWarrior for Palm OS Release 7. + +======================================================================== +Macintosh +======================================================================== +To build the Palm OS Emulator under Mac OS, you will need CodeWarrior +Pro 7.0. + +To build, simply load the project Emulator.mcp in the BuildMac folder, +select the project target (you'll mostly likely be interested in +building "POSER PPC"), and select the the "Make" menu item. For that +target, the resulting executable will end up in "...:BuildMac:Built:Palm +OS Emulator". + +If you want to build the ROM Transfer Palm OS application, you will need +CodeWarrior for Palm OS Release 7. + +======================================================================== +Unix +======================================================================== + +(A cool HOWTO by Jan Schaumann can be found at: + + <http://www.netmeister.org/palm/POSE/POSE-HOWTO.html>) + +Palm OS Emulator for Unix has been built on a number of platforms, but +the one it's developed under is RedHat Linux 6.0 (kernel 2.2.5, +glibc-devel 2.1.1-6 using XFree86 3.3.3.1-49 running a 16 bit display). +People have also built it under SuSe Linux, Solaris 2.6 and 2.7, +FreeBSD, Debian, and QNX Neutrino, so you may have luck under those or +other environments. Developers using RedHat Linux 7.0 need to make sure +that they have the gcc compiler patch from RedHat. + + <http://www.redhat.com/support/errata/rh7-errata-bugfixes.html> + +We use pthreads, so you need GNU glibc2 (aka Linux libc6) C library and +a 2.x kernel on a Linux system. Other operating systems need to support +true threads. + +The source makes heavy use of C++ templates and exceptions. On Linux, +you must have egcs-1.1.1 or better to compile it. egcs-1.1 or any gcc +below 2.95 may not work. RedHat Linux 6.0 comes with egcs 1.1.2, so you +should be OK there. If you are running RedHat Linux 5.2, you will need +to download the latest from <http://egcs.cygnus.com> and build it. For +other OS'es, either use egcs, or be sure your compiler supports these +C++ features. + +Note that egcs needs to be built with the HANDLE_SYSV_PRAGMA option +turned on in order to have the support to pack structures correctly. The +Linux version of egcs has this turned on, but other variants -- such as +the compiler that comes with FreeBSD -- may not. If you're using gcc +2.95 or later, make sure it was compiled with the HANDLE_PRAGMA_PACK +option. + +Sparc note: the Sparc assembler doesn't seem able to handle the mangled +C++ names emitted by GCC. You may have to follow the instructions in +the GCC FAQ "How to work around too long C++ symbol names?" + +Some versions of Linux are included with a version of gcc that cannot +correctly compile the emulator. It has a code generation bug that +causes the emulator to crash on startup. If you have gcc 2.96 or 2.97, +you probably have a version with the bug. Our configure script +attempts to detect compilers with the bug and invokes some workarounds +if it finds one. If those workarounds don't appear to be working for +you, you may want to revert to gcc 2.95.x or upgrade to gcc 3.0.x. Here +are instructions from one developer: + + What I did was compile gcc 2.95.3 --prefix=/usr/local/gcc2953 (ie, I + didn't destroy the 2.96 conpiler). Using that compiler (export + CC=/usr/local/gcc2953/bin/gcc, CXX=/usr/local/gcc2953/bin/g++), I + built glibc-2.2.2 and installed that in /usr/local. After that + completed, I put /usr/local/lib at the head of the search list in + /etc/ld.so.conf and rebooted. Then I compiled fltk and the emulator. + This time it worked. It may not be necessary to build the libraries + -- All I know is that it worked! + +We use the FLTK X toolkit. I'm not going to get into an X GUI Toolkit +religious war, so don't ask why not some other toolkit. You are +encouraged to add support for other toolkits, like Qt or GTK+ or even +Xt. I have tried to keep all of the FLTK code in the Em*Fltk.cpp files. +If you add support for another toolkit, please follow that pattern. +Don't pollute the UNIX-generic code with toolkit specific code. FLTK is +available from <http://www.fltk.org>, is a quick download, and is easy +to build on a variety of OS'es. We've tested with the binary install +RPMs for 1.0.3 and 1.0.4, as well as the source install of 1.0.5 and +1.0.7. "fluid" (the FLTK User Interface Design tool) is part of the +build, so make sure it gets installed, too. + + NOTE: Not all FLTK's install the same way. Some install their + includes in an "Fl" directory, some install their includes in + an "FL" directory. The emulator is written to look for them + in "FL". If you don't have that directory, you may need to + create a symbolic link with that name to "Fl". + + Additionally, the Emulator's build script expects libfltk.a to + be installed in /usr/lib or /usr/local/lib. If you've + installed it elsewhere, use the --with-fltk=DIR configure + flag. The directory you specify will be used as the prefix + for additional "include" and "lib" dirs to search. + + NOTE: Many users have compiled against FLTK 1.0.11 with no + apparent problems, so using that version instead of 1.0.7 + should be OK. FLTK 1.1.0 (in beta at the time of this + writing) is only minimally supported. Emulator 3.5 includes + initial support for this version of FLTK, but little testing + has been performed. Our confidence is high that there are no + problems, but your mileage may vary. + +To build the Emulator, first build and/or install FLTK. Doing this +first is very important. Otherwise, the Emulator's build script won't +find it. After that, switch to the BuildUnix directory and execute +the following commands: + + ./configure + make + +You will end up with an application called "pose" that you can run. + +If you want, the "configure" script understands the following command- +line switches: + + --enable-palm-profile Include support for profiling Palm applications + --enable-profile Include support for profiling Poser itself + --enable-debug Include debugging symbols. This option also + turns on palm-profile, turns off profile, and + compiles the source code without optimizations. + --enable-static-link static link; no shared libraries (default no). + --with-fltk=DIR Use the fltk which is installed on DIR. diff --git a/Docs/_Contributing.txt b/Docs/_Contributing.txt new file mode 100644 index 0000000..89873f6 --- /dev/null +++ b/Docs/_Contributing.txt @@ -0,0 +1,176 @@ +======================================================================== +Contributing guidelines 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> +======================================================================== + +The Palm OS Emulator is distributed under and protected by the GNU +GENERAL PUBLIC LICENSE (the full copy of which is found in _GPL.txt). +We make the source code available so that others can alter it for their +own needs. We do request you submit your changes back to us so that we +can merge them into the main version of the product, but there is no +requirement that you do so. Changes can be submitted to the current +maintainer (<mailto:keith.rollin@corp.palm.com>) or Palm Developer +Support (<mailto:bug.reports@corp.palm.com>). + +If you make changes and submit them back to us, all I ask is that you +follow a few guidelines. The general theme of these guidelines is to +follow the programming conventions you already find in the source code. +I don't want this thing to look like a patchwork quilt; it should look +like it was written by just one person. + +* Naming conventions: I use MacApp's naming conventions: + + Function names begin with upper case letters (e.g., SomeFunction). + + Private function names begin with "Prv" (e.g. PrvHelperFunction). + This includes static functions (local to a single file) and + private member functions. + + Local variables begin with lower case letters (e.g., myVariable). + + Global variables begin with a "g" (e.g., gCachedData). + + Data members begin with an "f" (e.g., fFieldOfDreams). However, + I'm flexible on this one. I think the UNIX guys are using + "_" for the UNIX-specific portions, and there are probably + still some Mac sections that use "m". + + Static data members begin with "fg" (e.g., fgDebuggerData). + + Constants start with a "k" (e.g., kTicksPerSecond). + + To help clean up the namespace a little bit, data types (classes, + structs, typedefs, etc.) and file names start with the "Em" + prefix. You may see a mix of this now in the sources, because + I'm slowly moving over to that convention. Using the "Em" + prefix for types is more "primitive" that using actual namespaces, + but it's simpler (easier to type). + + File guards are based on the name of the file, with the '.' replaced + with an underscore. Thus, the fileguard for EmWhizzyHeader.h is + EmWhizzyHeader_h. File guards are placed only in the header; they + are not used to control the inclusion of the header from another + file. + +* Use classes and objects only where it makes sense. There's no need + to go overboard. + +* You'll see some places where I use classes with all-static members + to emulate namespaces. This approach was used before CodeWarrior + supported namespaces. Now that it does, I've started using + namespaces. However, neither CodeWarrior Pro 5 nor VC++ 6.0 + support namespaces in their browsers, so choose which method you + like if you introduce a new namespace. + +* By convention, I use pointer types (e.g., "void*") for referencing + data in the host computer's space, and the UAE type "emuptr" to + reference data residing in the emulated Palm OS space. (This + comment may not make much sense now, but come back to it later + once you've looked over the sources and learned how Palm OS + memory is emulated.) + +* Braces go like this: + + if (...) + { + ... + } + + I use this approach because it is consistant with the bracing rules + for function bodies, it's easy to match up the begin and end of + a block, and because it's easy to comment out the "if" statement + in order to make the block unconditional. People trying to comment + out the "if" statement when it also includes the left brace at the + end have to deal with finding and commenting out the right brace + as well. + + The contents always move to the right. None of this in-and-out, + back-and-forth GNU stuff. + + I generally like to use braces even if there is only one line + in between them, but I'm not adamant about that. + +* One statement per line. None of this stuff: + + if (...) DoSomething(); + + I don't like the DoSomething() being on the same line, since that + makes it impossible to put a breakpoint on it. + +* Comment all functions using the following template: + + /*********************************************************************** + * + * FUNCTION: + * + * DESCRIPTION: + * + * PARAMETERS: none + * + * RETURNED: nothing + * + ***********************************************************************/ + + Not all functions are currently like this, but I'm working on that. + +* Call global functions using "::". E.g.: + + ::SomeGlobalFunction (); + + Again, not all of Poser sources follow this convention, but I'd + like to stick to it. + +* When calling non-static member functions from another function of the same + class or subclass, use "this->". When calling static member functions, + you may use "EmMyClass::" to prefix the function call. However, I'm not + really sure I like this latter convention, so use the prefix or not, as + you choice. + +* When referencing a data member, you may want to also use the "this->" + prefix. I currently don't use this much in Poser, preferring to use + the "f" prefix in the data member's name to indicate that it is a data + member. However, by using "this->", you can take advantage of VC++'s + type-completion features, which I'm finding to be really handy. + +* No platform-specific calls in the cross-platform files. If you find any + counter-examples to this rule, it's a bug. + +* Let's not go overboard with STL. Yes, I know you can write a MasterMind + program in one line with it (true!), but let's keen this sane. + +* Whitespace. Use lots of it! Vertically and horizontally! It's possible + to go overboard -- I knew one programmer who put spaces around every token + in his code, leading to stuff like: + + if ( myPtr -> mySubStruct . myField ) + { + for (ii = 0 ; ii < max ; ++ ii) + { + myObject -> CallSomeFunction ( ii * 2 ) ; + } + } + + But this is a bit extreme for me. I like putting braces on their own lines + for the vertical spacing, spaces in mathematical expressions, and spaces + between the function name and following parameter list, as well as the + places most other programmers put them. + + if (myPtr->mySubStruct.myField) + { + for (ii = 0; ii < max; ++ii) + { + myObject->CallSomeFunction (ii * 2); + } + } + +Anyway, I'm flexible on most of this stuff. These are merely guidelines. I'm +just asking that you keep them in mind if possible. + +Thanks, + +-- Keith Rollin +-- Palm OS Emulator engineer diff --git a/Docs/_Credits.txt b/Docs/_Credits.txt new file mode 100644 index 0000000..d42f661 --- /dev/null +++ b/Docs/_Credits.txt @@ -0,0 +1,219 @@ +======================================================================== +Credits 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> +======================================================================== + +The Palm OS Emulator is currently a Palm Computing product. However, it +was not originally written by Palm Computing. Rather, it was developed +by outside developers, on their own time and without help from Palm +Computing. This product is a tribute to them, their perseverance, +their creativity and their ingenuity. We just stepped in after the hard +parts were done. + +------------------------------------------------------------------------ +* Greg Hewgill + <http://www.hewgill.com/> + + Original Copilot, the basis for the Windows version of the Palm OS + Emulator. See the article "13hewgil.pdf" on how he developed + Copilot. + +------------------------------------------------------------------------ +* Craig Schofield + <http://members.aol.com/illumesoft/illume.html> + + Macintosh port of Copilot, the basis for the Macintosh version of + the Palm OS Emulator. + +------------------------------------------------------------------------ +* Bernd Schmidt + <http://www.freiburg.linux.de/~uae/> + + UAE (UAE Amiga Emulator), which provides the 68000 CPU emulator + used at the core of Copilot. + +------------------------------------------------------------------------ +* Bruce Ashley Photography + Santa Cruz, Ca 831-429-8300 + email: ba@phot.com + + For the amazing skins. + +------------------------------------------------------------------------ +* Bill Spitzak and others + <http://www.fltk.org/> + + FLTK - Fast Light Tool Kit for Unix (and Windows and soon Mac). + +------------------------------------------------------------------------ +* Matthias Ulrich Neeracher + <http://www.sourceforge.net/projects/gusi> + <http://www.iis.ee.ethz.ch/~neeri/macintosh/gusi-qa.html> + + GUSI -- the Grand Unified Sockets Interface for Macintosh. + +------------------------------------------------------------------------ +* John C. Daub + + CURLPushButton, used in the Mac emulator's About Box. + +------------------------------------------------------------------------ +* Quinn "The Eskimo" and Peter N Lewis, et al + <ftp://ftp.interarchy.com/> + + Internet Config, the brains behind the hyperlinks in the Mac emulator's + stunning About Box. + +------------------------------------------------------------------------ +* Neil Rhodes + + Communications Toolbox support in Mac serial code. + +------------------------------------------------------------------------ +* Ron Marianetti + + Fixes and speedups to the TCP/debugger handling code. + +------------------------------------------------------------------------ +* Adam Dingle + + Conditional breakpoints. + Profiling output enhancements. + Display address of corruption in errors reporting corrupted heaps. + +------------------------------------------------------------------------ +* Jean-loup Gailly + <http://www.gzip.org/> + + gzip. + +------------------------------------------------------------------------ +* The Independent JPEG Group + <http://www.ijg.org/> + + JPEG decompression routines. + +------------------------------------------------------------------------ +* Jeff Prosise + + The CQuantize class for collecting palette colors from a 24-bit image. + + Algorithm from the August 1996 issue of Microsoft Systems Journal. + <http://msdn.microsoft.com/library/periodic/period96/msj/S3F1.htm> + + Source code from the October 1997 issue of Microsoft Systems Journal. + <http://msdn.microsoft.com/library/periodic/period97/wicked1097.htm> + +------------------------------------------------------------------------ +* Catherine White, Stuart Malone + <http://www.llamagraphics.com/> + + Profiling code clean-ups. + Many excellent bug reports and analyses. + +------------------------------------------------------------------------ +* Jerry Kirk, Michael Kedl + + QNX Neutrino port. + Added serial port emulation code. + Added additional keyboard support. + Fixed massive memory leak. + +------------------------------------------------------------------------ +* Jon Fo + + Solaris 2.6/7 modifications. + +------------------------------------------------------------------------ +* Frank Yellin + + Solaris 2.6/7 modifications. + Many bug fixes to the NetLib redirection code. + +------------------------------------------------------------------------ +* Akhil Arora, Sun Microsystems + + For the long-term loan of an Ultra 2 Sparc system for Solaris + development. + +------------------------------------------------------------------------ +* Stefan Hoffmeister + + Borland C++ Builder port. + +------------------------------------------------------------------------ +* The traitor formerly known as the intern known as Jerry Lin + + Boggle sample program. + Gremlins Hordes. + Palm OS Emulator Binder. + Assorted other fit-only-for-an-intern tasks. + +------------------------------------------------------------------------ +* The intern known as Toshi Clark + + Eights sample program (cut down version of the 15 puzzle). + IR redirection. + Session Info dialog. + Horde stats. + SuperVZ emulation. + Initial MediaQ emulation. + Gremlin step/resume bug fixes. + Support for new (unreleased) Palm device. + Unique profile output file names. + International Strict Checks. + Initial Gremlin Minimization implementation. + +------------------------------------------------------------------------ +* Red Dutta + + "Export Database..." menu item. + +------------------------------------------------------------------------ +* Ben Darnell + + Debian port. + +------------------------------------------------------------------------ +* John Ludwig + + FreeBSD port. + +------------------------------------------------------------------------ +* Easy Software + <http://www.easysw.com/~mike/espws/> + + FLTK Widget Set. + +------------------------------------------------------------------------ +* Scott Gruby + <http://www.gruby.org/> + + Carbon port. + +------------------------------------------------------------------------ +* Alexandre Parenteau + <http://www.cvsgui.org/> + + Carbonized GUSI 2.1.5. + +------------------------------------------------------------------------ +* Anthony Fishbeck + <http://www.pocketpyro.com/> + + Design of plug-in architecture, and re-implementation of the + Emulator's system function patch system to make use of it. + +------------------------------------------------------------------------ +* Cooperative Computers, Inc. (Stuart Eichert, Justin Clark) + <http://www.coopcomp.com/> + + Gremlin Minimization enhancements. + +------------------------------------------------------------------------ +And thanks to the many users of the Palm OS Emulator who have made +suggestions on how to make it even better! diff --git a/Docs/_GPL.txt b/Docs/_GPL.txt new file mode 100644 index 0000000..32d0e60 --- /dev/null +++ b/Docs/_GPL.txt @@ -0,0 +1,340 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + <one line to give the program's name and a brief idea of what it does.> + Copyright (C) 19yy <name of author> + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) 19yy name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + <signature of Ty Coon>, 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/Docs/_News.txt b/Docs/_News.txt new file mode 100644 index 0000000..d478f8e --- /dev/null +++ b/Docs/_News.txt @@ -0,0 +1,71 @@ +======================================================================== +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.5 (2001-03-29) +---------------------------- +* Added m125, m130, m515, and i705 support. NOTE: at the time of + this writing, skins for these devices are not available. There is + no estimated date for when they will be available. + +* Enabled TRGpro and HandEra330 support for Mac. [Scott Gruby] + +* Allow access to the following UI data structures in support of + PalmOSGlue that comes with SDK 4.0 Update 1 (DR1): + + read/write access to ControlType.attr for CtlGlueNewSliderControl + and CtlGlueSetLeftAnchor + + read access to ListType.itemsText for LstGlueGetItemsText + + read access to TableType.numColumns for TblGlueGetColumnMasked + + read access to GraphicControlType.bitmapID and selectedBitmapID for + CtlGlueGetGraphics + +* Re-allow read/write access to the text returned by CtlGetLabel, + etc. It's OK to read the text, and we'll allow writing to the text + until we come up with a better API for altering it. [many] + +* Fixed HostImportFileWithID to return a non-zero ID. [Scott Johnson] + +* Fixed timeout calculations when using redirected send/recieve + calls. [many] + +* (Windows) Poser 3.4 de-asserted DTR when opening the host serial + port. Poser 3.5 reverts this change (DTR is asserted when the host + serial port is opened). [many] + +* Fixed problem with inability to set/change socket address/port in + serial port emulation redirection. [Mahendra Tailor] + +* (Mac) Better Mac OS X support (Quit menu item now respects + preferences regarding save-on-quit, and an idle Poser now gives more + time to other running processes). [Scott Gruby, Christopher Hunt] + +* (Unix) Fix the crawling dialogs (where dialogs appearing quickly in + succession march down the screen). [John Marshall] + +* When hostErrProfilingNotReady was added in Pose 3.1, it was done in + such a way as to change the value of hostErrUnknownError. Re-order + those two symbols so that hostErrUnknownError retains its original + value (at the expense of changing hostErrProfilingNotReady). [Scott + Johnson] diff --git a/Docs/_OldNews.txt b/Docs/_OldNews.txt new file mode 100644 index 0000000..3eca435 --- /dev/null +++ b/Docs/_OldNews.txt @@ -0,0 +1,6094 @@ +======================================================================== +News (latest changes) archive 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> +======================================================================== + + +Changes for 3.4 (2001-02-01) +---------------------------- +* Interim internal release dates: + 3.4a1 - 2001-10-18 + 3.4a2 - 2001-11-01 + 3.4a3 - 2001-11-09 + 3.4a4 - 2001-11-13 + 3.4a5 - 2001-11-15 + 3.4b1 - 2001-11-20 + 3.4b2 - 2001-11-27 + 3.4b3 - 2001-11-29 + 3.4b4 - 2001-12-03 + 3.4b5 - 2001-12-05 + 3.4b6 - 2001-12-06 + 3.4b7 - 2001-12-10 + 3.4b8 - 2001-12-18 + 3.4b9 - 2002-01-21 + + +# Documentation: I don't think it's ever been documented what Poser + means by "Error" and "Warning" (as listed in the Logging Options + dialog). Now, with the Error Handling dialog (see below), it's more + important to know what those mean. Errors and Warnings are very + similar. The only difference between them is that an Error is + generally fatal (the Continue button is disabled in the dialog box + displaying the message) and a Warning is not (the Continue button is + enabled). Examples of Errors are Address Errors, Divide By Zero + Errors, or calls to SysFatalAlert. Examples of Warnings are Low + Memory accesses, Direct Screen accesses, and Hardware Register + accesses. Since Warnings are not fatal, they can generally be + turned off at the developer's option in the Debugging Options + dialog. + +* Documentation: The release notes for 2.1d16 refer to the "Autoload" + facility being added, but it doesn't describe the Autoload facility. + What it means is that you can create a directory in the same + directory as the Poser executable called Autoload. All installable + files in this directory (.prcs, .pdbs, and .pqas) will be installed + any time a new session is created or old session is loaded. + + This facility is superceded on Windows and Unix by the -load_apps + command line option. + +* Added support for cross-platform modeless dialogs. Not only does + this finally enable the Gremlin Control Window on Unix, but it paves + the way for enabling other features (such as importing files via the + Exchange Manager, which needs the progress window to be modeless). + +* Added Memory Leak detection, controlled by a new option in the + Debugging Options dialog. On SysAppExit, the Emulator looks for + memory leaks (much in the same way Palm OS 3.5 and later do). If it + finds any, it writes information about the leaks (including memory + location, memory contents, and a stack crawl of the context that + allocated the leaked block) to a log file. In either case, the Palm + OS-generated "you have leaks" dialog is suppressed. + +* Added Overlay Errors to the Debugging Options dialog. This option + controls a facility of the Overlay Manager in Debug ROMs. When + enabled, it sets the omFtrShowErrorsFlag bit of the omFtrCreator + Feature. When this bit is set, the Overlay Manager reports errors + with overlay databases that it can't validate (name of the overlay, + plus the reason why it didn't validate properly). + +* When a Gremlin is running, all generated events are now saved to a + Palm Event (.pev) file. This event file contains a snapshot of the + initial session state along with a list of all the events that + Gremlins generated. The event file can be used for event playback + or event minimization (see below). + +* Added a Replay menu item that re-opens a Palm Event file and + replays all the events recorded in it. This is handy if the events + in the file lead to an error condition you'd like to create. It is + similar to running the same Gremlin on the same application over + again, except that instead of regenerating the same random events to + post to the application, the events are read from a file. + +* Added Minimization menu item. This feature also re-opens a Palm + Event file and replays the events in it. Additionally, it goes + through an iterative process of removing ranges of events and seeing + if the resulting subset of events still leads to a crash. If a + crash still occurs, then those events are permanetly removed from + the set of events and another range of events is similarly tested. + If a crash does NOT occur, then the removed events are put back and + again the iterative process tries again by removing another range of + events. The end result is a minimal set of events that reproduce a + crash. This set of events is saved to a new Palm Event file + (suitable for execution using the Replay menu item). As a final + step, the set of events is translated into a sequence of English + instructions suitable for a human to follow. + + The amount of time it takes to complete the minimization process can + vary wildly, depending on the speed of your application, how many of + the events in the initial set are required in the final set, where + those events are located in the initial set, etc. In the lab, one + particular 265 event set minimized to 9 events in 50 seconds, and a + 1200 event set minimized to 18 in 11 1/2 minutes. I've heard + reports that starting with an initial set of 2000 to 3000 events + takes a couple of hours. + + See _Bugs.txt for comments on the English output. + +* Added -minimize command-line option. This option takes a path to + a .pev file with an event set to minimize. After the minimization + has completed, the files are written out as normal and the + emulator exits. + +* Cleaned up methods for specifying how serial, IR, and and NetLib + data are redirected. + +* Support setting Trap break from PalmDebugger when executing 'atb + A###'. Poser had a bug leading it to support only 'atb + "FredFunction"' + +* Further restricted direct access to data structures. Poser allows + NO access if the OS supports an "accessor" function that provides + access to the remaining fields Palm wants to support. + +* Allow read access to "attr" fields of Control, List, Bitmap, Label, + and Scrollbar objects if the "accessor" function is not available -- + FrmGlueGetObjectUsable accesses those fields. FrmGlueGetObjectUsable + also accesses Gadget and Table objects, but Poser already allows + read access to "attr" for those objects. [Catherine White] + +* Cleaned up New Session dialog behavior in the face of missing or + unusable ROM files. + +* Converted dates in _OldNews.txt to John Marshall-approved ISO 8601 + format. + +* (Mac) Fixed bug leading to crash while displaying the "invalid ROM + checksum" error message. + +* Better UART support: all FIFO interrupts supported, all FIFO sizes + correct. + +* Tweaks to configure.in to better find GL and FLTK libraries. Look + in $ac_x_libraries when searching for GL libraries, and look in + $ac_x_libraries (instead of $x_libraries) and GLLIB when looking for + FLTK and making sure it has fl_height(). [wart@kobold.org] + +* (Unix) Additional gcc 3.0 compatibility. [John Marshall] + +* (Unix) Work around gcc 2.95.x and 2.96.x bugs, where they had + problems compiling an inline function taking a parameter with a + default value that involved calling a virtual function. [John + Marshall] + +* Removed uses of ## operator with a token only on the right-hand + side. This usage is unnecessary and its effect is undefined. [John + Marshall] + +* (Mac) Updated to CodeWarrior 7. + + * Updated projects. + + * Added LTimerTask.cp and LTimerTaskFunctor.cp to PowerPlant + project. + + * Added CarbonFrameworkLib to Poser targets. + + * Removed CustomTextColorCDEF.cp from PowerPlant project. + + * Removed LAMTabsControlImp.cp from PowerPlant project. Register + LAMControlImp instead of LAMTabsControlImp. + + * Because LTableView has fixed its problems with setting its + background to white, removed custom CWhiteTextColumn class, + reverting back to using LTextColumn. Also Removed + LColorEraseAttachments from ppobs. + + * Because LAMControlImp now supports > 255 characters, removed + LFixedAMStaticTextImp. + + * Because LDialogBox now handles default buttons better, removed + LFixedDialogBox. Instead, use custom LNotifierDialogBox so that + we can catch when the dialog box is being closed and notify our + dialog handling routines. + + * Undeffed EAGAIN and EDEADLK in GUSI's errno.h (defined in + <cerrno>) so that it can get redefined in GUSI's sys/errno.h. + + * In GUSI's inttypes.h, include stdint.h instead of defining the + C99 standard integer types itself. + + * In GUSI's in.h, comment out IP_OPTIONS...IP_RCVIFADDR, since + they're now also defined in OpenTransportProviders.h + + * In GUSI's fcntl.h, make fdopen() match that in MSL's stdio.h + (actually stdio.posix.h) again. + + * Added back S64Mod macro removed from <Math64.h>, needed in + GUSITimer.cp. + + * In GUSIOTNetDB.cp, don't #undef AF_INET. The idea in this file + was to undef it before including <OpenTptInternet.h>, which + defines it again. However, before undeffing that symbol, + GUSIOTNetDB.cp includes, which includes GUSIOTNetDB.h, which + includes GUSIOpenTransport.h, which includes + <OpenTptInternet.h>. Which means that <OpenTptInternet.h> + defines AF_INET before GUSIOTNetDB has a chance to undef it. + They both evaluate to 2 anyway, so duplicate #defines are OK. + + * Added PP_Suppress_Notes_22 to prefix files. + + * Specify LCleanupTask_Terminator as CFM Termination function. + + * CURLPushButton::AdjustCursorSelf -> AdjustMouseSelf. + + * Re-added definition of CRMRec, which is now surrounded by a + CALL_NOT_IN_CARBON flag in <CommResources.h>. + + * Re-added definitions of crmSerialDevice and CRMSerialRecord, + which are now surrounded by a CALL_NOT_IN_CARBON flag in + <CRMSerialDevices.h>. + + * Changed EmAddressBank::check to checkaddr; <Debugging.h> now + defines "check". + + * Renamed some private functions in HostControl.cpp so that they + no longer started with "__" (thus conflicting with some system + functions now defined in MSL). + + * NewPPCCompProc -> NewPPCCompUPP. The former used to be a macro + in PPCToolbox.h that was defined to the latter. It's now + surrounded by a CALL_NOT_IN_CARBON, so we call NewPPCCompUPP + directly, which is defined in EmClassic.cpp. + + * ampCmd -> volumeCmd; freqDurationCmd -> rateMultiplierCmd; + squareWaveSynth -> ? (zero, for now). + + * Got rid of EmCustomWindow, making use of the new facilities for + creating an LWindow from an existing Mac window. + +* (Windows) Change the way Poser remembers and resets its location + when changing skins. Poser can be embedded in another application + (such as an IDE), and needs to be cognizant that its location is not + necessarily in screen coordinates. [Christian Falch] + +* (Unix) Added support for --enable-static-link (forces static + linking with libraries -- no shared libraries). [Harry Dolan] + +* Added preferences for controlling skin appearance (dimming when + inactive, red when in debug mode, green when in Gremlin mode). + +* Fixed some places where error codes caused by file operations got + mangled before they could be used to generate error messages. [John + Marshall] + +* (Unix) Protect against the window trying to fit itself to the size + of a skin when their's no skin being used. [John Marshall] + +* Fixed byteswapping bug in NetLibGetServByName when running on a + Little Endian platform and NetLib Redirection is on -- the returned + port would be byteswapped. [Maurizio Moretti] + +* Re-allow calls to the following functions (previously proscribed in + 3.3): SysReserved10Trap1, SysReserved30Trap1, SysReserved30Trap2, + SysReserved31Trap1, OEMDispatch, OEMDispatch2. It's possible for + OEMs to have implemented these traps, or for some version of the OS + or extension to have implemented them, in ways that Poser doesn't + know about. So allow access to them. If they are in fact not + implemented, then Poser's "you just called an unimplemented trap" + mechanism will kick in. SysReserved40Trap1, SysReserved40Trap2, + SysReserved40Trap3, and SysReserved40Trap4 should also be given the + same treatment, but they weren't on the proscribed list in the first + place. + +* The following functions are now also officially allowed: + IntlGetRoutineAddress, SerPrimeWakeupHandler, SerReceiveWindowClose, + SerReceiveWindowOpen, SerSetWakeupHandler, SrmOpenBackground, + SrmPrimeWakeupHandler, SrmReceiveWindowClose, SrmReceiveWindowOpen, + SrmSetWakeupHandler, SysNotifyBroadcast, SyNotifyBroadcastDeferred. + +* (Unix) Protect against Poser hanging when performing a "paste the + host selection to the Palm OS's clipboard" operation and there is no + host selection. [John Marshall] + +* Expanded on the ContinueOnWarnings and ExitOnErrors preferences + from Poser 3.3. These have now been replace with the preferences + WarningOn, WarningOff, ErrorOn, ErrorOff. These control what + happens with Warnings and Errors with Gremlins On and Off. Each + preference can be set to one of ShowDialog (which will show the + message in the familiar error dialog with the Continue, Debug, and + Reset buttons), Continue (which will make Poser act as if the user + had seen the dialog and pressed the Continue button, but will not + actually show the dialog), Quit (which will cause Poser to quit with + an error code of 1 if an error occurred or an error code of 2 if a + warning occurred), or NextGremlin (which will cause Poser to no + longer generate events for the current Gremlin and switch to the + next Gremlin in a Horde). Note that these actions take place ONLY + if logging is enabled for warnings and errors. If logging is not + enabled, then Poser enable them for you (asking you first if it's OK + to do so). + +* Added a new preferences dialog to support the setting of the + WarningOn, WarningOff, ErrorOn, and ErrorOff preferences. + +* ContinueOnWarnings and ExitOnErrors can no longer be set from the + UI, and their settings will not be saved to the preferences file. + However, they CAN be set from the Windows command line or via the + HostSetPreference function, and Poser will heed them. SilentRunning + was never setable from the UI, but its handling is also the same as + the ContinueOnWarnings and ExitOnErrors preferences (you can set it + via the command line or HostControl, and Poser will heed it). + +* Fixed crasher that could occur if the list of Palm applications in + the preferences used to limit what applications a Gremlin could run + included an application that no longer existed on the device. [John + Marshall] + +* Added DmNextOpenDatabase and DmOpenDatabaseInfo Perl wrappers. + Added ListOpenDatabases.pl. Added "#!/usr/bin/perl -w" to + FormSpy.pl, PoserRPC.pl, and SkipStartup.pl and made them executable + types. Fixed up warnings to due adding -w. Updated SkipStartup.pl + to skip the language selection form on EFIGS ROMs. [John Marshall] + +* (Internal) Massive rewrite of application model, document model, + and window model code. Created EmAction and EmActionHandler + classes, supporting the manipulation of actions/commands as objects, + thus allowing them to be queued up and/or deferred. These changes + allow for much sharing of cross-platform code, bring to parity many + features (such as command line options on Unix and Mac OS X). + +* Implied by the above, command line options are now supported on + Unix. They are not supported on the Mac as (a) Mac OS 9 doesn't + have a way to specify command line options, and (b) Mac OS X won't + launch Poser from the command line in a terminal. + +* Fixed problem that could lead to Poser hanging. Poser would from + time to time need to suspend emulation at a very safe, stable spot + in order to carry out some of its operations. This spot was when + EvtGetEvent was called and there were no pending events. However, + it was possible that an emulated process would be wedged or in an + infinite loop and wasn't calling EvtGetEvent. Poser would hang in + the process of waiting for that infinite loop to end. There was + another problem similar to this involving background processes, but + it's too complicated to get into here. Suffice to say that both + problems were solved by using a mechanism different from having + Poser wait for EvtGetEvent. [Vitaly Kruglikov, James Phillips, and + possibly some other engineers from Handspring] + +* (Mac) Added check for minimal Carbon version number. If Carbon is + not at least version 1.2.5, display an error message and exit. + +* (Mac) Added a top-level exception handler that displays a "Fatal + Internal Error" message and quits. + +* (Unix) Enabled most HandEra 330 support (code in + EmTRGDiskIO::GetFilePath is still not enabled). [Michael Glickman] + +* Added HostImportFileWithID. This is the same as HostImportFile, + but it returns the LocalID of the installed database. [Ben Combee] + +* Changed any references from "Cards" to "HostFS". The Card Options + dialog never did anything with emulating SD or any other sorts of + cards. It just allowed you to enter parameters for the HostFS + extension. Having it say "Cards" just confused people who expected + that the options specified there would have some effect on the Card + Info application in the Palm OS. + +* (Windows) Sped up startup time by assuming that the only files in + the Skins directory that can contain link information are those + ending in .lnk. + +* Recognize databases of type 'htal' as containing system code, and + don't complain if they do system-like things. This will allow + Network HotSync (when NetSync.prc is installed in RAM) to work + again. + +* Automatically create directories specified in command line options + as containers for Poser-generated files (such as Gremlin and logging + output) if they don't already exist. + +* Allow multiple file selection in the Install Application/Database + dialog. [Michael Nordstrom] + +* The directory created by Gremlins to hold the files it also creates + is now named with the current date/time instead of the number of + milliseconds since the host system was booted. + +* Bound Posers not longer care if the Skins directory exists. [Kelly + Maher] + +* Fixed bug in NetLibGetHostByName when NetLib Redirection is turned + on: attempting to return netDNSMaxAddresses addresses would result + in memory after "addressList" to get NULLed (that is, the first + element of the "address" array). The solution is to do the same + this as NetLib, which is to only return netDNSMaxAddresses-1 + address pointers. Note that Poser still differs from the on-device + NetLib, in that it will return only first netDNSMaxAddresses-1 + addresses in addition to the pointers to them, while the on-device + NetLib will return netDNSMaxAddresses addresses (with no pointer + to the last one). + +* Fixed bug with restarting a Gremlin from an intermediate Gremlin + state file (Gremlin_XXX_Event_XXXXXXXX.psf). Poser would silently + reset when the newly started Gremlin would attempt to generate an + event to switch to another application. [Rick Wagner] + +* Fixed bug where running a Gremlin Horde would not switch to the + next Gremlin when an error occurred. + +* Emulate DragonballVZ requirement for having the entire LCD frame + buffer in a 128K segment. [Scott Johnson] + + +Changes for 3.3 (2001-08-27) +---------------------------- +* Interim internal release dates: + 3.3a1 - 2001-06-15 + 3.3a2 - 2001-06-18 + 3.3a3 - 2001-07-10 + 3.3a4 - 2001-07-12 + 3.3a5 - 2001-07-13 + 3.3a6 - 2001-07-27 + 3.3b1 - 2001-08-02 + 3.3b2 - 2001-08-07 + 3.3b3 - 2001-08-13 + 3.3b4 - 2001-08-14 + 3.3b5 - 2001-08-20 + 3.3b6 - 2001-08-22 + +* 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 + + +Changes for 3.2 (2001-06-03) +---------------------------- +* Interim internal release dates: + 3.2a1 - 2001-03-30 + 3.2b1 - 2001-05-06 + 3.2b2 - 2001-05-14 + 3.2b3 - 2001-05-29 + +* (Unix) Support psf, ram, rom, device, load_apps, and run_app + command line options. [David A. Jablonski] + +* Rewrote LCD-handling code to share a lot of cross-platform code. + The major user visible effect of this is that the Unix version now + has the white 2-pixel border around it when emulating a device with + an SED 1375 or 1376 display, and that the updating on Unix will be + faster (especially over a network). + +* Rewrote a lot of the EmDevice routines in order to be more table- + driven. Also added ability to configure the CPU object created, and + the minimum RAM size that can be configured. + +* Added Visor Edge support. [James Phillips] + +* Rewrote the menu-handling code to share a lot of cross-platform + code. Along the way, cleaned up some host-specific aspects of menu + handling. Over all: + + * Mac + + o Now has a popup menu that looks like the Windows version + (use Ctrl-click to display it). + + * Unix + + o The popup menu on Unix now is laid out the same way as the + Windows version. This includes finally having the MRU menus + for recent sessions and installable files. + + o Can press Shift-F10 to display the popup menu. + + * Windows + + o Menu items now have Alt shortcut keys. I would have used + the more-standard Ctrl, but that's currently used for + entering commands into the emulated environment. I would + have used the less-standard Ctrl+Shift, but felt that + requiring three fingers for a shortcut command was + excessive. + + o The menu is popped-up in response to a WM_CONTEXTMENU + message now instead of manually looking for F10 presses and + right button clicks. This means that (a) the menu is popped + up at the *end* of a right-button click instead of the + beginning, (b) you need to use Shift-F10 instead of just F10 + to popup the menu item, and (c) you can also use the "menu" + key on some PC keyboards (the "VK_APPS" key). + + * All + + o Paves the way for dynamically updating menus for different + circumstances (for instance, if emulating a particular + device requires a menu special for it, that can be added). + + o Hmmm...HostAddMenuCommand, anyone? :-) + +* Sped up the checking for direct access to UI Mgr data structures. + The overhead for this option should now be imperceptible. + +* Allow read/write access to font fields in ControlType, ListType, + and FormLabelType. [Many] + +* Allow read access to FormType::menuRscId field. [Markus Schmid] + +* Allow complete access to gadgets (since gadget callback functions + are given just a pointer to the gadget, but not the Form through + which they could make access calls). [Ben Combee] + +* Allow read/write access to "attr" for FormBitmapType before Palm OS + 3.2 -- FrmHideObject didn't change the usable bit before then. + [Steve Achelis] + +* Fix access to WindowType::frame field. This was allowed, but a bug + in the calculation of the field's offset invalidated the access. + [Stephen Best] + +* For Poser 3.1, access to WindowType fields displayWidthV20, + displayHeightV20, displayAddrV20, and bitmapP was documented as + "read only". This is now enforced; write access is no longer + allowed. + +* For Poser 3.1, access to the FieldType field attr was documented as + "read/write" before Palm OS 3.3. This is now enforced. + +* Allow access to WindowType fields even when the WindowType is part + of a FormType. It used to be that you could not access those fields + if the windowFlags.dialog bit was set. + +* Fixed bug where Poser itself would cause an access violation to + parts of a FormType when preparing the error message for a user + access violation to the FormType. + +* Poser used to read and cache the size of the system function + dispatch table. However, some versions of Palm OS now resize the + table, thus invalidating Poser's cached size value. The result is + that Poser would sometimes report that system functions are not + implemented when they really are. [Mike McCollister] + +* Squelch display of message saying that someone called DbgMessage + ("c") and DbgMessage ("Transaction finished"). [Catherine White, + Andreas Linke, Mark Peters] + +* (Mac) Carbonized. [Scott Gruby] + +* Be more robust in HostControl calls that take printf-style var-args + parameters. + +* Fix potential bug in code that tries to find the beginning of a + function given an address in that function. [Adam Liss] + +* Support Soft, Hard, Debug, and No Extension resets. The Reset menu + item now brings up a dialog allowing you to set various + reset-related options. The "Reset" button in the "Continue / Debug + / Reset" dialog is now "Reset...", and brings up the same dialog. By + default, the settings are set to a Soft Reset with Extensions. + +* Fixed problem where device could get into a "flashing" state while + running Gremlins, where the device is continually turning on and + off. [Stephen Best] + +* Added 4 more slots in Card Options dialog. + +* If the user brings up the Card Options dialog, Poser checks for the + existance of the HostFS shared library when exitting the dialog. If + the library is not installed, Poser displays a message dialog + suggesting that the user download and install it. + +* Make sure the user can't accidentally attempt to install a HotSync + User Name from the preferences dialog that's too long. [Steve + Achelis] + +* (Unix) Extended "Choose File" dialog to support the choosing of + directories. This "Choose Directory" dialog is used when clicking + on the "Browse" button in the "Card Options" dialog. Navigate via + the file/directory name list, or type the path into the edit box. + You can use TAB for name completion, '/' to indicate that you want + to enter the directory currently entered in the edit box, and RETURN + (or click on the OK button) to select the directory in the edit box. + +* (Unix) Implemented clipboard support. This support has uses in two + areas: copying the text from error message boxes (see the next + item), and clipboard interchange. Clipboard interchange is where + the Palm OS clipboard is kept in sync with the host clipboard. On + Unix, this is tricky because of the paradigm Unix uses for the + clipboard. But, in short, to copy from the Palm OS to a Unix + application, select the text in the Palm OS application, select the + Copy menu item in the Palm OS application, go to the Unix + application, and middle-click to paste the selection. To copy from + a Unix application to a Palm OS application, select the text in the + Unix application, go to the Palm OS application, set the insertion + point, and select the Paste menu item. + +* (Unix) The error dialog that reports runtime errors in Palm OS + applications (e.g., "Bus error", "Low-memory accessed", etc.) now + displays the text in a selectable pane. That is, the user can + select the text with the mouse. Once this is done, it acts like a + selection in any other Unix program, and can be pasted by + middle-clicking in the target Unix application. + +* (Unix) All dialogs are now centered on the main screen. + +* Show applications in the "New Gremlin" dialog even if they have the + dmHdrAttrHidden bit set. [Scott Johnson] + +* Fixed problem with profiling where any system function that Poser + completely implemented (including all HostControl functions) would + cause the profiling system to push a record onto an internal stack + but not pop it off later, leading to an internal stack overflow. + +* Using a debugger to single-step over a line of source code that + performed a "soft" invalid memory access (that is, one that is + proscribed by convention, and not, say, one that causes an address + error) would queue up the error and not show it until regular + execution was resumed. [Adam Dingle] + +* Support -horde_save_dir. This option has been around for a couple + of years, but never did anything. It now works as documented. Use + it to specify the location for "GremlinStates_*" directories. This + parent directory must already exist. If the directory does not + exist or is not specified, the "GremlinStates_*" directories will be + created in the Emulator directory as before. + +* When resetting a session or creating a new one, reset the Gremlin + state so that the Suspend and Resume menu items are no longer + enabled. + + +Changes for 3.1 (2001-03-16) +---------------------------- +* Interim internal release dates: + 3.0a9e1 - 2001-01-07 + 3.0a9e2 - 2001-01-09 + 3.0a9e3 - 2001-01-17 + 3.0a9e4 - 2001-01-23 + 3.0a9e5 - 2001-01-24 + 3.0a9e6 - 2001-02-07 + 3.0a9e7 - 2001-02-19 + 3.1b1 - 2001-02-22 + 3.1b2 - 2001-02-27 + 3.1b3 - 2001-02-28 + 3.1b4 - 2001-03-02 + 3.1b5 - 2001-03-08 + 3.1b6 - 2001-03-08 + 3.1b7 - 2001-03-14 + 3.1b8 - 2001-03-15 + +* Changed Skin file searching rules. Now, when starting up, Poser + looks for a directory called "Skins". On Mac and Windows, it looks + for this directory in the same directory as Poser itself. On Unix, + it looks in $POSER_DIR, $HOME, /usr/local/share/pose, and + /usr/share/pose, stopping at the first one that has a directory + named "Skins" or "skins". Once a Skins directory has been found, + that directory is recursively searched for *.skin files. + + Because the rule change may confuse users, Poser displays a warning + message on startup if it can't find a "Skins" directory. This + warning is displayed only once, so as to not disturb developers + who don't care a whole lot about skins. + +* If the Skins directory could not be found, display an error message + at startup. This will tell users that they either need to rename + their skins directory to "Skins", or to download the skins archive + from the Poser Web page. + +* Allow the setting of breakpoints in the prologue code of Palm OS + Manager's that are sub-dispatched. That is, the managers that take a + selector number and then use a secondary dispatch table to further + dispatch to the final function. Poser would originally skip over + this prologue code and jump directly to the final function + destination. However, one could not set breakpoints on the prologue + code and have them trigger in that case. Now if any breakpoint is + installed, Poser jumps to the prologue code. Otherwise, it jumps to + the final function address like it used to. This modification allows + people to use the 's' command in PalmDebugger to Step into Palm OS + functions that are sub-dispatched. + +* (Mac) Updated to CodeWarrior Pro 6. + +* (Mac) Updated to GUSI 2.13 (needed under CWP6). + +* (Mac) Worked around problem in PowerPlant 2.1 that caused the + highlighting to not always work in text lists in dialogs like the + New Gremlin dialog. + +* Recalibrated the Palm OS tick-counter to my 500MHz PC. The tick + counter now runs 3 times slower than before, resulting in 97 ticks + per second as opposed to the 297 ticks per second I was seeing + before. The upshot of all this is that repeating tasks (like + scrolling and holding down the hard buttons) don't zoom by as + quickly as before. + +* Cleaned up the handling of Poser-detected errors and their + messages. Before now, if you got an error message for a "soft" error + (that is, one that is not a hardware exception), Poser would display + a dialog box containing Continue, Debug, and Reset buttons. If you + clicked on Debug and there were no debugger, it would be the same as + clicking on Continue. Now, Poser will merely redisplay the same + dialog until you click on a different button or a debugger can be + found. + +* Switched to native "long long" operations in Profiling.cpp (this + issue was finally forced because someone forgot S64Compare in CWP6). + +* Adjusted the calculated heights for cells in LTextColumnView in + order to account for the 2 pixel inset LTextColumnView::DrawCell + uses. Ken noticed that descenders were getting chopped off. + +* Fixed problem in Hordes where specifying a switch depth but not + specifying a maximum depth (that is, not checking the third check + box in the dialog) would cause the Hordes mechanism to not actually + switch between different Gremlin numbers. + +* Implemented support for the timeout values passed to NetLibReceive + and NetLibSend. Previously, these values were ignored, leading to + hangs or overly-long timeouts on the desktop that wouldn't appear on + the device. [Hiroyuki Okamoto] + +* Fixed problems where entering a debugger could cause Poser to + complain that the PC is being set to an invalid value (mostly seen + when executing "att" in PalmDebugger). Fixing this problem also had + the benefit of speeding up emulation by 6%. + +* Would you believe that changing the following in the core emulation + loop from: + + uint16 opcode; + opcode = get_iword (0); + fCycleCount += (cpufunctbl[opcode]) (opcode); + + to: + + uint32 opcode; + opcode = get_iword (0); + fCycleCount += (cpufunctbl[opcode]) (opcode); + + sped up emulation by 4%? + +* Poser was relying on a lot of UAE types and routines for basic + facilities. For instance, Poser had standardized on uae_u8, uae_u16, + etc., for basic integral types, and get_byte, get_word, put_byte, + etc., for basic memory emulation. However, all of those are + UAE-specific. When implementing ARM support, those facilities may + not be available. Therefore, move those basic types and facilities + into Poser, give them Poser-ish names, and recast UAE to use those + genericized facilities. + +* When the SED1376 LCD is turned off, emulate the fact that the bus + to it is disabled. While disabled, any access to the SED registers + or VRAM will cause a bus error. + +* Add support for the interrupts caused by the additional sources on + the DragonBall VZ (UART2, TMR2, PWM2, etc.), and support the + configurable interrupt levels for those sources. + +* Keep the Palm OS clipbard in sync with the host platform's + clipboard. After a Palm OS application calls ClipboardAddItem or + ClipboardAppendItem, the Palm OS clipboard is copied to the host + clipboard. Before calls to ClipboardGetItem, the host clipboard is + copied to the Palm OS clipboard. Note that this synchronization is + not performed if a Gremlin is running so that any data on the host + clipboard doesn't alter the Gremlin outcome. + + With this change, it should be fairly painless to exchange data + between the emulated Palm device and the host computer. To copy data + into the emulated device: + + * Copy the text data with Ctrl-C (or as appropriate on Mac or Unix) + * Switch to the emulated device + * Make sure you have a field active that can accept text data + * Press Ctrl-C, then P. Ctrl-C enters the "/" stroke to invoke + the "Command" mode, and "P" invokes the Paste command. + + To copy data from the emulated device to the host: + + * Select the text on the emulated device + * Press Ctrl-C, then C to copy the data. + * Switch to the host computer application to receive the text + * Press Ctrl-V (or as appropriate on Mac or Unix). + + Note that data copied to the Palm's clipboard is silently truncated + to cbdMaxTextLength characters if necessary. + +* Fixed problem where some stack overflows weren't being detected. On + a LINK instruction, when the stack pointer is decremented to hold + the old A6 value, we check the stack. However, when the stack is + decremented again by the value specified by the LINK statement, that + wasn't being checked. + +* Completely rewrote the error messages generated when an emulated + application causes (either directly or indirectly) an error. This + includes both hardware exceptions (bus error, address error, divide + by zero, etc.) and emulator-detected errors (write to low-memory, + write to screen buffer, stack overflow, etc.). The new messages are + intended to be more useful (more detailed information) and clearer + (more explanatory text). + +* Added new error message to explain cases where it looks like an + invalid DrawWindow is being used. On Debug 3.5 ROMs, when there is + no valid DrawWindow, the Palm OS sets the value of the stored + DrawWindow to 0x80000000. This value causes a bus error. Poser + detects this kind of bus error and puts up a message saying what it + really thinks is going on. + +* Added new error message saying that the application is attempting + to write to the storage heap. Previously, the user would just see a + "bus error" message. + +* Previously when reporting a hardware exception, Poser would attempt + to contact a debugger before displaying an error message. Now Poser + displays an error message first. This mirrors the way other error + messages are handled. The exceptions to this rule are with Trace, + TRAP 0, and TRAP 8 exceptions. Those will still attempt to silently + enter the debugger first. If no debugger is connected, *then* an + error dialog is posted. + +* Poser used to report certain errors only once per application run. + The intention was to not pelt users constantly when running an + application that, say, draws directly to the screen. In an effort to + get more applications to be more compliant, this one-time-only + feature has been removed. If you need to turn off those error + messages, you can still use the Debug Options dialog. + +* After the previously-mentioned changed, an "it's always been there" + bug cropped up. After reporting a warning like "Application just + read from low-memory", the developer could click on the Debug button + and break into an external debugger. From the debugger, they could + examine the error, and then optionally continue the application's + execution. However, doing so would re-execute the instruction that + caused the error. We never saw this before because of Poser's + feature of reporting such errors only once per application run. But + with that feature removed, the application keeps breaking at the + same place. Even with the feature in place, there could be problems + if the instruction were some sort of pre/post-increment/decrement + instruction. The first time it was executed, the affected base + register would get modified. And it would get modified again the + second time it was executed, even if no error were reported. Anyway, + that's all fixed now. Now Poser waits for the instruction to + completely execute before reporting an error so that the PC is + properly incremented and the instruction doesn't get executed twice. + The only negative side effect of this change is that the PC will now + always point to the instruction *after* the one causing the error. + Most of the time, this will be confusing only if you're debugging at + the assembly level instead of the source level. However, if the + opcode executed was last opcode of a source-level statement, the + source line indicated by the debugger could be the one *after* + causing the error. + +* The last part of that last paragraph bears repeating: errors are + now flagged *after* the instruction causing it has finished, rather + than in the middle of the instruction. This means that the PC + reported to the debugger will be pointing to the *next* opcode. You + may need to mentally adjust for this difference in the debugger. + That is, you may need to look at the previous instruction or source + code line. + +* Poser keeps a list of Palm OS function names and error code names. + Updated this list for Palm OS 4.0. + +* Fixed some problems resuming a Gremlin from a saved file when no + upper event bound has been selected. [Catherine White, + Llamagraphics, Inc.] + +* (Windows) Work around the fact that connect may return WSAEINVAL or + WSAEWOULDBLOCK when it really means WSAEALREADY. [Mark Baysinger] + +* (Windows) Provide a default extension when asking to save a file. + [Mike McCollister] + +* (Windows) Fixed color problems when saving the LCD to a disk file + when it's in 16-bit mode. [Mike McCollister] + +* Added new command line option: -horde_quit_when_done. Specifying + this option on the command line will cause the emulator to exit + after completing a Horde. + +* Fixed problem with the Step Spy feature in PalmDebugger where + attempting to set a Step Spy address would cause Poser to raise an + invalid access error message. + +* Additional documentation: HostProfileInit takes two parameters: + maxCalls and maxDepth. These parameters determine the sizes of + arrays used to keep track of function calls and call depth. A + typical value for maxCalls is 65536, and for maxDepth is 200. In + future versions of Poser, the need for specifying these values may + be removed. + +* (Mac) Fixed application list in the New Horde dialog. There used to + be a feature whereby application names would be shown in Japanese if + running a Japanese ROM on a JLK-enabled Mac. Somewhere along the + way, this got broken. It should be fixed now. + +* (Mac) Messages strings used to be stored in a 'STRA' (string array) + resource. However, if an error occurred while handling a packet from + a debugger, Poser would be unable to access this resource when + forming an error message. This is because Poser would be operating + in the context of the debugger. Thus, the debugger's resources would + be available, but not Poser's. The result of this would be error + messages with the words "missing string #xxxx" in them. Now, the + strings are embedded in the application as string constants, the + same way as is done on Unix. + +* (Mac) Some messages would display missing character symbols (those + hollow boxes) instead of performing a linefeed/carriage return. + Fixed. + +* Corrected the spelling in some messages (ran the whole lot through + a spell checker, I did...). + +* Poser makes calls into ROM functions from time to time in order to + get information or perform some operation. Poser has known for a + long time to skip breakpoints in those functions when they're + executed in this fashion. Now Poser also skips DbgBreaks (TRAP 8s) + and Trap Breaks (from PalmDebugger's ATB command) as well. + +* (Mac) Translate high-ASCII characters when exchanging the Mac + clipboard with the Palm OS clipboard. + +* (Mac) Fixed problem where certain high-ASCII characters (CENT SIGN, + POUND SIGN, COPYRIGHT SIGN, PLUS-MINUS-SIGN, and MICRO SIGN) weren't + getting translated correctly into the PalmLatin code page. + +* Added checks for accesses to form, form object, and window data + structures from applications. In general, all access is prohibited. + The following exceptions are allowed: + + ======================= =========== ========================== + struct/field access type When direct access allowed + ======================= =========== ========================== + + WindowType + displayWidthV20 read only before Palm OS 2.0 + displayHeightV20 read only before Palm OS 2.0 + displayAddrV20 read only before Palm OS 3.5 + bitmapP read only before Palm OS 3.5 + frameType read/write always + + FormType + handler read only always + helpRscID read/write always + defaultButton read/write always + + FieldType + lines read only if AccessorDispatch not present + attr read/write before Palm OS 3.3 + + ControlType + attr read only if AccessorDispatch not present + style read only if AccessorDispatch not present + + ListType + attr read/write always + topItem read only before Palm OS 4.0 + + TableType + numRows read only before Palm OS 4.0 + numColumns read only before Palm OS 4.0 + topRow read only before Palm OS 4.0 + rowAttrs read only always + columnAttrs read only always + items real only always + attr read/write always + currentRow read/write before Palm OS 4.0 + currentColumn read/write before Palm OS 4.0 + + FormBitmapType + attr read only if AccessorDispatch not present + + FormLabelType + attr read only if AccessorDispatch not present + + FormGadgetType + attr read only if AccessorDispatch not present + attr read/write before Palm OS 3.5 + + ScrollBarType + attr read only if AccessorDispatch not present + attr read/write before Palm OS 3.5 + + WARNING: use of this option may dramatically slow down your + application's performance. You may want to make use of this + feature on a limited basis until the next relesae of Poser, + which will speed things back up again. + +* Added check for accesses to the unused portion of the stack. + +* Removed unused checkboxes from Debug Options dialog, and added or + enabled checkboxes for the new features. + +* Calling DbgMessage when no debugger was around to receive the + message could crash Poser. Now, if no debugger is attached, the + message is displayed in a dialog box. + +* When presented with an error dialog box, you can press Cmd-C (Mac), + Alt-C (Unix), or Ctrl-C (Windows) to copy the error message to the + clipboard. Note that on Unix, the cursor needs to be over the error + dialog box in order for the keystroke to be sent to the dialog box. + +* Rewrote the Breakpoints dialog as a cross-platform dialog, thus + making it available on Mac and Unix as well. + +* When a StepSpy condition (as established by PalmDebugger or any + other debugger using the relevent fields of the Continue debugger + packet) is triggered, or a Watchpoint condition (as established by + the Breakpoints dialog) is triggered, display a dialog box + describing what just happened, much like what happens on other + memory access error dialogs. + +* In checking the stack pointer against the low end of the stack or + when checking for memory accesses between the low end of the stack + and the stack pointer, Poser needs to know where the low end of the + stack is. Previously, it would just assume that the entire Memory + Manager chunk containing the stack pointer was used for the stack + and so the start of the chunk was the low end of the the stack. This + assumption was incorrect for some applications (particularly + background applications in the Palm OS) that would allocate a memory + block for use as "instance data" that also included an embedded + array for use as a private stack. In order to account for those + applications, Poser now also monitors calls to SysTaskCreate, which + is passed a stack starting address and size as parameters. + +* (Unix) Mapped ESCAPE to most dialog Cancel buttons. + +* (Unix) Made clicking on the dialog's Close box in the title bar the + same as pressing ESCAPE. If a button with an ESCAPE shortcut could + not be found, then pretend the user clicked on the Cancel button. + +* Re-implemented the Export Database dialog as a cross-platform + dialog. Added code to check for .pqa databases and tack on ".pqa" + instead of ".pdb" when forming the default filename. + +* (Mac) Poser implements the LEventDispatcher::UpdateMenus method to + update the session and database MRU sub-menus. However, this method + is called all the time, and since building those menus can be time + consuming, UI responsiveness is impacted. Now Poser just rebuilds + those menus when the MRU lists actually change. The drawback to this + approach is that the sub-menus could be incorrect if the files they + correspond to are deleted from the file system. + +* Extended -horde_apps command line parameter to take an "exclusion + modifier". If the list of application names is preceded with a dash + (e.g., "-Prefs,HotSync"), then all applications are available to + Gremlins *except* those applications. + +* Loading a session file used to involved installing the HotSync User + Name that's specified in the Properties/Preferences dialog. That + direction is now reversed. When a session is loaded, the HotSync + User Name is extracted from the session and installed as the + emulator preference. This allows you to specify different users in + saved sessions and have those restored when you reload those + session, as opposed to all sessions -- new and reloaded -- having + the same user name. [Scott Maxwell] + +* Fixed long-standing bug where reloading session files created on + previous days did not get their system date updated. The time would + be correct, but the date would the the date on which the session was + created (or whatever was established by the last use of the Date + preference panel). [Scott Johnson, Paul Nevai] + +* Better hard key emulation. On an actual device, pressing a key on a + sleeping device would trigger an edge-sensitive INT[3:0] interrupt. + Normally, this by itself won't wake up a device. However, a KB + interrupt can also be generated, and this interrupt will wake up a + device. Poser, on the other hand, ignored the fact that + edge-sensitve INT[3:0] interrupts weren't supposed to wake the + device, and it also failed to support the KB interrupt. Thus, on a + device, pressing a key to wake up the device would succeed because + of the KB interrupt, while on Poser it would succeed because of + Poser's incorrectly waking the device on an edge-sensitive INT[3:0] + interrupt. In Palm OS 4.0, INT[3:0] interrupts are actually maked + off when the device is asleep, and so pressing keys to wake the + device would utterly fail. Poser now supports the KB interrupt, and + devices wake up again under Palm OS 4.0. + +* Added serial port -> TCP socket mapping. You can now redirect + emulated serial communications to a socket connected to another + application running on the same or different host computer. On Mac + and Windows, in the Properties/Preferences dialog, select the TCP + menu item. This will enable the Target edit text item, wherein you + can enter an IP address:port (e.g. localhost:7777). On Unix, there + is no menu item for selecting a serial port; there's just an edit + text item. Normally, you'd have something like /dev/ttyS0 there. But + you can replace this with an IP-looking address (e.g., + localhost:7777), and Poser will recognize the difference and act + accordingly. + + When opening the emulated Palm serial port, Poser will open a + corresponding socket. It will first try to connect to another socket + at the given address. If that fails, it will revert to "server" + mode, and listen for connections on the given port. + +* Re-implemented the Preferences/Properties and Tracer Options + dialogs as cross-platform dialogs. + +* Added HostSessionSave. + + HostBoolType HostSessionSave(const char* saveFileName); + + The session will be saved to a file with the given name. Regardless + of whether or not the save attempt succeeds, the function returns + false. When the session file is reloaded, execution resumes at the + point where HostSessionSave is returning. In this case, the function + returns true. This can be handy if have debugging code that can + detect an invalid condition, and you want your debugging harness to + save a session file for a later post-mortem. When you reload that + snapshot later, you can break into a debugger. For example: + + void MyFunc (void) + { + // Check to see if our application's data is internally + // consistant. If not, save the state for later analysis. + + if (ASSERT_VALID () == false) + if (HostSessionSave ("c:\\temp\foo.psf")) + DbgBreak (); + } + +* Changed the type of the second parameter to HostTraceOutputB from + "const unsigned char*" to "const void*". [Ben Combee] + +* When a Gremlin is running and -- for whatever reason -- the device + goes to sleep, wake it up by pretending the user pressed the Power + button. + +* Give the Gremlin fake event generation mechanism a 1% chance of + generating a vchrAutoOff event. This is the same chance given to it + generating a vchrKeyboard event. [Mike McCollister] + +* Added facilities for resolving aliases (Mac), links (Unix), and + shortcuts (Windows). + +* Added profiling support for BSR opcodes. [B. CAMERON LESIUK] + +* (Windows) Provided better error message when trying to create bound + emulators on Windows 95, 98, and ME. [Gregory Allen Gaub] + +* Added support for system extensions that reside in RAM. Normally, + Poser treats code executing in RAM as "application" code, and + prohibits it from accessing areas of memory reserved for the + operating system. However, this approach prevented user-installed OS + components that reside in RAM (such as OS patches and updates). + Poser now recognizes those components and allows them access to + memory in the same way it allow the OS in ROM to access memory. + Components that Poser recognizes are system patches, system + extensions, and libraries with Palm creator IDs. + +* Updated copyright messages to include 2001. + +* Updated ROM Transfer to print slightly better messages on errors. + For instance, instead of displaying #773, it will display "timeout". + Similarly for all other serial manager error codes. + +* Updated ROM Transfer to use the Serial Manager instead of the + Serial Driver Library when available. Will also use Palm OS 4.0 + SrmExtOpen call if available. + +* Fixed problem where Poser could read off the end of the ROM image + when trying to determine what type of device it's for (when building + the Device menu in the New Session dialog). [John Ludwig] + +* (Unix) Set the default device in the ROM Transfer dialog to + "/dev/ttyS0" in order to impart to users what type of data should be + entered here. Because different Unixes have different device names + for their serial ports, the default may not be correct. But it + should get the idea across, preventing users from entering just "0", + for example. [Bob Marcum] + +* Added Prism and Platinum support. [James Phillips, Handspring] + +* Updated Profiling operation rules. + + When using the menu commands, the following rules are used: + + * System starts with only Start enabled. + + * Selecting Start starts profiling executed code, initializing + the profiling system first if necessary. After selecting Start, + Stop and Dump are enabled. + + * Selecting Stop suspends the profiling of executed code. After + selecting Stop, the Start and Dump menu items are enabled. + + * The user can select Start and Stop as many times has he wants. + Always, the other menu item will end up being enabled, as well + as Dump. + + * Selecting Dump first Stops any profiling (if necessary) and then + writes data collected while profiling to files on disk. After + selecting Dump, only the Start menu item is enabled. + + When using the HostControl calls, an analogous set of calls can take + place. The only difference is that HostProfileInit can be called + before the first call to HostProfileStart or after HostProfileDump + in order to specify any custom parameters. If any HostProfile* calls + are made out of sequence, the error code hostErrProfilingNotReady is + returned. [Michael Nordstrom] + +* Updated HostProfile* functions along the same lines. If a + HostProfile* call is made out of sequence, it will return + hostErrProfilingNotReady. + +* Enable/disable Gremlins menu items correctly. + +* (Windows) Added platform-specific support for HostSaveScreen. [Bill + Kirby] + +* (Windows) Added multiple monitor support. Mostly this means that + the device window won't always reposition itself on the primary + monitor. [Thomas Hagen Johansen] + +* (Unix) Added $X_CFLAGS to espws build flags. [John Ludwig] + +* (Unix) Removed -L/usr/lib from link path (leaving just + /usr/local/lib). Both of these were added on Jan. 8, 2000, + apparently in response to Ralf Zimmerman's comments on + emulator-forum ("Re: Problem while compiling POSE 3.0a3 on Linux", + posted Dec 28, 1999). However, adding /usr/lib may have been + overkill, since doing that hides any custom tools in /usr/local/lib. + [John Ludwig] + +* When checking the validity of databases before installing them, now + also check the database's creation and modification dates. Poser + doesn't care about these and neither does the Palm OS, but some + versions of HotSync complain if the creation date is more recent + than the modification date or if the creation date is zero, so + display a warning if either of those cases is true. + +* In 3.0a8, code was added to automatically change use of + 207.240.80.136 (the old proxy address) to 209.247.202.106 (the new + proxy address). Well, those addresses are changing again. Instead of + hardcoding the address this time, Poser now looks up the address, + using the name "content-dev.palm.net" (or "content-dev2.palm.net" if + that one's not available). + +* Made the ROM transfer process more robust. Modifying the ROM + Transfer application and the Emulator to randomly corrupt data and + drop characters at a higher-than-normal rate showed problems with + the transfer process's ability to recover from transmission errors. + Those should all be fixed now. + +* With NetLib Redirection on, recv() is called as the underlying + implementation of NetLibReceive. If recv() returns EGAIN, map it to + netErrWouldBlock. [Chad House] + +* A bug in an internal ROM function in Palm OS 3.5 and 4.0 causes the + message "Background must be at least half as wide as slider." to be + displayed under the opposite conditions that it should be. + +* Plugged a hole that could cause Poser to hang. Occassionally, + Poser needs to suspend emulation so that it can make it's own + calls to Palm OS functions (it does this, for example, when building + the list of applications that appears in the New Gremlins window). + Because suspending emulation between any two opcodes and inserting + a call to a Palm OS function can be disruptive (for instance, the + Palm OS function may change the state of the heap in a way that + would never happen on a real device), Poser tries to first halt + emulation at a safe stopping point. This stopping point use to be + at the next call to a Palm OS function. However, even that's not + safe enough. If, for example, the Memory Manager semaphore were + acquired when emulation was suspended, and the call Poser was making + tried to acquire the semaphore, then Poser's call could block, waiting + for the semaphore to be released. Because emulation is suspended, + that will never happen, and Poser hangs. So now, in addition to + suspending emulation on a system call, Poser also makes sure that + the Memory Manager semaphore is available. This change should fix + a number of mysterious Poser hangs, including some that occur when + downloading a file for debugging in CodeWarrior. + + +Changes for 3.0a8 (2000-11-17) +------------------------------ +* Interim internal release dates: + 3.0a8e1 - not released + 3.0a8e2 - 2000-09-05 + 3.0a8e3 - 2000-09-13 + 3.0a8e4 - 2000-09-14 + 3.0a8e5 - not released + 3.0a8e6 - not released + 3.0a8e7 - 2000-10-13 + 3.0a8e8 - 2000-10-19 + 3.0a8e9 - not released + 3.0a8e10 - 2000-11-06 + 3.0a8e11 - 2000-11-13 + 3.0a8e12 - 2000-11-16 + 3.0a8e13 - not released + 3.0a8e14 - 2000-11-17 + 3.0a8e15 - 2000-11-20 + 3.0a8e16 - 2000-11-26 + +* Added Dragonball VZ support. + +* Added SED1376 support. + +* Fixed (again) the problem with the Palm IIIc screen not getting + redrawn after turning the power off then on. + +* Palm devices since the Palm III have an A-to-D converter (ADC) + called the Burr-Brown ADS7843. Until now, Poser did no emulate this + hardware, and so patched the OS routines that tried accessing it, + causing them to return sensible values anyway. Poser now emulates + the ADC, and so no longer needs to patch certain traps. + +* Removed spaces from ROM Transfer file names. + +* In 3.0a7, added ability to pass-through keyboard modifiers to the + Palm OS. However, I forgot to implement this on non-Windows + platforms. Fixed that oversight. [Dave Johnson] + +* (Unix) Fixed problem where you could save a screen shot only if the + target file already existed. [Michael Nordstom] + +* (Unix) Allow multiple .prc (et al) files to be loaded at the same + time from the "Get File" dialog. [Michael Nordstrom] + +* (Unix) Updated Gremlins menu items after a Gremlin has been + started. [Michael Nordstrom] + +* (Unix) Remember last-accessed directory when the File dialog is + presented, and re-show that directory the next time the dialog is + displayed. [Michael Nordstrom] + +* Fixed inability to use serial port when emulating the EZ-based Palm + VII or the Palm VIIx. [Jason Simpkins] + +* Added support for RTS_CONT bit in the Dragonball UART register. + This gives better support for applications doing hardware + handshaking. + +* Before closing the host serial port in response to the emulated + UART being shutdown, make sure that all locally buffered data is + transmitted. + +* Worked around that d*** bug in Palm OS 3.3 that would cause it to + overflow the kernel stack on a reset. Now, if Poser detects a stack + overflow and it's the kernel stack, Poser lets it overflow into the + interrupt stack (which appears right below it in RAM); Poser just + holds off interrupts for as long as the stack has overflowed. + +* Map Ctrl-P to vchrPrevField, to match Ctrl-N mapping to + vchrNextField. [Ben Combee, David Slotter] + +* (Mac) Worked around problem with items in progress dialogs not + showing up immediately (or, sometimes, at all). For instance, in + the dialog tracking the progress of the installation of databases, + the Cancel button and "Files remaining" text didn't appear until + after the first file was completely installed. I now manually + activate and update the dialog after making it visible. + +* Hide a Palm OS 1.0 bug that would access memory location 0xC2 in + HwrSleep. + +* (Windows) Support double-clicking on a .rom file in order to launch + Poser. Before, doing this would crash Poser, as it thought the file + was a session file. Note that you need to run Poser once by itself + first in order to update the appropriate Registry entries. + +* Fixed problems with Poser allowing access to certain system globals + from certain RAM-based functions (such access is usually + disallowed). The affected globals were tsmFepLibStatusP and + tsmFepLibRefNum, which can be accessed by the glue function + TsmGlueGetFepGlobals. + +* Secure Web-based transactions would result in Poser displaying an + error message about memory accesses to "unallocated memory", + "unlocked memory", "memory manager data structures", etc. These + messages are now no longer displayed. + +* Fixed Palm Debugger fb, fw, fl and ft commands. Poser's response + to the Find debugger packet was incorrect. [Bob Petersen] + +* Fixed removal of breakpoints. Poser was disabling them instead of + out-and-out removing them. The effect that old breakpoints would + re-appear, albeit disabled, in PalmDebugger. [Bob Petersen] + +* Reimplemented HostFSetPos and HostFGetPos in terms of fseek and + ftell. Previously, they were implemented in terms of fsetpos and + fgetpos, but those functions aren't portable, in that the definition + of fpos_t changes from platform to platform. + +* Merged in TRGpro support from TRGnet. [Dan Smith] + +* (Internal) Massive rewrite of the core emulation/session handler. + + Previously, a single sub-system was responsible for creating, + loading, saving, resetting, and freeing sessions; emulating the + Dragonball core instruction set; and taking care of "Palm OS + smarts", where checking based knowledge of how the Palm OS and Palm + OS applications was used to enforce correct behavior. Additionally, + the interface to this massive, heterogeneous sub- system was + different depending on whether Poser was being built for a platform + that supported multi-threaded applications or not. + + Now that's all been changed. There's an EmSession sub-system that + takes care of processor- and platform-independent session creation, + deletion, etc. There's an abstract EmCPU class and a concrete + EmCPU68K subclass responsible for emulating the 68xxx instruction + set. And there's an EmPalmOS sub-system responsible for knowing how + the Palm OS works and enforcing correct behavior. + + With these changes, Poser should be in a better position to support + different processors (like ARM) and operating systems (like Linux, + or even future versions of Palm OS that operate significantly + different from the current one). And with a more unified interface + to these new sub-systems, the higher levels of Poser can now also be + rewritten to be more cross-platform. + +* (Unix) Fixed (finally?) problem with LCD not appearing to turn off + when the power button is clicked to turn off the emulated device. + +* (Unix) Resize and relayout the generic error message dialog box, + instead of putting the (could be long, could be short) error text in + a scrollable field. + +* If INetLib tries creating its default preferences with a proxy + server address of 207.240.80.136 (an old, obsolete address), replace + it with 209.247.202.106 (the current address). + +* Fixed support for loading Palm VIIx ROM images downloaded from an + actual device (as opposed to the ROM images on the www.palmos.com + site). The problem was that the code used to determine what device + a ROM image is intended for was tripping up on that image's format, + and so misidentified the ROM. + +* (Windows) Fixed crash that could occur when clicking on some + Logging Options dialog buttons. + +* Let the Palm OS function dns_decode_name read off the end of a + buffer. I'm not sure yet why this happens, but until I do, let it + happen. Otherwise, developers will be presented with an error + dialog they can't do anything about. [Doitchinov Ivan] + +* Cleaned up, simplified, and robustified the mechanism used to + implement the AutoRunAndQuit directory feature. Poser used to have + a complex and (apparently) fragile mechanism for tracking calls to + SysUIAppSwitch, SysAppLaunch, SysAppStartup, and SysAppExit in order + to make sure that when the desired application exitted that Poser + quit. That's all been thrown out. Now, when an application quits, + Poser merely checks (in SysAppExit) to see if its cardNo and dbID + match that of the target application. + +* Fixed problem with logging posted/received events with Japanese + ROMs on Little-Endian host computers. Poser wasn't byteswapping the + event data, and so was trying to fetch some data at the wrong memory + location. + +* Address two of the three cases where calling a Palm OS function + which causes an exception can crash the emulator: + + 1. When handling an RPC call (e.g., try "hd 3" from + PalmDebugger). + 2. When calling a Palm OS function in a trap patch. + + We still don't handle the third case: + + 3. When calling a Palm OS function in the UI thread (e.g., when + building the Gremlin application list). + +* When a hardware exception (such as a bus error) occurs, Poser first + tries to contact any attached debugger. If it can't find one, it + displays an error message containing Debug and Reset buttons. + Pressing Reset will reset the device. Pressing Debug will try again + to contact a debugger. If it continues to fail, it continues to + display the same dialog, until either the user presses Reset or a + debugger is finally found. + +* (Mac) Added two new HostControl functions: + + HostProfileGetCycles() + Returns the current running CPU cycle count. As with all + profiling-related HostControl functions, this one is available + only in the profiling version of the emulator. + + HostSaveScreen(const char*) + Saves the LCD frame buffer to the given file name. + +* For its own purposes, Poser tracks memory allocations and de- + allocations in the Palm OS dynamic heap. In general, except when + the Palm OS dynamic heap is in flux (because an allocation or + deallocation is in process), Poser's notion of the heap state should + match Palm OS's. However, Poser was failing to keep its notion in + sync with Palm OS's in the case where a memory allocation was + requested and failed. It was possible for the heap to be compacted + and for Poser to not notice and sync up with that compaction. This + error could lead to Poser reporting errors when it shouldn't or not + reporting errors when it should. + +* Fixed problem where Poser could crash if the emulated application + tried accessing memory location 0xFFFFFFFF. + +* Fixed problem with the appInfo block not getting installed if the + .pdb file being installed didn't have any records in it. + + +Changes for 3.0a7 (2000-08-07) +------------------------------ +* Interim internal release dates: + 3.0a7e1 - 2000-04-19 + 3.0a7e2 - 2000-04-25 + 3.0a7e3 - 2000-04-28 + 3.0a7e4 - 2000-05-31 + 3.0a7e5 - 2000-07-07 + 3.0a7e6 - 2000-07-17 + 3.0a7e7 - 2000-07-18 + 3.0a7e8 - 2000-07-31 + 3.0a7e9 - 2000-08-04 + 3.0a7e10 - 2000-08-09 + +* Added m100 support. + +* Added Palm VIIx support. + +* Implemented the following previously defined but unimplemenated + HostControl functions: HostMalloc, HostRealloc, HostFree, + HostRename, HostRemove, and HostTmpNam. + +* Added the following HostControl functions: HostStat, HostTruncate, + HostMkDir, HostRmDir, HostOpenDir, HostReadDir, HostCloseDir, + HostAscTime, HostClock, HostCTime, HostGMTime, HostLocalTime, + HostStrFPrint, HostTime, and HostUTime. + +* Added the following HostControl functions: HostSlotMax, + HostSlotRoot, and HostSlotHasCard. + +* Added Card Options dialog. + +* Renamed a bunch of HostControl types to follow Palm's naming + convention of having types end in "Type". Added typedefs for + backward compatibility with applications using the old type names. + +* When a session is reset, all HostControl resources are reclaimed. + That is, any blocks allocated with HostMalloc are freed, any files + opened with HostFOpen are closed, any directories opened with + HostOpenDir are closed, and any pointers to returned string buffers + (as with HostGetEnv) are now invalid and the buffers are + inaccessible. + +* After creating a handle with MemHandleNew, locking it, remembering + the pointer, and then freeing the handle with MemHandleFree, the + application could write to the freed block using the now-stale + pointer. Fixed. [Neil Rhodes] + +* Support TsmGlueGetFepGlobals accessing system globals. + +* Updated URLs to point to www.palmos.com. + +* Fixed double-dispose bug when handing the getting or setting of a + linger-related socket option. The symptom of this bug is that Poser + would crash when calling NetLibSocketOptionGet(...netSocketOptSock- + Linger...). [Peter Burka] + +* Fixed problem in NetLibSendPB when NetLib redirection is turned on; + the various parameters weren't converted correctly into something + the host TCP stack could use. [Rob Leslie] + +* (Unix) Added dynamic check for socklen_t in configure.in. [Radu + Cornea] + +* Internal change: added new support classes: EmPoint, EmRect, + EmRegion, EmRefCounted, EmRefCounter, and EmPixMap. + +* Used the preceding classes in rewriting the pipeline that converts + the LCD framebuffer into something that can be displayed on the host + screen. These changes (a) better insulate much of Poser from the + specifics of the LCD framebuffer format, (b) reduce the amount of + platform-specific code needed to create a bitmap that can be blitted + to the host screen, and (c) result in slightly faster emulation. + +* Poser makes use of the following as a compile-time assert: + + char _dummy[expr ? 1 : 0]; + + If (expr) is true, then the compiler evaluates the stuff inside the + brackets as 1. Otherwise, the compiler evaluates it to zero, + resulting in the invalid definition of a zero-sized array. However, + unbeknownst to this poor programmer, gcc allows the definition of + zero-sized arrays as an extension. Therefore, all instances of the + above technique have been changed to COMPILE_TIME_ASSERT(expr), + where COMPILE_TIME_ASSERT is a macro that expands to something like: + + char _dummy[expr ? 1 : -1]; + + Even gcc complains about that one. [Frank Yellin] + +* Now that we have a working compile-time assert, a number of errors + popped up. Part of the NetLib redirection facility involves + translating between NetLib data structures and host TCP (sockets) + data structures. The process of translating back and forth assumed + that various structs and constants between the two systems were the + same and could be copied back and forth without any interpretation. + This assumption was backed up by compile-time asserts. But those + asserts were broken. Now that they're working, it was found that + many assumptions were bad and/or wrong. Therefore, much of the + translation code was rewritten to remove those assumptions. [Frank + Yellin] + +* (Unix) Turn on -fexceptions unconditionally. While this is on by + default for C++, we now turn it on for C, too. Poser seems to need + this on Solaris/Sparc systems. [Frank Yellin] + +* (Unix) Implemented Save Screen... menu item. Files are saved to + .ppm format. + +* (Internal) Implemented EmDlg::DoGetFile, DoGetFileList, DoPutFile, + and DoGetDirectory on all platforms, and use them universally. + +* Added HostGetFile, HostPutFile, and HostGetDirectory. + +* (Unix) Use new "FileChooser" widget from Easy Software. This one + will probably get incorporated into FLTK 2.0, and it just plain + looks and works nicer anyway. [Easy Software] + +* Patched TblHandleEvent to fix a Palm OS 3.5 bug where the drawing + state would eventually become invalid, resulting in incorrect + drawing and possible ErrDisplays from the OS. [Tom Bulatewicz] + +* Inhibit error checking in NetLibBitMove. This function sometimes + accesses bytes past the end of an allocate block of memory, + resulting in a Poser error message, usually while using PQAs. As it + turns out, it does this in a fairly safe fashion, so prevent the + error message from appearing. + +* (Internal) Use new method to access low-memory Palm OS System + globals -- one based on the EmPalmStructs mechanism. + +* The progress dialog that's displayed when installing files has + changed. The progress indicator is now modelled after the Macintosh + file copy progress dialog; instead of having two indicators -- one + for files and one for the current file -- the single progress + indicator now indicates overall progress for all files being + installed. Also, the Stop button now works. Finally, the progress + dialog is now also implemented on Unix. + +* Enabled logging of Exchange Manager actions (just calls to ExgSend + and ExgReceive). + +* (Internal) New Session dialog is now implemented using cross- + platform techniques that Poser is slowly moving towards. This + change results in consistant behavior of the dialog across + platforms. + +* (Unix) "configure" script now supports "--with-fltk=DIR" command + line option. [Arturo Tena] + +* Poser contains facilities for extracting the "Macsbug" symbols that + can be appended to compiled functions for debugging purposes. It + finds these symbols using heuristic methods that don't always + succeed. If they fail, fail gracefully. [Adam Dingle] + +* Fixed problem where turning off the "power" to a Palm IIIc would + blank the LCD, but turning the "power" back on would not redraw the + LCD. [Bob Petersen] + +* Fixed implementation of Perl wrapper for HostImportFile and + HostExportFile. [Derek Johnson, Andy Ihlenfeldt, John Ludwig] + +* Poser would crash if you passed a full path to HostProfileDump + instead of just the name of a file. + +* Ensure that the binary file produced by profiling an application + ends with .mwp. + +* Include keyboard modifiers when posting key events from the host + computer's keyboard. [Ken Krugler] + +* Changed "New Session" dialog to use MRU list for ROM Files, and not + present devices for selection that cannot possibly run the chosen + ROM File. + +* Updated CodeWarrior projects to CodeWarrior 5.3 (IDE 4.0.4). + +* Fixed problem with lack of responsiveness in mouse-click handling. + The problem was that there was only a 1-element queue, as it were, + for handling mouse-clicks. It was too easy for the user to click + the mouse and let up on the button before the emulated Palm OS had a + chance to even recognize that the mouse button was down. Now there + is an n-element queue to handle mouse ups/downs. I had originally + stayed away from that because I thought that it would be too easy + for the user to overrun the event queue, zooming the mouse around + faster than the Palm OS could keep up. But we'll see how this works + out. Note that the hard buttons across the bottom of the the + emulated device can still be unresponsive. That's because there's + no queuing involved; the mechanism for handling them is different + from that used to handle events in the LCD area, and can't easily be + converted to do so. + +* (Unix) Fixed problem with specifying desktop serial port to use for + ROM Transfer. [Rick Richardson] + +* Catch a whole class of problems where Poser didn't detect when the + emulated program counter went bad. [Eugene Chin] + +* Fixed byteswapping problems with creating the binary output file + for profiling. Such a file created on Windows couldn't be read into + MW Profiler on a Mac. [Greg Simon] + +* (Internal) Rewrote all of the emulation code that deals with + hardware registers (such as the Dragonball registers). There were + many subsystems that had to deal with memory in this way (the + Dragonball (328, EZ) register handlers, the SED register handlers, + the Visor USB register handlers, the Palm VII EZ PLD register + handlers, the Sybol ASIC register handlers, etc.). All of these + subsystems originally were just cloned from each other and tweaked. + This lead to a lot of duplicated code. All that's now been changed + so that the common code is in EmBankRegs, and the hardware-specific + code is in subclasses of EmRegs. + +* (Mac) Fixed crash that would happen when clicking on the mailto URL + in the Palm section of the About box. + +* The Field Manager in Palm OS 1.0 - 3.2 has a bug that causes the + message "Invalid insertion point location" to be erroneously + displayed. Added a patch to ErrDisplayFileLineMsg to squelch this + message if it looks incorrect. [Stephen P. Hill, David Kendall] + +* (Mac) Updated to GUSI 2.1.1, fixing a bug in HostFOpen, where + creating the file ":x:y" would create a file called "x" if the + directory didn't exist. + +* (Unix) Re-arranged checks at bottom of EmulatorTypes.h to allow + for definition of INADDR_LOOPBACK. [Jon Fo] + +* (Unix) Specify -fpermissive to gcc to support broken X11 headers. + [Jon Fo] + + +Changes for 3.0a6 (2000-04-19) +------------------------------ +* Interim internal release dates: + 3.0a6e1 - 2000-03-06 + 3.0a6e2 - 2000-03-13 + 3.0a6e3 - not released + 3.0a6e4 - 2000-03-24 + 3.0a6e5 - 2000-03-31 + 3.0a6e6 - 2000-04-10 + 3.0a6e7 - 2000-04-12 + 3.0a6e8 - 2000-04-17 + +* (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. + + +Changes for 3.0a5 (2000-03-06) +------------------------------ +* Interim internal release dates: + 3.0a5e1 - 2000-02-25 + 3.0a5e2 - 2000-02-25 + 3.0a5e3 - 2000-03-01 + 3.0a5e4 - 2000-03-03 + +* Internal change: major change in the way the Dragonball and + DragonballEZ registers are handled for different devices. + Previously, there were two sub-systems: one that handled Dragonball + registers, and one that handled DragonballEZ registers. Any device + differences withing those two categories were handled with a set of + conditional statements. That mechanism started breaking down (the + conditionals were getting too twisty), so now device support is + broken down with a set of classes having the following hierarchy: + + EmRegs - fairly abstract base class + EmRegs328 - mildly abstract base class implementing Dragonball emulation common to all 328 devices + EmRegs328Pilot, EmRegs328PalmPilot, etc. - concrete base class filling in the missing, custom pieces for a specific device + EmRegsEZ - mildly abstract base class implementing Dragonball emulation common to all EZ devices + EmRegsEZPalmIIIx, EmRegsPalmV, etc. - concrete base class filling in the missing, custom pieces for a specific device + +* Added Symbol 1700 support. Note that Symbol-specific hardware is + not yet emulated. Attempting to use scanner or Spectrum facilities + will hang the device. [Ron Kupke, Darren Kropp, John Duhart, Harini + Bharadvaj] + +* Changed the way serial emulation is performed a little bit. + Before, I'd look at the UART-enable bit to determine whether or not + to open or close the host's serial port. However, that would lead + to problems on Unix when using pseudo-devices. While opening the + serial port, the Palm OS would enable and disable the UART several + times as it was configuring the communications. This would lead to + the host serial port being opened and closed several times. But + Unix pseudo-devices don't react to that usage very well. So now, + Poser looks at the serial line driver enable bit. This bit is + toggled just once at the beginning and end of a serial port session, + just like we want. [Eskil Heyn Olsen] + +* Fixed problem with serial emulation not working on Palm VII EZ. + +* Fixed problem where reloading a .psf file that had a Gremlin + running would not correctly install the Gremlin-specific logging + options. + +* Fixed problem affecting Gremlin reproducability. There was a patch + on KeyCurrentState to randomly set key bits when a Gremlin was + running. However, the RNG used to set the bits was in no way + synchronized with the RNG used to generate Gremlin events, nor was + it ever reset in any way when a Gremlin was started or restarted. + The effect was that any application that was sensitive to the + results of KeyCurrentState would react randomly. One example of + this was the Address Book, which looked to see if the Address Book + hard key was pressed in order to see if the user wanted to beam + his/her business card. + +* Fixed problem affecting Gremlin reproducability. Some applications + are sensitive to time and timing issues. Gremlins now tries to make + sure that all forms of time (including the DragonBall cycle counter, + the kernel's tick counter, the Palm OS tick counter, and the + Dragonball real-time clock) are all set to consistant values when a + Gremlin is started and restored when a Gremlin-active .psf file is + reloaded (the cycle and tick counters are set to zero, and the RTC + is set to 3:00pm). Also, when a Gremlin is running, the real-time + clock is unhooked from the host's clock (normally, the values read + from the Dragonball real-time clock are generated from the host's + clock functions). Instead, the RTC is incremented assuming that the + average instruction takes 12 cycles, and where the cycle time is + based on the Dragonball's PLL registers. + +* Set the chip and mask IDs. This is set to the 1H58B part for the + 328, and 1J83G for the EZ. + +* (Unix) Fixed problem with Logging Options dialog hanging. + +* Check PC and stack pointer when doing a TRAP #$F dispatch. + +* More up-to-date instructions for Network HotSyncing with Poser. + [Brian Mathis] + + These instructions are intended for developers or other POSE users + who want to synchronize the Palm OS Emulator with the same PC they + are running POSE on. Modifications to these directions may be + needed if a user wishes to synchronize with a PC on an attached + network. They were written on a Windows machine, and probably have + Windows specific instructions in them. It should be pretty painless + to adapt them to other platforms that support hotsyncing. + + These are current for version 30a3 and 30a4 of POSE emulating a Palm + V, OS 3.1, and Hotsync version 3.0.1/3.0.4, Windows 98 & NT. + + ----Configure Hotsync on your Desktop PC + + 1. Right-Click the hotsync icon in the system tray + + 2. Enable "Network". A check mark will appear next to it if it's + already enabled. + + ----Configure POSE: + + 1. Right-Click on the POSE window to bring up the Menu. Choose + "Settings/Properties". + + 2. Check the box next to "Redirect NetLib Calls to TCP/IP". + + 3. Click "OK" + + ----Configure Hotsync on the Palm + + 1. Open the "HotSync App". + + 2. "Menu/Options/Modem Sync Preferences" - set to "Network" + + 3. "Menu/Options/LANSync Preferences" - set to "LANSync" + + 4. "Menu/Options/Primary PC Setup" - enter "127.0.0.1" under + "Primary PC Address" (the middle one) + + 5. Under the "Modem Sync" icon on the main Hotsync screen, tap + "Select Service". Then tap "Done". You don't need to change any + info, you just need to have something selected. You can create a + new profile if you like. + + 6. Tap the "Modem Sync" button. Your PC should now kick into + action, and will probably ask you to choose an account, or create a + new one. It is highly recommended that you create a new account + just for POSE. + + See also the following KnowledgeBase article: + + <http://oasis.palm.com/devzone/knowledgebasearticle.cfm?article_id=1674> + +* Information from TRGnet on TRGpro support. [Mike Walter] + + TRGpro support for POSE + + Version 3.0a4 includes limited support for TRGpro emulation. This + version emulates the FAT file system API provided on the TRGpro. It + does not support the lower level CompactFlash API or the enhanced + audio API on the TRGpro. + + In order to emulate the TRGpro Fat file system, do the following: + + 1. Obtain a PalmOS 3.3 image from any device. (PalmIIIx, PalmV, + etc) + + 2. Modify file "Palm OS Emulator.ini" in your Windows + subdirectory. Change to line FfsHome to point to a subdirectory on + your drive. + + Example "FfsHome=C:\POSE\ + + 3. Put desired Palm programs and databases into subdirectory + specified above. + + 4. Run Emulator.exe. + + 5. Install the programs ffs_pose.prc and CFPro.prc onto emulator. + + 6. Run CFPro to move files back and forth between Emulator and + PC's subdirectory. + + Developers writing code for the FAT file system can now debug using + POSE. + + More documentation will be provided later, specifying exactly what + is and is not supported with the emulator. For example, card + insert/remove messages are not supported with this version. + + For those of you interested, the files modified/added to the POSE + software base were, Platform_FfsLibWin.cpp and + TrapPatches_FfsLib.cpp. + + Keep in mind that this is a first beta release, if you have any + questions or problems, email TRGnet directly. + + Zip file containing ffs_pose.prc and CFPro.prc can be downloaded + from: + + http://www.trgnet.com/download/pose/fat.zip + + POSE version 3.0a4 or greater can be downloaded from: + + http://www.palmos.com/dev/tech/tools/emulator/> + +* "Pen" events are essentially created as needed and inserted into + the Palm OS on demand from mouse events by way of a patch on the + SysEventGet function. However, until now, there was no + corresponding patch to EvtSysEventAvail to make that function return + true if the host mouse was down. Now there is. [Michael Nordstrom] + +* Added back long paths for MRU menus. [Chris Antos] + +* (Windows) Made F11 minimize the window. [Chris Antos] + +* (Windows) Swapped positions of About and Exit menu items. [Carlton + Craighead] + +* Simplified Skins dialog. + +* Simplified Gremlins dialog. Instead of entering magic numbers like + zero and -1, use checkboxes to enable desired features. + +* Added Palm IIIc skins. Renamed "Color Device" to Palm IIIc. + +* Added UsingPOSE.pdf. + +* (Unix) Implemented "File/Save" menu item. [Dan Poirier] + +* (Unix) Fixed problem where UART::Initialize would get called twice + when reloading a .psf file, triggering an assert. [Dan Poirier] + +* (Windows) Fixed problem with not setting the skin palette when + using the generic skin on 8-bit monitors. [Andreas Linke] + +* Removed SndInit patch that would set the system volume level to + zero, mirroring what happens in the simulator. However, this + caused problems with people not hearing sounds when they expected + to. So, removed the patch. If you don't want sound, turn it off + in the Preferences/Properties dialog. [Frederic Paolucci] + +* (Unix) Building under Solaris 2.6 (with gcc installed) is now + possible. It's probable that building under other SunOS environments + won't work. + +* (Unix) The window resizes to match skin selections. + +* Export Database dialog now primarily lists the actual database name, + with the application icon name in parentheses if it differs. + + +Changes for 3.0a4 (2000-01-28) +------------------------------ +* Interim internal release dates: + 3.0a4e1 - 1999-12-02 + 3.0a4e2 - 1999-12-30 + 3.0a4e3 - 2000-01-07 + 3.0a4e4 - 2000-01-23 + 3.0a4e5 - 2000-01-26 + 3.0a4e6 - 2000-01-27 + +* Yow...time to start updating those copyright statements...again... + and this time there's a lot more files! + +* When installing a .prc file, check for duplicate resources. + +* Provide better error messages when something goes awry while + installing an application or database. + +* Added support for Palm IIIe and Palm Vx: + + - Added as items to Device menu. + - Added code to save those devices as preferences. + - Added as -device parameters on command line ("PalmIIIe" and "PalmVx"). + - Added and mapped in appropriate skins. + - Added new internal type IDs. + - Corresponding tweaks to Binder application. + - Made Palm IIIe return same device ID as Palm IIIx. + - Made Palm Vx return same device ID as Palm V. + +* (Mac) Updated to GUSI 2.0.1. This has the following benefits: + + - Adds support for socket options. + - Based on Open Transport instead of Mac TCP. + - Fixes problem with menus sometimes getting disabled (the + old GUSI would eat up "resume" events, so PowerPlant didn't + know to re-enable the UI). + +* Fixed problem where Poser's heap walking routines were vulnerable + to odd master pointers. [Mike Chen] + +* Gremlins wasn't generating and posting hard button events properly. + [Steve Lemke] + +* (Unix) Fixed problem with trying to delete a skin with a stale + pointer. [Ben Darnell] + +* Updated ROM Transfer.mcp to CodeWarrior for Palm OS R6. + +* Support for the gdb debugger has been built-in for quite some time + (since 2.1d22 or so). Here, finally, are some instructions for + interacting with it. Note that you no longer need to use gdbpanel + or gdbplug if you were using those with earlier versions of Poser, + Copilot, or xcopilot. [Ben Thomas] + + - Build your app. Be sure to _both_ compile and link with -g + (e.g., "gcc -g ..."). On the compile pass, this generates the + necessary symbol information; on the link pass it forces the + inclusion of a debug runtime code that results in a breakpoint + being installed in PilotMain when the app starts. + + - Start Poser. + + - Load your app into Poser. + + - Start gdb, loading your application's symbol table (e.g., "gdb + myApp"). Note that the file to be loaded is the "myApp" file + created by the GCC link pass, not "myApp.prc" created by + buildprc. + + - Type "target pilot localhost:2000" to gdb. It should respond + with a message along the lines of "Remote debugging under PalmOS + using localhost:2000. Waiting... (Press Ctrl-C to connect to + halted machine)". + + - Start your app on Poser. + + - Wait for gdb to see the initial breakpoint and prompt you. + + - Start debugging. + +* Tweaks to the scripting samples: [Flash Sheridan, Steve Haneman] + + - Wait() no long automatically resumes. + - Added seperate Resume function + - Since wait no longer resumes, added TapPenSync, and TapButtonSync + which automatically call Wait and Resume at the beginning and end. + - Fixed some warnings that showed up when running Perl -w. + - Added MemPtrSetOwner, WinDisplayToWindowPt, WinWindowToDisplayPt. + - In TapButton, call WinWindowToDisplayPt. + - In EmRPC, added support for Coord type. + +* Internal change: encapsulated all device-specific information in an + EmDevice class. This should make it easier to add new devices, + since all the information is now in one place. + +* Stack overflow checking is back (cf 2.1d27)! Whenever it looks + like something is assigning a value to the stack pointer register, + Poser marks the memory block that pointer is in as a stack. Then, + when the stack pointer is decremented for any reason, it is compared + to the low end of the memory chunk. If it falls below, Poser + displays a fatal error dialog. If the stack pointer is just getting + close without actually going over, Poser will display a warning. + +* Fixed another case of Gremlins going to sleep on the job. Gremlins + normally posts new random events when the system calls EvtGetEvent + and there's nothing to return, resulting in SysDoze being called. + Most of the times, Gremlins will post an event and return from + EvtGetEvent. In the cases it doesn't, it forces EvtGetEvent to + return a nil event. However, if Gremlins was posting a Shakespeare + quote to a form field, and the form field was full, and there was a + non-empty selection, there was a 33% chance that neither an event + would be posted nor a nil event returned. This resulted in the + application having nothing to do (and so SysDoze was called) and + Gremlins thinking its job was done for the moment and putting itself + into a "do nothing" state. [Scott Maxwell] + +* (Windows) When reloading a .psf file, fixed a bug that prevent the + Gremlin Control Window from being reshown if the session file had + been saved while a Gremlin was running. [Scott Maxwell] + +* (Windows) Fixed a problem with relocating the ROM file that a .psf + file reference when that ROM file wasn't where it was supposed to + be, but it *was* in the same directory as the .psf file. + +* (Unix) Rolled in modifications for FreeBSD. [John Ludwig] + +* (Unix) Properly recognise X options such as -display and -geometry. + [Eric House, John Marshall] + +* Reset the Dragonball timer registers to a consistant state before + starting a Gremlin. This gives more consistant results. HOWEVER, + any application that is dependent on the time in any fashion may + still have consistancy problems when running Gremlins (that is, + starting Gremlin #0 at 3:00pm may give different results than when + it is started at 5:00pm). This is an issue that we'll try to + address in a future release. + +* Switch from obsolete xxxChr names to new vchrXXX names in logging + output. Also, if a winExit/EnterEvent is associated with a form, + print the name of that form in the logging output if event logging + is turned on. + +* (Mac, Windows) Added Tracer support. This is a facility for + sending logging information to an external logging application. Palm + applications use the following API for doing this: + + (All HostTraceOutput functions take a module identifier as their + first parameter. This parameter allows filtering out traces + according to their origin. Recognized modules are listed as error + classes in SystemMgr.h. Application should specify appErrorClass.) + + void HostTraceInit(void); + Call once at the beginning of your application to + initialize the logging facility. Initiates a connection + to the "tracing port" (specified in Poser's Tracing + Options dialog box). + + void HostTraceClose(void); + Call once at the exit of your application to release + any host logging resources. + + void HostTraceOutputT(unsigned short, const char*, ...); + Log a string of text to the tracing port via a + "printf-like" facility. + + void HostTraceOutputTL(unsigned short, const char*, ...); + Same as HostTraceOutputT with an additional line break. + + void HostTraceOutputVT(unsigned short, const char*, char* /*va_list*/); + vprintf-like variant of HostTraceOutputT. + + void HostTraceOutputVTL(unsigned short, const char*, char* /*va_list*/); + vprintf-like variant of HostTraceOutputTL. + + void HostTraceOutputB(unsigned short, const unsigned char*, unsigned long/*size_t*/); + Send binary data to the tracing port. + + The functionality for sending the logging information to the + external application is provided by a shared library (e.g., + "PalmTrace.dll" on Windows). The external application can be any + application that supports the open packet convention. The one we + provide is "Reporter". At the time of this writing, the shared + library and external reporting application will be provided in a + seperate archive. [Patrick Porlan, Regis Nicolas] + +* Internal changes: massive movement to make more source code cross + platform. New classes include: + + EmTransport: abstract base class representing a "pipe" between two + entities. + + EmTransportSerial: a pipe based on serial communications. Serial + port emulation (the facility that allows Palm OS Serial Manager + calls to pass thru to and from the host serial port) rewritten to + use EmTransportSerial. + + EmHostTransportSerial: class with different implementations on + different platforms in order to provide platform specific + functionality. + + EmDlg: class to manage dialogs in a cross-platform fashion. + + EmROMTransfer: class that implements a rewritten ROM download + facility, based on the new EmTransport and EmDlg classes. Because + the new ROM transfer code is based on EmTransport and not + EmTransportSerial, this means that it may be possible to transfer a + ROM using something other than the serial port in the future. + +* With the help of the previous changes, the ROM Download facility is + now available on Unix. + +* Internal change: rewrote JPEG decompression routines to better + modularize the source of compressed data and the destination of + decompressed data. This was done to better support JPEG images on + disk in addition to those in embedded resources. + +* Added back the old generic case graphics. These graphics are now + used when the user selects "Default" in the Skins menu and dialog. + The nicer graphics are now identified with names like "Standard - + English" and "Standard - Japanese". Eventually, those nicer + graphics will be moved to external files, reducing the size of Poser + drastically and reducing download times. + +* Internal change: synced up with the latest shared Palm OS files. + This change also included switching over to the new standardized + types (UInt32, Int16, etc.) from the old hodgepodge of types (DWord, + Long, Int, Byte, etc.). + +* ROM Transfer now downloads the entire ROM instead of just the "Big + ROM". It now is also a little more robust in light of some invalid + fields in Visor ROMs. + +* (Windows) Added support for TRGpro devices. This support comes in + the form of supporting TRGnet's FAT File System library. There is + no TRGpro menu item in the device menu. Instead, you can + effectively turn any Palm Computing device into the equivalent of a + TRGnet device by installing their FFS library -- which is what + manages access to the CompactFlash slot -- onto the device. + (Actually, all it needs is a stub library that you can get from + TRGnet.) Poser will redirect calls from that library to the host + file system. The root of the emulated FFS directory hierarchy is + specified by the FfsHome preference in Poser's preference file. It + can be a path relative to Poser's directory (e.g., "foo") or an + absolute path (e.g., "c:\temp\foo"). The directory will be created + if needed. If no preference is specified, or the value is empty, or + the specified directory could not be created, the root path defaults + to Poser's directory. There is currently no UI for setting the root + of the hierarchy; you have to edit the preference file by hand. + [Mike Walter] + +* Added Visor support. Note that no USB support is provided in this + release. This means that Poser will not download a ROM from a + device in a USB-connected cradle, nor will USB operations on the + emulated Visor be redirected to any host facility. + +* Fixed problem with a too-small name buffer in profiling routines. + Removed absolute address from generated function names, as that + annotation interferes with the CodeWarrior Profiler's ability to + unmangle C++ names. [Catherine White] + +* (Windows) Removed "Close" menu item from "bound" versions of Poser + (functionality duplicates "Exit"), and added "Save Screen". [Scott + Johnson] + +* (Unix) Added temporary hack to get Unix menus working (many would + result in the message that the system was not responding). The + solution implemented, however, is not optimal, and may lead to other + problems. Expect this area to receive more attention in the near + future. [Eric House] + +* Added sound emulation. Be sure to enable this in the preferences + if you want it. [William F. Weiher III] + +* Fixed a couple of minor problems in the NetLib redirection code, + one with accept() and another with the way select() timeouts were + set up. [bill pitore] + +* Fixed a problem with determining the baud rate established by the + UART, with the result that serial communications on 20MHz devices + (like the Palm Vx) didn't work. [Alan Finke] + + +Changes for 3.0a3 (1999-11-13) +------------------------------ +* Added Q&D PC checking. On JSR, BSR, RTS, and RTE, I check what + we're attempting to set the PC to. Originally, I had a pretty beefy + check that made sure the PC was in things like allocated, locked + chunks. However, that's expensive for now, so I backed off to + checking that the PC was (a) even, (b) in RAM or ROM, and (c) not in + low-memory. + +* The new UAE 0.8.10 code includes a new way to emulate ROR and ROL + instructions. Unfortunately, this new way runs afoul of a code + generation bug in CWCPPC 2.3.1 (from CW 5.2) on the Mac. Reverted + to the old way of emulating those instructions until Metrowerks + comes out with a compiler patch. [Catherine White] + +* (Unix) Added tweaks for Debian systems. [Ben Darnell] + +* (Mac) Changed the way Poser determines whether or not to translate + extended ASCII characters (those >= 0x80) into standard ASCII + equivalents. The new method should be more consistant and robust, + based on whether or not the user is running a Japanese Palm OS and a + Mac OS with the Japanese Language Kit installed. + +* The device could actually go to sleep while running Gremlins! + Sometimes, Gremlins will input a long series of key events. + However, key events don't reset the auto-off counter. Normally, the + Palm doesn't care, since key events are a side-effect of pen events, + which *do* reset the auto-off counter. But Poser doesn't enter key + events that way -- it inserts them directly with EvtEnqueueKey. Now + Poser calls EvtResetAutoOffTimer when it enters key events. [Steve + Lemke] + +* (Windows) Sped up Gremlin Hordes a little. There were some long + delays while switching from one Gremlin to another due to trying to + access the Gremlin Control Window from the wrong thread. There's + still a mysterious 2 second delay while switching Gremlins, but at + least one cause of the slow-down is fixed. + +* Fixed problem with Gremlins and Palm OS 3.5 systems. Gremlins + calls WinGetWindowBounds to get the bounds of a window in which to + generate pen taps. WinGetWindowBounds returns the bounds of the + window returned by WinGetDrawWindow. On older systems, if the draw + window were NULL, WinGetDrawWindow would return the display window. + On 3.5, this has been changed in debug ROMs; WinGetDrawWindow can + return NULL so as to force applications to make sure there is an + established draw window. Gremlins ran afoul of that change, and so + now calls WinSetDrawWindow(WinGetActiveWindow()) before calling + WinGetWindowBounds(). [Roger Flores, Steve Lemke] + +* In the event posting/receiving logging code, support the new Palm + OS 3.5 events. + +* In HostFPrintF, support + and space as flags, and * as a minimum + width field character. [Patrick Porlan] + +* Added Symbol 1700/1740 skin as an option for Palm III's. This is + *not* to say that Poser emulates symbol devices. It only means that + you can make a Palm III look like a Symbol device. [Ron Kupke] + +* Reformatted Gremlin Hordes log file to make it a little easier to + find the error messages. [Flash Sheridan, Catherine White] + +* Make a stronger effort to get the pen calibrated perfectly. The + original attempt (cf, 2.1d11) would occassionally only get us very + close, which could lead to inconsistent Gremlin runs. + +* Fixed a bug in the UAE 0.8.10 code where a corrupt status register + could get pushed onto the stack during an exception/interrupt and + the previous instruction that had affected the Z CPU flag was a BCHG + instruction that flipped the highmost bit from off to on (gee, how + could we have missed *that*). [Catherine White, Stuart Malone] + + +Changes for 3.0a2 (1999-11-05) +------------------------------ +* Updated to UAE 0.8.10. We were previously based on 0.8.3. The new + version fixes a few minor bugs (I never noticed them), perhaps + speeds things up a little, but most importantly cleans up those 2000 + "unreferenced label" warnings you get when compiling with gcc! OK, + so now there are some "unused variable" warnings, but there are a + lot fewer of them... + +* (Windows) The sequence of events involving saving a session when + creating or opening a new one was completely broken. + +* (Windows) Added support from Palm Europe for their tracing tool. + This tracing tool is a seperate application that receives tracing + information sent via HostControl functions. The documentation for + these functions is not yet available. Neither is the external + application. But they soon will be. I just wanted to at least + mention them so that people don't ask me about them if they see the + new functions in HostControl.h. + +* (Unix) Modified Perl script that creates ResStrings.cpp. It used + to add the strings to a map object (so that they can be looked up by + an ID number) by calling a function with about 2000 calls that + looked like "map[id] = str;". However, gcc would choke on this with + optimizations turned on. Now, that map addition is performed in a + seperate function, and that function is called 2000 times instead. + [Ben Darnell, Jon Fo] + + +Changes for 3.0a1 (1999-11-04) +------------------------------ +* Interim internal release dates: + 2.1d29.1 - 1999-08-26 + 3.0a1e2 - 1999-09-14 + 3.0a1e3 - 1999-09-15 + 3.0a1e4 - 1999-09-16 + 3.0a1e5 - 1999-09-21 + 3.0a1e6 - 1999-09-24 + 3.0a1e7 - 1999-09-30 + 3.0a1e8 - 1999-10-08 + 3.0a1e9 - 1999-10-14 + 3.0a1e10 - 1999-10-19 + 3.0a1e11 - 1999-10-27 + +* Rolled in Llamagraphics's profiling changes [Catherine White]: + + The motivation for these changes was to fix the crashing problem we + reported earlier. Here's what we changed: + + - We rewrote RecursiveAddressToStrings without recursion, and + named the new function LinearAddressToStrings. The old function + was recursing over both kids and siblings, which was blowing the + stack on the Macintosh. Since it doesn't matter what order the + addresses are converted in, a linear loop is faster and simpler. + + - Called ProfilerCleanup at the end of ProfilerDump. Since + calls[i].address is modified during the dump, the calls array + can't be reused after the dump since it no longer contains valid + addresses. It seems safer to dispose of it so that it isn't used + accidentally. + + - Replaced the two Debugger() calls in ProfilerInit with calls to + DisposeMemory(). We were encountering these Debugger calls + while testing our own code, probably because ProfilerInit was + being called twice somehow. Calling ProfilerInit twice should + now be harmless, and should no longer leak memory. + + - Changed the handling of function names so that they are no + longer limited to 31 characters. The new limit is 255 + characters. This means that most mangled C++ names can now be + parsed properly by the MW Profiler, which makes interpreting the + profiles easier. + + In order to accomplish this, we needed to add extra arguments to + two routines in Miscellaneous.cpp for the buffer capacity. This + capacity defaults to 32, which means that callers who don't pass + in the extra argument will get the same behavior as before. + + We also added code in the profiler so that the stringTable could + grow dynamically. This means that it isn't so important to + allocate enough memory for the stringTable initially. However, + the initial size is currently the same as the old size was, so + reallocation shouldn't occur very often. + +* (Mac) Updated to CodeWarrior Pro 5. + +* Overhauled handling of preferences/properties/settings/options... + These settings were previously stored as resource-based binary data + on the Mac, System Registry entries on Window, and an RC text file + on Unix. Now the information is saved out as a text file on all + platforms. And -- with a common source code base -- all information + is saved out consistantly (some platforms previously skipped saving + some information). Finally, with all information in an accessible + text file format, it should be easier for users to tweak or fix + settings (or even specify settings for which there is no UI). + + Note that NO attempt has been made to migrate forward settings from + the previous formats. + +* In line with that, if the InterceptSysFatalAlert is true (default), + Poser will intercept calls to SysFatalAlert and display the message + in its own dialog box. If this setting is false, Poser will let the + standard Palm OS function display the message. [Ken Krugler, Scott + Johnson] + +* If a SysFatalAlert dialog is displayed while a Gremlin is running, + the Gremlin will no longer be halted if the user clicks on Continue + (it used to be that the Gremlin was *always* halted). [Roger Flores] + +* (Windows) Ask user if they'd like to have a shortcut to Poser added + to the Start Menu. [Phil Shoemaker] + +* Better validation of .prc files. [Daniel McCarthy] + +* (Windows) Cancel button in file download progress dialog now works. + +* (Windows) Fixed byteswapping bug in PSF writing code. Poser should + now have a better chance of reading Mac-created PSF files on Windows + and vice-versa. + +* Fixed memory leak bug that would occur when closing a session. The + buffers holding the ROM image and auxilliary information weren't + being deleted. [bullshark (a real person with a real email + address)]. + +* (Windows) Added the Palm OS Emulator Binding tool, an NT-only + wizard which can bind a Windows Poser executable with (1) a ROM file + and a device configuration, or (2) a ROM file and a session file. + This will create a self-contained executable suitable for "kiosk" + run. + + Poser detects when it is bound, and modifies its behavior in the + following manner: + + (1) ROM + device configuration. Poser always starts by booting + into a new session with the selected device configuration and + ROM. If the user closes the session and creates a new one, he or + she will not be prompted for a device configuration. + + (2) ROM + PSF file. Poser always starts right into the state + saved in the PSF file. The user interface is abbreviated to + include only pertinent functionality (no debugging or logging, + for example) that is appropriate to a "kiosk" run. IF the user + closes the session, he or she only has the option to restart it + in the state saved in the PSF file. Posers bound this way share + a separate set of preferences then unbound Posers. + +* Made the socket port that an external debugger can connect to + configurable. The old hard-coded port of 2000 is still support for + backward compatibility, but clients should move away from that. + Instead, they should use the port specified in the + "DebuggerSocketPort" preference. (There is currently no UI for + changing this preference. But it can be changed by hand by editting + the Poser preferences file, which is in text format.) + +* Added the following functions to HostControl.h: + + HostErr HostProfileDetailFn (void* addr, HostBool logDetails) + + Profiles the function containing the given address. If + logDetails is true, profiling is performed at a machine- + language instruction level (each opcode is treated as + its own function). + + HostErr HostGremlinNew (const HostGremlinInfo*); + + Start a new Gremlin using the given specifications. + + HostBool HostGetPreference (const char*, char*); + void HostSetPreference (const char*, const char*); + + Get or set the specified preference. Preferences are + identified by name, the set of which can be seen in the Palm + OS Emulator Preferences file for your platform ("Palm OS + Emulator Preferences" in the Preferences folder on the Mac, + "Palm OS Emulator Preferences.ini" in the Windows System + directory on Windows, and ".poserrc" in your home directory + on Unix). The values are also specified as strings, + examples of which can be seen in the preferences file. + + HostErr HostSessionCreate (const char* device, long ramSize, const char* romPath); + + Create a new session based on the given parameters. + Fails if a session is already running. + + * NOTE: Not yet implemented. + + HostErr HostSessionOpen (const char* psfFileName); + + Open the given session. Fails if a session is already + running. + + * NOTE: Not yet implemented. + + HostErr HostSessionClose (const char* saveFileName); + + Close the current session, saving it to the given file. + The session is not saved if no file name is specified. + This function fails if no session is running. + + HostErr HostSessionQuit (void); + + Ask Poser to quit. Fails if a session is already + running. + + HostErr HostSignalSend (HostSignal signalNumber) + + Send a signal (identified by an integer) to any scripts + with HostSignalWait calls pending. If there are such + pending calls, Poser then halts waiting to be restarted + with HostSignalResume. If no one was waiting for any + signals, then Poser doesn't halt. + + HostErr HostSignalWait (long timeout, HostSignal* signalNumber) + + Wait for a signal from Poser. Signals can be predefined + (hostSignalIdle, hostSignalQuit) or user-defined. + HostSignalWait returns the signalled value. + + hostSignalIdle is issued by Poser when it detects that it's + going into an idle state. + + hostSignalQuit is issued by Poser when it's about to quit. + + HostErr HostSignalResume (void) + + Restarts Poser after it has issued a signal. By waiting + to be restarted, Poser allows external scripts to perform + any other operations first. + + + While the following functions are in the HostControl API, + they exist for external RPC clients to call and will return + errors if called by Palm OS applications: + + HostSessionCreate + HostSessionOpen + HostSessionClose + HostSessionQuit + HostSignalWait + HostSignalResume + +* Opened a socket (on the port specified in "RPCSocketPort" + preference) for external applications to make RPC calls. By sending + RPC packets, external applications can invoke any function in the + Palm OS dispatch table. This set of functions includes the + HostControl functions, which can be called even when no session is + running (which normally would mean that there isn't really a + dispatch table containing functions that can be called). + + Packets sent to the RPC sub-system use the same format as packets + sent to the debugger sub-system, that is, the Serial Link Protocol + packet format (also used by HotSync). This format is described in + Debugging.html. + + When sending command packets to the RPC sub-system, you need to set + the "dest" field of the packet header to: + + #define slkSocketRPC (slkSocketFirstDynamic + 10) + + as opposed to slkSocketDebugger or slkSocketConsole, as you would + when talking with the debugger sub-system. + + The RPC sub-system can accept one of 4 kinds of command pacets: + ReadMem, WriteMem, RPC, and RPC2. The first three packets are the + same as those sent to the debugger sub-system and are defined in + Debugging.html. RPC2 is an extension of the RPC packet in order to + support a wider range of facilities. + + RPC2 packets are defined as follows: + + #define sysPktRPC2Cmd 0x20 + #define sysPktRPC2Rsp 0xA0 + + struct SysPktRPCParamInfo + { + UInt8 byRef; // true if param is by reference + UInt8 size; // # of Bytes of paramData (must be even) + UInt16 data[1]; // variable length array of paramData + }; + + struct SysPktRPC2Type + { + _sysPktBodyCommon; // Common Body header + UInt16 trapWord; // which trap to execute + UInt32 resultD0; // result from D0 placed here + UInt32 resultA0; // result from A0 placed here + UInt16 resultException; // If an exception occurred, it's ID is here + UInt8 DRegMask; // Bitmasks indicating what registers need... + UInt8 ARegMask; // ...to be set on this call. + UInt32 Regs[1]; // Variable-length array holding register... + // ...values to be set on this call. + UInt16 numParams; // how many parameters follow + + // Following is a variable length array of SlkRPCParamInfo's + SysPktRPCParamType param[1]; + }; + + Most of this is the same as the RPC packet. It differs with the + addition of the following fields: + + resultException: if the function call failed because a hardware + exception occurred, the exception ID will be stored here. Otherwise, + this field contains zero. + + DRegMask: a bitmask indicating what D registers need to be set in + order to make this call. In particular, some functions require that + a "selector" value be placed in register D2. In this case, bit 2 of + DRegMask (the 3rd bit from the right) would be set. + + ARegMask: same comments. + + Regs[1]: a variable length array containing the values to be placed + in the registers to be set. Only the registers that are being + changed need to be supplied. Most of the time, DRegMask and ARegMask + will be zero and Regs would not appear in the packet. In the example + where D2 needs to be set, DRegMask would be 0x04, ARegMask would be + 0x00, and ARegMask would be followed by a single 32-bit value to be + placed in D2. If more than one register needs to be set, then the + register values should appear in the following order: D0, D1, ..., + D6, D7, A0, A1, ..., A6, A7. Again, only values for the registers + specified in DRegMask and ARegMask need to be provided. + +* Fixed crasher that could occur if "Received Events" logging was + turned on and one of three KeyDown events was popped off the stack. + [Ken Krugler, Jeff Yasuda] + +* (Unix) Added serial port emulation, as well as better support for + other OS and compiler flavors. [Jerry Kirk, Michael Kedl] + +* (Unix) Added support for cursor, page up/down keys. [Michael Kedl] + +* (Unix) Fixed massive memory leak when sessions ended. [Michael Kedl] + +* More evolution of skin support. Skins are now set on a device-by- + device basis from a new "Skins..." dialog box. Other aspects of the + device's appearance are also set from this dialog box, such as the + scaling factor and the LCD background color. + +* Look at the chip selects when determining what range of RAM should + be protected or not instead of just assuming 128K. [Steve Lemke] + +* Fixed problems with reloading .psf files what were saved when a + Gremlin was running. + +* Fixed problem with white border in 2x mode. + +* Fixed problem with setting some color table entries. [Bob Ebert] + +* Fixed problem with HwrDisplayWake hanging on power-up. [David Fedor] + +* Setting "DebuggerSocketPort" or "RPCSocketPort" preferences to zero + will disable their respective facilities. This should be handy in + cases where merely opening a TCP socket fires up any sort of + unwanted Remote Access facilites. [Ken Krugler] + +* (Mac) Fixed bug in new preferences saving mechanism where the + preferences would not get saved if the file didn't already exist. + [Mike Puckett] + +* Allow LCD window to be placed in negative coordinates. [Mike Puckett] + +* Addition of Gremlin Hordes. A Horde is basically a range of + Gremlins to run. You specify the range: the first Gremlin and the + last Gremlin in the Horde. Poser will start with the first Gremlin, + and generate that Gremlins event stream until one of four things + happens: + + - An error occurs (hardware exception, illegal memory access, etc.), + - The maximum number of events have been generated, + - A "switch" event occurs. A switch event is when a specified number + of the maximum number of events have been generated. + + When any of these conditions occur, the current Gremlin is either + halted or suspended and the next Gremlin in the Horde is selected. + When Poser has cycled through all the Gremlins in the range, it + cycles back and restarts any suspended Gremlins one at a time. When + all Gremlins have been halted (either because they've encountered an + error or they've reached the maximum number of events), the Hordes + session is completed. + +* (Windows) Added the following command-line options [Brian Estes]: + + -skin <name>: + Synonyn for -silkscreen. + + -ram_size <size in K>: + Synonym for -ram. + + -load_apps <file name list>: + A comma-seperated list of files (.prc's, etc.) to load after + startup. + + -run_app <app name>: + Application to run after startup. Note that this is the + name of the *application*, not the file. + + -quit_on_exit: + If -run_app was specified, quit when that application exits. + + -log_save_dir <path>: + Location for standard log file. Default = Poser's directory. + + -horde <num>: + Gremlin number to run after session is created or loaded. + Equivalent to setting -horde_first and -horde_last to the + same number. + + -horde_first <num>: + First Gremlin in a Gremlin Horde to run. + + -horde_last <num>: + Last Gremlin in a Gremlin Horde to run. + + -horde_apps <app name list>: + A comma-seperated list of applications Gremlins is allowed + to switch to. Default == entire device (no restrictions). + + -horde_save_dir <path>: + Location for directory that keeps saved session files and + logs. Default = Poser's directory. + + -horde_save_freq <num>: + Gremlin snapshot save frequency. Default = don't save + snapshots. + + -horde_depth_max <num>: + Total number of Gremlin events to generate for each Gremlin. + Default == no upper limit. + + -horde_depth_switch <num>: + Number of Gremlin events to generate before switching to + another Gremlin in a Horde. Default == the same number + specified for -horde_depth_max. + +* (Windows) Added support for Alt-F4; made it act like the Exit menu + item. [Ryan Robertson] + +* Fixed a problem with profiling calls to Palm OS function made via + the SYSTRAP_FASTER macro. The function entry would be recorded once + because it was a system call, and then again because it was made via + a JSR. Because the subsequent RTS would pop only one of those off of + the profiler's stack, the stack would get out of sync and overflow. + [Jameson Quinn] + +* (Windows, Unix) Now stop the CPU thread on almost any UI action. + Previously, the CPU thread would be stopped only in targeted + situations. Now, it's stopped whenever the user executed a menu + command. This change was made when I found out that the profiling + menu items could mess up the CPU thread if it weren't stopped first. + +* Updated ROM Transfer project to CodeWarrior for Palm OS 5.2 (that + is, CodeWarrior for Palm OS Release 5 with Metrowerks' two updates + applied). + +* Fixed the way time spent in the trap dispatcher was recorded when + profiling; entries for the same function weren't necessarily being + collapsed into a single entry. [Bob Ebert] + +* (Unix) Added JPEG case graphics. + +* (Windows) Added taskbar menu with Minimize/Move/Close menu items. + Note that there may still be problems with minimizing/maximizing + Poser. For instance, Windows NT does not minimize windows without + caption bars when you select "Minimize All Windows". Windows 98 + will hide Poser when selection "Show Desktop", but will restore + Poser when restoring another application window. These problems + appear to be shortcomings of Windows, but if anyone knows how to + accomodate these foibles, please let me know. [Scott Johnson] + +* More accurate emulation of ROM space. Now the chip-selects are + used in conjuction with the ROM image file size. [Steve Lemke, + Jesse Donaldson] + + In general: + + The size of the ROM image is always rounded up to the next power of + two. + + On Dragonball devices, I assume that the chip-selects are always set + to specify a 2 Meg ROM (this appropriate for all ROMs so far). On + DragonballEZ devices, I look at csASelect, bits 1-3 (BTW, the reset + value for this register is 0x00E0, so there don't seem to be any + boot-up issues). + + If the rounded ROM image size is larger than the size specified by + the chip-selects, then it gets truncated; the CPU won't be able to + access the far end of it. + + If the rounded ROM image size is the same as the size specified by + the chip-selects, then everything is fine. No truncating, no + mirroring. + + If the rounded ROM image size is smaller than the size specified by + the chip-selects, then the ROM image is mirrored for as many times + as is necessary to cover the range. + +* (Mac) Added Power Manager code to keep PowerBooks awake when Poser + is doing something and when the PowerBook is plugged in. [Mike + Puckett] + +* Ensure that windows (LCD, Gremlin Control) are onscreen when + they're created. Right now, this means that they are brought + onscreen if any part of them is offscreen. If this is too strict, + we can revisit the algorithm later. + +* The code to validate the objects on a form has been moved from + Gremlins-specific code into a patch on FrmDrawFrom. Now people will + get bugged about invalid objects even when not running Gremlins. :-) + + By the way, some people have reported that they get told about + invalid or offscreen form objects, and that they think these reports + are in error, as the objects reported have ludicrous positions and + sizes and have object IDs that don't exist in the resource + description file. If you get such a message, *strongly* suspect + that your object list has been trashed, possibly due to the changing + of a label or title. Eventually, Poser will be able to detect when + form object lists get trashed at the moment it occurs, and not later + on down the stream (such as when the form gets drawn). + +* When dragging files onto the LCD screen, the rules are: you can + drag any number and assortment of .prc, .pdb, and .pqa files; you + can drag only one .rom file, you can drag only one .psf file; you + can't mix files from any of the three just-mentioned categories + together. If you broke any of these rules, you'd get an error + message. However, this error message was broken in different way on + Mac and Windows (the Unix version doesn't support D&D yet -- any + takers?). This was fixed by making the majority of the relevent + code cross-platform, and then fixing *that*. [Roger Flores, Mike + Turcotte] + +* (Mac) Fixed problem with Japanese text showing up as "Jinglish" on + systems with the Japanese Language Kit installed. This was always + supposed to be a feature in the New Gremlin dialog (so that you + could see the application names correctly), but appears to have been + broken for some time. That should be fixed, and the same facility + has now been extended to the dialog containing error messages + generated by the Palm OS. [Ken Krugler] + +* Fixed bug in NetLibGetHostByAddr where the address was assumed to be + a NetSocketAddrType instead of anything that could be "len" bytes + long. [Bill Pittore] + +* Turned on checking of writes to ROM. This was off for a reason + (there's a comment next to the relevent part saying "HACK: We really + want it to be true!"), but I don't remember what it is. I was able + to run Gremlins on some apps for quite a while without error, so + hopefully we can get away with turning this back on. [Scott Johnson] + +* Take another stab at fixing the problem with FntDefineFont, as first + described in the release notes for 2.1d20. FntDefineFont can read + off the end of a source buffer, causing Poser to report an invalid + read access to memory manager data structures. This bug -- fixed in + Palm OS 3.2 -- doesn't need to be alerted by Poser. [Scott Johnson] + +* If an application executes DbgBreak and no debugger is attached, + display a friendly message in a dialog box that includes Continue + and Reset buttons. [Ken Krugler] + +* Added Red Dutta's "Export Database" menu item. This command takes + the place of the "posedbexport" Palm OS application, allowing you + to export databases and applications from the emulator to your + desktop computer as a .pdb or .prc file. [Red Dutta] + +* Patch SysReset so that Poser no longer complains about normally + proscribed actions (like mucking with low-memory) during a reboot. + +* Bring us in-sync with the Simulator with regards to entering + control-chars that map to Palm OS command-chars. The list is: + + control-A menuChr + control-B lowBatteryChr + control-C commandChr + control-D confirmChr + control-E launchChr + control-F keyboardChr + control-M linefeedChr + control-N nextFieldChr + control-S autoOffChr + control-T hardContrastChr + control-U backlightChr + + B, S, T, and U are new in this release. + + +Changes for 2.1d29 (1999-07-08) +------------------------------- +* Interim internal release dates: + 2.1d28.1 - 1999-06-04 + 2.1d28.2 - 1999-06-04 + 2.1d28.3 - 1999-06-11 + 2.1d28.4 - 1999-06-11 + 2.1d28.5 - 1999-06-11 + 2.1d28.6 - 1999-06-15 + 2.1d28.7 - 1999-06-16 + 2.1d28.8 - 1999-06-23 + 2.1d28.9 - 1999-06-25 + 2.1d28.10 - 1999-06-30 + +* For temporary backward compatibility, "bare" file names on the + command lineare treated as paths to .psf files. [Andreas Linke, Mike + McCollister] + +* (Mac) Fixed problem with receiving Error #18 when trying to download + ROMs from actual devices over the serial port. [Mark Ordal] + +* In debugger/sockets communications, allow for recv() returning + zero, indicating a closed connection. + +* Fixed multi-threading bugs. [Andrew Ball, Daniel McCarty, Scott + Johnson, Keith Wolcott, Art Dahm, Mark Lussier, Alex Robinson, + Patrick Porlan] + +* (Unix) Fixed some makefile problems. [many] + +* (Mac, Windows): new case graphics. Note that the edges of the new + graphics are a little rough; we'll be working on that for the next + release. Also, the Mac version doesn't set up a custom palette in + 8-bit mode, yet, so for best results, you might want to put your + monitor in 16- or 24-bit modes. Finally, the Unix version will get + the new graphics in the next release. + +* Print some logging information using signed instead of unsigned + value. [Oliver King-Smith] + +* Don't go into infinite recursion when the emulated PC is set to an + odd memory address. [John Marshall] + +* Fixed problem in the "NetLib redirected" version of + NetLibSocketAccept where the address and address length were not + returned. [Bill Pitore] + +* (Windows) As outlined in the notes for 2.1d28, Poser will look for + the last-saved .psf file when starting up. It used to save the + reference to this file as a full pathname. Now, if the attempt + to locate the file with the full pathname fails, Poser will look + for a .psf file with the same name in the same directory as + Poser itself. This approach is similar to the way in which + Poser looks for .ROM files that are no longer at their last known + location. [Michael Hado] + +* Worked around VC++ 6.0 bug where tabbed dialogs in applications + built by it won't show up on systems without IE 4.x installed. + [Michael S. Davis] + +* (Unix) Fixed a minor bug in skin loading code which causes Emulator + to crash when it tries to load a skin file from current directory. + [Vlad] + +* Set the command key bit when Gremlins posts an up or down arrow. + + +Changes for 2.1d28 (1999-05-21) +------------------------------- +* Interim internal release dates: + 2.1d27.1 - 1999-05-17 + +* (Windows) Added command line options: + + -psf <filename>: emulator loads the specified .psf file on startup. + + -rom <filename>: specifies the ROM image file to use. + -ram <size>: specifies the amount of RAM to emulate (in K). Valid sizes + are 128, 256, 512, 1024, 2048, 4096, and 8192. + -device <type>: specifies the device to emulate. Valid types are pilot, + palmpilot, palmiii, palmiiix, palmv, palmvii, and palmiiic. + -silkscreen <type>: 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 (1999-05-07) +------------------------------- +* Interim internal release dates: + 2.1d26.1 - ??? + 2.1d26.2 - ??? + 2.1d26.3 - ??? + 2.1d26.4 - 1999-03-25 + 2.1d26.5 - 1999-04-01 + 2.1d26.6 - ??? + 2.1d26.7 - ??? + 2.1d26.8 - 1999-04-27 + 2.1d26.9 - 1999-04-29 + 2.1d26.10 - 1999-05-05 + +* 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] + +* (Mac) Added support for Escape, F1-F4, page up/down. + +* 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 + inconsistent 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 occurred 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. + +* (Windows) Allow multiple .prc file selection in the Open File dialog. + +* 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 occurred, 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." + +* (Windows) Fixed problem with running on dual-processor boxes. [TBD] + +* There is now a "white paper" on Poser usage at the following URL: + + <http://www.palm.com/devzone/docs/pose.htm> + + +Changes for 2.1d26 (1999-02-26) +------------------------------- +* 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] + +* (Windows) Added conditional breakpoints. This is bolted on for now, + but should eventually be merged more seamlessly. 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 "<register> <condition> <constant>", + where + + <register> is one of the 68000 registers D0...D7 or A0...A7 + <condition> 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). + <constant> 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 (1999-02-16) +------------------------------- +* 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] + +* (Mac) Added WDEF project to 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] + +* (Windows) Centered the LCD. [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: + + <Time> <Gremlin Event> <Text> + + <Time> is the zero-based time in seconds, where the base is the time + of the first event logged. + + <Gremlin Event> is the event sequence number if Gremlins is running. + This field is omitted if Gremlins is not running. + + <Text> is the log text. Output is generally one line long, with the + major exception being hex dump information. + +* Allow more concurrent tailpatches. Previously, there was a fixed + number of traps that could be tailpatched at once. Exceeding this + limit would cause Poser to abort(). + +* Allow one particular SecurityLib function to access low-memory. + [Gavin Peacock] + +* Implemented HostSetLogFileSize. Increased default log size from + 128K to 1Meg. [Dan Rowley] + +* Support netSocketOptSockNonBlocking in NetLib redirection. Also + support the UDP calls (NetLib[Send|Receive](PB) with non-NULL + address specifications). With these changes, Windows users can now + Network HotSync. [Tilo Christ] + + Here's now (this is for Palm III): + + - Get the Network HotSync files from: + + <http://www.palm.com/support/downloads/netsync.html> + + - Run "nhssetup.exe" to extract "setupex.exe". + + - Run "setupex.exe" to install Network HotSync. + + - Fire up Poser. + + - Install "netsync.prc". There will be one in your ...\Palm + Desktop\ <UserName>\Install\ directory or your ...\Palm + Desktop\add-on\ directory. + + - Go to the HotSync application. + + - Select the "LANSync Prefs..." menu item. + + - Select the "LANSync" option. Click on "OK". + + - Select the "Primary PC Setup..." menu item. + + - Enter your Primay PC's IP address. You can get this from the + HotSync Manager (click on the HotSync icon in the TaskBar, + select the "Setup..." menu item, click on the "Network" tab, and + click on the "TCP/IP Settings..." button). Click on "OK". + + - Click on the "Select Service" button under the "Modem Sync" icon. + + - Create a new service or modify an existing one. Either way, the + result should be a service with the phone number set to "00". + Exit that screen. + + - Click on the "Modem Sync" icon and sync as usual. + +* (Mac) Additional note on NetLib redirection: currently, support + is implemented with the help of the GUSI library. This library is + built on top of MacTCP, which doesn't support the settting or + getting of socket options. Any call to NetLibSocketOptionGet or Set + will result in an error on the Mac. Eventually, emulation will be + performed with direct Open Transport calls, and this limitation will + go away. + + In the meantime, this limitation affects the ability to Network + HotSync from Poser runningon the Mac to HotSync running on a PC. + +* Fixed a long-standing 2.1dx bug where the screen would not always + reflect the state of the LCD buffer. One way this could happen is + if the screen were modified in a strictly high-memory to low-memory + order (as happens when a document is scrolled down). + +* (Windows) Fixed byteswapping problem in the addresses returned by + NetLibGetHostByName. [Pedro Alves] + +* The text file dumped by the profiler always used to be named + "Profile Results.txt" and would be written to the current default + directory. Now the file name is based on the file name used for the + binary output and is stored in the same directory as it. This is + mostly useful if the output file name is specified by + HostProfileDump (). [Steve Haneman] + +* While running Gremlins, validate the sizes of various form objects. + [Chris Antos] The rules are: + + * frmBitmapObj, frmLineObj, frmFrameObj, frmRectangleObj, + frmLabelObj, frmTitleObj, frmPopupObj: Don't care. We don't + touch them or look at them. + * frmControlObj: if the style is popupTriggerCtl, allow a + zero-width object. + * frmListObj: if the number of items is zero, allow a zero-height + object. + * In all other cases, disallow zero-height or zero-width objects, + as well as objects completely offscreen. + +* (Windows) Added mnemonic keys to the menus and dialogs. [Scott + Johnson] + +* Adjusted the internal rectangle indicating the bounds of the hard + buttons on the case graphics, now that the case graphics have + changed. [Horace Ho] + +* Enable storage heap write access in our NetLib-redirected version + of NetLibDmReceive. [Neil Rhodes] + +* Turned back on the checks to see if someone accesses the area from + 0x00018000 to 0x00020000. [Adam Dingle] + +* Added Japanese color silkscreens (no B&W yet). + + +Changes for 2.1d24 (1999-01-25) +------------------------------- +* Yow...time to start updating those copyright statements... + +* Fixed performance problems with logging (this really affected + Gremlins performance). [Andrew Ball] + +* Made small change to heap tracking routines; this change really + speeds up overall performance. A lot of performance tuning still + needs to be done here. [Scott Johnson] + +* NetLib redirection. [Phil Shoemaker, Ron Marianetti] + + Here's the current list of what doesn't yet work: + + Raw sockets (not on the Mac at all, works on Windows only if + your version of WinSock supports it). + + PalmOS-specified options: + netSocketOptSockNonBlocking + netSocketOptSockRequireErrClear + netSocketOptSockMultiPktAddr + + BSD sockets options that are not supported by "NetLib redirection" + because the underlying WinSock library doesn't support them: + netSocketOptTCPMaxSeg + netSocketOptIPOptions + netSocketOptSockSndLowWater + netSocketOptSockRcvLowWater + netSocketOptSockSndTimeout + netSocketOptSockRcvTimeout + + Timeouts + + NetLibGetMailExchangeByName + + UDP stuff + + Turning NetLib redirection on and off on the fly. It might be + safer to change the setting, then quit and restart Poser (or at + least reset the ROM). + + MacTCP doesn't appear to timeout if it can't make a connection + to a socket on a remote machine that isn't listening on that + socket. There may be other cases where MacTCP doesn't timeout + or return some other error. In those cases, the PalmOS application + will hang. You should be able to press Cmd-. to get out of those + situations, causing the patched NetLib to return a user-cancelled + error number. + + Comments on how NetLib redirection works: Poser has the ability + to intercept process execution at the points where an OS function + is called and where the OS function returns. Poser can then + execute additional code at these points, and can even skip + calling the ROM version at all if it wants. That's what happens + with NetLib redirection. The following calls are intercepted + and replaced with versions that make the corresponding host- + specific Ethernet calls: + + NetLibClose NetLibConnectionRefresh + NetLibDmReceive NetLibFinishCloseWait + NetLibGetHostByAddr NetLibGetHostByName + NetLibGetMailExchangeByName NetLibGetServByName + NetLibHandlePowerOff NetLibOpen + NetLibOpenConfig NetLibOpenCount + NetLibOpenIfCloseWait NetLibReceive + NetLibReceivePB NetLibSelect + NetLibSend NetLibSendPB + NetLibSleep NetLibSocketAccept + NetLibSocketAddr NetLibSocketBind + NetLibSocketClose NetLibSocketConnect + NetLibSocketListen NetLibSocketOpen + NetLibSocketOptionGet NetLibSocketOptionSet + NetLibSocketShutdown NetLibWake + + Because NetLibOpen (and its cousins) is entirely patched out, the + Palm OS version of NetLib never actually gets opened. This means + that the remaining, unpatched NetLib calls are made in the context + of a closed NetLib. I don't know if this differenc will affect + anyone, but it might be good for you to know. + + Comments on Palm VII supprt: Palm VII files are not yet externally + available. But Poser is preparing for that day, so when they *are* + available: + + Download the prerelease Palm VII rom and the required Debug + wireless panel which will configure the emulated OS so that + it knows you're not on a wireless device. + + To configure: open the ROM with the Palm OS Emulator, wait + until it has completed the boot process, and install the debug + wireless panel by dragging the prc onto the running emulator + window. Now open the Prefs application and go to the "Wireless" + panel. You'll see a box there entitled "wireline ip". Tap on + it, clear the existing selection, and enter "207.240.80.136". + Finally, open the preferences for the Palm OS Emulator itself + (right-mouse click under Windows), and turn on the "Redirect + Netlib calls to host TCP/IP" option. + + Now when you use a PQA, it will connect to the web site with + your PC's internet connectivity instead of a wireless radio. + (Warning: it is much faster that way! Pages will load much + more slowly when transmitted over the air.) Also, there may + be warnings where the Emulator notices possible bugs in the ROM. + Usually these are benign (but indicate the prerelease status of + the ROM) - pressing "continue" will usually get you by them. + + You can install PQAs by dragging them onto the Emulator window, + or using the Emulator's menu commands. Just make sure you're + neither in the Launcher when installing an application, nor + running the app you're upgrading. (Installing software while + the device is booting is also a bad idea.) The Calculator is + a convenient, safe app to be in when installing software. + + Note that if your PC is behind a firewall, you might not be able + to connect to our proxy server. Ask your system administrator to + enable port 5002 for you. + + If you get an error message along the lines of "no interfaces + found: net - 12", that's an indication that you didn't select + "Redirect NetLib" in the preferences panel. Getting the error + message "wrong socket type" is an indication that you didn't + install the DgbWirelessPnl application. + + +* More fixing of semaphore warnings: duh, changing the text of the + warning message doesn't change the test itself! [many...] + +* Made .prc/.pdb file loading more robust: the contents are now + validated before accessing them. This helps against problems + like 0x0A's turning into 0x0D's because of network downloading. + +* (Windows) Fixed byteswapping problem that would occur when gdb + tried to set a breakpoint [Ben Thomas]. + +* (Mac) Fixed problem with getting 'Could not save the file "" + because the file wasn't found' when trying to save a session. + [???] + +* Palm OS 1.0 support: Gremlins and pen events weren't being + inserted into the system because EvtGetSysEvent blocked on + SysSemaphoreWait instead of SysEvGroupWait in that version + of the OS (we were only patching the later to detect when + to insert events into the system). Now I patch both functions. + [Andrew Ball, Ken Hancock] + +* Set HotSync user name at boot-up. Name specified in preferences. + [Richard Ziegelmaier, et al] + +* Check for and report for out-of-range access to library functions. + +* The workaround for SysAppExit in d22 was hiding the workaround for + FindSaveFindStr from d20. Adjusted the tests so that one no + longer hides the other. [Matt Disher] + +* Exposed Palm VII and Web Clipping support in external release. + +* (Windows) Fixed a problem in the mechanism for exchanging debugger + information with the Metrowerks debugger. This problem could + potentially cause debugger packets to be ignored. However, there's + no evidence that this is the cause of the "Failed to connect to + remote" problem that some people are still reporting with R5. + [Ben Sessoms] + +* When handling SysPktRtnNameCmdType packets, force the given address + to be even. Otherwise, we'll generate an internal error as we try + to walk the function starting at an odd address. [Ben Sessoms] + +* Fixed long-standing bug that would crash the New Gremlin dialog if + the last item in the list had a ROM-based version and a RAM-based + version. + +* Sort the items in the New Gremlin dialog case-insensitively. + +* Added support for launching applications with documents. [Gavin + Peacock] + +* Updated bitmaps. [Ken Krugler, Stephen Best] + +* Fixed problem with getting a "yadda accessed memory manager data + structure" while dumping the results of profiling. [Adam Dingle] + +* Removed most (hopefully all) influences of Poser's memory + accessing and ROM function calling from the profiling output. + +* Fixed the profiler to handle TRAP $F / <dispatch number> sequences + where <dispatch number> is not in the range 0xA000-0xAFFF (some + development systems leave off the leading "A"). [Adam Dingle] + +* Bumped the default number of profiled functions from 20000 to 48K. + [Steve Haneman] + + +Changes for 2.1d23 (1998-12-16) +------------------------------- +* (Windows) fixed some byteswapping problems with debugger packets. + (Actually, put *back* some bugs that I fixed...) + +* Re-organized sources. + +* Added ability to patch libraries. Started patching out NetLib. + Note that there is no actual NetLib redirection in this release. + +* Fixed some serial port emulation problems: mirrored UART settings + into the host serial port just after the port has been opened, not + after the first call to SerSetSettings (there may *not* be a call + to SerSetSettings!). + +* Generating a profiling report now also produces a text file for + use on platforms that can't read the Metrowerks Profile tool + file format. + +* (Windows) Added profiling configuration. + + +Changes for 2.1d22 (1998-12-07) +------------------------------- +* Only warn about MemSemaphore usage on ROMs that themselves hold the + memory semaphore correctly. This time for sure! Also only warn + when the semaphore has been held for 1 minute (previously, the + timeout was 10 milliseconds). + +* Completely overhauled serial port emulation. More of the UART is + emulated more faithfully. + +* If no serial port is selected for emulation pass through and we're + not in loopback mode, drop transmitted bytes on the floor. + +* If IrDA is using the serial port, drop transmitted bytes on the + floor (for now). + +* Re: SysAppExit accessing a deleted stack: SysTaskDelete and a whole + host of other functions also access the deleted stack until the + kernel has a chance to switch to another stack. Much gnashing of + teeth was performed until an appropriate alternate heuristic could + be found. + +* Let PrvCompressedInnerBitBlt access bits outside the allocated + buffer. + +* (Windows) Fixed problems with Cancelling a ROM download. + +* Another attempt at fixing -192 errors at startup. + +* (Mac) Fixed problem with opening two windows when starting a session + by double-clicking on a ROM file. + +* (Mac) Goosed debugger messaging. Previously, an asynchronous + callback function would get called when Poser received a packet from + the debugger. The callback function would set a boolean and then + call a Toolbox function to wake up the application. The next time + the application's main-event-loop was entered, the packet would be + handled. However, the overhead of waking up the app and waiting for + the main-event-loop to be entered was way too high. I now handle + the debugger packet immediately in the asynchronous callback + function. This means that the debugger packet is handled in the + context of the calling application (the external debugger). If + Poser were to crash at this point, it would crash the debugger, not + Poser. Additionally, we have to be very careful not to allocate any + memory from within the callback, as such memory would be allocated + from the debugger's heap, not Poser's. + +* Changed some of the rules for interacting with an external + debugger. + + In order for an external debugger (PalmDebugger, MWDebug, or gdb) to + talk with a hardware device, the hardware device has to be + listening. There are two things a debugger can talk to: the Debugger + socket and the Console socket. These two sockets correspond to the + two windows in the PalmDebugger. + + To get the ROM to listen on the Console socket, the developer has to + execute shortcut-.2. To get the ROM to listen on the Debugger + socket, the device has to cause an exception somehow. Doing + something wrong (e.g., access invalid memory, divide by zero, etc.) + does this. Executing a DbgBreak also does this, which is what + happens when the user executes shortcut-.1. After the exception + occurs, the ROM goes into a loop where it listens for and responds + to debugger commands. + + Because external debuggers talk directly with Poser and not the ROM + when debugging with Poser, there's no need to execute shortcuts or + cause exceptions in order to start debugging. Poser is perfectly + capable of handling debugger requests, letting the emulated process + continue on its merry way. + + However, when dealing with commands sent to the debugger socket, + it's very important that the state of the emulated CPU not change. + Often several commands are issued, ultimately ending with some + command that restarts the emulated CPU. During these exchanges, the + debuggers assume that the state of the CPU has not changed since + "debug mode" was entered. For this reason, when commands are sent + to the Debugger socket: + + - Poser needs to be in "debug mode". That means that it has + halted any emulation and is just idling. If commands for + the Debugger socket come in and Poser is not in debug mode, + the commands are ignored. + - The exception to this rule is the "get state" Debugger + command. This command is issued when the user types "att" + in the Debug window. It indicates that the user wants to + enter debug mode for the purpose of setting breakpoints, + examine memory, etc. As a courtesey, Poser will enter + debug mode when it sees this command. + +* Install a 'pose' feature so that applications can tell if they are + running under Poser or not. + +* Install a 'gdbS' feature when connected via a socket to an external + debugger. The existance of this feature causes programs written + with prc tools to enter the debugger when they are launched. + +* (Windows) Removed a minimum version check that was preventing us + from using sockets on Windows '95. + + +Changes for 2.1d21 (1998-11-12) +------------------------------- +* Allow for NULL access bug in FldDelete. + +* (Windows) Allow for launching of Emulator by double clicking on + .psf or .rom files. + +* Added back a whole slew of strings accidentally deleted in d20. + + +Changes for 2.1d20 (1998-11-10) +------------------------------- +* Support full debugger protocol for latest PalmDebugger (with + integrated Poser support). + +* Fixed button mapping problems with EZ hardware. + +* Added Greg's Ymodem code for downloading ROMs. This includes his + fix for high-baud rate downloads. + +* Support for higher baud rates. + +* Re-establish serial port after Preferences/Properties dialog. + +* Allow for access to deleted stack in SysAppExit. + +* Allow for bug in NetPrvTaskMain that accesses low-memory. + +* Allow for bug in NetPrvSettingSet that reads from a random memory + location. + +* Tighten up on some inappropriate memory checks (only let some + functions get away with murder in older ROMs). + +* Removed check for bug in PrvGetBatteryPercent (it's been fixed). + +* Changed formatting of time displayed in Gremlins window. Was in + seconds, now in hh:mm:ss. + +* Revoked Memory Manager privileges for MemCmp, MemMove, and MemSet; + they no longer have free run of RAM like other MemMgr functions. + +* Allow for bug in FindSaveFindStr which reads off the end of the + handle passed to it. + +* Similar comments for FntDefineFont. When copying the contents of + an old, smaller buffer into a new, larger buffer, it copies the + size of the new buffer, causing MemMove to walk off the end of the + old buffer. + +* Let ScrInit access unallocate memory for when it copies the splash + screen from its temporary location to the real LCD buffer. + +* Re-enabled code that reports a bug in BackspaceChar, but only for + newer ROMs. + +* Internal change: Better encapsulation of what Palm OS bugs are + fixed in what version. + +* Only warn about MemSemaphore usage on ROMs that themselves hold + the memory semaphore correctly. + + +Changes for 2.1d19 (1998-10-30) +------------------------------- +* (Windows) Fixed problem with trying to auto-reload the previously + used .psf file on startup. + +* (Windows) Allow the user to click on the close box of the Startup + dialog (the one saying New/Open/Download/Exit). + +* Fixed two problems with heap management on 2.0 ROMs. First, I was + failing to recognize the fact that zero in the size field of a heap + header means that the heap is 64K bytes long. Second, I was + attempting to access *all* fields of the terminating sentry chunk. + This chunk only has a size field; attempts to access subsequent + fields may fail if the sentry is at the end of RAM. + + +Changes for 2.1d18 (1998-10-29) +------------------------------- +* Disabled Profiling menu items and Transfer ROM menu item until + the functionality behind those items can be implemented. + +* Added "Dragonball EZ" menu item to device list. + +* (Windows) Fixed problem with stale reference to the LCD window after + its been closed. + +* Fixed problem in MC68EZ328Bank::GetLCDDepth where it would return 4 + for grayscale mode instead of 2. + +* (Mac) Fixed problem getting -192 error on startup with a fresh + set of preferences. + + +Changes for 2.1d17 (1998-10-28) +------------------------------- +* Fixed bug in Gremlins when logging information; an internal counter + would wrap to be negative after a large number of events have been + posted. + +* Re-laid out Debug Options dialog and hooked up the checkboxes. + Disabled the ones that aren't supported yet. + +* (Windows) Fixed another "Unhandled exception caught in main" bug: + this one would occur when the Poser would try to open a .psf file + that no longer existed (the previous cause of this bug occurred + when Poser would try loading a .rom file that no longer existed). + +* (Windows) Remove old registry entries when found. + +* When an error occurs accessing a file, consistantly set the + %filename parameter for error messages. + +* Added "Log error messages" checkbox to New Gremlin dialog. + +* Save Gremlins settings to preferences. + +* Fixed bug in meta-memory tracking stuff that would trash the + emulator's heap if it was emulating a device with 256K of RAM + or less. + +* Clear the serial FIFO queues on reset. Fixes a problem with their + overflowing and serial port emulation is not turned on (that is, + "None" is selected in the Preferences/Properties dialog). + +* Fixed problems with trying to use "&string_object[0]" on empty + strings. Apparently, there is not necessarily any memory + allocated for empty string objects, so attempting to take the + address of the string fails. + + +Changes for 2.1d16 (1998-10-22) +------------------------------- +* Allow the opening of locked .rom, .psf, .prc, .pdb, and .pqa files. + +* Updated TextMgr calls to reflect new (long) parameters. + +* Added Autoload facility. + +* Fixed problem with trying to wakeup the device (by calling + EvtWakeup) when the interrupt level mask was too high. + + (Backed this modification out temporarily. Seems that the ROM can + spend a large percentage of its time at this interrupt level if + it's not doing anything else useful, preventing the user from + clicking on the LCD screen.) + +* Conditionalized the code so that Palm VII, Palm V, and Palm IIIx + could be included or excluded separately. + +* Conditionalized *this* file so that secret stuff can be stripped for + external releases. + +* Fixed the "Save Screen" functions (I'd commented them out while + adding support for lcdPageWidth and lcdPanningOffset registers and + forgot to go back and clean up). + + +Changes for 2.1d15 (1998-10-15) +------------------------------- +* Bug fix: my wrapper function for TxtGetCharBounds was accidentally + calling TxtGetNextChar (copy & paste error). + +* Bug fix: the routine that maps a range of "host" memory into + "emulated" memory would round the base address down to the nearest + multiple of four, but the routine that would reverse the process + didn't do the same rounding. This meant that the routine that + unmapped would be unable to find the address recorded by the routine + that did the mapping, and entries would never get unmapped. + +* Bug fix: if Poser reads in a preference setting for a Japanese + silkscreen and that version of Poser doesn't support Japanese + silkscreens, change the setting. Otherwise we'd get a -192 + (resource not found) error. + +* Relaxed MemSemaphoreReserve/Release testing. Now only track time + when "write" parameter is true. + +* Bug fix: allow debuggers access to reserved parts of Dragonball + memory. + +* (Mac) Show errors in a movable modal dialog, allowing the user + to switch to the Finder, possibly for the purpose of launching a + debugger. + +* Allow selection of multiple items in New Gremlins dialog. These + items are also reselected when the dialog is re-opened. + +* Added HostGremlinNumber, HostGremlinCounter, HostGremlinLimit. + + "The reason I'm asking is that I'd like to log info to figure out + what's going wrong with a specific gremlin test case, but since + it's pretty far along (e.g. 100000 steps) I only want to start + logging when I'm getting close to where I think the problem will + occur. The problem occurs after a different number of steps + depending on the gremlin seed value, thus I'd like to set my + 'start recording' value based on which gremlin is running." + +* Added HostLogFile. This function returns a special HostFILE* that + can be used by Palm OS applications that want to write to the same + file that any Poser facility is writing to. This HostFILE* is + special in that it is only open when Poser wants it to be, and is + write-only; any HostFxxx functions that attempt to read from + HostFILE's will fail when fed this HostFILE*. + + Output occurs only when Poser has turned on logging. If the + Palm OS application calls something like HostFPrintF(hostLogFile, + "...", ...) and logging is not turned on, the output is discarded. + +* Added HostSetLogFileSize. This function sets the maximum amount of + text written to the file created by Poser's logging facilities. + +* If Gremlins is running and a message needs to be displayed that can + be handled by clicking on a Continue button, write that message to + a log file instead and implicitly click on the Continue button. + +* If Gremlins is running, turn off the facility that causes the user + to be warned only once of certain kinds of errors (that is, the + error will be logged to the file every time). + +* In the logging output file, add a comment that only the last xxxK + of information is recorded. + + +Changes for 2.1d14 (1998-10-01) +------------------------------- +* Added Japanese silkscreens, and support for selecting them. + +* (Mac) Added "None" menu item to serial port menu. + +* Added support for lcdPageWidth and lcdPanningOffset registers. + +* Fixed bug with power-off (I wasn't allowing HwrSleep to change some + low-memory vectors, resulting in a warning dialog). + +* Check for and report heap corruptions. Poser walks the heap + regularly, usually to sync up its notion of where things are with + the Palm OS Memory Manager's. These walks used to be vulnerable to + corrupted heaps. Now they should be more robust. + +* (Mac) Updated to CodeWarrior Pro 4. + +* Instead of patching ErrDisplayFileLineMsg and showing its text in + our own dialog, let the ROM version execute. It will eventually + call SysFatalAlert, which we patch for the same reason (to show the + text in our own dialog with our own buttons). + +* Added stack overflow checking. On all opcodes changing the stack + pointer (PEA, MOVE, MOVEM, JSR, and any opcode operating on a + register with pre-decrement mode), I check the stack pointer to see + if it's (a) close to the end of the stack or (b) past the end of the + stack. The former gets a warning, the latter gets an error. + +* Initialize new RAM to 0xFF (make it look like new flash RAM). + +* (Windows) Fixed "Unhandled exception caught in main()" error message. + This would show up when the previously-used ROM file could not be + found. Now, the (slightly) less enigmatic message "Could not start + a new session because the file could not be found" is displayed. + More importantly, Poser no longer quits after displaying the message. + +* Added check for how long the Memory Manager semaphore was held. + Show a warning if held for more than 10 milliseconds. + +* Fixed problem with multiple Gremlin Control windows appearing in + the windows version. Doh! + +* Made the "Release" target an "External Release" target, and added + an "Internal Release" target. + +* Added support for loading clippings. + +* Made a change that should take care of accesses to invalid memory + from an external debugger. + + +Changes for 2.1d13 (1998-09-15) +------------------------------- +* Fixed bug in heap validation functions; when I extract the *signed* + hOffset value, I have to sign extend it from 24-bits to 32-bits. + +* Mark more parts of memory as memory manager data structures. + +* Support hardware sub-ID for EZ devices. + +* Support HwrIdentifyFeatures for 68328 devices. + +* Enable flash for Palm V and Palm IIIx. + +* Fixed long-standing Gremlins bug that would cause event pushing to + stop after a while (the Gremlin mechanism would enqueue and event + and then wait for it to be handled; however, in some cases, the + event would fail to be enqueued, and the Gremlin mechanism would + wait forever for that event to be handled). + +* Allow for a bug in SysBinarySearch in pre-3.0 systems that would + cause it to pass an invalid pointer to the search callback. + +* Added Gremlins Control window (displays gremlin number, current + event number, and elapsed time; also contains Stop, Resume, and Step + buttons). + +* Tweaked Gremlins engine so that doing a Step doesn't reset the + "until" value. + +* Performance enhancements: + + - Changing some functions to return "int" instead of "bool" + resulted in better code generation, leading to a 7% performance + boost in my canonical Gremlins test (Gremlin #0, 10000 events + on the Memo Pad). (Actually, this was only a win in VC++; + CodeWarrior worked better with "bool". Therefore, all of the + sources were changed to use "Bool", which is typedeffed to + "bool" or "int" depending on the compiler being used.) + + - Putting back an enhancement from Craig's Mac Copilot lead to a + 27% performance boost. The idea is to update only the scanlines + that are changed since the last screen refresh. Craig did it by + carefully comparing the current LCD buffer with a saved version + of it. I now do it instead by noting when the LCD buffer is + being written to (this is done fairly efficiently via the + MetaMemory tracking routines) and remembering the first and last + bytes in the LCD buffer that were written to. + +* Fixed trap number used in HostControl.h. + +* Updated to latest CharEncodingType values from TextMgr.h. + + +Changes for 2.1d12 (1998-09-02) +------------------------------- +* EmuTraps -> HostControl. + +* Let PrvFindMemoryLeaks walk the heap. + +* Added HostGetEnv. + + +Changes for 2.1d11 (1998-08-31) +------------------------------- +* Added support for AMD flash RAM. + +* (Windows) Fixed support for external debugging. + +* (Windows) Display dialog if an exception is caught in WinMain. + +* (Windows) Fixed the way the Dragonball(EZ) registers were + initialized. After things got going, the registers were OK, but the + initial values on little-endian machines was completely bogus. + +* (Mac) Updated creator resource text. + +* Totally revamped the way memory access checking is performed. In + addition to detecting access to low-memory, system globals, the + screen buffer and Dragonball(EZ) registers, I validate access to the + dynamic heap. Now, only the Memory Manager can fiddle with chunk + headers and trailers, free chunks, and unlocked chunks. For the time + being, low-stack access is no longer detected, though this feature + will return. Eventually, we should also be able to detect access to + uninitialized memory. + +* Updated to latest sysFtrNumXXX values. + +* Fixed test for Intl Mgr in gremlins. + +* Test for NULL in stub Intl Mgr functions. + +* I now calibrate the pen before running a gremlin. This is + necessary for consistant results between different runs across + boots. + +* Fixed error reporting problem where previous messages reported in + dialogs would inhibit other messages from appearing (that is, the + attempt to display a second message would end up showing the first + error message again). + +* Handle errant accesses to Dragonball space past the end of the last + defined register. + +* Check for and report unimplemented traps. This check detects + attempts to call functions that are off the end of the trap table as + well as calls to SysUnimplemented. + +* Internal change: consolidated more error handling in the Errors + class. Cleaned up the Errors interface a little bit. + +* Added temp hack to let PrvGetBatteryPercent read off the end of an + allocated chunk of memory. + + +Changes for 2.1d10 (1998-08-18) +------------------------------- +* Display correct error message if a low-stack access is performed (I + was previously re-using the "screen buffer access" message). + +* Low-memory access by the ROM was previously allowed up until + UIInitialize was called. That's been changed to TimInit. + +* Consolidated some "device" menu items in the New Session dialog, + and added a new device. + +* Per Steve and Roger, changed some function names in EmuTraps.h. + +* Added Control Panels to the list of applications in the New Gremlin + dialog box. + +* Added support for DbgMessage. + +* Internal change: Roger Flores Memorial Constant Eradication. Got + rid of a lot of constants in EmuTraps.cpp and TrapPatches.cpp. These + constants were used to fetch parameters from the emulated stack + pushed on there by emulated code. I now define structs that + describe the stack contents and use those (with the offsetof macro) + to get the values. In addition to the obvious one, another + advantage is that the macros can now determine the _size_ of the + parameters and call get_long, get_word, or get_byte accordingly. + +* Rolled in more IK/Gremlin changes for Ken. + +* Double-clicking on an app in the New Gremlin dialog will implicitly + click on the OK button. + +* (Mac) Support Cmd-D in the "Save this file?" dialog (you guys owe + me!) + +* Mapped some internal error numbers to error strings. + +* Re-establish the interrupt state of any pressed buttons after a + reset. This allows you to press the Power key and Cmd/Ctrl-R, + resulting in a Hard Reset. + +* Asking for the 'irda' ROM token will now always fail (at least, + until we can get some IrDA support implemented). NOTE: the ROM + calls HwrGetROMToken directly, which means that it will not see the + effect of this patch. + +* Internal change: Platform::DisposeMemory now takes a reference to a + pointer so that it can set that pointer to NULL. + +* Use Platform::AllocateMemory and Platform::DisposeMemory in the + profiling code, so that it can use temp memory on the Mac. + +* EmuProfileDump now uses the name passed in to it. If NULL is + passed in, a default name ("Profile Results") is used. + +* Started on checking memory accesses to the dynamic heap that are + outside of allocated memory chunks. Not activated yet because (a) + it's too slow and (b) the hueristics aren't quite right. + +* (Windows) Fixed bug with not reporting errors that occurred + while initializing the emulator. Now you're notified if the serial + port you've specified in the Properties dialog is busy. + +* (Windows) Made the example in the previous bullet a warning, + not a fatal error. + + +Changes for 2.1d9 (1998-08-04) +------------------------------ +* (Mac) Fixed problem where the emulator would attempt to save the RAM + file with no name if "Save Always" were selected, the user chose + Quit from the File menu, and the RAM file was new (i.e., had never + been saved before). + +* Prevent the system from _reading_ low-memory if it's (a) not + sleeping or dozing, (b) fully booted, and (c) not handling an + interrupt. + +* Hooked up "Fill New Blocks" and "Fill Disposed Blocks". + +* Minor optimizations to DRAM_Bank accessors. + +* Rolled in Ron's changes for finding a function's name. + +* Detect and report accesses to the space below the stack pointer and + above the low-end of the stack. Note that there is no checkbox in + "Debug Options" for this, but performance timing shows that there is + very low overhead for this check (less than .1%). + + IMPLEMENTATION NOTE: detecting accesses to the unused parts of the + stack obviously entail knowing where the stack is. This information + is gleaned from the SysAppInfoType block when the application is + launched. However, there's no really good way to hook into the + launch process. There are advantages and disadvantages to every + approach, but the one used here is to hook into SysAppStartup and + SysAppExit. This works for applications that use the standard + runtime startup code, but applications are not guaranteed to use + that standard code. Hopefully, the percentage of such applications + is low. + + Additionally, SysAppStartup and SysAppExit are called under + circumstances other than starting up the application. For instance, + they are called when action codes are sent to each application. To + differentiate the two, we ignore all calls to SysAppStartup that + don't contain sysAppLaunchCmdNormalLaunch in the cmd field of the + SysAppInfoType block. + +* Hooked up "Clean Stack" check box. This option was originally + defined to overwrite the parts of the stack that were freed up by an + UNLK or RTS opcode in an attempt to detect accesses to those ranges + of memory. Since that's now handled by the previous "*", "Clean + Stack" now means that we initialize the part of the stack reserved + by LINK opcodes, thus initializing local variables to well-defined + bad values. + +* Fixed bug that occurred when setting a breakpoint on an opcode just + after a call to a system function that was tailpatched by the + emulator. + + +Changes for 2.1d8 (1998-07-29) +------------------------------ +* EmuGrmIsRunning (and SysGremlins) FINALLY returns a correct value + instead of just returning "true" all the time. + +* Implemented EmuDmLoadFile and EmuDmSaveFile. + +* EmuDmSaveFile now takes a card number as the second parameter. + +* Added parameter checking to all EmuXXX functions. Functions that + return EmuErrs will return emuErrInvalidParameter. StdIO functions + return error values according to the ANSI/ISO standard, and will set + errno to emuErrInvalidParameter (note that functions that alter the + return values of ferror and/or feof will NOT affect those value, + which is DIFFERENT from the standard). + +* Fixed bug when setting the current time on startup. This bug would + cause a crash on new Palm V ROMs. + +* Fixed bug with new Palm V ROMs when they tried to identify how much + memory was on the "device". + +* (Windows) Fixed problem where clicking OK in the Properties dialog + would crash the emulator under Windows 95 (and could possibly crash + Windows 95, too!). + +* (Mac) Fixed problem where the serial port name would get lost, + prohibiting the emulator from being able to open the serial port. + + +Changes for 2.1d7 (1998-07-27) +------------------------------ +* (Mac) Don't feed the ROM mouse/pen events if we've turned off + emulator execution at idle time. This prevents problems if a dialog + comes up while tracking the mouse/pen. + +* Fixed long-standing bug from Mac Copilot 1.3 days. The functions + GetRegisters and SetRegisters can be used to save and restore the + CPU registers. The emulator used those functions for just that + purpose when it would call ROM functions as subroutines. However, + the status register was not faithfully saved, which meant that it + was not always put back the way it was found. Since status bits + would then occassionally change spontaneously out from under the + emulated process, things would occassionally go "haywire" (that's a + technical term). + +* Value returned by EmuHostGetVersion is now based on the + application's version resource instead of being hard-coded. + +* (Mac) Save window position. + +* Implemented EmuHostIsSelectorImplemented. + +* Holding down the Ctrl key while booting/resetting will stop the ROM + at the start of the Big ROM by using a temporary breakpoint. + + +Changes for 2.1d6 (1998-07-23) +------------------------------ +* Changed way emulated apps called host functions. Those functions + used to be called by invoking TRAP $E. Now we latch onto the + SysGremlins trap number. + +* Extended set of host functions. + +* Zap some card header fields to say that we don't emulate flash RAM. + +* Fixed problem with profiling. + +* (Mac) Fixed an execution path where an untyped ROM file wasn't + getting its type set. + +* Fixed problem with stopping on A-Trap breaks. + + +Changes for 2.1d5 (1998-07-21) +------------------------------ +* (Mac) added version that does profiling. + +* Fixed loading of "whole" ROMs (those with Big ROMs and Small ROMs). + +* Fixed loading of .pdb files that have an AppInfo block but no + records. + + +Changes for 2.1d4 (1998-07-20) +------------------------------ +* (Mac) turned Open and Install menu items into hierarchical menus. + +* Fixed bugs with saving and loading session files. + +* (Mac) turned Appearance Manager classes back on when running on a + sufficient machine (I'd accidentally left the application using the + GA classes even when AM was available). + +* (Mac) create the Debug Options window invisibly; reduces flickering + when opened. + +* Converted over to using the cross-platform classes FileReference + (reference to and unopened file) and FileHandle (reference to an + opened file). These classes allow more platform-independent code + (such as the preferences code, which used to deal with Aliases on + the Mac and file paths on Windows). + +* Overhauled error/exception handling/reporting. I now use a + consistant approach to detecting, handling, and reporting errors. + +* Rewrote the ROM image loading function. ROM images consist of two + parts: a Big ROM and a Small ROM. The ROM image file always + contains a Big ROM part, but not always a Small ROM part. However, + the Small ROM part is optional and can be dummied up if necessary. + The original version of the ROM image loader needed to load in the + ROM image file once, determine if the Small ROM was included, and + start over if it wasn't. The new ROM image loader is smarter, + reading in just the parts it needs to determine if the Small ROM is + there or not. Only after that does read in the full ROM file. + +* Put more strings in resources. Most, but not all, are now done. + +* Added StdIO wrappers (see EmuTraps.h). + + +Changes for 2.1d3 (1998-07-07) +------------------------------ +* Added progress bars when loading .prc and .pdb files. + +* Added support for drag and drop. + +* Now close previous session before opening the next. + +* (Mac) Added StandardGetFile file filter to allow files that start + with "rom." or end with ".rom" or " rom", but that don't have the + right file type. + +* Updated to latest EZ ROM header files (as of 7/6/98). + +* Update the low-memory checksum if low-memory is altered by an + external debugger. + +* Fixed long-standing bug that would corrupt ROMs when switching from + one to another. Since you couldn't do this on Windows in 2.0, you'd + only see it in the Mac 2.0 version. + +* When creating the preferences for the first time, set the amount of + RAM displayed in the New Configuration dialog to 1Meg. + +* (Mac) Allocate large chunks of memory from temp mem. + + +Changes for 2.1d2 (1998-07-02) +------------------------------ +* Revamped startup sequence. From the ERS: + + If the application is started by double-clicking on its icon, it + will attempt to perform some appropriate startup action. + + * If the user had saved a session document the previous time the + emulator had been run, the emulator will attempt to reload that + document. + + * If the user created a new session document during the previous + session but didn't save that document, the emulator will create + a document with the same settings. + + * If either of those attempts fails (for instance, the previously + used session document or ROM file cannot be found), or this is the + first time the user has used the emulator, or the user holds down + the Caps Lock key while starting the emulator, the user is + presented with a "New Configuration" dialog box. The user uses + this dialog box to specify a new hardware/RAM/ROM configuration + from which a new document is created. + + If the user double-clicks on an emulator document icon, the emulator + attempts to restore the session recorded in that file. This attempt + may fail if the ROM image for the session can no longer be found. In + that case, the session document can no longer be used; session + documents can only be used in conjunction with the exact same ROM + image that created them. + + If the user double-clicks on a ROM image icon, the emulator + presents the user with the "New Configuration" dialog box with the + selected ROM file entered into the ROM File text slot. + +* Brought Mac and Windows versions in sync with each other. + +* IMPORTANT NOTE: "RAM" files created by previous versions of the + emulator are no longer supported. There are two reasons for this. + First, they didn't contain enough information that today's session + files need (such as the associated ROM file name, or the device type + to emulate). Second, ".ram" is the extension for Real Audio Media + files. Therefore, the emulator now reads and writes ".psf" (Palm + Session File) files. + +* Added Registry information so that Emulator files have the right + description next to their names. + + +Changes for 2.1d1 (1998-06-22) +------------------------------ +* Updated to latest UAE. + +* (Mac) Updated to CodeWarrior Pro 3. (Requires "MW C/C++ PPC" + from May 19th or later.) + +* Removed 68K and FAT versions. + +* New menu organization. + +* More emphasis on documents, rather than ROM image files. + +* Lots of internal changes: + + - RAM_ROM broken out into many smaller files. + + - Lots of small performance tweaks. + + - More strings moved to resources. + + - Names of system functions are fetched directly from the ROM + instead of being hardcoded in StringData.cpp. + +* Added DragonballEZ support. + +* (Mac) Added white screen. + +* New Preferences/Properties... and Debug Options... dialogs. + +* New startup dialog for Windows (for when it needs help starting + up). + +* Fixed the bug where you couldn't enter typed characters if there + wasn't a blinking insertion point. + + +Changes for 2.0b3 (1998-06-02) +------------------------------ +* 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 (1998-05-25) +------------------------------ +* 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 (1998-05-20) +------------------------------ +* 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 (1998-05-13) +------------------------------ +* 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 (1998-05-07) +------------------------------ +* 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 occurred 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 (1998-04-27) +------------------------------ +* 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 (1998-04-22) +------------------------------ +* 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 (1998-04-17) +------------------------------ +* 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 (1998-04-09) +------------------------------ +* 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 (1998-03-30) +------------------------------ +* 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 (1998-03-04) +------------------------------ +* 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. diff --git a/Docs/_ReadMe.txt b/Docs/_ReadMe.txt new file mode 100644 index 0000000..d96261d --- /dev/null +++ b/Docs/_ReadMe.txt @@ -0,0 +1,108 @@ +======================================================================== +Read Me 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> +======================================================================== + +This document is the Read Me for the Palm OS Emulator (formerly known as +Copilot). + +Palm OS Emulator is an application that emulates the hardware for most +Palm Computing Platform Hardware devices (e.g., Pilot, PalmPilot, Palm +III, Palm V, Palm VII, etc.). The Emulator runs on most standard +desktop computers, includes those running Windows 95, Windows 98, +Windows NT 4.0, Windows 2000, Mac OS 8.6, Mac OS 9.x, Mac OS X, and +several flavors of Unix. On the Mac, you need CarbonLib 1.2.5 or later. +You can find CarbonLib at: + + <http://developer.apple.com/carbon/> +or: + <http://developer.apple.com/sdk/> + +With the Palm OS Emulator, you can emulate the functions of a Palm +hardware device, including running the built-in application, as well as +installing and running 3rd party applications. + +Palm OS Emulator is an Open Source project. That means that the source +code is available for you to peruse and modify. If you make any changes +that you think might benefit others, we urge you to consider sending +them back to Palm, Inc., for inclusion in the main source code base. + +You can find the Palm OS Emulator at: + + <http://www.palmos.com/dev/tech/tools/emulator/> + +You will also find this URL in the About Box for the Emulator. The URL +is an active hyperlink; you can usually just click on it to launch your +Web browser and have it automatically access the Emulator home page. + + +Guide to the documentation files: +--------------------------------- +UserGuide.pdf + The official Poser documentation. The current version documents + features up to Palm OS Emulator 3.0a8. See the _News.txt or + _OldNews.txt files for changes since that version. + +Bugs.txt + A small set of bugs that we think you need to know about. Not + all known bugs are listed here -- just fairly relevent ones. + +Building.txt + Instructions on how to build (compile) the Palm OS Emulator on + the various supported platforms. + +Contributing.txt + Guidelines to follow (or at least consider) if you are thinking + of contributing to this Open Source project. + +Credits.txt + List of people who have contributed to the Emulator project. + +GPL.txt + Palm OS Emulator is an Open Source project distributed under and + protected by the GNU GENERAL PUBLIC LICENSE. The text of the + license is included in this file. + +News.txt + Blow-by-blow descriptions of changes made to the emulator as it + evolves over time. + +OldNews.txt + News.txt was getting too big, so older entries have been archived + to this file. + +ReadMe.txt + The document you're currently reading. + +ToDo.txt + A short list of To Do items, for people wondering what features + are planned or for people wondering how they can contribute to + the project. + +12rollin.pdf + Handheld Systems Journal article written by the current Palm OS + Emulator engineer. Covers the differences between the Palm OS + Emulator and Copilot, the program from which it was derived. + +13hewgil.pdf + Handheld Systems Journal article written by the original author + of Copilot. + + +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. diff --git a/Docs/_ToDo.txt b/Docs/_ToDo.txt new file mode 100644 index 0000000..418076d --- /dev/null +++ b/Docs/_ToDo.txt @@ -0,0 +1,16 @@ +======================================================================== +Abridged To Do List 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> +======================================================================== + +This document contains an overview of some of the major features and +components of the Palm OS Emulator that still need to be added or worked +on. The are listed here not only to let people know what's to come, but +also to give them a starting point if they wish to contribute to the +development of the project. + +* TBD |