CAT2 Peripheral Driver Library

Driver API for UART. More...

Modules

 Macros
 
 Functions
 
 Data Structures
 
 Enumerated Types
 

Detailed Description

Driver API for UART.

The functions and other declarations used in this part of the driver are in cy_scb_uart.h. You can also include cy_pdl.h to get access to all functions and declarations in the PDL.

The Universal Asynchronous Receiver/Transmitter (UART) protocol is an asynchronous serial interface protocol. UART communication is typically point-to-point. The UART interface consists of two signals:

Additionally, two side-band signals are used to implement flow control in UART. Note that the flow control applies only to TX functionality.

Features:

Configuration Considerations

The UART driver configuration can be divided to number of sequential steps listed below:

Note
UART driver is built on top of the SCB hardware block. The SCB5 instance is used as an example for all code snippets. Modify the code to match your design.

Configure UART

To set up the UART driver, provide the configuration parameters in the cy_stc_scb_uart_config_t structure. For example: provide uartMode, oversample, dataWidth, enableMsbFirst, parity, and stopBits. The other parameters are optional. To initialize the driver, call Cy_SCB_UART_Init function providing a pointer to the populated cy_stc_scb_uart_config_t structure and the allocated cy_stc_scb_uart_context_t structure.

/* Allocate context for UART operation */
/* Populate configuration structure */
const cy_stc_scb_uart_config_t uartConfig =
{
.enableMutliProcessorMode = false,
.smartCardRetryOnNack = false,
.irdaInvertRx = false,
.irdaEnableLowPowerReceiver = false,
.enableLinMode = false,
.oversample = 12UL,
.enableMsbFirst = false,
.dataWidth = 8UL,
.enableInputFilter = false,
.breakWidth = 11UL,
.breakLevel = false, /* Only applicable for PSoC 4100S Max */
.dropOnFrameError = false,
.dropOnParityError = false,
.receiverAddress = 0UL,
.receiverAddressMask = 0UL,
.acceptAddrInFifo = false,
.enableCts = false,
.ctsPolarity = CY_SCB_UART_ACTIVE_LOW,
.rtsRxFifoLevel = 0UL,
.rtsPolarity = CY_SCB_UART_ACTIVE_LOW,
.rxFifoTriggerLevel = 0UL,
.rxFifoIntEnableMask = 0UL,
.txFifoTriggerLevel = 0UL,
.txFifoIntEnableMask = 0UL,
};
/* Configure UART to operate */
(void) Cy_SCB_UART_Init(SCB1, &uartConfig, &uartContext);

Assign and Configure Pins

Only dedicated SCB pins can be used for UART operation. The HSIOM register must be configured to connect dedicated SCB UART pins to the SCB block. Also, the UART output pins must be configured in Strong Drive Input Off mode and UART input pins in Digital High-Z:

/* Assign pins for UART on SCB1: P3[0], P3[1] */
#define UART_PORT (P3_0_PORT)
#define UART_RX_NUM (P3_0_NUM)
#define UART_TX_NUM (P3_1_NUM)
#define HSIOM_RX (P3_0_SCB1_UART_RX)
#define HSIOM_TX (P3_1_SCB1_UART_TX)
/* Connect SCB1 UART function to pins */
Cy_GPIO_SetHSIOM(UART_PORT, UART_RX_NUM, HSIOM_RX);
Cy_GPIO_SetHSIOM(UART_PORT, UART_TX_NUM, HSIOM_TX);
/* Configure pins for UART operation */
Cy_GPIO_SetDrivemode(UART_PORT, UART_RX_NUM, CY_GPIO_DM_HIGHZ);
Cy_GPIO_SetDrivemode(UART_PORT, UART_TX_NUM, CY_GPIO_DM_STRONG);

Assign Clock Divider

A clock source must be connected to the SCB block to oversample input and output signals, in this document this clock will be referred as clk_scb. You must use one of available integer or fractional dividers. Use the SysClk (System Clock) driver API to do this.

/* Assign divider type and number for UART */
#define UART_CLK_DIV_TYPE (CY_SYSCLK_DIV_16_BIT)
#define UART_CLK_DIV_NUMBER (0U)
/* Connect assigned divider to be a clock source for UART */
Cy_SysClk_PeriphAssignDivider(PCLK_SCB1_CLOCK, UART_CLK_DIV_TYPE, UART_CLK_DIV_NUMBER);

Configure Baud Rate

To get the UART to operate with the desired baud rate, the clk_scb frequency and the oversample must be configured. Use the SysClk (System Clock) driver API to configure clk_scb frequency. Set the oversample parameter in configuration structure to define the number of the SCB clocks within one UART bit-time.

/* UART desired baud rate is 115200 bps (Standard mode).
* The UART baud rate = (clk_scb / Oversample).
* For clk_peri = 48 MHz, select divider value 36 and get SCB clock = (48 MHz / 35) = 1,371 MHz.
* Select Oversample = 12. These setting results UART data rate = 1,371 MHz / 12 = 114250 bps.
*/
Cy_SysClk_PeriphSetDivider (UART_CLK_DIV_TYPE, UART_CLK_DIV_NUMBER, 35UL);
Cy_SysClk_PeriphEnableDivider(UART_CLK_DIV_TYPE, UART_CLK_DIV_NUMBER);

Refer to the technical reference manual (TRM) section UART sub-section Clocking and Oversampling to get information about how to configure the UART to run with desired baud rate.

Configure Interrupt

The interrupt is optional for the UART operation. To configure interrupt the Cy_SCB_UART_Interrupt function must be called in the interrupt handler for the selected SCB instance. Also, this interrupt must be enabled in the NVIC. The interrupt must be configured when High-Level API will be used.

void UART_Isr(void)
{
Cy_SCB_UART_Interrupt(SCB1, &uartContext);
}
/* Assign UART interrupt number and priority */
#define UART_INTR_NUM ((IRQn_Type) scb_1_interrupt_IRQn)
#define UART_INTR_PRIORITY (3U)
/* Populate configuration structure */
cy_stc_sysint_t uartIntrConfig =
{
.intrSrc = UART_INTR_NUM,
.intrPriority = UART_INTR_PRIORITY,
};
/* Hook interrupt service routine and enable interrupt */
(void) Cy_SysInt_Init(&uartIntrConfig, &UART_Isr);
NVIC_EnableIRQ(UART_INTR_NUM);

Enable UART

Finally, enable the UART operation by calling Cy_SCB_UART_Enable.

/* Enable UART to operate */
/* Enable global interrupts */
__enable_irq();

Common Use Cases

The UART API is divided into two categories: Low-Level and High-Level.
Do not mix High-Level and Low-Level API because a Low-Level API can adversely affect the operation of a High-Level API.

Low-Level API

The Low-Level functions allow interacting directly with the hardware and do not use Cy_SCB_UART_Interrupt. These functions do not require context for operation. Thus, NULL can be passed for context parameter in Cy_SCB_UART_Init and Cy_SCB_UART_Disable instead of a pointer to the context structure.

uint8_t txBuffer[BUFFER_SIZE];
/* Initialize txBuffer with command to transfer */
txBuffer[0] = CMD_START_TRANSFER;
txBuffer[1] = 0x00U;
txBuffer[2] = 0x01U;
Cy_SCB_UART_PutArrayBlocking(SCB1, txBuffer, sizeof(txBuffer));
/* Blocking wait for transfer completion */
{
}

High-Level API

The High-Level API use Cy_SCB_UART_Interrupt to execute the transfer. Call Cy_SCB_UART_Transmit to start transmission. Call Cy_SCB_UART_Receive to start receive operation. After the operation is started the Cy_SCB_UART_Interrupt handles the data transfer until its completion. Therefore Cy_SCB_UART_Interrupt must be called inside the user interrupt handler to make the High-Level API work. To monitor status of transmit operation, use Cy_SCB_UART_GetTransmitStatus and Cy_SCB_UART_GetReceiveStatus to monitor receive status appropriately. Alternatively use Cy_SCB_UART_RegisterCallback to register callback function to be notified about UART Callback Events.

Receive Operation

uint8_t rxBuffer[BUFFER_SIZE];
/* Start receive operation (do not check status) */
(void) Cy_SCB_UART_Receive(SCB1, rxBuffer, sizeof(rxBuffer), &uartContext);
/* Blocking wait until buffer is full */
while (0UL != (CY_SCB_UART_RECEIVE_ACTIVE & Cy_SCB_UART_GetReceiveStatus(SCB1, &uartContext)))
{
}
/* Handle received data */

Transmit Operation

uint8_t txBuffer[BUFFER_SIZE];
/* Initialize txBuffer with data to transfer */
txBuffer[0] = CMD_START_TRANSFER;
txBuffer[1] = 0x00U;
txBuffer[2] = 0x01U;
/* Start transmit operation (do not check status) */
(void) Cy_SCB_UART_Transmit(SCB1, txBuffer, sizeof(txBuffer), &uartContext);
/* Blocking wait for transmission completion */
while (0UL != (CY_SCB_UART_TRANSMIT_ACTIVE & Cy_SCB_UART_GetTransmitStatus(SCB1, &uartContext)))
{
}

There is also capability to insert a receive ring buffer that operates between the RX FIFO and the user buffer. The received data is copied into the ring buffer from the RX FIFO. This process runs in the background after the ring buffer operation is started by Cy_SCB_UART_StartRingBuffer. When Cy_SCB_UART_Receive is called, it first reads data from the ring buffer and then sets up an interrupt to receive more data if the required amount has not yet been read.

DMA Trigger

The SCB provides TX and RX output trigger signals that can be routed to the DMA controller inputs. These signals are assigned based on the data availability in the TX and RX FIFOs appropriately.

To route SCB TX or RX trigger signals to DMA controller use TrigMux (Trigger Multiplexer) driver API.

Note
To properly handle DMA level request signal activation and de-activation from the SCB peripheral block the DMA Descriptor typically must be configured to re-trigger after 16 Clk_Slow cycles.

Low Power Support

The UART driver provides callback functions to handle power mode transition. The callback Cy_SCB_UART_DeepSleepCallback must be called during execution of Cy_SysPm_CpuEnterDeepSleep. To trigger the callback execution, the callback must be registered before calling the power mode transition function. Refer to SysPm (System Power Management) driver for more information about power mode transitions and callback registration.

The UART is disabled during Deep Sleep and and stops driving the output pins. The state of the UART output pins TX and RTS is High-Z, which can cause unexpected behavior of the UART receiver due to possible glitches on these lines. These pins must be set to the inactive state before entering Deep Sleep. These pins must keep the inactive level (the same state when UART TX is enabled and does not transfer data) before entering Deep Sleep mode. To do that, write the GPIO data register of each pin to the inactive level for each output pin. Then configure High-Speed Input Output Multiplexer (HSIOM) of each pin to be controlled by the GPIO (use GPIO (General Purpose Input Output) driver API). After exiting Deep Sleep mode the UART must be enabled and the pins configuration restored to return the UART control of the pins. Copy Cy_SCB_UART_DeepSleepCallback as appropriate, and make the changes described above inside the function. Alternately, external pull-up or pull-down resistors can be connected to the appropriate UART lines to keep them inactive during Deep-Sleep.