home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 648a.lha / DebugUtils / debug.doc next >
Text File  |  1992-05-20  |  10KB  |  320 lines
  1.  
  2. Debug Utilities
  3.  
  4.  
  5. Enclosed are some tools I have found useful in debugging applications on the
  6. Amiga.  They comprise an integrated set which, when used with Enforcer and
  7. Mungwall, give the programmer a powerful and flexible means to disect source
  8. code.
  9.  
  10.  
  11. The files included here are:
  12.  
  13.     Executable:        ( Trace/bin )
  14.  
  15.         debug     - Provides debugging output independent of application startup.
  16.         tDB       - Utility to change 'debug' internal parameters.
  17.         test.SAS  - Short program to test tool set.  Linked with SAStrace.lib.
  18.         test.Manx - Short program to test tool set.  Linked with Manxtrace.lib.
  19.  
  20.  
  21.     Libraries:        ( Trace/libs )
  22.  
  23.         SAStrace.lib  - Link library for SAS compiler environment.
  24.         Manxtrace.lib - Link library for Manx compiler environment.
  25.  
  26.  
  27.     Source:            ( Trace )
  28.  
  29.         debug.c - Source code for debug.
  30.         tDB.c   - Source code for tDB.
  31.         test.c  - Source code for test.
  32.         trace.c - Source code for library modules.
  33.         debug.h - Header for debugging.  Should be #include'd in application.
  34.         trace.h - Header for compiling Debug Utilities.
  35.  
  36.         Make.Manx - Makefile for creating Manxtrace.lib.
  37.         Make.SAS  - Makefile for creating SAStrace.lib as well as executables.
  38.  
  39.  
  40.     Documentation:    ( Trace )
  41.  
  42.         debug.doc - This file.
  43.         Readme.db - 'Read this first' file.  Contains important info.
  44.  
  45.  
  46. These tools were written several years ago in an attempt to provide me with
  47. printf() type output capability for tasks created under Exec (ie: without
  48. AmigaDOS I/O capacity).  However, I soon abandoned them when I found that
  49. enabling the debug output often caused bugs to mysteriously vanish, only to
  50. reappear when the debug code was removed.
  51.  
  52. Recently I discovered the wonders of Enforcer and Mungwall, and decided to
  53. re-evaluate these tools.  I was pleasantly surprised to find that with some
  54. minor modifications to allow output to the serial and parallel ports I could
  55. surround Enforcer and Mungwall output with very specific data regarding the
  56. location of the hits within my code.
  57.  
  58. I hope you find them useful.
  59.  
  60.             Mark Porter (fog...)            Friday 08-May-92 22:58:01
  61.             Phoenix,        AZ
  62.             BIX: fog
  63.  
  64.  
  65.  
  66.  
  67.  
  68. Operation
  69.  
  70.  
  71. To obtain debug output the executable 'debug' should be started.  Generally
  72. it is easiest to start debug in the background by typing "run debug" at the
  73. CLI prompt.  Debug then opens a DOS console window and waits for messages to
  74. arrive at its MsgPort.
  75.  
  76. The appropriate trace.lib should be linked with application code.  In the
  77. library is one function:  Trace().  The action of this function is to send
  78. an Exec Message to the MsgPort opened by debug.  Debug will then output this
  79. information to a DOS console window, as well as one or more of a disk file,
  80. serial port, or parallel port.
  81.  
  82. To change any of the internal debug parameters the executable tDB is used.
  83. Several arguments are supported by tDB (see below).  tDB works much the same
  84. as Trace() in that it sends messages to debug.  The messages tell debug to
  85. adjust its parameters for future debug output.
  86.  
  87. For interactive applications that spend much of their time waiting for user
  88. input, the above technique allows for changing output characteristics de-
  89. pending on which part of code one wishes to test.  See the file test.c for
  90. examples on how to use Trace().
  91.  
  92.  
  93.  
  94.  
  95. Detailed Descriptions
  96.  
  97.  
  98.  
  99.     NAME
  100.  
  101.     debug - Provides debugging output capability to user applications.
  102.  
  103.  
  104.     SYNOPSIS
  105.  
  106.     debug [ level ]
  107.  
  108.  
  109.     DESCRIPTION
  110.  
  111.     Debug outputs information handed it by applications calling Trace() from
  112.     the trace.lib link library.  The output is sent to a DOS console window
  113.     (default) as well as one or more of a disk file, serial port, or parallel
  114.     port.  It is designed to work in conjuction with the trace.lib and the
  115.     executable tDB (see below).
  116.  
  117.     Several internal parameters are utilized by debug to screen incoming
  118.     messages for output.  These are:
  119.  
  120.     Debug Output Destinations:
  121.  
  122.         Debug information is always printed to the DOS console window (pro-
  123.         vided it meets the screening criteria presented below under DB_Function
  124.         List, DB_Screen, and DB_Level).  In addition the user can specify three
  125.         other destinations (see description of tDB below for further explana-
  126.         tion).
  127.  
  128.         1. Disk File.
  129.             Disk file output is enabled using "tDB -w [ filename ]".
  130.  
  131.         2. Serial Port.
  132.             Serial port output is enabled using "tDB -s".
  133.  
  134.         3.    Parallel Port.
  135.             Parallel port output is enabled using "tDB -p".
  136.  
  137.         The serial and parallel port output options were included to allow
  138.         debug to work in conjuction with Enforcer and Mungwall from Commodore.
  139.         Both of these utilities send output to the serial port (both also
  140.         have parallel port counterparts for users without terminal capability).
  141.  
  142.         With either of these configurations Enforcer and/or Mungwall output
  143.         can be surrounded by debug information to help isolate the source of
  144.         bugs.  I highly recommend debug usage in conjunction with these tools.
  145.  
  146.     DB_Function List:
  147.  
  148.         Contains a list of function names (ASCII characters) which are presum-
  149.         bly functions within the application being debugged.  Output from code
  150.         executed within these functions is enabled based upon the setting of
  151.         DB_Screen (see below).
  152.  
  153.         If the list is empty (default at startup), then output from within any
  154.         function is enabled, provided it meets the criteria for DB_Level.
  155.  
  156.     DB_Screen:
  157.  
  158.         This parameter can take on three settings:  db_none, db_include, or
  159.         db_exclude (implemented as enum variables within debug).
  160.  
  161.         1. db_none.
  162.             DB_Screen is ignored when determining output enabling.
  163.  
  164.         2. db_include.
  165.             If the message from Trace() is being executed within a function
  166.             whose name has been entered on the DB_Function List, output from
  167.             that message is enabled.  Any functions whose names do not appear
  168.             on the list will have their output disabled.
  169.  
  170.         3. db_exclude.
  171.             Works opposite db_include.  In this case output from a particular
  172.             function is enabled only if its name does not appear on the
  173.             DB_Function List.
  174.  
  175.         The default for DB_Screen is db_none.  When a function is added to
  176.         DB_Function List, DB_Screen is set to db_include.  To change values
  177.         after this use "tDB -t" to toggle between db_include and db_exclude.
  178.         If the DB_Function List becomes empty at any time, DB_Screen is reset
  179.         to db_none.
  180.  
  181.     DB_Level:
  182.  
  183.         The intent of this parameter is to indicate what nesting level from
  184.         within which the debug code is executing.  This allows the programmer
  185.         to turn on debugging within interior nested loops, or other constructs
  186.         as necessary.  Debug output will be disabled from any messages whose
  187.         level is less than DB_Level.
  188.  
  189.         Screening from this variable is always turned on, and will over-ride
  190.         enabled output due to DB_Function List values.  The default value is
  191.         zero, and can be specified on the command line at debug startup.
  192.  
  193.  
  194.     BUGS
  195.  
  196.     None known.
  197.  
  198.  
  199.  
  200.  
  201.     NAME
  202.  
  203.     tDB - Provides a mechanism for changing debug internal parameters.
  204.  
  205.  
  206.     SYNOPSIS
  207.  
  208.     tDB [ options ]
  209.  
  210.  
  211.     DESCRIPTION
  212.  
  213.     This program passes messages to debug which tell the latter to change
  214.     the value of its internal screening parameters.  Below are listed all
  215.     tDB's options.
  216.  
  217.         -e                Turn debug off.  Debug has no internal mechanism for
  218.                         returning to the Operating System.  The message DB_QUIT
  219.                         is sent from tDB when the -e option is specified.  Debug
  220.                         will then free allocated resources and terminate.
  221.  
  222.         -a <func>    Adds functions to DB_Function List.  The value <func> can
  223.                         be a list of names separated by spaces.
  224.  
  225.         -r <func>    Removes functions from DB_Function List.  The value of
  226.                         <func> can be a list of names separated by spaces.
  227.  
  228.         -c                Clears all entries from DB_Function List.
  229.  
  230.         -t                Toggles DB_Screen between db_include and db_exclude.  If
  231.                         DB_Screen is db_none, this parameter has no effect.
  232.  
  233.         -l [num]        Resets DB_Level to num.  If num is not specified DB_Level
  234.                         is taken as zero.
  235.  
  236.         -w    [file]    Open disk file 'file' for debug output.  If 'file' is not
  237.                         specified the name of the file becomes "DB.out".
  238.  
  239.         -we            Terminate output to disk file and close it.
  240.  
  241.         -s                Send debug output to serial port.
  242.  
  243.         -se            Terminate debug output to serial port.
  244.  
  245.         -p                Send debug output to parallel port.
  246.  
  247.         -pe            Terminate debug output to parallel port.
  248.  
  249.     If tDB is invoked with no command line arguments, debug internal status
  250.     is transmitted to tDB, which then outputs the information to the CLI.
  251.     This allows the user to check debug parameters whenever necessary.
  252.  
  253.  
  254.     BUGS
  255.  
  256.     None known.
  257.  
  258.  
  259.  
  260.     NAME
  261.  
  262.     Trace
  263.  
  264.  
  265.     SYNOPSIS
  266.  
  267.     Trace( level,function,message,arguments )
  268.  
  269.         int         level;
  270.         char        *function,
  271.                     *message;
  272.         unsigned     arguments;
  273.  
  274.  
  275.     DESCRIPTION
  276.  
  277.     Trace() is found in the C link library trace.lib (two libraries called
  278.     SAStrace.lib and Manxtrace.lib are included in this distribution).  It
  279.     should be called from within application code where debugging output is
  280.     desired.
  281.  
  282.     Argument descriptions:
  283.  
  284.         level            Debug level at which to enable output (see tDB and debug
  285.                         above).
  286.  
  287.         function        Name of function within which Trace() is executing.  In
  288.                         reality this can be any type of char *, but debug provides
  289.                         for interpreting this string as a function name, and its
  290.                         output is geared toward that end.
  291.  
  292.         message        Output message.  This string can be formatted exactly as
  293.                         the printf() style output mechanism.  For any run-time
  294.                         evaluated variables the standard %s, %c, %d, %f, etc.
  295.                         codes can be embedded.  The last parameter 'arguments'
  296.                         should contain variables whose type matches the % sequences
  297.                         in 'message' string.
  298.  
  299.         arguments    Variables whose values should be printed in the % codes
  300.                         of 'message' argument.
  301.  
  302.     Trace() supports a variable number of arguments in exactly the same manner
  303.     as printf().
  304.  
  305.     Trace() creates a MsgPort at each invocation.  Were this not the case,
  306.     the programmer would be forced to include some initialization and shut-
  307.     down code in the application, which I felt was undesireable.
  308.  
  309.  
  310.     REFERENCES
  311.  
  312.     The book "Debugging C" by Robert Ward (Que Publishing Corp.) is an excel-
  313.     lent introduction to instrumenting C code.  I have used the concepts given
  314.     in the book when writing Trace().
  315.  
  316.  
  317.     BUGS
  318.  
  319.     None known.
  320.