PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

Functions
High-Level
PDL API Reference » SCB (Serial Communication Block) » UART (SCB) » Functions

## General Description

## Functions
void | Cy_SCB_UART_StartRingBuffer (CySCB_Type *base, void *buffer, uint32_t size, cy_stc_scb_uart_context_t *context)
| Starts the receive ring buffer operation. More...
void | Cy_SCB_UART_StopRingBuffer (CySCB_Type *base, cy_stc_scb_uart_context_t *context)
| Stops receiving data into the ring buffer and clears the ring buffer. More...
uint32_t | Cy_SCB_UART_GetNumInRingBuffer (CySCB_Type const *base, cy_stc_scb_uart_context_t const *context)
| Returns the number of data elements in the ring buffer. More...
void | Cy_SCB_UART_ClearRingBuffer (CySCB_Type const *base, cy_stc_scb_uart_context_t *context)
| Clears the ring buffer. More...
cy_en_scb_uart_status_t | Cy_SCB_UART_Receive (CySCB_Type *base, void *buffer, uint32_t size, cy_stc_scb_uart_context_t *context)
| This function starts a UART receive operation. More...
void | Cy_SCB_UART_AbortReceive (CySCB_Type *base, cy_stc_scb_uart_context_t *context)
| Abort the current receive operation by clearing the receive status. More...
uint32_t | Cy_SCB_UART_GetReceiveStatus (CySCB_Type const *base, cy_stc_scb_uart_context_t const *context)
| Returns the status of the receive operation. More...
uint32_t | Cy_SCB_UART_GetNumReceived (CySCB_Type const *base, cy_stc_scb_uart_context_t const *context)
| Returns the number of data elements received since the last call to Cy_SCB_UART_Receive. More...
cy_en_scb_uart_status_t | Cy_SCB_UART_Transmit (CySCB_Type *base, void *buffer, uint32_t size, cy_stc_scb_uart_context_t *context)
| This function starts a UART transmit operation. More...
void | Cy_SCB_UART_AbortTransmit (CySCB_Type *base, cy_stc_scb_uart_context_t *context)
| Aborts the current transmit operation. More...
uint32_t | Cy_SCB_UART_GetTransmitStatus (CySCB_Type const *base, cy_stc_scb_uart_context_t const *context)
| Returns the status of the transmit operation. More...
uint32_t | Cy_SCB_UART_GetNumLeftToTransmit (CySCB_Type const *base, cy_stc_scb_uart_context_t const *context)
| Returns the number of data elements left to transmit since the last call to Cy_SCB_UART_Transmit. More...

## Function Documentation

## ◆ Cy_SCB_UART_StartRingBuffer()

void Cy_SCB_UART_StartRingBuffer | ( | CySCB_Type * | base,
|  | void * | buffer,
|  | uint32_t | size,
|  | cy_stc_scb_uart_context_t * | context
| ) |  |

Starts the receive ring buffer operation.

The RX interrupt source is configured to get data from the RX FIFO and put into the ring buffer.

Parameters

  base | The pointer to the UART SCB instance.
  buffer | Pointer to the user defined ring buffer. The element size is defined by the data type, which depends on the configured data width.
  size | The size of the receive ring buffer. Note that one data element is used for internal use, so if the size is 32, then only 31 data elements are used for data storage.
  context | The pointer to the context structure cy_stc_scb_uart_context_t allocated by the user. The structure is used during the UART operation for internal configuration and data retention. The user must not modify anything in this structure.

Note
  - The buffer must not be modified and stay allocated while the ring buffer operates.
  - This function overrides the RX interrupt sources and changes the RX FIFO level.

## ◆ Cy_SCB_UART_StopRingBuffer()

void Cy_SCB_UART_StopRingBuffer | ( | CySCB_Type * | base,
|  | cy_stc_scb_uart_context_t * | context
| ) |  |

Stops receiving data into the ring buffer and clears the ring buffer.

Parameters

  base | The pointer to the UART SCB instance.
  context | The pointer to the context structure cy_stc_scb_uart_context_t allocated by the user. The structure is used during the UART operation for internal configuration and data retention. The user must not modify anything in this structure.

## ◆ Cy_SCB_UART_GetNumInRingBuffer()

uint32_t Cy_SCB_UART_GetNumInRingBuffer | ( | CySCB_Type const * | base,
|  | cy_stc_scb_uart_context_t const * | context
| ) |  |

Returns the number of data elements in the ring buffer.

Parameters

  base | The pointer to the UART SCB instance.
  context | The pointer to the context structure cy_stc_scb_uart_context_t allocated by the user. The structure is used during the UART operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns
  The number of data elements in the receive ring buffer.

Note
  One data element is used for internal use, so when the buffer is full, this function returns (Ring Buffer size - 1).

## ◆ Cy_SCB_UART_ClearRingBuffer()

void Cy_SCB_UART_ClearRingBuffer | ( | CySCB_Type const * | base,
|  | cy_stc_scb_uart_context_t * | context
| ) |  |

Clears the ring buffer.

Parameters

  base | The pointer to the UART SCB instance.
  context | The pointer to the context structure cy_stc_scb_uart_context_t allocated by the user. The structure is used during the UART operation for internal configuration and data retention. The user must not modify anything in this structure.

## ◆ Cy_SCB_UART_Receive()

cy_en_scb_uart_status_t Cy_SCB_UART_Receive | ( | CySCB_Type * | base,
|  | void * | buffer,
|  | uint32_t | size,
|  | cy_stc_scb_uart_context_t * | context
| ) |  |

This function starts a UART receive operation.

It configures the receive interrupt sources to get data available in the receive FIFO and returns. The Cy_SCB_UART_Interrupt manages the further data transfer.

If the ring buffer is enabled, this function first reads data from the ring buffer. If there is more data to receive, it configures the receive interrupt sources to copy the remaining bytes from the RX FIFO when they arrive.

When the receive operation is completed (requested number of data elements received) the CY_SCB_UART_RECEIVE_ACTIVE status is cleared and the CY_SCB_UART_RECEIVE_DONE_EVENT event is generated.

Parameters

  base | The pointer to the UART SCB instance.
  buffer | Pointer to buffer to store received data. The element size is defined by the data type, which depends on the configured data width.
  size | The number of data elements to receive.
  context | The pointer to the context structure cy_stc_scb_uart_context_t allocated by the user. The structure is used during the UART operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns
  cy_en_scb_uart_status_t

Note
  - The buffer must not be modified and stay allocated until end of the receive operation.
  - This function overrides the RX interrupt sources and changes the RX FIFO level.

## ◆ Cy_SCB_UART_AbortReceive()

void Cy_SCB_UART_AbortReceive | ( | CySCB_Type * | base,
|  | cy_stc_scb_uart_context_t * | context
| ) |  |

Abort the current receive operation by clearing the receive status.

- If the ring buffer is disabled, the receive interrupt sources are disabled.
- If the ring buffer is enabled, the receive interrupt source is configured to get data from the receive FIFO and put it into the ring buffer.

Parameters

  base | The pointer to the UART SCB instance.
  context | The pointer to the context structure cy_stc_scb_uart_context_t allocated by the user. The structure is used during the UART operation for internal configuration and data retention. The user must not modify anything in this structure.

Note
  - The RX FIFO and ring buffer are not cleared after abort of receive operation.
  - If after the abort of the receive operation the transmitter continues sending data, it gets into the RX FIFO. To drop this data, the RX FIFO and ring buffer (if enabled) must be cleared when the transmitter stops sending data. Otherwise, received data will be kept and copied to the buffer when Cy_SCB_UART_Receive is called.

## ◆ Cy_SCB_UART_GetReceiveStatus()

uint32_t Cy_SCB_UART_GetReceiveStatus | ( | CySCB_Type const * | base,
|  | cy_stc_scb_uart_context_t const * | context
| ) |  |

Returns the status of the receive operation.

This status is a bit mask and the value returned may have multiple bits set.

Parameters

  base | The pointer to the UART SCB instance.
  context | The pointer to the context structure cy_stc_scb_uart_context_t allocated by the user. The structure is used during the UART operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns
  UART Receive Statuses.

Note
  The status is only cleared by calling Cy_SCB_UART_Receive again.

## ◆ Cy_SCB_UART_GetNumReceived()

uint32_t Cy_SCB_UART_GetNumReceived | ( | CySCB_Type const * | base,
|  | cy_stc_scb_uart_context_t const * | context
| ) |  |

Returns the number of data elements received since the last call to Cy_SCB_UART_Receive.

Parameters

  base | The pointer to the UART SCB instance.
  context | The pointer to the context structure cy_stc_scb_uart_context_t allocated by the user. The structure is used during the UART operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns
  The number of data elements received.

## ◆ Cy_SCB_UART_Transmit()

cy_en_scb_uart_status_t Cy_SCB_UART_Transmit | ( | CySCB_Type * | base,
|  | void * | buffer,
|  | uint32_t | size,
|  | cy_stc_scb_uart_context_t * | context
| ) |  |

This function starts a UART transmit operation.

It configures the transmit interrupt sources and returns. The Cy_SCB_UART_Interrupt manages the further data transfer.

When the transmit operation is completed (requested number of data elements sent on the bus), the CY_SCB_UART_TRANSMIT_ACTIVE status is cleared and the CY_SCB_UART_TRANSMIT_DONE_EVENT event is generated.

Parameters

  base | The pointer to the UART SCB instance.
  buffer | Pointer to user data to place in transmit buffer. The element size is defined by the data type, which depends on the configured data width.
  size | The number of data elements to transmit.
  context | The pointer to the context structure cy_stc_scb_uart_context_t allocated by the user. The structure is used during the UART operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns
  cy_en_scb_uart_status_t

Note
  - The buffer must not be modified and must stay allocated until its content is copied into the TX FIFO.
  - This function overrides the TX FIFO interrupt sources and changes the TX FIFO level.

## ◆ Cy_SCB_UART_AbortTransmit()

void Cy_SCB_UART_AbortTransmit | ( | CySCB_Type * | base,
|  | cy_stc_scb_uart_context_t * | context
| ) |  |

Aborts the current transmit operation.

It disables the transmit interrupt sources and clears the transmit FIFO and status.

Parameters

  base | The pointer to the UART SCB instance.
  context | The pointer to the context structure cy_stc_scb_uart_context_t allocated by the user. The structure is used during the UART operation for internal configuration and data retention. The user must not modify anything in this structure.

Side Effects
  The transmit FIFO clear operation also clears the shift register, so that the shifter can be cleared in the middle of a data element transfer, corrupting it. The data element corruption means that all bits that have not been transmitted are transmitted as "ones" on the bus.

## ◆ Cy_SCB_UART_GetTransmitStatus()

uint32_t Cy_SCB_UART_GetTransmitStatus | ( | CySCB_Type const * | base,
|  | cy_stc_scb_uart_context_t const * | context
| ) |  |

Returns the status of the transmit operation.

This status is a bit mask and the value returned may have multiple bits set.

Parameters

  base | The pointer to the UART SCB instance.
  context | The pointer to the context structure cy_stc_scb_uart_context_t allocated by the user. The structure is used during the UART operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns
  UART Transmit Status.

Note
  The status is only cleared by calling Cy_SCB_UART_Transmit or Cy_SCB_UART_AbortTransmit.

## ◆ Cy_SCB_UART_GetNumLeftToTransmit()

uint32_t Cy_SCB_UART_GetNumLeftToTransmit | ( | CySCB_Type const * | base,
|  | cy_stc_scb_uart_context_t const * | context
| ) |  |

Returns the number of data elements left to transmit since the last call to Cy_SCB_UART_Transmit.

Parameters

  base | The pointer to the UART SCB instance.
  context | The pointer to the context structure cy_stc_scb_uart_context_t allocated by the user. The structure is used during the UART operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns
  The number of data elements left to transmit.