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