pipe.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_PipeManagement Pipe Management
 *
 *  This module contains functions, macros and enums related to pipe management when in USB Host mode. This
 *  module contains the pipe management macros, as well as pipe interrupt and data send/recieve functions
 *  for various data types.
 *
 *  @{
 */

/** @defgroup Group_PipeRW Pipe Data Reading and Writing
 *
 *  Functions, macros, variables, enums and types related to data reading and writing from and to pipes.
 */
 
/** @defgroup Group_PipePacketManagement Pipe Packet Management
 *
 *  Functions, macros, variables, enums and types related to packet management of pipes.
 */
 
/** @defgroup Group_PipeControlReq Pipe Control Request Management
 *
 *  Module for host mode request processing. This module allows for the transmission of standard, class and
 *  vendor control requests to the default control endpoint of an attached device while in host mode.
 *
 *  \see Chapter 9 of the USB 2.0 specification.
 */ 

#ifndef __PIPE_H__
#define __PIPE_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: */
			/** Mask for \ref Pipe_GetErrorFlags(), indicating that a CRC error occurred in the pipe on the received data. */
			#define PIPE_ERRORFLAG_CRC16            (1 << 4)

			/** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware timeout error occurred in the pipe. */
			#define PIPE_ERRORFLAG_TIMEOUT          (1 << 3)

			/** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware PID error occurred in the pipe. */
			#define PIPE_ERRORFLAG_PID              (1 << 2)

			/** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware data PID error occurred in the pipe. */
			#define PIPE_ERRORFLAG_DATAPID          (1 << 1)

			/** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware data toggle error occurred in the pipe. */
			#define PIPE_ERRORFLAG_DATATGL          (1 << 0)

			/** Token mask for \ref Pipe_ConfigurePipe(). This sets the pipe as a SETUP token (for CONTROL type pipes),
			 *  which will trigger a control request on the attached device when data is written to the pipe.
			 */
			#define PIPE_TOKEN_SETUP                (0 << PTOKEN0)

			/** Token mask for \ref Pipe_ConfigurePipe(). This sets the pipe as a IN token (for non-CONTROL type pipes),
			 *  indicating that the pipe data will flow from device to host.
			 */
			#define PIPE_TOKEN_IN                   (1 << PTOKEN0)

			/** Token mask for \ref Pipe_ConfigurePipe(). This sets the pipe as a IN token (for non-CONTROL type pipes),
			 *  indicating that the pipe data will flow from host to device.
			 */
			#define PIPE_TOKEN_OUT                  (2 << PTOKEN0)

			/** Mask for the bank mode selection for the \ref Pipe_ConfigurePipe() macro. This indicates that the pipe
			 *  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 attached device) can access the pipe's bank at the one time.
			 */
			#define PIPE_BANK_SINGLE                (0 << EPBK0)

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

			/** Default size of the default control pipe's bank, until altered by the Endpoint0Size value 
			 *  in the device descriptor of the attached device.
			 */
			#define PIPE_CONTROLPIPE_DEFAULT_SIZE   64
			
			/** Pipe number mask, for masking against pipe addresses to retrieve the pipe's numerical address
			 *  in the device.
			 */
			#define PIPE_PIPENUM_MASK               0x07

			/** Total number of pipes (including the default control pipe at address 0) which may be used in
			 *  the device. Different USB AVR models support different amounts of pipes, this value reflects
			 *  the maximum number of pipes for the currently selected AVR model.
			 */
			#define PIPE_TOTAL_PIPES                7

			/** Size in bytes of the largest pipe bank size possible in the device. Not all banks on each AVR
			 *  model supports the largest bank size possible on the device; different pipe numbers support
			 *  different maximum bank sizes. This value reflects the largest possible bank of any pipe on the
			 *  currently selected USB AVR model.
			 */
			#define PIPE_MAX_SIZE                   256

			/** Endpoint number mask, for masking against endpoint addresses to retrieve the endpoint's
			 *  numerical address in the attached device.
			 */
			#define PIPE_EPNUM_MASK                 0x07

			/** Endpoint bank size mask, for masking against endpoint addresses to retrieve the endpoint's
			 *  bank size in the attached device.
			 */
			#define PIPE_EPSIZE_MASK                0x7FF

			/** Interrupt definition for the pipe IN interrupt (for INTERRUPT type pipes). Should be used with
			 *  the USB_INT_* macros located in USBInterrupt.h.
			 *
			 *  This interrupt will fire if enabled on an INTERRUPT type pipe if the pipe interrupt period has
			 *  elapsed and the pipe is ready for the next packet from the attached device to be read out from its
			 *  FIFO buffer (if received).
			 *
			 *  \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe
			 *        is selected), and will fire the common pipe interrupt vector.
			 *
			 *  \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
			 */
			#define PIPE_INT_IN                     UPIENX, (1 << RXINE) , UPINTX, (1 << RXINI)

			/** Interrupt definition for the pipe OUT interrupt (for INTERRUPT type pipes). 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 pipe interrupt period
			 *  has elapsed and the pipe is ready for a packet to be written to the pipe's FIFO buffer and sent
			 *  to the attached device (if required).
			 *  
			 *  \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe
			 *        is selected), and will fire the common pipe interrupt vector.
			 *
			 *  \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
			 */
			#define PIPE_INT_OUT                   UPIENX, (1 << TXOUTE), UPINTX, (1 << TXOUTI)

			/** Interrupt definition for the pipe SETUP bank ready interrupt (for CONTROL type pipes). Should be
			 *  used with the USB_INT_* macros located in USBInterrupt.h.
			 *
			 *  This interrupt will fire if enabled on an CONTROL type pipe when the pipe is ready for a new
			 *  control request.
			 *
			 *  \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe
			 *        is selected), and will fire the common pipe interrupt vector.
			 *
			 *  \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
			 */
			#define PIPE_INT_SETUP                 UPIENX, (1 << TXSTPE) , UPINTX, (1 << TXSTPI)

			/** Interrupt definition for the pipe error interrupt. Should be used with the USB_INT_* macros
			 *  located in USBInterrupt.h.
			 *
			 *  This interrupt will fire if enabled on a particular pipe if an error occurs on that pipe, such
			 *  as a CRC mismatch error.
			 *
			 *  \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe
			 *        is selected), and will fire the common pipe interrupt vector.
			 *
			 *  \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
			 *
			 *  \see \ref Pipe_GetErrorFlags() for more information on the pipe errors.
			 */
			#define PIPE_INT_ERROR                 UPIENX, (1 << PERRE), UPINTX, (1 << PERRI)

			/** Interrupt definition for the pipe NAK received interrupt. Should be used with the USB_INT_* macros
			 *  located in USBInterrupt.h.
			 *
			 *  This interrupt will fire if enabled on a particular pipe if an attached device returns a NAK in
			 *  response to a sent packet.
			 *
			 *  \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe
			 *        is selected), and will fire the common pipe interrupt vector.
			 *
			 *  \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
			 *
			 *  \see \ref Pipe_IsNAKReceived() for more information on pipe NAKs.
			 */
			#define PIPE_INT_NAK                   UPIENX, (1 << NAKEDE), UPINTX, (1 << NAKEDI)

			/** Interrupt definition for the pipe STALL received interrupt. Should be used with the USB_INT_* macros
			 *  located in USBInterrupt.h.
			 *
			 *  This interrupt will fire if enabled on a particular pipe if an attached device returns a STALL on the
			 *  currently selected pipe. This will also fire if the pipe is an isochronous pipe and a CRC error occurs.
			 *
			 *  \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe
			 *        is selected), and will fire the common pipe interrupt vector.
			 *
			 *  \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
			 */
			#define PIPE_INT_STALL                 UPIENX, (1 << RXSTALLE), UPINTX, (1 << RXSTALLI)

		/* Pseudo-Function Macros: */
			#if defined(__DOXYGEN__)
				/** Indicates the number of bytes currently stored in the current pipes's selected bank.
				 *
				 *  \note The return width of this function may differ, depending on the maximum pipe bank size
				 *        of the selected AVR model.
				 *
				 *  \ingroup Group_PipeRW
				 *
				 *  \return Total number of bytes in the currently selected Pipe's FIFO buffer
				 */
				static inline uint16_t Pipe_BytesInPipe(void);
				
				/** Returns the pipe address of the currently selected pipe. This is typically used to save the
				 *  currently selected pipe number so that it can be restored after another pipe has been manipulated.
				 *
				 *  \return Index of the currently selected pipe
				 */
				static inline uint8_t Pipe_GetCurrentPipe(void);

				/** Selects the given pipe number. Any pipe operations which do not require the pipe number to be
				 *  indicated will operate on the currently selected pipe.
				 *
				 *  \param PipeNumber  Index of the pipe to select
				 */
				static inline void Pipe_SelectPipe(uint8_t PipeNumber);
				
				/** Resets the desired pipe, including the pipe banks and flags.
				 *
				 *  \param PipeNumber  Index of the pipe to reset
				 */
				static inline void Pipe_ResetPipe(uint8_t PipeNumber);
				
				/** Enables the currently selected pipe so that data can be sent and received through it to and from
				 *  an attached device.
				 *
				 *  \note Pipes must first be configured properly via \ref Pipe_ConfigurePipe().
				 */
				static inline void Pipe_EnablePipe(void);

				/** Disables the currently selected pipe so that data cannot be sent and received through it to and
				 *  from an attached device.
				 */
				static inline void Pipe_DisablePipe(void);

				/** Determines if the currently selected pipe is enabled, but not necessarily configured.
				 *
				 * \return Boolean True if the currently selected pipe is enabled, false otherwise
				 */
				static inline bool Pipe_IsEnabled(void);
				
				/** Gets the current pipe token, indicating the pipe's data direction and type.
				 *
				 *  \return The current pipe token, as a PIPE_TOKEN_* mask
				 */
				static inline uint8_t Pipe_GetCurrentToken(void);
				
				/** Sets the token for the currently selected pipe to one of the tokens specified by the PIPE_TOKEN_*
				 *  masks. This can be used on CONTROL type pipes, to allow for bidirectional transfer of data during
				 *  control requests, or on regular pipes to allow for half-duplex bidirectional data transfer to devices
				 *  which have two endpoints of opposite direction sharing the same endpoint address within the device.
				 *
				 *  \param Token  New pipe token to set the selected pipe to, as a PIPE_TOKEN_* mask
				 */
				static inline void Pipe_SetPipeToken(uint8_t Token);
				
				/** Configures the currently selected pipe to allow for an unlimited number of IN requests. */
				static inline void Pipe_SetInfiniteINRequests(void);
				
				/** Configures the currently selected pipe to only allow the specified number of IN requests to be
				 *  accepted by the pipe before it is automatically frozen.
				 *
				 *  \param TotalINRequests  Total number of IN requests that the pipe may receive before freezing
				 */
				static inline void Pipe_SetFiniteINRequests(uint8_t TotalINRequests);

				/** Determines if the currently selected pipe is configured.
				 *
				 *  \return Boolean true if the selected pipe is configured, false otherwise
				 */
				static inline bool Pipe_IsConfigured(void);
				
				/** Sets the period between interrupts for an INTERRUPT type pipe to a specified number of milliseconds.
				 *
				 *  \param Milliseconds  Number of milliseconds between each pipe poll
				 */
				static inline void Pipe_SetInterruptPeriod(uint8_t Milliseconds);