The source files for the UART driver library resides in the emdrv/uartdrv folder, and are named uartdrv.c and uartdrv.h.
The UART driver support the UART capabilities of the USART and UART peripherals, but not the LEUART peripherals. The driver is fully reentrant and multiple driver instances can coexist. The driver does not buffer or queue data, but it queues UART transmit and receive operations. Both blocking and non-blocking transfer functions are available. Non-blocking transfer functions report transfer completion with callback functions. Transfers are done using DMA. Simple direct/forced transmit and receive functions are also available. Note that these functions are blocking and not suitable for low energy applications as they use CPU polling.
UART hardware flow control (CTS/RTS) is fully supported by the driver. UART software flow control (XON/XOFF) is partially supported by the driver. Read more about flow control support in Flow Control Support.
Some properties of the UARTDRV driver are compile-time configurable. These properties are set in a file named uartdrv_config.h. A template for this file, containing default values, resides in the emdrv/config folder. To configure UARTDRV for your application, provide your own configuration file. These are the available configuration parameters with default values defined.
// Maximum concurrent receive operations #define EMDRV_UARTDRV_MAX_CONCURRENT_RX_BUFS 6 // Maximum concurrent transmit operations #define EMDRV_UARTDRV_MAX_CONCURRENT_TX_BUFS 6 // Set to 1 to enable hardware flow control #define EMDRV_UARTDRV_HW_FLOW_CONTROL_ENABLE 1 // Maximum number of driver instances. This maximum applies only when EMDRV_UARTDRV_HW_FLOW_CONTROL_ENABLE = 1 #define EMDRV_UARTDRV_MAX_DRIVER_INSTANCES 4 // UART software flow control code: request peer to start TX #define UARTDRV_FC_SW_XON 0x11 // UART software flow control code: request peer to stop TX #define UARTDRV_FC_SW_XOFF 0x13
The properties of each UART driver instance are set at run-time via the UARTDRV_Init_t data structure input parameter to the UARTDRV_Init() function.
This section contain brief descriptions of the functions in the API. You will find detailed information on input and output parameters and return values by clicking on the hyperlinked function names. Most functions return an error code, ECODE_EMDRV_UARTDRV_OK is returned on success, see ecode.h and uartdrv.h for other error codes.
Your application code must include one header file: uartdrv.h.
UARTDRV_Init(), UARTDRV_DeInit()
These functions initializes or deinitializes the UARTDRV driver. Typically UARTDRV_Init() is called once in your startup code.
UARTDRV_GetReceiveStatus(), UARTDRV_GetTransmitStatus()
Query the status of a current transmit or receive operations. Reports number of items (frames) transmitted and remaining.
UARTDRV_GetReceiveDepth(), UARTDRV_GetTransmitDepth()
Get the number of queued receive or transmit operations.
UARTDRV_Transmit(), UARTDRV_Receive()
UARTDRV_TransmitB(), UARTDRV_ReceiveB()
UARTDRV_ForceTransmit(), UARTDRV_ForceReceive()
Transfer functions come in both blocking and non-blocking versions, the blocking versions have an uppercase B (for Blocking) at the end of their function name. Blocking functions will not return before the transfer has completed. The non-blocking functions signal transfer completion with a callback function. UARTDRV_ForceTransmit() and UARTDRV_ForceReceive() are also blocking. These two functions access the UART peripheral directly without using DMA or interrupts. UARTDRV_ForceTransmit() does not respect flow control. UARTDRV_ForceReceive() forces RTS low.
UARTDRV_Abort()
Abort current transmit or receive operations.
UARTDRV_FlowControlSet(), UARTDRV_FlowControlGetSelfStatus(), UARTDRV_FlowControlGetPeerStatus()
Set and get flow control status of self or peer device. Note that the return value from these two functions depends on the flow control mode set by UARTDRV_FlowControlSet() or UARTDRV_Init().
UARTDRV_FlowControlIgnoreRestrain()
Enables transmission when restrained by flow control.
If UART flow control is not required, make sure EMDRV_UARTDRV_HW_FLOW_CONTROL_ENABLE is set to 0. This reduces the code size and complexity of the driver.
There are two types of flow control supported, hardware and software. To enable any of these, set EMDRV_UARTDRV_HW_FLOW_CONTROL_ENABLE to 1 in uartdrv_config.h.
UART hardware flow control uses two additional pins for flow control handshaking, the clear-to-send (CTS) and ready-to-send (RTS) pins. RTS is an output and CTS is an input. These are active low signals. When CTS is high, the UART transmitter should stop sending frames. A receiver should set RTS high when it is no longer capable of receiving data.
To support hardware flow control, the driver includes the GPIOINT driver to emulate a hardware implementation of UART CTS/RTS flow control. Some revisions of the USART peripheral does not have CTS/RTS hardware support.
To enable hardware flow control, perform the following steps:
RTS is set high whenever there are no RX operations queued. The UART transmitter is halted when the CTS pin goes high. The transmitter completes the current frame before halting. DMA transfers are also halted.
UART software flow control uses in-band signaling, meaning the receiver sends special flow control characters to the transmitter and thereby removes the need for dedicated wires for flow control. The two symbols UARTDRV_FC_SW_XON and UARTDRV_FC_SW_XOFF are defined in uartdrv_config.h.
To enable support for software flow control, perform the following steps:
The application must monitor buffers and make decisions on when to send XON/XOFF. XON/XOFF can be sent to the peer using UARTDRV_FlowControlSet(). If the application implements a specific packet format where the flow control codes may appear only in fixed positions, then the application should not use UARTDRV_FlowControlSet(), but implement read and write of XON/XOFF into packet buffers. If the application code fully implements all the flow control logic, then EMDRV_UARTDRV_HW_FLOW_CONTROL_ENABLE should be set to 0 to reduce code space.
#include "uartdrv.h" // Define receive/transmit operation queues DEFINE_BUF_QUEUE(EMDRV_UARTDRV_MAX_CONCURRENT_RX_BUFS, rxBufferQueueI0); DEFINE_BUF_QUEUE(EMDRV_UARTDRV_MAX_CONCURRENT_TX_BUFS, txBufferQueueI0); // Configuration for USART0, location 1 #define MY_UART \ { \ USART0, \ 115200, \ _USART_ROUTE_LOCATION_LOC1, \ (USART_Stopbits_TypeDef)USART_FRAME_STOPBITS_ONE, \ (USART_Parity_TypeDef)USART_FRAME_PARITY_NONE, \ (USART_OVS_TypeDef)USART_CTRL_OVS_X16, \ false, \ uartdrvFlowControlHw, \ (GPIO_Port_TypeDef)AF_USART0_CS_PORT(_USART_ROUTE_LOCATION_LOC1), \ (GPIO_Port_TypeDef)AF_USART0_CS_PIN(_USART_ROUTE_LOCATION_LOC1), \ (GPIO_Port_TypeDef)AF_USART0_CLK_PORT(_USART_ROUTE_LOCATION_LOC1), \ (GPIO_Port_TypeDef)AF_USART0_CLK_PIN(_USART_ROUTE_LOCATION_LOC1), \ (UARTDRV_Buffer_FifoQueue_t *)&rxBufferQueueI0, \ (UARTDRV_Buffer_FifoQueue_t *)&txBufferQueueI0 \ } UARTDRV_HandleData_t handleData; UARTDRV_Handle_t handle = &handleData; int main(void) { uint8_t buffer[10]; UARTDRV_Init_t initDataA0 = MY_UART; UARTDRV_Init(handle, &initDataA0); // Transmit data using a blocking transmit function UARTDRV_Transmit(handle, buffer, 10); }