fx2usb.h

The fx2usb.h header contains USB support code for the Cypress FX2 series. When using this header, the fx2 and fx2usb libraries must be linked in.

Callback resolution

This header defines a number of callback functions, which requests the linker to locate a implementation for every of them. If you provide a callback explicitly, this callback will be used; if you do not, the linker will use the default one from the fx2usb library. Not all callbacks have default implementations.

Reference

Defines

SETUP_EP0_IN_DESC(addr)

Configure EP0 for an IN transfer from RAM of an USB descriptor of the following types:

Device
Device Qualifier
Configuration
Other Speed Configuration
String

Note that addr must be word-aligned.

SETUP_EP0_IN_DATA(addr, length): Configure EP0 for an IN transfer from RAM of data of arbitrary length. Note that addr must be word-aligned.

SETUP_EP0_BUF(length)

This call is deprecated.

Old documentation said: Configure EP0 for an IN or OUT transfer from or to EP0BUF. For an OUT transfer, specify length as 0.

However using SETUP_EP0_BUF(0) for OUT transfers will expose a race condition when the host is too eager to send more control transfers.

For IN control transfers, please use SETUP_EP0_IN_BUF(length) instead.

For OUT control transfers, please use one or more SETUP_EP0_OUT_BUF(), followed by a single ACK_EP0() call, but only after all data has been processed from EP0BUF.

If one desires to use the deprecated SETUP_EP0_BUF, then it can be re-enabled with: CFLAGS=-DSETUP_EP0_BUF_is_deprecated_use_SETUP_EP0_IN_BUF_or_SETUP_EP0_OUT_BUF_instead=1

SETUP_EP0_IN_BUF(length): Configure EP0 for an IN transfer from EP0BUF.

SETUP_EP0_OUT_BUF()

Configure EP0 for an OUT transfer from EP0BUF.

For OUT transfers please use one or more calls to SETUP_EP0_OUT_BUF() followed by a single call to ACK_EP0(). Do not call ACK_EP0() before processing all pending data in EP0BUF

ACK_EP0(): Acknowledge an EP0 SETUP or OUT transfer.

STALL_EP0(): Indicate an error in response to a EP0 transfer.

Typedefs

typedef const char *const usb_ascii_string_c

typedef const struct usb_configuration usb_configuration_c

typedef const struct usb_configuration *const usb_configuration_set_c

typedef const struct usb_descriptor_set usb_descriptor_set_c

Functions

void usb_init(bool disconnect)

Initialize the firmware USB stack. This performs the following:

enables USB interrupts handled by the support code,
takes EP0 under software control,
disconnects (if requested) and connects (if necessary).

volatile uint8_t *EPnCS_for_n(uint8_t n): Return a EPnCS register for given USB endpoint index, or 0 if no such endpoint exists.

void usb_serve_descriptor(usb_descriptor_set_c *set, enum usb_descriptor type, uint8_t index): Helper function for returning descriptors from a set of C structure definitions. This function relaxes all hardware restrictions on descriptor layout by copying the requested descriptor(s) into the scratch RAM. Sets up an EP0 IN transfer if a descriptor is found, stalls EP0 otherwise.

void usb_reset_data_toggles(usb_descriptor_set_c *set, uint8_t interface, uint8_t alt_setting): Helper function for resetting the endpoint data toggles for a subset of endpoints defined by the configuration value or interface number and alternate setting, which is necessary when processing a Set Configuration or Set Interface request. This function resets the endpoint toggles for the configuration value usb_config_value, and (if interface == 0xff && alt_setting == 0xff) all endpoints, or (otherwise) all endpoints assigned to interface with fields bInterfaceNumber == interface && bAlternateSetting == alt_setting.

void handle_usb_get_descriptor(enum usb_descriptor type, uint8_t index): Callback for the standard Get Descriptor request. This callback has a default implementation that returns descriptors from a global const struct usb_descriptor_set usb_descriptor_set = { ... };. See usb_serve_descriptor.

bool handle_usb_set_configuration(uint8_t config_value)

Callback for the standard Set Configuration request. This callback has a default implementation that sets usb_config_value to config_value and returns true if config_value is 0 or 1, and returns false otherwise.

The default implementation resets the data toggles using usb_reset_data_toggles and the global descriptor set; see handle_usb_get_descriptor.

void handle_usb_get_configuration(void): Callback for the standard Get Configuration request. This callback has a default implementation that sets up an EP0 IN transfer with value usb_config_value.

bool handle_usb_set_interface(uint8_t interface, uint8_t alt_setting)

Callback for the standard Set Interface request. This callback has a default implementation that returns true if alt_setting == 0, and returns false otherwise.

The default implementation resets the data toggles using usb_reset_data_toggles and the global descriptor set; see handle_usb_get_descriptor.

void handle_usb_get_interface(uint8_t interface): Callback for the standard Get Interface request. This callback has a default implementation that sets up an EP0 IN transfer with alternate setting number 0.

bool handle_usb_clear_endpoint_halt(uint8_t endpoint)

Callback for the standard Clear Feature - Endpoint - Endpoint Halt request. This callback has a default implementation that acknowledges the transfer and returns true.

The data toggle and the stall bit are reset by the interrupt handler if the handler returns true.

void handle_usb_setup(struct usb_req_setup *request): Callback for non-standard setup requests. This callback has a default implementation that stalls EP0.

Variables

bool usb_self_powered: Status variable indicating whether the device is currently self-powered. The value of this variable is returned via the standard Get Status - Device request.

bool usb_remote_wakeup: Status variable indicating whether the device is configured for remote wakeup. The value of this variable is returned via the standard Get Status - Device request.

uint8_t usb_config_value: Status variable indicating whether the device is in Address state (if the value is 0) or Configured state (the value corresponds to bConfigurationValue field of the descriptor of the selected configuration).

struct usb_configuration

#include <fx2usb.h>

An USB configuration descriptor. The USB configuration descriptor is followed by the interface, endpoint, and functional descriptors; these are laid out in the way they should be returned in response to the Get Configuration request.

Public Members