endpoint.h

LUFA (Lightweight USB Framework for AVRs) is my first foray into the world of USB. Originally based

/*
             LUFA Library
     Copyright (C) Dean Camera, 2009.
              
  dean [at] fourwalledcubicle [dot] com
      www.fourwalledcubicle.com
*/

/*
  Copyright 2009  Dean Camera (dean [at] fourwalledcubicle [dot] com)

  Permission to use, copy, modify, and distribute this software
  and its documentation for any purpose and without fee is hereby
  granted, provided that the above copyright notice appear in all
  copies and that both that the copyright notice and this
  permission notice and warranty disclaimer appear in supporting
  documentation, and that the name of the author not be used in
  advertising or publicity pertaining to distribution of the
  software without specific, written prior permission.

  The author disclaim all warranties with regard to this
  software, including all implied warranties of merchantability
  and fitness.  In no event shall the author be liable for any
  special, indirect or consequential damages or any damages
  whatsoever resulting from loss of use, data or profits, whether
  in an action of contract, negligence or other tortious action,
  arising out of or in connection with the use or performance of
  this software.
*/

/** \ingroup Group_USB
 *  @defgroup Group_EndpointManagement Endpoint Management
 *
 *  Functions, macros and enums related to endpoint management when in USB Device mode. This
 *  module contains the endpoint management macros, as well as endpoint interrupt and data
 *  send/recieve functions for various data types.
 *
 *  @{
 */

/** @defgroup Group_EndpointRW Endpoint Data Reading and Writing
 *
 *  Functions, macros, variables, enums and types related to data reading and writing from and to endpoints.
 */
 
/** @defgroup Group_EndpointPacketManagement Endpoint Packet Management
 *
 *  Functions, macros, variables, enums and types related to packet management of endpoints.
 */

#ifndef __ENDPOINT_H__
#define __ENDPOINT_H__

	/* Includes: */
		#include <avr/io.h>
		#include <stdbool.h>

		#include "../../../Common/Common.h"
		#include "../HighLevel/USBTask.h"

		#if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
			#include "../HighLevel/StreamCallbacks.h"
		#endif
		
	/* Enable C linkage for C++ Compilers: */
		#if defined(__cplusplus)
			extern "C" {
		#endif

	/* Public Interface - May be used in end-application: */
		/* Macros: */
			/** Endpoint data direction mask for \ref Endpoint_ConfigureEndpoint(). This indicates that the endpoint
			 *  should be initialized in the OUT direction - i.e. data flows from host to device.
			 */
			#define ENDPOINT_DIR_OUT                      (0 << EPDIR)

			/** Endpoint data direction mask for \ref Endpoint_ConfigureEndpoint(). This indicates that the endpoint
			 *  should be initialized in the IN direction - i.e. data flows from device to host.
			 */
			#define ENDPOINT_DIR_IN                       (1 << EPDIR)

			/** Mask for the bank mode selection for the \ref Endpoint_ConfigureEndpoint() macro. This indicates
			 *  that the endpoint should have one single bank, which requires less USB FIFO memory but results
			 *  in slower transfers as only one USB device (the AVR or the host) can access the endpoint's
			 *  bank at the one time.
			 */
			#define ENDPOINT_BANK_SINGLE                  (0 << EPBK0)

			/** Mask for the bank mode selection for the \ref Endpoint_ConfigureEndpoint() macro. This indicates
			 *  that the endpoint should have two banks, which requires more USB FIFO memory but results
			 *  in faster transfers as one USB device (the AVR or the host) can access one bank while the other
			 *  accesses the second bank.
			 */
			#define ENDPOINT_BANK_DOUBLE                  (1 << EPBK0)
			
			/** Endpoint address for the default control endpoint, which always resides in address 0. This is
			 *  defined for convenience to give more readable code when used with the endpoint macros.
			 */
			#define ENDPOINT_CONTROLEP                    0

			#if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
				/** Default size of the default control endpoint's bank, until altered by the Endpoint0Size value 
				 *  in the device descriptor. Not available if the FIXED_CONTROL_ENDPOINT_SIZE token is defined.
				 */
				#define ENDPOINT_CONTROLEP_DEFAULT_SIZE   8
			#endif
			
			/** Endpoint number mask, for masking against endpoint addresses to retrieve the endpoint's
			 *  numerical address in the device.
			 */
			#define ENDPOINT_EPNUM_MASK                   0x03

			/** Endpoint bank size mask, for masking against endpoint addresses to retrieve the endpoint's
			 *  bank size in the device.
			 */
			#define ENDPOINT_EPSIZE_MASK                  0x7FF
			
			/** Maximum size in bytes of a given endpoint.
			 *
			 *  \param n  Endpoint number, a value between 0 and (ENDPOINT_TOTAL_ENDPOINTS - 1)
			 */				
			#define ENDPOINT_MAX_SIZE(n)                  _ENDPOINT_GET_MAXSIZE(n)

			/** Indicates if the given endpoint supports double banking.
			 *
			 *  \param n  Endpoint number, a value between 0 and (ENDPOINT_TOTAL_ENDPOINTS - 1)
			 */				
			#define ENDPOINT_DOUBLEBANK_SUPPORTED(n)      _ENDPOINT_GET_DOUBLEBANK(n)

			#if !defined(CONTROL_ONLY_DEVICE)
				#if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER) || defined(__DOXYGEN__)
					/** Total number of endpoints (including the default control endpoint at address 0) which may
					 *  be used in the device. Different USB AVR models support different amounts of endpoints,
					 *  this value reflects the maximum number of endpoints for the currently selected AVR model.
					 */
					#define ENDPOINT_TOTAL_ENDPOINTS          7
				#else
					#define ENDPOINT_TOTAL_ENDPOINTS          5			
				#endif
			#else
				#define ENDPOINT_TOTAL_ENDPOINTS              1
			#endif

			/** Interrupt definition for the endpoint SETUP interrupt (for CONTROL type endpoints). Should be
			 *  used with the USB_INT_* macros located in USBInterrupt.h.
			 *
			 *  This interrupt will fire if enabled on a CONTROL type endpoint if a new control packet is
			 *  received from the host.
			 *
			 *  \note This interrupt must be enabled and cleared on *each* endpoint which requires it (after the
			 *        endpoint is selected), and will fire the common endpoint interrupt vector.
			 *
			 *  \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
			 */
			#define ENDPOINT_INT_SETUP                    UEIENX, (1 << RXSTPE), UEINTX, (1 << RXSTPI)

			/** Interrupt definition for the endpoint IN interrupt (for INTERRUPT type endpoints). Should be
			 *  used with the USB_INT_* macros located in USBInterrupt.h.
			 *
			 *  This interrupt will fire if enabled on an INTERRUPT type endpoint if a the endpoint interrupt
			 *  period has elapsed and the endpoint is ready for a new packet to be written to its FIFO buffer
			 *  (if required).
			 *
			 *  \note This interrupt must be enabled and cleared on *each* endpoint which requires it (after the
			 *        endpoint is selected), and will fire the common endpoint interrupt vector.
			 *
			 *  \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
			 */
			#define ENDPOINT_INT_IN                       UEIENX, (1 << TXINE) , UEINTX, (1 << TXINI)

			/** Interrupt definition for the endpoint OUT interrupt (for INTERRUPT type endpoints). Should be
			 *  used with the USB_INT_* macros located in USBInterrupt.h.
			 *
			 *  This interrupt will fire if enabled on an INTERRUPT type endpoint if a the endpoint interrupt
			 *  period has elapsed and the endpoint is ready for a packet from the host to be read from its
			 *  FIFO buffer (if received).
			 *
			 *  \note This interrupt must be enabled and cleared on *each* endpoint which requires it (after the
			 *        endpoint is selected), and will fire the common endpoint interrupt vector.
			 *
			 *  \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
			 */
			#define ENDPOINT_INT_OUT                      UEIENX, (1 << RXOUTE), UEINTX, (1 << RXOUTI)
			
		/* Pseudo-Function Macros: */
			#if defined(__DOXYGEN__)
				/** Indicates the number of bytes currently stored in the current endpoint's selected bank.
				 *
				 *  \note The return width of this function may differ, depending on the maximum endpoint bank size
				 *        of the selected AVR model.
				 *
				 *  \ingroup Group_EndpointRW
				 *
				 *  \return Total number of bytes in the currently selected Endpoint's FIFO buffer
				 */
				static inline uint16_t Endpoint_BytesInEndpoint(void);
			
				/** Get the endpoint address of the currently selected endpoint. This is typically used to save
				 *  the currently selected endpoint number so that it can be restored after another endpoint has
				 *  been manipulated.
				 *
				 *  \return Index of the currently selected endpoint
				 */
				static inline uint8_t Endpoint_GetCurrentEndpoint(void);
				
				/** Selects the given endpoint number. If the address from the device descriptors is used, the
				 *  value should be masked with the \ref ENDPOINT_EPNUM_MASK constant to extract only the endpoint
				 *  number (and discarding the endpoint direction bit).
				 *
				 *  Any endpoint operations which do not require the endpoint number to be indicated will operate on
				 *  the currently selected endpoint.
				 *
				 *  \param EndpointNumber Endpoint number to select
				 */
				static inline void Endpoint_SelectEndpoint(uint8_t EndpointNumber);
				
				/** Resets the endpoint bank FIFO. This clears all the endpoint banks and resets the USB controller's
				 *  In and Out pointers to the bank's contents.
				 *
				 *  \param EndpointNumber Endpoint number whose FIFO buffers are to be reset
				 */
				static inline void Endpoint_ResetFIFO(uint8_t EndpointNumber);
				
				/** Enables the currently selected endpoint so that data can be sent and received through it to
				 *  and from a host.
				 *
				 *  \note Endpoints must first be configured properly via \ref Endpoint_ConfigureEndpoint().
				 */
				static inline void Endpoint_EnableEndpoint(void);

				/** Disables the currently selected endpoint so that data cannot be sent and received through it
				 *  to and from a host.
				 */
				static inline void Endpoint_DisableEndpoint(void);
				
				/** Determines if the currently selected endpoint is enabled, but not necessarily configured.
				 *
				 * \return Boolean True if the currently selected endpoint is enabled, false otherwise
				 */
				static inline bool Endpoint_IsEnabled(void);
				
				/** Determines if the currently selected endpoint may be read from (if data is waiting in the endpoint
				 *  bank and the endpoint is an OUT direction, or if the bank is not yet full if the endpoint is an IN
				 *  direction). This function will return false if an error has occurred in the endpoint, if the endpoint
				 *  is an OUT direction and no packet (or an empty packet) has been received, or if the endpoint is an IN
				 *  direction and the endpoint bank is full.
				 *
				 *  \ingroup Group_EndpointPacketManagement
				 *
				 *  \return Boolean true if the currently selected endpoint may be read from or written to, depending on its direction
				 */
				static inline bool Endpoint_IsReadWriteAllowed(void);
				
				/** Determines if the currently selected endpoint is configured.
				 *
				 *  \return Boolean true if the currently selected endpoint has been configured, false otherwise
				 */
				static inline bool Endpoint_IsConfigured(void);
				
				/** Returns a mask indicating which INTERRUPT type endpoints have interrupted - i.e. their