home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d8xx / d886 / patchlibrary.lha / PatchLibrary / Patch.man < prev    next >
Encoding:
Text File  |  1993-07-16  |  5.5 KB  |  161 lines
  1. patch.library V1.55 manual:
  2.  
  3.  
  4. MOTIVATION:
  5.  
  6.     The idea for this library came up to me, when I recently wrote some
  7.     programs, which patch into library functions.
  8.  
  9.  
  10.  
  11. FEATURES:
  12.  
  13. - In general patch.library offers you an easy way of installing and removing
  14.   your own patches for library functions.
  15.  
  16. - Patch.library checks, if your patch can safely be removed (e.g.: when no
  17.   other task is running in the patchcode).
  18.  
  19. - In general patches may only be removed in LIFO order. Patch.library
  20.   provides a mechanism that allows you to remove any patch you installed
  21.   with patch.library almost any time (currently it is not possible to remove
  22.   the last installed patch, if other non-patch.library patches for the same
  23.   function have been installed later).
  24.  
  25. - In addition it provides you a priority system, which allows you to specify
  26.   the sequence of the patches, if more than one patch has to be installed for
  27.   one library function.
  28.  
  29. - Patch.library also provides you a way to check, if your patch is already
  30.   installed by supplying a name field for every patch.
  31.  
  32. - Patch.library automatically flushes caches from Kick V37.xxx on, so software
  33.   that uses patch.library will continue to work on systems with an 68040 or ....
  34.  
  35. - With patch.library you have no problems patching pre-V36 dos.library
  36.   functions, since patch.library automatically detects these nonstandard
  37.   functions and takes the appropriate steps to patch these functions.
  38.  
  39. - But always remember that installing and especially removing patches can never
  40.   be coded without any risk of crashing the machine. Although patch.library does
  41.   everything possible to minimize the chances of a crash, do not use its functions
  42.   without good care (e.g. minimize the number of install and remove operations)
  43.  
  44.  
  45.  
  46. ABOUT PATCHCODES:
  47.  
  48. The patchcode you install must obey these rules:
  49. - Patchcodes MUST be reentrant! (i.e. library-functions can always be used
  50.   by multiple tasks at the same time)
  51. - Patchcodes MUST preserve ALL registers!
  52.   (If replacing a library function a valid returncode must be set as documented
  53.   in the Autodocs)
  54. - Patchcodes MUST be pc-relative, if NPAT_NewCodeSize > 0!
  55. - Patchcodes should use as little stack as possible, because tasks using your code
  56.   may otherwise run out of stack.
  57. - Patchcodes can be ended either with the rts-instruction, which is the normal
  58.   method, or with the FALLBACK macro provided in 'PatchLibrary.i'.
  59.   The FALLBACK macro allows You to end the patch and execute the original
  60.   library function, if you replaced the library function (NPAT_Priority = 0).
  61.   The FALLBACK macro functions like a 'rts'-instruction, if NPAT_Priority <> 0.
  62.  
  63.  
  64.  
  65. NOTES & WARNINGS:
  66.  
  67. - Some library functions use in-line code (e.g.: exec.library/GetCC() )
  68.   Patching these functions will always fail.
  69. - It's up to your patchroutines to preserve the registers.
  70. - There is always a chance (very small) that memory will be deallocated, while
  71.   instructions from it will still executed (-> crash).
  72. - Patching functions will use some stack (at least 4 Bytes) from programs
  73.   calling the patched function. This might crash the machine, if a program
  74.   has only a very small stack reserve.
  75. - Files for C-support are not tested in detail (sorry!!)
  76.  
  77.  
  78.  
  79. MORE PROGRAMMER INFOS:
  80.  
  81. can be found in the accompanying file 'patch.doc' and in the example programs.
  82.  
  83.  
  84.  
  85. EXAMPLES:
  86.  
  87. The package includes two programs with assembler source to show you how
  88. to use the patch.library:
  89.  
  90. 1. CPUClr:
  91.     Installs a patch routine for graphics.library/BltClear(), which
  92.     uses the CPU instead of the BLITTER to clear Chipmem.
  93.     It shows how easy and save it can be to install and remove a patch,
  94.     without wasting memory or CPU time.
  95.     With the program CPUClrTEST you can check how much faster memory
  96.     clearing becomes.
  97.  
  98. 2. ShowNeededFiles:    (Simple SnoopDos)
  99.     Installs a couple of patch routines to monitor dos.library/Open(),
  100.     Lock() and LoadSeg() functions. It shows how the priority system
  101.     of patch.library works.
  102.     Break this program with CTRL-C.
  103.  
  104.  
  105.  
  106. FUTURE PLANS:
  107.  
  108. - Tags
  109. - Allow patching of devices and resources
  110. - Internal handling of PATERR_PatchInstalled
  111. - ...
  112.  
  113.  
  114.  
  115. LICENSE:
  116.  
  117. This material is © Copyright 1993 by Stefan Fuchs. All rights reserved.
  118.  
  119. It may be distributed freely as long as the following restrictions are met:
  120.  
  121. - The distributor may charge a fee to recover distribution costs.
  122.   The fee for diskette distribution should not be more than
  123.   the cost to obtain the same diskette from Fred Fish.
  124.  
  125. - The distributor agrees to cease distributing the programs and
  126.   data involved if requested to do so by the author.
  127.  
  128. - You may copy and distribute verbatim copies of the program's
  129.   executable code and documentation as you receive it, in any
  130.   medium, provided that you conspicuously and appropriately
  131.   publish only the original, unmodified program, with all
  132.   copyright notices and disclaimers of warranty intact and
  133.   including all the accompanying documentation, example files and
  134.   anything else that came with the original.
  135.  
  136. - If you are interested in including any of this material in a commercial
  137.   product, you should contact the author for his permission.
  138.  
  139. - The author will not be liable for any damage arising from the
  140.   failure of the programs or the library to perform as described,
  141.   or any destruction of other programs using the library residing
  142.   on a system. While I know of no damaging errors, the user of this
  143.   package uses it at his or her own risk.
  144.  
  145.  
  146.  
  147. CONTACT:
  148.  
  149.     To contact the author for bugreports, hints, ideas, donations, ....
  150.     write to:
  151.  
  152.  
  153.     Stefan Fuchs
  154.     Oskar-von-Miller-Str. 49
  155.  
  156.     8500 Nürnberg 30    (from 1st July 1993 on: 90478 Nürnberg)
  157.  
  158.     GERMANY
  159.  
  160.  
  161.