Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
USB Host Driver (UHD)

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.

Typedefs

typedef void(* uhd_callback_reset_t )(void)
 End of reset callback function type. More...
 
typedef void(* uhd_callback_setup_end_t )(usb_add_t add, uhd_trans_status_t status, uint16_t payload_trans)
 End of setup callback function type. More...
 
typedef bool(* uhd_callback_setup_run_t )(usb_add_t add, uint8_t **payload, uint16_t *payload_size)
 Data setup transfer callback function type. More...
 
typedef void(* uhd_callback_trans_t )(usb_add_t add, usb_ep_t ep, uhd_trans_status_t status, iram_size_t nb_transfered)
 End of transfer callback function type. More...
 

Enumerations

enum  uhd_speed_t {
  UHD_SPEED_LOW = 0,
  UHD_SPEED_FULL = 1,
  UHD_SPEED_HIGH = 2
}
 Device speed. More...
 
enum  uhd_trans_status_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 uhd_disable (bool b_id_stop)
 Disables the USB host mode. More...
 
void uhd_enable (void)
 Enables the USB host mode Start the ID pin management if the ID pin is available. More...
 
uint16_t uhd_get_frame_number (void)
 Returns the current Start Of Frame (SOF) number. More...
 
uint16_t uhd_get_microframe_number (void)
 Returns the current micro start of frame number. More...
 
uhd_speed_t uhd_get_speed (void)
 Returns the speed of connected device. More...
 
bool uhd_is_suspend (void)
 Test if the suspend state is enabled on the USB line. More...
 
void uhd_resume (void)
 Enables the IDLE state on the USB line. More...
 
void uhd_send_reset (uhd_callback_reset_t callback)
 Enables the Reset state on the USB line. More...
 
bool uhd_setup_request (usb_add_t add, usb_setup_req_t *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. More...
 
void uhd_suspend (void)
 Enables the suspend state on the USB line. More...
 
bool uhd_suspend_lpm (bool b_remotewakeup, uint8_t hird)
 Enables the suspend L1 state on the USB line. More...
 

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 uhd_ep0_alloc (usb_add_t add, uint8_t ep_size)
 Configures and enables a control endpoint 0. More...
 
bool uhd_ep_alloc (usb_add_t add, usb_ep_desc_t *ep_desc, uhd_speed_t speed)
 Configures and enables an endpoint. More...
 
void uhd_ep_free (usb_add_t add, usb_ep_t endp)
 Disables an endpoint or all endpoint of a device. More...
 
bool uhd_ep_run (usb_add_t add, usb_ep_t endp, bool b_shortpacket, uint8_t *buf, iram_size_t buf_size, uint16_t timeout, uhd_callback_trans_t callback)
 Allows to receive or send data on an endpoint. More...
 
void uhd_ep_abort (usb_add_t add, usb_ep_t endp)
 Aborts an on-going transfer on an endpoint. More...
 

High speed test mode management

The following functions allow the host to jump to a specific test mode required in high speed mode.

void uhd_test_mode_j (void)
 
void uhd_test_mode_k (void)
 
void uhd_test_mode_se0_nak (void)
 
void uhd_test_mode_packet (void)
 

UHC callbacks to provide for UHD

The following callbacks are used by UHD.

void uhc_start (void)
 Starts the host mode. More...
 
void uhc_stop (bool b_id_stop)
 Stops the host mode. More...
 
void uhc_notify_connection (bool b_plug)
 Notify device connection or disconnection. More...
 
void uhc_notify_sof (bool b_micro)
 Notify each start of frame sent by driver. More...
 
void uhc_notify_resume (void)
 Notify that a resume bus occurs A resume can occur after a downstream or an upstream resume. More...
 
void uhc_notify_resume_lpm (void)
 Notify that a resume bus occurs after a L1 state A resume can occur after a downstream or an upstream resume. More...
 

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 void(* uhd_callback_setup_end_t)(usb_add_t add, uhd_trans_status_t status, uint16_t payload_trans)

End of setup callback function type.

Registered by uhd_setup_request() Called when the setup request is completed.

Parameters
addUSB address of the setup request
statusTransfer status
payload_transNumber of data transfered during DATA phase
typedef bool(* uhd_callback_setup_run_t)(usb_add_t add, uint8_t **payload, uint16_t *payload_size)

Data setup transfer callback function type.

Registered by uhd_setup_request() 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
addUSB address of the setup request
payloadTo return the next buffer address
payload_sizeTo return the size of next buffer
Returns
true, if a new buffer is available, otherwise stop the request.
typedef void(* uhd_callback_trans_t)(usb_add_t add, usb_ep_t ep, uhd_trans_status_t status, iram_size_t nb_transfered)

End of transfer callback function type.

Registered by uhd_ep_run() Callback called by USB interrupt after data transfer or abort (reset,...).

Parameters
addUSB address used by the transfer
statusTransfer status
nb_transferedNumber of data transfered

Device speed.

Enumerator
UHD_SPEED_LOW 
UHD_SPEED_FULL 
UHD_SPEED_HIGH 

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.

void uhc_notify_connection ( bool  b_plug)

Notify device connection or disconnection.

Parameters
b_plugDevice connection, if true

References uhc_device_t::address, Assert, uhc_connection_tree(), uhc_power_running, and UHC_USB_ADD_NOT_VALID.

Referenced by _uhd_connect(), _uhd_disconnect(), and uhd_disable().

void uhc_notify_resume ( void  )

Notify that a resume bus occurs A resume can occur after a downstream or an upstream resume.

References uhc_remotewakeup(), and UHC_WAKEUP_EVENT.

Referenced by _uhd_sof_interrupt().

void uhc_notify_resume_lpm ( void  )

Notify that a resume bus occurs after a L1 state A resume can occur after a downstream or an upstream resume.

References UHC_WAKEUP_EVENT.

Referenced by _uhd_downstream_resume(), _uhd_upstream_resume(), and _uhd_wakeup().

void uhc_notify_sof ( bool  b_micro)

Notify each start of frame sent by driver.

Parameters
b_microIt is a micro start of frame, if true

References uhi_api_t::sof_notify, UHC_NB_UHI, uhc_sof_timeout, and uhc_sof_timeout_callback.

Referenced by _uhd_sof_interrupt().

void uhc_start ( void  )
void uhc_stop ( bool  b_id_stop)

Stops the host mode.

Parameters
b_id_stopStop USB ID pin management, if true.

References uhd_disable().

Referenced by run_test_stop_uhc().

void uhd_ep_abort ( usb_add_t  add,
usb_ep_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
addUSB address of endpoint
endpEndpoint to abort

References _uhd_ep_abort_pipe(), _uhd_get_pipe(), and UHD_TRANS_ABORTED.

void uhd_ep_free ( usb_add_t  add,
usb_ep_t  endp 
)
bool uhd_ep_run ( usb_add_t  add,
usb_ep_t  endp,
bool  b_shortpacket,
uint8_t *  buf,
iram_size_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
addUSB address of endpoint
endpEndpoint number
b_shortpacketEnabled automatic short packet
bufBuffer on Internal RAM to send or fill. It must be align, then use COMPILER_WORD_ALIGNED.
buf_sizeBuffer size to send or fill
timeoutTransfer timeout (ms)
callbackNULL 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 (ZLP) 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 buf_size, for OUT endpoint the data is sent packet by packet until size is achieved. If the size is multiple of endpoint size ZLP may be sent according to the b_shortpacket setting. For IN endpoint the data is received packet by packet, if the last packet exceeds the buffer size, the overflow data will be discarded. So for IN endpoint it's better to allocate buffer size aligned to endpoint size so no returned data is lost.
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.

References _uhd_get_pipe(), _uhd_pipe_trans_complete(), uhd_pipe_job_t::b_shortpacket, uhd_pipe_job_t::buf, uhd_pipe_job_t::buf_size, uhd_pipe_job_t::busy, uhd_pipe_job_t::call_end, cpu_irq_restore(), cpu_irq_save(), dev, uhd_pipe_job_t::nb_trans, usb_pipe_callback_parameter::pipe_num, usb_pipe_callback_parameter::required_size, uhd_pipe_job_t::timeout, and usb_pipe_callback_parameter::transfered_size.

Referenced by uhi_hid_mouse_start_trans_report().

uint16_t uhd_get_frame_number ( void  )

Returns the current Start Of Frame (SOF) number.

Returns
current start of frame number.

References dev.

uint16_t uhd_get_microframe_number ( void  )

Returns the current micro start of frame number.

Returns
current micro start of frame number required in high speed mode.
uhd_speed_t uhd_get_speed ( void  )

Returns the speed of connected device.

Returns
Device speed

References Assert, dev, UHD_SPEED_FULL, UHD_SPEED_LOW, USB_SPEED_FULL, and USB_SPEED_LOW.

Referenced by uhc_enumeration_step4().

bool uhd_is_suspend ( void  )

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

Returns
USB line in SUSPEND state, if true

References dev.

Referenced by uhc_is_suspend().

void uhd_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.

References dbg_print, dev, usb_host_pipe_config::pipe_type, uhd_lpm_suspend, uhd_resume_start, uhd_sleep_mode(), UHD_STATE_IDLE, uhd_suspend_start, usb_host_pipe_get_config(), and USB_HOST_PIPE_TYPE_EXTENDED.

Referenced by uhc_resume().

void uhd_send_reset ( uhd_callback_reset_t  callback)

Enables the Reset state on the USB line.

Parameters
callbackCallback when reset sequence is finished

References dev, and uhd_reset_callback.

Referenced by uhc_enumeration_reset().

bool uhd_setup_request ( usb_add_t  add,
usb_setup_req_t 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
addUSB address of control endpoint
reqSetup request definition
payloadBuffer to use in setup DATA phase
payload_sizeSize of buffer used in DATA phase
callback_runCallback to call if buffer is empty or full
callback_endCallback 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.

References _uhd_ctrl_phase_setup(), uhd_ctrl_request_t::add, Assert, uhd_ctrl_request_t::callback_end, uhd_ctrl_request_t::callback_run, cpu_irq_restore(), cpu_irq_save(), uhd_ctrl_request_t::next_request, uhd_ctrl_request_t::payload, uhd_ctrl_request_t::payload_size, and uhd_ctrl_request_t::req.

Referenced by uhc_dev_get_string(), uhc_dev_is_high_speed_support(), uhc_enumeration_step11(), uhc_enumeration_step12(), uhc_enumeration_step13(), uhc_enumeration_step14(), uhc_enumeration_step5(), uhc_enumeration_step9(), uhc_remotewakeup(), and uhc_request_bos_desc().

void uhd_suspend ( void  )

Enables the suspend state on the USB line.

The SUSPEND state is enable when SOF are disabled on USB line.

References dev, uhd_b_suspend_requested, uhd_ctrl_request_timeout, uhd_pipes_unfreeze, and uhd_suspend_start.

Referenced by _uhd_ctrl_request_end(), uhc_enumeration_suspend(), and uhc_suspend().

bool uhd_suspend_lpm ( bool  b_remotewakeup,
uint8_t  hird 
)

Enables the suspend L1 state on the USB line.

The SUSPEND LPM state is enable when a LPM transaction is done.

Parameters
b_remotewakeupAuthorize the remote wakeup features, if true
hirdHost Initiated Resume Duration
Returns
USB line in SUSPEND state, if true

References dbg_print, dev, uhd_ctrl_request_timeout, and usb_host_pipe_lpm_job().

Referenced by uhc_suspend_lpm().

void uhd_test_mode_j ( void  )
void uhd_test_mode_k ( void  )
void uhd_test_mode_packet ( void  )
void uhd_test_mode_se0_nak ( void  )