Windriver USB V8.01 User's Guide
Total Page:16
File Type:pdf, Size:1020Kb
WinDriver USB v8.01 User’s Guide Jungo Ltd COPYRIGHT Copyright ©1997 - 2006 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 98, Windows Me, Windows CE, Windows NT, Windows 2000, Windows XP and Windows Server 2003 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. 1 Contents Table of Contents 2 List of Figures 3 1 WinDriver Overview 4 1.1 IntroductiontoWinDriver . 4 1.2 Background .............................. 5 1.2.1 TheChallenge ........................ 5 1.2.2 TheWinDriverSolution . 6 1.3 Conclusion .............................. 6 1.4 WinDriverBenefits .......................... 7 1.5 WinDriverArchitecture . 8 1.6 WhatPlatformsDoesWinDriverSupport? . 8 1.7 LimitationsoftheDifferentEvaluationVersions . ...... 9 1.8 HowDoIDevelopMyDriverwithWinDriver? . 9 1.8.1 On Windows 98/Me/2000/XP/Server2003and Linux . 9 1.8.2 OnWindowsCE ....................... 10 1.9 WhatDoestheWinDriverToolkitInclude? . 10 1.9.1 WinDriverModules . 10 1.9.2 Utilities ............................ 11 1.9.3 WinDriver’sSpecificChipsetSupport . 12 1.9.4 Samples ........................... 12 1.10 Can I Distribute the Driver Created with WinDriver? . ..... 12 2 Understanding Device Drivers 13 2.1 DeviceDriverOverview . 13 2.2 Classification of Drivers According to Functionality . ....... 14 2.2.1 MonolithicDrivers . 14 2.2.2 LayeredDrivers .. .... .... ... .... .... .. 15 2.2.3 MiniportDrivers . 15 2.3 Classification of Drivers According to Operating Systems...... 16 2 CONTENTS 3 2.3.1 WDMDrivers ........................ 16 2.3.2 VxDDrivers ......................... 17 2.3.3 UnixDeviceDrivers . 17 2.3.4 LinuxDeviceDrivers . 17 2.4 TheEntryPointoftheDriver . 18 2.5 AssociatingtheHardwaretotheDriver . 18 2.6 CommunicatingwithDrivers . 18 3 WinDriver USB Overview 20 3.1 IntroductiontoUSB ......................... 20 3.2 WinDriverUSBBenefits . 21 3.3 USBComponents ........................... 22 3.4 DataFlowinUSBDevices . 22 3.5 USBDataExchange ......................... 24 3.6 USBDataTransferTypes . 25 3.6.1 ControlTransfer . 25 3.6.2 IsochronousTransfer . 25 3.6.3 InterruptTransfer . 26 3.6.4 BulkTransfer......................... 26 3.7 USBConfiguration .......................... 27 3.8 WinDriverUSB ............................ 29 3.9 WinDriverUSBArchitecture . 30 3.10 WhichDriversCanIWritewithWinDriverUSB? . 31 4 Installing WinDriver 32 4.1 SystemRequirements . 32 4.1.1 ForWindows98/Me . 32 4.1.2 ForWindows2000/XP/Server2003 . 32 4.1.3 ForWindowsCE ....................... 32 4.1.4 ForLinux........................... 33 4.2 WinDriverInstallationProcess . 33 4.2.1 Windows 98/Me/2000/XP/Server 2003 WinDriver InstallationInstructions . 33 4.2.2 Windows CE WinDriver Installation Instructions . 35 4.2.2.1 Installing WinDriver CE when Building New CE-basedPlatforms . 35 4.2.2.2 Installing WinDriver CE when Developing ApplicationsforCEComputers . 36 4.2.2.3 WindowsCEInstallationNote . 37 4.2.3 LinuxWinDriverInstallationInstructions . 37 4.2.3.1 PreparingtheSystemforInstallation . 37 4.2.3.2 Installation . 38 4.2.3.3 RestrictingHardwareAccessonLinux . 40 CONTENTS 4 4.3 UpgradingYourInstallation . 41 4.4 CheckingYourInstallation . 41 4.4.1 OnYourWindowsandLinuxMachines . 41 4.4.2 OnYourWindowsCEMachine . 42 4.5 UninstallingWinDriver . 43 4.5.1 OnWindows98/Me/2000/XP/Server2003 . 43 4.5.2 OnLinux ........................... 45 5 Using DriverWizard 46 5.1 AnOverview ............................. 46 5.2 DriverWizardWalkthrough . 47 5.3 DriverWizardNotes . .... .... .... ... .... .... .. 57 5.3.1 LoggingWinDriverAPICalls . 57 5.3.2 DriverWizardLogger . 57 5.3.3 AutomaticCodeGeneration . 57 5.3.3.1 GeneratingtheCode . 57 5.3.3.2 TheGeneratedUSBCCode . 57 5.3.3.3 TheGenerated Visual Basic and DelphiCode . 58 5.3.3.4 The Generated C# and Visual Basic .NET Code . 58 5.3.4 CompilingtheGeneratedCode . 58 5.3.4.1 Windows 98/Me/2000/XP/Server 2003 and WindowsCECompilation: . 58 5.3.4.2 LinuxCompilation . 58 6 Developing a Driver 59 6.1 UsingtheDriverWizardtoBuildaDeviceDriver . 59 6.2 Writing the Device Driver Without the DriverWizard . .... 60 6.2.1 IncludetheRequiredWinDriverFiles . 60 6.2.2 WriteYourCode .. .... .... ... .... .... .. 61 6.3 DevelopingYourDriveronWindowsCEPlatforms . 62 6.4 DevelopinginVisualBasicandDelphi . 63 6.4.1 UsingDriverWizard . 63 6.4.2 Samples ........................... 63 6.4.3 CreatingyourDriver . 63 7 Debugging Drivers 64 7.1 User-ModeDebugging . 64 7.2 DebugMonitor ............................ 64 7.2.1 UsingDebugMonitorinGraphicalMode . 65 7.2.2 UsingDebugMonitorinConsoleMode . 67 7.2.2.1 Running wddebug on Windows, Windows CE andLinux ..................... 67 CONTENTS 5 8 Enhanced Support for Specific Chipsets 69 8.1 Overview ............................... 69 8.2 Developinga DriverUsing the EnhancedChipset Support . .... 70 9 USB Control Transfers 71 9.1 USBControlTransfersOverview . 71 9.1.1 USBDataExchange . 71 9.1.2 MoreAbouttheControlTransfer . 72 9.1.3 TheSetupPacket . 73 9.1.4 USBSetupPacketFormat . 74 9.1.5 StandardDeviceRequestCodes . 75 9.1.6 SetupPacketExample . 75 9.2 PerformingControlTransferswithWinDriver . ... 77 9.2.1 ControlTransferswithDriverWizard . 77 9.2.2 ControlTransferswithWinDriverAPI . 79 10 Dynamically Loading Your Driver 80 10.1 WhyDoYouNeedaDynamicallyLoadableDriver? . 80 10.2 Windows98/Me/2000/XP/Server2003 . 80 10.2.1 WindowsDriverTypes . 80 10.2.2 TheWDREGUtility . 81 10.2.3 Dynamically Loading/Unloading windrvr6.sys INF Files . 82 10.3 Linux ................................. 83 11 Distributing Your Driver 84 11.1 GettingaValidLicenseforWinDriver . 84 11.2 Windows98/Me/2000/XP/Server2003 . 85 11.2.1 PreparingtheDistributionPackage . 85 11.2.2 InstallingYourDriverontheTargetComputer . 86 11.3 CreatinganINFFile .... .... .... ... .... .... .. 89 11.3.1 WhyShouldICreateanINFFile? . 89 11.3.2 HowDo IInstallan INF File When No DriverExists? . 90 11.3.3 How Do I Replace an Existing Driver Using the INF File? . 91 11.4 WindowsCE ............................. 94 11.5 Linux ................................. 95 11.5.1 WinDriverKernelModule . 95 11.5.2 User-Mode Hardware Control Application/Shared Objects . 96 11.5.3 InstallationScript . 96 12 WinDriver USB Device 97 12.1 WinDriverUSBDeviceOverview . 97 12.2 SystemandHardwareRequirements . 100 12.3 WinDriver Device Firmware (WDF) Directory Overview . .... 101 CONTENTS 6 12.3.1 ThecypressDirectory . 101 12.3.2 ThemicrochipDirectory . 102 12.3.3 ThephilipsDirectory . 105 12.3.4 ThesilabsDirectory . 107 12.3.5 TheWinDriverUSBDeviceFirmwareLibraries . 108 12.3.6 BuildingtheSampleCode . 109 12.4 WinDriverUSBDeviceDevelopmentProcess . 111 12.4.1 DefinetheDeviceUSBInterface . 111 12.4.1.1 EZ-USB EndpointBuffers Configuration . 117 12.4.2 GenerateDeviceFirmwareCode . 118 12.4.3 DeveloptheDeviceFirmware . 120 12.4.3.1 The Generated DriverWizard USB Device FirmwareFiles . 121 12.4.3.2 Build the Generated DriverWizard Firmware . 123 12.4.3.3 DownloadtheFirmwaretotheDevice . 124 12.4.4 DiagnoseandDebugYourHardware . 125 12.4.5 DevelopaUSBDeviceDriver . 125 A WinDriver USB PC Host API Reference 126 A.1 WinDriverUSB(WDU)LibraryOverview . 126 A.1.1 CallingSequenceforWinDriverUSB . 127 A.1.2 Upgrading from the WD_xxx USB API to the WDU_xxx API .............................. 130 A.2 USBUserCallbackFunctions . 131 A.2.1 WDU_ATTACH_CALLBACK(). 131 A.2.2 WDU_DETACH_CALLBACK(). 132 A.2.3 WDU_POWER_CHANGE_CALLBACK() . 133 A.3 USBFunctions ............................ 134 A.3.1 WDU_Init().......................... 134 A.3.2 WDU_SetInterface() . 136 A.3.3 WDU_GetDeviceAddr() . 137 A.3.4 WDU_GetDeviceInfo(). 138 A.3.5 WDU_PutDeviceInfo(). 139 A.3.6 WDU_Uninit() ... .... .... ... .... .... .. 140 A.3.7 WDU_Transfer() . 141 A.3.8 WDU_Wakeup() . 144 A.3.9 WDU_TransferDefaultPipe(). 145 A.3.10 WDU_TransferBulk() . 146 A.3.11 WDU_TransferIsoch() . 147 A.3.12 WDU_TransferInterrupt() . 148 A.3.13 WDU_HaltTransfer(). 149 A.3.14 WDU_ResetPipe() . 150 A.3.15 WDU_ResetDevice() . 151 CONTENTS 7 A.3.16 WDU_GetLangIDs() . 152 A.3.17 WDU_GetStringDesc(). 154 A.4 USBStructures ............................ 156 A.4.1 WDU_MATCH_TABLE . 157 A.4.2 WDU_EVENT_TABLE . 157 A.4.3 WDU_DEVICE ....................... 158 A.4.4 WDU_CONFIGURATION. 158 A.4.5 WDU_INTERFACE . 159 A.4.6 WDU_ALTERNATE_SETTING. 159 A.4.7 WDU_DEVICE_DESCRIPTOR . 160 A.4.8 WDU_CONFIGURATION_DESCRIPTOR . 161 A.4.9 WDU_INTERFACE_DESCRIPTOR . 161 A.4.10 WDU_ENDPOINT_DESCRIPTOR . 162 A.4.11WDU_PIPE_INFO . 162 A.5 GeneralWD_xxxFunctions . 163 A.5.1 CallingSequenceWinDriver–GeneralUse . 163 A.5.2 WD_Open().......................... 165 A.5.3 WD_Version() ... .... .... ... .... .... .. 166 A.5.4 WD_Close() ......................... 168 A.5.5 WD_Debug() ......................... 169 A.5.6 WD_DebugAdd(). 171 A.5.7 WD_DebugDump(). 173 A.5.8 WD_Sleep() ......................... 175 A.5.9 WD_License() ... .... .... ... .... .... .. 177 A.6 User-ModeUtilityFunctions . 180 A.6.1 Stat2Str() ........................... 180 A.6.2 get_os_type() . 181 A.6.3 ThreadStart() . 182 A.6.4 ThreadWait() .... .... .... ... .... .... .. 183 A.6.5 OsEventCreate() . 184 A.6.6 OsEventClose(). 185 A.6.7 OsEventWait() . 186 A.6.8 OsEventSignal() . 187 A.6.9 OsEventReset(). 188 A.6.10 OsMutexCreate() . 189 A.6.11OsMutexClose() . 190 A.6.12OsMutexLock(). 191 A.6.13 OsMutexUnlock() . 192 A.6.14 PrintDbgMessage() . ..