home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / h_doc / Debug < prev    next >
Encoding:
Text File  |  1997-01-20  |  9.1 KB  |  338 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for 
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #                                      
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    Debug.h
  12.     Author:  Copyright © 1995 Julian Smith, Cy Booker, Paul Field.
  13.     Version: 1.01 (04 Jun 1995)
  14.     Purpose: Defines interface to a set of functions useful for
  15.              debugging.
  16.     Mods:    25 Aug 1995 - JS - Added Desk_Debug_Assert.
  17.              12 Feb 1996 - JS - Removed Desk_Debug__Dummy, and changed 
  18.                                 Desk_Debug_Dummyf macro to use printf.
  19.                                 Made #defines of Debug<n>_Printf map 
  20.                                 straight to Desk_Debug_Dummyf for non-debug 
  21.                                 builds to stop cc from making a .o file 
  22.                                 which refers to Desk_debug_level, but doesn't 
  23.                                 actually use it in the code.
  24.              20 Feb 1996 - JS - Added #include <stdio.h>
  25.  
  26. */
  27.  
  28.  
  29. /*
  30.  
  31. Here are prototypes for a standard set of simple debugging functions.
  32.  
  33. Note that the main DeskLib library 'DeskLib:o.DeskLib' does *not*
  34. contain any of these functions - you have to link with a library inside
  35. 'DeskLib:o.Debug.' (or provide your own versions of the functions). This
  36. is so that different debugging libraries can be used, to output data to
  37. stderr, or a file in pipe or wherever you feel most comfortable with...
  38.  
  39. This header file ensures that all calls to Desk_Debug_xxx functions are
  40. macro-ed out by the preprocessor unless Desk_DeskLib_DEBUG is predefined.
  41.  
  42. This is so you can put lots of 'Desk_Debug_Printf(...)' calls etc in your
  43. code, safe in the knowledge that they will all disappear when building a
  44. normal version of your project.
  45.  
  46. */
  47.  
  48. #ifndef __Desk_Debug_h
  49. #define __Desk_Debug_h
  50.  
  51. #ifdef __cplusplus
  52.     extern "C" {
  53. #endif
  54.  
  55. #include <stdio.h>
  56. #include <stdarg.h>
  57.  
  58.  
  59. #ifndef __Desk_Core_h
  60.     #include "Desk.Core.h"
  61. #endif
  62.  
  63.  
  64.  
  65. typedef void (*Desk_debug_signalhandlerfn)( int sig, void *reference);
  66. /*
  67. This is a function-type which is called when a signal happens
  68. */
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75. #if !defined( Desk_DEBUG) && !defined( Desk__making_Debug)
  76.  
  77.     #define Desk_Debug_Initialise()
  78.     
  79.     #define Desk_Debug_InitialiseSignal()
  80.     #define Desk_Debug_ClaimSignal( fn, reference)
  81.     #define Desk_Debug_ReleaseSignal()
  82.     
  83.     #define    Desk_Debug_Finalise()
  84.     
  85.     #define Desk_Debug_Assert( expression)
  86.     
  87.     #define Desk_Debug_Error_CheckFatal( errfn)    Desk_Error_CheckFatal( errfn)
  88.     
  89.     #define Desk_Debug_Print( text)
  90.     
  91.     #define    Desk_Debug_DumpRegistersToFile()
  92.     
  93.     #define    Desk_Debug_SetNestingIndentation( indentstring)
  94.     
  95.     #define    Desk_Debug_DescribeError2( error)
  96.     
  97.     #define    Desk_Debug_SetLevel( level)
  98.     
  99.     #define    Desk_Debug_BackTrace()
  100.     #define    Desk_Debug_PrintMemory( start, size)
  101.     
  102.     #define Desk_Debug_Printf     Desk_Debug_Dummyf
  103.     #define Desk_Debug1_Printf    Desk_Debug_Dummyf
  104.     #define Desk_Debug2_Printf    Desk_Debug_Dummyf
  105.     #define Desk_Debug3_Printf     Desk_Debug_Dummyf
  106.     #define Desk_Debug4_Printf     Desk_Debug_Dummyf
  107.     #define Desk_Debug5_Printf     Desk_Debug_Dummyf
  108.     
  109.     #define Desk_Debug_VPrintf     Desk_Debug_Dummyf
  110.     #define Desk_Debug1_VPrintf    Desk_Debug_Dummyf
  111.     #define Desk_Debug2_VPrintf    Desk_Debug_Dummyf
  112.     #define Desk_Debug3_VPrintf     Desk_Debug_Dummyf
  113.     #define Desk_Debug4_VPrintf     Desk_Debug_Dummyf
  114.     #define Desk_Debug5_VPrintf     Desk_Debug_Dummyf
  115.     
  116.     #define    Desk_Debug_RedirectToFilename( filename)
  117.     
  118.     /*
  119.     These effectively remove any references to Desk_Debug_ functions from 
  120.     source code.
  121.     */
  122.  
  123. #else
  124.     
  125.     void    Desk_Debug_Initialise( void);
  126.     /*
  127.     Sets up the debug library - call this at the start of main().
  128.     */
  129.     
  130.     void    Desk_Debug_Finalise( void);
  131.     /*
  132.     Closes any output file. Not normally needed as the C runtime system
  133.     closes all open files automatically.
  134.     */
  135.     
  136.     void    Desk_Debug_InitialiseSignal( void);
  137.     /*
  138.     Sets up a handler for signals
  139.     */
  140.     
  141.     void    Desk_Debug_ClaimSignal( Desk_debug_signalhandlerfn fn, void *reference);
  142.     /*
  143.     Makes 'fn' be called when a signal occurs.
  144.     */
  145.     
  146.     void    Desk_Debug_ReleaseSignal( void);
  147.     /*
  148.     Stops the fn, from a previous call to Desk_Debug_ClaimSignal, being called
  149.     */
  150.     
  151.     int    Desk_Debug_Printf( const char *format, ...);
  152.     /*
  153.     Sends the text to the debug output, in same way as printf.
  154.     */
  155.     
  156.     int    Desk_Debug_VPrintf( const char *format, va_list va);
  157.     /*
  158.     Sends the text to the debug output, in same way as vprintf.
  159.     */
  160.     
  161.     void    Desk_Debug_Print( const char *text);
  162.     /*
  163.     Sends a string to the debug output.
  164.     */
  165.     
  166.     void    Desk_Debug_DumpRegistersToFile( void);
  167.     /*
  168.     Saves all registers to '<Wimp$ScrapDir>.regsxx' using OS_File
  169.     10, where 'xx' is a hex number starting at 0. Preserves all
  170.     registers apart from lr    and pc.
  171.      */
  172.     
  173.     void    Desk_Debug_SetNestingIndentation( const char* prefix);
  174.     /*
  175.     Future outputs from Desk_Debug_Printf are prefixed by multiples of
  176.     the specified string, according to the current function-call
  177.     nesting.
  178.     
  179.     Note that the prefix string is /not/ copied, so must be
  180.     permanent.
  181.     
  182.     Also note that you shouldn't call this if you are ever going to
  183.     call Desk_Debug_Printf from a place which doesn't have a stack
  184.     that the Desk_BackTrace functions understand - otherwise they
  185.     will cause an address exception or similar.
  186.     
  187.     This has only happened to me (JS) was inside a function which
  188.     was called by a CMHG IRQ veneer.
  189.     */
  190.     
  191.     struct Desk_error2_block;
  192.     void    Desk_Debug_DescribeError2( const struct Desk_error2_block* error);
  193.     /*
  194.     Uses Desk_Error2_FDescribe to send info about 'error' to Debug_Printf.
  195.      */
  196.     
  197.     
  198.     #define    Desk_Debug_SetLevel( level)    Desk_debug_level = (level)
  199.     /*
  200.     Use this so set the debug-level - it reduces to nothing with
  201.     normal compilation
  202.      */
  203.     
  204.     int    Desk_Debug_PrintfRef( void* reference, const char *format, ...);
  205.     /*
  206.     This function behaves exactly like Desk_Debug_Printf - 'reference' is ignored.
  207.     It is for use as a call-back receiver to functions which send a reference (eg
  208.     Desk_Error2_FDescribe).
  209.      */
  210.     
  211.     
  212.     void    Desk_Debug_BackTrace( void);
  213.     /*
  214.     Outputs a backtrace using Desk_Debug_Printf.
  215.      */
  216.     
  217.     
  218.     
  219.     #define Desk_Debug_Error_CheckFatal( errfn)        \
  220.         do    {                    \
  221.             Desk_os_error    *Desk_debug__e = errfn;    \
  222.                 if ( Desk_debug__e)    {    \
  223.                 Desk_Error_ReportFatal(     \
  224.                     Desk_debug__e->errnum,     \
  225.                     Desk_error_PLACE "%s",     \
  226.                     Desk_debug__e->errmess    \
  227.                     );            \
  228.                 }                \
  229.             }                    \
  230.             while (0)
  231.     /*
  232.     As Desk_Error_ReportFatal, but also displays the file and line number if
  233.     Desk_DeskLib_DEBUG is predefined.
  234.     */
  235.     
  236.     void    Desk_Debug__Assert( const char *expression, const char *sourcefile, int line);
  237.     /*
  238.     Not for user consumption - used by Desk_Debug_Assert.
  239.     */
  240.     
  241.     
  242.     void    Desk_Debug_PrintMemory( void* start, int size);
  243.     
  244.     void    Desk_Debug_RedirectToFilename( const char* filename);
  245.     /*
  246.     Only implemented in uniqfile at the moment.
  247.      */
  248.     
  249.     #define Desk_Debug_Assert( expression)                    \
  250.         (                                \
  251.             (expression)                         \
  252.                 ?                         \
  253.                 (void) 0                     \
  254.                 :                         \
  255.                 Desk_Debug__Assert( #expression, __FILE__, __LINE__)    \
  256.         )
  257.     /*
  258.     This is similar to the standard ANSI C 'assert' macro. If
  259.     'expression' evaluates to Desk_bool_FALSE, Desk_Debug_Printf is used
  260.     to output a diagnostic message, and then abort() is called.
  261.     
  262.     Like all the Desk_Debug_ commands, Desk_Debug_Assert is removed before compilation
  263.     unless Desk_DeskLib_DEBUG is defined.
  264.     
  265.     */
  266.     
  267.     #define Desk_Debug1_Printf (Desk_debug_level<1) ? 0 : Desk_Debug_Printf
  268.     /* Only outpus diagnostics if Desk_debug_level is >= 1    */
  269.     
  270.     #define Desk_Debug2_Printf (Desk_debug_level<2) ? 0 : Desk_Debug_Printf
  271.     /* Only outpus diagnostics if Desk_debug_level is >= 2    */
  272.     
  273.     #define Desk_Debug3_Printf (Desk_debug_level<3) ? 0 : Desk_Debug_Printf
  274.     /* Only outpus diagnostics if Desk_debug_level is >= 3    */
  275.     
  276.     #define Desk_Debug4_Printf (Desk_debug_level<4) ? 0 : Desk_Debug_Printf
  277.     /* Only outpus diagnostics if Desk_debug_level is >= 4    */
  278.     
  279.     #define Desk_Debug5_Printf (Desk_debug_level<5) ? 0 : Desk_Debug_Printf
  280.     /* Only outpus diagnostics if Desk_debug_level is >= 5    */
  281.     
  282.     /* 
  283.     The Desk_DebugN_Printf macros can be used to control how much 
  284.     diagnostic information is produced.
  285.     */
  286.     
  287. #endif
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298. #define Desk_Debug_Dummyf (Desk_bool_TRUE) ? 0 : printf
  299. /*
  300. A macro which is used to remove calls to a multi-argument function which
  301. returns an integer. This isn't a bomb-proof macro, but is the best I can
  302. come up with.
  303.  
  304. NB The simpler alternative macro '#define Desk_Debug_Dummyf if (0)
  305. Desk_Debug__Dummyf' isn't used because it affects the meaning of 'else' in
  306. (for example):
  307.  
  308. if (flag) Desk_Debug_Dummyf( "flag=%i\n", flag);
  309. else      flag=3;
  310.  
  311. */
  312.  
  313.  
  314. extern int    Desk_debug_level;
  315. /*
  316. This is initially 0. Setting it to values greater than zero will turn on
  317. any subsequent Desk_DebugX_Printf statements.
  318.  
  319. Note that this will only happen with code compiled with Desk_DeskLib_DEBUG
  320. predefined.
  321.  
  322. Note that this selection of Desk_DebugX_Printf is 'live' - ie you can change
  323. Desk_debug_level before calling different functions to only have diagnostics
  324. from certain parts of your code.
  325.  
  326. */
  327.  
  328.  
  329.  
  330.  
  331.  
  332. #ifdef __cplusplus
  333. }
  334. #endif
  335.  
  336.  
  337. #endif
  338.