SAMV71 Xplained Ultra Software Package 1.4

USB Host Driver (UHD)
[USB Stack Host]

Collaboration diagram for USB Host Driver (UHD):

Data Structures

struct  uhd_ctrl_request_t
 Structure to store the high level setup request. More...
struct  USBH_PipeJob_t
 Structure definition to store registered jobs on a pipe. More...

Defines

#define UHD_ISOCHRONOUS_NB_BANK   2
#define UHD_BULK_NB_BANK   2
#define UHD_INTERRUPT_NB_BANK   1

Typedefs

typedef void(* uhd_callback_reset_t )(void)
 End of reset callback function type. Registered by uhd_send_reset() Callback called when reset event is completed.
typedef bool(* uhd_callback_setup_run_t )(uint8_t add, uint8_t **payload, uint16_t *payload_size)
 Data setup transfer callback function type. Registered by USBH_HAL_SetupReq() Called during DATA phase when the (payload) buffer is full or empty. Then the setup request is halted. A new buffer can be provided to continue the DATA phase or abort DATA phase.
typedef void(* uhd_callback_setup_end_t )(uint8_t add, USBH_XfrStatus_t status, uint16_t payload_trans)
 End of setup callback function type. Registered by USBH_HAL_SetupReq() Called when the setup request is completed.
typedef void(* uhd_callback_trans_t )(uint8_t add, uint8_t ep, USBH_XfrStatus_t status, uint32_t nb_transfered)
 End of transfer callback function type. Registered by USBH_HAL_RunEndpoint() Callback called by USB interrupt after data transfer or abort (reset,...).

Enumerations

enum  USBH_Speed_t { UHD_SPEED_LOW = 0, UHD_SPEED_FULL = 1, UHD_SPEED_HIGH = 2 }
 

Device speed.


enum  USBH_XfrStatus_t {
  UHD_TRANS_NOERROR = 0, UHD_TRANS_DISCONNECT, UHD_TRANS_CRC, UHD_TRANS_DT_MISMATCH,
  UHD_TRANS_STALL, UHD_TRANS_NOTRESPONDING, UHD_TRANS_PIDFAILURE, UHD_TRANS_TIMEOUT,
  UHD_TRANS_ABORTED
}
 

Endpoint transfer status The status field is updated after each transaction attempt, whether successful or not.

More...

Functions

void USBHS_Handler (void)
void USBH_HAL_EnableUsbHost (void)
 Enables the USB host mode Start the ID pin management if the ID pin is available.
void USBH_HAL_DisableUsb (bool b_id_stop)
 Disables the USB host mode.
USBH_Speed_t USBH_HAL_GetSpeed (void)
 Returns the speed of connected device.
uint16_t USBH_HAL_GetFrameNum (void)
 Returns the current Start Of Frame (SOF) number.
uint16_t USBH_HAL_GetMicroFrameNum (void)
 Returns the current micro start of frame number.
void USBH_HAL_Reset (uhd_callback_reset_t callback)
 Enables the Reset state on the USB line.
void USBH_HAL_Suspend (void)
 Enables the suspend state on the USB line. The SUSPEND state is enable when SOF are disabled on USB line.
bool USBH_HAL_IsSuspended (void)
 Test if the suspend state is enabled on the USB line.
void USBH_HAL_Resume (void)
 Enables the IDLE state on the USB line. The IDLE state is enable when SOF are present on USB line. A Downstream Resume signal can be sent.
bool USBH_HAL_SetupReq (uint8_t add, USBGenericRequest *req, uint8_t *payload, uint16_t payload_size, uhd_callback_setup_run_t callback_run, uhd_callback_setup_end_t callback_end)
 Add a setup request in the control endpoint setup queue. Note: Request timeout is 5s.

Power management



enum  uhd_uotghs_state_enum {
  UHD_STATE_OFF = 0, UHD_STATE_WAIT_ID_HOST = 1, UHD_STATE_NO_VBUS = 2, UHD_STATE_DISCONNECT = 3,
  UHD_STATE_SUSPEND = 4, UHD_STATE_IDLE = 5
}
 

States of USBHS interface.


Control endpoint low level management routine.

This function performs control endpoint management. It handles the SETUP/DATA/HANDSHAKE phases of a control transaction.



enum  uhd_ctrl_request_phase_t {
  UHD_CTRL_REQ_PHASE_SETUP = 0, UHD_CTRL_REQ_PHASE_DATA_OUT = 1, UHD_CTRL_REQ_PHASE_DATA_IN = 2, UHD_CTRL_REQ_PHASE_ZLP_IN = 3,
  UHD_CTRL_REQ_PHASE_ZLP_OUT = 4
}
 

Bit definitions to store setup request state machine.

More...
struct uhd_ctrl_request_tuhd_ctrl_request_first
 Entry points of setup request list.
struct uhd_ctrl_request_tuhd_ctrl_request_last
volatile uint16_t uhd_ctrl_request_timeout
 Remaining time for on-going setup request (No request on-going if equal 0).
uint16_t uhd_ctrl_nb_trans
 Number of transfered byte on DATA phase of current setup request.
uhd_ctrl_request_phase_t uhd_ctrl_request_phase

Endpoint Management

The following functions allow drivers to create and remove endpoints, as well as set, clear and query their "halted" and "wedged" states.



bool USBH_HAL_ConfigureControlPipe (uint8_t add, uint16_t ep_size)
 Configures and enables a control endpoint 0.
bool USBH_HAL_ConfigurePipe (uint8_t add, USBEndpointDescriptor *ep_desc)
 Configures and enables an endpoint.
void USBH_HAL_FreePipe (uint8_t add, uint8_t endp)
 Disables an endpoint or all endpoint of a device.
bool USBH_HAL_RunEndpoint (uint8_t add, uint8_t endp, bool b_shortpacket, uint8_t *buf, uint32_t buf_size, uint16_t timeout, uhd_callback_trans_t callback)
 Allows to receive or send data on an endpoint.
void USBH_HAL_AbortEndPoint (uint8_t add, uint8_t endp)
 Aborts an on-going transfer on an endpoint.

UHC callbacks to provide for UHD

The following callbacks are used by UHD.



void USBH_start (void)
 Starts the host mode.
void USBH_stop (bool b_id_stop)
 Stops the host mode.
void USBH_notify_connection (bool b_plug)
 Notify device connection or disconnection.
void USBH_notify_sof (bool b_micro)
 Notify each start of frame sent by driver.
void USBH_notify_resume (void)
 Notify that a resume bus occurs A resume can occur after a downstream or an upstream resume.

Detailed Description

USB dual role configuration

The defines UHD_ENABLE and UDD_ENABLE must be added in project to allow the USB low level (UHD) to manage or not the dual role (device and host).

USBHS Custom configuration

The following USBHS driver configuration must be defined in conf_usb_host.h file of the application.

UHD_USB_INT_LEVEL
Option to change the interrupt priority (0 to 15) by default 5 (recommended).

UHD_USB_INT_FUN
Option to fit interrupt function to what defined in exception table.

UHD_ISOCHRONOUS_NB_BANK
Feature to reduce or increase isochronous endpoints buffering (1 to 2). Default value 2.

UHD_BULK_NB_BANK
Feature to reduce or increase bulk endpoints buffering (1 to 2). Default value 2.

UHD_INTERRUPT_NB_BANK
Feature to reduce or increase interrupt endpoints buffering (1 to 2). Default value 1.

management

The USB driver is fully managed by interrupt and does not request periodic task. Thereby, the USB events use callbacks to transfer the information. The callbacks can be declared in static during compilation or dynamically during code execution.

mode management

The driver uses the sleepmgr service to manage the different sleep modes. The sleep mode depends on USB driver state (uhd_uotghs_state_enum).

The UHD driver provides a low-level abstraction of the host controller hardware. Most events coming from the hardware such as interrupts may cause the UHD performing function call in UHC and UHI.


Typedef Documentation

typedef void(* uhd_callback_setup_end_t)(uint8_t add, USBH_XfrStatus_t status, uint16_t payload_trans)

End of setup callback function type. Registered by USBH_HAL_SetupReq() Called when the setup request is completed.

Parameters:
add USB address of the setup request
status Transfer status
payload_trans Number of data transfered during DATA phase

Definition at line 147 of file USBHDriver.h.

typedef bool(* uhd_callback_setup_run_t)(uint8_t add, uint8_t **payload, uint16_t *payload_size)

Data setup transfer callback function type. Registered by USBH_HAL_SetupReq() Called during DATA phase when the (payload) buffer is full or empty. Then the setup request is halted. A new buffer can be provided to continue the DATA phase or abort DATA phase.

Parameters:
add USB address of the setup request
payload To return the next buffer address
payload_size To return the size of next buffer
Returns:
true, if a new buffer is available, otherwise stop the request.

Definition at line 133 of file USBHDriver.h.

typedef void(* uhd_callback_trans_t)(uint8_t add, uint8_t ep, USBH_XfrStatus_t status, uint32_t nb_transfered)

End of transfer callback function type. Registered by USBH_HAL_RunEndpoint() Callback called by USB interrupt after data transfer or abort (reset,...).

Parameters:
add USB address used by the transfer
status Transfer status
nb_transfered Number of data transfered

Definition at line 161 of file USBHDriver.h.


Enumeration Type Documentation

Bit definitions to store setup request state machine.

Enumerator:
UHD_CTRL_REQ_PHASE_SETUP 

Wait a SETUP packet.

UHD_CTRL_REQ_PHASE_DATA_OUT 

Wait a OUT data packet.

UHD_CTRL_REQ_PHASE_DATA_IN 

Wait a IN data packet.

UHD_CTRL_REQ_PHASE_ZLP_IN 

Wait a IN ZLP packet.

UHD_CTRL_REQ_PHASE_ZLP_OUT 

Wait a OUT ZLP packet.

Definition at line 291 of file USBH_HAL.c.

Endpoint transfer status The status field is updated after each transaction attempt, whether successful or not.

Enumerator:
UHD_TRANS_NOERROR 

Transaction is successful.

UHD_TRANS_DISCONNECT 

Device is disconnected.

UHD_TRANS_CRC 

CRC error in data packet.

UHD_TRANS_DT_MISMATCH 

Data toggle PID did not match the expected value.

UHD_TRANS_STALL 

The endpoint returned a STALL PID.

UHD_TRANS_NOTRESPONDING 

Device did not respond to token (IN) or did not provide a handshake (OUT)

UHD_TRANS_PIDFAILURE 

Check bits on PID from endpoint failed.

UHD_TRANS_TIMEOUT 

Data transmission not completed before timeout.

UHD_TRANS_ABORTED 

Data transmission has been aborted.

Definition at line 82 of file USBHDriver.h.


Function Documentation

void USBH_HAL_AbortEndPoint ( uint8_t  add,
uint8_t  endp 
)

Aborts an on-going transfer on an endpoint.

If a transfer is on going, then it is stopped and the callback registered is called to signal the end of transfer. Note: The control endpoint is not authorized.

Parameters:
add USB address of endpoint
endp Endpoint to abort
bool USBH_HAL_ConfigureControlPipe ( uint8_t  add,
uint16_t  ep_size 
)

Configures and enables a control endpoint 0.

Parameters:
add USB address of endpoint
ep_size Endpoint control maximum size
Returns:
1 if the endpoint is enabled, otherwise 0.
bool USBH_HAL_ConfigurePipe ( uint8_t  add,
USBEndpointDescriptor *  ep_desc 
)

Configures and enables an endpoint.

Parameters:
add USB address of endpoint
ep_desc Endpoint descriptor
Returns:
1 if the endpoint is enabled, otherwise 0.
void USBH_HAL_DisableUsb ( bool  b_id_stop  ) 

Disables the USB host mode.

Parameters:
b_id_stop Stop ID pin management, if true.
void USBH_HAL_EnableUsbHost ( void   ) 

Enables the USB host mode Start the ID pin management if the ID pin is available.

Freeze USB clock to use wakeup interrupt to detect connection. After detection of wakeup interrupt, the clock is unfreeze to have the true connection interrupt.

void USBH_HAL_FreePipe ( uint8_t  add,
uint8_t  endp 
)

Disables an endpoint or all endpoint of a device.

Parameters:
add USB address of endpoint
endp Endpoint number and direction (USB_EP_DIR_IN/OUT). Remove all endpoints of USB address, if 0xFF.
uint16_t USBH_HAL_GetFrameNum ( void   ) 

Returns the current Start Of Frame (SOF) number.

Returns:
current start of frame number.
uint16_t USBH_HAL_GetMicroFrameNum ( void   ) 

Returns the current micro start of frame number.

Returns:
current micro start of frame number required in high speed mode.
USBH_Speed_t USBH_HAL_GetSpeed ( void   ) 

Returns the speed of connected device.

Returns:
Device speed
bool USBH_HAL_IsSuspended ( void   ) 

Test if the suspend state is enabled on the USB line.

Returns:
USB line in SUSPEND state, if true
void USBH_HAL_Reset ( uhd_callback_reset_t  callback  ) 

Enables the Reset state on the USB line.

Parameters:
callback Callback when reset sequence is finished
bool USBH_HAL_RunEndpoint ( uint8_t  add,
uint8_t  endp,
bool  b_shortpacket,
uint8_t *  buf,
uint32_t  buf_size,
uint16_t  timeout,
uhd_callback_trans_t  callback 
)

Allows to receive or send data on an endpoint.

If a USB DMA is available, the driver uses it to transfer endpoint data from or to internal RAM. When the transfer is finished or aborted (stall, reset, ...), the callback is called. This callback returns the transfer status and eventually the number of byte transfered. Note: The control endpoint is not authorized.

Parameters:
add USB address of endpoint
endp Endpoint number
b_shortpacket Enabled automatic short packet
buf Buffer on Internal RAM to send or fill. It must be align, then use COMPILER_WORD_ALIGNED.
buf_size Buffer size to send or fill
timeout Transfer timeout (ms)
callback NULL or function to call at the end of transfer
Warning:
About b_shortpacket, for OUT endpoint it means that a short packet or a Zero Length Packet must be sent to the USB line to properly close the USB transfer at the end of the data transfer. For Bulk and Interrupt IN endpoint, it will automatically stop the transfer at the end of the data transfer (received short packet).
About timeout, for BULK endpoint with timeout set to zero, it means that the transfer will never be stopped before transfer done. Since most of USB embedded peripherals do not manage the transfer bandwidth by peripheral hardware, such a BULK transfer will occupy all USB non-periodic transfer bandwidth. In this case, other BULK transfers started later will be pending until this transfer is done and bandwidth released. So it is better to use BULK transfers with none zero timeout.
Returns:
1 if function was successfully done, otherwise 0.
bool USBH_HAL_SetupReq ( uint8_t  add,
USBGenericRequest req,
uint8_t *  payload,
uint16_t  payload_size,
uhd_callback_setup_run_t  callback_run,
uhd_callback_setup_end_t  callback_end 
)

Add a setup request in the control endpoint setup queue. Note: Request timeout is 5s.

Parameters:
add USB address of control endpoint
req Setup request definition
payload Buffer to use in setup DATA phase
payload_size Size of buffer used in DATA phase
callback_run Callback to call if buffer is empty or full
callback_end Callback to call when request is finish
Returns:
true if the request has been accepted, otherwise false. Note: The swap of "req.wValues" from uin16_t to le16_t is done by UHD.
void USBH_notify_connection ( bool  b_plug  ) 

Notify device connection or disconnection.

Parameters:
b_plug Device connection, if true

Definition at line 971 of file USBH.c.

void USBH_notify_sof ( bool  b_micro  ) 

Notify each start of frame sent by driver.

Parameters:
b_micro It is a micro start of frame, if true

Definition at line 990 of file USBH.c.

void USBH_stop ( bool  b_id_stop  ) 

Stops the host mode.

Parameters:
b_id_stop Stop USB ID pin management, if true.

Definition at line 1038 of file USBH.c.

Here is the call graph for this function:

void USBHS_Handler ( void   ) 

USBD (UDP) interrupt handler Manages device resume, suspend, end of bus reset. Forwards endpoint events to the appropriate handler.

Definition at line 400 of file USBH_HAL.c.

Here is the call graph for this function:

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines