home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / coders / enforcer / enforcer.doc < prev    next >
Text File  |  1977-12-31  |  54KB  |  1,263 lines

  1. TABLE OF CONTENTS
  2.  
  3. Enforcer
  4. FindHit
  5. LawBreaker
  6. Move4K
  7. RebootOff
  8. SegTracker
  9. Enforcer                                                             Enforcer
  10.  
  11.    NAME
  12.     Enforcer V37 - An advanced version of Enforcer - Requires V37
  13.  
  14.    SYNOPSIS
  15.     Enforcer - A tool to watch for illegal memory accesses
  16.  
  17.    FUNCTION
  18.     Enforcer will use the MMU in the advanced 680x0 processors
  19.     to set up MMU tables to watch for illegal accesses to memory
  20.     such as the low-page and non-existent pages.
  21.  
  22.     To use, run Enforcer (plus any options you may wish)
  23.     If you wish to detach, just use RUN >NIL: <NIL: to start it.
  24.     You can also start it from the Workbench.  When started from Workbench,
  25.     Enforcer will read the tooltypes of its icon or selected project icon
  26.     for its options.  (See the sample project icons)
  27.  
  28.     Enforcer should only be run *after* SetPatch.
  29.  
  30.     If SegTracker is running in the system when Enforcer is started,
  31.     Enforcer will use the public SegTracker seglist tracking for
  32.     identifying the hits.
  33.  
  34.    INPUTS
  35.     The options for Enforcer are as follows:
  36.  
  37.     QUIET/S        - This tells Enforcer not to complain about any invalid
  38.                      access and to just build MMU tables for cache setting
  39.                      reasons -- mainly used in conjunction with an
  40.                      Amiga BridgeBoard in a 68030 environment so that
  41.                      the system can run with the data cache turned on.
  42.                      In this case,
  43.                                     RUN >NIL: Enforcer QUIET
  44.                      should be placed into the startup-sequence right
  45.                      after SetPatch.
  46.  
  47.     TINY/S         - This tells Enforcer to output a minimal hit.  The
  48.                      output is basically the first line of the Enforcer
  49.                      hit.  (see below)
  50.  
  51.     SMALL/S        - This tells Enforcer to output the hit line, the
  52.                      USP: line, and the Name: line.  (This means that
  53.                      no register or stack display will be output)
  54.  
  55.     SHOWPC/S       - This tells Enforcer to also output the two lines
  56.                      that contain the memory area around the PC where
  57.                      the hit happened.  Useful for disassembly.
  58.                      This option will not do anything if QUIET, SMALL or
  59.                      TINY output modes are selected.
  60.  
  61.     STACKLINES/K/N - This lets you pick the number of lines of stack
  62.                      backtrace to display.  The default is 2.  If set
  63.                      to 0, no stack backtrace will be displayed.  There
  64.                      is NO ENFORCED LIMIT on the number of lines.
  65.  
  66.     STACKCHECK/S   - This option tells Enforcer that you wish all of
  67.                      the long words displayed in the stack to be checked
  68.                      against the global seglists via SegTracker.
  69.                      This will tell you what seglist various return
  70.                      addresses are on the stack.  If you are not
  71.                      displaying stack information in the Enforcer hit
  72.                      then STACKCHECK will have nothing to check.
  73.                      If you are displaying stack information, then
  74.                      each long word will be check and only those which
  75.                      are in one of the tracked seglists will be
  76.                      displayed in a SegTracker line.
  77.                      The output will show the PC address first and
  78.                      then work its way back on the stack such that you
  79.                      can read it from bottom up as the order of calling
  80.                      or from top down as the stack-frame backtrace.
  81.  
  82.     AREGCHECK/S    - This option tells Enforcer that you wish all of
  83.                      the values in the Address Registers checked via
  84.                      SegTracker, much like STACKCHECK.
  85.  
  86.     DREGCHECK/S    - This option tells Enforcer that you wish all of
  87.                      the values in the Data Registers checked via
  88.                      SegTracker, much like STACKCHECK.
  89.  
  90.     DATESTAMP/S    - This makes Enforcer output a date and time with each
  91.                      hit.  Due to the nature of the way Enforcer must
  92.                      work, the time can not be read during the Enforcer
  93.                      hit itself so the time output will be the last time
  94.                      value the main Enforcer task set up.  Enforcer will
  95.                      update this value every second as to try to not
  96.                      use any real CPU time.  The time displayed in the
  97.                      hit will thus be exact.
  98.                      (Assuming the system clock is correct.)
  99.                      The date is output before anything from the hit
  100.                      other than the optional introduction string.
  101.  
  102.     DEADLY/S       - This makes Enforcer a bit nasty.  Normally,
  103.                      when an illegal read happens, Enforcer returns 0
  104.                      as the result of this read.  With this option,
  105.                      Enforcer will return $ABADFEED as the read data.
  106.                      This option can make programs with Enforcer hits
  107.                      cause even more hits.
  108.  
  109.     FSPACE/S       - This option will make the special $00F00000 address
  110.                      space available for writing.  This is useful for
  111.                      those people with $00F00000 boards.  Mainly Commodore
  112.                      internal development work -- should only be used
  113.                      in that enviroment.
  114.  
  115.     VERBOSE/S      - This option will make Enforcer display information
  116.                      as to the mapping of the I/O boards and other
  117.                      technical information.  This information maybe useful
  118.                      in specialized debugging.
  119.  
  120.     LED/K/N        - This option lets you specify the speed at which
  121.                      the LED will be toggled for each Enforcer hit.
  122.                      The default is 1 (which is like it always was)
  123.                      Setting it to 0 will make Enforcer not touch
  124.                      the LED.  Using a larger value will make the
  125.                      flash take longer (such that it can be noticed
  126.                      when doing I/O models other than the default
  127.                      serial output)  The time that the flash will
  128.                      take is a bit more than 1.3 microseconds times
  129.                      the number.  So 1000 will be a bit more than
  130.                      1.3 milliseconds.  (Or 1000000 is a bit more than
  131.                      1.3 seconds.)
  132.  
  133.     PARALLEL/S     - This option will make Enforcer use the parallel port
  134.                      hardware rather than the serial port for output.
  135.  
  136.     RAWIO/S        - This option will make Enforcer stuff the hit report
  137.     (special IO)     into an internal buffer and then from the main
  138.                      Enforcer process output the results via the
  139.                      RawPutChar() EXEC debugging LVO.  Since the output
  140.                      happens on the Enforcer task it is possible for a
  141.                      hit that ends in a system crash to not be able to
  142.                      be reported.  This option is here such that tools
  143.                      which can redirect debugging output can redirect
  144.                      the Enforcer output too.
  145.  
  146.     FILE/K         - This option will make Enforcer output the hit report
  147.     (special IO)     but to a file insted of sending it to the hardware
  148.                      directly or using the RAWIO LVO.  A good example of
  149.                      such a file is CON:0/0/640/100/HIT/AUTO/WAIT.
  150.                      Another thing that can be done is to have a program
  151.                      sit on a named pipe and have Enforcer output to it.
  152.                      This program can then do whatever it feels like with
  153.                      the Enforcer hits.  (Such as decode them, etc.)
  154.                      *NOTE*  It is not a good idea to have Enforcer hits
  155.                      go to a file on a disk as if the system crashes
  156.                      during/after the Enforcer hit, the disk may
  157.                      become corrupt.
  158.  
  159.     STDIO/S        - This option will make Enforcer output the hit report
  160.     (special IO)     to STDOUT.  This option only works from the CLI as it
  161.                      requires STDOUT.  It is best used with redirection or
  162.                      pipes.
  163.  
  164.     BUFFERSIZE/K/N - This lets you set Enforcer's internal output buffer
  165.                      for the special I/O options.  This option is only
  166.                      valid with the RAWIO, FILE, or STDIO options.
  167.                      The minimum setting is 8000.  The default is 8000.
  168.                      Having the right amount of buffer is rather
  169.                      important for the special I/O modes.  The reason
  170.                      is due to the fact that no operating system calls
  171.                      can be made from a bus error.  Thus, in the
  172.                      special I/O mode, Enforcer must store the output
  173.                      in this buffer and, via some special magic,
  174.                      wake up the Enforcer task to read the buffer and
  175.                      write it out as needed.  However, if a task is
  176.                      in Forbid() or Disable() when the Enforcer hit
  177.                      happens, the Enforcer task will not be able to
  178.                      output the results of the hit.  This buffer lets
  179.                      a number of hits happen even if the Enforcer task
  180.                      was unable to do the I/O.  If the number of
  181.                      hits that happen before the I/O was able to
  182.                      run gets too large, the last few hits will either
  183.                      be cut off completely or contain only partial
  184.                      information.
  185.  
  186.     INTRO/K        - This optional introduction string will be output
  187.                      at the start of every Enforcer hit.  For example:
  188.                      INTRO="*NBad Program!"   The default is no string.
  189.  
  190.     PRIORITY/K/N   - This lets you set Enforcer's I/O task priority.
  191.                      The default for this priority is 99.  In some
  192.                      special cases, you may wish to adjust this.
  193.                      It is, however, recommended that if you are using
  194.                      one of the special I/O options (RAWIO, FILE, or
  195.                      STDIO) that you keep the priority rather high.
  196.                      If the priority you supply is outside of the
  197.                      valid task priority range (-127 to 127) Enforcer
  198.                      will use the default priority.
  199.  
  200.     NOALERTPATCH/S - This option disables the patching of the EXEC
  201.                      Alert() function.  Normally Enforcer will patch
  202.                      this function to provide information as to what
  203.                      called Alert() and to prevent the Enforcer hits
  204.                      that a call to Alert() would cause.
  205.  
  206.     ON/S           - Mainly for completeness.  If not specified, it
  207.                      is assumed you want to turn ON Enforcer.
  208.  
  209.     QUIT=OFF/S     - Tells Enforcer to turn off.  Enforcer can also be
  210.                      stopped by sending a CTRL-C to its process.
  211.  
  212.    RESULTS
  213.     When run, a set of MMU tables that map addresses that are not
  214.     in the system's address map as invalid are installed.  Enforcer
  215.     will then trap invalid access attempts and generate a diagnostic
  216.     message as to what the illegal access was.  The first memory page
  217.     (the one starting at location 0) is also marked as invalid as many
  218.     programming errors cause invalid access to these addresses.  Invalid
  219.     addresses are completely off limits to applications.
  220.  
  221.     When an    access violation happens, a report such as the following
  222.     is output.
  223.  
  224. 03-Apr-93  21:26:18
  225. WORD-WRITE to  00000000        data=4444       PC: 07895CA4
  226. USP:  078D692C SR: 0000 SW: 0729  (U0)(-)(-)  TCB: 078A2690
  227. Data: DDDD0000 DDDD1111 DDDD2222 DDDD3333 DDDD4444 DDDD5555 DDDD6666 DDDD7777
  228. Addr: AAAA0000 AAAA1111 AAAA2222 AAAA3333 AAAA4444 AAAA5555 07800804 --------
  229. Stck: 00000000 07848E1C 00009C40 078A30B4 BBBBBBBB BBBBBBBB BBBBBBBB BBBBBBBB
  230. Stck: BBBBBBBB BBBBBBBB BBBBBBBB BBBBBBBB BBBBBBBB 078E9048 00011DA8 DEADBEEF
  231. ----> 07895CA4 - "lawbreaker"  Hunk 0000 Offset 0000007C
  232. PC-8: AAAA1111 247CAAAA 2222267C AAAA3333 287CAAAA 44442A7C AAAA5555 31C40000
  233. PC *: 522E0127 201433FC 400000DF F09A522E 012611C7 00CE4EAE FF7642B8 0324532E
  234. Name: "New_Shell"  CLI: "lawbreaker"  Hunk 0000 Offset 0000007C
  235.  
  236. LONG-READ from AAAA4444                        PC: 07895CA8
  237. USP:  078D692C SR: 0015 SW: 0749  (U0)(F)(-)  TCB: 078A2690
  238. Data: DDDD0000 DDDD1111 DDDD2222 DDDD3333 DDDD4444 DDDD5555 DDDD6666 DDDD7777
  239. Addr: AAAA0000 AAAA1111 AAAA2222 AAAA3333 AAAA4444 AAAA5555 07800804 --------
  240. Stck: 00000000 07848E1C 00009C40 078A30B4 BBBBBBBB BBBBBBBB BBBBBBBB BBBBBBBB
  241. Stck: BBBBBBBB BBBBBBBB BBBBBBBB BBBBBBBB BBBBBBBB 078E9048 00011DA8 DEADBEEF
  242. ----> 07895CA8 - "lawbreaker"  Hunk 0000 Offset 00000080
  243. PC-8: 247CAAAA 2222267C AAAA3333 287CAAAA 44442A7C AAAA5555 31C40000 522E0127
  244. PC *: 201433FC 400000DF F09A522E 012611C7 00CE4EAE FF7642B8 0324532E 01266C08
  245. Name: "New_Shell"  CLI: "lawbreaker"  Hunk 0000 Offset 00000080
  246.  
  247. 25-Jul-93  17:15:06
  248. Alert !! Alert 35000000     TCB: 07642F70     USP: 07657C10
  249. Data: 00000000 DDDD1111 DDDD2222 DDDD3333 0763852A DDDD5555 DDDD6666 35000000
  250. Addr: AAAA0000 AAAA1111 AAAA2222 AAAA3333 AAAA4444 0763852A 07400810 --------
  251. Stck: 076385A0 00000000 0752EE9A 00002800 07643994 00000000 0762F710 076305F0
  252. ----> 076385A0 - "lawbreaker"  Hunk 0000 Offset 00000098
  253.  
  254.     Here is a breakdown of what these reports are saying:
  255.  
  256.     In the first report, the first line is the date stamp.
  257.  
  258.     The first line of each report describes the access violation
  259.     and where it happened from.  In the case of a WRITE, the data
  260.     that was being written will be displayed as well.  If an instruction
  261.     mode access caused the fault, there will be an (INST) in the line.
  262.  
  263.     The first line may also contain the BUS ERROR message.  This will
  264.     be displayed when an address that is valid in the system lists
  265.     causes a physical bus fault during the access.  This usually
  266.     will happen with plug-in cards or when a hardware problem causes
  267.     some form of system fault.  Watch out, if this does show up, your
  268.     system may be unstable and/or unreliable.
  269.  
  270.     The second line (starts USP:) displays the USER stack pointer (USP),
  271.     the status register (SR:), the special status word (SW:).  It then
  272.     displays the supervisor/user state and the interrupt level.  This
  273.     will be from (U0) to (U7) or (S0) to (S7)  (S=Supervisor)  Next
  274.     is the forbid state (F=forbid, -=not) and the disable state (D or -)
  275.     of the task that was running when the access fault took place.
  276.     Finally, the task control block address is displayed (TCB:)
  277.  
  278.     The next two lines contain the data and address register dumps from
  279.     when the access fault happened.  Note that A7 is not listed here.
  280.     It is the stack pointer and is listed as USP: in the line above.
  281.  
  282.     Then come the lines of stack backtrace.  These lines show the
  283.     data on the stack.  If the stack is in invalid memory, Enforcer will
  284.     display a message to that fact.
  285.  
  286.     If SegTracker was installed before Enforcer, the "---->" lines
  287.     will display in which seglist the given addresses are in based on the
  288.     global tracking that SegTracker does.  (See docs on SegTracker)
  289.     If no seglist match is found, no lines will be displayed.
  290.     One line will be displayed for each of the stack longwords asked
  291.     for (see the STACKCHECK option) and one line for the PC address of
  292.     the Enforcer hit.  (The PC line is always checked for is SegTracker
  293.     is installed.)  The lines are in order: hit, first stack find,
  294.     second stack find, etc.  This is useful for tracking down who
  295.     called the routine that caused the Enforcer hit.
  296.  
  297.     Next, optionally, comes the data around the program counter when the
  298.     access fault happened.  The first line (PC-8:) is the 8 long-words
  299.     before the program counter.  The second line starts at the program
  300.     counter and goes for 8 long words.
  301.  
  302.     The last line displays the name of the task that was running when
  303.     the access fault took place.  If the task was a CLI, it will display
  304.     the name of the CLI command that was running.  If the access fault
  305.     was found to have happened within the seglist of a loaded program,
  306.     the segment number and the offset from the start of the segment will
  307.     be displayed.  (Note that this works for any LoadSeg()'ed process)
  308.  
  309.     Note that the name will display as "Processor Interrupt Level x"
  310.     if the access happened in an interrupt.
  311.  
  312.     The other output that could happen is when a program or the OS
  313.     calls the EXEC Alert function.  Enforcer catches these calls
  314.     and will display the alert information as seen above.  (With the
  315.     data and time if needed)
  316.  
  317.    WARNING
  318.     Enforcer is for software testing.  In this role it is vital.
  319.     Software that causes Enforcer hits may not be able to run on
  320.     newer hardware.  (Enforcer hits of high addresses on systems not
  321.     running Enforcer but with a 68040 will most likely crash the system)
  322.     Future systems and hardware will make this even more important.  The
  323.     system can NOT survive software that causes Enforcer hits.
  324.  
  325.     However, Enforcer is NOT a system protector.  As a side effect, it
  326.     may well keep a system from crashing when Enforcer hits happen, but
  327.     it may just as well make the software crash earlier.  Enforcer is
  328.     mainly a development and testing tool.
  329.  
  330.     Enforcer causes    no ill effects with correctly working software.
  331.     If a program fails to work while Enforcer is active, you should
  332.     contact the developer of that program.
  333.  
  334.    NOTES
  335.     This is Enforcer V37.  Bryce Nesbitt came up with the original
  336.     "Enforcer" that has been instrumental to the improvement in the
  337.     quality of software on the Amiga.  The Amiga users and developers
  338.     owe him a great deal for this.  Thank you Bryce!  Enforcer V37,
  339.     however, is a greatly enhanced and more advanced tool.
  340.  
  341.     Enforcer V37 came about due to a number of needs.  These included
  342.     the need for more output options and better performance.  It also
  343.     marks the removal of all kludges that were in the older versions.
  344.     Also, some future plans required some of these changes...
  345.  
  346.     In addition, the complete redesign was needed in order to
  347.     support the 68040.  The internal design of Enforcer is now set up
  348.     such that CPU/MMU specific code can be cleanly accessed from the
  349.     general house keeping aspect of the code.  The MMU bus error
  350.     handling is, however, 100% CPU specific.
  351.  
  352.     Since AbsExecBase is in low memory, reads of this address are slower
  353.     with Enforcer running.  Caching AbsExecBase locally is highly
  354.     recommended since it is in CHIP memory and on systems with FAST
  355.     memory, it will be faster to access the local cached value. (In
  356.     addition to the performance increase when running Enforcer) Note
  357.     that doing many reads of location 4 will hurt interrupt performance.
  358.  
  359.     When the Amiga produces an ALERT, EXEC places some magic numbers
  360.     into some special locations in low memory.  The exact pattern
  361.     changes between versions of the operating system.
  362.  
  363.     Enforcer will patch the EXEC function ColdReboot() in an attempt to
  364.     "get out of the way" when someone tries to reboot the system.
  365.     Enforcer will clean up as much as possible the MMU tables and then
  366.     call the original LVO.  When Enforcer is asked to quit, it will
  367.     check to make sure it can remove itself from this LVO. If it can
  368.     not, it will not quit at that time.  If run from the shell, it will
  369.     display a message saying that it tried but could not exit.  Enforcer
  370.     will continue to be active and you can try later to deactivate it.
  371.  
  372.     Enforcer will also patch the EXEC function Alert() in an attempt to
  373.     provide better tracking of other events in the system.  It is also
  374.     patched such that dead-end alerts will correctly reset the system
  375.     and be displayed.  With this patch in place, the normal alerts will
  376.     not be seen but will be replaced by the Enforcer output shown
  377.     above.  See LawBreaker for a more complete example of this.
  378.  
  379.    68020 NOTES
  380.     The 68020 does not have a built-in MMU but has a co-processor
  381.     feature that lets an external MMU be connected.  Enforcer MMU code
  382.     is designed for use with 68851 MMU.  This is the some-what 68030
  383.     compatible MMU by Motorola.  Enforcer uses the same code for both
  384.     the 68030 and the 68020/68851.  For this reason, 68020/68851 users
  385.     should see the 68030 NOTES section.
  386.  
  387.    68030 NOTES
  388.     The 68030 uses cycle/instruction continuation and will
  389.     supply the data on reads and ignore writes during an access
  390.     fault rather than let the real bus cycle happen.  This means
  391.     that on a fault caused by MMU tables, no bus cycle to the
  392.     fault address will be generated.  (For those of you with analyzers)
  393.  
  394.     In some cases, the 68030 will have advanced the Program Counter
  395.     past the instruction by the time the access fault happens.
  396.     This is usually only on WRITE faults.  For this reason, the PC
  397.     may either point at the instruction that caused the fault or
  398.     just after the instruction that caused the fault.  (Which could
  399.     mean that it is pointing to the middle of the instruction
  400.     that caused the fault.)
  401.  
  402.     Note that there is a processor called 68EC030.  This processor
  403.     has a disabled or defective MMU.  However, it may function well
  404.     enough for Enforcer to think it has a fully functional MMU and
  405.     thus Enforcer will attempt to run.  However, even if it looks like
  406.     the MMU is functioning, it is not fully operational and thus may
  407.     cause strange system activity and even crashes.  Do not assume
  408.     that Enforcer is safe to use on 68EC030 systems.
  409.  
  410.    68040 NOTES
  411.     Enforcer, on the 68040, *requires* that the 68040.library be
  412.     installed and it requires an MMU 68040 CPU.  The 68EC040 does not
  413.     have a MMU.  The 68LC040 does have an MMU and is supported. Enforcer
  414.     will work best in a system with the 68040.library 37.10 or better
  415.     but it does know how to deal with systems that do not have that
  416.     version.
  417.  
  418.     Due to the design of the 68040, Enforcer is required to do a number
  419.     of things differently.  For example, the MMU page size can only be
  420.     either 8K or 4K.  This means that to protect the low 1K of memory,
  421.     Enforcer will end up having to mark the first 4K of memory as
  422.     invalid and emulate the access to the 3K of that memory that is
  423.     valid. For this reason Enforcer moves a number of possible
  424.     structures from the first 4K of memory to higher addresses.  This
  425.     means that the system will continue to run at a reasonable speed.
  426.     The first time Enforcer is run it may need to allocate memory for
  427.     these structures that it will move.  Enforcer can never return this
  428.     memory to the system.
  429.  
  430.     In addition to the fact that the 68040 MMU table size is different,
  431.     the address fault handling is also different.  Namely, the 68040 can
  432.     only rerun the cycle and not continue it like the 68030. This means
  433.     that on a 68040, the page must be made available first and then made
  434.     unavailable.  To make this work, Enforcer will switch the instruction
  435.     that caused the error into trace mode and let it run with a special
  436.     MMU setup.  When the trace exception comes in, the MMU is set
  437.     back to the way it was.  Enforcer does its best to keep debuggers
  438.     working.  Note, however, that the interrupt level during a trace of
  439.     a READ will end up being set to 7.  This is to prevent interrupts
  440.     from changing the order of trace/MMU table execution.  The level
  441.     will be restored to the original state before continuing.  Since T0
  442.     mode tracing is also supported, there are also some changes in the
  443.     way it operates.  T0 mode tracing is defined, on the 68040, to cause
  444.     a trace whenever the instruction pipeline needed to be reloaded.
  445.     While on the 68020/030 processors this was normally only for the
  446.     branch instructions, in the 68040 this includes a large number of
  447.     other instructions.  (Including NOP!)  Anyway, if an Enforcer hit
  448.     happens while in T0 tracing mode, the trace will happen even on
  449.     instructions that normally would not cause a T0 mode trace.  Since
  450.     this may actually help in debugging and because it was not possible
  451.     to do anything else, this method of operation is deemed acceptable.
  452.  
  453.     Another issue with the 68040 is that WRITE faults happen *after* the
  454.     instruction has executed.  (Except for MOVEM)  In fact, it is common
  455.     for the 68040 to execute one or more extra instructions before the
  456.     WRITE fault is executed.  This design makes the 68040 much faster,
  457.     but it also makes the Program Counter value that Enforcer can report
  458.     for the fault much less likely to be pointing to the instruction
  459.     that caused it.  The worst cases are sequences such as a write fault
  460.     followed by a branch instruction.  In these cases, the branch is
  461.     usually already executed before the write fault happens and thus the
  462.     PC will be pointing to the target of the branch.  There is nothing
  463.     that can be done within Enforcer to help out here.  You will just
  464.     need to be aware of this and deal with it as best as possible.
  465.  
  466.     Along with the above issue, is the fact that since a write fault may
  467.     be delayed, a read fault may happen before the write fault shows up.
  468.     Internally, enforcer does not do special processing for these and
  469.     they will not show up.  Since another hit was happening anyway, it
  470.     is felt that it is best to just not report the hit.  Along the same
  471.     lines, the hit generated from a MOVEM instruction may only show as a
  472.     single hit rather than 1 for each register moved.
  473.  
  474.     On the Amiga, MOVE16 is not supported 100%.  Causing an Enforcer hit
  475.     with a MOVE16 will cause major problems and maybe cause Enforcer or
  476.     your task to lock.  Since MOVE16 is not supported, this is not a
  477.     major issue.  Just watch out if you are using this 68040
  478.     instruction.  (Also, watch out for the 68040 CPU bug with MOVE16)
  479.  
  480.     The functions CachePreDMA(), CachePostDMA(), and CacheControl() are
  481.     patched when the 68040 MMU is turned on by Enforcer.  These
  482.     functions are patched such the issues with DMA and the 68040
  483.     COPYBACK data caches are addressed.  The 68040.library normally
  484.     deals with this, however since Enforcer turns on the MMU, the method
  485.     of dealing with it in the 68040.library will not work. For this
  486.     reason, Enforcer will patch these and implement the required fix for
  487.     when the MMU is on.  When Enforcer is asked to exit, it will check
  488.     if it can remove itself from these functions.  If it can not, it
  489.     will ignore the request to exit.  If Enforcer was run from the CLI,
  490.     it will print a message saying that it can not exit when the attempt
  491.     is made.
  492.  
  493.    WRITING DEBUGGERS
  494.     If you wish to make a debugger that works with Enforcer to help
  495.     pinpoint Enforcer hits in the application and not cause Enforcer
  496.     hits itself, here are some simple tips and a bit of code.
  497.  
  498.    DEBUGGERS:  TRAPPING A HIT
  499.     To trap a hit requires a number of things to work.
  500.  
  501.     First, the debugger itself must never cause an Enforcer hit.
  502.     For help on that, see the "DEBUGGERS: NOT CAUSING A HIT"
  503.  
  504.     Second, the debugger must be global.  That is, you must be
  505.     able to deal with a task getting a hit that is not the task
  506.     under test.  There are a number of simple ways to deal with
  507.     this, and I will leave this up to the debugger writer.
  508.     (One method will be shown below)
  509.  
  510.     Third, the debugger must start *AFTER* Enforcer starts.
  511.     If it is started before Enforcer, the hits will not be
  512.     trapped.  (Note that this is not a problem)
  513.  
  514.     A very important point:  The code needs to be fast for
  515.     the special case of location 4.  This is shown in the
  516.     code below.  It is very important that this be fast.
  517.  
  518.     Note that it is much prefered that debuggers use the
  519.     method described below for trapping hits.  It should
  520.     be much more supportable this way as any of the tricky
  521.     work that may need to be done in the hit processing
  522.     will be handled by Enforcer itself.  If you wish the
  523.     hit decoded, you can capture the Enforcer output via a
  524.     pipe or some other method (such as RAWIO) or you can
  525.     leave that issue up to the user.
  526.  
  527.     Now, given the above, the following bits of code can be
  528.     used to get the debugger to switch into single-step mode
  529.     at the point of the Enforcer hit.  You can also set some
  530.     data value here to tell your debugger about this.
  531.  
  532.     ;
  533.     ; The following code is inserted into the bus error vector.
  534.     ; Make sure you follow the VBR to find the vector.
  535.     ; Store the old vector in the address OldVector
  536.     ; Make sure you already have the single-step trap vector
  537.     ; installed before you install this.  Note that any extra
  538.     ; code you add in the comment area *MUST NOT* cause a bus
  539.     ; fault of any kind, including reading of location 4.
  540.     ;
  541.     ; This is the 68020 and 68030 version...
  542.     ;
  543.     EnforcerHit:    ds.l    1                       ; Some private flag
  544.     MyTask:         ds.l    1                       ; Task under test
  545.     MyExecBase:     ds.l    1                       ; The local copy
  546.     OldVector:      ds.l    1                       ; One long word
  547.     NewVector:      cmp.l   #4,$10(sp)              ; 68020 and 68030
  548.                     beq.s   TraceSkip               ; If AbsExecBase, OK
  549.                     ;
  550.                     ; Now, if you wish to only trap a specific task,
  551.                     ; do the check at this point.  For example, a
  552.                     ; simple single-task debugger would do something
  553.                     ; like this:
  554.                     move.l  a0,-(sp)                ; Save this...
  555.                     move.l  MyExecBase(pc),a0       ; Get ExecBase...
  556.                     move.l  ThisTask(a0),a0         ; Get ThisTask
  557.                     cmp.l   MyTask(pc),a0           ; Are they the same?
  558.                     move.l  (sp)+,a0                ; Restore A0 (no flags)
  559.                     bne.s   TraceSkip               ; If not my task, skip
  560.                     ;
  561.                     bset.b  #7,(sp)                 ; Set trace bit...
  562.                     ; If you have any other data to set, do it now...
  563.                     ; Set as setting the EnforcerHit bit in your data...
  564.                     addq.l    #1,EnforcerHit          : Count the hit...
  565.                     ;
  566.     TraceSkip:      move.l  OldVector(pc),-(sp)     ; Ready to return
  567.                     rts
  568.     ;
  569.     ; This is the 68040 version...
  570.     ;
  571.     NewVector040:   cmp.l   #4,$14(sp)              ; 68040
  572.                     beq.s   TraceSkip040            ; If AbsExecBase, OK
  573.                     ;
  574.                     ; Now, if you wish to only trap a specific task,
  575.                     ; do the check at this point.  For example, a
  576.                     ; simple single-task debugger would do something
  577.                     ; like this:
  578.                     move.l  a0,-(sp)                ; Save this...
  579.                     move.l  MyExecBase(pc),a0       ; Get ExecBase...
  580.                     move.l  ThisTask(a0),a0         ; Get ThisTask
  581.                     cmp.l   MyTask(pc),a0           ; Are they the same?
  582.                     move.l  (sp)+,a0                ; Restore A0 (no flags)
  583.                     bne.s   TraceSkip               ; If not my task, skip
  584.                     ;
  585.                     bset.b  #7,(sp)                 ; Set trace bit...
  586.                     ; If you have any other data to set, do it now...
  587.                     ; Set as setting the EnforcerHit bit in your data...
  588.                     addq.l    #1,EnforcerHit          : Count the hit...
  589.                     ;
  590.     TraceSkip040:   move.l  OldVector(pc),-(sp)     ; Ready to return
  591.                     rts
  592.  
  593.    DEBUGGERS:  NOT CAUSING A HIT
  594.     In order not to cause Enforcer hits, you can do a number
  595.     of things.  The easiest is to test the address with the TypeOfMem()
  596.     EXEC function.  If TypeOfMem() returns 0, the address is not
  597.     in the memory lists.  However, this does not mean it is not a
  598.     valid address in all cases.  (ROM, chip registers, I/O boards)
  599.     For those cases, you can build a "valid memory access table"
  600.     much like Enforcer does.  Here is the code from Enforcer for
  601.     the base memory tables:
  602.  
  603.     /*
  604.      * Mark_Address(mmu,start address,length,type)
  605.      */
  606.  
  607.     /*
  608.      * Special case the first page of CHIP RAM
  609.      */
  610.     mmu=Mark_Address(mmu,0,0x1000,INVALID | NONCACHEABLE);
  611.  
  612.     /*
  613.      * Map in the free memory
  614.      */
  615.     Forbid();
  616.     mem=(struct MemHeader *)SysBase->MemList.lh_Head;
  617.     while (mem->mh_Node.ln_Succ)
  618.     {
  619.       mmu=Mark_Address(mmu,
  620.                        (ULONG)(mem->mh_Lower),
  621.                        (ULONG)(mem->mh_Upper)-(ULONG)(mem->mh_Lower),
  622.                        ((MEMF_CHIP & TypeOfMem(mem->mh_Lower)) ?
  623.                          (NONCACHEABLE | VALID) : (CACHEABLE | VALID)));
  624.       mem=(struct MemHeader *)(mem->mh_Node.ln_Succ);
  625.     }
  626.     Permit();
  627.  
  628.     /*
  629.      * Map in the autoconfig boards
  630.      */
  631.     if (ExpansionBase=OpenLibrary("expansion.library",0))
  632.     {
  633.     struct    ConfigDev    *cd=NULL;
  634.  
  635.       while (cd=FindConfigDev(cd,-1L,-1L))
  636.       {
  637.         /* Skip memory boards... */
  638.         if (!(cd->cd_Rom.er_Type & ERTF_MEMLIST))
  639.         {
  640.           mmu=Mark_Address(mmu,
  641.                            (ULONG)(cd->cd_BoardAddr),
  642.                            cd->cd_BoardSize,
  643.                            VALID | NONCACHEABLE);
  644.         }
  645.       }
  646.       CloseLibrary(ExpansionBase);
  647.     }
  648.  
  649.     /*
  650.      * Now for the control areas...
  651.      */
  652.     mmu=Mark_Address(mmu,0x00BC0000,0x00040000,VALID | NONCACHEABLE);
  653.     mmu=Mark_Address(mmu,0x00D80000,0x00080000,VALID | NONCACHEABLE);
  654.  
  655.     /*
  656.      * and the ROM...
  657.      */
  658.     mmu=Mark_Address(mmu,
  659.                      0x00F80000,
  660.                      0x00080000,
  661.                      VALID | CACHEABLE | WRITEPROTECT);
  662.  
  663.     /*
  664.      * If the credit card resource, make the addresses valid...
  665.      */
  666.     if (OpenResource("card.resource"))
  667.     {
  668.       mmu=Mark_Address(mmu,0x00600000,0x00440002,VALID | NONCACHEABLE);
  669.     }
  670.  
  671.     /*
  672.      * If CD-based Amiga (CDTV, A570, etc.)
  673.      */
  674.     if (FindResident("cdstrap"))
  675.     {
  676.       mmu=Mark_Address(mmu,0x00E00000,0x00080000,VALID | NONCACHEABLE);
  677.       mmu=Mark_Address(mmu,0x00B80000,0x00040000,VALID | NONCACHEABLE);
  678.     }
  679.  
  680.     /*
  681.      * Check for ReKick/ZKick/KickIt
  682.      */
  683.     if ((((ULONG)(SysBase->LibNode.lib_Node.ln_Name)) >> 16) == 0x20)
  684.     {
  685.       mmu=Mark_Address(mmu,
  686.                        0x00200000,
  687.                        0x00080000,
  688.                        VALID | CACHEABLE | WRITEPROTECT);
  689.     }
  690.  
  691.    SEE ALSO
  692.     "A master's secrets are only as good as the
  693.      master's ability to explain them to others."  -  Michael Sinz
  694.  
  695.    BUGS
  696.     None?
  697.  
  698. FindHit                                                               FindHit
  699.  
  700.    NAME
  701.     FindHit - A tool that can locate the source file and line number
  702.               that a SegTracker report happened at.
  703.  
  704.    SYNOPSIS
  705.     FindHit will read the executable file and if there is debugging
  706.     information in it, will try to locate the source file and line
  707.     number that correspond to the Enforcer hit HUNK/OFFSET.
  708.  
  709.    FUNCTION
  710.     FindHit uses the Lattice/SAS/MetaScope standard 'LINE'
  711.     debug hunk to locate the closest line to the hunk/offset given.
  712.     Note that this can only happen if the executable has the
  713.     LINE debugging turned on.  (The LawBreaker program has this
  714.     such that you can test this yourself.)
  715.  
  716.     In SAS/C 6.x, you need to compile with DEBUG=LINE or better
  717.     and do not use the link option of NODEBUG.
  718.  
  719.     In SAS/C 5.x, you need to compile with -d1 or better.
  720.     Note that FindHit works with the old SAS/C 5.x 'SRC '
  721.     debugging information too.  This is required for -d2 or
  722.     higher debugging support.  However, I do not have 'SRC ' hunk
  723.     documentation and thus FindHit may be very specific to the
  724.     SAS/C 5.x version of this hunk.
  725.  
  726.     In DICE (2.07 registered being the one I tried) the -d1
  727.     debug switch also supports the 'LINE' debug hunk and
  728.     works with FindHit.
  729.  
  730.     In HX68 and CAPE, you need to add the DEBUG directive to
  731.     the assembly code program.  (See LawBreaker source)
  732.  
  733.     For other languages, or other versions of the above, please
  734.     see the documentation that comes with the language.
  735.  
  736.    INPUTS
  737.     FILE/A      - The executable file, with debugging information.
  738.  
  739.     OFFSETS/A/M - The HEX offset (with or without leading $)
  740.                   If a hunk number other than the default
  741.                   is needed, it is expressed as hunk:offset.
  742.                   The default hunk is that of the last argument
  743.                   or hunk 0 if no hunk number has been given.
  744.                   For example:  12 $22 $3:12 22 4:$12 32 $0:$32
  745.                   will find information for:
  746.                   hunk $0, offset $12
  747.                   hunk $0, offset $22
  748.                   hunk $3, offset $12
  749.                   hunk $3, offset $22
  750.                   hunk $4, offset $12
  751.                   hunk $4, offset $32
  752.                   hunk $0, offset $32
  753.  
  754.    EXAMPLE
  755.     FindHit FooBar $0342 $1:4F2 3:$1A 2C
  756.     badcode.c : Line 184
  757.     No line number information for Hunk $1, Offset $4F2
  758.     badcode2.c : Line 12
  759.     badcode2.c : Line 14
  760.  
  761.     See the Enforcer documentation about issues dealing with the
  762.     exact location of the Enforcer hit.  The line given may
  763.     not be exactly where the hit happened.
  764.  
  765.     The way I use this is to always have line debugging turned on
  766.     when I compile.  This does not change the quality of the code
  767.     and takes only a small amount of extra disk space.  However,
  768.     what I do is to link the program twice:  Once to a file called
  769.     program.ld which contains all of the debugging information.
  770.     Then, I link program.ld to program, stripping debug information.
  771.     The command line for SLINK or BLINK is as follows:
  772.  
  773.         BLINK program.ld TO program NODEBUG
  774.  
  775.     I keep both of these on hand; with program being the one I
  776.     distribute and use.  When a hit happens, I can just use program.ld
  777.     with FindHit to get the line number and source file that it happened
  778.     in.  This way you can distribute your software without the debugging
  779.     information and still be able to use FindHit on the actual code.
  780.     (After all, that link command does nothing but strip symbol and
  781.     debug hunks)
  782.  
  783.    NOTES
  784.     Note that this program does nothing when run from the Workbench
  785.     and thus does not have an icon.
  786.  
  787.    SEE ALSO
  788.     "Quantum Physics:  The Dreams that Stuff is made of." - Michael Sinz
  789.  
  790.    BUGS
  791.  
  792. LawBreaker                                                         LawBreaker
  793.  
  794.    NAME
  795.     LawBreaker - A quicky test of Enforcer
  796.  
  797.    SYNOPSIS
  798.     This is a quick test of Enforcer and its reporting abilities.
  799.  
  800.    FUNCTION
  801.     This program is used to make sure that Enforcer is correctly
  802.     installed and operating.  LawBreaker works from either the CLI
  803.     or Workbench.  It will try to read and write certain memory
  804.     areas that will cause an Enforcer hit or four.
  805.  
  806.     LawBreaker will also do an Alert to show how Enforcer reports
  807.     an Alert.
  808.  
  809.     Note that the LawBreaker executable has debugging information
  810.     in it (standard LINE format debug hunk) such that you can
  811.     try the FindHit program to find the line that causes the hit.
  812.  
  813.    INPUTS
  814.     Just run it...
  815.  
  816.    RESULTS
  817.     When running Enforcer, you will see some output from Enforcer.
  818.     Output on a 68030 machine would look something like this:
  819.  
  820. 25-Jul-93  17:15:04
  821. WORD-WRITE to  00000000        data=0000       PC: 0763857C
  822. USP:  07657C14 SR: 0004 SW: 04C1  (U0)(-)(-)  TCB: 07642F70
  823. Data: DDDD0000 DDDD1111 DDDD2222 DDDD3333 0763852A DDDD5555 DDDD6666 DDDD7777
  824. Addr: AAAA0000 AAAA1111 AAAA2222 AAAA3333 AAAA4444 0763852A 07400810 --------
  825. Stck: 00000000 0752EE9A 00002800 07643994 00000000 076786D8 000208B0 2EAC80EE
  826. Stck: 487AFD12 486C82C4 4EBA3D50 4EBAEA28 4FEF0014 52ACE2E4 204D43EC 88BC203C
  827. ----> 0763857C - "lawbreaker"  Hunk 0000 Offset 00000074
  828. Name: "Shell"  CLI: "LawBreaker"  Hunk 0000 Offset 00000074
  829.  
  830. 25-Jul-93  17:15:04
  831. LONG-READ from AAAA4444                        PC: 07638580
  832. USP:  07657C14 SR: 0015 SW: 0501  (U0)(F)(-)  TCB: 07642F70
  833. Data: DDDD0000 DDDD1111 DDDD2222 DDDD3333 0763852A DDDD5555 DDDD6666 DDDD7777
  834. Addr: AAAA0000 AAAA1111 AAAA2222 AAAA3333 AAAA4444 0763852A 07400810 --------
  835. Stck: 00000000 0752EE9A 00002800 07643994 00000000 076786D8 000208B0 2EAC80EE
  836. Stck: 487AFD12 486C82C4 4EBA3D50 4EBAEA28 4FEF0014 52ACE2E4 204D43EC 88BC203C
  837. ----> 07638580 - "lawbreaker"  Hunk 0000 Offset 00000078
  838. Name: "Shell"  CLI: "LawBreaker"  Hunk 0000 Offset 00000078
  839.  
  840. 25-Jul-93  17:15:04
  841. BYTE-WRITE to  00000101        data=11         PC: 0763858A
  842. USP:  07657C14 SR: 0010 SW: 04A1  (U0)(F)(D)  TCB: 07642F70
  843. Data: 00000000 DDDD1111 DDDD2222 DDDD3333 0763852A DDDD5555 DDDD6666 DDDD7777
  844. Addr: AAAA0000 AAAA1111 AAAA2222 AAAA3333 AAAA4444 0763852A 07400810 --------
  845. Stck: 00000000 0752EE9A 00002800 07643994 00000000 076786D8 000208B0 2EAC80EE
  846. Stck: 487AFD12 486C82C4 4EBA3D50 4EBAEA28 4FEF0014 52ACE2E4 204D43EC 88BC203C
  847. ----> 0763858A - "lawbreaker"  Hunk 0000 Offset 00000082
  848. Name: "Shell"  CLI: "LawBreaker"  Hunk 0000 Offset 00000082
  849.  
  850. 25-Jul-93  17:15:04
  851. LONG-WRITE to  00000102        data=00000000   PC: 07638592
  852. USP:  07657C14 SR: 0014 SW: 0481  (U0)(-)(D)  TCB: 07642F70
  853. Data: 00000000 DDDD1111 DDDD2222 DDDD3333 0763852A DDDD5555 DDDD6666 DDDD7777
  854. Addr: AAAA0000 AAAA1111 AAAA2222 AAAA3333 AAAA4444 0763852A 07400810 --------
  855. Stck: 00000000 0752EE9A 00002800 07643994 00000000 076786D8 000208B0 2EAC80EE
  856. Stck: 487AFD12 486C82C4 4EBA3D50 4EBAEA28 4FEF0014 52ACE2E4 204D43EC 88BC203C
  857. ----> 07638592 - "lawbreaker"  Hunk 0000 Offset 0000008A
  858. Name: "Shell"  CLI: "LawBreaker"  Hunk 0000 Offset 0000008A
  859.  
  860. 25-Jul-93  17:15:06
  861. Alert !! Alert 35000000     TCB: 07642F70     USP: 07657C10
  862. Data: 00000000 DDDD1111 DDDD2222 DDDD3333 0763852A DDDD5555 DDDD6666 35000000
  863. Addr: AAAA0000 AAAA1111 AAAA2222 AAAA3333 AAAA4444 0763852A 07400810 --------
  864. Stck: 076385A0 00000000 0752EE9A 00002800 07643994 00000000 0762F710 076305F0
  865. ----> 076385A0 - "lawbreaker"  Hunk 0000 Offset 00000098
  866.  
  867.     Now, using FindHit, you would type:
  868.  
  869.     FindHit LawBreaker 0:82
  870.  
  871.     and it will tell you the source file name and the line number
  872.     where the hit happened.  See the FindHit documentation.
  873.  
  874.    NOTES
  875.     If enforcer is not running, the program should not cause the
  876.     system to crash.  It will, however, write to certain areas
  877.     of low memory.  Also, it will cause read access of some
  878.     addresses that may not exist.  This may cause bus faults.
  879.  
  880.    SEE ALSO
  881.     "Quantum Physics:  The Dreams that Stuff is made of." - Michael Sinz
  882.  
  883.    BUGS
  884.     There are 4 known Enforcer hits in this code and 1 alert, however,
  885.     they will not be fixed.  ;^)
  886.  
  887. Move4K                                                                 Move4K
  888.  
  889.    NAME
  890.     Move4K - Moves as much out of the lower 4K of RAM as possible
  891.  
  892.    SYNOPSIS
  893.     On 68040 systems, as much of the lower 4K of CHIP RAM as possible
  894.     is removed from system use.
  895.  
  896.    FUNCTION
  897.     On 68040 systems the MMU page sizes are 4K and 8K.  Enforcer
  898.     uses the 4K page size.  Since watching for hits of low memory
  899.     is a vital part of Enforcer, this means that the first 4K
  900.     of RAM will be marked invalid.  On current systems, only
  901.     the first 1K of RAM is invalid and thus 3K of RAM in that
  902.     first 4K will end up needing to be emulated in Enforcer.
  903.     In order to reduce the overhead that this causes (and the
  904.     major performance loss) this program will try to move as much
  905.     from that first 4K as possible and make any of the free
  906.     memory within the first 4K inaccessible.
  907.  
  908.     Enforcer itself also has this logic, but it may be useful
  909.     to be able to run this program as the first program in
  910.     the Startup-Sequence (*AFTER* SetPatch) to try to limit
  911.     the number of things that may use the lower 4K of RAM.
  912.  
  913.    INPUTS
  914.     Just run it...  Can be run from CLI or Workbench
  915.  
  916.    RESULTS
  917.     Any available memory in the lower 4K of CHIP RAM is removed
  918.     plus a special graphics buffer is moved if it needs to be.
  919.     After running this program you may have a bit less CHIP RAM
  920.     than before.  You can run this program as many times as you
  921.     wish since it only moves things if it needs to.
  922.  
  923.    NOTES
  924.     This program will do nothing on systems without a 68040.
  925.     It does not, however, check for the MMU and thus it will
  926.     move the lower 4K even if the CPU is not able to run Enforcer.
  927.  
  928.     V39 of the operating system already does have the lowest
  929.     MMU page empty and thus this program will effectively do
  930.     nothing under V39.
  931.  
  932.    SEE ALSO
  933.     "Eloquence is vehement simplicity"
  934.  
  935.    BUGS
  936.     None.
  937.  
  938. RebootOff                                                           RebootOff
  939.  
  940.    NAME
  941.     RebootOff - A keyboard reset handler to turn off Enforcer
  942.  
  943.    SYNOPSIS
  944.     This is a simple utility that will turn off Enforcer when a
  945.     keyboard reset happens.
  946.  
  947.    FUNCTION
  948.     This utility uses the feature of the A1000/A2000/A3000/A4000
  949.     Amiga systems to turn off Enforcer when the user does a
  950.     keyboard reset (ctrl-Amiga-Amiga).  This utility requires that
  951.     your Amiga supports (in hardware) the keyboard reset system.
  952.  
  953.     The reason this was written was such that Enforcer could be
  954.     "quit" just before you reboot your Amiga 3000.  This way
  955.     it will let the kickstart not need to be reloaded and
  956.     thus let utilities such as RAD: work across reboots.  Note
  957.     that this does *not* help in the case where the Amiga reboots
  958.     under software conditions.  It is only for keyboard resets.
  959.  
  960.    INPUTS
  961.     Just run it from either the CLI or Workbench.  It installs
  962.     a handler and exits.  On a keyboard reset, it will turn Enforcer
  963.     off before it lets the reset continue...  (max time of 10 seconds)
  964.  
  965.    RESULTS
  966.     Installs a small reset handler object and task into the system.
  967.     About 3700 bytes needed the first time it is run.
  968.  
  969.    NOTES
  970.     If Enforcer is not running, nothing will happen at Reset time.
  971.     If Enforcer can not quit, the reset system will continue to try
  972.     to quit Enforcer until the hardware timeout happens...
  973.  
  974.    SEE ALSO
  975.     From the home of the imaginary deadlines:
  976.     "It will take 2i weeks to do that project." - Michael Sinz
  977.  
  978. SegTracker                                                         SegTracker
  979.  
  980.    NAME
  981.     SegTracker - A global SegList tracking utility
  982.  
  983.    SYNOPSIS
  984.     A global tracking utility for disk loaded files including
  985.     libraries and devices.  If placed in the startup-sequence
  986.     right after SetPatch, it will track all disk loaded segments
  987.     (other than those loaded by SetPatch)
  988.  
  989.    FUNCTION
  990.     SegTracker will patch the DOS LoadSeg(), NewLoadSeg(), and UnLoadSeg()
  991.     functions in order to track the SegLists that are loaded.
  992.     SegTracker keeps these seglist stored in a "safe" manner and
  993.     even handles programs which SegList split.
  994.  
  995.     The first time the program is run, it installs the patches
  996.     and semaphore.  After that point, it just finds the semaphore
  997.     and uses it.
  998.  
  999.     When SegTracker is installed, it will scan the ROM for ROM modules
  1000.     and add their locations to the tracking list such that addresses
  1001.     within those modules can be identified.  Note that the offsets
  1002.     from the module is based on the location of the module's ROMTAG.
  1003.     The NOROM option will prevent this feature from being installed.
  1004.  
  1005.     By using SegTracker, it will be possible to better identify
  1006.     where Enforcer hits come from when dealing with libraries
  1007.     and devices.  Basically, it is a system-global Hunk-o-matic.
  1008.  
  1009.     External programs can then pass in an address to SegTracker
  1010.     either via the command line or via the given function pointer
  1011.     in the SegTracker semaphore and get back results as to what
  1012.     hunk and offset the address is at.
  1013.  
  1014.     To work with the function directly, you need to find the
  1015.     the semaphore of "SegTracker" using FindSemaphore().
  1016.     The structure found will be the following:
  1017.  
  1018.     struct  SegSem
  1019.     {
  1020.     struct  SignalSemaphore seg_Semaphore;
  1021.             SegTrack        *seg_Find;
  1022.     };
  1023.  
  1024.     The function pointer points to a routine that takes an address
  1025.     and two pointers to long words for returning the Segment number
  1026.     and Offset within the segment.  The function returns the name
  1027.     of the file loaded.  Note that you must call this function
  1028.     while in Forbid() and then copy the name as the seglist may
  1029.     be UnLoadSeg'ed at any moment and the name string will then
  1030.     no longer be in memory.
  1031.  
  1032.     typedef    char (* __asm SegTrack(register __a0 ULONG Address,
  1033.                                    register __a1 ULONG *SegNum,
  1034.                                    register __a2 ULONG *Offset));
  1035.  
  1036.     The above is for use in C code function pointer prototype
  1037.     in SAS/C 5 and 6.
  1038.  
  1039.    INPUTS
  1040.     SHOW/S  - Shows all of the segments being tracked.
  1041.  
  1042.     DUMP/S  - Displays all of the segment elements being tracked.
  1043.  
  1044.     NOROM/S - Tells segtracker not to scan ROM when it is
  1045.               installed, thus not adding ROM addresses to the
  1046.               tracking list.
  1047.  
  1048.     FIND/M  - Find the hex (in $xxxxx format) address in
  1049.               the tracked segments.  Multiple addresses
  1050.               can be given.
  1051.  
  1052.     Options are not available from Workbench as they require
  1053.     the CLI.  However, you can run SegTracker from Workbench
  1054.     to install it.
  1055.  
  1056.    EXAMPLE USAGE
  1057.     /*
  1058.      * A simple program that will "find" given addresses in the SegLists
  1059.      * This program has been compiled with SAS/C 6.2 without errors or
  1060.      * warnings.
  1061.      *
  1062.      * Compiler options:
  1063.      * DATA=FARONLY PARAMETERS=REGISTER NOSTACKCHECK
  1064.      * NOMULTIPLEINCLUDES STRINGMERGE STRUCTUREEQUIVALENCE
  1065.      * MULTIPLECHARACTERCONSTANTS DEBUG=LINE NOVERSION
  1066.      * OPTIMIZE OPTIMIZERINLOCAL NOICONS
  1067.      *
  1068.      * Linker options:
  1069.      * FindSeg.o TO FindSeg SMALLCODE SMALLDATA NODEBUG LIB LIB:sc.lib
  1070.      */
  1071.     #include <exec/types.h>
  1072.     #include <exec/execbase.h>
  1073.     #include <exec/libraries.h>
  1074.     #include <exec/semaphores.h>
  1075.     #include <dos/dos.h>
  1076.     #include <dos/dosextens.h>
  1077.     #include <dos/rdargs.h>
  1078.  
  1079.     #include <clib/exec_protos.h>
  1080.     #include <pragmas/exec_sysbase_pragmas.h>
  1081.  
  1082.     #include <clib/dos_protos.h>
  1083.     #include <pragmas/dos_pragmas.h>
  1084.  
  1085.     #include <string.h>
  1086.  
  1087.     #include "FindSeg_rev.h"
  1088.  
  1089.     #define EXECBASE (*(struct ExecBase **)4)
  1090.  
  1091.     typedef char (* __asm SegTrack(register __a0 ULONG,
  1092.                                    register __a1 ULONG *,
  1093.                                    register __a2 ULONG *));
  1094.  
  1095.     struct SegSem
  1096.     {
  1097.     struct SignalSemaphore seg_Semaphore;
  1098.            SegTrack        *seg_Find;
  1099.     };
  1100.  
  1101.     #define SEG_SEM "SegTracker"
  1102.  
  1103.     #define TEMPLATE "FIND/M" VERSTAG
  1104.  
  1105.     #define OPT_FIND  0
  1106.     #define OPT_COUNT 1
  1107.  
  1108.     ULONG cmd(void)
  1109.     {
  1110.     struct ExecBase *SysBase;
  1111.     struct Library  *DOSBase;
  1112.     struct RDArgs   *rdargs;
  1113.            ULONG    rc=RETURN_FAIL;
  1114.     struct SegSem   *segSem;
  1115.            char     **hex;
  1116.            LONG     opts[OPT_COUNT];
  1117.  
  1118.       SysBase = EXECBASE;
  1119.       if (DOSBase = OpenLibrary("dos.library",37))
  1120.       {
  1121.         memset((char *)opts, 0, sizeof(opts));
  1122.  
  1123.         if (!(rdargs = ReadArgs(TEMPLATE, opts, NULL)))
  1124.         {
  1125.           PrintFault(IoErr(),NULL);
  1126.         }
  1127.         else if (CheckSignal(SIGBREAKF_CTRL_C))
  1128.         {
  1129.           PrintFault(ERROR_BREAK,NULL);
  1130.         }
  1131.         else if (segSem=(struct SegSem *)FindSemaphore(SEG_SEM))
  1132.         {
  1133.           rc=RETURN_OK;
  1134.           if (opts[OPT_FIND])
  1135.           {
  1136.             for (hex=(char **)opts[OPT_FIND];(*hex);hex++)
  1137.             {
  1138.             char  *p;
  1139.             ULONG val;
  1140.             ULONG tmp[4];
  1141.             ULONG c;
  1142.  
  1143.               val=0;
  1144.               p=*hex;
  1145.               if (*p=='$') p++; /* Support $hex */
  1146.               while (*p)
  1147.               {
  1148.                 c=(ULONG)*p;
  1149.                 if ((c>='a') && (c<='f')) c-=32;
  1150.                 c-='0';
  1151.                 if (c>9)
  1152.                 {
  1153.                   c-=7;
  1154.                   if (c<10) c=16;
  1155.                 }
  1156.  
  1157.                 if (c<16)
  1158.                 {
  1159.                   val=(val << 4) + c;
  1160.                   p++;
  1161.                 }
  1162.                 else
  1163.                 {
  1164.                   val=0;
  1165.                   p=&p[strlen(p)];
  1166.                 }
  1167.               }
  1168.  
  1169.               /*
  1170.                * Ok, we need to do this within Forbid()
  1171.                * as segments can unload at ANY time, including
  1172.                * during AllocMem(), so we use a stack buffer...
  1173.                *
  1174.                */
  1175.               Forbid();
  1176.               if (p=(*segSem->seg_Find)(tmp[0]=val,&tmp[2],&tmp[3]))
  1177.               {
  1178.               char Buffer[200];
  1179.  
  1180.                 stccpy(Buffer,p,200);
  1181.                 tmp[1]=(ULONG)Buffer;
  1182.                 VPrintf("$%08lx - %s : Hunk %ld, Offset $%08lx",tmp);
  1183.  
  1184.                 /*
  1185.                  * Now get the SegList address by passing the
  1186.                  * same pointer for both hunk & offset.  Note
  1187.                  * that this is only in the newer SegTrackers
  1188.                  * To test if this worked, check if the result
  1189.                  * of this call is either a hunk or an offset.
  1190.                  */
  1191.                 (*segSem->seg_Find)(val,&tmp[0],&tmp[0]);
  1192.                 /*
  1193.                  * This "kludge" is for compatibility reasons
  1194.                  * Check if result is the same as either the hunk
  1195.                  * or the offset.  If so, do not print it...
  1196.                  */
  1197.                 if ((tmp[0]!=tmp[2]) && (tmp[0]!=tmp[3]))
  1198.                 {
  1199.                   VPrintf(", SegList $%08lx",tmp);
  1200.                 }
  1201.  
  1202.                 PutStr("\n");
  1203.               }
  1204.               else VPrintf("$%08lx - Not found\n",tmp);
  1205.               Permit();
  1206.             }
  1207.           }
  1208.         }
  1209.         else PutStr("Could not find SegTracker semaphore.\n");
  1210.  
  1211.         if (rdargs) FreeArgs(rdargs);
  1212.         CloseLibrary(DOSBase);
  1213.       }
  1214.       else if (DOSBase=OpenLibrary("dos.library",0))
  1215.       {
  1216.         Write(Output(),"Requires Kickstart 2.04 (37.175) or later.\n",43);
  1217.         CloseLibrary(DOSBase);
  1218.       }
  1219.  
  1220.       return(rc);
  1221.     }
  1222.  
  1223.    NOTES
  1224.     The earlier this command is run, the better off it will be in
  1225.     tracking disk loaded segments.  Under debug usage, you may
  1226.     wish to run the command right *AFTER* SetPatch.
  1227.  
  1228.     Some things may not call UnLoadSeg() to free their seglists.
  1229.     There is no way SegTracker can follow a seglist that is not
  1230.     unloaded via the dos.library call to UnLoadSeg().  For this
  1231.     reason, SegTracker adds new LoadSeg() segments to the top
  1232.     of its list.  This way, if any old segments are still on
  1233.     the list but have been unloaded via some other method
  1234.     they will not clash with newer segments during the find operation.
  1235.  
  1236.     Note that the resident list is one such place where
  1237.     UnLoadSeg() is not called to free the seglist.  Thus,
  1238.     if something is made resident and then later unloaded
  1239.     it will still be listed as tracked by SegTracker.
  1240.  
  1241.     In order to support a new feature in CPR, the SegTracker function
  1242.     got a "kludge" added to it.  If a segment is found, you can then
  1243.     call the function again with the same address but with having
  1244.     both pointers point to the same longword of storage.  By doing
  1245.     this, the function will now return (in that longword) the
  1246.     SegList pointer (CPTR not BPTR) of the file that contains
  1247.     the address.  The reason this method was used was so it
  1248.     would be compatible with older SegTracker versions.  In older
  1249.     versions you would not get the result you wanted but you would
  1250.     also not crash.  See the example above for more details on how
  1251.     to use this feature.  The SegTracker FIND option has been
  1252.     expanded to include this information.
  1253.  
  1254.     Due to the fact that I am working on a design of a new set of
  1255.     debugging tools (Enforcer/SegTracker/etc)  I do not wish to
  1256.     expand the current SegTracker model in too many ways.
  1257.  
  1258.    SEE ALSO
  1259.     "Quantum Physics:  The Dreams that Stuff is made of." - Michael Sinz
  1260.  
  1261.    BUGS
  1262.  
  1263.