WinDriver™ PCI/ISA/CardBus User's Manual

Version 11.4.0

Jungo Connectivity Ltd.

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. How Fast Can WinDriver Go?
1.4. Conclusion
1.5. WinDriver Benefits
1.6. WinDriver Architecture
1.7. What Platforms Does WinDriver Support?
1.8. Limitations of the Different Evaluation Versions
1.9. How Do I Develop My Driver with WinDriver?
1.9.1. On Windows and Linux
1.9.2. On Windows CE
1.10. What Does the WinDriver Toolkit Include?
1.10.1. WinDriver Modules
1.10.2. Utilities
1.10.3. Enhanced Chipset Support
1.10.4. Samples
1.11. 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. VxD Drivers
2.3.3. Unix Device Drivers
2.3.4. 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. Installing WinDriver
3.1. System Requirements
3.1.1. Windows System Requirements
3.1.2. Windows CE System Requirements
3.1.3. Linux System Requirements
3.2. WinDriver Installation Process
3.2.1. Windows WinDriver Installation Instructions
3.2.2. Windows CE WinDriver Installation Instructions Installing WinDriver CE when Building New CE-Based Platforms Installing WinDriver CE when Developing Applications for Windows CE Computers Windows CE Installation Note
3.2.3. Linux WinDriver Installation Instructions Preparing the System for Installation Installation Installation using a Debian or RPM Installation Package Manual Installation Registering Your WinDriver License Restricting Hardware Access on Linux
3.3. Upgrading Your Installation
3.4. Checking Your Installation
3.4.1. Windows and Linux Installation Check
3.4.2. Windows CE Installation Check
3.5. Uninstalling WinDriver
3.5.1. Windows WinDriver Uninstall Instructions
3.5.2. Linux WinDriver Uninstall Instructions
4. Using DriverWizard
4.1. An Overview
4.2. DriverWizard Walkthrough
4.2.1. Automatic Code Generation Generating the Code The Generated PCI/PCMCIA/ISA C Code
4.2.2. Compiling the Generated Code Windows and Windows CE Compilation Linux Compilation
5. Developing a Driver
5.1. Using DriverWizard to Build a Device Driver
5.2. Writing the Device Driver Without DriverWizard
5.2.1. Include the Required WinDriver Files
5.2.2. Write Your Code
5.2.3. Configure and Build Your Code
5.3. Developing Your Driver on Windows CE Platforms
6. Debugging Drivers
6.1. User-Mode Debugging
6.2. Debug Monitor
6.2.1. The wddebug_gui Utility Running wddebug_gui for a Renamed Driver
6.2.2. The wddebug Utility Console-Mode wddebug Execution Windows CE GUI wddebug Execution
7. Enhanced Support for Specific Chipsets
7.1. Overview
7.2. Developing a Driver Using the Enhanced Chipset Support
8. PCI Express
8.1. PCI Express Overview
8.2. WinDriver for PCI Express
9. Advanced Issues
9.1. Performing Direct Memory Access (DMA)
9.1.1. Implementing Scatter/Gather DMA
9.1.2. Implementing Contiguous-Buffer DMA Preallocating Contiguous DMA Buffers on Windows
9.2. Handling Interrupts
9.2.1. Interrupt Handling — Overview
9.2.2. WinDriver Interrupt Handling Sequence
9.2.3. Determining the Interrupt Types Supported by the Hardware
9.2.4. Determining the Interrupt Type Enabled for a PCI Card
9.2.5. Setting Up Kernel-Mode Interrupt Transfer Commands Interrupt Mask Commands Sample WinDriver Transfer Commands Code
9.2.6. WinDriver MSI/MSI-X Interrupt Handling Windows MSI/MSI-X Device INF Files
9.2.7. Sample User-Mode WinDriver Interrupt Handling Code
9.2.8. Interrupts on Windows CE Improving Interrupt Latency on Windows CE
9.3. Byte Ordering
9.3.1. Introduction to Endianness
9.3.2. WinDriver Byte Ordering Macros
9.3.3. Macros for PCI Target Access
9.3.4. Macros for PCI Master Access
10. Improving Performance
10.1. Overview
10.1.1. Performance Improvement Checklist
10.2. Improving the Performance of a User-Mode Driver
10.2.1. Using Direct Access to Memory-Mapped Regions
10.2.2. Block Transfers and Grouping Multiple Transfers
10.2.3. Performing 64-Bit Data Transfers
11. Understanding the Kernel PlugIn
11.1. Background
11.2. Do I Need to Write a Kernel PlugIn Driver?
11.3. What Kind of Performance Can I Expect?
11.4. Overview of the Development Process
11.5. The Kernel PlugIn Architecture
11.5.1. Architecture Overview
11.5.2. WinDriver's Kernel and Kernel PlugIn Interaction
11.5.3. Kernel PlugIn Components
11.5.4. Kernel PlugIn Event Sequence Opening a Handle from the User Mode to a Kernel PlugIn Driver Handling User-Mode Requests from the Kernel PlugIn Interrupt Handling — Enable/Disable and High Interrupt Request Level Processing Interrupt Handling — Deferred Procedure Calls Plug-and-Play and Power Management Events
11.6. How Does Kernel PlugIn Work?
11.6.1. Minimal Requirements for Creating a Kernel PlugIn Driver
11.6.2. Kernel PlugIn Implementation Before You Begin Write Your KP_Init Function Write Your KP_Open Function(s) Write the Remaining PlugIn Callbacks
11.6.3. Sample/Generated Kernel PlugIn Driver Code Overview
11.6.4. Kernel PlugIn Sample/Generated Code Directory Structure pci_diag and kp_pci Sample Directories The Generated DriverWizard Kernel PlugIn Directory
11.6.5. Handling Interrupts in the Kernel PlugIn Interrupt Handling in the User Mode (Without the Kernel PlugIn) Interrupt Handling in the Kernel (Using the Kernel PlugIn)
11.6.6. Message Passing
12. Creating a Kernel PlugIn Driver
12.1. Determine Whether a Kernel PlugIn is Needed
12.2. Prepare the User-Mode Source Code
12.3. Create a New Kernel PlugIn Project
12.4. Open a Handle to the Kernel PlugIn
12.5. Set Interrupt Handling in the Kernel PlugIn
12.6. Set I/O Handling in the Kernel PlugIn
12.7. Compile Your Kernel PlugIn Driver
12.7.1. On Windows
12.7.2. On Linux
12.8. Install Your Kernel PlugIn Driver
12.8.1. On Windows
12.8.2. On Linux
13. Dynamically Loading Your Driver
13.1. Why Do You Need a Dynamically Loadable Driver?
13.2. Windows Dynamic Driver Loading
13.2.1. Windows Driver Types
13.2.2. The wdreg Utility WDM Drivers Non-WDM Drivers
13.2.3. Dynamically Loading/Unloading windrvr6.sys INF Files
13.2.4. Dynamically Loading/Unloading Your Kernel PlugIn Driver
13.3. Linux Dynamic Driver Loading
13.3.1. Dynamically Loading/Unloading Your Kernel PlugIn Driver
13.4. Windows CE Dynamic Driver Loading
14. Distributing Your Driver
14.1. Getting a Valid License for WinDriver
14.2. Windows Driver Distribution
14.2.1. Preparing the Distribution Package
14.2.2. Installing Your Driver on the Target Computer
14.2.3. Installing Your Kernel PlugIn on the Target Computer
14.3. Windows CE Driver Distribution
14.3.1. Distribution to New Windows CE Platforms
14.3.2. Distribution to Windows CE Computers
14.4. Linux Driver Distribution
14.4.1. Preparing the Distribution Package Kernel Module Components User-Mode Hardware Control Application or Shared Object
14.4.2. Building and Installing the WinDriver Driver Module on the Target
14.4.3. Building and Installing Your Kernel PlugIn Driver on the Target
14.4.4. Installing the User-Mode Hardware Control Application or Shared Object
15. Driver Installation — Advanced Issues
15.1. Windows INF Files
15.1.1. Why Should I Create an INF File?
15.1.2. How Do I Install an INF File When No Driver Exists?
15.1.3. How Do I Replace an Existing Driver Using the INF File?
15.2. Renaming the WinDriver Kernel Driver
15.2.1. Windows Driver Renaming
15.2.2. Linux Driver Renaming
15.3. Windows Digital Driver Signing and Certification
15.3.1. Overview Authenticode Driver Signature Windows Certification Program
15.3.2. Driver Signing and Certification of WinDriver-Based Drivers HCK Test Notes
15.4. Windows XP Embedded WinDriver Component
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. API Reference
B.1. WD_DriverName
B.2. WDC Library Overview
B.3. WDC High-Level API
B.3.1. Structures, Types and General Definitions
B.3.1.2. WDC_DRV_OPEN_OPTIONS Definitions
B.3.1.3. WDC_DIRECTION Enumeration
B.3.1.4. WDC_ADDR_MODE Enumeration
B.3.1.5. WDC_ADDR_RW_OPTIONS Enumeration
B.3.1.6. WDC_ADDR_SIZE Definitions
B.3.1.7. WDC_SLEEP_OPTIONS Definitions
B.3.1.8. WDC_DBG_OPTIONS Definitions
B.3.1.9. WDC_SLOT_U Union
B.3.1.10. WDC_PCI_SCAN_RESULT Structure
B.3.1.11. WDC_PCMCIA_SCAN_RESULT Structure
B.3.2. WDC_DriverOpen()
B.3.3. WDC_DriverClose()
B.3.4. WDC_PciScanDevices()
B.3.5. WDC_PciScanDevicesByTopology()
B.3.6. WDC_PciScanRegisteredDevices()
B.3.7. WDC_PcmciaScanDevices()
B.3.8. WDC_PciGetDeviceInfo()
B.3.9. WDC_PcmciaGetDeviceInfo()
B.3.10. WDC_PciDeviceOpen()
B.3.11. WDC_PcmciaDeviceOpen()
B.3.12. WDC_IsaDeviceOpen()
B.3.13. WDC_PciDeviceClose()
B.3.14. WDC_PcmciaDeviceClose()
B.3.15. WDC_IsaDeviceClose()
B.3.16. WDC_CardCleanupSetup()
B.3.17. WDC_KernelPlugInOpen()
B.3.18. WDC_CallKerPlug()
B.3.19. WDC_ReadMemXXX()
B.3.20. WDC_WriteMemXXX()
B.3.21. WDC_ReadAddrXXX()
B.3.22. WDC_WriteAddrXXX()
B.3.23. WDC_ReadAddrBlock()
B.3.24. WDC_WriteAddrBlock()
B.3.25. WDC_MultiTransfer()
B.3.26. WDC_AddrSpaceIsActive()
B.3.27. WDC_PciReadCfgBySlot()
B.3.28. WDC_PciWriteCfgBySlot()
B.3.29. WDC_PciReadCfg()
B.3.30. WDC_PciWriteCfg()
B.3.31. WDC_PciReadCfgBySlotXXX()
B.3.32. WDC_PciWriteCfgBySlotXXX()
B.3.33. WDC_PciReadCfgXXX()
B.3.34. WDC_PciWriteCfgXXX()
B.3.35. WDC_PcmciaReadAttribSpace()
B.3.36. WDC_PcmciaWriteAttribSpace()
B.3.37. WDC_PcmciaSetWindow()
B.3.38. WDC_PcmciaSetVpp()
B.3.39. WDC_DMAContigBufLock()
B.3.40. WDC_DMASGBufLock()
B.3.41. WDC_DMABufUnlock()
B.3.42. WDC_DMASyncCpu()
B.3.43. WDC_DMASyncIo()
B.3.44. WDC_SharedBufferAlloc()
B.3.45. WDC_SharedBufferFree()
B.3.46. WDC_IntEnable()
B.3.47. WDC_IntDisable()
B.3.48. WDC_IntIsEnabled()
B.3.49. WDC_EventRegister()
B.3.50. WDC_EventUnregister()
B.3.51. WDC_EventIsRegistered()
B.3.52. WDC_SetDebugOptions()
B.3.53. WDC_Err()
B.3.54. WDC_Trace()
B.3.55. WDC_GetWDHandle()
B.3.56. WDC_GetDevContext()
B.3.57. WDC_GetBusType()
B.3.58. WDC_Sleep()
B.3.59. WDC_Version()
B.4. WDC Low-Level API
B.4.1. WDC_ID_U Union
B.4.2. WDC_ADDR_DESC Structure
B.4.3. WDC_DEVICE Structure
B.4.6. WDC_ADDR_IS_MEM Macro
B.4.10. WDC_INT_IS_MSI Macro
B.4.12. WDC_IS_KP Macro
B.5. WD_xxx Structures, Types and General Definitions
B.5.1. WD_BUS_TYPE Enumeration
B.5.2. ITEM_TYPE Enumeration
B.5.3. WD_PCMCIA_ACC_SPEED Enumeration
B.5.4. WD_PCMCIA_ACC_WIDTH Enumeration
B.5.5. WD_PCMCIA_VPP Enumeration
B.5.6. WD_PCI_ID Structure
B.5.7. WD_PCMCIA_ID Structure
B.5.8. WD_PCI_SLOT Structure
B.5.9. WD_PCMCIA_SLOT Structure
B.5.10. WD_ITEMS Structure
B.5.11. WD_CARD Structure
B.5.12. WD_PCI_CARD_INFO Structure
B.5.13. WD_PCMCIA_CARD_INFO Structure
B.5.14. WD_DMA Structure
B.5.15. WD_TRANSFER Structure
B.6. Kernel PlugIn Kernel-Mode Functions
B.6.1. KP_Init
B.6.2. KP_Open
B.6.3. KP_Close
B.6.4. KP_Call
B.6.5. KP_Event
B.6.6. KP_IntEnable
B.6.7. KP_IntDisable
B.6.8. KP_IntAtIrql
B.6.9. KP_IntAtDpc
B.6.10. KP_IntAtIrqlMSI
B.6.11. KP_IntAtDpcMSI
B.6.13. Kernel PlugIn Synchronization APIs
B.6.13.1. Kernel PlugIn Synchronization Types
B.6.13.2. kp_spinlock_init()
B.6.13.3. kp_spinlock_wait()
B.6.13.4. kp_spinlock_release()
B.6.13.5. kp_spinlock_uninit()
B.6.13.6. kp_interlocked_init()
B.6.13.7. kp_interlocked_uninit()
B.6.13.8. kp_interlocked_increment()
B.6.13.9. kp_interlocked_decrement()
B.6.13.10. kp_interlocked_add()
B.6.13.11. kp_interlocked_read()
B.6.13.12. kp_interlocked_set()
B.6.13.13. kp_interlocked_exchange()
B.7. Kernel PlugIn Structure Reference
B.7.4. KP_INIT
B.8. User-Mode Utility Functions
B.8.1. Stat2Str
B.8.2. get_os_type
B.8.3. ThreadStart
B.8.4. ThreadWait
B.8.5. OsEventCreate
B.8.6. OsEventClose
B.8.7. OsEventWait
B.8.8. OsEventSignal
B.8.9. OsEventReset
B.8.10. OsMutexCreate
B.8.11. OsMutexClose
B.8.12. OsMutexLock
B.8.13. OsMutexUnlock
B.8.14. PrintDbgMessage
B.8.15. WD_LogStart
B.8.16. WD_LogStop
B.8.17. WD_LogAdd
B.9. WinDriver Status Codes
B.9.1. Introduction
B.9.2. Status Codes Returned by WinDriver
C. Troubleshooting and Support
D. Evaluation Version Limitations
D.1. Windows WinDriver Evaluation Limitations
D.2. Windows CE WinDriver Evaluation Limitations
D.3. 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
4.1. Create or Open a WinDriver Project
4.2. Select Your Plug-and-Play Device
4.3. DriverWizard INF File Information
4.4. PCI Resources
4.5. Define Registers
4.6. Read/Write Memory and I/O
4.7. Listen to Interrupts
4.8. Define Transfer Commands for Level-Sensitive Interrupts
4.9. Code Generation Options
4.10. Additional Driver Options
6.1. Start Debug Monitor
6.2. Debug Options
6.3. wddebug Windows CE Start Log Message
6.4. wddebug Windows CE Stop Log Message
11.1. Kernel PlugIn Architecture
11.2. Interrupt Handling Without Kernel PlugIn
11.3. Interrupt Handling With the Kernel PlugIn