Making your first driver - complete walkthrough

This article describes how to create, build and debug your first driver using Visual Studio and VisualDDK. It provides detailed step-by-step instructions on using the development and debugging tools, leaving the driver API and architecture description behind. If you want to learn more about the API used to develop drivers, consider exploring online WDK help.

In this walkthrough we will create two drivers and test them using a virtual machine:

  • A dummy driver that simply prints a message when it is loaded

  • A ramdisk driver, that creates a virtual hard disk

If you prefer to use a second physical machine instead, skip the VM-related stuff. However, you will need either a direct COM, or a direct IEEE1394 (FireWire) connection between the machines.

Before you begin

Before you start making your driver, ensure that you have the required software. You can get the required Microsoft products for free if you are qualified for MSDNAA, DreamSpark or BizSpark. All third-party tools referenced here are free. So, prepare to download:

  • A virtual machine application (VirtualBox is free and recommended, VMWare is another alternative, any other VM application will also work, but will be slow due to lack of VirtualKD support).

  • A Windows installation disc or a disc image to install it on the VM.

  • Visual Studio (2005, 2008 or 2010). The Express edition won't work.

  • Windows Driver Kit (ask google for the latest version, or download version 7.1.0).

  • A 32-bit version of Debugging Tools for Windows. They are normally located in the Debuggers directory of the WDK ISO. Note that if you are using a 64-bit Windows version, you will need to install the 32-bit Debugging Tools manually by running V:\Debuggers\setup_x86.exe. Visual Studio is a 32-bit process and won't work with the 64-bit Debug Tools.

  • Latest version of VisualDDK.

If you don't have a tool to mount the downloaded ISO images, consider WinCDEmu.

Preparing

The first thing you need to do is to install the virtual machine application. This walkthrough refers to VirtualBox, however, if you prefer to use any other VM, the steps will be similar. Then, create a new virtual machine. It is recommended to select the PIX chipset instead of the ICH9 one when setting the VM properties. Once the VM is created, you will need to install Windows on it. This walkthrough uses Windows 7, however, any other modern version will do. After Windows Setup completes, ensure that the virtual machine can access the physical machine via the network: it is recommended to set the network adapter settings in the VM to NAT. If you encounter connection problems later, check your firewall settings.

Once Windows is installed on the VM install VMWare Tools/VirtualBox additions  (in VirtualBox, just select "Devices->Install guest additions"). It is also recommended to setup a virtual shared folder (VM Settings->Shared folders), or use a network share to be able to copy files between the physical machine and the VM.  Finally, create a snapshot called "clean Windows installation" (it won't consume any additional disk space, but will be useful if anything goes wrong) and switch the VM off.

Now install Visual Studio on the physical machine. Note that you will need support for C++ (enable 64-bit support if you plan to build 64-bit drivers) and C# (required for certain VisualDDK components). Then install Windows Driver kit and Debugging Tools on the physical machine.

Finally install VisualDDK. Note that if you install VisualDDK before installing Visual Studio, it won't be integrated correctly and you will have to re-run VisualDDK installer. If you are using VirtualBox or VMWare, you will need to do some additional steps:

  • If you are using VirtualBox, go to the VirtualBox install directory, rename VBoxDD.DLL into VBoxDD0.DLL and copy C:\Program Files (x86)\VisualDDK\VirtualBox\{x86/x64}\VBoxDD.dll in the VirtualBox directory. This will enable VirtualKD - a plugin that increases VMWare/VirtualBox debugging speed and usability.

  • It is recommended to turn of UAC on the virtual machine. Otherwise, VisualDDK monitor won't be able to start automatically every time you start your virtual machine.

  • Copy C:\Program Files (x86)\VisualDDK\target\vminstall.exe to your virtual machine and run it there. Do not run vminstall.exe on the physical machine! You can use either VM shared folders, or a network drive to copy the file to VM. Once vminstall is done, it will ask for a reboot. As you are going to create the driver project first, it is recommended that you shut down the VM instead.

    Hint: if you have set up a VirtualBox shared folder (e.g. called SHARE), it will be accessible as a network folder \\VBOXSVR\SHARE:

    screenshot vminstall

Creating the first driver

  1. Start Visual Studio from in administrator mode (right click-> run as administrator), select "File->New->Project", then select "Visual C++ -> VisualDDK->VisualDDK driver wizard".

  2. Select the directory and project name (e.g. Driver1). Press OK.

  3. In the Driver Wizard dialog box do the following:

    • Select "A sample legacy driver" as the driver template.

    • Select "Use Visual Studio project system". This is the easiest way to start developing, but it is not officially supported by Microsoft.

    • It is recommended that you enable the "Generate CPP files" checkbox. You can write C-style code using C++ compiler, however you will have better debugging experience due to features like built-in wchar_t type.

    screenshot create driver project

  4. Press OK so that the project is created

  5. Now you can build the driver using "Build->Build solution" command (or just press Ctrl+Shift+B). If the build fails due to missing include files, ensure that the DDKPATH/WDKPATH environment variable is set and that Visual Studio has been restarted since then.

  6. Now let's add some custom code to our driver. In this example, let's just print a message when the driver loads and unloads. Add the following line before the return statement of the DriverEntry() function:

    7. DbgPrint("Hello, world!\n");

  7. Add the following line in the beginning ofthe Driver1Unload() function:

    DbgPrint("Goodbye, world!\n");

    Your code should look the following way now:

    screenshot hello code

  8. Rebuild the driver by selecting "Build->Build solution". Note that if you want to use a 64-bit target OS, you need to select x64 instead of Win32 as the current build platform.

  9. Now let's debug the driver using VisualDDK. Start your virtual machine. When the OS selection menu appears, select the VirtualKD entry and press ENTER:

    screenshot vm start

  10. Switch back to Visual Studio and select "Debug->Start debugging driver". A debugging settings dialog will appear:

    screenshot debug settings

  11. Ensure that "debugging connection" is set to "Virtual machine" and your currently running VM is selected. It it is not in the list, press "refresh". Ensure that the "starting driver" and "stopping driver" settings are set to "legacy driver" and the correct driver name is entered. When done, press "launch".

  12. If you are debugging a driver for the first time, a settings dialog will appear:

    screenshot settings

    Ensure that the debugging tools location is set correctly (remember, you need a 32-bit version even on a 64-bit machine!) and that the downloaded symbol path points to a valid directory. If you did not debug any drivers before, create a new empty directory (e.g. C:\SYMBOLS.NET) and select it as the directory for downloaded symbols.

    Hint: you can significantly speed up symbol loading by going to the Symbol Policy tab and selecting "Load symbols for NT kernel and drivers from current solution only".

  13. When you're done, press OK. A connection progress dialog will appear:

    14. screenshot connecting

  14. As we have just started our VM, the Win32 subsystem is not yet running and the driver will not be loaded automatically. VisualDDK will detect it, display a message in debug console and stop the target OS execution:

    15. screenshot first breakpoint

  15. If you are familiar with WinDbg, the current debugging state is equivalent to WinDbg just after connecting to a kernel-mode target. You can enter any WinDbg commands in VisualDDK console, or use the corresponding functions of Visual Studio.

  16. To let VisualDDK load our driver we need to let the OS boot completely. To do that, simply press F5 or select Debug->Continue in Visual Studio menu. Note that the OS may take some time to load.

  17. When the operating system has loaded, ensure that VisualDDK monitor has been started on the Virtual Machine. If not, start it manually (default location is c:\DDKLaunchMonitor.exe). If Windows Firewall shows an "access blocked" popup, you need to select both private and public networks and press "allow access":

    screenshot windows firewall

  18. Once VisualDDK monitor has started, ensure that it has detected the virtual machine IP address(es) correctly:

    screenshot launch monitor

  19. Now switch back to Visual Studio, click at the "driver1.sys unloaded" text in VisualDDK console, and select "load driver". If you cannot find the corresponding button, you can also press shift+F5 to stop debugging and then hit F5 to start another debugging session. Note that it won't restart your target OS, but will unload your driver if it was loaded.

  20. If you are loading this driver for the first time, VisualDDK will show a driver installation prompt:

    screenshot driver installation

  21. Ensure that the parameters are set correctly and press "install". Once the installation is complete, the driver will be loaded. Check VisualDDK console window for the "Hello, world" message:

    screenshot hello world

  22. Now let's unload the driver. Click at "Driver1.sys loaded" message and select "unload driver":

    screenshot unload

    Hint: you can also press Shift+F5 to stop debugging and unload the driver. However, if you want to debug some code that only gets called during unload, using the "unload driver" command is the only way to do.

  23. Let's test some simple interactive debugging functionality. Put a breakpoint on the line containing the IoCreateDevice() call and start your driver again by selecting "Debug->Start debugging driver". Once the breakpoint is hit, open the "watch 1" window and add "DriverObject" to watch list. Note that all other debugging techniques common to Visual Studio (e.g. hovering mouse over a variable to view its value) will work:

    screenshot debug

  24. When you're done checking out the debugging functions, unload the driver again.

  25. Important advice: Now once the OS is booted, VisualDDK monitor is running and no custom drivers are loaded, it is a good time to create another Virtual Machine snapshot. When you want to debug a driver later, you will simply need to restore the snapshot and press "start debugging driver". VisualDDK will do the rest. You won't have to wait until the OS starts or start anything manually. However, please note that shutting down the VM while Visual Studio is running could hang the latter. To do it safely, always use the "Settings->Disconnect from target" command in VisualDDK console.

Creating a sample ramdisk driver

VisualDDK driver wizard allows creating driver projects based on BazisLib, an object-oriented library for simplified driver design. One of sample projects provided by BazisLib is the ramdisk driver. The following walkthrough will show how to create a project based on it.

  1. Start Visual Studio from in administrator mode (right click-> run as administrator), select "File->New->Project", then select "Visual C++ -> VisualDDK->VisualDDK driver wizard".

  2. If you have not installed BazisLib, click at the "Install BazisLib" button to do it automatically.

  3. Select "A bus-based RAMDISK driver (BazisLib)" from the driver template list:

    screenshot ramdisk

  4. Build the project by pressing Ctrl+Shift+B.

  5. This sample project creates 2 RAM disks:

    • The first one has a size of 16MB and contains a precomputed MBR describing 1 partition. This disk will immediately receive a drive letter when Windows recognizes it.

    • The second one is 32MB large and has no precomputed MBR. Thus, you will need to create a partition manually using Disk Management snap-in in Computer Management.

    Fore more details, look into the OnStartDevice() method in RamDiskBus.cpp.

  6. Start your driver by selecting "Debug->Start debugging driver". Select default launching options.

  7. When a driver installation prompt appears, press "install driver". Go to your VM and confirm the installation of an unsigned driver.

  8. If everything went right, switch to your VM, right-click at the "computer" item in Start Menu, select "Manage" and go to Disk Management. You will see the 2 virtual disks:

    screenshot disk manager

  9. Now go to device manager (press Win+Break and select "device manager"). Select "View->Devices by connection" and ensure that the virtual disks are present:

    screenshot device manager

  10. Now let's do some debugging. Open ramdisk.cpp and put a breakpoint on RamDisk::Read() method. Switch to VM and open the newly created disk in Explorer. The breakpoint wil hit:

    screenshot debug 2

  11. Check out the call stack to see how BazisLib automatically routed the request from the OS to the worker thread, decoded it and invoked a simple Read() method. If you want to implement your own virtual disk driver, consider making your own implementation of the BazisLib::AIBasicDisk interface and reusing BazisLib code to handle all OS-related issues. BazisLib is available under LGPL.