AM261x MCU+ SDK: APIs for Synopsys driver

| AM261x MCU+ SDK 26.00.00 |

Sub Modules | Files | Data Structures | Functions | Enumerations | Macros
APIs for Synopsys driver
APIs for SOC Specific Device Drivers » APIs for USB

## Introduction

This module has APIs for USB Synopsis IP device driver.

## Sub Modules
| Control Endpoint 0 API Routines
| Endpoint API Routines
| Function Driver callback routines
| Function Driver notification routines
| Initialization API Routines
| Miscellaneous API Routines
| TRB API Routines

## Files
file | pcd.h
| This file contains the structures, constants, and interfaces for the Perpherial Contoller Driver (PCD).

## Data Structures
struct | dwc_req_t
| Structure representing a USB transfer request. More...
struct | dwc_usb3_pcd_req_t
| DWC_usb3 request structure. More...
struct | dwc_ep_t
| The `dwc_ep` structure represents the state of a single EP when acting in device mode. It contains the data items needed for an EP to be activated and transfer packets. More...
union | dwc_setup_pkt_t
| Buffer used to store the SETUP packet for EP0. More...
struct | dwc_usb3_pcd_ep_t
| PCD Endpoint structure. This structure represents an endpoint (EP) in the Peripheral Controller Driver (PCD). More...
struct | dwc_hiber_scratchpad_array
| Structure representing an array of hibernation scratchpad DMA addresses. More...
struct | dwc_usb3_pcd_t
| DWC_usb3 PCD Structure. This structure encapsulates the data for the dwc_usb3 PCD. More...

## Functions
void | dwc_usb3_stop_all_xfers (dwc_usb3_pcd_t *pcd)
| Stop any active xfers on the non-EP0 endpoints. More...
void | dwc_usb3_complete_request (dwc_usb3_pcd_t *pcd, dwc_usb3_pcd_ep_t *ep, u32 event)
| This routine handles non-EP0 transfers. More...
dwc_usb3_pcd_ep_t * | dwc_usb3_get_out_ep (dwc_usb3_pcd_t *pcd, u32 ep_num)
| This routine returns a pointer to Out EP struct with number ep_num. More...
dwc_usb3_pcd_ep_t * | dwc_usb3_get_in_ep (dwc_usb3_pcd_t *pcd, u32 ep_num)
| This routine returns a pointer to In EP struct with number ep_num. More...
void | dwc_usb3_handle_ep_intr (dwc_usb3_pcd_t *pcd, u32 physep, u32 event)
| This interrupt indicates that an EP has a pending interrupt. More...
int | dwc_usb3_handle_dev_intr (dwc_usb3_pcd_t *pcd, u32 event)
| PCD interrupt handler. More...
void | dwc_usb3_handle_connect_done_intr (dwc_usb3_pcd_t *pcd)
| This interrupt occurs when a Connect Done is detected. Read the device status register and set the device speed in the data structure. Set up EP0 to receive SETUP packets. More...
void | dwc_enter_hibernation (dwc_usb3_pcd_t *pcd, int save_state)
| This routine sends the core into hibernation, saving the core's runtime state if requested. More...
void | dwc_exit_hibernation_after_connect (dwc_usb3_pcd_t *pcd, int connected)
| This routine finishes exiting from hibernation once the device is connected. More...
int | dwc_exit_hibernation (dwc_usb3_pcd_t *pcd, int restore_state)
| This routine wakes the core from hibernation. More...
int | dwc_usb3_handle_pme_intr (struct dwc_usb3_device *dev)
void | dwc_usb3_power_ctl (struct dwc_usb3_device *dev, int on)
void | dwc_usb3_task_schedule (struct tasklet_struct *tasklet)
| OS-specific routines called from core code. More...

## Enumerations
enum | ep0state_e { EP0_IDLE, EP0_IN_DATA_PHASE, EP0_OUT_DATA_PHASE, EP0_IN_WAIT_GADGET, EP0_OUT_WAIT_GADGET, EP0_IN_WAIT_NRDY, EP0_OUT_WAIT_NRDY, EP0_IN_STATUS_PHASE, EP0_OUT_STATUS_PHASE, EP0_STALL }
| Enumeration representing the various states of Endpoint 0 (EP0). More...
enum | pcdstate_e { DWC_STATE_UNCONNECTED, DWC_STATE_DEFAULT, DWC_STATE_ADDRESSED, DWC_STATE_CONFIGURED }
| Enumeration representing the various states of the PCD. More...

## Macros
#define | DWC_MAX_TX_FIFOS 16
| Maximum number of Tx FIFOs. Depends on the RTL configuration. No way to probe the value at runtime. More...
#define | DWC_MAX_PHYS_EP 32
| Maximum number of physical EPs. Depends on the RTL configuration. No way to probe the value at runtime. More...
#define | DWC_MAX_DATA_BUFS 13
| Maximum number of data buffers per TRB. OS/application specific. More...
#define | DWC_MAX_EPS 5U
| Maximum number of EPs, defined by USB spec. More...
#define | DWC_MAX_EP0_SIZE 512
| Maxpacket size for EP0, defined by USB3 spec. More...
#define | DWC_MAX_PACKET_SIZE 1024
| Maxpacket size for any EP, defined by USB3 spec. More...
#define | dwc_usb3_pcd_ep_to_pcd(pcd_ep) ((pcd_ep)->dwc_ep.pcd)
| Macro to retrieve the PCD structure from a PCD endpoint. More...
#define | dwc_usb3_pcd_ep_num(pcd_ep) ((pcd_ep)->dwc_ep.num)
| Macro to retrieve the endpoint number from a PCD endpoint. More...
#define | dwc_usb3_pcd_ep_type(pcd_ep) ((pcd_ep)->dwc_ep.type)
| Macro to retrieve the endpoint type from a PCD endpoint. More...
#define | dwc_usb3_pcd_ep_is_in(pcd_ep) ((pcd_ep)->dwc_ep.is_in)
| Macro to check if the endpoint direction is IN. More...
#define | dwc_usb3_ep0_setup_desc(pcd) (pcd)->ep0_setup_desc
| Macro to retrieve the descriptor for SETUP packets for EP0. More...
#define | dwc_usb3_ep0_setup_desc_dma(pcd) (pcd)->ep0_setup_desc_dma
| Macro to retrieve the DMA address of the SETUP packet descriptor for EP0. More...
#define | dwc_usb3_ep0_out_desc(pcd) (pcd)->ep0_out_desc
| Macro to retrieve the descriptor for Data Out or Status Out phases for EP0. More...
#define | dwc_usb3_ep0_out_desc_dma(pcd) (pcd)->ep0_out_desc_dma
| Macro to retrieve the DMA address of the Data Out or Status Out descriptor for EP0. More...
#define | dwc_usb3_ep0_in_desc(pcd) (pcd)->ep0_in_desc
| Macro to retrieve the descriptor for Data In or Status In phases for EP0. More...
#define | dwc_usb3_ep0_in_desc_dma(pcd) (pcd)->ep0_in_desc_dma
| Macro to retrieve the DMA address of the Data In or Status In descriptor for EP0. More...
#define | dwc_usb3_ep0_setup_pkt(pcd) (pcd)->ep0_setup_pkt
| Macro to retrieve the SETUP packet buffer for EP0. More...
#define | dwc_usb3_ep0_setup_pkt_dma(pcd) (pcd)->ep0_setup_pkt_dma
| Macro to retrieve the DMA address of the SETUP packet buffer for EP0. More...

## Macro Definition Documentation

## ◆ DWC_MAX_TX_FIFOS

#define DWC_MAX_TX_FIFOS 16

Maximum number of Tx FIFOs. Depends on the RTL configuration. No way to probe the value at runtime.

## ◆ DWC_MAX_PHYS_EP

#define DWC_MAX_PHYS_EP 32

Maximum number of physical EPs. Depends on the RTL configuration. No way to probe the value at runtime.

## ◆ DWC_MAX_DATA_BUFS

#define DWC_MAX_DATA_BUFS 13

Maximum number of data buffers per TRB. OS/application specific.

## ◆ DWC_MAX_EPS

#define DWC_MAX_EPS 5U

Maximum number of EPs, defined by USB spec.

## ◆ DWC_MAX_EP0_SIZE

#define DWC_MAX_EP0_SIZE 512

Maxpacket size for EP0, defined by USB3 spec.

## ◆ DWC_MAX_PACKET_SIZE

#define DWC_MAX_PACKET_SIZE 1024

Maxpacket size for any EP, defined by USB3 spec.

## ◆ dwc_usb3_pcd_ep_to_pcd

#define dwc_usb3_pcd_ep_to_pcd | ( |  | pcd_ep | ) | ((pcd_ep)->dwc_ep.pcd)

Macro to retrieve the PCD structure from a PCD endpoint.

Parameters

  pcd_ep | Pointer to the PCD endpoint structure.

Returns
  Pointer to the associated PCD structure.

## ◆ dwc_usb3_pcd_ep_num

#define dwc_usb3_pcd_ep_num | ( |  | pcd_ep | ) | ((pcd_ep)->dwc_ep.num)

Macro to retrieve the endpoint number from a PCD endpoint.

Parameters

  pcd_ep | Pointer to the PCD endpoint structure.

Returns
  Endpoint number.

## ◆ dwc_usb3_pcd_ep_type

#define dwc_usb3_pcd_ep_type | ( |  | pcd_ep | ) | ((pcd_ep)->dwc_ep.type)

Macro to retrieve the endpoint type from a PCD endpoint.

Parameters

  pcd_ep | Pointer to the PCD endpoint structure.

Returns
  Endpoint type.

## ◆ dwc_usb3_pcd_ep_is_in

#define dwc_usb3_pcd_ep_is_in | ( |  | pcd_ep | ) | ((pcd_ep)->dwc_ep.is_in)

Macro to check if the endpoint direction is IN.

Parameters

  pcd_ep | Pointer to the PCD endpoint structure.

Returns
  True if the endpoint direction is IN, false otherwise.

## ◆ dwc_usb3_ep0_setup_desc

#define dwc_usb3_ep0_setup_desc | ( |  | pcd | ) | (pcd)->ep0_setup_desc

Macro to retrieve the descriptor for SETUP packets for EP0.

Parameters

  pcd | Pointer to the PCD structure.

Returns
  Pointer to the SETUP packet descriptor.

## ◆ dwc_usb3_ep0_setup_desc_dma

#define dwc_usb3_ep0_setup_desc_dma | ( |  | pcd | ) | (pcd)->ep0_setup_desc_dma

Macro to retrieve the DMA address of the SETUP packet descriptor for EP0.

Parameters

  pcd | Pointer to the PCD structure.

Returns
  DMA address of the SETUP packet descriptor.

## ◆ dwc_usb3_ep0_out_desc

#define dwc_usb3_ep0_out_desc | ( |  | pcd | ) | (pcd)->ep0_out_desc

Macro to retrieve the descriptor for Data Out or Status Out phases for EP0.

Parameters

  pcd | Pointer to the PCD structure.

Returns
  Pointer to the Data Out or Status Out descriptor.

## ◆ dwc_usb3_ep0_out_desc_dma

#define dwc_usb3_ep0_out_desc_dma | ( |  | pcd | ) | (pcd)->ep0_out_desc_dma

Macro to retrieve the DMA address of the Data Out or Status Out descriptor for EP0.

Parameters

  pcd | Pointer to the PCD structure.

Returns
  DMA address of the Data Out or Status Out descriptor.

## ◆ dwc_usb3_ep0_in_desc

#define dwc_usb3_ep0_in_desc | ( |  | pcd | ) | (pcd)->ep0_in_desc

Macro to retrieve the descriptor for Data In or Status In phases for EP0.

Parameters

  pcd | Pointer to the PCD structure.

Returns
  Pointer to the Data In or Status In descriptor.

## ◆ dwc_usb3_ep0_in_desc_dma

#define dwc_usb3_ep0_in_desc_dma | ( |  | pcd | ) | (pcd)->ep0_in_desc_dma

Macro to retrieve the DMA address of the Data In or Status In descriptor for EP0.

Parameters

  pcd | Pointer to the PCD structure.

Returns
  DMA address of the Data In or Status In descriptor.

## ◆ dwc_usb3_ep0_setup_pkt

#define dwc_usb3_ep0_setup_pkt | ( |  | pcd | ) | (pcd)->ep0_setup_pkt

Macro to retrieve the SETUP packet buffer for EP0.

Parameters

  pcd | Pointer to the PCD structure.

Returns
  Pointer to the SETUP packet buffer.

## ◆ dwc_usb3_ep0_setup_pkt_dma

#define dwc_usb3_ep0_setup_pkt_dma | ( |  | pcd | ) | (pcd)->ep0_setup_pkt_dma

Macro to retrieve the DMA address of the SETUP packet buffer for EP0.

Parameters

  pcd | Pointer to the PCD structure.

Returns
  DMA address of the SETUP packet buffer.

## Enumeration Type Documentation

## ◆ ep0state_e

enum ep0state_e

Enumeration representing the various states of Endpoint 0 (EP0).

Enumerator
EP0_IDLE | Idle state waiting for host to initiate transfer
EP0_IN_DATA_PHASE | IN data phase of a control transfer
EP0_OUT_DATA_PHASE | OUT data phase of a control transfer
EP0_IN_WAIT_GADGET | Waiting for the gadget to complete the IN transfer
EP0_OUT_WAIT_GADGET | Waiting for the gadget to complete the OUT transfer
EP0_IN_WAIT_NRDY | Waiting for the IN not ready event from the core
EP0_OUT_WAIT_NRDY | Waiting for the OUT not ready event from the core
EP0_IN_STATUS_PHASE | IN status phase of a control transfer
EP0_OUT_STATUS_PHASE | OUT status phase of a control transfer
EP0_STALL | Stall state, waiting for the host to clear the stall

## ◆ pcdstate_e

enum pcdstate_e

Enumeration representing the various states of the PCD.

Enumerator
DWC_STATE_UNCONNECTED | Device not connected to Host
DWC_STATE_DEFAULT | Device in default state
DWC_STATE_ADDRESSED | Device in addressed state
DWC_STATE_CONFIGURED | Device in configured state

## Function Documentation

## ◆ dwc_usb3_stop_all_xfers()

void dwc_usb3_stop_all_xfers | ( | dwc_usb3_pcd_t * | pcd | ) |

Stop any active xfers on the non-EP0 endpoints.

Parameters

  pcd | Programming view of DWC_usb3 peripheral controller.

## ◆ dwc_usb3_complete_request()

void dwc_usb3_complete_request | ( | dwc_usb3_pcd_t * | pcd,
|  | dwc_usb3_pcd_ep_t * | ep,
|  | u32 | event
| ) |  |

This routine handles non-EP0 transfers.

This routine gets the request corresponding to the completed transfer and then calls the core routine for handling the completion.

Parameters

  pcd | Programming view of DWC_usb3 peripheral controller.
  ep | The EP to complete the request on.
  event | The event associated with the transfer.

## ◆ dwc_usb3_get_out_ep()

dwc_usb3_pcd_ep_t* dwc_usb3_get_out_ep | ( | dwc_usb3_pcd_t * | pcd,
|  | u32 | ep_num
| ) |  |

This routine returns a pointer to Out EP struct with number ep_num.

Parameters

  pcd | Programming view of DWC_usb3 peripheral controller.
  ep_num | The endpoint number.

Returns
  Pointer to the Out EP struct.

## ◆ dwc_usb3_get_in_ep()

dwc_usb3_pcd_ep_t* dwc_usb3_get_in_ep | ( | dwc_usb3_pcd_t * | pcd,
|  | u32 | ep_num
| ) |  |

This routine returns a pointer to In EP struct with number ep_num.

Parameters

  pcd | Programming view of DWC_usb3 peripheral controller.
  ep_num | The endpoint number.

Returns
  Pointer to the In EP struct.

## ◆ dwc_usb3_handle_ep_intr()

void dwc_usb3_handle_ep_intr | ( | dwc_usb3_pcd_t * | pcd,
|  | u32 | physep,
|  | u32 | event
| ) |  |

This interrupt indicates that an EP has a pending interrupt.

Parameters

  pcd | Programming view of DWC_usb3 peripheral controller.
  physep | The physical endpoint number.
  event | The event associated with the transfer.

## ◆ dwc_usb3_handle_dev_intr()

int dwc_usb3_handle_dev_intr | ( | dwc_usb3_pcd_t * | pcd,
|  | u32 | event
| ) |  |

PCD interrupt handler.

The PCD handles the device interrupts. Many conditions can cause a device interrupt. When an interrupt occurs, the device interrupt service routine determines the cause of the interrupt and dispatches handling to the appropriate routine.

Parameters

  pcd | Programming view of DWC_usb3 peripheral controller.
  event | The event associated with the transfer.

Returns
  0 if no further action is needed, 1 if the device should enter

## ◆ dwc_usb3_handle_connect_done_intr()

void dwc_usb3_handle_connect_done_intr | ( | dwc_usb3_pcd_t * | pcd | ) |

This interrupt occurs when a Connect Done is detected. Read the device status register and set the device speed in the data structure. Set up EP0 to receive SETUP packets.

Parameters

  pcd | Programming view of DWC_usb3 peripheral controller.

## ◆ dwc_enter_hibernation()

void dwc_enter_hibernation | ( | dwc_usb3_pcd_t * | pcd,
|  | int | save_state
| ) |  |

This routine sends the core into hibernation, saving the core's runtime state if requested.

Parameters

  pcd | Programming view of DWC_usb3 peripheral controller.
  save_state | If non-zero, the core's runtime state is saved.

## ◆ dwc_exit_hibernation_after_connect()

void dwc_exit_hibernation_after_connect | ( | dwc_usb3_pcd_t * | pcd,
|  | int | connected
| ) |  |

This routine finishes exiting from hibernation once the device is connected.

Parameters

  pcd | Programming view of DWC_usb3 peripheral controller.
  connected | If non-zero, the device is already connected to the host.

## ◆ dwc_exit_hibernation()

int dwc_exit_hibernation | ( | dwc_usb3_pcd_t * | pcd,
|  | int | restore_state
| ) |  |

This routine wakes the core from hibernation.

Parameters

  pcd | Programming view of DWC_usb3 peripheral controller.
  restore_state | If non-zero, the core's runtime state is restored.

Returns
  0 on success, 1 on failure.

## ◆ dwc_usb3_handle_pme_intr()

int dwc_usb3_handle_pme_intr | ( | struct dwc_usb3_device * | dev | ) |

## ◆ dwc_usb3_power_ctl()

void dwc_usb3_power_ctl | ( | struct dwc_usb3_device * | dev,
|  | int | on
| ) |  |

## ◆ dwc_usb3_task_schedule()

void dwc_usb3_task_schedule | ( | struct tasklet_struct * | tasklet | ) |

OS-specific routines called from core code.

Parameters

  tasklet | Pointer to the tasklet structure to be scheduled.