From 8ab682b615a6c379f7f8480ec1b334bdc7cd6b02 Mon Sep 17 00:00:00 2001 From: king_he <6384784@qq.com> Date: Mon, 16 May 2022 01:29:05 +0000 Subject: [PATCH] update en/device-dev/driver/driver-platform-uart-des.md. Signed-off-by: king_he <6384784@qq.com> --- .../driver/driver-platform-uart-des.md | 61 +++++++++---------- 1 file changed, 30 insertions(+), 31 deletions(-) diff --git a/en/device-dev/driver/driver-platform-uart-des.md b/en/device-dev/driver/driver-platform-uart-des.md index 0d8809f05b..59bcedfd43 100644 --- a/en/device-dev/driver/driver-platform-uart-des.md +++ b/en/device-dev/driver/driver-platform-uart-des.md @@ -2,27 +2,27 @@ ## Overview -- The Universal Asynchronous Receiver/Transmitter \(UART\) is a universal serial data bus used for asynchronous communication. It enables bi-directional communication between devices in full-duplex mode. -- UART is widely used to print information for debugging or to connect to various external modules such as GPS and Bluetooth. -- A UART is connected to other modules through two wires \(as shown in [Figure 1](#fig68294715408)\) or four wires \(as shown in [Figure 2](#fig179241542163112)\). - - TX: TX pin of the transmitting UART. It is connected to the RX pin of the peer UART. - - RX: RX pin of the receiving UART. It is connected to the TX pin of the peer UART. - - RTS: Request to Send signal pin. It is connected to the CTS pin of the peer UART and is used to indicate whether the local UART is ready to receive data. - - CTS: Clear to Send signal pin. It is connected to the RTS pin of the peer UART and is used to indicate whether the local UART is allowed to send data to the peer end. - - **Figure 1** 2-wire UART communication +The Universal Asynchronous Receiver/Transmitter \(UART\) is a universal serial data bus used for asynchronous communication. It enables bi-directional communication between devices in full-duplex mode. +UART is widely used to print information for debugging or to connect to various external modules such as GPS and Bluetooth. +A UART is connected to other modules through two wires \(as shown in [Figure 1](#fig68294715408)\) or four wires \(as shown in [Figure 2](#fig179241542163112)\). +- TX: TX pin of the transmitting UART. It is connected to the RX pin of the peer UART. +- RX: RX pin of the receiving UART. It is connected to the TX pin of the peer UART. +- RTS: Request to Send signal pin. It is connected to the CTS pin of the peer UART and is used to indicate whether the local UART is ready to receive data. +- CTS: Clear to Send signal pin. It is connected to the RTS pin of the peer UART and is used to indicate whether the local UART is allowed to send data to the peer end. + + **Figure 1** 2-wire UART communication ![](figures/2-wire-uart-communication.png "2-wire-uart-communication") - **Figure 2** 4-wire UART communication + **Figure 2** 4-wire UART communication ![](figures/4-wire-uart-communication.png "4-wire-uart-communication") -- The transmitting and receiving UARTs must ensure that they have the same settings on particular attributes such as the baud rate and data format \(start bit, data bit, parity bit, and stop bit\) before they start to communicate. During data transmission, a UART sends data to the peer end over the TX pin and receives data from the peer end over the RX pin. When the size of the buffer used by a UART for storing received data reaches the preset threshold, the RTS signal of the UART changes to **1** \(data cannot be received\), and the peer UART stops sending data to it because its CTS signal does not allow it to send data. -- The UART interface defines a set of common functions for operating a UART port, including obtaining and releasing device handles, reading and writing data of a specified length, and obtaining and setting the baud rate, as well as the device attributes. +The transmitting and receiving UARTs must ensure that they have the same settings on particular attributes such as the baud rate and data format \(start bit, data bit, parity bit, and stop bit\) before they start to communicate. During data transmission, a UART sends data to the peer end over the TX pin and receives data from the peer end over the RX pin. When the size of the buffer used by a UART for storing received data reaches the preset threshold, the RTS signal of the UART changes to **1** \(data cannot be received\), and the peer UART stops sending data to it because its CTS signal does not allow it to send data. +The UART interface defines a set of common functions for operating a UART port, including obtaining and releasing device handles, reading and writing data of a specified length, and obtaining and setting the baud rate, as well as the device attributes. ## Available APIs -**Table 1** APIs for the UART driver +**Table 1** APIs for the UART driver

Capability

@@ -94,7 +94,7 @@
->![](../public_sys-resources/icon-note.gif) **NOTE:** +>![](../public_sys-resources/icon-note.gif) **NOTE**
>All functions provided in this document can be called only in kernel space. ## Usage Guidelines @@ -103,16 +103,16 @@ [Figure 3](#fig99673244388) shows the process of using a UART device. -**Figure 3** Process of using a UART device +**Figure 3** Process of using a UART device ![](figures/process-of-using-a-uart-device.png "process-of-using-a-uart-device") ### Obtaining a UART Device Handle -Before performing UART communication, call **UartOpen** to obtain a UART device handle. This function returns the pointer to the UART device handle with a specified port number. +Before performing UART communication, call **UartOpen** to obtain a UART device handle. This function returns the pointer to the UART device handle with a specified port number. DevHandle UartOpen\(uint32\_t port\); -**Table 2** Description of UartOpen +**Table 2** Description of UartOpen

Parameter

@@ -144,7 +144,7 @@ DevHandle UartOpen\(uint32\_t port\);
-The following example shows how to obtain a UART device handle based on the assumption that the UART port number is **3**: +The following example shows how to obtain a UART device handle based on the assumption that the UART port number is **3**: ``` DevHandle handle = NULL; /* The UART device handle */ @@ -162,7 +162,7 @@ After obtaining the UART device handle, set the UART baud rate by calling the fo int32\_t UartSetBaud\(DevHandle handle, uint32\_t baudRate\); -**Table 3** Description of UartSetBaud +**Table 3** Description of UartSetBaud

Parameter

@@ -199,7 +199,7 @@ int32\_t UartSetBaud\(DevHandle handle, uint32\_t baudRate\);
-The following example shows how to set the UART baud rate to **9600**: +The following example shows how to set the UART baud rate to **9600**: ``` int32_t ret; @@ -216,7 +216,7 @@ After setting the UART baud rate, obtain the current baud rate by calling the fo int32\_t UartGetBaud\(DevHandle handle, uint32\_t \*baudRate\); -**Table 4** Description of UartGetBaud +**Table 4** Description of UartGetBaud

Parameter

@@ -271,7 +271,7 @@ Before performing UART communication, set the UART device attributes by calling int32\_t UartSetAttribute\(DevHandle handle, struct UartAttribute \*attribute\); -**Table 5** Description of UartSetAttribute +**Table 5** Description of UartSetAttribute

Parameter

@@ -333,7 +333,7 @@ After setting the UART device attributes, obtain the current device attributes b int32\_t UartGetAttribute\(DevHandle handle, struct UartAttribute \*attribute\); -**Table 6** Description of UartGetAttribute +**Table 6** Description of UartGetAttribute

Parameter

@@ -388,7 +388,7 @@ Before performing UART communication, set the UART transmission mode by calling int32\_t UartSetTransMode\(DevHandle handle, enum UartTransMode mode\); -**Table 7** Description of UartSetTransMode +**Table 7** Description of UartSetTransMode

Parameter

@@ -425,7 +425,7 @@ int32\_t UartSetTransMode\(DevHandle handle, enum UartTransMode mode\);
-The following example shows how to set the transmission mode to **UART\_MODE\_RD\_BLOCK**: +The following example shows how to set the transmission mode to **UART\_MODE\_RD\_BLOCK**: ``` int32_t ret; @@ -442,7 +442,7 @@ To write data into a UART device, call the following function: int32\_t UartWrite\(DevHandle handle, uint8\_t \*data, uint32\_t size\); -**Table 8** Description of UartWrite +**Table 8** Description of UartWrite

Parameter

@@ -502,7 +502,7 @@ To write data into a UART device, call the following function: int32\_t UartRead\(DevHandle handle, uint8\_t \*data, uint32\_t size\); -**Table 9** Description of UartRead +**Table 9** Description of UartRead

Parameter

@@ -557,7 +557,7 @@ if (ret < 0) { ``` >![](../public_sys-resources/icon-caution.gif) **CAUTION:** ->Data is successfully read from the UART device if a non-negative value is returned. If the return value is **0**, no valid data can be read from the UART device. If the return value is greater than **0**, the return value is the length of the data actually read from the UART device. The length is less than or equal to the value of **size** and does not exceed the maximum length of data to read at a time specified by the UART controller in use. +>Data is successfully read from the UART device if a non-negative value is returned. If the return value is **0**, no valid data can be read from the UART device. If the return value is greater than **0**, the return value is the length of the data actually read from the UART device. The length is less than or equal to the value of **size** and does not exceed the maximum length of data to read at a time specified by the UART controller in use. ### Destroying the UART Device Handle @@ -567,7 +567,7 @@ void UartClose\(DevHandle handle\); This function will release the resources previously obtained. -**Table 10** Description of UartClose +**Table 10** Description of UartClose

Parameter

@@ -655,5 +655,4 @@ _ERR: /* Destroy the UART device handle. */ UartClose(handle); } -``` - +``` \ No newline at end of file -- GitLab