LUFA Library  140302
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Pipe Management (AVR8)

Pipe management definitions for the Atmel AVR8 architecture. More...

Macros

#define PIPE_CONTROLPIPE_DEFAULT_SIZE   64
 
#define PIPE_MAX_SIZE   256
 
#define PIPE_TOTAL_PIPES   7
 

Functions

static void Pipe_ClearError (void) ATTR_ALWAYS_INLINE
 
bool Pipe_ConfigurePipe (const uint8_t Address, const uint8_t Type, const uint8_t EndpointAddress, const uint16_t Size, const uint8_t Banks)
 
bool Pipe_ConfigurePipeTable (const USB_Pipe_Table_t *const Table, const uint8_t Entries)
 
static void Pipe_DisablePipe (void) ATTR_ALWAYS_INLINE
 
static void Pipe_EnablePipe (void) ATTR_ALWAYS_INLINE
 
static void Pipe_Freeze (void) ATTR_ALWAYS_INLINE
 
static uint8_t Pipe_GetBoundEndpointAddress (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
 
static uint8_t Pipe_GetCurrentPipe (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
 
static uint8_t Pipe_GetErrorFlags (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
 
static uint8_t Pipe_GetPipeDirection (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
 
static uint8_t Pipe_GetPipeInterrupts (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
 
static uint8_t Pipe_GetPipeToken (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
 
static bool Pipe_HasPipeInterrupted (const uint8_t Address) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
 
static bool Pipe_IsConfigured (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
 
static bool Pipe_IsEnabled (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
 
bool Pipe_IsEndpointBound (const uint8_t EndpointAddress) ATTR_WARN_UNUSED_RESULT
 
static bool Pipe_IsError (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
 
static bool Pipe_IsFrozen (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
 
static void Pipe_ResetPipe (const uint8_t Address) ATTR_ALWAYS_INLINE
 
static void Pipe_SelectPipe (const uint8_t Address) ATTR_ALWAYS_INLINE
 
static void Pipe_SetFiniteINRequests (const uint8_t TotalINRequests) ATTR_ALWAYS_INLINE
 
static void Pipe_SetInfiniteINRequests (void) ATTR_ALWAYS_INLINE
 
static void Pipe_SetInterruptPeriod (const uint8_t Milliseconds) ATTR_ALWAYS_INLINE
 
static void Pipe_SetPipeToken (const uint8_t Token) ATTR_ALWAYS_INLINE
 
static void Pipe_Unfreeze (void) ATTR_ALWAYS_INLINE
 

Variables

uint8_t USB_Host_ControlPipeSize
 

Pipe Error Flag Masks

#define PIPE_ERRORFLAG_OVERFLOW   (1 << 6)
 
#define PIPE_ERRORFLAG_UNDERFLOW   (1 << 5)
 
#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)
 

Pipe Token Masks

#define PIPE_TOKEN_SETUP   (0 << PTOKEN0)
 
#define PIPE_TOKEN_IN   (1 << PTOKEN0)
 
#define PIPE_TOKEN_OUT   (2 << PTOKEN0)
 

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/receive functions for various data types.

Macro Definition Documentation

#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_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_OVERFLOW   (1 << 6)

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

#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_ERRORFLAG_UNDERFLOW   (1 << 5)

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

#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_TOKEN_IN   (1 << PTOKEN0)

Token mask for Pipe_SetPipeToken() and Pipe_GetPipeToken(). 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_SetPipeToken() and Pipe_GetPipeToken(). This sets the pipe as a OUT 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_SetPipeToken() and Pipe_GetPipeToken(). 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  )
inlinestatic

Clears the error flags for the currently selected pipe.

bool Pipe_ConfigurePipe ( const uint8_t  Address,
const uint8_t  Type,
const uint8_t  EndpointAddress,
const uint16_t  Size,
const uint8_t  Banks 
)

Configures the specified pipe address with the given pipe type, endpoint address within the attached device, bank size and number of hardware banks.

A newly configured pipe is frozen by default, and must be unfrozen before use via the Pipe_Unfreeze() before being used. Pipes should be kept frozen unless waiting for data from a device while in IN mode, or sending data to the device in OUT mode. IN type pipes are also automatically configured to accept infinite numbers of IN requests without automatic freezing - this can be overridden by a call to Pipe_SetFiniteINRequests().

Parameters
[in]AddressPipe address to configure.
[in]TypeType of pipe to configure, an EP_TYPE_* mask. Not all pipe types are available on Low Speed USB devices - refer to the USB 2.0 specification.
[in]EndpointAddressEndpoint address within the attached device that the pipe should interface to.
[in]SizeSize of the pipe's bank, where packets are stored before they are transmitted to the USB device, or after they have been received from the USB device (depending on the pipe's data direction). The bank size must indicate the maximum packet size that the pipe can handle.
[in]BanksNumber of banks to use for the pipe being configured.
Attention
When the ORDERED_EP_CONFIG compile time option is used, Pipes must be configured in ascending order, or bank corruption will occur.
Note
Certain microcontroller model's pipes may have different maximum packet sizes based on the pipe's index - refer to the chosen microcontroller's datasheet to determine the maximum bank size for each pipe.

The default control pipe should not be manually configured by the user application, as it is automatically configured by the library internally.

This routine will automatically select the specified pipe upon success. Upon failure, the pipe which failed to reconfigure correctly will be selected.
Returns
Boolean true if the configuration succeeded, false otherwise.
bool Pipe_ConfigurePipeTable ( const USB_Pipe_Table_t *const  Table,
const uint8_t  Entries 
)

Configures a table of pipe descriptions, in sequence. This function can be used to configure multiple pipes at the same time.

Note
Pipe with a zero address will be ignored, thus this function cannot be used to configure the control pipe.
Parameters
[in]TablePointer to a table of pipe descriptions.
[in]EntriesNumber of entries in the pipe table to configure.
Returns
Boolean true if all pipes configured successfully, false otherwise.
static void Pipe_DisablePipe ( void  )
inlinestatic

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  )
inlinestatic

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

Precondition
The currently selected pipe must first be configured properly via Pipe_ConfigurePipe().
static void Pipe_Freeze ( void  )
inlinestatic

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

static uint8_t Pipe_GetBoundEndpointAddress ( void  )
inlinestatic

Retrieves the endpoint address of the endpoint within the attached device that the currently selected pipe is bound to.

Returns
Endpoint address the currently selected pipe is bound to.
static uint8_t Pipe_GetCurrentPipe ( void  )
inlinestatic

Returns the pipe address of the currently selected pipe. This is typically used to save the currently selected pipe address so that it can be restored after another pipe has been manipulated.

Returns
Index of the currently selected pipe.
static uint8_t Pipe_GetErrorFlags ( void  )
inlinestatic

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_GetPipeDirection ( void  )
inlinestatic

Determines the currently selected pipe's direction.

Returns
The currently selected pipe's direction, as a PIPE_DIR_* mask.
static uint8_t Pipe_GetPipeInterrupts ( void  )
inlinestatic

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 uint8_t Pipe_GetPipeToken ( void  )
inlinestatic

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

Returns
The current pipe token, as a PIPE_TOKEN_* mask.
static bool Pipe_HasPipeInterrupted ( const uint8_t  Address)
inlinestatic

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

Parameters
[in]AddressAddress 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  )
inlinestatic

Determines if the currently selected pipe is configured.

Returns
Boolean true if the selected pipe is configured, false otherwise.
static bool Pipe_IsEnabled ( void  )
inlinestatic

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

Returns
Boolean true if the currently selected pipe is enabled, false otherwise.
bool Pipe_IsEndpointBound ( const uint8_t  EndpointAddress)

Determines if a pipe has been bound to the given device endpoint address. If a pipe which is bound to the given endpoint is found, it is automatically selected.

Parameters
[in]EndpointAddressAddress and direction mask of the endpoint within the attached device to check.
Returns
Boolean true if a pipe bound to the given endpoint address of the specified direction is found, false otherwise.
static bool Pipe_IsError ( void  )
inlinestatic

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 bool Pipe_IsFrozen ( void  )
inlinestatic

Determines if the currently selected pipe is frozen, and not able to accept data.

Returns
Boolean true if the currently selected pipe is frozen, false otherwise.
static void Pipe_ResetPipe ( const uint8_t  Address)
inlinestatic

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

Parameters
[in]AddressAddress of the pipe to reset.
static void Pipe_SelectPipe ( const uint8_t  Address)
inlinestatic

Selects the given pipe address. Any pipe operations which do not require the pipe address to be indicated will operate on the currently selected pipe.

Parameters
[in]AddressAddress of the pipe to select.
static void Pipe_SetFiniteINRequests ( const uint8_t  TotalINRequests)
inlinestatic

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
[in]TotalINRequestsTotal number of IN requests that the pipe may receive before freezing.
static void Pipe_SetInfiniteINRequests ( void  )
inlinestatic

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

static void Pipe_SetInterruptPeriod ( const uint8_t  Milliseconds)
inlinestatic

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

Parameters
[in]MillisecondsNumber of milliseconds between each pipe poll.
static void Pipe_SetPipeToken ( const uint8_t  Token)
inlinestatic

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
[in]TokenNew pipe token to set the selected pipe to, as a PIPE_TOKEN_* mask.
static void Pipe_Unfreeze ( void  )
inlinestatic

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

Variable Documentation

uint8_t USB_Host_ControlPipeSize

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.

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