Bulk Transfers Using Visual Basic 6.0

Transcription

1 Revision 0.BMay 11, 2001 Introduction This document describes Bulk_XferVB, a small Windows application that uses Bulk Transfers to move data in and out of EZ-USB / EZ-USB FX devices using the EZ-USB General Purpose Device Driver; after some inital dev-board setup, the user types characters into a text box and sees them echoed in another text box, looped-back from the board. Bulk_XFerVB also serves to demonstrate how to write Visual Basic applications that communicate with the EZ-USB family development boards Assumptions Before executing Bulk_XferVB, you should install the Cypress EZ-USB Development Kit, version 1.9. To view or modify the Bulk_XferVB project and related VB form and module files, you should also install Microsoft Visual Studio 6.0. Installation of the Microsoft Win98DDK is not required but may prove helpful as a reference. Installing and running Bulk_XferVB Prepare your EZ_USB Development Board by launching EZ-Control Panel and download ep_pair.hex. Ep_pair is a 8051 program that loops back bulk endpoint packets from EP2OUT to EP2IN. The code is written in C and uses the both the EZ-USB library and the EZ-USB FrameWorks. Please refer to the Development Kit for details. If you have installed Developer Studio, you can run Bulk_XFerVB either by launching the.exe or by running the application within the Visual Basic IDE. Using the application When you used the Control Panel to download the ep_pair.hex 8051 program, you selected a symbolic link to the device driver associated with your EZ-USB board. In Figure 1, this is shown as Ezusb-0 Next, enter the number of characters that will trigger the bulk transfer operation. Then, press the tab key or move your mouse cursor into the first text box and begin typing. If, for example, you entered a trigger value of 3, after typing abc into the input textbox, the characters abc will appear in the output textbox. How Bulk_XferVB works Each character that is typed in the input text box causes a text-changed event to occur and control passes to txtin_change (see listing, line 34). When this happens, the most recently typed character is appended to a trigger buffer of characters. When the length of the trigger buffer equals the trigger value, the routine DoBulkXfer is called (line 309). DoBulkXfer opens the specified EZ-USB device driver, confirms that ep_pair.hex is running on the EZ-USB board, and verifies that the expected communication pipe has been established (lines ). After the correct device has been properly identified, DoBulkXfer writes the trigger buffer characters to the EZ-USB board using the Bulk transfer type (lines ) and control returns to the txtin_change routine. Figure 1. After you launch Bulk_XferVB.exe, select the same device name in the space provided. See Figure 2. Figure 2. Cypress Semiconductor Corporation 3901 North First Street San Jose CA May 11, 2001, rev. 0.B

2 Type Chars continue typing one character continue typing Add Chars to trigger buffer buffer length = trigger value buffered characters Display output buffered characters Bulk Transfer Write Bulk Transfer Read ep_pair firmware on EZ-USB Figure 3. Then, DoBulkXfer is called to read the characters back in, also with a Bulk transfer, and the characters are moved to the output text box. References EZ-USB FX Technical Reference Manual, Version 1.1, Cypress Semiconductor, Universal Serial Bus System Architecture, by Don Anderson, MindShare Inc. Addison-Wesley, 1997, ISBN USB Complete, by Jan Axelson. Lakeview Research, 1999, ISBN USB Design by Example, by John Hyde. John Wylie & Sons, 1999, ISBN

3 Listing 1 ' EZ-USB Bulk Transfer Example 2 ' copyright (c) 2000 Cypress Semiconductor 3 ' 4 ' file: frmbulk.frm 5 6 Option Explicit 7 8 Public strbuffer As String 9 10 Private Sub Form_Load() 11 Dim Index As Integer 12 Dim sdrivername As String 13 Dim hdriver As Long ' find all the attached EZ-USB devices and 16 ' add them to the devices drop-down list 17 For Index = 0 To MAX_USB_DEV_NUMBER sdrivername = "Ezusb-" & Index 19 hdriver = OpenDriver(sDriverName) 20 If hdriver > 0 Then 21 cmbdrivername.additem sdrivername 22 CloseHandle hdriver 23 End If 24 Next If cmbdrivername.listcount > 0 Then 27 cmbdrivername.text = cmbdrivername.list(0) 28 Else 29 ErrMsg (ebaddriver) 30 End 31 End If 32 End Sub Private Sub txtin_change() Dim buffer(63) As Byte 37 Dim result As Long 38 Dim i As Integer 39 Dim ldatalen As Long 40 Dim sdrivername As String ' keep track of new text added to input text 43 strbuffer = strbuffer + Right(txtIn, 1) 44 3

4 45 ' have we hit the "xfer trigger"? 46 If Len(strBuffer) = Val(txtBlkSize.Text) Then ' put new string data into byte buffer 49 ldatalen = Len(strBuffer) 50 For i = 1 To ldatalen 51 buffer(i - 1) = Asc(Mid(strBuffer, i, 1)) 52 Next 53 strbuffer = "" sdrivername = cmbdrivername.text ' write the data to the EZ-USB board 58 result = DoBulkXfer(sDriverName, ewrite, buffer, ldatalen) 59 If result <> 1 Then: ErrMsg (result): Exit Sub ' clear out buffer 62 For i = 0 To 63 ' no rabbits up my sleeve 63 buffer(i) = 0 64 Next ' get text back from EZ-USB board 67 result = DoBulkXfer(sDriverName, eread, buffer, ldatalen) 68 If result <> 1 Then: ErrMsg (result): Exit Sub ' move characters from buffer to output text area 71 For i = 1 To ldatalen 72 txtout.text = txtout.text + Chr(buffer(i - 1)) 73 Next End If ' xfer trigger reached End Sub Private Sub txtblksize_change() 80 Dim temp As Integer 81 ' coerce input to text representing number between 1 and temp = Val(txtBlkSize) If temp < 0 Or temp > 64 Then 85 MsgBox "Enter a valid Bulk Transfer block size between 1 and 64.", vbinformation, _ "Input Error" 87 txtblksize.selstart = 0 88 txtblksize.sellength = 3 89 End If 90 End Sub 4

5 91 92 Private Sub cmdclearin_click() 93 txtin.text = "" 94 End Sub Private Sub cmdclearout_click() 97 txtout.text = "" 98 End Sub Private Sub Form_Activate() 101 txtblksize.setfocus 102 End Sub Private Sub cmdclearin_click() 105 txtin.text = "" 106 End Sub Private Sub cmdclearout_click() 109 txtout.text = "" 110 End Sub Private Sub Form_Activate() 113 txtblksize.setfocus 114 End Sub ' EZ-USB Bulk Transfer Example 117 ' copyright (c) 2000 Cypress Semiconductor 118 ' file: BulkXfer.bas Option Explicit ' = = = = W I N A P I = = = = Public Declare Function CreateFile Lib "kernel32" Alias "CreateFileA" _ 125 (ByVal lpfilename As String, ByVal dwdesiredaccess As Long, ByVal dwsharemode As _ 126 Long, lpsecurityattributes As Any, ByVal dwcreationdisposition As Long, _ 127 ByVal dwflagsandattributes As Long, ByVal htemplatefile As Long) As Long Public Declare Function CloseHandle Lib "kernel32" (ByVal hobject As Long) As Long Public Declare Function DeviceIoControl Lib "kernel32" (ByVal hdevice As Long, _ 132 ByVal dwiocontrolcode As Long, lpinbuffer As Any, ByVal ninbuffersize As Long, _ 133 lpoutbuffer As Any, ByVal noutbuffersize As Long, lpbytesreturned As Long, _ 134 ByVal lpoverlapped As Long) As Long ' = = = = C O N S T A N T S = = = = 5

6 Public Const GENERIC_WRITE = &H Public Const FILE_SHARE_WRITE = &H2 140 Public Const OPEN_EXISTING = Public Const METHOD_BUFFERED = Public Const METHOD_IN_DIRECT = Public Const METHOD_OUT_DIRECT = Public Const MAX_PIPES = Public Const MAX_USB_DEV_NUMBER = Enum ErrorEnum 150 ebadparam = ebaddriver = ebadpipe = End Enum Enum EZ_ReadOrWrite 156 ewrite = eread = End Enum ' = = = = I O C T L D E F I N I O N S = = = = ' Set the base of the IOCTL control codes 164 Private Const Ezusb_IOCTL_INDEX = &H ' (DeviceType) << 16) ((Access) << 14) ((Function) << 2) (Method) 167 ' note: DeviceType for each control code is FILE_DEVICE_UNKNOWN 168 ' FILE_DEVICE_UNKNOWN * 2^16 = &H ' 'Access' = FILE_ANY_ACCESS = Public Const IOCTL_Ezusb_GET_PIPE_INFO = _ 172 &H METHOD_BUFFERED + (Ezusb_IOCTL_INDEX + 0) * Private Const IOCTL_Ezusb_GET_DEVICE_DESCRIPTOR = _ 175 &H METHOD_BUFFERED + (Ezusb_IOCTL_INDEX + 1) * Public Const IOCTL_EZUSB_BULK_READ = _ 178 &H METHOD_OUT_DIRECT + (Ezusb_IOCTL_INDEX + 19) * Public Const IOCTL_EZUSB_BULK_WRITE = _ 181 &H METHOD_IN_DIRECT + (Ezusb_IOCTL_INDEX + 20) *

7 183 ' = = = = U S B R e q ' d D a t a T y p e s = = = = 184 Public Type USBDeviceDescriptorType ' USB device descriptor 185 bdescriptorlength As Byte 186 bdescriptor As Byte 187 ispecrelease As Integer 188 bdeviceclass As Byte 189 bdevicesubclass As Byte 190 bdeviceprotocol As Byte 191 bmaxpacketsize As Byte 192 ivendorid As Integer 193 iproductid As Integer 194 idevicerelease As Integer 195 bmanufacturer As Byte 196 bproduct As Byte 197 bserialnumber As Byte 198 bnumberconfigurations As Byte 199 fill(128) As Byte 200 End Type Public Type BulkTransferControlType 203 lpipenum As Long 204 End Type Public Enum USBDPipeEnum 207 eusbdpipetypecontrol = eusbdpipetypeisochronous 209 eusbdpipetypebulk 210 eusbdpipetypeinterrupt 211 End Enum Public Type USBDPipeInformationType 214 ' 215 ' OUTPUT 216 ' These fields are filled in by USBD 217 ' 218 imaximumpacketsize As Integer 'Maximum packet size for this pipe 219 bendpointaddress As Byte ' 8 bit USB endpoint address (includes direction) 220 ' taken from endpoint descriptor 221 binterval As Byte ' Polling interval in ms if interrupt pipe PipeType As USBDPipeEnum ' PipeType identifies type of transfer valid for this pipe 224 lpipehandle As Long ' 227 ' INPUT 228 ' These fields are filled in by the client driver 7

8 229 ' 230 lmaximumtransfersize As Long ' Maximum size for a single request 231 ' in bytes. 232 lpipeflags As Long 233 End Type Public Type USBDInterfaceInformationType 236 ilength As Integer ' Length of this structure, including 237 ' all pipe information structures that 238 ' follow. 239 ' 240 ' INPUT 241 ' 242 ' Interface number and Alternate setting this 243 ' structure is associated with 244 ' 245 binterfacenumber As Byte 246 balternatesetting As Byte ' 249 ' OUTPUT 250 ' These fields are filled in by USBD 251 ' 252 bclass As Byte 253 bsubclass As Byte 254 bprotocol As Byte 255 breserved As Byte linterfacehandle As Long 258 lnumberofpipes As Long Pipes(MAX_PIPES) As USBDPipeInformationType 261 End Type Public Function GetDeviceDescriptor(hDriverHandle As Long, _ 264 usbdd As USBDeviceDescriptorType) As Integer 265 Dim result As Long 266 Dim lbytesreturned As Long hdriverhandle = OpenDriver(driver) If hdriverhandle > 0 Then 271 result = DeviceIoControl(hDriverHandle, IOCTL_Ezusb_GET_DEVICE_DESCRIPTOR, _ 272 usbdd, Len(usbDD), usbdd, Len(usbDD), lbytesreturned, 0) 273 CloseHandle hdriverhandle 274 Else 8

9 275 result = End If GetDeviceDescriptor = result End Function 281 Function GetPipeInfo(strDriver As String, pi As USBDInterfaceInformationType) As Long 282 ' retrieves information about available pipes 283 ' 284 ' IN strdriver symbolic link name assigned to device driver, e.g. "Ezusb-0" 285 ' OUT pi holds information about pipes after successful return 286 ' 287 ' returns: 1 = successful call 288 ' 0 = unsuccessful call Dim result As Long 291 Dim hdriverhandle As Long 292 Dim lbytesreturned As Long hdriverhandle = OpenDriver(strDriver) GetPipeInfo = If hdriverhandle > 0 Then result = DeviceIoControl(hDriverHandle, IOCTL_Ezusb_GET_PIPE_INFO, pi, _ 301 Len(pi), pi, Len(pi), lbytesreturned, 0) 302 CloseHandle (hdriverhandle) 303 End If GetPipeInfo = result End Function Function DoBulkXfer(strDriver As String, pipe As Integer, ByRef buffer() _ 310 As Byte, ByRef datalen As Long) As Long 311 ' transfers a block of bytes to or from EZ-USB device using Bulk Transfer 312 ' 313 ' IN strdriver symbolic link name assigned to device driver, e.g. "Ezusb-0" 314 ' IN pipe numeric pipe id 315 ' I/O buffer byte array for data 316 ' I/O datalen integer variable containing number of valid data bytes in buffer 317 ' 318 ' returns: 1 = successful transfer 319 ' 0 = unsuccessful transfer; caller should call EZGetLastError function 320 ' -1 = bad parameter 9

10 321 ' -2 = bad driver 322 ' -3 = bad pipe number 323 Dim hdriverhandle As Long 324 Dim result As Long 325 Dim btc As BulkTransferControlType 326 Dim pi As USBDInterfaceInformationType 327 Dim usbdd As USBDeviceDescriptorType 328 Dim lbytesreturned As Long ' get a handle to the requested driver 331 hdriverhandle = OpenDriver(strDriver) 332 ' 333 If hdriverhandle > 0 Then ' is ep_pair.hex loaded into the EZ-USB firmware? result = DeviceIoControl(hDriverHandle, IOCTL_Ezusb_GET_DEVICE_DESCRIPTOR, _ 338 usbdd, Len(usbDD), usbdd, Len(usbDD), lbytesreturned, 0) If result = 0 Then: DoBulkXfer = result ' VID 0x547 and PID 0x1002 set up by ep_pair.hex download 343 If usbdd.ivendorid <> &H547 And usbdd.iproductid <> &H1002 Then 344 DoBulkXfer = ebadpipe 345 Exit Function 346 End If ' get data about caller's pipe 349 result = GetPipeInfo(strDriver, pi) If result = 0 Then 352 DoBulkXfer = result 353 Exit Function 354 End If ' is caller's pipe legal? 357 If pi.lnumberofpipes <= pipe Then 358 DoBulkXfer = ebadpipe 359 Exit Function 360 Else ' put the pipe id into the BulkTransferControl structure 361 btc.lpipenum = pipe 362 End If ' determine the endpoint direction and do the device call 365 If (pi.pipes(pipe).bendpointaddress > 128) Then 366 result = DeviceIoControl(hDriverHandle, IOCTL_EZUSB_BULK_READ, btc, _ 10

11 367 Len(btc), buffer(0), datalen, datalen, 0) 368 Else 369 result = DeviceIoControl(hDriverHandle, IOCTL_EZUSB_BULK_WRITE, btc, _ 370 Len(btc), buffer(0), datalen, datalen, 0) 371 End If ' close the driver 374 CloseHandle (hdriverhandle) DoBulkXfer = result Else DoBulkXfer = ebaddriver End If End Function Function OpenDriver(sDriverName As String) As Long 387 ' get handle to EZ-USB driver 388 ' 389 ' IN sdrivername symbolic link name assigned during enumeration 390 ' 391 ' returns: driver handle 392 ' 393 ' called by: BulkXFer 394 ' GetPipeInfo OpenDriver = CreateFile("\\.\" & sdrivername, GENERIC_WRITE, FILE_SHARE_WRITE, _ 397 vbnull, OPEN_EXISTING, 0, vbnull) End Function Sub ErrMsg(err As ErrorEnum) 402 ' display error messages to user 403 ' 404 ' IN err error code returned from BulkXfer 405 ' 406 ' called By: BulkXfer Select Case err Case ebaddriver 411 MsgBox "Selected EZ-USB Device Driver was not found. Perhaps no " & _ 412 "device is connected.", vbokonly + vbcritical, "BulkXFer Error" 11

12 413 Case ebadpipe 414 MsgBox "Correct Pipe not found. Perhaps ""Ep-pair.hex"" was not " & _ 415 "downloaded to a development board.", vbokonly + vbcritical, "BulkXFer Error" 416 Case Else 417 MsgBox "Unknown Error.", vbokonly + vbcritical, "BulkXFer Error" 418 End Select End Sub 12