WinDriver™ USB User's Manual

Jungo Connectivity Ltd.

Version 12.6.0

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

Brand and product names mentioned in this document are trademarks of their respective owners and are used here only for identification purposes.


Table of Contents

1. WinDriver Overview
1.1. Introduction to WinDriver
1.2. Background
1.2.1. The Challenge
1.2.2. The WinDriver Solution
1.3. Conclusion
1.4. WinDriver Benefits
1.5. WinDriver Architecture
1.6. What Platforms Does WinDriver Support?
1.7. Limitations of the Different Evaluation Versions
1.8. How Do I Develop My Driver with WinDriver?
1.8.1. On Windows and Linux
1.9. What Does the WinDriver Toolkit Include?
1.9.1. WinDriver Modules
1.9.2. Utilities
1.9.3. Samples
1.10. Can I Distribute the Driver Created with WinDriver?
2. Understanding Device Drivers
2.1. Device Driver Overview
2.2. Classification of Drivers According to Functionality
2.2.1. Monolithic Drivers
2.2.2. Layered Drivers
2.2.3. Miniport Drivers
2.3. Classification of Drivers According to Operating Systems
2.3.1. WDM Drivers
2.3.2. Unix Device Drivers
2.3.3. Linux Device Drivers
2.4. The Entry Point of the Driver
2.5. Associating the Hardware with the Driver
2.6. Communicating with Drivers
3. WinDriver USB Overview
3.1. Introduction to USB
3.2. WinDriver USB Benefits
3.3. USB Components
3.4. Data Flow in USB Devices
3.5. USB Data Exchange
3.6. USB Data Transfer Types
3.6.1. Control Transfer
3.6.2. Isochronous Transfer
3.6.3. Interrupt Transfer
3.6.4. Bulk Transfer
3.7. USB Configuration
3.8. WinDriver USB
3.9. WinDriver USB Architecture
4. Installing WinDriver
4.1. System Requirements
4.1.1. Windows System Requirements
4.1.2. Linux System Requirements
4.2. WinDriver Installation Process
4.2.1. Windows WinDriver Installation Instructions
4.2.2. Linux WinDriver Installation Instructions
4.2.2.1. Preparing the System for Installation
4.2.2.2. Installation
4.2.2.3. Restricting Hardware Access on Linux
4.3. Upgrading Your Installation
4.4. Checking Your Installation
4.4.1. Windows and Linux Installation Check
4.5. Uninstalling WinDriver
4.5.1. Windows WinDriver Uninstall Instructions
4.5.2. Linux WinDriver Uninstall Instructions
5. Using DriverWizard
5.1. An Overview
5.2. DriverWizard Walkthrough
5.2.1. Automatic Code Generation
5.2.1.1. Generating the Code
5.2.1.2. The Generated USB C Code
5.2.2. Compiling the Generated Code
5.2.2.1. Windows Compilation
5.2.2.2. Linux Compilation
6. Developing a Driver
6.1. Using DriverWizard to Build a Device Driver
6.2. Writing the Device Driver Without DriverWizard
6.2.1. Include the Required WinDriver Files
6.2.2. Write Your Code
6.2.3. Configure and Build Your Code
7. Debugging Drivers
7.1. User-Mode Debugging
7.2. Debug Monitor
7.2.1. The wddebug_gui Utility
7.2.1.1. Running wddebug_gui for a Renamed Driver
7.2.2. The wddebug Utility
7.2.2.1. Console-Mode wddebug Execution
8. USB Transfers
8.1. Overview
8.2. USB Control Transfers
8.2.1. USB Control Transfers Overview
8.2.1.1. Control Data Exchange
8.2.1.2. More About the Control Transfer
8.2.1.3. The Setup Packet
8.2.1.4. USB Setup Packet Format
8.2.1.5. Standard Device Request Codes
8.2.1.6. Setup Packet Example
8.2.2. Performing Control Transfers with WinDriver
8.2.2.1. Control Transfers with DriverWizard
8.2.2.2. Control Transfers with WinDriver API
8.3. Functional USB Data Transfers
8.3.1. Functional USB Data Transfers Overview
8.3.2. Single-Blocking Transfers
8.3.2.1. Performing Single-Blocking Transfers with WinDriver
8.3.3. Streaming Data Transfers
8.3.3.1. Performing Streaming with WinDriver
9. Dynamically Loading Your Driver
9.1. Why Do You Need a Dynamically Loadable Driver?
9.2. Windows Dynamic Driver Loading
9.2.1. The wdreg Utility
9.2.1.1. Overview
9.2.2. Dynamically Loading/Unloading windrvr1260.sys INF Files
9.3. Linux Dynamic Driver Loading
10. Distributing Your Driver
10.1. Getting a Valid WinDriver License
10.2. Windows Driver Distribution
10.2.1. Preparing the Distribution Package
10.2.2. Installing Your Driver on the Target Computer
10.3. Linux Driver Distribution
10.3.1. Preparing the Distribution Package
10.3.1.1. Kernel Module Components
10.3.1.2. User-Mode Hardware-Control Application or Shared Object
10.3.2. Building and Installing the WinDriver Driver Modules on the Target
10.3.3. Installing the User-Mode Hardware-Control Application or Shared Object
11. Driver Installation — Advanced Issues
11.1. Windows INF Files
11.1.1. Why Should I Create an INF File?
11.1.2. How Do I Install an INF File When No Driver Exists?
11.1.3. How Do I Replace an Existing Driver Using the INF File?
11.2. Renaming the WinDriver Kernel Driver
11.2.1. Windows Driver Renaming
11.2.2. Linux Driver Renaming
11.3. Windows Digital Driver Signing and Certification
11.3.1. Overview
11.3.1.1. Authenticode Driver Signature
11.3.1.2. Windows Certification Program
11.3.2. Driver Signing and Certification of WinDriver-Based Drivers
11.3.2.1. HCK Test Notes
A. 64-Bit Operating Systems Support
A.1. Supported 64-Bit Architectures
A.2. Support for 32-Bit Applications on 64-Bit Windows and Linux Platforms
A.3. 64-Bit and 32-Bit Data Types
B. WinDriver USB Host API Reference
B.1. WD_DriverName
B.2. WinDriver USB (WDU) Library Overview
B.2.1. Calling Sequence for WinDriver USB
B.2.2. Upgrading from the WD_xxx USB API to the WDU_xxx API
B.3. USB User Callback Functions
B.3.1. WDU_ATTACH_CALLBACK
B.3.2. WDU_DETACH_CALLBACK
B.3.3. WDU_POWER_CHANGE_CALLBACK
B.4. USB Functions
B.4.1. WDU_Init
B.4.2. WDU_SetInterface
B.4.3. WDU_GetDeviceAddr
B.4.4. WDU_GetDeviceRegistryProperty
B.4.5. WDU_GetDeviceInfo
B.4.6. WDU_PutDeviceInfo
B.4.7. WDU_Uninit
B.4.8. Single-Blocking Transfer Functions
B.4.8.1. WDU_Transfer
B.4.8.2. WDU_HaltTransfer
B.4.8.3. WDU_TransferDefaultPipe
B.4.8.4. WDU_TransferBulk
B.4.8.5. WDU_TransferIsoch
B.4.8.6. WDU_TransferInterrupt
B.4.9. Streaming Data Transfer Functions
B.4.9.1. WDU_StreamOpen
B.4.9.2. WDU_StreamStart
B.4.9.3. WDU_StreamRead
B.4.9.4. WDU_StreamWrite
B.4.9.5. WDU_StreamFlush
B.4.9.6. WDU_StreamGetStatus
B.4.9.7. WDU_StreamStop
B.4.9.8. WDU_StreamClose
B.4.10. WDU_ResetPipe
B.4.11. WDU_ResetDevice
B.4.12. WDU_SelectiveSuspend
B.4.13. WDU_Wakeup
B.4.14. WDU_GetLangIDs
B.4.15. WDU_GetStringDesc
B.5. USB Data Types
B.5.1. WD_DEVICE_REGISTRY_PROPERTY Enumeration
B.5.2. USB Structures
B.5.2.1. WDU_MATCH_TABLE Structure
B.5.2.2. WDU_EVENT_TABLE Structure
B.5.2.3. WDU_DEVICE Structure
B.5.2.4. WDU_CONFIGURATION Structure
B.5.2.5. WDU_INTERFACE Structure
B.5.2.6. WDU_ALTERNATE_SETTING Structure
B.5.2.7. WDU_DEVICE_DESCRIPTOR Structure
B.5.2.8. WDU_CONFIGURATION_DESCRIPTOR Structure
B.5.2.9. WDU_INTERFACE_DESCRIPTOR Structure
B.5.2.10. WDU_ENDPOINT_DESCRIPTOR Structure
B.5.2.11. WDU_PIPE_INFO Structure
B.6. General WD_xxx Functions
B.6.1. Calling Sequence WinDriver — General Use
B.6.2. WD_Open()
B.6.3. WD_Version()
B.6.4. WD_Close()
B.6.5. WD_Debug()
B.6.6. WD_DebugAdd()
B.6.7. WD_DebugDump()
B.6.8. WD_Sleep()
B.6.9. WD_License()
B.7. User-Mode Utility Functions
B.7.1. Stat2Str
B.7.2. get_os_type
B.7.3. ThreadStart
B.7.4. ThreadWait
B.7.5. OsEventCreate
B.7.6. OsEventClose
B.7.7. OsEventWait
B.7.8. OsEventSignal
B.7.9. OsEventReset
B.7.10. OsMutexCreate
B.7.11. OsMutexClose
B.7.12. OsMutexLock
B.7.13. OsMutexUnlock
B.7.14. PrintDbgMessage
B.7.15. WD_LogStart
B.7.16. WD_LogStop
B.7.17. WD_LogAdd
B.8. WinDriver Status Codes
B.8.1. Introduction
B.8.2. Status Codes Returned by WinDriver
B.8.3. Status Codes Returned by USBD
C. Troubleshooting and Support
D. Evaluation Version Limitations
D.1. Windows WinDriver Evaluation Limitations
D.2. Linux WinDriver Evaluation Limitations
E. Purchasing WinDriver
F. Distributing Your Driver — Legal Issues
G. Additional Documentation

List of Figures

1.1. WinDriver Architecture
2.1. Monolithic Drivers
2.2. Layered Drivers
2.3. Miniport Drivers
3.1. USB Endpoints
3.2. USB Pipes
3.3. Device Descriptors
3.4. WinDriver USB Architecture
5.1. Create a New Driver Project
5.2. Select Your Device
5.3. DriverWizard INF File Information
5.4. DriverWizard Multi-Interface INF File Information — Specific Interface
5.5. DriverWizard Multi-Interface INF File Information — Composite Device
5.6. Select Device Interface
5.7. USB Control Transfers
5.8. Listen to Pipe
5.9. Write to Pipe
5.10. Code Generation Options
7.1. Start Debug Monitor
7.2. Debug Options
8.1. USB Data Exchange
8.2. USB Read and Write
8.3. Custom Request
8.4. Request List
8.5. USB Request Log
B.1. WinDriver USB Calling Sequence
B.2. WinDriver USB Structures
B.3. WinDriver-API Calling Sequence