REVISION HISTORY : BETA debugger
-------------------------------------

Note: Many of these revisions are for internal tech-support reference
and were not actually released.

4.35 24/01/95	32X/Saturn off-line mods updated to cope with missing
		 targets while switching screens or loading excutables

4.36 25/01/95	Another off-line mod update (oops, missed one)

4.37 29/01/95	Minor disassembler fixes inc:
		 removal of SH1 ops (brk, ldbr, stbr, rtb)
		 fixed the 'stc illegal' for some illgal ops
		 fixed 'stc sysreg' showing wrong sys reg

4.38 31/01/95	Removed Err display from register window

4.39 01/02/95	corrected disasm of mov.b @($80,gbr),r0
		 to use *unsigned* offset

4.40 02/02/95	corrected fill & download problem
		 that I introduced in 4.38

--------------------------------------------------
YOU MUST USE DOWNLOADER 1.10 or later from here on!

4.42 07/01/95	C variable data: members now hang off tags
		 (so they're out of the main name-pool)
		Alt-B to set hardware breakpoint.

4.43 09/01/95	structure within structures now type OK
		 (I temp lost scope in 4.42)

4.44 09/01/95	Wide message window (>80 columns) now OK
		Message POLL speed now independent of update rate
		FormFeed (ascii 0x0C) in message clears window

4.45 14/02/95	register unions & structures now view/open OK
		 and display register name

4.48 14/02/95	new message window handler
		(needs DEXBIOS 1.21 or PSYBIOS 1.21 or later)
		(still auto-detects and works with old one too)

4.49 26/02/95	fixed occasional dropped char in new message handler

4.49a 06/03/95	oops. 4.49 refused to work with MESS1 ver 1.01
		now changed to work with 1.XX

4.50 22/03/95	running an off-line unit no longer crashes debugger

4.51 24/03/95	extended max source files from 512 to 1024
		added missing Alt-G to watch window keylist

4.51a 18/04/95	corrected SH2 disassembly of 'stc vbr,rn'
		drag mouse in window to scroll it up/down
		removed extra debug regs from below register window border

4.53 14/05/95	added /a switch to share unit 0 symbols over all units

4.54 02/06/95	fixed makesafe (shift-ESC) to stop target and turn ints off
		 (because it was sending wrong SCSI command)

4.55 05/06/95	fixed 'running from a BP' on unit 1 (slave SH2)
		 to only take 1 keypress now.

4.56 06/06/95	Oops. 4.55 was a bad build. My mistake.
		 This is how it should have been.
		(only 2 or 3 developers picked up 4.55 before I
                 spotted it though)

4.57 16/06/95	hex No.s in C exprs (don't need leading zero anymore)
		fixed disasm of mov r0,@(NN,gbr) displacement 8 bit, not 4!
4.58 19/06/95	memory ranges of configs other than .C00 ignored
		hopefully fixed occasional missing curson on alt screens
		new resetcpu code - resets target box & CD emu on Saturn & PSX Alt-R + SAT205

4.59 05/07/95	allows modification of variables in Watch and Var windows
                fixed old error message problem for unrecognised symbol

4.60 05/07/95	dereferencing a pointer now fixes class to STATIC
		(so deref of a watchpoint register pointer to a structure is now correct)

4.61 06/07/05	changing screens no longer flushes message buffers
		message buffer increased to 100 lines.

4.62 06/07/95	auto-detects C startup and runs to main() if not given /d command line switch

4.63 26/07/95	minor update: fixed shift-f6 (clear all BP counts)
		source file window can now scroll left/right

4.64 28/07/95	restricted auto-source-mode, to only if no config file
		(because it was annoying developers)

4.65 28/07/95	restricted auto-source-mode, to only if no config file
		(but still got auto-run to main)

4.67 09/07/95	removed 'makesafe' call from CPE loader
		now *does not* turn off ints before program starts

4.69 24/07/95	now supports source file paths (Alt-P in file window)
		Alt-L and Ctrl-L no longer crash Var and Watch windows

4.70 01/09/95	Automatic Overlay Support
		Unix \n newlines now work properly in message window

4.71 14/09/95	+ fixed name completion that I broke in 4.70
4.72 18/09/95	internal tidy-up (MX handling for SH2 units)

4.73 21/09/95	fixed memfollow (alt-F in memory window to follow ptr)
4.74 21/09/95	mouse click in zoomed window now OK
		cursor clamping to left of mem window corrected.

4.75 26/09/95	stack-crawl (left and right arrow in var window)
		cexp.asm seperated from main code (as MASM couldn't cope)
		'searching' box in file window now hides if not found
		update animation only active if continous update mode
		condition on hardware break that was done for Williams in 4.65s is now back

4.76 28/09/95	Unix (LF) or DOS (CRLF) or MAC (CR) newlines now
		 work properly in message window. (from 4.70 the DOS
		 ones were accidentally double-spaced.)

4.76a29/09/95	allows $ in C names (for Carolyn @ EA)

4.77 16/10/95	Pseudo-support for long long (64 bit) data type

4.78 06/11/95	Floating point support added to watch display

4.79 13/11/95	fixed DOS extender quirk which was causing
		'UPLOAD MEM TO FILE' to fail for amounts >4K (ver 4.78 only)

4.80 15/11/95	changed shift-esc makesafe so that ints *stay* off
		modded ctrl-F2 'prog reload' so breakpoints are preserved.
		<clear> option added to hardware break dialog

4.82 24/11/95	C expression evaluator now supports typecasting

4.83 14/12/95	new keypress: ctrl-f9 restores IPL (to what it was before shift-ESC) and runs

4.84 15/02/96	ctrl-F9 to restore IRQ status (to what it was b4 shift-esc) and run
		 + some minor dialog changes

4.85 15/02/96	space bar toggles window between source & dis modes

4.86 16/02/96	global scope can now be seen whilst stepping overlays

4.87 26/02/96	corrected enum display in watch/var window

Message window support
----------------------

Note: From 4.48 onwards the debugger supports old *and* new style
message facilities. To print a message you just execute a fileserver
write but to a negative file handle.

The text message you write will be sent to PSYBIOS on the PC.

OLD STYLE PSYBIOS versions prior to 1.22 will make the message
available to the debugger.

NEW STYLE PSYBIOS version 1.22 or later will look for a resident
message handler and pass the message to that. If it does not find
an installed message handler it will discard the message.

So, if you use PSYBIOS 1.22 or later you must also have installed a
message handler such as:-

e.g.

MESS1.COM  which will make messages available to the debugger

or

MESS3.COM  which will pass messages to a PC serial port. (very handy
if you have a laptop PC or Psion Series 3 terminal program monitoring
the serial port output)


SH2 Hardware Break Support
**************************

You must have the appropriate new downloader installed
(version 1.10 or later) installed on the target otherwise the
debugger will not function correctly.

Hardware break can be accessed by typing Alt-B in
DBUG32X or DBUGSAT version 4.42 up.

In assembler mode you will be prompted for a mask value.
This mask has zero bits to enable therefore a mask value of ZERO
will be the usual value to trap one particular address.
Note that this is the INVERSE of the PSX hardware debug.

This facility uses only User Break Channel A.
Channel B is still available for your own use.

If you have any questions about this please contact SN Systems.


Saturn & 32X Version 4.32 and later: OFF-LINE mods
--------------------------------------------------

At start-up only the master SH2 is visible to the debugger. Any cpu
windows on the screen which are not visible to the debugger will
display "Unit not available" in an empty window.

Your own code will initialise the slave SH2 (don't forget to set the
Psy-Q vectors if you want to debug it). Once your master SH2 program
has started up the slave you must force the debugger to re-scan for
new cpus. To do this press keypad '*' on your PC keyboard.

At this point the slave cpu will come on-line and your slave windows
will display correctly. Don;t forget, you can toggle any window
between displaying all supported cpu's by pressing Alt-T


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

Copy your old debugger away somewhere safe first cos you may need
to switch back to it if you have problems.

Copy the new debugger to your Psy-Q executable directory.

-------

V4.25 up allows you to use the sizeof() function in a C expression.
This function will return the size of the result of the expression
within the brackets.

-------

This debugger features the all new VARIABLE window and WATCH window.
In either window you can use the following keys:-

+	open up the info (e.g. structure or array etc) under cursor

-	close ditto

tab	change result display format of C expression under cursor

right arrow	increments array index under cursor
left arrow	decrements array index under cursor

Note: currently these last two only work if the array entry has not
been expanded by pressing '+'.

Also in a watch window you can use INSERT and DEL to add and remove
watch expressions.

Pressing Alt-G will enter watch records for all your global
variables. Unlike VAR window, these are saved on exit.

Note that watch expressions, window lock expressions, and calculator
expressions can now be C or assembler syntax - just click on the
button on the dialog box before you enter the expression to select
which type.

If you have any questions then please call or email me.

-- 
Andy Beveridge       andy@snsystems.co.uk


SOURCE FILE PATHS - new with debugger version 4.69 up.
------------------------------------------------------

By typing Alt-P in a file window you can enter a search path to be
used to find source files for source-level debugging.
This path works just like a normal DOS path - entries are delimited
by semicolons.

When the debugger looks for source file it will check...

1) the full path to the file as in the symbol file. This will usually
be a fully canonicalised DOS filename as seen by the machine upon
which the project was built.

2) IF 1) above fails to find the file only then will it isolate the
filename from the end of the built path-name and then search for that
file in each of the directories specified in the source-file search
path.

e.g. if original source file at build time was MAIN.C and it was
compiled in the C:\PROJX\PSX\SRC directory then the .SYM file will
contain the entry

C:\PROJX\PSX\SRC\MAIN.C to describe the file. The debugger will first
seach for that specific file. If it cannot find it and your search
path is set to:-

        C:\;C:\TEMP;H:\COMMON\SRC

then the debugger will next look for:-

   C:\MAIN.C  then  C:\TEMP\MAIN.C  then  H:\COMMON\SRC\MAIN.C

in that order. Note that you can specify the current directory in the
search path just by adding an empty entry.

e.g.    ;C:\;C:\TEMP;H:\COMMON\SRC

will cause it to look in the current directory first

or      C:\;C:\TEMP;;H:\COMMON\SRC

will cause it to look in the current directory after C:\TEMP but
before looking in H:\COMMON\SRC

If all is not clear then you are welcome to call or email SN Systems
to ask for help.


---------------------------------------------------------------------
IMPORTANT NOTE:
We appear to have experienced a small version control problem which
means that (some, maybe all) PSX 4.69 had the source path feature but
Saturn 4.69 did not.
This may cause confusion as pressing Alt-P will cause previous
versions of the Saturn debugger to print the current window instead.

4.70 was not released (it was demo'd at ECTS).

4.71 is released and definitely has the source path mods as well as
the auto-overlay support in both PSX and Saturn versions.

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

AUTO OVERLAY SUPPORT - New from 4.70 up
========================================

This feature was added at the request of developers making very heavy
use of overlays to handle converting extremely large PC games over to
Playstation's limited 2MB RAM. It is still in development so if you
have any suggestions for improvements please let us know. In
particular, if you debug using multiple symbol files then we may need
to make a few small changes. I'm holding off to see if anyone needs
this.

Not much to say about this here as it is all automatic. To use this
feature all you need is an appropriate symbol file that contains the
new format overlay records. To make such a file you will need to be
using a recent version of the linker which also has this support.

For more details check-out the OVLEG.ZIP (OVerLay Example) file on
our BBS and FTP site. This example will show you how to set-up your
.LNK linker control file and .MAK makefile to produce symbol files
with overlay information.


STACK CRAWL - New from 4.75 up
==============================

**********************************************************************
*** This feature is disabled in SATURN Psy-Q until SEGA or CYGNUS  ***
*** release a version of the GNU compiler with correct stack-frame ***
*** info in the debug output.                                      ***
**********************************************************************

The user-interface on this is still very experimental - don't be
surprised if it changes over the next few versions. Any feedback on
this feature is welcomed (to Andy@snsys.com please, not SCE).

Currently this feature can only be accessed by:-

1) pressing left or right arrow keys whilst in a VAR window.

Although this is a Var window key it will in fact temporarily change
the cpu context as seen by all windows on the screen.
The right arrow key will dereference the current displayed scope by
one level. i.e. it will change context to that of the routine which
called the one you're in. It does this by unpicking the stack frame
of the current routine - temporarily restoring registers, and
program context to that of the instruction following the call to the
current level. This can be done again and again to walk back up
through the C call-stack . At each context you can examine that
function's local variables and parameters. The register display will
also change to that context - you will see that the PC is after the
call.

Note that this only works whilst the target is stopped. If you
continue the target running (or step or trace) then the context
is first restored to the point at which you stopped the program.

If you dereference back to a point which has no scope then the
debugger will allow this but the var window will correctly display
that there is no scope for this context. All debugger windows will be
correct for the new context - look at a disasembly window and go-to
the PC (tab) and you will see that the PC is at the instruction which
called the C function you unpicked.
If you try to derefence again from this point you will see an error
message informing you that there is no C stack frame to unpick at this
point.

future updates to the stack-crawler will include:-

1) A level above the default current scope (left arrow from current
var scope) which will display all the function calls on the call-stack
and allow you to select a context from that for variable display.

2) function name display (in var window title and in top-level stack
dump) will contain expanded details of parameters it was called with.


