Short: Debug tool for pool-allocations, a la Mungwall (OS3.x) Type: dev/debug Author: Magne Oestlyngen (magneo@stud.cs.uit.no) Uploader: Magne Oestlyngen (magneoe@stud.cs.uit.no) ------------------==================================------------------ 950707 PoolWatch release 1.03 Requires AmigaDOS 3.0 (V39) or higher to run. Copyright © 1994-1995 Ultima Thule Software All Rights Reserved. Author: Magne Østlyngen ------------------==================================------------------ Disclaimer ~~~~~~~~~~ This software entitled "PoolWatch" is not public domain but freely distributable (FreeWare). This means that you can copy it and give it to all your friends, upload it to a BBS or include it in a PD-library. The only restrictions are: All the files included in this archive must be in their original form without additions, deletions or modifications of any kind. PoolWatch may not be distributed for profit, and only a nominal charge may be associated with its distribution. Permission is hereby given to distribute PoolWatch on the Fish disks (CD or floppy) and the AmiNet CD. If you want to distribute "PoolWatch" with any commercial product, you will need written permission from the author. "PoolWatch" is provided "AS IS" without warranty of any kind, and the author is not responsible for any damage this software may do. (Just in case :-) What is PoolWatch ? ~~~~~~~~~~~~~~~~~~~ PoolWatch is a debug tool for OS 3.0 and higher designed to watch and correct illegal allocation and freeing of memory that use the pool-functions provided in OS 3.0 and upwards. PoolWatch is necessary since Mungwall do not catch any illegal memory handling concerning pool-allocations. PoolWatch is especially useful in combination with Enforcer, Mungwall (which will watch normal allocations that use AllocMem/FreeMem), SegTracker and FindHit (included in the Enforcer archive). If SegTracker is running in the system when PoolWatch is started, PoolWatch will use the public SegTracker seglist tracking for identifying the hunk and offset into the executable doing illegal allocations. What does PoolWatch do ? ~~~~~~~~~~~~~~~~~~~~~~~~ PoolWatch will patch CreatePool(), DeletePool(), AllocPooled(), and FreePooled() in exec.library. PoolWatch will use these functions but will add extra security on top of all pool-allocations. In most cases of illegal allocation/freeing, PoolWatch will report the error to the user and correct the problem (if possible). Please note that PoolWatch does not offer any memory protection if a task writes to a random addresse in memory, but will take care of most problems associated with pool allocations. In detail, PoolWatch will do the following things: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ CreatePool() ¯¯¯¯¯¯¯¯¯¯¯¯ - PoolWatch will check and warn you if the tresh-size if greater than the puddle-size. - PoolWatch will add the pool to its private list of pools created by PoolWatch. AllocPooled() ¯¯¯¯¯¯¯¯¯¯¯¯¯ - PoolWatch will verify that the pool pointer is within the valid ram-area, and warn you if it's not (this will also take care of NULL pool pointers). - PoolWatch will check if the pool was created by PoolWatch. If not, the pool pointer will be passed directly to AllocPooled() in exec without modifications. - PoolWatch will add a wall of 32 bytes on each side of the allocation, and later check these walls in DeletePool() and FreePooled(). - Except when MEMF_CLEAR is set, memory is filled with $DEADFOOD. If this number shows up in an Enforcer or PoolWatch report, the caller is allocating memory and doesn't initialize it before using it. - PoolWatch will check and warn you if 0 bytes of memory is requested. FreePooled() ¯¯¯¯¯¯¯¯¯¯¯¯ - PoolWatch will verify that the pool and memory pointers are within the valid ram-area, and warn you if they're not (this will also take care of NULL pool and memory pointers). - PoolWatch will check if the pool was created by PoolWatch. If not, the pool pointer will be passed directly to FreePooled() in exec without modifications. - PoolWatch will check if the memory if freed with the correct length, and warn you if not. PoolWatch will ofcourse free the memory using the correct length. - The allocation will be checked to make sure the walls have not been overwritten. - Memory is filled with $DEADBEEF before it is freed, encouraging programs reusing freed memory to crash. DeletePool() ¯¯¯¯¯¯¯¯¯¯¯¯ - PoolWatch will verify that the pool pointer is within the valid ram-area, and warn you if it's not (this will also take care of NULL pool pointers). - PoolWatch will check if the pool was created by PoolWatch. If not, the pool pointer will be passed directly to DeletePool() in exec without modifications. - If the pool was allocated by PoolWatch, all the remaining allocations will be checked to make sure no walls have been overwritten. - Memory is filled with $DEADBEEF before it is freed, encouraging programs reusing freed memory to crash. Usage ~~~~~ If you type only "PoolWatch" on the command line, PoolWatch will default to serial output for showing messages. PoolWatch will output the debug info to the serial port with the function kprintf(). You can use a local serial debug capture tool such as Sushi to capture this output and display it in a standard console window. PoolWatch can *not* be run from Workbench. -Q=QUIT The QUIT option (-Q for short) will signal PoolWatch to quit. If all memory allocated by PoolWatch has been freed, PoolWatch will remove its patches and quit. -NS=NOSTACK This option will prevent PoolWatch from printing the contents of the stack when a program cause a PoolWatch hit. -NR=NOREGS This option will prevent PoolWatch from printing the contents of the registers when a program cause a PoolWatch hit. -S=STDIO When this option is on, PoolWatch will output all text to the shell PoolWatch was started from. When this option is not on, PoolWatch will use raw io, ie. output all text directly to the serial port. -DI=DOILLEGAL When an error has occured, PoolWatch will run an ILLEGAL instruction. This is only useful if you are debugging your own program, and is tracing through it with CPR, for instance. You should normally not use this option. -U=UPDATE If PoolWatch is already in memory, this switch will tell it to update its arguments. History ~~~~~~~ v1.0 (5-Apr-95): - Initial release 1.0 of PoolWatch. v1.01 (6-Apr-95): - Oh, great. Just after release, I found out that compiling with optimize wasn't too smart, since it removed some important bytes. Worked around the problem. v1.02 (27-May-95): - Fixed an FreeMem() bug on program termination and an error in printing of CLI commandname. - Added arguments NOSTACK, NOREGS and STDIO. v1.03 (7-Jul-95): - Added argument DOILLEGAL (suggested by Eivind Eklund). - Memory is now munged, even if MungWall is running, which ofcourse is the right thing to do. (Bug reported by Eivind Eklund). - Fixed an odd address error in the wall-checking (Bug reported by Martin Gierich) - Added argument UPDATE. ********************************************************************** ***************************** REMEMBER ******************************* ********************************************************************** *NOTHING* should cause PoolWatch to react. If all pool allocations in an application are handled correctly, there's no reason for PoolWatch to give warnings. Software that use illegal allocations or overwrite existing memory will not function properly in AmigaOS and will crash the system or other programs. If you use PoolWatch and discover a problem with a program, please notify the author of that program so the problem can be fixed. *All* application writers that use pool allocations should test their applications extensivly with PoolWatch, Mungwall, Enforcer and SegTracker. ********************************************************************** FeedBack ~~~~~~~~ Please send donations (Yeah, it's FreeWare, but you _can_ send me money, gifts, chocolate, email, snailmail, etc...), bug reports or a list of features you would like to have included in future releases (if the feedback is big enough, there might even _be_ future releases) to: Magne Østlyngen Strandveien 59B N-9007 Tromsø Norway Email: magneoe@stud.cs.uit.no (Magne Oestlyngen) Fido: 2:212/8.15 (Magne Oestlyngen) You can also get in touch with me at the following BBSes in Norway: Ultima Thule and Abbs Support. Thanks to ~~~~~~~~~ Petter Nilsen for writing the initial documentation, useful suggestions and beta-testing. Jan Van den Baard for betatesting Kamil Iskra for suggestions Eivind Eklund for suggestions/bug-report Martin Gierich for bug-report Michael Sinz for Enforcer