projects / pub / USBasp.git / blob
? search:


172ab33d76d31db51e47f2fa033ea8902cd21d3a
[pub/USBasp.git] / LUFA / Drivers / USB / LowLevel / Endpoint.h
1 /*
2 LUFA Library
3 Copyright (C) Dean Camera, 2009.
4
5 dean [at] fourwalledcubicle [dot] com
6 www.fourwalledcubicle.com
7 */
8
9 /*
10 Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com)
11
12 Permission to use, copy, modify, and distribute this software
13 and its documentation for any purpose and without fee is hereby
14 granted, provided that the above copyright notice appear in all
15 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/recieve 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 /** @defgroup Group_EndpointPacketManagement Endpoint Packet Management
47 *
48 * Functions, macros, variables, enums and types related to packet management of endpoints.
49 */
50
51 #ifndef __ENDPOINT_H__
52 #define __ENDPOINT_H__
53
54 /* Includes: */
55 #include <avr/io.h>
56 #include <stdbool.h>
57
58 #include "../../../Common/Common.h"
59 #include "../HighLevel/USBTask.h"
60
61 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
62 #include "../HighLevel/StreamCallbacks.h"
63 #endif
64
65 /* Enable C linkage for C++ Compilers: */
66 #if defined(__cplusplus)
67 extern "C" {
68 #endif
69
70 /* Public Interface - May be used in end-application: */
71 /* Macros: */
72 /** Endpoint data direction mask for \ref Endpoint_ConfigureEndpoint(). This indicates that the endpoint
73 * should be initialized in the OUT direction - i.e. data flows from host to device.
74 */
75 #define ENDPOINT_DIR_OUT (0 << EPDIR)
76
77 /** Endpoint data direction mask for \ref Endpoint_ConfigureEndpoint(). This indicates that the endpoint
78 * should be initialized in the IN direction - i.e. data flows from device to host.
79 */
80 #define ENDPOINT_DIR_IN (1 << EPDIR)
81
82 /** Mask for the bank mode selection for the \ref Endpoint_ConfigureEndpoint() macro. This indicates
83 * that the endpoint should have one single bank, which requires less USB FIFO memory but results
84 * in slower transfers as only one USB device (the AVR or the host) can access the endpoint's
85 * bank at the one time.
86 */
87 #define ENDPOINT_BANK_SINGLE (0 << EPBK0)
88
89 /** Mask for the bank mode selection for the \ref Endpoint_ConfigureEndpoint() macro. This indicates
90 * that the endpoint should have two banks, which requires more USB FIFO memory but results
91 * in faster transfers as one USB device (the AVR or the host) can access one bank while the other
92 * accesses the second bank.
93 */
94 #define ENDPOINT_BANK_DOUBLE (1 << EPBK0)
95
96 /** Endpoint address for the default control endpoint, which always resides in address 0. This is
97 * defined for convenience to give more readable code when used with the endpoint macros.
98 */
99 #define ENDPOINT_CONTROLEP 0
100
101 #if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
102 /** Default size of the default control endpoint's bank, until altered by the Endpoint0Size value
103 * in the device descriptor. Not available if the FIXED_CONTROL_ENDPOINT_SIZE token is defined.
104 */
105 #define ENDPOINT_CONTROLEP_DEFAULT_SIZE 8
106 #endif
107
108 /** Endpoint number mask, for masking against endpoint addresses to retrieve the endpoint's
109 * numerical address in the device.
110 */
111 #define ENDPOINT_EPNUM_MASK 0x03
112
113 /** Endpoint bank size mask, for masking against endpoint addresses to retrieve the endpoint's
114 * bank size in the device.
115 */
116 #define ENDPOINT_EPSIZE_MASK 0x7FF
117
118 /** Maximum size in bytes of a given endpoint.
119 *
120 * \param n Endpoint number, a value between 0 and (ENDPOINT_TOTAL_ENDPOINTS - 1)
121 */
122 #define ENDPOINT_MAX_SIZE(n) _ENDPOINT_GET_MAXSIZE(n)
123
124 /** Indicates if the given endpoint supports double banking.
125 *
126 * \param n Endpoint number, a value between 0 and (ENDPOINT_TOTAL_ENDPOINTS - 1)
127 */
128 #define ENDPOINT_DOUBLEBANK_SUPPORTED(n) _ENDPOINT_GET_DOUBLEBANK(n)
129
130 #if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER) || defined(__DOXYGEN__)
131 /** Total number of endpoints (including the default control endpoint at address 0) which may
132 * be used in the device. Different USB AVR models support different amounts of endpoints,
133 * this value reflects the maximum number of endpoints for the currently selected AVR model.
134 */
135 #define ENDPOINT_TOTAL_ENDPOINTS 7
136 #else
137 #define ENDPOINT_TOTAL_ENDPOINTS 5
138 #endif
139
140 /** Interrupt definition for the endpoint SETUP interrupt (for CONTROL type endpoints). Should be
141 * used with the USB_INT_* macros located in USBInterrupt.h.
142 *
143 * This interrupt will fire if enabled on a CONTROL type endpoint if a new control packet is
144 * received from the host.
145 *
146 * \note This interrupt must be enabled and cleared on *each* endpoint which requires it (after the
147 * endpoint is selected), and will fire the common endpoint interrupt vector.
148 *
149 * \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
150 */
151 #define ENDPOINT_INT_SETUP UEIENX, (1 << RXSTPE), UEINTX, (1 << RXSTPI)
152
153 /** Interrupt definition for the endpoint IN interrupt (for INTERRUPT type endpoints). Should be
154 * used with the USB_INT_* macros located in USBInterrupt.h.
155 *
156 * This interrupt will fire if enabled on an INTERRUPT type endpoint if a the endpoint interrupt
157 * period has elapsed and the endpoint is ready for a new packet to be written to its FIFO buffer
158 * (if required).
159 *
160 * \note This interrupt must be enabled and cleared on *each* endpoint which requires it (after the
161 * endpoint is selected), and will fire the common endpoint interrupt vector.
162 *
163 * \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
164 */
165 #define ENDPOINT_INT_IN UEIENX, (1 << TXINE) , UEINTX, (1 << TXINI)
166
167 /** Interrupt definition for the endpoint OUT interrupt (for INTERRUPT type endpoints). Should be
168 * used with the USB_INT_* macros located in USBInterrupt.h.
169 *
170 * This interrupt will fire if enabled on an INTERRUPT type endpoint if a the endpoint interrupt
171 * period has elapsed and the endpoint is ready for a packet from the host to be read from its
172 * FIFO buffer (if received).
173 *
174 * \note This interrupt must be enabled and cleared on *each* endpoint which requires it (after the
175 * endpoint is selected), and will fire the common endpoint interrupt vector.
176 *
177 * \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
178 */
179 #define ENDPOINT_INT_OUT UEIENX, (1 << RXOUTE), UEINTX, (1 << RXOUTI)
180
181 /* Pseudo-Function Macros: */
182 #if defined(__DOXYGEN__)
183 /** Indicates the number of bytes currently stored in the current endpoint's selected bank.
184 *
185 * \note The return width of this function may differ, depending on the maximum endpoint bank size
186 * of the selected AVR model.
187 *
188 * \ingroup Group_EndpointRW
189 *
190 * \return Total number of bytes in the currently selected Endpoint's FIFO buffer
191 */
192 static inline uint16_t Endpoint_BytesInEndpoint(void);
193
194 /** Get the endpoint address of the currently selected endpoint. This is typically used to save
195 * the currently selected endpoint number so that it can be restored after another endpoint has
196 * been manipulated.
197 *
198 * \return Index of the currently selected endpoint
199 */
200 static inline uint8_t Endpoint_GetCurrentEndpoint(void);
201
202 /** Selects the given endpoint number. If the address from the device descriptors is used, the
203 * value should be masked with the \ref ENDPOINT_EPNUM_MASK constant to extract only the endpoint
204 * number (and discarding the endpoint direction bit).
205 *
206 * Any endpoint operations which do not require the endpoint number to be indicated will operate on
207 * the currently selected endpoint.
208 *
209 * \param EndpointNumber Endpoint number to select
210 */
211 static inline void Endpoint_SelectEndpoint(uint8_t EndpointNumber);
212
213 /** Resets the endpoint bank FIFO. This clears all the endpoint banks and resets the USB controller's
214 * In and Out pointers to the bank's contents.
215 *
216 * \param EndpointNumber Endpoint number whose FIFO buffers are to be reset
217 */
218 static inline void Endpoint_ResetFIFO(uint8_t EndpointNumber);
219
220 /** Enables the currently selected endpoint so that data can be sent and received through it to
221 * and from a host.
222 *
223 * \note Endpoints must first be configured properly via \ref Endpoint_ConfigureEndpoint().
224 */
225 static inline void Endpoint_EnableEndpoint(void);
226
227 /** Disables the currently selected endpoint so that data cannot be sent and received through it
228 * to and from a host.
229 */
230 static inline void Endpoint_DisableEndpoint(void);
231
232 /** Determines if the currently selected endpoint is enabled, but not necessarily configured.
233 *
234 * \return Boolean True if the currently selected endpoint is enabled, false otherwise
235 */
236 static inline bool Endpoint_IsEnabled(void);
237
238 /** Determines if the currently selected endpoint may be read from (if data is waiting in the endpoint
239 * bank and the endpoint is an OUT direction, or if the bank is not yet full if the endpoint is an IN
240 * direction). This function will return false if an error has occurred in the endpoint, if the endpoint
241 * is an OUT direction and no packet (or an empty packet) has been received, or if the endpoint is an IN
242 * direction and the endpoint bank is full.
243 *
244 * \ingroup Group_EndpointPacketManagement
245 *
246 * \return Boolean true if the currently selected endpoint may be read from or written to, depending on its direction
247 */
248 static inline bool Endpoint_IsReadWriteAllowed(void);
249
250 /** Determines if the currently selected endpoint is configured.
251 *
252 * \return Boolean true if the currently selected endpoint has been configured, false otherwise
253 */
254 static inline bool Endpoint_IsConfigured(void);
255
256 /** Returns a mask indicating which INTERRUPT type endpoints have interrupted - i.e. their
257 * interrupt duration has elapsed. Which endpoints have interrupted can be determined by
258 * masking the return value against (1 << {Endpoint Number}).
259 *
260 * \return Mask whose bits indicate which endpoints have interrupted
261 */
262 static inline uint8_t Endpoint_GetEndpointInterrupts(void);
263
264 /** Clears the endpoint interrupt flag. This clears the specified endpoint number's interrupt
265 * mask in the endpoint interrupt flag register.
266 *
267 * \param EndpointNumber Index of the endpoint whose interrupt flag should be cleared
268 */
269 static inline void Endpoint_ClearEndpointInterrupt(uint8_t EndpointNumber);
270
271 /** Determines if the specified endpoint number has interrupted (valid only for INTERRUPT type
272 * endpoints).
273 *
274 * \param EndpointNumber Index of the endpoint whose interrupt flag should be tested
275 *
276 * \return Boolean true if the specified endpoint has interrupted, false otherwise
277 */
278 static inline bool Endpoint_HasEndpointInterrupted(uint8_t EndpointNumber);
279
280 /** Determines if the selected IN endpoint is ready for a new packet.
281 *
282 * \ingroup Group_EndpointPacketManagement
283 *
284 * \return Boolean true if the current endpoint is ready for an IN packet, false otherwise.
285 */
286 static inline bool Endpoint_IsINReady(void);
287
288 /** Determines if the selected OUT endpoint has received new packet.
289 *
290 * \ingroup Group_EndpointPacketManagement
291 *
292 * \return Boolean true if current endpoint is has received an OUT packet, false otherwise.
293 */
294 static inline bool Endpoint_IsOUTReceived(void);
295
296 /** Determines if the current CONTROL type endpoint has received a SETUP packet.
297 *
298 * \ingroup Group_EndpointPacketManagement
299 *
300 * \return Boolean true if the selected endpoint has received a SETUP packet, false otherwise.
301 */
302 static inline bool Endpoint_IsSETUPReceived(void);
303
304 /** Clears a received SETUP packet on the currently selected CONTROL type endpoint, freeing up the
305 * endpoint for the next packet.
306 *
307 * \ingroup Group_EndpointPacketManagement
308 *
309 * \note This is not applicable for non CONTROL type endpoints.
310 */
311 static inline void Endpoint_ClearSETUP(void);
312
313 /** Sends an IN packet to the host on the currently selected endpoint, freeing up the endpoint for the
314 * next packet and switching to the alternative endpoint bank if double banked.
315 *
316 * \ingroup Group_EndpointPacketManagement
317 */
318 static inline void Endpoint_ClearIN(void);
319
320 /** Acknowledges an OUT packet to the host on the currently selected endpoint, freeing up the endpoint
321 * for the next packet and switching to the alternative endpoint bank if double banked.
322 *
323 * \ingroup Group_EndpointPacketManagement
324 */
325 static inline void Endpoint_ClearOUT(void);
326
327 /** Stalls the current endpoint, indicating to the host that a logical problem occurred with the
328 * indicated endpoint and that the current transfer sequence should be aborted. This provides a
329 * way for devices to indicate invalid commands to the host so that the current transfer can be
330 * aborted and the host can begin its own recovery sequence.
331 *
332 * The currently selected endpoint remains stalled until either the \ref Endpoint_ClearStall() macro
333 * is called, or the host issues a CLEAR FEATURE request to the device for the currently selected
334 * endpoint.
335 *
336 * \ingroup Group_EndpointPacketManagement
337 */
338 static inline void Endpoint_StallTransaction(void);
339
340 /** Clears the STALL condition on the currently selected endpoint.
341 *
342 * \ingroup Group_EndpointPacketManagement
343 */
344 static inline void Endpoint_ClearStall(void);
345
346 /** Determines if the currently selected endpoint is stalled, false otherwise.
347 *
348 * \ingroup Group_EndpointPacketManagement
349 *
350 * \return Boolean true if the currently selected endpoint is stalled, false otherwise
351 */
352 static inline bool Endpoint_IsStalled(void);
353
354 /** Resets the data toggle of the currently selected endpoint. */
355 static inline void Endpoint_ResetDataToggle(void);
356
357 /** Determines the currently selected endpoint's direction.
358 *
359 * \return The currently selected endpoint's direction, as a ENDPOINT_DIR_* mask.
360 */
361 static inline uint8_t Endpoint_GetEndpointDirection(void);
362 #else
363 #if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER) || defined(__DOXYGEN__)
364 #define Endpoint_BytesInEndpoint() UEBCX
365 #else
366 #define Endpoint_BytesInEndpoint() UEBCLX
367 #endif
368
369 #define Endpoint_GetCurrentEndpoint() (UENUM & ENDPOINT_EPNUM_MASK)
370
371 #define Endpoint_SelectEndpoint(epnum) MACROS{ UENUM = epnum; }MACROE
372
373 #define Endpoint_ResetFIFO(epnum) MACROS{ UERST = (1 << epnum); UERST = 0; }MACROE
374
375 #define Endpoint_EnableEndpoint() MACROS{ UECONX |= (1 << EPEN); }MACROE
376
377 #define Endpoint_DisableEndpoint() MACROS{ UECONX &= ~(1 << EPEN); }MACROE
378
379 #define Endpoint_IsEnabled() ((UECONX & (1 << EPEN)) ? true : false)
380
381 #define Endpoint_IsReadWriteAllowed() ((UEINTX & (1 << RWAL)) ? true : false)
382
383 #define Endpoint_IsConfigured() ((UESTA0X & (1 << CFGOK)) ? true : false)
384
385 #define Endpoint_GetEndpointInterrupts() UEINT
386
387 #define Endpoint_ClearEndpointInterrupt(n) MACROS{ UEINT &= ~(1 << n); }MACROE
388
389 #define Endpoint_HasEndpointInterrupted(n) ((UEINT & (1 << n)) ? true : false)
390
391 #define Endpoint_IsINReady() ((UEINTX & (1 << TXINI)) ? true : false)
392
393 #define Endpoint_IsOUTReceived() ((UEINTX & (1 << RXOUTI)) ? true : false)
394
395 #define Endpoint_IsSETUPReceived() ((UEINTX & (1 << RXSTPI)) ? true : false)
396
397 #define Endpoint_ClearSETUP() MACROS{ UEINTX &= ~(1 << RXSTPI); }MACROE
398
399 #define Endpoint_ClearIN() MACROS{ uint8_t Temp = UEINTX; UEINTX = (Temp & ~(1 << TXINI)); \
400 UEINTX = (Temp & ~(1 << FIFOCON)); }MACROE
401
402 #define Endpoint_ClearOUT() MACROS{ uint8_t Temp = UEINTX; UEINTX = (Temp & ~(1 << RXOUTI)); \
403 UEINTX = (Temp & ~(1 << FIFOCON)); }MACROE
404
405 #define Endpoint_StallTransaction() MACROS{ UECONX |= (1 << STALLRQ); }MACROE
406
407 #define Endpoint_ClearStall() MACROS{ UECONX |= (1 << STALLRQC); }MACROE
408
409 #define Endpoint_IsStalled() ((UECONX & (1 << STALLRQ)) ? true : false)
410
411 #define Endpoint_ResetDataToggle() MACROS{ UECONX |= (1 << RSTDT); }MACROE
412
413 #define Endpoint_GetEndpointDirection() (UECFG0X & ENDPOINT_DIR_IN)
414 #endif
415
416 /* Enums: */
417 /** Enum for the possible error return codes of the \ref Endpoint_WaitUntilReady() function.
418 *
419 * \ingroup Group_EndpointRW
420 */
421 enum Endpoint_WaitUntilReady_ErrorCodes_t
422 {
423 ENDPOINT_READYWAIT_NoError = 0, /**< Endpoint is ready for next packet, no error. */
424 ENDPOINT_READYWAIT_EndpointStalled = 1, /**< The endpoint was stalled during the stream
425 * transfer by the host or device.
426 */
427 ENDPOINT_READYWAIT_DeviceDisconnected = 2, /**< Device was disconnected from the host while
428 * waiting for the endpoint to become ready.
429 */
430 ENDPOINT_READYWAIT_Timeout = 3, /**< The host failed to accept or send the next packet
431 * within the software timeout period set by the
432 * \ref USB_STREAM_TIMEOUT_MS macro.
433 */
434 };
435
436 /** Enum for the possible error return codes of the Endpoint_*_Stream_* functions.
437 *
438 * \ingroup Group_EndpointRW
439 */
440 enum Endpoint_Stream_RW_ErrorCodes_t
441 {
442 ENDPOINT_RWSTREAM_ERROR_NoError = 0, /**< Command completed successfully, no error. */
443 ENDPOINT_RWSTREAM_ERROR_EndpointStalled = 1, /**< The endpoint was stalled during the stream
444 * transfer by the host or device.
445 */
446 ENDPOINT_RWSTREAM_ERROR_DeviceDisconnected = 1, /**< Device was disconnected from the host during
447 * the transfer.
448 */
449 ENDPOINT_RWSTREAM_ERROR_Timeout = 2, /**< The host failed to accept or send the next packet
450 * within the software timeout period set by the
451 * \ref USB_STREAM_TIMEOUT_MS macro.
452 */
453 ENDPOINT_RWSTREAM_ERROR_CallbackAborted = 3, /**< Indicates that the stream's callback function
454 * aborted the transfer early.
455 */
456 };
457
458 /** Enum for the possible error return codes of the Endpoint_*_Control_Stream_* functions..
459 *
460 * \ingroup Group_EndpointRW
461 */
462 enum Endpoint_ControlStream_RW_ErrorCodes_t
463 {
464 ENDPOINT_RWCSTREAM_ERROR_NoError = 0, /**< Command completed successfully, no error. */
465 ENDPOINT_RWCSTREAM_ERROR_HostAborted = 1, /**< The aborted the transfer prematurely. */
466 };
467
468 /* Inline Functions: */
469 /** Reads one byte from the currently selected endpoint's bank, for OUT direction endpoints.
470 *
471 * \ingroup Group_EndpointRW
472 *
473 * \return Next byte in the currently selected endpoint's FIFO buffer
474 */
475 static inline uint8_t Endpoint_Read_Byte(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
476 static inline uint8_t Endpoint_Read_Byte(void)
477 {
478 return UEDATX;
479 }
480
481 /** Writes one byte from the currently selected endpoint's bank, for IN direction endpoints.
482 *
483 * \ingroup Group_EndpointRW
484 *
485 * \param Byte Next byte to write into the the currently selected endpoint's FIFO buffer
486 */
487 static inline void Endpoint_Write_Byte(const uint8_t Byte) ATTR_ALWAYS_INLINE;
488 static inline void Endpoint_Write_Byte(const uint8_t Byte)
489 {
490 UEDATX = Byte;
491 }
492
493 /** Discards one byte from the currently selected endpoint's bank, for OUT direction endpoints.
494 *
495 * \ingroup Group_EndpointRW
496 */
497 static inline void Endpoint_Discard_Byte(void) ATTR_ALWAYS_INLINE;
498 static inline void Endpoint_Discard_Byte(void)
499 {
500 uint8_t Dummy;
501
502 Dummy = UEDATX;
503 }
504
505 /** Reads two bytes from the currently selected endpoint's bank in little endian format, for OUT
506 * direction endpoints.
507 *
508 * \ingroup Group_EndpointRW
509 *
510 * \return Next word in the currently selected endpoint's FIFO buffer
511 */
512 static inline uint16_t Endpoint_Read_Word_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
513 static inline uint16_t Endpoint_Read_Word_LE(void)
514 {
515 uint16_t Data;
516
517 Data = UEDATX;
518 Data |= (((uint16_t)UEDATX) << 8);
519
520 return Data;
521 }
522
523 /** Reads two bytes from the currently selected endpoint's bank in big endian format, for OUT
524 * direction endpoints.
525 *
526 * \ingroup Group_EndpointRW
527 *
528 * \return Next word in the currently selected endpoint's FIFO buffer
529 */
530 static inline uint16_t Endpoint_Read_Word_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
531 static inline uint16_t Endpoint_Read_Word_BE(void)
532 {
533 uint16_t Data;
534
535 Data = (((uint16_t)UEDATX) << 8);
536 Data |= UEDATX;
537
538 return Data;
539 }
540
541 /** Writes two bytes to the currently selected endpoint's bank in little endian format, for IN
542 * direction endpoints.
543 *
544 * \ingroup Group_EndpointRW
545 *
546 * \param Word Next word to write to the currently selected endpoint's FIFO buffer
547 */
548 static inline void Endpoint_Write_Word_LE(const uint16_t Word) ATTR_ALWAYS_INLINE;
549 static inline void Endpoint_Write_Word_LE(const uint16_t Word)
550 {
551 UEDATX = (Word & 0xFF);
552 UEDATX = (Word >> 8);
553 }
554
555 /** Writes two bytes to the currently selected endpoint's bank in big endian format, for IN
556 * direction endpoints.
557 *
558 * \ingroup Group_EndpointRW
559 *
560 * \param Word Next word to write to the currently selected endpoint's FIFO buffer
561 */
562 static inline void Endpoint_Write_Word_BE(const uint16_t Word) ATTR_ALWAYS_INLINE;
563 static inline void Endpoint_Write_Word_BE(const uint16_t Word)
564 {
565 UEDATX = (Word >> 8);
566 UEDATX = (Word & 0xFF);
567 }
568
569 /** Discards two bytes from the currently selected endpoint's bank, for OUT direction endpoints.
570 *
571 * \ingroup Group_EndpointRW
572 */
573 static inline void Endpoint_Discard_Word(void) ATTR_ALWAYS_INLINE;
574 static inline void Endpoint_Discard_Word(void)
575 {
576 uint8_t Dummy;
577
578 Dummy = UEDATX;
579 Dummy = UEDATX;
580 }
581
582 /** Reads four bytes from the currently selected endpoint's bank in little endian format, for OUT
583 * direction endpoints.
584 *
585 * \ingroup Group_EndpointRW
586 *
587 * \return Next double word in the currently selected endpoint's FIFO buffer
588 */
589 static inline uint32_t Endpoint_Read_DWord_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
590 static inline uint32_t Endpoint_Read_DWord_LE(void)
591 {
592 union
593 {
594 uint32_t DWord;
595 uint8_t Bytes[4];
596 } Data;
597
598 Data.Bytes[0] = UEDATX;
599 Data.Bytes[1] = UEDATX;
600 Data.Bytes[2] = UEDATX;
601 Data.Bytes[3] = UEDATX;
602
603 return Data.DWord;
604 }
605
606 /** Reads four bytes from the currently selected endpoint's bank in big endian format, for OUT
607 * direction endpoints.
608 *
609 * \ingroup Group_EndpointRW
610 *
611 * \return Next double word in the currently selected endpoint's FIFO buffer
612 */
613 static inline uint32_t Endpoint_Read_DWord_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
614 static inline uint32_t Endpoint_Read_DWord_BE(void)
615 {
616 union
617 {
618 uint32_t DWord;
619 uint8_t Bytes[4];
620 } Data;
621
622 Data.Bytes[3] = UEDATX;
623 Data.Bytes[2] = UEDATX;
624 Data.Bytes[1] = UEDATX;
625 Data.Bytes[0] = UEDATX;
626
627 return Data.DWord;
628 }
629
630 /** Writes four bytes to the currently selected endpoint's bank in little endian format, for IN
631 * direction endpoints.
632 *
633 * \ingroup Group_EndpointRW
634 *
635 * \param DWord Next double word to write to the currently selected endpoint's FIFO buffer
636 */
637 static inline void Endpoint_Write_DWord_LE(const uint32_t DWord) ATTR_ALWAYS_INLINE;
638 static inline void Endpoint_Write_DWord_LE(const uint32_t DWord)
639 {
640 UEDATX = (DWord & 0xFF);
641 UEDATX = (DWord >> 8);
642 UEDATX = (DWord >> 16);
643 UEDATX = (DWord >> 24);
644 }
645
646 /** Writes four bytes to the currently selected endpoint's bank in big endian format, for IN
647 * direction endpoints.
648 *
649 * \ingroup Group_EndpointRW
650 *
651 * \param DWord Next double word to write to the currently selected endpoint's FIFO buffer
652 */
653 static inline void Endpoint_Write_DWord_BE(const uint32_t DWord) ATTR_ALWAYS_INLINE;
654 static inline void Endpoint_Write_DWord_BE(const uint32_t DWord)
655 {
656 UEDATX = (DWord >> 24);
657 UEDATX = (DWord >> 16);
658 UEDATX = (DWord >> 8);
659 UEDATX = (DWord & 0xFF);
660 }
661
662 /** Discards four bytes from the currently selected endpoint's bank, for OUT direction endpoints.
663 *
664 * \ingroup Group_EndpointRW
665 */
666 static inline void Endpoint_Discard_DWord(void) ATTR_ALWAYS_INLINE;
667 static inline void Endpoint_Discard_DWord(void)
668 {
669 uint8_t Dummy;
670
671 Dummy = UEDATX;
672 Dummy = UEDATX;
673 Dummy = UEDATX;
674 Dummy = UEDATX;
675 }
676
677 /* External Variables: */
678 /** Global indicating the maximum packet size of the default control endpoint located at address
679 * 0 in the device. This value is set to the value indicated in the device descriptor in the user
680 * project once the USB interface is initialized into device mode.
681 *
682 * If space is an issue, it is possible to fix this to a static value by defining the control
683 * endpoint size in the FIXED_CONTROL_ENDPOINT_SIZE token passed to the compiler in the makefile
684 * via the -D switch. When a fixed control endpoint size is used, the size is no longer dynamically
685 * read from the descriptors at runtime and instead fixed to the given value. When used, it is
686 * important that the descriptor control endpoint size value matches the size given as the
687 * FIXED_CONTROL_ENDPOINT_SIZE token - it is recommended that the FIXED_CONTROL_ENDPOINT_SIZE token
688 * be used in the descriptors to ensure this.
689 *
690 * \note This variable should be treated as read-only in the user application, and never manually
691 * changed in value.
692 */
693 #if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
694 extern uint8_t USB_ControlEndpointSize;
695 #else
696 #define USB_ControlEndpointSize FIXED_CONTROL_ENDPOINT_SIZE
697 #endif
698
699 /* Function Prototypes: */
700 /** Configures the specified endpoint number with the given endpoint type, direction, bank size
701 * and banking mode. Endpoints should be allocated in ascending order by their address in the
702 * device (i.e. endpoint 1 should be configured before endpoint 2 and so on).
703 *
704 * The endpoint type may be one of the EP_TYPE_* macros listed in LowLevel.h and the direction
705 * may be either \ref ENDPOINT_DIR_OUT or \ref ENDPOINT_DIR_IN.
706 *
707 * The bank size must indicate the maximum packet size that the endpoint can handle. Different
708 * endpoint numbers can handle different maximum packet sizes - refer to the chosen USB AVR's
709 * datasheet to determine the maximum bank size for each endpoint.
710 *
711 * The banking mode may be either \ref ENDPOINT_BANK_SINGLE or \ref ENDPOINT_BANK_DOUBLE.
712 *
713 * The success of this routine can be determined via the \ref Endpoint_IsConfigured() macro.
714 *
715 * By default, the routine is entirely dynamic, and will accept both constant and variable inputs.
716 * If dynamic configuration is unused, a small space savings can be made by defining the
717 * STATIC_ENDPOINT_CONFIGURATION macro via the -D switch to the compiler, to optimize for constant
718 * input values.
719 *
720 * \note This routine will select the specified endpoint, and the endpoint will remain selected
721 * once the routine completes regardless of if the endpoint configuration succeeds.
722 *
723 * \return Boolean true if the configuration succeeded, false otherwise
724 */
725 bool Endpoint_ConfigureEndpoint(const uint8_t Number, const uint8_t Type, const uint8_t Direction,
726 const uint16_t Size, const uint8_t Banks);
727
728 /** Spinloops until the currently selected non-control endpoint is ready for the next packet of data
729 * to be read or written to it.
730 *
731 * \note This routine should not be called on CONTROL type endpoints.
732 *
733 * \ingroup Group_EndpointRW
734 *
735 * \return A value from the \ref Endpoint_WaitUntilReady_ErrorCodes_t enum.
736 */
737 uint8_t Endpoint_WaitUntilReady(void);
738
739 /** Reads and discards the given number of bytes from the endpoint from the given buffer,
740 * discarding fully read packets from the host as needed. The last packet is not automatically
741 * discarded once the remaining bytes has been read; the user is responsible for manually
742 * discarding the last packet from the host via the \ref Endpoint_ClearOUT() macro. Between
743 * each USB packet, the given stream callback function is executed repeatedly until the next
744 * packet is ready, allowing for early aborts of stream transfers.
745 *
746 * The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token
747 * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled
748 * and this function has the Callback parameter omitted.
749 *
750 * \note This routine should not be used on CONTROL type endpoints.
751 *
752 * \ingroup Group_EndpointRW
753 *
754 * \param Length Number of bytes to send via the currently selected endpoint.
755 * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
756 *
757 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
758 */
759 uint8_t Endpoint_Discard_Stream(uint16_t Length
760 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
761 , uint8_t (* const Callback)(void)
762 #endif
763 );
764
765 /** Writes the given number of bytes to the endpoint from the given buffer in little endian,
766 * sending full packets to the host as needed. The last packet filled is not automatically sent;
767 * the user is responsible for manually sending the last written packet to the host via the
768 * \ref Endpoint_ClearIN() macro. Between each USB packet, the given stream callback function
769 * is executed repeatedly until the endpoint is ready to accept the next packet, allowing for early
770 * aborts of stream transfers.
771 *
772 * The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token
773 * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled
774 * and this function has the Callback parameter omitted.
775 *
776 * \note This routine should not be used on CONTROL type endpoints.
777 *
778 * \ingroup Group_EndpointRW
779 *
780 * \param Buffer Pointer to the source data buffer to read from.
781 * \param Length Number of bytes to read for the currently selected endpoint into the buffer.
782 * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
783 *
784 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
785 */
786 uint8_t Endpoint_Write_Stream_LE(const void* Buffer, uint16_t Length
787 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
788 , uint8_t (* const Callback)(void)
789 #endif
790 ) ATTR_NON_NULL_PTR_ARG(1);
791
792 /** Writes the given number of bytes to the endpoint from the given buffer in big endian,
793 * sending full packets to the host as needed. The last packet filled is not automatically sent;
794 * the user is responsible for manually sending the last written packet to the host via the
795 * \ref Endpoint_ClearIN() macro. Between each USB packet, the given stream callback function
796 * is executed repeatedly until the endpoint is ready to accept the next packet, allowing for early
797 * aborts of stream transfers.
798 *
799 * The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token
800 * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled
801 * and this function has the Callback parameter omitted.
802 *
803 * \note This routine should not be used on CONTROL type endpoints.
804 *
805 * \ingroup Group_EndpointRW
806 *
807 * \param Buffer Pointer to the source data buffer to read from.
808 * \param Length Number of bytes to read for the currently selected endpoint into the buffer.
809 * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
810 *
811 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
812 */
813 uint8_t Endpoint_Write_Stream_BE(const void* Buffer, uint16_t Length
814 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
815 , uint8_t (* const Callback)(void)
816 #endif
817 ) ATTR_NON_NULL_PTR_ARG(1);
818
819 /** Reads the given number of bytes from the endpoint from the given buffer in little endian,
820 * discarding fully read packets from the host as needed. The last packet is not automatically
821 * discarded once the remaining bytes has been read; the user is responsible for manually
822 * discarding the last packet from the host via the \ref Endpoint_ClearOUT() macro. Between
823 * each USB packet, the given stream callback function is executed repeatedly until the endpoint
824 * is ready to accept the next packet, allowing for early aborts of stream transfers.
825 *
826 * The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token
827 * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled
828 * and this function has the Callback parameter omitted.
829 *
830 * \note This routine should not be used on CONTROL type endpoints.
831 *
832 * \ingroup Group_EndpointRW
833 *
834 * \param Buffer Pointer to the destination data buffer to write to.
835 * \param Length Number of bytes to send via the currently selected endpoint.
836 * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
837 *
838 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
839 */
840 uint8_t Endpoint_Read_Stream_LE(void* Buffer, uint16_t Length
841 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
842 , uint8_t (* const Callback)(void)
843 #endif
844 ) ATTR_NON_NULL_PTR_ARG(1);
845
846 /** Reads the given number of bytes from the endpoint from the given buffer in big endian,
847 * discarding fully read packets from the host as needed. The last packet is not automatically
848 * discarded once the remaining bytes has been read; the user is responsible for manually
849 * discarding the last packet from the host via the \ref Endpoint_ClearOUT() macro. Between
850 * each USB packet, the given stream callback function is executed repeatedly until the endpoint
851 * is ready to accept the next packet, allowing for early aborts of stream transfers.
852 *
853 * The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token
854 * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled
855 * and this function has the Callback parameter omitted.
856 *
857 * \note This routine should not be used on CONTROL type endpoints.
858 *
859 * \ingroup Group_EndpointRW
860 *
861 * \param Buffer Pointer to the destination data buffer to write to.
862 * \param Length Number of bytes to send via the currently selected endpoint.
863 * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
864 *
865 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
866 */
867 uint8_t Endpoint_Read_Stream_BE(void* Buffer, uint16_t Length
868 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
869 , uint8_t (* const Callback)(void)
870 #endif
871 ) ATTR_NON_NULL_PTR_ARG(1);
872
873 /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in little endian,
874 * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
875 * in both failure and success states; the user is responsible for manually clearing the setup OUT to
876 * finalize the transfer via the \ref Endpoint_ClearOUT() macro.
877 *
878 * \note This routine should only be used on CONTROL type endpoints.
879 *
880 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
881 * together; i.e. the entire stream data must be read or written at the one time.
882 *
883 * \ingroup Group_EndpointRW
884 *
885 * \param Buffer Pointer to the source data buffer to read from.
886 * \param Length Number of bytes to read for the currently selected endpoint into the buffer.
887 *
888 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
889 */
890 uint8_t Endpoint_Write_Control_Stream_LE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
891
892 /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in big endian,
893 * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
894 * in both failure and success states; the user is responsible for manually clearing the setup OUT to
895 * finalize the transfer via the \ref Endpoint_ClearOUT() macro.
896 *
897 * \note This routine should only be used on CONTROL type endpoints.
898 *
899 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
900 * together; i.e. the entire stream data must be read or written at the one time.
901 *
902 * \ingroup Group_EndpointRW
903 *
904 * \param Buffer Pointer to the source data buffer to read from.
905 * \param Length Number of bytes to read for the currently selected endpoint into the buffer.
906 *
907 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
908 */
909 uint8_t Endpoint_Write_Control_Stream_BE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
910
911 /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in little endian,
912 * discarding fully read packets from the host as needed. The device IN acknowledgement is not
913 * automatically sent after success or failure states; the user is responsible for manually sending the
914 * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro.
915 *
916 * \note This routine should only be used on CONTROL type endpoints.
917 *
918 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
919 * together; i.e. the entire stream data must be read or written at the one time.
920 *
921 * \ingroup Group_EndpointRW
922 *
923 * \param Buffer Pointer to the destination data buffer to write to.
924 * \param Length Number of bytes to send via the currently selected endpoint.
925 *
926 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
927 */
928 uint8_t Endpoint_Read_Control_Stream_LE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
929
930 /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in big endian,
931 * discarding fully read packets from the host as needed. The device IN acknowledgement is not
932 * automatically sent after success or failure states; the user is responsible for manually sending the
933 * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro.
934 *
935 * \note This routine should only be used on CONTROL type endpoints.
936 *
937 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
938 * together; i.e. the entire stream data must be read or written at the one time.
939 *
940 * \ingroup Group_EndpointRW
941 *
942 * \param Buffer Pointer to the destination data buffer to write to.
943 * \param Length Number of bytes to send via the currently selected endpoint.
944 *
945 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
946 */
947 uint8_t Endpoint_Read_Control_Stream_BE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
948
949 /* Private Interface - For use in library only: */
950 #if !defined(__DOXYGEN__)
951 /* Macros: */
952 #define Endpoint_AllocateMemory() MACROS{ UECFG1X |= (1 << ALLOC); }MACROE
953 #define Endpoint_DeallocateMemory() MACROS{ UECFG1X &= ~(1 << ALLOC); }MACROE
954
955 #define _ENDPOINT_GET_MAXSIZE(n) _ENDPOINT_GET_MAXSIZE2(ENDPOINT_DETAILS_EP ## n)
956 #define _ENDPOINT_GET_MAXSIZE2(details) _ENDPOINT_GET_MAXSIZE3(details)
957 #define _ENDPOINT_GET_MAXSIZE3(maxsize, db) maxsize
958
959 #define _ENDPOINT_GET_DOUBLEBANK(n) _ENDPOINT_GET_DOUBLEBANK2(ENDPOINT_DETAILS_EP ## n)
960 #define _ENDPOINT_GET_DOUBLEBANK2(details) _ENDPOINT_GET_DOUBLEBANK3(details)
961 #define _ENDPOINT_GET_DOUBLEBANK3(maxsize, db) db
962
963 #if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER)
964 #define ENDPOINT_DETAILS_EP0 64, true
965 #define ENDPOINT_DETAILS_EP1 256, true
966 #define ENDPOINT_DETAILS_EP2 64, true
967 #define ENDPOINT_DETAILS_EP3 64, true
968 #define ENDPOINT_DETAILS_EP4 64, true
969 #define ENDPOINT_DETAILS_EP5 64, true
970 #define ENDPOINT_DETAILS_EP6 64, true
971 #else
972 #define ENDPOINT_DETAILS_EP0 64, true
973 #define ENDPOINT_DETAILS_EP1 64, false
974 #define ENDPOINT_DETAILS_EP2 64, false
975 #define ENDPOINT_DETAILS_EP3 64, true
976 #define ENDPOINT_DETAILS_EP4 64, true
977 #endif
978
979 #if defined(STATIC_ENDPOINT_CONFIGURATION)
980 #define Endpoint_ConfigureEndpoint(Number, Type, Direction, Size, Banks) \
981 Endpoint_ConfigureEndpointStatic(Number, \
982 ((Type << EPTYPE0) | Direction), \
983 ((1 << ALLOC) | Banks | Endpoint_BytesToEPSizeMask(Size)));
984 #endif
985
986 /* Function Prototypes: */
987 void Endpoint_ClearEndpoints(void);
988 bool Endpoint_ConfigureEndpointStatic(const uint8_t Number, const uint8_t UECFG0XData, const uint8_t UECFG1XData);
989
990 /* Inline Functions: */
991 static inline uint8_t Endpoint_BytesToEPSizeMask(const uint16_t Bytes) ATTR_WARN_UNUSED_RESULT ATTR_CONST ATTR_ALWAYS_INLINE;
992 static inline uint8_t Endpoint_BytesToEPSizeMask(const uint16_t Bytes)
993 {
994 if (Bytes <= 8)
995 return (0 << EPSIZE0);
996 else if (Bytes <= 16)
997 return (1 << EPSIZE0);
998 else if (Bytes <= 32)
999 return (2 << EPSIZE0);
1000 #if defined(USB_LIMITED_CONTROLLER)
1001 else
1002 return (3 << EPSIZE0);
1003 #else
1004 else if (Bytes <= 64)
1005 return (3 << EPSIZE0);
1006 else if (Bytes <= 128)
1007 return (4 << EPSIZE0);
1008 else
1009 return (5 << EPSIZE0);
1010 #endif
1011 };
1012
1013 #endif
1014
1015 /* Disable C linkage for C++ Compilers: */
1016 #if defined(__cplusplus)
1017 }
1018 #endif
1019
1020 #endif
1021
1022 /** @} */
USB isp AVR programmer