USB subsystem API¶

USB Device Controller API
USB Device Core Layer API

USB Device Controller API ¶

group _usb_device_controller_api

USB Device Controller API.

Typedefs

typedef void (*usb_dc_ep_callback)(u8_t ep, enum usb_dc_ep_cb_status_code cb_status)¶: Callback function signature for the USB Endpoint status

typedef void (*usb_dc_status_callback)(enum usb_dc_status_code cb_status, const u8_t *param)¶: Callback function signature for the device

Enums

enum usb_dc_status_code¶

USB Driver Status Codes.

Status codes reported by the registered device status callback.

Values:

USB_DC_ERROR¶: USB error reported by the controller

USB_DC_RESET¶: USB reset

USB_DC_CONNECTED¶: USB connection established, hardware enumeration is completed

USB_DC_CONFIGURED¶: USB configuration done

USB_DC_DISCONNECTED¶: USB connection lost

USB_DC_SUSPEND¶: USB connection suspended by the HOST

USB_DC_RESUME¶: USB connection resumed by the HOST

USB_DC_INTERFACE¶: USB interface selected

USB_DC_SET_HALT¶: Set Feature ENDPOINT_HALT received

USB_DC_CLEAR_HALT¶: Clear Feature ENDPOINT_HALT received

USB_DC_SOF¶: Start of Frame received

USB_DC_UNKNOWN¶: Initial USB connection status

enum usb_dc_ep_cb_status_code¶

USB Endpoint Callback Status Codes.

Status Codes reported by the registered endpoint callback.

Values:

USB_DC_EP_SETUP¶: SETUP received

USB_DC_EP_DATA_OUT¶: Out transaction on this EP, data is available for read

USB_DC_EP_DATA_IN¶: In transaction done on this EP

enum usb_dc_ep_type¶

USB Endpoint type.

Values:

USB_DC_EP_CONTROL = 0¶: Control type endpoint

USB_DC_EP_ISOCHRONOUS¶: Isochronous type endpoint

USB_DC_EP_BULK¶: Bulk type endpoint

USB_DC_EP_INTERRUPT¶: Interrupt type endpoint

Functions

int usb_dc_attach(void)¶

Attach USB for device connection.

Function to attach USB for device connection. Upon success, the USB PLL is enabled, and the USB device is now capable of transmitting and receiving on the USB bus and of generating interrupts.

Return: 0 on success, negative errno code on fail.

int usb_dc_detach(void)¶

Detach the USB device.

Function to detach the USB device. Upon success, the USB hardware PLL is powered down and USB communication is disabled.

Return: 0 on success, negative errno code on fail.

int usb_dc_reset(void)¶

Reset the USB device.

This function returns the USB device and firmware back to it’s initial state. N.B. the USB PLL is handled by the usb_detach function

Return: 0 on success, negative errno code on fail.

int usb_dc_set_address(const u8_t addr)¶

Set USB device address.

Return

0 on success, negative errno code on fail.

Parameters

addr: Device address

int usb_dc_set_status_callback(const usb_dc_status_callback cb)¶

Set USB device controller status callback.

Function to set USB device controller status callback. The registered callback is used to report changes in the status of the device controller. The status code are described by the usb_dc_status_code enumeration.

Return

0 on success, negative errno code on fail.

Parameters

cb: Callback function

int usb_dc_ep_check_cap(const struct usb_dc_ep_cfg_data *const cfg)¶

check endpoint capabilities

Function to check capabilities of an endpoint. usb_dc_ep_cfg_data structure provides the endpoint configuration parameters: endpoint address, endpoint maximum packet size and endpoint type. The driver should check endpoint capabilities and return 0 if the endpoint configuration is possible.

Return

0 on success, negative errno code on fail.

Parameters

cfg: Endpoint config

int usb_dc_ep_configure(const struct usb_dc_ep_cfg_data *const cfg)¶

Configure endpoint.

Function to configure an endpoint. usb_dc_ep_cfg_data structure provides the endpoint configuration parameters: endpoint address, endpoint maximum packet size and endpoint type.

Return

0 on success, negative errno code on fail.

Parameters

cfg: Endpoint config

int usb_dc_ep_set_stall(const u8_t ep)¶

Set stall condition for the selected endpoint.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table

int usb_dc_ep_clear_stall(const u8_t ep)¶

Clear stall condition for the selected endpoint.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table

int usb_dc_ep_is_stalled(const u8_t ep, u8_t *const stalled)¶

Check if the selected endpoint is stalled.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table
stalled: Endpoint stall status

int usb_dc_ep_halt(const u8_t ep)¶

Halt the selected endpoint.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table

int usb_dc_ep_enable(const u8_t ep)¶

Enable the selected endpoint.

Function to enable the selected endpoint. Upon success interrupts are enabled for the corresponding endpoint and the endpoint is ready for transmitting/receiving data.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table

int usb_dc_ep_disable(const u8_t ep)¶

Disable the selected endpoint.

Function to disable the selected endpoint. Upon success interrupts are disabled for the corresponding endpoint and the endpoint is no longer able for transmitting/receiving data.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table

int usb_dc_ep_flush(const u8_t ep)¶

Flush the selected endpoint.

This function flushes the FIFOs for the selected endpoint.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table

int usb_dc_ep_write(const u8_t ep, const u8_t *const data, const u32_t data_len, u32_t *const ret_bytes)¶

Write data to the specified endpoint.

This function is called to write data to the specified endpoint. The supplied usb_ep_callback function will be called when data is transmitted out.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table
data: Pointer to data to write
data_len: Length of the data requested to write. This may be zero for a zero length status packet.
ret_bytes: Bytes scheduled for transmission. This value may be NULL if the application expects all bytes to be written

int usb_dc_ep_read(const u8_t ep, u8_t *const data, const u32_t max_data_len, u32_t *const read_bytes)¶

Read data from the specified endpoint.

This function is called by the endpoint handler function, after an OUT interrupt has been received for that EP. The application must only call this function through the supplied usb_ep_callback function. This function clears the ENDPOINT NAK, if all data in the endpoint FIFO has been read, so as to accept more data from host.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table
data: Pointer to data buffer to write to
max_data_len: Max length of data to read
read_bytes: Number of bytes read. If data is NULL and max_data_len is 0 the number of bytes available for read should be returned.

int usb_dc_ep_set_callback(const u8_t ep, const usb_dc_ep_callback cb)¶

Set callback function for the specified endpoint.

Function to set callback function for notification of data received and available to application or transmit done on the selected endpoint, NULL if callback not required by application code. The callback status code is described by usb_dc_ep_cb_status_code.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table
cb: Callback function

int usb_dc_ep_read_wait(u8_t ep, u8_t *data, u32_t max_data_len, u32_t *read_bytes)¶

Read data from the specified endpoint.

This is similar to usb_dc_ep_read, the difference being that, it doesn’t clear the endpoint NAKs so that the consumer is not bogged down by further upcalls till he is done with the processing of the data. The caller should reactivate ep by invoking usb_dc_ep_read_continue() do so.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table
data: Pointer to data buffer to write to
max_data_len: Max length of data to read
read_bytes: Number of bytes read. If data is NULL and max_data_len is 0 the number of bytes available for read should be returned.

int usb_dc_ep_read_continue(u8_t ep)¶

Continue reading data from the endpoint.

Clear the endpoint NAK and enable the endpoint to accept more data from the host. Usually called after usb_dc_ep_read_wait() when the consumer is fine to accept more data. Thus these calls together act as a flow control mechanism.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table

int usb_dc_ep_mps(u8_t ep)¶

Get endpoint max packet size.

Return

Enpoint max packet size (mps)

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table

struct usb_dc_ep_cfg_data¶

#include <usb_dc.h>

USB Endpoint Configuration.

Structure containing the USB endpoint configuration.

USB Device Core Layer API ¶

group _usb_device_core_api

USB Device Core Layer API.

Defines

USB_TRANS_READ¶

USB_TRANS_WRITE¶

USB_TRANS_NO_ZLP¶

Typedefs

typedef void (*usb_ep_callback)(u8_t ep, enum usb_dc_ep_cb_status_code cb_status)¶: Callback function signature for the USB Endpoint status.

typedef int (*usb_request_handler)(struct usb_setup_packet *setup, s32_t *transfer_len, u8_t **payload_data)¶

Callback function signature for class specific requests.

Function which handles Class specific requests corresponding to an interface number specified in the device descriptor table. For host to device direction the ‘len’ and ‘payload_data’ contain the length of the received data and the pointer to the received data respectively. For device to host class requests, ‘len’ and ‘payload_data’ should be set by the callback function with the length and the address of the data to be transmitted buffer respectively.

typedef void (*usb_interface_config)(u8_t bInterfaceNumber)¶: Function for interface runtime configuration.

typedef void (*usb_transfer_callback)(u8_t ep, int tsize, void *priv)¶: Callback function signature for transfer completion.

Functions

int usb_set_config(struct usb_cfg_data *config)¶

Configure USB controller.

Function to configure USB controller. Configuration parameters must be valid or an error is returned

Return

0 on success, negative errno code on fail

Parameters

config: Pointer to configuration structure

int usb_deconfig(void)¶

Deconfigure USB controller.

This function returns the USB device to it’s initial state

Return: 0 on success, negative errno code on fail

int usb_enable(struct usb_cfg_data *config)¶

Enable USB for host/device connection.

Function to enable USB for host/device connection. Upon success, the USB module is no longer clock gated in hardware, it is now capable of transmitting and receiving on the USB bus and of generating interrupts.

Return

0 on success, negative errno code on fail.

Parameters

config: Pointer to configuration structure

int usb_disable(void)¶

Disable the USB device.

Function to disable the USB device. Upon success, the specified USB interface is clock gated in hardware, it is no longer capable of generating interrupts.

Return: 0 on success, negative errno code on fail

int usb_write(u8_t ep, const u8_t *data, u32_t data_len, u32_t *bytes_ret)¶

Write data to the specified endpoint.

Function to write data to the specified endpoint. The supplied usb_ep_callback will be called when transmission is done.

Return

0 on success, negative errno code on fail

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table
data: Pointer to data to write
data_len: Length of data requested to write. This may be zero for a zero length status packet.
bytes_ret: Bytes written to the EP FIFO. This value may be NULL if the application expects all bytes to be written

int usb_read(u8_t ep, u8_t *data, u32_t max_data_len, u32_t *ret_bytes)¶

Read data from the specified endpoint.

This function is called by the Endpoint handler function, after an OUT interrupt has been received for that EP. The application must only call this function through the supplied usb_ep_callback function.

Return

0 on success, negative errno code on fail

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table
data: Pointer to data buffer to write to
max_data_len: Max length of data to read
ret_bytes: Number of bytes read. If data is NULL and max_data_len is 0 the number of bytes available for read is returned.

int usb_ep_set_stall(u8_t ep)¶

Set STALL condition on the specified endpoint.

This function is called by USB device class handler code to set stall condition on endpoint.

Return

0 on success, negative errno code on fail

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table

int usb_ep_clear_stall(u8_t ep)¶

Clears STALL condition on the specified endpoint.

This function is called by USB device class handler code to clear stall condition on endpoint.

Return

0 on success, negative errno code on fail

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table

int usb_ep_read_wait(u8_t ep, u8_t *data, u32_t max_data_len, u32_t *read_bytes)¶

Read data from the specified endpoint.

This is similar to usb_ep_read, the difference being that, it doesn’t clear the endpoint NAKs so that the consumer is not bogged down by further upcalls till he is done with the processing of the data. The caller should reactivate ep by invoking usb_ep_read_continue() do so.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table
data: pointer to data buffer to write to
max_data_len: max length of data to read
read_bytes: Number of bytes read. If data is NULL and max_data_len is 0 the number of bytes available for read should be returned.

int usb_ep_read_continue(u8_t ep)¶

Continue reading data from the endpoint.

Clear the endpoint NAK and enable the endpoint to accept more data from the host. Usually called after usb_ep_read_wait() when the consumer is fine to accept more data. Thus these calls together acts as flow control mechanism.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table

void usb_transfer_ep_callback(u8_t ep, enum usb_dc_ep_cb_status_code)¶

Transfer management endpoint callback.

If a USB class driver wants to use high-level transfer functions, driver needs to register this callback as usb endpoint callback.

int usb_transfer(u8_t ep, u8_t *data, size_t dlen, unsigned int flags, usb_transfer_callback cb, void *priv)¶

Start a transfer.

Start a usb transfer to/from the data buffer. This function is asynchronous and can be executed in IRQ context. The provided callback will be called on transfer completion (or error) in thread context.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table
data: Pointer to data buffer to write-to/read-from
dlen: Size of data buffer
flags: Transfer flags (USB_TRANS_READ, USB_TRANS_WRITE…)
cb: Function called on transfer completion/failure
priv: Data passed back to the transfer completion callback

int usb_transfer_sync(u8_t ep, u8_t *data, size_t dlen, unsigned int flags)¶

Start a transfer and block-wait for completion.

Synchronous version of usb_transfer, wait for transfer completion before returning.

Return

number of bytes transferred on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table
data: Pointer to data buffer to write-to/read-from
dlen: Size of data buffer
flags: Transfer flags

void usb_cancel_transfer(u8_t ep)¶

Cancel any ongoing transfer on the specified endpoint.

Return

0 on success, negative errno code on fail.

Parameters

ep: Endpoint address corresponding to the one listed in the device configuration table

struct usb_ep_cfg_data¶

#include <usb_device.h>

USB Endpoint Configuration.

This structure contains configuration for the endpoint.

struct usb_interface_cfg_data¶

#include <usb_device.h>

USB Interface Configuration.

This structure contains USB interface configuration.

struct usb_cfg_data¶

#include <usb_device.h>

USB device configuration.

The Application instantiates this with given parameters added using the “usb_set_config” function. Once this function is called changes to this structure will result in undefined behavior. This structure may only be updated after calls to usb_deconfig

USB subsystem API¶

USB Device Controller API¶

USB Device Core Layer API¶

USB Device Controller API ¶

USB Device Core Layer API ¶