Home

WinDriver™ USB User`s Manual

1. 44 Checking Your Installation o 4 4 1 Windows and Linux Installation Check 4 4 2 Windows CE Installation Check 45 Uninstalling WinDriver 4 5 1 Windows WinDriver Uninstall Instructions 4 5 2 Linux WinDriver Uninstall Instructions Using DriverWizard 5 1 AMWOVEIVIEN oor oh aaa ae 5 2 DriverWizard Walkthrough 5 3 DriverWizard Notes esana eaaa a de 5 3 1 Logging WinDriver API Calls 5 3 2 DriverWizard Logger o o 5 3 3 Automatic Code Generation o 5 3 3 1 Generating the Code 5 3 3 2 The Generated USB C Code 5 3 3 3 The Generated Visual Basic and Delphi Code 5 3 3 4 The Generated C and Visual Basic NET Code 5 3 4 Compiling the Generated Code 5 3 4 1 Windows and Windows CE Compilation 5 3 4 2 Linux Compilation 5 3 5 Bus Analyzer Integration Ellisys Visual USB Developing a Driver 6 1 Using the DriverWizard to Build a Device Driver 6 2 Writing the Device Driver Without the DriverWizard 6 2 1 Include the Required WinDriver Files 6 2 2 Write Your Code o o 6 3 Developing Your Driver on Windows CE Platforms 6 4 Developing in Visual Basic and Delphi 6 4 1 Using DriverWizard o a O42 Samples
2. Ppe lame Pipe Type Information 1 ppedxd Conto drecton in Bout packet size 64 2 ppedx82 Buk Grection in packet sze 512 Action Write to Pipe C x e Figure 5 9 Write to Pipe v You can reset input and output pipes by pressing the Reset Pipe button for the selected pipe 7 Generate the skeletal driver code a Select to generate code either via the Generate Code toolbar icon or from the Project Generate Code menu b In the Select Code Generation Options dialogue box that will appear choose the code language and development environment s for the generated code and select Next to generate the code 5 2 DriverWizard Walkthrough 69 Select Code Generation Options In which language do you want your code to be generated ANSI C Generate project makefile for MS Developer Studio 6 5 C MS Developer Studio NET 2003 C MS Developer Studio NET 2005 for x86 C MS Developer Studio NET 2005 for AMD64 C MS Developer Studio NET 2005 for Windows Mobile 5 C Microsoft eMbdedded Visual C for CE C Microsoft Platform Builder C for CE C Borland C Builder 3 C Borland C Builder 4 6 C Linux Makefile Solaris Makefile C Tornado 2 Figure 5 10 Code Generation Options c Save your project if required and click OK to open your development environment with the generated driver d Close DriverWizard 8 Compile and run the generated code
3. RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 160 B 4 8 3 WDU_TransferDefaultPipe PURPOSE e Transfers data to or from a device through the default pipe PROTOTYPE DWORD WDU_TransferDefaultPipe WDU_DEVICE HANDLE hDevice DWORD fRead DWORD dwOptions PVOID pBuffer DWORD dwBufferSize PDWORD pdwBytesTransferred PBYTE pSetupPacket DWORD dwTimeout PARAMETERS See parameters of WDU_Transfer B 4 8 1 Note that dwPipeNum is not a parameter of this function DESCRIPTION See description of WDU_Transfer B 4 8 1 RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 161 B 4 8 4 WDU_TransferBulk PURPOSE e Performs bulk data transfer to or from a device PROTOTYPE DWORD WDU_TransferBulk WDU_DEVICE HANDLE hDevice DWORD dwPipeNum DWORD fRead DWORD dwOptions PVOID pBuffer DWORD dwBufferSize PDWORD pdwBytesTransferred DWORD dwTimeout PARAMETERS See parameters of WDU_Transfer B 4 8 1 Note that pSetupPacket is not a parameter of this function DESCRIPTION See description of WDU_Transfer B 4 8 1 RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 162 B 4 8 5 WDU_Transferlsoch PURPOSE e Performs isochronous data transfer
4. when using the old WD_UsbXXX APIs The procedure for upgrading your installation on other operating systems is the same as the one described above Please check the respective installation sections for installation details 4 4 Checking Your Installation 55 4 4 Checking Your Installation 4 4 1 Windows and Linux Installation Check 1 Start DriverWizard On Windows by choosing Programs WinDriver DriverWizard from the Start menu or using the shortcut that is automatically created on your Desktop A third option for activating the DriverWizard on Windows is by running wdwizard exe from a command prompt under the wizard sub directory On Linux you can access the wizard application via the file manager under the wizard sub directory or run the wizard application via a shell 2 Make sure that your WinDriver license is installed see section 4 2 which explains how to install WinDriver If you are an evaluation version user you do not need to install a license 4 4 2 Windows CE Installation Check 1 Copy the console mode Debug Monitor utility WinDriver util wddebug lt TARGET_CPU gt wddebug exe from the host Windows machine to a directory on your target Windows CE device 2 Run the Debug Monitor with the status command on the target device wddebug exe status If the windriver installation was successful the application will display information regarding the Debug Monitor version and current status the r
5. e Adds user printouts into log file PROTOTYPE VOID DLLCALLCONV WD_LogAdd const char sFormat eae cui ca es PARAMETERS Input Output argument OT ip DESCRIPTION Format control suing Optional format arguments RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 8 WinDriver Status Codes 227 B S WinDriver Status Codes B 8 1 Introduction Most of the WinDriver functions return a status code where zero WD_STATUS_SUCCESS means success and a non zero value means failure The Stat2Str functions can be used to retrieve the status description string for a given status code The status codes and their descriptive strings are listed below B 8 WinDriver Status Codes 228 B 8 2 Status Codes Returned by WinDriver WD_READ_WRITE_CONFLICT Conflict between read and write operations WD_ZERO_PACKET_SIZE WD_INSUFFICIENT RESOURCES WD_UNKNOWN PIPE_TYPE Unknown pipe type WD_SYSTEM INTERNAL ERROR WD_RESOURCE_OVERLAP WD_DATA_MISMATCH WD_WRONG_UNIQUE_ID Wrong unique ID WD_OPERATION_ALREADY_DONE Operation already done WD_NO_LICENSE No valid license WD_USB_DESCRIPTOR_ERROR USB descriptor error E WD_NOT IMPLEMENTED Function not implemented WD_FAILED_ENABLING_INTERRUPT Failed enabling interrupt D WD_DEVICE_NOT_FOUND Incorrect WinDriver version installed WD INVALID 10CTE WD_IN TERRUPT_NOT_ENABLED Interrupt not enabled WD_SET CONFIGURATION_FAIL
6. such as the manufacturer name device name and device class directly from the wizard and let DriverWizard generate a device INF file that uses your definitions as explained in section 5 2 3 Regardless of the method used to create your device INF file in order to use your new driver module you must change the references to windrvr 6 in this file to your new driver name as explained above 12 2 Renaming the WinDriver Kernel Driver 125 3 Verify that your application calls the WD_DriverName function B 1 with your new driver name before calling any other WinDriver function Note that the sample and generated DriverWizard WinDriver applications already include a call to this function but with the default driver name windrvr6 so all you need to do is replace the driver name that is passed to the function in the code with your new driver name 4 Verify that your user mode driver project is built with the WD_DRIVER_NAME_CHANGE preprocessor flag e g DWD_DRIVER_NAME_CHANGE Note The sample and generated DriverWizard WinDriver projects makefiles already set this preprocessor flag by default 5 Install your new driver by following the instructions in section 11 2 of the manual using the modified files from your new installation directory instead of the installation files from the original WinDriver distribution 12 2 2 Linux Driver Rename Rename the Linux WinDriver kernel driver windrvr6 o ko using eithe
7. 233 CONTENTS 9 E Purchasing WinDriver 236 F Distributing Your Driver Legal Issues 237 G Additional Documentation 238 List of Figures 1 1 2 1 22 23 3 1 3 2 3 3 3 4 9 1 9 2 93 9 4 93 WinDriver Architecture s os os o o e o e 16 Monolithic Drivers gt s so o e ee ee 23 Layered Drovers e iaa ee a aha Bok a BG a A a Y 24 Miniport Drivers o 2 2 ee 25 USB Endpomts v es S sean ae ee Be be Ee ee ee Bae HS 32 USB Pipes aa wih Arad amp Bays we bos a He ey es 33 Device Descriptors ori pone EA 37 WinDriver USB Architecture 000004 41 Create or Open a WinDriver Project 61 Select Your Device sudne ue a aw GOR a ds RO a o 61 DriverWizard INF File Information 62 DriverWizard Multi Interface INF File Information Specific Interface 63 DriverWizard Multi Interface INF File Information Composite Device 64 Select Device Interface o mirar ee eE 65 USB Control Transfers 225422457 dra rea Tuy epa Tee 66 Listen to PIP e e conie a mmea ae red A 67 Writ eto PIDE eec pisa e m ma aa i i a a Be a bes 68 Code Generation Options osoo 000 69 Ellisys Visual USB Integration o e T2 Start Debug Monitor c css sera cesserena necesser 79 Debug Options s raees eteen Se A ee eS 80 USB Data Exchange 5442445 be See bead A 87 USB Read and Write 2 2 en 89 Custom Request cies Ba a Se a a a ae ae 93 Reques
8. DEVICE Device Class WinDriver s unique Class Use this option for a non standard type of device WinDriver will set a new Class type for your device This is a multi interface device Generate INF file for the root device itself Generate INF file for the following device interfaces Interface 1 Interface 0 Automatically install the INF file Note This will replace any existing driver you may have For your device Figure 5 5 DriverWizard Multi Interface INF File Information Composite Device d When you are done click Next and choose the directory in which you wish to store the generated INF file DriverWizard will then automatically generate the INF file for you On Windows 2000 XP Server 2003 Vista you can choose to automatically install the INF file from the DriverWizard by checking the Automatically Install the INF file option in the DriverWizard s INF 5 2 DriverWizard Walkthrough 65 generation dialogue this option is checked by default for USB devices On Windows 98 Me you must install the INF file manually using Windows Add New Hardware Wizard or Upgrade Device Driver Wizard as explained in section 12 1 If the automatic INF file installation on Windows 2000 XP Server 2003 Vista fails DriverWizard will notify you and provide manual installation instructions for this OS as well e wm When the INF file installation completes select and open your device
9. The hardware resources assigned to the device by the firmware in translated form WdDevicePropertyClassName The name of the device s setup OS sine oma WdDevicePropertyClassGuid The GUID for the device s O AA WdDevicePropertyDriverKeyName The name of the driver specific A pasty WdDevicePropertyManufacturer Device manufacturer string WdDevicePropertyFriendly Name Friendly device name typically defined by the class installer which can be used to distinguish between two similar devices B 5 USB Data Types 185 WdDevicePropertyLocationInformation Information about the device s Location on the bus string format The interpertation of this information is bus specific WdDevicePropertyPhysicalDeviceObjectName The name of the Physical Device Object PDO for the device WdDeviceProperty BusTypeGuid The GUID for the bus to ONES tinted comet WdDevicePropertyLegacyBusType The bus type e g PCIBus or eS pec WdDeviceProperty BusNumber The legacy bus number of the bus to which the device is connected WdDevicePropertyEnumeratorName The name of the device s enumerator e g PCI or root WdDeviceProperty Address The device s bus address The interpertation of this address is bus specific WdDeviceProperty UINumber A number associated with the device that can be displayed in the user interface WdDevicePropertyInstallState The device s installation state WdDevicePropertyRemovalPolicy The device
10. 5 3 3 2 but from a GUI NET program 5 3 4 Compiling the Generated Code 5 3 4 1 Windows and Windows CE Compilation As explained above on Windows you can select to generate project and workspace solution files for any of the supported integrated development environments IDEs MSDEV Visual C 5 6 MSDEV NET 2003 2005 Borland C Builder Visual Basic 6 0 Borland Delphi MS eMbedded Visual C or MS Platform Builder and you can also select to automatically invoke your selected IDE from the wizard You can then proceed to immediately build and run the code from your IDE You can also build the generated code from any other IDE that supports the selected code language and target OS Simply create a new project file for your selected IDE then add the generated source files to your project and compile and run the code NOTES e For Windows 98 Me 2000 XP Server 2003 Vista the generated IDE files are located under an x86 directory for 32 bit projects or amd64 directory for 64 bit projects e For Windows CE note that the generated Windows Mobile code is targeted at the Windows Mobile 5 0 6 0 ARMV4I SDK 5 3 4 2 Linux Compilation Use the makefile that was created for you by DriverWizard in order to build the generated code using your favourite compiler preferably GCC 5 3 DriverWizard Notes 72 5 3 5 Bus Analyzer Integration Ellisys Visual USB DriverWizard provides native support for the Ellisys Explorer
11. B 1 with your new driver name before calling any other WinDriver function Note that the sample and generated DriverWizard WinDriver applications already include a call to this function but with the default driver name windrvr6 so all you need to do is replace the driver name that is passed to the function in the code with your new driver name 3 Verify that your user mode driver project is built with the WD_DRIVER_NAME_CHANGE preprocessor flag DWD_DRIVER_NAME_CHANGE Note The sample and generated DriverWizard WinDriver projects makefiles already set this preprocessor flag by default 4 Install your new driver by following the instructions in section 11 4 of the manual using the modified files from the generated xxx_installation directory instead of the installation files from the original WinDriver distribution As part of the installation build your new kernel driver module by following the instructions in section 11 4 1 using the files from your new installation directory 12 2 2 2 Manually Rename the Linux Driver To manually rename the Linux WinDriver kernel driver follow these steps 1 Create a new installation directory and copy the redist lib and include directories from the original WinDriver distribution to this new directory 2 Make the following changes to the files in your copy of the redist directory a Replace any occurrences of the SDRIVER_NAMES string in the linux_wrappers c file with your new drive
12. e Use this code as a starting point for your device driver Modify where needed to perform your driver s specific functionality e The source code DriverWizard creates can be compiled with any 32 bit compiler and will run on all supported platforms without modification 5 3 DriverWizard Notes 70 5 3 DriverWizard Notes 5 3 1 Logging WinDriver API Calls You have the option to log all the WinDriver API calls using the DriverWizard with the API calls input and output parameters You can select this option by selecting the Log API calls option from the Tools menu or by clicking on the Log API calls toolbar icon in the DriverWizard s opening window 5 3 2 DriverWizard Logger The wizard logger is the empty window that opens along with the Device Resources dialogue box when you open a new project The logger keeps track of all of the input and output during the diagnostics stage so that you may analyze your device s physical performance at a later time You can save the log for future reference When saving the project your log is saved as well Each log is associated with one project 5 3 3 Automatic Code Generation After you have finished diagnosing your device and have ensured that it runs according to your specifications you are ready to write your driver 5 3 3 1 Generating the Code Generate code by selecting this option either via the DriverWizard s Generate Code toolbar icon or from the wizard s Project Generate Cod
13. from the list in the Select Your Device screen 4 Uninstall the INF file of your device You can use the Uninstall option to uninstall the INF file of your device Once you uninstall the INF file the device will no longer be registered to work with the windrvr6 sys and the INF file will be deleted from the Windows root directory If you do not need to uninstall an INF file skip this step and proceed to the next one a In the Select Your Device screen click the Uninstall INF file button b Select the INF file to be removed 5 Select the desired alternate setting Fie Tools Project Help 2 uo i ie A Active Projects Alternate Setting 2 AA sd Cypress Semiconductor Corp Product ID 1003 E Cypress Semiconductor Corp Product1D 1003 S nt Alternate Setting 0 Al Al Pipe Name Pipe Type Information 1 pipe 0x0 Control direction in amp out packet size 64 2 pipe 0x82 Buk direction in packet size 512 Alternate Setting 6 3 pipe Oxs Buk direction out packet size 512 information Panel Log Output Description Figure 5 6 Select Device Interface 5 2 DriverWizard Walkthrough 66 The DriverWizard detects all the device s supported alternate settings and displays them Select the desired alternate setting from the displayed list DriverWizard will display the pipes information for the selected alternate setting NOTE
14. s current removal policy Windows XP and later B 5 USB Data Types 186 B 5 2 USB Structures The following figure depicts the structure hierarchy used by WinDriver s USB API The arrays situated in each level of the hierarchy may contain more elements than are depicted in the diagram Arrows are used to represent pointers In the interest of clarity only one structure at each level of the hierarchy is depicted in full detail with all of its elements listed and pointers from it pictured WDU_ DEVICE Descriptor Piped i e aj pConfigs ej pActiveConfig pActivelnterface WDU_CONFIGURATION WDU_CONFIGURATION Descriptor dwNuminterfaces 21 pinterfaces WDU_CONFIGURATION WDU_INTERFACE WDU_INTERFACE pAlternateSettings dwNumAltSettings r pActiveAltSetting WDU INTERFACE WDU ALTERNATE SETTING WDU_ALTERNATE SETTING Descriptor WDU ALTERNATE SETTING WDU_ENDPOINT DESCRIPTOR WDU_PIPE_INFO bLength bDescriptorType bEndpointAddress bmAttributes wMaxPacketSize binterval dwNumber dwMaximumPacketSize type direction binterval Figure B 2 WinDriver USB Structures B 5 USB Data Types 187 B 5 2 1 WDU_MATCH_TABLE Structure USB match table structure NOTE For all field members if value is set to zero match all p gt wVendorld WORD Required USB Vendor I
15. 200 USB analyzer on Windows XP and higher 32 bit only This support enables you to e Initiate USB traffic capture directly from DriverWizard e Capture discrete control transfers To capture USB traffic 1 Select Tools Start USB Analyzer Capture to start capturing USB data 2 To finish the data capture select Tools Stop USB Analyzer Capture A dialogue box will appear notifying you where DriverWizard stored the analyzer trace Click Yes to run Ellisys s Visual Analyzer with the captured data To capture a discrete control trasfer check the Trace USB transaction in Ellisys Visual USB check box in the control transfers dialogue box Pipe 0 Control Setup Packet Write to pipe data Hex Custom request Type Request walue windex wLength 00 o 0000 o 0 00 00 00 00 00 00 00 00 Action File to Pipe Trace USB transaction in Ellisys Visual USB Figure 5 11 Ellisys Visual USB Integration Chapter 6 Developing a Driver This chapter takes you through the WinDriver driver development cycle NOTE If your device is based on one of the chipsets for which WinDriver provides enhanced support The Cypress EZ USB family Microchip PIC18F4550 Philips PDIUSBD12 Texas Instruments TUSB3410 TUSB3210 TUSB2136 and TUSB5052 Agere USS2828 Silicon Laboratories C805 1F320 read the following overview and then skip straight to Chapter 8 6 1 Using the DriverWizard to Build a Device Driver Use DriverWizard
16. A unique identifier for the stream as returned by WDU_St reamOpen pBuffer Pointer to a data buffer containing the data to write to the stream bytes Number of bytes to write to the stream pdwBytes Written Pointer to a value indicating the number of bytes actually written to the stream RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 171 B 4 9 5 WDU_StreamFlush PURPOSE e Flushes a write stream i e writes the entire contents of the stream s data buffer to the device e Blocks until the completion of all pending I O on the stream i This function can be called for both blocking and non blocking streams PROTOTYPE DWORD DLLCALLCONV WDU_StreamFlush WDU_STREAM HANDLE hStream PARAMETERS Type Input Output WDU_STREAM_HANDIE Input DESCRIPTION hStream A unique identifier for the stream as returned by WDU_StreamOpen RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 172 B 4 9 6 WDU_StreamGetStatus PURPOSE e Returns a stream s current status PROTOTYPE DWORD DLLCALLCONV WDU_StreamGetStatus WDU_STREAM_HANDLE hStream BOOL pfIsRunning DWORD pdwLastError DWORD pdwBytesInBuffer PARAMETERS Name Type Input Output WDU_STREAM_HANDLE Input gt pflsRunning BOOL Output gt pdwLastError DWORD Output gt pdwB
17. Select the Send debug messages to the operating system kernel debugger option if you want debugging messages to be sent to an external kernel debugger as well This option enables you to send to an external kernel debugger all the debug information that is received from WinDriver s kernel module Now run your application reproduce the problem and view the debug information in the external kernel debugger s log Windows users can use Microsoft s WinDbg tool for example which is freely supplied with Microsoft s Driver Development Kit DDK and from Microsoft s web site Microsoft Debugging Tools page 3 Once you have defined what you want to trace and on what level click OK to close the Debug Options window 4 Activate your program step by step or in one run 5 Watch the Debug Monitor log for errors or any unexpected messages 7 2 1 1 Running the Graphical Debug Monitor for a Renamed Driver By default the graphical Debug Monitor program wddebug_gui logs messages from the windrvr6 sys o ko driver However you can also use wddebug_gui to log debug messages from a renamed driver see explanation in section 12 2 regarding renaming the windrvr6 driver module by running wddebug_gui from the command line with the driver_name option wddebug_gui lt driver_name gt NOTE The driver name should be set to the name of the driver file without the file s extension e g windrvr6 not windrvr6 sys on Windows or
18. This section describes WinDriver s single blocking data transfer functions For more information refer to section 9 3 2 of the manual 155 B 4 USB Functions 156 B 4 8 1 WDU_Transfer PURPOSE e Transfers data to or from a device PROTOTYPE DWORD WDU_Transfer WDU_DEVICE HANDLE hDevice DWORD dwPipeNum DWORD fRead DWORD dwOptions PVOID pBuffer DWORD dwBufferSize PDWORD pdwBytesTransferred PBYTE pSetupPacket DWORD dwTimeout PARAMETERS WDU_DEVICE_HANDLE B 4 USB Functions 157 DESCRIPTION hDevice A unique meer for the device interface received from pes tinea dwPipeNum The 1 e of the pipe a which the data is TRUE ee _ read FALSE for wite dwOptions oN irae bit mask which can consist of a combination of any of the following flags USB_ISOCH_NOASAP For isochronous data transfers Setting this option instructs the lower USB stack driver usbd sys to use a preset frame number instead of the next available frame while performing the data transfer Use this flag if you notice unused frames during the transfer on low speed or full speed devices USB 1 1 only and only on Windows excluding Windows CE USB_ISOCH_RESET Resets the isochronous pipe before the data transfer It also resets the pipe after minor errors consequently allowing to transfer to continue USB_ISOCH_FULL_PACKETS_ONLY Prevents transfers of less than the packet size on isochronous pipes USB_BULK_IN
19. Trace USB transaction in Ellisys Yisual USB Figure 9 3 Custom Request 9 2 USB Control Transfers 94 e For a standard USB request select a USB request from the requests list which includes requests such as GET_DESCRIPTOR CONFIGURATION GET_DESCRIPTOR DEVICE GET_STATUS DEVICE etc see Figure 9 4 The description of the selected request will be displayed in the Request Description box on the right hand of the dialogue window 3 Pipe O Control Setup Packet Write to pipe data Hex Custom request Custom request GET_DESCRIPTOR CONFIGURATION GET_DESCRIPTOR DEVICE GET_DESCRIPTOR STRING GET_STATUS DEVICE GET_STATUS ENDPOINT GET_STATUS INTERFACE Action Write to Pipe Read from Pipe Sve ee Trace USB transaction in Ellisys Visual USB Figure 9 4 Requests List 3 The results of the transfer such as the data that was read or a relevant error are displayed in Driver Wizard s Log window Figure 9 5 below shows the contents of the Log window after a successful GET_DESCRIPTOR DEVICE request 9 2 USB Control Transfers 95 Information Panel 12 0100 02 00 00 00 40840403 10 00 00 0102 Q 0001 Log Output Description Figure 9 5 USB Request Log 9 2 2 2 Control Transfers with WinDriver API To perform a read or write transaction on the control pipe you can either use the API generated by DriverWizard for your hardware or directly call the WinDr
20. accesses your hardware by using the generic windrvr6 sys driver WinDriver s kernel module Therefore you might want to dynamically load and unload the driver windrvr6 sys which you can do using wdreg In addition in WDM compatible operating systems you also need to dynamically load INF files for your Plug and Play devices wdreg enables you to do so automatically on Windows 2000 XP Server 2003 Vista This section includes wdreg usage examples which are based on the detailed description of wdreg contained in the previous section e To start windrvr6 sys on Windows 98 Me 2000 XP Server 2003 Vista wdreg inf lt path to windrvr6 inf gt install This command loads windrvr6 inf and starts the windrvr6 sys service e To load an INF file named device inf located under the c tmp directory on Windows 2000 XP Server 2003 Vista wdreg inf c tmp device inf install On Windows 2000 XP Server 2003 Vista you can replace the install option in the example above with preinstall in order to pre install the device INF file for a device that is not currently connected to the PC To unload the driver INF file use the same commands but simply replace install in the examples above with uninstall 10 3 Linux Dynamic Driver Loading 103 10 3 Linux Dynamic Driver Loading e To dynamically load WinDriver on Linux execute sbin modprobe windrvr6 e To dynamically unload WinDriver execute sbin rmmod windrvr6 e You can also use the wdreg sc
21. as returned by WDU_St reamOpen pBuffer Pointer to a data buffer to be filled with the data read from the stream Number of bytes to read from the stream pdwBytesRead Pointer to a value indicating the number of bytes actually read from the stream RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 169 B 4 9 4 WDU_StreamWrite PURPOSE e Writes data from the applciation to a write stream For a blocking stream fBlocking TRUE see WDU_StreamOpen the call to this function is blocked until the entire data is written to the stream or until the stream s attempt to write to the device times out i e the timeout period for transfers between the stream and the device as set in the dwRxTxTimeout WDU_StreamOpen parameter B 4 9 1 expires For a non blocking stream fBlocking FALSE the function writes as much data as currently possible to the stream s data buffer and returns immediately For both blocking and non blocking transfers the function returns the amount of bytes that were actually written to the stream within the pdwBytesWritten parameter PROTOTYPE DWORD DLLCALLCONV WDU_StreamWrite HANDLE hStream const PVOID pBuffer DWORD bytes DWORD pdwBytesWritten PARAMETERS Input Output WDU_STREAM_HANDIE gt pBuffer const PVOID DWORD gt pdwBytesWritten DWORD B 4 USB Functions 170 DESCRIPTION hStream
22. cVer if ver dwVer lt WD_VER printf Error incorrect WinDriver version n B 6 General WD_xxx Functions 198 B 6 4 WD_Close PURPOSE e Closes the access to the WinDriver kernel module PROTOTYPE void WD_Close HANDLE hWD PARAMETERS Input Output HANDLE Input DESCRIPTION Description hWD Handle to WinDriver s kernel mode driver as received from WD_Open B 6 2 RETURN VALUE None REMARKS e This function must be called when you finish using WinDriver kernel module EXAMPLE WD_Close hWD B 6 General WD_xxx Functions 199 B 6 5 WD_Debug PURPOSE e Sets debugging level for collecting debug messages PROTOTYPE DWORD WD_Debug HANDLE hWD WD DEBUG pDebug PARAMETERS B 6 General WD_xxx Functions 200 DESCRIPTION Handle to WinDriver s kernel mode driver as received from WD_Open B 6 2 gt dwCmd Debug command Set filter Clear buffer etc For more details please refer to DEBUG_COMMAND in windrvr h gt dwLevel Used for dwCmd DEBUG_SET_FILTER Sets the debugging level to collect Error Warning Info Trace For more details please refer to DEBUG_LEVEL in windrvr h gt dwSection Used for dwCmd DEBUG_SET_FILTER Sets the sections to collect I O Memory Interrupt etc Use S_ALL for all For more details please refer to DEBUG_SECTION in windrvr h gt dwLevelMessageBox Used for dwCmd DEBUG_SET_FILTER Sets the debugging level to p
23. call called DeviceloControl in Windows and ioct1 in Linux In this I O control call the application specifies e The device to which the call is made by providing the device s handle e An IOCTL code that describes which function this device should perform e A buffer with the data on which the request should be performed The IOCTL code is a number that the driver and the requester agree upon for a common task The data passed between the driver and the application is encapsulated into a structure In Windows this structure is called an I O Request Packet IRP and is encapsulated by the I O Manager This structure is passed on to the device driver which may modify it and pass it down to other device drivers Chapter 3 WinDriver USB Overview This chapter explores the basic characteristics of the Universal Serial Bus USB and introduces WinDriver USB s features and architecture NOTE The references to the WinDriver USB toolkit in this chapter relate to the standard WinDriver USB toolkit for development of USB host drivers 3 1 Introduction to USB USB Universal Serial Bus is an industry standard extension to the PC architecture for attaching peripherals to the computer It was originally developed in 1995 by leading PC and telecommunication industry companies such as Intel Compaq Microsoft and NEC USB was developed to meet several needs among them the needs for an inexpensive and widespread connectivity
24. computer 4 Install your hardware control application DLL on the target If your hardware control application DLL uses wdapi920 dll as is the case for the sample and generated DriverWizard WinDriver projects also copy this DLL from the WinDriver redist WINCE lt TARGET_CPU gt directory on the development PC to the target s Windows directory 11 4 Linux Driver Distribution 114 11 4 Linux Driver Distribution 11 4 Since NOTES The Linux kernel is continuously under development and kernel data structures are subject to frequent changes To support such a dynamic development environment and still have kernel stability the Linux kernel developers decided that kernel modules must be compiled with header files identical to those with which the kernel itself was compiled They enforce this by including a version number in the kernel header files that is checked against the version number encoded into the kernel This forces Linux driver developers to facilitate recompilation of their driver based on the target system s kernel version If you have renamed the WinDriver kernel module windrvr6 0 ko as explained in section 12 2 replace the relevant windrvr6 references with the name of your driver and replace references to the WinDriver redist lib and include directories with the path to your copy of the relevant directory For example when using the generated DriverWizard renamed driver files for your driver project a
25. drivers 12 3 2 1 WHQL DTM Test Notes As indicated in the WHQL documentation before submitting the driver for testing you need to download Microsoft s Driver Test Manager DTM http www microsoft com whdc DevTools WDK DTM mspx and run the relevant tests for your hardware software After you have verified that you can successfully pass the DTM tests create the required logs package and proceed according to Microsoft s documentation When running the DTM tests note the following The DTM test class for WinDriver based drivers should be Unclassified Universal Device The Driver Verifier test is applied to all unsigned drivers found on the test machine It is therefore important to try and minimize the number of unsigned drivers installed on the test PC apart from the test driver windrvr6 sys The USB Selective Suspend test requires that the depth of the under test USB device in the USB devices tree is at least one external hub and no more than two external hubs deep The ACPI Stress test requires that the ACPI settings in the BIOS support the S3 power state Verify that the PAE switch is added to the boot flags in the PC s boot ini file 12 4 Windows XP Embedded WinDriver Component 131 e The tests submission requires you to provide a pdb debug symbol file and an ouput of the PREfast utility defects xml You can find copies of these files for the windrvr6 sys driver in the WinDriver redist directory When sel
26. file for your USB device refer to section 12 1 1 of the manual For detailed information on creation of INF files with DriverWizard refer to section 5 2 see specifically step 3 With 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 MSDEV NET Borland C Builder Borland Delphi Visual Basic 6 0 MS eMbedded Visual C MS Platform Builder C or GCC For more information regarding implementation of USB transfers with WinDriver refer to Chapter 9 of the manual 3 9 WinDriver USB Architecture 40 3 9 WinDriver USB Architecture To access your hardware your application calls the WinDriver kernel module using functions from the WinDriver USB API The high level functions utilize the low level functions which use IOCTLs to enable communication between the WinDriver kernel module and your user mode application The WinDriver kernel module accesses your USB device resources through the native operating system calls There are two layers responsible for abstracting the USB device to the USB device driver The upper layer is the USB Driver USBD layer which includes the USB Hub Driver and the USB Core Driver The lower level is the Host Controller Driver HCD layer The division of duties between the HCD and USBD layers is not defined and is operating system dependent Both the HCD and USBD are software interfaces and components
27. file that you created for the device This will prevent Windows from automatically detecting and installing an obsolete file You can search the INF directory for the device s vendor ID and device product ID to locate the file s associated with the device 11 2 Windows Driver Distribution 108 e Install WinDriver s kernel module 1 Copy windrvr6 sys windrvr6 inf and wd920 cat to the same directory NOTE wd920 cat contains the driver s Authenticode digital signature for Windows 2000 XP Server 2003 Vista In order to maintain the signature s validity this file must be found in the same installation directory as the windrvr6 inf file If you select to distribute the catalog and INF files in different directories or make any changes to these files or to any other files referred to by the catalog file such as windrvr6 sys you will need to do either of the following Create a new catalog file and re sign the driver using this file Comment out or remove the following line in the windrvr6 inf file CatalogFile wd920 cat and do not include the catalog file in your driver distribution However note that this option invalidates the driver s digital signature For more information regading driver digital signing and certification and the signing of your WinDriver based driver refer to section 12 3 of the manual 2 Use the utility wdreg wdreg16 to install WinDriver s kernel module on the target computer NO
28. gt directory is either x86 32 bit binaries for x86 platforms am64 64 bit binaries for x64 platforms or am64 x86 32 bit binaries for x64 platforms e For Windows CE WinDriver lib WINCE lt CPU gt wdapi920 lib e For Linux WinDriver lib libwdapi920 so You can also include the library s source files in your project instead of linking the project with the library The C source files are located under the WinDriver src wdapi directory NOTE When linking your project with the wdapi920 library shared object you will need to distribute the wdapi920 DLL shared object with your driver For Windows get wdapi920 dll wdapi920_32 dll for 32 bit applications targeted at 64 bit platforms from the WinDriver redist or WinDriver redist_win98_compat directory For Linux distribute WinDriver lib libwdapi920 so For details refer to the driver distribution instructions in Chapter 11 4 Add any other WinDriver source files that implement API that you which to use in your code e g files from the WinDriver samples shared directory 6 2 2 Write Your Code 1 Call WOU_Init B 4 1 at the beginning of your program to initialize WinDriver for your USB device and wait for the device attach callback The relevant device information will be provided in the attach callback 2 Once the attach callback is received you can start using one of the WDU_Transfer B 4 8 1 functions family to send and receive data 3 To finish call
29. kernel driver follow these steps 1 Create a copy of the WinDriver redist directory and modify the files in this directory as follows e Rename the windrvr6 sys and windrvr6 inf files replacing windrvr6 in the file names with your selected driver name e g my_driver Note that you must leave the sys inf file extension e Modify your copy of the windrvr6 inf file a Replace all windrvr6 occurrences in the file with the name of your new driver e g my_driver b Change the name of the driver service for the AddService key under the DriverInstall NT Services section in the INF file to your selected driver service name e g MyDriver 2 Replace any occurrences of windrvr6 in your device INF file which registers your device with the selected driver with the name of your new driver module e g my_driver You can also make additional modifications to this file if you wish such as changing the manufacturer or driver provider strings NOTE DriverWizard automatically generates a device INF for your device under the generated driver project directory The file s name is derived from the name selected for your driver project e g lt my_driver gt inf You can also generate the device INF file yourself by selecting the INF generation option from the DriverWizard s Select Your Device screen which is displayed when selecting to create a new host driver project When using this method you can set your own INF strings
30. lt command gt The Debug Monitor command to execute e Activation commands on Turn the Debug Monitor on off Turn the Debug Monitor off dbg_on Redirect the debug messages from the Debug Monitor to a kernel debugger and turn the Debug Monitor on if it was not already turned on 7 2 Debug Monitor 83 dbg_off Stop redirecting debug messages from the Debug Monitor to a kernel debugger NOTE The on and dbg_on commands can be run together with the level and or sections options described below e dump Continuously display dump debug information until the user presses Esc e status Display information regarding the running lt driver_name gt kernel module the current Debug Monitor status including the active debug level and sections when the Debug Monitor is on and the size of the debug messages buffer NOTE The following options are applicable only to the Debug Monitor on and dbg_on activation commands described above lt level gt The debug trace level to set The level can be set to either of the following flags ERROR WARN INFO or TRACE where ERROR is the lowest trace level and TRACE is the highest level displays all messages The default debug trace level is ERROR lt sections gt The debug sections to set The debug sections determine what part of the WinDriver API you would like to monitor For a full list of all supported debug sections run wddebug with no arguments t
31. of the INF file in your distribution package 12 1 INF Files Windows 98 Me 2000 XP Server 2003 Vista 119 12 1 3 How Do I Replace an Existing Driver Using the INF File NOTE You must have administrative privileges in order to replace a driver on Windows 98 Me 2000 XP Server 2003 Vista 1 On Windows 2000 if you wish to upgrade the driver for USB devices that have been registered to work with earlier versions of WinDriver we recommend that you first delete from Windows INF directory windir inf any previous INF files for the device to prevent Windows from installing an old INF file in place of the new file that you created Look for files containing your device s vendor and device IDs and delete them 2 Install your INF file e On Windows 2000 XP Server 2003 Vista you can automatically install the INF file You can use the wdreg utility with the install command to automatically install the INF file on Windows 2000 XP Server 2003 Vista wdreg inf lt path to INF file gt install for more information refer to section 10 2 2 of the manual On the development PC you can have the INF file automatically installed when selecting to generate the INF file with the DriverWizard by checking the Automatically Install the INF file option in the DriverWizard s INF generation window see section 5 2 It is also possible to install the INF file manually on Windows 2000 XP Server 2003 Vista using either of the follo
32. ports to support the connection of external devices 3 4 Data Flow in USB Devices During the operation of a USB device the host can initiate a flow of data between the client software and the device Data can be transferred between the host and only one device at a time peer to peer communication However two hosts cannot communicate directly nor can two USB 3 4 Data Flow in USB Devices 32 devices with the exception of On The Go OTG devices where one device acts as the master host and the other as the slave The data on the USB bus is transferred via pipes that run between software memory buffers on the host and endpoints on the device Data flow on the USB bus is half duplex i e data can be transmitted only in one direction at a given time An endpoint is a uniquely identifiable entity on a USB device which is the source or terminus of the data that flows from or to the device Each USB device logical or physical has a collection of independent endpoints The three USB speeds low full and high all support one bi directional control endpoint endpoint zero and 15 unidirectional endpoints Each unidirectional endpoint can be used for either inbound or outbound transfers so theoretically there are 30 supported endpoints Each endpoint has the following attributes bus access frequency bandwidth requirement endpoint number error handling mechanism maximum packet size that can be transmitted or received transfer
33. referred to as blocking streams and streams that perform non blocking transfers will be referred to as non blocking streams The function s dwRxTxTimeout parameter indicates the desired timeout period for transfers between the stream and the device After opening a stream call NDU_StreamStart B 4 9 2 to begin data transfers between the stream s data buffer and the device In the case of a read stream the driver will constantly read data from the device into the stream s buffer in blocks of a pre defined size as set in the dwRxSize parameter of the WDU_StreamOpen function B 4 9 1 In the case of a write stream the driver will constantly check for data in the stream s data buffer and write any data that is found to the device To read data from a read stream to the user mode host application call WDU_StreamRead B 4 9 3 In case of a blocking stream the read function blocks until the entire amount of data requested by the application is transferred from the stream to the application or until the stream s attempt to read data from the device times out 9 3 Functional USB Data Transfers 98 In the case of a non blocking stream the function transfers to the application as much of the requested data as possible subject to the amount of data currently available in the stream s data buffer and returns immediately To write data from the user mode host application to a write the stream call WDU_StreamWr
34. solution for peripherals in general and for computer telephony integration in particular an easy to use and flexible method of reconfiguring the PC and a solution for adding a large number of external peripherals The USB standard meets these needs The USB specification allows for the connection of a maximum of 127 peripheral devices including hubs to the system either on the same port or on different ports USB also supports Plug and Play installation and hot swapping The USB 1 1 standard supports both isochronous and asynchronous data transfers and has dual speed data transfer 1 5 Mb s megabits per second for low speed USB devices and 12 Mb s for high speed USB devices much faster than the original serial 29 3 2 WinDriver USB Benefits 30 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 up to 500 mA of current to devices attached on the bus The USB 2 0 standard supports a signalling rate of 480 Mb s known as high speed which is 40 times faster than the USB 1 1 full speed transfer rate USB 2 0 is fully forward and backward compatible with USB 1 1 and uses existing cables and connectors USB 2 0 supports connections with PC peripherals that provide expanded functionality and require wider bandwidth In addition it can handle a larger number of peripherals simultaneously USB 2 0 enha
35. to diagnose your device View the device s configuration information transfer data on the device s pipes send standard requests to the control pipe and reset the pipes Verify that your device operates as expected Use DriverWizard to generate skeletal code for your device in C C Visual Basic NET Delphi or Visual Basic For more information about DriverWizard refer to Chapter 5 If you are using one of the specific chipsets for which WinDriver offers enhanced support The Cypress EZ USB family Microchip PIC18F4550 Philips PDIUSBD12 Texas Instruments TUSB3410 TUSB3210 TUSB2136 and TUSB5052 Agere USS2828 Silicon Laboratories C805 1F320 we recommend that you use the specific sample code provided for your chip as your skeletal driver code For more details regarding WinDriver s enhanced support for specific chipsets refer to Chapter 8 73 6 2 Writing the Device Driver Without the DriverWizard 74 e Use any C NET Delphi Visual Basic compiler such as MSDEV Visual C C MSDEV NET Borland C Builder Borland Delphi Visual Basic 6 0 MS eMbedded Visual C MS Platform Builder C GCC etc to compile the skeletal driver you need e For Linux use any compilation environment preferably GCC to build your code e That is all you need to do in order to create your user mode driver Please see Appendix B for a detailed description of WinDriver s USB API For more information regarding implementation of USB
36. to or from a device PROTOTYPE DWORD WDU_TransferlIsoch WDU_DEVICE HANDLE hDevice DWORD dwPipeNum DWORD fRead DWORD dwOptions PVOID pBuffer DWORD dwBufferSize PDWORD pdwBytesTransferred DWORD dwTimeout PARAMETERS See parameters of WDU_Transfer B 4 8 1 Note that pSetupPacket is not a parameter of this function DESCRIPTION See description of WDU_Transfer B 4 8 1 RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 163 B 4 8 6 WDU_TransferInterrupt PURPOSE e Performs interrupt data transfer to or from a device PROTOTYPE DWORD WDU_TransferInterrupt WDU_DEVICE HANDLE hDevice DWORD dwPipeNum DWORD fRead DWORD dwOptions PVOID pBuffer DWORD dwBufferSize PDWORD pdwBytesTransferred DWORD dwTimeout PARAMETERS See parameters of WDU_Transfer B 4 8 1 Note that pSetupPacket is not a parameter of this function DESCRIPTION See description of WDU_Transfer B 4 8 1 RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 164 B 4 9 Streaming Data Transfer Functions This section describes WinDriver s streaming data transfer functions For a detailed explanation regarding stream transfers and their implementation with Windriver refer to section 9 3 3 of the manual The APIs described in this
37. to the newly created mutex object RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 gt B 7 User Mode Utility Functions 220 B 7 11 OsMutexClose PURPOSE e Closes a handle to a mutex object PROTOTYPE void OsMutexClose HANDLE hOsMutex PARAMETERS TapuOutput HANDLE DESCRIPTION The handle to the mutex object to be closed RETURN VALUE None B 7 User Mode Utility Functions 221 B 7 12 OsMutexLock PURPOSE e Locks the specified mutex object PROTOTYPE DWORD OsMutexLock HANDLE hOsMutex PARAMETERS Tnput Output HANDLE DESCRIPTION The handle to the mutex object to be locked RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 7 User Mode Utility Functions 222 B 7 13 OsMutexUnlock PURPOSE e Releases unlocks a locked mutex object PROTOTYPE DWORD OsMutexUnlock HANDLE hOsMutex PARAMETERS Tnput Output HANDLE DESCRIPTION The handle to the mutex object to be unlocked RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 7 User Mode Utility Functions 223 B 7 14 PrintDbgMessage PURPOSE e Sends debug messages to the debug monitor PROTOTYPE void PrintDbgMessage DWORD dwLevel DWORD dwSection const char format k arcument ik PARAMETERS Taput Output DWORD DWORD argum
38. transfers with WinDriver refer to Chapter 9 of the manual 6 2 Writing the Device Driver Without the DriverWizard There may be times when you choose to write your driver directly without using DriverWizard In such cases either follow the steps outlined in this section to create a new driver project or use one of the WinDriver samples which most closely resembles your target driver and modify the sample to suit your specific requirements 6 2 1 Include the Required WinDriver Files 1 Include the relevant WinDriver header files in your driver project all header files are found under the WinDriver include directory All WinDriver projects require the windrvr h header file When using the WDU_xxx WinDriver USB API B 2 include the wdu_lib h header file this file already includes windrvr h Include any other header file that provides APIs that you wish to use from your code e g files from the WinDriver samples shared directory which provide convenient diagnostics functions 2 Include the relevant header files from your source code For example to use the USB API from the wdu_lib h header file add the following line to the code tinclude wdu_lib h 6 2 Writing the Device Driver Without the DriverWizard 75 3 Link your code with the wdapi920 library shared object e For Windows 98 Me 2000 XP Server 2003 Vista WinDriver lib lt CPU gt wdapi920 lib or wdapi920_borland lib for Borland C Builder where the lt CPU
39. windrvr6 o on Linux For example if you have renamed the default windrvr6 sys driver on Windows to my_driver sys you can log messages from your driver by running the Debug Monitor using the following command wddebug_gui my driver 7 2 Debug Monitor 82 7 2 2 Using the Debug Monitor in Console Mode wddebug The Debug Monitor utility comes in a console mode version WinDriver util wddebug which is available for all supported operating systems To use the wddebug console mode version of the Debug Monitor utility on Windows 98 Me 2000 XP Server 2003 Vista Windows CE and Linux run the WinDriver util wddebug utility as explained below On Windows CE start a Windows CE command window CMD EXE on the Windows CE target and then run the program WDDEBUG EXE inside this shell WDDEBUG USAGE wddebug lt driver_name gt lt command gt lt level gt lt sections gt NOTE The wddebug command options must be used in the order in which they appear in the usage demonstration above lt driver_name gt The name of the driver to which to apply the command The driver name can be set either to windrvr6 default or to the name of any driver renamed from the windrvr6 driver module see explanation in section 12 2 NOTE The driver name should be set to the name of the driver file without the file s extension e g windrvr6 not windrvr6 sys on Windows or windrvr6 o on Linux
40. you are ready turn off the Debug Monitor by running wddebug with the off command i You can also run wddebug with the status command while the Debug Monitor is turned off in order to view information regarding the running lt driver_name gt kernel module EXAMPLE The following is an example of a typical wddebug usage sequence Since no lt driver_name gt is set the commands are applied to the default driver windrvr6 e Turn the Debug Monitor on with the highest trace level for all sections wddebug on TRACE ALL Note This is the same as running wddebug on TRACE since ALL is default debug sections option e Dump the debug messages continuously until you hit Esc wddebug dump e Use the driver and view the debug messages in the command prompt e Turn the Debug Monitor off wddebug off Chapter 8 Enhanced Support for Specific Chipsets 8 1 Overview In addition to the standard WinDriver API and the DriverWizard code generation capabilities described in this manual which support development of drivers for any USB device WinDriver offers enhanced support for specific USB chipsets The enhanced support includes custom API and sample diagnostics code which are designed specifically for these chipsets WinDriver s enhanced support is currently available for the following chipsets The Cypress EZ USB family Microchip PIC18F4550 Philips PDIUSBD12 Texas Instruments TUSB3410 TUSB3210 TUSB2136 and TU
41. 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 181 REMARKS If dwNumLangIDs is zero the function will return only the number of supported language IDs in pbNumSupportedLangIDs but will not update the language IDs array pLangIDs with the actual IDs For this usage pLhangIDs can be NULL since it is not referenced but pbNumSupportedLangIDs must not be NULL pbNumSupportedLangIDs can be NULL if the user only wants to receive the list of supported language IDs and not the number of supported IDs In this case bNumLangIDs cannot be zero and pLangIDs cannot be NULL If the device does not support any language IDs the function will return success The caller should therefore check the value of pbNumSupportedLangIDs after the function returns If the size of the phangIDs array bNumLangIDs is smaller than the number of IDs supported by the device pbNumSupportedLangIDs the function will read and return only the first bNumLangIDs supported language IDs B 4 USB Functions 182 B 4 15 WDU_GetStringDesc PURPOSE e Reads a string descriptor from a device by string index PROTOTYPE DWORD DLLCALLCONV WDU_GetStringDesc WDU_DEVICE HANDLE hDevice BYTE bStrIndex PCHAR pcDescStr DWORD dwSize WDU_LANGID langID PARAMETERS Tnput Outpui WDU_DEVICE_ HANDLE bSulndex BYTE WDU_LANGID DESCRIPTION A unique identifier for the device interface pStrindex pbBuf The read string d
42. 139 B 2 2 Upgrading from the WD_xxx USB API to the WDU_xxx APL A Does bee ee PIS Oe Pe oe eee Pe 142 B 3 USB User Callback Functions 143 B 3 1 WDU_ATTACH_CALLBACK 143 B 3 2 WDU_DETACH_CALLBACK 144 B 3 3 WDU_POWER_CHANGE_CALLBACK 145 CONTENTS 7 B4 USB Functions sp cs 440 emyr cw Ee oboe ew om Ee e RA 146 BAI WDU LINN sv esc be ee ee Se ee Se a ed 146 B 4 2 WDU_SetinterfaceO 148 B 4 3 WDU_GetDeviceAddrO o 149 B 4 4 WDU_GetDeviceRegistryPropertyO 150 B 4 5 WDU_GetDevicelnftoO 152 B 4 6 WDU_PutDeviceInfo 153 B47 WDU_Unmit se sc da ve ee rsa Pak ee Eee ees 154 B 4 8 Single Blocking Transfer Functions 155 B 4 8 1 WDU_TransferO 156 B 4 8 2 WDU_HaltTransterO 159 B 4 8 3 WDU_TransferDefaultPipeO 160 B 4 8 4 WDU_TransferBulkQ 161 B 4 8 5 WDU_Transferlsoch 162 B 4 8 6 WDU_TransferInterrupt 163 B 4 9 Streaming Data Transfer Functions 164 B 4 9 1 WDU_StreamOpen 164 B 4 9 2 WDU_StreamStartQ 166 B 4 9 3 WDU_StreamReadO 167 B 4 9 4 WDU_StreamWrite 169 B 4 9 5 WDU_StreamFlushO 171 B 4 9 6 WDU_StreamGetStatusO 172 B 4 9 7 WDU_StreamStopO 173 B 4 9 8 W
43. 2000 XP Server 2003 Vista distribution although on these platforms it is recommended to use the files from the WinDriver redist directory On Windows 2000 XP Server 2003 Vista if you have renamed the WinDriver kernel module windrvr6 sys as explained in section 12 2 replace the relevant windrvr6 references with the name of your driver and replace references to the WinDriver redist directory with the path to the directory that contains your modified installation files For example when using the generated DriverWizard renamed driver files for your driver project as explained in section 12 2 1 1 you can replace references to the WinDriver redist directory with references to the generated xxx_installation redist directory where xxx is the name of your generated driver project If you have created new INF and or catalog files for your driver replace the references to the original WinDriver INF files and or to the wd920 cat catalog file with the names of your new files see information in sections 12 2 1 and 12 3 2 regarding renaming of the original files 11 2 Windows Driver Distribution 106 Distributing the driver you created is a multi step process First create a distribution package that includes all the files required for the installation of the driver on the target computer Second install the driver on the target machine This involves installing windrvr6 sys and windrvr6 inf and installing the specific INF file for y
44. BMIT the function returns WD_OPERATION_FAILED REMARKS e WDU_SelectiveSuspend is supported on Windows XP and higher B 4 USB Functions 179 B 4 13 WDU_Wakeup PURPOSE e Enables Disables the wakeup feature PROTOTYPE DWORD WDU_Wakeup WDU_DEVICE HANDLE hDevice DWORD dwOptions PARAMETERS Tnput Outpai WDU DEVICE HANDLE DWORD DESCRIPTION A unique identifier for the device interface dwOptions Can be either WDU_WAKEUP_ENABLE enable wakeup OR WDU_WAKEUP_DISABLE disable wakeup RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 180 B 4 14 WDU_GetLangIDs PURPOSE e Reads a list of supported language IDs and or the number of supported language IDs from a device PROTOTYPE DWORD DLLCALLCONV WDU_GetLanglDs WDU_DEVICE HANDLE hDevice PBYTE pbNumSupportedLangIDs WDU_LANGID pLangIDs BYTE bNumLangIDs PARAMETERS palo sip WDU_DEVICE HANDLE gt pbNumSupportedLangIDs PBYTE gt pLanglDs WDU_LANGID gt bNumLangIDs BYTE DESCRIPTION A unique identifier for the device interface pbNumSupportedLangIDs Parameter to receive number of supported language IDs pLangIDs Array of language IDs If bNumLangIDs is not zero the function will fill this array with the supported language IDs for the device bNumLangIDs Number of IDs in the pLangIDs array RETURN VALUE Returns WD_STATUS_SUCCESS
45. D to detect as assigned by ee ismo oo vaes gt wProductld WORD Required USB Product ID to detect as assigned by the remato bDeviceCias bDeviceSubClass Name B 5 2 2 WDU_EVENT_TABLE Structure USB events table structure This structure is declared in the WinDriver include wdu_lib h header file Description Description gt pfDeviceAttach WDU_ATTACH_CALLBACK Will be called by WinDriver e a gt pfDeviceDetach WDU_DETACH_CALLBACK Will be called by WinDriver e A Me is cetached gt pfPowerChange WDU_POWER_CHANGE_CALLBACK Will be called by WinDriver when there is a change in a device s power state gt pUserData PVOID Pointer to user mode data to be passed to the callbacks B 5 USB Data Types 188 B 5 2 3 WDU_DEVICE Structure USB device information structure WDU_DEVICE_DESCRIPTOR Device descriptor information structure B 5 2 7 gt Pipe WDU_PIPE_INFO Pipe information structure B 5 2 11 for the gt pConfigs WDU_CONFIGURATION Pointer to the device s configuration information gt pActiveConfig WDU_CONFIGURATION Pointer to a configuration information structure B 5 2 4 for the device s active configuration gt pActivelnterface WDU_INTERFACE Array of pointers to interface information WD_USB_MAX_INTERFACES structures B 5 2 5 for the device s active interfaces B 5 2 4 WDU_CONFIGURATION Structure Configuration information structure Name gt Descriptor WDU_C
46. DLE hStream PARAMETERS Type Tapat Output WDU_STREAM_HANDLE Tnput DESCRIPTION hStream A unique identifier for the stream as returned by WDU_St reamOpen RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 167 B 4 9 3 WDU_StreamRead PURPOSE e Reads data from a read stream to the application For a blocking stream fBlocking TRUE see WDU_StreamOpen the call to this function is blocked until the specified amount of data bytes is read or until the stream s attempt to read from the device times out i e the timeout period for transfers between the stream and the device as set in the dwRxTxTimeout WDU_StreamOpen parameter B 4 9 1 expires For a non blocking stream fBlocking FALSE the function transfers to the application as much of the requested data as possible subject to the amount of data currently available in the stream s data buffer and returns immediately For both blocking and non blocking transfers the function returns the amount of bytes that were actually read from the stream within the pdwBytesRead parameter PROTOTYPE DWORD DLLCALLCONV WDU_StreamRead HANDLE hStream PVOID pBuffer DWORD bytes DWORD pdwBytesRead PARAMETERS input Ouiput WDU_STREAM_HANDLE pufer BVOT DWORD gt pdwBytesRead DWORD B 4 USB Functions 168 DESCRIPTION hStream A unique identifier for the stream
47. DU_StreamClose 174 B410 WDU ResetPipe kes ES eR ee ra 175 B 4 11 WDU_ResetDevicel 176 B 4 12 WDU_SelectiveSuspend 178 B413 WDU_WakeupO s se ecs e o e 020200048 179 B 4 14 WDU_GetLangIDs ooo 180 B 4 15 WDU_GetStringDescO o egrs eee ree eperra tiea 182 BS USB Data Types ooreet 44645 e h4 84633 Eey 4 eS 184 B 5 1 WD_DEVICE_REGISTRY_PROPERTY Enumeration 184 B52 USB Structures os s 0646604446 68 5 6 BE OO 186 B 5 2 1 WDU_MATCH_TABLE Structure 187 B 5 2 22 WDU_EVENT_TABLE Structure 187 B 5 2 3 WDU_DEVICE Structure 188 B 5 2 4 WDU_CONFIGURATION Structure 188 B 5 2 5 WDU_INTERFACE Structure 189 B 5 2 6 WDU_ALTERNATE_SETTING Structure 189 B 5 2 7 WDU_DEVICE_DESCRIPTOR Structure 190 B 5 2 8 WDU_CONFIGURATION_DESCRIPTOR Suce e lt br rl fe ee wi eh oe eS 190 CONTENTS B 6 1 B 6 2 B 6 3 B 6 4 B 6 5 B 6 6 B 6 7 B 6 8 B 6 9 B 7 1 B 7 2 B 7 3 B 7 4 B 7 5 B 7 6 B 7 7 B 7 8 B 7 9 B 7 10 B 7 11 B 7 12 B 7 13 B 7 14 B 7 15 B 7 16 B 7 17 B 8 1 B 8 2 B 8 3 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 Calling Sequence WinDriver General Use WDOpent s s rete e ar aa A ewe ES WD_Version orcas aaa RR ee OO WID Close escritas Parke eeee eee WD
48. De b g cite ees opgee Hs eed HERSEY ES WD_DebugAddO o WD_DebugDumpO o o WD Sleep aca apesta a a o data aS WDuLicense corsa coca tek bh B 7 User Mode Utility Functions StatZS EO Cea a a ad foe Gee 2S BOLOS TYPE eers asa a AE ee eed ThteadStart 22423444 404544654446 44454 55 ThreadWait c sas oe eca ee ee OsEventCr ate so ece Seek he hee eke Se EN OsEventClose o ee e 6 44 6244 04 we eee OH OSEVEntWalt cesa wa ee ee ek See eee OsEventSignal o 0020020 eee OsEventReset ee OsMiutexCreate moco posa oa wads Gale ee ee 2S OsMutexClosel 2 2 0 ee ee OsMutexLock 24 3444424463446 44484546 OsMutexUnlock 000002 eee PrintDbgMessage 2 ee ee WD LogStart i e 24 oS Gees Pop hae ee ete 4 WID LogStopl s si 2 petre prerii eee ee ee ee WD LogAdd ee e poea endase ema Gh EOE LY B 8 WinDriver Status Codes Introduction 2 245 624 68244 664465 Bee eee Status Codes Returned by WinDriver Status Codes Returned by USBD 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 191 191 192 193 193 195 196 198 199 201 203 205 207 210 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 227 228 229
49. Driver vb samples directory 1 10 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 royalties free in as many copies as you wish See the license agreement WinDriver docs license pdf for more details Chapter 2 Understanding Device Drivers This chapter provides you with a general introduction to device drivers and takes you through the structural elements of a device driver NOTE Using WinDriver you do not need to familiarize yourself with the internal workings of driver development As explained in Chapter 1 of the manual WinDriver enables you to communicate with your hardware and develop a driver for your device from the user mode using only WinDriver s simple APIs without any need for driver or kernel development knowledge 2 1 Device Driver Overview Device drivers are the software segments that provides an interface between the operating system and the specific hardware devices such as terminals disks tape drives video cards and network media The device driver brings the device into and out of service sets hardware parameters in the device transmits data from the kernel to the device receives data from the device and passes it back to the kernel and handles device errors A driver acts like a translator between the device and programs that use the device Each device has its own set of spec
50. E Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 EXAMPLE WD_DEBUG_ADD add BZERO add add dwLevel D_WARN add dwSection S_MISC sprintf add pcBuffer This message will be displayed in the debug monitor n WD_DebugAdd hWD amp add B 6 General WD_xxx Functions 203 B 6 7 WD_DebugDump PURPOSE e Retrieves debug messages buffer PROTOTYPE DWORD WD_DebugDump HANDLE hWD WD_DEBUG DUMP pDebugDump PARAMETERS Tnput Outpai HANDLE pDebug WD_DEBUG_DUMP I pcBuffer PCHAR Input Output DWORD DESCRIPTION Description hWD Handle to WinDriver s kernel mode driver as received from WD_Open B 6 2 pDebugDump Pointer to a debug dump information structure gt pcBuffer Buffer to receive debug messages Size of buffer in bytes RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 6 General WD_xxx Functions 204 EXAMPLE char buffer 1024 WD_DEBUG_DUMP dump dump pcBuffer buffer dump dwSize sizeof buffer WD_DebugDump hWD dump B 6 General WD_xxx Functions 205 B 6 8 WD_Sleep PURPOSE e Delays execution for a specific duration of time PROTOTYPE DWORD WD_Sleep HANDLE hWD WD_SLEEP xpSleep PARAMETERS Type Input Output HANDLE Taput gt pSleep WD_SLEEP _IdwMicroSeconds DWORD Input _IdwOptions DWORD Input DESCRIPTION Descri
51. E Set configuration operation failed B 8 WinDriver Status Codes 229 B 8 3 Status Codes Returned by USBD The following WinDriver status codes comply with USBD_XXX status codes returned by the USB stack drivers USBD Status Codes NOTE The status codes consist of one of the status types above and an error code i e OXXYYYYYYYL where X status type and YYYYYYY error code The same error codes may also appear with one of the other status types as well HC Host Controller Status Codes NOTE These use the WD_USBD_STATUS_HALTED status type WD_USBD_STATUS_CRC HC status CRC WD_USBD_STATUS_BTSTUFF HC status Bit stuffing WD_USBD_STATUS_DATA _TOGGLE_MISMATCH HC status Data toggle mismatch WD_USBD_STATUS_STALL_PID HC status PID stall WD_USBD_STATUS_DEV_NOT_RESPONDING HC status Device not responding WD_USBD_STATUS_BUFFER_OVERRUN WD_USBD_STATUS_FIFO HC status FIFO B 8 WinDriver Status Codes 230 Status Code For Windows only WD_USBD_STATUS_XACT_ERROR HC status The host controller has set the Transaction Error XactErr bit in the transfer descriptor s status field WD_USBD_STATUS_BABBLE_DETECTED WD_USBD_STATUS_DATA_BUFFER_ERROR For Windows CE only WD_USBD_STATUS_NOT_COMPLETE WD_USBD_STATUS_CLIENT_BUFFER For all platforms WD_USBD_STATUS_CANCELED Returned by HCD Host Controller Driver if a transfer is submitted to an endpoint that is stalled WD_USBD_STATUS_ENDPOINT_HALTED HCD Transfer submitted t
52. E sn ecw eek we ew cas ee What Does the WinDriver Toolkit Include 1 9 1 WinDriver Modules LOA UUES z paons A AA ee eS 1 9 3 WinDriver s Specific Chipset Support 194 Samples pibe po si A See RS Can I Distribute the Driver Created with WinDriver 2 Understanding Device Drivers 2 1 2 2 2 3 Device Driver Overview s a s oa POSS wo EA e eS Classification of Drivers According to Functionality 2 2 1 Monolithic Drivers ea ce o o o 22 2 Layered Drivers weres e cd e ee 2 2 3 Miniport Drivers c teea ss rara he Ee eS Classification of Drivers According to Operating Systems 2 CONTENTS 2 4 25 2 6 3 1 32 3 3 3 4 3 5 3 6 4 1 4 2 2 3 WDM DANVETS o re a ow Seite 2 Se oon be hes 23 2 VXD Drivers evo soe Gey oe bow ae we a ew eS 23 3 Unix Device Drivers acc poe en a a a G 2 3 4 Linux Device Drivers 2 4 The Entry Point of the Driver 0 Associating the Hardware to the Driver Communicating with Drivers o o o WinDriver USB Overview Introduction to USB sss gos e sydda py etay aeS is WinDriver USB Benefits s e 06 0 60846 6848 es i oea pia USB Components aos s eean n eae Be a ees Data Flow in USB Devices ceases ii USB Data Exchange 2 5 4 6 ee pS SoG a oe ae es USB Data Transfer Types s gt ocs o o oo e 3 6 1 Control Transfer
53. ERS Type Input Output WDU STREAM HANDLE Input DESCRIPTION hStream A unique identifier for the stream as returned by WDU_StreamOpen RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 175 B 4 10 WDU_ResetPipe PURPOSE e Resets a pipe by clearing both the halt condition on the host side of the pipe and the stall condition on the endpoint This function is applicable for all pipes except pipe00 PROTOTYPE DWORD WDU_ResetPipe WDU_DEVICE HANDLE hDevice DWORD dwPipeNum PARAMETERS Input Output WDU_DEVICE_HANDLE dwPipeNum DWORD DESCRIPTION A unique identifier for the device interface dwPipeNum The pipe s number RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 REMARKS e This function should be used if a pipe is halted in order to clear the halt B 4 USB Functions 176 B 4 11 WDU_ResetDevice PURPOSE e Resets a device PROTOTYPE DWORD WDU_ResetDevice WDU_DEVICE HANDLE hDevice DWORD dwOptions PARAMETERS input Output WDU DEVICE HANDLE DWORD DESCRIPTION A unique identifier for the device interface dwOptions Can be either zero or WD_USB_ HARD RESET reset the device even if it is not disabled After using this option it is advised to set the interface device using WDU_Set Interface B 4 2 WD_USB_CYCLE_PORT simul
54. For USB devices with only one alternate setting configured DriverWizard automatically selects the detected alternate setting and therefore the Select Device Interface dialogue will not be displayed 6 Diagnose your device Before writing your device driver it is important to make sure your hardware is working as expected Use DriverWizard to diagnose your hardware All of your activity will be logged in the DriverWizard log so that you may later analyze your tests a Test your USB device s pipes DriverWizard shows the pipes detected for the selected alternate setting To perform USB data transfers on the pipes follow these steps i Select the desired pipe ii For a control pipe a bidirectional pipe click Read Write A new dialogue will appear allowing you to select a standard USB request or define a custom request as demonstrated in Figure 5 7 3 Pipe 0 Control Setup Packet Write to pipe data Hex Custom request v Type Request wYalue wIndex wLength oo po 0000 0 jo 00 00 00 00 00 00 00 00 Action Read from Pipe Clear Save Write Data Trace USB transaction in Ellisys Visual USB Figure 5 7 USB Control Transfers 5 2 DriverWizard Walkthrough 67 111 Alternate Setting 2 When you select one of the available standard USB requests the setup packet information for the selected request is automatically filled and the request description is dis
55. For example e From a CD tar xvzf mnt cdrom LINUX WD920LN tgz e From a downloaded file tar xvzf home username WD920LN tgz 4 Change directory to your WinDriver redist directory the tar automatically creates a WinDriver directory cd lt WinDriver directory path gt redist 5 Install WinDriver a lt WinDriver directory gt redist configure NOTE The configure script creates a makefile based on your specific running kernel You may run the configure script based on another kernel source you have installed by adding the flag with kernel source lt path gt to the configure script The lt path gt is the full path to the kernel source directory e g usr src linux b lt WinDriver directory gt redist make c Become super user lt WinDriver directory gt redist su d Install the driver lt WinDriver directory gt redistf make install 4 2 WinDriver Installation Process 53 6 Create a symbolic link so that you can easily launch the DriverWizard GUI ln s lt full path to WinDriver gt 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 windrvr6 depending on how you wish to allow users to access hardware through the device If you are using a Linux 2 6 x kernel that has the udev file system change the pe
56. Integrated Circuit is provided as an example Byen 0112131415167 819 10 Content 12 01 00 01 40147 05 80 Content 00 OF 0000 00 00 OT As defined in the USB specification byte 0 indicates the length of the descriptor bytes 2 3 contain the USB specification release number byte 7 is the maximum packet size for endpoint 00 bytes 8 9 are the Vendor ID bytes 10 11 are the Product ID etc 9 2 USB Control Transfers 93 9 2 2 Performing Control Transfers with WinDriver WinDriver allows you to easily send and receive control transfers on Pipe00 while using DriverWizard to test your device You can either use the API generated by DriverWizard 5 for your hardware or directly call the WinDriver WDU_Transfer B 4 8 1 function from within your application 9 2 2 1 Control Transfers with DriverWizard 1 Choose Pipe 0x0 and click the Read Write button 2 You can either enter a custom setup packet or use a standard USB request e For a custom request enter the required setup packet fields For a write transaction that includes a data stage enter the data in the Write to pipe data Hex field Click Read From Pipe or Write To Pipe according to the required transaction see Figure 9 3 ES Pipe O Control Setup Packet Write to pipe data Hex Custom request vj Type Request wWalue wIndex wLength o0 0 0000 o 0 00 00 00 00 00 00 00 00 Action Read from Pipe
57. LL that communicates with the WinDriver kernel for the x86 HPC emulation mode of Windows CE REDIST K86EMU WINDRVR_CE_EMU LIB an import library that is used to link with WinDriver applications that are compiled for the x86 HPC emulation mode of Windows CE 1 9 3 WinDriver s Specific Chipset Support WinDriver provides custom wrapper APIs and sample code for major USB chipsets see Chapter 8 including for the following chipsets Cypress EZ USB WinDriver cypress Microchip PIC18F4550 WinDriver microchip pic18f4550 Philips PDIUSBD12 WinDriver pdiusbd12 Texas Instruments TUSB3410 TUSB3210 TUSB2136 and TUSB5052 WinDriver ti Agere USS2828 WinDriver agere Silicon Laboratories C8051F320 USB WinDriver silabs 1 10 Can I Distribute the Driver Created with WinDriver 21 1 9 4 Samples In addition to the samples provided for specific chipsets 1 9 3 WinDriver includes a variety of samples that demonstrate how to use WinDriver s API to communicate with your device and perform various driver tasks e C samples found under the WinDriver samples directory These samples also include the source code for the utilities listed above 1 9 2 e NET C and Visual Basic NET samples Windows found under the WinDriver csharp net and WinDriver vb net directories respectively e Delphi Pascal samples Windows WinDriver delphi samples directory e Visual Basic samples Windows found under the Win
58. NTERFACE_DESCRIPTOR Structure USB interface descriptor information structure gt bLength UCHAR Size in bytes of the descriptor 9 bytes gt bInterfaceClass UCHAR The interface s class code as assigned by eS E E gt bInterfaceSubClass UCHAR The interface s sub class code as assigned by gt bInterfaceProtocol UCHAR The interface s protocol code as assigned by gt Interface UCHAR Index of string descriptor that describes this ow ee B 5 2 10 WDU_ENDPOINT_DESCRIPTOR Structure USB endpoint descriptor information structure Name gt bLength UCHAR Size in bytes of the descriptor 7 bytes gt bDescriptorType UCHAR Endpoint descriptor 0x05 gt bEndpointAddress UCHAR Endpoint address Use bits 0 3 for endpoint number set bits 4 6 to zero 0 and set bit 7 to zero 0 for outbound data and one 1 for inbound data ignored for control endpoints gt bmAttributes UCHAR Specifies the transfer type for this endpoint control interrupt isochronous or bulk See the USB specification for further information gt wMaxPacketSize USHORT Maximum size of packets this endpoint can send or receive gt bInterval UCHAR Interval in frame counts for polling endpoint data transfers Ignored for bulk and control endpoints Must equal for isochronous endpoints May range from 1 to 255 for interrupt endpoints B 5 USB Data Types 192 B 5 2 11 WDU_PIPE_INFO Structure USB p
59. ONFIGURATION_DESCRIPTOR Configuration descriptor information Cee o fsmte B S280 gt dwNuminterfaces DWORD Number of interfaces supported by this ae e gt pInterfaces WDU_INTERFACE Pointer to the beginning of an array of interface information structures B 5 2 5 for the configuration s interfaces B 5 USB Data Types B 5 2 5 WDU_INTERFACE Structure Interface information structure gt pAlternateSettings WDU_ALTERNATE_SETTING gt dwNumAltSettings DWORD gt pActiveAltSetting WDU_ALTERNATE_SETTING 189 Pointer to the beginning of an array of alternate setting information structures B 5 2 6 for the interface s alternate settings Number of alternate settings supported by this interface Pointer to an alternate setting information structure B 5 2 6 for the interface s B 5 2 6 WDU_ALTERNATE_SETTING Structure Alternate setting information structure Name Type active alternate setting gt Descriptor WDU_INTERFACE_DESCRIPTOR Interface descriptor information structure B 5 2 9 gt pEndpointDescriptors WDU_ENDPOINT_DESCRIPTOR Pointer to the beginning of an array WDU_PIPE_INFO of endpoint descriptor information structures B 5 2 10 for the alternate setting s endpoints Pointer to the beginning of an array of pipe information structures B 5 2 11 for the alternate setting s pipes B 5 USB Data Types 190 B 5 2 7 WDU_DEVICE_DESCRIPTOR Structure USB device descr
60. SB5052 Agere USS2828 Silicon Laboratories C805 1F320 85 8 2 Developing a Driver Using the Enhanced Chipset Support 86 8 2 Developing a Driver Using the Enhanced Chipset Support When developing a driver for a device based on one of the enhanced support chipsets 8 1 you can use WinDriver s chipset set specific support by following these steps 1 Locate the sample diagnostics program for your device under the WinDriver chip_vendor chip_name directory Most of the sample diagnostics program names are derived from the sample s main purpose e g download_sample for a firmware download sample and their source code can be found directly under the specific chip_name directory 2 Run the custom diagnostics program to diagnose your device and familiarize yourself with the options provided by the sample program 3 Use the source code of the diagnostics program as your skeletal device driver and modify the code as needed to suit your specific development needs When modifying the code you can utilize the custom WinDriver API for your specific chip The custom API is typically found under the WinDriver chip_vendor lib directory Chapter 9 USB Transfers This chapter provides detailed information regarding implementation of USB transfers using WinDriver 9 1 Overview As explained in section 3 5 the USB standard supports two kinds of data exchange between the host and the device control exchange and functional da
61. TE wdreg is dependent on the difxapi dll DLL On Windows 2000 XP Server 2003 Vista type from the command line wdreg inf lt path to windrvr6 inf gt install On Windows 98 Me type from the command line wdreg16 inf lt path to windrvr6 inf gt install For example if windrvr6 inf and windrvr6 sys are in the d MyDevice directory on the target computer the command should be wdreg inf d MyDevice windrvr6 inf install You can find the executable of wdreg in the WinDriver package under the WinDriver util directory For a general description of this utility and its usage please refer to Chapter 10 11 2 Windows Driver Distribution 109 NOTE wdreg is an interactive utility If it fails it will display a message instructing the user how to overcome the problem In some cases the user may be asked to reboot the computer CAUTION When distributing your driver take care not to overwrite a newer version of windrvr6 sys with an older version of the file in Windows drivers directory windir system32 drivers You should configure your installation program 1f you are using one or your INF file so that the installer automatically compares the time stamp on these two files and does not overwrite a newer version with an older one e Install the INF file for your device registering your Plug and Play device with windrvr6 sys Windows 2000 XP Server 2003 Vista Use the utility wdreg to automatically load the INF fi
62. TK DDI DKI Write the kernel mode device driver that does the basic hardware input output Write the application in user mode that accesses the hardware through the device driver written in kernel mode Repeat the first four steps for each new operating system on which the code should run 1 3 Conclusion 14 1 2 2 The WinDriver Solution Easy Development WinDriver enables Windows Windows CE and Linux programmers to create USB based device drivers in an extremely short time WinDriver allows you to create your driver in the familiar user mode environment using MSDEV Visual C C MSDEV NET Borland C Builder Borland Delphi Visual Basic 6 0 MS eMbedded Visual C MS Platform Builder C GCC or any other appropriate compiler You do not need to have any device driver knowledge nor do you have to be familiar with operating system internals kernel programming the DDK ETK or DDI DKI Cross Platform The driver created with WinDriver will run on Windows 98 Me 2000 XP Server 2003 Vista Windows CE NET Windows Embedded CE v6 00 Windows Mobile 5 0 6 0 and Linux In other words write it once run it on many platforms Friendly Wizards DriverWizard included is a graphical diagnostics tool that lets you view the device s resources and test the communication with the hardware with just a few mouse clicks before writing a single line of code Once the device is operating to your satisfaction DriverWizard creates the skelet
63. T_URB_SIZE_OVERRIDE_128K Limits the size of the USB Request Block URB to 128KB pBuffer Address of the data buffer dwBufferSize Number of bytes to transfer The buffer size is not limited to the device s maximum packet size therefore you can use larger buffers by setting the buffer size to a multiple of the maximum packet size Use large buffers to reduce the number of context switches and thereby improve performance pdwBytesTransferred Number of bytes actually transferred pSetupPacket An 8 byte packet to transfer to control pipes dwTimeout Maximum time in milliseconds ms to complete a transfer A value of zero indicates no timeout infinite wait RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 158 REMARKS e The resolution of the timeout the dwTimeout parameter is according to the operating system scheduler s time slot For example in Windows the timeout s resolution is 10 milliseconds ms B 4 USB Functions 159 B 4 8 2 WDU_HaltTransfer PURPOSE e Halts the transfer on the specified pipe only one simultaneous transfer per pipe is allowed by WinDriver PROTOTYPE DWORD WDU_HaltTransfer WDU_DEVICE HANDLE hDevice DWORD dwPipeNum PARAMETERS Input Output WDU_DEVICE_HANDLE dwPipeNum DWORD DESCRIPTION Description A unique identifier for the device interface dwPipeNum The number of the pipe
64. Texas Instruments Agere and Silicon Laboratories chipsets frees the developer from the need to study the hardware s specification Applications are binary compatible across Windows 98 Me 2000 XP Server 2003 Vista Applications are source code compatible across all supported operating systems Windows 98 Me 2000 XP Server 2003 Vista Windows CE NET Windows Embedded CE v6 00 Windows Mobile 5 0 6 0 and Linux Can be used with common development environments including MSDEV Visual C C MSDEV NET Borland C Builder Borland Delphi Visual Basic 6 0 MS eMbedded Visual C MS Platform Builder C GCC or any other appropriate compiler No DDK ETK DDI or any system level programming knowledge required Supports multiple CPUs Includes dynamic driver loader Comprehensive documentation and help files Detailed examples in C C Visual Basic NET Delphi and Visual Basic 6 0 WHOL certifiable driver Windows Two months of free technical support No run time fees or royalties 1 5 WinDriver Architecture 1 5 WinDriver Architecture Your Application DII Shared Object Your Driver Code WinDriver NET Wrapper API wdapi_dotnet DLL High level WinDriver API wdapi DLL shared object User Mode Kernel Mode Low Level WinDriver API WinDriver Kernel Module windrvr6 sys o ko dll ORE Priye HARR O Components You Write O WinDriver Components O OS Compon
65. The control transaction always begins with a setup stage The setup stage is followed by zero or more control data transactions data stage that carry the specific information for the requested operation and finally a status transaction completes the control transfer by returning the status to the host During the setup stage an 8 byte setup packet is used to transmit information to the control endpoint of the device The setup packet s format is defined by the USB specification A control transfer can be a read transaction or a write transaction In a read transaction the setup packet indicates the characteristics and amount of data to be read from the device In a write transaction the setup packet contains the command sent written to the device and the number of control data bytes that will be sent to the device in the data stage Refer to Figure 9 2 taken from the USB specification for a sequence of read and write transactions in indicates data flow from the device to the host out indicates data flow from the host to the device 9 2 USB Control Transfers 89 Setup Data Stage Stage Optional Status Control win er Setup Data Stage Stage Optional Status Control cua Fara Setup Status Stage No da o data Cone Figure 9 2 USB Read and Write 9 2 1 3 The Setup Packet The setup packets combined with the control data stage and the status stage are used to configure and send command
66. The default driver name which is used if the function is not called is windrvr6 This function must be called once and only once from the beginning of your application before calling any other WinDriver function including WD_Open WDU_Init as demonstrated in the sample and generated DriverWizard WinDriver applications which include a call to this function with the default driver name windrvr6 On Windows and Linux If you select to modify the name of the WinDriver kernel module windrvr6 sys o ko as explained in section 12 2 you must ensure that your application calls WD_DriverName with your new driver name In order to use the WD_DriverName function your user mode driver project must be built with WD_DRIVER_NAME_CHANGE preprocessor flag e g DWD_DRIVER_NAME_CHANGE for Visual Studio and gcc The sample and generated DriverWizard Windows and Linux WinDriver projects makefiles already set this preprocessor flag B 1 WD_DriverName 137 PROTOTYPE const char DLLCALLCONV WD_DriverName const charx sName PARAMETERS Input Output DESCRIPTION Description sName The name of the WinDriver kernel module to be used by the application NOTE The driver name should be indicated without the driver file s extension For example use windrvr6 not windrvr6 sys or windrvr6 o RETURN VALUE Returns the selected driver name on success returns NULL on failure e g if the function is called twic
67. USB Data Transfers 9 3 1 Functional USB Data Transfers Overview Functional USB data exchange is used to move data to and from the device There are three types of USB data transfers Bulk Interrupt and Isochronous which are described in detail in sections 3 6 2 3 6 4 of the manual Functional USB data transfers can be implemented using two alternative methods single blocking transfers and streaming transfers both supported by WinDriver as explained in the following sections The generated DriverWizard USB code 5 3 3 and the generic WinDriver util usb_diag exe utility 1 9 2 source code located under the WinDriver samples usb_diag directory enable the user to select which type of transfer to perform 9 3 2 Single Blocking Transfers In the single blocking USB data transfer scheme blocks of data are synchronously transferred hence blocking between the host and the device per request from the host hence single transfers 9 3 2 1 Performing Single Blocking Transfers with WinDriver WinDriver s WOU_Transfer function and the WOU_TransferBulk WDU_TransferIsoch and WDU_TransferInterrupt convenience functions all described in section B 4 8 of the manual enable you to easily impelment single blocking USB data transfers You can also perform single blocking transfers using the DriverWizard utility which uses the WDU_Transfer function as demonstrated in section 5 2 of the manual 9 3 F
68. WDU_Uninit B 4 7 to un register from the device 6 3 Developing Your Driver on Windows CE Platforms 76 6 3 Developing Your Driver on Windows CE Platforms In order to register your USB device to work with WinDriver you can perform one of two of the following Call WDU_Init B 4 1 before the device is plugged into the CE system OR You can add the following entry to the registry can be added to your platform reg file HKEY_LOCAL_MACHINE DRIVERS USB LoadClients lt ID gt Default Default WDR DLL windrvr6 d11 lt ID gt consists of your vendor ID and product ID separated by an underscore character lt MY VENDOR ID gt _ lt MY PRODUCT ID gt Insert your device specific information to this key The key registers your device with Windows CE Plug and Play USB driver and enables identification of the device during boot You can refer to the registry after calling WDU_Init and then this key will exist From that moment the device will be recognized by CE If your device has a persistent registry this addition will remain until you remove it For more information refer to the Microsoft Development Network MSDN Library under the USB Driver Registry Settings section 6 4 Developing in Visual Basic and Delphi 47 6 4 Developing in Visual Basic and Delphi The entire WinDriver API can be used when developing drivers in Visual Basic and Delphi 6 4 1 Using DriverWizard DriverWizard can be used to diagnose yo
69. WinDriver USB User s Manual Version 9 20 d JUNGO http www jungo com COPYRIGHT Jungo Ltd 2005 2008 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 Brand and product names mentioned in this document are trademarks of their respective holders and are used here only for identification purposes Contents Table of Contents List of Figures 1 WinDriver Overview 1 1 1 2 1 3 1 5 1 6 1 7 1 8 1 9 1 10 Introduction to WinDriver 2 a ee eee Backeround lt 3 s co e be A a ae ee ew ee 12 1 WherChallenge i ons adas eed eee ie Hae Os 1 2 2 The WinDriver Solution 0 4 Conclusion e mail Ge WinDriver Benefits 2 0 0 0 0 0 ee ee ee eee WinDriver Architecture s ss ea sa e e e ae is pe we SS What Platforms Does WinDriver Support Limitations of the Different Evaluation Versions How Do I Develop My Driver with WinDriver 1 8 1 On Windows andLinux 0 1 8 2 On Windows C
70. a handle to access the WinDriver kernel module The handle is used by all WinDriver APIs and therefore must be called before any other WinDriver API is called PROTOTYPE HANDLE WD_Open void RETURN VALUE The handle to the WinDriver kernel module If device could not be opened returns INVALID_HANDLE_VALUE REMARKS e If you are a registered user please refer to the documentation of WD_License B 6 9 for an example of how to register your WinDriver license EXAMPLE HANDLE hWD hWD WD_Open if hWD INVALID HANDLE VALUE printf Cannot open WinDriver device n B 6 General WD_xxx Functions 196 B 6 3 WD_Version PURPOSE e Returns the version number of the WinDriver kernel module currently running PROTOTYPE DWORD WD_Version HANDLE hWD WD_VERSION pVer PARAMETERS Tnput Outpui HANDLE Taput WD_VERSION DWORD Output CHARTIZ5 Output DESCRIPTION Description hWD Handle to WinDriver s kernel mode driver as received from WD_Open B 6 2 pVer Pointer to a WinDriver version information structure gt cVer Version information string The version string s size is limited to 128 characters including the NULL terminator character RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 6 General WD_xxx Functions 197 EXAMPLE WD_VERSION ver BZERO ver WD_Version hWD ver printf s n ver
71. ad of the installation files from the original WinDriver distribution As part of the installation build your new kernel driver module by following the instructions in section 11 4 1 using the files from your new installation directory 12 3 Digital Driver Signing amp Certification Windows 2000 XP Server 2003 Vista 12 3 1 Overview Before distributing your driver you can select to digitally sign it and or certify it either by submitting it to Microsoft s Windows Logo Program certification and signature or by having the driver Authenticode signed On most existing Windows operating systems a driver can be installed successfully even if it has not been digitally signed or certified However there are advantages to getting your driver signed Among these advantages are successful driver installation on targets on which the installation of unsigned drivers has been blocked avoid Windows unsigned driver warnings during the driver s installation full pre installation of INF files 12 1 on Windows XP and newer is supported only for signed drivers The importance of digital code signing was further extended with the release of the Windows Vista operating system as explained at http www microsoft com whdc winlogo drvsign drvsign mspx For more information on digital driver signing and certification refer to the Introduction to Code Signing topic in the Microsoft Development Network MSDN documentation 12 3 Digital Driver S
72. ake lt OS gt lt build mode free checked gt For example to build a release version of the driver for Windows XP ddk_make winxp free Note The ddk_make bat utility is provided under the WinDriver util directory and should be automatically identified by Windows when runnning the installation command After rebuilding the xxx sys driver copy the new driver file to the generated xxx redist directory 2 Verify that your application calls the WD_DriverName function B 1 with your new driver name before calling any other WinDriver function Note that the sample and generated DriverWizard WinDriver applications already include a call to this function but with the default driver name windrvr6 so all you need to do is replace the driver name that is passed to the function in the code with your new driver name 3 Verify that your user mode driver project is built with the WD_DRIVER_NAME_CHANGE preprocessor flag e g DWD_DRIVER_NAME_CHANGE 12 2 Renaming the WinDriver Kernel Driver 124 Note The sample and generated DriverWizard WinDriver projects makefiles already set this preprocessor flag by default 4 Install your new driver by following the instructions in section 11 2 of the manual using the modified files from the generated xxx_installation directory instead of the installation files from the original WinDriver distribution 12 2 1 2 Manually Rename the Windows Driver To manually rename the Windows WinDriver
73. al driver source code giving access functions to all the resources on the hardware Kernel Mode Performance WinDriver s API is optimized for performance 1 3 Conclusion Using WinDriver a developer need only do the following to create an application that accesses the custom hardware e Start DriverWizard and detect the hardware and its resources e Automatically generate the device driver code from within DriverWizard or use one of the WinDriver samples as the basis for the application see Chapter 8 for an overview of WinDriver s enhanced support for specific chipsets e Modify the user mode application as needed using the generated sample functions to implement the desired functionality for your application Your hardware access application will run on all the supported platforms 1 6 just re compile the code for the target platform The code is binary compatible across Windows 98 Me 2000 XP Server 2003 Vista platforms so there is no need to rebuild the code when porting the driver between these operating systems 1 4 WinDriver Benefits 15 1 4 WinDriver Benefits Easy user mode driver development Friendly DriverWizard allows hardware diagnostics without writing a single line of code Automatically generates the driver code for the project in C C Visual Basic NET Delphi Pascal or Visual Basic Supports any USB device regardless of manufacturer Enhanced support for Cypress Microchip Philips
74. all version h e 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 see if you have this file If you do not follow these steps in order to install the file 1 Become super user su 2 Change directory to the Linux source directory cd usr src linux 3 Type make xconfig 4 Save the configuration by choosing Save and Exit 5 Type make dep In order to run GUI WinDriver applications e g DriverWizard 5 Debug Monitor 7 2 you must also have version 5 0 of the libstdc library libstde s0 5 If you do not have this file install it from the relevant RPM in your Linux distribution e g compat libstdc Before proceeding with the installation you must also make sure that you have a linux symbolic link If you do not create one by typing 4 2 WinDriver Installation Process 52 usr src ln s lt target kernel gt linux For example for the Linux 2 4 kernel type usr src ln s linux 2 4 linux 4 2 3 2 Installation 1 Insert the WinDriver CD into your Linux machine s CD drive or copy the downloaded file to your preferred directory 2 Change directory to your preferred installation directory for example to your home directory cd 3 Extract the WinDriver distribution file WD920LN tgz tar xvzf lt file location gt WD920LN tgz
75. anage Catalog Items and then click the Import button and select the WinDriver cec file from the relevant WinDriver samples wince_install lt TARGET_CPU gt directory e g WinDriver samples wince_install ARMV4I This will add a WinDriver component to the Platform Builder Catalog c In the Catalog view right click the mouse on the WinDriver Component node in the Third Party tree and select Add to OS design 3 Compile your Windows CE platform Sysgen stage 4 If you did not perform the procedure described in step 2 above perform the following steps after the Sysgen stage in order to manually integrate the driver into your platform NOTE If you followed the procedure described in step 2 skip this step and go directly to step 5 a Run the Windows CE IDE and open your platform b Select Open Release Directory from the Build menu c Copy the WinDriver CE kernel file WinDriver redist lt TARGET_CPU gt windrvr6 dll to the _FLATRELEASEDIR sub directory on the target development platform should be the current directory in the new command window d Append the contents of the project_wd reg file in the WinDriver samples wince_installl directory to the project reg file in the _FLATRELEASEDIR sub directory e Append the contents of the project_wd bib file in the WinDriverl samples wince_installl directory to the project bib file in the _FLATRELEASEDIR sub directory This step i
76. anually either via Windows Add New Hardware Wizard or Upgrade Device Driver Wizard as explained below Windows Add New Hardware Wizard NOTE This method can be used if no other driver is currently installed for the device or if the user first uninstalls removes the current driver for the device Otherwise Windows New Hardware Found Wizard which activates the Add New Hardware Wizard will not appear for this device 1 To activate the Windows Add New Hardware Wizard attach the hardware device to the computer or if the device is already connected scan for hardware changes Refresh 2 When Windows Add New Hardware Wizard appears follow its installation instructions When asked point to the location of the INF file in your distribution package Windows Upgrade Device Driver Wizard 1 Open Windows Device Manager From the System Properties window right click on My Computer and select Properties select the Device Manager tab 2 wm Select your device from the Device Manager devices list choose the Driver tab and click the Update Driver button To locate your device in the Device Manager select View devices by connection and navigate to Standard PC PCI bus PCI to USB Universal Host Controller or any other controller you are using OHCI EHCTD USB Root Hub lt your device gt 3 wm Follow the instructions of the Upgrade Device Driver Wizard that opens When asked point to the location
77. are If you select to use the WinDriver component as outlined in step 2 the registry file to modify is WinDriverl samples wince_install lt TARGET_CPU gt WinDriver reg e g 11 3 Windows CE Driver Distribution 111 WinDriver samples wince_install ARMV4I WinDriver reg Otherwise modify the WinDriver samples wince_install project_wd reg file 2 You can simplify the driver integration into your Windows CE platform by following the procedure described in this step before the Sysgen platform compilation stage NOTE e The procedure described in this step is relevant only for developers who use Windows CE 4 x 5 x with Platform Builder Developers who use Windows CE 6 x with MSDEV 2005 should skip to the next step 3 This procedure provides a convenient method for integrating WinDriver into your Windows CE platform If you select not to use this method you will need to perform the manual integration steps described in step 4 below after the Sysgen stage The procedure described in this step also adds the WinDriver kernel module windrvr6 dll to your OS image This is a necessary step if you want the WinDriver CE kernel file windrvr6 dll to be a permanent part of the Windows CE image NK BIN which is the case if you select to transfer the file to your target platform using a floppy disk However if you prefer to have the file windrvr6 dll loaded on demand via the CESH PPSH services you need to perform the manual integrati
78. ate an INF File 117 12 1 2 How Do I Install an INF File When No Driver Exists 117 12 1 3 How Do I Replace an Existing Driver Using the INF File 119 12 2 Renaming the WinDriver Kernel Driver 121 12 2 1 Windows Driver Rename o 121 12 2 1 1 Rename the Windows Driver Using Driver Wizard eca a acs Se a SE we OOO 122 12 2 1 2 Manually Rename the Windows Driver 124 12 2 2 Linux Driver Rename 2 125 12 2 2 1 Rename the Linux Driver Using DriverWizard 125 12 2 2 2 Manually Rename the Linux Driver 126 12 3 Digital Driver Signing amp Certification Windows 2000 XP Server 2003 ViSt es pra ra A 127 12 3 1 OVEIMIEW sos orinar as ir e hes 127 12 3 1 1 Authenticode Driver Signature 128 12 3 1 2 WHQL Driver Certification 128 12 3 2 Driver Signing amp Certification of WinDriver Based Drivers 129 12 3 2 1 WHQL DTM Test Notes 130 12 4 Windows XP Embedded WinDriver Component 131 A 64 bit Operating Systems Support 133 A l Supported 64 bit Architectures oaoa aa 133 A 2 Support for 32 bit Applications on 64 bit Architectures 133 A 3 64 bit and 32 bit Data Types o o 134 B WinDriver USB PC Host API Reference 135 B 1 WD _DriverName acpi 22644 se he ee bee eee oa 136 B 2 WinDriver USB WDU Library Overview 138 B 2 1 Calling Sequence for WinDriver USB
79. ate unplugging and replugging of the device prompting the operating system to re enumerate the device without resetting it This option is supported only on Windows XP and higher RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 177 REMARKS e WDU_ResetDevice is supported only on Windows and Windows CE beginning with Windows CE 5 0 The WD_USB_CYCLE_PORT option is supported on Windows XP and higher e The function issues a request from the Windows USB driver to reset a hub port provided the Windows USB driver supports this feature B 4 USB Functions 178 B 4 12 WDU_SelectiveSuspend PURPOSE e Submits a request to suspend a given device selective suspend or cancels a previous suspend request PROTOTYPE DWORD DLLCALLCONV WDU_SelectiveSuspend WDU_DEVICE HANDLE hDevice DWORD dwOptions PARAMETERS Input Output WDU DEVICE HANDLE DWORD DESCRIPTION A unique identifier for the device interface dwOptions Can be set to either of the following WDU_SELECTIVE_SUSPEND_OPTIONS values WDU_SELECTIVE_SUSPEND_SUBMIT submit a request to suspend the device WDU_SELECTIVE_SUSPEND_CANCEL cancel a previous request to suspend the device RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 If the device is busy when a suspend request is submitted dwOptions WDU_SELECTIVE_SUSPEND_SU
80. ayed on every interaction with the hardware using DriverWizard 234 D 3 Linux WinDriver Evaluation Limitations 235 e WinDriver CE emulation on Windows 2000 XP Server 2003 Vista will stop working after 30 days D 3 Linux WinDriver Evaluation Limitations e Each time WinDriver is activated an Unregistered message appears e DriverWizard 5 Each time DriverWizard is activated an Unregistered message appears An evaluation message is displayed on every interaction with the hardware using DriverWizard e WinDriver s kernel module will work for no more then 60 minutes at a time In order to continue working the WinDriver kernel module must be reloaded remove and insert the module using the following commands To remove sbin rmmod windrvr6 To insert sbin modprobe windrvr6 Appendix E Purchasing WinDriver Fill in the order form found in Start WinDriver Order Form on your Windows start menu and send it to Jungo via email fax or mail see details below Your WinDriver package will be sent to you via Fedex or standard postal mail The WinDriver license string will be emailed to you immediately EMAIL Support support jungo com Sales sales jungo com PHONE USA Toll Free 1 877 514 0537 Worldwide 972 9 8859365 POSTAL ADDRESS Jungo Ltd P O Box 8493 Netanya 42504 ISRAEL WEB http www jungo com FAX USA Toll Free 1 877 514 0538 Worldwide 972 9 8859366 Appendix F Di
81. back is supported only in Windows operating systems starting from Windows 2000 B 4 USB Functions 146 B 4 USB Functions The functions described in this section are declared in the WinDriver include wdu_lib h header file B 4 1 WDU_Init PURPOSE e Starts listening to devices matching input criteria and registers notification callbacks for these devices PROTOTYPE DWORD WDU_Init WDU_DRIVER_HANDLE phDriver WDU_MATCH TABLE pMatchTables DWORD dwNumMatchTables WDU_EVENT_TABLE pEventTable const chiar isikicensic DWORD dwOptions PARAMETERS pEventTable WDU_EVENT_TABLE DWORD B 4 USB Functions 147 DESCRIPTION pEventTable Pointer to an event table structure B 5 2 2 which holds the addresses of the user mode device status change notification callback functions B 3 and the data to pass to the callbacks sLicense WinDriver s license string dwOptions Can be zero or WD_ACKNOWLEDGE the user can seize control over the device when returning value in WDU_ATTACH_CALLBACK B 3 1 RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 148 B 4 2 WDU_SetInterface PURPOSE e Sets the alternate setting for the specified interface PROTOTYPE DWORD WDU_SetInterface WDU_DEVICE HANDLE hDevice DWORD dwInterfaceNum DWORD dwAlternateSetting PARAMETERS Tnput Output WDU_DEVICE_HANDLE gt dwInterfaceN
82. be installed using the wdreg utility as explained in the following sections 10 2 2 The WDREG Utility WinDriver provides a utility for dynamically loading and unloading your driver which replaces the slower manual process using Windows Device Manager which can still be used for the device INF For Windows 2000 XP Server 2003 Vista this utility is provided in two forms wdreg and wdreg_gui Both versions can be found under the WinDriver util directory can be run from the command line and provide the same functionality The difference is that wdreg_gui displays installation messages graphically while wdreg displays them in console mode For Windows 98 Me the wdreg16 utility is provided This section describes the usage of wdreg wdreg_gui wdreg16 on Windows operating systems NOTES 1 wdreg for Windows 2000 XP Server 2003 Vista is dependent on the Driver Install Frameworks API DIFxAPI DLL difxapi dll unless when run with the compat option described below difxapi dll is provided under the WinDriver util diretory 2 The explanations and examples below refer to wdreg but for Windows 2000 XP Server 2003 Vista you can replace any references to wdreg with wdreg_gui 3 For Windows 98 Me replace the references to wdreg with wdreg16 unless otherwise indicated in the documentation 4 On Windows 98 Me you can only use wdreg16 to install the windrvr6 sys WDM driver by installing windrvr6 inf but you cannot use wdreg16
83. cense hWD amp lic WD_Close hWD return dwStatus B 7 User Mode Utility Functions 210 B 7 User Mode Utility Functions This section describes a number of user mode utility functions you will find useful for implementing various tasks These utility functions are multi platform implemented on all operating systems supported by WinDriver B 7 1 Stat2Str Q PURPOSE e Retrieves the status string that corresponds to a status code PROTOTYPE const char Stat2Str DWORD dwStatus PARAMETERS input Output DWORD DESCRIPTION dwStatus A numeric status code RETURN VALUE Returns the verbal status description string that corresponds to the specified numeric status code REMARKS See section B 8 for a complete list of status codes and strings B 7 User Mode Utility Functions B 7 2 get_os_type PURPOSE e Retrieves the type of the operating system PROTOTYPE OS_TYPE get_os_type void RETURN VALUE Returns the type of the operating system If the operating system type is not detected returns OS_CAN_NOT_DETECT 211 B 7 User Mode Utility Functions 212 B 7 3 ThreadStart PURPOSE e Creates a thread PROTOTYPE DWORD ThreadStart HANDLE phThread HANDLER_FUNC pFunc void pData PARAMETERS Input Output gt phThread HANDLE gt pFunc typedef void HANDLER_FUNC Input void pData VOID DESCRIPTION phThread Returns the handle to the created thread Start
84. ch interface may operate independently The interface descriptor describes the number of the interface the 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 3 8 WinDriver USB 38 Endpoint Level The lowest level is the endpoint descriptor which provides the host with information regarding the endpoint s data transfer type and maximum packet size For isochronous endpoints the maximum packet size is used to reserve the required bus time for the data transfer i e the bandwidth Other endpoint attributes are its bus access frequency endpoint number error handling mechanism and direction The same endpoint can have different properties and consequently different uses in different alternate settings Seems complicated Not at all WinDriver automates the USB configuration process The included DriverWizard utility 5 and USB diagnostics application scan the USB bus detect all USB devices and their configurations interfaces alternate settings and endpoints and enable you 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 conta
85. clude all supported Windows CE platforms including Windows Mobile 1 Copy WinDriver s kernel module windrvr6 dll from the WinDriver redist WINCE lt TARGET_CPU gt directory on the Windows host development PC to the Windows directory on your target Windows CE platform 2 Add WinDriver to the list of device drivers Windows CE loads on boot e Modify the registry according to the entries documented in the file WinDriver samples wince_installl project_wd reg This can be done using the Windows CE Pocket Registry Editor on the hand held CE computer or by using the Remote CE Registry Editor Tool supplied with MS eMbedded Visual C Windows CE 4 x 5 x MSDEV NET 2005 Windows Mobile or Windows CE 6 x Note that in order to use the Remote CE Registry Editor tool you will need to have Windows CE Services installed on your Windows host platform On Windows Mobile the operating system s security scheme prevents the loading of unsigned drivers at boot time therefore the WinDriver kernel module has to be reloaded after boot To load WinDriver on the target Windows Mobile platform every time the OS is started copy the WinDriver redist Windows_Mobile_5_ARMV4I wdreg exe utility to the Windows StartUp directory on the target 3 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
86. ctionality and enables you to code your specific driver logic from the user mode 1 5 On Windows and Linux you can change the name of the WinDriver kernel module to your preferred driver name and then distribute the renamed driver instead of windrvr6 sys o ko The following sections explain how to rename the driver for each of the supported operating systems i A renamed WinDriver kernel driver can be installed on the same PC as the original windrvr6 sys o ko kernel module You can also install multiple renamed WinDriver drivers on the same PC simultaneously TIP Try to give your driver a unique name in order to avoid a potenial conflict with other drivers on the target PCs on which your driver will be installed 12 2 1 Windows Driver Rename Rename the Windows WinDriver kernel driver windrvr6 sys using either of the two alternative methods described in the following sections TIP It is recommended to use the first method described in setion 12 2 1 1 since it automates most of the work for you 12 2 Renaming the WinDriver Kernel Driver 122 NOTES e References to the WinDriver redist directory in this section can be replaced with WinDriver redist_win98_compat The redist directory contains a digitally signed WHQL compliant windrvr6 sys driver and related files The redist_win98_compat directory contains an unsigned non WHQL compliant version of the driver for Windows 98 Me and high
87. current driver for the device Otherwise the Windows Found New Hardware Wizard which activates the Add New Hardware Wizard will not appear for this device 1 To activate the Windows Add New Hardware Wizard attach the hardware device to the computer or if the device is already connected scan for hardware changes Refresh 2 When Windows Add New Hardware Wizard appears follow its installation instructions When asked specify the location of the INF file in your distribution package Windows Upgrade Device Driver Wizard 1 Open Windows Device Manager From the System Properties window right click on My Computer and select Properties select the Device Manager tab 2 wm Select your device from the Device Manager devices list open it choose the Driver tab and click the Update Driver button To locate your device in the Device Manager select View devices by connection and navigate to Standard PC PCI bus PCI to USB Universal Host Controller or any other controller you are using OHCI EHCI USB Root Hub lt your device gt 3 wm Follow the instructions of the Upgrade Device Driver Wizard that opens Locate the INF in your distribution package when asked 12 2 Renaming the WinDriver Kernel Driver 121 12 2 Renaming the WinDriver Kernel Driver The WinDriver APIs are implemented within the windrvr6 sys dll o ko kernel driver module depending on the OS which provides the main driver fun
88. disconnection of hardware for example 2 5 Associating the Hardware to the Driver Operating systems differ in how they link a device to its driver In Windows the link is performed by the INF file which registers the device to work with the driver This association is performed before the DriverEntry routine is called The operating system recognizes the device looks up in its database which INF file is associated with the device and according to the INF file calls the driver s entry point In Linux the link between a device and its driver is defined in the init_module routine The init_module routine includes a callback which states what hardware the driver is designated to handle The operating system calls the driver s entry point based on the definition in the code 2 6 Communicating with Drivers A driver can create an instance thus enabling an application to open a handle to the driver through which the application can communicate with it The applications communicate with the drivers using a file access API Application Program Interface Applications open a handle to the driver using CreateFile call in Windows or open call in Linux with the name of the device as the file name In order to read from and write to the device the application calls ReadFile and WriteFile in Windows or read write in Linux 2 6 Communicating with Drivers 28 Sending requests is accomplished using an I O control
89. driver called a module Linux modules can be loaded or removed dynamically without requiring the system to be shut down A Linux driver can be written so that it is statically linked or written in a modular form that allows it to be dynamically loaded 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 Like Unix device drivers Linux device drivers are either layered or monolithic drivers 2 4 The Entry Point of the Driver 27 2 4 The Entry Point of the Driver Every device driver must have one main entry point like the main function in a C console application This entry point is called DriverEntry in Windows and init_module in Linux When the operating system loads the device driver this driver entry procedure is called There is some global initialization that every driver needs to perform only once when it is loaded for the first time This global initialization is the responsibility of the DriverEntry init_module routine The entry function also registers which driver callbacks will be called by the operating system These driver callbacks are operating system requests for services from the driver In Windows these callbacks are called dispatch routines and in Linux they are called file operations Each registered callback is called by the operating system as a result of some criteria such as
90. dware is performing as expected Code generation Once you are ready to build your code let DriverWizard generate your driver code for you The code generated by DriverWizard is composed of the following elements Library functions for accessing each element of your device s resources memory ranges I O ranges registers and interrupts A 32 bit diagnostics program in console mode with which you can diagnose your device This application utilizes the special library functions described above Use this diagnostics program as your skeletal device driver A project workspace solution that you can use to automatically load all of the project information and files into your development environment For Linux DriverWizard generates the required makefile 5 2 DriverWizard Walkthrough To use DriverWizard 1 Attach your hardware to the computer Attach your device to a USB port on your computer 2 Run Driver Wizard and select your device a Click Start Programs WinDriver Driver Wizard or double click the DriverWizard icon on your desktop on Windows or run the wdwizard utility from the WinDriver wizard directory b Click New host driver project to start a new project or Open an existing project to open a saved session 5 2 DriverWizard Walkthrough 61 Choose Your Project WinDriver The World Standard in Driver Development New host driver project Open an existing project Canc
91. e _FLATRELEASEDIR sub directory e wm Append the contents of the project_wd bib file in the WinDriver samples wince_install directory to the project bib file in the _FLATRELEASEDIR sub directory This step is only necessary if you want the WinDriver CE kernel file windrvr6 dll to be a permanent part of the Windows CE image NK BIN which is the case if you select to transfer the file to your target platform using a floppy disk If you prefer to have the file windrvr6 dll loaded on demand via the CESH PPSH services you do not need to carry out this step until you build a permanent kernel 5 Select Make Run Time Image from the Build menu and name the new image NK BIN 6 Download your new kernel to the target platform and initialize it either by selecting Download Initialize from the Target menu or by using a floppy disk 7 Restart your target CE platform The WinDriver CE kernel will automatically load 8 Install your hardware control application DLL on the target If your hardware control application DLL uses wdapi920 dll as is the case for the sample and generated DriverWizard WinDriver projects also copy this DLL from the WinDriver redist WINCE lt TARGET_CPU gt directory on the Windows host development PC to the target s Windows directory 11 3 Windows CE Driver Distribution 113 11 3 2 Distribution to Windows CE Computers NOTE Unless otherwise specified Windows CE references in this section in
92. e from the same application REMARKS e The ability to rename the WinDriver kernel module is supported on Windows and Linux as explained in section 12 2 On Windows CE always call the WD_DriverName function with the default WinDriver kernel module name windrvr6 or refrain from calling the function altogether B 2 WinDriver USB WDU Library Overview 138 B 2 WinDriver USB WDU Library Overview This section provides a general overview of WinDriver s USB Library WDU including e An outline of the WOU_xxx API calling sequence see section B 2 1 e Instructions for upgrading code developed with the previous WinDriver USB API used in version 5 22 and earlier to use the improved WDU_xxx API see section B 2 2 If you do not need to upgrade USB driver code developed with an older version of WinDriver simply skip this section The WDU library s interface is found in the WinDriver include wdu_lib h and WinDriver include windrvr h header files which should be included from any source file that calls the WDU API wdu_lib h already includes windrvr h B 2 WinDriver USB WDU Library Overview 139 B 2 1 Calling Sequence for WinDriver USB The WinDriver WDU_xxx USB API is designed to support event driven transfers between your user mode USB application and USB devices This is in contrast to earlier versions in which USB devices were initialized and controlled using a specific sequence of function calls You can i
93. e menu DriverWizard will generate the source code for your driver and place it along with the project file xxx wdp where xxx is the project name The files are saved in a directory DriverWizard creates for every development environment and operating system selected in the code generation dialogue box 5 3 3 2 The Generated USB C Code In the source code directory you now have a new xxx_diag c source file where xxx is the name you selected for your DriverWizard project This file implements a diagnostic USB application which demonstrates how to use WinDriver s USB API to locate and communicate with your USB device s including detection of Plug and Play events device insertion removal etc performing read write transfers on the pipes resetting the pipes and changing the device s active alternate setting The generated application supports handling of multiple identical USB devices 5 3 DriverWizard Notes 71 5 3 3 3 The Generated Visual Basic and Delphi Code The generated DriverWizard Visual Basic and Delphi code includes similar functions and provides similar functionality as the generated C code described in section 5 3 3 2 The generated Delphi code implements a console application like the C code while the Visual Basic code implements a GUI application 5 3 3 4 The Generated C and Visual Basic NET Code The generated DriverWizard C and Visual Basic NET code provides similar functionality as the generated C code
94. e the dialogue box until you have generated an INF for your device using the steps below 5 2 DriverWizard Walkthrough 62 3 Generate an INF file for Driver Wizard When developing a driver for a Plug and Play Windows operating system 1 e Windows 98 Me 2000 XP Server 2003 Vista you are required to install an INF file for your device This file will register your Plug and Play device to work with the windrvr6 sys driver The file generated by the DriverWizard in this step should later be distributed to your customers using Windows 98 Me 2000 XP Server 2003 Vista and installed on their PCs The INF file you generate here is also designed to enable DriverWizard to diagnose your device As explained earlier this is required only when using WinDriver to support a Plug and Play device such as USB on a Plug and Play system Windows 98 Me 2000 XP Server 2003 Vista Additional information concerning the need for an INF file is explained in section 12 1 1 If you do not need to generate an INF file e g if you are using DriverWizard on Linux skip this step and proceed to the next one To generate the INF file with the DriverWizard follow the steps below a In the Select Your Device screen click the Generate INF file button or click Next b DriverWizard will display information detected for your device Vendor ID Product ID Device Class manufacturer name and device name and allow you to modify this information Enter I
95. e you do not distribute your WinDriver license string which is used in the code 11 4 3 Installation Script We suggest that you supply an installation shell script that copies your driver executables DLL to the correct locations perhaps usr local bin and then invokes make or gmake to build and install the WinDriver kernel module Chapter 12 Driver Installation Advanced Issues 12 1 INF Files Windows 98 Me 2000 XP Server 2003 Vista Device information INF files are text files that provide information used by the Plug and Play mechanism in Windows 98 Me 2000 XP Server 2003 Vista to install software that supports a given hardware device INF files are required for hardware that identifies itself such as USB and PCI An INF file includes all necessary information about a device and the files to be installed When hardware manufacturers introduce new products they must create INF files to explicitly define the resources and files required for each class of device In some cases the INF file for your specific device is supplied by the operating system In other cases you will need to create an INF file for your device WinDriver s DriverWizard can generate a specific INF file for your device The INF file is used to notify the operating system that WinDriver now handles the selected device For USB devices you will not be able to access the device with WinDriver either from the DriverWizard or from the code withou
96. ecting to rename and rebuild the windrvr6 sys driver module as explained in section 12 2 a new debug symbols file is created for the driver The original defects xml file is also applicable to the rebuilt driver Before submitting the file for certification you need to create a new catalog file which lists your driver and specific INF file s and refer to this catalog file from your INF file s as explained above 12 3 2 12 4 Windows XP Embedded WinDriver Component When creating a Windows XP Embedded image using the Target Designer tool from Microsoft s Windows Embedded Studio you can select the components that you wish to add to your image The added components will be installed automatically during the first boot on the Windows XP Embedded target on which the image is loaded To automatically install the required WinDriver files such as the windrvr6 inf file and the WinDriver kernel driver that it installs windrvr6 sys your device INF file and the WinDriver API DLL wdapi920 dll on Windows XP Embedded platforms you can create a relevant WinDriver component and add it to your Windows XP Embedded image WinDriver simplifies this task for you by providing you with a ready made component WinDriver redist xp_embedded wd_component windriver sld To use the provided component follow the steps below NOTE The provided windriver sld component relies on the existence of a wd_files directory in the same directory that
97. ectory on the target 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 to make sure that WinDriver CE is loaded and is functioning correctly see section 4 4 which describes how to check your installation 4 2 2 3 Windows CE Installation Note The WinDriver installation on the host Windows 2000 XP Server 2003 Vista PC defines a WD_BASEDIR environment variable which is set to point to the location of your WinDriver directory as selected during the installation This variable is used during the DriverWizard 5 code generation it determines the default directory for saving your generated code and is used in the include paths of the generated project make files Therefore if you decide to change the name and or location of your host WinDriver directory after the installation you should also edit the value of the WD_BASEDIR environment variable and set it to point to the location of your new WinDriver directory You can edit the value of WD_BASEDIR by following these steps 1 Open the System Properties dialogue Start System Control Panel System 2 In the Advanced tab click the Environment Variables button 3 In the System variables box select the WD_BASEDIR variable and click the Edit button or double click the mouse on t
98. ed by the function PROTOTYPE DWORD WDU_GetDevicelnfo WDU_DEVICE HANDLE hDevice WDU_DEVICE ppDevicelInfo PARAMETERS input Output WDU_DEVICE_HANDLE gt ppDevicelnfo WDU_DEVICE DESCRIPTION A unique identifier for a device interface ppDevicelnfo Pointer to pointer to a USB device information structure B 5 2 3 RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 153 B 4 6 WDU_PutDevicelnfo PURPOSE e Receives a device information pointer allocated with a previous WDU_GetDeviceInfo B 4 5 call in order to perform the necessary cleanup PROTOTYPE void WDU_PutDevicelnfo WDU_DEVICE pDevicelInfo PARAMETERS Input Output gt pDevicelnfo WDU_DEVICE DESCRIPTION Name Description pDeviceInfo Pointer to a USB device information structure B 5 2 3 as returned by a previous call to WDU_GetDeviceInfo B 4 5 RETURN VALUE None B 4 USB Functions 154 B 4 7 WDU_Uninit PURPOSE e Stops listening to devices matching a given criteria and un registers the notification callbacks for these devices PROTOTYPE void WDU_Uninit WDU_DRIVER_ HANDLE hDriver PARAMETERS Type Input Output WDU_DRIVER_HANDLE DESCRIPTION Name Description hDriver Handle to the registration received from WDU_Init B 4 1 RETURN VALUE None B 4 USB Functions B 4 8 Single Blocking Transfer Functions
99. el Figure 5 1 Create or Open a WinDriver Project c Select your Device from the list of devices detected by DriverWizard Select Your Device Please select your device from the detected devices below or choose ISA card for non plug play cards Type Description Vendor j L Refresh devices list PCI PCI Virtual Device ISA ISA Device ISA Device Generis INE Re ISA Parallel Port ISA Device PCI VIA YT8374 P4X400 Host Controller AGP Bridge VIA PCI VIA VT8235 PCI to PCI Bridge AGP 2 0 3 0 VIA NVIDIA NV18 6 GeForce4 MX 4000 NVIDIA PCI Realtek RTL81394 8 C Fast Ethernet Adapter Realtek PCI PLX PCI 9056RDK Lite PCI 9056 Rapid Development Kit PLX PCI NEC UPD9210FGC 7EA USB Host Controller NEC PCI NEC uPD9210FGC 7EA USB Host Controller NEC PCI NEC Uninstall INF file emiconductor Corp PCI PCI VIA YT83C572 VT6202 USB 1 0 Controller PCI VIA YT83C572 VT6202 USB 1 0 Controller PCI VIA YT6202 USB 2 0 Enhanced Host Controller PCI VIA VT8235 PCI to ISA Bridge PCI VIA YT82C596b Sound Controller Device Description Vendor ID 04b4 Product ID 1003 Interface number Unknown This device is configured to work with WinDriver DEVICE Figure 5 2 Select Your Device NOTE On Windows 98 if you do not see your USB device in the list reconnect it and make sure the New Hardware Found Add New Hardware wizard appears for your device Do not clos
100. emove or comment out the reference to the wd920 cat file from the windrvr6 inf file or your renamed version of this file e Submit your driver for WHQL certification or have it Authenticode signed Note that while renaming WinDriver redist windrvr6 sys nullifies the driver s digital signature the driver is still WHQL compliant and can therefore be submitted for WHQL testing To digitally sign certify your driver follow these steps Create a new catalog file for your driver as explained in Microsoft s WHQL documentation The new file should reference both windrvr6 sys 12 3 Digital Driver Signing amp Certification Windows 2000 XP Server 2003 Vista 130 or your renamed driver and any INF files used in your driver s installation Assign the name of your new catalog file to the CatalogFile entry in your driver s INF file s You can either change the CatalogFile entry in the windrvr6 inf file to refer to your new catalog file and add a similar entry in your device specific INF file or incorporate both windrvr6 inf and your device INF file into a single INF file that contains such a CatalogFile entry If you wish to submit your driver for WHQL certification refer to the additional guidelines in section 12 3 2 1 Submit your driver for WHQL certification or for an Authenticode signature Note that many WinDriver customers have already successfully digitally signed and certified their WinDriver based
101. ent O T DESCRIPTION Description dwLevel Assigns the level in the Debug Monitor in which the data will be declared If zero D_ERROR will be declared For more details please refer to DEBUG_LEVEL in windrvr h dwSection Assigns the section in the Debug Monitor in which the data will be declared If zero S_MISC will be declared For more details please refer to DEBUG_SECTION in windrvr h Format control Sting Optional arguments limited to 256 bytes RETURN VALUE None B 7 User Mode Utility Functions 224 B 7 15 WD_LogStart PURPOSE e Opens a log file PROTOTYPE DWORD WD_LogStart const char x sFileName const char sMode PARAMETERS Name Input Output DESCRIPTION Name of log file to be opened sMode Type of access permitted For example NULL or w opens an empty file for writing and if the given file exists its contents are destroyed a opens a file for writing at the end of the file i e append RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 REMARKS e Once a log file is opened all API calls are logged in this file You may add your own printouts to the log file by calling WD_LogAdd B 7 17 B 7 User Mode Utility Functions B 7 16 WD_LogStop PURPOSE e Closes a log file PROTOTYPE VOID WD_LogStop void RETURN VALUE None 225 B 7 User Mode Utility Functions 226 B 7 17 WD _LogAdd PURPOSE
102. ents Figure 1 1 WinDriver Architecture For hardware access your application calls one of the WinDriver user mode functions The user mode function calls the WinDriver kernel which accesses the hardware for you through the native calls of the operating system 1 6 What Platforms Does WinDriver Support 17 1 6 What Platforms Does WinDriver Support WinDriver supports the following operating systems e Windows 98 Me 2000 XP Server 2003 Vista henceforth collectively Windows e Windows CE 4 x 5 x Windows CE NET Windows Embedded CE v6 00 Windows Mobile 5 0 6 0 henceforth collectively Windows CE e Linux The same source code will run on all supported platforms simply re compile it for the target platform The source code is binary compatible across Windows 98 Me 2000 XP Server 2003 Vista so executables created with WinDriver can be ported among these operating systems without re compilation Even if your code is meant only for one of the supported operating systems using WinDriver will give you the flexibility to move your driver to another operating system in the future without needing to change your code 1 7 Limitations of the Different Evaluation Versions All the evaluation versions of the WinDriver USB Host toolkit are full featured No functions are limited or crippled in any way The evaluation version of WinDriver varies from the registered version in the following ways e Each time WinDriv
103. er Renaming the signed windrvr6 sys driver nullifies its signature In such cases you can select either to sign your new driver or to distribute an unsigned driver For more information on driver signing and certification refer to section 12 3 For guidelines for signing and certifying your renamed driver refer to section 12 3 2 12 2 1 1 Rename the Windows Driver Using DriverWizard To rename your Windows WinDriver kernel driver using DriverWizard recommended follow the steps in this section ja References to xxx in this section should be replaced with the name of your generated DriverWizard driver project Use the DriverWizard utility to generate driver code for your hardware on Windows 5 2 7 using your preferred driver name xxx as the name of the generated driver project The generated project directory xxx will include an xxx_installation directory with the following files and directories e redist directory xxx sys Your new driver which is actually a renamed copy of the windrvr6 sys driver Note The properties of the generated driver file such as the file s version company name etc are identical to the properties of the original windrvr6 sys driver You can rebuild the driver with new properties using the files from the generated xxx_installation sys directory as explained below xxx_driver inf A modified version of the windrvr6 inf file which will be used to instal
104. er is activated an Un registered message appears e When using the DriverWizard a dialogue box with a message stating that an evaluation version is being run appears on every interaction with the hardware e In the Linux and Windows CE versions the driver will remain operational for 60 minutes after which time it must be restarted e The Windows evaluation version expires 30 days from the date of installation For more details please refer to appendix D 1 8 How Do I Develop My Driver with WinDriver 1 8 1 On Windows and Linux 1 Start DriverWizard and use it to diagnose your hardware see details in Chapter 5 1 9 What Does the WinDriver Toolkit Include 18 2 Let DriverWizard generate skeletal code for your driver or use one of the WinDriver samples as the basis for your driver application see Chapter 8 for details regarding WinDriver s enhanced support for specific chipsets 3 Modify the generated sample code to suit your application s needs 4 Run and debug your driver The code generated by DriverWizard is a diagnostics program that contains functions that perform data transfers on the device s pipes send requests to the control pipe change the active alternate setting reset pipes and more 1 8 2 On Windows CE 1 Plug your hardware into a Windows host machine Diagnose your hardware using DriverWizard Let DriverWizard generate your driver s skeletal code gt uu N Modify thi
105. escriptor the descriptor is returned as a bytes array dwBufSize The size of pbBuf langID The language ID to be used in the get string descriptor request that is sent to the device If the langID param is O the function will use the first supported language ID returned from the device if exists pdwDescSize If not NULL will be updated with the size of the returned descriptor B 4 USB Functions 183 RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 REMARKS e If pbBuf is not large enough to hold the string descriptor dwBufSize lt pdwDescSize the returned descriptor will be truncated to dwBufSize bytes B 5 USB Data Types 184 B 5 USB Data Types The types described in this section are declared in the WinDriver include windrvr h header file unless otherwise specified in the documentation B 5 1 WD_DEVICE_REGISTRY PROPERTY Enumeration Enumeration of device registry property identifiers String properties are returned in NULL terminated WCHAR array format i For more information regarding the properties described in this enumaration refer to the description of the Windows IoGetDeviceProperty function s DevicePropert y parameter in the Microsoft Development Network MSDN documentation WdDevicePropertyBootConfiguration The hardware resources assigned to the device by the firmware in raw data form WdDevicePropertyBootConfigurationTranslated
106. ey provide direct access to hardware and privileged operating system functions VxD drivers can be stacked or layered in any fashion but the driver structure itself does not impose any layering 2 3 3 Unix Device Drivers In the classic Unix driver model devices belong to one 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 linked into the kernel that run in privileged kernel mode Generally driver code runs on behalf of a user mode application Access to Unix drivers from user mode applications is provided via the file system In other words devices appear to the applications as special device files that can be opened Unix device drivers are either layered or monolithic drivers A monolithic driver can be perceived as a one layer layered driver 2 3 4 Linux Device Drivers Linux device drivers are based on the classic Unix device driver model In addition Linux introduces some new characteristics Under Linux a block device can be accessed like a character device as in Unix but also has a block oriented interface that is invisible to the user or application Traditionally under Unix device drivers are linked with the kernel and the system is brought down and restarted after installing a new driver Linux introduces the concept of a dynamically loadable
107. fer Control Transfer is mainly intended to support configuration command and status operations between the software on the host and the device This transfer type is used for low full and high speed devices Each USB device has at least one control pipe default pipe which provides access to the configuration status and control information Control transfer is bursty non periodic communication The control pipe is bi directional i e data can flow in both directions Control transfer has a robust error detection recovery and retransmission mechanism and retries are made without the involvement of the driver The maximum packet size for control endpoints can be only 8 bytes for low speed devices 8 16 32 or 64 bytes for full speed devices and only 64 bytes for high speed devices For more in depth information regarding USB control transfers and their implementation refer to section 9 2 of the manual 3 6 USB Data Transfer Types 35 3 6 2 Isochronous Transfer Isochronous Transfer is most commonly used for time dependent information such as multimedia streams and telephony This transfer type can be used by full speed and high speed devices but not by low speed devices Isochronous transfer is periodic and continuous The isochronous pipe is unidirectional i e a certain endpoint can either transmit or receive information Bi directional isochronous communication requires two isochronous pipes one in each direc
108. fers between your user mode USB application and USB devices This is in contrast to earlier versions in which USB devices were initialized and controlled using a specific sequence of function calls As a result of this change you will need to modify your USB applications that were designed to interface with earlier versions of WinDriver to ensure that they will work with WinDriver v6 X on all supported platforms and not only on Microsoft Windows You will have to reorganize your application s code so that it conforms with the framework illustrated by the piece of meta code provided in section B 2 1 In addition the functions that collectively define the USB API have been changed The new functions described in the next few sections provide an improved interface between user mode USB applications and the WinDriver kernel module Note that the new functions receive their parameters directly unlike the old functions which received their parameters using a structure The table below lists the legacy functions in the left column and indicates in the right column which function or functions replace s each of the legacy functions Use this table to quickly determine which new functions to use in your new code High Level API has been replaced Dy WD_Open U_Init B 4 1 WD_Version WD_UsbScanDevice D NDU_Set Interface 0 B42 WDU_GetDeviceInfo B 4 5 fOU_Uninit 0 1847 has been replaced by WD_UsbTransfer WDU_Transfe
109. he case of a write stream before closing it Note Each call to WDU_StreamOpen must have a matching call to WDU_StreamClose later on in the code in order to perform the necessary cleanup Chapter 10 Dynamically Loading Your Driver 10 1 Why Do You Need a Dynamically Loadable Driver When adding a new driver you may be required to reboot the system in order for it to load your new driver into the system WinDriver is a dynamically loadable driver which enables your customers to start your application immediately after installing it without the need for reboot NOTE In order to successfully UNLOAD your driver make sure there are no open handles to the driver from WinDriver applications or from connected Plug and Play devices that were registered with WinDriver using an INF file 10 2 Windows Dynamic Driver Loading 10 2 1 Windows Driver Types Windows drivers can be implemented as either of the following types e WDM Windows Driver Model drivers Files with the extension sys on Windows 98 Me 2000 XP Server 2003 Vista e g windrvr6 sys WDM drivers are installed via the installation of an INF file see below 99 10 2 Windows Dynamic Driver Loading 100 e Non WDM Legacy drivers These include drivers for non Plug and Play Windows operating systems Windows NT 4 0 and files with the extension vxd on Windows 98 Me The WinDriver Windows kernel module windrvr6 sys is a fully WDM driver which can
110. he variable 4 In the Edit System Variable dialogue replace the Variable Value with the full path to your new WinDriver directory then click OK and click OK again from the System Properties dialogue Note that if you install the WinDriver Windows 98 Me 2000 XP Server 2003 Vista tool kit on the same host PC the installation will override the value of the WD_BASEDIR variable from the Windows CE installation 4 2 WinDriver Installation Process 51 4 2 3 Linux WinDriver Installation Instructions 4 2 3 1 Preparing the System for Installation In Linux kernel modules must be compiled with the same header files that the kernel itself was compiled with Since WinDriver installs the kernel module windrvr6 o ko 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 the Linux kernel source code e If you have yet to install Linux install it including the kernel source code by following the instructions for your Linux distribution e If Linux is already installed on your machine check whether the Linux source code was installed You can do this by looking for linux in the usr sre directory If the source code is not installed either install it or reinstall Linux with the source code by following the instructions for your Linux distribution Inst
111. hi 4 1 1 2 Windows 2000 XP Server 2003 Vista System Requirements e Any x86 32 bit or 64 bit x64 AMD64 or Intel EM64T processor e Any development environment supporting C NET VB or Delphi e Windows 2000 requires SP4 e Windows XP requires SP2 43 4 1 System Requirements 44 4 1 2 Windows CE System Requirements e An x86 MIPS ARM Windows Embedded CE v6 00 or Windows CE 4 x 5 0 NET target platform or an ARMV4I Windows Mobile 5 0 6 0 target platform Windows 2000 XP Server 2003 Vista host development platform For Windows CE 4 x 5 0 Microsoft eMbedded Visual C with a corresponding target SDK OR Microsoft Platform Builder with a corresponding BSP Board Support Package for the target platform For Windows Embedded CE 6 0 Microsoft Visual Studio MSDEV NET with the Windows CE 6 0 plugin For Windows Mobile Microsoft Visual Studio MSDEV NET 2005 4 13 Linux System Requirements Any 32 bit x86 processor with a Linux 2 4 x or 2 6 x kernel or Any 64 bit x86 AMD64 or Intel EM64T x86_64 processor with a Linux 2 4 x or 2 6 x kernel or Any PowerPC 32 bit processor with a Linux 2 4 x or 2 6 x kernel or Any PowerPC 64 bit processor with a Linux 2 6 x kernel A GCC compiler NOTE The version of the GCC compiler should match the compiler version used for building the running Linux kernel Any 32 bit or 64 bit development environment depending on your target configuration support
112. holds the component Therefore do not rename the provided WinDriver redist xp_embedded wd_component wd_files directory or modify its contents unless instructed to so in the following guidelines 1 Modify the dev inf file The windriver sld component depends on the existence of a dev inf file in the wd_files directory The WinDriver installation on your development Windows platform contains a generic WinDriver redist xp_embedded wd_component wd_files dev inf file Use either of the following methods to modify this file to suit your device e Modify the generic dev inf file to describe your device At the very least you must modify the template DeviceList entry and insert your 12 4 Windows XP Embedded WinDriver Component 132 device s hardware type and vendor and product IDs For example for a device with vendor ID 0x1234 and product ID 0x5678 my_dev_usb Install USB VID_1234 amp PID_5678 OR e Create an INF file for your device using DriverWizard 5 2 3 and name it dev inf or use an INF file from one of WinDriver s enhanced support chipsets 8 that suits your card and rename it to dev inf Then copy your dev inf device INF file to the WinDriver redist xp_embedded wd_component wd_files directory 2 Add the WinDriver component to the Windows Embedded Component Database a Open the Windows Embedded Component Database Manager DBMgr b Click Import c Select the WinDriver component WinDriver red
113. ialized commands that only its driver knows In contrast most programs access devices by using generic commands The driver therefore accepts generic commands from a program and then translates them into specialized commands for the device 22 2 2 Classification of Drivers According to Functionality 23 2 2 Classification of Drivers According to Functionality There are numerous driver types differing in their functionality This subsection briefly describes three of the most common driver types 2 2 1 Monolithic Drivers Monolithic drivers are device drivers that embody all the functionality needed to support a hardware device 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 Application User Mode Kernel Mode Figure 2 1 Monolithic Drivers Monolithic drivers are supported in all operating systems including all Windows platforms and all Unix platforms 2 2 Classification of Drivers According to Functionality 24 2 2 2 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 exa
114. igning amp Certification Windows 2000 XP Server 2003 Vista 128 12 3 1 1 Authenticode Driver Signature The Microsoft Authenticode mechanism verifies the authenticity of driver s provider It allows driver developers to include information about themselves and their code with their programs through the use of digital signatures and informs users of the driver that the driver s publisher is participating in an infrastructure of trusted entities The Authenticode signature does not however guarantee the code s safety or functionality The WinDriver redist windrvr6 sys driver has an Authenticode digital signature 12 3 1 2 WHQL Driver Certification Microsoft s Windows Logo Program http www microsoft com whdc winlogo default mspx lays out procedures for submitting hardware and software modules including drivers for Microsoft quality assurance tests Passing the tests qualifies the hardware software for Microsoft certification which verifies both the driver provider s authenticity and the driver s safety and functionality Device drivers should be submitted for certification together with the hardware that they drive The driver and hardware are submitted to Microsoft s Windows Hardware Quality Labs WHQL testing in order to receive digital signature and certification This procedure verifies both the driver s provider and its behavior For detailed information regarding the WHQL certification process refer to
115. industry Uses commodity technologies Optimized for integration in peripheral and host hardware Low cost implementation therefore suitable for development of low cost peripherals Low cost cables and connectors Built in power management and distribution 3 3 USB Components The Universal Serial bus consists of the following primary components USB Host The USB host platform 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 the insertion and removal 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 allows multiple USB devices to attach to a single USB port on a USB host Hubs on the back plane of the hosts are called root hubs Other hubs are called external hubs USB Function A USB device that can transmit or receive data or control information over the bus and that provides a function A function is typically implemented as a separate peripheral device that plugs into a port on a hub using a cable However it is also possible to create a compound device which 1s a physical package that implements multiple functions and an embedded hub with a single USB cable A compound device appears to the host as a hub with one or more non removable USB devices which may have
116. ing C for user mode On your development PC glibe2 3 x libstde s0 5 is required for running GUI WinDriver applications e g DriverWizard 5 Debug Monitor 7 2 4 2 WinDriver Installation Process 45 4 2 WinDriver Installation Process The WinDriver CD contains all versions of WinDriver for all the different operating systems The CD s root directory contains the Windows 98 Me 2000 XP Server 2003 Vista and Windows CE version This will automatically begin when you insert the CD into your CD drive The other versions of WinDriver are located in sub directories i e Linux Wince etc 4 2 1 Windows WinDriver Installation Instructions NOTE You must have administrative privileges in order to install WinDriver on Windows 98 Me 2000 XP Server 2003 Vista 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 installation file WD920 EXE 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 WD920 EXE 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 e Typical install all WinDriver modu
117. ing address of the code that the new thread is to execute The handler s prototype HANDLER_FUNC is defined in utils h Pointer to the data to be passed to the new thread RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 7 User Mode Utility Functions 213 B 7 4 ThreadWait PURPOSE e Waits for a thread to exit PROTOTYPE void ThreadWait HANDLE hThread PARAMETERS Input Output gt hThread HANDLE DESCRIPTION hThread The handle to the thread whose completion is awaited RETURN VALUE None B 7 User Mode Utility Functions 214 B 7 5 OsEventCreate PURPOSE e Creates an event object PROTOTYPE DWORD OsEventCreate HANDLE phOsEvent PARAMETERS pavo ip gt phOsEvent HANDLE DESCRIPTION Description phOsEvent The pointer to a variable that receives a handle to the newly created event object RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 7 User Mode Utility Functions 215 B 7 6 OsEventClose PURPOSE e Closes a handle to an event object PROTOTYPE void OsEventClose HANDLE hOsEvent PARAMETERS TapuOutput HANDLE DESCRIPTION The handle to the event object to be closed RETURN VALUE None B 7 User Mode Utility Functions 216 B 7 7 OsEventWait PURPOSE e Waits until a specified event object is in the signaled state or the time out in
118. ins all configuration information acquired at this early stage 3 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 operating system s internals Using WinDriver USB developers can create USB drivers without having to use the operating system s development kits such as the Windows DDK In addition Windows developers do not need to familiarize themselves with Microsoft s Win32 Driver Module WDM The driver code developed with WinDriver USB is binary compatible across the supported Windows platforms Windows 98 Me 2000 XP Server 2003 Vista and source code compatible across all supported operating systems Windows 98 Me 2000 XP Server 2003 Vista Windows CE NET Windows Embedded CE v6 00 Windows Mobile 5 0 6 0 and Linux For an up to date list of supported operating systems visit Jungo s web site at http www jungo com WinDriver USB is a generic tool kit that supports all USB devices from all vendors and with all types of configurations WinDriver USB encapsulates the USB specification and architecture letting you focus on your application logic WinDriver USB features the graphical DriverWizard utility 5 which enables you to easily detect your hardware view its configuration information and test it before writing a single line of code DriverWizard first lets 3 8 WinDriver USB 39 you cho
119. ion 10 2 2 of the manual On the development PC you can have the INF file automatically installed when selecting to generate the INF file with the DriverWizard by checking the Automatically Install the INF file option in the DriverWizard s INF generation window see section 5 2 It is also possible to install the INF file manually on Windows 2000 XP Server 2003 Vista using either of the following methods Windows Found New Hardware Wizard This wizard is activated when the device is plugged in or if the device was already connected when scanning for hardware changes from the Device Manager Windows Add Remove Hardware Wizard Right click the mouse on My Computer select Properties choose the Hardware tab and click on Hardware Wizard Windows Upgrade Device Driver Wizard Select the device from the Device Manager devices list select Properties choose the Driver tab 12 1 INF Files Windows 98 Me 2000 XP Server 2003 Vista 118 and click the Update Driver button On Windows 2000 XP Server 2003 Vista you can choose to upgrade the driver directly from the Properties list In all the manual installation methods above you will need to point Windows to the location of the relevant INF file during the installation We recommend using the wdreg utility to install the INF file automatically instead of installing it manually Windows 98 Me On Windows 98 Me you need to install the INF file for your USB device m
120. ipe information structure DWORD Pipe number Zero for default pipe gt dwMaximumPacketSize DWORD Maximum size of packets that can be transferred using this pipe DWORD Transfer type for this pipe gt direction DWORD Direction of the transfer USB_DIR_IN or USB_DIR_OUT for isochronous bulk or interrupt pipes USB_DIR_IN_OUT for control pipes gt dwInterval DWORD Interval in milliseconds ms Relevant only to interrupt pipes B 6 General WD_xxx Functions 193 B 6 General WD_xxx Functions B 6 1 Calling Sequence WinDriver General Use The following is a typical calling sequence for the WinDriver API WD_Open WD_Version fC General WinDriver API A ag PrintDbgMessage as dd WD_DebugAdd WD_Sleep WD_Logxxx WD_Close Figure B 3 WinDriver API Calling Sequence B 6 General WD_xxx Functions 194 NOTES e We recommend calling the WinDriver function WD_Version B 6 3 after calling WD_Open B 6 2 and before calling any other WinDriver function Its purpose is to return the WinDriver kernel module windrvr6 sys dll o ko version number thus providing the means to verify that your application is version compatible with the WinDriver kernel module WD_DebugAdd B 6 6 and WD_Sleep B 6 8 can be called anywhere after WD_Open B 6 General WD_xxx Functions 195 B 6 2 WD_Open PURPOSE e Opens
121. iptor information structure Name ype Description gt bLength JCHAR Size in bytes of the descriptor 18 bytes gt bDescriptorType JCHA Device descriptor 0x01 gt bedUSB JSHORT Number of the USB specification with which the device complies gt bDeviceClass JCHAR The device s class gt bDeviceSubClass JCHA The device s sub class gt bDeviceProtocol JCHAR The device s protocol gt bMaxPacketSize0 JCHA Maximum size of transferred packets gt idVendor JSHORT Vendor ID as assigned by USB IF gt idProduct SHORT Product ID as assigned by the product manufacturer gt bedDevice USHORT Device release number gt iManufacturer Index of manufacturer string descriptor gt iProduct Index of product string descriptor gt iSerialNumber Index of serial number string descriptor gt bNumConfigurations Number of possible configurations B 5 2 8 WDU_CONFIGURATION_DESCRIPTOR Structure USB configuration descriptor information structure Name gt bLengih gt pDescripiorType wTotalLength USHORT BNuminierfacas _bConfigurationValue gt iConfiguration UCHAR Index of string descriptor that describes this configuration gt bmAttributes UCHAR Power settings for this configuration e D6 self powered e D5 remote wakeup allows device to wake up the host gt MaxPower UCHAR Maximum power consumption for this configuration in 2mA units B 5 USB Data Types 191 B 5 2 9 WDU_I
122. ist xp_embedded wd_component windriver sld as the SLD file and click Import 3 Add the WinDriver component to your Windows XP Embedded image a Open your project in the Target Designer b Double click the WinDriver component to add it to your project Note If you already have an earlier version of the WinDriver component in your project s components list right click this component and select Upgrade c Run a dependency check and build your image After following these steps WinDriver will automatically be installed during the first boot on the target Windows XP Embedded platform on which your image is loaded NOTE If you have selected to rename the WinDriver kernel module 12 2 you will not be able to use the provided windriver sld component You can build your own component for the renamed driver or use the wdreg utility to install the driver on the target Windows XP Embedded platform as explained in the manual Appendix A 64 bit Operating Systems Support A 1 Supported 64 bit Architectures WinDriver supports the following 64 bit platforms Linux AMD64 or Intel EM64T x86_64 For a full list of the Linux platforms supported by WinDriver refer to section 4 1 3 Windows AMD64 or Intel EM64T x64 For a full list of the Windows platforms supported by WinDriver refer to sections 4 1 1 1 and 4 1 1 2 A 2 Support for 32 bit Applications on 64 bit Architectures WinDriver for Linux AMD64 and Wi
123. istribution 107 e Preliminary Steps To avoid reboot before attempting to install the driver make sure that there are no open handles to the windrvr6 sys service This includes verifying that there are no open applications that use this service and that there are no connected Plug and Play devices that are registered to work with windrvr6 sys i e no INF files that point to this driver are currently installed for any of the Plug and Play devices connected to the PC or the INF file is installed but the device is disabled This may be relevant for example when upgrading a driver developed with an earlier version of WinDriver version 6 0 and later only since previous versions used a different module name You should therefore either disable or uninstall all Plug and Play devices that are registered to work with WinDriver from the Device Manager Properties Uninstall Properties Disable or Remove on Win98 Me or otherwise disconnect the device s from the PC If you do not do this attempts to install the new driver using wdreg will produce a message that instructs the user to either uninstall all devices currently registered to work with WinDriver or reboot the PC in order to successfully execute the installation command On Windows 2000 remove any INF file s previously installed for your device such as files created with an earlier version of WinDriver from the windir inf directory before installing the new INF
124. ite B 4 9 4 In case of a blocking stream the function blocks until the entire data is written to the stream or until the stream s attempt to write data to the device times out In the case of a non blocking stream the function writes as much of the write data as currently possible to the stream and returns immediately For both blocking and non blocking transfers the read write function returns the amount of bytes actually transferred between the stream and the calling application within an output parameter pdwBytesRead B 4 9 3 pdwBytesWritten B 4 9 4 You can flush an active stream at any time by calling the WDU_StreamF lush function B 4 9 5 which writes the entire contents of the stream s data buffer to the device for a write stream and blocks until all pending I O for the stream is handled You can flush both blocking and non blocking streams You can call WDU_StreamGetStatus B 4 9 6 for any open stream in order to get the stream s current status information To stop the data streaming between an active stream and the device call WDU_StreamStop B 4 9 7 In the case of a write stream the function flushes the stream 1 e writes its contents to the device before stopping it An open stream can be stopped and restarted at any time until it is closed To close an open stream call NDU_StreamClose B 4 9 8 The function stops the stream including flushing its data to the device in t
125. iver WDU_Transfer B 4 8 1 function from within your application Fill the setup packet in the BYTE SetupPacket 8 array and call these functions to send setup packets on Pipe00 and to retrieve control and status data from the device e The following sample demonstrates how to fill the SetupPacket 8 variable with a GET_DESCRIPTOR setup packet setupPacket 0 0x80 BmRequstType setupPacket 1 0x6 bRequest 0x6 GET_DESCRIPTOR setupPacket 2 0 wValue setupPacket 3 0x1 wValue Descriptor Type 0x1 DEVICE setupPacket 4 0 wIndex setupPacket 5 0 wIndex setupPacket 6 0x12 wLength Size for the returned buffer setupPacket 7 0 wLength e The following sample demonstrates how to send a setup packet to the control pipe a GET instruction the device will return the information requested in the pBuffer variable WDU_TransferDefaultPipe hDev TRUE 0 pBuffer dwSize bytes_transferred amp setupPacket 0 10000 e The following sample demonstrates how to send a setup packet to the control pipe a SET instruction WDU_TransferDefaultPipe hDev FALSE 0 NULL 0 9 3 Functional USB Data Transfers 96 bytes_transferred amp setupPacket 0 10000 For further information regarding WDU_TransferDefaultPipe refer to section B 4 8 3 For further information regarding WDU_Transfer refer to section B 4 8 1 9 3 Functional
126. iver directory then click OK and click OK again from the System Properties dialogue The following steps are for registered users only In order to register your copy of WinDriver with the license you received from Jungo follow the steps below 8 Activate DriverWizard GUI Start Programs WinDriver Driver Wizard 9 Select the Register WinDriver option from the File menu and insert the license string you received from Jungo Click the Activate License button 10 To register source code that you developed during the evaluation period refer to the documentation of WDU_Init B 4 1 4 2 WinDriver Installation Process 47 4 2 2 Windows CE WinDriver Installation Instructions 4 2 2 1 Installing WinDriver CE when Building New CE Based Platforms NOTES e The following instructions apply to platform developers who build Windows CE kernel images using Windows CE Platform Builder or using MSDEV 2005 with the Windows CE 6 0 plugin The instructions use the notation Windows CE IDE to refer to either of these platforms e We recommend that you read Microsoft s documentation and understand the Windows CE and device driver integration procedure before you perform the installation 1 Edit the project registry file to match your target hardware If you select to use the WinDriver component as outlined in step 2 the registry file to modify is WinDriver samples wince_install lt TARGET_CPU gt WinDriver reg e g Wi
127. iyet essere a 9 3 3 Streaming Data Transfers o o 9 3 3 1 Performing Streaming with WinDriver 10 Dynamically Loading Your Driver 10 1 10 2 10 3 10 4 Why Do You Need a Dynamically Loadable Driver Windows Dynamic Driver Loading 10 2 1 Windows Driver Types 200 10 2 2 The WDREG Utility 10 2 3 Dynamically Loading Unloading windrvr6 sys INF Files Linux Dynamic Driver Loading _ o o Windows Mobile Dynamic Driver Loading 11 Distributing Your Driver 11 1 11 2 Getting a Valid License for WinDriver Windows Driver Distribution o 11 2 1 Preparing the Distribution Package 11 2 2 Installing Your Driver on the Target Computer Windows CE Driver Distribution o o 11 3 1 Distribution to New Windows CE Platforms 82 85 85 86 96 97 97 99 99 99 99 100 102 103 103 CONTENTS 6 11 3 2 Distribution to Windows CE Computers 113 11 4 Linux Driver Distribution o e 114 11 4 1 WinDriver Kernel Module 114 11 4 2 User Mode Hardware Control Application Shared Objects 115 11 4 3 Installation Script o e 115 12 Driver Installation Advanced Issues 116 12 1 INF Files Windows 98 Me 2000 XP Server 2003 Vista 116 12 1 1 Why Should I Cre
128. l and copy this file to the target s windir sysWOW 64 directory NOTE If you attempt to write a 32 bit installation program that installs a 64 bit program and therefore copies the 64 bit wdapi920 dll DLL to the windir system32 directory you may find that the file is actually copied to the 32 bit windir sysWOW64 directory The reason for this is that Windows x64 platforms translate references to 64 bit directories from 32 bit commands into references to 32 bit directories You can avoid the problem by using 64 bit commands to perform the necessary installation steps from your 32 bit installation program The system64 exe program provided in the WinDriver redist directory of the Windows x64 WinDriver distributions enables you to do this e Install your hardware control application DLL Copy your hardware control application DLL to the target and run it 11 3 Windows CE Driver Distribution 11 3 1 Distribution to New Windows CE Platforms NOTE The following instructions apply to platform developers who build Windows CE kernel images using Windows CE Platform Builder or using MSDEV 2005 with the Windows CE 6 0 plugin The instructions use the notation Windows CE IDE to refer to either of these platforms To distribute the driver you developed with WinDriver to a new target Windows CE platform follow these steps 1 If you have not already done so edit the project registry file to match your target hardw
129. l your new xxx sys driver You can make additional modifications to this file if you wish namely changing the string definitions and or comments in the file 12 2 Renaming the WinDriver Kernel Driver 123 xxx_device inf A modified version of the standard generated DriverWizard INF file for your device which registers your device with your driver xxx sys You can make additional modifications to this file if you wish such as changing the manufacturer or driver provider strings wdapi920 dll A copy of the WinDriver API DLL The DLL is copied here in order to simplify the driver distribution allowing you to use the generated xxx redist directory as the main installation directory for your driver instead of the original WinDriver redist directory e sys directory This directory contains files for advanced users who wish to change the properties of their driver file Note Changing the file s properties requires rebuilding of the driver module using the Windows Driver Development Kit DDK To modify the properties of your xxx sys driver file a Verify that the Windows DDK is installed on your development PC or elsewhere on its network and set the BASEDIR environment variable to point to your DDK installation directory b Modify the xxx re resources file in the generated sys directory in order to set different driver file properties c Rebuild the driver by running the following command ddk_m
130. le To automatically install your INF file on Windows 2000 XP Server 2003 Vista and update Windows Device Manager run wdreg with the install command wdreg inf lt path to your INF file gt install You can also use the preinstall command to pre install an INF file for a device that is not currently connected to the PC wdreg inf lt path to your INF file gt preinstall NOTE On Windows 2000 if another INF file was previously installed for the device which registered the device to work with the Plug and Play driver used in earlier versions of WinDriver remove any INF file s for the device from the windir inf directory before installing the new INF file that you created This will prevent Windows from automatically detecting and installing an obsolete file You can search the INF directory for the device s vendor ID and device product ID to locate the file s associated with the device Windows 98 Me Install the INF file manually using Windows Add New Hardware Wizard or Upgrade Device Driver Wizard as outlined in detail in section 12 1 11 3 Windows CE Driver Distribution 110 e Install wdapi920 dll If your hardware control application DLL uses wdapi920 dll as is the case for the sample and generated DriverWizard WinDriver projects copy this DLL to the target s windir system32 directory If you are distributing a 32 bit application DLL to a target 64 bit platform rename wdapi920_32 dll to wdapi920 dl
131. les generic WinDriver toolkit specific chipset APIs e Compact install only the generic WinDriver toolkit e Custom select which WinDriver modules to install 6 After the installer finishes copying the required files choose whether to view the Quick Start guides 7 You may be prompted to reboot your computer 4 2 WinDriver Installation Process 46 NOTE The WinDriver installation defines a WO_BASEDIR environment variable which is set to point to the location of your WinDriver directory as selected during the installation This variable is used during the DriverWizard 5 code generation it determines the default directory for saving your generated code and is used in the include paths of the generated project make files Therefore if you decide to change the name and or location of your WinDriver directory after the installation you should also edit the value of the WD_BASEDIR environment variable and set it to point to the location of your new WinDriver directory You can edit the value of WD_BASEDIR by following these steps 1 Open the System Properties dialogue Start System Control Panel System 2 In the Advanced tab click the Environment Variables button 3 In the System variables box select the WD_BASEDIR variable and click the Edit button or double click the mouse on the variable 4 In the Edit System Variable dialogue replace the Variable Value with the full path to your new WinDr
132. lient but failed to reach the miniport in time E B 8 WinDriver Status Codes 232 Status Code WD_USBD_STATUS_ISO_NOT_ACCESSED_LATE USBD The packet was not sent because the client submitted it too late to transmit Appendix C Troubleshooting and Support Please refer to http www jungo com st support support_windriver html for additional resources for developers including e Technical documents e FAQs e Samples e Quick start guides 233 Appendix D Evaluation Version Limitations D 1 Windows WinDriver Evaluation Limitations e Each time WinDriver is activated an Unregistered message appears e When using DriverWizard a dialogue box with a message stating that an evaluation version is being run appears on every interaction with the hardware e DriverWizard 5 Each time DriverWizard is activated an Unregistered message appears An evaluation message is displayed on every interaction with the hardware using DriverWizard e WinDriver will function for only 30 days after the original installation D 2 Windows CE WinDriver Evaluation Limitations e Each time WinDriver is activated an Unregistered message appears e The WinDriver CE Kernel windrvr6 dll will operate for no more than 60 minutes at a time e DriverWizard 5 used on a host Windows 2000 XP Server 2003 Vista PC Each time DriverWizard is activated an Unregistered message appears An evaluation message is displ
133. log e Use DriverWizard to validate your device s USB configuration and test the communication with the device 7 2 Debug Monitor Debug Monitor is a powerful graphical and console mode tool for monitoring all activities handled by the WinDriver kernel windrvr6 sys d11 0 ko You can use this tool to monitor how each command sent to the kernel is executed In addition WinDriver enables you to print your own debug messages to the Debug Monitor using the WD_DebugAdd function B 6 6 or the high level PrintDbgMessage function B 7 14 The Debug Monitor has two modes graphical mode and console mode The following sections explain how to operate Debug Monitor in both modes 78 7 2 Debug Monitor 79 7 2 1 Using the Debug Monitor in Graphical Mode wddebug_gui The graphical GUI version of the Debug Monitor utility wddebug_gui is available for Windows 98 Me 2000 XP Server 2003 Vista and Linux You may also use the Debug Monitor to debug your Windows CE driver code running on CE emulation on a Windows 2000 XP Server 2003 Vista platform For Windows CE targets use Debug Monitor in console mode 7 2 2 1 Run the Debug Monitor using either of the following alternative methods e Run WinDriver util wddebug_gui e Run the Debug Monitor from the DriverWizard s Tools menu e On Windows run Start Programs WinDriver Debug Monitor B WinDriver Debug Monitor File Edit View Help LICEA WinDriver Debug M
134. mple 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 supported in all operating systems including all Windows platforms and all Unix platforms Figure 2 2 Layered Drivers 2 2 3 Miniport Drivers A Miniport driver is an add on to a class driver that supports miniport drivers It is used so the miniport driver does not have to implement all of the functions required of a driver for that class The class driver provides the basic class functionality for the miniport driver A class driver is a driver that supports a group of devices of common functionality such as all HID devices or all network devices Miniport drivers are also called miniclass drivers or minidrivers and are supported in the Windows NT 2000 family namely Windows NT 2000 XP Server 2003 Vista 2 3 Classification of Drivers According to Operating Systems 25 Application User Mode O arenas Kernel Mode RK SSSSSSSSSSSSSSSSSS ND N X SDIS Framework Nia S SG Figure 2 3 Miniport Drivers Windows NT 2000 XP Server 2003 Vista provide 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 The NDIS miniport driver is one example of such a driver The NDIS minipo
135. mplement the three user callback functions specified in the next section WOU_ATTACH_CALLBACK B 3 1 WOU_DETACH_CALLBACK B 3 2 and WDU_POWER_CHANGE_CALLBACK B 3 3 at the very least WDU_ATTACH_CALLBACK These functions are used to notify your application when a relevant system event occurs such as the attaching or detaching of a USB device For best performance minimal processing should be done in these functions Your application calls WOU_Init B 4 1 and provides the criteria according to which the system identifies a device as relevant or irrelevant The WDU_Init function must also pass pointers to the user callback functions Your application then simply waits to receive a notification of an event Upon receipt of such a notification processing continues Your application may make use of any functions defined in the high or low level APIs below The high level functions provided for your convenience make use of the low level functions which in turn use IOCTLs to enable communication between the WinDriver kernel module and your user mode application When exiting your application calls WDU_Uninit B 4 7 to stop listening to devices matching the given criteria and to un register the notification callbacks for these devices The following figure depicts the calling sequence described above Each vertical line represents a function or process Each horizontal arrow represents a signal or request drawn from the initiator
136. n B 6 2 pLicense Pointer to a WinDriver license information structure gt cLicense A buffer to contain the license string that is to be transferred to the WinDriver kernel module If an empty string is transferred then WinDriver kernel module returns the current license type to the parameter dwLicense gt dwLicense Returns the license type of the specified license string cLicnese The return value is a bit mask of license flags defined as an enum in windrvr h Zero signifies an invalid license string Additional flags for determining the license type are returned in dwLicense2 if needed gt dwLicense2 Returns additional flags for determining the license type if dwLicense cannot hold all the relevant information otherwise zero RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 REMARKS e When using a registered version this function must be called before any other WinDriver API call apart from WD_Open B 6 2 in order to register the license from the code B 6 General WD_xxx Functions 209 EXAMPLE Example usage Add registration routine to your application DWORD RegisterWinDriver HANDLE hWD WD_LICENSE lic DWORD dwStatus WD_INVALID_HANDLE hWD WD_Open if hWD INVALID_HANDLE_VALUE BZERO lic Replace the following string with your license string strcpy lic cLicense 12345abcde12345 CompanyName dwStatus WD_Li
137. n Start WinDriver Uninstall OR run the uninstall exe utility from the WinDriver installation directory The uninstall will stop and unload the WinDriver kernel module windrvr6 sys delete the copy of the windrvr6 inf file from the windir inf directory on Windows 2000 XP Server 2003 Vista windir inf other directory on Windows 98 Me delete WinDriver from Windows Start menu delete the WinDriver installation directory 4 5 Uninstalling WinDriver 57 except for files that you added to this directory and delete the short cut icons to the DriverWizard and Debug Monitor utilities from the Desktop e On a target PC on which you installed the WinDriver kernel module windrvr6 sys but not the entire WinDriver toolkit Use the wdreg utility to stop and unload the driver wdreg inf lt path to windrvr6 inf gt uninstall NOTE When running this command windrvr6 sys should reside in the same directory as windrvr6 inf On the development PC the relevant wdreg uninstall command is executed for you by the uninstall utility NOTES e If there are open handles to WinDriver when attempting to uninstall it either using the uninstall utility or by running the wdreg uninstall command directly for example if there is an open WinDriver application or a connected Plug and Play device that has been registered to work with WinDriver via an INF file on Windows 98 Me 2000 XP Server 2003 Vista an appropriate
138. nDriver samples wince_install ARMV4I WinDriver reg Otherwise modify the WinDriver samples wince_install project_wd reg file 2 You can simplify the driver integration into your Windows CE platform by following the procedure described in this step before the Sysgen platform compilation stage NOTE The procedure described in this step is relevant only for developers who use Windows CE 4 x 5 x with Platform Builder Developers who use Windows CE 6 x with MSDEV 2005 should skip to the next step 3 This procedure provides a convenient method for integrating WinDriver into your Windows CE platform If you select not to use this method you will need to perform the manual integration steps described in step 4 below after the Sysgen stage The procedure described in this step also adds the WinDriver kernel module windrvr6 dll to your OS image This is a necessary step if you want the WinDriver CE kernel file windrvr6 dll to be a permanent part of the Windows CE image NK BIN which is the case if you select to transfer the file to your target platform using a floppy disk However if you prefer to have the file windrvr6 dll loaded on demand via the CESH PPSH services you need to perform the manual integration method described in step 4 instead of performing the procedure described in the present step 4 2 WinDriver Installation Process 48 a Run the Windows CE IDE and open your platform b From the File menu select M
139. nces the user s experience of many applications including interactive gaming broadband Internet access desktop and Web publishing Internet services and conferencing Because of its benefits described also in section 3 2 below USB is currently enjoying broad market acceptance 3 2 WinDriver USB Benefits This section describes the main benefits of the USB standard and the WinDriver USB toolkit which supports this standard External connection maximizing ease of use Self identifying peripherals supporting 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 hundreds of 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 a data transfer rate of up to 480 Mb s high speed for USB 2 0 for the operating systems that officially support this standard and up to 12 Mb s full speed for USB 1 1 Guaranteed bandwidth and low latencies appropriate for telephony audio etc isochronous transfer may use almost the entire bus bandwidth Flexibility supports a wide range of packet sizes and a wide range of data transfer rates 3 3 USB Components 31 Robustness built in error handling mechanism and dynamic insertion and removal of devices with no delay observed by the user Synergy with PC
140. ndows AMD64 support both 32 bit and 64 bit applications In order to build a 32 bit application for one of these platforms use any appropriate 32 bit compiler with the DKERNEL_64BIT compilation flag Note however that 64 bit applications are more efficient 133 A 3 64 bit and 32 bit Data Types 134 A 3 64 bit and 32 bit Data Types In general DWORD is unsigned long While any 32 bit compiler treats this type as 32 bits wide 64 bit compilers treat this type differently With Windows 64 bit compilers the size of this type is still 32 bits However with UNIX 64 bit compilers e g GCC the size of this type is 64 bits In order to avoid compiler dependency issues use the UINT32 and UINT64 cross platform types when you want to refer to a 32 bit or 64 bit address respectively Appendix B WinDriver USB PC Host API Reference NOTE This function reference is C oriented The WinDriver NET Visual Basic and Delphi APIs have been implemented as closely as possible to the C APIs therefore NET VB and Delphi programmers can also use this reference to better understand the WinDriver APIs for their selected development language For the exact API implementation and usage examples for your selected language refer to the WinDriver NET VB Delphi source code 135 B 1 WD_DriverName 136 B 1 WD_DriverName PURPOSE e Sets the name of the WinDriver kernel module which will be used by the calling application NOTE e
141. nfigurations each configuration has one or more interfaces and each interface has zero or more endpoints as demonstrated in Figure 3 3 below 3 7 USB Configuration 37 Device Descriptor Configuration Descriptor y Configuration Descriptor Interface Descriptor y Interface Descriptor Endpoint Endpoint Descriptor g Descriptor Figure 3 3 Device Descriptors Device Level The device descriptor includes general information about the USB device i e global information for all of the device configurations The device descriptor identifies among other things the device class HID device hub locator device 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 Each descriptor identifies the number of interfaces grouped in the configuration and the power attributes of the configuration such as self powered remote wakeup maximum power consumption and more Only one configuration can be loaded at a given time For example an ISDN adapter might have two different configurations one that presents it with a single interface of 128 Kb s and a second that presents it with two interfaces of 64 Kb s each Interface Level The interface is a related set of endpoints that present a specific functionality or feature of the device Ea
142. nformation for INF File Please fill in the information below for your device This information will be incorporated into the INF file which WinDriver will generate for your device The information you specify will appear in the Device Manager after the installation of the INF file Vendor ID 04b4 Device ID 1003 Manufacturer name Cypress Semiconductor Corp Device name DEVICE Device Class OTHER WinDriver s unique Class Use this option for a non standard type of device WinDriver will set a new Class type for your device Automatically install the INF file Note This will replace any existing driver you may have for your device Figure 5 3 DriverWizard INF File Information 5 2 DriverWizard Walkthrough 63 c For multiple interface USB devices you can select to generate an INF file either for the composite device or for a specific interface e When selecting to generate an INF file for a specific interface of a multi interface USB device the INF information dialogue will indicate for which interface the INF file is generated Enter Information for INF File Please fill in the information below for your device This information will be incorporated into the INF file which WinDriver will generate For your device The information you specify will appear in the Device Manager after the installation of the INF file Vendor ID 1111 Device ID 1111 Manufacture
143. o stalled endpoint Software Status Codes NOTE Only the error bit is set WD_USBD_STATUS_NO_MEMORY USBD Out of memory WD_USBD_STATUS_INVALID_URB_FUNCTION USBD Invalid URB function WD_USBD_STATUS_INVALID_PARAMETER USBD Invalid parameter Returned if client driver attempts to close an endpoint interface or configuration with outstanding transfers WD_USBD_STATUS_ERROR_BUSY USBD Attempted to close endpoint interface configuration with outstanding transfer Returned by USBD if it cannot complete a URB request Typically this will be returned in the URB status field when the IRP is completed with a more specific error code The IRP status codes are indicated in WinDriver s Debug Monitor tool wddebug_gui Returned when there is not enough bandwidth available to open a requested endpoint WD_USBD_STATUS_NO_BANDWIDTH USBD Not enough bandwidth for ndpoint Generic HC Host Controller error WD_USBD_STATUS_INTERNAL_HC_ERROR USBD Host controller error Returned when a short packet terminates the transfer i e USBD_SHORT_TRANSFER_OK bit not set WD_USBD_STATUS_ERROR_SHORT_TRANSFER JSBD Transfer terminated with short packet B 8 WinDriver Status Codes 231 Status Code Returned if the requested start frame is not within USBD_ISO_START_FRAME_RANGE of the current USB frame NOTE The stall bit is set WD_USBD_STATUS_BAD_START_ FRAME Returned by HCD Host Controller Driver if all packets in an isochronous
144. o view its usage instructions The default debug sections flag is ALL sets all the supported debug sections USAGE SEQUENCE To log messages using wddebug use this sequence e Turn on the Debug Monitor by running wddebug with either the on command or the dbg_on command which redirects the debug messages to a kernel debugger before turning on the Debug Monitor You can use the level and or sections flags to set the debug level and or sections for the log If these options are not explicitly set the default values will be used You can also log messages from a renamed WinDriver driver by preceding the command with the name of the driver see the lt driver_name gt option above The default monitored driver is windrvr6 7 2 Debug Monitor 84 Run wddebug with the dump command to begin dumping debug messages to the command prompt You can turn off the display of the debug messages at any time by pressing Esc in the command prompt Run applications that use the driver and view the debug messages as they are being logged to the command prompt the kernel debugger You can run wddebug with the status command at any time while the Debug Monitor is on in order to view the current debug level and sections as well as information regarding the running lt driver_name gt kernel module e You can use dbg_on and dbg_off to toggle the redirection of debug messages to a kernel debugger at any time while the Debug Monitor is on When
145. of the operating system where the HCD layer represents a lower level of abstraction The HCD 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 Core Driver and USB Hub Driver implement the hardware access and data transfer by communicating with the HCD using the Host Controller Driver Interface HCDI The USB Hub Driver is responsible for identifying the addition and removal of devices from a particular hub When the Hub Driver receives a signal that a device was attached or detached it uses additional host software and the USB Core 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 s USB API developers can perform all the hardware related operations without having to master the lower level implementation for supporting these operations 3 9 WinDriver USB Architecture 41 E WinDriver Components Your Application DIl Shared Object J Os Components z 7 Your Driver Code b WinDri
146. on method described in step 4 instead of performing the procedure described in the present step a Run the Windows CE IDE and open your platform b From the File menu select Manage Catalog Items and then click the Import button and select the WinDriver cec file from the relevant WinDriver samples wince_install lt TARGET_CPU gt directory e g WinDriver samples wince_install ARMV4I This will add a WinDriver component to the Platform Builder Catalog c In the Catalog view right click the mouse on the WinDriver Component node in the Third Party tree and select Add to OS design 3 Compile your Windows CE platform Sysgen stage 4 If you did not perform the procedure described in step 2 above perform the following steps after the Sysgen stage in order to manually integrate the driver into your platform NOTE If you followed the procedure described in step 2 skip this step and go directly to step 5 11 3 Windows CE Driver Distribution 112 a Run the Windows CE IDE and open your platform b Select Open Release Directory from the Build menu c Copy the WinDriver CE kernel file WinDriver redist lt TARGET_CPU gt windrvr6 dll to the _FLATRELEASEDIR sub directory on the target development platform should be the current directory in the new command window d Append the contents of the project_wd reg file in the WinDriverl samples wince_installl directory to the project reg file in th
147. on is displayed data can be transferred on the pipes the pipes can be reset etc Once the device is operating to your satisfaction DriverWizard creates the skeletal driver source code with functions to access your hardware s resources If you are developing a driver for a device that is based on one of the enhanced support USB chipsets The Cypress EZ USB family Microchip PIC18F4550 Philips PDIUSBD12 Texas Instruments TUSB3410 TUSB3210 TUSB2136 and TUSB5052 Agere USS2828 Silicon Laboratories C8051F320 we recommend you read Chapter 8 which explains WinDriver s enhanced support for specific chipsets before starting your driver development DriverWizard can be used to diagnose your hardware and can generate an INF file for hardware running under Windows 98 Me 2000 XP Server 2003 Vista Avoid using DriverWizard to generate code for a device based on one of the supported USB chipsets 8 as DriverWizard generates generic code which will have to be modified according to the specific functionality of the device in question 59 5 2 DriverWizard Walkthrough 60 Preferably use the complete source code libraries and sample applications supplied in the package tailored to the various USB chipsets DriverWizard is an excellent tool for two major phases in your HW Driver development Hardware diagnostics After the hardware has been built attach your device to a USB port on your machine and use DriverWizard to verify that the har
148. onitor v9 01 Running WinDriver v9 01 Jungo c 1997 2007 Build Date Jun 10 2007 x86 32bit SYS 13 48 53 OS Windows NT 5 1 Build 0 0 2600 Service Pack 2 Time Sun 10 Jun 15 50 33 2007 Figure 7 1 Start Debug Monitor 7 2 Debug Monitor 80 2 Set the Debug Monitor s status trace level and debug sections information from the Debug Options dialogue which is activated either from the Debug Monitor s View Debug Options menu or the Debug Options toolbar button Debug Options Section yo PnP Memory Kernel Plugin Interrupts PCI Miscellaneous License Card Registration PCMCIA ISA PnP USB Kernel Driver DMA Events All Sections Level Error O Warn O Info Trace C Send debug messages to the operating system kernel debugger Figure 7 2 Debug Options e Status Set trace on or off e Section Choose what part of the WinDriver API you would like to monitor USB developers should select the USB section TIP Choose carefully those sections that you would like to monitor Checking more options than necessary could result in an overflow of information making it harder for you to locate your problem 7 2 Debug Monitor 81 e Level Choose the level of messages you want to see for the resources defined Error is the lowest trace level resulting in minimum output to the screen Trace is the highest trace level displaying every operation the WinDriver kernel performs
149. ose the desired configuration interface and alternate setting combination using a friendly graphical user interface After detecting and configuring your USB device you can proceed to test the communication with the device perform data transfers on the pipes send control requests reset the pipes etc in order to ensure that all your hardware resources function as expected After your hardware is diagnosed you can use DriverWizard to automatically generate your device driver source code in C C Visual Basic NET Delphi or Visual Basic WinDriver USB provides user mode APIs which you can call from within your application in order to implement the communication with your device The WinDriver USB API includes USB unique operations such as reset of a pipe or a device The generated DriverWizard code implements a diagnostics application which demonstrates how to use WinDriver s USB API to drive your specific device In order to use the application you just need to compile and run it You can jump start your development cycle by using this application as your skeletal driver and then modifying the code as needed to implement the desired driver functionality for your specific device DriverWizard also automates the creation of an INF file that registers your device to work with WinDriver which is an essential step in order to correctly identify and handle USB devices using WinDriver For an explanation on why you need to create an INF
150. ot being used by another program e View a list of modules and the programs using each of them sbin 1lsmod e Close any applications that are using the WinDriver module e Unload any modules that are using the WinDriver module sbin t rmmod 2 Unload the WinDriver module sbin rmmod windrvr6 3 If you are not using a Linux 2 6 x kernel that supports the udev file system remove the old device node in the dev directory rm rf dev windrvr6 4 Remove the file windriver rc from the etc directory rm rf etc windriver rc 5 Remove the file windriver re from HOME rm rf SHOME windriver rc 6 If you created a symbolic link to DriverWizard delete the link using the command rm f usr bin wdwizard 7 Delete the WinDriver installation directory using the command rm rf WinDriver 8 Erase the following shared object file if it exists usr lib libwdapi920 so 32 bit PowerPC or 32 bit x86 usr lib64 libwdapi920 so 64 bit x86 Chapter 5 Using DriverWizard This chapter describes WinDriver DriverWizard s hardware diagnostics and driver code generation capabilities 5 1 An Overview DriverWizard included in the WinDriver toolkit is a GUI based diagnostics and driver generation tool that allows you to write to and read from the hardware before writing a single line of code The hardware is diagnosed through a Graphical User Interface the device s configuration and pipes informati
151. our device Finally you need to install and execute the hardware control application that you developed with WinDriver These steps can be performed using wdreg utility 11 2 1 Preparing the Distribution Package Your distribution package should include the following files Your hardware control application DLL windrvr6 sys Get this file from the WinDriver redist directory in the WinDriver package windrvr6 inf Get this file from the WinDriver redist directory in the WinDriver package wd920 cat Windows 2000 XP Server 2003 Vista Get this file from the WinDriver redist directory in the WinDriver package wdapi920 dll for distribution of 32 bit binaries to 32 bit target platforms or for distribution of 64 bit binaries to 64 bit platforms or wdapi920_32 dll for distribution of 32 bit binaries to 64 bit platforms Get this file from the WinDriver redist directory in the WinDriver package difxapi dll required by the wdreg exe utility 10 2 2 Get this file from the WinDriver util directory in the WinDriver package An INF file for your device You can generate this file with the DriverWizard as explained in section 5 2 11 2 2 Installing Your Driver on the Target Computer NOTE The user must have administrative privileges on the target computer in order to install your driver Follow the instructions below in the order specified to properly install your driver on the target computer 11 2 Windows Driver D
152. performance drivers 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 of this manual deals 12 NOTE 1 2 Background 13 with the features that WinDriver offers to the advanced user However 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 WinDriver supports development for all USB chipsets Enhanced support is offered for Cypress Microchip Philips Texas Instruments Agere and Silicon Laboratories USB chipsets as outlined in Chapter 8 of the manual Visit Jungo s web site at http www jungo com for the latest news about WinDriver and other driver development tools that Jungo offers 1 2 Background 1 2 1 The Challenge In protected operating systems such as Windows and Linux a programmer cannot access hardware directly from the application level user mode where development work is usually done Hardware can only be accessed from within the operating system itself kernel mode or Ring 0 utilizing 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 Learn how to write a device driver Learn new tools for developing debugging in kernel mode DDK E
153. periodic large packet bursty communication Bulk transfer allows access to the bus on an as available basis guarantees the data transfer but not the latency and provides an 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 the other stream pipes isochronous and interrupt the bulk pipe is also unidirectional so bi directional transfers require two endpoints The maximum packet size for bulk endpoints can be 8 16 32 or 64 bytes for full speed devices and 512 bytes for high speed devices 3 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 hierarchical structure with four levels e The Device level e The Configuration level e The Interface level this level may include an optional sub level called Alternate Setting e The Endpoint level There is only one device descriptor for each USB device Each device has one or more co
154. pipe endpoint and two functional data transfer pipes endpoints as identified by WinDriver s DriverWizard utility discussed in Chapter 5 ajja DriverWizard File Tools Project Help 2080068 Active Projects Alternate Setting 2 vd Cypress Semiconductor Corp Product ID 1003 4 Cypress Semiconductor Corp Product ID 1003 Interface 0 Alternate Setting 0 Alternate Setting 1 Pipe Name Pipe Type Information Alternate cn 1 1 Ppe0x0 Control direction in out packet size 64 Alternate Setting 4 Alternate Setting 5 2 pipe 0x82 Buk direction in packet size 512 Alternate Setting 6 3 pipe Oxs Buk direction out packet size 512 information Panel Log Output Description Figure 3 2 USB Pipes More information on how to implement the control transfer by sending setup packets can be found in section 9 2 3 6 USB Data Transfer Types 34 3 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 supports four different transfer types A type is selected for a specific endpoint according to the requirements of the device and the software The transfer type of a specific endpoint is determined in the endpoint descriptor The USB specification provides for the following data transfer types 3 6 1 Control Trans
155. played in the Request Description box For a custom request you are required to enter the setup packet information and write data if exists yourself The size of the setup packet should be eight bytes and it should be defined using little endian byte ordering The setup packet information should conform to the USB specification parameters bmRequest Type bRequest wValue wIndex wLength NOTE More detailed information on the standard USB requests on how to implement the control transfer and how to send setup packets can be found in section 9 2 For an input pipe moves data from device to host click Listen to Pipe To successfully accomplish this operation with devices other than HID you need to first verify that the device sends data to the host If no data is sent after listening for a short period of time DriverWizard will notify you that the Transfer Failed pipe 0x0 Control Pipe Name Pipe Type direction in amp out packet size 64 direction in packet size 512 direction out packet size 512 Figure 5 8 Listen to Pipe 5 2 DriverWizard Walkthrough 68 To stop reading click Stop Listen to Pipe iv For an output pipe moves data from host to device click Write to Pipe A new dialogue box will appear asking you to enter the data to write The DriverWizard log will contain the result of the operation amp Write To Pipe Write to pipe data Hex DE AD BE AF
156. ption hWD Handle to WinDriver s kernel mode driver as received from WD_Open B 6 2 pSleep Pointer to a sleep information structure gt dwMicroSeconds Sleep time in microseconds 1 1 000 000 of a second gt dwOptions A bit mask which can be set to either of the following ezero 0 Busy sleep default OR e SLEEP_NON_BUSY Delay execution without consuming CPU resources Not relevant for under 17 000 micro seconds Less accurate than busy sleep RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 6 General WD_xxx Functions REMARKS e Example usage to access slow response hardware EXAMPLE WD_Sleep slp BZERO slp slp dwMicroSeconds 200 WD_Sleep hWD amp slp 206 B 6 General WD_xxx Functions 207 B 6 9 WD_License PURPOSE e Transfers the license string to the WinDriver kernel module and returns information regarding the license type of the specified license string NOTE When using the WOU USB APIs B 2 your WinDriver license registration is done via the call to WOU_Init B 4 1 so you do not need to call WD_License directly from your code PROTOTYPE DWORD WD_License HANDLE hWD WD_LICENSE pLicense PARAMETERS input Outpai HANDLE WD _LICENSE CHART DWORD Li dwLicense2 DWORD B 6 General WD_xxx Functions 208 DESCRIPTION Handle to WinDriver s kernel mode driver as received from WD_Ope
157. r B 4 8 1 WDU_TransferDefaultPipe B 4 8 3 WDU_TransferBulk B 4 8 4 WDU_TransferIsoch B 4 8 5 W ansferInterrupt B 4 8 6 tTra DU_Tr WOU_Halt Transfer 18482 WD_UsbResetPipe WDU_ResetPipe B 4 10 WD_UsbResetDevice WDU_ResetDevice B 4 11 WD_UsbResetDeviceEx B 3 USB User Callback Functions 143 B 3 USB User Callback Functions B 3 1 WDU_ATTACH_CALLBACK PURPOSE e WinDriver calls this function when a new device matching the given criteria is attached provided it is not yet controlled by another driver This callback is called once for each matching interface PROTOTYPE typedef BOOL DLLCALLCONV WDU_ATTACH CALLBACK WDU_DEVICE HANDLE hDevice WDU_DEVICE pDevicelInfo PVOID pUserData PARAMETERS ImputOuipal WDU_DEVICE HANDLE Input gt pDevicelnfo WDU_DEVICE Input PVOID Input DESCRIPTION A unique identifier for the device interface pDevicelInfo Pointer to a USB device information structure B 5 2 3 Valid until the end of the function pUserData Pointer to user mode data for the callback as passed to WDU_Init B 4 1 within the event table parameter pEvent Table gt pUserData RETURN VALUE If the WD_ACKNOWLEDGE flag was set in the call to WDU_Init B 4 1 within the dwOptions parameter the callback function should check if it wants to control the device and if so return TRUE otherwise return FALSE If
158. r name MANUFACTURER Device name DEVICE Device Class OTHER WinDriver s unique Class Use this option For a non standard type of device WinDriver will set a new Class type for your device This is a multi interface device Generate INF file for the root device itself Generate INF file for the Following device interfaces Interface O Automatically install the INF file Note This will replace any existing driver you may have For your device Figure 5 4 DriverWizard Multi Interface INF File Information Specific Interface e When selecting to generate an INF file for a composite device of a multi interface USB device the INF information dialogue provides you with the option to either generate an INF file for the root device itself or generate an INF file for specific interfaces 5 2 DriverWizard Walkthrough 64 which you can select from the dialogue Selecting to generate an INF file for the root device will enable you to handle multiple active interfaces simultaneously Enter Information for INF File Please fill in the information below for your device This information will be incorporated into the INF file which WinDriver will generate for your device The information you specify will appear in the Device Manager after the installation of the INF file Vendor ID 1111 Device ID 1111 Manufacturer name MANUFACTURER Device name
159. r name e g my_driver b Replace the configure script in the new directory with a copy of the WinDriver wizard windrvr6_configure sre file rename this file to configure and replace the 3DRIVER_NAME_CHANGE_F LAGS string in this file with DWD_DRIVER_NAME_CHANGE Note The copies of the lib and include directories should not be modified These copies are created since the supported WinDriver Linux kernel driver 12 3 Digital Driver Signing amp Certification Windows 2000 XP Server 2003 Vista 127 build method relies on the existence of these directories directly under the same parent directory as the redist directory 3 Verify that your application calls the WD_DriverName function B 1 with your new driver name before calling any other WinDriver function Note that the sample and generated DriverWizard WinDriver applications already include a call to this function but with the default driver name windrvr6 so all you need to do is replace the driver name that is passed to the function in the code with your new driver name 4 Verify that your user mode driver project is built with the WD_DRIVER_NAME_CHANGE preprocessor flag DWD_DRIVER_NAME_CHANGE Note The sample and generated DriverWizard WinDriver projects makefiles already set this preprocessor flag by default 5 Install your new driver by following the instructions in section 11 4 of the manual using the modified files from your new installation directory inste
160. r of the two alternative methods described in the following sections TIP It is recommended to use the first method described in setion 12 2 2 1 since it automates most of the work for you 12 2 2 1 Rename the Linux Driver Using Driver Wizard To rename your Linux WinDriver kernel driver using DriverWizard recommended follow the steps in this section References to xxx in this section should be replaced with the name of your generated DriverWizard driver project p Use the DriverWizard utility to generate driver code for your hardware on Linux 5 2 7 using your preferred driver name xxx as the name of the generated driver project The generated project directory xxx will include an xxx_installation directory with the following files and directories e redist directory This directory contains copies of the files from the original WinDriver redist installation directory but with the 12 2 Renaming the WinDriver Kernel Driver 126 required modifications for building your xxx o ko driver instead of windrvr6 0 ko lib and include directories Copies of the library and include directories from the original WinDriver distribution These copies are created since the supported Linux WinDriver kernel driver build method relies on the existence of these directories directly under the same parent directory as the redist directory 2 Verify that your application calls the WD_DriverName function
161. r util wddebug_gui a graphical debugging tool that collects information about your driver as it runs WinDriver also includes a console version of this program WinDriver util wddebug which can be used on platforms that have no GUI support such as Windows CE For details regarding the Debug Monitor refer to section 7 2 WinDriver distribution package WinDriver redist Windows Windows CE and Linux WinDriver redist_win98_compat Windows 98 Me 2000 XP Server 2003 Vista the files you include in the driver distribution to customers This manual the full WinDriver manual this document in different formats can be found under the WinDriver docs directory 1 9 What Does the WinDriver Toolkit Include 20 1 9 2 Utilities usb_diag exe WinDriver util usb_diag exe enables the user to view the resources of connected USB devices and communicate with the devices transfer data to from the device set the active alternate setting reset pipes etc On Windows 98 Me 2000 XP Server 2003 Vista the program identifies all devices that have been registered to work with WinDriver using an INF file On the other supported operating systems the program identifies all USB devices connected to the target platform pci_dump exe WinDriver util pci_dump exe used to obtain a dump of the PCI configuration registers of the installed PCI cards The Windows CE version also includes REDIST X86EMU WINDRVR_CE_EMU DLL D
162. rey ise to speci ar endpoint oran ete 3 winde The upper byte ofthe Tadex word wLengthL A word size value that indicates the number of bytes to be transferred if there is a data stage wLengthH The upper byte of the Length word 9 2 USB Control Transfers 91 9 2 1 5 Standard Device Request Codes The table below shows the standard device request codes GET_STATUS o 2 9 2 1 6 Setup Packet Example This example of a standard USB device request illustrates the setup packet format and its fields The setup packet is in Hex format The following setup packet is for a control read transaction that retrieves the device descriptor from the USB device The device descriptor includes information such as USB standard revision vendor ID and product ID GET_DESCRIPTOR Device Setup Packet 80 06 00 01 00 00 12 00 9 2 USB Control Transfers 92 Setup packet meaning BmRequest Type 8h 1000b bit 7 1 gt direction of data is from device to host Oh 0000b bits 0 1 00 gt the recipient is the device oe ee 3 wValueH The descriptor type is device values Se P oo wIndexL The index is not relevant in this setup packet since there is only one device gt Cs winder wLengthL hoe of the data to be retrieved 18 12h bytes this is the length of the device descriptor 7 went A COCOCOCOCOCTC S In response the device sends the device descriptor data A device descriptor of Cypress EZ USB
163. rint in a message box For more details please refer to DEBUG_LEVEL in windrvr h gt dwBufferSize Used for dwCmd DEBUG_SET_BUFFER The size of buffer in the kernel RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 EXAMPLE WD_DEBUG dbg BZERO dbg dbg dwCmd DEBUG_SET_FILTER dbg dwLevel D_ERROR dog dwSection S_ALL dbg dwLevelMessageBox D_ERROR WD_Debug hWD amp dbg B 6 General WD_xxx Functions 201 B 6 6 WD_DebugAdd PURPOSE e Sends debug messages to the debug log Used by the driver code PROTOTYPE DWORD WD_DebugAdd HANDLE hWD WD_DEBUG_ADD pData PARAMETERS Input Output HANDLE WD_DEBUG_ADD a LidwLevel DWORD DWORD ApcBuffer CHAR 256 DESCRIPTION Description hWD Handle to WinDriver s kernel mode driver as received from WD_Open B 6 2 Pointer to an additional debug information structure gt dwLevel Assigns the level in the Debug Monitor in which the data will be declared If dwLevel is zero D_ERROR will be declared For more details please refer to DEBUG_LEVEL in windrvr h gt dwSection Assigns the section in the Debug Monitor in which the data will be declared If dwSection is zero S_MISC section will be declared For more details please refer to DEBUG_SECTION in windrvr h gt pcBuffer The string to copy into the message log B 6 General WD_xxx Functions 202 RETURN VALU
164. ript from the WinDriver util directory to install load windrvr6 o0 ko Usage wdreg lt module name gt To install the windrvr6 module run wdreg windrvr6 TIP To automatically load windrvr6 0 ko on each boot run the wdreg script from the target Linux etc rc d rc local file wdreg windrvr6 10 4 Windows Mobile Dynamic Driver Loading The WinDriver redist Windows_Mobile_5_ARMV4MN wdreg exe utility can be used for loading the WinDriver kernel module windrvr6 dll on a Windows Mobile platform TIP On Windows Mobile the operating system s security scheme prevents the loading of unsigned drivers at boot time therefore the WinDriver kernel module has to be reloaded after boot To load WinDriver on the target Windows Mobile platform every time the OS is started copy the wdreg exe utility to the Windows StartUp directory on the target The source code of the Windows Mobile wdreg exe utility is available under the WinDriver samples wince_install wdreg directory on the development PC Chapter 11 Distributing Your Driver Read this chapter in the final stages of driver development It will guide you in preparing your driver for distribution 11 1 Getting a Valid License for WinDriver To purchase a WinDriver license complete the WinDriver docs order pdf order form and fax or email it to Jungo Complete details are included on the order form Alternatively you can order WinDriver on line For more details vi
165. rmissions by modifying your etc udev permissions d 50 udev permissions file For example add the following line to provide read and write permissions windrvr6 root root 0666 Otherwise use the chmod command for example chmod 666 dev windrvr6 9 Define a new WD_BASEDIR environment variable and set it to point to the location of your WinDriver directory as selected during the installation This variable is used in the make and source files of the WinDriver samples and generated DriverWizard 5 code and is also used to determine the default directory for saving your generated DriverWizard project If you do not define this variable you will be instructed to do so when attempting to build the sample generated code using the WinDriver makefiles NOTE If you decide to change the name and or location of your WinDriver directory after the installation you should also edit the value of the WD_BASEDIR environment variable and set it to point to the location of your new WinDriver directory 10 You can now start using WinDriver to access your hardware and generate your driver code TIP You can use the wdreg script to load the WinDriver kernel module 10 3 To automatically load windrvr6 o ko on each boot run the wdreg script from the target Linux etc rc d rc local file wdreg windrvr6 The following steps are for registered users only In order to register your copy of WinDriver with the license you received from Jungo follow the s
166. rt 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 various 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 2 3 Classification of Drivers According to Operating Systems 2 3 1 WDM Drivers WDM Windows Driver Model drivers are kernel mode drivers within the Windows NT and Windows 98 operating system families The Windows NT family includes Windows NT 2000 XP Server 2003 Vista and the Windows 98 family includes Windows 98 and Windows Me WDM works by channeling some of the work of the device driver into portions of the code that are integrated into the operating system These portions of code handle all of the low level buffer management including DMA and Plug and Play Pnp device enumeration 2 3 Classification of Drivers According to Operating Systems 26 WDM drivers are PnP drivers that support power management protocols and include monolithic drivers layered drivers and miniport drivers 2 3 2 VxD Drivers VxD drivers are Windows 95 98 Me Virtual Device Drivers often called VxDs because the file names end with the vxd extension VxD drivers are typically monolithic in nature Th
167. s code using eMbedded Visual C to meet your specific needs If you are using Platform Builder activate it and insert the generated pbp into your workspace 5 Test and debug your code and hardware from the CE emulation running on the host machine 1 9 What Does the WinDriver Toolkit Include A printed version of this manual Two months of free technical support Phone Fax Email WinDriver modules The WinDriver CD Utilities Chipset support APIs Sample files 1 9 What Does the WinDriver Toolkit Include 19 1 9 1 WinDriver Modules e WinDriver WinDriver include the general purpose hardware access toolkit The main files here are windrvr h Declarations and definitions of WinDriver s basic API wdu_lib h Declarations and definitions of the WinDriver USB WDU library which provides convenient wrapper USB APIs windrvr_int_thread h Declarations of convenient wrapper functions to simplify interrupt handling windrvr_events h Declarations of APIs for handling and Plug and Play and power management events utils h Declarations of general utility functions status_strings h Declarations of API for converting WinDriver status codes to descriptive error strings DriverWizard WinDriver wizard wdwizard a graphical tool that diagnoses your hardware and enables you to easily generate code for your driver refer to Chapter 5 for details Graphical Debugger WinDrive
168. s explained in section 12 2 2 1 you can replace references to the WinDriver redist directory with references to the generated xxx_installation redist directory where xxx is the name of your generated driver project 1 WinDriver Kernel Module windrvr6 0 ko is a kernel module it must be recompiled for every kernel version on which it is loaded To facilitate this we supply the following components all provided under the WinDriver redist directory unless explicitly specified otherwise in order to insulate the WinDriver kernel module from the Linux kernel windrvr_gcc_v2 a windrvr_gcec_v3 a and windrvr_gcc_v3_regparm a compiled object code for the WinDriver kernel module windrvr_gec_v2 a is used for kernels compiled with GCC v2 x x and windrvr_gec_v3 a is used for kernels compiled with GCC v3 x x windrvr_gec_v3_regparm a is used for kernels compiled with GCC v3 x x with the regparm flag linux_wrappers c h wrapper library source code files that bind the WinDriver kernel module to the Linux kernel linux_common h windrvr h wd_ver h and wdusb_interface h header files required for building the WinDriver kernel module on the target wdusb_linux c used by WinDriver to utilize the USB stack 11 4 Linux Driver Distribution 115 e configure a configuration script which creates a makefile that compiles and inserts the module windrvr6 o ko into the kernel makefile in wdreg provided under the WinDriver util director
169. s only necessary if you want the WinDriver CE kernel file windrvr6 dll to be a permanent part of the Windows CE image NK BIN which is the case if you select to transfer the file to your target platform using a floppy disk If you prefer to have the file windrvr6 dll loaded on demand via the CESH PPSH services you do not need to carry out this step until you build a permanent kernel 5 Select Make Run Time Image from the Build menu and name the new image NK BIN 6 Download your new kernel to the target platform and initialize it either by selecting Download Initialize from the Target menu or by using a floppy disk 4 2 WinDriver Installation Process 49 7 Restart your target CE platform The WinDriver CE kernel will automatically load 8 Compile and run the sample programs to make sure that WinDriver CE is loaded and is functioning correctly see section 4 4 2 which describes how to check your installation 4 2 2 2 Installing WinDriver CE when Developing Applications for Windows CE Computers NOTE Unless otherwise specified Windows CE references in this section include all supported Windows CE platforms including Windows Mobile The following instructions apply to driver developers who do not build the Windows CE kernel but only download their drivers built using Microsoft eMbedded Visual C Windows CE 4 x 5 x or MSDEV NET 2005 Windows Mobile or Windows CE 6 x to a ready made Windows CE platform 1 In
170. s to the device Chapter 9 of the USB specification defines standard device requests USB requests such as these are sent from the host to the device using setup packets The USB device is required to respond properly to these requests In addition each vendor may define device specific setup packets to perform device specific operations The standard setup packets standard USB device requests are detailed below The vendor s device specific setup packets are detailed in the vendor s data book for each USB device 9 2 USB Control Transfers 90 9 2 1 4 USB Setup Packet Format The table below shows the format of the USB setup packet For more information please refer to the USB specification at http www usb org Byte Description bmRequest Type Bit 7 Request direction 0 Host to device Out 1 Device to host In Bits 5 6 Request type O standard 1 class 2 vendor 3 reserved Bits 0 4 Recipient O device 1 interface 2 endpoint 3 other The actual request see the Standard Device Request Codes table 9 2 1 5 llos A word size value that varies according to the request For example in the CLEAR_FEATURE request the value is used to select the feature in the GET_DESCRIPTOR request the value indicates the descriptor type and in the SET_ADDRESS request the value contains the device address 3 vaen The upper byte of the Value word wIndexL A word size value that varies according to the request The index is
171. section are currently supported only on Windows 2000 and higher B 4 9 1 WDU_StreamOpen PURPOSE e Opens a new stream for the specified pipe A stream can be associated with any pipe except for the control pipe Pipe 0 The stream s data transfer direction read write is derived from the direction of its pipe PROTOTYPE DWORD DLLCALLCONV WDU_StreamOpen WDU_DEVICE HANDLE hDevice DWORD dwPipeNum DWORD dwBufferSize DWORD dwRxSize BOOL fBlocking DWORD dwOptions DWORD dwRxTxTimeout WDU_STREAM_HANDLE phStream PARAMETERS Type B 4 USB Functions DESCRIPTION fBlocking dwOptions dwRxTxTimeout 165 Description A unique identifier for the device interface The number of the pipe for which to open the stream The size in bytes of the stream s data buffer The size in bytes of the data blocks that the stream reads from the device This parameter is relevant only for read streams and must be set to a value that is not larger than the value of the dwBufferSize parameter e TRUE for a blocking stream which performs blocked I O e FALSE for a non blocking stream which performs non blocking I O For additional information refer to section 9 3 3 1 A bit mask which can consists of a combination of any of the following flags USB_ISOCH_NOASAP For isochronous data transfers Setting this option instructs the lower USB stack driver usbd sys to use a preset frame number in
172. sert the WinDriver CD into your Windows host CD drive 2 Exit the automatic installation 3 Double click the CD_SETUP EXE file found in the WINCE directory on the CD This will copy all required WinDriver files to your host development platform 4 Copy WinDriver s kernel module windrvr6 dll from the WinDriver redist WINCE lt TARGET_CPU gt directory on the Windows host development PC to the Windows directory on your target Windows CE platform 5 Add WinDriver to the list of device drivers Windows CE loads on boot e Modify the registry according to the entries documented in the file WinDriver samples wince_installl project_wd reg This can be done using the Windows CE Pocket Registry Editor on the hand held CE computer or by using the Remote CE Registry Editor Tool supplied with MS eMbedded Visual C Windows CE 4 x 5 x MSDEV NET 2005 Windows Mobile or Windows CE 6 x Note that in order to use the Remote CE Registry Editor tool you will need to have Windows CE Services installed on your Windows host platform On Windows Mobile the operating system s security scheme prevents the loading of unsigned drivers at boot time therefore the WinDriver 4 2 WinDriver Installation Process 50 kernel module has to be reloaded after boot To load WinDriver on the target Windows Mobile platform every time the OS is started copy the WinDriver redist Windows_Mobile_5_ARMV4I wdreg exe utility to the Windows StartUp dir
173. sit our web site http www jungo com In order to install the registered version of WinDriver and to activate driver code that you have developed during the evaluation period on the development machine please follow the installation instructions found in section 4 2 above 104 11 2 Windows Driver Distribution 105 11 2 Windows Driver Distribution NOTES e For Windows 2000 XP Server 2003 Vista all references to wdreg in this section can be replaced with wdreg_gui which offers the same functionality but displays GUI messages instead of console mode messages For Windows 98 Me all references to wdreg should be replaced with wdregl6 For more information regarding the wdreg utility see Chapter 10 The WinDriver installation directory contains two distribution directories redist and redist_win98_compat WinDriver redist contains a digitally signed WHQL compliant windrvr6 sys driver and related INF and catalog files for Windows 2000 XP Server 2003 Vista see section 12 3 of the manual for details regarding digital driver signature and WHQL certification WinDriver redist_win98_compat contains an unsigned windrvr6 sys driver and a related INF file for Windows 98 Me 2000 XP Server 2003 Vista When distributing the driver to a Windows 98 Me replace any references to the WinDriver redist directory in this section with WinDriver redist_win98_compat You can also use the files from this directory for a Windows
174. ss sine Hw ew iaa 3 6 2 Isochronous Transfer segre ssp y e ae 3 6 3 Interrupt Transfer o 364 Bulk Transter s s yec oes Bok Bs a Owe oR Ee OR USB Configuration ieda e seei e OS EE Oe e Winbriver USB 0 enea 4b dae a oe a eee eae eS WinDriver USB Architecture 2 0 0 0 00000004 Which Drivers Can I Write with WinDriver USB Installing WinDriver System Requirements e res so arepita gtp tepe opia 4 1 1 Windows System Requirements 4 1 1 1 Windows 98 Me System Requirements 4 1 1 2 Windows 2000 XP Server 2003 Vista System Requirements se ee g e ro eap a y ea 4 1 2 Windows CE System Requirements 4 1 3 Linux System Requirements WinDriver Installation Process ooo 4 2 1 Windows WinDriver Installation Instructions 4 2 2 Windows CE WinDriver Installation Instructions 4 2 2 1 Installing WinDriver CE when Building New CE Based Platforms 4 2 2 2 Installing WinDriver CE when Developing Applications for Windows CE Computers 4 2 2 3 Windows CE Installation Note 4 2 3 Linux WinDriver Installation Instructions 4 2 3 1 Preparing the System for Installation 4 2 3 2 Installation 29 26 26 26 ay 27 27 43 43 43 43 43 44 44 45 45 47 47 CONTENTS 7 4 2 3 3 Restricting Hardware Access on Linux 4 3 Upgrading Your Installation
175. stead of the next available frame while performing the data transfer Use this flag if you notice unused frames during the transfer on low speed or full speed devices USB 1 1 only and only on Windows USB_ISOCH_RESET Resets the isochronous pipe before the data transfer It also resets the pipe after minor errors consequently allowing the transfer to continue USB_ISOCH_FULL_PACKETS_ONLY Prevents transfers of less than the packet size on isochronous pipes USB_BULK_INT_URB_SIZE_OVERRIDE_128K Limits the size of the USB Request Block URB to 128KB USB_ STREAM OVERWRITE_BUFFER_WHEN_FULL When there is not enough free space in a read stream s data buffer to complete the transfer overwrite old data in the buffer Applicable only to read streams Maximum time in milliseconds ms for the completion of a data transfer between the stream and the device A value of zero indicates no timeout infinite wait Pointer to a unique identifier for the stream to be returned by the function and passed to the other WDU_StreamXXX functions B 4 USB Functions 166 RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 9 2 WDU_StreamStart PURPOSE e Starts a stream i e starts transfers between the stream and the device Data will be transferred according to the stream s direction read write PROTOTYPE DWORD DLLCALLCONV WDU_StreamStart WDU_STREAM HAN
176. stributing Your Driver Legal Issues WinDriver is licensed per seat The WinDriver license allows one developer on a single computer to develop an unlimited number of device drivers and to freely distribute the created drivers without royalties as outlined in the license agreement in the WinDriver docs license pdf file 237 Appendix G Additional Documentation UPDATED MANUALS The most updated WinDriver user manuals can be found on Jungo s site at http www jungo com st support support_windriver html VERSION HISTORY If you wish to view WinDriver version history refer to the WinDriver Release Notes http www jungo com st wdver htm1 The release notes include a list of the new features enhancements and fixes that have been added in each WinDriver version TECHNICAL DOCUMENTS For additional information refer to the WinDriver Technical Documents database http www jungo com st support tech_docs_indexes main_index html This database includes detailed descriptions of WinDriver s features utilities and APIs and their correct usage troubleshooting of common problems useful tips and answers to frequently asked questions 238
177. t first registering the device to work with windrvr6 sys This is done by installing an INF file for the device The DriverWizard will offer to automatically generate the INF file for your device You can use the DriverWizard to generate the INF file on the development machine as explained in section 5 2 of the manual and then install the INF file on any machine to which you distribute the driver as explained in the following sections 116 12 1 INF Files Windows 98 Me 2000 XP Server 2003 Vista 117 12 1 1 Why Should I Create an INF File To stop the Windows Found New Hardware Wizard from popping up after each boot To enable WinDriver and DriverWizard to access USB devices To ensure that the operating system can assign physical addresses to a USB device To load the new driver created for the device An INF file must be created whenever developing a new driver for Plug and Play hardware that will be installed on a Plug and Play system To replace the existing driver with a new one 12 1 2 How Do I Install an INF File When No Driver Exists NOTE You must have administrative privileges in order to install an INF file on Windows 98 Me 2000 XP Server 2003 Vista e Windows 2000 XP Server 2003 Vista On Windows 2000 XP Server 2003 Vista you can use the wdreg utility with the install command to automatically install the INF file wdreg inf lt path to the INF file gt install for more information refer to sect
178. ta exchange The WinDriver APIs enable you to implement both control and functional data transfers Figure 9 1 demonstrates how a device s pipes are displayed in the DriverWizard utility which enables you to perform transfers from a GUI environment Alternate Setting 2 Pipe Name Pipe Type Information Control Pipe Pipe 00 HL 1 pipe Oxo Control rection in amp out packet size 64 Functional gman ak rection in packet size 512 Pipes Bulk 3 ppeOx6 Buk rection out packet size 512 Interrupt Isochronous Figure 9 1 USB Data Exchange 87 9 2 USB Control Transfers 88 Section 9 2 below provides detailed information regarding USB control transfers and how they can be implemented using WinDriver Section 9 3 describes the functional data transfer implementation options provided by WinDriver 9 2 USB Control Transfers 9 2 1 USB Control Transfers Overview 9 2 1 1 Control Data Exchange USB control exchange is used to determine device identification and configuration requirements and to configure a device and can also be used for other device specific purposes including control of other pipes on the device Control exchange takes place via a control pipe mainly the default Pipe 0 which always exists The control transfer consists of a setup stage in which a setup packet 1s sent from the host to the device an optional data stage and a status stage 9 2 1 2 More About the Control Transfer
179. teps below 11 Activate the DriverWizard GUI lt path to WinDriver gt wizard wdwizard 4 3 Upgrading Your Installation 54 12 Select the Register WinDriver option from the File menu and insert the license string you received from Jungo 13 Click the Activate License button 14 To register source code that you developed during the evaluation period refer to the documentation of WDU_Init B 4 1 4 2 3 3 Restricting Hardware Access on Linux CAUTION Since dev windrvr6 gives direct hardware access to user programs it may compromise kernel stability on multi user Linux systems Please restrict access to the DriverWizard and the device file dev windrvr6 to trusted users For security reasons the WinDriver installation script does not automatically perform the steps of changing the permissions on dev windrvr6 and the DriverWizard executable wdwizard 4 3 Upgrading Your Installation To upgrade to a new version of WinDriver on Windows follow the steps outlined in section 4 2 1 which illustrate the process of installing WinDriver for Windows 98 Me 2000 XP Server 2003 Vista You can either choose to overwrite the existing installation or install to a separate directory After installation start DriverWizard and enter the new license string if you have received one This completes the upgrade of WinDriver To upgrade your source code pass the new license string as a parameter to WDU_Init B 4 1 or to WD_License
180. terval elapses PROTOTYPE DWORD OsEventWait HANDLE hOsEvent DWORD dwSecTimeout PARAMETERS Tnput Output HANDLE DWORD DESCRIPTION Name The handle to the event object dwSecTimeout Time out interval of the event in seconds A time out value of zero signifies an infinite wait RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 7 User Mode Utility Functions 217 B 7 8 OsEventSignal PURPOSE e Sets the specified event object to the signaled state PROTOTYPE DWORD OsEventSignal HANDLE hOsEvent PARAMETERS Tnput Output HANDLE DESCRIPTION The handle to the event objec RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 7 User Mode Utility Functions 218 B 7 9 OsEventReset PURPOSE e Resets the specified event object to the non signaled state PROTOTYPE DWORD OsEventReset HANDLE hOsEvent PARAMETERS ImputOuipal HANDLE DESCRIPTION The handle to the event objec RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 7 User Mode Utility Functions 219 B 7 10 OsMutexCreate PURPOSE e Creates a mutex object PROTOTYPE DWORD OsMutexCreate HANDLE phOsMutex PARAMETERS pavo ip gt phOsMutex HANDLE DESCRIPTION Description phOsMutex The pointer to a variable that receives a handle
181. the following Microsoft web pages e WHQL home page http www microsoft com whdc whql default mspx e WHQL Policies page http www microsoft com whdc whql policies default mspx e Windows Quality Online Services Winqual home page https winqual microsoft com e Winqual help https winqual microsoft com Help e WHQL tests procedures and forms download page http www microsoft com whdc whql WHOLdwn mspx e Windows Driver Kit WDK http www microsoft com whdc devtools wdk default mspx e Driver Test Manager DTM http www microsoft com whdc DevTools WDK DIM mspx Note Some of the links require Windows Internet Explorer 12 3 Digital Driver Signing amp Certification Windows 2000 XP Server 2003 Vista 129 12 3 2 Driver Signing amp Certification of WinDriver Based Drivers As indicated above 12 3 1 1 The WinDriver redist windrvr6 sys driver has an Authenticode signature Since WinDriver s kernel module windrvr6 sys is a generic driver which can be used as a driver for different types of hardware devices it cannot be submitted as a stand alone driver for WHQL certification However once you have used WinDriver to develop a Windows 2000 XP Server 2003 Vista driver for your selected hardware you can submit both the hardware and driver for Microsoft WHQL certification as explained below The driver certification and signature procedures either via Authenticode or WHQL require the crea
182. the WD_ACKNOWLEDGE flag was not set in the call to WDU_Init then the return value of the callback function is insignificant B 3 USB User Callback Functions 144 B 3 2 WDU_DETACH_CALLBACK PURPOSE e WinDriver calls this function when a controlled device has been detached from the system PROTOTYPE typedef void DLLCALLCONV WDU_DETACH _CALLBACK WDU_DEVICE HANDLE hDevice PVOID pUserData PARAMETERS Name Type Input Output WDU_DEVICE HANDLE PVOID DESCRIPTION Name A unique identifier for the device interface pUserData Pointer to user mode data for the callback as passed to WDU_Init B 4 1 within the event table parameter pEventTable gt pUserData RETURN VALUE None B 3 USB User Callback Functions 145 B 3 3 WDU_POWER_CHANGE_CALLBACK PURPOSE e WinDriver calls this function when a controlled device has changed its power settings PROTOTYPE typedef BOOL DLLCALLCONV WDU_POWER_CHANGE CALLBACK WDU_DEVICE HANDLE hDevice DWORD dwPowerState PVOID pUserData PARAMETERS Input Output DWORD PVOID DESCRIPTION A unique identifier for the device interface dwPowerState Number of the power state selected pUserData Pointer to user mode data for the callback as passed to WDU_Init B 4 1 within the event table parameter pEventTable gt pUserData RETURN VALUE TRUE FALSE Currently there is no significance to the return value REMARKS e This call
183. tion USB guarantees the isochronous transfer access to the USB bandwidth i e 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 Since timeliness is more important than correctness in this type of transfer no retries are made in case of error in the data transfer However the data receiver can determine that an error occurred on the bus 3 6 3 Interrupt Transfer Interrupt Transfer is intended for devices that send and receive small amounts of data infrequently or in an asynchronous time frame This transfer type can be used for low full and high speed devices Interrupt transfer type guarantees a maximum service period and that delivery will be re attempted in the next period if there is an error on the bus The interrupt pipe like the isochronous pipe is unidirectional and periodical The maximum packet size for interrupt endpoints can be 8 bytes or less for low speed devices 64 bytes or less for full speed devices and 1 024 bytes or less for high speed devices 3 7 USB Configuration 36 3 6 4 Bulk Transfer Bulk Transfer is typically used for devices that transfer large amounts of non time sensitive data and that can use any available bandwidth such as printers and scanners This transfer type can be used by full speed and high speed devices but not by low speed devices Bulk transfer is non
184. tion of a catalog file for the driver This file is a sort of hash which describes other files The signed windrvr6 sys driver is provided with a matching catalog file WinDriver redist wd920 cat This file is assigned to the CatalogFile entry in the windrvr6 inf file provided as well in the redist directory This entry is used to inform Windows of the driver s signature and the relevant catalog file during the driver s installation When the name contents or even the date of the files described in a driver s catalog file is modified the catalog file and consequently the driver signature associated with it become invalid Therefore if you select to rename the windrvr6 sys driver 12 2 and or the related windrvr6 inf file the wd920 cat catalog file and the related driver signature will become invalid In addition when using WinDriver to develop a driver for your Plug and Play device you normally also create a device specific INF file that registers your device to work with the windrvr6 sys driver module or a renamed version of this driver Since this INF file is created at your site for your specific hardware it is not referenced from the wd920 cat catalog file and cannot be signed by Jungo apriori When renaming windrvr6 sys and or creating a device specific INF file for your device you have two alternative options regarding your driver s digital signing e Do not digitally sign your driver If you select this option r
185. to install any other INF files This section explains how to use the wdreg utility to install the WDM windrvr6 sys driver on Windows 98 Me 2000 XP Server 2003 Vista or to install INF files that register USB devices to work with this driver on Windows 2000 XP Server 2003 Vista 10 2 Windows Dynamic Driver Loading 101 On Windows 2000 XP Server 2003 Vista you can rename the windrvr6 sys kernel module and modify your device INF file to register with your renamed driver as explained in section 12 2 1 To install your modified INF files using wdreg simply replace any references to windrvr6 below with the name of your new driver Usage The wdreg utility can be used in two ways as demonstrated below 1 2 wdreg inf lt filename gt silent log lt logfile gt install uninstall enable disable wdreg rescan lt enumerator gt silent log lt logfile gt OPTIONS wdreg supports several basic OPTIONS from which you can choose one some or none inf The path of the INF file to be dynamically installed rescan lt enumerator gt Windows 2000 XP Server 2003 Vista Rescan enumerator ROOT USB etc for hardware changes Only one enumerator can be specified silent Suppress display of all messages optional log lt logfile gt Log all messages to the specified file optional compat Windows 2000 XP Server 2003 Vista Use the traditional SetupDi API instead of the ne
186. to the recipient Time progresses from top to bottom B 2 WinDriver USB WDU Library Overview 140 time detach WinDriver WDU_Init Notify the user of currenfly attached devices Signal Attach A A Notify the user of the attach of the new device Signal Attach SS WDU_SetInterface 2 WDU _Transer rain may tt er guests o W USB Device Notify the user ofthe detached device Signal Detach device_detach YYDU_Uninit If the WD_ACKNOVVLEDGE flag was set in the call to VWWDU_Init the attach callback should return TRUE to accept control of the device or FALSE otherwise USB Device 2 Only possible if the attach callback returned TRUE Figure B 1 WinDriver USB Calling Sequence B 2 WinDriver USB WDU Library Overview 141 The following piece of meta code can serve as a framework for your user mode application s code attach if this is my device Set the desired alternate setting Signal main about the attachment of this device a return TRUE else return FALSE detach signal main about the detachment of this device main WDU_Init while wait for new devices issue transfers WDU_Uninit B 2 WinDriver USB WDU Library Overview 142 B 2 2 Upgrading from the WD_xxx USB API to the WDU_xxx API The WinDriver WDU_xxx USB API provided beginning with version 6 00 is designed to support event driven trans
187. transfer complete with an error WD_USBD_STATUS_ISOCH_REQUEST_FAILED HCD Isochronous transfer completed with error Returned by USBD if the frame length control for a given HC Host Controller is already taken by another driver WD_USBD_STATUS_FRAME_CONTROL_OWNED USBD Frame length control already taken Returned by USBD if the caller does not own frame length control and attempts to release or modify the HC frame length WD_USBD_STATUS_FRAME_CONTROL_NOT_OWNED USBD Attempted operation on frame length control not owned by caller Additional software error codes added for USB 2 0 for Windows only WD_USBD_STATUS_NOT_SUPPORTED JSBD API not upported implemented ISBD Invalid configuration descriptor ISBD Insufficient resources ISBD Set configuration failed ISBD Buffer too small WD_USBD_STATUS_INTERFACE_NOT_FOUND JSBD Interface not found WD_USBD_STATUS_INAVLID_PIPE_ FLAGS JSBD Invalid pipe flags WD_USBD_STATUS_TIMEOUT JSBD Timeout WD_USBD_STATUS_DEVICE_GONE SBD Device gone a E E 7 SBD Status not mapped E WD_USBD_STATUS_STATUS_NOT_MAPPED Extended isochronous error codes returned by USBD These errors appear in the packet status field of an isochronous transfer WD_USBD_STATUS_ISO_NOT_ACCESSED_BY_HW USBD The controller did not access WD_USBD_STATUS_ISO_TD_ERROR USBD Controller reported an error in the TD WD_USBD_STATUS_ISO_NA_LATE_USBPORT USBD The packet was submitted in time by the c
188. try property The function will fill the buffer only if the buffer size as indicated in the input value of the pdwSize parameter is sufficient i e gt the property s size as returned via pdwSize pBuffer can be set to NULL when using the function only to retrieve the size of the registry property see pdwSize pdwSize As input points to a value indicating the size of the user supplied buffer pBuffer if pBuffer is set to NULL the input value of this parameter is ignored As output points to a value indicating the required buffer size for storing the registry property B 4 USB Functions 151 property The ID of the registry property to be retrieved see the description of the WD_DEVICE_REGISTRY_PROPERTY enumeration B 5 1 Note String registry properties are in WCHAR format RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 REMARKS e When the size of the provided user buffer pBuf fer pdwSize input is not sufficient to hold the requested registry property the function returns WD_INVALID_PARAMETER e This function is supported only on Windows 2000 and higher B 4 USB Functions 152 B 4 5 WDU_GetDevicelnfo PURPOSE e Gets configuration information from a device including all the device descriptors NOTE The caller to this function is responsible for calling WOU_PutDevicelInfo B 4 6 in order to free the ppDeviceInfo pointer return
189. ts List 22 4 be eee bbe he ee ee ees 94 USB Request Loo omisiones GOR a we G 95 LIST OF FIGURES B 1 WinDriver USB Calling Sequence B 2 WinDriver USB Structures B 3 WinDriver API Calling Sequence Chapter 1 WinDriver Overview In this chapter you will explore the uses of WinDriver and learn the basic steps of creating your driver This manual outlines WinDriver s support for USB devices WinDriver also supports development for PCI PCMCIA CardBus ISA EIS A CompactPCI PCI Express devices For detailed information regarding WinDriver s support for these buses please refer to the WinDriver Product Line page on our web site http www jungo com st windriver htm1 and to the WinDriver PCI PCMCIA CardBus ISA EISA CompactPCI PCI Express User s Manual whic is available on line at http www jungo com st support support_windriver html 1 1 Introduction to WinDriver WinDriver is a development toolkit that dramatically simplifies the difficult task of creating device drivers and hardware access applications WinDriver includes a wizard and code generation features that automatically detect your hardware and generate the driver to access it from your application The driver and application you develop using WinDriver is source code compatible across all supported operating systems 1 6 The driver is binary compatible across Windows 98 Me 2000 XP Server 2003 Vista WinDriver provides a complete solution for creating high
190. type and direction into or out of the device Endpoints Data Pipes Data Transfer we Figure 3 1 USB Endpoints A pipe is a logical component that represents an association between an endpoint on the USB device and software on the host Data is moved to and from a device through a pipe A pipe can be either a stream pipe or a message pipe depending on the type of data transfer used in the pipe Stream pipes handle interrupt bulk and isochronous transfers while message pipes support the control transfer type The different USB transfer types are discussed below 3 6 3 5 USB Data Exchange 33 3 5 USB Data Exchange The USB standard supports two kinds of data exchange between a host and a 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 USB data transfers Bulk Interrupt and Isochronous Control Exchange is used to determine device identification and configuration requirements and to configure a device and can also be used for other device specific purposes including control of other pipes on the device Control exchange takes place via a control pipe mainly the default Pipe 0 which always exists 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 Figure 3 2 below depicts a USB device with one bi directional control
191. um DWORD gt dwAlternateSetting DWORD DESCRIPTION A unique identifier for the device interface dwInterfaceNum The interface s number dwAlternateSetting The desired alternate setting value RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 149 B 4 3 WDU_GetDeviceAddr PURPOSE e Gets the USB address for a given device PROTOTYPE DWORD WDU_GetDeviceAddr WDU_DEVICE_HANDLE hDevice ULONG pAddress PARAMETERS Name Input Output WDU_DEVICE_HANDLE gt pAddress ULONG DESCRIPTION Name A unique identifier for a device interface pAddress A pointer to the address number returned by the function RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 REMARKS e This function is supported only on Windows 2000 and higher B 4 USB Functions 150 B 4 4 WDU_GetDeviceRegistryProperty PURPOSE e Gets the specified registry property of a given USB device PROTOTYPE DWORD DLLCALLCONV WDU_GetDeviceRegistryProperty WDU_DEVICE HANDLE hDevice PVOID pBuffer PDWORD pdwSize WD_DEVICE_REGISTRY_PROPERTY property PARAMETERS Input Output WDU_DEVICE_HANDLE pBuffer PVOID PDWORD Inpu Ourpat WD _DEVICE_REGISTRY_PROPERT DESCRIPTION A unique identifier of the device interface pBuffer Pointer to a user allocated buffer to be filled with the requested regis
192. unctional USB Data Transfers 97 9 3 3 Streaming Data Transfers In the streaming USB data transfer scheme data is continuously streamed between the host and the device using internal buffers allocated by the host driver streams Stream transfers allow for a sequential data flow between the host and the device and can be used to reduce single blocking transfer overhead which may occur as a result of multiple function calls and context switches between user and kernel modes This 1s especially relevant for devices with small data buffers which might for example overwrite data before the host is able to read it due to a gap in the data flow between the host and device 9 3 3 1 Performing Streaming with WinDriver WinDriver s NDU_StreamXXX functions described in section B 4 9 of the manual enable you to impelment USB streaming data transfers To begin performing stream transfers call the WOU_St reamOpen function B 4 9 1 When this function is called WinDriver creates a new stream object for the specified data pipe You can open a stream for any pipe except for the control pipe Pipe 0 The stream s data transfer direction read write is derived from the direction of its pipe WinDriver supports both blocking and non blocking stream transfers The open functions Blocking parameter indicates which type of transfer to perform see explanation below Streams that perform blocking transfers will henceforth be
193. unning WinDriver kernel module and general system information 4 5 Uninstalling WinDriver 56 4 5 Uninstalling WinDriver This section will help you to uninstall either the evaluation or registered version of WinDriver 4 5 1 Windows WinDriver Uninstall Instructions NOTES e For Windows 98 Me replace references to wdreg below with wdreg16 e For Windows 2000 XP Server 2003 Vista you can also use the wdreg_gui exe utility instead of wdreg exe e wdreg exe wdreg_gui exe and wdreg16 exe are found under the WinDriver util directory see Chapter 10 for details regarding these utilities 1 Close any open WinDriver applications including DriverWizard the Debug Monitor wddebug_gui exe and user specific applications 2 On Plug and Play Windows systems Windows 98 Me 2000 XP Server 2003 Vista Uninstall all Plug and Play devices USB PCI PCMCIA that have been registered with WinDriver via an INF file e On Windows 2000 XP Server 2003 Vista Uninstall the device using the wdreg utility wdreg inf lt path to the INF file gt uninstall On Windows 98 Me Uninstall Remove the device manually from the Device Manager e Verify that no INF files that register your device s with WinDriver s kernel module windrvr6 sys are found in the windir inf directory and or windir inf other directory Windows 98 Me 3 Uninstall WinDriver e On the development PC on which you installed the WinDriver toolkit Ru
194. ur hardware and verify that it is working properly before you start coding You can then proceed to automatically generate source code with the wizard in a variety of languages including Delphi and Visual Basic For more information refer to Chapter 5 and Section 6 4 3 below 6 4 2 Samples Samples for drivers written using the WinDriver API in Delphi or Visual Basic can be found in 1 WinDriverl delphil samples 2 WinDriverl vb samples Use these samples as a starting point for your own driver 6 4 3 Creating your Driver The method of development in Visual Basic is the same as the method in C using the automatic code generation feature of DriverWizard Your work process should be as follows e Use DriverWizard to easily diagnose your hardware e Verify that it is working properly e Generate your driver code e Integrate the driver into your application e You may find it useful to use the WinDriver samples to get to know the WinDriver API and as your skeletal driver code Chapter 7 Debugging Drivers The following sections describe how to debug your hardware access application code 7 1 User Mode Debugging e Since WinDriver is accessed from the user mode we recommend that you first debug your code using your standard debugging software e The Debug Monitor utility 7 2 logs debug messages from WinDriver s kernel and user mode APIs You can also use WinDriver APIs to send your own debug messages to the Debug Monitor
195. ver NET wrapper AP b b LJ wdapi_dotnet High level WinDriver API wdapi DLL shared object Corro rro roo oro rr Kernel Mode Low Level WinDriver API WinDriver Kernel Module windrvr6 sys o ko dll Host Controller Driver HCD HITBRGIHYER I TI Peel briver 1 11 Omellpriver o E lM Figure 3 4 WinDriver USB Architecture 3 10 Which Drivers Can I Write with WinDriver USB 42 3 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 is required 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 whenever possible Chapter 4 Installing WinDriver This chapter takes you through the process of installing WinDriver on your development platform and shows you how to verify that your WinDriver is properly installed The last section discusses the uninstall procedure To find out how to install the driver you create on target platforms refer to Chapter 11 4 1 System Requirements 4 1 1 Windows System Requirements 4 1 1 1 Windows 98 Me System Requirements e Any x86 32 bit processor e Any 32 bit development environment supporting C VB or Delp
196. vicio A a a ab 6 4 3 Creating your Driver o Debugging Drivers 7 41 User Mode Debugging e e o 1 2 Debug Monitor sp lt pepi seppe 88 be bes ewe eee ee 7 2 1 Using the Debug Monitor in Graphical Mode wddebug gui 7 2 1 1 Running the Graphical Debug Monitor for a Renamed Driver 73 13 74 74 T3 77 77 TT TI CONTENTS 7 2 2 Using the Debug Monitor in Console Mode wddebug 8 Enhanced Support for Specific Chipsets 8 1 8 2 OVEIVIEW iros a Re ew eee A Developing a Driver Using the Enhanced Chipset Support 9 USB Transfers 9 1 9 2 9 3 OVERVIEW 22 Oe Pee eh Oe eee ts USB Control Transfers gt e c ccce ca o e a 9 2 1 USB Control Transfers Overview 9 2 1 1 Control Data Exchange 9 2 1 2 More About the Control Transfer 9 2 1 3 TheSetup Packet 9 2 1 4 USB Setup Packet Format 9 2 1 5 Standard Device Request Codes 9 2 1 6 Setup Packet Example 9 2 2 Performing Control Transfers with WinDriver 9 2 2 1 Control Transfers with DriverWizard 9 2 2 2 Control Transfers with WinDriver API Functional USB Data Transfers o o 9 3 1 Functional USB Data Transfers Overview 9 3 2 Single Blocking Transfers 0 9 3 2 1 Performing Single Blocking Transfers with WinDr
197. warning message will be displayed The message will provide you with the option to either close the open application s uninstall disconnect the relevant device s and Retry to uninstall the driver or Cancel the uninstall of the driver in which case the windrvr6 sys kernel driver will not be uninstalled This ensures that you do not uninstall the WinDriver kernel module windrvr6 sys as long as it is being used You can check if the WinDriver kernel module is loaded by running the Debug Monitor utility WinDriver util wddebug_gui exe When the driver is loaded the Debug Monitor log displays driver and OS information otherwise it displays a relevant error message On the development PC the uninstall command will delete this utility therefore in order to use it after you execute the uninstallation create a copy of wddebug_gui exe before performing the uninstall procedure 4 If windrvr6 sys was successfully unloaded erase the following files if they exist windir system32 drivers windrvr6 sys e windir inf windrvr6 inf Windows 2000 XP Server 2003 Vista windir inf Jungowindrvr6 inf Windows 98 Me 4 5 Uninstalling WinDriver 58 windir system32 wdapi920 dll windir sysWOW64 wdapi920 dll Windows x64 5 Reboot the computer 4 5 2 Linux WinDriver Uninstall Instructions NOTE You must be logged in as root to perform the uninstall procedure 1 Verify that the WinDriver module is n
198. wer Driver Install Frameworks API DIFxAPD ACTIONS wdreg supports several basic ACTIONS install Installs the INF file copies the relevant files to their target locations dynamically loads the driver specified in the INF file name by replacing the older version if needed preinstall Windows 2000 XP Server 2003 Vista Pre installs the INF file for a non present device uninstall Removes your driver from the registry so that it will not load on next boot see note below enable Enables your driver disable Disables your driver i e dynamically unloads it but the driver will reload after system boot see note below 10 2 Windows Dynamic Driver Loading 102 NOTE In order to successfully disable uninstall WinDriver you must first close any open handles to the windrvr6 sys service This includes closing any open WinDriver applications and uninstalling from the Device Manager or using wdreg any USB devices that are registered to work with the windrvr6 sys service or otherwise removing such devices wdreg will display a relevant warning message if you attempt to stop windrvr6 sys when there are still open handles to the service and will enable you to select whether to close all open handles and Retry or Cancel and reboot the PC to complete the command s operation 10 2 3 Dynamically Loading Unloading windrvr6 sys INF Files When using WinDriver you develop a user mode application that controls and
199. wing methods Windows Found New Hardware Wizard This wizard is activated when the device is plugged in or if the device was already connected when scanning for hardware changes from the Device Manager Windows Add Remove Hardware Wizard Right click on My Computer select Properties choose the Hardware tab and click on Hardware Wizard Windows Upgrade Device Driver Wizard Select the device from the Device Manager devices list select Properties choose the Driver tab and click the Update Driver button On Windows 2000 XP Server 2003 Vista you can choose to upgrade the driver directly from the Properties list 12 1 INF Files Windows 98 Me 2000 XP Server 2003 Vista 120 In the manual installation methods above you will need to point Windows to the location of the relevant INF file during the installation If the installation wizard offers to install an INF file other than the one you have generated select Install one of the other drivers and choose your specific INF file from the list We recommend using the wdreg utility to install the INF file automatically instead of installing it manually On Windows 98 Me you need to install the INF file manually via Windows Add New Hardware Wizard or Upgrade Device Driver Wizard as explained below Windows Add New Hardware Wizard NOTE This method can be used if no other driver is currently installed for the device or if the user first uninstalls removes the
200. y and setup_inst_dir the configure script uses makefile in which creates a makefile This makefile calls the wdreg utility shell script and setup_inst_dir All three files must be copied to the target TIP You can use the wdreg script to load the WinDriver kernel module 10 3 To automatically load windrvr6 o ko on each boot run the wdreg script from the target Linux etc re d re local file wdreg windrvr6 You need to distribute these components along with your driver source object code 11 4 2 User Mode Hardware Control Application Shared Objects Copy the hardware control application shared objects that you created with WinDriver to the target If your hardware control application shared objects use libwdapi920 so as is the case for the sample and generated DriverWizard WinDriver projects copy this shared object from the WinDriver lib directory on the development PC to the target s library directory usr lib for 32 bit PowerPC or 32 bit x86 targets usr lib64 for 64 bit x86 targets Since your hardware control application shared objects do not have to be matched against the kernel version number you are free to distribute it as binary code if you wish to protect your source code from unauthorized copying or as source code Note that under the license agreement with Jungo you may not distribute the source code of the libwdapi920 so shared object CAUTION If you select to distribute your source code make sur
201. ytesInBuffer DWORD Output DESCRIPTION Name hStream A unique identifier for the stream as returned by WDU_St reamOpen pfIsRunning Pointer to a value indicating the stream s current state e TRUE the stream is currently running e FALSE the stream is currently stopped pdwLastError Pointer to the last error associated with the stream pdwBytesInBuffer Pointer to the current bytes count in the stream s data buffer RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 173 B 4 9 7 WDU_StreamStop PURPOSE e Stops an active stream i e stops transfers between the stream and the device In the case of a write stream the function flushes the stream i e writes its contents to the device before stopping it PROTOTYPE DWORD DLLCALLCONV WDU_StreamStop WDU_STREAM_HANDLE hStream PARAMETERS Type Input Output WDU STREAM HANDLE Input DESCRIPTION hStream A unique identifier for the stream as returned by WDU_StreamOpen RETURN VALUE Returns WD_STATUS_SUCCESS 0 on success or an appropriate error code otherwise B 8 B 4 USB Functions 174 B 4 9 8 WDU_StreamClose PURPOSE e Closes an open stream The function stops the stream including flushing its data to the device in the case of a write stream before closing it PROTOTYPE DWORD DLLCALLCONV WDU_StreamClose WDU_STREAM_HANDLE hStream PARAMET

WinDriver™ USB User`s Manual

Contents

Download Pdf Manuals

Related Search

Related Contents

WinDriver&trade; USB User`s Manual

Contents

Download Pdf Manuals

Related Search

Related Contents

WinDriver™ USB User`s Manual