
			Debugging Tools 1990

Here are some quick descriptions and credits for the tools on this disk.
Including some great tools which were not available in time to be described
in the devcon notes (such as eatmem, mks_lens, and lvo).


Most CLI tools provide usage if called with "?".  Some of the more complex
tools (Wack and Wedge) are fully documented in the manual of the older
Software Toolkit (a CATS support item).  Many of the tools on this disk are
updated and enhanced versions in preparation for Software Toolkit II.


If you are planning on releasing software to the public, be sure to test
with the various watchdog tools first!	Memmung and io_torture work on any
system.  If you have an MMU and are running V1.3, use _Enforcer_.  If you
are running 2.0, chose between _Enforcer_, or CPU trap.  If running an
A3000, use complainer.




autodoc

   Extracts autodocs from your source code, with docs on how to code your
   comments to make this possible.  See autodoc.doc for usage.


bumprev

   Bumps the revision in an xxx_rev.h or .i file.
   Usage: bumprev version revfilename	(example bumprev 36 my_rev)


charset

   Printf's a table of the Amiga character set (ECMA-94 Latin 1 International
   8-bit character set) with hex and binary upper/lower nibble values.


complainer and complainer.par (by Bryce Nesbitt)

   A3000 MMU watchdog.	Use in conjunction with MemMung to catch use of
   freed or uninitialized memory, and writes to ROM or non-existant memory.
   Requires serial terminal.
   Usage: complainer[.par] on|off


cputrap and cputrap.par (by Valentin Pepelea)

   A2500 MMU watchdog traps for use with the 2.0 CPU command.
   Catches illegal memory accesses, low memory reads/writes, writes
   to ROM, etc.  Use in conjunction with MemMung to also catch use of
   freed memory of pointers. Requires 2.0, MMU, CPU command, and serial
   terminal (cputrap) or parallel printer (cputrap.par).
   Usage: run cputrap[.par]
	  CPU trap


config (by Carolyn Scheppner)

   Displays your system configuration ( versions, chips, boards, etc.) With
   "debug" option it lists all of the autoconfig info for each board.

   Usage: config [debug]


configdev (by Bryce Nesbitt)

   Lists every last detail about every AutoConfig (tm) device in the
   system. Knows about Zorro III cards.

   Usage: configdev [brief]


crash3, crash4, crash5, crash8, crasha (by C. Scheppner)

   Little programs to crash your machine (just what you need :-)
   They are useful when testing debugging tools like SRT and TNT.
   They are non-destructive - they just crash the shell process you call
   them from.  They store recognizable values in most registers before
   they crash (like d0=0 thru d7=7, a0=10 thru a6=16 EXCEPT a2=program
   counter and a3=stack pointer) so you can tell if your debugging tool
   is picking up the right info.


devlist (by Carolyn Scheppner)

   Lists all currently loaded/available devices in the system.


devmon (by Carolyn Scheppner)

   Exec device monitor.  Wedges into Open/Close/Expunge/BeginIO vectors
   of any exec device unit and reports on all calls.  With "full" option,
   the exec functions DoIO, SendIO, WaitIO, AbortIO, and ReplyMsg are
   also wedged.  Default output option buffers 40K of debug output
   then outputs to your choice of screen or file when you exit.
   (Local buffer can be restarted at any time).  With "remote" option,
   output is kprintf'd.  Warning - I don't suggest using remote option
   for heavy-use or time-critical devices like timer.device (too slow).


disked

   Sector editor documented in Bantam AmigaDOS manual.	See the toolkit
   documentation for an example.


doslist (by Andy Finkel)

   Lists all of your dos device and volume environment information.
   This version has a larger buffer for folks with lots of devices.


drip

   A classic memory loss tool.
   Usage: drip [threshold]
   Call it again to check for memory loss.


eatcycles (by John Szucs)

   Requires 2.0.  Lets you bog down the processor to simulate heavy
   multitasking loads.


eatmem (by John Szucs)

   Requires 2.0.  Great gadtools-interface memory control panel.
   Lets you dynamically adjust the amount of free memory available for
   testing under low memory situations, or to simulate a machine with
   less memory.


enforcer and enforcer.par (by Bryce Nesbitt)

   MMU watchdog.  Works under 2.0 and 1.3.  Catches illegal memory
   accesses, low memory reads/writes, writes to ROM, areas of no memory,
   etc.

   Use with MemMung to also catch use of freed memory or pointer. Requires
   MMU and serial terminal.

   Usage: enforcer on|off|fprotect


flush (by Carolyn Scheppner)

   Does three big memory allocations to force currently unopened
   ram-resident fonts, libraries, and devices out of the system. (3 allocs
   so that libs/devs that have other libs/devs open... can be flushed,
   followed by the libs/devs THEY had open, etc...) Used when testing for
   memory loss.  (flush, avail, run your program, exit program, flush,
   avail).


frags

   Shows summary of memory fragmentation.


intlist (from the original by Carl Sassenrath)

   System interrupt lister.


io_torture (by Bryce Nesbitt)

   Device IO watchdog - watches for reuse of IORequests before they have
   completed.  Requires serial terminal.


lawbreaker (by Bryce Nesbitt)

   A little program to test your MMU debugging tool and remote setup.  Does
   an read of location $14, and a write to location $C0EDBAE.


liblist (by Carolyn Scheppner)

   Lists all currently loaded/available libraries in the system.


lvo (by Carolyn Scheppner)

   If you have a directory or disk assigned the name FD:, containing
   the FD files, lvo can give you the LVO offset of a function (hex
   and decimal) and the usage line for the function (handy for quick
   checks on function arguments and registers).  Wedgeline option
   generates command lines for Wedge.
   Usage: lvo library [functionname] [wedgeline]
   Example: lvo exec OpenLibrary


memlist (by Carolyn Scheppner)

   Displays all of the system's memory areas and free memory lists.  Can
   be redirected to a disk file.


memmon (by Carolyn Scheppner)

   Simple memory monitor for checking relative memory usage while
   running your program.  Redirect to a disk file for a log.


memmung (by Bryce Nesbitt)

   Freed memory invalidation tool.  Sets address $0, and all Free'd memory
   to a nasty value, designed to cause you big problems if you are using
   null pointers or accessing freed memory.  If used in conjunction with
   an MMU Watchdog tool (enforcer, cputrap, or complainer as appropriate)
   you get informative messages on such accesses (rather than crashes).
   Use by itself if you don't have an MMU but be prepared to crash.

   Usage: run memmung


memwall (by Randell Jesup)

   Memwall puts a magic cookie around all memory allocations (or all by
   a particular task) and complains serially when the memory is freed
   if the cookie has been trashed.  And it now has new snoop-compatible
   output for the snoop option for use with snoopstrip.  Warning -
   anything that frees larger allocations in pieces will cause memwall
   to complain and not free the memory (layers does this).
   Requires a serial terminal.
   Usage: memwall [task Name] [fill N] [presize N] [postsize N] [snoop]


mks_lens (by Mike Sinz)

   A magnifying-glass for for screen text and graphics.  Lets you
   examine every pixel easily.	Useful for debugging graphic
   placement and trashing.


modlist (by Carolyn Scheppner)

   Lists all of the resident modules in the system.


owner (by Mike Sinz)

   Searches exec lists trying to find owner of a piece of memory.
   Usage: owner 0xhhhhhh [0xhhhhhh, etc.]


peek, poke (by Carolyn Scheppner)

   Let you peek or poke memory, and compare memory contents against a
   masked or unmasked value.


printertest (by Bob Burns)

   Printer driver test for printer driver writers.


readpixel (by Carolyn Scheppner)

   Tool that lets you click on pixels to find out their pen number and
   x/y position.  Useful for measuring things onscreen or checking their
   positions.  Coordinates are relative to top left corner of screen.


romwack

   Freezes your system and enters the rom-based system serial debugger,
   allowing you to examine your machine's memory remotely.  Same effect
   as calling Debug() from within a program.
   See RomWack docs in the Addison-Wesley Rom Kernel Manual.


settaskname (by Carolyn Scheppner)

   Lets you change the name of a CLI to any same or shorter length name.
   Useful in conjuction with the MemWall [task Name] option.

   Usage: settaskname newname


showgfxbase (by Carolyn Scheppner)

   Shows some popular GfxBase variables.


showlocks ( Copyright Chuck McManis )

   Shows the outstanding locks on a volume.
   Usage: showlocks volumename


snoop (by Carl Sassenrath, modified by R. Jesup and C. Scheppner)

   Snoop reports serially on all memory allocations and deallocations.
   You should capture snoop's output in a terminal program's ascii buffer
   abd then run snoopstrip on it to leave just unmatched allocs/frees.
   This version outputs full 32-bit addresses.	Modified to snoop both
   AllocMem/FreeMem, plus AllocVec/FreeVec if run under 2.0.
   NOTE! In order for snoopstrip to be able to match up AllocVec's and
   FreeVec's, I have to lie about the sizes and output the ACTUAL size
   rather than the requested size for these functions (requested size is
   not available on a FreeVec call).  Requires serial terminal.

   Usage: snoop


snoopstrip (by Neil Katin, modified by C. Scheppner)

   Snoopstrip is used to strip all matching allocations and frees from
   a captured snoop output file (or from the output of MemWall's snoop
   option).  All unmatched allocs and frees will cause snoopstrip to
   output a "NoAlloc:" or an "UnFreed:" line, specifying the allocation
   and the owning task.  This new version requires the full 32-bit output
   such as produced by the new Snoop and MemWall programs above.
   Snoopstrip no longer throws away lines it does not understand (unless
   used with the "discard" option).  Instead, it will just prepend the
   lines with a "?".  If it thinks it is being fed old-style 24-bit snoop
   output, it will also output a warning.

   Usage:  snoopstrip <snoopfile >outfile [discard]


sparemem (by Carolyn Scheppner)

   Lets you reduce free memory TO a certain amount or BY a certain amount.
   (I wrote it before I saw how nice eatmem is).  Still could be useful
   when (for instance) trying to test a bootable disk under lowered
   memory conditions.
   Usage: sparemem c=[-]bytes f=[-]bytes


srt (by Carolyn Scheppner)
srt.text

   Wedges into AutoRequest to trap Software Error requesters and replace
   with a debug requester containing PC, registers, task name, etc.
   Unfortunately, almost all of 2.0 uses EasyRequest() now, so SRT
   is useless for intercepting 2.0 requesters or software errors.
   However, one handy feature under 1.3 is that it can be installed
   after you crash (then click Retry in requester).
   Usage: srt textfile [default is s:srt.text]
   See new "tnt" below for trapping 1.3/2.0 software errors.


tasklist (by Carolyn Scheppner)

   Lists all tasks in the system and their addresses.


tnt (by Carolyn Scheppner)

  (== trap no tasks  or something like that with the same letters...)

   New!  Installs (or removes) a special task trap handler for all
   current and future system tasks and processes.  Instead of
   Software Errors, you'll get an SRT-style debugging requester
   showing the name, registers, program counter, and stack pointer
   of the crashed task, process, or command.  Lets you suspend the
   task if you wish.  Works with (or without) Enforcer and CPU.
   However, turn it off before using a trap-based debugger.
   Usage: tnt [off]


tstat (by Carolyn Scheppner)

   I use this a lot.  It displays a whole bunch of information about
   any task, including what its registers, stack pointer, and PC
   were last time it got switched out.	You can give it a CLI number
   or an exec task name.  You can also give it a repeat time in ticks
   (50th's of a second) and it will monitor the task continuously.
   It shows all of the signal states, and Forbid/Disable nest counts,
   stack usage, and highest stack usage.  Very handy for spotting
   unfreed signals, extra/missing Forbids/Disables, stack problems,
   memory drips, etc.  And you can even use it as a poor-man's
   logic state analyzer - you can crudely follow the execution
   of any task or process by watching it's PC.


wack, wack1.0 (original Wack1.0 by Carl Sassenrath, revision by Eric Cotton)

   Simple usage: wack [programname]
   Symbolic debuggers.	See Software Toolkit for docs.
   Or try ?<RET> in Wack.


watchmem (by Andy Finkel)

   Processor based tool for spotting trashing of low memory on systems
   without an MMU.
   Usage: RUN watchemem [ file | window ] opt n [interval] (n==nocorrect)


wedge (by Carolyn Scheppner)

   Lets you wedge into just about any system function.	Call multiple
   times to install several wedges.  Wedge LIST shows currently installed
   wedges.  Wedge KILLALL kills all installed wedges.  Wedge help gives
   help.  Can snoop on just particular tasks/commands, or on all but
   particular tasks/commands.  Use "lvo" with wedgeline option to create
   command lines for wedge.  (redirect lvo to a file, then execute the file).
   Accompanying s/xxx.w files are sample script files (generated by lvo) for
   installing some wedges.
   Type wedge HELP for help.  See Software Toolkit for full docs.


winlist (by Carolyn Scheppner)

   Lists all screens and windows in the system.

