michaelh/zephyr
1
0
Fork 0
Code Releases Activity

usb: Add transfer management API

Browse source 
The transfer API provides 'high' level functions to manage sending and
reception of USB data. A USB (class) driver has to register the generic
usb_transfer_ep_callback as endpoint status callback in order to use
the API.

With this API, the class driver does not need to take care of low-level
usb transfer management (packet splitting, ZLP, synchronization...).
The usb_transfer methods will split transfer into multiple transactions
depending endpoint max size and controller capabilities.

Once the transfer is completed, class driver is notified by a callback.
The usb_transfer method can be executed in IRQ/atomic context.
A usb_transfer synchronous helper exists which block-waits until
transfer completion.

In write case, a transfer is complete when all data has been sent.
In read case, a transfer is complete when the exact amount of data
requested has been received or if a short-pkt (including ZLP) is
received.

transfer methods are thread-safe.

A transfer can be cancelled at any time.

Signed-off-by: Loic Poulain <loic.poulain@linaro.org>
This commit is contained in:
Loic Poulain 2018-02-05 16:47:12 +01:00 • committed by Anas Nashif
commit 16921b0698
2 changed files with 345 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

65
include/usb/usb_device.h
View file

@ -298,4 +298,69 @@ int usb_ep_read_wait(u8_t ep, u8_t *data, u32_t max_data_len,
*/
int usb_ep_read_continue(u8_t ep);
/**
* Callback function signature for transfer completion.
*/
typedef void (*usb_transfer_callback)(u8_t ep, int tsize, void *priv);
/* USB transfer flags */
#define USB_TRANS_READ BIT(0) /** Read transfer flag */
#define USB_TRANS_WRITE BIT(1) /** Write transfer flag */
#define USB_TRANS_NO_ZLP BIT(2) /** No zero-length packet flag */
/**
* @brief 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.
*/
void usb_transfer_ep_callback(u8_t ep, enum usb_dc_ep_cb_status_code);
/**
* @brief 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.
*
* @param[in] ep Endpoint address corresponding to the one
* listed in the device configuration table
* @param[in] data Pointer to data buffer to write-to/read-from
* @param[in] dlen Size of data buffer
* @param[in] flags Transfer flags (USB_TRANS_READ, USB_TRANS_WRITE...)
* @param[in] cb Function called on transfer completion/failure
* @param[in] priv Data passed back to the transfer completion callback
*
* @return 0 on success, negative errno code on fail.
*/
int usb_transfer(u8_t ep, u8_t *data, size_t dlen, unsigned int flags,
usb_transfer_callback cb, void *priv);
/**
* @brief Start a transfer and block-wait for completion
*
* Synchronous version of usb_transfer, wait for transfer completion before
* returning.
*
* @param[in] ep Endpoint address corresponding to the one
* listed in the device configuration table
* @param[in] data Pointer to data buffer to write-to/read-from
* @param[in] dlen Size of data buffer
* @param[in] flags Transfer flags
*
* @return number of bytes transferred on success, negative errno code on fail.
*/
int usb_transfer_sync(u8_t ep, u8_t *data, size_t dlen, unsigned int flags);
/**
* @brief Cancel any ongoing transfer on the specified endpoint
*
* @param[in] ep Endpoint address corresponding to the one
* listed in the device configuration table
*
* @return 0 on success, negative errno code on fail.
*/
void usb_cancel_transfer(u8_t ep);
#endif /* USB_DEVICE_H_ */