The UDD driver provides a low-level abstraction of the device controller hardware.

Most events coming from the hardware such as interrupts, which may cause the UDD to call into the UDC and UDI.

Data Structures
struct	udd_ctrl_request_t
	Global variable to give and record information of the setup request management. More...

Macros
#define	Udd_setup_is_in() (USB_REQ_DIR_IN == (udd_g_ctrlreq.req.bmRequestType & USB_REQ_DIR_MASK))
	Return true if the setup request udd_g_ctrlreq indicates IN data transfer. More...

#define	Udd_setup_is_out() (USB_REQ_DIR_OUT == (udd_g_ctrlreq.req.bmRequestType & USB_REQ_DIR_MASK))
	Return true if the setup request udd_g_ctrlreq indicates OUT data transfer. More...

#define	Udd_setup_recipient() (udd_g_ctrlreq.req.bmRequestType & USB_REQ_RECIP_MASK)
	Return the recipient of the SETUP request udd_g_ctrlreq. More...

#define	Udd_setup_type() (udd_g_ctrlreq.req.bmRequestType & USB_REQ_TYPE_MASK)
	Return the type of the SETUP request udd_g_ctrlreq. More...

Typedefs
typedef void(*	udd_callback_halt_cleared_t )(void)
	End of halt callback function type. More...

typedef void(*	udd_callback_trans_t )(udd_ep_status_t status, iram_size_t nb_transfered, udd_ep_id_t ep)
	End of transfer callback function type. More...

typedef uint8_t	udd_ep_id_t
	Endpoint identifier. More...

Enumerations
enum	udd_ep_status_t { UDD_EP_TRANSFER_OK = 0, UDD_EP_TRANSFER_ABORT = 1 }
	Endpoint transfer status Returned in parameters of callback register via udd_ep_run routine. More...

Functions
void	udd_attach (void)
	Attach device to the bus when possible. More...

void	udd_detach (void)
	Detaches the device from the bus. More...

void	udd_disable (void)
	Disables the USB Device mode. More...

void	udd_enable (void)
	Enables the USB Device mode. More...

uint16_t	udd_get_frame_number (void)
	Returns the current start of frame number. More...

uint16_t	udd_get_micro_frame_number (void)
	Returns the current micro start of frame number. More...

uint8_t	udd_getaddress (void)
	Returns the USB address of device. More...

bool	udd_include_vbus_monitoring (void)
	Authorizes the VBUS event. More...

bool	udd_is_high_speed (void)
	Test whether the USB Device Controller is running at high speed or not. More...

void	udd_send_remotewakeup (void)
	The USB driver sends a resume signal called Upstream Resume. More...

void	udd_set_address (uint8_t address)
	Changes the USB address of device. More...

void	udd_set_setup_payload (uint8_t *payload, uint16_t payload_size)
	Load setup payload. More...

Variables
udd_ctrl_request_t	udd_g_ctrlreq
	Global variable to give and record information of the set up request management. 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	udd_ep_alloc (udd_ep_id_t ep, uint8_t bmAttributes, uint16_t MaxEndpointSize)
	Configures and enables an endpoint. More...

void	udd_ep_free (udd_ep_id_t ep)
	Disables an endpoint. More...

bool	udd_ep_is_halted (udd_ep_id_t ep)
	Check if the endpoint ep is halted. More...

bool	udd_ep_set_halt (udd_ep_id_t ep)
	Set the halted state of the endpoint ep. More...

bool	udd_ep_clear_halt (udd_ep_id_t ep)
	Clear the halted state of the endpoint ep. More...

bool	udd_ep_wait_stall_clear (udd_ep_id_t ep, udd_callback_halt_cleared_t callback)
	Registers a callback to call when endpoint halt is cleared. More...

bool	udd_ep_run (udd_ep_id_t ep, bool b_shortpacket, uint8_t *buf, iram_size_t buf_size, udd_callback_trans_t callback)
	Allows to receive or send data on an endpoint. More...

void	udd_ep_abort (udd_ep_id_t ep)
	Aborts transfer on going on endpoint. More...

High speed test mode management
The following functions allow the device to jump to a specific test mode required in high speed mode.
void	udd_test_mode_j (void)

void	udd_test_mode_k (void)

void	udd_test_mode_se0_nak (void)

void	udd_test_mode_packet (void)

UDC callbacks to provide for UDD
The following callbacks are used by UDD.
bool	udc_process_setup (void)
	Decodes and manages a setup request. More...

void	udc_reset (void)
	Reset the UDC. More...

void	udc_sof_notify (void)
	To signal that a SOF is occurred. More...

#define Udd_setup_is_in ( ) (USB_REQ_DIR_IN == (udd_g_ctrlreq.req.bmRequestType & USB_REQ_DIR_MASK))

Return true if the setup request udd_g_ctrlreq indicates IN data transfer.

Referenced by _usb_ep0_on_setup(), udc_process_setup(), udc_reqstd(), and udi_hid_setup().

#define Udd_setup_is_out ( ) (USB_REQ_DIR_OUT == (udd_g_ctrlreq.req.bmRequestType & USB_REQ_DIR_MASK))

Return true if the setup request udd_g_ctrlreq indicates OUT data transfer.

Referenced by udi_hid_setup().

#define Udd_setup_recipient ( ) (udd_g_ctrlreq.req.bmRequestType & USB_REQ_RECIP_MASK)

Return the recipient of the SETUP request udd_g_ctrlreq.

See Also: usb_recipient

Referenced by udc_process_setup(), and udc_reqstd().

#define Udd_setup_type ( ) (udd_g_ctrlreq.req.bmRequestType & USB_REQ_TYPE_MASK)

Return the type of the SETUP request udd_g_ctrlreq.

See Also: usb_reqtype.

Referenced by udc_process_setup(), and udi_hid_setup().

typedef void(* udd_callback_halt_cleared_t)(void)

End of halt callback function type.

Registered by routine udd_ep_wait_stall_clear() Callback called when endpoint stall is cleared.

typedef void(* udd_callback_trans_t)(udd_ep_status_t status, iram_size_t nb_transfered, udd_ep_id_t ep)

End of transfer callback function type.

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

Parameters

status	UDD_EP_TRANSFER_OK, if transfer is complete
status	UDD_EP_TRANSFER_ABORT, if transfer is aborted
n	number of data transfered

typedef uint8_t udd_ep_id_t

Endpoint identifier.

enum udd_ep_status_t

Endpoint transfer status Returned in parameters of callback register via udd_ep_run routine.

Enumerator
UDD_EP_TRANSFER_OK
UDD_EP_TRANSFER_ABORT

bool udc_process_setup ( void )

Decodes and manages a setup request.

The driver call it when a SETUP packet is received. The udd_g_ctrlreq contains the data of SETUP packet. If this callback accepts the setup request then it must return 1 and eventually update udd_g_ctrlreq to send or receive data.

Returns: 1 if the request is accepted, otherwise 0.

Decodes and manages a setup request.

This function parses a USB SETUP request and submits an appropriate response back to the host or, in the case of SETUP OUT requests with data, sets up a buffer for receiving the data payload.

The main standard requests defined by the USB 2.0 standard are handled internally. The interface requests are sent to UDI, and the specific request sent to a specific application callback.

Returns: true if the request is supported, else the request is stalled by UDD

References udd_ctrl_request_t::callback, udd_ctrl_request_t::over_under_run, udd_ctrl_request_t::payload_size, udd_ctrl_request_t::req, udc_req_ep(), udc_req_iface(), udc_reqstd(), udd_g_ctrlreq, Udd_setup_is_in, Udd_setup_recipient, Udd_setup_type, USB_REQ_RECIP_ENDPOINT, USB_REQ_RECIP_INTERFACE, USB_REQ_TYPE_STANDARD, and usb_setup_req_t::wLength.

Referenced by _usb_ep0_on_setup().

void udc_reset ( void )

Reset the UDC.

The UDC must reset all configuration.

Reset the UDC.

References usb_conf_desc_t::bNumInterfaces, CPU_TO_LE16, udc_config_speed_t::desc, udc_device_status, udc_iface_disable(), udc_num_configuration, udc_ptr_conf, UDC_REMOTEWAKEUP_DISABLE, USB_DEV_STATUS_BUS_POWERED, USB_DEV_STATUS_REMOTEWAKEUP, and USB_DEV_STATUS_SELF_POWERED.

Referenced by _usb_on_bus_reset(), udc_req_std_dev_set_configuration(), udc_req_std_dev_set_feature(), and udc_stop().

void udc_sof_notify ( void )

To signal that a SOF is occurred.

The UDC must send the signal to all UDIs enabled

References usb_conf_desc_t::bNumInterfaces, udc_config_speed_t::desc, udi_api_t::sof_notify, udc_num_configuration, udc_ptr_conf, and udc_config_speed_t::udi_apis.

Referenced by _usb_on_sof_notify().

void udd_attach ( void )

Attach device to the bus when possible.

Warning: If a VBus control is included in driver, then it will attach device when an acceptable Vbus level from the host is detected.

References _usb_device_lpm_suspend(), _usb_on_bus_reset(), _usb_on_sof_notify(), _usb_on_suspend(), _usb_on_wakeup(), udd_sleep_mode(), UDD_STATE_IDLE, usb_device, usb_device_attach(), USB_DEVICE_CALLBACK_LPMSUSP, USB_DEVICE_CALLBACK_RESET, USB_DEVICE_CALLBACK_SOF, USB_DEVICE_CALLBACK_SUSPEND, USB_DEVICE_CALLBACK_WAKEUP, usb_device_enable_callback(), and usb_device_register_callback().

Referenced by _uhd_vbus_handler(), udc_attach(), and udd_enable().

void udd_detach ( void )

Detaches the device from the bus.

The driver must remove pull-up on USB line D- or D+.

References udd_sleep_mode(), UDD_STATE_SUSPEND, usb_device, and usb_device_detach().

Referenced by _uhd_vbus_handler(), udc_detach(), and udd_disable().

void udd_disable ( void )

Disables the USB Device mode.

References cpu_irq_restore(), cpu_irq_save(), udd_detach(), udd_sleep_mode(), UDD_STATE_OFF, and usb_dual_disable().

Referenced by udc_stop().

void udd_enable ( void )

Enables the USB Device mode.

References _uhd_vbus_handler(), _usb_vbus_config(), cpu_irq_restore(), cpu_irq_save(), is_usb_vbus_high, usb_config::source_generator, udd_attach(), UDD_CLOCK_GEN, udd_sleep_mode(), UDD_STATE_SUSPEND, udd_wait_clock_ready(), usb_device, usb_dual_enable(), usb_enable(), usb_get_config_defaults(), and usb_init().

Referenced by udc_start().

void udd_ep_abort ( udd_ep_id_t ep )

Aborts transfer on going on 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

ep	Endpoint to abort

References udd_ep_get_job(), udd_ep_job_t, UDD_EP_TRANSFER_ABORT, usb_device, and usb_device_endpoint_abort_job().

Referenced by udc_req_std_ep_set_feature(), udd_ep_free(), and udd_ep_set_halt().

bool udd_ep_alloc	(	udd_ep_id_t	ep,
		uint8_t	bmAttributes,
		uint16_t	MaxEndpointSize
	)

Configures and enables an endpoint.

Parameters

ep	Endpoint number including direction (USB_EP_DIR_IN/USB_EP_DIR_OUT).
bmAttributes	Attributes of endpoint declared in the descriptor.
MaxEndpointSize	Endpoint maximum size

Returns: 1 if the endpoint is enabled, otherwise 0.

References usb_device_endpoint_config::ep_address, usb_device_endpoint_config::ep_size, usb_device_endpoint_config::ep_type, STATUS_OK, udd_ep_get_job(), udd_ep_job_t, udd_ep_transfer_process(), usb_device, USB_DEVICE_ENDPOINT_CALLBACK_TRCPT, USB_DEVICE_ENDPOINT_CALLBACK_TRFAIL, usb_device_endpoint_enable_callback(), usb_device_endpoint_get_config_defaults(), usb_device_endpoint_register_callback(), usb_device_endpoint_set_config(), USB_DEVICE_ENDPOINT_TYPE_BULK, USB_DEVICE_ENDPOINT_TYPE_INTERRUPT, USB_DEVICE_ENDPOINT_TYPE_ISOCHRONOUS, USB_ENDPOINT_1023_BYTE, USB_ENDPOINT_128_BYTE, USB_ENDPOINT_16_BYTE, USB_ENDPOINT_256_BYTE, USB_ENDPOINT_32_BYTE, USB_ENDPOINT_512_BYTE, USB_ENDPOINT_64_BYTE, USB_ENDPOINT_8_BYTE, USB_EP_ADDR_MASK, USB_EP_TYPE_BULK, USB_EP_TYPE_INTERRUPT, USB_EP_TYPE_ISOCHRONOUS, and USB_EP_TYPE_MASK.

Referenced by udc_iface_enable().

bool udd_ep_clear_halt ( udd_ep_id_t ep )

Clear the halted state of the endpoint ep.

After calling this function, any transaction on ep will be handled normally, i.e. a STALL handshake will not be sent, and the data toggle sequence will start at DATA0.

Parameters

ep	The ID of the endpoint to be un-halted

Returns: 1 if function was successfully done, otherwise 0.

References udd_ep_get_job(), udd_ep_job_t, usb_device, usb_device_endpoint_clear_halt(), and USB_EP_ADDR_MASK.

Referenced by udc_req_std_ep_clear_feature().

void udd_ep_free ( udd_ep_id_t ep )

Disables an endpoint.

Parameters

ep	Endpoint number including direction (USB_EP_DIR_IN/USB_EP_DIR_OUT).

References usb_device_endpoint_config::ep_address, usb_device_endpoint_config::ep_type, udd_ep_abort(), usb_device, USB_DEVICE_ENDPOINT_CALLBACK_TRCPT, usb_device_endpoint_disable_callback(), usb_device_endpoint_get_config_defaults(), usb_device_endpoint_set_config(), USB_DEVICE_ENDPOINT_TYPE_DISABLE, usb_device_endpoint_unregister_callback(), and USB_EP_ADDR_MASK.

Referenced by udc_iface_disable().

bool udd_ep_is_halted ( udd_ep_id_t ep )

Check if the endpoint ep is halted.

Parameters

ep	The ID of the endpoint to check.

Returns: 1 if ep is halted, otherwise 0.

References usb_device, and usb_device_endpoint_is_halted().

Referenced by udc_req_std_ep_get_status(), and udd_ep_run().

bool udd_ep_run	(	udd_ep_id_t	ep,
		bool	b_shortpacket,
		uint8_t *	buf,
		iram_size_t	buf_size,
		udd_callback_trans_t	callback
	)

Allows to receive or send data on an endpoint.

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

Parameters

ep	The ID of the endpoint to use
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
callback	NULL or function to call at the end of transfer

Warning: About b_shortpacket, for IN endpoint it means that a short packet (or a Zero Length Packet) will be sent to the USB line to properly close the usb transfer at the end of the data transfer. For Bulk and Interrupt OUT endpoint, it will automatically stop the transfer at the end of the data transfer (received short packet).

Returns: 1 if function was successfully done, otherwise 0.

References cpu_irq_restore(), cpu_irq_save(), usb_device_endpoint_config::ep_size, STATUS_OK, UDD_ENDPOINT_MAX_TRANS, udd_ep_get_job(), udd_ep_is_halted(), udd_ep_job_t, UDD_EP_TRANSFER_OK, usb_device, usb_device_endpoint_read_buffer_job(), usb_device_endpoint_write_buffer_job(), USB_EP_ADDR_MASK, and USB_EP_DIR_IN.

Referenced by udi_hid_multi_touch_send_report_in().

bool udd_ep_set_halt ( udd_ep_id_t ep )

Set the halted state of the endpoint ep.

After calling this function, any transaction on ep will result in a STALL handshake being sent. Any pending transactions will be performed first, however.

Parameters