projects / pub / USBasp.git / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
blame | history | raw | HEAD
More porting of the USB core to the AVR32.
[pub/USBasp.git] / LUFA / Drivers / USB / LowLevel / Endpoint.h
1 /*
2 LUFA Library
3 Copyright (C) Dean Camera, 2010.
4
5 dean [at] fourwalledcubicle [dot] com
6 www.fourwalledcubicle.com
7 */
8
9 /*
10 Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com)
11
12 Permission to use, copy, modify, distribute, and sell this
13 software and its documentation for any purpose is hereby granted
14 without fee, provided that the above copyright notice appear in
15 all copies and that both that the copyright notice and this
16 permission notice and warranty disclaimer appear in supporting
17 documentation, and that the name of the author not be used in
18 advertising or publicity pertaining to distribution of the
19 software without specific, written prior permission.
20
21 The author disclaim all warranties with regard to this
22 software, including all implied warranties of merchantability
23 and fitness. In no event shall the author be liable for any
24 special, indirect or consequential damages or any damages
25 whatsoever resulting from loss of use, data or profits, whether
26 in an action of contract, negligence or other tortious action,
27 arising out of or in connection with the use or performance of
28 this software.
29 */
30
31 /** \ingroup Group_USB
32 * @defgroup Group_EndpointManagement Endpoint Management
33 *
34 * Functions, macros and enums related to endpoint management when in USB Device mode. This
35 * module contains the endpoint management macros, as well as endpoint interrupt and data
36 * send/receive functions for various data types.
37 *
38 * @{
39 */
40
41 /** @defgroup Group_EndpointRW Endpoint Data Reading and Writing
42 *
43 * Functions, macros, variables, enums and types related to data reading and writing from and to endpoints.
44 */
45
46 /** \ingroup Group_EndpointRW
47 * @defgroup Group_EndpointPrimitiveRW Read/Write of Primitive Data Types
48 *
49 * Functions, macros, variables, enums and types related to data reading and writing of primitive data types
50 * from and to endpoints.
51 */
52
53 /** \ingroup Group_EndpointRW
54 * @defgroup Group_EndpointStreamRW Read/Write of Multi-Byte Streams
55 *
56 * Functions, macros, variables, enums and types related to data reading and writing of data streams from
57 * and to endpoints.
58 */
59
60 /** @defgroup Group_EndpointPacketManagement Endpoint Packet Management
61 *
62 * Functions, macros, variables, enums and types related to packet management of endpoints.
63 */
64
65 #ifndef __ENDPOINT_H__
66 #define __ENDPOINT_H__
67
68 /* Includes: */
69 #if defined(__AVR32__)
70 #include <avr32/io.h>
71 #include <stdint.h>
72 #include <stdbool.h>
73 #elif defined(__AVR__)
74 #include <avr/io.h>
75 #include <avr/pgmspace.h>
76 #include <avr/eeprom.h>
77 #include <stdbool.h>
78 #endif
79
80 #include "../../../Common/Common.h"
81 #include "LowLevel.h"
82 #include "../HighLevel/USBTask.h"
83
84 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
85 #include "../HighLevel/StreamCallbacks.h"
86 #endif
87
88 /* Enable C linkage for C++ Compilers: */
89 #if defined(__cplusplus)
90 extern "C" {
91 #endif
92
93 /* Preprocessor Checks: */
94 #if !defined(__INCLUDE_FROM_USB_DRIVER)
95 #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
96 #endif
97
98 /* Public Interface - May be used in end-application: */
99 /* Macros: */
100 #if defined(__AVR32__) || defined(__DOXYGEN__)
101 /** Endpoint data direction mask for \ref Endpoint_ConfigureEndpoint(). This indicates that the endpoint
102 * should be initialized in the OUT direction - i.e. data flows from host to device.
103 */
104 #define ENDPOINT_DIR_OUT 0
105
106 /** Endpoint data direction mask for \ref Endpoint_ConfigureEndpoint(). This indicates that the endpoint
107 * should be initialized in the IN direction - i.e. data flows from device to host.
108 */
109 #define ENDPOINT_DIR_IN AVR32_USBB_EPDIR_IN
110
111 /** Mask for the bank mode selection for the \ref Endpoint_ConfigureEndpoint() macro. This indicates
112 * that the endpoint should have one single bank, which requires less USB FIFO memory but results
113 * in slower transfers as only one USB device (the AVR or the host) can access the endpoint's
114 * bank at the one time.
115 */
116 #define ENDPOINT_BANK_SINGLE AVR32_USBB_EPBK_SINGLE
117
118 /** Mask for the bank mode selection for the \ref Endpoint_ConfigureEndpoint() macro. This indicates
119 * that the endpoint should have two banks, which requires more USB FIFO memory but results
120 * in faster transfers as one USB device (the AVR or the host) can access one bank while the other
121 * accesses the second bank.
122 */
123 #define ENDPOINT_BANK_DOUBLE AVR32_USBB_EPBK_DOUBLE
124 #elif defined(__AVR__)
125 #define ENDPOINT_DIR_OUT (0 << EPDIR)
126 #define ENDPOINT_DIR_IN (1 << EPDIR)
127 #define ENDPOINT_BANK_SINGLE (0 << EPBK0)
128 #define ENDPOINT_BANK_DOUBLE (1 << EPBK0)
129 #endif
130
131 /** Endpoint address for the default control endpoint, which always resides in address 0. This is
132 * defined for convenience to give more readable code when used with the endpoint macros.
133 */
134 #define ENDPOINT_CONTROLEP 0
135
136 #if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
137 /** Default size of the default control endpoint's bank, until altered by the Endpoint0Size value
138 * in the device descriptor. Not available if the FIXED_CONTROL_ENDPOINT_SIZE token is defined.
139 */
140 #define ENDPOINT_CONTROLEP_DEFAULT_SIZE 8
141 #endif
142
143 /** Endpoint number mask, for masking against endpoint addresses to retrieve the endpoint's
144 * numerical address in the device.
145 */
146 #define ENDPOINT_EPNUM_MASK 0x07
147
148 /** Endpoint direction mask, for masking against endpoint addresses to retrieve the endpoint's
149 * direction for comparing with the ENDPOINT_DESCRIPTOR_DIR_* masks.
150 */
151 #define ENDPOINT_EPDIR_MASK 0x80
152
153 /** Endpoint bank size mask, for masking against endpoint addresses to retrieve the endpoint's
154 * bank size in the device.
155 */
156 #define ENDPOINT_EPSIZE_MASK 0x7FF
157
158 /** Maximum size in bytes of a given endpoint.
159 *
160 * \param[in] n Endpoint number, a value between 0 and (ENDPOINT_TOTAL_ENDPOINTS - 1)
161 */
162 #define ENDPOINT_MAX_SIZE(n) _ENDPOINT_GET_MAXSIZE(n)
163
164 /** Indicates if the given endpoint supports double banking.
165 *
166 * \param[in] n Endpoint number, a value between 0 and (ENDPOINT_TOTAL_ENDPOINTS - 1)
167 */
168 #define ENDPOINT_DOUBLEBANK_SUPPORTED(n) _ENDPOINT_GET_DOUBLEBANK(n)
169
170 #if !defined(CONTROL_ONLY_DEVICE)
171 #if (defined(USB_SERIES_4_AVR) || defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR) || \
172 defined(USB_SERIES_UC3B_AVR) || defined(__DOXYGEN__))
173 /** Total number of endpoints (including the default control endpoint at address 0) which may
174 * be used in the device. Different USB AVR models support different amounts of endpoints,
175 * this value reflects the maximum number of endpoints for the currently selected AVR model.
176 */
177 #define ENDPOINT_TOTAL_ENDPOINTS 7
178 #else
179 #define ENDPOINT_TOTAL_ENDPOINTS 5
180 #endif
181 #else
182 #define ENDPOINT_TOTAL_ENDPOINTS 1
183 #endif
184
185 /* Pseudo-Function Macros: */
186 #if defined(__DOXYGEN__)
187 /** Indicates the number of bytes currently stored in the current endpoint's selected bank.
188 *
189 * \note The return width of this function may differ, depending on the maximum endpoint bank size
190 * of the selected AVR model.
191 *
192 * \ingroup Group_EndpointRW
193 *
194 * \return Total number of bytes in the currently selected Endpoint's FIFO buffer
195 */
196 static inline uint16_t Endpoint_BytesInEndpoint(void);
197
198 /** Get the endpoint address of the currently selected endpoint. This is typically used to save
199 * the currently selected endpoint number so that it can be restored after another endpoint has
200 * been manipulated.
201 *
202 * \return Index of the currently selected endpoint
203 */
204 static inline uint8_t Endpoint_GetCurrentEndpoint(void);
205
206 /** Selects the given endpoint number. If the address from the device descriptors is used, the
207 * value should be masked with the \ref ENDPOINT_EPNUM_MASK constant to extract only the endpoint
208 * number (and discarding the endpoint direction bit).
209 *
210 * Any endpoint operations which do not require the endpoint number to be indicated will operate on
211 * the currently selected endpoint.
212 *
213 * \param[in] EndpointNumber Endpoint number to select
214 */
215 static inline void Endpoint_SelectEndpoint(uint8_t EndpointNumber);
216
217 /** Resets the endpoint bank FIFO. This clears all the endpoint banks and resets the USB controller's
218 * In and Out pointers to the bank's contents.
219 *
220 * \param[in] EndpointNumber Endpoint number whose FIFO buffers are to be reset
221 */
222 static inline void Endpoint_ResetFIFO(uint8_t EndpointNumber);
223
224 /** Enables the currently selected endpoint so that data can be sent and received through it to
225 * and from a host.
226 *
227 * \note Endpoints must first be configured properly via \ref Endpoint_ConfigureEndpoint().
228 */
229 static inline void Endpoint_EnableEndpoint(void);
230
231 /** Disables the currently selected endpoint so that data cannot be sent and received through it
232 * to and from a host.
233 */
234 static inline void Endpoint_DisableEndpoint(void);
235
236 /** Determines if the currently selected endpoint is enabled, but not necessarily configured.
237 *
238 * \return Boolean True if the currently selected endpoint is enabled, false otherwise
239 */
240 static inline bool Endpoint_IsEnabled(void);
241
242 /** Determines if the currently selected endpoint may be read from (if data is waiting in the endpoint
243 * bank and the endpoint is an OUT direction, or if the bank is not yet full if the endpoint is an IN
244 * direction). This function will return false if an error has occurred in the endpoint, if the endpoint
245 * is an OUT direction and no packet (or an empty packet) has been received, or if the endpoint is an IN
246 * direction and the endpoint bank is full.
247 *
248 * \ingroup Group_EndpointPacketManagement
249 *
250 * \return Boolean true if the currently selected endpoint may be read from or written to, depending on its direction
251 */
252 static inline bool Endpoint_IsReadWriteAllowed(void);
253
254 /** Determines if the currently selected endpoint is configured.
255 *
256 * \return Boolean true if the currently selected endpoint has been configured, false otherwise
257 */
258 static inline bool Endpoint_IsConfigured(void);
259
260 /** Returns a mask indicating which INTERRUPT type endpoints have interrupted - i.e. their
261 * interrupt duration has elapsed. Which endpoints have interrupted can be determined by
262 * masking the return value against (1 << {Endpoint Number}).
263 *
264 * \return Mask whose bits indicate which endpoints have interrupted
265 */
266 static inline uint8_t Endpoint_GetEndpointInterrupts(void);
267
268 /** Determines if the specified endpoint number has interrupted (valid only for INTERRUPT type
269 * endpoints).
270 *
271 * \param[in] EndpointNumber Index of the endpoint whose interrupt flag should be tested
272 *
273 * \return Boolean true if the specified endpoint has interrupted, false otherwise
274 */
275 static inline bool Endpoint_HasEndpointInterrupted(uint8_t EndpointNumber);
276
277 /** Determines if the selected IN endpoint is ready for a new packet.
278 *
279 * \ingroup Group_EndpointPacketManagement
280 *
281 * \return Boolean true if the current endpoint is ready for an IN packet, false otherwise.
282 */
283 static inline bool Endpoint_IsINReady(void);
284
285 /** Determines if the selected OUT endpoint has received new packet.
286 *
287 * \ingroup Group_EndpointPacketManagement
288 *
289 * \return Boolean true if current endpoint is has received an OUT packet, false otherwise.
290 */
291 static inline bool Endpoint_IsOUTReceived(void);
292
293 /** Determines if the current CONTROL type endpoint has received a SETUP packet.
294 *
295 * \ingroup Group_EndpointPacketManagement
296 *
297 * \return Boolean true if the selected endpoint has received a SETUP packet, false otherwise.
298 */
299 static inline bool Endpoint_IsSETUPReceived(void);
300
301 /** Clears a received SETUP packet on the currently selected CONTROL type endpoint, freeing up the
302 * endpoint for the next packet.
303 *
304 * \ingroup Group_EndpointPacketManagement
305 *
306 * \note This is not applicable for non CONTROL type endpoints.
307 */
308 static inline void Endpoint_ClearSETUP(void);
309
310 /** Sends an IN packet to the host on the currently selected endpoint, freeing up the endpoint for the
311 * next packet and switching to the alternative endpoint bank if double banked.
312 *
313 * \ingroup Group_EndpointPacketManagement
314 */
315 static inline void Endpoint_ClearIN(void);
316
317 /** Acknowledges an OUT packet to the host on the currently selected endpoint, freeing up the endpoint
318 * for the next packet and switching to the alternative endpoint bank if double banked.
319 *
320 * \ingroup Group_EndpointPacketManagement
321 */
322 static inline void Endpoint_ClearOUT(void);
323
324 /** Stalls the current endpoint, indicating to the host that a logical problem occurred with the
325 * indicated endpoint and that the current transfer sequence should be aborted. This provides a
326 * way for devices to indicate invalid commands to the host so that the current transfer can be
327 * aborted and the host can begin its own recovery sequence.
328 *
329 * The currently selected endpoint remains stalled until either the \ref Endpoint_ClearStall() macro
330 * is called, or the host issues a CLEAR FEATURE request to the device for the currently selected
331 * endpoint.
332 *
333 * \ingroup Group_EndpointPacketManagement
334 */
335 static inline void Endpoint_StallTransaction(void);
336
337 /** Clears the STALL condition on the currently selected endpoint.
338 *
339 * \ingroup Group_EndpointPacketManagement
340 */
341 static inline void Endpoint_ClearStall(void);
342
343 /** Determines if the currently selected endpoint is stalled, false otherwise.
344 *
345 * \ingroup Group_EndpointPacketManagement
346 *
347 * \return Boolean true if the currently selected endpoint is stalled, false otherwise
348 */
349 static inline bool Endpoint_IsStalled(void);
350
351 /** Resets the data toggle of the currently selected endpoint. */
352 static inline void Endpoint_ResetDataToggle(void);
353
354 /** Determines the currently selected endpoint's direction.
355 *
356 * \return The currently selected endpoint's direction, as a ENDPOINT_DIR_* mask.
357 */
358 static inline uint8_t Endpoint_GetEndpointDirection(void);
359
360 /** Sets the direction of the currently selected endpoint.
361 *
362 * \param[in] DirectionMask New endpoint direction, as a ENDPOINT_DIR_* mask.
363 */
364 static inline void Endpoint_SetEndpointDirection(uint8_t DirectionMask);
365 #else
366 #if defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR)
367 #define Endpoint_BytesInEndpoint() UEBCX
368 #elif defined(USB_SERIES_4_AVR)
369 #define Endpoint_BytesInEndpoint() (((uint16_t)UEBCHX << 8) | UEBCLX)
370 #elif defined(USB_SERIES_2_AVR)
371 #define Endpoint_BytesInEndpoint() UEBCLX
372 #elif defined(USB_SERIES_UC3B_AVR)
373 #define Endpoint_BytesInEndpoint() ((__AVR32_EPREG_X(UESTA0) & AVR32_USBB_BYCT_MASK) >> AVR32_USBB_BYCT)
374 #endif
375
376 #if defined(__AVR32__)
377 #if !defined(CONTROL_ONLY_DEVICE)
378 #define Endpoint_GetCurrentEndpoint() USB_SelectedEPNumber
379 #define Endpoint_SelectEndpoint(epnum) MACROS{ USB_SelectedEPNumber = (epnum); }MACROE
380 #define Endpoint_IsReadWriteAllowed() (__AVR32_EPREG_X(UESTA0) & AVR32_USBB_RWAL_MASK)
381 #else
382 #define Endpoint_GetCurrentEndpoint() ENDPOINT_CONTROLEP
383 #define Endpoint_SelectEndpoint(epnum) (void)(epnum)
384 #endif
385
386 #define Endpoint_ResetFIFO(epnum) MACROS{ AVR32_USBB.UERST |= (AVR32_USBB_EPRST0_MASK << (epnum)); \
387 AVR32_USBB.UERST &= ~(AVR32_USBB_EPRST0_MASK << (epnum)); }MACROE
388 #define Endpoint_EnableEndpoint() MACROS{ AVR32_USBB.UERST |= (AVR32_USBB_UERST_EPEN0_MASK << (epen)); }MACROE
389 #define Endpoint_DisableEndpoint() MACROS{ AVR32_USBB.UERST &= ~(AVR32_USBB_UERST_EPEN0_MASK << (epen)); }MACROE
390 #define Endpoint_IsEnabled() ((AVR32_USBB.UERST & (AVR32_USBB_UERST_EPEN0_MASK << (epen))) ? true : false)
391
392 #define Endpoint_IsConfigured() ((__AVR32_EPREG_X(UESTA0) & AVR32_USBB_UESTA0_CFGOK_MASK) ? true : false)
393 #define Endpoint_GetEndpointInterrupts() (AVR32_USBB.UDINT >> AVR32_USBB_EP0INT)
394 #define Endpoint_HasEndpointInterrupted(n) ((AVR32_USBB.UDINT & (AVR32_USBB_EP0INT << (n))) ? true : false)
395 #define Endpoint_IsINReady() ((__AVR32_EPREG_X(UESTA0) & AVR32_USBB_TXINI) ? true : false)
396 #define Endpoint_IsOUTReceived() ((__AVR32_EPREG_X(UESTA0) & AVR32_USBB_RXOUTI) ? true : false)
397 #define Endpoint_IsSETUPReceived() ((__AVR32_EPREG_X(UESTA0) & AVR32_USBB_RXSTPI) ? true : false)
398 #define Endpoint_ClearSETUP() MACROS{ __AVR32_EPREG_X(UESTA0CLR) = AVR32_USBB_RXSTPIC; }MACROE
399 #define Endpoint_ClearIN() MACROS{ __AVR32_EPREG_X(UESTA0CLR) = AVR32_USBB_TXINIC; \
400 __AVR32_EPREG_X(UECON0CLR) = AVR32_USBB_FIFOCONC; }MACROE
401 #define Endpoint_ClearOUT() MACROS{ __AVR32_EPREG_X(UESTA0CLR) = AVR32_USBB_RXOUTI; \
402 __AVR32_EPREG_X(UECON0CLR) = AVR32_USBB_FIFOCONC; }MACROE
403 #define Endpoint_StallTransaction() MACROS{ __AVR32_EPREG_X(UECON0SET) = AVR32_USBB_STALLRQS; }MACROE
404 #define Endpoint_ClearStall() MACROS{ __AVR32_EPREG_X(UECON0CLR) = AVR32_USBB_STALLRQC; }MACROE
405 #define Endpoint_IsStalled() ((__AVR32_EPREG_X(UECON0) & AVR32_USBB_STALLRQ) ? true : false)
406 #define Endpoint_ResetDataToggle() MACROS{ __AVR32_EPREG_X(UECON0CLR) = AVR32_USBB_RSTDTS; }MACROE
407 #define Endpoint_GetEndpointDirection() ((__AVR32_EPREG_X(UECFG0) & ENDPOINT_DIR_IN) ? true : false)
408 #define Endpoint_SetEndpointDirection(dir) MACROS{ __AVR32_EPREG_X(UECFG0) = \
409 ((__AVR32_EPREG_X(UECFG0) & ENDPOINT_DIR_IN) | (dir)); }MACROE
410 #elif defined(__AVR__)
411 #if !defined(CONTROL_ONLY_DEVICE)
412 #define Endpoint_GetCurrentEndpoint() (UENUM & ENDPOINT_EPNUM_MASK)
413 #define Endpoint_SelectEndpoint(epnum) MACROS{ UENUM = (epnum); }MACROE
414 #define Endpoint_IsReadWriteAllowed() ((UEINTX & (1 << RWAL)) ? true : false)
415 #else
416 #define Endpoint_GetCurrentEndpoint() ENDPOINT_CONTROLEP
417 #define Endpoint_SelectEndpoint(epnum) (void)(epnum)
418 #endif
419
420 #define Endpoint_ResetFIFO(epnum) MACROS{ UERST = (1 << (epnum)); UERST = 0; }MACROE
421 #define Endpoint_EnableEndpoint() MACROS{ UECONX |= (1 << EPEN); }MACROE
422 #define Endpoint_DisableEndpoint() MACROS{ UECONX &= ~(1 << EPEN); }MACROE
423 #define Endpoint_IsEnabled() ((UECONX & (1 << EPEN)) ? true : false)
424
425 #define Endpoint_IsConfigured() ((UESTA0X & (1 << CFGOK)) ? true : false)
426 #define Endpoint_GetEndpointInterrupts() UEINT
427 #define Endpoint_HasEndpointInterrupted(n) ((UEINT & (1 << (n))) ? true : false)
428 #define Endpoint_IsINReady() ((UEINTX & (1 << TXINI)) ? true : false)
429 #define Endpoint_IsOUTReceived() ((UEINTX & (1 << RXOUTI)) ? true : false)
430 #define Endpoint_IsSETUPReceived() ((UEINTX & (1 << RXSTPI)) ? true : false)
431 #define Endpoint_ClearSETUP() MACROS{ UEINTX &= ~(1 << RXSTPI); }MACROE
432
433 #if !defined(CONTROL_ONLY_DEVICE)
434 #define Endpoint_ClearIN() MACROS{ uint8_t Temp = UEINTX; UEINTX = (Temp & ~(1 << TXINI)); \
435 UEINTX = (Temp & ~(1 << FIFOCON)); }MACROE
436 #define Endpoint_ClearOUT() MACROS{ uint8_t Temp = UEINTX; UEINTX = (Temp & ~(1 << RXOUTI)); \
437 UEINTX = (Temp & ~(1 << FIFOCON)); }MACROE
438 #else
439 #define Endpoint_ClearIN() MACROS{ UEINTX &= ~(1 << TXINI); }MACROE
440 #define Endpoint_ClearOUT() MACROS{ UEINTX &= ~(1 << RXOUTI); }MACROE
441 #endif
442
443 #define Endpoint_StallTransaction() MACROS{ UECONX |= (1 << STALLRQ); }MACROE
444 #define Endpoint_ClearStall() MACROS{ UECONX |= (1 << STALLRQC); }MACROE
445 #define Endpoint_IsStalled() ((UECONX & (1 << STALLRQ)) ? true : false)
446 #define Endpoint_ResetDataToggle() MACROS{ UECONX |= (1 << RSTDT); }MACROE
447 #define Endpoint_GetEndpointDirection() (UECFG0X & ENDPOINT_DIR_IN)
448 #define Endpoint_SetEndpointDirection(dir) MACROS{ UECFG0X = ((UECFG0X & ~ENDPOINT_DIR_IN) | (dir)); }MACROE
449 #endif
450 #endif
451
452 /* Enums: */
453 /** Enum for the possible error return codes of the \ref Endpoint_WaitUntilReady() function.
454 *
455 * \ingroup Group_EndpointRW
456 */
457 enum Endpoint_WaitUntilReady_ErrorCodes_t
458 {
459 ENDPOINT_READYWAIT_NoError = 0, /**< Endpoint is ready for next packet, no error. */
460 ENDPOINT_READYWAIT_EndpointStalled = 1, /**< The endpoint was stalled during the stream
461 * transfer by the host or device.
462 */
463 ENDPOINT_READYWAIT_DeviceDisconnected = 2, /**< Device was disconnected from the host while
464 * waiting for the endpoint to become ready.
465 */
466 ENDPOINT_READYWAIT_Timeout = 3, /**< The host failed to accept or send the next packet
467 * within the software timeout period set by the
468 * \ref USB_STREAM_TIMEOUT_MS macro.
469 */
470 };
471
472 /** Enum for the possible error return codes of the Endpoint_*_Stream_* functions.
473 *
474 * \ingroup Group_EndpointStreamRW
475 */
476 enum Endpoint_Stream_RW_ErrorCodes_t
477 {
478 ENDPOINT_RWSTREAM_NoError = 0, /**< Command completed successfully, no error. */
479 ENDPOINT_RWSTREAM_EndpointStalled = 1, /**< The endpoint was stalled during the stream
480 * transfer by the host or device.
481 */
482 ENDPOINT_RWSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during
483 * the transfer.
484 */
485 ENDPOINT_RWSTREAM_Timeout = 3, /**< The host failed to accept or send the next packet
486 * within the software timeout period set by the
487 * \ref USB_STREAM_TIMEOUT_MS macro.
488 */
489 ENDPOINT_RWSTREAM_CallbackAborted = 4, /**< Indicates that the stream's callback function
490 * aborted the transfer early.
491 */
492 };
493
494 /** Enum for the possible error return codes of the Endpoint_*_Control_Stream_* functions..
495 *
496 * \ingroup Group_EndpointStreamRW
497 */
498 enum Endpoint_ControlStream_RW_ErrorCodes_t
499 {
500 ENDPOINT_RWCSTREAM_NoError = 0, /**< Command completed successfully, no error. */
501 ENDPOINT_RWCSTREAM_HostAborted = 1, /**< The aborted the transfer prematurely. */
502 ENDPOINT_RWCSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during
503 * the transfer.
504 */
505 };
506
507 /* Inline Functions: */
508 /** Reads one byte from the currently selected endpoint's bank, for OUT direction endpoints.
509 *
510 * \ingroup Group_EndpointPrimitiveRW
511 *
512 * \return Next byte in the currently selected endpoint's FIFO buffer
513 */
514 static inline uint8_t Endpoint_Read_Byte(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
515 static inline uint8_t Endpoint_Read_Byte(void)
516 {
517 #if defined(__AVR32__)
518 return __AVR32_EPREG_X(UEDAT0);
519 #elif defined(__AVR__)
520 return UEDATX;
521 #endif
522 }
523
524 /** Writes one byte from the currently selected endpoint's bank, for IN direction endpoints.
525 *
526 * \ingroup Group_EndpointPrimitiveRW
527 *
528 * \param[in] Byte Next byte to write into the the currently selected endpoint's FIFO buffer
529 */
530 static inline void Endpoint_Write_Byte(const uint8_t Byte) ATTR_ALWAYS_INLINE;
531 static inline void Endpoint_Write_Byte(const uint8_t Byte)
532 {
533 #if defined(__AVR32__)
534 __AVR32_EPREG_X(UEDAT0) = Byte;
535 #elif defined(__AVR__)
536 UEDATX = Byte;
537 #endif
538 }
539
540 /** Discards one byte from the currently selected endpoint's bank, for OUT direction endpoints.
541 *
542 * \ingroup Group_EndpointPrimitiveRW
543 */
544 static inline void Endpoint_Discard_Byte(void) ATTR_ALWAYS_INLINE;
545 static inline void Endpoint_Discard_Byte(void)
546 {
547 uint8_t Dummy;
548
549 #if defined(__AVR32__)
550 Dummy = __AVR32_EPREG_X(UEDAT0);
551 #elif defined(__AVR__)
552 Dummy = UEDATX;
553 #endif
554 }
555
556 /** Reads two bytes from the currently selected endpoint's bank in little endian format, for OUT
557 * direction endpoints.
558 *
559 * \ingroup Group_EndpointPrimitiveRW
560 *
561 * \return Next word in the currently selected endpoint's FIFO buffer
562 */
563 static inline uint16_t Endpoint_Read_Word_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
564 static inline uint16_t Endpoint_Read_Word_LE(void)
565 {
566 union
567 {
568 uint16_t Word;
569 uint8_t Bytes[2];
570 } Data;
571
572 #if defined(__AVR32__)
573 Data.Bytes[0] = __AVR32_EPREG_X(UEDAT0);
574 Data.Bytes[1] = __AVR32_EPREG_X(UEDAT0);
575 #elif defined(__AVR__)
576 Data.Bytes[0] = UEDATX;
577 Data.Bytes[1] = UEDATX;
578 #endif
579
580 return Data.Word;
581 }
582
583 /** Reads two bytes from the currently selected endpoint's bank in big endian format, for OUT
584 * direction endpoints.
585 *
586 * \ingroup Group_EndpointPrimitiveRW
587 *
588 * \return Next word in the currently selected endpoint's FIFO buffer
589 */
590 static inline uint16_t Endpoint_Read_Word_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
591 static inline uint16_t Endpoint_Read_Word_BE(void)
592 {
593 union
594 {
595 uint16_t Word;
596 uint8_t Bytes[2];
597 } Data;
598
599 #if defined(__AVR32__)
600 Data.Bytes[1] = __AVR32_EPREG_X(UEDAT0);
601 Data.Bytes[0] = __AVR32_EPREG_X(UEDAT0);
602 #elif defined(__AVR__)
603 Data.Bytes[1] = UEDATX;
604 Data.Bytes[0] = UEDATX;
605 #endif
606
607 return Data.Word;
608 }
609
610 /** Writes two bytes to the currently selected endpoint's bank in little endian format, for IN
611 * direction endpoints.
612 *
613 * \ingroup Group_EndpointPrimitiveRW
614 *
615 * \param[in] Word Next word to write to the currently selected endpoint's FIFO buffer
616 */
617 static inline void Endpoint_Write_Word_LE(const uint16_t Word) ATTR_ALWAYS_INLINE;
618 static inline void Endpoint_Write_Word_LE(const uint16_t Word)
619 {
620 #if defined(__AVR32__)
621 __AVR32_EPREG_X(UEDAT0) = (Word & 0xFF);
622 __AVR32_EPREG_X(UEDAT0) = (Word >> 8);
623 #elif defined(__AVR__)
624 UEDATX = (Word & 0xFF);
625 UEDATX = (Word >> 8);
626 #endif
627 }
628
629 /** Writes two bytes to the currently selected endpoint's bank in big endian format, for IN
630 * direction endpoints.
631 *
632 * \ingroup Group_EndpointPrimitiveRW
633 *
634 * \param[in] Word Next word to write to the currently selected endpoint's FIFO buffer
635 */
636 static inline void Endpoint_Write_Word_BE(const uint16_t Word) ATTR_ALWAYS_INLINE;
637 static inline void Endpoint_Write_Word_BE(const uint16_t Word)
638 {
639 #if defined(__AVR32__)
640 __AVR32_EPREG_X(UEDAT0) = (Word >> 8);
641 __AVR32_EPREG_X(UEDAT0) = (Word & 0xFF);
642 #elif defined(__AVR__)
643 UEDATX = (Word >> 8);
644 UEDATX = (Word & 0xFF);
645 #endif
646 }
647
648 /** Discards two bytes from the currently selected endpoint's bank, for OUT direction endpoints.
649 *
650 * \ingroup Group_EndpointPrimitiveRW
651 */
652 static inline void Endpoint_Discard_Word(void) ATTR_ALWAYS_INLINE;
653 static inline void Endpoint_Discard_Word(void)
654 {
655 uint8_t Dummy;
656
657 #if defined(__AVR32__)
658 Dummy = __AVR32_EPREG_X(UEDAT0);
659 Dummy = __AVR32_EPREG_X(UEDAT0);
660 #elif defined(__AVR__)
661 Dummy = UEDATX;
662 Dummy = UEDATX;
663 #endif
664 }
665
666 /** Reads four bytes from the currently selected endpoint's bank in little endian format, for OUT
667 * direction endpoints.
668 *
669 * \ingroup Group_EndpointPrimitiveRW
670 *
671 * \return Next double word in the currently selected endpoint's FIFO buffer
672 */
673 static inline uint32_t Endpoint_Read_DWord_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
674 static inline uint32_t Endpoint_Read_DWord_LE(void)
675 {
676 union
677 {
678 uint32_t DWord;
679 uint8_t Bytes[4];
680 } Data;
681
682 #if defined(__AVR32__)
683 Data.Bytes[0] = __AVR32_EPREG_X(UEDAT0);
684 Data.Bytes[1] = __AVR32_EPREG_X(UEDAT0);
685 Data.Bytes[2] = __AVR32_EPREG_X(UEDAT0);
686 Data.Bytes[3] = __AVR32_EPREG_X(UEDAT0);
687 #elif defined(__AVR__)
688 Data.Bytes[0] = UEDATX;
689 Data.Bytes[1] = UEDATX;
690 Data.Bytes[2] = UEDATX;
691 Data.Bytes[3] = UEDATX;
692 #endif
693
694 return Data.DWord;
695 }
696
697 /** Reads four bytes from the currently selected endpoint's bank in big endian format, for OUT
698 * direction endpoints.
699 *
700 * \ingroup Group_EndpointPrimitiveRW
701 *
702 * \return Next double word in the currently selected endpoint's FIFO buffer
703 */
704 static inline uint32_t Endpoint_Read_DWord_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
705 static inline uint32_t Endpoint_Read_DWord_BE(void)
706 {
707 union
708 {
709 uint32_t DWord;
710 uint8_t Bytes[4];
711 } Data;
712
713 #if defined(__AVR32__)
714 Data.Bytes[3] = __AVR32_EPREG_X(UEDAT0);
715 Data.Bytes[2] = __AVR32_EPREG_X(UEDAT0);
716 Data.Bytes[1] = __AVR32_EPREG_X(UEDAT0);
717 Data.Bytes[0] = __AVR32_EPREG_X(UEDAT0);
718 #elif defined(__AVR__)
719 Data.Bytes[3] = UEDATX;
720 Data.Bytes[2] = UEDATX;
721 Data.Bytes[1] = UEDATX;
722 Data.Bytes[0] = UEDATX;
723 #endif
724
725 return Data.DWord;
726 }
727
728 /** Writes four bytes to the currently selected endpoint's bank in little endian format, for IN
729 * direction endpoints.
730 *
731 * \ingroup Group_EndpointPrimitiveRW
732 *
733 * \param[in] DWord Next double word to write to the currently selected endpoint's FIFO buffer
734 */
735 static inline void Endpoint_Write_DWord_LE(const uint32_t DWord) ATTR_ALWAYS_INLINE;
736 static inline void Endpoint_Write_DWord_LE(const uint32_t DWord)
737 {
738 #if defined(__AVR32__)
739 __AVR32_EPREG_X(UEDAT0) = (DWord & 0xFF);
740 __AVR32_EPREG_X(UEDAT0) = (DWord >> 8);
741 __AVR32_EPREG_X(UEDAT0) = (DWord >> 16);
742 __AVR32_EPREG_X(UEDAT0) = (DWord >> 24);
743 #elif defined(__AVR__)
744 UEDATX = (DWord & 0xFF);
745 UEDATX = (DWord >> 8);
746 UEDATX = (DWord >> 16);
747 UEDATX = (DWord >> 24);
748 #endif
749 }
750
751 /** Writes four bytes to the currently selected endpoint's bank in big endian format, for IN
752 * direction endpoints.
753 *
754 * \ingroup Group_EndpointPrimitiveRW
755 *
756 * \param[in] DWord Next double word to write to the currently selected endpoint's FIFO buffer
757 */
758 static inline void Endpoint_Write_DWord_BE(const uint32_t DWord) ATTR_ALWAYS_INLINE;
759 static inline void Endpoint_Write_DWord_BE(const uint32_t DWord)
760 {
761 #if defined(__AVR32__)
762 __AVR32_EPREG_X(UEDAT0) = (DWord >> 24);
763 __AVR32_EPREG_X(UEDAT0) = (DWord >> 16);
764 __AVR32_EPREG_X(UEDAT0) = (DWord >> 8);
765 __AVR32_EPREG_X(UEDAT0) = (DWord & 0xFF);
766 #elif defined(__AVR__)
767 UEDATX = (DWord >> 24);
768 UEDATX = (DWord >> 16);
769 UEDATX = (DWord >> 8);
770 UEDATX = (DWord & 0xFF);
771 #endif
772 }
773
774 /** Discards four bytes from the currently selected endpoint's bank, for OUT direction endpoints.
775 *
776 * \ingroup Group_EndpointPrimitiveRW
777 */
778 static inline void Endpoint_Discard_DWord(void) ATTR_ALWAYS_INLINE;
779 static inline void Endpoint_Discard_DWord(void)
780 {
781 uint8_t Dummy;
782
783 #if defined(__AVR32__)
784 Dummy = __AVR32_EPREG_X(UEDAT0);
785 Dummy = __AVR32_EPREG_X(UEDAT0);
786 Dummy = __AVR32_EPREG_X(UEDAT0);
787 Dummy = __AVR32_EPREG_X(UEDAT0);
788 #elif defined(__AVR__)
789 Dummy = UEDATX;
790 Dummy = UEDATX;
791 Dummy = UEDATX;
792 Dummy = UEDATX;
793 #endif
794 }
795
796 /* External Variables: */
797 /** Global indicating the maximum packet size of the default control endpoint located at address
798 * 0 in the device. This value is set to the value indicated in the device descriptor in the user
799 * project once the USB interface is initialized into device mode.
800 *
801 * If space is an issue, it is possible to fix this to a static value by defining the control
802 * endpoint size in the FIXED_CONTROL_ENDPOINT_SIZE token passed to the compiler in the makefile
803 * via the -D switch. When a fixed control endpoint size is used, the size is no longer dynamically
804 * read from the descriptors at runtime and instead fixed to the given value. When used, it is
805 * important that the descriptor control endpoint size value matches the size given as the
806 * FIXED_CONTROL_ENDPOINT_SIZE token - it is recommended that the FIXED_CONTROL_ENDPOINT_SIZE token
807 * be used in the descriptors to ensure this.
808 *
809 * \note This variable should be treated as read-only in the user application, and never manually
810 * changed in value.
811 */
812 #if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
813 extern uint8_t USB_ControlEndpointSize;
814 #else
815 #define USB_ControlEndpointSize FIXED_CONTROL_ENDPOINT_SIZE
816 #endif
817
818 /* Function Prototypes: */
819 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
820 #define __CALLBACK_PARAM , StreamCallbackPtr_t Callback
821 #else
822 #define __CALLBACK_PARAM
823 #endif
824
825 /** Configures the specified endpoint number with the given endpoint type, direction, bank size
826 * and banking mode. Endpoints should be allocated in ascending order by their address in the
827 * device (i.e. endpoint 1 should be configured before endpoint 2 and so on) to prevent fragmentation
828 * of the USB FIFO memory.
829 *
830 * The endpoint type may be one of the EP_TYPE_* macros listed in LowLevel.h and the direction
831 * may be either \ref ENDPOINT_DIR_OUT or \ref ENDPOINT_DIR_IN.
832 *
833 * The bank size must indicate the maximum packet size that the endpoint can handle. Different
834 * endpoint numbers can handle different maximum packet sizes - refer to the chosen USB AVR's
835 * datasheet to determine the maximum bank size for each endpoint.
836 *
837 * The banking mode must be a ENDPOINT_BANK_* mask.
838 *
839 * \note The default control endpoint does not have to be manually configured, as it is automatically
840 * configured by the library internally.
841 *
842 * \note This routine will select the specified endpoint, and the endpoint will remain selected
843 * once the routine completes regardless of if the endpoint configuration succeeds.
844 *
845 * \return Boolean true if the configuration succeeded, false otherwise
846 */
847 bool Endpoint_ConfigureEndpoint(const uintN_t Number, const uintN_t Type, const uintN_t Direction,
848 const uint16_t Size, const uintN_t Banks);
849
850 /** Spin-loops until the currently selected non-control endpoint is ready for the next packet of data
851 * to be read or written to it.
852 *
853 * \note This routine should not be called on CONTROL type endpoints.
854 *
855 * \ingroup Group_EndpointRW
856 *
857 * \return A value from the \ref Endpoint_WaitUntilReady_ErrorCodes_t enum.
858 */
859 uint8_t Endpoint_WaitUntilReady(void);
860
861 /** Completes the status stage of a control transfer on a CONTROL type endpoint automatically,
862 * with respect to the data direction. This is a convenience function which can be used to
863 * simplify user control request handling.
864 */
865 void Endpoint_ClearStatusStage(void);
866
867 /** Reads and discards the given number of bytes from the endpoint from the given buffer,
868 * discarding fully read packets from the host as needed. The last packet is not automatically
869 * discarded once the remaining bytes has been read; the user is responsible for manually
870 * discarding the last packet from the host via the \ref Endpoint_ClearOUT() macro. Between
871 * each USB packet, the given stream callback function is executed repeatedly until the next
872 * packet is ready, allowing for early aborts of stream transfers.
873 *
874 * The callback routine should be created according to the information in \ref Group_StreamCallbacks.
875 * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
876 * disabled and this function has the Callback parameter omitted.
877 *
878 * \note This routine should not be used on CONTROL type endpoints.
879 *
880 * \ingroup Group_EndpointStreamRW
881 *
882 * \param[in] Length Number of bytes to send via the currently selected endpoint.
883 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
884 *
885 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
886 */
887 uint8_t Endpoint_Discard_Stream(uint16_t Length __CALLBACK_PARAM);
888
889 /** Writes the given number of bytes to the endpoint from the given buffer in little endian,
890 * sending full packets to the host as needed. The last packet filled is not automatically sent;
891 * the user is responsible for manually sending the last written packet to the host via the
892 * \ref Endpoint_ClearIN() macro. Between each USB packet, the given stream callback function
893 * is executed repeatedly until the endpoint is ready to accept the next packet, allowing for early
894 * aborts of stream transfers.
895 *
896 * The callback routine should be created according to the information in \ref Group_StreamCallbacks.
897 * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
898 * disabled and this function has the Callback parameter omitted.
899 *
900 * \note This routine should not be used on CONTROL type endpoints.
901 *
902 * \ingroup Group_EndpointStreamRW
903 *
904 * \param[in] Buffer Pointer to the source data buffer to read from.
905 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
906 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
907 *
908 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
909 */
910 uint8_t Endpoint_Write_Stream_LE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
911
912 /** EEPROM buffer source version of \ref Endpoint_Write_Stream_LE().
913 *
914 * \ingroup Group_EndpointStreamRW
915 *
916 * \param[in] Buffer Pointer to the source data buffer to read from.
917 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
918 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
919 *
920 * \note Not available on AVR32 UC3B targets.
921 *
922 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
923 */
924 uint8_t Endpoint_Write_EStream_LE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
925
926 /** FLASH buffer source version of \ref Endpoint_Write_Stream_LE().
927 *
928 * \note The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
929 *
930 * \ingroup Group_EndpointStreamRW
931 *
932 * \param[in] Buffer Pointer to the source data buffer to read from.
933 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
934 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
935 *
936 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
937 */
938 uint8_t Endpoint_Write_PStream_LE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
939
940 /** Writes the given number of bytes to the endpoint from the given buffer in big endian,
941 * sending full packets to the host as needed. The last packet filled is not automatically sent;
942 * the user is responsible for manually sending the last written packet to the host via the
943 * \ref Endpoint_ClearIN() macro. Between each USB packet, the given stream callback function
944 * is executed repeatedly until the endpoint is ready to accept the next packet, allowing for early
945 * aborts of stream transfers.
946 *
947 * The callback routine should be created according to the information in \ref Group_StreamCallbacks.
948 * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
949 * disabled and this function has the Callback parameter omitted.
950 *
951 * \note This routine should not be used on CONTROL type endpoints.
952 *
953 * \ingroup Group_EndpointStreamRW
954 *
955 * \param[in] Buffer Pointer to the source data buffer to read from.
956 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
957 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
958 *
959 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
960 */
961 uint8_t Endpoint_Write_Stream_BE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
962
963 /** EEPROM buffer source version of \ref Endpoint_Write_Stream_BE().
964 *
965 * \ingroup Group_EndpointStreamRW
966 *
967 * \param[in] Buffer Pointer to the source data buffer to read from.
968 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
969 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
970 *
971 * \note Not available on AVR32 UC3B targets.
972 *
973 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
974 */
975 uint8_t Endpoint_Write_EStream_BE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
976
977 /** FLASH buffer source version of \ref Endpoint_Write_Stream_BE().
978 *
979 * \note The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
980 *
981 * \ingroup Group_EndpointStreamRW
982 *
983 * \param[in] Buffer Pointer to the source data buffer to read from.
984 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
985 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
986 *
987 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
988 */
989 uint8_t Endpoint_Write_PStream_BE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
990
991 /** Reads the given number of bytes from the endpoint from the given buffer in little endian,
992 * discarding fully read packets from the host as needed. The last packet is not automatically
993 * discarded once the remaining bytes has been read; the user is responsible for manually
994 * discarding the last packet from the host via the \ref Endpoint_ClearOUT() macro. Between
995 * each USB packet, the given stream callback function is executed repeatedly until the endpoint
996 * is ready to accept the next packet, allowing for early aborts of stream transfers.
997 *
998 * The callback routine should be created according to the information in \ref Group_StreamCallbacks.
999 * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
1000 * disabled and this function has the Callback parameter omitted.
1001 *
1002 * \note This routine should not be used on CONTROL type endpoints.
1003 *
1004 * \ingroup Group_EndpointStreamRW
1005 *
1006 * \param[out] Buffer Pointer to the destination data buffer to write to.
1007 * \param[in] Length Number of bytes to send via the currently selected endpoint.
1008 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
1009 *
1010 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
1011 */
1012 uint8_t Endpoint_Read_Stream_LE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
1013
1014 /** EEPROM buffer source version of \ref Endpoint_Read_Stream_LE().
1015 *
1016 * \ingroup Group_EndpointStreamRW
1017 *
1018 * \param[out] Buffer Pointer to the destination data buffer to write to, located in EEPROM memory space.
1019 * \param[in] Length Number of bytes to send via the currently selected endpoint.
1020 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
1021 *
1022 * \note Not available on AVR32 UC3B targets.
1023 *
1024 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
1025 */
1026 uint8_t Endpoint_Read_EStream_LE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
1027
1028 /** Reads the given number of bytes from the endpoint from the given buffer in big endian,
1029 * discarding fully read packets from the host as needed. The last packet is not automatically
1030 * discarded once the remaining bytes has been read; the user is responsible for manually
1031 * discarding the last packet from the host via the \ref Endpoint_ClearOUT() macro. Between
1032 * each USB packet, the given stream callback function is executed repeatedly until the endpoint
1033 * is ready to accept the next packet, allowing for early aborts of stream transfers.
1034 *
1035 * The callback routine should be created according to the information in \ref Group_StreamCallbacks.
1036 * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
1037 * disabled and this function has the Callback parameter omitted.
1038 *
1039 * \note This routine should not be used on CONTROL type endpoints.
1040 *
1041 * \ingroup Group_EndpointStreamRW
1042 *
1043 * \param[out] Buffer Pointer to the destination data buffer to write to.
1044 * \param[in] Length Number of bytes to send via the currently selected endpoint.
1045 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
1046 *
1047 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
1048 */
1049 uint8_t Endpoint_Read_Stream_BE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
1050
1051 /** EEPROM buffer source version of \ref Endpoint_Read_Stream_BE().
1052 *
1053 * \ingroup Group_EndpointStreamRW
1054 *
1055 * \param[out] Buffer Pointer to the destination data buffer to write to, located in EEPROM memory space.
1056 * \param[in] Length Number of bytes to send via the currently selected endpoint.
1057 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
1058 *
1059 * \note Not available on AVR32 UC3B targets.
1060 *
1061 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
1062 */
1063 uint8_t Endpoint_Read_EStream_BE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
1064
1065 /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in little endian,
1066 * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
1067 * in both failure and success states; the user is responsible for manually clearing the setup OUT to
1068 * finalize the transfer via the \ref Endpoint_ClearOUT() macro.
1069 *
1070 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
1071 * to clear the status stage when using this routine in a control transaction.
1072 *
1073 * \note This routine should only be used on CONTROL type endpoints.
1074 *
1075 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
1076 * together; i.e. the entire stream data must be read or written at the one time.
1077 *
1078 * \ingroup Group_EndpointStreamRW
1079 *
1080 * \param[in] Buffer Pointer to the source data buffer to read from.
1081 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
1082 *
1083 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
1084 */
1085 uint8_t Endpoint_Write_Control_Stream_LE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
1086
1087 /** EEPROM buffer source version of Endpoint_Write_Control_Stream_LE.
1088 *
1089 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
1090 * to clear the status stage when using this routine in a control transaction.
1091 *
1092 * \note This routine should only be used on CONTROL type endpoints.
1093 *
1094 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
1095 * together; i.e. the entire stream data must be read or written at the one time.
1096 *
1097 * \ingroup Group_EndpointStreamRW
1098 *
1099 * \param[in] Buffer Pointer to the source data buffer to read from.
1100 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
1101 *
1102 * \note Not available on AVR32 UC3B targets.
1103 *
1104 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
1105 */
1106 uint8_t Endpoint_Write_Control_EStream_LE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
1107
1108 /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_LE().
1109 *
1110 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
1111 * to clear the status stage when using this routine in a control transaction.
1112 *
1113 * \note The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
1114 *
1115 * \note This routine should only be used on CONTROL type endpoints.
1116 *
1117 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
1118 * together; i.e. the entire stream data must be read or written at the one time.
1119 *
1120 * \ingroup Group_EndpointStreamRW
1121 *
1122 * \param[in] Buffer Pointer to the source data buffer to read from.
1123 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
1124 *
1125 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
1126 */
1127 uint8_t Endpoint_Write_Control_PStream_LE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
1128
1129 /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in big endian,
1130 * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
1131 * in both failure and success states; the user is responsible for manually clearing the setup OUT to
1132 * finalize the transfer via the \ref Endpoint_ClearOUT() macro.
1133 *
1134 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
1135 * to clear the status stage when using this routine in a control transaction.
1136 *
1137 * \note This routine should only be used on CONTROL type endpoints.
1138 *
1139 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
1140 * together; i.e. the entire stream data must be read or written at the one time.
1141 *
1142 * \ingroup Group_EndpointStreamRW
1143 *
1144 * \param[in] Buffer Pointer to the source data buffer to read from.
1145 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
1146 *
1147 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
1148 */
1149 uint8_t Endpoint_Write_Control_Stream_BE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
1150
1151 /** EEPROM buffer source version of \ref Endpoint_Write_Control_Stream_BE().
1152 *
1153 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
1154 * to clear the status stage when using this routine in a control transaction.
1155 *
1156 * \note This routine should only be used on CONTROL type endpoints.
1157 *
1158 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
1159 * together; i.e. the entire stream data must be read or written at the one time.
1160 *
1161 * \ingroup Group_EndpointStreamRW
1162 *
1163 * \param[in] Buffer Pointer to the source data buffer to read from.
1164 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
1165 *
1166 * \note Not available on AVR32 UC3B targets.
1167 *
1168 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
1169 */
1170 uint8_t Endpoint_Write_Control_EStream_BE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
1171
1172 /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_BE().
1173 *
1174 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
1175 * to clear the status stage when using this routine in a control transaction.
1176 *
1177 * \note The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
1178 *
1179 * \note This routine should only be used on CONTROL type endpoints.
1180 *
1181 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
1182 * together; i.e. the entire stream data must be read or written at the one time.
1183 *
1184 * \ingroup Group_EndpointStreamRW
1185 *
1186 * \param[in] Buffer Pointer to the source data buffer to read from.
1187 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
1188 *
1189 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
1190 */
1191 uint8_t Endpoint_Write_Control_PStream_BE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
1192
1193 /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in little endian,
1194 * discarding fully read packets from the host as needed. The device IN acknowledgement is not
1195 * automatically sent after success or failure states; the user is responsible for manually sending the
1196 * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro.
1197 *
1198 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
1199 * to clear the status stage when using this routine in a control transaction.
1200 *
1201 * \note This routine should only be used on CONTROL type endpoints.
1202 *
1203 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
1204 * together; i.e. the entire stream data must be read or written at the one time.
1205 *
1206 * \ingroup Group_EndpointStreamRW
1207 *
1208 * \param[out] Buffer Pointer to the destination data buffer to write to.
1209 * \param[in] Length Number of bytes to send via the currently selected endpoint.
1210 *
1211 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
1212 */
1213 uint8_t Endpoint_Read_Control_Stream_LE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
1214
1215 /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_LE().
1216 *
1217 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
1218 * to clear the status stage when using this routine in a control transaction.
1219 *
1220 * \note This routine should only be used on CONTROL type endpoints.
1221 *
1222 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
1223 * together; i.e. the entire stream data must be read or written at the one time.
1224 *
1225 * \ingroup Group_EndpointStreamRW
1226 *
1227 * \param[out] Buffer Pointer to the destination data buffer to write to.
1228 * \param[in] Length Number of bytes to send via the currently selected endpoint.
1229 *
1230 * \note Not available on AVR32 UC3B targets.
1231 *
1232 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
1233 */
1234 uint8_t Endpoint_Read_Control_EStream_LE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
1235
1236 /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in big endian,
1237 * discarding fully read packets from the host as needed. The device IN acknowledgement is not
1238 * automatically sent after success or failure states; the user is responsible for manually sending the
1239 * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro.
1240 *
1241 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
1242 * to clear the status stage when using this routine in a control transaction.
1243 *
1244 * \note This routine should only be used on CONTROL type endpoints.
1245 *
1246 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
1247 * together; i.e. the entire stream data must be read or written at the one time.
1248 *
1249 * \ingroup Group_EndpointStreamRW
1250 *
1251 * \param[out] Buffer Pointer to the destination data buffer to write to.
1252 * \param[in] Length Number of bytes to send via the currently selected endpoint.
1253 *
1254 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
1255 */
1256 uint8_t Endpoint_Read_Control_Stream_BE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
1257
1258 /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_BE().
1259 *
1260 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
1261 * to clear the status stage when using this routine in a control transaction.
1262 *
1263 * \note This routine should only be used on CONTROL type endpoints.
1264 *
1265 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
1266 * together; i.e. the entire stream data must be read or written at the one time.
1267 *
1268 * \ingroup Group_EndpointStreamRW
1269 *
1270 * \param[out] Buffer Pointer to the destination data buffer to write to.
1271 * \param[in] Length Number of bytes to send via the currently selected endpoint.
1272 *
1273 * \note Not available on AVR32 UC3B targets.
1274 *
1275 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
1276 */
1277 uint8_t Endpoint_Read_Control_EStream_BE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
1278
1279 /* Private Interface - For use in library only: */
1280 #if !defined(__DOXYGEN__)
1281 /* Macros: */
1282 #if defined(__AVR32__)
1283 #define Endpoint_AllocateMemory() MACROS{ __AVR32_EPREG_X(UECFG10) |= AVR32_USBB_UECFG0_ALLOC_MASK; }MACROE
1284 #define Endpoint_DeallocateMemory() MACROS{ __AVR32_EPREG_X(UECFG10) &= ~AVR32_USBB_UECFG0_ALLOC_MASK; }MACROE
1285
1286 #define Endpoint_ConfigureEndpoint(Number, Type, Direction, Size, Banks) \
1287 Endpoint_ConfigureEndpoint_Prv((Number), \
1288 (((Type) << AVR32_USBB_UECFG0_EPTYPE) | (Direction)), \
1289 (AVR32_USBB_UECFG0_ALLOC_MASK | (Banks) | \
1290 (__builtin_constant_p(Size) ? \
1291 Endpoint_BytesToEPSizeMask(Size) : \
1292 Endpoint_BytesToEPSizeMaskDynamic(Size))))
1293 #elif defined(__AVR__)
1294 #define Endpoint_AllocateMemory() MACROS{ UECFG1X |= (1 << ALLOC); }MACROE
1295 #define Endpoint_DeallocateMemory() MACROS{ UECFG1X &= ~(1 << ALLOC); }MACROE
1296
1297 #define Endpoint_ConfigureEndpoint(Number, Type, Direction, Size, Banks) \
1298 Endpoint_ConfigureEndpoint_Prv((Number), \
1299 (((Type) << EPTYPE0) | (Direction)), \
1300 ((1 << ALLOC) | (Banks) | \
1301 (__builtin_constant_p(Size) ? \
1302 Endpoint_BytesToEPSizeMask(Size) : \
1303 Endpoint_BytesToEPSizeMaskDynamic(Size))))
1304 #endif
1305
1306 #define _ENDPOINT_GET_MAXSIZE(n) _ENDPOINT_GET_MAXSIZE2(ENDPOINT_DETAILS_EP ## n)
1307 #define _ENDPOINT_GET_MAXSIZE2(details) _ENDPOINT_GET_MAXSIZE3(details)
1308 #define _ENDPOINT_GET_MAXSIZE3(maxsize, db) maxsize
1309
1310 #define _ENDPOINT_GET_DOUBLEBANK(n) _ENDPOINT_GET_DOUBLEBANK2(ENDPOINT_DETAILS_EP ## n)
1311 #define _ENDPOINT_GET_DOUBLEBANK2(details) _ENDPOINT_GET_DOUBLEBANK3(details)
1312 #define _ENDPOINT_GET_DOUBLEBANK3(maxsize, db) db
1313
1314 #if defined(USB_SERIES_4_AVR) || defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR)
1315 #define ENDPOINT_DETAILS_EP0 64, true
1316 #define ENDPOINT_DETAILS_EP1 256, true
1317 #define ENDPOINT_DETAILS_EP2 64, true
1318 #define ENDPOINT_DETAILS_EP3 64, true
1319 #define ENDPOINT_DETAILS_EP4 64, true
1320 #define ENDPOINT_DETAILS_EP5 64, true
1321 #define ENDPOINT_DETAILS_EP6 64, true
1322 #elif defined(USB_SERIES_UC3B_AVR)
1323 #define ENDPOINT_DETAILS_EP0 64, false
1324 #define ENDPOINT_DETAILS_EP1 64, true
1325 #define ENDPOINT_DETAILS_EP2 64, true
1326 #define ENDPOINT_DETAILS_EP3 64, true
1327 #define ENDPOINT_DETAILS_EP4 64, true
1328 #define ENDPOINT_DETAILS_EP5 256, true
1329 #define ENDPOINT_DETAILS_EP6 256, true
1330 #elif defined(USB_SERIES_2_AVR)
1331 #define ENDPOINT_DETAILS_EP0 64, true
1332 #define ENDPOINT_DETAILS_EP1 64, false
1333 #define ENDPOINT_DETAILS_EP2 64, false
1334 #define ENDPOINT_DETAILS_EP3 64, true
1335 #define ENDPOINT_DETAILS_EP4 64, true
1336 #endif
1337
1338 /* Function Prototypes: */
1339 void Endpoint_ClearEndpoints(void);
1340 uintN_t Endpoint_BytesToEPSizeMaskDynamic(const uint16_t Size);
1341 bool Endpoint_ConfigureEndpoint_Prv(const uintN_t Number, const uintN_t UECFG0XData, const uintN_t UECFG1XData);
1342
1343 /* Inline Functions: */
1344 static inline uintN_t Endpoint_BytesToEPSizeMask(const uint16_t Bytes) ATTR_WARN_UNUSED_RESULT ATTR_CONST ATTR_ALWAYS_INLINE;
1345 static inline uintN_t Endpoint_BytesToEPSizeMask(const uint16_t Bytes)
1346 {
1347 #if defined(__AVR32__)
1348 uint8_t MaskVal = 0;
1349 uint16_t CheckBytes = 8;
1350
1351 while (CheckBytes < Bytes)
1352 {
1353 MaskVal++;
1354 CheckBytes <<= 1;
1355 }
1356
1357 return (MaskVal << AVR32_USBB_EPSIZE);
1358 #else
1359 uint8_t MaskVal = 0;
1360 uint16_t CheckBytes = 8;
1361
1362 while (CheckBytes < Bytes)
1363 {
1364 MaskVal++;
1365 CheckBytes <<= 1;
1366 }
1367
1368 return (MaskVal << EPSIZE0);
1369 #endif
1370 }
1371
1372 #endif
1373
1374 /* Disable C linkage for C++ Compilers: */
1375 #if defined(__cplusplus)
1376 }
1377 #endif
1378
1379 #endif
1380
1381 /** @} */
USB isp AVR programmer