Windows Driver Kit: WDM Devices
USB Bulk Transfer Driver Sample
Description
The BulkUSB driver sample is a generic function driver based on the Microsoft Windows Driver Model (WDM). This sample supports Plug and Play (PnP), Power Management (PM), Windows Management Instrumentation (WMI), and the selective suspend (SS) features.
This sample is based off the selSusp Windows Driver Kit (WDK) sample. For more information about how to handle PnP, PM, WMI, and SS features and implementations, see the selSusp sample and the WDK documentation.
The USB device that is used for this sample is a generic Intel I82930 USB evaluation board that is programmed with a simple loopback test by using a 64 KB circular buffer. None of the code in the sample is specific to this controller chip.
The Bulkusb.sys driver is a minidriver that transfers asynchronous bulk data packets to and from this board. The USB Request Blocks (URBs) allow an abstracted chip-independent transfer to and from the core USB stack. The sample also consists of a console application.
Theory of Operation
The following table describes Bulkusb read and write operations.
Requests | Dispatch routines |
IRP_MJ_CREATE | BulkUsb_DispatchCreate() |
IRP_MJ_CLOSE | BulkUsb_DispatchClose() |
IRP_MJ_READ | BulkUsb_DispatchReadWrite() |
IRP_MJ_WRITE | BulkUsb_DispatchReadWrite() |
The BulkUsb_DispatchCreate routine enables user-mode applications to open handles to the device or to a specific pipe.
Pipe #3 and pipe #4 correspond to the bulk IN and bulk OUT pipes on the I82930 board respectively. The driver does not hard-code the pipe number for read and write requests.
The BulkUsb_DispatchClose routine closes an open handle to a specific pipe and the device.
The BulkUsb_DispatchReadWrite routine transforms the original read/write request into an internal device control request, creates and initializes an URB for this request, and sets a completion routine for this request (BulkUsb_ReadWriteCompletion). The amount of data that is transferred is limited by the BULKUSB_MAX_TRANSFER_SIZE (64 KB circular buffer limitation). For additional data transfers, the request (Irp/Urb pair) is re-initialized and resubmitted in the completion routine.
Because the driver does not save the read/write context information anywhere in the driver, but passes it along to the completion routine, the driver is multi-threaded safe.
Please refer to the detailed inline comments in the BulkUSB driver for implementation details.
The Rwbulk.exe console application is used to initiate bulk transfers and obtain a dump of information on the device's I/O endpoints. The application also demonstrates how to use GUID-based device names and pipe names that the operating system generates by using the SetupDiXxx user-mode APIs.
Implementation and Design
This sample should be used as a template for creating a USB function driver that utilizes BULK transfers.
Building the Sample
The contained source files will build a single binary,
Bulkusb.sys.
Installation
General
Make an OEM installation diskette or equivalent installation source directory for Bulkusb.sys by copying Bulkusb.sys and Bulkusb.inf into the disk. The sample BulkUsb.inf file is in the WDK BulkUsb\Sys source directory.
Make sure your device has been programmed with the device VID/PID in the Bulkusb.inf file. If not, edit the device VID, PID, and description text to match your test board/device.
When you plug in the device, the Found New Hardware Wizard dialog box appears with the subheading Install Hardware Device Drivers.
Select Search for a suitable driver for your device (Recommended) and then click Next. The following screen asks you to specify your installation source floppy or directory.
Specify your installation location, and then click Next. The operating system is ready to install the driver.
Make sure there is a full source path to BulkUsb.inf, and click Next. You will briefly see a "Copying Files" message box.
When the Found New Hardware Wizard dialog box appears, displaying a message that the installation is complete, click Finish.
You should now have a copy of BulkUsb.sys in your \System32\Drivers directory, a BulkUsb.inf file in your \Winnt\Inf directory, and a newly-created BulkUsb.pnf file, which is a precompiled setup information file that the operating system creates. If during installation you receive an error, or if the operating system says you must restart to finish installation of this device, something has gone wrong.
Alternate Installation
REGISTRY OVERRIDES
BulkUsb.inf is in the Sys subdirectory. You can set registry overrides for:
- "DebugLevel" debug verbosity level, where 0 == no debug output, 1 == default, higher == more verbose.
- "MaximumTransferSize" The 'chunk size' (default 4k) large IO requests are broken up by the driver.
Code Tour
File Manifest
| File | Description |
|---|
| Bulkdev.c | Dispatch routines for create, close, and selective suspend. |
| Bulkdev.h | Definitions for functions contained in Bulkdev.c. |
| Bulkpnp.c | PnP dispatch and handler routines. |
| Bulkpnp.h | Definitions for PnP dispatch and handler routines. |
| Bulkpwr.c | WDM power dispatch and handler routines. |
| Bulkpwr.h | Definitions for power dispatch and handler routines. |
| Bulkrwr.c | Functions that handle USB bulk transfers to a device. |
| Bulkrwr.h | Definitions for functions that handle USB bulk transfers. |
| Bulkusb.c | DriverEntry, AddDevice, and core initialization functions. |
| Bulkusb.h | Core definitions used by the driver. |
| Bulkusb.inf | Sample INF file to install the driver. |
| Bulkusb.mof | MOF file to define WMI data structures. |
| Bulkusb.rc | Resource file for driver. |
| Bulkusr.h | Definitions for user-mode DEVICE_CONTROL interfaces. |
| Bulkwmi.c | Handler functions for SYSTEM_CONTROL(WMI) requests. |
| Bulkwmi.h | Definitions for functions in Bulkwmi.c. |
| sources | Sources file to build the sample. |
Build machine: CAPEBUILD