VisualDDK Quick Start Guide
Note: for a defailed complete beginner's walkthrough on creating and debugging drivers using VisualDDK, follow this link.
This guide provides step-by-step instructions from installing and configuring VisualDDK to building and debugging your first driver. You can feel free exploring VisualDDK functionality on your own, however, this short guide shows how to quickly access the most useful features. Here we go:
Ensure that you have installed Visual Studio 2005/2008, latest version of Debugging Tools For Windows x86 (tested with WinDDK 6000 and 7600), and DDK or WDK. Note than even on x64 host machines you need to install 32-bit version of Debugging Tools, as VisualStudio itself is 32-bit and requires 32-bit DLLs.
Install VisualDDK to your machine by running the provided Installer.
In the configuration wizard select paths to Windows DDK, WDK, or both. Note that you need to have admin privilege, so installer can update the %DDKPATH% and %WDKPATH% environment variables. Otherwise, Visual Studio will not be able to locate your WDK and DDK files:
Note that all projects created by VisualDDK will use %DDKPATH% or %WDKPATH%
to reference DDK files instead of absolute disk path, allowing you to build
them on any machine with VisualDDK installed.
In the last page of configuration wizard, select all versions of Visual Studio, that you want to integrate with. It is recommended to check the "register debug version of DDKDebugger.DLL" flag, so in case of any bugs, it will be easier to detect them and to produce a bug report. Please note that the bottleneck for kernel debugging is debugger-to-kernel connection. That way, using debug build instead of release one will not slow down your debugging.
Let the configuration wizard register all components with Visual Studio. If any errors occur, please submit a bug report on SysProgs.org forum.
Install the VirtualKD DLL and VisualDDK launch monitor on your virtual machine by copying target\vminstall.exe file from VisualDDK directory to the virtual machine and running it. Note that it will automatically detect whether the VM is 32- or 64-bit and install corresponding binaries. If you are using real machines for debugging, just copy DDKLaunchMonitor.exe to the machine and ensure that it is running.
If you are planning to use VirtualBox for debugging your drivers, install the patched VBoxDD.DLL file:
- Rename the VBoxDD.dll file in your VirtualBox folder to VBoxDD0.dll.
- Copy modified VBoxDD.dll from VisualDDK\VirtualBox to VirtualBox directory.
- Ensure that you have selected correct version (x86 or x64) of VBoxDD.dll
More information about VM-related issues can be read here.
You can now quickly test kernel debugging by opening any solution in Visual Studio, selecting Debug->Attach to Process and choosing "Kernel-Mode connections" under "Transport":
You can use the following "Qualifier strings":
- raw://windbg_connection_params (example: raw://com:modem)
- vm://vm_name (requires VirtualKD) [works for both VMWare and VirtualBox]
This will allow you to attach to a running kernel and debug it directly from Visual Studio. However, this is only the tip of the iceberg. VisualDDK supports much more convenient way of developing and debugging drivers:
Start Visual Studio, select File->New->Project, choose VisualDDK. Finally, select VisualDDK Driver Wizard.
While you can also import existing sources into a VisualDDK driver project, it is recommended to create a simple driver for the first time:
You can either create a legacy driver (you'll need to create a service on a remote machine manually, or via a generated .reg file), or a WDM driver (and install it from Add Hardware Wizard). As using .reg file requires reboot, it is recommended to create a simple WDM driver.
Ensure that DDKLaunchMonitor.exe is running on the target machine. Ensure that the firewall allows opening TCP and UDP ports:
This screenshot shows DDKLaunchMonitor output after a driver was copied and launched.
Choose Debug->Driver Launch Settings:
In the "VisualDDK Project Launcher" dialog, select the debug connection type, target machine IP address (to copy driver there via DDKLaunchMonitor), and the way to start and stop your driver:
Click the Launch button an observe VisualDDK connecting and launching your driver. As you are running your driver for the first time, VisualDDK will offer to automatically install the driver on the target machine. Install the driver (do not forget to acknwledge unsigned driver installation on the target).
If you have set up breakpoints before, one of them will be activated now. However, if not, you can set them while running (target execution will be automatically stopped until you resume it). You can also use the "Break All" command in Visual Studio.
VisualDDK will terminate the debugging session automatically, when it detects your driver unloaded (unless you disabled it in Launcher configuration). However, you can stop the session at any time by using the "Stop Debugging" command. In that case, VisualDDK Launcher will try to unload your driver using the command you provided:
Note that if you have set any breakpoints on driver unloading, they will be skipped if you unload your driver that way.
Setup keyboard shortcuts for VisualDDK actions and enjoy