Pipe Management
[USB - LUFA/Drivers/USB/USB.h]


Modules

 Pipe Data Reading and Writing
 Pipe Packet Management
 Pipe Control Request Management

Defines

#define PIPE_ERRORFLAG_CRC16   (1 << 4)
#define PIPE_ERRORFLAG_TIMEOUT   (1 << 3)
#define PIPE_ERRORFLAG_PID   (1 << 2)
#define PIPE_ERRORFLAG_DATAPID   (1 << 1)
#define PIPE_ERRORFLAG_DATATGL   (1 << 0)
#define PIPE_TOKEN_SETUP   (0 << PTOKEN0)
#define PIPE_TOKEN_IN   (1 << PTOKEN0)
#define PIPE_TOKEN_OUT   (2 << PTOKEN0)
#define PIPE_BANK_SINGLE   (0 << EPBK0)
#define PIPE_BANK_DOUBLE   (1 << EPBK0)
#define PIPE_CONTROLPIPE   0
#define PIPE_CONTROLPIPE_DEFAULT_SIZE   64
#define PIPE_PIPENUM_MASK   0x07
#define PIPE_TOTAL_PIPES   7
#define PIPE_MAX_SIZE   256
#define PIPE_EPNUM_MASK   0x07
#define PIPE_EPSIZE_MASK   0x7FF
#define PIPE_INT_IN   UPIENX, (1 << RXINE) , UPINTX, (1 << RXINI)
#define PIPE_INT_OUT   UPIENX, (1 << TXOUTE), UPINTX, (1 << TXOUTI)
#define PIPE_INT_SETUP   UPIENX, (1 << TXSTPE) , UPINTX, (1 << TXSTPI)
#define PIPE_INT_ERROR   UPIENX, (1 << PERRE), UPINTX, (1 << PERRI)
#define PIPE_INT_NAK   UPIENX, (1 << NAKEDE), UPINTX, (1 << NAKEDI)
#define PIPE_INT_STALL   UPIENX, (1 << RXSTALLE), UPINTX, (1 << RXSTALLI)

Functions

static uint8_t Pipe_GetCurrentPipe (void)
static void Pipe_SelectPipe (uint8_t PipeNumber)
static void Pipe_ResetPipe (uint8_t PipeNumber)
static void Pipe_EnablePipe (void)
static void Pipe_DisablePipe (void)
static bool Pipe_IsEnabled (void)
static uint8_t Pipe_GetCurrentToken (void)
static void Pipe_SetPipeToken (uint8_t Token)
static void Pipe_SetInfiniteINRequests (void)
static void Pipe_SetFiniteINRequests (uint8_t TotalINRequests)
static bool Pipe_IsConfigured (void)
static void Pipe_SetInterruptPeriod (uint8_t Milliseconds)
static uint8_t Pipe_GetPipeInterrupts (void)
static void Pipe_ClearPipeInterrupt (uint8_t PipeNumber)
static bool Pipe_HasPipeInterrupted (uint8_t PipeNumber)
static void Pipe_Unfreeze (void)
static void Pipe_Freeze (void)
static void Pipe_ClearError (void)
static bool Pipe_IsError (void)
static void Pipe_ClearErrorFlags (void)
static uint8_t Pipe_GetErrorFlags (void)
bool Pipe_ConfigurePipe (const uint8_t Number, const uint8_t Type, const uint8_t Token, const uint8_t EndpointNumber, const uint16_t Size, const uint8_t Banks)

Variables

uint8_t USB_ControlPipeSize

Detailed Description

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.

Define Documentation

#define PIPE_BANK_DOUBLE   (1 << EPBK0)

Mask for the bank mode selection for the 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_SINGLE   (0 << EPBK0)

Mask for the bank mode selection for the 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_CONTROLPIPE   0

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_DEFAULT_SIZE   64

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_EPNUM_MASK   0x07

Endpoint number mask, for masking against endpoint addresses to retrieve the endpoint's numerical address in the attached device.

#define PIPE_EPSIZE_MASK   0x7FF

Endpoint bank size mask, for masking against endpoint addresses to retrieve the endpoint's bank size in the attached device.

#define PIPE_ERRORFLAG_CRC16   (1 << 4)

Mask for Pipe_GetErrorFlags(), indicating that a CRC error occurred in the pipe on the received data.

#define PIPE_ERRORFLAG_DATAPID   (1 << 1)

Mask for Pipe_GetErrorFlags(), indicating that a hardware data PID error occurred in the pipe.

#define PIPE_ERRORFLAG_DATATGL   (1 << 0)

Mask for Pipe_GetErrorFlags(), indicating that a hardware data toggle error occurred in the pipe.

#define PIPE_ERRORFLAG_PID   (1 << 2)

Mask for Pipe_GetErrorFlags(), indicating that a hardware PID error occurred in the pipe.

#define PIPE_ERRORFLAG_TIMEOUT   (1 << 3)

Mask for Pipe_GetErrorFlags(), indicating that a hardware timeout error occurred in the pipe.

#define PIPE_INT_ERROR   UPIENX, (1 << PERRE), UPINTX, (1 << PERRI)

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 also:
ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.

Pipe_GetErrorFlags() for more information on the pipe errors.

#define PIPE_INT_IN   UPIENX, (1 << RXINE) , UPINTX, (1 << RXINI)

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 also:
ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.

#define PIPE_INT_NAK   UPIENX, (1 << NAKEDE), UPINTX, (1 << NAKEDI)

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 also:
ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.

Pipe_IsNAKReceived() for more information on pipe NAKs.

#define PIPE_INT_OUT   UPIENX, (1 << TXOUTE), UPINTX, (1 << TXOUTI)

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 also:
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 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 also:
ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.

#define PIPE_INT_STALL   UPIENX, (1 << RXSTALLE), UPINTX, (1 << RXSTALLI)

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 also:
ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.

#define PIPE_MAX_SIZE   256

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_PIPENUM_MASK   0x07

Pipe number mask, for masking against pipe addresses to retrieve the pipe's numerical address in the device.

#define PIPE_TOKEN_IN   (1 << PTOKEN0)

Token mask for 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_OUT   (2 << PTOKEN0)

Token mask for 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_SETUP   (0 << PTOKEN0)

Token mask for 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_TOTAL_PIPES   7

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.


Function Documentation

static void Pipe_ClearError ( void   )  [inline, static]

Clears the master pipe error flag.

static void Pipe_ClearErrorFlags ( void   )  [inline, static]

Clears all the currently selected pipe's hardware error flags, but does not clear the master error flag for the pipe.

static void Pipe_ClearPipeInterrupt ( uint8_t  PipeNumber  )  [inline, static]

Clears the interrupt flag for the specified pipe number.

Parameters:
PipeNumber Index of the pipe whose interrupt flag is to be cleared

bool Pipe_ConfigurePipe ( const uint8_t  Number,
const uint8_t  Type,
const uint8_t  Token,
const uint8_t  EndpointNumber,
const uint16_t  Size,
const uint8_t  Banks 
)

Configures the specified pipe number with the given pipe type, token, target endpoint number in the attached device, bank size and banking mode. Pipes should be allocated in ascending order by their address in the device (i.e. pipe 1 should be configured before pipe 2 and so on).

The pipe type may be one of the EP_TYPE_* macros listed in LowLevel.h, the token may be one of the PIPE_TOKEN_* masks.

The bank size must indicate the maximum packet size that the pipe can handle. Different pipe numbers can handle different maximum packet sizes - refer to the chosen USB AVR's datasheet to determine the maximum bank size for each pipe.

The banking mode may be either PIPE_BANK_SINGLE or PIPE_BANK_DOUBLE.

A newly configured pipe is frozen by default, and must be unfrozen before use via the Pipe_Unfreeze() macro.

Note:
This routine will select the specified pipe, and the pipe will remain selected once the routine completes regardless of if the pipe configuration succeeds.
Returns:
Boolean true if the configuration is successful, false otherwise

static void Pipe_DisablePipe ( void   )  [inline, static]

Disables the currently selected pipe so that data cannot be sent and received through it to and from an attached device.

static void Pipe_EnablePipe ( void   )  [inline, static]

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 Pipe_ConfigurePipe().

static void Pipe_Freeze ( void   )  [inline, static]

Freezes the selected pipe, preventing it from communicating with an attached device.

static uint8_t Pipe_GetCurrentPipe ( void   )  [inline, static]

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.

Returns:
Index of the currently selected pipe

static uint8_t Pipe_GetCurrentToken ( void   )  [inline, static]

Gets the current pipe token, indicating the pipe's data direction and type.

Returns:
The current pipe token, as a PIPE_TOKEN_* mask

static uint8_t Pipe_GetErrorFlags ( void   )  [inline, static]

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.

Returns:
Mask comprising of PIPE_ERRORFLAG_* bits indicating what error has occurred on the selected pipe

static uint8_t Pipe_GetPipeInterrupts ( void   )  [inline, static]

Returns a mask indicating which pipe's interrupt periods have elapsed, indicating that the pipe should be serviced.

Returns:
Mask whose bits indicate which pipes have interrupted

static bool Pipe_HasPipeInterrupted ( uint8_t  PipeNumber  )  [inline, static]

Determines if the specified pipe number has interrupted (valid only for INTERRUPT type pipes).

Parameters:
PipeNumber Index of the pipe whose interrupt flag should be tested
Returns:
Boolean true if the specified pipe has interrupted, false otherwise

static bool Pipe_IsConfigured ( void   )  [inline, static]

Determines if the currently selected pipe is configured.

Returns:
Boolean true if the selected pipe is configured, false otherwise

static bool Pipe_IsEnabled ( void   )  [inline, static]

Determines if the currently selected pipe is enabled, but not necessarily configured.

Returns:
Boolean True if the currently selected pipe is enabled, false otherwise

static bool Pipe_IsError ( void   )  [inline, static]

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 also:
Pipe_GetErrorFlags() macro for information on retrieving the exact error flag.
Returns:
Boolean true if an error has occurred on the selected pipe, false otherwise

static void Pipe_ResetPipe ( uint8_t  PipeNumber  )  [inline, static]

Resets the desired pipe, including the pipe banks and flags.

Parameters:
PipeNumber Index of the pipe to reset

static void Pipe_SelectPipe ( uint8_t  PipeNumber  )  [inline, static]

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.

Parameters:
PipeNumber Index of the pipe to select

static void Pipe_SetFiniteINRequests ( uint8_t  TotalINRequests  )  [inline, static]

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.

Parameters:
TotalINRequests Total number of IN requests that the pipe may receive before freezing

static void Pipe_SetInfiniteINRequests ( void   )  [inline, static]

Configures the currently selected pipe to allow for an unlimited number of IN requests.

static void Pipe_SetInterruptPeriod ( uint8_t  Milliseconds  )  [inline, static]

Sets the period between interrupts for an INTERRUPT type pipe to a specified number of milliseconds.

Parameters:
Milliseconds Number of milliseconds between each pipe poll

static void Pipe_SetPipeToken ( uint8_t  Token  )  [inline, static]

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.

Parameters:
Token New pipe token to set the selected pipe to, as a PIPE_TOKEN_* mask

static void Pipe_Unfreeze ( void   )  [inline, static]

Unfreezes the selected pipe, allowing it to communicate with an attached device.


Variable Documentation

Global indicating the maximum packet size of the default control pipe located at address 0 in the device. This value is set to the value indicated in the attached device's device descriptor once the USB interface is initialized into host mode and a device is attached to the USB bus.

Note:
This variable should be treated as read-only in the user application, and never manually changed in value.


Generated on Sun May 10 15:26:14 2009 for LUFA Library by  doxygen 1.5.7.1