| LPCOpen Platform v1.03 LPCOpen Platform for NXP LPC Microcontrollers

- Main Page
- Modules
- Data Structures
- Files
- Related Pages

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Modules | Macros | Functions | Variables
Pipe Management
USB Core - software/LPCUSBLib/Drivers/USB/USB.h

## Detailed Description

Pipe management definitions.

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.

## Data Structures
struct | USB_Pipe_Data_t

## Modules
| Pipe Control Request Management
| Pipe control request definitions.
| Pipe Data Reading and Writing
| Pipe data read/write definitions.
| Pipe Packet Management
| Pipe packet management definitions.

## Macros
#define | PIPE_CONTROLPIPE 0
#define | PIPE_PIPENUM_MASK 0x0F
#define | PIPE_EPNUM_MASK 0x0F
#define | PIPE_EPDIR_MASK 0x80
#define | PIPE_CONTROLPIPE_DEFAULT_SIZE 8
#define | PIPE_TOTAL_PIPES HCD_MAX_ENDPOINT
#define | PIPE_MAX_SIZE 512

## Functions
static uint8_t | Pipe_GetCurrentPipe (const uint8_t corenum) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
| 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.
static void | Pipe_SelectPipe (const uint8_t corenum, const uint8_t PipeNumber) ATTR_ALWAYS_INLINE
| 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.
static void | Pipe_ResetPipe (const uint8_t corenum, const uint8_t PipeNumber) ATTR_ALWAYS_INLINE
| Resets the desired pipe, including the pipe banks and flags.
static void | Pipe_EnablePipe (void) ATTR_ALWAYS_INLINE
static void | Pipe_DisablePipe (void) ATTR_ALWAYS_INLINE
static bool | Pipe_IsEnabled (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
| Determines if the currently selected pipe is enabled, but not necessarily configured.
static uint8_t | Pipe_GetPipeToken (const uint8_t corenum) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
| Gets the current pipe token, indicating the pipe's data direction and type.
static void | Pipe_SetPipeToken (const uint8_t Token) ATTR_DEPRECATED ATTR_ALWAYS_INLINE
| 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.
static void | Pipe_SetInfiniteINRequests (void) ATTR_DEPRECATED ATTR_ALWAYS_INLINE
static void | Pipe_SetFiniteINRequests (const uint8_t TotalINRequests) ATTR_DEPRECATED ATTR_ALWAYS_INLINE
| 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.
static bool | Pipe_IsConfigured (const uint8_t corenum) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
| Determines if the currently selected pipe is configured.
static uint8_t | Pipe_GetBoundEndpointAddress (const uint8_t corenum) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
| Retrieves the endpoint address of the endpoint within the attached device that the currently selected pipe is bound to.
static void | Pipe_SetInterruptPeriod (const uint8_t Milliseconds) ATTR_ALWAYS_INLINE
| Sets the period between interrupts for an INTERRUPT type pipe to a specified number of milliseconds.
static uint8_t | Pipe_GetPipeInterrupts (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
| Returns a mask indicating which pipe's interrupt periods have elapsed, indicating that the pipe should be serviced.
static bool | Pipe_HasPipeInterrupted (const uint8_t PipeNumber) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
| Determines if the specified pipe number has interrupted (valid only for INTERRUPT type pipes).
static void | Pipe_Unfreeze (void) ATTR_ALWAYS_INLINE
static void | Pipe_Freeze (void) ATTR_ALWAYS_INLINE
static bool | Pipe_IsFrozen (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
| Determines if the currently selected pipe is frozen, and not able to accept data.
static void | Pipe_ClearError (void) ATTR_ALWAYS_INLINE
static bool | Pipe_IsError (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
| 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.
static uint8_t | Pipe_GetErrorFlags (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
| 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.
bool | Pipe_ConfigurePipe (const uint8_t corenum, 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.
void | Pipe_ClosePipe (const uint8_t corenum, uint8_t pipenum)
bool | Pipe_IsEndpointBound (const uint8_t EndpointAddress) ATTR_WARN_UNUSED_RESULT
| 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.

## Variables
uint8_t | hostselected
HCD_USB_SPEED | hostportspeed []
uint8_t | pipeselected [MAX_USB_CORE]
USB_Pipe_Data_t | PipeInfo [MAX_USB_CORE][PIPE_TOTAL_PIPES]

## Macro Definition Documentation

#define PIPE_BANK_DOUBLE (1 << 1)

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 LPC or the attached device) can access one bank while the other accesses the second bank.

Definition at line 176 of file Pipe.h.

#define PIPE_BANK_SINGLE (0 << 1)

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 LPC or the attached device) can access the pipe's bank at the one time.

Definition at line 169 of file Pipe.h.

#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.

Definition at line 98 of file Pipe.h.

#define PIPE_CONTROLPIPE_DEFAULT_SIZE 8

Default size of the default control pipe's bank, until altered by the Endpoint0Size value in the device descriptor of the attached device.

Definition at line 182 of file Pipe.h.

#define PIPE_EPDIR_MASK 0x80

Endpoint direction mask, for masking against endpoint addresses to retrieve the endpoint's direction for comparing with the `ENDPOINT_DESCRIPTOR_DIR_*` masks.

Definition at line 113 of file Pipe.h.

#define PIPE_EPNUM_MASK 0x0F

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

Definition at line 108 of file Pipe.h.

#define PIPE_ERRORFLAG_CRC16 (1 << 4)

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

Definition at line 130 of file Pipe.h.

#define PIPE_ERRORFLAG_DATAPID (1 << 1)

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

Definition at line 139 of file Pipe.h.

#define PIPE_ERRORFLAG_DATATGL (1 << 0)

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

Definition at line 142 of file Pipe.h.

#define PIPE_ERRORFLAG_OVERFLOW (1 << 6)

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

Definition at line 124 of file Pipe.h.

#define PIPE_ERRORFLAG_PID (1 << 2)

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

Definition at line 136 of file Pipe.h.

#define PIPE_ERRORFLAG_TIMEOUT (1 << 3)

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

Definition at line 133 of file Pipe.h.

#define PIPE_ERRORFLAG_UNDERFLOW (1 << 5)

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

Definition at line 127 of file Pipe.h.

#define PIPE_MAX_SIZE 512

Size in bytes of the largest pipe bank size possible in the device. Not all banks on each LPC 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 LPC model.

Definition at line 195 of file Pipe.h.

#define PIPE_PIPENUM_MASK 0x0F

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

Definition at line 103 of file Pipe.h.

#define PIPE_TOKEN_IN (1)

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.

Definition at line 155 of file Pipe.h.

#define PIPE_TOKEN_OUT (2)

Token mask for Pipe_ConfigurePipe(). This sets the pipe as a OUT token (for non-CONTROL type pipes), indicating that the pipe data will flow from host to device.

Definition at line 160 of file Pipe.h.

#define PIPE_TOKEN_SETUP (0)

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.

Definition at line 150 of file Pipe.h.

#define PIPE_TOTAL_PIPES HCD_MAX_ENDPOINT

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

Definition at line 188 of file Pipe.h.

## Function Documentation

static void Pipe_ClearError | ( | void |  | ) |
| inline static

Clears the error flags for the currently selected pipe.

Definition at line 473 of file Pipe.h.

void Pipe_ClosePipe | ( | const uint8_t | corenum,
|  | uint8_t | pipenum
| ) |  |

Definition at line 83 of file Pipe.c.

bool Pipe_ConfigurePipe | ( | const uint8_t | corenum,
|  | 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.

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. 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

  corenum | : USB port number
  Number | : Pipe number to configure. This must be more than 0 and less than PIPE_TOTAL_PIPES.
  Type | : Type 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.
  Token | : Pipe data token, either PIPE_TOKEN_SETUP, PIPE_TOKEN_OUT or PIPE_TOKEN_IN. All pipes (except Control type) are unidirectional - data may only be read from or written to the pipe bank based on its direction, not both.
  EndpointNumber | : Endpoint index within the attached device that the pipe should interface to.
  Size | : Size 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.
  Banks | : Number of banks to use for the pipe being configured, a `PIPE_BANK_*` mask. More banks uses more USB DPRAM, but offers better performance. Isochronous type pipes must have at least two banks.

Note
  When the `ORDERED_EP_CONFIG` compile time option is used, Pipes must be configured in ascending order, or bank corruption will occur.
  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.

Definition at line 45 of file Pipe.c.

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.

Definition at line 317 of file Pipe.h.

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.

Precondition
  The currently selected pipe must first be configured properly via Pipe_ConfigurePipe().

Definition at line 307 of file Pipe.h.

static void Pipe_Freeze | ( | void |  | ) |
| inline static

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

Definition at line 454 of file Pipe.h.

static uint8_t Pipe_GetBoundEndpointAddress | ( | const uint8_t | corenum | ) |
| inline static

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

Parameters

  corenum | : USB port number

Returns
  address the currently selected pipe is bound to.

Definition at line 400 of file Pipe.h.

static uint8_t Pipe_GetCurrentPipe | ( | const uint8_t | corenum | ) |
| 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.

Parameters

  corenum | : USB port number

Returns
  Index of the currently selected pipe

Definition at line 267 of file Pipe.h.

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.

Definition at line 501 of file Pipe.h.

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.

Definition at line 424 of file Pipe.h.

static uint8_t Pipe_GetPipeToken | ( | const uint8_t | corenum | ) |
| inline static

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

Parameters

  corenum | : USB port number

Returns
  The current pipe token, as a `PIPE_TOKEN_*` mask.

Definition at line 341 of file Pipe.h.

static bool Pipe_HasPipeInterrupted | ( | const 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.

Definition at line 438 of file Pipe.h.

static bool Pipe_IsConfigured | ( | const uint8_t | corenum | ) |
| inline static

Determines if the currently selected pipe is configured.

Parameters

  corenum | : USB port number

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

Definition at line 386 of file Pipe.h.

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.

Definition at line 328 of file Pipe.h.

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

  EndpointAddress | : EndpointAddress Address 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.

Definition at line 97 of file Pipe.c.

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.

Definition at line 488 of file Pipe.h.

static bool Pipe_IsFrozen | ( | void |  | ) |
| inline static

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.

Definition at line 465 of file Pipe.h.

static void Pipe_ResetPipe | ( | const uint8_t | corenum,
|  | const uint8_t | PipeNumber
| ) |  |
| inline static

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

Parameters

  corenum | : USB port number
  PipeNumber | : Index of the pipe to reset

Returns
  Nothing

Definition at line 295 of file Pipe.h.

static void Pipe_SelectPipe | ( | const uint8_t | corenum,
|  | const 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

  corenum | : USB port number
  PipeNumber | : Index of the pipe to select

Returns
  Nothing

Definition at line 282 of file Pipe.h.

static void Pipe_SetFiniteINRequests | ( | const 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

Returns
  Nothing

Definition at line 376 of file Pipe.h.

static void Pipe_SetInfiniteINRequests | ( | void |  | ) |
| inline static

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

Definition at line 364 of file Pipe.h.

static void Pipe_SetInterruptPeriod | ( | const 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.

Returns
  Nothing

Definition at line 412 of file Pipe.h.

static void Pipe_SetPipeToken | ( | const 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.

Returns
  Nothing

Definition at line 358 of file Pipe.h.

static void Pipe_Unfreeze | ( | void |  | ) |
| inline static

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

Definition at line 446 of file Pipe.h.

## Variable Documentation

HCD_USB_SPEED hostportspeed[]

USB speed of connected devices

Definition at line 42 of file Pipe.c.

uint8_t hostselected

Current active USB module number

Definition at line 43 of file Pipe.c.

USB_Pipe_Data_t PipeInfo[MAX_USB_CORE][PIPE_TOTAL_PIPES]

Array stores all pipes USB_Pipe_Data_t information available of all USB modules

Definition at line 40 of file Pipe.c.

uint8_t pipeselected[MAX_USB_CORE]

Array stores current active pipe number of each USB module

Definition at line 39 of file Pipe.c.