4.2 DriverWizard Walkthrough

To use DriverWizard:

1. Attach your hardware to the computer:
   Attach the card to the appropriate bus slot on your computer. OR
   You have the option of using DriverWizard to generate code for a PCI device without having the actual device installed. When selecting this option, DriverWizard will generate code for your virtual PCI device.

   ****************************************************************************************

   NOTE

   When selecting the virtual PCI device option, the DriverWizard allows you to define the device's resources. By specifying the IO/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 IO/Memory ranges are irrelevant, since these will be automatically detected by DriverWizard when you install a physical device.

   ****************************************************************************************

2. Run DriverWizard and select your device:
   

       (a)

   Click Start | Programs | WinDriver | DriverWizard or double click the DriverWizard icon on your desktop (on Windows), or run the wdwizard utility from the WinDriver/wizard/ directory.

       (b)

   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

   

       (c)

   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: PCI Virtual Device.

3. Generate an INF file for DriverWizard:
   When developing a driver for a Plug and Play Windows operating system (i.e., Windows 98/Me/2000/XP/Server 2003/Vista) you are required to install an INF file for your device. This file will register your Plug and Play device to work with the windrvr6.sys driver. The file generated by the DriverWizard in this step should later be distributed to your customers using Windows 98/Me/2000/XP/Server 2003/Vista, and installed on their PCs.
   The INF file you generate here is also designed to enable DriverWizard to diagnose your device (for example, when no driver is installed for your PCI/PCMCIA device). As explained earlier, this is required only when using WinDriver to support a Plug and Play device (PCI/PCMCIA) on a Plug and Play system (Windows 98/Me/2000/XP/Server 2003/Vista). Additional information concerning the need for an INF file is explained in section 15.1.1.

   If you do not need to generate an INF file, skip this step and proceed to the next one.

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

       (a)

   In the Select Your Device screen, click the Generate .INF file button or click Next.

   Figure 4.3: DriverWizard INF File Information

   

       (b)

   DriverWizard will display information detected for your device - Vendor ID, Device ID, Device Class, manufacturer name and device name - and allow you to modify the manufacturer and device names and the device class information.

       (c)

   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.

   On Windows 2000/XP/Server 2003/Vista you can choose to automatically install the INF file from the DriverWizard by checking the Automatically Install the INF file option in the DriverWizard's INF generation dialogue.
   On Windows 98/Me you must install the INF file manually, using Windows Add New Hardware Wizard or Upgrade Device Driver Wizard, as explained in section 15.1.
   If the automatic INF file installation on Windows 2000/XP/Server 2003/Vista fails, DriverWizard will notify you and provide manual installation instructions for this OS as well.

       (d)

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

   ****************************************************************************************

   	NOTE
   	To use Message-Signaled Interrups (MSI) or Extended Message-Signaled Interrups (MSI-X) on Windows Vista (for PCI cards that support MSI/MSI-X) you will need to modify or replace the generated DriverWizard INF file to include specific MSI information, otherwise WinDriver will attempt to use legacy level sensitive interrupt handling for your card, as explained in section 9.2.6.1 of the manual.

   ****************************************************************************************

4. 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.

       (a)

   In the Select Your Device screen, click the Uninstall .INF file button.

       (b)

   Select the INF file to be removed.

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

       (a)

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

   • DriverWizard will automatically detect your Plug-and-Play hardware's resources (I/O ranges, memory ranges and interrupts).

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

     Figure 4.4: PCI Resources

     

     You can define the registers manually.

     Figure 4.5: Define Registers

     

     ****************************************************************************************

     	NOTE
     	You have the option to check the Auto Read box in the Register Information window. The registers that are marked with the Auto Read option will automatically be read with any register read/write operation performed from the Wizard (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.

     Figure 4.6: Read/Write Memory and I/O

     

     ****************************************************************************************

     	NOTE
     	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.

     ****************************************************************************************

   • 'Listen' to your hardware's interrupts.

     Figure 4.7: Listen to Interrupts

     

     ****************************************************************************************

     NOTES

     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! The specific interrupt-acknowledgment information is hardware-specific. The DriverWizard does not currently support listening to MSI/MSI-X interrupts [9.2.6].

     ****************************************************************************************

     Figure 4.8: Define Transfer Commands for Level Sensitive Interrupts

     

6. Generate the skeletal driver code:

       (a)

   Select to generate code either via the Generate Code toolbar icon or from the Project | Generate Code menu.

       (b)

   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

   

       (c)

   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.

   Figure 4.10: Additional Driver Options

   

   ****************************************************************************************

   	NOTE
   	Before generating Kernel PlugIn code you must install Microsoft's Driver Development Kit (DDK) for your target OS(s).

   ****************************************************************************************

       (d)

   Save your project (if required) and click OK to open your development environment with the generated driver.

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