APPLICATION NOTE 9.15

Transcription

1 APPLICATION NOTE 9.15 U2DP Driver Development Specification Rev. 02/14/2002

2 80 Arkay Drive Hauppauge, NY (631) FAX (631) Copyright SMSC All rights reserved. Circuit diagrams and other information relating to SMSC products are included as a means of illustrating typical applications. Consequently, complete information sufficient for construction purposes is not necessarily given. Although the information has been checked and is believed to be accurate, no responsibility is assumed for inaccuracies. SMSC reserves the right to make changes to specifications and product descriptions at any time without notice. Contact your local SMSC sales office to obtain the latest specifications before placing your product order. The provision of this information does not convey to the purchaser of the described semiconductor devices any licenses under any patent rights or other intellectual property rights of SMSC or others. All sales are expressly conditional on your agreement to the terms and conditions of the most recently dated version of SMSC's standard Terms of Sale Agreement dated before the date of your order (the "Terms of Sale Agreement"). The product may contain design defects or errors known as anomalies which may cause the product's functions to deviate from published specifications. Anomaly sheets are available upon request. SMSC products are not designed, intended, authorized or warranted for use in any life support or other application where product failure could cause or contribute to personal injury or severe property damage. Any and all such uses without prior written approval of an Officer of SMSC and further testing and/or modification will be fully at the risk of the customer. Copies of this document or other SMSC literature, as well as the Terms of Sale Agreement, may be obtained by visiting SMSC s website at SMSC is a registered trademark of Standard Microsystems Corporation ( SMSC ). Product names and company names are the trademarks of their respective holders. SMSC DISCLAIMS AND EXCLUDES ANY AND ALL WARRANTIES, INCLUDING WITHOUT LIMITATION ANY AND ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND AGAINST INFRINGEMENT AND THE LIKE, AND ANY AND ALL WARRANTIES ARISING FROM ANY COURSE OF DEALING OR USAGE OF TRADE. IN NO EVENT SHALL SMSC BE LIABLE FOR ANY DIRECT, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES; OR FOR LOST DATA, PROFITS, SAVINGS OR REVENUES OF ANY KIND; REGARDLESS OF THE FORM OF ACTION, WHETHER BASED ON CONTRACT; TORT; NEGLIGENCE OF SMSC OR OTHERS; STRICT LIABILITY; BREACH OF WARRANTY; OR OTHERWISE; WHETHER OR NOT ANY REMEDY OF BUYER IS HELD TO HAVE FAILED OF ITS ESSENTIAL PURPOSE, AND WHETHER OR NOT SMSC HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SMSC AN 9.15 Page 2 Rev. 02/14/2002

3 TABLE OF CONTENTS 1 Architecture Description User Mode IOCTL Interface IO Control Codes (IOCTL) IOCTL_USB_DATAPUMP_READ IOCTL_USB_DATAPUMP_WRITE IOCTL_USB_DATAPUMP_GETVIDPID IOCTL_USB_DATAPUMP_SETTIMEOUT Transport Definition / Driver to Firmware Description PHASE-1 / Transmission of CBW PHASE-2 / Data Phase PHASE-3 / Status Phase Endpoint Information U2DP Bi-directional Endpoints Related Documents...10 SMSC AN 9.15 Page 3 Rev. 02/14/2002

4 1 ARCHITECTURE 1.1 Description The U2DP software system consists of a high level C language programming interface, dynamic link library, device driver, INF, header files, and sample code. The purpose of this document is to describe the IOCTL interface to the U2DP Window s based driver, and the transport definition between the driver layer and the U2DP firmware. It is intended to provide details about the low-level transport mechanisms without disclosing proprietary technology incorporate in the library or application-programming interface. The U2DP embedded generic data pump software provides customers with the ability to quickly prototype USB devices, utilizing Standard Microsystems USB peripheral controllers. The combination of the customer s device and the application geared U2DP software constitutes a complete system, which can be delivered to the prospective customer. U2DP offers API extensibility, robustness, performance, portability, and an intuitive interface that provides the SMSC customer with the most complete solution for fast application specific prototyping. The host side architecture consists of a configuration utility (DpConfig), which communicates with the smusb.dll, which in turn sends formatted IOCTL s to the U2DP driver on the host system. The architecture is laid out as follows: DpConfig User Application SMUSB.DLL SMSCDP2K.sys O/S Specific USB Driver Stack U2DP Firmware Customers Device FIGURE 1 - ARCHITECTURAL DIAGRAM HOST SIDE SMSC AN 9.15 Page 4 Rev. 02/14/2002

5 2 USER MODE IOCTL INTERFACE This section describes the interface for contacting the U2DP driver from a user-mode DLL or application. 2.1 IO Control Codes (IOCTL) The following table is a quick-reference to the functions provided by the SMSCDP2K or equivalently named driver. A detailed description of each function and its usage follows the table. IOCTL_USB_DATAPUMP_GETVIDPID IOCTL_USB_DATAPUMP_SETTIMEOUT IOCTL_USB_DATAPUMP_WRITE IOCTL_USB_DATAPUMP_READ IOCTL_USB_DATAPUMP_READ Input Format: USB_DATAPUMP_RW structure. The structure contains information about what data to read from the USB device. Output Format: USB_DATAPUMP_RW structure. The output structure is the same structure as passed in, however the buffer will contain data read from the device and the actual length of the data read will be in the length field. Input Structure: typedef struct _USB_DATAPUMP_RW { uint32 memtype; uint32 address; uint32 length; uint32 flags; uint32 bufferlength; uint32 data; // one of the following memory type codes // 0x = read from data memory // 0x = read from idata memory // 0x = read from code space // 0x = read from xdata memory // 0x = read from ISA I/O memory // 0x = read from ISA memory // address to read from // length of data to read / returned length of read // special flags // 0x = no auto increment // 0x = auto increment the address (0,1,2,3) // effectively reading bytes from address+0,1,2,3 // number of bytes following this 32-bit value // first 32 bits of a variable-length buffer above } USB_DATAPUMP_RW, *PUSB_DATAPUMP_RW ; Purpose: Tell the driver to issue a read command to the USB device. This command can read from one to 32bit-length of data from the device. Short transfers and errors will terminate the transaction abruptly, and the effective count of what was actually transferred will be reflected in the length field. SMSC AN 9.15 Page 5 Rev. 02/14/2002

6 2.1.2 IOCTL_USB_DATAPUMP_WRITE Input Format: USB_DATAPUMP_RW structure. The structure contains information about what data to write to the USB device. Output Format: USB_DATAPUMP_RW structure. The output structure is the same structure as passed in, however the structure will have an updated actual length of the data written in the length field. Input Structure: typedef struct _USB_DATAPUMP_RW { uint32 memtype; uint32 address; uint32 length; uint32 flags; uint32 bufferlength; uint32 data; // one of the following memory type codes // 0x = read from data memory // 0x = read from idata memory // 0x = read from code space // 0x = read from xdata memory // 0x = read from ISA I/O memory // 0x = read from ISA memory // address to write to // length of data to write / returned length of written // special flags // 0x = no auto increment (write to same) // 0x = auto increment the address (0,1,2,3) // Effectively writing bytes from address+0,1,2,3 // number of bytes following this 32-bit value // first 32 bits of a variable-length buffer above } USB_DATAPUMP_RW, *PUSB_DATAPUMP_RW ; Purpose: Tell the driver to issue a write command to the USB device. This command can read from one to 32bit-length of data from the device. Errors will terminate the transaction abruptly, and the effective count of what was actually transferred will be reflected in the length field IOCTL_USB_DATAPUMP_GETVIDPID Input Format: A buffer with a minimum length of 24 bytes. This buffer does not have to be pre-formatted. Output Format: A NULL terminated string containing the VID/PID of the given USB device, with the instance number of the device as three decimal digits appended as the last three readable characters. The caller must provide the buffer and buffer length information on the call to DeviceIoControl. OutString[23] = 0x0 Structures: None Purpose: Retrieve VID/PID information about the given USB device. SMSC AN 9.15 Page 6 Rev. 02/14/2002

7 2.1.4 IOCTL_USB_DATAPUMP_SETTIMEOUT Input Format: A pointer to 32-bits of data representing a timeout value in seconds. Output Format: None Structures: None Purpose: Set the default IRP / USB request timeout for each transaction. This timeout is in seconds, and represents the timeout on each individual phase of the CBW, DATA, and STATUS. SMSC AN 9.15 Page 7 Rev. 02/14/2002

8 3 TRANSPORT DEFINITION / DRIVER TO FIRMWARE 3.1 Description The U2DP driver receives the IOCTL command from the application level and processes it in asynchronous stages. These stages mimic the USB specification for Mass Storage Class in many ways. There are differences in the way U2DP transports its requests to the firmware code apart from the Mass Storage Class specification. You can find this specification and all of the USB Mass Storage Class specifications at PHASE-1 / Transmission of CBW The first phase of any read or write transaction always involves creating and sending a CBW or command-blockwrapper to the device. The format of this CBW is described below Command Phase - Example CBW - #pragma pack(1) 17 bytes wcbwsignature = 0xA5 // CBW Signature = 0x5A // bcbwtag = 0x00 // continuously incrementing CBW tag value dwcbwdatatransferlength = 0x00 // example 64 byte transfer LSB and MSB = 0x40 // bmcbwflags = 0x80 // CBW_FLAGS_DATA_IN = 0x80, // CBW_FLAGS_DATA_OUT = 0x00 bcbwcblength = 0x08 // length of valid CB data below 8 bytes COMMAND BLOCK SECTION OF CBW CBWCB[0] = 0x01 // auto increment flag // 0x01 = Read auto-increment enabled // 0x02 = Read auto-increment disabled // 0x03 = Write auto-increment enabled // 0x04 = Write auto-increment disabled CBWCB[1] = 0x01 // memory type flag // 0x00 = DATA SPACE // 0x01 = IDATA SPACE // 0x02 = CODE SPACE // 0x03 = XDATA SPACE // 0x04 = ISA IO MEMORY SPACE // 0x05 = ISA MEMORY SPACE CBWCB[2] = 0x50 // MSB of address 0x5000 CBWCB[3] = 0x00 // LSB of address 0x5000 CBWCB[4] = 0x78 // transfer length of 0x CBWCB[5] = 0x56 CBWCB[6] = 0x34 CBWCB[7] = 0x12 SMSC AN 9.15 Page 8 Rev. 02/14/2002

9 3.3 PHASE-2 / Data Phase During this phase, the data is either read or written depending on the i/o transaction. If you are sending 64 bytes, then transmit 64 bytes of data exactly. If you are reading 94 bytes, then read 94 bytes exactly. On reads that are terminated by a short transfer, the length field of the IOCTL structure is updated to reflect the actual amount read. 3.4 PHASE-3 / Status Phase This phase constitutes the status sent by the firmware reflecting any partial bytes counts or errors during the I/O transaction. The status phase immediately follows the data phase. If the bulk pipe is stalled due to an illegal request, the stall shall be cleared and the status retrieved. The format of this CSW (command status wrapper) is described below. The CSW is eight bytes long CSW - Status Phase - #pragma pack(1) 8 bytes wcswsignature = 0x5a // signature of our CSW = 0xa5 // signature of our CSW bcswtag = 0x00 // tag of CBW that was sent // For Data-Out, the device shall report the difference // between the amount of data expected as stated in the // dwcbwdatatransferlength, and the actual amount of // data processed by the device. dwcswdataresidue = 0x40 // For Data-In, the device shall report the difference = 0x00 // between the amount of data expected as stated in the = 0x00 // dwcbwdatatransferlength and the actual amount of = 0x00 // relevant data sent by the device. This value shall // never exceed the value of dwcbwdatatransferlength bcswstatus = 0x00 // Indicates success or failure of the command. // The device shall set this byte to zero if // the command completed successfully. A non-zero // value shall indicate a failure during // command execution. SMSC AN 9.15 Page 9 Rev. 02/14/2002

10 4 ENDPOINT INFORMATION 4.1 U2DP Bi-directional Endpoints U2DP uses a bulk-only protocol with a single, bi-directional endpoint. ENDPOINT#2 is used for transmitting the CBW, reading and/or writing during the data phase, and receiving the CSW during the status phase. U2DP uses a single endpoint for its transactions to maintain forward compatibility with other SMSC parts. Refer to the U2DP Firmware Developer Kit documentation for more information. 4.2 Related Documents U2DP Firmware Developers Guide / Firmware Developers Kit U2DP Tutorial SMSC AN 9.15 Page 10 Rev. 02/14/2002