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