Driver Debugging

1
Driver Debugging

• Eliyas Yakub
• Developer Support
• DDK

2
Agenda

• Overview of PnP driver
• How to get device status with a debugger
• Debug driver unload issue
• How to debug enable debug tracing in
• NDIS
• Video
• PCI/PCMCIA
• SCSI
• 1394
• USB
• HID
• Serial
• Audio
• Printer

3
Basic Objects

• Driverobject one for every driver
• Deviceobjects one or more object created by
  drivers to represent devices
• Three kinds of Deviceobjects
• PDO (Physical deviceobject created by bus driver)
• FDO (Functional deviceobject created function
  driver)
• FiDO (Filter deviceobjects created by filter
  drivers)
• Devnode present in the PDO
• Devnode contains the PNP state of the device

4
Device Stack
Upper Class
Upper Device
Function Driver
Lower Class
Lower Device
Bus Driver
PDO
5
DriverObject

• If you know the service name
• !drvobj toaster
• Driver object (81254df8) is for
• \Driver\toaster
• Driver Extension List (id , addr)
• Device Object list
• 811b4bf8
• !drvobj 81254df8

6
Device Stack

• From the deviceobject, you can get the entire
  device stack information
• KDgt!devstack 811b4bf8
• !DevObj !DrvObj !DevExt
  ObjectName
• gt811b4bf8 \Driver\toaster 811b4cb0
• 81753a30 \Driver\busenum 81753ae8 0000004f
• !DevNode 81750a60
• DeviceInst is "Toaster\MsToaster\11a590e2c001
  "
• ServiceName is "toaster"

7
Status of a device - Devnode

• Dump the devnode to get the pnp state and
  resources of a device
• !DevNode 0x81750a60
• DevNode 0x81750a60 for PDO 0x81753a30
• Parent 0x8179b350 Sibling 0000000000 Child
  0000000000
• InstancePath is "Toaster\MsToaster\11a590e2c0
  01"
• ServiceName is "toaster"
• State DeviceNodeStarted (0x308)
• Previous State DeviceNodeEnumerateCompletion
  (0x30d)
• StateHistory07 DeviceNodeEnumerateCompletion
  (0x30d)
• StateHistory06 DeviceNodeStarted (0x308)
• StateHistory05 DeviceNodeStartPostWork
  (0x307)
• StateHistory04 DeviceNodeStartCompletion
  (0x306)
• StateHistory03 DeviceNodeResourcesAssigned
  (0x304)
• StateHistory02 DeviceNodeDriversAdded
  (0x303)
• StateHistory01 DeviceNodeInitialized
  (0x302)
• StateHistory00 DeviceNodeUninitialized
  (0x301)
• Flags (0x00000030) DNF_ENUMERATED,
  DNF_IDS_QUERIED
• CapabilityFlags (0x00000218) EjectSupported,
  Removable,
• SurpriseRemovalOK

8
Devnode (2)

• !DevNode 817ba310 2
• DevNode 0x817ba310 for PDO 0x817958e0
• ltsnipgt
• CmResourceList at 0xe139f7f8 Version 0.0
  Interface 0x5 Bus 0
• Entry 0 - Port (0x1) Device Exclusive (0x1)
• Flags (0x31) - PORT_MEMORY PORT_IO
  16_BIT_DECODE POSITIVE_DECODE
• Range starts at 0xffa0 for 0x10 bytes
• Entry 1 - DevicePrivate (0x81) Device
  Exclusive (0x1)
• Flags (0000) -
• Data - 0x00000001, 0x00000004, 0000000000
• BootResourcesList at 0xe1392f40 Version 1.1
  Interface 0x5 Bus 0
• Entry 0 - Port (0x1) Undetermined Sharing (0)
• Flags (0x01) - PORT_MEMORY PORT_IO
• Range starts at 0xffa0 for 0x10 bytes

9
Devnode (3)

• To display the entire device tree starting from
  the root device
• !devnode 0 1

10
Resource Conflict

• !arbiter current system resource arbiters and
  arbitrated ranges.
• This command is useful for debugging resource
  conflicts
• Windbg help describes how to use !arbiter command
  to identify resource conflict

11
Get dispatch points

• !drvobj toaster 2
• Driver object (81254df8) is for
• \Driver\toaster
• DriverEntry f9e20242 toaster!DriverEntry
• DriverStartIo 00000000
• DriverUnload f9e1db9c toaster!ToasterUnload
• Dispatch routines
• 00 IRP_MJ_CREATE
  f9e1d369 toaster!ToasterCreate
• 16 IRP_MJ_POWER
  f9e1dc57 toaster!ToasterDispatchPower
• 17 IRP_MJ_SYSTEM_CONTROL
  f9e1ed26 toaster!ToasterSystemControl
• 18 IRP_MJ_DEVICE_CHANGE
  804f9fe2 nt!IopInvalidDeviceRequest
• 1b IRP_MJ_PNP
  f9e1ca44 toaster!ToasterDispatchPnp
• bp toaster!ToasterDispatchPnp

12
Dump Deviceobject

• !devobj 811b4bf8
• Device object (811b4bf8) is for
• \Driver\toaster DriverObject 81254df8
• Current Irp 00000000 RefCount 0 Type 00000022
  Flags 00002004
• DevExt 811b4cb0 DevObjExt 811b4d98
• ExtensionFlags (0000000000)
• AttachedTo (Lower) 81753a30 \Driver\busenum
• Device queue is not busy.

13
Dump a PDO

• !devobj 81753a30
• Device object (81753a30) is for
• 0000004f \Driver\busenum DriverObject 8123de18
• Current Irp 00000000 RefCount 0 Type 0000002a
  Flags 00003040
• DevExt 81753ae8 DevObjExt 81753b20 DevNode
  81750a60
• ExtensionFlags (0000000000)
• AttachedDevice (Upper) 811b4bf8 \Driver\toaster
• Device queue is not busy.

14
Debugging Driver Unload

• Due to leaked references or open handles
• Get the driverobject/deviceobject address
  (IopLoadDriver or IoCreateDevice)
• !object 81a578c0
• Object 81a578c0 Type (81bd0e70) Device
  ObjectHeader 81a578a8 HandleCount 0
  PointerCount 3
• Directory Object e1001208 Name Serial0
• ba w4 81a578a8 "kg"

15
Due to Open Handles

• Run oh.exe on the target checked build system
• This tells the system to track handles
• Restart the machine disable the device
• PNP dumps following info when a query remove is
  vetoed
• 1Beginning handle dump1 (Failed
  Query-Remove - Might by due to leaked
  handles)1 DeviceObject816CAEE0 ProcessID1744T
  FileObject817808D0 Handle636T 1Dump complete
  - 1 total handles found.
• !process 6D0

16
Debug Trace

• Introduced new DbgPrintEx function on XP
• ULONG DbgPrintEx( IN ULONG ComponentID,
• IN ULONG Level, IN PCHAR Format, . . . .
  arguments )
• Microsoft has defined 95 component filter IDs
  (Look for DPFLTR_TYPE in ntddk.h)
• For every component filter, there is global mask
  variable
• NT! Kd_IHVVIDEO_Mask
• NT!Kd_IHVAUDIO_Mask

17
Debug Trace

• You can set the value of the mask either thru
  registry or with a debugger HKLM\SYSTEM\CCS\Contr
  ol\Session Manager\Debug Print Filter
  IHV_AUDIOREG_DWORD0xFFFFFFFF
• Or
• ed NT! Kd_IHVAUDIO_Mask 0xffffffff
• Debug output is filtered based on global mask
  (Kd_Win2000_Mask) and component level mask
• How the mask and level values are used in
  filtering the output is documented in the Windbg
  Help file.

18
Debug Trace

• Find your component ID either from the ntddk.h
  file or
• KDgt x NT!Kd__Mask
• Set the value to max for verbose output
  (0xffffffff)
• Not all the drivers in the system are using this
  new function

19
NDIS Debugging

• Requires checked build NDIS
• Load NDIS debugger extension
• !load ndiskd.dll
• Enable NDIS debug tracing
• ! dbglevel
• Current setting INFO
• Available settings
• INFO LOG WARN ERR
• ! dbgsystems
• Current settings PNP
• Available settings
• INIT CONFIG SEND RECV PROTOCOL
• BIND BUS_QUERY REGISTRY MEMORY FILTER
• REQUEST WORK_ITEM PNP PM OPEN
• LOCKS RESET WMI NDIS_CO REFERENCE

20
NDIS Debug Tracing

• Enable through registry
• HKLM\SYSTEM\CurrentControlSet\Services\NDIS\Parame
  ters
• "DebugLevel"dword00000000
• "DebugSystems"dword000030F3
• "DebugBreakPoint"dword00000001
• Requires a reboot.
• Values of DebugSystems DebugLevel are
  documented in the DDK.

21
NDIS Extensions

• !miniports
• Miniport Driver Block 816f6190, Version 0.0
• Miniport 81645870 Direct Parallel
• Miniport Driver Block 8166f8b0, Version 4.5
• Miniport 8166caf0 3Com 3C920 Integrated Fast
  Ethernet Controller (3C905C-TX Compatible)
• Miniport Driver Block 81676b20, Version 2.0
• Miniport 81673878 3Com 10/100 PCI Server NIC
  w/3XP (3CR990SVR95)
• !miniport 81673878
• Dumps both NDIS, PNP and Power state of the device

22
NDIS Extensions (2)

• !protocols
• Protocol 815c3e90 TCPIP
• Open 81729be0 - Miniport 8162f670 3Com 3C920
  Integrated Fast Ethernet Controller
• Protocol 81712210 NDPROXY
• Open 81605008 - Miniport 81645870 Direct
  Parallel
• Protocol 8171ddb8 NDISWAN
• Open 81721150 - Miniport 81645870 Direct
  Parallel
• Open 81605110 - Miniport 81582138 WAN
  Miniport (PPTP)
• !protocol 815c3e90
• !mopen 81721150

23
NDIS Extensions (3)
24
Video Miniport Debugging

• Requires checked build system or checked build
  video port miniport drivers
• Doesnt have debugger extension
• Enable debug tracing by setting the global
  variable(s)
• Variable names are different between Win2K and XP

25
Video Miniport (2)

• On Windows 2000, you can enable debug tracing
  either through registry or debugger
• Set the value of VideoDebugLevel (0-3) in the
  registry
• HKLM\SYSTEM\CCS\Services\DriverName\DeviceN
• VideoDebugLevelREG_DWORD 2
• ed videoprt!VideoDebugLevel 3

26
Video Miniport (3)

• Video port on XP uses new DbgPrintEx function
• Following variables are defined for video drivers
• Kd_IHVVIDEO_Mask
• Kd_VIDEO_Mask
• Kd_VIDEOPRT_Mask
• HKLM\SYSTEM\CCS\Control\Session Manager\Debug Prin
  t Filter
• IHVVIDEODWORD 0xffffffff

27
Storage Driver Debugging

• On Win2K

• On XP, set values of
• NT!Kd_ScsiPort_Mask
• NT!Kd_ScsiMiniport_Mask

28
SCSI Driver

• To list device objects created for all SCSI
  controllers and devices
• !object \device\scsi
• Object 8186f410 Type (818cbba0) Directory
• ObjectHeader 8186f3f8
• HandleCount 0 PointerCount 4
• Directory Object 8189d550 Name Scsi
• HashBucket 15 81200a50 Device
  'aic78xx1Port2Path0Target3Lun0'
• HashBucket 22 8186e030 Device 'aic78xx1'

29
SCSI Driver

• !devobj 81200a50
• Device object (81200a50) is for
• aic78xx1Port2Path0Target3Lun0 \Driver\aic78xx
  DriverObject 81893cb0
• Current Irp 00000000 RefCount 0 Type 00000007
  Flags 00001050
• DevExt 81200b08 DevObjExt 81200fc8 Dope 81247728
  DevNode 8120cf28
• ExtensionFlags (0000000000)
• AttachedDevice (Upper) 81247030 \Driver\Disk
• DeviceQueue 811c7308 811e9e68 811e9848 811e9508
  811e91c8 811c6e68 811c6b28

30
SCSI Driver

• !irp 811c7308
• Irp is active with 5 stacks 3 is current (
  0x811c73c0)
• Mdl 811f4d48 Thread 811ef020 Irp stack
  trace.
• cmd flg cl Device File
  Completion-Context
• 0, 0 0 0 00000000 00000000
  00000000-00000000
• Args 00000000 00000000 00000000 00000000
• 0, 0 0 0 00000000 00000000
  00000000-00000000
• Args 00000000 00000000 00000000 00000000
• gt f, 0 0 e1 81200a50 00000000
  ed051184-811c5928 Success Error Cancel pending
• \Driver\aic78xx CLASSPNP!ClassIoComplete
• Args 811c5928 00000000 00000000 00000000
• 3,34 2 e0 81247030 811bb1a8
  80522ed2-00000000 Success Error Cancel
• \Driver\Disk ntkrnlmp!PsLookupThreadByThre
  adId
• Args 00001000 00000000 00107000 00000004
• 3, 0 0 0 811fc020 811bb1a8
  00000000-00000000
• \FileSystem\RAW
• Args 00001000 00000000 00107000 00000000

31
SCSI Driver

• !srb 811c5928
• Srb 811c5928 is from pool
• SRB_FUNCTION_EXECUTE_SCSI Path 0, Tgt 3, Lun 0,
  Tag ff, SrbStat 0, ScsiStat 0
• OrgRequest 811c5868 SrbExtension 00000000 TimeOut
  0000000a SrbFlags 00000342
• Queue Enable, No freeze, Cache Enable,
• 10 byte command with data transfer in 28 0 0
  0 8 38 0 0 8 0
• dt SCSI_REQUEST_BLOCK 0x811c5928

32
SCSI Driver

• !scsikd.scsiext 81200a50
• Q Depth 020 (255) InquiryData 0x81200C0E
• DeviceMap Keys Target 0x00019c Lun 0x000264
• Bypass SRB_DATA blocks 4 _at_ 0x81200c88 List
  0x81200e68
• RS Irp 0x81259d68 Srb _at_ 0x81200f28 MDL _at_
  0x81200f68
• Request list _at_0x81200BF8
• Tick count is 86376
• SrbData 0x811C7E68 Srb 0x811C7F28 Irp
  0x811DC008 lt1s
• SrbData 0x811C7B28 Srb 0x811C7BE8 Irp
  0x811E7008 lt1s
• ...
• !srbdata 0x811C7E68

33
1394 Debugging

• Windows 2000/XP 1394 stack

• ed ohci1394!ohcidebuglevel 6

34
USB Debugging

• Requires checked build system or checked build
  USB modules
• Enable debug tracing by setting the global
  variables
• One debugger extension (!urb ltaddressgt)
• Different between Win2K and XP

35
USB Debugging (2)

• Windows 2000 USB stack

• ed USBD!USBD_Debug_Trace_Level 2

36
USB Debugging (2)

• Windows XP USB stack

• All USB miniport drivers use USBPORT for debug
  output

37
PCI Debug Extensions

• !pci - Displays the current status of the PCI
  buses and any devices attached to them.
• !pcitree - Displays information on PCI device
  objects
• !devext ltaddessgt PCI
• ltaddressgt is the address of a device extension
  to
• be dumped.
• lttypegt is the type of the object owning this
  extension
• PCI if it is a PCI device extension
• ISAPNP if it is an ISAPNP device
  extension
• PCMCIA if it a PCMCIA device
  extension
• USBD OPENHCI UHCD if it is a USB Host
  Controller extension
• USBHUB if it is a USB Hub extension
• HID if it is a HID device extension

38
PCMCIA Debugging

• Set PCMCIA!PcmciaDebugMask (0x00000000
  0xFFFFFFFF)
• 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

39
Printer Driver Debugging (Usermode)

• 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 UI module or the
  rendering module
• Unidrv debugging "ed unidrv!giDebugLevel 1".
• Debugger extensions "!gdikdx.help" to view the
  gdikdx debugger extension.

40
Printer Driver (Kernelmode)

• Run gflags and enable Place Heap Allocation at
  end of pages on spoolsv.exe
• Restart spooler (net stop/start spooler)
• Run verifier.exe on Win32K.sys to debug your
  printer driver

41
Audio Driver Debugging

• For Windows2000/XP

42
HID Driver Debugging

• Debug trace from hidusb by setting
  hidusb.sys!HIDUSB_DebugLevel (0 or 1)
• Debug trace from hidclass by setting
  hidclass!dbgverbose (0 or 1)
• !devext lthid_device_extensiongt HID
• !hidppd ltaddressgt
• address - Specifies the hexadecimal address of
  the HIDP_PREPARSED_DATA structure

43
Serial Driver

• Serial Set the DebugLevel in the registry
  HKLM\System\CCS\Services\Serial
• DebugLevel REG_DWORD0xFFFFFFFF
• Or
• ed Serial!SerialDebugLevel (0x00000000
  0xFFFFFFFF)
• Mask values are defined in DDKROOT\src\kernel\s
  erial\serial.h
• Serenum Set the DebugLevel in the registry
  HKLM\System\CCS\Services\Serenum
• DebugLevel REG_DWORD1FF
• Mask values are defined in DDKROOT\src\kernel\s
  erenum\serenum.h

44
Device Installation Debugging

• Enable SetupAPI logging through registry
• HKLM\Software\Microsoft\Windows\CurrentVersion\Set
  up
• LogLevel REG_DWORD0x8000FF00
• LogLevel flag is made up of three parts
  0xSSSSDDGG (documented in the DDK)
• GG general options
• DD Device installation
• SSSS Special flags

45
Device Installation (2)

• You can send trace to the debugger as well as to
  a log file systemroot\setupapi.log
• Works on Free and Checked system.
• Doesnt require reboot.
• To get verbose trace from kernel usermode pnp
  manager, set nt!Kd_NTOSPNP_Mask and
  nt!Kd_PNPMGR_Mask to 0xFFFFFFFF

46
Discussion

• Q A