1. USB
Copyright © 2004, 2005 Cypress Semiconductor Inc. All Rights Reserved.
USB Device Interface Driver
Support for Interrupt and Control Transfer Types
Setup Wizard for easy and accurate descriptor generation
Runtime support for descriptor set selection
Optional USB String Descriptors
Optional HID Class support
The USB Device User Module provides a USB Chapter 9 compliant device framework. The user module provides a low level driver for the control endpoint that decodes and dispacthes requests from the USB Host. The user module supports the HID Class. USB descriptors can be configured with the USB Setup Wizard.
The USB Device User Module support USB 2.0 Low Speed operation on the enCoRe II device family.
The USB Device User Module doe not use the PSoC Designer User Module Parameter Grid Display for personalization. Instead, it uses form driven USB Setup Wizard to define the USB descriptors for the application. From the descriptors, the Wizard personalizes the User Module.
The Application Programming Interface routines in this section allow programmatic control of the USB User Module. The following sections describe descriptor generation and integration intolist the basic and device specific API functions. It is assumed that the developer has a basic understanding of the USB protocol and is familiar with the USB 2.0 specification, especially Chapter 9, USB Device Framework.
In the following API descriptions, parameter references for bDevice, bInterface, and bEP refer to the device index, interface index and endpoint number. The values are derived implicitly from the USB Setup Wizard.
bDevice ranges from 0 to the number of device descriptors defined in the USB Setup Wizard and are positionally dependent to the order in the USB Setup Wizard (bDevice = 0 is the top entry, bDevice = 1 for the second entry and so on).
bInterface ranges from 0 to the number of interfaces defined for a configuration and is positionally dependent to the order in the USB Setup Wizard.
bEP is the endpoint number specified in the Endpoint Descriptor.
Note The API routines for the USB user modules are not reentrant. Because they depend on internal global variables in RAM, executing these routines from an interrupt is not supported by the API support supplied with this user module. If this is a requirement for a design, contact the local Cypress Field Application Engineer.
Description:
Performs all required initialization for USB Device User Module.
C Prototype:
Assembly:
Parameters:
Register A contains the device number from the desired Device Descriptor set that was entered with the USB Setup Wizard.
Return Value:
None
Side Effects:
The A and X registers may be altered by this function.
Description:
Performs all necessary shutdown task required for the USB User Module.
C Prototype:
Assembly:
Parameters:
None
Return Value:
None
Side Effects:
The A and X registers may be altered by this function.
Description:
Checks for USB Bus Activity.
C Prototype:
Assembly:
Parameters:
None
Return Value:
Returns 1 if the USB was active since the last check, otherwise returns 0.
Side Effects:
The A and X registers may be altered by this function.
Description:
C Prototype:
Assembly:
Parameters:
None
Return Value:
Returns the currently assigned configuration. Returns 0 if the device is not configured.
Side Effects:
The A and X registers may be altered by this function.
Description:
Gets the Endpoint state for the specified endpoint. The endpoint can have one of three states, two of the states mean different things for IN and OUT endpoints. The table below outlines the possible states and their meaning for IN and OUT endpoints.
C Prototype:
Assembly:
Parameters:
Register A contains the endpoint number
Return Value:
Returns the current state of the specified USB endpoint.
Side Effects:
The A and X registers may be altered by this function.
Description:
This functions returns the value of the endpoint count register. The Serial Interface Engine (SIE) includes two bytes of checksum data in the count. This function subtracts two from the count before returning the value. This function should only be called for OUT endpoints, after a call to USB_bGetEPState returns EVENT_PENDING.
C Prototype:
Assembly:
Parameters:
None
Return Value:
Returns 1 if the USB host has enabled REMOTE WAKEUP, otherwise returns 0.
Side Effects:
The A and X registers may be altered by this function.
Description:
This functions returns the value of the endpoint count register. The Serial Interface Enginer (SIE) includes two bytes of checksum data in the count. This function subtracts two from the count before returning the value. This function should only be called for OUT endpoints, after a call to USB_GetEPState returns EVENT_PENDING.
C Prototype:
Assembly:
Parameters:
Register A contains the endpoint number
Return Value:
Returns the current byte count from the specified USB endpoint.
Side Effects:
The A and X registers may be altered by this function.
Description:
Loads and enables the specified USB endpoint for an IN transfer.
C Prototype:
Assembly:
Parameters:
Register A contains the address of the RAM buffer containing the IN data
Return Value:
None
Side Effects:
The A and X registers may be altered by this function.
Description:
Enables the specified USB OUT endpoint. This function should not be called for IN endpoints.
C Prototype:
Assembly:
Parameters:
Register A contains the endpoint number
Return Value:
None
Side Effects:
The A and X registers may be altered by this function.
Description:
Disables the specified USB OUT endpoint. This function should not be called for IN endpoints.
C Prototype:
Assembly:
Parameters:
Register A contains the endpoint number
Return Value:
None
Side Effects:
The A and X registers may be altered by this function.
Description:
Forces a J, K, or SE0 state on the D+/D-. Used for signaling remote wakeup to the USB host.
C Prototype:
Assembly:
Parameters:
Register A contains one of the following constants:.
Return Value:
None
Side Effects:
The A and X registers may be altered by this function.
Description:
Puts the USB Transceiver into power-down mode, while maintaining the USB address assigned by the USB host. To restore the USB Transceiver to normal operation, the USB_Resume function should be called.
C Prototype:
Assembly:
Parameters:
None
Return Value:
None
Side Effects:
The A and X registers may be altered by this function.
Description:
Puts the USB Transceiver into normal operation, following a call to USB_Suspend. It retains the USB address that had been assigned by the USB host.
C Prototype:
Assembly:
Parameters:
None
Return Value:
None
Side Effects:
The A and X registers may be altered by this function.
Description:
Updates the HID Report Idle timer and returns the expiry status. Reloads the timer if it expires.
C Prototype:
Assembly:
Parameters:
Register A contains the interface number
Return Value:
Register A contains:.
Side Effects:
The A and X registers may be altered by this function.
Description:
Returns the protocol value for the selected interface
C Prototype:
Assembly:
Parameters:
bInterface contains the desired interface number
Return Value:
Register A contains the protocol value
Side Effects:
The A and X registers may be altered by this function.
Sample code can be found in the PSoC Designer Examples directory.
The following section describes the requests supported by the USB User Module. If a request is not supported the USB User Module normally responds with a STALL, indicating a Request Error.
This section details all of the USB descriptors provided by the USB User Module. The descriptions include the descriptor format and how User Module parameters map into the descriptor data.
The Setup Wizard is a tool provided by Cypress to assist engineers in the designing of USB devices. The Setup Wizard displays the Device Descriptor tree; when expanded the following folders that are part of the standard USB descriptor definitions appear:
Device Attributes
Configuration Descriptor
Interface Descriptor
HID Class Descriptor
Endpoint Descriptor
String/LANGID
Descriptor - HID
To access the Setup Wizard, right click over the USB Icon in the device editor and click the "USB Setup Wizard..." menu item.
When the Device Descriptor tree is fully expanded, all the Setup Wizard options can be seen. The left side displays the name of the Descriptor, the center displays the data, and the left displays the operation that may be performed for a particular Descriptor. In some instances, a Descriptor has a pull-down menu that presents options available for it.
The Setup Wizard window may be described as a table that presents three major areas for programming. The first area is the Descriptor USB User Module, the second is the String/LANGID, and the third is the Descriptor HID Report. Two buttons below the table may be used to perform a selected command.
The first section presents the Descriptor USB User Module -- this will be subsequently describe in greater details. The second section presents the String/LANGID; when a string ID is required, this area is used for input of that string. To add a string for a USB device, click on the Add String operation. The software adds a row and prompts you to "Edit your string here". Enter the new string then click the Save/Generate Descriptors button. Once the string is saved, it is available for use in the Descriptor USB User Module from the pull-down menus. If you close the Wizard window without saving, the string will be lost and not available for use.
The third area presents the Descriptor HID Report Root. From here you can request an HID Report for the device selected.
The first column displays folders that may be expanded and collapsed. For the purpose of this discussion, the tree must be fully expanded so that all options are visible. The Setup Wizard permits the entering of data into the middle Data column; if there is a pull-down menu, it can be used to select a different option. If there is no pull-down menu, but there is "data", use the cursor to highlight and select the "data", then over-write that data with another value or text-option. All the values entered must meet the USB 2.0 Chapter 9 Specifications.
The first folder that is displayed at the top is the USB User Module Descriptor Root. It has the user module name in the Data column (this is the user-module name given to it by the software; right-clicking on the user module presents "Rename" as one of the options). This user module is the one that was placed in the Interconnect View. The Add Device operation on the right-hand column adds another USB device complete with all the different fields required for describing it. The new USB device will be listed at the bottom after the Endpoint Descriptor. Click the Save/Generate Descriptors button. If you do not save the newly added device, it will not be available for use.
Device Descriptor has DEVICE_NUMBER as the Data; it may be Removed or a Configuration may be added. All the information about a particular USB device may be entered by over-writing the existing data or by using a pull-down menu.
When the input of data is complete, either by using the pull-down menus or by filling in alpha-numeric text in the appropriate spots, select the Save/Generate Descriptors button; the data that will define your design can only be made permanent by the use of this button.
The USB User Module support USB Suspend, Resume, and Remote Wakeup. Since these features must be tightly coupled into the user application, the USB User Module provides a set of API Functions.
The USB_bCheckActivity API function provides a means to check if any USB Bus activity has occurred. The application uses the function to determine if the conditions to enter USB Suspend have been met.
Once the conditions to enter USB Suspend have been met, the application should take appropriate steps to reduce current consumption to meet the suspend current requirements. To put the USB SIE and Transceiver into power-down mode, the application calls the USB_Suspend API function. This function disables the USB block, but maintains the current USB address (in the USBCR register). The device can use the Sleep feature of the enCoRe II to reduce current consumption.
While the device is suspended, it should periodically check to determine if the conditions to leave the suspended state have been met. One way check resume conditions is to use the Sleep Timer to periodically wake the device. If the resume conditions have been met, the application calls the USB_Resume API function. This function enables the USB SIE and Transceiver, bringing them out of power-down mode. It does not change the USB address field of the USBCR register, thus maintaining the USB address previously assigned by the host.
USB Remote Wakeup
If the device supports remote wakeup, the application can determine if the host has enabled remote wakeup with the USB_bRWUEnabled API function. When the device is suspended and it determines the conditions to initiate a remote wakeup have been met, the application can use the USB_Force API function to force the appropriate J and K states onto the USB Bus, thus signaling a remote wakeup.
The USB User Module supports Vendor Specific Requests (VSR) by providing a SETUP request dispatcher, exposing the control endpoint initialization entry points for Control Read, Control Write and No Data control transfers and providing transfer completion notification. The USB User Module Endpoint 0 Interrupt Service Routine (ISR) transfers control to a handler provided by the application. The handler initializes specific user module data structures and transfers control back to the Endpoint 0 ISR. The user module handles the subsequent data and status stages of the transfer without any involvement of the user application. Upon completion of the transfer, the user module updates a completion status block. The status block can be monitored by the application to determine it the VSR has completed.
All control transfers, including VSRs, have a SETUP stage, an optional data stage, and a status stage. The SETUP stage is unique for each request. During the SETUP stage, the handler must prepare the application to receive data for control writes and prepares data for transmission to the host for control reads. For no data control transfers, the handler may extract information from the SETUP packet itself.
The Endpoint 0 ISR processes the data and status stages exactly the same way for all requests. During the data stage, the ISR copies data to or from the control endpoint buffer (registers EP0DATA0-EP0DATA7) depending upon the direction of the transaction.
During the status stage, the Endpoint 0 ISR updates the completion status block. The ISR detects and reports premature completion.
Depending on the application requirements, the Endpoint 0 ISR can dispatch up to eight types of VSRs based on the bmRequestType field of the SETUP. Refer to section 9.3 of the USB 2.0 specification for a discussion of bmRequestType. The application must provide an assembly language dispatch routine
and expose it to by resetting the Enable Flag to 1 in the custom code block of the USB.inc file.
At a minimum, the dispatch routine must return control back to the Endpoint ISR by a LJMP to one of the Endpoint 0 ISR Return Points listed in the following table. The dispatch routine may destroy the A and X registers, but the Stack Pointer (SP) and any other relevant context must be restored prior to returning control to the ISR.
The status completion block contains two data items, a one byte completion status code and a two byte transfer length. The "main" application can monitor the completion status to determine how to proceed. Completion status codes are found in the following table.
The transfer length is the actual number of data bytes tranfered.