Aminet 10/aminetcdnumber101996.iso/Aminet/util/wb/PatchWBPens.lha/Patch.man

Text File | 1994-08-13 | 8KB | 203 lines

patch.library V3.50 manual:


MOTIVATION:

    The idea for this library came up to me, when I recently wrote some
    programs, which patch into library functions.



FEATURES:

- In general patch.library offers you an easy way of installing and removing
  your own patches for library functions.

- Patch.library checks, if your patch can safely be removed (e.g.: when no
  other task is running in the patchcode).

- In general patches may only be removed in LIFO order. Patch.library
  provides a mechanism that allows you to remove any patch you installed
  with patch.library any time.

- In addition it provides you a priority system, which allows you to specify
  the sequence of the patches, if more than one patch has to be installed for
  one library function.

- Patch.library also provides you a way to check, if your patch is already
  installed by supplying a name field for every patch.

- Patch.library automatically flushes caches from Kick V37.xxx on, so software
  that uses patch.library will continue to work on systems with an 68040 or ....

- With patch.library you have no problems patching pre-V36 dos.library
  functions, since patch.library automatically detects these nonstandard
  functions and takes the appropriate steps to patch these functions.

- The tasks using the patch may be limited to certain tasknames and/or taskIDs.

- But always remember that installing and especially removing patches can never
  be coded without any risk of crashing the machine. Although patch.library does
  everything possible to minimize the chances of a crash, do not use its functions
  without good care (e.g. minimize the number of install and remove operations)



NEWS FOR V2:
- New functions for V2:
   * RemovePatchTags()
    replaces the obsolete functions RemovePatch() and WaitRemovePatch()
    patches can now be removed ANY TIME
   * InstallPatchTags()
    replaces the obsolete function InstallPatch()
    patching of libraries, devices and resources is now possible
- Many of the internal structures have been made public, so the lists may be
  scanned by application programs. Note that these structures were rearranged
  for V2, so make sure that at least patch.library V2 is installed.
  Also make sure to use the semaphore protection, when scanning these lists.
- Some bugs have been removed and a few possible locking problems have been solved.



NEWS FOR V3:
- New functions for V3:
   * FindPatchTags()
    can be used instead of the old FindPatch() function, but takes a
    taglist as parameter for future enhancements.
   * SetPatch()
    Makes it possible to limit the tasks, which will use a patch.
    (e.g.: A OpenWindow() function patch will only apply, if CygnusED opens
    a window / A DisplayBeep() function patch will be used for all
    tasks, but not for the task, which has the TaskID $007c835a).
    Some other attributes of a patch may also be set.
   * GetPatch()
    This function will, return some attributes and lists of a patch.
   * PatchFreeVec()
    Frees memory returned by GetPatch().


ABOUT PATCHCODES:

The patchcode you install must obey these rules:
- Patchcodes MUST be reentrant! (i.e. library-functions can always be used
  by multiple tasks at the same time)
- Patchcodes MUST preserve ALL registers!
  (If replacing a library function a valid returncode must be set as documented
  in the Autodocs)
- Patchcodes MUST be pc-relative, if NewCodeSize > 0!
- Patchcodes should use as little stack as possible, because tasks using your code
  may otherwise run out of stack.
- Patchcodes can be ended either with the rts-instruction, which is the normal
  method, or with the FALLBACK macro provided in 'Patch.i'.
  The FALLBACK macro allows You to end the patch and execute the original
  library function, if you replaced the library function (Priority = 0).
  The FALLBACK macro functions like a 'rts'-instruction, if Priority <> 0.



NOTES & WARNINGS:

- Some library functions use in-line code (e.g.: exec.library/GetCC() )
  Patching these functions will always fail.
- It's up to your patchroutines to preserve the registers.
- There is always a chance (very small) that memory will be deallocated, while
  instructions from it will still executed (-> crash).
- Patching functions will use some stack (at least 4 Bytes) from programs
  calling the patched function. This might crash the machine, if a program
  has only a very small stack reserve.
- The patches should be written in assembler - support for C-patches is currently
  not provided, but it should be possible to write the appropriate stub.



MORE PROGRAMMER INFOS:

can be found in the accompanying file 'patch.doc' and in the example programs.



FUTURE PLANS:
- Create AmigaGuide documentations.
- Write a program, that works similar to SaferPatches, but uses patch.library.
- Write a commodity similar to the Commodity Exchange program that allows
    manipulations of the IncludeTask, ExcludeTask lists of the patches
    and a way to load and save these settings (already under development).
- Program more applications using the patch.library.



EXAMPLES:

The package includes two programs with assembler source to show you how
to use the patch.library:

1. CPUClr:
    Installs a patch routine for graphics.library/BltClear(), which
    uses the CPU instead of the BLITTER to clear Chipmem.
    It shows how easy and save it can be to install and remove a patch,
    without wasting memory or CPU time.
    With the program CPUClrTEST you can check how much faster memory
    clearing becomes.
    For more informations about CPUClr see CPUClr.doc.

2. ShowNeededFiles:    (Simple SnoopDos)
    Installs some patch routines to monitor dos.library/Open(),
    Lock() and LoadSeg() functions. It shows how the priority system
    of patch.library works.
    Note that this program works with all versions of the dos.library.
    Break this program with CTRL-C.



LICENSE:

This material is © Copyright 1993/94 by Stefan Fuchs. All rights reserved.

It may be distributed freely as long as the following restrictions are met:

- The distributor may charge a fee to recover distribution costs.
  The fee for diskette distribution should not be more than
  the cost to obtain the same diskette from Fred Fish.

- The distributor agrees to cease distributing the programs and
  data involved if requested to do so by the author.

- You may copy and distribute verbatim copies of the program's
  executable code and documentation as you receive it, in any
  medium, provided that you conspicuously and appropriately
  publish only the original, unmodified program, with all
  copyright notices and disclaimers of warranty intact and
  including all the accompanying documentation, example files and
  anything else that came with the original.

- If you are interested in including any of this material in a commercial
  product, you should contact the author for his permission.

- The author will not be liable for any damage arising from the
  failure of the programs or the library to perform as described,
  or any destruction of other programs using the library residing
  on a system. While I know of no damaging errors, the user of this
  package uses it at his or her own risk.


This package may be distributed in PD-series (e.g.: the Fred Fish library)!


CONTACT:

    To contact the author for bugreports, hints, ideas, donations, ....
    write to:


    Stefan Fuchs                 E-Mail: [e-mail]
    Oskar-von-Miller-Str. 49

    D - 90478 Nürnberg
    GERMANY


AND FINALLY:
    If You use patch.library in any of your projects, please sent me a copy,
    of your program, so i can make sure that everything works fine with
    future versions of patch.library.