***************************************************************************** * * * Conditions of use HeartBeat 1.0 * * ----------------- ------------- * * * * This program has been provided for the enjoyment of the masses. * * It is Public Domain. * * Since the author doesn't ask for anything in return, the user * * will accept the following conditions: * * * * 1) In no case whatsoever shall the author be liable for any * * damages, losses etc... due to the use of this program. * * 2) Distribution of the program is only allowed subject to the * * following restrictions: * * * * 2.a) No file part of this distribution will be omitted or * * modified in any way. * * 2.b) None of the files which are part of this distribution * * should be stored on environmentally unfriendly media. * * (e.g. paper! (listings, faxes)) * * * * Laurence Vanhelsuwé * * 22-APR-92 * * * ***************************************************************************** Program Title : HeartBeat (HB) (Version 1.0) ------------------------- Author : Laurence Vanhelsuwé ---------------------------- 0. Short description: ------------------ HeartBeat (short: HB) is a system call monitor which allows all system calls accessible through libraries, devices or resources to be snooped on. Generic argument snooping is also provided. 1. Requirements/Installation: -------------------------- This program makes heavy use of the new 2.0 system calls. Additionally HeartBeat assumes a logical directory (assign) called FD: which contains ".fd" files (as many as you can lay your hands on). These files are normally distributed on Workbench disks and describe system library, device and resource calls. For example, my system contains the following files in FD: ( DIR FD: ) amigaguide_lib.fd asl_lib.fd battclock_lib.fd battmem_lib.fd bullet_lib.fd cardres_lib.fd cia_lib.fd colorwheel_lib.fd commodities_lib.fd console_lib.fd datatypes_lib.fd diskfont_lib.fd disk_lib.fd dos_lib.fd dtclass_lib.fd exec_lib.fd expansion_lib.fd gadtools_lib.fd graphics_lib.fd icon_lib.fd iffparse_lib.fd input_lib.fd intuition_lib.fd keymap_lib.fd layers_lib.fd locale_lib.fd mathffp_lib.fd mathieeedoubbas_lib.fd mathieeedoubtrans_lib.fd mathieeesingbas_lib.fd mathieeesingtrans_lib.fd mathtrans_lib.fd misc_lib.fd potgo_lib.fd ramdrive_lib.fd rexxsyslib_lib.fd timer_lib.fd translator_lib.fd utility_lib.fd wb_lib.fd 2. How to use it: -------------- Just type the following at any Shell prompt: RUN HB I suggest you "run" HeartBeat because HB currently changes the current directory but does not restore it before exiting (sorry). Using a "RUN" shields you from this side-effect. Check out the menus and you'll get: PROJECT OPTIONS LIBRARIES A-I LIBRARIES J-Z Your main menus are the two library menus which list all the libraries that HeartBeat knows about (and devices and resources). Select any library you're familiar with and you'll be presented with a list of its system calls (any function names highlighted in inverse video means they don't point to ROM code (could be virus?)). Now select a system call by moving the highlight over the function and click... you are now monitoring this call. A seperate window popped up to display your monitored function. Using a similar select-and-click method in this second window you can bring up the register template window and define an "arguments match template". You are presented with 32 string gadgets: one pair for every data and address register of the 680x0. One for the register's value (or bits you want to see set or cleared) and one for a mask defining which bits you care about (0 means you don't care at all what value this register is). Note that the string gadgets accept decimal and hexadecimal numbers (prefixed with $). The default values which initially appear are explained as follows: - register A7 has a mask of $FFFFFFFF and a value of $00000000. (this ensures a "no match" WHATEVER the settings of the other registers are since the SP can never point to 0!). - register D0 has a mask of $FFFFFFFF and a garbage value of $A1B2C3D4 (this gives a very high probability of a "no match" as detected by the wedge routine since it starts with D0,D1,D2...) Basically this is done to prevent matches occuring before you've defined the template yourself (the matching process is active all the time). You can select between two match action modes: - just count matches (a separate counter is used for matches) - freeze calling Task (a "!" will turn into a "*" in output window) The freezing option only works if you explicitly tell HeartBeat which Task in the system you want to monitor. This is done by selecting the "Watch Task..." option in the OPTIONS menu. The project menu allows you to load and save a HeartBeat "session". A session is just the collection of system functions that you are currently monitoring. When loading a previously saved session, the window with monitored functions might contain less functions as originally saved. This is because the library (device or resource) to which these functions belong might not be accessible this time round (not opened). (e.g. the rexxsyslib might have been accessible by HeartBeat when saving a session but not any more when loading). 3. HeartBeat: it's uses. --------------------- HeartBeat is a system call monitor. HB complements programs like MonIDCMP, SnoopDOS or SPY, although HB does not have any bias towards a particular library like SnoopDOS or SPY. Because of this general-purpose nature, HB can't give you very detailed information of what the parameters passed to a routine are. In fact, it doesn't give you any. (ha!) It just counts each call made, whether by a specific Task in the system or globally (by any Task). In this simple mode HeartBeat can be viewed as a higher level extension to my other system utility : ISAN (Instruction Stream ANalyzer) which has also been put in the Public Domain. To make the program a bit more useful, you can also define a register arguments template on a per-function basis: you could for example count the number of times AllocMem() is called with the MEMF_CHIP flag set. You would do this by defining a value and mask for data register D1 (where the memory type argument has to be passed) and specifying "don't care" masks for all other registers of the 680x0. To make the program somewhat more productive you can ask HeartBeat to freeze the calling Task when an argument template matches. You can obviously un-freeze such a Task too (by clicking on the function when its frozen marker "*" has appeared). Example uses: - work out whether a program uses OS 2.0 calls or not. - snooping on programs to see if they use system calls when.. a) they should (to allocate memory for example) or when b) they shouldn't (for example THE bottleneck of a brilliant ecology simulator program called "Jitter" could very well be its use of RectFill(); to draw just 4 pixels RectFill() uses nothing less than the Blitter to do its stuff and this could be re-coded to be at least ten times faster in optimized assembler!!) - learn about the Amiga and surprise yourself at how often or how rarely functions get called... and wonder whether the frequently called ones are implemented efficiently or not... - catching faulty programs or viri by intercepting calls with particular pararmeters. (a virus might well make AllocAbs() or SetFunction() calls). 4. Internals: ---------- HeartBeat gets all its "knowledge" of Amiga system internals from the .fd files in the FD: directory. From these files it extracts: a) library names (or device or resource names) b) function LVOs and names c) function accessability c) Means that HeartBeat does not allow you to access system private functions (##private). 5. HeartBeat Limitations/Warnings: ------------------------------- !CRASH! Be careful when monitoring Exec and other low-level and/or critical libraries. In particular all Exec routines which rely on privilege exception trapping tricks will crash the system when attempting to monitor them. Similarly the SumLibrary() function crashes because of SetFunction() interactions. !CRASH! Be very careful too with HeartBeat's freeze option. Freezing any system Task which disables any part of the system that you in turn need to unfreeze the Task (e.g. mouse input routines, sprite moving routines, Text printing routines...) will effectively result in freezing the entire machine ! 6. History: -------- I like low-level system utilities like this. I think they should be provided as standard when you buy a machine like the Amiga. AmigaDOS' "STATUS FULL" and "BREAK" commands are just pathetic when you compare them with what a UNIX hacker has at his disposal. Since the Amiga has quite a lot in common (complexity wise) with UNIX machines the Amiga user should also have an arsenal of tools at his side to make better use of his machine. 7. Future: ------- Some ideas for future versions of HeartBeat are already: - allow function RESULTS to be trapped too (handy for errors) - allow argument register mappings to be defined (SetAPen(1)->SetAPen(2)) - remove all bugs in current version... To any programmers thinking of enhancing HB: please don't "adopt" HeartBeat yet. I know it's far from robust and complete at this moment, but it's already useful enough to be released. I'd like to get some feedback and work one the next release myself. 8. Credits: -------- Since I'm still stuck with old 1.2 Rom Kernal Manuals and the like, I could not have written this program without the source codes of various 2.0 programs in the Fish library. I am especially grateful to Steve Tibbett for adding the source to his PSX release (even though it's a bit sparse on comments !!). Any comments, ideas or bug reports? My name and address are: Laurence Vanhelsuwé Christinastraat 105 B-8400 Oostende BELGIUM Enjoy !