Statistics
| Branch: | Tag: | Revision:

root / LUFA / Drivers / USB / Core / AVR8 / Endpoint_AVR8.h @ 978b99e5

History | View | Annotate | Download (34.8 KB)

1
/*
2
             LUFA Library
3
     Copyright (C) Dean Camera, 2011.
4

5
  dean [at] fourwalledcubicle [dot] com
6
           www.lufa-lib.org
7
*/
8

    
9
/*
10
  Copyright 2011  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 Endpoint definitions for the AVR8 microcontrollers.
33
 *  \copydetails Group_EndpointManagement_AVR8
34
 *
35
 *  \note This file should not be included directly. It is automatically included as needed by the USB driver
36
 *        dispatch header located in LUFA/Drivers/USB/USB.h.
37
 */
38

    
39
/** \ingroup Group_EndpointRW
40
 *  \defgroup Group_EndpointRW_AVR8 Endpoint Data Reading and Writing (AVR8)
41
 *  \brief Endpoint data read/write definitions for the Atmel AVR8 architecture.
42
 *
43
 *  Functions, macros, variables, enums and types related to data reading and writing from and to endpoints.
44
 */
45

    
46
/** \ingroup Group_EndpointPrimitiveRW
47
 *  \defgroup Group_EndpointPrimitiveRW_AVR8 Read/Write of Primitive Data Types (AVR8)
48
 *  \brief Endpoint primitive read/write definitions for the Atmel AVR8 architecture.
49
 *
50
 *  Functions, macros, variables, enums and types related to data reading and writing of primitive data types
51
 *  from and to endpoints.
52
 */
53

    
54
/** \ingroup Group_EndpointPacketManagement
55
 *  \defgroup Group_EndpointPacketManagement_AVR8 Endpoint Packet Management (AVR8)
56
 *  \brief Endpoint packet management definitions for the Atmel AVR8 architecture.
57
 *
58
 *  Functions, macros, variables, enums and types related to packet management of endpoints.
59
 */
60

    
61
/** \ingroup Group_EndpointManagement
62
 *  \defgroup Group_EndpointManagement_AVR8 Endpoint Management (AVR8)
63
 *  \brief Endpoint management definitions for the Atmel AVR8 architecture.
64
 *
65
 *  Functions, macros and enums related to endpoint management when in USB Device mode. This
66
 *  module contains the endpoint management macros, as well as endpoint interrupt and data
67
 *  send/receive functions for various data types.
68
 *
69
 *  @{
70
 */
71

    
72
#ifndef __ENDPOINT_AVR8_H__
73
#define __ENDPOINT_AVR8_H__
74

    
75
        /* Includes: */
76
                #include "../../../../Common/Common.h"
77
                #include "../USBTask.h"
78
                #include "../USBInterrupt.h"
79

    
80
        /* Enable C linkage for C++ Compilers: */
81
                #if defined(__cplusplus)
82
                        extern "C" {
83
                #endif
84

    
85
        /* Preprocessor Checks: */
86
                #if !defined(__INCLUDE_FROM_USB_DRIVER)
87
                        #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
88
                #endif
89

    
90
        /* Private Interface - For use in library only: */
91
        #if !defined(__DOXYGEN__)
92
                /* Macros: */
93
                        #define _ENDPOINT_GET_MAXSIZE(EPIndex)         _ENDPOINT_GET_MAXSIZE2(ENDPOINT_DETAILS_EP ## EPIndex)
94
                        #define _ENDPOINT_GET_MAXSIZE2(EPDetails)      _ENDPOINT_GET_MAXSIZE3(EPDetails)
95
                        #define _ENDPOINT_GET_MAXSIZE3(MaxSize, Banks) (MaxSize)
96

    
97
                        #define _ENDPOINT_GET_BANKS(EPIndex)           _ENDPOINT_GET_BANKS2(ENDPOINT_DETAILS_EP ## EPIndex)
98
                        #define _ENDPOINT_GET_BANKS2(EPDetails)        _ENDPOINT_GET_BANKS3(EPDetails)
99
                        #define _ENDPOINT_GET_BANKS3(MaxSize, Banks)   (Banks)
100

    
101
                        #if defined(USB_SERIES_4_AVR) || defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR)
102
                                #define ENDPOINT_DETAILS_MAXEP             7
103

    
104
                                #define ENDPOINT_DETAILS_EP0               64,  1
105
                                #define ENDPOINT_DETAILS_EP1               256, 2
106
                                #define ENDPOINT_DETAILS_EP2               64,  2
107
                                #define ENDPOINT_DETAILS_EP3               64,  2
108
                                #define ENDPOINT_DETAILS_EP4               64,  2
109
                                #define ENDPOINT_DETAILS_EP5               64,  2
110
                                #define ENDPOINT_DETAILS_EP6               64,  2
111
                        #else
112
                                #define ENDPOINT_DETAILS_MAXEP             5
113

    
114
                                #define ENDPOINT_DETAILS_EP0               64,  1
115
                                #define ENDPOINT_DETAILS_EP1               64,  1
116
                                #define ENDPOINT_DETAILS_EP2               64,  1
117
                                #define ENDPOINT_DETAILS_EP3               64,  2
118
                                #define ENDPOINT_DETAILS_EP4               64,  2
119
                        #endif
120

    
121
                /* Inline Functions: */
122
                        static inline uint8_t Endpoint_BytesToEPSizeMask(const uint16_t Bytes) ATTR_WARN_UNUSED_RESULT ATTR_CONST
123
                                                                                               ATTR_ALWAYS_INLINE;
124
                        static inline uint8_t Endpoint_BytesToEPSizeMask(const uint16_t Bytes)
125
                        {
126
                                uint8_t  MaskVal    = 0;
127
                                uint16_t CheckBytes = 8;
128

    
129
                                while (CheckBytes < Bytes)
130
                                {
131
                                        MaskVal++;
132
                                        CheckBytes <<= 1;
133
                                }
134

    
135
                                return (MaskVal << EPSIZE0);
136
                        }
137

    
138
                /* Function Prototypes: */
139
                        void Endpoint_ClearEndpoints(void);
140
                        bool Endpoint_ConfigureEndpoint_Prv(const uint8_t Number,
141
                                                            const uint8_t UECFG0XData,
142
                                                            const uint8_t UECFG1XData);
143

    
144
        #endif
145

    
146
        /* Public Interface - May be used in end-application: */
147
                /* Macros: */                        
148
                        /** \name Endpoint Bank Mode Masks */
149
                        //@{
150
                        /** Mask for the bank mode selection for the \ref Endpoint_ConfigureEndpoint() macro. This indicates
151
                         *  that the endpoint should have one single bank, which requires less USB FIFO memory but results
152
                         *  in slower transfers as only one USB device (the AVR or the host) can access the endpoint's
153
                         *  bank at the one time.
154
                         */
155
                        #define ENDPOINT_BANK_SINGLE                    (0 << EPBK0)
156

    
157
                        /** Mask for the bank mode selection for the \ref Endpoint_ConfigureEndpoint() macro. This indicates
158
                         *  that the endpoint should have two banks, which requires more USB FIFO memory but results
159
                         *  in faster transfers as one USB device (the AVR or the host) can access one bank while the other
160
                         *  accesses the second bank.
161
                         */
162
                        #define ENDPOINT_BANK_DOUBLE                    (1 << EPBK0)
163
                        //@}
164

    
165
                        #if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
166
                                /** Default size of the default control endpoint's bank, until altered by the control endpoint bank size
167
                                 *  value in the device descriptor. Not available if the \c FIXED_CONTROL_ENDPOINT_SIZE token is defined.
168
                                 */
169
                                #define ENDPOINT_CONTROLEP_DEFAULT_SIZE     8
170
                        #endif
171

    
172
                        /** Retrieves the maximum bank size in bytes of a given endpoint.
173
                         *
174
                         *  \note This macro will only work correctly on endpoint indexes that are compile-time constants
175
                         *        defined by the preprocessor.
176
                         *
177
                         *  \param[in] EPIndex  Endpoint number, a value between 0 and (\ref ENDPOINT_TOTAL_ENDPOINTS - 1)
178
                         */
179
                        #define ENDPOINT_MAX_SIZE(EPIndex)              _ENDPOINT_GET_MAXSIZE(EPIndex)
180

    
181
                        /** Retrieves the total number of banks supported by the given endpoint.
182
                         *
183
                         *  \note This macro will only work correctly on endpoint indexes that are compile-time constants
184
                         *        defined by the preprocessor.
185
                         *
186
                         *  \param[in] EPIndex  Endpoint number, a value between 0 and (\ref ENDPOINT_TOTAL_ENDPOINTS - 1)
187
                         */
188
                        #define ENDPOINT_BANKS_SUPPORTED(EPIndex)       _ENDPOINT_GET_BANKS(EPIndex)
189

    
190
                        #if !defined(CONTROL_ONLY_DEVICE) || defined(__DOXYGEN__)
191
                                /** Total number of endpoints (including the default control endpoint at address 0) which may
192
                                 *  be used in the device. Different USB AVR models support different amounts of endpoints,
193
                                 *  this value reflects the maximum number of endpoints for the currently selected AVR model.
194
                                 */
195
                                #define ENDPOINT_TOTAL_ENDPOINTS            ENDPOINT_DETAILS_MAXEP
196
                        #else
197
                                #define ENDPOINT_TOTAL_ENDPOINTS            1
198
                        #endif
199

    
200
                /* Enums: */
201
                        /** Enum for the possible error return codes of the \ref Endpoint_WaitUntilReady() function.
202
                         *
203
                         *  \ingroup Group_EndpointRW_AVR8
204
                         */
205
                        enum Endpoint_WaitUntilReady_ErrorCodes_t
206
                        {
207
                                ENDPOINT_READYWAIT_NoError                 = 0, /**< Endpoint is ready for next packet, no error. */
208
                                ENDPOINT_READYWAIT_EndpointStalled         = 1, /**< The endpoint was stalled during the stream
209
                                                                                 *   transfer by the host or device.
210
                                                                                 */
211
                                ENDPOINT_READYWAIT_DeviceDisconnected      = 2,        /**< Device was disconnected from the host while
212
                                                                                 *   waiting for the endpoint to become ready.
213
                                                                                 */
214
                                ENDPOINT_READYWAIT_BusSuspended            = 3, /**< The USB bus has been suspended by the host and
215
                                                                                 *   no USB endpoint traffic can occur until the bus
216
                                                                                 *   has resumed.
217
                                                                                 */
218
                                ENDPOINT_READYWAIT_Timeout                 = 4, /**< The host failed to accept or send the next packet
219
                                                                                 *   within the software timeout period set by the
220
                                                                                 *   \ref USB_STREAM_TIMEOUT_MS macro.
221
                                                                                 */
222
                        };
223

    
224
                /* Inline Functions: */
225
                        /** Configures the specified endpoint number with the given endpoint type, direction, bank size
226
                         *  and banking mode. Once configured, the endpoint may be read from or written to, depending
227
                         *  on its direction.
228
                         *
229
                         *  \param[in] Number     Endpoint number to configure. This must be more than 0 and less than
230
                         *                        \ref ENDPOINT_TOTAL_ENDPOINTS.
231
                         *
232
                         *  \param[in] Type       Type of endpoint to configure, a \c EP_TYPE_* mask. Not all endpoint types
233
                         *                        are available on Low Speed USB devices - refer to the USB 2.0 specification.
234
                         *
235
                         *  \param[in] Direction  Endpoint data direction, either \ref ENDPOINT_DIR_OUT or \ref ENDPOINT_DIR_IN.
236
                         *                        All endpoints (except Control type) are unidirectional - data may only be read
237
                         *                        from or written to the endpoint bank based on its direction, not both.
238
                         *
239
                         *  \param[in] Size       Size of the endpoint's bank, where packets are stored before they are transmitted
240
                         *                        to the USB host, or after they have been received from the USB host (depending on
241
                         *                        the endpoint's data direction). The bank size must indicate the maximum packet size
242
                         *                        that the endpoint can handle.
243
                         *
244
                         *  \param[in] Banks      Number of banks to use for the endpoint being configured, an \c ENDPOINT_BANK_* mask.
245
                         *                        More banks uses more USB DPRAM, but offers better performance. Isochronous type
246
                         *                        endpoints <b>must</b> have at least two banks.
247
                         *
248
                         *  \note When the \c ORDERED_EP_CONFIG compile time option is used, Endpoints <b>must</b> be configured in
249
                         *        ascending order, or bank corruption will occur.
250
                         *        \n\n
251
                         *
252
                         *  \note Different endpoints may have different maximum packet sizes based on the endpoint's index - refer to
253
                         *        the chosen microcontroller model's datasheet to determine the maximum bank size for each endpoint.
254
                         *        \n\n
255
                         *
256
                         *  \note The default control endpoint should not be manually configured by the user application, as
257
                         *        it is automatically configured by the library internally.
258
                         *        \n\n
259
                         *
260
                         *  \note This routine will automatically select the specified endpoint upon success. Upon failure, the endpoint
261
                         *        which failed to reconfigure correctly will be selected.
262
                         *
263
                         *  \return Boolean \c true if the configuration succeeded, \c false otherwise.
264
                         */
265
                        static inline bool Endpoint_ConfigureEndpoint(const uint8_t Number,
266
                                                                      const uint8_t Type,
267
                                                                      const uint8_t Direction,
268
                                                                      const uint16_t Size,
269
                                                                      const uint8_t Banks) ATTR_ALWAYS_INLINE;
270
                        static inline bool Endpoint_ConfigureEndpoint(const uint8_t Number,
271
                                                                      const uint8_t Type,
272
                                                                      const uint8_t Direction,
273
                                                                      const uint16_t Size,
274
                                                                      const uint8_t Banks)
275
                        {
276
                                return Endpoint_ConfigureEndpoint_Prv(Number, ((Type << EPTYPE0) | (Direction ? (1 << EPDIR) : 0)),
277
                                                                      ((1 << ALLOC) | Banks | Endpoint_BytesToEPSizeMask(Size)));
278
                        }
279

    
280
                        /** Indicates the number of bytes currently stored in the current endpoint's selected bank.
281
                         *
282
                         *  \note The return width of this function may differ, depending on the maximum endpoint bank size
283
                         *        of the selected AVR model.
284
                         *
285
                         *  \ingroup Group_EndpointRW_AVR8
286
                         *
287
                         *  \return Total number of bytes in the currently selected Endpoint's FIFO buffer.
288
                         */
289
                        static inline uint16_t Endpoint_BytesInEndpoint(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
290
                        static inline uint16_t Endpoint_BytesInEndpoint(void)
291
                        {
292
                                #if defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR)
293
                                        return UEBCX;
294
                                #elif defined(USB_SERIES_4_AVR)
295
                                        return (((uint16_t)UEBCHX << 8) | UEBCLX);
296
                                #elif defined(USB_SERIES_2_AVR)
297
                                        return UEBCLX;
298
                                #endif
299
                        }
300

    
301
                        /** Get the endpoint address of the currently selected endpoint. This is typically used to save
302
                         *  the currently selected endpoint number so that it can be restored after another endpoint has
303
                         *  been manipulated.
304
                         *
305
                         *  \return Index of the currently selected endpoint.
306
                         */
307
                        static inline uint8_t Endpoint_GetCurrentEndpoint(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
308
                        static inline uint8_t Endpoint_GetCurrentEndpoint(void)
309
                        {
310
                                #if !defined(CONTROL_ONLY_DEVICE)
311
                                        return (UENUM & ENDPOINT_EPNUM_MASK);
312
                                #else
313
                                        return ENDPOINT_CONTROLEP;
314
                                #endif
315
                        }
316

    
317
                        /** Selects the given endpoint number. If the address from the device descriptors is used, the
318
                         *  value should be masked with the \ref ENDPOINT_EPNUM_MASK constant to extract only the endpoint
319
                         *  number (and discarding the endpoint direction bit).
320
                         *
321
                         *  Any endpoint operations which do not require the endpoint number to be indicated will operate on
322
                         *  the currently selected endpoint.
323
                         *
324
                         *  \param[in] EndpointNumber Endpoint number to select.
325
                         */
326
                        static inline void Endpoint_SelectEndpoint(const uint8_t EndpointNumber) ATTR_ALWAYS_INLINE;
327
                        static inline void Endpoint_SelectEndpoint(const uint8_t EndpointNumber)
328
                        {
329
                                #if !defined(CONTROL_ONLY_DEVICE)
330
                                        UENUM = EndpointNumber;
331
                                #endif
332
                        }
333

    
334
                        /** Resets the endpoint bank FIFO. This clears all the endpoint banks and resets the USB controller's
335
                         *  data In and Out pointers to the bank's contents.
336
                         *
337
                         *  \param[in] EndpointNumber Endpoint number whose FIFO buffers are to be reset.
338
                         */
339
                        static inline void Endpoint_ResetEndpoint(const uint8_t EndpointNumber) ATTR_ALWAYS_INLINE;
340
                        static inline void Endpoint_ResetEndpoint(const uint8_t EndpointNumber)
341
                        {
342
                                UERST = (1 << EndpointNumber);
343
                                UERST = 0;
344
                        }
345

    
346
                        /** Enables the currently selected endpoint so that data can be sent and received through it to
347
                         *  and from a host.
348
                         *
349
                         *  \note Endpoints must first be configured properly via \ref Endpoint_ConfigureEndpoint().
350
                         */
351
                        static inline void Endpoint_EnableEndpoint(void) ATTR_ALWAYS_INLINE;
352
                        static inline void Endpoint_EnableEndpoint(void)
353
                        {
354
                                UECONX |= (1 << EPEN);
355
                        }
356

    
357
                        /** Disables the currently selected endpoint so that data cannot be sent and received through it
358
                         *  to and from a host.
359
                         */
360
                        static inline void Endpoint_DisableEndpoint(void) ATTR_ALWAYS_INLINE;
361
                        static inline void Endpoint_DisableEndpoint(void)
362
                        {
363
                                UECONX &= ~(1 << EPEN);
364
                        }
365

    
366
                        /** Determines if the currently selected endpoint is enabled, but not necessarily configured.
367
                         *
368
                         * \return Boolean \c true if the currently selected endpoint is enabled, \c false otherwise.
369
                         */
370
                        static inline bool Endpoint_IsEnabled(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
371
                        static inline bool Endpoint_IsEnabled(void)
372
                        {
373
                                return ((UECONX & (1 << EPEN)) ? true : false);
374
                        }
375

    
376
                        /** Retrieves the number of busy banks in the currently selected endpoint, which have been queued for
377
                         *  transmission via the \ref Endpoint_ClearIN() command, or are awaiting acknowledgement via the
378
                         *  \ref Endpoint_ClearOUT() command.
379
                         *
380
                         *  \ingroup Group_EndpointPacketManagement_AVR8
381
                         *
382
                         *  \return Total number of busy banks in the selected endpoint.
383
                         */
384
                        static inline uint8_t Endpoint_GetBusyBanks(void) ATTR_ALWAYS_INLINE ATTR_WARN_UNUSED_RESULT;
385
                        static inline uint8_t Endpoint_GetBusyBanks(void)
386
                        {
387
                                return (UESTA0X & (0x03 << NBUSYBK0));
388
                        }
389

    
390
                        /** Aborts all pending IN transactions on the currently selected endpoint, once the bank
391
                         *  has been queued for transmission to the host via \ref Endpoint_ClearIN(). This function
392
                         *  will terminate all queued transactions, resetting the endpoint banks ready for a new
393
                         *  packet.
394
                         *
395
                         *  \ingroup Group_EndpointPacketManagement_AVR8
396
                         */
397
                        static inline void Endpoint_AbortPendingIN(void)
398
                        {
399
                                while (Endpoint_GetBusyBanks() != 0)
400
                                {
401
                                        UEINTX |= (1 << RXOUTI);
402
                                        while (UEINTX & (1 << RXOUTI));
403
                                }
404
                        }
405

    
406
                        /** Determines if the currently selected endpoint may be read from (if data is waiting in the endpoint
407
                         *  bank and the endpoint is an OUT direction, or if the bank is not yet full if the endpoint is an IN
408
                         *  direction). This function will return false if an error has occurred in the endpoint, if the endpoint
409
                         *  is an OUT direction and no packet (or an empty packet) has been received, or if the endpoint is an IN
410
                         *  direction and the endpoint bank is full.
411
                         *
412
                         *  \ingroup Group_EndpointPacketManagement_AVR8
413
                         *
414
                         *  \return Boolean \c true if the currently selected endpoint may be read from or written to, depending
415
                         *          on its direction.
416
                         */
417
                        static inline bool Endpoint_IsReadWriteAllowed(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
418
                        static inline bool Endpoint_IsReadWriteAllowed(void)
419
                        {
420
                                return ((UEINTX & (1 << RWAL)) ? true : false);
421
                        }
422

    
423
                        /** Determines if the currently selected endpoint is configured.
424
                         *
425
                         *  \return Boolean \c true if the currently selected endpoint has been configured, \c false otherwise.
426
                         */
427
                        static inline bool Endpoint_IsConfigured(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
428
                        static inline bool Endpoint_IsConfigured(void)
429
                        {
430
                                return ((UESTA0X & (1 << CFGOK)) ? true : false);
431
                        }
432

    
433
                        /** Returns a mask indicating which INTERRUPT type endpoints have interrupted - i.e. their
434
                         *  interrupt duration has elapsed. Which endpoints have interrupted can be determined by
435
                         *  masking the return value against <tt>(1 << <i>{Endpoint Number}</i>)</tt>.
436
                         *
437
                         *  \return Mask whose bits indicate which endpoints have interrupted.
438
                         */
439
                        static inline uint8_t Endpoint_GetEndpointInterrupts(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
440
                        static inline uint8_t Endpoint_GetEndpointInterrupts(void)
441
                        {
442
                                return UEINT;
443
                        }
444

    
445
                        /** Determines if the specified endpoint number has interrupted (valid only for INTERRUPT type
446
                         *  endpoints).
447
                         *
448
                         *  \param[in] EndpointNumber  Index of the endpoint whose interrupt flag should be tested.
449
                         *
450
                         *  \return Boolean \c true if the specified endpoint has interrupted, \c false otherwise.
451
                         */
452
                        static inline bool Endpoint_HasEndpointInterrupted(const uint8_t EndpointNumber) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
453
                        static inline bool Endpoint_HasEndpointInterrupted(const uint8_t EndpointNumber)
454
                        {
455
                                return ((Endpoint_GetEndpointInterrupts() & (1 << EndpointNumber)) ? true : false);
456
                        }
457

    
458
                        /** Determines if the selected IN endpoint is ready for a new packet to be sent to the host.
459
                         *
460
                         *  \ingroup Group_EndpointPacketManagement_AVR8
461
                         *
462
                         *  \return Boolean \c true if the current endpoint is ready for an IN packet, \c false otherwise.
463
                         */
464
                        static inline bool Endpoint_IsINReady(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
465
                        static inline bool Endpoint_IsINReady(void)
466
                        {
467
                                return ((UEINTX & (1 << TXINI)) ? true : false);
468
                        }
469

    
470
                        /** Determines if the selected OUT endpoint has received new packet from the host.
471
                         *
472
                         *  \ingroup Group_EndpointPacketManagement_AVR8
473
                         *
474
                         *  \return Boolean \c true if current endpoint is has received an OUT packet, \c false otherwise.
475
                         */
476
                        static inline bool Endpoint_IsOUTReceived(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
477
                        static inline bool Endpoint_IsOUTReceived(void)
478
                        {
479
                                return ((UEINTX & (1 << RXOUTI)) ? true : false);
480
                        }
481

    
482
                        /** Determines if the current CONTROL type endpoint has received a SETUP packet.
483
                         *
484
                         *  \ingroup Group_EndpointPacketManagement_AVR8
485
                         *
486
                         *  \return Boolean \c true if the selected endpoint has received a SETUP packet, \c false otherwise.
487
                         */
488
                        static inline bool Endpoint_IsSETUPReceived(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
489
                        static inline bool Endpoint_IsSETUPReceived(void)
490
                        {
491
                                return ((UEINTX & (1 << RXSTPI)) ? true : false);
492
                        }
493

    
494
                        /** Clears a received SETUP packet on the currently selected CONTROL type endpoint, freeing up the
495
                         *  endpoint for the next packet.
496
                         *
497
                         *  \ingroup Group_EndpointPacketManagement_AVR8
498
                         *
499
                         *  \note This is not applicable for non CONTROL type endpoints.
500
                         */
501
                        static inline void Endpoint_ClearSETUP(void) ATTR_ALWAYS_INLINE;
502
                        static inline void Endpoint_ClearSETUP(void)
503
                        {
504
                                UEINTX &= ~(1 << RXSTPI);
505
                        }
506

    
507
                        /** Sends an IN packet to the host on the currently selected endpoint, freeing up the endpoint for the
508
                         *  next packet and switching to the alternative endpoint bank if double banked.
509
                         *
510
                         *  \ingroup Group_EndpointPacketManagement_AVR8
511
                         */
512
                        static inline void Endpoint_ClearIN(void) ATTR_ALWAYS_INLINE;
513
                        static inline void Endpoint_ClearIN(void)
514
                        {
515
                                #if !defined(CONTROL_ONLY_DEVICE)
516
                                        UEINTX &= ~((1 << TXINI) | (1 << FIFOCON));
517
                                #else
518
                                        UEINTX &= ~(1 << TXINI);
519
                                #endif
520
                        }
521

    
522
                        /** Acknowledges an OUT packet to the host on the currently selected endpoint, freeing up the endpoint
523
                         *  for the next packet and switching to the alternative endpoint bank if double banked.
524
                         *
525
                         *  \ingroup Group_EndpointPacketManagement_AVR8
526
                         */
527
                        static inline void Endpoint_ClearOUT(void) ATTR_ALWAYS_INLINE;
528
                        static inline void Endpoint_ClearOUT(void)
529
                        {
530
                                #if !defined(CONTROL_ONLY_DEVICE)
531
                                        UEINTX &= ~((1 << RXOUTI) | (1 << FIFOCON));
532
                                #else
533
                                        UEINTX &= ~(1 << RXOUTI);
534
                                #endif
535
                        }
536

    
537
                        /** Stalls the current endpoint, indicating to the host that a logical problem occurred with the
538
                         *  indicated endpoint and that the current transfer sequence should be aborted. This provides a
539
                         *  way for devices to indicate invalid commands to the host so that the current transfer can be
540
                         *  aborted and the host can begin its own recovery sequence.
541
                         *
542
                         *  The currently selected endpoint remains stalled until either the \ref Endpoint_ClearStall() macro
543
                         *  is called, or the host issues a CLEAR FEATURE request to the device for the currently selected
544
                         *  endpoint.
545
                         *
546
                         *  \ingroup Group_EndpointPacketManagement_AVR8
547
                         */
548
                        static inline void Endpoint_StallTransaction(void) ATTR_ALWAYS_INLINE;
549
                        static inline void Endpoint_StallTransaction(void)
550
                        {
551
                                UECONX |= (1 << STALLRQ);
552
                        }
553

    
554
                        /** Clears the STALL condition on the currently selected endpoint.
555
                         *
556
                         *  \ingroup Group_EndpointPacketManagement_AVR8
557
                         */
558
                        static inline void Endpoint_ClearStall(void) ATTR_ALWAYS_INLINE;
559
                        static inline void Endpoint_ClearStall(void)
560
                        {
561
                                UECONX |= (1 << STALLRQC);
562
                        }
563

    
564
                        /** Determines if the currently selected endpoint is stalled, false otherwise.
565
                         *
566
                         *  \ingroup Group_EndpointPacketManagement_AVR8
567
                         *
568
                         *  \return Boolean \c true if the currently selected endpoint is stalled, \c false otherwise.
569
                         */
570
                        static inline bool Endpoint_IsStalled(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
571
                        static inline bool Endpoint_IsStalled(void)
572
                        {
573
                                return ((UECONX & (1 << STALLRQ)) ? true : false);
574
                        }
575

    
576
                        /** Resets the data toggle of the currently selected endpoint. */
577
                        static inline void Endpoint_ResetDataToggle(void) ATTR_ALWAYS_INLINE;
578
                        static inline void Endpoint_ResetDataToggle(void)
579
                        {
580
                                UECONX |= (1 << RSTDT);
581
                        }
582

    
583
                        /** Determines the currently selected endpoint's direction.
584
                         *
585
                         *  \return The currently selected endpoint's direction, as a \c ENDPOINT_DIR_* mask.
586
                         */
587
                        static inline uint8_t Endpoint_GetEndpointDirection(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
588
                        static inline uint8_t Endpoint_GetEndpointDirection(void)
589
                        {
590
                                return (UECFG0X & (1 << EPDIR)) ? ENDPOINT_DIR_IN : ENDPOINT_DIR_OUT;
591
                        }
592

    
593
                        /** Sets the direction of the currently selected endpoint.
594
                         *
595
                         *  \param[in] DirectionMask  New endpoint direction, as a \c ENDPOINT_DIR_* mask.
596
                         */
597
                        static inline void Endpoint_SetEndpointDirection(const uint8_t DirectionMask) ATTR_ALWAYS_INLINE;
598
                        static inline void Endpoint_SetEndpointDirection(const uint8_t DirectionMask)
599
                        {
600
                                UECFG0X = ((UECFG0X & ~(1 << EPDIR)) | (DirectionMask ? (1 << EPDIR) : 0));
601
                        }
602

    
603
                        /** Reads one byte from the currently selected endpoint's bank, for OUT direction endpoints.
604
                         *
605
                         *  \ingroup Group_EndpointPrimitiveRW_AVR8
606
                         *
607
                         *  \return Next byte in the currently selected endpoint's FIFO buffer.
608
                         */
609
                        static inline uint8_t Endpoint_Read_8(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
610
                        static inline uint8_t Endpoint_Read_8(void)
611
                        {
612
                                return UEDATX;
613
                        }
614

    
615
                        /** Writes one byte to the currently selected endpoint's bank, for IN direction endpoints.
616
                         *
617
                         *  \ingroup Group_EndpointPrimitiveRW_AVR8
618
                         *
619
                         *  \param[in] Data  Data to write into the the currently selected endpoint's FIFO buffer.
620
                         */
621
                        static inline void Endpoint_Write_8(const uint8_t Data) ATTR_ALWAYS_INLINE;
622
                        static inline void Endpoint_Write_8(const uint8_t Data)
623
                        {
624
                                UEDATX = Data;
625
                        }
626

    
627
                        /** Discards one byte from the currently selected endpoint's bank, for OUT direction endpoints.
628
                         *
629
                         *  \ingroup Group_EndpointPrimitiveRW_AVR8
630
                         */
631
                        static inline void Endpoint_Discard_8(void) ATTR_ALWAYS_INLINE;
632
                        static inline void Endpoint_Discard_8(void)
633
                        {
634
                                uint8_t Dummy;
635

    
636
                                Dummy = UEDATX;
637

    
638
                                (void)Dummy;
639
                        }
640

    
641
                        /** Reads two bytes from the currently selected endpoint's bank in little endian format, for OUT
642
                         *  direction endpoints.
643
                         *
644
                         *  \ingroup Group_EndpointPrimitiveRW_AVR8
645
                         *
646
                         *  \return Next two bytes in the currently selected endpoint's FIFO buffer.
647
                         */
648
                        static inline uint16_t Endpoint_Read_16_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
649
                        static inline uint16_t Endpoint_Read_16_LE(void)
650
                        {
651
                                union
652
                                {
653
                                        uint16_t Value;
654
                                        uint8_t  Bytes[2];
655
                                } Data;
656

    
657
                                Data.Bytes[0] = UEDATX;
658
                                Data.Bytes[1] = UEDATX;
659

    
660
                                return Data.Value;
661
                        }
662

    
663
                        /** Reads two bytes from the currently selected endpoint's bank in big endian format, for OUT
664
                         *  direction endpoints.
665
                         *
666
                         *  \ingroup Group_EndpointPrimitiveRW_AVR8
667
                         *
668
                         *  \return Next two bytes in the currently selected endpoint's FIFO buffer.
669
                         */
670
                        static inline uint16_t Endpoint_Read_16_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
671
                        static inline uint16_t Endpoint_Read_16_BE(void)
672
                        {
673
                                union
674
                                {
675
                                        uint16_t Value;
676
                                        uint8_t  Bytes[2];
677
                                } Data;
678

    
679
                                Data.Bytes[1] = UEDATX;
680
                                Data.Bytes[0] = UEDATX;
681

    
682
                                return Data.Value;
683
                        }
684

    
685
                        /** Writes two bytes to the currently selected endpoint's bank in little endian format, for IN
686
                         *  direction endpoints.
687
                         *
688
                         *  \ingroup Group_EndpointPrimitiveRW_AVR8
689
                         *
690
                         *  \param[in] Data  Data to write to the currently selected endpoint's FIFO buffer.
691
                         */
692
                        static inline void Endpoint_Write_16_LE(const uint16_t Data) ATTR_ALWAYS_INLINE;
693
                        static inline void Endpoint_Write_16_LE(const uint16_t Data)
694
                        {
695
                                UEDATX = (Data & 0xFF);
696
                                UEDATX = (Data >> 8);
697
                        }
698

    
699
                        /** Writes two bytes to the currently selected endpoint's bank in big endian format, for IN
700
                         *  direction endpoints.
701
                         *
702
                         *  \ingroup Group_EndpointPrimitiveRW_AVR8
703
                         *
704
                         *  \param[in] Data  Data to write to the currently selected endpoint's FIFO buffer.
705
                         */
706
                        static inline void Endpoint_Write_16_BE(const uint16_t Data) ATTR_ALWAYS_INLINE;
707
                        static inline void Endpoint_Write_16_BE(const uint16_t Data)
708
                        {
709
                                UEDATX = (Data >> 8);
710
                                UEDATX = (Data & 0xFF);
711
                        }
712

    
713
                        /** Discards two bytes from the currently selected endpoint's bank, for OUT direction endpoints.
714
                         *
715
                         *  \ingroup Group_EndpointPrimitiveRW_AVR8
716
                         */
717
                        static inline void Endpoint_Discard_16(void) ATTR_ALWAYS_INLINE;
718
                        static inline void Endpoint_Discard_16(void)
719
                        {
720
                                uint8_t Dummy;
721

    
722
                                Dummy = UEDATX;
723
                                Dummy = UEDATX;
724

    
725
                                (void)Dummy;
726
                        }
727

    
728
                        /** Reads four bytes from the currently selected endpoint's bank in little endian format, for OUT
729
                         *  direction endpoints.
730
                         *
731
                         *  \ingroup Group_EndpointPrimitiveRW_AVR8
732
                         *
733
                         *  \return Next four bytes in the currently selected endpoint's FIFO buffer.
734
                         */
735
                        static inline uint32_t Endpoint_Read_32_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
736
                        static inline uint32_t Endpoint_Read_32_LE(void)
737
                        {
738
                                union
739
                                {
740
                                        uint32_t Value;
741
                                        uint8_t  Bytes[4];
742
                                } Data;
743

    
744
                                Data.Bytes[0] = UEDATX;
745
                                Data.Bytes[1] = UEDATX;
746
                                Data.Bytes[2] = UEDATX;
747
                                Data.Bytes[3] = UEDATX;
748

    
749
                                return Data.Value;
750
                        }
751

    
752
                        /** Reads four bytes from the currently selected endpoint's bank in big endian format, for OUT
753
                         *  direction endpoints.
754
                         *
755
                         *  \ingroup Group_EndpointPrimitiveRW_AVR8
756
                         *
757
                         *  \return Next four bytes in the currently selected endpoint's FIFO buffer.
758
                         */
759
                        static inline uint32_t Endpoint_Read_32_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
760
                        static inline uint32_t Endpoint_Read_32_BE(void)
761
                        {
762
                                union
763
                                {
764
                                        uint32_t Value;
765
                                        uint8_t  Bytes[4];
766
                                } Data;
767

    
768
                                Data.Bytes[3] = UEDATX;
769
                                Data.Bytes[2] = UEDATX;
770
                                Data.Bytes[1] = UEDATX;
771
                                Data.Bytes[0] = UEDATX;
772

    
773
                                return Data.Value;
774
                        }
775

    
776
                        /** Writes four bytes to the currently selected endpoint's bank in little endian format, for IN
777
                         *  direction endpoints.
778
                         *
779
                         *  \ingroup Group_EndpointPrimitiveRW_AVR8
780
                         *
781
                         *  \param[in] Data  Data to write to the currently selected endpoint's FIFO buffer.
782
                         */
783
                        static inline void Endpoint_Write_32_LE(const uint32_t Data) ATTR_ALWAYS_INLINE;
784
                        static inline void Endpoint_Write_32_LE(const uint32_t Data)
785
                        {
786
                                UEDATX = (Data &  0xFF);
787
                                UEDATX = (Data >> 8);
788
                                UEDATX = (Data >> 16);
789
                                UEDATX = (Data >> 24);
790
                        }
791

    
792
                        /** Writes four bytes to the currently selected endpoint's bank in big endian format, for IN
793
                         *  direction endpoints.
794
                         *
795
                         *  \ingroup Group_EndpointPrimitiveRW_AVR8
796
                         *
797
                         *  \param[in] Data  Data to write to the currently selected endpoint's FIFO buffer.
798
                         */
799
                        static inline void Endpoint_Write_32_BE(const uint32_t Data) ATTR_ALWAYS_INLINE;
800
                        static inline void Endpoint_Write_32_BE(const uint32_t Data)
801
                        {
802
                                UEDATX = (Data >> 24);
803
                                UEDATX = (Data >> 16);
804
                                UEDATX = (Data >> 8);
805
                                UEDATX = (Data &  0xFF);
806
                        }
807

    
808
                        /** Discards four bytes from the currently selected endpoint's bank, for OUT direction endpoints.
809
                         *
810
                         *  \ingroup Group_EndpointPrimitiveRW_AVR8
811
                         */
812
                        static inline void Endpoint_Discard_32(void) ATTR_ALWAYS_INLINE;
813
                        static inline void Endpoint_Discard_32(void)
814
                        {
815
                                uint8_t Dummy;
816

    
817
                                Dummy = UEDATX;
818
                                Dummy = UEDATX;
819
                                Dummy = UEDATX;
820
                                Dummy = UEDATX;
821

    
822
                                (void)Dummy;
823
                        }
824

    
825
                /* External Variables: */
826
                        /** Global indicating the maximum packet size of the default control endpoint located at address
827
                         *  0 in the device. This value is set to the value indicated in the device descriptor in the user
828
                         *  project once the USB interface is initialized into device mode.
829
                         *
830
                         *  If space is an issue, it is possible to fix this to a static value by defining the control
831
                         *  endpoint size in the \c FIXED_CONTROL_ENDPOINT_SIZE token passed to the compiler in the makefile
832
                         *  via the -D switch. When a fixed control endpoint size is used, the size is no longer dynamically
833
                         *  read from the descriptors at runtime and instead fixed to the given value. When used, it is
834
                         *  important that the descriptor control endpoint size value matches the size given as the
835
                         *  \c FIXED_CONTROL_ENDPOINT_SIZE token - it is recommended that the \c FIXED_CONTROL_ENDPOINT_SIZE token
836
                         *  be used in the device descriptors to ensure this.
837
                         *
838
                         *  \note This variable should be treated as read-only in the user application, and never manually
839
                         *        changed in value.
840
                         */
841
                        #if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
842
                                extern uint8_t USB_Device_ControlEndpointSize;
843
                        #else
844
                                #define USB_Device_ControlEndpointSize FIXED_CONTROL_ENDPOINT_SIZE
845
                        #endif
846

    
847
                /* Function Prototypes: */
848
                        /** Completes the status stage of a control transfer on a CONTROL type endpoint automatically,
849
                         *  with respect to the data direction. This is a convenience function which can be used to
850
                         *  simplify user control request handling.
851
                         */
852
                        void Endpoint_ClearStatusStage(void);
853

    
854
                        /** Spin-loops until the currently selected non-control endpoint is ready for the next packet of data
855
                         *  to be read or written to it.
856
                         *
857
                         *  \note This routine should not be called on CONTROL type endpoints.
858
                         *
859
                         *  \ingroup Group_EndpointRW_AVR8
860
                         *
861
                         *  \return A value from the \ref Endpoint_WaitUntilReady_ErrorCodes_t enum.
862
                         */
863
                        uint8_t Endpoint_WaitUntilReady(void);
864

    
865
        /* Disable C linkage for C++ Compilers: */
866
                #if defined(__cplusplus)
867
                        }
868
                #endif
869

    
870
#endif
871

    
872
/** @} */
873