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