-----------------------------------------------------------------------------
File name:	PD_PATCH.TXT			Revision date:	1998.10.10
Created by:	Ulf Ronald Andersson		Creation date:	1998.10.09
Feedback to:	dlanor@oden.se
-----------------------------------------------------------------------------
File purpose:	Document how to make 'Pure Debugger' compatible to MagiC etc.
-----------------------------------------------------------------------------
Release:	All information in this file is free for any use whatever !
-----------------------------------------------------------------------------
Disclaimer:	No one is responsible for anything this file may lead to !
-----------------------------------------------------------------------------
Credits:	Eabe Kuik supplied info on the STinG patch, which led me to
		try some more variants, and finally to write this document.
-----------------------------------------------------------------------------

Introduction:  (aka: Why YOU might NEED these patches...)
-------------

The 'Pure Debugger' PD.PRG supplied with the 'Pure C' compiler has several
compatibility problems, since it was written quite a while ago and thus
ignores some new standards of programming and enhanced function libraries
used in (or at least with) some new TOS versions and other modern software.

This means that PD.PRG usually bombs when used with most multitaskers, and
that it interferes in other ways with some other software (eg: STinG).

The instructions given in further sections of this file describe how you
can make patched versions of PD.PRG that eliminate most, perhaps all, of
those problems.  For example, I can now use such a patched debugger under
MagiC, without suffering the 'lockup' problem that the original has.
-----------------------------------------------------------------------------

The patch methods:  (aka: What the patches change inside PD.PRG)
------------------

PD.PRG links into many system vectors, and does so without proper regard
to the mandatory use of XBRA protocol which is demanded by modern Atari
guidelines for vector bending. This is the reason for most of the problems.
Fortunately there is a way to 'turn off' the bending entirely for any
of the exception vectors involved, although the program itself has no way
of letting the user make such configuration (it wasn't thought necessary).

Inside PD.PRG there is a structure holding variables used for bending the
exception vectors.  There is also a table with one 16-bit entry for each
exception vector defined (from vector number 0 and up). Those 16-bit words
are actually indexes for the main structure, but zero is used to indicate
that the given exception vector should not be bent at all.

This means that we can gain compatibility with software which is allergic
to the way PD.PRG bends a specific vector, simply by using a version of
PD.PRG where the index for that vector has been patched to zero.

There is inevitably one drawback of this method, which is that a patched
version of PD.PRG is unable to 'catch' exceptions through the vectors for
which the bending has been 'turned off' this way.  For this reason I find
it useful to have several patched versions, so that I only 'turn off' the
bending for those vectors that would cause incompatibility problems with
the software (or TOS/MagiC) which is active in the test.
-----------------------------------------------------------------------------

How to make a patch:
--------------------

You will need some kind of editor for binary files.  I use 'HEX_EDIT' but
there are many others around.  If you use a so-called 'disk editor', then
make sure that it doesn't treat the file as 'sectors'.  The editor DADE,
supplied with the 'Diamond Edge' disk optimizer/medic, is one example of
a disk editor which is *not* suitable to edit binary files.  It rounds
the file size up to the nearest multiple of the sector size, which means
that the resulting file no longer has a legal program format.
(It may even be diagnosed as a link virus...)

Fortunately such stupid behaviour is not very common, so I do not think
that you will have any real problems finding some file editor that can
do the job properly (like HEX_EDIT).

Start the patching by making a copy of the original PD.PRG file, renaming
this copy to something that lets you remember what it's 'specialties' are.
I use the following names:

PD        seldom used now (original)          \
PD_MULT   used to debug under multitaskers     >  without STinG
PD_COMP   used to debug 'weird' TOS benders   / 

PD_STING  used to debug under standard TOS    \
PD_SMULT  used to debug under multitaskers     >  with STinG
PD_SCOMP  used to debug 'weird' TOS benders   /

Load the renamed copy of PD.PRG (never edit original) into the file editor,
and then search for the following sequence of 8 16-bit words:

0000 0000 0080 008C 0098 00E6 00F2 00FE

This sequence should occur only once in the file, and that should be in the
so-called 'data section' (for those who are familiar with the file format).
In the version I have this occurs at offset $17790 from file start, but it
may differ in other versions, so I will refer to the location symbolically,
as 'table_base' in the remainder of this text.

Assuming that your editor displays 16 bytes per line, it should now display
the table data somewhat like the following:

Address of line:  +$00  +$02  +$04  +$06  +$08  +$0A  +$0C  +$0E
----------------  ----  ----  ----  ----  ----  ----  ----  ----
table_base+$00:   0000  0000  0080  008C  0098  00E6  00F2  00FE ;vector 0-7
table_base+$10:   010A  0142  0268  0000  0000  0160  016C  0000 ;vector 8-15
table_base+$20:   0000  0000  0000  0000  0000  0000  0000  0000 ;vector 16-23
table_base+$30:   0178  0000  0000  0000  0000  0000  0000  0000 ;vector 24-31
table_base+$40:   0000  02C6  02D0  0000  0000  0000  0000  0000 ;vector 32-39
table_base+$50:   0000  0000  0000  0000  0000  0364  036C  0000 ;vector 40-47
table_base+$60:   0214  0220  022C  0238  0244  0250  025C  0000 ;vector 48-55

Do not attempt to patch any data beyond the area shown above, because that
data is probably needed for entirely different purposes than this table.

If the data does not match that displayed here, then you probably have a
version which is already patched somehow.  Try to find an original PD.PRG
version 1.1.  At least two revisions exist from 1992-1993, and the patch
instructions given here should certainly fit both of those. As for others
I have no way of knowing if they too use identical data and methods, so
at present I can not help you with how to patch them (I don't HAVE them).

If everything matches at this point, then patch the 16-bit indexes of the
vectors to be patched (more on the choice of these follows) to zero. Then
save the file and exit the editor.  Remember to check that the editor has
not altered the file size.  That size should be identical to the size of
the original PD.PRG.  If it has been changed you need another editor for
the job...
-----------------------------------------------------------------------------

Choosing vectors to patch:
--------------------------

The vector numbers shown to the right in my rendering of the index table in
the section above gives the system exception vector numbers corresponding
to the indexes of each line.  So once you know the number of a vector that
needs to be patched you can easily find its place in the table, and from it
calculate the address at which the index lies that must be zeroed.  But do
remember to check its original value against that in my table.  If they do
not match, you may have made a mistake somewhere so recalculate again.

I have found it useful to patch five vectors so far:

1:  Privilege Violation exception vector.
    -------------------------------------
    This patch is needed to avoid problems when debugging with STinG
    networking kernel running.
    The vector number is 8, so the index is at (table_base + $10)
    change the original index value $010A to zero to patch it.

2:  Trap #2 exception vector.  (aka: XGEM function dispatcher)
    -------------------------
    This patch is needed to avoid lockup of PD.PRG under MagiC, as well as
    with some other software that modifies AES functions.
    The vector number is 34, so the index is at (table_base + $44)
    change the original index value $02D0 to zero to patch it.

3:  Trap #1 exception vector.  (aka: GEMDOS function dispatcher)
    -------------------------
    This patch should eliminate problems with programs that bend GEMDOS
    functions in ways incompatible with PD.PRG.  (No modern one known.)
    The vector number is 33, so the index is at (table_base + $42)
    change the original index value $02C6 to zero to patch it.

4:  Trap #13 exception vector.  (aka: BIOS function dispatcher)
    --------------------------
    This patch should eliminate problems with programs that bend BIOS
    functions in ways incompatible with PD.PRG.  (No modern one known.)
    The vector number is 45, so the index is at (table_base + $5A)
    change the original index value $0364 to zero to patch it.

5:  Trap #14 exception vector.  (aka: XBIOS function dispatcher)
    --------------------------
    This patch should eliminate problems with programs that bend XBIOS
    functions in ways incompatible with PD.PRG.  (No modern one known.)
    The vector number is 46, so the index is at (table_base + $5C)
    change the original index value $036C to zero to patch it.

All my own patched debugger variants that I mentioned earlier have only
those 5 vectors patched, in various combinations as described below:

Filename   Vectors patched
--------   ---------------
PD_MULT    vector 34 only, for testing without STinG under multitaskers
PD_COMP    vectors 33, 34, 45, 46, to test 'weird benders' without STinG

PD_STING   vector 8 only, for testing with STinG
PD_SMULT   vectors 8, 34, for testing with STinG under multitaskers
PD_SCOMP   vectors 8, 33, 34, 45, 46, to test 'weird benders' with STinG

NB: PD_MULT, PD_SMULT, PD_COMP, PD_SCOMP have all been tested successfully
    under MultiTOS, Geneva, N_AES, and MagiC 5.  All of those systems will
    cause an unpatched PD.PRG to lockup, so this is a significant gain.

    The degree of functionality in various multitaskers varies, depending
    on differencies between them, but some functionality exists for all.
    (All that I have tested the pathes with that is, as summarized below.)

Tasker:    Problems:
-------    ---------
MagiC 5    No problems known.  Everything seems to work as it should.
Geneva     No problems known.  Everything seems to work as it should.
MultiTOS   Keyboard input has no effect, but mouse commands etc work fine.
N_AES      Keyboard input has no effect, but mouse commands etc work fine.

Good news to users of MagiC and Geneva as you see...  (like me  :-)

But even users of MTOS/N_AES may find it useful to browse memory contents
etc using the mouse operations in PD, though most advanced features will
not be available without keyboard access.
-----------------------------------------------------------------------------
End of file:	PD_PATCH.TXT
-----------------------------------------------------------------------------
