4.2 DriverWizard Walkthrough

4.2 DriverWizard Walkthrough
	Chapter 4. Using DriverWizard

To use DriverWizard:

Attach your hardware to the computer:
Attach the card to the appropriate bus slot on your computer.
Alternatively, you have the option to use DriverWizard to generate code for a virtual PCI device, without having the actual device installed, by selecting the PCI Virtual Device DriverWizard option (see information in step 2). When selecting this option, DriverWizard will generate code for your virtual PCI device.

Run DriverWizard and select your device:

Start DriverWizard – <path to WinDriver>/wizard/wdwizard or /Applications/wdwizard.app on Mac OS X. On Windows you can also run DriverWizard from the Start menu: Start | Programs | WinDriver | DriverWizard.
On Windows 7 and Vista you must run DriverWizard as administrator.
Click New host driver project to start a new project, or Open an existing project to open a saved session.
Figure 4.1 Create or Open a WinDriver Project

Select your Plug-and-Play card from the list of devices detected by DriverWizard.

Figure 4.2 Select Your Plug-and-Play Device

For non-Plug-and-Play cards, select ISA.
To generate code for a PCI device that is not currently attached to the computer, select PCI Virtual Device.

When selecting the PCI Virtual Device option, DriverWizard allows you to define the device's resources. By specifying the I/O and/or Memory ranges, you may further define run-time registers (the offsets are relative to BARs). In addition, the IRQ must be specified if you want to generate code that acknowledges interrupts via run-time registers. Note, that the IRQ number and the size of the I/O and Memory ranges are irrelevant, since these will be automatically detected by DriverWizard when you install a physical device.

Generate an INF file for DriverWizard:
On Windows 7/Vista/Server 2008/Server 2003/XP/2000, the driver for Plug-and-Play devices (such as PCI and PCMCIA) is installed by installing an INF file for the device. DriverWizard enables you to generate an INF file that registers your device to work with WinDriver (i.e., with the windrvr6.sys driver). The INF file generated by DriverWizard should later be distributed to your customers who are using Windows 7 / Vista / Server 2008 / Server 2003 / XP / 2000, and installed on their PCs.

The INF file that you generate in this step is also designed to enable DriverWizard to diagnose your device on Windows 7 / Vista / Server 2008 / Server 2003 / XP / 2000 (for example, when no driver is installed for your PCI/PCMCIA device). Additional information concerning the need for an INF file is provided in section 15.1.1.

If you do not need to generate an INF file (e.g., if you are using DriverWizard on Linux), skip this step and proceed to the next one.

To generate the INF file with DriverWizard, follow the steps below:

In the Select Your Device screen, click the Generate .INF file button or click Next .
DriverWizard will display information detected for your device – Vendor ID, Device ID, Device Class, manufacturer name and device name – and allow you to modify this information, as demonstrated in Figure 4.3 below.

When you are done, click Next and choose the directory in which you wish to store the generated INF file. DriverWizard will then automatically generate the INF file for you.

You can choose to automatically install the INF file by checking the Automatically Install the INF file option in the DriverWizard's INF generation dialogue.
If the automatic INF file installation fails, DriverWizard will notify you and provide manual installation instructions (refer also the manual INF file installation instructions in section 15.1).

Figure 4.3 DriverWizard INF File Information

Handling of PCI Message-Signaled Interrupts (MSI) and Extended Message-Signaled Interrupts (MSI-X) requires specific configuration in the device's INF file, as explained in section 9.2.6.1 of the manual.
On Windows Vista and higher, if your hardware supports MSI or MSI-X, the Support Message Signaled Interrupts option in the DriverWizard's INF generation dialogue will be enabled and checked by default. When this option is checked, the generated DriverWizard INF file for your device will include support for MSI/MSI-X handling. However, when this option is not checked, PCI interrupts will be handled using the legacy level-sensitive interrupts method, regardless of whether the hardware and OS support MSI/MSI-X.

When the INF file installation completes, select and open your device from the list in the Select Your Device screen.

Uninstall the INF file of your device:
You can use the Uninstall option to uninstall the INF file of your Plug-and-Play device (PCI/PCMCIA). Once you uninstall the INF file, the device will no longer be registered to work with the windrvr6.sys, and the INF file will be deleted from the Windows root directory.
If you do not need to uninstall an INF file, skip this step and proceed to the next one.
1. In the Select Your Device screen, click the Uninstall .INF file button.
2. Select the INF file to be removed.

Diagnose your device:
Before writing your device driver, it is important to make sure your hardware is working as expected. Use DriverWizard to diagnose your hardware. All of your activity will be logged in the DriverWizard log so that you may later analyze your tests:

Define and test your device's I/O and memory ranges, registers and interrupts:

DriverWizard will automatically detect your Plug-and-Play hardware resources: I/O ranges, memory ranges, and interrupts.

Figure 4.4 PCI Resources

For non-Plug-and-Play hardware, define your hardware's resources manually.

You can also manually define hardware registers, as demonstrated in Figure 4.5 below.

Figure 4.5 Define Registers


	When defining registers, you may check the Auto Read box in the Register Information window. Registers marked as Auto Read will automatically be read for any register read/write operation performed from DriverWizard. The read results will be displayed in the wizard's Log window.

Read and write to the I/O ports, memory space and your defined registers, as demonstrated in Figure 4.6.


	When accessing memory mapped ranges, be aware that Linux PowerPC uses big-endian for handling memory storage, as opposed to the PCI bus that uses little-endian. For more information regarding little/big-endian issues, refer to section 9.3.

Figure 4.6 Read/Write Memory and I/O

'Listen' to your hardware's interrupts.

Figure 4.7 Listen to Interrupts

For level-sensitive interrupts, such as legacy PCI interrupts, you must use DriverWizard to define the interrupt status register and assign the read/write command(s) for acknowledging (clearing) the interrupt, before attempting to listen to the interrupts with the wizard, otherwise the OS may hang! Figure 4.8 below demonstrates how to define an interrupt acknowledgment command for a defined INTCSR hardware register. Note, however, that interrupt acknowledgment information is hardware-specific.

Figure 4.8 Define Transfer Commands for Level-Sensitive Interrupts

Generate the skeletal driver code:
1. Select to generate code either via the Generate Code toolbar icon or from the Project | Generate Code menu.
2. In the Select Code Generation Options dialogue box that will appear, choose the code language and development environment(s) for the generated code and select Next to generate the code.
  Figure 4.9 Code Generation Options
3. Click Next and indicate whether you wish to handle Plug-and-Play and power management events from within your driver code, and whether you wish to generate Kernel PlugIn code.
  To compile the generated Kernel PlugIn code, the Windows Driver Kit (WDK) must be installed.
4. Save your project (if required) and click OK to open your development environment with the generated driver.
Compile and run the generated code:
- Use this code as a starting point for your device driver. Modify where needed to perform your driver's specific functionality.
- The source code DriverWizard creates can be compiled with any 32-bit compiler, and will run on all supported platforms without modification.
For detailed compilation instructions, refer to section 4.2.4.

4.2.1 Logging WinDriver API Calls

You have the option to log all the WinDriver API calls using DriverWizard, with the API calls input and output parameters. You can select this option by selecting the Log API calls option from the Tools menu or by clicking on the Log API calls toolbar icon in DriverWizard's opening window.

4.2.2 DriverWizard Logger

The wizard logger is the empty window that opens along with the Device Resources dialogue box when you open a new project. The logger keeps track of all of the input and output during the diagnostics stage, so that you may analyze your device's physical performance at a later time. You can save the log for future reference. When saving the project, your log is saved as well. Each log is associated with one project.

4.2.3 Automatic Code Generation

After you have finished diagnosing your device and have ensured that it runs according to your specifications, you are ready to write your driver.

4.2.3.1 Generating the Code

Generate code by selecting this option either via DriverWizard's Generate Code toolbar icon or from the wizard's Project | Generate Code menu. DriverWizard will generate the source code for your driver, and place it along with the project file (xxx.wdp, where "xxx" is the project name). The files are saved in a directory DriverWizard creates for every development environment and operating system selected in the code generation dialogue box.

4.2.3.2 The Generated PCI/PCMCIA/ISA C Code

In the source code directory you now have a new xxx_lib.h file, which contains type definitions and functions declarations for the API created for you by the DriverWizard, and an xxx_lib.c source file, which contains the implementation of the generated device-specific API.
In addition, you will find an xxx_diag.c source file, which includes a main() function and implements a sample diagnostics application that utilizes the generated DriverWizard API to communicate with your device.

The code generated by DriverWizard is composed of the following elements and files, where xxx represents your DriverWizard project name:

Library functions for accessing each element of your card's resources (memory ranges and I/O, registers and interrupts):
- xxx_lib.c Here you can find the implementation of the hardware-specific API (declared in xxx_lib.h), using the WinDriver Card (WDC) API [B.2].
- xxx_lib.h Header file that contains type definitions and function declarations for the API implemented in the xxx_lib.c source file.
  You should include this file in your source code in order to use the API generated by DriverWizard for your device.
A diagnostics program that utilizes the generated DriverWizard API (declared in xxx_lib.h) to communicate with your device(s):
- xxx_diag.c The source code of the generated diagnostics console application.
  Use this diagnostics program as your skeletal device driver.
A list of all files created can be found at xxx_files.txt.

After creating your code, compile it with your favorite compiler, and see it work!

Change the function main() of the program so that the functionality suits your needs.

4.2.3.3 The Generated Visual Basic and Delphi Code

The generated DriverWizard Visual Basic and Delphi code includes similar functions and provides similar functionality as the generated C code described in section 4.2.3.2.

The generated Delphi code implements a console application (like the C code), while the Visual Basic code implements a GUI application.

4.2.3.4 The Generated C# Code

The generated DriverWizard C# code provides similar functionality as the generated C code [4.2.3.2], but from a GUI .NET program.

4.2.4 Compiling the Generated Code

4.2.4.1 Windows and Windows CE Compilation

As explained above, on Windows you can select to generate project and workspace/solution files for any of the supported integrated development environments (IDEs) – MS Visual Studio 5.0/6.0/2003/2005/2008/2010, Borland C++ Builder, Visual Basic 6.0, Borland Delphi, MS eMbedded Visual C++, or MS Platform Builder – and you can also select to automatically invoke your selected IDE from the wizard. You can then proceed to immediately build and run the code from your IDE.

You can also build the generated code from any other IDE that supports the selected code language and target OS. Simply create a new project file for your selected IDE, then add the generated source files to your project and compile and run the code.


	For Windows 7/Vista/Server 2008/Server 2003/XP/2000, the generated IDE files are located under an x86 directory – for 32-bit projects, or amd64 directory – for 64-bit projects. For Windows CE, note that the generated Windows Mobile code is targeted at the Windows Mobile 5.0/6.0 ARMV4I SDK.


	To build a Kernel PlugIn project (on Windows), follow the instructions in section 12.7.1.

4.2.4.2 Mac OS X Compilation

As explained above, you can use DriverWizard to generate an Xcode project and a related makefile. You can easily build the generated code using either of the following methods:


	In the following instructions, <project_dir> signfies the path to the location in which you saved your project (for example, ~/WinDriver/wizard/my_projects/JungoDriver), and xxx signfies your selected project name (for example, JungoDriver).

Use Xcode to open the generated Xcode project – <project_dir>/macos/xxx.xcodeproj (for example, ~/WinDriver/wizard/my_projects/JungoDriver/macos/JungoDriver.xcodeproj) – and build the code.
Open a command-line prompt, change directory to the <project_dir>/macos directory (for example, ~/WinDriver/wizard/my_projects/JungoDriver/macos), and run make to build the code.

The build will create an xxx application under a <project_dir>/macos/build/Release or <project_dir>/macos/build/Debug sub-directory – depending on how you selected to build the project (for example, ~/WinDriver/wizard/my_projects/JungoDriver/macos/build/Release/JungoDriver).

You can also build the generated code using any other IDE/compiler that is supported on Mac OS X. Simply create a new project or make file for your selected IDE/compiler, add the generated source files to your project/makefile, and build the code.


	To build a Kernel PlugIn project, follow the instructions in section 12.7.2.

4.2.4.3 Linux Compilation

Use the makefile that was created for you by DriverWizard in order to build the generated code using your favorite compiler, preferably GCC.


	To build a Kernel PlugIn project, follow the instructions in section 12.7.3.


	On Windows 7 and Vista you must run DriverWizard as administrator.


	To compile the generated Kernel PlugIn code, the Windows Driver Kit (WDK) must be installed.