1/*
2 * Copyright (c) 2007-2013 ETH Zurich.
3 * All rights reserved.
4 *
5 * This file is distributed under the terms in the attached LICENSE file.
6 * If you do not find this file, copies can be found by writing to:
7 * ETH Zurich D-INFK, Haldeneggsteig 4, CH-8092 Zurich. Attn: Systems Group.
8 */
9
10#ifndef _LIBUSB_TRANSFER_H_
11#define _LIBUSB_TRANSFER_H_
12
13#include <usb/usb_xfer.h>
14
15/// USB transfer id type
16typedef uint32_t usb_xfer_id_t;
17
18/// callback function for completed transfers
19typedef void (usb_transfer_cb_t)(usb_error_t err, const void *data,
20        uint32_t data_length);
21
22// the USB control endpoint
23#define USB_ENDPOINT_CONTROL 0
24
25/**
26 * this enumeration stores the different states of an USB transfer
27 */
28enum usb_transfer_state {
29    USB_TRANSFER_STATE_SETUP,   ///< transfer is setup
30    USB_TRANSFER_STATE_STALLED, ///< transfer is in stalled state
31    USB_TRANSFER_STATE_DONE,    ///< transfer is executed successfully
32    USB_TRANSFER_STATE_ERROR,   ///< transfer is in error state
33};
34
35/// USB transfer state type
36typedef enum usb_transfer_state usb_tstate_t;
37
38/**
39 * this data structure contains the necessary data for setting up
40 * a new USB transfer
41 */
42struct usb_transfer_setup {
43    uint32_t max_bytes;             ///< maximum bytes to to transfer
44    uint32_t max_frames;            ///< the maximum bumber of frames
45    uint32_t interval;              ///< the interval for interrupt / isochr
46    uint32_t timeout;               ///< period till the transfer timeouts
47    struct usb_xfer_flags flags;    ///< some specific transfer flags
48    uint8_t type;                   ///< the type of the usb pipe
49    uint8_t direction;              ///< the direction of the data transfer
50    uint8_t endpoint;               ///< the associated endpoint of the transfer
51    uint8_t interface;              ///< the itnerface to use
52    usb_transfer_cb_t *callback;    ///< the function to call upon completition
53};
54
55/// USB transfer setup type
56typedef struct usb_transfer_setup usb_transfer_setup_t;
57
58/* setting up / freeing up  transfers  */
59usb_error_t usb_transfer_setup_control(usb_transfer_setup_t *setup,
60        usb_transfer_cb_t *done_cb, usb_xfer_id_t *ret_id);
61
62usb_error_t usb_transfer_setup_isoc(usb_transfer_setup_t *setup,
63        usb_transfer_cb_t *done_cb, usb_xfer_id_t *ret_id);
64
65usb_error_t usb_transfer_setup_bulk(usb_transfer_setup_t *setup,
66        usb_transfer_cb_t *done_cb, usb_xfer_id_t *ret_id);
67
68usb_error_t usb_transfer_setup_intr(usb_transfer_setup_t *setup,
69        usb_transfer_cb_t *done_cb, usb_xfer_id_t *ret_id);
70
71usb_error_t usb_transfer_unsetup(usb_xfer_id_t tid);
72
73/* transfer control */
74usb_error_t usb_transfer_start(usb_xfer_id_t tid);
75
76usb_error_t usb_transfer_stop(usb_xfer_id_t tid);
77
78/* stall handling */
79usb_error_t usb_transfer_clear_stall(usb_xfer_id_t tid);
80
81/* state */
82usb_error_t usb_transfer_get_state(usb_xfer_id_t tid, usb_tstate_t *ret_state);
83
84usb_error_t usb_transfer_get_status(usb_xfer_id_t tid, uint32_t *ret_actlen,
85        uint32_t *ret_length, uint32_t *ret_actframes, uint32_t *ret_numframes);
86
87#endif
88