pipe.h

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

				/** Returns a mask indicating which pipe's interrupt periods have elapsed, indicating that the pipe should
				 *  be serviced.
				 *
				 *  \return Mask whose bits indicate which pipes have interrupted
				 */
				static inline uint8_t Pipe_GetPipeInterrupts(void);
				
				/** Clears the interrupt flag for the specified pipe number.
				 *
				 *  \param PipeNumber  Index of the pipe whose interrupt flag is to be cleared
				 */
				static inline void Pipe_ClearPipeInterrupt(uint8_t PipeNumber);
				
				/** Determines if the specified pipe number has interrupted (valid only for INTERRUPT type
				 *  pipes).
				 *
				 *  \param PipeNumber  Index of the pipe whose interrupt flag should be tested
				 *
				 *  \return Boolean true if the specified pipe has interrupted, false otherwise
				 */
				static inline bool Pipe_HasPipeInterrupted(uint8_t PipeNumber);
				
				/** Unfreezes the selected pipe, allowing it to communicate with an attached device. */
				static inline void Pipe_Unfreeze(void);
				
				/** Freezes the selected pipe, preventing it from communicating with an attached device. */
				static inline void Pipe_Freeze(void);

				/** Clears the master pipe error flag. */
				static inline void Pipe_ClearError(void);
				
				/** Determines if the master pipe error flag is set for the currently selected pipe, indicating that
				 *  some sort of hardware error has occurred on the pipe.
				 *
				 *  \see \ref Pipe_GetErrorFlags() macro for information on retrieving the exact error flag.
				 *
				 *  \return Boolean true if an error has occurred on the selected pipe, false otherwise
				 */
				static inline bool Pipe_IsError(void);
				
				/** Clears all the currently selected pipe's hardware error flags, but does not clear the master error
				 *  flag for the pipe.
				 */
				static inline void Pipe_ClearErrorFlags(void);
				
				/** Gets a mask of the hardware error flags which have occurred on the currently selected pipe. This
				 *  value can then be masked against the PIPE_ERRORFLAG_* masks to determine what error has occurred.
				 *
				 *  \return  Mask comprising of PIPE_ERRORFLAG_* bits indicating what error has occurred on the selected pipe
				 */
				static inline uint8_t Pipe_GetErrorFlags(void);
				
				/** Determines if the currently selected pipe may be read from (if data is waiting in the pipe
				 *  bank and the pipe is an IN direction, or if the bank is not yet full if the pipe is an OUT
				 *  direction). This function will return false if an error has occurred in the pipe, or if the pipe
				 *  is an IN direction and no packet (or an empty packet) has been received, or if the pipe is an OUT
				 *  direction and the pipe bank is full.
				 *
				 *  \note This function is not valid on CONTROL type pipes.
				 *
				 *  \ingroup Group_PipePacketManagement
				 *  
				 *  \return Boolean true if the currently selected pipe may be read from or written to, depending on its direction
				 */
				static inline bool Pipe_IsReadWriteAllowed(void);
				
				/** Determines if an IN request has been received on the currently selected pipe.
				 *
				 *  \ingroup Group_PipePacketManagement
				 *
				 *  \return Boolean true if the current pipe has received an IN packet, false otherwise.
				 */
				static inline bool Pipe_IsINReceived(void);
				
				/** Determines if the currently selected pipe is ready to send an OUT request.
				 *
				 *  \ingroup Group_PipePacketManagement
				 *
				 *  \return Boolean true if the current pipe is ready for an OUT packet, false otherwise.
				 */
				static inline bool Pipe_IsOUTReady(void);

				/** Determines if no SETUP request is currently being sent to the attached device on the selected
				 *  CONTROL type pipe.
				 *
				 *  \ingroup Group_PipePacketManagement
				 *
				 *  \return Boolean true if the current pipe is ready for a SETUP packet, false otherwise.
				 */
				static inline bool Pipe_IsSETUPSent(void);
				
				/** Sends the currently selected CONTROL type pipe's contents to the device as a SETUP packet.
				 *
				 *  \ingroup Group_PipePacketManagement		
				 */
				static inline void Pipe_ClearSETUP(void);

				/** Acknowledges the reception of a setup IN request from the attached device on the currently selected
				 *  pipe, freeing the bank ready for the next packet.
				 *
				 *  \ingroup Group_PipePacketManagement
				 */
				static inline void Pipe_ClearIN(void);

				/** Sends the currently selected pipe's contents to the device as an OUT packet on the selected pipe, freeing
				 *  the bank ready for the next packet.
				 *
				 *  \ingroup Group_PipePacketManagement
				 */
				static inline void Pipe_ClearOUT(void);

				/** Determines if the device sent a NAK (Negative Acknowledge) in response to the last sent packet on
				 *  the currently selected pipe. This occurs when the host sends a packet to the device, but the device
				 *  is not currently ready to handle the packet (i.e. its endpoint banks are full). Once a NAK has been
				 *  received, it must be cleared using \ref Pipe_ClearNAKReceived() before the previous (or any other) packet
				 *  can be re-sent.
				 *
				 *  \ingroup Group_PipePacketManagement
				 *
				 *  \return Boolean true if an NAK has been received on the current pipe, false otherwise
				 */
				static inline bool Pipe_IsNAKReceived(void);

				/** Clears the NAK condition on the currently selected pipe.
				 *
				 *  \ingroup Group_PipePacketManagement
				 *
				 *  \see \ref Pipe_IsNAKReceived() for more details.
				 */
				static inline void Pipe_ClearNAKReceived(void);
				 
				/** Determines if the currently selected pipe has had the STALL condition set by the attached device.
				 *
				 *  \ingroup Group_PipePacketManagement
				 *
				 *  \return Boolean true if the current pipe has been stalled by the attached device, false otherwise
				*/
				static inline bool Pipe_IsStalled(void);
				
				/** Clears the STALL condition detection flag on the currently selected pipe, but does not clear the
				 *  STALL condition itself (this must be done via a ClearFeature control request to the device).
				 *
				 *  \ingroup Group_PipePacketManagement
				 */
				static inline void Pipe_ClearStall(void);
			#else
				#define Pipe_BytesInPipe()             UPBCX

				#define Pipe_GetCurrentPipe()          (UPNUM & PIPE_PIPENUM_MASK)

				#define Pipe_SelectPipe(pipenum)       MACROS{ UPNUM = pipenum; }MACROE
				
				#define Pipe_ResetPipe(pipenum)        MACROS{ UPRST = (1 << pipenum); UPRST = 0; }MACROE

				#define Pipe_EnablePipe()              MACROS{ UPCONX |= (1 << PEN); }MACROE

				#define Pipe_DisablePipe()             MACROS{ UPCONX &= ~(1 << PEN); }MACROE

				#define Pipe_IsEnabled()               ((UPCONX & (1 << PEN)) ? true : false)

				#define Pipe_GetPipeToken()            (UPCFG0X & PIPE_TOKEN_MASK)

				#define Pipe_SetToken(token)           MACROS{ UPCFG0X = ((UPCFG0X & ~PIPE_TOKEN_MASK) | token); }MACROE
				
				#define Pipe_SetInfiniteINRequests()   MACROS{ UPCONX |= (1 << INMODE); }MACROE

				#define Pipe_SetFiniteINRequests(n)    MACROS{ UPCONX &= ~(1 << INMODE); UPINRQX = n; }MACROE

				#define Pipe_IsConfigured()            ((UPSTAX  & (1 << CFGOK)) ? true : false)

				#define Pipe_SetInterruptPeriod(ms)    MACROS{ UPCFG2X = ms; }MACROE

				#define Pipe_GetPipeInterrupts()       UPINT

				#define Pipe_ClearPipeInterrupt(n)     MACROS{ UPINT &= ~(1 << n); }MACROE

				#define Pipe_HasPipeInterrupted(n)     ((UPINT & (1 << n)) ? true : false)

				#define Pipe_Unfreeze()                MACROS{ UPCONX &= ~(1 << PFREEZE); }MACROE

				#define Pipe_Freeze()                  MACROS{ UPCONX |= (1 << PFREEZE); }MACROE

				#define Pipe_ClearError()              MACROS{ UPINTX &= ~(1 << PERRI); }MACROE

				#define Pipe_IsError()                 ((UPINTX & (1 << PERRI)) ? true : false)
				
				#define Pipe_ClearErrorFlags()         MACROS{ UPERRX = 0; }MACROE

				#define Pipe_GetErrorFlags()           UPERRX

				#define Pipe_IsReadWriteAllowed()      ((UPINTX & (1 << RWAL)) ? true : false)

				#define Pipe_IsINReceived()            ((UPINTX & (1 << RXINI)) ? true : false)

				#define Pipe_IsOUTReady()              ((UPINTX & (1 << TXOUTI)) ? true : false)

				#define Pipe_IsSETUPSent()             ((UPINTX & (1 << TXSTPI)) ? true : false)

				#define Pipe_ClearIN()                 MACROS{ uint8_t Temp = UPINTX; UPINTX = (Temp & ~(1 << RXINI)); \
				                                               UPINTX = (Temp & ~(1 << FIFOCON)); }MACROE

				#define Pipe_ClearOUT()                MACROS{ uint8_t Temp = UPINTX; UPINTX = (Temp & ~(1 << TXOUTI)); \
				                                               UPINTX = (Temp & ~(1 << FIFOCON)); }MACROE
				
				#define Pipe_ClearSETUP()              MACROS{ uint8_t Temp = UPINTX; UPINTX = (Temp & ~(1 << TXSTPI)); \
				                                               UPINTX = (Temp & ~(1 << FIFOCON)); }MACROE

				#define Pipe_IsNAKReceived()           ((UPINTX & (1 << NAKEDI)) ? true : false)

				#define Pipe_ClearNAKReceived()        MACROS{ UPINTX &= ~(1 << NAKEDI); }MACROE

				#define Pipe_IsStalled()               ((UPINTX & (1 << RXSTALLI)) ? true : false)

				#define Pipe_ClearStall()              MACROS{ UPINTX &= ~(1 << RXSTALLI); }MACROE
			#endif

		/* Enums: */
			/** Enum for the possible error return codes of the Pipe_WaitUntilReady function
			 *
			 *  \ingroup Group_PipeRW
			 */
			enum Pipe_WaitUntilReady_ErrorCodes_t
			{
				PIPE_READYWAIT_NoError                 = 0, /**< Pipe ready for next packet, no error */
				PIPE_READYWAIT_PipeStalled             = 1,	/**< The device stalled the pipe while waiting. */			
				PIPE_READYWAIT_DeviceDisconnected      = 2,	/**< Device was disconnected from the host while waiting. */
				PIPE_READYWAIT_Timeout                 = 3, /**< The device failed to accept or send the next packet
				                                             *   within the software timeout period set by the
				                                             *   \ref USB_STREAM_TIMEOUT_MS macro.
				                                             */
			};

			/** Enum for the possible error return codes of the Pipe_*_Stream_* functions.
			 *
			 *  \ingroup Group_PipeRW
			 */
			enum Pipe_Stream_RW_ErrorCodes_t
			{
				PIPE_RWSTREAM_NoError            = 0, /**< Command completed successfully, no error. */
				PIPE_RWSTREAM_PipeStalled        = 1, /**< The device stalled the pipe during the transfer. */		
				PIPE_RWSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during
			                                           *   the transfer.
			                                           */		
				PIPE_RWSTREAM_Timeout            = 3, /**< The device failed to accept or send the next packet
				                                       *   within the software timeout period set by the
				                                       *   \ref USB_STREAM_TIMEOUT_MS macro.
				                                       */
				PIPE_RWSTREAM_CallbackAborted    = 4, /**< Indicates that the stream's callback function aborted
			                                           *   the transfer early.
				                                       */
			};

		/* Inline Functions: */
			/** Reads one byte from the currently selected pipe's bank, for OUT direction pipes.
			 *
			 *  \ingroup Group_PipeRW
			 *
			 *  \return Next byte in the currently selected pipe's FIFO buffer
			 */
			static inline uint8_t Pipe_Read_Byte(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
			static inline uint8_t Pipe_Read_Byte(void)
			{
				return UPDATX;
			}

			/** Writes one byte from the currently selected pipe's bank, for IN direction pipes.
			 *
			 *  \ingroup Group_PipeRW
			 *
			 *  \param Byte  Next byte to write into the the currently selected pipe's FIFO buffer
			 */
			static inline void Pipe_Write_Byte(const uint8_t Byte) ATTR_ALWAYS_INLINE;
			static inline void Pipe_Write_Byte(const uint8_t Byte)
			{
				UPDATX = Byte;
			}

			/** Discards one byte from the currently selected pipe's bank, for OUT direction pipes.
			 *
			 *  \ingroup Group_PipeRW
			 */
			static inline void Pipe_Discard_Byte(void) ATTR_ALWAYS_INLINE;
			static inline void Pipe_Discard_Byte(void)
			{
				uint8_t Dummy;
				
				Dummy = UPDATX;
			}
			
			/** Reads two bytes from the currently selected pipe's bank in little endian format, for OUT
			 *  direction pipes.
			 *
			 *  \ingroup Group_PipeRW
			 *
			 *  \return Next word in the currently selected pipe's FIFO buffer
			 */
			static inline uint16_t Pipe_Read_Word_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
			static inline uint16_t Pipe_Read_Word_LE(void)
			{
				uint16_t Data;
				
				Data  = UPDATX;
				Data |= (((uint16_t)UPDATX) << 8);
			
				return Data;
			}

			/** Reads two bytes from the currently selected pipe's bank in big endian format, for OUT
			 *  direction pipes.
			 *
			 *  \ingroup Group_PipeRW
			 *
			 *  \return Next word in the currently selected pipe's FIFO buffer
			 */
			static inline uint16_t Pipe_Read_Word_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
			static inline uint16_t Pipe_Read_Word_BE(void)
			{
				uint16_t Data;
				
				Data  = (((uint16_t)UPDATX) << 8);
				Data |= UPDATX;
			
				return Data;
			}
			
			/** Writes two bytes to the currently selected pipe's bank in little endian format, for IN
			 *  direction pipes.
			 *
			 *  \ingroup Group_PipeRW
			 *
			 *  \param Word  Next word to write to the currently selected pipe's FIFO buffer
			 */