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{ uint8_t Temp = UEINTX; UEINTX = (Temp & ~(1 << TXINI)); \
 432                                                                                       UEINTX = (Temp & ~(1 << FIFOCON)); }MACROE
 433
 434                                 #define Endpoint_ClearOUT()                   MACROS{ uint8_t Temp = UEINTX; UEINTX = (Temp & ~(1 << RXOUTI)); \
 435                                                                                       UEINTX = (Temp & ~(1 << FIFOCON)); }MACROE
 436
 437                                 #define Endpoint_StallTransaction()           MACROS{ UECONX |= (1 << STALLRQ); }MACROE
 438
 439                                 #define Endpoint_ClearStall()                 MACROS{ UECONX |= (1 << STALLRQC); }MACROE
 440
 441                                 #define Endpoint_IsStalled()                  ((UECONX & (1 << STALLRQ)) ? true : false)
 442
 443                                 #define Endpoint_ResetDataToggle()            MACROS{ UECONX |= (1 << RSTDT); }MACROE
 444
 445                                 #define Endpoint_GetEndpointDirection()       (UECFG0X & ENDPOINT_DIR_IN)
 446                         #endif
 447
 448                 /* Enums: */
 449                         /** Enum for the possible error return codes of the Endpoint_WaitUntilReady function.
 450                          *
 451                          *  \ingroup Group_EndpointRW
 452                          */
 453                         enum Endpoint_WaitUntilReady_ErrorCodes_t
 454                         {
 455                                 ENDPOINT_READYWAIT_NoError                 = 0, /**< Endpoint is ready for next packet, no error. */
 456                                 ENDPOINT_READYWAIT_EndpointStalled         = 1, /**< The endpoint was stalled during the stream
 457                                                                                  *   transfer by the host or device.
 458                                                                                  */
 459                                 ENDPOINT_READYWAIT_DeviceDisconnected      = 2, /**< Device was disconnected from the host while
 460                                                                                  *   waiting for the endpoint to become ready.
 461                                                                                  */
 462                                 ENDPOINT_READYWAIT_Timeout                 = 3, /**< The host failed to accept or send the next packet
 463                                                                                  *   within the software timeout period set by the
 464                                                                                  *   USB_STREAM_TIMEOUT_MS macro.
 465                                                                                  */
 466                         };
 467
 468                         /** Enum for the possible error return codes of the Endpoint_*_Stream_* functions.
 469                          *
 470                          *  \ingroup Group_EndpointRW
 471                          */
 472                         enum Endpoint_Stream_RW_ErrorCodes_t
 473                         {
 474                                 ENDPOINT_RWSTREAM_ERROR_NoError            = 0, /**< Command completed successfully, no error. */
 475                                 ENDPOINT_RWSTREAM_ERROR_EndpointStalled    = 1, /**< The endpoint was stalled during the stream
 476                                                                                  *   transfer by the host or device.
 477                                                                                  */
 478                                 ENDPOINT_RWSTREAM_ERROR_DeviceDisconnected = 1, /**< Device was disconnected from the host during
 479                                                                                  *   the transfer.
 480                                                                                  */
 481                                 ENDPOINT_RWSTREAM_ERROR_Timeout            = 2, /**< The host failed to accept or send the next packet
 482                                                                                  *   within the software timeout period set by the
 483                                                                                  *   USB_STREAM_TIMEOUT_MS macro.
 484                                                                                  */
 485                                 ENDPOINT_RWSTREAM_ERROR_CallbackAborted    = 3, /**< Indicates that the stream's callback function
 486                                                                              *   aborted the transfer early.
 487                                                                                  */
 488                         };
 489
 490                         /** Enum for the possible error return codes of the Endpoint_*_Control_Stream_* functions..
 491                          *
 492                          *  \ingroup Group_EndpointRW
 493                          */
 494                         enum Endpoint_ControlStream_RW_ErrorCodes_t
 495                         {
 496                                 ENDPOINT_RWCSTREAM_ERROR_NoError            = 0, /**< Command completed successfully, no error. */
 497                                 ENDPOINT_RWCSTREAM_ERROR_HostAborted        = 1, /**< The aborted the transfer prematurely. */
 498                         };
 499
 500                 /* Inline Functions: */
 501                         /** Reads one byte from the currently selected endpoint's bank, for OUT direction endpoints.
 502                          *
 503                          *  \ingroup Group_EndpointRW
 504                          *
 505                          *  \return Next byte in the currently selected endpoint's FIFO buffer
 506                          */
 507                         static inline uint8_t Endpoint_Read_Byte(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 508                         static inline uint8_t Endpoint_Read_Byte(void)
 509                         {
 510                                 return UEDATX;
 511                         }
 512
 513                         /** Writes one byte from the currently selected endpoint's bank, for IN direction endpoints.
 514                          *
 515                          *  \ingroup Group_EndpointRW
 516                          *
 517                          *  \param Byte  Next byte to write into the the currently selected endpoint's FIFO buffer
 518                          */
 519                         static inline void Endpoint_Write_Byte(const uint8_t Byte) ATTR_ALWAYS_INLINE;
 520                         static inline void Endpoint_Write_Byte(const uint8_t Byte)
 521                         {
 522                                 UEDATX = Byte;
 523                         }
 524
 525                         /** Discards one byte from the currently selected endpoint's bank, for OUT direction endpoints.
 526                          *
 527                          *  \ingroup Group_EndpointRW
 528                          */
 529                         static inline void Endpoint_Discard_Byte(void) ATTR_ALWAYS_INLINE;
 530                         static inline void Endpoint_Discard_Byte(void)
 531                         {
 532                                 uint8_t Dummy;
 533
 534                                 Dummy = UEDATX;
 535                         }
 536
 537                         /** Reads two bytes from the currently selected endpoint's bank in little endian format, for OUT
 538                          *  direction endpoints.
 539                          *
 540                          *  \ingroup Group_EndpointRW
 541                          *
 542                          *  \return Next word in the currently selected endpoint's FIFO buffer
 543                          */
 544                         static inline uint16_t Endpoint_Read_Word_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 545                         static inline uint16_t Endpoint_Read_Word_LE(void)
 546                         {
 547                                 uint16_t Data;
 548
 549                                 Data  = UEDATX;
 550                                 Data |= (((uint16_t)UEDATX) << 8);
 551
 552                                 return Data;
 553                         }
 554
 555                         /** Reads two bytes from the currently selected endpoint's bank in big endian format, for OUT
 556                          *  direction endpoints.
 557                          *
 558                          *  \ingroup Group_EndpointRW
 559                          *
 560                          *  \return Next word in the currently selected endpoint's FIFO buffer
 561                          */
 562                         static inline uint16_t Endpoint_Read_Word_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 563                         static inline uint16_t Endpoint_Read_Word_BE(void)
 564                         {
 565                                 uint16_t Data;
 566
 567                                 Data  = (((uint16_t)UEDATX) << 8);
 568                                 Data |= UEDATX;
 569
 570                                 return Data;
 571                         }
 572
 573                         /** Writes two bytes to the currently selected endpoint's bank in little endian format, for IN
 574                          *  direction endpoints.
 575                          *
 576                          *  \ingroup Group_EndpointRW
 577                          *
 578                          *  \param Word  Next word to write to the currently selected endpoint's FIFO buffer
 579                          */
 580                         static inline void Endpoint_Write_Word_LE(const uint16_t Word) ATTR_ALWAYS_INLINE;
 581                         static inline void Endpoint_Write_Word_LE(const uint16_t Word)
 582                         {
 583                                 UEDATX = (Word & 0xFF);
 584                                 UEDATX = (Word >> 8);
 585                         }
 586
 587                         /** Writes two bytes to the currently selected endpoint's bank in big endian format, for IN
 588                          *  direction endpoints.
 589                          *
 590                          *  \ingroup Group_EndpointRW
 591                          *
 592                          *  \param Word  Next word to write to the currently selected endpoint's FIFO buffer
 593                          */
 594                         static inline void Endpoint_Write_Word_BE(const uint16_t Word) ATTR_ALWAYS_INLINE;
 595                         static inline void Endpoint_Write_Word_BE(const uint16_t Word)
 596                         {
 597                                 UEDATX = (Word >> 8);
 598                                 UEDATX = (Word & 0xFF);
 599                         }
 600
 601                         /** Discards two bytes from the currently selected endpoint's bank, for OUT direction endpoints.
 602                          *
 603                          *  \ingroup Group_EndpointRW
 604                          */
 605                         static inline void Endpoint_Discard_Word(void) ATTR_ALWAYS_INLINE;
 606                         static inline void Endpoint_Discard_Word(void)
 607                         {
 608                                 uint8_t Dummy;
 609
 610                                 Dummy = UEDATX;
 611                                 Dummy = UEDATX;
 612                         }
 613
 614                         /** Reads four bytes from the currently selected endpoint's bank in little endian format, for OUT
 615                          *  direction endpoints.
 616                          *
 617                          *  \ingroup Group_EndpointRW
 618                          *
 619                          *  \return Next double word in the currently selected endpoint's FIFO buffer
 620                          */
 621                         static inline uint32_t Endpoint_Read_DWord_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 622                         static inline uint32_t Endpoint_Read_DWord_LE(void)
 623                         {
 624                                 union
 625                                 {
 626                                         uint32_t DWord;
 627                                         uint8_t  Bytes[4];
 628                                 } Data;
 629
 630                                 Data.Bytes[0] = UEDATX;
 631                                 Data.Bytes[1] = UEDATX;
 632                                 Data.Bytes[2] = UEDATX;
 633                                 Data.Bytes[3] = UEDATX;
 634
 635                                 return Data.DWord;
 636                         }
 637
 638                         /** Reads four bytes from the currently selected endpoint's bank in big endian format, for OUT
 639                          *  direction endpoints.
 640                          *
 641                          *  \ingroup Group_EndpointRW
 642                          *
 643                          *  \return Next double word in the currently selected endpoint's FIFO buffer
 644                          */
 645                         static inline uint32_t Endpoint_Read_DWord_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 646                         static inline uint32_t Endpoint_Read_DWord_BE(void)
 647                         {
 648                                 union
 649                                 {
 650                                         uint32_t DWord;
 651                                         uint8_t  Bytes[4];
 652                                 } Data;
 653
 654                                 Data.Bytes[3] = UEDATX;
 655                                 Data.Bytes[2] = UEDATX;
 656                                 Data.Bytes[1] = UEDATX;
 657                                 Data.Bytes[0] = UEDATX;
 658
 659                                 return Data.DWord;
 660                         }
 661
 662                         /** Writes four bytes to the currently selected endpoint's bank in little endian format, for IN
 663                          *  direction endpoints.
 664                          *
 665                          *  \ingroup Group_EndpointRW
 666                          *
 667                          *  \param DWord  Next double word to write to the currently selected endpoint's FIFO buffer
 668                          */
 669                         static inline void Endpoint_Write_DWord_LE(const uint32_t DWord) ATTR_ALWAYS_INLINE;
 670                         static inline void Endpoint_Write_DWord_LE(const uint32_t DWord)
 671                         {
 672                                 UEDATX = (DWord &  0xFF);
 673                                 UEDATX = (DWord >> 8);
 674                                 UEDATX = (DWord >> 16);
 675                                 UEDATX = (DWord >> 24);
 676                         }
 677
 678                         /** Writes four bytes to the currently selected endpoint's bank in big endian format, for IN
 679                          *  direction endpoints.
 680                          *
 681                          *  \ingroup Group_EndpointRW
 682                          *
 683                          *  \param DWord  Next double word to write to the currently selected endpoint's FIFO buffer
 684                          */
 685                         static inline void Endpoint_Write_DWord_BE(const uint32_t DWord) ATTR_ALWAYS_INLINE;
 686                         static inline void Endpoint_Write_DWord_BE(const uint32_t DWord)
 687                         {
 688                                 UEDATX = (DWord >> 24);
 689                                 UEDATX = (DWord >> 16);
 690                                 UEDATX = (DWord >> 8);
 691                                 UEDATX = (DWord &  0xFF);
 692                         }
 693
 694                         /** Discards four bytes from the currently selected endpoint's bank, for OUT direction endpoints.
 695                          *
 696                          *  \ingroup Group_EndpointRW
 697                          */
 698                         static inline void Endpoint_Discard_DWord(void) ATTR_ALWAYS_INLINE;
 699                         static inline void Endpoint_Discard_DWord(void)
 700                         {
 701                                 uint8_t Dummy;
 702
 703                                 Dummy = UEDATX;
 704                                 Dummy = UEDATX;
 705                                 Dummy = UEDATX;
 706                                 Dummy = UEDATX;
 707                         }
 708
 709                 /* External Variables: */
 710                         /** Global indicating the maximum packet size of the default control endpoint located at address
 711                          *  0 in the device. This value is set to the value indicated in the device descriptor in the user
 712                          *  project once the USB interface is initialized into device mode.
 713                          *
 714                          *  If space is an issue, it is possible to fix this to a static value by defining the control
 715                          *  endpoint size in the FIXED_CONTROL_ENDPOINT_SIZE token passed to the compiler in the makefile
 716                          *  via the -D switch. When a fixed control endpoint size is used, the size is no longer dynamically
 717                          *  read from the descriptors at runtime and instead fixed to the given value. When used, it is
 718                          *  important that the descriptor control endpoint size value matches the size given as the
 719                          *  FIXED_CONTROL_ENDPOINT_SIZE token - it is recommended that the FIXED_CONTROL_ENDPOINT_SIZE token
 720                          *  be used in the descriptors to ensure this.
 721                          *
 722                          *  \note This variable should be treated as read-only in the user application, and never manually
 723                          *        changed in value.
 724                          */
 725                         #if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
 726                                 extern uint8_t USB_ControlEndpointSize;
 727                         #else
 728                                 #define USB_ControlEndpointSize FIXED_CONTROL_ENDPOINT_SIZE
 729                         #endif
 730
 731                 /* Function Prototypes: */
 732                         /** Configures the specified endpoint number with the given endpoint type, direction, bank size
 733                          *  and banking mode. Endpoints should be allocated in ascending order by their address in the
 734                          *  device (i.e. endpoint 1 should be configured before endpoint 2 and so on).
 735                          *
 736                          *  The endpoint type may be one of the EP_TYPE_* macros listed in LowLevel.h and the direction
 737                          *  may be either ENDPOINT_DIR_OUT or ENDPOINT_DIR_IN.
 738                          *
 739                          *  The bank size must indicate the maximum packet size that the endpoint can handle. Different
 740                          *  endpoint numbers can handle different maximum packet sizes - refer to the chosen USB AVR's
 741                          *  datasheet to determine the maximum bank size for each endpoint.
 742                          *
 743                          *  The banking mode may be either ENDPOINT_BANK_SINGLE or ENDPOINT_BANK_DOUBLE.
 744                          *
 745                          *  The success of this routine can be determined via the Endpoint_IsConfigured() macro.
 746                          *
 747                          *  By default, the routine is entirely dynamic, and will accept both constant and variable inputs.
 748                          *  If dynamic configuration is unused, a small space savings can be made by defining the
 749                          *  STATIC_ENDPOINT_CONFIGURATION macro via the -D switch to the compiler, to optimize for constant
 750                          *  input values.
 751                          *
 752                          *  \note This routine will select the specified endpoint, and the endpoint will remain selected
 753                          *        once the routine completes regardless of if the endpoint configuration succeeds.
 754                          *
 755                          *  \return Boolean true if the configuration succeeded, false otherwise
 756                          */
 757                         bool Endpoint_ConfigureEndpoint(const uint8_t  Number, const uint8_t Type, const uint8_t Direction,
 758                                                         const uint16_t Size, const uint8_t Banks);
 759
 760                         /** Spinloops until the currently selected non-control endpoint is ready for the next packet of data
 761                          *  to be read or written to it.
 762                          *
 763                          *  \note This routine should not be called on CONTROL type endpoints.
 764                          *
 765                          *  \ingroup Group_EndpointRW
 766                          *
 767                          *  \return A value from the Endpoint_WaitUntilReady_ErrorCodes_t enum.
 768                          */
 769                         uint8_t Endpoint_WaitUntilReady(void);
 770
 771                         /** Reads and discards the given number of bytes from the endpoint from the given buffer,
 772                          *  discarding fully read packets from the host as needed. The last packet is not automatically
 773                          *  discarded once the remaining bytes has been read; the user is responsible for manually
 774                          *  discarding the last packet from the host via the Endpoint_ClearOUT() macro. Between
 775                          *  each USB packet, the given stream callback function is executed repeatedly until the next
 776                          *  packet is ready, allowing for early aborts of stream transfers.
 777                          *
 778                          *      The callback routine should be created using the STREAM_CALLBACK() macro. If the token
 779                          *  NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled
 780                          *  and this function has the Callback parameter omitted.
 781                          *
 782                          *  \note This routine should not be used on CONTROL type endpoints.
 783                          *
 784                          *  \ingroup Group_EndpointRW
 785                          *
 786                          *  \param Length    Number of bytes to send via the currently selected endpoint.
 787                          *  \param Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback
 788                          *
 789                          *  \return A value from the Endpoint_Stream_RW_ErrorCodes_t enum.
 790                          */
 791                         uint8_t Endpoint_Discard_Stream(uint16_t Length
 792                         #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
 793                                                         , uint8_t (* const Callback)(void)
 794                         #endif
 795                                                         );
 796
 797                         /** Writes the given number of bytes to the endpoint from the given buffer in little endian,
 798                          *  sending full packets to the host as needed. The last packet filled is not automatically sent;
 799                          *  the user is responsible for manually sending the last written packet to the host via the
 800                          *  Endpoint_ClearIN() macro. Between each USB packet, the given stream callback function
 801                          *  is executed repeatedly until the endpoint is ready to accept the next packet, allowing for early
 802                          *  aborts of stream transfers.
 803                          *
 804                          *      The callback routine should be created using the STREAM_CALLBACK() macro. If the token
 805                          *  NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled
 806                          *  and this function has the Callback parameter omitted.
 807                          *
 808                          *  \note This routine should not be used on CONTROL type endpoints.
 809                          *
 810                          *  \ingroup Group_EndpointRW
 811                          *
 812                          *  \param Buffer    Pointer to the source data buffer to read from.
 813                          *  \param Length    Number of bytes to read for the currently selected endpoint into the buffer.
 814                          *  \param Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback
 815                          *
 816                          *  \return A value from the Endpoint_Stream_RW_ErrorCodes_t enum.
 817                          */
 818                         uint8_t Endpoint_Write_Stream_LE(const void* Buffer, uint16_t Length
 819                         #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
 820                                                          , uint8_t (* const Callback)(void)
 821                         #endif
 822                                                          ) ATTR_NON_NULL_PTR_ARG(1);
 823
 824                         /** Writes the given number of bytes to the endpoint from the given buffer in big endian,
 825                          *  sending full packets to the host as needed. The last packet filled is not automatically sent;
 826                          *  the user is responsible for manually sending the last written packet to the host via the
 827                          *  Endpoint_ClearIN() macro. Between each USB packet, the given stream callback function
 828                          *  is executed repeatedly until the endpoint is ready to accept the next packet, allowing for early
 829                          *  aborts of stream transfers.
 830                          *
 831                          *      The callback routine should be created using the STREAM_CALLBACK() macro. If the token
 832                          *  NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled
 833                          *  and this function has the Callback parameter omitted.
 834                          *
 835                          *  \note This routine should not be used on CONTROL type endpoints.
 836                          *
 837                          *  \ingroup Group_EndpointRW
 838                          *
 839                          *  \param Buffer    Pointer to the source data buffer to read from.
 840                          *  \param Length    Number of bytes to read for the currently selected endpoint into the buffer.
 841                          *  \param Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback
 842                          *
 843                          *  \return A value from the Endpoint_Stream_RW_ErrorCodes_t enum.
 844                          */
 845                         uint8_t Endpoint_Write_Stream_BE(const void* Buffer, uint16_t Length
 846                         #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
 847                                                          , uint8_t (* const Callback)(void)
 848                         #endif
 849                                                          ) ATTR_NON_NULL_PTR_ARG(1);
 850
 851                         /** Reads the given number of bytes from the endpoint from the given buffer in little endian,
 852                          *  discarding fully read packets from the host as needed. The last packet is not automatically
 853                          *  discarded once the remaining bytes has been read; the user is responsible for manually
 854                          *  discarding the last packet from the host via the Endpoint_ClearOUT() macro. Between
 855                          *  each USB packet, the given stream callback function is executed repeatedly until the endpoint
 856                          *  is ready to accept the next packet, allowing for early aborts of stream transfers.
 857                          *
 858                          *      The callback routine should be created using the STREAM_CALLBACK() macro. If the token
 859                          *  NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled
 860                          *  and this function has the Callback parameter omitted.
 861                          *
 862                          *  \note This routine should not be used on CONTROL type endpoints.
 863                          *
 864                          *  \ingroup Group_EndpointRW
 865                          *
 866                          *  \param Buffer    Pointer to the destination data buffer to write to.
 867                          *  \param Length    Number of bytes to send via the currently selected endpoint.
 868                          *  \param Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback
 869                          *
 870                          *  \return A value from the Endpoint_Stream_RW_ErrorCodes_t enum.
 871                          */
 872                         uint8_t Endpoint_Read_Stream_LE(void* Buffer, uint16_t Length
 873                         #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
 874                                                         , uint8_t (* const Callback)(void)
 875                         #endif
 876                                                         ) ATTR_NON_NULL_PTR_ARG(1);
 877
 878                         /** Reads the given number of bytes from the endpoint from the given buffer in big endian,
 879                          *  discarding fully read packets from the host as needed. The last packet is not automatically
 880                          *  discarded once the remaining bytes has been read; the user is responsible for manually
 881                          *  discarding the last packet from the host via the Endpoint_ClearOUT() macro. Between
 882                          *  each USB packet, the given stream callback function is executed repeatedly until the endpoint
 883                          *  is ready to accept the next packet, allowing for early aborts of stream transfers.
 884                          *
 885                          *      The callback routine should be created using the STREAM_CALLBACK() macro. If the token
 886                          *  NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled
 887                          *  and this function has the Callback parameter omitted.
 888                          *
 889                          *  \note This routine should not be used on CONTROL type endpoints.
 890                          *
 891                          *  \ingroup Group_EndpointRW
 892                          *
 893                          *  \param Buffer    Pointer to the destination data buffer to write to.
 894                          *  \param Length    Number of bytes to send via the currently selected endpoint.
 895                          *  \param Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback
 896                          *
 897                          *  \return A value from the Endpoint_Stream_RW_ErrorCodes_t enum.
 898                          */
 899                         uint8_t Endpoint_Read_Stream_BE(void* Buffer, uint16_t Length
 900                         #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
 901                                                         , uint8_t (* const Callback)(void)
 902                         #endif
 903                                                         ) ATTR_NON_NULL_PTR_ARG(1);
 904
 905                         /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in little endian,
 906                          *  sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
 907                          *  in both failure and success states; the user is responsible for manually clearing the setup OUT to
 908                          *  finalize the transfer via the Endpoint_ClearControlOUT() macro.
 909                          *
 910                          *  \note This routine should only be used on CONTROL type endpoints.
 911                          *
 912                          *  \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
 913                          *           together; i.e. the entire stream data must be read or written at the one time.
 914                          *
 915                          *  \ingroup Group_EndpointRW
 916                          *
 917                          *  \param Buffer  Pointer to the source data buffer to read from.
 918                          *  \param Length  Number of bytes to read for the currently selected endpoint into the buffer.
 919                          *
 920                          *  \return A value from the Endpoint_ControlStream_RW_ErrorCodes_t enum.
 921                          */
 922                         uint8_t Endpoint_Write_Control_Stream_LE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
 923
 924                         /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in big endian,
 925                          *  sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
 926                          *  in both failure and success states; the user is responsible for manually clearing the setup OUT to
 927                          *  finalize the transfer via the Endpoint_ClearControlOUT() macro.
 928                          *
 929                          *  \note This routine should only be used on CONTROL type endpoints.
 930                          *
 931                          *  \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
 932                          *           together; i.e. the entire stream data must be read or written at the one time.
 933                          *
 934                          *  \ingroup Group_EndpointRW
 935                          *
 936                          *  \param Buffer  Pointer to the source data buffer to read from.
 937                          *  \param Length  Number of bytes to read for the currently selected endpoint into the buffer.
 938                          *
 939                          *  \return A value from the Endpoint_ControlStream_RW_ErrorCodes_t enum.
 940                          */
 941                         uint8_t Endpoint_Write_Control_Stream_BE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
 942
 943                         /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in little endian,
 944                          *  discarding fully read packets from the host as needed. The device IN acknowledgement is not
 945                          *  automatically sent after success or failure states; the user is responsible for manually sending the
 946                          *  setup IN to finalize the transfer via the Endpoint_ClearControlIN() macro.
 947                          *
 948                          *  \note This routine should only be used on CONTROL type endpoints.
 949                          *
 950                          *  \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
 951                          *           together; i.e. the entire stream data must be read or written at the one time.
 952                          *
 953                          *  \ingroup Group_EndpointRW
 954                          *
 955                          *  \param Buffer  Pointer to the destination data buffer to write to.
 956                          *  \param Length  Number of bytes to send via the currently selected endpoint.
 957                          *
 958                          *  \return A value from the Endpoint_ControlStream_RW_ErrorCodes_t enum.
 959                          */
 960                         uint8_t Endpoint_Read_Control_Stream_LE(void* Buffer, uint16_t Length)  ATTR_NON_NULL_PTR_ARG(1);
 961
 962                         /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in big endian,
 963                          *  discarding fully read packets from the host as needed. The device IN acknowledgement is not
 964                          *  automatically sent after success or failure states; the user is responsible for manually sending the
 965                          *  setup IN to finalize the transfer via the Endpoint_ClearControlIN() macro.
 966                          *
 967                          *  \note This routine should only be used on CONTROL type endpoints.
 968                          *
 969                          *  \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
 970                          *           together; i.e. the entire stream data must be read or written at the one time.
 971                          *
 972                          *  \ingroup Group_EndpointRW
 973                          *
 974                          *  \param Buffer  Pointer to the destination data buffer to write to.
 975                          *  \param Length  Number of bytes to send via the currently selected endpoint.
 976                          *
 977                          *  \return A value from the Endpoint_ControlStream_RW_ErrorCodes_t enum.
 978                          */
 979                         uint8_t Endpoint_Read_Control_Stream_BE(void* Buffer, uint16_t Length)  ATTR_NON_NULL_PTR_ARG(1);
 980
 981         /* Private Interface - For use in library only: */
 982         #if !defined(__DOXYGEN__)
 983                 /* Macros: */
 984                         #define Endpoint_AllocateMemory()              MACROS{ UECFG1X |=  (1 << ALLOC); }MACROE
 985                         #define Endpoint_DeallocateMemory()            MACROS{ UECFG1X &= ~(1 << ALLOC); }MACROE
 986
 987                         #define _ENDPOINT_GET_MAXSIZE(n)               _ENDPOINT_GET_MAXSIZE2(ENDPOINT_DETAILS_EP ## n)
 988                         #define _ENDPOINT_GET_MAXSIZE2(details)        _ENDPOINT_GET_MAXSIZE3(details)
 989                         #define _ENDPOINT_GET_MAXSIZE3(maxsize, db)    maxsize
 990
 991                         #define _ENDPOINT_GET_DOUBLEBANK(n)            _ENDPOINT_GET_DOUBLEBANK2(ENDPOINT_DETAILS_EP ## n)
 992                         #define _ENDPOINT_GET_DOUBLEBANK2(details)     _ENDPOINT_GET_DOUBLEBANK3(details)
 993                         #define _ENDPOINT_GET_DOUBLEBANK3(maxsize, db) db
 994
 995                         #if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER)
 996                                 #define ENDPOINT_DETAILS_EP0               64,  true
 997                                 #define ENDPOINT_DETAILS_EP1               256, true
 998                                 #define ENDPOINT_DETAILS_EP2               64,  true
 999                                 #define ENDPOINT_DETAILS_EP3               64,  true
1000                                 #define ENDPOINT_DETAILS_EP4               64,  true
1001                                 #define ENDPOINT_DETAILS_EP5               64,  true
1002                                 #define ENDPOINT_DETAILS_EP6               64,  true
1003                         #else
1004                                 #define ENDPOINT_DETAILS_EP0               64,  true
1005                                 #define ENDPOINT_DETAILS_EP1               64,  false
1006                                 #define ENDPOINT_DETAILS_EP2               64,  false
1007                                 #define ENDPOINT_DETAILS_EP3               64,  true
1008                                 #define ENDPOINT_DETAILS_EP4               64,  true
1009                         #endif
1010
1011                         #if defined(STATIC_ENDPOINT_CONFIGURATION)
1012                                 #define Endpoint_ConfigureEndpoint(Number, Type, Direction, Size, Banks)        \
1013                                                                      Endpoint_ConfigureEndpointStatic(Number,   \
1014                                                                               ((Type << EPTYPE0) | Direction),  \
1015                                                                               ((1 << ALLOC) | Banks | Endpoint_BytesToEPSizeMask(Size)));
1016                         #endif
1017
1018                 /* Function Prototypes: */
1019                         void Endpoint_ClearEndpoints(void);
1020                         bool Endpoint_ConfigureEndpointStatic(const uint8_t Number, const uint8_t UECFG0XData, const uint8_t UECFG1XData);
1021
1022                 /* Inline Functions: */
1023                         static inline uint8_t Endpoint_BytesToEPSizeMask(const uint16_t Bytes) ATTR_WARN_UNUSED_RESULT ATTR_CONST ATTR_ALWAYS_INLINE;
1024                         static inline uint8_t Endpoint_BytesToEPSizeMask(const uint16_t Bytes)
1025                         {
1026                                 if (Bytes <= 8)
1027                                   return (0 << EPSIZE0);
1028                                 else if (Bytes <= 16)
1029                                   return (1 << EPSIZE0);
1030                                 else if (Bytes <= 32)
1031                                   return (2 << EPSIZE0);
1032                                 #if defined(USB_LIMITED_CONTROLLER)
1033                                 else
1034                                   return (3 << EPSIZE0);
1035                                 #else
1036                                 else if (Bytes <= 64)
1037                                   return (3 << EPSIZE0);
1038                                 else if (Bytes <= 128)
1039                                   return (4 << EPSIZE0);
1040                                 else
1041                                   return (5 << EPSIZE0);
1042                                 #endif
1043                         };
1044
1045         #endif
1046
1047         /* Disable C linkage for C++ Compilers: */
1048                 #if defined(__cplusplus)
1049                         }
1050                 #endif
1051
1052 #endif
1053
1054 /** @} */