Usb_api

Macros
#define	USB_INTEP_RX_SHIFT   16
#define	USB_RX_EPSTATUS_SHIFT   16
#define	EP_OFFSET(Endpoint)   (Endpoint - 0x10)

Functions
void	USBHostSuspend (uint32_t ui32Base)
void	USBHostReset (uint32_t ui32Base, bool bStart)
void	USBHighSpeed (uint32_t ui32Base, bool bEnable)
void	USBHostResume (uint32_t ui32Base, bool bStart)
uint32_t	USBHostSpeedGet (uint32_t ui32Base)
uint32_t	USBDevSpeedGet (uint32_t ui32Base)
void	USBIntDisableControl (uint32_t ui32Base, uint32_t ui32Flags)
void	USBIntEnableControl (uint32_t ui32Base, uint32_t ui32Flags)
uint32_t	USBIntStatusControl (uint32_t ui32Base)
void	USBIntDisableEndpoint (uint32_t ui32Base, uint32_t ui32Flags)
void	USBIntEnableEndpoint (uint32_t ui32Base, uint32_t ui32Flags)
uint32_t	USBIntStatusEndpoint (uint32_t ui32Base)
void	USBIntRegister (uint32_t ui32Base, void(*pfnHandler)(void))
void	USBIntUnregister (uint32_t ui32Base)
uint32_t	USBEndpointStatus (uint32_t ui32Base, uint32_t ui32Endpoint)
void	USBHostEndpointStatusClear (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32Flags)
void	USBDevEndpointStatusClear (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32Flags)
void	USBHostEndpointDataToggle (uint32_t ui32Base, uint32_t ui32Endpoint, bool bDataToggle, uint32_t ui32Flags)
void	USBEndpointDataToggleClear (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32Flags)
void	USBHostEndpointPing (uint32_t ui32Base, uint32_t ui32Endpoint, bool bEnable)
void	USBDevEndpointStall (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32Flags)
void	USBDevEndpointStallClear (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32Flags)
void	USBDevConnect (uint32_t ui32Base)
void	USBDevDisconnect (uint32_t ui32Base)
void	USBDevAddrSet (uint32_t ui32Base, uint32_t ui32Address)
uint32_t	USBDevAddrGet (uint32_t ui32Base)
void	USBHostEndpointConfig (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32MaxPayload, uint32_t ui32NAKPollInterval, uint32_t ui32TargetEndpoint, uint32_t ui32Flags)
void	USBHostEndpointSpeed (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32Flags)
void	USBDevEndpointConfigSet (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32MaxPacketSize, uint32_t ui32Flags)
void	USBDevEndpointConfigGet (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t *pui32MaxPacketSize, uint32_t *pui32Flags)
void	USBFIFOConfigSet (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32FIFOAddress, uint32_t ui32FIFOSize, uint32_t ui32Flags)
void	USBFIFOConfigGet (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t *pui32FIFOAddress, uint32_t *pui32FIFOSize, uint32_t ui32Flags)
void	USBEndpointDMAConfigSet (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32Config)
void	USBEndpointDMAEnable (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32Flags)
void	USBEndpointDMADisable (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32Flags)
uint32_t	USBEndpointDataAvail (uint32_t ui32Base, uint32_t ui32Endpoint)
int32_t	USBEndpointDataGet (uint32_t ui32Base, uint32_t ui32Endpoint, uint8_t *pui8Data, uint32_t *pui32Size)
void	USBDevEndpointDataAck (uint32_t ui32Base, uint32_t ui32Endpoint, bool bIsLastPacket)
void	USBHostEndpointDataAck (uint32_t ui32Base, uint32_t ui32Endpoint)
int32_t	USBEndpointDataPut (uint32_t ui32Base, uint32_t ui32Endpoint, uint8_t *pui8Data, uint32_t ui32Size)
int32_t	USBEndpointDataSend (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32TransType)
void	USBFIFOFlush (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32Flags)
void	USBHostRequestIN (uint32_t ui32Base, uint32_t ui32Endpoint)
void	USBHostRequestINClear (uint32_t ui32Base, uint32_t ui32Endpoint)
void	USBHostRequestStatus (uint32_t ui32Base)
void	USBHostAddrSet (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32Addr, uint32_t ui32Flags)
uint32_t	USBHostAddrGet (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32Flags)
void	USBHostHubAddrSet (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32Addr, uint32_t ui32Flags)
uint32_t	USBHostHubAddrGet (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32Flags)
void	USBHostPwrConfig (uint32_t ui32Base, uint32_t ui32Flags)
void	USBHostPwrFaultEnable (uint32_t ui32Base)
void	USBHostPwrFaultDisable (uint32_t ui32Base)
void	USBHostPwrEnable (uint32_t ui32Base)
void	USBHostPwrDisable (uint32_t ui32Base)
uint32_t	USBFrameNumberGet (uint32_t ui32Base)
void	USBOTGSessionRequest (uint32_t ui32Base, bool bStart)
uint32_t	USBFIFOAddrGet (uint32_t ui32Base, uint32_t ui32Endpoint)
uint32_t	USBModeGet (uint32_t ui32Base)
void	USBHostMode (uint32_t ui32Base)
void	USBDevMode (uint32_t ui32Base)
void	USBOTGMode (uint32_t ui32Base)
void	USBModeConfig (uint32_t ui32Base, uint32_t ui32Mode)
void	USBPHYPowerOff (uint32_t ui32Base)
void	USBPHYPowerOn (uint32_t ui32Base)
void	USBEndpointPacketCountSet (uint32_t ui32Base, uint32_t ui32Endpoint, uint32_t ui32Count)
uint32_t	USBNumEndpointsGet (uint32_t ui32Base)
void	USBClockEnable (uint32_t ui32Base, uint32_t ui32Div, uint32_t ui32Flags)
void	USBClockDisable (uint32_t ui32Base)

Detailed Description

Introduction

The USB APIs provide a set of functions that are used to access the MSP432E4 USB device, host and/or device, or OTG controllers. The APIs are split into groups according to the functionality provided by the USB controller present in the microcontroller. The groups are the following: USBDev, USBHost, USBOTG, USBDMA, USBEndpoint, and USBFIFO. The APIs in the USBDev group are used when the USB controller is operating as a Device. The APIs in the USBHost group are used when the USB controller is operating as a Host. The USBOTG APIs are used when configuring a USB controller that supports OTG mode. With USB OTG controllers, once the mode of the USB controller is configured, the device or host APIs are used. The remainder of the APIs are used for both USB host and USB device controllers. The USBEndpoint APIs are used to configure and access the endpoints, the USBDMA APIs are used to configure and operate the DMA controller within the USB module, and the USBFIFO APIs are used to configure the size and location of the FIFOs.

General USB API Functions

The USB APIs provide all of the functions needed by an application to implement a USB device or USB host stack. The APIs abstract the IN/OUT nature of endpoints based on the type of USB controller that is in use. Any API that uses the IN/OUT terminology complies with the standard USB interpretation of these terms. For example, an OUT endpoint on a microcontroller that has only a device interface actually receives data on this endpoint, while a microcontroller that has a host interface actually transmits data on an OUT endpoint.

Another important fact to understand is that all endpoints in the USB controller, whether host or device, have two "sides" to them, allowing each endpoint to both transmit and receive data. An application can use a single endpoint for both and IN and OUT transactions. For example: In device mode, endpoint 1 can be configured to have BULK IN and BULK OUT handled by endpoint 1. It is important to note that the endpoint number used is the endpoint number reported to the host. For microcontrollers with host controllers, the application can use an endpoint to communicate with both IN and OUT endpoints of different types as well. For example: Endpoint 2 can be used to communicate with one device's interrupt IN endpoint and another device's bulk OUT endpoint at the same time. This configuration effectively gives the application one dedicated control endpoint for IN or OUT control transactions on endpoint 0 and seven IN endpoints and seven OUT endpoints.

The USB controller has a global FIFO memory space that can be allocated to endpoints. The overall size of the FIFO RAM is 2048 or 4096 bytes, depending on the MSP432E4 device used. It is important to note that the first 64 bytes of this memory are dedicated to endpoint 0 for control transactions. The remaining 1984 or 4032 bytes are configurable however the application requires. The FIFO configuration is usually set up at the beginning of the application and not modified once the USB controller is in use. The FIFO configuration uses the USBFIFOConfig() API to configure the starting address and the size of the FIFOs that are dedicated to each endpoint.

Example: FIFO Configuration

0-64 - endpoint 0 IN/OUT (64 bytes).

64-576 - endpoint 1 IN (512 bytes).

576-1088 - endpoint 1 OUT (512 bytes).

1088-1600 - endpoint 2 IN (512 bytes).

//
// FIFO for endpoint 1 IN starts at address 64 and is 512 bytes in size.
//
USBFIFOConfig(USB0_BASE, USB_EP_1, 64, USB_FIFO_SZ_512, USB_EP_DEV_IN);

//
// FIFO for endpoint 1 OUT starts at address 576 and is 512 bytes in size.
//
USBFIFOConfig(USB0_BASE, USB_EP_1, 576, USB_FIFO_SZ_512, USB_EP_DEV_OUT);

//
// FIFO for endpoint 2 IN starts at address 1088 and is 512 bytes in size.
//
USBFIFOConfig(USB0_BASE, USB_EP_2, 1088, USB_FIFO_SZ_512, USB_EP_DEV_IN);

Using USB with the uDMA Controller

On devices that do not have an integrated DMA in the USB controller, the uDMA can be used with the USB controller for either sending or receiving data with both host and device controllers. The uDMA controller cannot be used to access endpoint 0, however all other endpoints are capable of using the uDMA controller. The uDMA channel numbers for USB are defined by the following values:

• DMA_CHANNEL_USBEP1RX
• DMA_CHANNEL_USBEP1TX
• DMA_CHANNEL_USBEP2RX
• DMA_CHANNEL_USBEP2TX
• DMA_CHANNEL_USBEP3RX
• DMA_CHANNEL_USBEP3TX

For devices with more than 8 endpoints, the required endpoints must be assigned to one of the 3 DMA receive channels and 3 DMA transmit channels using the USBEndpointDMAChannel() function.

Because the uDMA controller views transfers as either transmit or receive and the USB controller operates on IN/OUT transactions, some care must be taken to use the correct uDMA channel with the correct endpoint. USB host IN and USB device OUT endpoints both use receive uDMA channels while USB host OUT and USB device IN endpoints use transmit uDMA channels.

When configuring the endpoint, there are additional DMA settings required. When calling USBDevEndpointConfigSet() for an endpoint that uses uDMA, extra flags must be added to the ulFlags parameter. These flags are one of USB_EP_DMA_MODE_0 or USB_EP_DMA_MODE_1 to control the mode of the DMA transaction, and likely USB_EP_AUTO_SET to allow the data to be transmitted automatically once a packet is ready. When using USB_EP_DMA_MODE_0, the USB controller only generates an interrupt when the full transfer is complete. As a result, the application must know the full transfer size before configuring the DMA transfer. In USB_EP_DMA_MODE_1, the USB controller generates DMA requests only when a full packet is transferred and interrupts the processor on any short packet. The short packet data remains in the USB FIFO, and the application must trigger the last transfer of data from the FIFO. The USB_EP_AUTO_SET is specified when using uDMA to prevent the need for application code to start the actual transfer of data on every full packet of data.

Example: Endpoint configuration for a device IN endpoint:

//
// Endpoint 1 is a device mode BULK IN endpoint using DMA.
//
USBDevEndpointConfigSet(USB0_BASE, USB_EP_1, 64,
                        (USB_EP_MODE_BULK | USB_EP_DEV_IN |
                         USB_EP_DMA_MODE_0 | USB_EP_AUTO_SET));

Next, the application must configure the uDMA controller for the desired DMA transfer to the FIFO. To clear out any previous settings, the application calls DMAChannelAttributeClear(). Then the application calls DMAChannelAttributeSet() for the uDMA channel that corresponds to the endpoint and specify the DMA_CONFIG_USEBURST flag.

Note

All uDMA transfers used by the USB controller must enable burst mode.

The application also provides the size of each DMA transaction, combined with the source and destination increments and the arbitration level for the uDMA controller.

Example: Configure endpoint 1 transmit channel.

//
// Set up the DMA for USB transmit.
//
DMAChannelAttributeClear(DMA_CHANNEL_USBEP1TX, DMA_CONFIG_ALL);

//
// Enable uDMA burst mode.
//
DMAChannelAttributeSet(DMA_CHANNEL_USBEP1TX, DMA_CONFIG_USEBURST);

//
// Data size is 8 bits and the source has a one byte increment.
// Destination has no increment as it is a FIFO.
//
DMAChannelControlSet(DMA_CHANNEL_USBEP1TX, DMA_DATA_SIZE_8, DMA_ADDR_INC_8,
                     DMA_ADDR_INC_NONE, DMA_ARB_64, 0);

The next step is to actually start the uDMA transfer once the data is ready to be sent. There are only two calls that the application must make to start a new transfer. For most cases, the previous uDMA configuration remains the same. The call to DMAChannelTransferSet() resets the source and destination addresses for the DMA transfer and specifies how much data to send. The call to DMAChannelEnable() actually allows the DMA controller to begin requesting data to fill the FIFO.

Example: Start the transfer of data on endpoint 1.

//
// Configure the address and size of the data to transfer.
//
DMAChannelTransferSet(DMA_CHANNEL_USBEP1TX, DMA_MODE_BASIC, pData,
                      USBFIFOAddr(USB0_BASE, USB_EP_1), 64);
//
// Start the transfer.
//
DMAChannelEnable(DMA_CHANNEL_USBEP1TX);

Because the uDMA interrupt occurs on the same interrupt vector as any other USB interrupt, the application must perform an extra check to determine the actual source of the interrupt. It is important to note that the DMA interrupt does not mean that the USB transfer is complete, but only that the data has been transferred to the USB controller's FIFO. There is also an interrupt indicating that the USB transfer is complete. However, both events must be handled in the same interrupt routine because if other code in the system holds off the USB interrupt routine, both the uDMA complete and transfer complete can occur before the USB interrupt handler is called. The USB has no status bit indicating that the interrupt was due to a DMA complete, which means that the application must remember if a DMA transaction was in progress. The example below shows the g_ulFlags global variable being used to remember that a DMA transfer was pending.

Example: Interrupt handling with uDMA.

if((g_ulFlags & EP1_DMA_IN_PEND) &&
   (DMAChannelModeGet(DMA_CHANNEL_USBEP1TX) == DMA_MODE_STOP))
{
    //
    // Handle the DMA complete case.
    //
    ...
}

//
// Get the interrupt status.
//
ulStatus = USBIntStatusEndpoint(USB0_BASE);

if(ulStatus & USB_INTEP_DEV_IN_1)
{
    //
    // Handler the transfer complete case.
    //
    ...
}

To use the USB device controller with an OUT endpoint, the application must use a receive uDMA channel. When calling USBDevEndpointConfigSet() for an endpoint that uses uDMA, the application must set extra flags in the ulFlags parameter. The USB_EP_DMA_MODE_0 and USB_EP_DMA_MODE_1 parameters control the mode of the transaction, USB_EP_AUTO_CLEAR allows the data to be received automatically without manually acknowledging that the data has been read. If the transfer size is not known, USB_EP_DMA_MODE_1 is used as it does not generate an interrupt when each packet is sent over USB and interrupts if a short packet is received. In USB_EP_DMA_MODE_1, the last short packet remains in the FIFO and must be read by software when the interrupt is received. If the full transfer size is known, USB_EP_DMA_MODE_0 can be used because it does not interrupt the processor after each packet and completes even if the last packet is a short packet. The USB_EP_AUTO_CLEAR flag is normally specified when using uDMA to allow the USB controller to transfer multiple packets without interruption of the microcontroller. The example below configures endpoint 1 as a Device mode Bulk OUT endpoint using DMA mode 1 with a max packet size of 64 bytes.

Example: Configure endpoint 1 receive channel:

//
// Endpoint 1 is a device mode BULK OUT endpoint using DMA.
//
USBDevEndpointConfigSet(USB0_BASE, USB_EP_1, 64,
                        (USB_EP_DEV_OUT | USB_EP_MODE_BULK |
                         USB_EP_DMA_MODE_1 | USB_EP_AUTO_CLEAR));

Next the application is required to configure the uDMA controller to match the desired transfer. Like the transmit case, the first call to DMAChannelAttributeClear() is made to clear any previous settings. This function is followed by a call to DMAChannelAttributeSet() with the DMA_CONFIG_USEBURST value.

Note

All uDMA transfers used by the USB controller must use burst mode.

The final call configures the read access size to 8 bits wide, the source address increment to 0, the destination address increment to 8 bits and the uDMA arbitration size to 64 bytes.

Example: Configure endpoint 1 transmit channel.

//
// Clear out any uDMA settings.
//
DMAChannelAttributeClear(DMA_CHANNEL_USBEP1RX, DMA_CONFIG_ALL);

DMAChannelAttributeSet(DMA_CHANNEL_USBEP1RX, DMA_CONFIG_USEBURST);

DMAChannelControlSet(DMA_CHANNEL_USBEP1RX, DMA_DATA_SIZE_8,
                     DMA_ADDR_INC_NONE, DMA_ADDR_INC_8, DMA_ARB_64, 0);

The next step is to actually start the uDMA transfer. Unlike the transfer side, if the application is ready, the receive side can be set up right away to wait for incoming data. Like the transmit case, these calls are the only ones required to start a new transfer, because normally, the previous uDMA configuration can remain the same.

Example: Start requesting data on endpoint 1.

//
// Configure the address and size of the data to transfer.  The transfer
// is from the USB FIFO for endpoint 0 to g_DataBufferIn.
//
DMAChannelTransferSet(DMA_CHANNEL_USBEP1RX, DMA_MODE_BASIC,
                      USBFIFOAddr(USB0_BASE, USB_EP_1), g_DataBufferIn,
                      64);

//
// Enable the uDMA channel and wait for data.
//
DMAChannelEnable(DMA_CHANNEL_USBEP1RX);

The uDMA interrupt occurs on the same interrupt vector as any other USB interrupt, which means that the application must determine what the actual source of the interrupt was. It is possible that the USB interrupt does not indicate that the USB transfer was complete. The interrupt can also be generated by a short packet, error, or even a transmit complete. As a result, the application must check both receive cases to determine if the interrupt is related to receiving data on the endpoint. Because the USB has no status bit indicating that the interrupt was due to a DMA complete, the application must remember if a DMA transaction was in progress.

Example: Interrupt handling with uDMA.

//
// Get the current interrupt status.
//
ulStatus = USBIntStatusEndpoint(USB0_BASE);

if(ulStatus & USB_INTEP_DEV_OUT_1)
{
    //
    // Handle a short packet.
    //
    ...
}
else if((g_ulFlags & EP1_DMA_OUT_PEND) &&
        (DMAChannelModeGet(DMA_CHANNEL_USBEP1RX) == DMA_MODE_STOP)
{
    //
    // Handle the DMA complete case.
    //
    ...

    //
    // Restart receive DMA if desired.
    //
    ...
}

Using the integrated USB DMA Controller

Some USB controllers include an integrated USB DMA controller for DMA access to the USB FIFOs that is used instead of the uDMA controller. The programming method for using the integrated USB DMA controller differs from that used with the uDMA controller to move USB FIFO data to and from system memory.

The integrated USB DMA controller has a basic set of functions that allows an application to determine whether this feature is available and if so, provide additional details about the USB DMA controller. An application can use the USBDMANumChannels() function to determine if the USB controller supports the integrated USB DMA controller by checking that the returned value is non-zero. Like most DMA controllers, the USB DMA controller is used to transfer data between the USB controller and system memory using a simple address and count value. While the transfer size can be specified as any number of bytes, the USB DMA controller can only perform accesses on 32-bit-aligned boundaries, so care must be taken to only specify transfer addresses in modulo-4 increments. The USB DMA controller also has a fixed number of DMA channels that can be dynamically assigned to any endpoint and can be used to either transmit or receive data. The total number of DMA channels available is determined using the USBDMANumChannels() function. The channel numbers themselves are numbered from 0 to the maximum number of channels minus one. The UDMA_CHANNEL_USBEPnRX and UDMA_CHANNEL_USBEPnTX defines for the uDMA must not be used as the channel numbers when using the integrated USB DMA controller.

Each DMA channel can be configured with various settings that assign a channel to an endpoint and configure how it is used during a DMA transfer. The DMA channel is configured using the ulConfig parameter of the USBDMAChannelConfigSet() function. To set the proper direction for the transfer, the USB_DMA_CFG_DIR_TX or USB_DMA_CFG_DIR_RX option must be added to the ulConfig parameter. The DMA burst lengths are specified in 32-bit word increments using one of the following values added to the ulConfig parameter: USB_DMA_CFG_BURST_NONE (default), USB_DMA_CFG_BURST_4, USB_DMA_CFG_BURST_8, or USB_DMA_CFG_BURST_16. The DMA mode is also used to control how the DMA controller handles interrupting the processor. USB_DMA_CFG_MODE_0 is typically used when only a single packet is being sent or received using DMA as it triggers an interrupt per packet transfered. USB_DMA_CFG_MODE_1 is used when multiple packets are being sent using DMA and triggers one completion interrupt per transfer when spanning multiple packets rather than triggering an interrupt per packet. In addition, when calling USBDevEndpointConfigSet() for an endpoint that uses DMA, extra flags must be added to the ulFlags parameter. These flags are one of USB_EP_DMA_MODE_0 or USB_EP_DMA_MODE_1 to control the mode of the DMA transaction, and likely USB_EP_AUTO_SET to allow the data to be transmitted automatically once a packet is ready. When using USB_EP_DMA_MODE_0, the USB controller only generates an interrupt when the full transfer is complete. As a result, the application must know the full transfer size before configuring the DMA transfer. In USB_EP_DMA_MODE_1, the USB controller generates DMA requests only when a full packet is transferred and interrupts the processor on any short packet. The short packet data remains in the USB FIFO, and the application must trigger the last transfer of data from the FIFO. The USB_EP_AUTO_SET is specified when using uDMA to prevent the need for application code to start the actual transfer of data on every full packet of data.

The method for configuring the USB DMA controller to perform a DMA transfer varies based on the USB mode (Host or Device), the size of the transfer, and the direction of the transfer. It is important to understand the interrupt mechanisms when dealing with the USB DMA controller. There are two types of interrupts that occur. The first is the normal endpoint interrupt that indicates a USB packet transfer has completed, and the other is a USB DMA interrupt that indicates a USB DMA transfer has completed. A USB DMA transfer complete does not indicate that the packet transmission has completed, but rather that the transfer to or from the FIFO has completed. Depending on the situation, the application may have to wait for more than one interrupt to signal the completion of the USB transaction. The next sections describe how to use the integrated USB DMA controller to complete USB transactions in the most common scenarios.

Sending a Single Packet

The first type of transfer is a single packet transfer that is less than or equal to the maximum packet size for the endpoint. In this mode, the DMA controller copies data from memory into the USB FIFO for the endpoint. In most cases, it is the responsibility of the application to then manually trigger a USB transfer when the DMA is complete using the USBEndpointDataSend() function. However, if the USB_EP_AUTO_SET value is included as an option to the USBDevEndpointConfigSet() or the USBHostEndpointConfig() function and the transfer is of exactly the maximum packet size, then it is not necessary to manually trigger a USB transfer and doing so may cause an extra null packet to be sent.

If endpoints are not dynamically allocated by the application, some of the DMA and endpoint configuration can be treated as static and executed only once during initial configuration.

Example: Endpoint configuration for USB DMA transmit

//
// Endpoint 1 uses Mode 0 and transmit.
//
USBEndpointDMAConfigSet(USB0_BASE, USB_EP_1, USB_EP_HOST_OUT |
                                             USB_EP_DMA_MODE_0);

//
// Assign endpoint 1 to DMA channel 0 using Mode 0, no bursting, for
// transmit, and enable DMA interrupts.
//
USBDMAChannelConfigSet(USB0_BASE, 0, USB_EP_1, USB_DMA_CFG_MODE_0 |
                                               USB_DMA_CFG_BURST_NONE |
                                               USB_DMA_CFG_DIR_TX |
                                               USB_DMA_CFG_INT_EN);

The following actions must be performed every time a DMA transfer is ready to be scheduled.

Example: Sending a packet using DMA on channel 0.

//
// Set the source address for the transfer to pvBuffer.
//
USBDMAChannelAddressSet(USB0_BASE, 0, pvBuffer);

//
// Set the transfer size to 44 bytes and the packet count to 0.
//
USBDMAChannelCountSet(USB0_BASE, 0, 44);
USBEndpointPacketCountSet(USB0_BASE, 0, 0)

//
// Enable the DMA transfer.
//
USBDMAChannelEnable();

Once the DMA transfer is started, the application must wait for a DMA completion interrupt. DMA completion triggers a normal USB controller interrupt, and the actual status for the DMA interrupt is returned by calling the USBDMAChannelIntStatus() function. The interrupt handler must handle all pending DMA channels because the call to USBDMAChannelIntStatus() automatically clears all pending DMA interrupts. Once the DMA status indicates complete, the last step is to schedule the USB transfer by calling the USBEndpointDataSend() function as shown below and then wait for a second endpoint interrupt that signals the completion of the USB transfer. The second interrupt must check if the transfer has completed by calling the USBIntStatusEndpoint() function to see if the interrupt was for the given endpoint.

Example: Starting a transfer on channel 0 after DMA completes.

//
// Start the USB transfer.
//
USBEndpointDataSend(USB0_BASE,USB_EP_1, USB_TRANS_OUT);

Sending Multiple Packets

The next type of transfer is a multiple packet transfer when the transfer size is greater than the maximum packet size for the endpoint. In this mode, the DMA controller copies data from memory into the USB FIFO for the endpoint in blocks that are the size of the maximum packet. If the last packet is a short packet, it is the responsibility of the application to manually start the USB transfer when the DMA transfer is complete. Because the USB_EP_AUTO_SET is used when multiple packets are being sent, it is not necessary to manually trigger the final transfer if the transfer is of exactly the maximum packet size.

If endpoints are not dynamically allocated by the application, some of the DMA and endpoint configuration can be treated as static and executed only once during initial configuration.

Example: Static endpoint configuration for DMA multiple packet transmit.

//
// Endpoint 1 uses Mode 1 and transmit and enables automatic sending
// when a full packet is sent to the FIFO.
//
USBEndpointDMAConfigSet(USB0_BASE, USB_EP_1, USB_EP_HOST_OUT |
                                             USB_EP_DMA_MODE_1 |
                                             USB_EP_AUTO_SET);

//
// Assign endpoint 1 to DMA channel 1 using Mode 1, no bursting, transmit,
// and enable DMA interrupts.
//
USBDMAChannelConfigSet(USB0_BASE, 1, USB_EP_1, USB_DMA_CFG_MODE_1 |
                                               USB_DMA_CFG_BURST_NONE |
                                               USB_DMA_CFG_DIR_TX |
                                               USB_DMA_CFG_INT_EN)

The following actions must be performed every time a DMA transfer is scheduled. If the transfer size is not an even multiple of the maximum packet size, then the USBEndpointPacketCountSet() is passed in (transfer_size/max_packet_size) + 1 otherwise the number of packets is (transfer_size/max_packet_size).

Example: Starting a DMA send multi-packet transfer on channel 1.

//
// Set the source address for the transfer to pvBuffer.
//
USBDMAChannelAddressSet(USB0_BASE, 1, pvBuffer);

//
// Set the transfer size to 1024 bytes and the packet count to 16.
// The packet count does not require a + 1 because 1024/64 leaves no
// remaining bytes to send in a final packet.
//
USBDMAChannelCountSet(USB0_BASE, 0, 1024);
USBEndpointPacketCountSet(USB0_BASE, 0, 1024/64);

//
// Enable the DMA transfer.
//
USBDMAChannelEnable();

Once the DMA transfer is started, the application must wait for a DMA completion interrupt. The DMA completion triggers a normal USB controller interrupt, and the status for the DMA interrupt is returned by calling the USBDMAChannelIntStatus(). The interrupt handler must handle all pending DMA channels because the call to USBDMAChannelIntStatus() automatically clears all pending DMA interrupts. At this point, if the transfer size is a multiple of the maximum packet size, the transfer is complete and no other action is required. If there is a short packet at the end of the transfer, then the last step is to schedule the final USB transfer by calling the USBEndpointDataSend() and then wait for a final endpoint interrupt to signal completion of the USB transfer. The transfer is complete when the application receives a final endpoint interrupt, which is returned by the USBIntStatusEndpoint() function.

Receiving a Single Packet

Receiving packets is a little more complicated than sending because in some cases you do not know when the receive request occurs or how much data is being sent when you configure the endpoint. This section handles receiving a single packet transfer that is less than or equal to the maximum packet size for an endpoint. In this mode, the DMA controller copies data from the USB endpoint FIFO to system memory. The DMA transfer of a single packet must be started when the packet is received. If the USB_EP_AUTO_CLEAR option is included in the call to USBEndpointDMAConfigSet(), then the receive is acknowledged when the DMA transfer pulls the last data from the FIFO. The DMA transfer is started when the endpoint receive interrupt indicates that data is available in the FIFO. The examples below demonstrate the steps necessary to complete a DMA transfer of a single packet.

If endpoints are not dynamically allocated by the application, some of the DMA and endpoint configuration can be treated as static and executed only once during initial configuration.

Example: Static endpoint configuration for single packet DMA receive

//
// Endpoint 2 uses Mode 0, receive, and enables automatic acknowledge
// when a full packet is read from the FIFO.
//
USBEndpointDMAConfigSet(USB0_BASE, USB_EP_2, USB_EP_HOST_IN |
                                             USB_EP_DMA_MODE_0 |
                                             USB_EP_AUTO_CLEAR);

//
// Assign endpoint 2 to DMA channel 3 using Mode 0, no bursting, receive,
// and enable DMA interrupts.
//
USBDMAChannelConfigSet(USB0_BASE, 3, USB_EP_2, USB_DMA_CFG_MODE_0 |
                                               USB_DMA_CFG_BURST_NONE |
                                               USB_DMA_CFG_DIR_RX |
                                               USB_DMA_CFG_INT_EN);
//
// Make sure that DMA is not enabled on the endpoint.  If DMA is left
// enabled, the endpoint interrupt does not occur.
//
USBEndpointDMADisable(USB0_BASE, 3, USB_EP_HOST_IN);

Once the endpoint interrupt indicates that a packet is ready for transfer, then the application takes the following steps to start the DMA transfer to receive the data from the FIFO.

Example: Starting a DMA receive transfer on channel 3.

//
// Set the destination address for the transfer to pvBuffer.
//
USBDMAChannelAddressSet(USB0_BASE, 3, pvBuffer);

//
// Set the transfer size to 48 bytes and the packet count to 0.
//
USBDMAChannelCountSet(USB0_BASE, 3, 48);
USBEndpointPacketCountSet(USB0_BASE, 3, 0)

//
// Enable the DMA transfer.
//
USBDMAChannelEnable();

Now the application must wait for a final interrupt to indicate that the DMA has completed by checking the return value from the USBDMAChannelIntStatus() function. If the endpoint was not configured with the USB_EP_AUTO_CLEAR function, then a final call to USBDevEndpointDataAck() or USBHostEndpointDataAck() is required to acknowledge the packet. The USB_EP_AUTO_CLEAR feature must not be used if the packet may need to be stalled.

Receiving a Multiple Packets

This section handles receiving multiple packets with a single DMA transfer. This method is used when the total size of the transfer is greater than the maximum packet size for the endpoint. If there is a trailing null packet or short packet, the final transfer must be manually acknowledged with a call to USBDevEndpointDataAck() or USBHostEndpointDataAck(). Unlike the single packet, this transfer can be configured before the packet is received if the size of the transfer is known beforehand. Because this type of USB DMA uses mode 1, the transfer only starts if a full packet has been received. If a short packet is unexpectedly received, the transfer does not start, but the USB endpoint interrupt is still signaled so that the transfer can be started manually if needed. This mechanism is also needed anytime the final packet is a short packet. The examples below demonstrate the steps necessary to complete a DMA transfer of multiple packets.

If endpoints are not dynamically allocated by the application, some of the DMA and endpoint configuration can be treated as static and executed only once during initial configuration.

Example: Static endpoint configuration for DMA multiple packet receive

//
// If in USB device mode.
//
if(bUSBDeviceMode)
{
    USBEndpointDMAConfigSet(USB0_BASE, USB_EP_2, USB_EP_HOST_IN |
                                                 USB_EP_DMA_MODE_1 |
                                                 USB_EP_AUTO_CLEAR);
}
else
{
    //
    // In host mode, USB_EP_AUTO_REQUEST is needed to trigger new requests.
    //
    USBEndpointDMAConfigSet(USB0_BASE, USB_EP_2, USB_EP_HOST_IN |
                                                 USB_EP_AUTO_REQUEST |
                                                 USB_EP_DMA_MODE_1 |
                                                 USB_EP_AUTO_CLEAR);
}

//
// Assign endpoint 2 to DMA channel 3 using Mode 1, no bursting, receive,
// and enable DMA interrupts.
//
USBDMAChannelConfigSet(USB0_BASE, 3, USB_EP_2, USB_DMA_CFG_MODE_1 |
                                               USB_DMA_CFG_BURST_NONE |
                                               USB_DMA_CFG_DIR_RX |
                                               USB_DMA_CFG_INT_EN)

//
// Make sure that DMA is not enabled on the endpoint.  If DMA is left
// enabled, the endpoint interrupt does not occur.
//
USBEndpointDMADisable(USB0_BASE, 3, USB_EP_HOST_IN);

When the application is ready to start the multiple packet transfer, the application starts the transfer by taking the following steps.

Example: Starting a multiple packet DMA receive transfer on channel 3.

//
// Set the destination address for the transfer to pvBuffer.
//
USBDMAChannelAddressSet(USB0_BASE, 3, pvBuffer);

//
// Set the transfer size to 512 bytes and the packet count to 8.
//
USBDMAChannelCountSet(USB0_BASE, 3, 512);
USBEndpointPacketCountSet(USB0_BASE, 3, 512/64);

//
// Enable the DMA transfer.
//
USBEndpointDMAEnable(USB0_BASE, USB_EP_2, USB_EP_HOST_IN);
USBDMAChannelEnable(USB0_BASE, 3);

Now the application waits for the interrupt to indicate that either the DMA has completed or that a short packet has been received. If USBDMAChannelIntStatus() indicates that the transfer is complete, then there are no more steps to take. If there is no pending DMA interrupt, then a short packet was received, and the application can either manually read the data from the FIFO or switch to the steps above to trigger a single packet transfer to complete the USB transfer.

The remainder of the USB functions are not directly needed for USB DMA transfers but may be needed for other application-specific reasons. The first two of these remaining functions are USBDMAChannelIntEnable() and USBDMAChannelIntDisable(), which are a pair of functions to enable and disable a specific DMA channel from generating interrupts. The USBDMAChannelEnable() function is explained previously. The USBDMAChannelDisable() function disables a specific DMA channel if necessary. In some cases, there is global DMA status that is reported to the application via the USBDMAChannelStatus() function, which can be handled and cleared by calling the USBDMAChannelStatusClear() function. See the documentation for the USBDMAChannelStatusClear() function for more details on the possible status values.

USB Link Power Management Functions

Some MSP432E4 microcontrollers controllers include support for the USB Link Power Management (LPM) feature. This feature allows a USB host to put a device into sleep mode much faster than normally possible with the default USB suspend, which takes about 3ms. The MSP432E4 USB controller only supports entering the L1 state, which is a sleep state and not the full suspend state (L2). The L1 state has no specific power requirements and, with LPM, can be entered and exited much faster than the suspend state. Even with the L1 state implemented, the suspend state is still supported when the USB bus is idle for 3ms. The L1 sleep state is supported in both host and device modes including support for LPM remote wake. This section covers the support available in DriverLib for both USB host and device modes and all of the configuration options.

Host Mode LPM Support

The USB host mode support for LPM includes the ability to send a request for a device to enter LPM mode and to resume from the LPM-initiated sleep mode. The application can make a request at any time by calling the USBHostLPMSend() function, which requests the device to enter LPM mode as soon as the command is sent on the USB bus. When the host wants to wake the device, it can call the USBHostLPMResume() function, or if the device supports remote wake from LPM, the device can also initiate resume signaling.

The USB controller must to be configured before use by calling the USBHostLPMConfig() function. Two configuration options are available: the resume time and if the device is allowed to use the remote wake feature. The resume time is specified in microseconds ranging from 50us to 1200us and is passed in the ulResumeTime parameter of the USBHostLPMConfig() function. The remaining option determines if the device is allowed to issue remote wake signaling by using the USB_HOST_LPM_RMTWAKE option. The USB_HOST_LPM_L1 option is at present the only mode that is supported when using LPM. The following example demonstrates how to configure and enable USB LPM support.

Example: Configure LPM in host mode.

//
// Enable LPM with 500us resume signaling and enable remote wake.
//
USBHostLPMConfig(USB0_BASE, 500, USB_HOST_LPM_RMTWAKE | USB_HOST_LPM_L1)

//
// Enable all LPM related interrupts for host mode.
//
USBLPMIntEnable(USB0_BASE, USB_INTLPM_RESUME | USB_INTLPM_INCOMPLETE |
                           USB_INTLPM_ACK | USB_INTLPM_NYET |
                           USB_INTLPM_STALL));

After an LPM request to enter the L1 sleep state, the device can respond in one of four ways. The possible responses all generate a USB interrupt if the interrupts are enabled with a call to USBLPMIntEnable(), or the application can poll for a response using the USBLPMIntStatus() function. It is important to remember that any call to USBLPMIntStatus() clears all currently pending interrupts, so any pending interrupts must be handled after this call. The following are the valid interrupt responses returned from a call to USBLPMIntStatus():

• USB_INTLPM_INCOMPLETE - The device failed to respond to the LPM request.
• USB_INTLPM_ACK - The device received the response and accepted the command.
• USB_INTLPM_NYET - The device responded with NYET indicating that it is not prepared to handle the request at this time.
• USB_INTLPM_STALL - The device received the command but does not support this LPM request.
• USB_INTLPM_RESUME - The device has resumed from the L1 state due to a host request or a remote resume request.

Device Mode LPM Support

The USB device mode support for LPM includes the ability to receive requests to enter and exit the L1 sleep state. If the host enables remote wake from the L1 state, then the device can issue remote wake requests by calling the USBDevLPMRemoteWake() function after a device has been placed into the L1 state by an LPM request from the host.

The USB device can be configured to handle the incoming LPM request in multiple ways depending on the application requirements. Before the USB controller can properly respond to LPM commands, it must first be configured by calling the USBDevLPMConfig() function with the required configuration options. The three valid configurations that control how the USB controller responds to LPM requests from the host are:

• USB_DEV_LPM_NONE - Do not respond to any LPM requests, causing a timeout on the host side.
• USB_DEV_LPM_EN - Enable full LPM responses from the device.
• USB_DEV_LPM_EXTONLY - Receive extended packets, but do not handle LPM requests.

Example: Configure LPM in device mode.

//
// Enable full LPM support in device mode.
//
USBDevLPMConfig(USB0_BASE, USB_DEV_LPM_EN)

//
// Enable all LPM related interrupts for host mode.
//
USBLPMIntEnable(USB0_BASE, USB_INTLPM_ERROR | USB_INTLPM_RESUME |
                           USB_INTLPM_INCOMPLETE | USB_INTLPM_ACK |
                           USB_INTLPM_NYET | USB_INTLPM_STALL));

When a USB device receives an LPM command from the host, the results are stored and an interrupt is triggered. The results of the last successful LPM request are returned by calling the USBLPMLinkStateGet() function, and the targeted endpoint is returned by calling USBLPMEndpointGet(). These functions should be called to properly handle the incoming LPM request. The only valid link state change that is supported is a change to the remote wake feature, which is enabled if the USBLPMLinkStateGet() return value has the USB_DEV_LPM_LS_RMTWAKE bit set.

Example: Handling an incoming LPM request.

unsigned long ulStatus;
unsigned long ulEndpoint;

//
// Get the current link state and the targeted endpoint.
//
ulStatus = USBLPMLinkStateGet(USB0_BASE);
ulEndpoint = USBLPMEndpointGet(USB0_BASE);

//
// Check if remote wake is enabled.
//
if(ulStatus & USB_DEV_LPM_LS_RMTWAKE)
{
    // Handle enable of remote wake.
}
else
{
    // Handle disable of remote wake.
}

If the USB host controller enables remote wake on the device by sending an LPM request with the remote wake feature enabled, then the device is allowed to send remote wake requests to the host. A remote wake is sent by the device calling the USBDevLPMRemoteWake() function.

Example: Sending a remote wake from a USB device.

//
// Send a remote wake signal.
//
USBDevLPMRemoteWake(USB0_BASE);

USB UTMI Low Pin Interface (ULPI)

Some MSP432E4 USB controllers include support for connecting an external USB physical (PHY) interface that adds support for USB high speed operation when the internal PHY's full speed operation does not provide the bandwidth needed by an application. The USB controller supports the USB 2.0 Transceiver Macrocell Interface (UTMI) Low Pin Interface (ULPI) contained in the USB 2.0 specification. The configuration options for the ULPI interface are set by calling the USBULPIConfig() function. The options for configuring the ULPI interface include using the external PHY for VBUS detection by specifying USB_ULPI_EXTVBUS and enabling external VBUS over-current detection by specifying USB_ULPI_EXTVBUS_IND. The ULPI interface is not enabled by default so the application must call the USBULPIEnable() function and can call the USBULPIDisable() function if it must disable the ULPI interface. Normal operation does not require direct access to the external PHY, but if necessary the USBULPIRegRead() and USBULPIRegWrite() functions provide direct access to ULPI PHY registers.

Example: Configuring and Enabling a ULPI connected USB PHY.

//
// Enable external VBUS and over-current detection and enable the
// ULPI interface.
//
USBULPIConfig(USB0_BASE, USB_ULPI_EXTVBUS | USB_ULPI_EXTVBUS_IND);
USBULPIEnable(USB0_BASE);

Programming Example

This example code makes the calls necessary to configure endpoint 1, in device mode, as a bulk IN endpoint. The first call configures endpoint 1 to have a maximum packet size of 64 bytes and makes it a bulk IN endpoint. The call to USBFIFOConfig() configures the starting address to 64 bytes in and 64 bytes long. It also specifies USB_EP_DEV_IN to indicate a device mode IN endpoint. The next two calls demonstrate how to fill the data FIFO for this endpoint and then have it scheduled for transmission on the USB bus. The USBEndpointDataPut() call puts data into the FIFO but does not actually start the data transmission. The USBEndpointDataSend() call schedules the transmission to go out the next time the host controller requests data on this endpoint.

//
// Configure Endpoint 1.
//
USBDevEndpointConfigSet(USB0_BASE, USB_EP_1, 64, DISABLE_NAK_LIMIT,
                        USB_EP_MODE_BULK | USB_EP_DEV_IN);

//
// Configure FIFO as a device IN endpoint FIFO starting at address 64
// and is 64 bytes in size.
//
USBFIFOConfig(USB0_BASE, USB_EP_1, 64, USB_FIFO_SZ_64, USB_EP_DEV_IN);

...

//
// Put the data in the FIFO.
//
USBEndpointDataPut(USB0_BASE, USB_EP_1, pucData, 64);

//
// Start the transmission of data.
//
USBEndpointDataSend(USB0_BASE, USB_EP_1, USB_TRANS_IN);

Macro Definition Documentation

USB_INTEP_RX_SHIFT

#define USB_INTEP_RX_SHIFT   16

Referenced by USBIntDisableEndpoint(), USBIntEnableEndpoint(), and USBIntStatusEndpoint().

USB_RX_EPSTATUS_SHIFT

#define USB_RX_EPSTATUS_SHIFT   16

Referenced by USBDevEndpointStatusClear(), USBEndpointStatus(), and USBHostEndpointStatusClear().

EP_OFFSET

#define EP_OFFSET

(

Endpoint

)

(Endpoint - 0x10)

Referenced by USBDevEndpointConfigGet(), USBDevEndpointConfigSet(), USBDevEndpointDataAck(), USBDevEndpointStall(), USBDevEndpointStallClear(), USBDevEndpointStatusClear(), USBEndpointDataAvail(), USBEndpointDataGet(), USBEndpointDataToggleClear(), USBEndpointDMAConfigSet(), USBEndpointDMADisable(), USBEndpointDMAEnable(), USBEndpointStatus(), USBFIFOFlush(), USBHostEndpointConfig(), USBHostEndpointDataAck(), USBHostEndpointDataToggle(), USBHostEndpointSpeed(), USBHostEndpointStatusClear(), USBHostRequestIN(), and USBHostRequestINClear().

Function Documentation

USBHostSuspend()

void USBHostSuspend

(

uint32_t

ui32Base

)

Puts the USB bus in a suspended state.

Parameters

ui32Base

specifies the USB module base address.

When used in host mode, this function puts the USB bus in the suspended state.

Note

This function must only be called in host mode.

Returns

None.

References ASSERT, HWREGB, USB_O_POWER, and USB_POWER_SUSPEND.

USBHostReset()

void USBHostReset	(	uint32_t	ui32Base,
		bool	bStart
	)

Handles the USB bus reset condition.

Parameters

ui32Base	specifies the USB module base address.
bStart	specifies whether to start or stop signaling reset on the USB bus.

When this function is called with the bStart parameter set to true, this function causes the start of a reset condition on the USB bus. The caller must then delay at least 20ms before calling this function again with the bStart parameter set to false.

Note

This function must only be called in host mode.

Returns

None.

References ASSERT, HWREGB, USB_O_POWER, and USB_POWER_RESET.

USBHighSpeed()

void USBHighSpeed	(	uint32_t	ui32Base,
		bool	bEnable
	)

Enables or disables USB high-speed negotiation.

Parameters

ui32Base	specifies the USB module base address.
bEnable	specifies whether to enable or disable high-speed negotiation.

High-speed negotiations for both host and device mode are enabled when this function is called with the bEnable parameter set to true. In device mode this causes the device to negotiate for high speed when the USB controller receives a reset from the host. In host mode, the USB host enables high-speed negotiations when resetting the connected device. If bEnable is set to false the controller only operates only in full-speed or low-speed.

Example: Enable USB high-speed mode.

//! //
//! // Enable USB high-speed mode.
//! //
//! USBHighSpeed(USB0_BASE, true);
//! 

\note This feature should only be called when the USB is connected to
an external ULPI PHY.

\return None.  

References ASSERT, HWREGB, USB_O_POWER, and USB_POWER_HSENAB.

USBHostResume()

void USBHostResume	(	uint32_t	ui32Base,
		bool	bStart
	)

Handles the USB bus resume condition.

Parameters

ui32Base	specifies the USB module base address.
bStart	specifies if the USB controller is entering or leaving the resume signaling state.

When in device mode, this function brings the USB controller out of the suspend state. This call must first be made with the bStart parameter set to true to start resume signaling. The device application must then delay at least 10ms but not more than 15ms before calling this function with the bStart parameter set to false.

When in host mode, this function signals devices to leave the suspend state. This call must first be made with the bStart parameter set to true to start resume signaling. The host application must then delay at least 20ms before calling this function with the bStart parameter set to false. This action causes the controller to complete the resume signaling on the USB bus.

Note

This function must only be called in host mode.

Returns

None.

References ASSERT, HWREGB, USB_O_POWER, and USB_POWER_RESUME.

USBHostSpeedGet()

uint32_t USBHostSpeedGet

(

uint32_t

ui32Base

)

Returns the current speed of the USB device connected.

Parameters

ui32Base

specifies the USB module base address.

This function returns the current speed of the USB bus in host mode.

Example: Get the USB connection speed.

//! //
//! // Get the connection speed of the device connected to the USB controller.
//! //
//! USBHostSpeedGet(USB0_BASE);
//! 

\note This function must only be called in host mode.

\return Returns one of the following: \b USB_LOW_SPEED, \b USB_FULL_SPEED,
\b USB_HIGH_SPEED, or \b USB_UNDEF_SPEED.  

References ASSERT, HWREGB, USB_DEVCTL_FSDEV, USB_DEVCTL_LSDEV, USB_FULL_SPEED, USB_HIGH_SPEED, USB_LOW_SPEED, USB_O_DEVCTL, USB_O_POWER, USB_POWER_HSMODE, and USB_UNDEF_SPEED.

USBDevSpeedGet()

uint32_t USBDevSpeedGet

(

uint32_t

ui32Base

)

Returns the current speed of the USB controller in device mode.

Parameters

ui32Base

specifies the USB module base address.

This function returns the operating speed of the connection to the USB host controller. This function returns either USB_HIGH_SPEED or USB_FULL_SPEED to indicate the connection speed in device mode.

Example: Get the USB connection speed.

//! //
//! // Get the connection speed of the USB controller.
//! //
//! USBDevSpeedGet(USB0_BASE);
//! 

\note This function must only be called in device mode.

\return Returns either \b USB_HIGH_SPEED or \b USB_FULL_SPEED.  

References ASSERT, HWREGB, USB_FULL_SPEED, USB_HIGH_SPEED, USB_O_POWER, and USB_POWER_HSMODE.

USBIntDisableControl()

void USBIntDisableControl	(	uint32_t	ui32Base,
		uint32_t	ui32Flags
	)

Disables control interrupts on a specified USB controller.

Parameters

ui32Base	specifies the USB module base address.
ui32Flags	specifies which control interrupts to disable.

This function disables the control interrupts for the USB controller specified by the ui32Base parameter. The ui32Flags parameter specifies which control interrupts to disable. The flags passed in the ui32Flags parameters must be the definitions that start with USB_INTCTRL_* and not any other USB_INT flags.

Returns

None.

References ASSERT, HWREG, HWREGB, USB_INTCTRL_ALL, USB_INTCTRL_MODE_DETECT, USB_INTCTRL_POWER_FAULT, USB_INTCTRL_STATUS, USB_O_EPCIM, USB_O_IDVIM, and USB_O_IE.

USBIntEnableControl()

void USBIntEnableControl	(	uint32_t	ui32Base,
		uint32_t	ui32Flags
	)

Enables control interrupts on a specified USB controller.

Parameters

ui32Base	specifies the USB module base address.
ui32Flags	specifies which control interrupts to enable.

This function enables the control interrupts for the USB controller specified by the ui32Base parameter. The ui32Flags parameter specifies which control interrupts to enable. The flags passed in the ui32Flags parameters must be the definitions that start with USB_INTCTRL_* and not any other USB_INT flags.

Returns

None.

References ASSERT, HWREG, HWREGB, USB_EPCIM_PF, USB_IDVIM_ID, USB_INTCTRL_ALL, USB_INTCTRL_MODE_DETECT, USB_INTCTRL_POWER_FAULT, USB_INTCTRL_STATUS, USB_O_EPCIM, USB_O_IDVIM, and USB_O_IE.

USBIntStatusControl()

uint32_t USBIntStatusControl

(

uint32_t

ui32Base

)

Returns the control interrupt status on a specified USB controller.

Parameters

ui32Base

specifies the USB module base address.

This function reads control interrupt status for a USB controller. This call returns the current status for control interrupts only, the endpoint interrupt status is retrieved by calling USBIntStatusEndpoint(). The bit values returned are compared against the USB_INTCTRL_* values.

The following are the meanings of all USB_INCTRL_ flags and the modes for which they are valid. These values apply to any calls to USBIntStatusControl(), USBIntEnableControl(), and USBIntDisableControl(). Some of these flags are only valid in the following modes as indicated in the parentheses: Host, Device, and OTG.

• USB_INTCTRL_ALL - A full mask of all control interrupt sources.
• USB_INTCTRL_VBUS_ERR - A VBUS error has occurred (Host Only).
• USB_INTCTRL_SESSION - Session Start Detected on A-side of cable (OTG Only).
• USB_INTCTRL_SESSION_END - Session End Detected (Device Only)
• USB_INTCTRL_DISCONNECT - Device Disconnect Detected (Host Only)
• USB_INTCTRL_CONNECT - Device Connect Detected (Host Only)
• USB_INTCTRL_SOF - Start of Frame Detected.
• USB_INTCTRL_BABBLE - USB controller detected a device signaling past the end of a frame (Host Only)
• USB_INTCTRL_RESET - Reset signaling detected by device (Device Only)
• USB_INTCTRL_RESUME - Resume signaling detected.
• USB_INTCTRL_SUSPEND - Suspend signaling detected by device (Device Only)
• USB_INTCTRL_MODE_DETECT - OTG cable mode detection has completed (OTG Only)
• USB_INTCTRL_POWER_FAULT - Power Fault detected (Host Only)

Note

This call clears the source of all of the control status interrupts.

Returns

Returns the status of the control interrupts for a USB controller.

References ASSERT, HWREG, HWREGB, USB_EPCISC_PF, USB_IDVRIS_ID, USB_INTCTRL_MODE_DETECT, USB_INTCTRL_POWER_FAULT, USB_O_EPCISC, USB_O_IDVISC, and USB_O_IS.

USBIntDisableEndpoint()

void USBIntDisableEndpoint	(	uint32_t	ui32Base,
		uint32_t	ui32Flags
	)

Disables endpoint interrupts on a specified USB controller.

Parameters

ui32Base	specifies the USB module base address.
ui32Flags	specifies which endpoint interrupts to disable.

This function disables endpoint interrupts for the USB controller specified by the ui32Base parameter. The ui32Flags parameter specifies which endpoint interrupts to disable. The flags passed in the ui32Flags parameters must be the definitions that start with USB_INTEP_* and not any other USB_INT flags.

Returns

None.

References ASSERT, HWREGH, USB_INTEP_0, USB_INTEP_DEV_IN, USB_INTEP_DEV_OUT, USB_INTEP_HOST_IN, USB_INTEP_HOST_OUT, USB_INTEP_RX_SHIFT, USB_O_RXIE, and USB_O_TXIE.

USBIntEnableEndpoint()

void USBIntEnableEndpoint	(	uint32_t	ui32Base,
		uint32_t	ui32Flags
	)

Enables endpoint interrupts on a specified USB controller.

Parameters

ui32Base	specifies the USB module base address.
ui32Flags	specifies which endpoint interrupts to enable.

This function enables endpoint interrupts for the USB controller specified by the ui32Base parameter. The ui32Flags parameter specifies which endpoint interrupts to enable. The flags passed in the ui32Flags parameters must be the definitions that start with USB_INTEP_* and not any other USB_INT flags.

Returns

None.

References ASSERT, HWREGH, USB_INTEP_0, USB_INTEP_DEV_IN, USB_INTEP_DEV_OUT, USB_INTEP_HOST_IN, USB_INTEP_HOST_OUT, USB_INTEP_RX_SHIFT, USB_O_RXIE, and USB_O_TXIE.

USBIntStatusEndpoint()

uint32_t USBIntStatusEndpoint

(

uint32_t

ui32Base

)

Returns the endpoint interrupt status on a specified USB controller.

Parameters

ui32Base

specifies the USB module base address.

This function reads endpoint interrupt status for a USB controller. This call returns the current status for endpoint interrupts only, the control interrupt status is retrieved by calling USBIntStatusControl(). The bit values returned are compared against the USB_INTEP_* values. These values are grouped into classes for USB_INTEP_HOST_* and USB_INTEP_DEV_* values to handle both host and device modes with all endpoints.

Note

This call clears the source of all of the endpoint interrupts.

Returns

Returns the status of the endpoint interrupts for a USB controller.

References ASSERT, HWREGH, USB_INTEP_RX_SHIFT, USB_O_RXIS, and USB_O_TXIS.

USBIntRegister()

void USBIntRegister	(	uint32_t	ui32Base,
		void(*)(void)	pfnHandler
	)

Registers an interrupt handler for the USB controller.

Parameters

ui32Base	specifies the USB module base address.
pfnHandler	is a pointer to the function to be called when a USB interrupt occurs.

This function registers the handler to be called when a USB interrupt occurs and enables the global USB interrupt in the interrupt controller. The specific desired USB interrupts must be enabled via a separate call to USBIntEnable(). It is the interrupt handler's responsibility to clear the interrupt sources via calls to USBIntStatusControl() and USBIntStatusEndpoint().

See also

IntRegister() for important information about registering interrupt handlers.

Returns

None.

References ASSERT.

USBIntUnregister()

void USBIntUnregister

(

uint32_t

ui32Base

)

Unregisters an interrupt handler for the USB controller.

Parameters

ui32Base

specifies the USB module base address.

This function unregisters the interrupt handler. This function also disables the USB interrupt in the interrupt controller.

See also

IntRegister() for important information about registering or unregistering interrupt handlers.

Returns

None.

References ASSERT.

USBEndpointStatus()

uint32_t USBEndpointStatus	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint
	)

Returns the current status of an endpoint.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.

This function returns the status of a specified endpoint. If any of these status bits must be cleared, then the USBDevEndpointStatusClear() or the USBHostEndpointStatusClear() functions must be called.

The following are the status flags for host mode:

• USB_HOST_IN_PID_ERROR - PID error on the specified endpoint.
• USB_HOST_IN_NOT_COMP - The device failed to respond to an IN request.
• USB_HOST_IN_STALL - A stall was received on an IN endpoint.
• USB_HOST_IN_DATA_ERROR - There was a CRC or bit-stuff error on an IN endpoint in Isochronous mode.
• USB_HOST_IN_NAK_TO - NAKs received on this IN endpoint for more than the specified timeout period.
• USB_HOST_IN_ERROR - Failed to communicate with a device using this IN endpoint.
• USB_HOST_IN_FIFO_FULL - This IN endpoint's FIFO is full.
• USB_HOST_IN_PKTRDY - Data packet ready on this IN endpoint.
• USB_HOST_OUT_NAK_TO - NAKs received on this OUT endpoint for more than the specified timeout period.
• USB_HOST_OUT_NOT_COMP - The device failed to respond to an OUT request.
• USB_HOST_OUT_STALL - A stall was received on this OUT endpoint.
• USB_HOST_OUT_ERROR - Failed to communicate with a device using this OUT endpoint.
• USB_HOST_OUT_FIFO_NE - This endpoint's OUT FIFO is not empty.
• USB_HOST_OUT_PKTPEND - The data transfer on this OUT endpoint has not completed.
• USB_HOST_EP0_NAK_TO - NAKs received on endpoint zero for more than the specified timeout period.
• USB_HOST_EP0_ERROR - The device failed to respond to a request on endpoint zero.
• USB_HOST_EP0_IN_STALL - A stall was received on endpoint zero for an IN transaction.
• USB_HOST_EP0_IN_PKTRDY - Data packet ready on endpoint zero for an IN transaction.

The following are the status flags for device mode:

• USB_DEV_OUT_SENT_STALL - A stall was sent on this OUT endpoint.
• USB_DEV_OUT_DATA_ERROR - There was a CRC or bit-stuff error on an OUT endpoint.
• USB_DEV_OUT_OVERRUN - An OUT packet was not loaded due to a full FIFO.
• USB_DEV_OUT_FIFO_FULL - The OUT endpoint's FIFO is full.
• USB_DEV_OUT_PKTRDY - There is a data packet ready in the OUT endpoint's FIFO.
• USB_DEV_IN_NOT_COMP - A larger packet was split up, more data to come.
• USB_DEV_IN_SENT_STALL - A stall was sent on this IN endpoint.
• USB_DEV_IN_UNDERRUN - Data was requested on the IN endpoint and no data was ready.
• USB_DEV_IN_FIFO_NE - The IN endpoint's FIFO is not empty.
• USB_DEV_IN_PKTPEND - The data transfer on this IN endpoint has not completed.
• USB_DEV_EP0_SETUP_END - A control transaction ended before Data End condition was sent.
• USB_DEV_EP0_SENT_STALL - A stall was sent on endpoint zero.
• USB_DEV_EP0_IN_PKTPEND - The data transfer on endpoint zero has not completed.
• USB_DEV_EP0_OUT_PKTRDY - There is a data packet ready in endpoint zero's OUT FIFO.

Returns

The current status flags for the endpoint depending on mode.

References ASSERT, EP_OFFSET, HWREGH, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_O_RXCSRL1, USB_O_TXCSRL1, and USB_RX_EPSTATUS_SHIFT.

USBHostEndpointStatusClear()

void USBHostEndpointStatusClear	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32Flags
	)

Clears the status bits in this endpoint in host mode.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
ui32Flags	are the status bits that are cleared.

This function clears the status of any bits that are passed in the ui32Flags parameter. The ui32Flags parameter can take the value returned from the USBEndpointStatus() call.

Note

This function must only be called in host mode.

Returns

None.

References ASSERT, EP_OFFSET, HWREGB, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_O_CSRL0, USB_O_RXCSRL1, USB_O_TXCSRL1, and USB_RX_EPSTATUS_SHIFT.

USBDevEndpointStatusClear()

void USBDevEndpointStatusClear	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32Flags
	)

Clears the status bits in this endpoint in device mode.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
ui32Flags	are the status bits that are cleared.

This function clears the status of any bits that are passed in the ui32Flags parameter. The ui32Flags parameter can take the value returned from the USBEndpointStatus() call.

Note

This function must only be called in device mode.

Returns

None.

References ASSERT, EP_OFFSET, HWREGB, USB_CSRL0_RXRDYC, USB_CSRL0_SETENDC, USB_DEV_EP0_OUT_PKTRDY, USB_DEV_EP0_SENT_STALL, USB_DEV_EP0_SETUP_END, USB_DEV_RX_DATA_ERROR, USB_DEV_RX_OVERRUN, USB_DEV_RX_SENT_STALL, USB_DEV_TX_SENT_STALL, USB_DEV_TX_UNDERRUN, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_O_CSRL0, USB_O_RXCSRL1, USB_O_TXCSRL1, and USB_RX_EPSTATUS_SHIFT.

USBHostEndpointDataToggle()

void USBHostEndpointDataToggle	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		bool	bDataToggle,
		uint32_t	ui32Flags
	)

Sets the value data toggle on an endpoint in host mode.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	specifies the endpoint to reset the data toggle.
bDataToggle	specifies whether to set the state to DATA0 or DATA1.
ui32Flags	specifies whether to set the IN or OUT endpoint.

This function is used to force the state of the data toggle in host mode. If the value passed in the bDataToggle parameter is false, then the data toggle is set to the DATA0 state, and if it is true it is set to the DATA1 state. The ui32Flags parameter can be USB_EP_HOST_IN or USB_EP_HOST_OUT to access the desired portion of this endpoint. The ui32Flags parameter is ignored for endpoint zero.

Note

This function must only be called in host mode.

Returns

None.

References ASSERT, EP_OFFSET, HWREGB, USB_CSRH0_DT, USB_CSRH0_DTWE, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_EP_HOST_IN, USB_O_CSRH0, USB_O_RXCSRH1, USB_O_TXCSRH1, USB_RXCSRH1_DT, USB_RXCSRH1_DTWE, USB_TXCSRH1_DT, and USB_TXCSRH1_DTWE.

USBEndpointDataToggleClear()

void USBEndpointDataToggleClear	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32Flags
	)

Sets the data toggle on an endpoint to zero.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	specifies the endpoint to reset the data toggle.
ui32Flags	specifies whether to access the IN or OUT endpoint.

This function causes the USB controller to clear the data toggle for an endpoint. This call is not valid for endpoint zero and can be made with host or device controllers.

The ui32Flags parameter must be one of USB_EP_HOST_OUT, USB_EP_HOST_IN, USB_EP_DEV_OUT, or USB_EP_DEV_IN.

Returns

None.

References ASSERT, EP_OFFSET, HWREGB, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_EP_DEV_IN, USB_EP_HOST_OUT, USB_O_RXCSRL1, USB_O_TXCSRL1, USB_RXCSRL1_CLRDT, and USB_TXCSRL1_CLRDT.

USBHostEndpointPing()

void USBHostEndpointPing	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		bool	bEnable
	)

Enables or disables ping tokens for an endpoint using high-speed control transfers in host mode.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	specifies the endpoint to enable/disable ping tokens.
bEnable	specifies whether enable or disable ping tokens.

This function configures the USB controller to either send or not send ping tokens during the data and status phase of high speed control transfers. The only supported value for ui32Endpoint is USB_EP_0 because all control transfers are handled using this endpoint. If the bEnable is true then ping tokens are enabled, if false then ping tokens are disabled. This must be used if the controller must support communications with devices that do not support ping tokens in high speed mode.

Example: Disable ping transactions in host mode on endpoint 0.

//! //
//! // Disable ping transaction on endpoint 0.
//! //
//! USBHostEndpointPing(USB0_BASE, USB_EP_0, false);
//! 

\note This function must only be called in host mode.

\return None.  

References ASSERT, HWREGB, USB_CSRH0_DISPING, USB_EP_0, and USB_O_CSRH0.

USBDevEndpointStall()

void USBDevEndpointStall	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32Flags
	)

Stalls the specified endpoint in device mode.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	specifies the endpoint to stall.
ui32Flags	specifies whether to stall the IN or OUT endpoint.

This function causes the endpoint number passed in to go into a stall condition. If the ui32Flags parameter is USB_EP_DEV_IN, then the stall is issued on the IN portion of this endpoint. If the ui32Flags parameter is USB_EP_DEV_OUT, then the stall is issued on the OUT portion of this endpoint.

Note

This function must only be called in device mode.

Returns

None.

References ASSERT, EP_OFFSET, HWREGB, USB_CSRL0_RXRDYC, USB_CSRL0_STALL, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_EP_DEV_IN, USB_EP_DEV_OUT, USB_O_CSRL0, USB_O_RXCSRL1, USB_O_TXCSRL1, USB_RXCSRL1_STALL, and USB_TXCSRL1_STALL.

USBDevEndpointStallClear()

void USBDevEndpointStallClear	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32Flags
	)

Clears the stall condition on the specified endpoint in device mode.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	specifies which endpoint to remove the stall condition.
ui32Flags	specifies whether to remove the stall condition from the IN or the OUT portion of this endpoint.

This function causes the endpoint number passed in to exit the stall condition. If the ui32Flags parameter is USB_EP_DEV_IN, then the stall is cleared on the IN portion of this endpoint. If the ui32Flags parameter is USB_EP_DEV_OUT, then the stall is cleared on the OUT portion of this endpoint.

Note

This function must only be called in device mode.

Returns

None.

References ASSERT, EP_OFFSET, HWREGB, USB_CSRL0_STALLED, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_EP_DEV_IN, USB_EP_DEV_OUT, USB_O_CSRL0, USB_O_RXCSRL1, USB_O_TXCSRL1, USB_RXCSRL1_CLRDT, USB_RXCSRL1_STALL, USB_RXCSRL1_STALLED, USB_TXCSRL1_CLRDT, USB_TXCSRL1_STALL, and USB_TXCSRL1_STALLED.

USBDevConnect()

void USBDevConnect

(

uint32_t

ui32Base

)

Connects the USB controller to the bus in device mode.

Parameters

ui32Base

specifies the USB module base address.

This function causes the soft connect feature of the USB controller to be enabled. Call USBDevDisconnect() to remove the USB device from the bus.

Note

This function must only be called in device mode.

Returns

None.

References ASSERT, HWREGB, USB_O_POWER, and USB_POWER_SOFTCONN.

USBDevDisconnect()

void USBDevDisconnect

(

uint32_t

ui32Base

)

Removes the USB controller from the bus in device mode.

Parameters

ui32Base

specifies the USB module base address.

This function causes the soft connect feature of the USB controller to remove the device from the USB bus. A call to USBDevConnect() is needed to reconnect to the bus.

Note

This function must only be called in device mode.

Returns

None.

References ASSERT, HWREGB, USB_O_POWER, and USB_POWER_SOFTCONN.

USBDevAddrSet()

void USBDevAddrSet	(	uint32_t	ui32Base,
		uint32_t	ui32Address
	)

Sets the address in device mode.

Parameters

ui32Base	specifies the USB module base address.
ui32Address	is the address to use for a device.

This function configures the device address on the USB bus. This address was likely received via a SET ADDRESS command from the host controller.

Note

This function must only be called in device mode.

Returns

None.

References ASSERT, HWREGB, and USB_O_FADDR.

USBDevAddrGet()

uint32_t USBDevAddrGet

(

uint32_t

ui32Base

)

Returns the current device address in device mode.

Parameters

ui32Base

specifies the USB module base address.

This function returns the current device address. This address was set by a call to USBDevAddrSet().

Note

This function must only be called in device mode.

Returns

The current device address.

References ASSERT, HWREGB, and USB_O_FADDR.

USBHostEndpointConfig()

void USBHostEndpointConfig	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32MaxPayload,
		uint32_t	ui32NAKPollInterval,
		uint32_t	ui32TargetEndpoint,
		uint32_t	ui32Flags
	)

Sets the base configuration for a host endpoint.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
ui32MaxPayload	is the maximum payload for this endpoint.
ui32NAKPollInterval	is the either the NAK timeout limit or the polling interval, depending on the type of endpoint.
ui32TargetEndpoint	is the endpoint that the host endpoint is targeting.
ui32Flags	are used to configure other endpoint settings.

This function sets the basic configuration for the transmit or receive portion of an endpoint in host mode. The ui32Flags parameter determines some of the configuration while the other parameters provide the rest. The ui32Flags parameter determines whether this is an IN endpoint (USB_EP_HOST_IN or USB_EP_DEV_IN) or an OUT endpoint (USB_EP_HOST_OUT or USB_EP_DEV_OUT), whether this is a Full speed endpoint (USB_EP_SPEED_FULL) or a Low speed endpoint (USB_EP_SPEED_LOW).

The USB_EP_MODE_ flags control the type of the endpoint.

• USB_EP_MODE_CTRL is a control endpoint.
• USB_EP_MODE_ISOC is an isochronous endpoint.
• USB_EP_MODE_BULK is a bulk endpoint.
• USB_EP_MODE_INT is an interrupt endpoint.

The ui32NAKPollInterval parameter has different meanings based on the USB_EP_MODE value and whether or not this call is being made for endpoint zero or another endpoint. For endpoint zero or any Bulk endpoints, this value always indicates the number of frames to allow a device to NAK before considering it a timeout. If this endpoint is an isochronous or interrupt endpoint, this value is the polling interval for this endpoint.

For interrupt endpoints, the polling interval is the number of frames between interrupt IN requests to an endpoint and has a range of 1 to 255. For isochronous endpoints this value represents a polling interval of 2 ^ (ui32NAKPollInterval - 1) frames. When used as a NAK timeout, the ui32NAKPollInterval value specifies 2 ^ (ui32NAKPollInterval - 1) frames before issuing a time out.

There are two special time out values that can be specified when setting the ui32NAKPollInterval value. The first is MAX_NAK_LIMIT, which is the maximum value that can be passed in this variable. The other is DISABLE_NAK_LIMIT, which indicates that there is no limit on the number of NAKs.

The USB_EP_DMA_MODE_ flags determine the type of DMA access to the endpoint data FIFOs. The choice of the DMA mode depends on how the DMA controller is configured and how it is being used. See the ``Using USB with the uDMA Controller'' or the ''Using the integrated USB DMA Controller'' section for more information on DMA configuration depending on the type of DMA that is supported by the USB controller.

When configuring the OUT portion of an endpoint, the USB_EP_AUTO_SET bit is specified to cause the transmission of data on the USB bus to start as soon as the number of bytes specified by ui32MaxPayload has been written into the OUT FIFO for this endpoint.

When configuring the IN portion of an endpoint, the USB_EP_AUTO_REQUEST bit can be specified to trigger the request for more data once the FIFO has been drained enough to fit ui32MaxPayload bytes. The USB_EP_AUTO_CLEAR bit can be used to clear the data packet ready flag automatically once the data has been read from the FIFO. If this option is not used, this flag must be manually cleared via a call to USBDevEndpointStatusClear() or USBHostEndpointStatusClear().

For interrupt endpoints in low or full speed mode, the polling interval (ui32NAKPollInterval) is the number of frames between interrupt IN requests to an endpoint and has a range of 1 to 255. For interrupt endpoints in high speed mode the polling interval is 2 ^ (ui32NAKPollInterval - 1) microframes between interrupt IN requests to an endpoint and has a range of 1 to 16.

Note

This function must only be called in host mode.

Returns

None.

References ASSERT, EP_OFFSET, HWREGB, HWREGH, MAX_NAK_LIMIT, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_EP_AUTO_CLEAR, USB_EP_AUTO_REQUEST, USB_EP_AUTO_SET, USB_EP_DMA_MODE_0, USB_EP_DMA_MODE_1, USB_EP_HOST_OUT, USB_EP_MODE_BULK, USB_EP_MODE_CTRL, USB_EP_MODE_INT, USB_EP_MODE_ISOC, USB_EP_MODE_MASK, USB_EP_SPEED_FULL, USB_EP_SPEED_HIGH, USB_O_NAKLMT, USB_O_RXCSRH1, USB_O_RXINTERVAL1, USB_O_RXMAXP1, USB_O_RXTYPE1, USB_O_TXCSRH1, USB_O_TXINTERVAL1, USB_O_TXMAXP1, USB_O_TXTYPE1, USB_O_TYPE0, USB_RXCSRH1_AUTOCL, USB_RXCSRH1_AUTORQ, USB_RXCSRH1_DMAEN, USB_RXCSRH1_DMAMOD, USB_TXCSRH1_AUTOSET, USB_TXCSRH1_DMAEN, USB_TXCSRH1_DMAMOD, USB_TXTYPE1_PROTO_BULK, USB_TXTYPE1_PROTO_CTRL, USB_TXTYPE1_PROTO_INT, USB_TXTYPE1_PROTO_ISOC, USB_TXTYPE1_SPEED_FULL, USB_TXTYPE1_SPEED_HIGH, USB_TXTYPE1_SPEED_LOW, USB_TYPE0_SPEED_FULL, USB_TYPE0_SPEED_HIGH, and USB_TYPE0_SPEED_LOW.

USBHostEndpointSpeed()

void USBHostEndpointSpeed	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32Flags
	)

Changes the speed of the connection for a host endpoint.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
ui32Flags	are used to configure other endpoint settings.

This function sets the USB speed for an IN or OUT endpoint in host mode. The ui32Flags parameter specifies the speed using one of the following values: USB_EP_SPEED_LOW, USB_EP_SPEED_FULL, or USB_EP_SPEED_HIGH. The ui32Flags parameter also specifies which direction is set by adding the logical OR in either USB_EP_HOST_IN or USB_EP_HOST_OUT. All other flags are ignored. This function is typically only used for endpoint 0, but could be used with other endpoints as well.

Example: Set host transactions on endpoint 0 to full speed..

//! //
//! // Set host endpoint 0 transactions to full speed.
//! //
//! USBHostEndpointSpeed(USB0_BASE, USB_EP_0, USB_EP_SPEED_FULL);
//! 

\note This function must only be called in host mode.

\return None.  

References ASSERT, EP_OFFSET, HWREGB, HWREGH, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_EP_HOST_OUT, USB_EP_SPEED_FULL, USB_EP_SPEED_HIGH, USB_O_RXTYPE1, USB_O_TXTYPE1, USB_O_TYPE0, USB_RXTYPE1_SPEED_M, USB_TXTYPE1_SPEED_M, USB_TYPE0_SPEED_FULL, USB_TYPE0_SPEED_HIGH, and USB_TYPE0_SPEED_LOW.

USBDevEndpointConfigSet()

void USBDevEndpointConfigSet	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32MaxPacketSize,
		uint32_t	ui32Flags
	)

Sets the configuration for an endpoint.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
ui32MaxPacketSize	is the maximum packet size for this endpoint.
ui32Flags	are used to configure other endpoint settings.

This function sets the basic configuration for an endpoint in device mode. Endpoint zero does not have a dynamic configuration, so this function must not be called for endpoint zero. The ui32Flags parameter determines some of the configuration while the other parameters provide the rest.

The USB_EP_MODE_ flags define what the type is for the specified endpoint.

• USB_EP_MODE_CTRL is a control endpoint.
• USB_EP_MODE_ISOC is an isochronous endpoint.
• USB_EP_MODE_BULK is a bulk endpoint.
• USB_EP_MODE_INT is an interrupt endpoint.

The USB_EP_DMA_MODE_ flags determine the type of DMA access to the endpoint data FIFOs. The choice of the DMA mode depends on how the DMA controller is configured and how it is being used. See the ``Using USB with the uDMA Controller'' or the ''Using the integrated USB DMA Controller'' section for more information on DMA configuration depending on the type of DMA that is supported by the USB controller.

When configuring an IN endpoint, the USB_EP_AUTO_SET bit can be specified to cause the automatic transmission of data on the USB bus as soon as ui32MaxPacketSize bytes of data are written into the FIFO for this endpoint. This option is commonly used with DMA (both on devices with integrated USB DMA as well as those that use uDMA) as no interaction is required to start the transmission of data.

When configuring an OUT endpoint, the USB_EP_AUTO_REQUEST bit is specified to trigger the request for more data once the FIFO has been drained enough to receive ui32MaxPacketSize more bytes of data. Also for OUT endpoints, the USB_EP_AUTO_CLEAR bit can be used to clear the data packet ready flag automatically once the data has been read from the FIFO. If this option is not used, this flag must be manually cleared via a call to USBDevEndpointStatusClear(). Both of these settings can be used to remove the need for extra calls when using the controller with DMA.

Note

This function must only be called in device mode.

Returns

None.

References ASSERT, EP_OFFSET, HWREGB, HWREGH, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_EP_AUTO_CLEAR, USB_EP_AUTO_SET, USB_EP_DEV_IN, USB_EP_DIS_NYET, USB_EP_DMA_MODE_0, USB_EP_DMA_MODE_1, USB_EP_MODE_ISOC, USB_EP_MODE_MASK, USB_O_RXCSRH1, USB_O_RXCSRL1, USB_O_RXMAXP1, USB_O_TXCSRH1, USB_O_TXCSRL1, USB_O_TXMAXP1, USB_RXCSRH1_AUTOCL, USB_RXCSRH1_DISNYET, USB_RXCSRH1_DMAEN, USB_RXCSRH1_DMAMOD, USB_RXCSRH1_ISO, USB_RXCSRL1_CLRDT, USB_TXCSRH1_AUTOSET, USB_TXCSRH1_DMAEN, USB_TXCSRH1_DMAMOD, USB_TXCSRH1_ISO, and USB_TXCSRL1_CLRDT.

USBDevEndpointConfigGet()

void USBDevEndpointConfigGet	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t *	pui32MaxPacketSize,
		uint32_t *	pui32Flags
	)

Gets the current configuration for an endpoint.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
pui32MaxPacketSize	is a pointer which is written with the maximum packet size for this endpoint.
pui32Flags	is a pointer which is written with the current endpoint settings. On entry to the function, this pointer must contain either USB_EP_DEV_IN or USB_EP_DEV_OUT to indicate whether the IN or OUT endpoint is to be queried.

This function returns the basic configuration for an endpoint in device mode. The values returned in *pui32MaxPacketSize and *pui32Flags are equivalent to the ui32MaxPacketSize and ui32Flags previously passed to USBDevEndpointConfigSet() for this endpoint.

Note

This function must only be called in device mode.

Returns

None.

References ASSERT, EP_OFFSET, HWREGB, HWREGH, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_EP_AUTO_CLEAR, USB_EP_AUTO_SET, USB_EP_DEV_IN, USB_EP_DEV_OUT, USB_EP_DMA_MODE_0, USB_EP_DMA_MODE_1, USB_EP_MODE_BULK, USB_EP_MODE_ISOC, USB_O_RXCSRH1, USB_O_RXMAXP1, USB_O_TXCSRH1, USB_O_TXMAXP1, USB_RXCSRH1_AUTOCL, USB_RXCSRH1_DMAEN, USB_RXCSRH1_DMAMOD, USB_RXCSRH1_ISO, USB_TXCSRH1_AUTOSET, USB_TXCSRH1_DMAEN, USB_TXCSRH1_DMAMOD, and USB_TXCSRH1_ISO.

USBFIFOConfigSet()

void USBFIFOConfigSet	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32FIFOAddress,
		uint32_t	ui32FIFOSize,
		uint32_t	ui32Flags
	)

Sets the FIFO configuration for an endpoint.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
ui32FIFOAddress	is the starting address for the FIFO.
ui32FIFOSize	is the size of the FIFO specified by one of the USB_FIFO_SZ_ values.
ui32Flags	specifies what information to set in the FIFO configuration.

This function configures the starting FIFO RAM address and size of the FIFO for a specified endpoint. Endpoint zero does not have a dynamically configurable FIFO, so this function must not be called for endpoint zero. The ui32FIFOSize parameter must be one of the values in the USB_FIFO_SZ_ values.

The ui32FIFOAddress value must be a multiple of 8 bytes and directly indicates the starting address in the USB controller's FIFO RAM. For example, a value of 64 indicates that the FIFO starts 64 bytes into the USB controller's FIFO memory. The ui32Flags value specifies whether the endpoint's OUT or IN FIFO must be configured. If in host mode, use USB_EP_HOST_OUT or USB_EP_HOST_IN, and if in device mode, use USB_EP_DEV_OUT or USB_EP_DEV_IN.

Returns

None.

References ASSERT, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_EP_DEV_IN, and USB_EP_HOST_OUT.

USBFIFOConfigGet()

void USBFIFOConfigGet	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t *	pui32FIFOAddress,
		uint32_t *	pui32FIFOSize,
		uint32_t	ui32Flags
	)

Returns the FIFO configuration for an endpoint.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
pui32FIFOAddress	is the starting address for the FIFO.
pui32FIFOSize	is the size of the FIFO as specified by one of the USB_FIFO_SZ_ values.
ui32Flags	specifies what information to retrieve from the FIFO configuration.

This function returns the starting address and size of the FIFO for a specified endpoint. Endpoint zero does not have a dynamically configurable FIFO, so this function must not be called for endpoint zero. The ui32Flags parameter specifies whether the endpoint's OUT or IN FIFO must be read. If in host mode, the ui32Flags parameter must be USB_EP_HOST_OUT or USB_EP_HOST_IN, and if in device mode, the ui32Flags parameter must be either USB_EP_DEV_OUT or USB_EP_DEV_IN.

Returns

None.

References ASSERT, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_EP_DEV_IN, and USB_EP_HOST_OUT.

USBEndpointDMAConfigSet()

void USBEndpointDMAConfigSet	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32Config
	)

Configure the DMA settings for an endpoint.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
ui32Config	specifies the configuration options for an endpoint.

This function configures the DMA settings for a specified endpoint without changing other options that may already be configured. In order for the DMA transfer to be enabled, the USBEndpointDMAEnable() function must be called before starting the DMA transfer. The configuration options are passed in the ui32Config parameter and can have the values described below.

One of the following values to specify direction:

• USB_EP_HOST_OUT or USB_EP_DEV_IN - This setting is used with DMA transfers from memory to the USB controller.
• USB_EP_HOST_IN or USB_EP_DEV_OUT - This setting is used with DMA transfers from the USB controller to memory.

One of the following values:

• USB_EP_DMA_MODE_0(default) - This setting is typically used for transfers that do not span multiple packets or when interrupts are required for each packet.
• USB_EP_DMA_MODE_1 - This setting is typically used for transfers that span multiple packets and do not require interrupts between packets.

Values only used with USB_EP_HOST_OUT or USB_EP_DEV_IN:

• USB_EP_AUTO_SET - This setting is used to allow transmit DMA transfers to automatically be sent when a full packet is loaded into a FIFO. This is needed with USB_EP_DMA_MODE_1 to ensure that packets go out when the FIFO becomes full and the DMA has more data to send.

Values only used with USB_EP_HOST_IN or USB_EP_DEV_OUT:

• USB_EP_AUTO_CLEAR - This setting is used to allow receive DMA transfers to automatically be acknowledged as they are received. This is needed with USB_EP_DMA_MODE_1 to ensure that packets continue to be received and acknowledged when the FIFO is emptied by the DMA transfer.

Values only used with USB_EP_HOST_IN:

• USB_EP_AUTO_REQUEST - This setting is used to allow receive DMA transfers to automatically request a new IN transaction when the previous transfer has emptied the FIFO. This is typically used in conjunction with USB_EP_AUTO_CLEAR so that receive DMA transfers can continue without interrupting the main processor.

Example: Set endpoint 1 receive endpoint to automatically acknowledge request and automatically generate a new IN request in host mode.

//! //
//! // Configure endpoint 1 for receiving multiple packets using DMA.
//! //
//! USBEndpointDMAConfigSet(USB0_BASE, USB_EP_1, USB_EP_HOST_IN |
//!                                              USB_EP_DMA_MODE_1 |
//!                                              USB_EP_AUTO_CLEAR |
//!                                              USB_EP_AUTO_REQUEST);
//! 

\b Example: Set endpoint 2 transmit endpoint to automatically send each
packet in host mode when spanning multiple packets.

//! //
//! // Configure endpoint 1 for transmitting multiple packets using DMA.
//! //
//! USBEndpointDMAConfigSet(USB0_BASE, USB_EP_2, USB_EP_HOST_OUT |
//!                                              USB_EP_DMA_MODE_1 |
//!                                              USB_EP_AUTO_SET);
//! 

\return None.  

References EP_OFFSET, HWREGB, USB_EP_AUTO_CLEAR, USB_EP_AUTO_REQUEST, USB_EP_AUTO_SET, USB_EP_DMA_MODE_1, USB_EP_HOST_OUT, USB_O_RXCSRH1, USB_O_TXCSRH1, USB_RXCSRH1_AUTOCL, USB_RXCSRH1_AUTORQ, USB_RXCSRH1_DMAMOD, USB_TXCSRH1_AUTOSET, and USB_TXCSRH1_DMAMOD.

USBEndpointDMAEnable()

void USBEndpointDMAEnable	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32Flags
	)

Enable DMA on a specified endpoint.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
ui32Flags	specifies which direction and what mode to use when enabling DMA.

This function enables DMA on a specified endpoint and configures the mode according to the values in the ui32Flags parameter. The ui32Flags parameter must have USB_EP_DEV_IN or USB_EP_DEV_OUT set. Once this function is called the only DMA or error interrupts are generated by the USB controller.

Note

If this function is called when an endpoint is configured in DMA mode 0 the USB controller does not generate an interrupt.

Returns

None.

References EP_OFFSET, HWREGB, USB_EP_DEV_IN, USB_O_RXCSRH1, USB_O_TXCSRH1, USB_RXCSRH1_DMAEN, and USB_TXCSRH1_DMAEN.

USBEndpointDMADisable()

void USBEndpointDMADisable	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32Flags
	)

Disable DMA on a specified endpoint.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
ui32Flags	specifies which direction to disable.

This function disables DMA on a specified endpoint to allow non-DMA USB transactions to generate interrupts normally. The ui32Flags parameter must be USB_EP_DEV_IN or USB_EP_DEV_OUT; all other bits are ignored.

Returns

None.

References EP_OFFSET, HWREGB, USB_EP_DEV_IN, USB_O_RXCSRH1, USB_O_TXCSRH1, USB_RXCSRH1_DMAEN, and USB_TXCSRH1_DMAEN.

USBEndpointDataAvail()

uint32_t USBEndpointDataAvail	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint
	)

Determines the number of bytes of data available in a specified endpoint's FIFO.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.

This function returns the number of bytes of data currently available in the FIFO for the specified receive (OUT) endpoint. It may be used prior to calling USBEndpointDataGet() to determine the size of buffer required to hold the newly-received packet.

Returns

This call returns the number of bytes available in a specified endpoint FIFO.

References ASSERT, EP_OFFSET, HWREGH, USB_CSRL0_RXRDY, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_O_COUNT0, USB_O_CSRL0, and USB_O_RXCSRL1.

USBEndpointDataGet()

int32_t USBEndpointDataGet	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint8_t *	pui8Data,
		uint32_t *	pui32Size
	)

Retrieves data from the specified endpoint's FIFO.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
pui8Data	is a pointer to the data area used to return the data from the FIFO.
pui32Size	is initially the size of the buffer passed into this call via the pui8Data parameter. It is set to the amount of data returned in the buffer.

This function returns the data from the FIFO for the specified endpoint. The pui32Size parameter indicates the size of the buffer passed in the pui32Data parameter. The data in the pui32Size parameter is changed to match the amount of data returned in the pui8Data parameter. If a zero-byte packet is received, this call does not return an error but instead just returns a zero in the pui32Size parameter. The only error case occurs when there is no data packet available.

Returns

This call returns 0, or -1 if no packet was received.

References ASSERT, EP_OFFSET, HWREGB, HWREGH, USB_CSRL0_RXRDY, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_O_COUNT0, USB_O_CSRL0, USB_O_FIFO0, and USB_O_RXCSRL1.

USBDevEndpointDataAck()

void USBDevEndpointDataAck	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		bool	bIsLastPacket
	)

Acknowledge that data was read from the specified endpoint's FIFO in device mode.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
bIsLastPacket	indicates if this packet is the last one.

This function acknowledges that the data was read from the endpoint's FIFO. The bIsLastPacket parameter is set to a true value if this is the last in a series of data packets on endpoint zero. The bIsLastPacket parameter is not used for endpoints other than endpoint zero. This call can be used if processing is required between reading the data and acknowledging that the data has been read.

Note

This function must only be called in device mode.

Returns

None.

References ASSERT, EP_OFFSET, HWREGB, USB_CSRL0_DATAEND, USB_CSRL0_RXRDYC, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_O_CSRL0, USB_O_RXCSRL1, and USB_RXCSRL1_RXRDY.

USBHostEndpointDataAck()

void USBHostEndpointDataAck	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint
	)

Acknowledge that data was read from the specified endpoint's FIFO in host mode.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.

This function acknowledges that the data was read from the endpoint's FIFO. This call is used if processing is required between reading the data and acknowledging that the data has been read.

Note

This function must only be called in host mode.

Returns

None.

References ASSERT, EP_OFFSET, HWREGB, USB_CSRL0_RXRDY, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_O_CSRL0, USB_O_RXCSRL1, and USB_RXCSRL1_RXRDY.

USBEndpointDataPut()

int32_t USBEndpointDataPut	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint8_t *	pui8Data,
		uint32_t	ui32Size
	)

Puts data into the specified endpoint's FIFO.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
pui8Data	is a pointer to the data area used as the source for the data to put into the FIFO.
ui32Size	is the amount of data to put into the FIFO.

This function puts the data from the pui8Data parameter into the FIFO for this endpoint. If a packet is already pending for transmission, then this call does not put any of the data into the FIFO and returns -1. Care must be taken to not write more data than can fit into the FIFO allocated by the call to USBFIFOConfigSet().

Returns

This call returns 0 on success, or -1 to indicate that the FIFO is in use and cannot be written.

References ASSERT, HWREGB, USB_CSRL0_TXRDY, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_O_CSRL0, USB_O_FIFO0, and USB_TXCSRL1_TXRDY.

USBEndpointDataSend()

int32_t USBEndpointDataSend	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32TransType
	)

Starts the transfer of data from an endpoint's FIFO.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
ui32TransType	is set to indicate what type of data is being sent.

This function starts the transfer of data from the FIFO for a specified endpoint. This function is called if the USB_EP_AUTO_SET bit was not enabled for the endpoint. Setting the ui32TransType parameter allows the appropriate signaling on the USB bus for the type of transaction being requested. The ui32TransType parameter must be one of the following:

• USB_TRANS_OUT for OUT transaction on any endpoint in host mode.
• USB_TRANS_IN for IN transaction on any endpoint in device mode.
• USB_TRANS_IN_LAST for the last IN transaction on endpoint zero in a sequence of IN transactions.
• USB_TRANS_SETUP for setup transactions on endpoint zero.
• USB_TRANS_STATUS for status results on endpoint zero.

Returns

This call returns 0 on success, or -1 if a transmission is already in progress.

References ASSERT, HWREGB, USB_CSRL0_TXRDY, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_O_CSRL0, and USB_TXCSRL1_TXRDY.

USBFIFOFlush()

void USBFIFOFlush	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32Flags
	)

Forces a flush of an endpoint's FIFO.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
ui32Flags	specifies if the IN or OUT endpoint is accessed.

This function forces the USB controller to flush out the data in the FIFO. The function can be called with either host or device controllers and requires the ui32Flags parameter be one of USB_EP_HOST_OUT, USB_EP_HOST_IN, USB_EP_DEV_OUT, or USB_EP_DEV_IN.

Returns

None.

References ASSERT, EP_OFFSET, HWREGB, USB_CSRH0_FLUSH, USB_CSRL0_RXRDY, USB_CSRL0_TXRDY, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_EP_DEV_IN, USB_EP_HOST_OUT, USB_O_CSRH0, USB_O_CSRL0, USB_O_RXCSRL1, USB_O_TXCSRL1, USB_RXCSRL1_FLUSH, USB_RXCSRL1_RXRDY, USB_TXCSRL1_FLUSH, and USB_TXCSRL1_TXRDY.

USBHostRequestIN()

void USBHostRequestIN	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint
	)

Schedules a request for an IN transaction on an endpoint in host mode.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.

This function schedules a request for an IN transaction. When the USB device being communicated with responds with the data, the data can be retrieved by calling USBEndpointDataGet() or via a DMA transfer.

Note

This function must only be called in host mode and only for IN endpoints.

Returns

None.

References ASSERT, EP_OFFSET, HWREGB, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_O_CSRL0, USB_O_RXCSRL1, and USB_RXCSRL1_REQPKT.

USBHostRequestINClear()

void USBHostRequestINClear	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint
	)

Clears a scheduled IN transaction for an endpoint in host mode.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.

This function clears a previously scheduled IN transaction if it is still pending. This function is used to safely disable any scheduled IN transactions if the endpoint specified by ui32Endpoint is reconfigured for communications with other devices.

Note

This function must only be called in host mode and only for IN endpoints.

Returns

None.

References ASSERT, EP_OFFSET, HWREGB, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_O_CSRL0, USB_O_RXCSRL1, and USB_RXCSRL1_REQPKT.

USBHostRequestStatus()

void USBHostRequestStatus

(

uint32_t

ui32Base

)

Issues a request for a status IN transaction on endpoint zero.

Parameters

ui32Base

specifies the USB module base address.

This function is used to cause a request for a status IN transaction from a device on endpoint zero. This function can only be used with endpoint zero as that is the only control endpoint that supports this ability. This function is used to complete the last phase of a control transaction to a device and an interrupt is signaled when the status packet has been received.

Note

This function must only be called in host mode.

Returns

None.

References ASSERT, HWREGB, USB_CSRL0_REQPKT, USB_CSRL0_STATUS, and USB_O_CSRL0.

USBHostAddrSet()

void USBHostAddrSet	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32Addr,
		uint32_t	ui32Flags
	)

Sets the functional address for the device that is connected to an endpoint in host mode.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
ui32Addr	is the functional address for the controller to use for this endpoint.
ui32Flags	determines if this is an IN or an OUT endpoint.

This function configures the functional address for a device that is using this endpoint for communication. This ui32Addr parameter is the address of the target device that this endpoint is communicating with. The ui32Flags parameter indicates if the IN or OUT endpoint is set.

Note

This function must only be called in host mode.

Returns

None.

References ASSERT, HWREGB, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_EP_HOST_OUT, and USB_O_TXFUNCADDR0.

USBHostAddrGet()

uint32_t USBHostAddrGet	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32Flags
	)

Gets the current functional device address for an endpoint.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
ui32Flags	determines if this is an IN or an OUT endpoint.

This function returns the current functional address that an endpoint is using to communicate with a device. The ui32Flags parameter determines if the IN or OUT endpoint's device address is returned.

Note

This function must only be called in host mode.

Returns

Returns the current function address being used by an endpoint.

References ASSERT, HWREGB, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_EP_HOST_OUT, and USB_O_TXFUNCADDR0.

USBHostHubAddrSet()

void USBHostHubAddrSet	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32Addr,
		uint32_t	ui32Flags
	)

Sets the hub address for the device that is connected to an endpoint.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
ui32Addr	is the hub address and port for the device using this endpoint. The hub address must be defined in bits 0 through 6 with the port number in bits 8 through 14.
ui32Flags	determines if this is an IN or an OUT endpoint.

This function configures the hub address for a device that is using this endpoint for communication. The ui32Flags parameter determines if the device address for the IN or the OUT endpoint is configured by this call and sets the speed of the downstream device. Valid values are one of USB_EP_HOST_OUT or USB_EP_HOST_IN optionally ORed with USB_EP_SPEED_LOW.

Note

This function must only be called in host mode.

Returns

None.

References ASSERT, HWREGB, HWREGH, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_EP_HOST_OUT, USB_EP_SPEED_FULL, USB_EP_SPEED_HIGH, USB_O_TXHUBADDR0, USB_O_TYPE0, USB_TYPE0_SPEED_FULL, USB_TYPE0_SPEED_HIGH, and USB_TYPE0_SPEED_LOW.

USBHostHubAddrGet()

uint32_t USBHostHubAddrGet	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32Flags
	)

Gets the current device hub address for this endpoint.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint to access.
ui32Flags	determines if this is an IN or an OUT endpoint.

This function returns the current hub address that an endpoint is using to communicate with a device. The ui32Flags parameter determines if the device address for the IN or OUT endpoint is returned.

Note

This function must only be called in host mode.

Returns

This function returns the current hub address being used by an endpoint.

References ASSERT, HWREGB, USB_EP_0, USB_EP_1, USB_EP_2, USB_EP_3, USB_EP_4, USB_EP_5, USB_EP_6, USB_EP_7, USB_EP_HOST_OUT, and USB_O_TXHUBADDR0.

USBHostPwrConfig()

void USBHostPwrConfig	(	uint32_t	ui32Base,
		uint32_t	ui32Flags
	)

Sets the configuration for USB power fault.

Parameters

ui32Base	specifies the USB module base address.
ui32Flags	specifies the configuration of the power fault.

This function controls how the USB controller uses its external power control pins (USBnPFLT and USBnEPEN). The flags specify the power fault level sensitivity, the power fault action, and the power enable level and source.

One of the following can be selected as the power fault level sensitivity:

• USB_HOST_PWRFLT_LOW - An external power fault is indicated by the pin being driven low.
• USB_HOST_PWRFLT_HIGH - An external power fault is indicated by the pin being driven high.

One of the following can be selected as the power fault action:

• USB_HOST_PWRFLT_EP_NONE - No automatic action when power fault detected.
• USB_HOST_PWRFLT_EP_TRI - Automatically tri-state the USBnEPEN pin on a power fault.
• USB_HOST_PWRFLT_EP_LOW - Automatically drive USBnEPEN pin low on a power fault.
• USB_HOST_PWRFLT_EP_HIGH - Automatically drive USBnEPEN pin high on a power fault.

One of the following can be selected as the power enable level and source:

• USB_HOST_PWREN_MAN_LOW - USBnEPEN is driven low by the USB controller when USBHostPwrEnable() is called.
• USB_HOST_PWREN_MAN_HIGH - USBnEPEN is driven high by the USB controller when USBHostPwrEnable() is called.
• USB_HOST_PWREN_AUTOLOW - USBnEPEN is driven low by the USB controller automatically if USBOTGSessionRequest() has enabled a session.
• USB_HOST_PWREN_AUTOHIGH - USBnEPEN is driven high by the USB controller automatically if USBOTGSessionRequest() has enabled a session.

When using the VBUS glitch filter, the USB_HOST_PWREN_FILTER can be addded to ignore small, short drops in VBUS level caused by high power consumption. This feature is mainly used to avoid causing VBUS errors caused by devices with high in-rush current.

Returns

None.

References ASSERT, HWREG, HWREGH, USB_EPC_EPEN_M, USB_EPC_PFLTACT_M, USB_EPC_PFLTAEN, USB_EPC_PFLTSEN_HIGH, USB_HOST_PWREN_FILTER, USB_O_EPC, and USB_O_VDC.

USBHostPwrFaultEnable()

void USBHostPwrFaultEnable

(

uint32_t

ui32Base

)

Enables power fault detection.

Parameters

ui32Base

specifies the USB module base address.

This function enables power fault detection in the USB controller. If the USBnPFLT pin is not in use, this function must not be used.

Note

This function must only be called in host mode.

Returns

None.

References ASSERT, HWREGH, USB_EPC_PFLTEN, and USB_O_EPC.

USBHostPwrFaultDisable()

void USBHostPwrFaultDisable

(

uint32_t

ui32Base

)

Disables power fault detection.

Parameters

ui32Base

specifies the USB module base address.

This function disables power fault detection in the USB controller.

Note

This function must only be called in host mode.

Returns

None.

References ASSERT, HWREGH, USB_EPC_PFLTEN, and USB_O_EPC.

USBHostPwrEnable()

void USBHostPwrEnable

(

uint32_t

ui32Base

)

Enables the external power pin.

Parameters

ui32Base

specifies the USB module base address.

This function enables the USBnEPEN signal, which enables an external power supply in host mode operation.

Note

This function must only be called in host mode.

Returns

None.

References ASSERT, HWREGH, USB_EPC_EPENDE, and USB_O_EPC.

USBHostPwrDisable()

void USBHostPwrDisable

(

uint32_t

ui32Base

)

Disables the external power pin.

Parameters

ui32Base

specifies the USB module base address.

This function disables the USBnEPEN signal, which disables an external power supply in host mode operation.

Note

This function must only be called in host mode.

Returns

None.

References ASSERT, HWREGH, USB_EPC_EPENDE, and USB_O_EPC.

USBFrameNumberGet()

uint32_t USBFrameNumberGet

(

uint32_t

ui32Base

)

Gets the current frame number.

Parameters

ui32Base

specifies the USB module base address.

This function returns the last frame number received.

Returns

The last frame number received.

References ASSERT, HWREGH, and USB_O_FRAME.

USBOTGSessionRequest()

void USBOTGSessionRequest	(	uint32_t	ui32Base,
		bool	bStart
	)

Starts or ends a session.

Parameters

ui32Base	specifies the USB module base address.
bStart	specifies if this call starts or ends a session.

This function is used in OTG mode to start a session request or end a session. If the bStart parameter is set to true, then this function starts a session and if it is false it ends a session.

Returns

None.

References ASSERT, HWREGB, USB_DEVCTL_SESSION, and USB_O_DEVCTL.

USBFIFOAddrGet()

uint32_t USBFIFOAddrGet	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint
	)

Returns the absolute FIFO address for a specified endpoint.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	specifies which endpoint's FIFO address to return.

This function returns the actual physical address of the FIFO. This address is needed when the USB is going to be used with the uDMA controller and the source or destination address must be set to the physical FIFO address for a specified endpoint. This function can also be used to provide the physical address to manually read data from an endpoints FIFO.

Returns

None.

References USB_O_FIFO0.

USBModeGet()

uint32_t USBModeGet

(

uint32_t

ui32Base

)

Returns the current operating mode of the controller.

Parameters

ui32Base

specifies the USB module base address.

This function returns the current operating mode on USB controllers with OTG or Dual mode functionality.

For OTG controllers:

The function returns one of the following values on OTG controllers:

USB_OTG_MODE_ASIDE_HOST indicates that the controller is in host mode on the A-side of the cable.

USB_OTG_MODE_ASIDE_DEV indicates that the controller is in device mode on the A-side of the cable.

USB_OTG_MODE_BSIDE_HOST indicates that the controller is in host mode on the B-side of the cable.

USB_OTG_MODE_BSIDE_DEV indicates that the controller is in device mode on the B-side of the cable. If an OTG session request is started with no cable in place, this mode is the default.

USB_OTG_MODE_NONE indicates that the controller is not attempting to determine its role in the system.

For Dual Mode controllers:

The function returns one of the following values:

USB_DUAL_MODE_HOST indicates that the controller is acting as a host.

USB_DUAL_MODE_DEVICE indicates that the controller acting as a device.

USB_DUAL_MODE_NONE indicates that the controller is not active as either a host or device.

Returns

Returns USB_OTG_MODE_ASIDE_HOST, USB_OTG_MODE_ASIDE_DEV, USB_OTG_MODE_BSIDE_HOST, USB_OTG_MODE_BSIDE_DEV, USB_OTG_MODE_NONE, USB_DUAL_MODE_HOST, USB_DUAL_MODE_DEVICE, or USB_DUAL_MODE_NONE.

References ASSERT, HWREGB, USB_DEVCTL_DEV, USB_DEVCTL_HOST, USB_DEVCTL_SESSION, USB_DEVCTL_VBUS_M, and USB_O_DEVCTL.

USBHostMode()

void USBHostMode

(

uint32_t

ui32Base

)

Change the mode of the USB controller to host.

Parameters

ui32Base

specifies the USB module base address.

This function changes the mode of the USB controller to host mode.

Note

This function must only be called on microcontrollers that support OTG operation.

Returns

None.

References ASSERT, HWREGB, USB_GPCS_DEVMODOTG, and USB_O_GPCS.

USBDevMode()

void USBDevMode

(

uint32_t

ui32Base

)

Change the mode of the USB controller to device.

Parameters

ui32Base

specifies the USB module base address.

This function changes the mode of the USB controller to device mode.

Returns

None.

References ASSERT, HWREGB, USB_GPCS_DEVMOD, USB_GPCS_DEVMODOTG, and USB_O_GPCS.

USBOTGMode()

void USBOTGMode

(

uint32_t

ui32Base

)

Changes the mode of the USB controller to OTG.

Parameters

ui32Base

specifies the USB module base address.

This function changes the mode of the USB controller to OTG mode. This function is only valid on microcontrollers that have the OTG capabilities.

Returns

None.

References ASSERT, HWREGB, and USB_O_GPCS.

USBModeConfig()

void USBModeConfig	(	uint32_t	ui32Base,
		uint32_t	ui32Mode
	)

Change the operating mode of the USB controller.

Parameters

ui32Base	specifies the USB module base address.
ui32Mode	specifies the operating mode of the USB OTG pins.

This function changes the operating modes of the USB controller. When operating in full OTG mode, the USB controller uses the VBUS and ID pins to detect mode and voltage changes. While these pins are primarily used in OTG mode, they can also affect the operation of host and device modes. In device mode, the USB controller can be configured to monitor or ignore VBUS. Monitoring VBUS allows the controller to determine if it has been disconnected from the host. In host mode, the USB controller uses the VBUS pin to detect loss of VBUS caused by excessive power draw due to a drop in the VBUS voltage. This call takes the place of USBHostMode(), USBDevMode(), and USBOTGMode(). The ui32Mode value should be one of the following values:

• USB_MODE_OTG enables operating in full OTG mode, VBUS and ID are used by the controller.
• USB_MODE_HOST enables operating only as a host with no monitoring of VBUS or ID pins.
• USB_MODE_HOST_VBUS enables operating only as a host with monitoring of VBUS pin. This configuration enables detection of VBUS droop while still forcing host mode.
• USB_MODE_DEVICE enables operating only as a device with no monitoring of VBUS or ID pins.
• USB_MODE_DEVICE_VBUS enables operating only as a device with monitoring of VBUS pin. This configuration enables disconnect detection while still forcing device mode.

Example: Force device mode but allow monitoring of the USB VBUS pin.

//! //
//! // Force device mode but allow monitoring of VBUS for disconnect.
//! //
//! USBModeConfig(USB_MODE_DEVICE_VBUS);
//! 

\return None.  

References ASSERT, HWREG, and USB_O_GPCS.

USBPHYPowerOff()

void USBPHYPowerOff

(

uint32_t

ui32Base

)

Powers off the internal USB PHY.

Parameters

ui32Base

specifies the USB module base address.

This function powers off the internal USB PHY, reducing the current consumption of the device. While in the powered-off state, the USB controller is unable to operate.

Returns

None.

References HWREGB, USB_O_POWER, and USB_POWER_PWRDNPHY.

USBPHYPowerOn()

void USBPHYPowerOn

(

uint32_t

ui32Base

)

Powers on the internal USB PHY.

Parameters

ui32Base

specifies the USB module base address.

This function powers on the internal USB PHY, enabling it return to normal operation. By default, the PHY is powered on, so this function must only be called if USBPHYPowerOff() has previously been called.

Returns

None.

References HWREGB, USB_O_POWER, and USB_POWER_PWRDNPHY.

USBEndpointPacketCountSet()

void USBEndpointPacketCountSet	(	uint32_t	ui32Base,
		uint32_t	ui32Endpoint,
		uint32_t	ui32Count
	)

Sets the number of packets to request when transferring multiple bulk packets.

Parameters

ui32Base	specifies the USB module base address.
ui32Endpoint	is the endpoint index to target for this write.
ui32Count	is the number of packets to request.

This function sets the number of consecutive bulk packets to request when transferring multiple bulk packets with DMA.

Returns

None.

References HWREG, USB_O_RQPKTCOUNT1, and USBEPToIndex.

USBNumEndpointsGet()

uint32_t USBNumEndpointsGet

(

uint32_t

ui32Base

)

Returns the number of USB endpoint pairs on the device.

Parameters

ui32Base

specifies the USB module base address.

This function returns the number of endpoint pairs supported by the USB controller corresponding to the passed base address. The value returned is the number of IN or OUT endpoints available and does not include endpoint 0 (the control endpoint). For example, if 15 is returned, there are 15 IN and 15 OUT endpoints available in addition to endpoint 0.

Returns

Returns the number of IN or OUT endpoints available.

References HWREGB, USB_EPINFO_TXEP_M, and USB_O_EPINFO.

USBClockEnable()

void USBClockEnable	(	uint32_t	ui32Base,
		uint32_t	ui32Div,
		uint32_t	ui32Flags
	)

Configures and enables the clocking to the USB controller's PHY.

Parameters

ui32Base	specifies the USB module base address.
ui32Div	specifies the divider for the internal USB PHY clock.
ui32Flags	configures the internal USB PHY clock and specifies the clock source for a ULPI-connected PHY.

This function configures and enables the USB PHY clock. In addition, for systems that use a ULPI-connected external PHY, this function configures the source for the PHY clock. The ui32Flags parameter specifies the clock source with the following values:

• USB_CLOCK_INTERNAL uses the internal PLL combined with the ui32Div value to generate the USB clock that is used by the internal USB PHY. In addition, when using an external ULPI-connected USB PHY, the specified clock is output on the USB0CLK pin.
• USB_CLOCK_EXTERNAL specifies that USB0CLK is an input from the ULPI-connected external PHY.

The ui32Div parameter is used to specify a divider for the internal clock if the USB_CLOCK_INTERNAL is specified and is ignored if USB_CLOCK_EXTERNAL is specified. When the USB_CLOCK_INTERNAL is specified, the ui32Div value must be set so that the PLL_VCO/ui32Div results in a 60-MHz clock.

Example: Enable the USB clock with a 480-MHz PLL setting.

//! //
//! // Enable the USB clock using a 480-MHz PLL.
//! // (480-MHz/8 = 60-MHz)
//! //
//! USBClockEnable(USB0_BASE, 8, USB_CLOCK_INTERNAL);
//! 

\return None.  

References ASSERT, HWREG, and USB_O_CC.

USBClockDisable()

void USBClockDisable

(

uint32_t

ui32Base

)

Disables the clocking of the USB controller's PHY.

Parameters

ui32Base

specifies the USB module base address.

This function disables the USB PHY clock. This function should not be called in applications where the USB controller is used.

Example: Disable the USB PHY clock input.

//! //
//! // Disable clocking of the USB controller's PHY.
//! //
//! USBClockDisable(USB0_BASE);
//! 

\return None.  

References ASSERT, HWREG, and USB_O_CC.