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