home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / prog / utils / hart.lha / README < prev   
Text File  |  1992-05-25  |  10KB  |  251 lines
  1. *****************************************************************************
  2. *                                        *
  3. *    Conditions of use                HeartBeat 1.0        *
  4. *    -----------------                -------------        *
  5. *                                        *
  6. *    This program has been provided for the enjoyment of the masses.        *
  7. *    It is Public Domain.                            *
  8. *    Since the author doesn't ask for anything in return, the user        *
  9. *    will accept the following conditions:                    *
  10. *                                        *
  11. *    1) In no case whatsoever shall the author be liable for any        *
  12. *       damages, losses etc... due to the use of this program.        *
  13. *    2) Distribution of the program is only allowed subject to the        *
  14. *       following restrictions:                        *
  15. *                                        *
  16. *    2.a) No file part of this distribution will be omitted or        *
  17. *         modified in any way.                        *
  18. *    2.b) None of the files which are part of this distribution        *
  19. *         should be stored on environmentally unfriendly media.        *
  20. *         (e.g. paper! (listings, faxes))                    *
  21. *                                        *
  22. *                    Laurence Vanhelsuwé            *
  23. *                    22-APR-92                *
  24. *                                        *
  25. *****************************************************************************
  26.  
  27.         ** PROGRAM REQUIRES DOS 2.0 TO RUN **
  28.         ** PROGRAM REQUIRES DOS 2.0 TO RUN **
  29.  
  30.  
  31. Program Title : HeartBeat (HB)    (Version 1.0)
  32. -------------------------
  33. Author : Laurence Vanhelsuwé
  34. ----------------------------
  35.  
  36. 0. Short description:
  37.    ------------------
  38.  
  39.     HeartBeat is a system call monitor which allows all system calls
  40.     accessible through libraries, devices or resources to be snooped
  41.     on. Generic argument snooping is also provided.
  42.  
  43.  
  44. 1. Requirements/Installation:
  45.    --------------------------
  46.  
  47.     This program makes heavy use of the new 2.0 system calls.
  48.     Additionally HeartBeat assumes a logical directory (assign) called
  49.  
  50.         FD:
  51.  
  52.     which contains ".fd" files (as many as you can lay your hands on).
  53.     These files are normally distributed on Workbench disks and describe
  54.     system library, device and resource calls.
  55.  
  56. 2. How to use it:
  57.    --------------
  58.  
  59.     Just type the following at any Shell prompt:
  60.  
  61.         RUN HeartBeat
  62.  
  63.     I suggest you "run" HeartBeat because HB currently changes the
  64.     current directory but does not restore it before exiting (sorry).
  65.     Using a "RUN" shields you from this side-effect.
  66.  
  67.     Check out the menus and you'll get:
  68.  
  69.         PROJECT   OPTIONS   LIBRARIES A-I   LIBRARIES J-Z
  70.  
  71.     Your main menus are the two library menus which list all the
  72.     libraries that HeartBeat knows about (and devices and resources).
  73.  
  74.     Select any library you're familiar with and you'll be presented
  75.     with a list of its system calls.
  76.     Now select a system call by moving the highlight over the function
  77.     and click... you are now monitoring this call.
  78.     A seperate window popped up to display your monitored function.
  79.  
  80.     Using a similar select-and-click method in this second window you can
  81.     bring up the register template window and define an "arguments match
  82.     template".
  83.     You are presented with 32 string gadgets: one pair for every data and
  84.     address register of the 680x0. One for the register's value (or bits
  85.     you want to see set or cleared) and one for a mask defining which bits
  86.     you care about (0 means you don't care at all what value this register
  87.     is).
  88.     Note that the string gadgets accept decimal and hexadecimal numbers
  89.     (prefixed with $).
  90.     The default values which initially appear are explained as follows:
  91.      - register A7 has a mask of $FFFFFFFF and a value of $00000000.
  92.        (this ensures a "no match" WHATEVER the settings of the other
  93.        registers are since the SP can never point to 0!).
  94.      - register D0 has a mask of $FFFFFFFF and a garbage value of $A1B2C3D4
  95.        (this gives a very high probability of a "no match" as detected by
  96.        the wedge routine since it starts with D0,D1,D2...)
  97.  
  98.     Basically this is done to prevent matches occuring before you've
  99.     defined the template yourself (the matching process is active all the
  100.     time).
  101.  
  102.     You can select between two match action modes:
  103.      - just count matches    (a separate counter is used for matches)
  104.      - freeze calling Task    (a "!" will turn into a "*" in output window)
  105.  
  106.     The freezing option only works if you explicitly tell HeartBeat
  107.     which Task in the system you want to monitor.
  108.     This is done by selecting the "Watch Task..." option in the OPTIONS
  109.     menu.
  110.  
  111.     The project menu allows you to load and save a HeartBeat "session".
  112.     A session is just the collection of system functions that you are
  113.     currently monitoring.
  114.  
  115.     When loading a previously saved session, the window with monitored
  116.     functions might contain less functions as originally saved.
  117.     This is because the library (device or resource) to which these
  118.     functions belong might not be accessible this time round (not opened).
  119.     (e.g. the rexxsyslib might have been accessible by HeartBeat when
  120.     saving a session but not any more when loading).
  121.  
  122. 3. HeartBeat: it's uses.
  123.    ---------------------
  124.  
  125.     HeartBeat is a system call monitor.
  126.  
  127.     HB complements programs like MonIDCMP, SnoopDOS or SPY, although HB
  128.     does not have any bias towards a particular library like SnoopDOS
  129.     or SPY.
  130.     Because of this general-purpose nature, HB can't give you very
  131.     detailed information of what the parameters passed to a routine
  132.     are. In fact, it doesn't give you any. (ha!)
  133.     It just counts each call made, whether by a specific Task in the
  134.     system or globally (by any Task).
  135.     In this simple mode HeartBeat can be viewed as a higher level
  136.     extension to my other system utility :
  137.         ISAN (Instruction Stream ANalyzer)
  138.     which has also been put in the Public Domain.
  139.  
  140.     To make the program a bit more useful, you can also define a
  141.     register arguments template on a per-function basis: you could for
  142.     example count the number of times AllocMem() is called with the
  143.     MEMF_CHIP flag set.
  144.     You would do this by defining a value and mask for data register
  145.     D1 (where the memory type argument has to be passed) and specifying
  146.     "don't care" masks for all other registers of the 680x0.
  147.  
  148.     To make the program somewhat more productive you can ask HeartBeat
  149.     to freeze the calling Task when an argument template matches.
  150.     You can obviously un-freeze such a Task too (by clicking on the
  151.     function when its frozen marker "*" has appeared).
  152.  
  153.     Example uses:
  154.  
  155.     - work out whether a program uses OS 2.0 calls or not.
  156.  
  157.     - snooping on programs to see if they use system calls when..
  158.        a) they should (to allocate memory for example) or when
  159.        b) they shouldn't
  160.         (for example THE bottleneck of a brilliant ecology simulator
  161.         program called "Jitter" could very well be its use of
  162.         RectFill(); to draw just 4 pixels RectFill() uses nothing
  163.         less than the Blitter to do its stuff and this could be
  164.         re-coded to be at least ten times faster in optimized
  165.         assembler!!)
  166.  
  167.     - learn about the Amiga and surprise yourself at how often or how
  168.       rarely functions get called... and wonder whether the frequently
  169.       called ones are implemented efficiently or not...
  170.  
  171.     - catching faulty programs or viri by intercepting calls with
  172.       particular pararmeters. (a virus might well make AllocAbs() or
  173.       SetFunction() calls).
  174.  
  175. 4. Internals:
  176.    ----------
  177.  
  178.     HeartBeat gets all its "knowledge" of Amiga system internals from
  179.     the .fd files in the FD: directory.
  180.     From these files it extracts:
  181.         a) library names (or device or resource names)
  182.         b) function LVOs and names
  183.         c) function accessability
  184.     c) Means that HeartBeat does not allow you to access system private
  185.     functions (##private).
  186.  
  187.  
  188. 5. HeartBeat Limitations/Warnings:
  189.    -------------------------------
  190.  
  191. !CRASH!    Be careful when monitoring Exec and other low-level and/or critical
  192.     libraries.
  193.     In particular all Exec routines which rely on privilege exception
  194.     trapping tricks will crash the system when attempting to monitor them.
  195.     Similarly the SumLibrary() function crashes because of SetFunction()
  196.     interactions.
  197.  
  198. !CRASH!    Be very careful too with HeartBeat's freeze option.
  199.     Freezing any system Task which disables any part of the system that
  200.     you in turn need to unfreeze the Task (e.g. mouse input routines,
  201.     sprite moving routines, Text printing routines...) will effectively
  202.     result in freezing the entire machine !
  203.  
  204. 6. History:
  205.    --------
  206.  
  207.     I like low-level system utilities like this.
  208.     I think they should be provided as standard when you buy a machine
  209.     like the Amiga.
  210.     AmigaDOS' "STATUS FULL" and "BREAK" commands are just pathetic
  211.     when you compare them with what a UNIX hacker has at his disposal.
  212.     Since the Amiga has quite a lot in common (complexity wise) with
  213.     UNIX machines the Amiga user should also have an arsenal of tools
  214.     at his side to make better use of his machine.
  215.  
  216. 7. Future:
  217.    -------
  218.  
  219.     Some ideas for future versions of HeartBeat are already:
  220.     - allow function RESULTS to be trapped too (handy for errors)
  221.     - allow argument register mappings to be defined (SetAPen(1)->SetAPen(2))
  222.  
  223.     - remove all bugs in current version...
  224.  
  225.     To any programmers thinking of enhancing HB: please don't "adopt"
  226.     HeartBeat yet. I know it's far from robust and complete at this moment,
  227.     but it's already useful enough to be released.
  228.     I'd like to get some feedback and work one the next release myself.
  229.  
  230. 8. Credits:
  231.    --------
  232.  
  233.     Since I'm still stuck with old 1.2 Rom Kernal Manuals and the like,
  234.     I could not have written this program without the source codes of
  235.     various 2.0 programs in the Fish library.
  236.     I am especially grateful to Steve Tibbett for adding the source
  237.     to his PSX release (even though it's a bit sparse on comments !!).
  238.  
  239.     Any comments, ideas or bug reports? 
  240.     My name and address are:
  241.     
  242.     Laurence Vanhelsuwé
  243.     720, Anlaby Road
  244.     Hull
  245.     HU4 6BP
  246.     United Kingdom
  247.  
  248.  
  249.  
  250.                             Enjoy !
  251.