tmk_core/protocol/lufa/LUFA-git/LUFA/Drivers/USB/Core/UC3/Endpoint_UC3.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2014.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2014  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 disclaims 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_HSB_ADDRESS_SPACE_SIZE            (64 * 1024UL)
  94
  95                 /* Inline Functions: */
  96                         static inline uint32_t Endpoint_BytesToEPSizeMask(const uint16_t Bytes) ATTR_WARN_UNUSED_RESULT ATTR_CONST
  97                                                                                                 ATTR_ALWAYS_INLINE;
  98                         static inline uint32_t Endpoint_BytesToEPSizeMask(const uint16_t Bytes)
  99                         {
 100                                 uint8_t  MaskVal    = 0;
 101                                 uint16_t CheckBytes = 8;
 102
 103                                 while (CheckBytes < Bytes)
 104                                 {
 105                                         MaskVal++;
 106                                         CheckBytes <<= 1;
 107                                 }
 108
 109                                 return (MaskVal << AVR32_USBB_EPSIZE_OFFSET);
 110                         }
 111
 112                 /* Function Prototypes: */
 113                         void Endpoint_ClearEndpoints(void);
 114                         bool Endpoint_ConfigureEndpoint_Prv(const uint8_t Number,
 115                                                             const uint32_t UECFGXData);
 116
 117                 /* External Variables: */
 118                         extern volatile uint32_t USB_Endpoint_SelectedEndpoint;
 119                         extern volatile uint8_t* USB_Endpoint_FIFOPos[];
 120         #endif
 121
 122         /* Public Interface - May be used in end-application: */
 123                 /* Macros: */
 124                         #if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
 125                                 /** Default size of the default control endpoint's bank, until altered by the control endpoint bank size
 126                                  *  value in the device descriptor. Not available if the \c FIXED_CONTROL_ENDPOINT_SIZE token is defined.
 127                                  */
 128                                 #define ENDPOINT_CONTROLEP_DEFAULT_SIZE     8
 129                         #endif
 130
 131                         #if !defined(CONTROL_ONLY_DEVICE) || defined(__DOXYGEN__)
 132                                 #if defined(USB_SERIES_UC3A3_AVR32) || defined(USB_SERIES_UC3A4_AVR32)
 133                                         #define ENDPOINT_TOTAL_ENDPOINTS        8
 134                                 #else
 135                                         /** Total number of endpoints (including the default control endpoint at address 0) which may
 136                                          *  be used in the device. Different AVR models support different amounts of endpoints,
 137                                          *  this value reflects the maximum number of endpoints for the currently selected AVR model.
 138                                          */
 139                                         #define ENDPOINT_TOTAL_ENDPOINTS        7
 140                                 #endif
 141                         #else
 142                                 #define ENDPOINT_TOTAL_ENDPOINTS            1
 143                         #endif
 144
 145                 /* Enums: */
 146                         /** Enum for the possible error return codes of the \ref Endpoint_WaitUntilReady() function.
 147                          *
 148                          *  \ingroup Group_EndpointRW_UC3
 149                          */
 150                         enum Endpoint_WaitUntilReady_ErrorCodes_t
 151                         {
 152                                 ENDPOINT_READYWAIT_NoError                 = 0, /**< Endpoint is ready for next packet, no error. */
 153                                 ENDPOINT_READYWAIT_EndpointStalled         = 1, /**< The endpoint was stalled during the stream
 154                                                                                  *   transfer by the host or device.
 155                                                                                  */
 156                                 ENDPOINT_READYWAIT_DeviceDisconnected      = 2, /**< Device was disconnected from the host while
 157                                                                                  *   waiting for the endpoint to become ready.
 158                                                                                  */
 159                                 ENDPOINT_READYWAIT_BusSuspended            = 3, /**< The USB bus has been suspended by the host and
 160                                                                                  *   no USB endpoint traffic can occur until the bus
 161                                                                                  *   has resumed.
 162                                                                                  */
 163                                 ENDPOINT_READYWAIT_Timeout                 = 4, /**< The host failed to accept or send the next packet
 164                                                                                  *   within the software timeout period set by the
 165                                                                                  *   \ref USB_STREAM_TIMEOUT_MS macro.
 166                                                                                  */
 167                         };
 168
 169                 /* Inline Functions: */
 170                         /** Configures the specified endpoint address with the given endpoint type, bank size and number of hardware
 171                          *  banks. Once configured, the endpoint may be read from or written to, depending on its direction.
 172                          *
 173                          *  \param[in] Address    Endpoint address to configure.
 174                          *
 175                          *  \param[in] Type       Type of endpoint to configure, a \c EP_TYPE_* mask. Not all endpoint types
 176                          *                        are available on Low Speed USB devices - refer to the USB 2.0 specification.
 177                          *
 178                          *  \param[in] Size       Size of the endpoint's bank, where packets are stored before they are transmitted
 179                          *                        to the USB host, or after they have been received from the USB host (depending on
 180                          *                        the endpoint's data direction). The bank size must indicate the maximum packet size
 181                          *                        that the endpoint can handle.
 182                          *
 183                          *  \param[in] Banks      Number of hardware banks to use for the endpoint being configured.
 184                          *
 185                          *  \attention When the \c ORDERED_EP_CONFIG compile time option is used, Endpoints <b>must</b> be configured in
 186                          *             ascending order, or bank corruption will occur.
 187                          *
 188                          *  \note Different endpoints may have different maximum packet sizes based on the endpoint's index - refer to
 189                          *        the chosen microcontroller model's datasheet to determine the maximum bank size for each endpoint.
 190                          *        \n\n
 191                          *
 192                          *  \note The default control endpoint should not be manually configured by the user application, as
 193                          *        it is automatically configured by the library internally.
 194                          *        \n\n
 195                          *
 196                          *  \note This routine will automatically select the specified endpoint upon success. Upon failure, the endpoint
 197                          *        which failed to reconfigure correctly will be selected.
 198                          *
 199                          *  \return Boolean \c true if the configuration succeeded, \c false otherwise.
 200                          */
 201                         static inline bool Endpoint_ConfigureEndpoint(const uint8_t Address,
 202                                                                       const uint8_t Type,
 203                                                                       const uint16_t Size,
 204                                                                       const uint8_t Banks) ATTR_ALWAYS_INLINE;
 205                         static inline bool Endpoint_ConfigureEndpoint(const uint8_t Address,
 206                                                                       const uint8_t Type,
 207                                                                       const uint16_t Size,
 208                                                                       const uint8_t Banks)
 209                         {
 210                                 uint8_t Number = (Address & ENDPOINT_EPNUM_MASK);
 211
 212                                 if (Number >= ENDPOINT_TOTAL_ENDPOINTS)
 213                                   return false;
 214
 215                                 return Endpoint_ConfigureEndpoint_Prv(Number,
 216                                                                       (AVR32_USBB_ALLOC_MASK |
 217                                                                        ((uint32_t)Type << AVR32_USBB_EPTYPE_OFFSET) |
 218                                                                        ((Address & ENDPOINT_DIR_IN) ? AVR32_USBB_UECFG0_EPDIR_MASK : 0) |
 219                                                                        ((Banks > 1) ? AVR32_USBB_UECFG0_EPBK_SINGLE : AVR32_USBB_UECFG0_EPBK_DOUBLE) |
 220                                                                        Endpoint_BytesToEPSizeMask(Size)));
 221                         }
 222
 223                         /** Indicates the number of bytes currently stored in the current endpoint's selected bank.
 224                          *
 225                          *  \ingroup Group_EndpointRW_UC3
 226                          *
 227                          *  \return Total number of bytes in the currently selected Endpoint's FIFO buffer.
 228                          */
 229                         static inline uint16_t Endpoint_BytesInEndpoint(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 230                         static inline uint16_t Endpoint_BytesInEndpoint(void)
 231                         {
 232                                 return (&AVR32_USBB.UESTA0)[USB_Endpoint_SelectedEndpoint].byct;
 233                         }
 234
 235                         /** Determines the currently selected endpoint's direction.
 236                          *
 237                          *  \return The currently selected endpoint's direction, as a \c ENDPOINT_DIR_* mask.
 238                          */
 239                         static inline uint32_t Endpoint_GetEndpointDirection(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 240                         static inline uint32_t Endpoint_GetEndpointDirection(void)
 241                         {
 242                                 return ((&AVR32_USBB.UECFG0)[USB_Endpoint_SelectedEndpoint].epdir ? ENDPOINT_DIR_IN : ENDPOINT_DIR_OUT);
 243                         }
 244
 245                         /** Get the endpoint address of the currently selected endpoint. This is typically used to save
 246                          *  the currently selected endpoint so that it can be restored after another endpoint has been
 247                          *  manipulated.
 248                          *
 249                          *  \return Index of the currently selected endpoint.
 250                          */
 251                         static inline uint8_t Endpoint_GetCurrentEndpoint(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 252                         static inline uint8_t Endpoint_GetCurrentEndpoint(void)
 253                         {
 254                                 return (USB_Endpoint_SelectedEndpoint | Endpoint_GetEndpointDirection());
 255                         }
 256
 257                         /** Selects the given endpoint address.
 258                          *
 259                          *  Any endpoint operations which do not require the endpoint address to be indicated will operate on
 260                          *  the currently selected endpoint.
 261                          *
 262                          *  \param[in] Address  Endpoint address to select.
 263                          */
 264                         static inline void Endpoint_SelectEndpoint(const uint8_t Address) ATTR_ALWAYS_INLINE;
 265                         static inline void Endpoint_SelectEndpoint(const uint8_t Address)
 266                         {
 267                                 USB_Endpoint_SelectedEndpoint = (Address & ENDPOINT_EPNUM_MASK);
 268                         }
 269
 270                         /** Resets the endpoint bank FIFO. This clears all the endpoint banks and resets the USB controller's
 271                          *  data In and Out pointers to the bank's contents.
 272                          *
 273                          *  \param[in] Address  Endpoint number whose FIFO buffers are to be reset.
 274                          */
 275                         static inline void Endpoint_ResetEndpoint(const uint8_t Address) ATTR_ALWAYS_INLINE;
 276                         static inline void Endpoint_ResetEndpoint(const uint8_t Address)
 277                         {
 278                                 uint32_t EndpointNumber = (Address & ENDPOINT_EPNUM_MASK);
 279
 280                                 AVR32_USBB.uerst |=  (AVR32_USBB_EPRST0_MASK << EndpointNumber);
 281                                 AVR32_USBB.uerst &= ~(AVR32_USBB_EPRST0_MASK << EndpointNumber);
 282                                 USB_Endpoint_FIFOPos[EndpointNumber] = &AVR32_USBB_SLAVE[EndpointNumber * ENDPOINT_HSB_ADDRESS_SPACE_SIZE];
 283                         }
 284
 285                         /** Enables the currently selected endpoint so that data can be sent and received through it to
 286                          *  and from a host.
 287                          *
 288                          *  \note Endpoints must first be configured properly via \ref Endpoint_ConfigureEndpoint().
 289                          */
 290                         static inline void Endpoint_EnableEndpoint(void) ATTR_ALWAYS_INLINE;
 291                         static inline void Endpoint_EnableEndpoint(void)
 292                         {
 293                                 AVR32_USBB.uerst |=  (AVR32_USBB_EPEN0_MASK << USB_Endpoint_SelectedEndpoint);
 294                         }
 295
 296                         /** Disables the currently selected endpoint so that data cannot be sent and received through it
 297                          *  to and from a host.
 298                          */
 299                         static inline void Endpoint_DisableEndpoint(void) ATTR_ALWAYS_INLINE;
 300                         static inline void Endpoint_DisableEndpoint(void)
 301                         {
 302                                 AVR32_USBB.uerst &= ~(AVR32_USBB_EPEN0_MASK << USB_Endpoint_SelectedEndpoint);
 303                         }
 304
 305                         /** Determines if the currently selected endpoint is enabled, but not necessarily configured.
 306                          *
 307                          * \return Boolean \c true if the currently selected endpoint is enabled, \c false otherwise.
 308                          */
 309                         static inline bool Endpoint_IsEnabled(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 310                         static inline bool Endpoint_IsEnabled(void)
 311                         {
 312                                 return ((AVR32_USBB.uerst & (AVR32_USBB_EPEN0_MASK << USB_Endpoint_SelectedEndpoint)) ? true : false);
 313                         }
 314
 315                         /** Retrieves the number of busy banks in the currently selected endpoint, which have been queued for
 316                          *  transmission via the \ref Endpoint_ClearIN() command, or are awaiting acknowledgement via the
 317                          *  \ref Endpoint_ClearOUT() command.
 318                          *
 319                          *  \ingroup Group_EndpointPacketManagement_UC3
 320                          *
 321                          *  \return Total number of busy banks in the selected endpoint.
 322                          */
 323                         static inline uint8_t Endpoint_GetBusyBanks(void) ATTR_ALWAYS_INLINE ATTR_WARN_UNUSED_RESULT;
 324                         static inline uint8_t Endpoint_GetBusyBanks(void)
 325                         {
 326                                 return (&AVR32_USBB.UESTA0)[USB_Endpoint_SelectedEndpoint].nbusybk;
 327                         }
 328
 329                         /** Aborts all pending IN transactions on the currently selected endpoint, once the bank
 330                          *  has been queued for transmission to the host via \ref Endpoint_ClearIN(). This function
 331                          *  will terminate all queued transactions, resetting the endpoint banks ready for a new
 332                          *  packet.
 333                          *
 334                          *  \ingroup Group_EndpointPacketManagement_UC3
 335                          */
 336                         static inline void Endpoint_AbortPendingIN(void)
 337                         {
 338                                 while (Endpoint_GetBusyBanks() != 0)
 339                                 {
 340                                         (&AVR32_USBB.UECON0SET)[USB_Endpoint_SelectedEndpoint].killbks = true;
 341                                         while ((&AVR32_USBB.UECON0)[USB_Endpoint_SelectedEndpoint].killbk);
 342                                 }
 343                         }
 344
 345                         /** Determines if the currently selected endpoint may be read from (if data is waiting in the endpoint
 346                          *  bank and the endpoint is an OUT direction, or if the bank is not yet full if the endpoint is an IN
 347                          *  direction). This function will return false if an error has occurred in the endpoint, if the endpoint
 348                          *  is an OUT direction and no packet (or an empty packet) has been received, or if the endpoint is an IN
 349                          *  direction and the endpoint bank is full.
 350                          *
 351                          *  \ingroup Group_EndpointPacketManagement_UC3
 352                          *
 353                          *  \return Boolean \c true if the currently selected endpoint may be read from or written to, depending
 354                          *          on its direction.
 355                          */
 356                         static inline bool Endpoint_IsReadWriteAllowed(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 357                         static inline bool Endpoint_IsReadWriteAllowed(void)
 358                         {
 359                                 return (&AVR32_USBB.UESTA0)[USB_Endpoint_SelectedEndpoint].rwall;
 360                         }
 361
 362                         /** Determines if the currently selected endpoint is configured.
 363                          *
 364                          *  \return Boolean \c true if the currently selected endpoint has been configured, \c false otherwise.
 365                          */
 366                         static inline bool Endpoint_IsConfigured(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 367                         static inline bool Endpoint_IsConfigured(void)
 368                         {
 369                                 return (&AVR32_USBB.UESTA0)[USB_Endpoint_SelectedEndpoint].cfgok;
 370                         }
 371
 372                         /** Returns a mask indicating which INTERRUPT type endpoints have interrupted - i.e. their
 373                          *  interrupt duration has elapsed. Which endpoints have interrupted can be determined by
 374                          *  masking the return value against <tt>(1 << <i>{Endpoint Number}</i>)</tt>.
 375                          *
 376                          *  \return Mask whose bits indicate which endpoints have interrupted.
 377                          */
 378                         static inline uint32_t Endpoint_GetEndpointInterrupts(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 379                         static inline uint32_t Endpoint_GetEndpointInterrupts(void)
 380                         {
 381                                 return ((AVR32_USBB.udint & (AVR32_USBB_EP6INT_MASK | AVR32_USBB_EP5INT_MASK |
 382                                                              AVR32_USBB_EP4INT_MASK | AVR32_USBB_EP3INT_MASK |
 383                                                              AVR32_USBB_EP2INT_MASK | AVR32_USBB_EP1INT_MASK |
 384                                                              AVR32_USBB_EP0INT_MASK)) >> AVR32_USBB_EP0INT_OFFSET);
 385                         }
 386
 387                         /** Determines if the specified endpoint number has interrupted (valid only for INTERRUPT type
 388                          *  endpoints).
 389                          *
 390                          *  \param[in] Address  Address of the endpoint whose interrupt flag should be tested.
 391                          *
 392                          *  \return Boolean \c true if the specified endpoint has interrupted, \c false otherwise.
 393                          */
 394                         static inline bool Endpoint_HasEndpointInterrupted(const uint8_t Address) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 395                         static inline bool Endpoint_HasEndpointInterrupted(const uint8_t Address)
 396                         {
 397                                 return ((Endpoint_GetEndpointInterrupts() & (AVR32_USBB_EP0INT_MASK << (Address & ENDPOINT_EPNUM_MASK))) ? true : false);
 398                         }
 399
 400                         /** Determines if the selected IN endpoint is ready for a new packet to be sent to the host.
 401                          *
 402                          *  \ingroup Group_EndpointPacketManagement_UC3
 403                          *
 404                          *  \return Boolean \c true if the current endpoint is ready for an IN packet, \c false otherwise.
 405                          */
 406                         static inline bool Endpoint_IsINReady(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 407                         static inline bool Endpoint_IsINReady(void)
 408                         {
 409                                 return (&AVR32_USBB.UESTA0)[USB_Endpoint_SelectedEndpoint].txini;
 410                         }
 411
 412                         /** Determines if the selected OUT endpoint has received new packet from the host.
 413                          *
 414                          *  \ingroup Group_EndpointPacketManagement_UC3
 415                          *
 416                          *  \return Boolean \c true if current endpoint is has received an OUT packet, \c false otherwise.
 417                          */
 418                         static inline bool Endpoint_IsOUTReceived(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 419                         static inline bool Endpoint_IsOUTReceived(void)
 420                         {
 421                                 return (&AVR32_USBB.UESTA0)[USB_Endpoint_SelectedEndpoint].rxouti;
 422                         }
 423
 424                         /** Determines if the current CONTROL type endpoint has received a SETUP packet.
 425                          *
 426                          *  \ingroup Group_EndpointPacketManagement_UC3
 427                          *
 428                          *  \return Boolean \c true if the selected endpoint has received a SETUP packet, \c false otherwise.
 429                          */
 430                         static inline bool Endpoint_IsSETUPReceived(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 431                         static inline bool Endpoint_IsSETUPReceived(void)
 432                         {
 433                                 return (&AVR32_USBB.UESTA0)[USB_Endpoint_SelectedEndpoint].rxstpi;
 434                         }
 435
 436                         /** Clears a received SETUP packet on the currently selected CONTROL type endpoint, freeing up the
 437                          *  endpoint for the next packet.
 438                          *
 439                          *  \ingroup Group_EndpointPacketManagement_UC3
 440                          *
 441                          *  \note This is not applicable for non CONTROL type endpoints.
 442                          */
 443                         static inline void Endpoint_ClearSETUP(void) ATTR_ALWAYS_INLINE;
 444                         static inline void Endpoint_ClearSETUP(void)
 445                         {
 446                                 (&AVR32_USBB.UESTA0CLR)[USB_Endpoint_SelectedEndpoint].rxstpic = true;
 447                                 USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint] = &AVR32_USBB_SLAVE[USB_Endpoint_SelectedEndpoint * ENDPOINT_HSB_ADDRESS_SPACE_SIZE];
 448                         }
 449
 450                         /** Sends an IN packet to the host on the currently selected endpoint, freeing up the endpoint for the
 451                          *  next packet and switching to the alternative endpoint bank if double banked.
 452                          *
 453                          *  \ingroup Group_EndpointPacketManagement_UC3
 454                          */
 455                         static inline void Endpoint_ClearIN(void) ATTR_ALWAYS_INLINE;
 456                         static inline void Endpoint_ClearIN(void)
 457                         {
 458                                 (&AVR32_USBB.UESTA0CLR)[USB_Endpoint_SelectedEndpoint].txinic   = true;
 459                                 (&AVR32_USBB.UECON0CLR)[USB_Endpoint_SelectedEndpoint].fifoconc = true;
 460                                 USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint] = &AVR32_USBB_SLAVE[USB_Endpoint_SelectedEndpoint * ENDPOINT_HSB_ADDRESS_SPACE_SIZE];
 461                         }
 462
 463                         /** Acknowledges an OUT packet to the host on the currently selected endpoint, freeing up the endpoint
 464                          *  for the next packet and switching to the alternative endpoint bank if double banked.
 465                          *
 466                          *  \ingroup Group_EndpointPacketManagement_UC3
 467                          */
 468                         static inline void Endpoint_ClearOUT(void) ATTR_ALWAYS_INLINE;
 469                         static inline void Endpoint_ClearOUT(void)
 470                         {
 471                                 (&AVR32_USBB.UESTA0CLR)[USB_Endpoint_SelectedEndpoint].rxoutic  = true;
 472                                 (&AVR32_USBB.UECON0CLR)[USB_Endpoint_SelectedEndpoint].fifoconc = true;
 473                                 USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint] = &AVR32_USBB_SLAVE[USB_Endpoint_SelectedEndpoint * ENDPOINT_HSB_ADDRESS_SPACE_SIZE];
 474                         }
 475
 476                         /** Stalls the current endpoint, indicating to the host that a logical problem occurred with the
 477                          *  indicated endpoint and that the current transfer sequence should be aborted. This provides a
 478                          *  way for devices to indicate invalid commands to the host so that the current transfer can be
 479                          *  aborted and the host can begin its own recovery sequence.
 480                          *
 481                          *  The currently selected endpoint remains stalled until either the \ref Endpoint_ClearStall() macro
 482                          *  is called, or the host issues a CLEAR FEATURE request to the device for the currently selected
 483                          *  endpoint.
 484                          *
 485                          *  \ingroup Group_EndpointPacketManagement_UC3
 486                          */
 487                         static inline void Endpoint_StallTransaction(void) ATTR_ALWAYS_INLINE;
 488                         static inline void Endpoint_StallTransaction(void)
 489                         {
 490                                 (&AVR32_USBB.UECON0SET)[USB_Endpoint_SelectedEndpoint].stallrqs = true;
 491                         }
 492
 493                         /** Clears the STALL condition on the currently selected endpoint.
 494                          *
 495                          *  \ingroup Group_EndpointPacketManagement_UC3
 496                          */
 497                         static inline void Endpoint_ClearStall(void) ATTR_ALWAYS_INLINE;
 498                         static inline void Endpoint_ClearStall(void)
 499                         {
 500                                 (&AVR32_USBB.UECON0CLR)[USB_Endpoint_SelectedEndpoint].stallrqc = true;
 501                         }
 502
 503                         /** Determines if the currently selected endpoint is stalled, \c false otherwise.
 504                          *
 505                          *  \ingroup Group_EndpointPacketManagement_UC3
 506                          *
 507                          *  \return Boolean \c true if the currently selected endpoint is stalled, \c false otherwise.
 508                          */
 509                         static inline bool Endpoint_IsStalled(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 510                         static inline bool Endpoint_IsStalled(void)
 511                         {
 512                                 return (&AVR32_USBB.UECON0)[USB_Endpoint_SelectedEndpoint].stallrq;
 513                         }
 514
 515                         /** Resets the data toggle of the currently selected endpoint. */
 516                         static inline void Endpoint_ResetDataToggle(void) ATTR_ALWAYS_INLINE;
 517                         static inline void Endpoint_ResetDataToggle(void)
 518                         {
 519                                 (&AVR32_USBB.UECON0SET)[USB_Endpoint_SelectedEndpoint].rstdts = true;
 520                         }
 521
 522                         /** Sets the direction of the currently selected endpoint.
 523                          *
 524                          *  \param[in] DirectionMask  New endpoint direction, as a \c ENDPOINT_DIR_* mask.
 525                          */
 526                         static inline void Endpoint_SetEndpointDirection(const uint32_t DirectionMask) ATTR_ALWAYS_INLINE;
 527                         static inline void Endpoint_SetEndpointDirection(const uint32_t DirectionMask)
 528                         {
 529                                 (&AVR32_USBB.UECFG0)[USB_Endpoint_SelectedEndpoint].epdir = (DirectionMask == ENDPOINT_DIR_IN);
 530                         }
 531
 532                         /** Reads one byte from the currently selected endpoint's bank, for OUT direction endpoints.
 533                          *
 534                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 535                          *
 536                          *  \return Next byte in the currently selected endpoint's FIFO buffer.
 537                          */
 538                         static inline uint8_t Endpoint_Read_8(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 539                         static inline uint8_t Endpoint_Read_8(void)
 540                         {
 541                                 return *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 542                         }
 543
 544                         /** Writes one byte to the currently selected endpoint's bank, for IN direction endpoints.
 545                          *
 546                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 547                          *
 548                          *  \param[in] Data  Data to write into the the currently selected endpoint's FIFO buffer.
 549                          */
 550                         static inline void Endpoint_Write_8(const uint8_t Data) ATTR_ALWAYS_INLINE;
 551                         static inline void Endpoint_Write_8(const uint8_t Data)
 552                         {
 553                                 *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++) = Data;
 554                         }
 555
 556                         /** Discards one byte from the currently selected endpoint's bank, for OUT direction endpoints.
 557                          *
 558                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 559                          */
 560                         static inline void Endpoint_Discard_8(void) ATTR_ALWAYS_INLINE;
 561                         static inline void Endpoint_Discard_8(void)
 562                         {
 563                                 uint8_t Dummy;
 564
 565                                 Dummy = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 566
 567                                 (void)Dummy;
 568                         }
 569
 570                         /** Reads two bytes from the currently selected endpoint's bank in little endian format, for OUT
 571                          *  direction endpoints.
 572                          *
 573                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 574                          *
 575                          *  \return Next two bytes in the currently selected endpoint's FIFO buffer.
 576                          */
 577                         static inline uint16_t Endpoint_Read_16_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 578                         static inline uint16_t Endpoint_Read_16_LE(void)
 579                         {
 580                                 uint16_t Byte0 = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 581                                 uint16_t Byte1 = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 582
 583                                 return ((Byte1 << 8) | Byte0);
 584                         }
 585
 586                         /** Reads two bytes from the currently selected endpoint's bank in big endian format, for OUT
 587                          *  direction endpoints.
 588                          *
 589                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 590                          *
 591                          *  \return Next two bytes in the currently selected endpoint's FIFO buffer.
 592                          */
 593                         static inline uint16_t Endpoint_Read_16_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 594                         static inline uint16_t Endpoint_Read_16_BE(void)
 595                         {
 596                                 uint16_t Byte0 = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 597                                 uint16_t Byte1 = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 598
 599                                 return ((Byte0 << 8) | Byte1);
 600                         }
 601
 602                         /** Writes two bytes to the currently selected endpoint's bank in little endian format, for IN
 603                          *  direction endpoints.
 604                          *
 605                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 606                          *
 607                          *  \param[in] Data  Data to write to the currently selected endpoint's FIFO buffer.
 608                          */
 609                         static inline void Endpoint_Write_16_LE(const uint16_t Data) ATTR_ALWAYS_INLINE;
 610                         static inline void Endpoint_Write_16_LE(const uint16_t Data)
 611                         {
 612                                 *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++) = (Data & 0xFF);
 613                                 *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++) = (Data >> 8);
 614                         }
 615
 616                         /** Writes two bytes to the currently selected endpoint's bank in big endian format, for IN
 617                          *  direction endpoints.
 618                          *
 619                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 620                          *
 621                          *  \param[in] Data  Data to write to the currently selected endpoint's FIFO buffer.
 622                          */
 623                         static inline void Endpoint_Write_16_BE(const uint16_t Data) ATTR_ALWAYS_INLINE;
 624                         static inline void Endpoint_Write_16_BE(const uint16_t Data)
 625                         {
 626                                 *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++) = (Data >> 8);
 627                                 *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++) = (Data & 0xFF);
 628                         }
 629
 630                         /** Discards two bytes from the currently selected endpoint's bank, for OUT direction endpoints.
 631                          *
 632                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 633                          */
 634                         static inline void Endpoint_Discard_16(void) ATTR_ALWAYS_INLINE;
 635                         static inline void Endpoint_Discard_16(void)
 636                         {
 637                                 uint8_t Dummy;
 638
 639                                 Dummy = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 640                                 Dummy = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 641
 642                                 (void)Dummy;
 643                         }
 644
 645                         /** Reads four bytes from the currently selected endpoint's bank in little endian format, for OUT
 646                          *  direction endpoints.
 647                          *
 648                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 649                          *
 650                          *  \return Next four bytes in the currently selected endpoint's FIFO buffer.
 651                          */
 652                         static inline uint32_t Endpoint_Read_32_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 653                         static inline uint32_t Endpoint_Read_32_LE(void)
 654                         {
 655                                 uint32_t Byte0 = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 656                                 uint32_t Byte1 = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 657                                 uint32_t Byte2 = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 658                                 uint32_t Byte3 = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 659
 660                                 return ((Byte3 << 24) | (Byte2 << 16) | (Byte1 << 8) | Byte0);
 661                         }
 662
 663                         /** Reads four bytes from the currently selected endpoint's bank in big endian format, for OUT
 664                          *  direction endpoints.
 665                          *
 666                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 667                          *
 668                          *  \return Next four bytes in the currently selected endpoint's FIFO buffer.
 669                          */
 670                         static inline uint32_t Endpoint_Read_32_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 671                         static inline uint32_t Endpoint_Read_32_BE(void)
 672                         {
 673                                 uint32_t Byte0 = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 674                                 uint32_t Byte1 = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 675                                 uint32_t Byte2 = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 676                                 uint32_t Byte3 = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 677
 678                                 return ((Byte0 << 24) | (Byte1 << 16) | (Byte2 << 8) | Byte3);
 679                         }
 680
 681                         /** Writes four bytes to the currently selected endpoint's bank in little endian format, for IN
 682                          *  direction endpoints.
 683                          *
 684                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 685                          *
 686                          *  \param[in] Data  Data to write to the currently selected endpoint's FIFO buffer.
 687                          */
 688                         static inline void Endpoint_Write_32_LE(const uint32_t Data) ATTR_ALWAYS_INLINE;
 689                         static inline void Endpoint_Write_32_LE(const uint32_t Data)
 690                         {
 691                                 *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++) = (Data &  0xFF);
 692                                 *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++) = (Data >> 8);
 693                                 *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++) = (Data >> 16);
 694                                 *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++) = (Data >> 24);
 695                         }
 696
 697                         /** Writes four bytes to the currently selected endpoint's bank in big endian format, for IN
 698                          *  direction endpoints.
 699                          *
 700                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 701                          *
 702                          *  \param[in] Data  Data to write to the currently selected endpoint's FIFO buffer.
 703                          */
 704                         static inline void Endpoint_Write_32_BE(const uint32_t Data) ATTR_ALWAYS_INLINE;
 705                         static inline void Endpoint_Write_32_BE(const uint32_t Data)
 706                         {
 707                                 *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++) = (Data >> 24);
 708                                 *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++) = (Data >> 16);
 709                                 *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++) = (Data >> 8);
 710                                 *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++) = (Data &  0xFF);
 711                         }
 712
 713                         /** Discards four bytes from the currently selected endpoint's bank, for OUT direction endpoints.
 714                          *
 715                          *  \ingroup Group_EndpointPrimitiveRW_UC3
 716                          */
 717                         static inline void Endpoint_Discard_32(void) ATTR_ALWAYS_INLINE;
 718                         static inline void Endpoint_Discard_32(void)
 719                         {
 720                                 uint8_t Dummy;
 721
 722                                 Dummy = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 723                                 Dummy = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 724                                 Dummy = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 725                                 Dummy = *(USB_Endpoint_FIFOPos[USB_Endpoint_SelectedEndpoint]++);
 726
 727                                 (void)Dummy;
 728                         }
 729
 730                 /* External Variables: */
 731                         /** Global indicating the maximum packet size of the default control endpoint located at address
 732                          *  0 in the device. This value is set to the value indicated in the device descriptor in the user
 733                          *  project once the USB interface is initialized into device mode.
 734                          *
 735                          *  If space is an issue, it is possible to fix this to a static value by defining the control
 736                          *  endpoint size in the \c FIXED_CONTROL_ENDPOINT_SIZE token passed to the compiler in the makefile
 737                          *  via the -D switch. When a fixed control endpoint size is used, the size is no longer dynamically
 738                          *  read from the descriptors at runtime and instead fixed to the given value. When used, it is
 739                          *  important that the descriptor control endpoint size value matches the size given as the
 740                          *  \c FIXED_CONTROL_ENDPOINT_SIZE token - it is recommended that the \c FIXED_CONTROL_ENDPOINT_SIZE token
 741                          *  be used in the device descriptors to ensure this.
 742                          *
 743                          *  \attention This variable should be treated as read-only in the user application, and never manually
 744                          *             changed in value.
 745                          */
 746                         #if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
 747                                 extern uint8_t USB_Device_ControlEndpointSize;
 748                         #else
 749                                 #define USB_Device_ControlEndpointSize FIXED_CONTROL_ENDPOINT_SIZE
 750                         #endif
 751
 752                 /* Function Prototypes: */
 753                         /** Configures a table of endpoint descriptions, in sequence. This function can be used to configure multiple
 754                          *  endpoints at the same time.
 755                          *
 756                          *  \note Endpoints with a zero address will be ignored, thus this function cannot be used to configure the
 757                          *        control endpoint.
 758                          *
 759                          *  \param[in] Table    Pointer to a table of endpoint descriptions.
 760                          *  \param[in] Entries  Number of entries in the endpoint table to configure.
 761                          *
 762                          *  \return Boolean \c true if all endpoints configured successfully, \c false otherwise.
 763                          */
 764                         bool Endpoint_ConfigureEndpointTable(const USB_Endpoint_Table_t* const Table,
 765                                                              const uint8_t Entries);
 766
 767                         /** Completes the status stage of a control transfer on a CONTROL type endpoint automatically,
 768                          *  with respect to the data direction. This is a convenience function which can be used to
 769                          *  simplify user control request handling.
 770                          *
 771                          *  \note This routine should not be called on non CONTROL type endpoints.
 772                          */
 773                         void Endpoint_ClearStatusStage(void);
 774
 775                         /** Spin-loops until the currently selected non-control endpoint is ready for the next packet of data
 776                          *  to be read or written to it.
 777                          *
 778                          *  \note This routine should not be called on CONTROL type endpoints.
 779                          *
 780                          *  \ingroup Group_EndpointRW_UC3
 781                          *
 782                          *  \return A value from the \ref Endpoint_WaitUntilReady_ErrorCodes_t enum.
 783                          */
 784                         uint8_t Endpoint_WaitUntilReady(void);
 785
 786         /* Disable C linkage for C++ Compilers: */
 787                 #if defined(__cplusplus)
 788                         }
 789                 #endif
 790
 791 #endif
 792
 793 /** @} */
 794