P A T C H   U T I L I T I E S 
__________________________________________________________________________
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯


The AmigaOS' patch function is quite limited. It is only possible to remove
all patches in the opposite order they were installed. Otherwise, trouble
will occur.

So, some smart programmers wrote utilities that patches the OS patch function
and replace it with a better one. Then you can remove all patches in any order
you like. I strongly suggest to use such a program.

Anyhow, some problems may occur, since PatchWork patches some fundamental
functions (e. g. AllocMem() and Permit()). If you have such problems, delete
the bad patch utility and find a new one.


 STACK TROUBLE 
---------------

It is crucial that PatchWork finds the caller's PC on the stack, and nothing
before that. If a patch utility pushes some data on the stack before starting
the patch functions, PatchWork will show the utilities PC instead of the callers
PC.

I currently don't know a patch utility with that problem. Anyhow, be prepared.


 FUNCTION TROUBLE 
------------------

A serious problem is if the new SetFunction() routine of the patch utility uses
any OS functions after setting the new function vector. Let me explain why.

For example, our program will patch the Permit() function.

This is the state before SetFunction() has been called.

                +----------+                            +--------------------+
  BEFORE        | Permit() |--------------------------->| Permit OS function |
                +----------+                            +--------------------+
                                 +--------------+
                                 | Permit patch |-----> NIL
                                 +--------------+

We can see the Permit() entry pointing to the Permit OS function in ROM, and
our patch which has not yet been inserted.

Usually, SetFunction() writes the new function address into the library and
returns a pointer to the old function address.

  After         +----------+                            +--------------------+
  SetFunction() | Permit() |-+               Return --->| Permit OS function |
                +----------+ |                          +--------------------+
                             |   +--------------+
                             +-->| Permit patch |-----> NIL
                                 +--------------+

Our patch can now jump to the original Permit OS function, thus building a
chain:

                +----------+                            +--------------------+
  AFTER         | Permit() |-+                     +--->| Permit OS function |
                +----------+ |                     |    +--------------------+
                             |   +--------------+  |
                             +-->| Permit patch |--+
                                 +--------------+

But there is one weak point! After SetFunction() has been executed (but before
our patch points back to the ROM function), the Permit patch still points to NIL.
If someone would call Permit() at this stage, the system would crash immediately.

Usually, there is no chance for that, since patches are applied while the system
is Forbid()den. But when the patch utility calls Permit(), or breaks the disabled
state, the system will crash!

PatchWork does not point to NIL, but will show up the alert "8BADC0DE" instead.
If this one will show up while starting PatchWork, you will know that your
patch utility is faulty. Anyhow, this alert won't show in all cases. Another
good hint is if your system crashes after launching PatchWork.


 WORKING ONES 
--------------

These Utilities are known to work with PatchWork:

  · PatchControl V2.3 or higher (AlienDesign, see MCP packet)
  · SaferPatches V2.04 or higher
  · No patch utility at all... ;-)


 NOT WORKING ONES 
------------------

These Utilities are known to fail:

  · SaferPatches V2.03 and before
  · MagicMenu V2.25 (use NOPERMIT)


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

If you are using patch utilities, then make sure that they are started before
PatchWork is running. Don't start them afterwards!

If the system will then crash during startup, or the alert occurs, then delete
that tool and use a newer or other one...

There is an alternative you may try: use the NOPERMIT parameter to disable the
exec/Permit() patch. This will help in some cases, as e.g. MagicMenu V2.25.