9.3.2 Software: Firmware, USB Class Specific Code, and Application Code
The embedded software flow for the USB applications vary based on the USB OTG controller role as: Host/Device. The following sections describe the embedded software flow for both the USB Device mode and the USB Host mode.
USB Device mode: As per the device mode functionality, Microchip recommends that the USB Protocol descriptors are required to be created in the low level drivers. These descriptors are sent to the USB host which the SmartFusion 2 is connected to at the time of the USB protocol enumeration processes.
- SmartFusion 2 USB OTG controller is used in USB Device mode with the USB standard class like mass storage, human interface device (HID), communications device, and so on
- And have implemented the class driver application
If the SmartFusion 2 USB OTG controller is used as a vendor-specific application with a vendor-specific-class-driver and an application code, then Microchip recommends implementing the USB host class drivers for the USB host (for example, PC) that SmartFusion 2 communicates through the USB protocol.
The firmware catalog in the Libero SoC design software, as shown in the following figure, has the reference implementations for the class drivers and application code for the USB standard mass storage, HID, and the communications device. Microchip recommends to refer these drivers to implement the USB device application as per the requirements.
For more implementation details on the USB Protocol for the USB Device mode, see the USB 2.0 specifications.
Microchip provides the device drivers for the USB OTG controller for SmartFusion 2 and recommends using these drivers for the application development. The USB OTG drivers are implemented in two layers: USB logical driver layer (LDL) and USB core interface layer (CIL). CIL layer is the interface between the MSS USB OTG HW core and LDL.
The following table lists the APIs available in the USB firmware drivers and the description of CIL.
| API | Description |
|---|---|
| MSS_USB_core_get_configdata() | Returns the hardware (HW) configuration of the MSS USB core. This configuration cannot be changed. |
| MSS_USB_core_cep_flush_fifo() | Flushes the content of the Control EP FIFO. |
| MSS_USB_core_tx_ep_flush_fifo() | Flushes the content of transmit EP FIFO. |
| MSS_USB_core_rx_ep_flush_fifo() | Flushes the content of receive EP FIFO. |
| MSS_USB_core_enable_irq() | Enables USB IRQ. IRQ is selected by the parameter value provided with this function. |
| MSS_USB_core_disable_irq() | Disables USB IRQ. IRQ is selected by the parameter value provided with this function. |
| MSS_USB_core_ep_is_txfifo_notempty() | Indicates that there is at least one byte present in the Transmit endpoint FIFO |
| Specific to Device mode core interface layer APIs | |
| MSS_USB_core_get_device_info() | Returns the configuration of the MSS USB core. This configuration cannot be changed. |
| MSS_USB_core_device_set_address() | Sets the address of the MSS USB in Device mode. This value generally is assigned by the USB host to identify the device. |
| MSS_USB_core_device_get_address() | Returns the address set for the MSS USB in the Device mode. This value generally is assigned by the USB host to identify the device. |
| MSS_USB_core_device_force_resume() | Forces the MSS USB core to exit Suspend mode and generate resume signaling when operating in Device mode. |
| MSS_USB_core_device_set_isoupdate() | Forces ISO endpoint from the time data is deemed ready to wait for an SOF token before IN token is received. If IN token is received before an SOF token, then a zero length data packet will be sent. |
| MSS_USB_core_device_clr_isoupdate() | Configures the ISO EP so that, once the data is deemed ready, ISO endpoint will not wait for SOF token to arrive before IN token. Data will be transmitted on the next received IN token. |
| API | Description |
|---|---|
| MSS_USB_device_set_desc_cb_handler() | Provides the call-back functions for USB descriptors to this driver. |
| MSS_USB_device_set_class_cb_handler() | Provides the call-back functions for USB class implementation to this driver. |
| MSS_USB_device_init() | Initializes the MSS USB to operate in Device mode at desired USB speed. |
| MSS_USB_device_cep_configure() | Configures the Control EP. Parameters for Control EP such as max_pkt_size, FIFO address, and FIFO size in the MSS core are fixed. |
| MSS_USB_device_cep_read_prepare() | Prepares the Control EP for receiving control transfer packet. |
| MSS_USB_device_cep_write() | Transmits data on Control EP. |
| MSS_USB_device_cep_error() | Stalls the CEP when there is a error in data exchange or when the USB request is not supported. |
| MSS_USB_device_cep_clr_error() | Clears the stall condition on previously stalled control endpoint. |
| MSS_USB_device_tx_ep_configure() | Configures the transmit EP (USB IN Transfers) as per the provided parameters. |
| MSS_USB_device_rx_ep_configure() | Configures the receive EP (USB OUT Transfers) as per the provided parameters. |
| MSS_USB_device_rx_ep_read_prepare() | Prepares receive EP for receiving data packets. (USB OUT Transfers). |
| MSS_USB_device_tx_ep_write() | Transmits data on transmit endpoint (USB IN Transfers). |
| MSS_USB_device_tx_ep_error() | Stalls transmit endpoint when there is error in data exchange. |
| MSS_USB_device_rx_ep_error() | Stalls receive endpoint when there is error in data exchange. |
| MSS_USB_device_tx_ep_clr_error() | Clears the stall condition on previously stalled transmit endpoint. |
| MSS_USB_device_rx_ep_clr_error() | Clears the stall condition on previously stalled receive endpoint. |
The USB OTG controller device driver framework is made flexible to the application/class specific driver implementations by providing the callback functions. These call back functions are to be implemented by the class driver which will have class specific commands and responses.
The following table shows the call back function prototype and refer to the example projects provided to know how to use these call back functions.
| Callback API | Description |
|---|---|
| uint8_t (*usb_class_init) (uint8_t cfgidx); | This function is called when USB device receives SET_CONFIGURATION request from the USB host with a non-zero cfgidx number. The parameter cfgidx indicates the configuration number that should be set by the USB device. |
| uint8_t (*usb_class_deinit) (uint8_t cfgidx); | This function is called when the USB device receives SET_CONFIGURATION request from the USB host with a cfgidx = 0. The parameter cfgidx indicates the configuration number that should be set by the USB device. USB device goes into the MSS_USB_ADDRESS_STATE on receiving this command. |
| uint8_t* (*usb_class_get_descriptor) (uint8_t recipient, uint8_t type, uint32_t* length); | This function is called when USB device receives GET_DESCRIPTOR request from USB host requesting a class specific descriptor (configuration, class, interface, endpoint, OTG, vendor descriptors). The parameter recipient indicates the intended recipient by the USB host (endpoint, interface or device). The parameter type indicates the type of descriptor requested. |
| uint8_t (*usb_class_process_requests) (uint8_t** buf_p, uint8_t request, uint32_t* length, uint8_t* data_buf_p, uint32_t data_len); | This function is called when USB device receives class specific request from USB host. The parameter request indicates the class specific request that need to be processed. The function should return a pointer to the data requested structure in the return parameter buf_p and length of the buffer in the return parameter length. If the host provides data along with the request to be processed, a pointer to this data will be passed in the parameter data_buf_p, and the size of the buffer will be passed in the parameter data_len. |
| uint8_t (*usb_class_datain) (mss_usb_ep_num_t num, uint8_t status); | This function is called when provided data is transferred on previously configured transmit endpoint. The parameter num indicates the endpoint on which data is received. The parameter status indicates error status of the transmit transaction. A non-zero status value indicates that there was error in last receive transaction. |
| uint8_t (*usb_class_dataout) (mss_usb_ep_num_t num, uint8_t status, uint32_t rx_count); | This function is called when data is received on previously configured receive endpoint. The parameter num indicates the endpoint on which data is received. The parameter status indicates error status of the receive transaction. A non-zero status value indicates that there was error in last receive transaction. The rx_count parameter indicates the number of bytes received in the last receive transaction. |
| uint8_t (*usb_class_cep_datain) (uint8_t status); | This function is called when data packet is transmitted on previously configured control endpoint. The parameter status indicates error status of the transmit transaction. A non-zero status value indicates that there was error in last transmit transaction. |
| uint8_t (*usb_class_cep_dataout) (uint8_t status); | This function is called when data packet is received on previously configured control endpoint. The parameter status indicates error status of the receive transaction. A non-zero status value indicates that there was error in last receive transaction. |
| uint8_t *(*usb_device_descriptor) (uint32_t* length); | This function is called when USB device receives the GET_DESCRIPTOR command requesting device descriptor from USB host. This function should return a pointer to the device descriptor and provide the length of the descriptor in the return parameter. |
| uint8_t *(*usb_device_qual_descriptor) (mss_usb_device_speed_t speed, uint32_t* length); | This function is called when USB device receives the GET_DESCRIPTOR command requesting device qualifier descriptor from USB host. This function should return a pointer to the device qualifier descriptor and provide the length of the descriptor in the return parameter. |
| uint8_t *(*usb_string_descriptor) (uint8_t index, uint32_t* length); | This function is called when USB device receives the GET_DESCRIPTOR command requesting specific string descriptor from USB host. Requested string descriptor number is provided in parameter index. This function should return a pointer to the requested string descriptor and provide the length of the descriptor in the return parameter length. |
For more information on the API detailed description and parameters to the APIs, see the SmartFusion 2 MSS USB Device Core Driver’s User Guide.