





                               GSBug Version 1.5
                             Current Version 1.5B11





Version 1.5b11 (DAL)


You can use SetOSBrk and ClrOSBRK with call names now.  Class-1 names all end
in GS to distinguish them from their class-0 siblings.  Examples:

    SetOSBrk #1

    SetOSBrk _Create

    SetOSBrk #2001

    SetOSBrk _CreateGS


The debugger now changes its own handleUs memory ID during a real-time JSL to 
match the code being stepped.  For example, now you can step over an MMStartUp 
and get the expected ID returned (the application's instead of the debugger's).


Changed 'D' command to 'I' so it doesn't interfere with typing a hex number
that starts with a D.  The I command toggles the 'ignore REP/SEP instructions
mode' when disassembling.


Changed parsing for the P (Print screen) command so that it just beeps if there are any 
characters after the P.  (Typing 'put' intead of 'out' can no longer hang your 
system.)


Put the help screen for MP mode back in.


The solid flashing cursor in MEM, MP, and BP no longer flashes.  In exchange
for this, special characters (like braces) that happen to be in Inverse don't
flash while you're in the subscreens.


Added pseudo tool call $0BFF=DebugSetHook (one Long parameter).  The N
("neat- o") command calls this hook.


Removed a conditional hard-coded increment of $004002 when X-ing a JSR.


Added REP #$30 on the two tool-dispatcher-intercept routines.  Making tool
calls in other than full native mode is still not a good idea.


Fixed real-time breakpoints for most 1-byte instructions and all 16-bit load
immediate instructions.  Previously, they crashed when used with a count
greater than one.


Please note that */System/System.Setup/GSBug.Setup is *already* loaded 
automatically (has been for quite a while).



Version 1.5b10 (DAL)


Stepping in emulation mode should be much more reliable now, although it isn't 
perfect (in particular, one place where there's a window of vulnerability is
using X on a JSR in emulation mode, but if you have the I bit set in your P
register there's no problem).


Having the stack in $01xx works much better now, whether you're in emulation
or not.  This works by frequently stuffing a $80 into $01/0100 (EMULSTACK,
the location the interrupt manager and other things used to set the $01xx
stack when needed).


If you trace code that actually uses the $01/0100 value to set the stack
pointer, you still have a problem, since your program will start using the
part of the stack that gets toasted on every interrupt.


You can now type in GSBug even if the Event Manager is on but keyboard
interrupts are off.  Previously this would leave you dead in the water.


Files created with CSave now have a real filetype/auxtype assignment ($5A/0005).


Fixed DebugStr to return no error (previously it was returning the high two
bytes of the caller's address as an error).


Took out code that was checking $C020 (not SLOTREG at $C02D) to see if the
printer slot was switched in.  Makes no sense anyway, because a printer can
legitimately be either an internal or external slot.


Brought the list of Toolbox call names up to date for System Software 5.0.3
(see changes below).


Added tool set names (for example, $0002 is Memory Manager).  For some time, 
you've been able to use SetTBrk with a tool set number, to force a break on
every call to that tool set.  Now you can do it by name, too.

Examples:

    SetTBrk #2

    SetTBrk _Memory Manager

    ShowBrks


Saved about 900 bytes by removing many extra copies of the string "Unknown".


Obsolete call names removed:

1522    TEInsertPageBreak
2022    TEGetHooks
2122    TESetHooks
2222    TEGetDefProc


Call names corrected:

0D02    RemoveFromOOMQueue
2115    SelectIText
1021    VDKeyGetKRCol
1121    VDKeyGetKGCol
1221    VDKeyGetKBCol



Call names added:

3603    ReleaseROMResource  3703    ConvSeconds     010A    SANEBootInit
020A    SANEStartUp         030A    SANEShutDown    040A    SANEVersion
050A    SANEReset           060A    SANEStatus      090A    FPNum
0A0A    DecStrNum           0B0A    ElemNum         5D0E    TaskMasterContent
5E0E    TaskMasterKey       1713    GetDeviceName   1813    PrGetPrinterSpecs
1913    PrDevPrChanged      1A13    PrDevStartup    1B13    PrDevShutDown
1C13    PrDevOpen           1D13    PrDevRead       1E13    PrDevWrite
1F13    PrDevClose          2013    PrDevStatus     2113    PrDevAsyncRead
2213    PrDevWriteBackground    3013    PrDevIsItSafe   2022    TEOffsetToPoint
2122    TEPointToOffset     2222    TEGetDefProc    2322    TEGetRuler
2422    TESetRuler          2522    TEScroll        2622    TEGetInternalProc
2722    TEGetLastError      2822    TECompactRecord
0123    MSBoot              0223    MSStartUp       0323    MSShutDown
0423    MSVersion           0523    MSReset         0623    MSStatus
0923    SetBasicChan        0A23    SetMIDIMode     0B23    PlayNote
0C23    StopNote            0D23    KillAllNotes    0E23    SetRecTrack
0F23    SetPlayTrack        1023    TrackToChan     1123    Locate
1223    SetVelComp          1323    SetMIDIPort     1423    SetInstrument
1523    SeqPlayer           1623    SetTempo        1723    SetCallBack
1823    SysExOut            1923    SetBeat         1A23    MIDIMessage
1B23    LocateEnd           1C23    Merge           1D23    DeleteTrack
1E23    SetMetro            1F23    GetMSData       2023    ConvertToTime
2123    ConvertToMeasure    2223    MSSuspend       2323    MSResume
2423    SetTuningTable      2523    GetTuningTable  2623    SetTrackOut
2723    StartMIDIDriver     2823    StopMIDIdriver  04FF    DebugVersion
06FF    DebugStatus         09FF    DebugStr        0AFF    SetMileStone



Tool Set Names  (You can use these with SetTBrk.)

0001    Tool Locator
0002    Memory Manager
0003    Misc Tools
0004    QuickDraw
0005    Desk Manager
0006    Event Manager
0007    Scheduler
0008    Sound Tools
0009    ADB
000A    SANE
000B    Integer Math
000C    Text Tools
000E    Window Manager
000F    Menu Manager
0010    Control Manager
0011    Loader
0012    QuickDraw Aux
0013    Print Manager
0014    Line Edit
0015    Dialog Manager
0016    Scrap Manager
0017    Standard File
0019    Note Synth
001A    Note Seq
001B    Font Manager
001C    List Manager
001D    ACE
001E    Resource Manager
0020    Midi
0021    Video Overlay
0022    Text Edit
0023    MIDI Synth
00FF    Debugger



GS/OS Call Names

Brought the list of GS/OS call names up to date for System Software 5.0.3.


Removed this call:

$000E   ExpandPath (becuase there's no class-0 version)


Added these class-1 call names:

$2029   Quit
$2033   FSTSpecific
$2034   AddNotifyProc
$2035   DelNotifyProc
$2036   DRename
$2037   GetStdRefNum
$2038   GetRefNum
$2039   GetRefInfo




What It Doesn't Do Yet


Note--sometimes the debugger gets mysteriously disconnected from the
Apple-Ctl-ESC vector.  If you can reproduce this, let me know.


Holding down Option occasionally overrides a memory-protect area, but
sometimes it crashes instead.


Some of the help screens are incompelete or inaccurate.


Templates currently limited to 64K.  If template file >64K, it gets left open
by accident.


There's a harmless problem where hitting SPACE to single-step an RTS
sometimes doesn't do anything at all.


Using X to execute a JSR real-time has problems sometimes.  It's been known
to scramble the B register (if anyone has a reproducible case, let me know!),
and I've seen it come back in $01/Fxxx space with the ROM enabled when the
language card was supposed to be.


Breakpoints don't work quite right in bank-switched memory, either (it doesn't
store the original instruction into the right bank?).


Should show OS call names on a JSL $E100B0 (examine stack if stepping, and look 
for a PEA $xxxx in a disassembly).


Install notify procedure so OS breaks still work after coming back from
ProDOS 8.


The debugger chains into the tool-dispatcher vectors its own way.  It should
use the standard method defined in GS Technical Note #87.


Should make the Init version take exactly 64K to avoid mucking up memory use.
This will also fix problems where tool calls made from the same bank as GSBug
never trigger a tool break.


Will implement pseudo Tool calls to set and clear debugger breakpoints under 
program control.


May make the MEM locations labelable (and save labels in the config file).


RHandleS template partially implemented?


Unload should call UserShutDown on self (under ProDOS 8, just beep instead).


Make sure that "\" for changing display modes is documented.


Should load */System/System.Setup/GSBug.TMPL automatically.



Documentation


The GSBug manual from APDA of 3/16/89 seems to be the latest there is.  All
features not covered there should be in these release notes.



History


This part of the document details all changes made to the debugger from version 
1.3b1 to 1.5b8.


Bug Fixes:

Real Time Tool Breaks - The mechanism for using tool breaks real time has
been modified, the old method never worked quite right, what used to happen
was that when a tool break was to occur, the stub in the dispatch vector
would simply jump into the debugger, this would cause the stack and processor
not to be set as if they came from an interupt, and the next exit of the
debugger would cause code execution to start at an inapropriate case, also
the actual tracing of a tool break would also cause the debugger to
improperly save the current registers, so that the stack/direct page and
processor status might come back damaged from a tool break. The stub has
been modified to now enter the debugger with a break instruction instead
of jumping to the front. This seems to solve all real time tool break
problems.

Error tool breaks - These also did not work well, and did not seem to be
used by anyone anyway, so they have been removed to make room for OSBreaks.

Version 1.5b3:
% display code was fixed so that the '*' would properly be displayed in
  front of any toolbox glue that is detected.
% Fixed template data display so that if the data being displayed crosses
  a bank boundry, the data is properly followed into the new bank.
% Modified the IN command so that it respects trigger counts of 0 and does
  not insert real time breaks.

Version 1.5b5:
% Added Glue tool break support. Now toolbreaks work for regular and glue
  tool breaks. ErrorBreaks do not work for glue as they do not make a lot
  of sense.
% Made debugger work even when a DA window is open. See new features below.
% Added keyClick so that you hear whenever the system draws a key from the
  event queue. Also, cleaned up some comments.

Version 1.5b6:
% Added new DebugStr toolcall that can be used to get more from the debugger.

Version 1.5b7:
% Added support for real time conditional breaks.
% Added OSBreaks.
% Fixed the Debugger tool calls (like DebugStr ) so that they use the proper
  tool numbers (they had the toolset number in the high byte instead of the
  low byte) Documentation for them should also be right.

Version 1.5b8:
% Added a debugger version and status call to the debugger tools.
% Enhanced the OSBreak facility.
% Removed the keyclicks because Dave complained.

Version 1.5b9:
% Fixed some bugs.


New Features:

DebugStr:
This feature is designed to allow developers to better know where in their
program the debugger was entered. The way this feature works is that if you
want to enter the debugger programatically you can now also pass a string to
the debugger which will be printed on the bottom line of the screen when the
debugger is entered.

The way this mechanism works is a fake tool call that the debugger now
supports. Since this looks like a normal tool call it can be easily called
by any high level language as well as by assembly language.  This toolcall
called DebugStr takes a single parameter, a pointer to a pascal string. When
the tool call is made the debugger is entered as if you had put a break
into your code, but the string you passed is displayed on the screen and
the program counter has been bumped passed the tool call jsl. This way you
can simply resume execution with two simple keystrokes (with the init
version hit 'R' <return>).

Calling this new feature might look something like this

        PushLong #DebugStr
        ldx #$09FF
        jsl >$E10000

    ...
DebugStr    str 'You are about to do blah.'

from pascal the same would be achieved by doing this...

        DebugStr('You are about to do blah.');

I would recommend that assembly language users use a macro to make the
toolcall and call it _DebugStr.  MPW IIGS Pascal users could use the
following to define the debugstr routine:

    Procedure DebugStr(theString:str255);
        INLINE $09FFA2, $E1000022;

This call will also work when being called via the glue vector. 
NOTE: Since this call is only available when the debugger is loaded you
will ALWAYS want to be sure to remove ALL calls to the debugger before
releasing your program (or even using it on machines that do not have a
debugger installed).


SetMileStone:
SetMileStone operates exactly the same way as debugstr except that the
debugger is not actually entered. This will allow tracking of random
crashes by allowing you to call the SetMileStone routine with milestones
that have been met. Any time the debugger is entered via a BRK instruction
or thru the keyboard, the last string passed via the SetMileStone call will
be displayed. The toolcall number for SetMileStone is $0AFF, the  MPW IIGS
Pascal interface might look like this:

    Procedure SetMileStone (theString:str255);
        INLINE $0AFFA2, $E1000022;


DebugVersion, DebugStatus:
These calls are added so that an application can identify the version of the
debugger that is loaded and thus know what calls can be made to the debug
tool. Currently, these calls are identical and return the same result. The
DebugStatus call returns non-zero for true (as opposed to $FFFF which most
people might want...) other than that these calls act the same as any other
toolbox status or version call, each call requires a word space on the stack
for the result which is on the top of the stack when the call completes. If
a debugger is loaded that does not support this feature you will get a
standard tool locator error. For version 1.5b8 the version number returned
is $158F .As you might expect, this number will change as the debugger
version changes and it will always go up, never down.


Glue Snypher:
Glue snypher is a routine that can recognize high level language tool calls
that are made with the standard glue entry, when a call to glue is detected
while disassembling an instruction the call to glue will be replaced with
*_TooName in a manner similar to how real tool calls now work. Glue snypher
is also used by the memory protect feature, if a glue call is detected
while the standard toolbox memory protect range is on, the glue call will
be treated as if it were a JSL >$e10000.  All glue entries MUST be a JSL
to one of 3 standard types of glue that are shown below:


ToolGlueType1   LDX #$ToolNum
    JSL >$E10004
    ...
    RTL

ToolGlueType2   LDX #$ToolNum
    JML CommonCall
    ...
CommonCall  JSL >$E10004
    ...
    RTL

ToolGlueType3   LDX #$ToolNum
    JMP CommonCall

If any other types of glue calls are used, they will not be properly detected.


Glue Breaks:
In addition to glue snypher further support was added for high level
languages by extending the tool break support to the glue vector ($E10004).
Since error conditions are treated differently with glue (The second RTL
ain't mine no more...) it seems unreasonable to also support error breaks
via the glue vector. 


OSBreaks:
OSBreaks work very much the same way that tool breaks work with three
exceptions. First, instead of breaking on a tool call they will break on
a call to the OS. Next, you can NOT specify an OS break by name, only by
number. Lastly, they are not supported in trace mode, only in real time
mode.  To use OSBreaks you simply type setOSBrk #xxxx where xxxx is the 
number of the OS routine that you want to break on. This number is matched
exactly when an OS call is made, so if you do not know if the target call
is class 0 or class 1 you must set the break for both calls. OSBreaks are
supported via both vectors, inline and stackbased. The following is a
list of commands that operate on OS breaks and what they do.

SetOSBrk - adds a number to the OS break list
ClrOSBrk - Removes a given number from the OS break list
ClrAllOSBrk - Removes all numbers from the OS break list
OSBrkIn - enables real time scanning for OS breaks
OSBrkOut - disables real time scanning of OS breaks
ShowBrks - lists all tool and OS breaks currently set.


DA Debugging support:
In the past it has always been difficult to debug certain new desk
accessories because they accept keystrokes, and keep the debugger from
receiving them. I have added a patching mechanism to the system event
call that is installed when the debugger is installed that fixes this
problem. The way this feature now works is that if the caps lock key is
down no keyboard events get passed to system event (and then to any open
DA's) and the debugger will always get them. A side effect of this is that
when the debugger screen is not active applications will get the same
keystroke events if the CAPS LOCK key is down. As a gentle reminder of
this feature, when installed, it will make your GS speaker click whenever
a key is processed by getNextEvent.  The debugger used to click on every
keystroke, regardless of the state of the CAPS LOCK key.  Dave complained
enough that the debugger was changed to only click when keys are pressed
if the CAPS LOCK key is down.


New Template types:

We have added support for a few more data types in templates, these are
mainly for use with GS/OS strings, but can also be used for any word
length string. they are:

    InputStr:   This type will read the next word of data and treat it as
                a length word for string data that follows. The entire
                contents of the string will be displayed.

    OutputStr:  Similar to InputStr except that the first word is a buffer
                length and the second word is the string length. After the
                string is displayed the debugger will skip to the end of
                the buffer to find the next byte of data to process.


RealTime Conditional Breakpoints:

The debugger now supports conditional real time breakpoints. In the past
when a breakpoint was entered in the breakpoint list and you used the IN
feature to make them work real time, the trigger count that you entered
was ignored. Now, If you the trigger count is supported the same way it is
supported in trace mode, that is, if you insert a real time breakpoint
with a count higher than 1 it will break on the Nth execution of the
opcode at that location. NOTE: Currently the following opcodes are not
supported as real time conditional breakpoints: JSL(mem), JSR(mem),
JSR(mem,x), JMP(mem), JMP(mem,x), RTI.

In addition to supporting a count value for real time break points, the
debugger now also allows a simple conditional statement to be used instead.
The debugger allows only one conditional statement at a time, but as many
of the breakpoints can use it as you want. To enable the conditional
statement (henceforth called IF) simply type an "i" when entering a
breakpoints trigger value instead of a hex digit. To set the current IF
use the command SetIF. the syntax of the SetIF command is as follows:

    SETIF {width} {Spec1}{Operator}{Spec2}

Legal {width} values
     W  for word 
     B  for byte

Legal {Operator} values
    =   for is equal to
    #   for is NOT equal to
    <   for is less than
    >   for is Greater than or equal to

Legal {Spec1} and {Spec2} values are
    A,X,Y,S,D,P,B   for the corresponding register
    $BBXXXX     as the address of a value in memory
    #$XXXX      as a hexidecimal constant ({SPEC2} only)

Some examples of IFs

    SETIF W A<#$0101        (Break if the word in <A> is less than #$0101)
    SETIF B $021234=$034321 (Break if the bytes at $02/1234 and $03/4321
                             are the same.)

NOTE: Currently only long addresses are supported.
