qmk_firmware/internals_usb_device_udd_group.md

group usb_device_udd_group

USB low-level driver for USB device mode

Summary

Members	Descriptions
define UDC_REMOTEWAKEUP_LPM_ENABLE
define UDC_REMOTEWAKEUP_LPM_DISABLE
define UDC_SUSPEND_LPM_EVENT
define dbg_print
define UDD_ENDPOINT_MAX_TRANS	Maximum size of a transfer in multi-packet mode
public static udd_ep_job_t * udd_ep_get_job(udd_ep_id_t ep)	Get the detailed job by endpoint number.
public static void udd_ep_trans_in_next(void * pointer)	Endpoint IN process, continue to send packets or zero length packet.
public static void udd_ep_trans_out_next(void * pointer)	Endpoint OUT process, continue to receive packets or zero length packet.
public static void udd_ep_transfer_process(struct usb_module * module_inst,void * pointer)	Endpoint Transfer Complete callback function, to do the next transfer depends on the direction(IN or OUT)
public void udd_ep_abort(udd_ep_id_t ep)	Aborts transfer on going on endpoint.
public bool udd_is_high_speed(void)	Test whether the USB Device Controller is running at high speed or not.
public uint16_t udd_get_frame_number(void)	Returns the current start of frame number.
public uint16_t udd_get_micro_frame_number(void)	Returns the current micro start of frame number.
public void udd_ep_free(udd_ep_id_t ep)	Disables an endpoint.
public bool udd_ep_alloc(udd_ep_id_t ep,uint8_t bmAttributes,uint16_t MaxEndpointSize)	Configures and enables an endpoint.
public bool udd_ep_is_halted(udd_ep_id_t ep)	Check if the endpoint ep is halted.
public bool udd_ep_set_halt(udd_ep_id_t ep)	Set the halted state of the endpoint ep.
public bool udd_ep_clear_halt(udd_ep_id_t ep)	Clear the halted state of the endpoint ep.
public 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.
public static void udd_ctrl_stall_data(void)	Control Endpoint stall sending data.
public 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.
public void udd_set_address(uint8_t address)	Changes the USB address of device.
public uint8_t udd_getaddress(void)	Returns the USB address of device.
public void udd_send_remotewakeup(void)	The USB driver sends a resume signal called Upstream Resume.
public void udd_set_setup_payload(uint8_t * payload,uint16_t payload_size)	Load setup payload.
public static void udd_ctrl_fetch_ram(void)	Control Endpoint translate the data in buffer into Device Request Struct.
public static void udd_ctrl_send_zlp_in(void)	Control Endpoint send out zero length packet.
public static void udd_ctrl_in_sent(void)	Process control endpoint IN transaction.
public static void udd_ctrl_out_received(void * pointer)	Process control endpoint OUT transaction.
public static void _usb_ep0_on_setup(struct usb_module * module_inst,void * pointer)
public static void udd_ctrl_underflow(void * pointer)	Control Endpoint Process when underflow condition has occurred.
public static void udd_ctrl_overflow(void * pointer)	Control Endpoint Process when overflow condition has occurred.
public static void _usb_ep0_on_tansfer_fail(struct usb_module * module_inst,void * pointer)
public static void _usb_ep0_on_tansfer_ok(struct usb_module * module_inst,void * pointer)
public static void udd_ctrl_ep_enable(struct usb_module * module_inst)	Enable Control Endpoint.
public static void _usb_on_suspend(struct usb_module * module_inst,void * pointer)
public static void _usb_on_sof_notify(struct usb_module * module_inst,void * pointer)
public static void _usb_on_bus_reset(struct usb_module * module_inst,void * pointer)
public static void _usb_on_wakeup(struct usb_module * module_inst,void * pointer)
public void udd_detach(void)	Detaches the device from the bus.
public void udd_attach(void)	Attach device to the bus when possible.
public void udd_enable(void)	Enables the USB Device mode.
public void udd_disable(void)	Disables the USB Device mode.

Members

define UDC_REMOTEWAKEUP_LPM_ENABLE

define UDC_REMOTEWAKEUP_LPM_DISABLE

define UDC_SUSPEND_LPM_EVENT

define dbg_print

define UDD_ENDPOINT_MAX_TRANS

Maximum size of a transfer in multi-packet mode

public static udd_ep_job_t * udd_ep_get_job(udd_ep_id_t ep)

Get the detailed job by endpoint number.

Parameters

• ep Endpoint Address

Parameters

• pointer to an udd_ep_job_t structure instance

public static void udd_ep_trans_in_next(void * pointer)

Endpoint IN process, continue to send packets or zero length packet.

Parameters

• pointer Pointer to the endpoint transfer status parameter struct from driver layer.

public static void udd_ep_trans_out_next(void * pointer)

Endpoint OUT process, continue to receive packets or zero length packet.

Parameters

• pointer Pointer to the endpoint transfer status parameter struct from driver layer.

public static void udd_ep_transfer_process(struct usb_module * module_inst,void * pointer)

Endpoint Transfer Complete callback function, to do the next transfer depends on the direction(IN or OUT)

Parameters

• module_inst Pointer to USB module instance

• pointer Pointer to the endpoint transfer status parameter struct from driver layer.

public 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

public bool udd_is_high_speed(void)

Test whether the USB Device Controller is running at high speed or not.

Returns

true if the Device is running at high speed mode, otherwise false.

public uint16_t udd_get_frame_number(void)

Returns the current start of frame number.

Returns

current start of frame number.

public uint16_t udd_get_micro_frame_number(void)

Returns the current micro start of frame number.

Returns

current micro start of frame number required in high speed mode.

public 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).

public 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.

public 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.

public 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

• ep The ID of the endpoint to be halted

Returns

1 if ep is halted, otherwise 0.

public 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.

public 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.

Parameters

• ep The ID of the endpoint to use

• callback NULL or function to call when endpoint halt is cleared

if the endpoint is not halted then the callback is called immediately.

Returns

1 if the register is accepted, otherwise 0.

public static void udd_ctrl_stall_data(void)

Control Endpoint stall sending data.

public 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

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.

public void udd_set_address(uint8_t address)

Changes the USB address of device.

Parameters

• address New USB address

public uint8_t udd_getaddress(void)

Returns the USB address of device.

Returns

USB address

public void udd_send_remotewakeup(void)

The USB driver sends a resume signal called Upstream Resume.

public void udd_set_setup_payload(uint8_t * payload,uint16_t payload_size)

Load setup payload.

Parameters

• payload Pointer on payload

• payload_size Size of payload

public static void udd_ctrl_fetch_ram(void)

Control Endpoint translate the data in buffer into Device Request Struct.

public static void udd_ctrl_send_zlp_in(void)

Control Endpoint send out zero length packet.

public static void udd_ctrl_in_sent(void)

Process control endpoint IN transaction.

public static void udd_ctrl_out_received(void * pointer)

Process control endpoint OUT transaction.

Parameters

• pointer Pointer to the endpoint transfer status parameter struct from driver layer.

public static void _usb_ep0_on_setup(struct usb_module * module_inst,void * pointer)

public static void udd_ctrl_underflow(void * pointer)

Control Endpoint Process when underflow condition has occurred.

Parameters

• pointer Pointer to the endpoint transfer status parameter struct from driver layer.

public static void udd_ctrl_overflow(void * pointer)

Control Endpoint Process when overflow condition has occurred.

Parameters

• pointer Pointer to the endpoint transfer status parameter struct from driver layer.

public static void _usb_ep0_on_tansfer_fail(struct usb_module * module_inst,void * pointer)

public static void _usb_ep0_on_tansfer_ok(struct usb_module * module_inst,void * pointer)

public static void udd_ctrl_ep_enable(struct usb_module * module_inst)

Enable Control Endpoint.

Parameters

• module_inst Pointer to USB module instance

public static void _usb_on_suspend(struct usb_module * module_inst,void * pointer)

public static void _usb_on_sof_notify(struct usb_module * module_inst,void * pointer)

public static void _usb_on_bus_reset(struct usb_module * module_inst,void * pointer)

public static void _usb_on_wakeup(struct usb_module * module_inst,void * pointer)

public void udd_detach(void)

Detaches the device from the bus.

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

public void udd_attach(void)

Attach device to the bus when possible.

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

public void udd_enable(void)

Enables the USB Device mode.

public void udd_disable(void)

Disables the USB Device mode.