UART.md

# UART
## **Overview**
Defines standard APIs of universal asynchronous receiver/transmitter \(UART\) capabilities.
You can use this module to access the UART and enable the driver to operate a UART-compliant device. The functions in this module help you to obtain and release the UART device handle, read and write data, obtain and set the baud rate and device attributes.
**Since:**
1.0
## **Summary**
## Files

File Name	Description
uart_if.h	Declares standard UART APIs.

## Data Structures

Data Structure Name	Description
UartAttribute	Defines basic attributes of the UART port.

## Enumerations

Enumeration Name	Description
UartTransMode {   UART_MODE_RD_BLOCK = 0, UART_MODE_RD_NONBLOCK, UART_MODE_DMA_RX_EN, UART_MODE_DMA_RX_DIS,   UART_MODE_DMA_TX_EN, UART_MODE_DMA_TX_DIS }	Enumerates UART transmission modes.

## Functions

Function Name	Description
UartOpen (uint32_t port)	struct DevHandle *  Obtains the UART device handle.
UartClose (struct DevHandle *handle)	void  Releases the UART device handle.
UartRead (struct DevHandle *handle, uint8_t *data, uint32_t size)	int32_t  Reads data of a specified size from a UART device.
UartWrite (struct DevHandle *handle, uint8_t *data, uint32_t size)	int32_t  Writes data of a specified size into a UART device.
UartGetBaud (struct DevHandle *handle, uint32_t *baudRate)	int32_t  Obtains the baud rate of the UART device.
UartSetBaud (struct DevHandle *handle, uint32_t baudRate)	int32_t  Sets the baud rate for the UART device.
UartGetAttribute (struct DevHandle *handle, struct UartAttribute *attribute)	int32_t  Obtains the UART attribute.
UartSetAttribute (struct DevHandle *handle, struct UartAttribute *attribute)	int32_t  Sets the UART attribute.
UartSetTransMode (struct DevHandle *handle, enum UartTransMode mode)	int32_t  Sets the UART transmission mode.

## **Details**
## **Enumeration Type Documentation**
## UartTransMode
```
enum [UartTransMode](UART.md#gab9e041a0802a7e24da22215b458bf7db)
```
**Description:**
Enumerates UART transmission modes.
**Attention:**
The UART controller determines whether an enumerated transmission mode is supported.

Enumerator	Description
UART_MODE_RD_BLOCK	Blocking mode
UART_MODE_RD_NONBLOCK	Non-blocking mode
UART_MODE_DMA_RX_EN	DMA enabled for data receiving
UART_MODE_DMA_RX_DIS	DMA disabled for data receiving
UART_MODE_DMA_TX_EN	DMA enabled for data transmitting
UART_MODE_DMA_TX_DIS	DMA disabled for data transmitting

## **Function Documentation**
## UartClose\(\)
```
void UartClose (struct [DevHandle](DevHandle.md) * handle)
```
**Description:**
Releases the UART device handle.
If you no longer need to access the UART device, you should call this function to close its handle so as to release unused memory resources.
**Parameters:**

Name	Description
handle	Indicates the pointer to the UART device handle, which is obtained via UartOpen.

## UartGetAttribute\(\)
```
int32_t UartGetAttribute (struct [DevHandle](DevHandle.md) * handle, struct [UartAttribute](UartAttribute.md) * attribute )
```
**Description:**
Obtains the UART attribute.
UART attributes include data bits, stop bits, parity bit, CTS, RTS, and receiving and transmitting FIFO.
**Parameters:**

Name	Description
handle	Indicates the pointer to the UART device handle, which is obtained via UartOpen.
attribute	Indicates the pointer to the obtained UART attribute.

**Returns:**
Returns **0** if the UART attribute is obtained; returns a negative number otherwise.
## UartGetBaud\(\)
```
int32_t UartGetBaud (struct [DevHandle](DevHandle.md) * handle, uint32_t * baudRate )
```
**Description:**
Obtains the baud rate of the UART device.
**Parameters:**

Name	Description
handle	Indicates the pointer to the UART device handle, which is obtained via UartOpen.
baudRate	Indicates the pointer to the obtained baud rate.

**Returns:**
Returns **0** if the baud rate is obtained; returns a negative number otherwise.
## UartOpen\(\)
```
struct [DevHandle](DevHandle.md)* UartOpen (uint32_t port)
```
**Description:**
Obtains the UART device handle.
Before accessing the UART device, you must call this function to obtain the UART device handle.
**Parameters:**

Name	Description
port	Indicates the UART port.

**Returns:**
Returns the pointer to the UART device handle if the handle is obtained; returns **NULL** otherwise.
## UartRead\(\)
```
int32_t UartRead (struct [DevHandle](DevHandle.md) * handle, uint8_t * data, uint32_t size )
```
**Description:**
Reads data of a specified size from a UART device.
**Parameters:**

Name	Description
handle	Indicates the pointer to the UART device handle, which is obtained via UartOpen.
data	Indicates the pointer to the buffer for receiving the data.
size	Indicates the size of the data to read.

**Returns:**
Returns the size of the data that is successfully read; returns a negative number if the reading fails.
## UartSetAttribute\(\)
```
int32_t UartSetAttribute (struct [DevHandle](DevHandle.md) * handle, struct [UartAttribute](UartAttribute.md) * attribute )
```
**Description:**
Sets the UART attribute.
UART attributes include data bits, stop bits, parity bit, CTS, RTS, and receiving and transmitting FIFO.
**Parameters:**

Name	Description
handle	Indicates the pointer to the UART device handle, which is obtained via UartOpen.
attribute	Indicates the pointer to the UART attribute to set.

**Returns:**
Returns **0** if the setting is successful; returns a negative number otherwise.
## UartSetBaud\(\)
```
int32_t UartSetBaud (struct [DevHandle](DevHandle.md) * handle, uint32_t baudRate )
```
**Description:**
Sets the baud rate for the UART device.
**Parameters:**

Name	Description
handle	Indicates the pointer to the UART device handle, which is obtained via UartOpen.
baudRate	Indicates the baud rate to set.

**Returns:**
Returns **0** if the setting is successful; returns a negative number otherwise.
## UartSetTransMode\(\)
```
int32_t UartSetTransMode (struct [DevHandle](DevHandle.md) * handle, enum [UartTransMode](UART.md#gab9e041a0802a7e24da22215b458bf7db) mode )
```
**Description:**
Sets the UART transmission mode.
**Parameters:**

Name	Description
handle	Indicates the pointer to the UART device handle, which is obtained via UartOpen.
mode	Indicates a transmission mode enumerated in {@linkUartTransMode}.

**Returns:**
Returns **0** if the setting is successful; returns a negative number otherwise.
## UartWrite\(\)
```
int32_t UartWrite (struct [DevHandle](DevHandle.md) * handle, uint8_t * data, uint32_t size )
```
**Description:**
Writes data of a specified size into a UART device.
**Parameters:**

Name	Description
handle	Indicates the pointer to the UART device handle, which is obtained via UartOpen.
data	Indicates the pointer to the data to write.
size	Indicates the size of the data to write.

**Returns:**
Returns **0** if the data is successfully written; returns a negative number otherwise.