U S A G E 
__________________________________________________________________________
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

 REQUIREMENTS 
--------------

  · AmigaOS 2.04 (V37) or higher (V36 won't work!)
  · A terminal connected to the internal serial port, or Sushi
  · SegTracker (not required, but suggested)
  · disassembler.library by Thomas Richter (optionally)

 INSTALLATION 
--------------

   Just copy PatchWork into your CLI path and this guide file into whereever
you store good documentations. ;)

   You should start PatchWork after SetPatch and after any SetFunction()
enhancer (e.g. PatchControl).

 START 
-------

   You need to start PatchWork from the shell, as it is no Workbench tool.

   PatchWork won't detach, so you should use "run <>NIL: PatchWork" if you
want to start it in the startup-sequence.

   You can always remove PatchWork by pressing <CTRL>-<C>, sending a break,
or starting another instance of PatchWork.

 SHELL PARAMETERS 
------------------

LEVEL/K/N       Set the severity threshold to be put out. Defaults
                to 0. More about severity levels see below.

MINOS/K/N       You can provide the minimal required OS version of your
                program here. Any PatchWork hit that is fixed starting
                from this OS version will be suppressed. E.g. if your
                program requires at least AmigaOS 39, just provide MINOS=39.

TINY/S          Tiny output. Just show the cause of the hit.

SMALL/S         Small output. Shows the cause of the hit and the PC,
                TCB and Task name.

STACKLINES/K/N  Number of stack lines to be output. Each stack line
                consists of 32 stack bytes. There is no limit here!

STACKCHECK/S    Check also all stack entries with SegTracker

SHOWPC/S        Show 32 bytes around the current PC

AREGCHECK/S     Check also the contents of the address registers
                with SegTracker.

DREGCHECK/S     Check also the contents of the data registers with
                SegTracker.

ROMHITS/S       Usually, all hits caused by the AmigaOS ROM will be
                suppressed. With this option set, they will also be shown.
                Yes, the AmigaOS ROM actually throws PatchWork hits!

DEADLY/S        With this option set, some functions will return a worst
                case scenario return code instead of the real return code
                under certain conditions. See patch documentation below.

DISABLECHECK/S  It is only allowed to disable system interrupts for a
                maximum time of 250ms.  This option will check if this time
                range is kept. A 68020 or better is required for this test.
                It won't work on most Amiga emulations and might trouble on
                DraCo. Even more, this test could cause hardware timeouts,
                so be very careful and do not use this option permanently.
                If you don't know what I'm talking about, I strongly
                encourage you not to use this option!

NOPERMIT/S      Does not patch the Permit() function. This is useful
                if your system crashes on start of PatchWork (or shows an
                8BADC0DE alert), caused by a poor patch utility. There is no
                reason to use this option if PatchWork starts up without any
                problems.

DISPC/S         Show a disassembly of the code around the current PC. This
                option requires Thomas Richter's disassembler.library to
                be installed properly.

DISRANGE/K/N    Range of bytes to be disassembled before and after the
                PC. Defaults to 32.


 BADNESS LEVELS 
----------------

   All hits are divided into four levels of severity. The higher the
level, the more probable is a system crash caused by it.

   0    Hits with level 0 won't crash the system. They are legal and
        absolutely harmless. The only function of level 0 hits are
        for mental notes, e.g. that a special OS version is required
        for the function or the way it is used. Also see MINOS.

   1    Hits with level 1 also won't crash the system, but they are
        ugly, obsoleted, needless or waste system time, as e.g. an
        "AllocMem(0)" or "OldOpenLibrary("...")".

   2    Hits with level 2 might crash the system, especially with
        multitasking interaction. This are e.g. FindPort()s without
        a prior Forbid(). You must not rely on a result you get from
        a level 2 hit! It has most probably already changed. If not,
        it is just luck, but nothing more... ;-)

        With the DEADLY option, some of the level 2 hits will try to
        crash your program by returning worst case return codes.

   3    Hits with level 3 will crash the system sooner or later. They
        are used against the rules of AutoDocs, and thus will have
        unpredictable results. Or they will result in memory loss. In
        any way, they are used wrong.

        Two examples: CopyMem() with overlapping memory areas, or
        DeleteMsgPort() without clearing up the message queue before.

   ANY hit starting from level 1 is a real bad hit, and should be
removed if possible, to enhance system stability and future compatibility.