Jungo Ltd

WinDriver 5.22 User's Guide

COPYRIGHT

Copyright © 1997-2002 Jungo Ltd. All Rights Reserved

Information in this document is subject to change without notice. The software described in this document is furnished under a license agreement. The software may be used, copied or distributed only in accordance with that agreement. No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or any means, electronically or mechanically, including photocopying and recording for any purpose without the written permission of Jungo Ltd.

Windows, Win32, Windows 95, Windows 98, Windows Me, Windows CE, Windows NT, Windows 2000 and Windows XP are trademarks of Microsoft Corp. WinDriver and KernelDriver are trademarks of Jungo. Other brand and product names are trademarks or registered trademarks of their respective holders.

Contents

List of Figures

    1.1  WinDriver Architecture
    1.2  Monolithic Drivers
    1.3  Layered Drivers
    1.4  Miniport Drivers

    2.1  USB Endpoints
    2.2  USB Pipes
    2.3  WinDriver USB Architecture

    4.1  Selection of PnP Device
    4.2  DriverWizard INF File Information
    4.3  USB Device Configuration
    4.4  A PCI Diagnostics Screen
    4.5  USB Diagnostics Screen
    4.6  Generate Code Option
    4.7  Select Driver Type
    4.8  Options for Generating Code
    4.9  Notification Events
    4.10  INF Generation

    6.1  Start Debug Monitor
    6.2  Set Trace Options

    8.1  USB Data Exchange
    8.2  USB Read and Write
    8.3  Pipe Selection
    8.4  USB Pipes
    8.5  Log Screen

    10.1  Kernel PlugIn Architecture
    10.2  Interrupt Handling without Kernel PlugIn
    10.3  Interrupt Handling with the Kernel PlugIn

Chapter 1
WinDriver Overview

1.1  Introduction to WinDriver

WinDriver is a development toolkit that dramatically simplifies the difficult task of creating device drivers and hardware access applications. The driver and application you develop using WinDriver is source code compatible between all supported operating systems (WinDriver currently supports Windows 95/98/Me/NT/2000/XP/CE, Linux, Solaris and VxWorks.). The driver is binary compatible between Windows 95/98/Me/NT/2000/XP. Bus architecture support includes PCI/CardBus/ISA/ISAPnP/EISA/CompactPCI and USB. WinDriver provides a complete solution for creating high performance drivers, which handle interrupts and I/O at optimal rates.

Don't let the size of this manual fool you - WinDriver makes developing device drivers an easy task that takes hours instead of months. Most developers will find that reading this chapter and glancing through the DriverWizard and function reference chapters is all they need to successfully write their driver.

The major part of this manual deals with the features that WinDriver offers to the advanced user.

WinDriver supports all USB and PCI bridges, from all vendors. Enhanced support is offered for the PLX / Altera / Marvell / PLDA / AMCC and QuickLogic PCI chips. A special chapter is dedicated to developers of USB devices and PCI card drivers who are using USB and PCI chips from these vendors. The final chapters of this manual explain how to tune your driver code to achieve optimal performance, with special emphasis on the Kernel PlugIn feature of WinDriver. This feature allows the developer to write and debug the entire device driver in the user mode, and later drop performance critical parts into the Kernel mode. Therefore, the driver achieves optimal Kernel mode performance, with user mode ease of development.

Visit Jungo's web site at http://www.jungo.co.uk for the latest news about WinDriver and other driver development tools that Jungo offers.

Good luck with your project!

1.2  Background

1.2.1  The Challenge

In protected operating systems (such as Windows, Linux and Solaris), a programmer cannot access hardware directly from the application level (the user mode) where development work is usually done. Hardware access is allowed only from within the operating system itself (the Kernel mode or Ring 0), by software modules called device drivers. In order to access a custom hardware device from the application level, a programmer must do the following:

• Learn the internals of the operating system he is working on (Windows 95/98/Me/NT/2000/XP/CE, Linux, Solaris and VxWorks).
• Learn how to write a device driver.
• Learn new tools for developing / debugging in the Kernel mode (DDK, ETK, DDI/DKI).
• Write the Kernel mode device driver that does the basic hardware input/output.
• Write the application in the User mode, which accesses the hardware through the device driver written in the Kernel mode.
• Repeat the first four steps for each new operating system on which the code should run.

1.2.2  The WinDriver Solution

Easy Development - WinDriver enables Windows programmers to create PCI/CardBus/ISA/ISAPnP/EISA/CompactPCI and USB based device drivers in an extremely short time. WinDriver allows you to create your driver in the user mode in the familiar environment - Using MSDEV, Visual C/C++, Borland Delphi, Borland C++, Visual Basic, GCC or any other 32 bit compiler. WinDriver eliminates the need for you to be familiar with the operating system internals, kernel programming or with the DDK, ETK, DDI / DKI or have any device driver knowledge.

Cross Platform - The driver created with WinDriver will run on
Windows 95/98/Me/NT/2000/XP/CE, Linux, Solaris and VxWorks,
- i.e., write once - Run on many platforms.

Friendly Wizards - DriverWizard (included) is a graphical diagnostics tool that lets you write to, and read from the hardware, before writing a single line of code. With a few clicks of the mouse, the hardware is diagnosed - Memory ranges are read, registers are toggled and interrupts are checked. Once the device is operating to your satisfaction, DriverWizard creates the skeletal driver source code, giving access functions to all the resources on the hardware.

Kernel Mode Performance - WinDriver's API is optimized for performance. For drivers that need Kernel mode performance, WinDriver offers the Kernel PlugIn. This powerful feature enables you to create and debug your code in the user mode, and run the performance critical parts of your code, (such as the interrupt handler, or access to I/O mapped memory ranges), in Kernel mode, thereby achieving Kernel mode performance (zero performance degradation). This unique feature allows the developer to run the user mode code in the OS kernel without having to learn how the kernel works. When working with Windows CE or VxWorks, there is no need to use the Kernel PlugIn since in Windows CE and VxWorks there is no separation between user mode and Kernel mode. This enables you to achieve optimal performance from the user mode code.

1.3  How Fast Can WinDriver Go?

Using the WinDriver Kernel PlugIn you can expect the same throughput as a custom kernel driver. You are limited only by your operating system and hardware limitations. A ballpark figure of the throughput you can reach using the Kernel PlugIn would be about 100,000 interrupts per second.

1.4  Conclusion

• Start DriverWizard and detect the hardware and its resources.

• Automatically generate the device driver code from within DriverWizard.

• Call the generated functions from the user mode application.

1.5  WinDriver Benefits

• Easy User mode driver development.
• Kernel PlugIn for high performance drivers.
• Friendly DriverWizard allows hardware diagnostics without writing a single line of code.
• DriverWizard automatically generates the driver code for the project in C\C++ or Delphi (Pascal).
• Supports any PCI/CardBus/ISA/ISAPnP/EISA/CompactPCI and USB device regardless of manufacturer.
• Enhanced support for PLX 9030/9050/9052/9054/9060/9080/IOP 480, Altera, Marvell, QuickLogic, PLDA, and AMCC PCI bridges, allows the developer to disregard the PCI bridge details.
• Applications are binary-compatible across Windows 95/98/Me/NT/2000/XP.
• Applications are source code compatible across Windows 95/98/Me/NT/2000/XP/CE, Linux, Solaris and VxWorks.
• WinDriver can be used with common development environments including MSDEV, Visual C/C++, Borland Delphi, Borland C++, Visual Basic, GCC or any other 32 compiler.
• No DDK, ETK, DDI or any system-level programming knowledge is required.
• Supports I/O, DMA, Interrupt handling and access to memory mapped cards.
• Supports multiple CPU and multiple PCI bus platforms.
• Includes dynamic driver loader.
• Comprehensive documentation and help files.
• Detailed examples in C, Delphi and Visual Basic are included.
• Two months of free technical support.
• No run time fees or royalties.

1.6  WinDriver Architecture

Figure 1.1: WinDriver Architecture

For hardware access, your application calls one of the WinDriver functions from the WinDriver User mode library (windrvr.h). The User mode library calls the WinDriver kernel, which accesses the hardware for you, through the native calls of the operating system.

WinDriver's design minimizes performance hits on your code, even though it is running in the User mode. However, some hardware drivers have high performance requirements, that cannot be achieved in User mode. This is where WinDriver's edge sharpens - After easily creating and debugging your code in User mode, you may drop the performance critical modules of your code (such as a hardware interrupt handler) into the WinDriver Kernel PlugIn without changing a single line of it. Now, WinDriver kernel calls this module from the Kernel mode, thereby achieving maximal performance. This allows you to program and debug in the User mode, and still achieve kernel performance where needed. In Windows CE and VxWorks there is no separation between User mode and Kernel mode, therefore you may achieve optimal performance directly from the User mode, eliminating the need to use the Kernel PlugIn in these operating systems.

1.7  What Platforms Does WinDriver Support?

1.8  Limitations of the Different Evaluation Versions

All the evaluation versions of WinDriver are full featured. No functions are limited or crippled in any way. The following is a list of the differences between the evaluation versions and the registered ones:

• Each time WinDriver is activated, an Un-registered message appears.
• When using the DriverWizard, a dialog box with a message stating that an evaluation version is being run, is popped up on every interaction with the hardware.
• In the Linux, Solaris, VxWorks and CE versions - The driver is operational for 60 minutes after which it has to be restarted.
• The Windows evaluation version expires 30 days from the date of installation.

For more details please refer to appendix B.

1.9  How Do I Develop My Driver with WinDriver?

1.9.1  On Windows 95, 98, Me, NT, 2000 and XP

1. Start DriverWizard (Please refer to Chapter 4 for more details).
2. Diagnose your card using DriverWizard.
3. Let DriverWizard generate skeletal code for your driver. The code generated by DriverWizard is in fact a diagnostics program that contains functions that read and write to any resource detected or defined (including custom defined registers), enables your card's interrupts and listens to them.
4. Modify the code generated by DriverWizard to suit your particular application needs.
5. Run and debug your driver in the User mode.
6. If your code contains performance critical sections, improve their performance (see Chapter 9).

1.9.2  On Windows CE

1. Plug your hardware into a Windows host machine.
2. Activate Visual C++ for CE on the host machine.
3. Diagnose your hardware using DriverWizard.
4. Let DriverWizard generate your driver's skeletal code.
5. Modify this code using Visual C++ to meet your specific needs.
6. Test and debug your code and hardware from the CE emulation running on the host machine.
7. If your code contains performance critical sections, improve their performance by referring to Chapter 9.

1.9.3  On Linux and Solaris

Starting from version 5.0, WinDriver offers a GUI DriverWizard that facilitates driver development on Linux and Solaris. Use the GUI DriverWizard for Linux and Solaris in the same way as the DriverWizard on Windows to generate Linux and Solaris code.

If you are using WinDriver 4.x or an older version, and you do not use the Linux or Solaris X11 GUI, you may wish to consider using Windows as an initial development platform.

If you do not have a Windows machine, you may use the sample files included with WinDriver as skeletons for your driver and change them to meet your needs, using the WinDriver API.

1.9.4  On VxWorks

1. Plug your hardware into a Windows host machine.
2. Diagnose your hardware using DriverWizard for Windows.
3. Let DriverWizard generate your driver's skeletal code and project makefile for Tornado.
4. Move the code to your tornado environment and compile it.
5. Modify this code using tornado development environment or any other 32-bit development environment to meet your specific needs.

1.10  What Does the WinDriver Toolkit Include?

• The WinDriver CD.
• A printed version of this manual.
• Two months of free technical support (Phone / Fax / Email).
• WinDriver CE license, enabling you to run your CE driver code on your NT machine using CE emulation.
• WinDriver Linux and Solaris licenses, enabling you to use DriverWizard on a Windows machine to diagnose hardware and automatically generate driver skeletal code. You can then compile and run the code on your Linux / Solaris machine. The code will not run on your Windows machine without WinDriver for Windows licensing.
• WinDriver modules.
• Utilities.
• Chipset support APIs.
• Sample files.

1.10.1  WinDriver Modules

• WinDriver - (WinDriver\include) - The general purpose hardware access toolkit. The main files here are:
  • windrvr.h: the WinDriver API, data structures and constants are defined in this header file.

  • windrvr_int_thread.h: a convenience header file, that contains wrapper functions to simplify interrupt handling.

• DriverWizard (Start Menu | Programs | WinDriver | DriverWizard) - A graphical tool that diagnoses your hardware and lets you easily code your driver.

• Graphical Debugger (Start Menu | Programs | WinDriver | Debug Monitor) - A graphical debugging tool which collects information about your driver as it runs. On Linux, Solaris, WinCE and VxWorks, you can use the console version of this program.

• WinDriver distribution package (WinDriver\redist) - The files you include in the driver distribution to customers.

• WinDriver Kernel PlugIn (WinDriver\kerplug) - The files and samples needed to create a Kernel PlugIn for WinDriver.

• This manual (Start Menu | Programs | WinDriver) - The full WinDriver manual (this document), in PDF, Windows Help and HTML formats.

1.10.2  Utilities

• PCI_SCAN.EXE (\WinDriver\util\pci_scan.exe) - Enables you to get a list of the PCI cards installed and the resources allocated for each of them.
• PCI_DUMP.EXE (\WinDriver\util\pci_dump.exe) - Used for getting a dump of all the PCI configuration registers of the PCI cards installed.
• USB_DIAG.EXE (\WinDriver\util\usb_diag.exe) - Provides a list of the USB devices installed, the resources allocated for each one of them, and for accessing the USB devices.

The CE version includes:

• \REDIST\... \X86EMU\WINDRVR_CE_EMU.DLL: This DLL communicates with the WinDriver kernel, for the X86 HPC emulation mode of Windows CE.
• \REDIST\... \X86EMU\WINDRVR_CE_EMU.LIB: An import library, used for linking with WinDriver applications that are compiled for the X86 HPC emulation mode of Windows CE.

1.10.3  WinDriver's Specific Chipset Support

These are APIs that support the major PCI bridge chipsets, for even faster code development:

• WinDriver PLX APIs (for the 9030, 9050, 9052, 9054, 9060, 9080, 9056 and 9656 PCI bridges) - WinDriver\plx\9050 and \ 9054, \9060, \9080 respectively.
• WinDriver Marvell APIs (for the Marvell GT64 PCI bridges) -
  WinDriver\marvell\gt64.
• WinDriver AMCC APIs (for the AMCC S5933 PCI bridges) - WinDriver\amcc.
• WinDriver ALTERA (for Altera PCI cores) - WinDriver\altera.
• WinDriver QuickLogic APIs (for the QuickLogic PCI bridges) - WinDriver\QuickLogic.

Each of the directories above includes the following subdirectories:

• \lib - The special chipset API for the PLX / AMCC / QuickLogic/ Altera chipset, written using the WinDriver API.
• \xxx_diag - A sample diagnostics application, which was written using the special library functions available for the chipsets. This application may be compiled and executed as-is (xxx_diag i.e., p9054_diag.c for the PLX 9054 chip).

1.10.4  Samples

Here you will find the source code for the utilities listed earlier, along with other samples which show how to perform the various driver tasks. Find the sample closest to the driver you need and use it to jump-start your driver development process:

• WinDriver samples (WinDriver\samples) - Samples which demonstrate different common drivers.
• WinDriver for Altera / AMCC / Cypress / Marvel / PLX / Quicklogic samples
  (e.g., WinDriver\PLX\p9054_diag or WinDriver\Cypress\bulk_sample etc.) - Source code of the diagnostics applications for the specific chipsets that WinDriver supports.

1.11  Can I Distribute the Driver Created with WinDriver?

Yes. WinDriver is purchased as a development toolkit, and any device driver created using WinDriver may be distributed royalty free in as many copies as you wish. See the license agreement (WinDriver\docs\license.txt) for more details.

1.12  Device Driver Overview

This section provides an overview of the common device driver architectures.

1.12.1  Monolithic Drivers

These are the device drivers that are primarily used to drive custom hardware. A monolithic driver is accessed by one or more user applications, and directly drives a hardware device. The driver communicates with the application through I/O control commands - (IOCTLs), and drives the hardware using calls to the different DDK, ETK, DDI / DKI functions.

Figure 1.2: Monolithic Drivers

Monolithic drivers exist in all operating systems including all Windows platforms and all Unix platforms.

1.12.2  Windows 95/98/Me Drivers

We use the term Windows drivers for VxD drivers that run on Windows 95, Windows 98 and Windows Me. These drivers do not work on Windows NT. Windows drivers are typically monolithic in nature. They provide direct access to hardware and privileged operating system functions. Windows drivers can be stacked or layered in any fashion, but the driver structure itself does not impose any layering.

1.12.3  NT Driver Model

Other than monolithic drivers, Windows NT uses other kinds of drivers: layered and miniport drivers. These drivers are generally unique to Windows NT, but subsets or minor variations of which might be supported on other Windows versions.

Layered Drivers

Layered drivers are device drivers that are part of a stack of device drivers, that together process an I/O request. An example of a layered driver is a driver that intercepts calls to the disk, and encrypts / decrypts all data being transferred to / from the disk. In this example, a driver would be hooked on to the top of the existing driver and would only do the encryption / decryption.

Layered drivers are sometimes also known as filter drivers, and are also supported in Windows 95/98/Me.

Figure 1.3: Layered Drivers

Miniport Drivers

There are classes of device drivers in which, much of the code has to do with the functionality of the device, and not with the device's inner workings.

Figure 1.4: Miniport Drivers

Windows NT/2000/XP, for instance, provides several driver classes (called ports) that handle the common functionality of their class. It is then up to the user to add only the functionality that has to do with the inner workings of the specific hardware.

An example for a miniport driver is the NDIS miniport driver. The NDIS miniport framework is used to create network drivers that hook up to NT's communication stacks, and are therefore accessible to common communication calls used by applications. The Windows NT kernel provides drivers for the different communication stacks, and other code that is common to communication cards. Due to the NDIS framework, the network card developer does not have to write all of this code, only the code that is specific to the network card he is developing.

1.12.4  Unix Device Drivers

In the classic Unix driver model, devices belong to on of three categories, character (char) devices, block devices and network devices. Drivers that implement these devices are correspondingly known as char drivers, block drivers or network drivers. Under Unix, drivers are code units that are linked into the kernel, and run in privileged Kernel mode. Generally, driver code runs on behalf of the User mode application. Access to Unix drivers from User mode applications is provided via the filesystem. In other words, devices appear to the applications as special device files that can be opened.

Character (also referred to as "char") devices can be accessed as files, and are implemented by char drivers. These drivers usually implement the open, close, read, write and ioctl system calls. The console and the serial port are examples of devices that are implemented by char drivers. Applications access char devices through files known as device nodes, such as /dev/console or /dev/ttyS0.

Block Block devices are also accessed as files, and are implemented by block drivers. These devices are generally used to represent hardware on which you can implement a file system. Typically, block devices are accessed by multiples of a block of data at a time. Block sizes are typically 512 bytes or 1 Kilobyte. Block drivers interface with the kernel through a similar interface as a char driver. The device node for a block device shows differently in the filesystem listing.

Network Network interfaces are used to perform network transactions between applications residing on a network. A network interface may work through a hardware device or sometimes be implemented completely in software, like the loopback interface. User applications perform network transactions through interfaces to the kernel network subsystem (usually exposed as an API, such as sockets and pipes). Network interfaces send and receive network packets on behalf of user applications, without regard to how each individual transaction maps to actual packets being transmitted.

Network interfaces don't easily fit into the block or char philosophy, and therefore are not visible as device nodes in the filesystem. They are represented by system wide unique logical names such as eth0. Clearly, network interfaces are not accessed via the open/read/write ... system calls. Instead they are accessed through network APIs, such as sockets, pipes, RPC, etc.

1.12.5  Linux Device Drivers

Linux device drivers are based on the classic Unix device driver model. In addition, Linux introduces some new characteristics.

Under Linux, block devices can also be accessed like a character device, but have an additional block oriented interface which is invisible to the user or application.

Traditionally, under Unix, device drivers had to be linked with the kernel, and the system had to be brought down and restarted after installing a new driver. Linux introduced the concept of a dynamically loadable driver called a module. Linux modules can be loaded or removed dynamically without requiring the system to be shut down. All Linux drivers can be written so that they are statically linked, or in modular form, which makes them dynamically loadable. This makes Linux memory usage very efficient because modules can be written to probe for their own hardware and unload themselves if they cannot find the hardware they are looking for.

1.12.6  Solaris Device Drivers

Solaris device drivers are also based on the classic Unix device driver model. Like Linux, Solaris drivers may either be statically linked with the kernel, or may be dynamically loaded and removed, from the kernel.

1.13  Matching the Right Tool for Your Driver

Jungo offers two driver development products: WinDriver and KernelDriver.

WinDriver is designed for monolithic type User mode drivers. It enables you to access your hardware directly from within your Win32 application, without writing a Kernel mode device driver. Using WinDriver you can either access your hardware directly from your application (in User mode) or write a DLL that you can call from many different applications.

In addition, WinDriver provides a complete solution for high performance drivers. Using WinDriver's Kernel PlugIn, you can drop your User mode code into the kernel and reach full Kernel mode performance.

A driver created with WinDriver runs on Windows 95/98/Me/NT/2000/XP/CE, Linux, Solaris and VxWorks. Typically, a developer without any previous driver knowledge can get a driver running in a matter of a few hours (compared to several weeks with a kernel mode driver).

KernelDriver is intended for situations that require running drivers in Kernel mode. Network drivers under Linux and Windows for example, almost always need to reside in the kernel. In addition, kernel programming under Windows NT is necessary for layered or miniport drivers. The KernelDriver tool kit allows you to write Kernel mode drivers for Windows platforms (Windows 95/98/Me/NT/2000/XP) and Linux. KernelDriver also offers special support for Windows NT model drivers - A C++ toolkit that provides classes that encapsulate thousands of lines of kernel code, enabling you to focus on your /driver's added-value functionality, instead of OS internals.

Chapter 2
WinDriver USB Overview

This chapter explores the basic characteristics of the USB bus and introduces WinDriver USB's features and architecture.

2.1  Introduction to USB

USB (short for Universal Serial Bus), is an industry standard extension to the PC architecture, for attaching peripherals to the computer. The Universal Serial Bus was originally developed in 1995 by leading PC and telecommunication industry companies, such as Intel, Compaq, Microsoft and NEC. The motivation for the development of USB, was fueled because of several considerations. Among them are the needs for an inexpensive and widespread connectivity solution for peripherals in general and for the Computer Telephony Integration in particular, the need for an easy to use and flexible method of reconfiguring the PC and a solution for adding a large number of external peripherals.

The USB interface meets the needs stated above. A single USB port can be used to connect up to 127 peripheral devices. USB also supports Plug-and-Play installation and hot swapping. USB 1.1 supports both isochronous and asynchronous data transfers and has dual speed data transfer; 1.5Mbps (Megabit per second) for low speed USB devices and 12Mbps for high speed USB devices (much faster than the original serial port). Cables connecting the device to the PC can be up to five meters (16.4 feet) long. USB includes built-in power distribution for low power devices, and can provide limited power (maximum: 500mA of current) to devices attached on the bus.

Because of these benefits, USB is enjoying broad market acceptance today.

USB 2.0 supports a faster signalling rate of 480 Mb/S that is 40 times faster than USB 1.1. USB2.0 is fully forward and backward compatible with USB1.1 and uses the existing cables and connectors.

USB2.0 supports a connection for higher bandwidth, higher functionality PC peripherals. In addition, it has the capability to handle more simultaneously running peripherals.

USB2.0 will benefit many applications like Interactive Gaming, Broadband Internet Access, Desktop and Web Publishing, Internet Services and Conferencing.

2.2  WinDriver USB Benefits

• External connection; easy to use for the end user.

• Self identifying peripherals, automatic mapping of function to driver, and configuration.

• Dynamically attachable and re-configurable peripherals.

• Suitable for device bandwidths ranging from a few Kb/s to several Mb/s.

• Supports isochronous as well as asynchronous transfer types over the same set of wires.

• Supports simultaneous operation of many devices (multiple connections).

• Supports up to 127 devices.

• Guaranteed bandwidth and low latencies; appropriate for telephony, audio, etc. (Isochronous transfer may use almost entire bus bandwidth).

• Flexibility: Supports a wide range of packet sizes and a wide range of data rates.

• Robustness: Error handling mechanism built into protocol, dynamic insertion and removal of devices identified in user observed real time.

• Synergy with PC industry.

• Optimized for integration in peripheral and host hardware.

• Low cost implementation, therefore suitable for development of low cost peripherals.

• Low cost cables and connectors.

• Uses commodity technologies.

• Built in power management and distribution.

2.3  USB Components

USB Host: The USB host computer is where the USB host controller is installed, and where the client software / device driver runs. The USB host controller is the interface between the host and the USB peripherals. The host is responsible for detecting attachment and removals of USB devices, managing the control and data flow between the host and the devices, providing power to attached devices and more.

USB Hub: A USB device that enables connecting additional USB devices to a single USB port on the USB host. Hubs on the back plane of the hosts are called root hubs. Other hubs are external hubs.

USB Function: The USB device that is able to transmit or receive data or control information over the bus, and provides a function. Compound devices provide multiple functions on the USB bus.

2.4  Data Flow in USB Devices

During the operation of the USB device, data flows between the client software and the device. The data is moved between memory buffers of the software on the host and the device, using pipes, which end in endpoints on the device side.

An endpoint is a uniquely identifiable entity on the USB device, which is the source or the terminus of the data that flows from or to the device. Each USB device, logical or physical, has a collection of independent endpoints. Endpoint attributes are their bus access frequency, their bandwidth requirement, their endpoint number, their error handling mechanism, the maximum packet size that the endpoint can transmit or receive, their transfer type and their direction (into the device / out of the device).

Pipes are logical components, representing associations between an endpoint on the USB device and software on the host. The data is moved to and from the device through a pipe. A pipe can be of two modes: stream pipe and message pipe, according to the type of data transfer used in that pipe. Pipes, sending data in interrupt, bulk or isochronous types are stream pipes, while control transfer type is supported by the message pipes. The different USB transfer types are discussed below:

Figure 2.1: USB Endpoints

2.5  USB Data Exchange

The USB standard supports two kinds of data exchange between the host and the device: functional data exchange and control exchange:

• Functional data exchange is used to move data to and from the device. There are three types of data transfers: Bulk transfers, Interrupt transfers and Isochronous transfers.

• Control exchange is used to configure a device when it is first attached and can also be used for other device specific purposes, including control of other pipes on the device. The control exchange is transferred via the control pipe (Pipe 00). The control transfer consists of a setup stage (in which a setup packet is sent from the host to the device), an optional data stage and a status stage.

The screen shot below shows a USB device with one bi-directional control and three functional data transfer pipes / endpoints:

Figure 2.2: USB Pipes

2.6  USB Data Transfer Types

The USB device (function) communicates with the host by transferring data through a pipe between a memory buffer on the host and an endpoint on the device. USB provides different transfer types, that best suit the service required by the device and by the software. The transfer type of a specific endpoint is determined in the endpoint descriptor.

There are four different types of data transfer within the USB specification:

Control Transfer: Control transfer is mainly intended to support configuration, command and status operations between the software on the host and the device. Each USB device has at least one control pipe (default pipe), which provides access to the configuration, status and control information. The control pipe is a bi-directional pipe. Control transfer is bursty, non-periodic communication. Control transfer has a robust error detection, recovery and retransmission mechanism and retries are made with no involvement of the driver. Control transfer is used by low speed and high speed devices.

Isochronous Transfer: A type usually used for time dependent information, such as multimedia streams and telephony. The transfer is periodic and continuous. The isochronous pipe is uni-directional and a certain endpoint can either transmit or receive information. For bi-directional isochronous communication there's a need to use two isochronous pipes, one in each direction. USB guarantees the isochronous transfer access to the USB bandwidth (that is it reserves the required amount of bytes of the USB frame) with bounded latency and guarantees the data transfer rate through the pipe unless there is less data transmitted. Up to 90% of the USB frame can be allocated to periodic transfers (isochronous and interrupt transfers). If, during configuration, there is no sufficient bus time available for the requester isochronous pipe, the configuration is not established. Since time is more important than correctness in these types of transfers, no retries are made in case of error in the data transfer, though the data receiver can determine the error that occurred on the bus. Isochronous transfer can be used only by high speed devices.

Interrupt Transfer: Interrupt transfer is intended for devices that send and receive small amounts of data, in low frequency or in an asynchronous time frame. An interrupt transfer type guarantees a maximum service period and a retry of delivery to be attempted in the next period, in case of an error on the bus. The interrupt pipe, like the isochronous pipe, is uni-directional. The bus access time period (1-255ms for high speed devices and 10-255ms for low speed devices) is specified by the endpoint of the interrupt pipe. Although the host and the device can count only on the time period indicated by the endpoint, the system can provide a shorter period up to 1 ms.

Bulk Transfer: Bulk transfer is non-periodic, large packet, bursty communication. Bulk transfer typically supports devices that transfer large amounts of non-time sensitive data, and that can use any available bandwidth, such as printers and scanners. Bulk transfer allows access to the bus on availability basis, guarantees the data transfer but not the latency and provides error check mechanism with retries attempts. If part of the USB bandwidth is not being used for other transfers, the system will use it for bulk transfer. Like previous stream pipes (isochronous and interrupt) the bulk pipe is also uni-directional. Bulk transfer can only be used by high speed devices.

2.7  USB Configuration

Before the USB function (or functions in a compound device) can be operated, the device must be configured. The host does the configuring, by acquiring the configuration information from the USB device. USB devices report their attributes by descriptors. A descriptor is the defined structure and format in which the data is transferred. A complete description of the USB descriptors can be found in Chapter 9 of the USB Specification (See http://www.usb.org for the full specification).

It is best to view the USB descriptors as a hierarchic structure of four levels:

• The Device level.

• The Configuration level.

• The Interface level (this level may include an optional sub-level called alternate settings).

• The Endpoint level.

Device Level: At the top level is the device descriptor, that includes general information about the USB device, that is global information for all of the device configurations. The device descriptor describes, among other things, the device class (USB devices are divided into device classes, such as HID devices, hubs, locator devices etc.), subclass, protocol code, Vendor ID, Device ID and more. Each USB device has one device descriptor.

Configuration Level: A USB device has one or more configuration descriptors, which describe the number of interfaces grouped in each configuration and power attributes of the configuration (such as self-powered, remote wakeup, maximum power consumption and more). At a given time, only one configuration is loaded. An example of different configurations of the same device may be an ISDN adapter, where one configuration presents it with a single interface of 128KB/s and a second configuration with two interfaces of 64KB/s.

Interface Level: The interface is a related set of endpoints that present a specific functionality or feature of the device. Each interface may operate independently. The interface descriptor describes the number of the interface, number of endpoints used by this interface, and the interface specific class, subclass and protocol values when the interface operates independently. In addition, an interface may have alternate settings. The alternate settings allow the endpoints or their characteristics to be varied after the device is configured.

Endpoint Level: The lowest level is the endpoint descriptor that provides the host with information regarding the data transfer type of the endpoint and the bandwidth of each endpoint (the maximum packet size of the specific endpoint). For isochronous endpoints, this value is used to reserve the bus time required for the data transfer. Other attributes of the endpoints are their bus access frequency, their endpoint number, their error handling mechanism, and their direction.

Seems complicated? Not at all! WinDriver automates the USB configuration process. The included DriverWizard and USB diagnostics application, scan the USB bus, detect all USB devices and their different configurations, interfaces, settings and endpoints, and enables the developer to pick the desired configuration before starting driver development.

WinDriver identifies the endpoint transfer type as determined in the endpoint descriptor. The driver created with WinDriver contains all configuration information acquired at this early stage.

2.8  WinDriver USB

WinDriver USB enables developers to quickly develop high performance drivers for USB based devices, without having to learn the USB specifications or the OS internals. Using WinDriver USB, developers can create USB drivers without having to use the DDK, and without having to be familiar with Microsoft's WDM (Win32 Driver Module).

The driver code developed with WinDriver USB is binary compatible between Windows 98, Windows Me, Windows 2000 and Windows XP.

The source code will be code compatible among all other operating systems, supported by WinDriver USB. For up to date information regarding operating systems currently supported by WinDriver USB, please check Jungo's web site at
http://www.jungo.co.uk.

WinDriver USB encapsulates the USB specification and architecture, letting you focus on your application logic. WinDriver USB features DriverWizard, with which you can detect your hardware, configure it and test it before writing a single line of code. DriverWizard will lead you through the configuration procedure first, enable you to choose the desirable configuration, interface and alternate setting through a friendly graphical user interface. After detecting and configuring your USB device, you can then test it, listen to pipes, write and read packets and ensure that all your hardware resources function as expected. WinDriver USB is a generic tool kit, which supports all USB devices, from all vendors and with all types of configurations.

After your hardware is diagnosed, DriverWizard automatically generates your device driver source code in C or in Delphi. WinDriver USB provides user mode APIs to your hardware, which you can call from within your application. The WinDriver USB API is specific for your USB device and includes USB unique operations such as reset-pipe and reset-device. Along with the device API, WinDriver USB creates a diagnostics application, which just needs to be compiled and run. You can use this application as your skeletal driver to jump-start your development cycle. If you are a VB programmer, you will find all WinDriver USB API supported for you also in VB, giving you everything you need to develop your driver in VB.

DriverWizard also automates the creation of an INF file where needed. The INF file is a text file used by the Plug-n-Play mechanisms of Windows 95/98/Me/2000/XP to load the driver for the newly installed hardware or to replace an existing driver. The INF file includes all necessary information about the device(s) and the files to be installed. INF files are required for hardware that identify themselves, such as USB and PCI. In some cases, the INF file of your specific device is included in the INF files that are shipped with the operating system. In other cases, you will need to create an INF file for your device. WinDriver automates this process for you. More information on how to create your own INF file with DriverWizard can be found in Chapter 4 that explains the DriverWizard. Installation instructions of INF files can be found in Chapter 13 that illustrates how to distribute your driver.

Using WinDriver USB, all development is done in the user mode, using familiar development and debugging tools and your favorite compiler (such as MSDEV, Visual C/C++, Borland Delphi, Borland C++, Visual Basic).

WinDriver USB API is designed to give you optimized performance. In cases where native Kernel mode performance is needed, use WinDriver USB's unique Kernel PlugIn feature (included). This powerful feature enables you to write and debug your code in the user mode, and then simply drop it into the Kernel PlugIn for kernel mode execution. This unique architecture enables you to achieve maximum performance with user mode ease of use.

2.9  WinDriver USB Architecture

Figure 2.3: WinDriver USB Architecture

To access your hardware, your application calls the required WinDriver USB API function from the WinDriver user mode Library (windrvr.h). The user mode Library calls the WinDriver Kernel module, windrvr.sys. The WinDriver Kernel module accesses your USB device resources through the native operating system calls.

There are two layers responsible to abstract the USB device to the USB device driver:

The upper one is the USB Driver layer (including the USB Driver (USBD) and USB Hub Driver) and the lower one is the Host Controller Driver layer (HCD). The division of duties between the host controller driver and USB driver is not defined, and is operating system dependent. Both host controller driver and USB driver are software interfaces and components of the operating system, where the host controller driver layer represents a lower level of abstraction.

The host controller driver is the software layer that provides an abstraction of the host controller hardware while the USBD provides an abstraction of the USB device and the data transfer between the host software and the function of the USB device.

The USBD communicates with its clients (the specific device driver for example) through the USB Driver Interface (USBDI). At the lower level, the USB driver and USB hub driver implement the hardware access and data transfer by communicating with the HCD using the host controller driver interface.

The USB hub Driver is responsible for identifying addition and removal of devices from a particular hub. Once the Hub Driver receives a signal that a device was attached or detached, it uses additional host software and the USB driver to recognize and configure the device. The software implementing the configuration can include the hub driver, the device driver and other software.

WinDriver USB abstracts the configuration procedure and hardware access described above for the developer. With WinDriver USB API, developers can do all the hardware related operations without having to master the lower levels of implementing these activities.

2.10  Which Drivers Can I Write with WinDriver USB?

Almost all monolithic drivers (drivers that need to access specific USB devices), can be written with WinDriver USB. In cases where a standard driver needs to be written, e.g., NDIS driver, SCSI driver, Display driver, USB to Serial port drivers, USB layered drivers, etc., use KernelDriver USB (also from Jungo).

For quicker development time, select WinDriver USB over KernelDriver USB wherever possible.

Chapter 3
Installation and Setup

This chapter takes you through the WinDriver installation process, and shows you how to verify that your WinDriver is properly installed. The last section discusses the uninstallation procedure.

3.1  System Requirements

3.1.1  For Windows 95 / 98 / Me

• An x86 processor.

• Any 32-bit development environment supporting C, VB or Delphi.

3.1.2  For Windows NT / 2000 / XP

• An x86 processor.

• Any 32-bit development environment supporting C, VB or Delphi.

• Windows NT: Required at least Service Pack 3. Recommended: Service Pack 6.

3.1.3  For Windows CE

• An x86 Windows CE target platform.

• Windows NT/2000/XP host development platform.

• Microsoft eMbedded Visual C++ with a corresponding target SDK
  

  or
  

  Microsoft Platform Builder with corresponding BSP (Board Support Package) for the taget platform.

3.1.4  For Linux

• WinDriver supports all versions of Linux from 2.0.31 and above, including embedded Linux and Linux 2.4x.

• An x86 processor.

• Any 32-bit development environment supporting C (such as GCC).

3.1.5  For Solaris

• WinDriver supports Solaris 2.6/7.0/8.0, for both Sparc and Intel x86 platforms.

• Any 32-bit development environment supporting C (such as GCC).

3.1.6  For VxWorks

• Windows host development platform.

• Tornado II IDE.

• Selected Target Platform: This should be running a processor that has a BSP (Board Support Package) compatible with the list of CPU/BSP combinations supported by DriverBuilder.

  For an up-to-date list, see the URL below:
  http://www.jungo.co.uk/db-vxworks.html#platforms
  

  For information on BSP compatibility, please contact your nearest WindRiver Systems support representative.

3.2  Installing WinDriver

The WinDriver CD contains all versions of WinDriver for all the different operating systems. The CD's root directory contains the Windows 95/98/Me and NT/2000/XP version. This will automatically begin when you insert the CD into your CD drive. The other versions of WinDriver are located in subdirectories i.e., \Linux, \Wince and so on.

3.2.1  Installing WinDriver for Windows 95, 98, Me, NT, 2000 and XP

1. Insert the WinDriver CD into your CD-ROM drive.
   (When installing WinDriver by downloading it from Jungo's web site instead of using the WinDriver CD, double click the downloaded WinDriver file (WDxxx.EXE) in your download directory, and go to step 3).

2. Wait a few seconds until the installation program starts automatically. If for some reason it does not start automatically, double-click the file Wdxxx.EXE (where xxx is the version number) and click the Install WinDriver button.

3. Read the license agreement carefully, and click Yes if you accept its terms.

4. Choose the destination location in which to install WinDriver.

5. In the Setup Type screen, choose one of the following:
   • Typical - To install all WinDriver modules. (Generic WinDriver toolkit + specific chipset APIs).

   • Compact - To install only the generic WinDriver toolkit.

   • Custom - To choose which modules of WinDriver to install. You may choose which APIs will be installed.

6. After the installer completes copying all the required files, chose whether to view the quick-start guides.

7. You may now be prompt to reboot your computer.

In order to register your copy of WinDriver with the license you have received from Jungo, please follow the steps bellow:

1. Activate DriverWizard GUI (Start | Programs | WinDriver | DriverWizard).

2. Select the Register WinDriver option from the File menu and insert the license string you received from Jungo there. Press Activate License button.

3. To activate source code you have developed during the evaluation period, please refer to WD_license function refence.

3.2.2  Installing WinDriver CE

The installation instructions for WinDriver CE differ depending on what you want to do with Windows CE. There are two types of CE development tasks -

1. "Building" new CE based platforms.
   

   This will usually be the case if you are an OEM who ports the Windows CE operating system to his custom hardware using Microsoft Platform Builder (for example, if you are developing a device like a Pocket PC or a Handheld PC).

2. Developing applications for Windows CE based computers.
   

   This will usually be the case if you are an ISV (independent software vendor) who develops applications, using Microsoft eMbedded Visual Tools, targeted to run on CE platforms created by the OEMs.

Installing WinDriver CE when "building" new CE based platforms

1. Run Microsoft Platform Builder and open your platform.

2. Select Open Build Release Directory in the Build menu.

3. Copy the WinDriver CE kernel file
   \WinDriver\redist\TARGET_CPU\windrvr.dll
   to the %_FLATRELEASEDIR% subdirectory on your development platform (should be the current directory in the new command window).

4. Append the contents of the file
   \WinDriver\samples\wince_install\PROJECT_WD.REG
   to the file PROJECT.REG in the %_FLATRELEASEDIR% subdirectory.

5. Append the contents of the file
   \WinDriver\samples\wince_install\PROJECT_WD.BIB
   to the file PROJECT.BIB in the %_FLATRELEASEDIR% subdirectory.

   This step is only necessary if you want the WinDriver CE kernel file (WINDRVR.DLL) to be part of the Windows CE image (NK.BIN) permanently. This would be the case if you were transferring the file to your target platform using a floppy disk. If you prefer to have the file WINDRVR.DLL loaded on demand via the CESH/PPSH services, you need not carry out this step until you build a permanent kernel.

6. Select Make Image in the Build menu called NK.BIN.

7. Download your new kernel to the target platform and initialize it (e.g., select Download / Initialize in the Target menu or by using a floppy disk).

8. Restart your target CE platform. The WinDriver CE kernel will automatically load.

9. Compile and run the sample programs (see Section that describes how to check your installation) to make sure that WinDriver CE is loaded and is functioning correctly.

Installing WinDriver CE when developing applications for CE computers

1. Insert the WinDriver CD into your Windows host CD drive.

2. Exit from the auto installation.

3. Double click the Cd_setup.exe file from the \Wince directory inside the CD. This will copy all needed WinDriver files to your host development platform.

4. Copy the WinDriver CE kernel file
   \WinDriver\redist\TARGET_CPU\windrvr.dll
   to the \WINDOWS subdirectory of your target CE computer.

5. Use the Windows CE Remote Registry Editor tool (ceregedt.exe) or the Pocket Registry Editor (pregedt.exe) on your target CE computer to modify your registry so that the WinDriver CE kernel is loaded appropriately. The file \WinDriver\samples\wince_install\PROJECT_WD.REG contains the appropriate changes to be made.

6. Restart your target CE computer. The WinDriver CE kernel will automatically load. You will have to do a warm reset rather than just suspend/resume (use the reset or power button on your target CE computer).

7. Compile and run the sample programs (see Section 3.4 that describes how to check your installation) to make sure that WinDriver CE is loaded and is functioning correctly.

3.2.3  Installing WinDriver for Linux

Preparing the System for Installation

In Linux, Kernel modules must be compiled with the identical header files that the kernel itself was compiled with. Since WinDriver installs the Kernel module windrvr.o, it must compile with the header files of the Linux kernel during the installation process.

Therefore, before you install WinDriver for Linux, verify that the Linux source code and the file versions.h are installed on your machine:

Install linux kernel source code

• If you have yet to install Linux, please choose Custom installation when performing the installation and then choose to install the source code.

• If Linux is already installed on the machine, you must check to see if the Linux source code was installed. You can do this by looking for linux in the /usr/src directory. If the source code is not installed, you can either reinstall Linux with the source code, as described above, or you can install the source code by following these steps:
  1. Login as super user.

  2. Type:
     /$ rpm -i /<source location>/ <Linux distributor>/RPMS/kernel-source-<version number>
     (For example: to install the source code from the Linux installation CD-Rom, for RedHat 7.1, type:
     /$ rpm -i /mnt/cdrom/RedHat/RPMS/
     kernel-source-2.4.2.-2.i386rpm)

     TIP! If you do not have a RPM with the source code you may download it from the following link: http://rpmfind.net/linux/RPM/.

• The file version.h is created when you first compile the Linux kernel source code. Some distributions provide a compiled kernel without the file version.h. Look under /usr/src/linux/include/linux/ to check if you have this file. If you do not, please follow these steps:
  1. Type:
     /$ make xconfig
  2. Save the configuration by choosing Save and Exit.
  3. Type:
     /$ make dep.

Installation

1. Insert the WinDriver CD into your Linux machine CD drive or copy the downloaded file to your preferred directory.

2. Change directory to your preferred installation directory (for example, your home directory):
   /$ cd ~

3. Extract the file WDxxxLN.tgz (where xxx is the version number):
   ~$ tar xvzf /<file location>/WDxxxLN.tgz
   For example:
   
   • From a CD:
     ~$ tar xvzf /mnt/cdrom/LINUX/WDxxxLN.tgz
     
   • From a downloaded file:
     ~$ tar xvzf /home/username/WDxxxLN.tgz

4. Change directory to WinDriver (this directory gets created by tar):
   ~$ cd WinDriver/

   NOTE: In V5.x, this directory gets created by tar, but in versions preceding 5.x, the WinDriver directory does not get created by the extraction. Therefore when working with versions preceding 5.x (for example: version 4.33), first create a directory (e.g., WinDriver) before proceeding with the installation. (/$ mkdir ~/WinDriver)

5. Install WinDriver:
   1. ~/WinDriver$ make
   2. Become super user:
      ~/WinDriver$ su
   3. Install the driver:
      ~/WinDriver# make install

6. Create a symbolic link so that you can easily launch the DriverWizard GUI
   ~/WinDriver$ ln -s TILDE/WinDriver/wizard/wdwizard/ usr/bin/wdwizard

7. Change the read and execute permissions on the file wdwizard so that ordinary users can access this program.

8. Change the user and group ids and give read/write permissions to the device file /dev/windrvr depending on how you wish to allow users to access hardware through the device.

9. You can now start using WinDriver to access your hardware and generate your driver code!

In order to register your copy of WinDriver with the license you have received from Jungo, please follow the steps bellow:

1. Activate the DriverWizard GUI:
   ~/WinDriver/wizard$ ./wdwizard
2. Select the Register WinDriver option from the File menu and insert the license string you received from Jungo.
3. Press Activate License button.
4. To register source code you have developed during the evaluation period, please refer to WD_License function reference in section A.1.9.

Restricting Hardware Access on Linux

3.2.4  Installing WinDriver for Solaris

Since WinDriver installation installs the Kernel module windrvr.o, it should be installed by the system administrator logged in as root, or with root privileges.

1. Insert your CD into your Solaris machine CD drive or copy the downloaded file to your preferred directory.

2. Change directory to preferred installation directory, (for example, your home directory):
   /$ cd ~

3. Copy the file WDxxxSLS.tgz (Sparc) or WDxxxSL.tgz (Intel) to the current directory (here "xxx" stands for the version number, for example 500):
   ~$ cp /home/username /WDxxxSL.tgz /

   NOTE: When installing WinDriver for Solaris x86 use WDxxxSL.tgz instead of WDxxxSLS.tgz.

4. Extract the file:
   ~$ gunzip -c WDxxxSLS.tgz | tar -xvf WDxxxSLS.tar

5. Change directory to WinDriver.
   

   CAUTION: In V5.x this directory gets created by tar but in versions preceding 5.x, the WinDriver directory does not get created by the extraction. Therefore with older versions like 4.3, first create a directory (say WinDriver) before proceeding with the installation.

6. Install WinDriver for Solaris
   ~/WinDriver$ ./ install_windrvr

7. Create a symbolic link so that you can easily launch the DriverWizard GUI
   ~/WinDriver$ ln -s TILDE/WinDriver/wizard/wdwizard /usr/bin/wdwizard

8. Change the read and execute permissions on the file wdwizard so that ordinary users can access this program

9. Change the user and group ids and give read/write permissions to the device file /dev/windrvr depending on how you wish to allow users to access hardware through the device.

10. You can now start using WinDriver to access your hardware and generate your driver code!

In order to register your copy of WinDriver with the license you have received from Jungo, please follow the steps bellow:

1. Activate the DriverWizard GUI
   ~/WinDriver/wizard$ ./wdwizard

2. Select the Register WinDriver option from the File menu and insert the license string you received from Jungo.
3. Press Activate License button.

4. To register source code you have developed during the evaluation period, please refer to WD_License function reference in section A.1.9.

Restricting Hardware Access on Solaris

Solaris Platform Specific Issues

WinDriver for Solaris supports version 2.6, 7.0 and 8.0 on Intel X86 and Sparc. The same WinDriver based hardware access code will run on both platforms after recompilation.

WinDriver does not support Solaris 7.0 or 8.0 64 bit kernel. To switch from a 64 bit kernel to a 32 bit kernel follow these simple steps:

1. Reboot the computer (as s