LUFA/Drivers/USB/Core/UC3/Endpoint_UC3.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2011.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, distribute, and sell this
  13   software and its documentation for any purpose is hereby granted
  14   without fee, provided that the above copyright notice appear in
  15   all copies and that both that the copyright notice and this
  16   permission notice and warranty disclaimer appear in supporting
  17   documentation, and that the name of the author not be used in
  18   advertising or publicity pertaining to distribution of the
  19   software without specific, written prior permission.
  20
  21   The author disclaim all warranties with regard to this
  22   software, including all implied warranties of merchantability
  23   and fitness.  In no event shall the author be liable for any
  24   special, indirect or consequential damages or any damages
  25   whatsoever resulting from loss of use, data or profits, whether
  26   in an action of contract, negligence or other tortious action,
  27   arising out of or in connection with the use or performance of
  28   this software.
  29 */
  30
  31 /** \file
  32  *  \brief USB Endpoint definitions for the AVR32 UC3 microcontrollers.
  33  *  \copydetails Group_EndpointManagement_UC3
  34  *
  35  *  \note This file should not be included directly. It is automatically included as needed by the USB driver
  36  *        dispatch header located in LUFA/Drivers/USB/USB.h.
  37  */
  38
  39 /** \ingroup Group_EndpointRW
  40  *  \defgroup Group_EndpointRW_UC3 Endpoint Data Reading and Writing (UC3)
  41  *  \brief Endpoint data read/write definitions for the Atmel AVR32 UC3 architecture.
  42  *
  43  *  Functions, macros, variables, enums and types related to data reading and writing from and to endpoints.
  44  */
  45
  46 /** \ingroup Group_EndpointPrimitiveRW
  47  *  \defgroup Group_EndpointPrimitiveRW_UC3 Read/Write of Primitive Data Types (UC3)
  48  *  \brief Endpoint primitive read/write definitions for the Atmel AVR32 UC3 architecture.
  49  *
  50  *  Functions, macros, variables, enums and types related to data reading and writing of primitive data types
  51  *  from and to endpoints.
  52  */
  53
  54 /** \ingroup Group_EndpointPacketManagement
  55  *  \defgroup Group_EndpointPacketManagement_UC3 Endpoint Packet Management (UC3)
  56  *  \brief Endpoint packet management definitions for the Atmel AVR32 UC3 architecture.
  57  *
  58  *  Functions, macros, variables, enums and types related to packet management of endpoints.
  59  */
  60
  61 /** \ingroup Group_EndpointManagement
  62  *  \defgroup Group_EndpointManagement_UC3 Endpoint Management (UC3)
  63  *  \brief Endpoint management definitions for the Atmel AVR32 UC3 architecture.
  64  *
  65  *  Functions, macros and enums related to endpoint management when in USB Device mode. This
  66  *  module contains the endpoint management macros, as well as endpoint interrupt and data
  67  *  send/receive functions for various data types.
  68  *
  69  *  @{
  70  */
  71
  72 #ifndef __ENDPOINT_UC3_H__
  73 #define __ENDPOINT_UC3_H__
  74
  75         /* Includes: */
  76                 #include "../../../../Common/Common.h"
  77                 #include "../USBTask.h"
  78                 #include "../USBInterrupt.h"
  79
  80         /* Enable C linkage for C++ Compilers: */
  81                 #if defined(__cplusplus)
  82                         extern "C" {
  83                 #endif
  84
  85         /* Preprocessor Checks: */
  86                 #if !defined(__INCLUDE_FROM_USB_DRIVER)
  87                         #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
  88                 #endif
  89
  90         /* Private Interface - For use in library only: */
  91         #if !defined(__DOXYGEN__)
  92                 /* Macros: */
  93                         #define _ENDPOINT_GET_MAXSIZE(EPIndex)            _ENDPOINT_GET_MAXSIZE2(ENDPOINT_DETAILS_EP ## EPIndex)
  94                         #define _ENDPOINT_GET_MAXSIZE2(EPDetails)         _ENDPOINT_GET_MAXSIZE3(EPDetails)
  95                         #define _ENDPOINT_GET_MAXSIZE3(MaxSize, Banks)    (MaxSize)
  96
  97                         #define _ENDPOINT_GET_BANKS(EPIndex)              _ENDPOINT_GET_BANKS2(ENDPOINT_DETAILS_EP ## EPIndex)
  98                         #define _ENDPOINT_GET_BANKS2(EPDetails)           _ENDPOINT_GET_BANKS3(EPDetails)
  99                         #define _ENDPOINT_GET_BANKS3(MaxSize, Banks)      (Banks)
 100
 101                         #if defined(USB_SERIES_UC3A0_AVR32) || defined(USB_SERIES_UC3A1_AVR32)
 102                                 #define ENDPOINT_DETAILS_MAXEP                 7
 103
 104                                 #define ENDPOINT_DETAILS_EP0                   64,  1
 105                                 #define ENDPOINT_DETAILS_EP1                   256, 2
 106                                 #define ENDPOINT_DETAILS_EP2                   256, 2
 107                                 #define ENDPOINT_DETAILS_EP3                   64,  2
 108                                 #define ENDPOINT_DETAILS_EP4                   64,  2
 109                                 #define ENDPOINT_DETAILS_EP5                   256, 2
 110                                 #define ENDPOINT_DETAILS_EP6                   256, 2
 111                         #elif defined(USB_SERIES_UC3A3_AVR32) || defined(USB_SERIES_UC3A4_AVR32)
 112                                 #define ENDPOINT_DETAILS_MAXEP                 8
 113
 114                                 #define ENDPOINT_DETAILS_EP0                   64,  1
 115                                 #define ENDPOINT_DETAILS_EP1                   512, 2
 116                                 #define ENDPOINT_DETAILS_EP2                   512, 2
 117                                 #define ENDPOINT_DETAILS_EP3                   512, 2
 118                                 #define ENDPOINT_DETAILS_EP4                   512, 2
 119                                 #define ENDPOINT_DETAILS_EP5                   512, 2
 120                                 #define ENDPOINT_DETAILS_EP6                   512, 2
 121                                 #define ENDPOINT_DETAILS_EP7                   512, 2
 122                         #elif defined(USB_SERIES_UC3B0_AVR32) || defined(USB_SERIES_UC3B1_AVR32)
 123                                 #define ENDPOINT_DETAILS_MAXEP                 7
 124
 125                                 #define ENDPOINT_DETAILS_EP0                   64,  1
 126                                 #define ENDPOINT_DETAILS_EP1                   64,  2
 127                                 #define ENDPOINT_DETAILS_EP2                   64,  2
 128                                 #define ENDPOINT_DETAILS_EP3                   64,  2
 129                                 #define ENDPOINT_DETAILS_EP4                   64,  2
 130                                 #define ENDPOINT_DETAILS_EP5                   256, 2
 131                                 #define ENDPOINT_DETAILS_EP6                   256, 2
 132                         #endif
 133
 134                         #define ENDPOINT_HSB_ADDRESS_SPACE_SIZE            (64 * 1024UL)
 135
 136                 /* Inline Functions: */
 137                         static inline uint32_t Endpoint_BytesToEPSizeMask(const uint16_t Bytes) ATTR_WARN_UNUSED_RESULT ATTR_CONST
 138                                                                                                 ATTR_ALWAYS_INLINE;
 139                         static inline uint32_t Endpoint_BytesToEPSizeMask(const uint16_t Bytes)
 140                         {
 141                                 uint8_t  MaskVal    = 0;
 142                                 uint16_t CheckBytes = 8;
 143
 144                                 while (CheckBytes < Bytes)
 145                                 {
 146                                         MaskVal++;
 147                                         CheckBytes <<= 1;
 148                                 }
 149
 150                                 return (MaskVal << AVR32_USBB_EPSIZE_OFFSET);
 151                         }
 152
 153                 /* Function Prototypes: */
 154                         void Endpoint_ClearEndpoints(void);
 155                         bool Endpoint_ConfigureEndpoint_Prv(const uint8_t Number,
 156                                                             const uint32_t UECFGXData);
 157
 158                 /* External Variables: */
 159                         extern volatile uint32_t USB_SelectedEndpoint;
 160                         extern volatile uint8_t* USB_EndpointFIFOPos[];
 161         #endif
 162
 163         /* Public Interface - May be used in end-application: */
 164                 /* Macros: */
 165                         /** \name Endpoint Direction Masks */
 166                         //@{
 167                         /** Endpoint data direction mask for \ref Endpoint_ConfigureEndpoint(). This indicates that the endpoint
 168                          *  should be initialized in the OUT direction - i.e. data flows from host to device.
 169                          */
 170                         #define ENDPOINT_DIR_OUT                        AVR32_USBB_UECFG0_EPDIR_OUT
 171
 172                         /** Endpoint data direction mask for \ref Endpoint_ConfigureEndpoint(). This indicates that the endpoint
 173                          *  should be initialized in the IN direction - i.e. data flows from device to host.
 174                          */
 175                         #define ENDPOINT_DIR_IN                         AVR32_USBB_UECFG0_EPDIR_IN
 176                         //@}
 177
 178                         /** \name Endpoint Bank Mode Masks */
 179                         //@{
 180                         /** Mask for the bank mode selection for the \ref Endpoint_ConfigureEndpoint() macro. This indicates
 181                          *  that the endpoint should have one single bank, which requires less USB FIFO memory but results
 182                          *  in slower transfers as only one USB device (the AVR or the host) can access the endpoint's
 183                          *  bank at the one time.
 184                          */
 185                         #define ENDPOINT_BANK_SINGLE                    AVR32_USBB_UECFG0_EPBK_SINGLE
 186
 187                         /** Mask for the bank mode selection for the \ref Endpoint_ConfigureEndpoint() macro. This indicates
 188                          *  that the endpoint should have two banks, which requires more USB FIFO memory but results
 189                          *  in faster transfers as one USB device (the AVR or the host) can access one bank while the other
 190                          *  accesses the second bank.
 191                          */
 192                         #define ENDPOINT_BANK_DOUBLE                    AVR32_USBB_UECFG0_EPBK_DOUBLE
 193
 194                         #if defined(USB_SERIES_UC3A3_AVR32) || defined(USB_SERIES_UC3A4_AVR32) || defined(__DOXYGEN__)
 195                                 /** Mask for the bank mode selection for the \ref Endpoint_ConfigureEndpoint() macro. This indicates
 196                                  *  that the endpoint should have three banks, which requires more USB FIFO memory but results
 197                                  *  in faster transfers as one USB device (the AVR or the host) can access one bank while the other
 198                                  *  accesses the remaining banks.
 199                                  *
 200                                  *  \note Not available on all AVR models.
 201                                  */
 202                                 #define ENDPOINT_BANK_TRIPLE                AVR32_USBB_UECFG0_EPBK_TRIPLE
 203                         #endif
 204                         //@}
 205
 206                         #if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
 207                                 /** Default size of the default control endpoint's bank, until altered by the control endpoint bank size
 208                                  *  value in the device descriptor. Not available if the \c FIXED_CONTROL_ENDPOINT_SIZE token is defined.
 209                                  */
 210                                 #define ENDPOINT_CONTROLEP_DEFAULT_SIZE     8
 211                         #endif
 212
 213                         /** Retrieves the maximum bank size in bytes of a given endpoint.
 214                          *
 215                          *  \note This macro will only work correctly on endpoint indexes that are compile-time constants
 216                          *        defined by the preprocessor.
 217                          *
 218                          *  \param[in] EPIndex  Endpoint number, a value between 0 and (\ref ENDPOINT_TOTAL_ENDPOINTS - 1)
 219                          */
 220                         #define ENDPOINT_MAX_SIZE(EPIndex)              _ENDPOINT_GET_MAXSIZE(EPIndex)
 221
 222                         /** Retrieves the total number of banks supported by the given endpoint.
 223                          *
 224                          *  \note This macro will only work correctly on endpoint indexes that are compile-time constants
 225                          *        defined by the preprocessor.
 226                          *
 227                          *  \param[in] EPIndex  Endpoint number, a value between 0 and (\ref ENDPOINT_TOTAL_ENDPOINTS - 1)
 228                          */
 229                         #define ENDPOINT_BANKS_SUPPORTED(EPIndex)       _ENDPOINT_GET_BANKS(EPIndex)
 230
 231                         #if !defined(CONTROL_ONLY_DEVICE) || defined(__DOXYGEN__)
 232                                 /** Total number of endpoints (including the default control endpoint at address 0) which may
 233                                  *  be used in the device. Different AVR models support different amounts of endpoints,
 234                                  *  this value reflects the maximum number of endpoints for the currently selected AVR model.
 235                                  */
 236                                 #define ENDPOINT_TOTAL_ENDPOINTS            ENDPOINT_DETAILS_MAXEP
 237                         #else
 238                                 #define ENDPOINT_TOTAL_ENDPOINTS            1
 239                         #endif
 240
 241                 /* Enums: */
 242                         /** Enum for the possible error return codes of the \ref Endpoint_WaitUntilReady() function.
 243                          *
 244                          *  \ingroup Group_EndpointRW_UC3
 245                          */
 246                         enum Endpoint_WaitUntilReady_ErrorCodes_t
 247                         {
 248                                 ENDPOINT_READYWAIT_NoError                 = 0, /**< Endpoint is ready for next packet, no error. */
 249                                 ENDPOINT_READYWAIT_EndpointStalled         = 1, /**< The endpoint was stalled during the stream
 250                                                                                  *   transfer by the host or device.
 251                                                                                  */
 252                                 ENDPOINT_READYWAIT_DeviceDisconnected      = 2, /**< Device was disconnected from the host while
 253                                                                                  *   waiting for the endpoint to become ready.
 254                                                                                  */
 255                                 ENDPOINT_READYWAIT_BusSuspended            = 3, /**< The USB bus has been suspended by the host and
 256                                                                                  *   no USB endpoint traffic can occur until the bus
 257                                                                                  *   has resumed.
 258                                                                                  */
 259                                 ENDPOINT_READYWAIT_Timeout                 = 4, /**< The host failed to accept or send the next packet
 260                                                                                  *   within the software timeout period set by the
 261                                                                                  *   \ref USB_STREAM_TIMEOUT_MS macro.
 262                                                                                  */
 263                         };
 264
 265                 /* Inline Functions: */
 266                         /** Configures the specified endpoint number with the given endpoint type, direction, bank size
 267                          *  and banking mode. Once configured, the endpoint may be read from or written to, depending
 268                          *  on its direction.
 269                          *
 270                          *  \param[in] Number     Endpoint number to configure. This must be more than 0 and less than
 271                          *                        \ref ENDPOINT_TOTAL_ENDPOINTS.
 272                          *
 273                          *  \param[in] Type       Type of endpoint to configure, a \c EP_TYPE_* mask. Not all endpoint types
 274                          *                        are available on Low Speed USB devices - refer to the USB 2.0 specification.
 275                          *
 276                          *  \param[in] Direction  Endpoint data direction, either \ref ENDPOINT_DIR_OUT or \ref ENDPOINT_DIR_IN.
 277                          *                        All endpoints (except Control type) are unidirectional - data may only be read
 278                          *                        from or written to the endpoint bank based on its direction, not both.
 279                          *
 280                          *  \param[in] Size       Size of the endpoint's bank, where packets are stored before they are transmitted
 281                          *                        to the USB host, or after they have been received from the USB host (depending on
 282                          *                        the endpoint's data direction). The bank size must indicate the maximum packet size
 283                          *                        that the endpoint can handle.
 284                          *
 285                          *  \param[in] Banks      Number of banks to use for the endpoint being configured, an \c ENDPOINT_BANK_* mask.
 286                          *                        More banks uses more USB DPRAM, but offers better performance. Isochronous type
 287                          *                        endpoints <b>must</b> have at least two banks.
 288                          *
 289                          *  \note When the \c ORDERED_EP_CONFIG compile time option is used, Endpoints <b>must</b> be configured in
 290                          *        ascending order, or bank corruption will occur.
 291                          *        \n\n
 292                          *
 293                          *  \note Different endpoints may have different maximum packet sizes based on the endpoint's index - refer to
 294                          *        the chosen microcontroller model's datasheet to determine the maximum bank size for each endpoint.
 295                          *        \n\n
 296                          *
 297                          *  \note The default control endpoint should not be manually configured by the user application, as
 298                          *        it is automatically configured by the library internally.
 299                          *        \n\n
 300                          *
 301                          *  \note This routine will automatically select the specified endpoint upon success. Upon failure, the endpoint
 302                          *        which failed to reconfigure correctly will be selected.
 303                          *
 304                          *  \return Boolean \c true if the configuration succeeded, \c false otherwise.
 305                          */
 306                         static inline bool Endpoint_ConfigureEndpoint(const uint8_t Number,
 307                                                                       const uint8_t Type,
 308                                                                       const uint8_t Direction,
 309                                                                       const uint16_t Size,
 310                                                                       const uint8_t Banks) ATTR_ALWAYS_INLINE;
 311                         static inline bool Endpoint_ConfigureEndpoint(const uint8_t Number,
 312                                                                       const uint8_t Type,
 313                                                                       const uint8_t Direction,
 314                                                                       const uint16_t Size,
 315                                                                       const uint8_t Banks)
 316                         {
 317                                 return Endpoint_ConfigureEndpoint_Prv(Number, (AVR32_USBB_ALLOC_MASK |
 318                                                                                ((uint32_t)Type      << AVR32_USBB_EPTYPE_OFFSET) |
 319                                                                                ((uint32_t)Direction << AVR32_USBB_EPDIR_OFFSET)  |
 320                                                                                ((uint32_t)Banks     << AVR32_USBB_EPBK_OFFSET)   |
 321                                                                                Endpoint_BytesToEPSizeMask(Size)));
 322                         }
 323
 324                         /** Indicates the number of bytes currently stored in the current endpoint's selected bank.
 325                          *
 326                          *  \note The return width of this function may differ, depending on the maximum endpoint bank size
 327                          *        of the selected AVR model.
 328                          *
 329                          *  \ingroup Group_EndpointRW_UC3
 330                          *
 331                          *  \return Total number of bytes in the currently selected Endpoint's FIFO buffer.
 332                          */
 333                         static inline uint16_t Endpoint_BytesInEndpoint(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 334                         static inline uint16_t Endpoint_BytesInEndpoint(void)
 335                         {
 336                                 return (&AVR32_USBB.UESTA0)[USB_SelectedEndpoint].byct;
 337                         }
 338
 339                         /** Get the endpoint address of the currently selected endpoint. This is typically used to save
 340                          *  the currently selected endpoint number so that it can be restored after another endpoint has
 341                          *  been manipulated.
 342                          *
 343                          *  \return Index of the currently selected endpoint.
 344                          */
 345                         static inline uint8_t Endpoint_GetCurrentEndpoint(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 346                         static inline uint8_t Endpoint_GetCurrentEndpoint(void)
 347                         {
 348                                 return USB_SelectedEndpoint;
 349                         }
 350
 351                         /** Selects the given endpoint number. If the address from the device descriptors is used, the
 352                          *  value should be masked with the \ref ENDPOINT_EPNUM_MASK constant to extract only the endpoint
 353                          *  number (and discarding the endpoint direction bit).
 354                          *
 355                          *  Any endpoint operations which do not require the endpoint number to be indicated will operate on
 356                          *  the currently selected endpoint.
 357                          *
 358                          *  \param[in] EndpointNumber Endpoint number to select.
 359                          */
 360                         static inline void Endpoint_SelectEndpoint(const uint8_t EndpointNumber) ATTR_ALWAYS_INLINE;
 361                         static inline void Endpoint_SelectEndpoint(const uint8_t EndpointNumber)
 362                         {
 363                                 USB_SelectedEndpoint = EndpointNumber;
 364                         }
 365
 366                         /** Resets the endpoint bank FIFO. This clears all the endpoint banks and resets the USB controller's
 367                          *  data In and Out pointers to the bank's contents.
 368                          *
 369                          *  \param[in] EndpointNumber Endpoint number whose FIFO buffers are to be reset.
 370                          */
 371                         static inline void Endpoint_ResetEndpoint(const uint8_t EndpointNumber) ATTR_ALWAYS_INLINE;
 372                         static inline void Endpoint_ResetEndpoint(const uint8_t EndpointNumber)
 373                         {
 374                                 AVR32_USBB.uerst |=  (AVR32_USBB_EPRST0_MASK << EndpointNumber);
 375                                 AVR32_USBB.uerst &= ~(AVR32_USBB_EPRST0_MASK << EndpointNumber);
 376                                 USB_EndpointFIFOPos[EndpointNumber] = &AVR32_USBB_SLAVE[EndpointNumber * ENDPOINT_HSB_ADDRESS_SPACE_SIZE];
 377                         }
 378
 379                         /** Enables the currently selected endpoint so that data can be sent and received through it to
 380                          *  and from a host.
 381                          *
 382                          *  \note Endpoints must first be configured properly via \ref Endpoint_ConfigureEndpoint().
 383                          */
 384                         static inline void Endpoint_EnableEndpoint(void) ATTR_ALWAYS_INLINE;
 385                         static inline void Endpoint_EnableEndpoint(void)
 386                         {
 387                                 AVR32_USBB.uerst |=  (AVR32_USBB_EPEN0_MASK << USB_SelectedEndpoint);
 388                         }
 389
 390                         /** Disables the currently selected endpoint so that data cannot be sent and received through it
 391                          *  to and from a host.
 392                          */
 393                         static inline void Endpoint_DisableEndpoint(void) ATTR_ALWAYS_INLINE;
 394                         static inline void Endpoint_DisableEndpoint(void)
 395                         {
 396                                 AVR32_USBB.uerst &= ~(AVR32_USBB_EPEN0_MASK << USB_SelectedEndpoint);
 397                         }
 398
 399                         /** Determines if the currently selected endpoint is enabled, but not necessarily configured.
 400                          *
 401                          * \return Boolean \c true if the currently selected endpoint is enabled, \c false otherwise.
 402                          */
 403                         static inline bool Endpoint_IsEnabled(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 404                         static inline bool Endpoint_IsEnabled(void)
 405                         {
 406                                 return ((AVR32_USBB.uerst & (AVR32_USBB_EPEN0_MASK << USB_SelectedEndpoint)) ? true : false);
 407                         }
 408
 409                         /** Retrieves the number of busy banks in the currently selected endpoint, which have been queued for
 410                          *  transmission via the \ref Endpoint_ClearIN() command, or are awaiting acknowledgement via the
 411                          *  \ref Endpoint_ClearOUT() command.
 412                          *
 413                          *  \ingroup Group_EndpointPacketManagement_UC3
 414                          *
 415                          *  \return Total number of busy banks in the selected endpoint.
 416                          */
 417                         static inline uint8_t Endpoint_GetBusyBanks(void) ATTR_ALWAYS_INLINE ATTR_WARN_UNUSED_RESULT;
 418                         static inline uint8_t Endpoint_GetBusyBanks(void)
 419                         {
 420                                 return (&AVR32_USBB.UESTA0)[USB_SelectedEndpoint].nbusybk;
 421                         }
 422
 423                         /** Aborts all pending IN transactions on the currently selected endpoint, once the bank
 424                          *  has been queued for transmission to the host via \ref Endpoint_ClearIN(). This function
 425                          *  will terminate all queued transactions, resetting the endpoint banks ready for a new
 426                          *  packet.
 427                          *
 428                          *  \ingroup Group_EndpointPacketManagement_UC3
 429                          */
 430                         static inline void Endpoint_AbortPendingIN(void)
 431                         {
 432                                 while (Endpoint_GetBusyBanks() != 0)
 433                                 {
 434                                         (&AVR32_USBB.UECON0SET)[USB_SelectedEndpoint].killbks = true;
 435                                         while ((&AVR32_USBB.UECON0)[USB_SelectedEndpoint].killbk);
 436                                 }
 437                         }
 438
 439                         /** Determines if the currently selected endpoint may be read from (if data is waiting in the endpoint
 440                          *  bank and the endpoint is an OUT direction, or if the bank is not yet full if the endpoint is an IN
 441                          *  direction). This function will return false if an error has occurred in the endpoint, if the endpoint
 442                          *  is an OUT direction and no packet (or an empty packet) has been received, or if the endpoint is an IN
 443                          *  direction and the endpoint bank is full.
 444                          *
 445                          *  \ingroup Group_EndpointPacketManagement_UC3
 446                          *
 447                          *  \return Boolean \c true if the currently selected endpoint may be read from or written to, depending
 448                          *          on its direction.
 449                          */
 450                         static inline bool Endpoint_IsReadWriteAllowed(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 451                         static inline bool Endpoint_IsReadWriteAllowed(void)
 452                         {
 453                                 return (&AVR32_USBB.UESTA0)[USB_SelectedEndpoint].rwall;
 454                         }
 455
 456                         /** Determines if the currently selected endpoint is configured.
 457                          *
 458                          *  \return Boolean \c true if the currently selected endpoint has been configured, \c false otherwise.
 459                          */
 460                         static inline bool Endpoint_IsConfigured(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 461                         static inline bool Endpoint_IsConfigured(void)
 462                         {
 463                                 return (&AVR32_USBB.UESTA0)[USB_SelectedEndpoint].cfgok;
 464                         }
 465
 466                         /** Returns a mask indicating which INTERRUPT type endpoints have interrupted - i.e. their
 467                          *  interrupt duration has elapsed. Which endpoints have interrupted can be determined by
 468                          *  masking the return value against <tt>(1 << <i>{Endpoint Number}</i>)</tt>.
 469                          *
 470                          *  \return Mask whose bits indicate which endpoints have interrupted.
 471                          */
 472                         static inline uint8_t Endpoint_GetEndpointInterrupts(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 473                         static inline uint8_t Endpoint_GetEndpointInterrupts(void)
 474                         {
 475                                 return ((AVR32_USBB.udint & (AVR32_USBB_EP6INT_MASK | AVR32_USBB_EP5INT_MASK |
 476                                                              AVR32_USBB_EP4INT_MASK | AVR32_USBB_EP3INT_MASK |
 477                                                              AVR32_USBB_EP2INT_MASK | AVR32_USBB_EP1INT_MASK |
 478                                                              AVR32_USBB_EP0INT_MASK)) >> AVR32_USBB_EP0INT_OFFSET);
 479                         }
 480
 481                         /** Determines if the specified endpoint number has interrupted (valid only for INTERRUPT type
 482                          *  endpoints).
 483                          *
 484                          *  \param[in] EndpointNumber  Index of the endpoint whose interrupt flag should be tested.
 485                          *
 486                          *  \return Boolean \c true if the specified endpoint has interrupted, \c false otherwise.
 487                          */
 488                         static inline bool Endpoint_HasEndpointInterrupted(const uint8_t EndpointNumber) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 489                         static inline bool Endpoint_HasEndpointInterrupted(const uint8_t EndpointNumber)
 490                         {
 491                                 return ((Endpoint_GetEndpointInterrupts() & (AVR32_USBB_EP0INT_MASK << EndpointNumber)) ? true : false);
 492                         }
 493
 494                         /** Determines if the selected IN endpoint is ready for a new packet to be sent to the host.
 495                          *
 496                          *  \ingroup Group_EndpointPacketManagement_UC3
 497                          *
 498                          *  \return Boolean \c true if the current endpoint is ready for an IN packet, \c false otherwise.
 499                          */
 500                         static inline bool Endpoint_IsINReady(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 501                         static inline bool Endpoint_IsINReady(void)
 502                         {
 503                                 return (&AVR32_USBB.UESTA0)[USB_SelectedEndpoint].txini;
 504                         }
 505
 506                         /** Determines if the selected OUT endpoint has received new packet from the host.
 507                          *
 508                          *  \ingroup Group_EndpointPacketManagement_UC3
 509                          *
 510                          *  \return Boolean \c true if current endpoint is has received an OUT packet, \c false otherwise.
 511                          */
 512                         static inline bool Endpoint_IsOUTReceived(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 513                         static inline bool Endpoint_IsOUTReceived(void)
 514                         {
 515                                 return (&AVR32_USBB.UESTA0)[USB_SelectedEndpoint].rxouti;
 516                         }
 517
 518                         /** Determines if the current CONTROL type endpoint has received a SETUP packet.
 519                          *
 520                          *  \ingroup Group_EndpointPacketManagement_UC3
 521                          *
 522                          *  \return Boolean \c true if the selected endpoint has received a SETUP packet, \c false otherwise.
 523                          */
 524                         static inline bool Endpoint_IsSETUPReceived(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 525                         static inline bool Endpoint_IsSETUPReceived(void)
 526                         {
 527                                 return (&AVR32_USBB.UESTA0)[USB_SelectedEndpoint].rxstpi;
 528                         }
 529
 530                         /** Clears a received SETUP packet on the currently selected CONTROL type endpoint, freeing up the
 531                          *  endpoint for the next packet.
 532                          *
 533                          *  \ingroup Group_EndpointPacketManagement_UC3
 534                          *
 535                          *  \note This is not applicable for non CONTROL type endpoints.
 536                          */
 537                         static inline void Endpoint_ClearSETUP(void) ATTR_ALWAYS_INLINE;
 538                         static inline void Endpoint_ClearSETUP(void)
 539                         {
 540                                 (&AVR32_USBB.UESTA0CLR)[USB_SelectedEndpoint].rxstpic = true;
 541                                 USB_EndpointFIFOPos[USB_SelectedEndpoint] = &AVR32_USBB_SLAVE[USB_SelectedEndpoint * ENDPOINT_HSB_ADDRESS_SPACE_SIZE];
 542                         }
 543
 544                         /** Sends an IN packet to the host on the currently selected endpoint, freeing up the endpoint for the
 545                          *  next packet and switching to the alternative endpoint bank if double banked.
 546                          *
 547                          *  \ingroup Group_EndpointPacketManagement_UC3
 548                          */
 549                         static inline void Endpoint_ClearIN(void) ATTR_ALWAYS_INLINE;
 550                         static inline void Endpoint_ClearIN(void)
 551                         {
 552                                 (&AVR32_USBB.UESTA0CLR)[USB_SelectedEndpoint].txinic   = true;
 553                                 (&AVR32_USBB.UECON0CLR)[USB_SelectedEndpoint].fifoconc = true;
 554                                 USB_EndpointFIFOPos[USB_SelectedEndpoint] = &AVR32_USBB_SLAVE[USB_SelectedEndpoint * ENDPOINT_HSB_ADDRESS_SPACE_SIZE];
 555                         }
 556
 557                         /** Acknowledges an OUT packet to the host on the currently selected endpoint, freeing up the endpoint
 558                          *  for the next packet and switching to the alternative endpoint bank if double banked.
 559                          *
 560                          *  \ingroup Group_EndpointPacketManagement_UC3
 561                          */
 562                         static inline void Endpoint_ClearOUT(void) ATTR_ALWAYS_INLINE;
 563                         static inline void Endpoint_ClearOUT(void)
 564                         {
 565                                 (&AVR32_USBB.UESTA0CLR)[USB_SelectedEndpoint].rxoutic  = true;
 566                                 (&AVR32_USBB.UECON0CLR)[USB_SelectedEndpoint].fifoconc = true;
 567                                 USB_EndpointFIFOPos[USB_SelectedEndpoint] = &AVR32_USBB_SLAVE[USB_SelectedEndpoint * ENDPOINT_HSB_ADDRESS_SPACE_SIZE];
 568                         }
 569
 570                         /** Stalls the current endpoint, indicating to the host that a logical problem occurred with the
 571                          *  indicated endpoint and that the current transfer sequence should be aborted. This provides a
 572                          *  way for devices to indicate invalid commands to the host so that the current transfer can be
 573                          *  aborted and the host can begin its own recovery sequence.
 574                          *
 575                          *  The currently selected endpoint remains stalled until either the \ref Endpoint_ClearStall() macro
 576                          *  is called, or the host issues a CLEAR FEATURE request to the device for the currently selected
 577                          *  endpoint.
 578                          *
 579                          *  \ingroup Group_EndpointPacketManagement_UC3
 580                          */
 581                         static inline void Endpoint_StallTransaction(void) ATTR_ALWAYS_INLINE;
 582                         static inline void Endpoint_StallTransaction(void)
 583                         {
 584                                 (&AVR32_USBB.UECON0SET)[USB_SelectedEndpoint].stallrqs = true;
 585                         }
 586
 587                         /** Clears the STALL condition on the currently selected endpoint.
 588                          *
 589                          *  \ingroup Group_EndpointPacketManagement_UC3
 590                          */
 591                         static inline void Endpoint_ClearStall(void) ATTR_ALWAYS_INLINE;
 592                         static inline void Endpoint_ClearStall(void)
 593                         {
 594                                 (&AVR32_USBB.UECON0CLR)[USB_SelectedEndpoint].stallrqc = true;
 595                         }
 596
 597                         /** Determines if the currently selected endpoint is stalled, false otherwise.
 598                          *
 599                          *  \ingroup Group_EndpointPacketManagement_UC3
 600                          *
 601                          *  \return Boolean \c true if the currently selected endpoint is stalled, \c false otherwise.
 602                          */
 603                         static inline bool Endpoint_IsStalled(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 604                         static inline bool Endpoint_IsStalled(void)
 605                         {
 606                                 return (&AVR32_USBB.UECON0)[USB_SelectedEndpoint].stallrq;
 607                         }
 608
 609                         /** Resets the data toggle of the currently selected endpoint. */
 610                         static inline void Endpoint_ResetDataToggle(void) ATTR_ALWAYS_INLINE;
 611                         static inline void Endpoint_ResetDataToggle(void)
 612                         {
 613                                 (&AVR32_USBB.UECON0SET)[USB_SelectedEndpoint].rstdts = true;
 614                         }
 615
 616                         /** Determines the currently selected endpoint's direction.
 617                          *
 618                          *  \return The currently selected endpoint's direction, as a \c ENDPOINT_DIR_* mask.
 619                          */
 620                         static inline uint32_t Endpoint_GetEndpointDirection(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 621                         static inline uint32_t Endpoint_GetEndpointDirection(void)
 622                         {
 623                                 return ((&AVR32_USBB.UECFG0)[USB_SelectedEndpoint].epdir ? ENDPOINT_DIR_IN : ENDPOINT_DIR_OUT);
 624                         }
 625
 626                         /** Sets the direction of the currently selected endpoint.
 627                          *
 628                          *  \param[in] DirectionMask  New endpoint direction, as a \c ENDPOINT_DIR_* mask.
 629                          */
 630                         static inline void Endpoint_SetEndpointDirection(const uint32_t DirectionMask) ATTR_ALWAYS_INLINE;
 631                         static inline void Endpoint_SetEndpointDirection(const uint32_t DirectionMask)
 632                         {
 633                                 (&AVR32_USBB.UECFG0)[USB_SelectedEndpoint].epdir = (DirectionMask == ENDPOINT_DIR_IN);
 634                         }
 635
 636                         /** Reads one byte from the currently selected endpoint's bank, for OUT direction endpoints.
 637                          *
 638                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 639                          *
 640                          *  \return Next byte in the currently selected endpoint's FIFO buffer.
 641                          */
 642                         static inline uint8_t Endpoint_Read_8(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 643                         static inline uint8_t Endpoint_Read_8(void)
 644                         {
 645                                 return *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 646                         }
 647
 648                         /** Writes one byte to the currently selected endpoint's bank, for IN direction endpoints.
 649                          *
 650                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 651                          *
 652                          *  \param[in] Data  Data to write into the the currently selected endpoint's FIFO buffer.
 653                          */
 654                         static inline void Endpoint_Write_8(const uint8_t Data) ATTR_ALWAYS_INLINE;
 655                         static inline void Endpoint_Write_8(const uint8_t Data)
 656                         {
 657                                 *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++) = Data;
 658                         }
 659
 660                         /** Discards one byte from the currently selected endpoint's bank, for OUT direction endpoints.
 661                          *
 662                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 663                          */
 664                         static inline void Endpoint_Discard_8(void) ATTR_ALWAYS_INLINE;
 665                         static inline void Endpoint_Discard_8(void)
 666                         {
 667                                 uint8_t Dummy;
 668
 669                                 Dummy = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 670                         }
 671
 672                         /** Reads two bytes from the currently selected endpoint's bank in little endian format, for OUT
 673                          *  direction endpoints.
 674                          *
 675                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 676                          *
 677                          *  \return Next two bytes in the currently selected endpoint's FIFO buffer.
 678                          */
 679                         static inline uint16_t Endpoint_Read_16_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 680                         static inline uint16_t Endpoint_Read_16_LE(void)
 681                         {
 682                                 uint16_t Byte1 = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 683                                 uint16_t Byte0 = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 684
 685                                 return ((Byte0 << 8) | Byte1);
 686                         }
 687
 688                         /** Reads two bytes from the currently selected endpoint's bank in big endian format, for OUT
 689                          *  direction endpoints.
 690                          *
 691                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 692                          *
 693                          *  \return Next two bytes in the currently selected endpoint's FIFO buffer.
 694                          */
 695                         static inline uint16_t Endpoint_Read_16_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 696                         static inline uint16_t Endpoint_Read_16_BE(void)
 697                         {
 698                                 uint16_t Byte0 = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 699                                 uint16_t Byte1 = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 700
 701                                 return ((Byte0 << 8) | Byte1);
 702                         }
 703
 704                         /** Writes two bytes to the currently selected endpoint's bank in little endian format, for IN
 705                          *  direction endpoints.
 706                          *
 707                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 708                          *
 709                          *  \param[in] Data  Data to write to the currently selected endpoint's FIFO buffer.
 710                          */
 711                         static inline void Endpoint_Write_16_LE(const uint16_t Data) ATTR_ALWAYS_INLINE;
 712                         static inline void Endpoint_Write_16_LE(const uint16_t Data)
 713                         {
 714                                 *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++) = (Data >> 8);
 715                                 *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++) = (Data & 0xFF);
 716                         }
 717
 718                         /** Writes two bytes to the currently selected endpoint's bank in big endian format, for IN
 719                          *  direction endpoints.
 720                          *
 721                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 722                          *
 723                          *  \param[in] Data  Data to write to the currently selected endpoint's FIFO buffer.
 724                          */
 725                         static inline void Endpoint_Write_16_BE(const uint16_t Data) ATTR_ALWAYS_INLINE;
 726                         static inline void Endpoint_Write_16_BE(const uint16_t Data)
 727                         {
 728                                 *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++) = (Data & 0xFF);
 729                                 *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++) = (Data >> 8);
 730                         }
 731
 732                         /** Discards two bytes from the currently selected endpoint's bank, for OUT direction endpoints.
 733                          *
 734                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 735                          */
 736                         static inline void Endpoint_Discard_16(void) ATTR_ALWAYS_INLINE;
 737                         static inline void Endpoint_Discard_16(void)
 738                         {
 739                                 uint8_t Dummy;
 740
 741                                 Dummy = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 742                                 Dummy = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 743                         }
 744
 745                         /** Reads four bytes from the currently selected endpoint's bank in little endian format, for OUT
 746                          *  direction endpoints.
 747                          *
 748                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 749                          *
 750                          *  \return Next four bytes in the currently selected endpoint's FIFO buffer.
 751                          */
 752                         static inline uint32_t Endpoint_Read_32_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 753                         static inline uint32_t Endpoint_Read_32_LE(void)
 754                         {
 755                                 uint32_t Byte3 = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 756                                 uint32_t Byte2 = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 757                                 uint32_t Byte1 = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 758                                 uint32_t Byte0 = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 759
 760                                 return ((Byte0 << 24) | (Byte1 << 16) | (Byte2 << 8) | Byte3);
 761                         }
 762
 763                         /** Reads four bytes from the currently selected endpoint's bank in big endian format, for OUT
 764                          *  direction endpoints.
 765                          *
 766                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 767                          *
 768                          *  \return Next four bytes in the currently selected endpoint's FIFO buffer.
 769                          */
 770                         static inline uint32_t Endpoint_Read_32_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 771                         static inline uint32_t Endpoint_Read_32_BE(void)
 772                         {
 773                                 uint32_t Byte0 = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 774                                 uint32_t Byte1 = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 775                                 uint32_t Byte2 = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 776                                 uint32_t Byte3 = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 777
 778                                 return ((Byte0 << 24) | (Byte1 << 16) | (Byte2 << 8) | Byte3);
 779                         }
 780
 781                         /** Writes four bytes to the currently selected endpoint's bank in little endian format, for IN
 782                          *  direction endpoints.
 783                          *
 784                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 785                          *
 786                          *  \param[in] Data  Data to write to the currently selected endpoint's FIFO buffer.
 787                          */
 788                         static inline void Endpoint_Write_32_LE(const uint32_t Data) ATTR_ALWAYS_INLINE;
 789                         static inline void Endpoint_Write_32_LE(const uint32_t Data)
 790                         {
 791                                 *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++) = (Data >> 24);
 792                                 *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++) = (Data >> 16);
 793                                 *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++) = (Data >> 8);
 794                                 *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++) = (Data &  0xFF);
 795                         }
 796
 797                         /** Writes four bytes to the currently selected endpoint's bank in big endian format, for IN
 798                          *  direction endpoints.
 799                          *
 800                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 801                          *
 802                          *  \param[in] Data  Data to write to the currently selected endpoint's FIFO buffer.
 803                          */
 804                         static inline void Endpoint_Write_32_BE(const uint32_t Data) ATTR_ALWAYS_INLINE;
 805                         static inline void Endpoint_Write_32_BE(const uint32_t Data)
 806                         {
 807                                 *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++) = (Data &  0xFF);
 808                                 *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++) = (Data >> 8);
 809                                 *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++) = (Data >> 16);
 810                                 *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++) = (Data >> 24);
 811                         }
 812
 813                         /** Discards four bytes from the currently selected endpoint's bank, for OUT direction endpoints.
 814                          *
 815                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 816                          */
 817                         static inline void Endpoint_Discard_32(void) ATTR_ALWAYS_INLINE;
 818                         static inline void Endpoint_Discard_32(void)
 819                         {
 820                                 uint8_t Dummy;
 821
 822                                 Dummy = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 823                                 Dummy = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 824                                 Dummy = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 825                                 Dummy = *(USB_EndpointFIFOPos[USB_SelectedEndpoint]++);
 826                         }
 827
 828                 /* External Variables: */
 829                         /** Global indicating the maximum packet size of the default control endpoint located at address
 830                          *  0 in the device. This value is set to the value indicated in the device descriptor in the user
 831                          *  project once the USB interface is initialized into device mode.
 832                          *
 833                          *  If space is an issue, it is possible to fix this to a static value by defining the control
 834                          *  endpoint size in the \c FIXED_CONTROL_ENDPOINT_SIZE token passed to the compiler in the makefile
 835                          *  via the -D switch. When a fixed control endpoint size is used, the size is no longer dynamically
 836                          *  read from the descriptors at runtime and instead fixed to the given value. When used, it is
 837                          *  important that the descriptor control endpoint size value matches the size given as the
 838                          *  \c FIXED_CONTROL_ENDPOINT_SIZE token - it is recommended that the \c FIXED_CONTROL_ENDPOINT_SIZE token
 839                          *  be used in the device descriptors to ensure this.
 840                          *
 841                          *  \note This variable should be treated as read-only in the user application, and never manually
 842                          *        changed in value.
 843                          */
 844                         #if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
 845                                 extern uint8_t USB_Device_ControlEndpointSize;
 846                         #else
 847                                 #define USB_Device_ControlEndpointSize FIXED_CONTROL_ENDPOINT_SIZE
 848                         #endif
 849
 850                 /* Function Prototypes: */
 851                         /** Completes the status stage of a control transfer on a CONTROL type endpoint automatically,
 852                          *  with respect to the data direction. This is a convenience function which can be used to
 853                          *  simplify user control request handling.
 854                          */
 855                         void Endpoint_ClearStatusStage(void);
 856
 857                         /** Spin-loops until the currently selected non-control endpoint is ready for the next packet of data
 858                          *  to be read or written to it.
 859                          *
 860                          *  \note This routine should not be called on CONTROL type endpoints.
 861                          *
 862                          *  \ingroup Group_EndpointRW_UC3
 863                          *
 864                          *  \return A value from the \ref Endpoint_WaitUntilReady_ErrorCodes_t enum.
 865                          */
 866                         uint8_t Endpoint_WaitUntilReady(void);
 867
 868         /* Disable C linkage for C++ Compilers: */
 869                 #if defined(__cplusplus)
 870                         }
 871                 #endif
 872
 873 #endif
 874
 875 /** @} */
 876