INFO: Debug Printing Implementation in the Device Drivers

ID: Q90082

The information in this article applies to:

Microsoft Win32 Device Driver Kit (DDK) for Windows NT, versions 3.1, 3.5, 3.51

SUMMARY

Each device driver uses its own method for debug printing. There are things that each method will have in common.

Many of the drivers use a debug print routine that controls the level of debug messages that are printed. Debug printing can also typically be disabled. Here are some examples of the different print routines and how they are used:


   COM driver                           SerialDump()
   AT disk controller                   AtDump()
   SCSI class, port, and miniport       DebugPrint()

In the SCSI drivers, if DBG is defined, then debug printing can be used (checked build). If DBG is not defined, then debug printing is not used (free build).


   #if DBG
   #define DebugPrint(x)  ScsiDebugPrint x
   #else
   #define DebugPrint(x)
   #endif

The messages that can be printed are classified by level, 0 being the lowest level, 3 being the highest level. When a call is made to the debug printing routine, the first variable is a message level and the second variable is a message string.


   DebugPrint((1,"ScsiCdRomRead: Invalid I/O parameters\n"));

The debug printing routine compares the message level with a global variable (defined by the device driver) that sets the current message level that can be printed. If the message level is acceptable, the message string is printed. The comparison method varies between drivers. For example, messages from SCSI drivers are printed if they are less than or equal to the current message level. The AT disk controller performs an ORing operation to determine if the message is printable. The following mechanism is used by the COM driver


   #if DBG
   #define SerialDump(LEVEL, STRING) \ 
      do {\ 
         if(SerialDebugLevel & LEVEL){\ 
            DbgPrint STRING; \ 
         }\ 
         if(LEVEL == SERBUGCHECK){\ 
            ASSERT(FALSE);\ 
         }\ 
      }while(0)
   #else
   #define SerialDump(LEVEL, STRING) do {NOTHING;} while(0)
   #endif

MORE INFORMATION

For the COM driver, the global variable used to store the current message level is SerialDebugLevel. See INITUNLO.C to examine this variable's usage. For the AT ESDI disk driver, the variable used is AtDebugLevel. See ATDISK.C for this variables usage. The global variable for SCSI drivers is ScsiDebug. All of these variables (SerialDebugLevel, AtDebugLevel and ScsiDebug) have a default value of 0 and could be modified to produce more debugging output.

Note, since source code for SCSIPORT.SYS is not available with the NT DDK, this variable can only be modified from the kernel debugger in the following manner:


   kd >ed scsiport!scsidebug 3
   kd >g

Keywords : NTDDKDebug
Version : WINNT:3.1,3.5,3.51;
Platform : winnt
Issue type : kbinfo