home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 3 / Meeting_Pearls_III.iso / Pearls / debug / Background / PoolWatch / PoolWatch.doc < prev    next >
Text File  |  1995-08-18  |  9KB  |  243 lines
  1. Short: Debug tool for pool-allocations, a la Mungwall (OS3.x)
  2. Type: dev/debug
  3. Author: Magne Oestlyngen (magneo@stud.cs.uit.no)
  4. Uploader: Magne Oestlyngen (magneoe@stud.cs.uit.no)
  5.  
  6. ------------------==================================------------------
  7. 950707
  8.                         PoolWatch release 1.03
  9.  
  10.             Requires AmigaDOS 3.0 (V39) or higher to run.
  11.  
  12.              Copyright © 1994-1995 Ultima Thule Software
  13.                          All Rights Reserved.
  14.  
  15.                        Author: Magne Østlyngen
  16.  
  17. ------------------==================================------------------
  18.  
  19. Disclaimer
  20. ~~~~~~~~~~
  21. This  software  entitled  "PoolWatch"  is not public domain but freely
  22. distributable (FreeWare).  This means that you can copy it and give it
  23. to all your friends, upload it to a BBS or include it in a PD-library.
  24. The  only  restrictions  are:   All the files included in this archive
  25. must  be  in  their  original  form  without  additions,  deletions or
  26. modifications  of  any  kind.   PoolWatch  may  not be distributed for
  27. profit,  and  only  a  nominal  charge  may  be  associated  with  its
  28. distribution.   Permission  is hereby given to distribute PoolWatch on
  29. the  Fish  disks  (CD  or  floppy)  and the AmiNet CD.  If you want to
  30. distribute  "PoolWatch"  with  any  commercial  product, you will need
  31. written  permission  from the author.  "PoolWatch" is provided "AS IS"
  32. without  warranty  of  any kind, and the author is not responsible for
  33. any damage this software may do.  (Just in case :-)
  34.  
  35.  
  36. What is PoolWatch ?
  37. ~~~~~~~~~~~~~~~~~~~
  38. PoolWatch  is a debug tool for OS 3.0 and higher designed to watch and
  39. correct  illegal  allocation  and  freeing  of  memory  that  use  the
  40. pool-functions provided in OS 3.0 and upwards.  PoolWatch is necessary
  41. since  Mungwall  do  not  catch any illegal memory handling concerning
  42. pool-allocations.
  43.  
  44. PoolWatch  is especially useful in combination with Enforcer, Mungwall
  45. (which  will  watch  normal  allocations  that  use AllocMem/FreeMem),
  46. SegTracker and FindHit (included in the Enforcer archive).
  47.  
  48. If  SegTracker  is  running  in  the system when PoolWatch is started,
  49. PoolWatch   will  use  the  public  SegTracker  seglist  tracking  for
  50. identifying  the  hunk  and  offset  into the executable doing illegal
  51. allocations.
  52.  
  53.  
  54. What does PoolWatch do ?
  55. ~~~~~~~~~~~~~~~~~~~~~~~~
  56. PoolWatch  will  patch  CreatePool(), DeletePool(), AllocPooled(), and
  57. FreePooled()  in exec.library.  PoolWatch will use these functions but
  58. will add extra security on top of all pool-allocations.  In most cases
  59. of  illegal allocation/freeing, PoolWatch will report the error to the
  60. user  and  correct  the  problem  (if  possible).   Please  note  that
  61. PoolWatch  does  not offer any memory protection if a task writes to a
  62. random  addresse  in  memory,  but  will  take  care  of most problems
  63. associated with pool allocations.
  64.  
  65.  
  66. In detail, PoolWatch will do the following things:
  67. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  68.  
  69. CreatePool()
  70. ¯¯¯¯¯¯¯¯¯¯¯¯
  71. -  PoolWatch will check and warn you if the tresh-size if greater than
  72. the puddle-size.
  73.  
  74. -  PoolWatch will add the pool to its private list of pools created by
  75. PoolWatch.
  76.  
  77. AllocPooled()
  78. ¯¯¯¯¯¯¯¯¯¯¯¯¯
  79. -  PoolWatch  will  verify  that  the pool pointer is within the valid
  80. ram-area,  and  warn you if it's not (this will also take care of NULL
  81. pool pointers).
  82.  
  83. -  PoolWatch will check if the pool was created by PoolWatch.  If not,
  84. the  pool  pointer  will  be  passed directly to AllocPooled() in exec
  85. without modifications.
  86.  
  87. -  PoolWatch  will  add  a  wall  of  32  bytes  on  each  side of the
  88. allocation,   and   later   check  these  walls  in  DeletePool()  and
  89. FreePooled().
  90.  
  91. -  Except when MEMF_CLEAR is set, memory is filled with $DEADFOOD.  If
  92. this number shows up in an Enforcer or PoolWatch report, the caller is
  93. allocating memory and doesn't initialize it before using it.
  94.  
  95. - PoolWatch will check and warn you if 0 bytes of memory is requested.
  96.  
  97. FreePooled()
  98. ¯¯¯¯¯¯¯¯¯¯¯¯
  99. -  PoolWatch  will verify that the pool and memory pointers are within
  100. the  valid  ram-area, and warn you if they're not (this will also take
  101. care of NULL pool and memory pointers).
  102.  
  103. -  PoolWatch will check if the pool was created by PoolWatch.  If not,
  104. the  pool  pointer  will  be  passed  directly to FreePooled() in exec
  105. without modifications.
  106.  
  107. - PoolWatch will check if the memory if freed with the correct length,
  108. and  warn  you  if not.  PoolWatch will ofcourse free the memory using
  109. the correct length.
  110.  
  111. -  The allocation will be checked to make sure the walls have not been
  112. overwritten.
  113.  
  114. -  Memory  is  filled  with  $DEADBEEF before it is freed, encouraging
  115. programs reusing freed memory to crash.
  116.  
  117. DeletePool()
  118. ¯¯¯¯¯¯¯¯¯¯¯¯
  119. -  PoolWatch  will  verify  that  the pool pointer is within the valid
  120. ram-area,  and  warn you if it's not (this will also take care of NULL
  121. pool pointers).
  122.  
  123. -  PoolWatch will check if the pool was created by PoolWatch.  If not,
  124. the  pool  pointer  will  be  passed  directly to DeletePool() in exec
  125. without modifications.
  126.  
  127. -   If  the  pool  was  allocated  by  PoolWatch,  all  the  remaining
  128. allocations   will  be  checked  to  make  sure  no  walls  have  been
  129. overwritten.
  130.  
  131. -  Memory  is  filled  with  $DEADBEEF before it is freed, encouraging
  132. programs reusing freed memory to crash.
  133.  
  134.  
  135. Usage
  136. ~~~~~
  137. If  you  type  only  "PoolWatch"  on  the command line, PoolWatch will
  138. default  to serial output for showing messages.  PoolWatch will output
  139. the  debug  info  to the serial port with the function kprintf().  You
  140. can  use  a  local  serial debug capture tool such as Sushi to capture
  141. this output and display it in a standard console window.
  142.  
  143. PoolWatch can *not* be run from Workbench.
  144.  
  145.  
  146. -Q=QUIT
  147. The  QUIT option (-Q for short) will signal PoolWatch to quit.  If all
  148. memory  allocated  by  PoolWatch has been freed, PoolWatch will remove
  149. its patches and quit.
  150.  
  151. -NS=NOSTACK
  152. This  option  will prevent PoolWatch from printing the contents of the
  153. stack when a program cause a PoolWatch hit.
  154.  
  155. -NR=NOREGS
  156. This  option  will prevent PoolWatch from printing the contents of the
  157. registers when a program cause a PoolWatch hit.
  158.  
  159. -S=STDIO
  160. When  this  option  is on, PoolWatch will output all text to the shell
  161. PoolWatch  was  started  from.   When this option is not on, PoolWatch
  162. will use raw io, ie.  output all text directly to the serial port.
  163.  
  164. -DI=DOILLEGAL
  165. When an error has occured, PoolWatch will run an ILLEGAL instruction.
  166. This is only useful if you are debugging your own program, and is
  167. tracing through it with CPR, for instance.  You should normally not
  168. use this option.
  169.  
  170. -U=UPDATE
  171. If PoolWatch is already in memory, this switch will tell it to update
  172. its arguments.
  173.  
  174. History
  175. ~~~~~~~
  176.  
  177. v1.0 (5-Apr-95):
  178. - Initial release 1.0 of PoolWatch.
  179.  
  180. v1.01 (6-Apr-95):
  181. - Oh,  great.   Just  after  release,  I found out that compiling with
  182.   optimize  wasn't  too  smart, since it removed some important bytes.
  183.   Worked around the problem.
  184.  
  185. v1.02 (27-May-95):
  186. - Fixed an FreeMem() bug on program termination and an error in
  187.   printing of CLI commandname.
  188. - Added arguments NOSTACK, NOREGS and STDIO.
  189.  
  190. v1.03 (7-Jul-95):
  191. - Added argument DOILLEGAL (suggested by Eivind Eklund).
  192. - Memory is now munged, even if MungWall is running, which ofcourse is
  193.   the right thing to do.  (Bug reported by Eivind Eklund).
  194. - Fixed  an  odd  address  error in the wall-checking (Bug reported by
  195.   Martin Gierich)
  196. - Added argument UPDATE.
  197.  
  198. **********************************************************************
  199. ***************************** REMEMBER *******************************
  200. **********************************************************************
  201.  
  202. *NOTHING* should cause PoolWatch to react.  If all pool allocations in
  203. an  application are handled correctly, there's no reason for PoolWatch
  204. to  give warnings.  Software that use illegal allocations or overwrite
  205. existing  memory  will not function properly in AmigaOS and will crash
  206. the  system  or  other  programs.  If you use PoolWatch and discover a
  207. problem  with  a  program, please notify the author of that program so
  208. the  problem  can  be  fixed.  *All* application writers that use pool
  209. allocations  should test their applications extensivly with PoolWatch,
  210. Mungwall, Enforcer and SegTracker.
  211.  
  212. **********************************************************************
  213.  
  214.  
  215. FeedBack
  216. ~~~~~~~~
  217. Please  send  donations  (Yeah,  it's  FreeWare, but you _can_ send me
  218. money,  gifts,  chocolate, email, snailmail, etc...), bug reports or a
  219. list  of  features  you would like to have included in future releases
  220. (if the feedback is big enough, there might even _be_ future releases)
  221. to:
  222.  
  223. Magne Østlyngen
  224. Strandveien 59B
  225. N-9007 Tromsø
  226. Norway
  227.  
  228. Email: magneoe@stud.cs.uit.no (Magne Oestlyngen)
  229. Fido: 2:212/8.15 (Magne Oestlyngen)
  230.  
  231. You can also get in touch with me at the following BBSes in Norway:
  232. Ultima Thule and Abbs Support.
  233.  
  234.  
  235. Thanks to
  236. ~~~~~~~~~
  237.  Petter Nilsen      for writing the initial documentation, useful suggestions and beta-testing.
  238.  Jan Van den Baard  for betatesting
  239.  Kamil Iskra        for suggestions
  240.  Eivind Eklund      for suggestions/bug-report
  241.  Martin Gierich     for bug-report
  242.  Michael Sinz       for Enforcer
  243.