Making Your first driver-complete walkthrough (using VISUALDDK)

This article describes what 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 AR Chitecture description behind. If you want to learn more about the API used to develop drivers, consider exploring online WDK help.

In this walkthrough we'll create the drivers and test them using a virtual machine:

• A dummy driver that simply prints a message when it's 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'll need either a direct COM, or a direct IEEE1394 (FireWire) connection between the machines.

Before you begin

before you start making your driver, ensure so you have the required software. You can get the required Microsoft products for free if you are qualified For msdnaa, dreamspark or bi Zspark. All Third-party tools referenced here is free. So, prepare to download:

• A virtual machine application (Virtualbox is free and recommended, vmware is another Alternat Ive, any other VM application'll also work, but would 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, 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 is normally located in the debuggers directory of the WDK ISO. Note that if you is using a 64-bit Windows version, you'll 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 has a tool to mount the downloaded ISO images, consider WinCDEmu.

Preparing

The first thing you need to the install the virtual machine application. This is walkthrough refers to VirtualBox, however, and if you prefer to use any other VM, the steps would 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 a created, you'll need to install Windows on it. This walkthrough uses Windows 7, however, any other modern version would do. After Windows Setup completes, ensure this virtual machine can access the physical machine via the network:it is Reco Mmended to set the network adapter settings on 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 (VirtualBox, just select "Devices->in Stall guest Additions "). It is also recommended to setup a virtual shared folder (VM settings->shared folders), or use a network share to be ABL  E 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 would be us Eful if anything goes wrong) and switch the VM off.

Now install Visual Studio in the physical machine. Note that you'll need support for C + + (Enable 64-bit support if your plan to build 64-bit drivers) and C # (required for C Ertain VISUALDDK components). Then install Windows Driver kits and debugging Tools on the physical machine.

Finally install VISUALDDK. Note that if you install VISUALDDK before installing Visual Studio, it won ' t is integrated correctly and you'll have the to Re-run VISUALDDK installer. If you is using VirtualBox or VMWare, you'll need to do some additional steps:

• If you is using VirtualBox, go to the VirtualBox install directory, rename VBoxDD.DLL into VBoxDD0.DLL and copyC:\Pro Gram Files (x86) \visualddk\virtualbox\{x86/x64}\vboxdd.dll in the VirtualBox directory. This would enablevirtualkd-a plugin that increases Vmware/virtualbox debugging speed and usability.

• It is recommended to turn of UAC in the virtual machine. Otherwise, VISUALDDK Monitor won ' is able to the 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 Gkfx folders, or a network drive to copy the file to VM. Once Vminstall is done, it'll ask for a reboot. As you were going to create the driver project first, it's recommended that's shut down the VM instead.

  Hint:if You has set up a VirtualBox shared folder (e.g. called SHARE), it'll be accessible as a network folder\\VBOXSVR\SHARE:

Creating the first driver

2. Start Visual Studio from in Administrator mode (right click-> run as Administrator), select "File->new->project", Then select "Visual C + +, VISUALDDK->VISUALDDK Driver Wizard".

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

6. 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-to-start developing, but it's not officially supported by Microsoft.

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

8. Press OK So, the project is created

10. 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 the DDKPATH/WDKPATH environment variable are set and that Visu Al Studio had been restarted since then.

12. 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:

Dbgprint ("Hello, world!\n");

2. Add the following line in the beginning ofthe driver1unload () function:

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

   Your code should look the following to now:

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

6. 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:

8. Switch back to Visual Studio and select "Debug->start Debugging Driver". A Debugging Settings dialog would appear:

10. Ensure that "debugging connection" are set to "Virtual machines" and your currently running VM is selected. It is not the list, press "Refresh". Ensure that the "starting driver" and "stopping driver" settings was set to "legacy driver" and the correct driver name is Entered. When done, press "launch".

12. If You is debugging a driver for the first time, a settings dialog would appear:

    Ensure that the debugging tools are set correctly (Remember, you need a 32-bit version even on a 64-bit machin e!) And that the downloaded symbol path points to a valid directory. If You do 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 k Ernel and drivers from current solution only ".

14. When you ' re done, press OK. A Connection Progress Dialog would appear:

1. As we have just started our VMS, the WIN32 subsystem is not yet running and the driver would not be loaded automatically. VISUALDDK would detect it, display a message in debug console and stop the target OS execution:

2. If you were familiar with WINDBG, the current debugging state was equivalent to WINDBG just after connecting to a Kernel-mod E Target. You can enter any WINDBG commands on VISUALDDK console, or use the corresponding functions of Visual Studio.

4. To let VISUALDDK load our driver we need to let the OS boot completely. To does, simply press F5 or select Debug->continue in Visual Studio menu. Note that the OS could take some time to load.

6. When the operating system had loaded, ensure that VISUALDDK Monitor had been started on the Virtual machine. If not, the 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 ":

8. Once VISUALDDK Monitor has started, ensure that it had detected the virtual machine IP address (es) correctly:

10. Now switch back to Visual Studio, click on 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 hits F5 to start Anoth ER debugging session. Note that it won ' t restart your the target OS, but would unload your driver if it was loaded.

12. If You is loading this driver for the first time, visualddk'll show a driver installation prompt:

14. Ensure that the parameters is set correctly and press "install". Once the installation is complete, the driver would be loaded. Check VISUALDDK Console window for the ' Hello, World ' message:

16. Now let ' s unload the driver. Click at "Driver1.sys Loaded" message and select "Unload Driver":

    Hint:you can also press SHIFT+F5 to stop debugging and unload the driver. However, if you want to debug some code this only gets called during unload, using the "Unload Driver" command was the only Do.

18. 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->star T debugging Driver ". Once The breakpoint is hits, 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) W Ill work:

20. When you do checking out the debugging functions, unload the driver again.

22. Important advice: Now once the OS was booted, VISUALDDK Monitor is running and no custom drivers are loaded, it's a good time to create Anot Her Virtual machine snapshot. When you want-to-debug a driver later, you'll simply need to restore the snapshot and press "Start Debugging Driver". VisualDDK'll do the rest. You won ' t has to wait until the OS starts or start anything manually. However, please note this shutting down the VM while Visual Studio was running could hang the latter. To does 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, a object-oriented library for simplified Drive R design. One of the sample projects provided by Bazislib is the RAMDisk driver. The following walkthrough would show how to create a project based on it.

2. Start Visual Studio from in Administrator mode (right click-> run as Administrator), select "File->new->project", Then select "Visual C + +, VISUALDDK->VISUALDDK Driver Wizard".

4. If you had not installed Bazislib, click on the "Install bazislib" button to do it automatically.

6. Select "A bus-based RAMDISK Driver (bazislib)" From the Driver Template list:

8. Build the project by pressing Ctrl+shift+b.

10. 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 would immediately receive a drive letter when Windows recognizes it.

    • The second one is 32MB large and have no precomputed MBR. Thus, you'll need to the create a partition manually using Disk Management snap-in in computer Management.

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

12. Start your driver by selecting "Debug->start Debugging Driver". Select default launching Options.

14. When a driver installation prompt appears, press "Install driver". Go to your VMS and confirm the installation of an unsigned driver.

16. If everything went right, switch to your VMS, right-click at the ' computer ' item in Start Menu, select ' Manage ' and go to D ISK Management. You'll see the 2 virtual disks:

18. Now go to Device Manager (press Win+break and select "Device Manager"). Select "View->devices by Connection" and ensure, the virtual disks is present:

20. Now let's do some debugging. Open Ramdisk.cpp and put a breakpoint on Ramdisk::read () method. Switch to VMS and open the newly created disk in Explorer. The breakpoint wil hit:

22. Check out the "Call stack" to "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::aibasi Cdisk interface and reusing bazislib code to handle all os-related issues. Bazislib is available under LGPL.

http://articles.sysprogs.org/visualddk/firstdriver/

Making Your first driver-complete walkthrough (using VISUALDDK)