ENFORCER


FUNCTION

    Enclosed is a majik tool for detecting invisible bugs in programs; _The
    Enforcer_ uses the MMU to build a shroud of protection over anything
    that is not legal memory.  Any "empty holes" in the address space are
    marked as illegal by _Enforcer_.  Reads of the system ROMs are allowed,
    but not writes.  With the exception of longword reads of location 4,
    the lowest 1K of memory is completely off-limits.

    Enforcer runs on any Amiga or OS revision, as long a the MMU is not
    already in use.  This version of Enforcer also works on the A3000 under
    SuperKickstart (V1.3 or 2.0).  Under V1.3, enforcer requires SetPatch
    version 1.38 or later.



SETUP
    Connect a terminal or another Amiga to the serial port of your machine.
    If you don't have an external terminal, just use a modem & terminal
    software on the same machine.  Most modems simply echo back characters
    when not on-line.  (alternately, you can use Enforcer.par which
    outputs debugging information to the parallel port)

    Execute "enforcer". (or enforcer.par)

    Execute "lawbreaker" to verify that everything is working.  Lawbreaker
    does two illegal memory references.



DESCRIPTION

    When an illegal access is detected, the power LED will flash and a
    detailed message will be sent out the serial port (at the default
    speed).  Illegal writes are aborted, illegal reads return NULL data.
    For example:

Program Counter (approximate)= 783C460         Fault address        =DEADBEEF
User stack pointer	     = 7860ABC	       DOS Proccess address = 7839F98
Data: 00000001 01E0F0FB 00000FA0 0783AE18 00000001 01E0987F 01E0A93D 0783C3EC
Addr: 0783AE18 0785FB28 07810114 0783C3EC 07860AC0 00F8F56A 00F8F55E 078021D0
Status register =$8	       Special status word =$729 (WRITE-WORD)
Data output buffer  =$FFFFADEF (o)
Process/CLI = Background CLI ,"lawbreaker"
Hunk-O-Matic says: PC address is in hunk #0, near offset $70



    CLI command "lawbreaker" has written the word value $ADEF to location
    $DEADBEEF.	The write was aborted.	With the information given, it is
    usually quite easy to figure out what went wrong.



Remote keystrokes:
	    ^S	- pause.  You may have to press it more than once.
	    ^Q	- resume
	    ^X	- When in ^S, press ^X to suspend _Enforcer_ reporting.
		  Use ^Q to resume.


Command line options:
	    on
	    fprotect	;Same as on, but write protects $F00000-$F7FFFF
	    off




Notes:

    Illegal hits from CLI commands named "metascope" or "wack" are ignored.

    Rebooting an A3000 running Enforcer causes the SuperKickstart to be
    reloaded from scratch next time you boot.  Some call this a feature.
    This will, however, kill RAD:.  When enforcer is off, SuperKickstart is
    not reloaded.

    The Alert() system call writes to locations in the $180-$1C0 area.




---- Notes on the current version of Enforcer

1. Hunk-o-matic can only output hunk offsets if your program
   was started from a shell (ie. not from Workbench).

2. The type of memory access (such as READ-WORD or READ-INSTR) is very
   important for debugging.  READ-BYTE hits are generally a read of an
   uninitialized string pointer.  READ-WORD and READ-LONG at low
   addresses are generally references off an uninitialized structure
   pointer.  WRITE hits of the same sizes are generally related
   to the same types of uninitialized pointers.  In combination
   with MungWall, similar hits at high addresses are generally
   caused by accessing a string or structure after it has been
   deallocated.  A READ-INSTR hit means your program counter
   is trashed and your program is executing garbage.  This is
   usually caused by using an invalid library base pointer or
   by trashing a return address on your stack.  A READ-INSTR
   hit at an address like $FFFFFFxx is genrally caused by an
   uninitialized library base pointer (PC jumped to an LVO which
   is a negative word offset, from a 0 base pointer).

   See mungwall.doc for additional information on the particular
   nasty high values mungwall trashes free memory with.  This will
   help you debug Mungwall+Enforcer hits.

3. Some new information in the latest enforcer:

  (---)(-)(-)    SR=0008   SSW=0769   
   I-n here means hit occurred within a level n interrupt 

  (---)(-)(-)    SR=0008   SSW=0769   
        F here means it occurred in a Forbid

  (---)(-)(-)    SR=0008   SSW=0769   
           D here means it occurred in a Disable

  (---)(-)(-)    SR=0008   SSW=0769   
                 Additional processor status information

Sample enforcer hits:

Program Counter (approximate)=  396606		Fault address       =      14
User stack pointer           =  439100		DOS process address =  35C380
Data: DDDD0041 DDDD1100 DDDD2200 DDDD3300 DDDD4400 DDDD5500 DDDD6600 DDDD7700
Addr: AAAA0000 AAAA1100 AAAA2200 AAAA3300 AAAA4400 AAAA5500 00001420 00002E28
Stck: 00000009 00000008 00000007 00000006 00000005 00000004 00000003 00000002
READ-WORD  (---)(F)(D)    SR=0015   SSW=0769   
Background CLI, "lawbreaker", Hunk #0, Offset $96

Program Counter (approximate)=  396618		Fault address       =FEEDFACE
User stack pointer           =  439100		DOS process address =  35C380
Data: DDDD0041 DDDD1100 DDDD2200 DDDD3300 DDDD4400 DDDD5500 DDDD6600 DDDD7700
Addr: AAAA0000 AAAA1100 AAAA2200 AAAA3300 AAAA4400 AAAA5500 00001420 00002E28
Stck: 00000009 00000008 00000007 00000006 00000005 00000004 00000003 00000002
WRITE-LONG  (---)(F)(-)    SR=0018   SSW=0709   Write Data= DDDD0041 (A)
Background CLI, "lawbreaker", Hunk #0, Offset $A8