Driver testing

Generic information on how to test and debug Windows drivers. Please see TailLight testing for specific instructions for the drivers in this repo.

Prerequisites

• Install Visual Studio.
• Install Windows Driver Kit (WDK).
• Download or build the drivers, so that you have the driver INF/SYS and other files available.

Drivers should be tested on a separate computer, since malfunctioning drivers might crash the system. Driver debugging furthermore require running the debugger on a separate computer, since breaking execution will freeze the tested computer. It's often convenient to use a virtual machine (VM) as test computer.

Target computer configuration

Steps to enable driver loading:

• Disable Secure Boot in UEFI/BIOS.
• Enable test-signed drivers: bcdedit /set testsigning on

Steps to enable driver debugging (optional)

• Enable kernel debugging: bcdedit /debug on
• Debugging alternatives:
  1. Either: Configure kernel debugging with VirtualBox
  2. Or: Configure kernel debugging with Hyper-V
  3. Or: Configuration of KDNET network kernel debugging with a network cable if you have a supported NIC.
  4. Or: Configuration of kernel-mode debugging over a USB 3.0 cable with a USB 3 A/A crossover cable:
     • bcdedit /dbgsettings usb targetname:KernelUSBConn
     • From the host computer, connect with the WinDbg over USB to the KernelUSBConn target.
  5. Or: Local kernel debugging with WinDbg
     • Use lkd> !dbgprint command to print the debug buffer content.
• Restart the target computer.
• Reconnect to the target computer using WinDbg.

Enable driver debug logging

Either, break WinDBG execution and send the following command to enable display of DPFLTR_IHVDRIVER_ID debug messages: kd>

ed nt!Kd_IHVDRIVER_Mask 0xffffffff

Or, merge the following IHVDRIVER-debugging.reg file on the target machine:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Debug Print Filter]
"IHVDRIVER"=dword:ffffffff

Display of KdPrint(()) and DPFLTR_DEFAULT_ID debug messages can similarly be enabled with: kd>

ed nt!Kd_DEFAULT_Mask 0xff

Driver Verifier (optional)

Driver verifier is an in-built Widows feature that monitors kernel-mode drivers to detect illegal function calls or actions that might corrupt the system. It can be enabled with the following commands:

1. Run verifier.exe from an admin command-prompt.
2. Select "Create standard settings".
3. Select "Select driver names from a list".
4. Select the desired driver SYS and click "Finish".
5. Reboot to make the changes take effect.

Driver (un)installation

The PnPUtil tool included in Windows can be used for manually installing and uninstalling drivers. Test-signed drivers furthermore require the signing certificate to be added to the "root" and "trustedpublisher" certificate stores in order to load.

The drivers in this repo contain batch scripts to simplify driver installation:

• Run INSTALL_*.bat from an admin command-prompt to install the driver with associated certificate.
• Run UNINSTALL_*.bat from an admin command-prompt to uninstall the driver.

It's also possible to install and uninstall drivers manually from "Device Manager".

Installed drivers can be viewed with msinfo32.exe:

Driver debugging

Open WinDBG and add the folder with the driver PDB symbols:

Connect to the kernel and select "break on connection" to make the debugger break when the driver is loaded:

This will enable early placement of breakpoints.

Then, open driver source file(s) and right click to insert breakpoints:

Kernel object inspection

Inspect device object based on PDO or FDO address:

kd> !devstack  0xFFFFBB8DA03B4060
  !DevObj           !DrvObj            !DevExt           ObjectName
  ffffbb8d9eec38d0  \Driver\TailLight  ffffbb8d9e89e5b0  
> ffffbb8da03b4060  \Driver\HidUsb     ffffbb8da03b41b0  00000034
!DevNode ffffbb8da0371c80 :
  DeviceInst is "HID\VID_2341&PID_8037&MI_02\7&12501c9d&0&0000"
  ServiceName is "TailLight"

 kd> !devobj ffffbb8d9eec38d0
Device object (ffffbb8d9eec38d0) is for:
  \Driver\TailLight DriverObject ffffbb8d9f1dde30
Current Irp 00000000 RefCount 0 Type 00000022 Flags 00002004
SecurityDescriptor ffff818f809d72e0 DevExt ffffbb8d9e89e5b0 DevObjExt ffffbb8d9eec3a48 
ExtensionFlags (0000000000)  
Characteristics (0x00000100)  FILE_DEVICE_SECURE_OPEN
AttachedTo (Lower) ffffbb8da03b4060 \Driver\HidUsb
Device queue is not busy.

Display information about a WDF IO target (FDO or PDO):

kd> !wdfiotarget 0x000044725fc0bd38
Treating handle as a KMDF handle!

WDFIOTARGET 000044725fc0bd38
=========================
!wdfdevice 0x0000447261437ca8
Target Device: !devobj  0xffffbb8da02bba50
Target PDO: !devobj  0xffffbb8da07a14b0

Type: Remote target
State:  WdfIoTargetStarted

Requests pending: 0

Requests sent: 0

Requests sent with ignore-target-state: 0


Target name:  \Device\00000038
Target FileObject: dt nt!_FILE_OBJECT  0xffffbb8da2002340
WDF file !handle  0xffffffff80001cc8. Search for 'Object: xxxx Type: File', run '!fileobj xxxx'
Open type:  WdfIoTargetOpenByName

Leak detection

Connect WinDBG to the kernel, "Break" execution and run !poolused 4 <TAG> to list all memory allocations for the driver with pool tag <TAG> (example: !poolused 4 TaLi).