How to enable verbose debug tracing in various drivers and subsystems (314743)


The information in this article applies to:

  • Microsoft Windows XP Driver Development Kit (DDK)
  • Microsoft Windows 2000 Driver Development Kit (DDK)
  • Microsoft Windows 2000 Professional
  • Microsoft Windows 2000 Server
  • Microsoft Windows 2000 Datacenter Server
  • Microsoft Windows 2000 Advanced Server
  • Microsoft Windows XP Home Edition
  • Microsoft Windows XP Professional
This article was previously published under Q314743

SUMMARY

When you debug device drivers, it is important that you receive verbose debug tracing from the drivers and related subsystems.

Most of the Microsoft-provided drivers and subsystems use global variables and a predefined set of values to control the verbosity of the debug tracing information that is sent to the debugger.

This article discusses the following topics:
  • How to enable and control the debug tracing level by using a kernel debugger and registry values.
  • For a certain class of drivers, you can use the corresponding debugger extensions to enable and control debug tracing.
  • The differences between enabling debug tracing in Windows 2000 and Windows XP.

MORE INFORMATION

Important This article contains information about running .chk files for development and testing purposes. Microsoft Product Support Services (PSS) does not support production systems that have .chk files installed unless you were told by PSS to install the .chk files to isolate a problem. Before you install .chk files on a production system, make sure to back up the system, and make sure that you understand how to restore the replaced file if a problem occurs.

For more information about .chk files, click the following article numbers to view the articles in the Microsoft Knowledge Base:

103659 Setup hangs while inspecting hardware; how to use Ntdetect.com

320040 How to use Ntdetect.chk to identify hardware problems in Windows 2000

For information about how to back up and restore the system, view Windows 2000 Help and support. For more information about NTbackups, click the following article numbers to view the articles in the Microsoft Knowledge Base:

240363 How to use the Backup program to back up and restore the system state in Windows 2000

You can also contact your backup product provider for information about how to use their product.

Note The following debugging information is subject to change at any time and is intended only for driver-debugging purposes. Also note that debug information may not be particularly useful to anyone other than developers.

Video miniport debugging

Note the following about video miniport debugging:
  • It requires checked build video port and miniport drivers.
  • It does not use a debugger extension.
  • It enables debug tracing by setting the global variable (or variables).
  • Variable names in Windows 2000 are different from those in Windows XP.
  • In Windows 2000, you can enable debug tracing either through the registry or the debugger, as follows:
    • Set the value of VideoDebugLevel (0-3) in the registry, as follows: HKEY_LOCAL_MACHINE\SYSTEM\CCS\Services\DriverName\DeviceN VideoDebugLevel:REG_DWORD: 2
    • Or through the debugger, as follows:

      ed videoprt!VideoDebugLevel 2

  • The video port on a Windows XP-based computer uses the new DbgPrintEx function (see the "NOTES" section of this article).

    The following variables are defined for video drivers:

    Kd_IHVVIDEO_Mask
    Kd_VIDEO_Mask
    Kd_VIDEOPRT_Mask

    To set a mask, do the following:
    • Add the mask that you want in the registry. For example: HKEY_LOCAL_MACHINE\SYSTEM\CCS\Control\Session Manager\Debug Print Filter "IHVVIDEO"=DWORD: 0xffffffff
    • Or in the debugger, as follows:

      ed Kd_IHVVIDEO_Mask 0xffffffff

1394 debugging

Note the following about 1394 debugging:
  • It requires a checked build system or checked build 1394 modules.
  • On both Windows 2000 and Windows XP-based systems, set the corresponding global variable through the debugger. For example:

    ed ohci1394!ohcidebuglevel 6

      Module name    Debug symbol  Range
    OHCI1394.SYSohcidebuglevel1-6
    SBP2PORT.SYSsbp2debuglevel1-4
    1394BUS.SYSbusdebuglevel1-5
    For more information, click the following article number to view the article in the Microsoft Knowledge Base:

    259855 How to enable debug prints in IEEE 1394 drivers

USB debugging

Note the following about universal serial bus (USB) debugging:
  • It requires a checked build system or checked build USB modules.
  • On a Windows 2000-based system, you need to set the corresponding global variable through the debugger. For example:

    ed USBD!USBD_Debug_Trace_Level 2

      Module name    Debug symbol  Range
    UHCD.SYSUHCD_Debug_Trace_Level0-2
    OPENHCI.SYSOHCI_Debug_Trace_Level0-2
    USBHUB.SYSUSBH_Debug_Trace_Level0-3
    USBD.SYSUSBD_Debug_Trace_Level0-3
  • Use the following parameters on a Windows XP-based system.
      Module name    Debug symbol  Range
    USBPORT.SYSUSBPORT_Debug_Trace_Level0-4
    USBCCGP.SYSDbgVerbose0 or 1
    USBHUB.SYSUSBH_Debug_Trace_Level0-3
    USBD.SYSUSBD_Debug_Trace_Level0-3
    USBPORT.SYSUSBPORT_CatcTrapEnable0-1
  • All USB miniport drivers use USBPORT for debug output.

PCI debugging

Note the following about Peripheral Component Interconnect (PCI) debugging:
  • It requires a checked build system or a checked build PCI.SYS module.
  • On both Windows 2000 and Windows XP-based systems, set the corresponding global variable through the debugger. For example (with 0x3 being the most verbose:

    ed PCI!PciDebug 0x3

      Module name    Debug symbol  Range
    PCI.SYS PciDebug  0-3 

PCMCIA debugging

Note the following about PCMCIA debugging:
  • It requires a checked build system or a checked build pcmcia module.
  • On both Windows 2000 and Windows XP-based systems, set the corresponding global variable through the debugger. For example

    ed PCMCIA!PcmciaDebugMask 0xFFFFFFFF

    where:
    #define PCMCIA_DEBUG_ALL       0xFFFFFFFF
#define PCMCIA_DEBUG_TUPLES    0x00000001
#define PCMCIA_DEBUG_ENABLE    0x00000002
#define PCMCIA_DEBUG_PARSE     0x00000004
#define PCMCIA_DUMP_CONFIG     0x00000008
#define PCMCIA_DEBUG_INFO      0x00000010
#define PCMCIA_DEBUG_IOCTL     0x00000020
#define PCMCIA_DEBUG_DPC       0x00000040
#define PCMCIA_DEBUG_ISR       0x00000080
#define PCMCIA_DEBUG_CANCEL    0x00000100
#define PCMCIA_DUMP_SOCKET     0x00000200
#define PCMCIA_READ_TUPLE      0x00000400
#define PCMCIA_SEARCH_PCI      0x00000800
#define PCMCIA_DEBUG_FAIL      0x00008000
#define PCMCIA_PCCARD_READY    0x00010000
#define PCMCIA_DEBUG_DETECT    0x00020000
#define PCMCIA_COUNTERS        0x00040000
#define PCMCIA_DEBUG_OVERRIDES 0x00080000
#define PCMCIA_DEBUG_IRQMASK   0x00100000
      Module name    Debug symbol  Range
    PCMCIA.SYS PcmciaDebugMask  0-FFFFFFFF 

NDIS debugging

Note the following about network driver interface specification (NDIS) debugging:

Storage driver debugging

Note the following about storage driver debugging:
  • It requires a checked build system or checked build storage modules. For more information, click the following article number to view the article in the Microsoft Knowledge Base:

    296225 How to enable SCSIPORT debug logging

Printer driver debugging

Note the following about printer driver debugging.

User mode

  • Requires a checked build system or checked build printer driver components (unidrv or pscript).
  • Attach to either the printing application or the spooler process (spoolsv.exe), depending on whether you are debugging the user interface (UI) module or the rendering module.
  • For Unidrv debugging, use the following setting:

    ed unidrv!giDebugLevel 1

Kernel mode

  • Run the gflags command, and then enable the following flag on spoolsv.exe:
    • Windows 2000: "Place Heap Allocation at end of pages"
    • Windows XP: "enable page heap"
  • Restart the spooler (net stop/start spooler).
  • Run verifier.exe on Win32K.sys to debug your printer driver.

Audio driver debugging

Note the following about audio driver debugging:
  • It requires a checked build system or checked build audio modules.
  • On both Windows 2000 and Windows XP-based systems, set the corresponding global variable through the debugger. For example:

    ed USBAUDIO!USBAudioDebugLevel 3

       Module name       Debug symbol      Range  
    USBAUDIO.SYSUSBAudioDebugLevel0-3
    SYSAUDIO.SYSSYSAUDIOTraceLevel0-100

HID driver debugging

Note the following about HID driver debugging:
  • It requires a checked build system or checked build HID modules.
  • On both Windows 2000 and Windows XP-based systems, set the corresponding global variable through the debugger. For example:

    ed HIDCLASS!dbgverbose 1

       Module name       Debug symbol      Range  
    HIDUSB.SYSHIDUSB_DebugLevel0-1
    HIDCLASS.SYSdbgverbose0-1

Serial driver debugging

Note the following about serial driver debugging:
  • It requires a checked build system or checked build serial modules.
  • Serial.sys (on both Windows 2000 and Windows XP-based systems):
    • Set the DebugLevel value in the registry, as follows:

      HKLM\System\CCS\Services\Serial "DebugLevel"= REG_DWORD:0xFFFFFFFF

      Or set it through the debugger, as follows:

      ed Serial!SerialDebugLevel (0x00000000 - 0xFFFFFFFF)

    • Mask values are defined in the following directory:

      %DDKROOT%\src\kernel\serial\serial.h

  • Serenum.sys (on both Windows 2000 and Windows XP-based systems):
    • Set the DebugLevel value in the registry, as follows:

      HKEY_LOCAL_MACHINE\System\CCS\Services\Serenum "DebugLevel"= REG_DWORD:1FF

    • Mask values are defined in the following directory:

      %DDKROOT%\src\kernel\serenum\serenum.h

Modem driver debugging

To enable full unimodem verbose debugging on Windows 2000 and Windows XP-based systems, you need to have a checked build, and then do the following:
  1. For everything except Mdminst.dll and Unimdm.tsp, add the following registry keys:
    • HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Unimodem "DebugFlags"=dword:0000003f
    • HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon "SFCDisable"=dword:00000001
    • HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Modem "DebugFlags"=dword:0000003f
    • HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Modemcsa "DebugFlags"=dword:0000003f
  2. For Mdminst.dll, copy Unimdm.ini into %windir%. The following is an example of a Unimdm.ini file:
    [ModemUI]
; DumpFlags:
;    00000001   DCB
;    00000002   MODEMSETTINGS
;    00000004   DEVCAPS
DumpFlags=0x0000000f

; TraceFlags:
;    00000001   Warnings
;    00000002   Errors
;    00000004   General 
;    00000008   Function trace
TraceFlags=0x0000000f

; BreakFlags:
;    00000001   Break on validate
;    00000040   Break on process attach
;    00000100   Break on API enter
BreakFlags=0x00000000

;; --------------------------------------------------------------------

[Modem]
; DumpFlags:
DumpFlags=0x0000000f

; TraceFlags:
;    00000001   Warnings
;    00000002   Errors
;    00000004   General 
;    00000008   Function trace
;    00010000   Detection queries
;    00020000   Class installer trace
TraceFlags=0x0003000f

; BreakFlags:
;    00000001   Break on validate
;    00000040   Break on process attach
;    00000100   Break on API enter
BreakFlags=0x00000000

;; --------------------------------------------------------------------

[SerialUI]
; DumpFlags:
;    00000001   DCB
DumpFlags=0x00000000

; TraceFlags:
;    00000001   Warnings
;    00000002   Errors
;    00000004   General 
;    00000008   Function trace
TraceFlags=0x00000000

; BreakFlags:
;    00000001   Break on validate
;    00000040   Break on process attach
;    00000100   Break on API enter
BreakFlags=0x00000000

;; --------------------------------------------------------------------

[Unimdm]
; DumpFlags:
DumpFlags=0x0000000f

; TraceFlags:
;    00000001   Warnings
;    00000002   Errors
;    00000004   General 
;    00000008   Function trace
;    00010000   dwDeviceID related
;    00020000   hdLine related
;    00040000   hdCall related
;    00080000   pLineDev related
;    00100000   pModemInfo related
TraceFlags=0x001f000f

; BreakFlags:
;    00000001   Break on validate
;    00000040   Break on process attach
;    00000080   Break on process detach
;    00000100   Break on API enter
BreakFlags=0x00000000
  3. For Unimdm.tsp debugging, add the following registry key:

    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{4D36E96D-E325-11CE-BFC1-08002BE10318}\device instance\Logging

Device installation debugging

To receive a verbose trace from kernel and usermode PNP manager on Windows XP and later versions, you have to obtain a checked build, and then run following code: 

ed NT!Kd_NTOSPNP_Mask 0xFFFFFFFF ed NT!Kd_PNPMGR_Mask 0xFFFFFFFF

On Windows 2000, you can set global variable PnpEnumDebugLevel to 1 or 2 in the kernel debugger as follows: 

ed nt!PnpEnumDebugLevel 2

Notes

Some of the drivers and subsystems on Windows XP-based systems use the new DbgPrintEx function: 
ULONG DbgPrintEx(IN ULONG ComponentID,
                 IN ULONG Level, IN PCHAR Format, . . . .
                 [arguments]);
Microsoft has defined about 95 different component IDs (look for DPFLTR_TYPE in the Ntddk.h file). For every component filter ID, there is a global mask variable, for example,

NT! Kd_IHVVIDEO_Mask, NT!Kd_IHVAUDIO_Mask

You can set the value of the mask either through the registry, as follows:

HKEY_LOCAL_MACHINE\SYSTEM\CCS\Control\Session Manager\Debug Print Filter


"IHV_AUDIO"=REG_DWORD:0xFFFFFFFF or with a debugger, for example,

ed NT!Kd_IHVAUDIO_Mask 0xffffffff

Debug output is filtered based on the global mask (Kd_Win2000_Mask) and the component level mask. The Windbg Help file documents how the mask and level values are used in filtering the output.

To enable debug tracing, use the following code to locate your component ID either from the Ntddk.h file or from the debugger: 
x NT!Kd_*_Mask
Then, set the value to the maximum for verbose output (0xffffffff). Currently, only a few classes of drivers (described in the "More Information" section of this article) use this new function.
Modification Type:MajorLast Reviewed:9/27/2005
Keywords:kbBug kbDebug kbdisplay kbfile kbhowto kbinfo kbInput kbKMode kbNDIS kbPlugPlay kbSerial kbUSB kbWDM KB314743 kbAudDeveloper
©2004 Microsoft Corporation. All rights reserved.