UART

概述

Ameba 系列产品支持 UART 接口，能够进行异步串行全双工通信。

功能特性

  • 支持多种 UART 数据格式

  • 可配置的接收时钟，支持低功耗接收模式

  • 支持硬件自动流控

  • 支持接收信号去抖

  • 支持接收波特率监控与校正

  • 支持串行红外编码与解码

  • 工作模式

    • 轮询模式

    • 中断模式

    • DMA 模式

收发时钟

发送时钟与波特率

  • 时钟：XTAL40M

  • 波特率：110bps - 8Mbps

接收时钟与波特率

不同芯片支持的接收时钟可能包括 XTAL40M、OSC2M 和 XTAL2M，各芯片支持的接收时钟如下所示：

RTL8721Dx:

支持的接收时钟包括 XTAL40M 时钟和 OSC2M 时钟。

接收时钟对应的波特率范围如下表所示：

接收时钟

XTAL40M（默认）

OSC2M

XTAL2M

波特率

110bps - 8Mbps

110bps - 115200bps

110bps - 115200bps

工作模式

根据需要，可配置 UART 工作在以下三种模式：

轮询模式

这是最基础的工作模式。CPU 通过轮询 UART 的状态寄存器，然后根据需要读写 FIFO 缓冲区，以实现数据的收发。

适用于对实时性要求较低的小规模数据传输。

中断模式

当满足配置的触发条件时，UART 硬件会发送中断信号通知 CPU 处理相关事务。

该方式无需频繁轮询，使得 CPU 占用率降低且响应速度更快。

DMA 模式

通过 UART 与 DMA 握手机制，由 DMA 控制器负责数据传输，减轻 CPU 的处理负担。

适用于需处理大量数据的应用，如音视频流处理、大数据传输等情境。

  • UART 通过 DMA 模式发送数据，过程由 GDMA 控制。

  • UART 通过 DMA 模式接收数据，过程由 GDMA 或 UART 控制:

    • 如果开发者需要接收 固定长度 的数据，可以利用 GDMA 控制 UART DMA 。

    • 如果开发者需要接收 不固定长度 的数据，可以利用 UART 控制 UART DMA 。

备注

  • 关于使用 DMA 模式传输的注意事项，请参考 DMA 和缓存 介绍。

  • 关于使用 UART DMA 接收的不同方式，请参考 应用示例 中的内容。

硬件自动流控

UART 支持硬件自动流控，通过请求发送 RTS 信号和清除发送 CTS 信号，自动控制数据的传输，避免数据丢失或溢出。

硬件自动流控的收发双方设备连接如图所示：

../../_images/uart_trx_rts_cts.svg

UART 自动流控信号连接

备注

RTS 和 CTS 信号为低电平有效。

RTS 信号行为

  • 设备 A 在准备好接收数据时将其 RTS 信号置为低电平，通知设备 B 可以发送数据。

  • 当设备 A 的接收 FIFO 中的数据量达到配置阈值时，RTS 信号被置为高电平，通知设备 B 不要再发送数据。

  • 当设备 A 的接收 FIFO 中的数据量减少到一定程度，RTS 信号被置为低电平，通知设备 B 可以继续发送数据。

备注

  • RTS 信号一旦被拉高，再次拉低的时刻取决于接收 FIFO 中的数据量。

RTL8721Dx:

接收 FIFO 完全为空 时，RTS 线才会被置为低电平。

CTS 信号行为

设备 A 监控来自设备 B 的 CTS 信号，以判断是否继续发送数据:

  • 当 CTS 信号为低电平，设备 A 可以发送数据。

  • 当 CTS 信号为高电平，设备 A 不发送数据。

应用示例

SDK 提供了两类功能示例，帮助开发者了解和使用 UART 功能：

  • mbed 示例

    • 路径：{SDK}\example\peripheral\mbed\UART\{demo}

    • 展示如何在 mbed 环境中实现 UART 控制。

  • raw 示例

    • 路径：{SDK}\example\peripheral\raw\UART\{demo}

    • 展示如何在无抽象层的情况下直接控制 UART。

以下是对 raw 示例功能的简要说明：

备注

要了解示例支持的芯片，请查看示例路径下的 README.md 文件。

Raw API

UART Exported Types

struct IrDA_InitTypeDef

UART IRDA Init Structure Definition.

Public Members

u32 UART_IrDARxInv

Specifies the uart irda rx invert control. This parameter can be ENABLE or DISABLE. ENABLE: invert the irda input signal. DISABLE: does't invert the irda input signal. This parameter is only used in IrDA mode.

u32 UART_IrDATxInv

Specifies the uart irda tx invert control. This parameter can be ENABLE or DISABLE. ENABLE: invert the irda output signal. DISABLE: does't invert the irda output signal. This parameter is only used in IrDA mode.

u32 UART_UpperShift

Specifies the uart irda tx pulse right edge shift direction. This parameter can be a value of UART IRDA Pulse Shift.

u32 UART_UpperShiftVal

Specifies the uart irda tx pulse right edge shift value in the given direction. This parameter can be a number between 0x0000 and 0x7fff.

u32 UART_LowShift

Specifies the uart irda tx pulse left edge shift direction. This parameter can be a value of UART IRDA Pulse Shift.

u32 UART_LowShiftVal

Specifies the uart irda tx pulse left edge shift value in the given direction. This parameter can be a number between 0x0000 and 0x7fff.

u32 UART_RxFilterThres

Specifies the uart irda rx filter threshold. This parameter can be a number between 0x0000 and 0x7fff This parameter is only used in IrDA mode.

u32 UART_RxFilterCmd

Specifies the uart irda rx filter control. This parameter can be ENABLE or DISABLE. ENABLE: uart IrDA rx filter is used. DISABLE: uart IrDA rx filter is not used. This parameter is only used in IrDA mode.

struct UARTCFG_TypeDef

UART CFG Structure Definition.

Public Members

u32 LOW_POWER_RX_ENABLE
struct UART_DevTable

UART Dev Table Structure Definition.

Public Members

UART_TypeDef *UARTx
u32 Tx_HandshakeInterface
u32 Rx_HandshakeInterface
IRQn_Type IrqNum
struct UART_InitTypeDef

UART Init Structure Definition.

Public Members

u32 DmaModeCtrl

Specifies the uart DMA mode state. This parameter can be ENABLE or DISABLE.

u32 WordLen

Specifies the UART word length. This parameter can be a value of UART Word Length.

u32 StopBit

Specifies the UART stop bit number. This parameter can be a value of UART Stop Bit.

u32 Parity

Specifies the UART parity. This parameter can be a value of UART Parity Enable.

u32 ParityType

Specifies the UART parity type. This parameter can be a value of UART Parity Type.

u32 StickParity

Specifies the UART sticky parity. This parameter can be a value of UART Sticky Parity Type.

u32 FlowControl

Specifies the UART auto flow control. This parameter can be ENABLE or DISABLE.

u32 RxFifoTrigLevel

Specifies the UART rx fifo trigger level. This parameter can be a value of UART Rx FIFO Trigger Level.

u32 RxErReportCtrl

Specifies the UART rx error report control. This parameter can be a value of UART Rx Error Report.

u32 RxTimeOutCnt

Specifies the UART rx time out counter. This parameter can be a number between 0x00 and 0xffff.

UART Exported Constants

UART IRDA Pulse Shift

/* IrDA TX pulse shift left direction. */
#define UART_IRDA_PULSE_LEFT_SHIFT ((u32)0x00000000)

/* IrDA TX pulse shift right direction. */
#define UART_IRDA_PULSE_RIGHT_SHIFT ((u32)0x00000001)

/* Check if IrDA pulse shift value is valid. */
#define IS_IRDA_PUL_SHIFT (((SHIFT) == UART_IRDA_PULSE_LEFT_SHIFT) || \
    ((SHIFT) == UART_IRDA_PULSE_RIGHT_SHIFT))

UART MAUTO FLOW CONTROL define

/* Enable UART auto flow control via AFE and RTS bits. */
#define RUART_MCL_FLOW_ENABLE ((u32)(RUART_BIT_AFE | RUART_BIT_RTS))

UART Parity Enable

/* UART parity disabled. */
#define RUART_PARITY_DISABLE ((u32)0x00000000)

/* UART parity enabled. */
#define RUART_PARITY_ENABLE ((u32)0x00000001)

/* Check if UART parity enable value is valid. */
#define IS_UART_PARITY_ENABLE (((VAL) == RUART_PARITY_DISABLE) || \
    ((VAL) == RUART_PARITY_ENABLE))

UART Parity Type

/* UART parity type: odd. */
#define RUART_ODD_PARITY ((u32)0x00000000)

/* UART parity type: even. */
#define RUART_EVEN_PARITY ((u32)0x00000001)

/* Check if UART parity type value is valid. */
#define IS_UART_PARITY_TYPE (((VAL) == RUART_ODD_PARITY) || \
    ((VAL) == RUART_EVEN_PARITY))

UART Rx Error Report

/* UART Rx error report disabled. */
#define UART_RX_ERROR_REPORT_DISABLE ((u32)0x00000000)

/* UART Rx error report enabled. */
#define UART_RX_ERROR_REPORT_ENABLE ((u32)0x00000001)

/* Check if UART Rx error report value is valid. */
#define IS_UART_RX_ERROR_REPORT (((REPORT) == UART_RX_ERROR_REPORT_DISABLE) || \
    ((REPORT) == UART_RX_ERROR_REPORT_ENABLE))

UART Rx Error Type

/* Bitmask of all Rx error flags. */
#define UART_ALL_RX_ERR (RUART_BIT_RXFIFO_ERR | \
    RUART_BIT_BREAK_INT | \
    RUART_BIT_FRM_ERR | \
    RUART_BIT_PAR_ERR | \
    RUART_BIT_OVR_ERR)

UART Rx FIFO Trigger Level

/* Rx FIFO trigger level: 1 byte. */
#define UART_RX_FIFOTRIG_LEVEL_1BYTES ((u32)0x00000000)
RTL8721Dx: 
/* Rx FIFO trigger level: quarter full. */
#define UART_RX_FIFOTRIG_LEVEL_QUARTER ((u32)0x00000001)

/* Rx FIFO trigger level: half full. */
#define UART_RX_FIFOTRIG_LEVEL_HALF ((u32)0x00000002)

/* Rx FIFO trigger level: depth minus 2. */
#define UART_RX_FIFOTRIG_LEVEL_MINUS2 ((u32)0x00000003)

UART Software Status

/* TX state: DMA transfer in progress. */
#define STATETX_DMA 1

/* TX state: interrupt-driven transfer in progress. */
#define STATETX_INT 2

/* TX state: polling transfer in progress. */
#define STATETX_POLL 3

/* RX state: DMA receive in progress. */
#define STATERX_DMA 1

/* RX state: interrupt-driven receive in progress. */
#define STATERX_INT 2

/* RX state: polling receive in progress. */
#define STATERX_POLL 3

UART Sticky Parity Type

/* UART sticky parity disabled. */
#define RUART_STICK_PARITY_DISABLE ((u32)0x00000000)

/* UART sticky parity enabled. */
#define RUART_STICK_PARITY_ENABLE ((u32)0x00000001)

/* Check if UART sticky parity enable value is valid. */
#define IS_UART_STICK_PARITY_ENABLE (((VAL) == RUART_STICK_PARITY_DISABLE) || \
    ((VAL) == RUART_STICK_PARITY_ENABLE))

UART Stop Bit

/* UART stop bit: 1 stop bit. */
#define RUART_STOP_BIT_1 ((u32)0x00000000)

/* UART stop bit: 2 stop bits. */
#define RUART_STOP_BIT_2 ((u32)0x00000001)

/* Check if UART stop bit value is valid. */
#define IS_UART_STOP_BIT (((VAL) == RUART_STOP_BIT_1) || \
    ((VAL) == RUART_STOP_BIT_2))

UART Word Length

/* UART word length: 7 bits. */
#define RUART_WLS_7BITS ((u32)0x00000000)

/* UART word length: 8 bits. */
#define RUART_WLS_8BITS ((u32)0x00000001)

/* Check if UART word length value is valid. */
#define IS_UART_WLS (((VAL) == RUART_WLS_7BITS) || \
    ((VAL) == RUART_WLS_8BITS))

UART Exported Functions

void UART_IrDACmd(UART_TypeDef *UARTx, u32 NewState)

Enable or disable the IrDA function.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • NewState -- New state of the IrDA. This parameter can be ENABLE or DISABLE.

void UART_IrDAInit(UART_TypeDef *UARTx, IrDA_InitTypeDef *IrDA_InitStruct)

Configure the UART's IrDA interface.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • IrDA_InitStruct -- Pointer to a IrDA_InitTypeDef structure that contains the configuration information of the IrDA module.

void UART_IrDAStructInit(IrDA_InitTypeDef *IrDA_InitStruct)

Fill each IrDA_InitStruct member with its default value.

参数:

  • IrDA_InitStruct -- Pointer to a IrDA_InitTypeDef structure which will be initialized.

void UART_LPRxBaudSet(UART_TypeDef *UARTx, u32 BaudRate, u32 RxIPClockHz)

Set UART baud rate of low power rx path.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • BaudRate -- Desired baud rate.

  • RxIPClockHz -- UART rx clock in Hz.

备注

According to the baud rate calculation formula in low power rx path, CycPerbit = round(fpclock/BaudRate)

void UART_MonitorParaConfig(UART_TypeDef *UARTx, u32 BitNumThres, u32 OscPerbitUpdCtrl)

Configure UART monitor parameters.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • BitNumThres -- Configure bit number threshold of one monitor period.

  • OscPerbitUpdCtrl -- OSC cycnum_perbit update bit, which can be ENABLE or DISABLE.

void UART_RXDMACmd(UART_TypeDef *UARTx, u32 NewState)

Enable or disable UART RX DMA.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • NewState -- New state of UART RX DMA. This parameter can be ENABLE or DISABLE.

void UART_RXDMAConfig(UART_TypeDef *UARTx, u32 RxDmaBurstSize)

Configure UART RX DMA burst size.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • RxDmaBurstSize -- UART RX DMA burst size.

备注

  • RxDmaBurstSize should not be more than half of rxfifo depth.

  • RxDmaBurstSize should not be smaller than GDMA_SrcMsize in function UART_RXGDMA_Init().

  • For better performance, it is suggested to make RxDmaBurstSize be equal to GDMA_SrcMsize, which is 16.

bool UART_RXGDMA_Init(u8 UartIndex, GDMA_InitTypeDef *GDMA_InitStruct, void *CallbackData, IRQ_FUN CallbackFunc, u8 *pRxBuf, u32 RxCount)

Initialize and enable UART RX GDMA.

参数:

  • UartIndex -- UART index, which can be 0~(MAX_UART_INDEX-1).

  • GDMA_InitStruct -- Pointer to a GDMA_InitTypeDef structure that contains configuration information of the GDMA peripheral.

  • CallbackData -- GDMA callback data.

  • CallbackFunc -- GDMA callback function.

  • pRxBuf -- Pointer to rx buffer.

  • RxCount -- Rx count, 0 means using UART as DMA flow controller.

返回:

TRUE or FALSE.

void UART_RxDebounceCmd(UART_TypeDef *UARTx, u32 NewState)

Enable or disable the rx debounce function.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • NewState -- New state of rx debounce function. This parameter can be ENABLE or DISABLE.

void UART_RxDebounceConfig(UART_TypeDef *UARTx, u32 RxDebounceCycle)

Configure UART RX Debounce Cycle.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • RxDebounceCycle -- UART RX Debounce Cycle.

备注

unit is cycle of sclk.

u32 UART_RxMonBaudCtrlRegGet(UART_TypeDef *UARTx)

Get the Monitor Baud Rate control register value of the Low Power Rx Path.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

返回:

The value of the MON_BAUD_CTRL register.

备注

MON_BAUD_CTRL[28:9] field value is the monitor result under OSC 2M Hz Clock.

void UART_RxMonitorCmd(UART_TypeDef *UARTx, u32 NewState)

Enable or disable the monitor function in Low Power Rx Path.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • NewState -- New state of monitoring. This parameter can be ENABLE or DISABLE.

u32 UART_RxMonitorSatusGet(UART_TypeDef *UARTx)

Get the status of the Low Power Rx Monitoring.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

返回:

The value of the REG_MON_BAUD_STS register.

备注

Read this register can clear the monitor interrupt status. Besides, REG_MON_BAUD_STS[19:0] field value is the monitor result under XTAL 2M Hz Clock.

void UART_TXDMACmd(UART_TypeDef *UARTx, u32 NewState)

Enable or disable UART TX DMA.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • NewState -- New state of UART TX DMA. This parameter can be ENABLE or DISABLE.

void UART_TXDMAConfig(UART_TypeDef *UARTx, u32 TxDmaBurstSize)

Configure UART TX DMA burst size.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • TxDmaBurstSize -- UART TX DMA burst size.

备注

  • TxDmaBurstSize should not be smaller than GDMA_DstMsize in function UART_TXGDMA_Init().

  • For better performance, it is suggested to make TxDmaBurstSize be equal to GDMA_DstMsize, which is 4.

bool UART_TXGDMA_Init(u8 UartIndex, GDMA_InitTypeDef *GDMA_InitStruct, void *CallbackData, IRQ_FUN CallbackFunc, u8 *pTxBuf, u32 TxCount)

Initialize and enable UART TX GDMA.

参数:

  • UartIndex -- UART index, which can be 0~(MAX_UART_INDEX-1).

  • GDMA_InitStruct -- Pointer to a GDMA_InitTypeDef structure that contains configuration information of the GDMA peripheral.

  • CallbackData -- GDMA callback data.

  • CallbackFunc -- GDMA callback function.

  • pTxBuf -- Pointer to tx buffer.

  • TxCount -- Tx count.

返回:

TRUE or FALSE.

RTL8721Dx:
void UART_RTSForceCmd(UART_TypeDef *UARTx, u32 NewState)

Force UART RTS_output to be logic 1(inactive) or logic 0(active).

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • NewState --

    This parameter can be one of the following values:

    • ENABLE: Force RTS_output to be inactive, informing peer device to stop sending data.

    • DISABLE: RTS_output stays active until Rx FIFO level reaches RECVTRG and becomes active again, informing peer device to continue sending data.

备注

BIT_AFE should be set to 1 when call UART_RTSForceCmd().

UART Normal Functions

void UART_BaudParaGet(u32 baudrate, u32 *ovsr, u32 *ovsr_adj)

Get ovsr & ovsr_adj parameters according to the given baudrate.

参数:

  • baudrate -- Desired baudrate in bps.

  • ovsr -- Pointer to ovsr parameter.

  • ovsr_adj -- Pointer to ovsr_adj parameter.

void UART_BaudParaGetFull(u32 IPclk, u32 baudrate, u32 *ovsr, u32 *ovsr_adj)

Get ovsr & ovsr_adj parameters according to the given baudrate and UART IP clock.

参数:

  • IPclk -- UART IP clock in Hz.

  • baudrate -- Desired baudrate in bps.

  • ovsr -- Pointer to ovsr parameter.

  • ovsr_adj -- Pointer to ovsr_adj parameter.

void UART_BreakCtl(UART_TypeDef *UARTx, u32 NewState)

Enable or disable UART break control function.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • NewState -- New state of UART Break Signal. This parameter can be ENABLE or DISABLE.

void UART_CharGet(UART_TypeDef *UARTx, u8 *pRxByte)

Receive single data from UART rx FIFO.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • pRxByte -- Pointer to received data.

void UART_CharPut(UART_TypeDef *UARTx, u8 TxData)

Transmit single data to UART tx FIFO.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • TxData -- Data to be transmitted.

u32 UART_ClearRxFifo(UART_TypeDef *UARTx)

Clear Rx FIFO.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

返回:

Rx FIFO is empty or not, which can be a value of:

  • TRUE: Rx FIFO is cleared.

  • FALSE: Rx FIFO is not cleared.

void UART_ClearTxFifo(UART_TypeDef *UARTx)

Clear Tx FIFO.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

void UART_DeInit(UART_TypeDef *UARTx)

Deinitialize the UARTx peripheral registers to their default reset values.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

void UART_INTConfig(UART_TypeDef *UARTx, u32 UART_IT, u32 newState)

Enable or disable specified UARTx interrupt(s).

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • UART_IT -- Specified UARTx interrupt sources to be enabled or disabled. This parameter can be one or a combination of IER register bits.

  • newState -- New state of the specified UARTx interrupts. This parameter can be ENABLE or DISABLE.

void UART_INT_Clear(UART_TypeDef *UARTx, u32 UART_IT)

Clear specified UARTx interrupt status.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • UART_IT -- Specified UARTx interrupt sources to be clear. This parameter can be one or a combination of ICR register bits.

void UART_Init(UART_TypeDef *UARTx, UART_InitTypeDef *UART_InitStruct)

Initialize the UARTx peripheral according to the specified parameters in the UART_InitStruct.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • UART_InitStruct -- Pointer to a UART_InitTypeDef structure that contains the configuration information of the specified UART peripheral.

u32 UART_IntStatus(UART_TypeDef *UARTx)

Get the interrupt identification register value.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

返回:

The interrupt identification register value.

u32 UART_LineStatusGet(UART_TypeDef *UARTx)

Get the Line status register value.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

返回:

The Line status register value.

u32 UART_ModemStatusGet(UART_TypeDef *UARTx)

Get the modem status register value.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

返回:

The modem status register value.

u32 UART_Readable(UART_TypeDef *UARTx)

Check if there is data in rx FIFO.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

返回:

Status value, which can be one of the following values:

  • 1: Rx FIFO has valid data and data can be read from rx FIFO.

  • 0: Rx FIFO is empty.

void UART_ReceiveData(UART_TypeDef *UARTx, u8 *OutBuf, u32 Count)

Receive data from rx FIFO to given buffer.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • OutBuf -- Pointer to buffer to save data read from UART FIFO.

  • Count -- Number of data to be read.

u32 UART_ReceiveDataTO(UART_TypeDef *UARTx, u8 *OutBuf, u32 Count, u32 Times)

Receive data from rx FIFO before timeout.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • OutBuf -- Pointer to buffer to save data read from UART FIFO.

  • Count -- Number of data to be read.

  • Times -- Polling times before timeout.

返回:

Received data length.

void UART_RxByteCntClear(UART_TypeDef *UARTx)

Clear Rx Byte Counter.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

备注

Clear Rx Byte Counter(REG_RX_BYTE_CNT[15:0]) by writing 1 to clr_rx_byte_cnt(REG_RX_BYTE_CNT[16]).

u32 UART_RxByteCntGet(UART_TypeDef *UARTx)

Get Rx Byte Counter Value.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

返回:

The value of Rx Byte Counter.

备注

This counter will be increased by 1 each time reading rx FIFO, no matter rx FIFO is empty or not.

void UART_RxCmd(UART_TypeDef *UARTx, u32 NewState)

Enable or disable UART high rate rx path.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • NewState -- New state of the Rx Path. This parameter can be ENABLE or DISABLE.

备注

Because the TX/RX of the IrDA transceiver are in the same module, RX FIFO can also receive available data when in the process of TX. Therefore, the RX Path must be disabled when TX is going on. Namely, IrDA must work in the Half duplex mode, though normal UART IP supports Full duplex.

void UART_SendData(UART_TypeDef *UARTx, u8 *InBuf, u32 Count)

Transmit data to tx FIFO with polling UART writable status.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • InBuf -- Pointer to buffer to be written to Tx FIFO.

  • Count -- Number of data to be written.

u32 UART_SendDataTO(UART_TypeDef *UARTx, u8 *InBuf, u32 Count, u32 Times)

Transmit data to tx FIFO before timeout.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • InBuf -- Pointer to buffer to be written to Tx FIFO.

  • Count -- Number of data to be written.

  • Times -- Polling times before timeout.

返回:

Transmitted data length.

void UART_SetBaud(UART_TypeDef *UARTx, u32 BaudRate)

Set UART baudrate according to given baudrate.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • BaudRate -- Desired baudrate in bps.

void UART_SetBaudExt(UART_TypeDef *UARTx, u32 Ovsr, u32 Ovsr_adj)

Set UART baudrate according to given baudrate parameter Ovsr & Ovsr_adj.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • Ovsr -- Ovsr parameter, which is related with integer part. This parameter is calculated with UART IP clock and desired baudrate.

  • Ovsr_adj -- Ovsr_adj parameter, which is related with fractional part. This parameter is also calculated with UART IP clock and desired baudrate.

void UART_SetRxLevel(UART_TypeDef *UARTx, u32 FifoLv)

Set UART RX FIFO level to trigger RX interrupt/RTS de-assert.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • FifoLv -- RX FIFO trigger level, this parameter can be one of the values in UART Rx FIFO Trigger Level.

void UART_StructInit(UART_InitTypeDef *UART_InitStruct)

Fill each UART_InitStruct member with its default value.

参数:

  • UART_InitStruct -- Pointer to a UART_InitTypeDef structure which will be initialized.

void UART_WaitBusy(UART_TypeDef *UARTx, u32 PollTimes)

Wait until uart tx completes.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

  • PollTimes -- Polling times before exiting.

u32 UART_Writable(UART_TypeDef *UARTx)

Check if tx FIFO is writable.

参数:

  • UARTx -- UART device pointer, which can be any UARTx_DEV defined in Peripheral Declarations.

返回:

Status value, which can be one of the following values:

  • 1: Tx FIFO is not full and writing data to tx FIFO is ok.

  • 0: Tx FIFO is full.

Mbed API

MBED_UART Exported Types

Enumeration Type

enum FlowControl

UART FlowControl mode used by serial_set_flow_control.

Values:

/* No RTS/CTS. */
FlowControlNone

/* RTS enable. */
FlowControlRTS

/* CTS enable. */
FlowControlCTS

/* RTS/CTS enable. */
FlowControlRTSCTS
enum SerialFifoLevel

Define RX FIFO Level: RX interrupt trigger, RTS de-assert trigger.

Values:

/* RX FIFO trigger level at 1 byte. */
FifoLv1Byte = 0

/* RX FIFO trigger level at quarter full. */
FifoLvQuarter = 1

/* RX FIFO trigger level at half full. */
FifoLvHalf = 2

/* RX FIFO trigger level at nearly full. */
FifoLvFull = 3
enum SerialIrq

UART Interrupt enable/disable used by serial_irq_set.

Values:

/* RX IRQ enable/disable. */
RxIrq

/* TX IRQ enable/disable. */
TxIrq
enum SerialParity

UART Parity mode used by serial_format.

Values:

/* Parity disable. */
ParityNone = 0

/* Odd parity enable. */
ParityOdd = 1

/* Even parity enable. */
ParityEven = 2

/* Sticky parity 1 enable. */
ParityForced1 = 3

/* Sticky parity 0 enable. */
ParityForced0 = 4

Structure Type

typedef struct serial_s serial_t

Serial object type, defined as struct serial_s.

typedef void (*uart_irq_handler)(uint32_t id, SerialIrq event)

Typedef function pointer to point UART interrupt handler.

MBED_UART Exported Functions

void serial_baud(serial_t *obj, int baudrate)

Set UART device baudrate.

参数:

  • obj -- UART object defined in application software.

  • baudrate -- Baud Rate in units of bps, e.g. 115200.

void serial_break_clear(serial_t *obj)

Disable UART break control function.

参数:

  • obj -- UART object defined in application software.

void serial_break_set(serial_t *obj)

Enable UART break control function.

参数:

  • obj -- UART object defined in application software.

void serial_clear(serial_t *obj)

Clear UART Rx FIFO.

参数:

  • obj -- UART object defined in application software.

void serial_clear_rx(serial_t *obj)

Clear UART Rx FIFO.

参数:

  • obj -- UART object defined in application software.

void serial_clear_tx(serial_t *obj)

Clear UART Tx FIFO.

参数:

  • obj -- UART object defined in application software.

void serial_disable(serial_t *obj)

Disable UART clock and function.

参数:

  • obj -- UART object defined in application software.

void serial_enable(serial_t *obj)

Enable UART clock and function.

参数:

  • obj -- UART object defined in application software.

void serial_format(serial_t *obj, int data_bits, SerialParity parity, int stop_bits)

Set UART format.

参数:

  • obj -- UART object defined in application software.

  • data_bits --

    Data bits, this parameter can be one of the following values:

    • 7

    • 8

  • parity --

    Parity type, this parameter can be one of the following values:

    • ParityNone

    • ParityOdd

    • ParityEven

    • ParityForced1

    • ParityForced0

  • stop_bits --

    Stop bit, this parameter can be one of the following values:

    • 2

    • 1

void serial_free(serial_t *obj)

Deinitialize the UART device, including clock, function, interrupt and UART registers.

参数:

  • obj -- UART object defined in application software.

int serial_getc(serial_t *obj)

Get one byte data through UART.

参数:

  • obj -- UART object defined in application software.

返回:

Received character.

备注

This function is a synchronous, blocking API.

void serial_init(serial_t *obj, PinName tx, PinName rx)

Initialize the UART device, including clock, function, interrupt and UART registers.

参数:

  • obj -- UART object defined in application software.

  • tx -- Tx PinName according to pinmux spec.

  • rx -- Rx PinName according to pinmux spec.

void serial_irq_handler(serial_t *obj, uart_irq_handler handler, uint32_t id)

Register UART interrupt handler if needed.

参数:

  • obj -- UART object defined in application software.

  • handler -- UART interrupt callback function.

  • id -- UART interrupt callback parameter.

void serial_irq_set(serial_t *obj, SerialIrq irq, uint32_t enable)

Configure UART interrupt.

参数:

  • obj -- UART object defined in application software.

  • irq --

    Tx or Rx interrupt, this parameter can be one of the following values:

    • RxIrq

    • TxIrq

  • enable --

    This parameter can be one of the following values:

    • 0: Disable specified irq handler.

    • 1: Enable specified irq handler.

void serial_putc(serial_t *obj, int c)

Send one byte data through UART.

参数:

  • obj -- UART object defined in application software.

  • c -- Data to be transmitted.

备注

This function is a synchronous, blocking API.

int serial_readable(serial_t *obj)

Check if there is data in UART Rx FIFO.

参数:

  • obj -- UART object defined in application software.

返回:

Check result, which can be a value of the followings:

  • 1: There is data in Rx FIFO.

  • 0: There is no data in Rx FIFO.

int32_t serial_recv_blocked(serial_t *obj, char *prxbuf, uint32_t len, uint32_t timeout_ms)

Receive data of target length under polling mode before timeout.

参数:

  • obj -- UART object defined in application software.

  • prxbuf -- Pointer to the buffer that saves data read from UART FIFO.

  • len -- Number of data to be received.

  • timeout_ms -- Polling time before timeout in units of ms.

返回:

Bytes of received data.

备注

This function is synchronous API.

void serial_recv_comp_handler(serial_t *obj, void *handler, uint32_t id)

Register UART Rx complete handler.

参数:

  • obj -- UART object defined in application software.

  • handler -- UART Rx complete callback function.

  • id -- UART Rx complete callback parameter.

备注

This function is called when asynchronous API is used.

int32_t serial_recv_stream(serial_t *obj, char *prxbuf, uint32_t len)

Receive data of target length under interrupt mode.

参数:

  • obj -- UART object defined in application software.

  • prxbuf -- Pointer to the buffer that saves data read from UART FIFO.

  • len -- Number of data to be read.

返回:

HAL status, which can be a value of the followings:

  • HAL_OK(0): Success.

  • HAL_BUSY(1): Error.

备注

This function is asynchronous API.

int32_t serial_recv_stream_abort(serial_t *obj)

Stop the stream or stream_dma RX.

参数:

  • obj -- UART object defined in application software.

返回:

Number of Bytes received before stop.

int32_t serial_recv_stream_dma(serial_t *obj, char *prxbuf, uint32_t len)

Receive data of target length under DMA mode.

参数:

  • obj -- UART object defined in application software.

  • prxbuf -- Pointer to the buffer that saves data read from UART FIFO.

  • len -- Number of data to be read.

返回:

HAL status, which can be a value of the followings:

  • HAL_OK(0): Success.

  • HAL_BUSY(1): Error.

备注

This function is asynchronous API.

int32_t serial_recv_stream_dma_timeout(serial_t *obj, char *prxbuf, uint32_t len, uint32_t timeout_ms, void *force_cs)

Receive data under DMA mode before hardware timeout and UART is flow controller.

参数:

  • obj -- UART object defined in application software.

  • prxbuf -- Pointer to the buffer that saves data read from UART FIFO.

  • len -- Maximum received data length before timeout, or unused on platforms where data reception length is determined by hardware timeout only.

  • timeout_ms -- Hardware timeout in ms for Rx.

  • force_cs -- Not used, reserved for compatibility.

返回:

HAL status, which can be a value of the followings:

  • HAL_OK(0): Success.

  • HAL_BUSY(1): Error.

备注

This function is asynchronous API.

int32_t serial_recv_stream_timeout(serial_t *obj, char *prxbuf, uint32_t len, uint32_t timeout_ms, void *force_cs)

Receive data of target length under interrupt mode before timeout.

参数:

  • obj -- UART object defined in application software.

  • prxbuf -- Pointer to the buffer that saves data read from UART FIFO.

  • len -- Number of data to be received.

  • timeout_ms -- Polling time before timeout.

  • force_cs -- Forcing context switch function.

返回:

Bytes of data received before timeout if success or -1 if error happens.

备注

This function is a synchronous, blocking API.

void serial_rx_fifo_level(serial_t *obj, SerialFifoLevel FifoLv)

Set UART Rx FIFO trigger level.

参数:

  • obj -- UART object defined in application software.

  • FifoLv -- FIFO level enum index.

int32_t serial_send_blocked(serial_t *obj, char *ptxbuf, uint32_t len, uint32_t timeout_ms)

Send data of target length under polling mode before timeout.

参数:

  • obj -- UART object defined in application software.

  • ptxbuf -- Pointer to the buffer that saves data to be written to Tx FIFO.

  • len -- Number of data to be sent.

  • timeout_ms -- Polling time before timeout.

返回:

Bytes of transmitted data.

备注

This function is synchronous API.

void serial_send_comp_handler(serial_t *obj, void *handler, uint32_t id)

Register UART Tx complete handler.

参数:

  • obj -- UART object defined in application software.

  • handler -- UART Tx complete callback function.

  • id -- UART Tx complete callback parameter.

备注

This function is called when asynchronous API is used.

int32_t serial_send_stream(serial_t *obj, char *ptxbuf, uint32_t len)

Send data of target length under interrupt mode.

参数:

  • obj -- UART object defined in application software.

  • ptxbuf -- Pointer to the buffer that saves data to be written to Tx FIFO.

  • len -- Number of data to be sent.

返回:

HAL status, which can be a value of the followings:

  • HAL_OK(0): Success.

  • HAL_BUSY(1): Error.

备注

This function is asynchronous API.

int32_t serial_send_stream_abort(serial_t *obj)

Stop the stream or stream_dma TX.

参数:

  • obj -- UART object defined in application software.

返回:

Number of Bytes sent before stop if UART is in Tx state or HAL_OK(0) if not.

int32_t serial_send_stream_dma(serial_t *obj, char *ptxbuf, uint32_t len)

Send data of target length under DMA mode.

参数:

  • obj -- UART object defined in application software.

  • ptxbuf -- Pointer to the buffer that saves data to be written to Tx FIFO.

  • len -- Number of data to be sent.

返回:

HAL status, which can be a value of the followings:

  • HAL_OK(0): Success.

  • HAL_BUSY(1): Error.

备注

This function is asynchronous API.

void serial_set_flow_control(serial_t *obj, FlowControl type, PinName rxflow, PinName txflow)

Set UART auto flow control.

参数:

  • obj -- UART object defined in application software.

  • type -- Auto flow control type.

  • rxflow -- RTS pin.

  • txflow -- CTS pin.

int serial_writable(serial_t *obj)

Check whether it is permitted to write data to UART Tx FIFO.

参数:

  • obj -- UART object defined in application software.

返回:

Check result, which can be a value of the followings:

  • 1: It is ok to write data to Tx FIFO.

  • 0: It is not ok to write data to Tx FIFO.

RTL8721Dx:
void serial_pinout_tx(PinName tx)

Configure UART Tx pinmux.

参数:

  • tx -- Tx PinName according to pinmux spec.

常见问题排查

通过 UART 唤醒丢数据

现象

向UART发送数据唤醒系统，唤醒后发现丢失了部分数据

原因

接收FIFO大小有限，发送数据太长时，系统来不及处理，只能保留一部分数据

解决方法

  • 调整唤醒数据长度，不能大于接收FIFO大小

  • 先利用dummy字符唤醒系统，再发送有效数据

UART 利用 DMA 接收数据时越界

现象

在RTL8721Dx/RTL8720E/RTL8710E/RTL8726E/RTL8713E/RTL8730E上， 运行raw_uart_dma_rx_fc示例进行数据接收时，数据量超出buffer范围

原因

UART控制DMA接收时，电路不会对数据量做限制

解决方法

运行raw_uart_dma_stream示例并打开宏UART_USE_GTIMER_TO， 开发者可以在连续接收的前提下，接收不超过指定数量的数据