summaryrefslogtreecommitdiffhomepage
path: root/digital/zigbit/bitcloud/stack/Components/HAL/include/usb.h
blob: d561d8b5064c0c0208c62937d8e2817951ba8095 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
/**************************************************************************//**
  \file  usb.h

  \brief The header file describes the usb interface

  \author
    Atmel Corporation: http://www.atmel.com \n
    Support email: avr@atmel.com

  Copyright (c) 2008-2011, Atmel Corporation. All rights reserved.
  Licensed under Atmel's Limited License Agreement (BitCloudTM).

  \internal
  History:
    17/07/08 A. Khromykh - Created
 ******************************************************************************/
/******************************************************************************
 *   WARNING: CHANGING THIS FILE MAY AFFECT CORE FUNCTIONALITY OF THE STACK.  *
 *   EXPERT USERS SHOULD PROCEED WITH CAUTION.                                *
 ******************************************************************************/

#ifndef _USB_H
#define _USB_H

/******************************************************************************
                   Define(s) section
******************************************************************************/
// \cond
// USB device API return values
// Indicates the operation was successful
#define STATUS_SUCCESS             0
// Endpoint/device is already busy
#define STATUS_BUSY                1
// Operation has been aborted
#define STATUS_ABORTED             2
// Operation has been aborted because the device was configured
#define STATUS_RESET               3

// USB device states
// The device is currently suspended
#define DEVICE_SUSPENDED            0
// USB cable is plugged into the device
#define DEVICE_ATTACHED             1
// Host is providing +5V through the USB cable
#define DEVICE_POWERED              2
// Device has been reset
#define DEVICE_DEFAULT              3
// The device has been given an address on the bus
#define DEVICE_ADDRESS              5
// A valid configuration has been selected
#define DEVICE_CONFIGURED           6
// \endcond

/******************************************************************************
                   Types section
******************************************************************************/
// transaction callback type
typedef void (* TransferCallback_t)(void *pArg, uint8_t status, uint16_t transferred, uint16_t remaining);

BEGIN_PACK
// Usb endpoint descriptor
typedef struct PACK
{
  uint8_t  bLength;          // Size of the descriptor in bytes
  uint8_t  bDescriptorType;  // Descriptor type
  uint8_t  bEndpointAddress; // Address and direction of the endpoint
  uint8_t  bmAttributes;     // Endpoint type and additional characteristics (for isochronous endpoints)
  uint16_t wMaxPacketSize;   // Maximum packet size (in bytes) of the endpoint
  uint8_t  bInterval;        // Polling rate of the endpoint
} HAL_UsbEndPointDescptr_t;
END_PACK

/******************************************************************************
                   Prototypes section
******************************************************************************/
/**************************************************************************//**
\brief Registers user's request handler

\param[in]
  f - pointer to user's callback
******************************************************************************/
void HAL_RegisterRequestHandler(void (* f)(uint8_t *req));

/**************************************************************************//**
\brief Registers user's end of bus reset handler

\param[in]
  f - pointer to user's callback
******************************************************************************/
void HAL_RegisterEndOfBusResetHandler(void (* f)(void));

/**************************************************************************//**
\brief Registers user's resume handler

\param[in]
  f - pointer to user's callback
******************************************************************************/
void HAL_RegisterResumeHandler(void (* f)(void));

/**************************************************************************//**
\brief Registers user's suspend handler

\param[in]
  f - pointer to user's callback
******************************************************************************/
void HAL_RegisterSuspendHandler(void (* f)(void));

/**************************************************************************//**
\brief Configures an endpoint according to its Endpoint Descriptor.

\param[in]
  descriptor - Pointer to an Endpoint descriptor.
******************************************************************************/
void HAL_ConfigureEndpoint(HAL_UsbEndPointDescptr_t *descriptor);

/**************************************************************************//**
\brief Sends data through a USB endpoint. Sets up the transfer descriptor,
writes one or two data payloads (depending on the number of FIFO bank
for the endpoint) and then starts the actual transfer. The operation is
complete when all the data has been sent.

*If the size of the buffer is greater than the size of the endpoint
(or twice the size if the endpoint has two FIFO banks), then the buffer
must be kept allocated until the transfer is finished*. This means that
it is not possible to declare it on the stack (i.e. as a local variable
of a function which returns after starting a transfer).

\param[in]
  eptnum - Endpoint number.
\param[in]
  data - Pointer to a buffer with the data to send.
\param[in]
  size - Size of the data buffer.
\param[in]
  callback - Optional callback function to invoke when the transfer is complete.
\param[in]
  argument - Optional argument to the callback function.

\return
  STATUS_SUCCESS if the transfer has been started; otherwise, the
  corresponding error status code.
******************************************************************************/
uint8_t HAL_UsbWrite(uint8_t eptnum, void *data, uint32_t size, TransferCallback_t callback, void *argument);

/**************************************************************************//**
\brief Reads incoming data on an USB endpoint This methods sets the transfer
descriptor and activate the endpoint interrupt. The actual transfer is
then carried out by the endpoint interrupt handler. The Read operation
finishes either when the buffer is full, or a short packet (inferior to
endpoint maximum  size) is received.

*The buffer must be kept allocated until the transfer is finished*.

\param[in]
  eptnum - Endpoint number.
\param[in]
  data - Pointer to a data buffer.
\param[in]
  size - Size of the data buffer in bytes.
\param[in]
  callback - Optional end-of-transfer callback function.
\param[in]
  argument - Optional argument to the callback function.

\return
  STATUS_SUCCESS if the read operation has been started; otherwise,
  the corresponding error code.
******************************************************************************/
uint8_t HAL_UsbRead(uint8_t eptnum, void *data, uint32_t size, TransferCallback_t callback, void *argument);

/**************************************************************************//**
\brief Sets the HALT feature on the given endpoint (if not already in this state).

\param[in]
  eptnum - Endpoint number.
******************************************************************************/
void HAL_Halt(uint8_t eptnum);

/**************************************************************************//**
\brief Clears the Halt feature on the given endpoint.

\param[in]
  eptnum - Endpoint number.
******************************************************************************/
void HAL_Unhalt(uint8_t eptnum);

/**************************************************************************//**
\brief Returns the current Halt status of an endpoint.

\param[in]
  eptnum - Endpoint number.

\return
  1 - if the endpoint is currently halted;
  0 - otherwise.
******************************************************************************/
uint8_t HAL_IsHalted(uint8_t eptnum);

/**************************************************************************//**
\brief Causes the given endpoint to acknowledge the next packet it receives with
a STALL handshake.

\param[in]
  eptnum - Endpoint number.

\return
  STATUS_SUCCESS or STATUS_BUSY.
******************************************************************************/
uint8_t HAL_Stall(uint8_t eptnum);

/**************************************************************************//**
\brief Sets the device address to the given value.

\param[in]
  address - New device address.
******************************************************************************/
void HAL_SetAddress(uint8_t *address);

/**************************************************************************//**
\brief Sets the current device configuration.

\param[in]
  cfgnum - Configuration number to set.
******************************************************************************/
void HAL_SetConfiguration(uint8_t cfgnum);

/**************************************************************************//**
\brief Initializes the USB driver. This function must be called before host
bus reset and after pull up is connected to D+. After pull up was connected
to D+ host resets device with 100ms delay.

\param[in]
  reqMem - Memory for usb request. Memory is allocated by user.
******************************************************************************/
void HAL_UsbInit(uint8_t *reqMem);

/**************************************************************************//**
\brief Returns the current state of the USB device.

\return
  Device current state.
******************************************************************************/
uint8_t HAL_GetState(void);

#endif /* _USB_H */