diff --git a/en/device-dev/driver/driver-platform-uart-des.md b/en/device-dev/driver/driver-platform-uart-des.md index 20340bfd49d68136a9ca711cca35ca5c2cdb0834..3ddb92b532569df4718931c9c3ca32b7e7e010c1 100644 --- a/en/device-dev/driver/driver-platform-uart-des.md +++ b/en/device-dev/driver/driver-platform-uart-des.md @@ -1,156 +1,86 @@ -# UART +# UART -## 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. +## 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 - ![](figures/2-wire-uart-communication.png "2-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. - - -## Available APIs - -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. - -**Table 1** APIs for the UART driver - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Capability

-

Function

-

Description

-

Obtaining and releasing device handles

-

-

UartOpen

-

Obtains the UART device handle.

-

UartClose

-

Releases a specified UART device handle.

-

Reading and writing data

-

-

UartRead

-

Reads data of a specified length from a UART device.

-

UartWrite

-

Writes data of a specified length into a UART device.

-

Obtaining and setting the baud rate

-

UartGetBaud

-

Obtains the UART baud rate.

-

UartSetBaud

-

Sets the UART baud rate.

-

Obtaining and setting device attributes

-

-

UartGetAttribute

-

Obtains the UART device attributes.

-

UartSetAttribute

-

Sets the UART device attributes.

-

Setting the transmission mode

-

UartSetTransMode

-

Sets the UART transmission mode.

-
- ->![](../public_sys-resources/icon-note.gif) **NOTE**
->All functions provided in this document can be called only in kernel space. - -## Usage Guidelines - -### How to Use + +A UART is connected to other modules through two wires (as shown in Figure 1) or four wires (as shown in Figure 2). + - 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** Two-wire UART communication + + ![](figures/2-wire-uart-communication.png "2-wire-uart-communication") + + **Figure 2** Four-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. + + +## Available APIs + + **Table 1** UART driver APIs + +| API| Description| +| -------- | -------- | +| UartOpen | Obtains a UART device handle.| +| UartClose | Releases a UART device handle.| +| UartRead | Reads data of the specified length from a UART device.| +| UartWrite | Writes data of the specified length to a UART device.| +| UartGetBaud | Obtains the UART baud rate.| +| UartSetBaud | Sets the UART baud rate.| +| UartGetAttribute | Obtains UART device attributes.| +| UartSetAttribute | Sets UART device attributes.| +| UartSetTransMode | Sets the UART transmission mode.| + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+> All APIs described in this document can be called only in kernel mode. + + +## Usage Guidelines + + +### How to Use The figure below illustrates how to use the APIs. -**Figure 3** Using UART driver APIs -![](figures/using-uart-process.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. - -DevHandle UartOpen\(uint32\_t port\); - -**Table 2** Description of UartOpen - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

port

-

UART port number.

-

Return Value

-

Description

-

NULL

-

Failed to obtain the UART device handle.

-

Device handle

-

UART device handle.

-
- -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 */ -uint32_t port = 3; /* UART port number */ + **Figure 3** Using UART driver APIs + + ![](figures/using-UART-process.png) + + +### Opening 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 the specified port number. + + +``` +DevHandle UartOpen(uint32_t port); +``` + + **Table 2** Description of UartOpen + +| Parameter| Description| +| -------- | -------- | +| port | UART port number.| +| **Return Value**| **Description**| +| NULL | The operation failed.| +| Device handle| The operation is successful. The obtained UART device handle is returned.| + + Example: Obtain the device handle of UART port 3. + +``` +DevHandle handle = NULL; /* UART device handle */ +uint32_t port = 3; /* UART port number */ handle = UartOpen(port); if (handle == NULL) { HDF_LOGE("UartOpen: failed!\n"); @@ -158,51 +88,29 @@ if (handle == NULL) { } ``` -### Setting the UART Baud Rate - -After obtaining the UART device handle, set the UART baud rate by calling the following function: - -int32\_t UartSetBaud\(DevHandle handle, uint32\_t baudRate\); - -**Table 3** Description of UartSetBaud - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-

baudRate

-

Baud rate of the UART to set.

-

Return Value

-

Description

-

0

-

Succeeded in setting the UART baud rate.

-

Negative value

-

Failed to set the UART baud rate.

-
- -The following example shows how to set the UART baud rate to **9600**: +### Setting the UART Baud Rate + +Call **UartSetBaud()** to set the UART baud rate. + + +``` +int32_t UartSetBaud(DevHandle handle, uint32_t baudRate); +``` + + **Table 3** Description of UartSetBaud + +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle.| +| baudRate | Baud rate to set.| +| **Return Value**| **Description**| +| 0 | The operation is successful.| +| Negative value| The operation failed.| + +Example: Set the UART baud rate to **9600**. + + ``` int32_t ret; /* Set the UART baud rate to 9600. */ @@ -212,51 +120,29 @@ if (ret != 0) { } ``` -### Obtaining the UART Baud Rate - -After setting the UART baud rate, obtain the current baud rate by calling the following function: - -int32\_t UartGetBaud\(DevHandle handle, uint32\_t \*baudRate\); - -**Table 4** Description of UartGetBaud - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-

baudRate

-

Pointer to the UART baud rate.

-

Return Value

-

Description

-

0

-

Succeeded in obtaining the UART baud rate.

-

Negative value

-

Failed to obtain the UART baud rate.

-
- -The following example shows how to obtain the UART baud rate: +### Obtaining the UART Baud Rate + +Call **UartGetBaud()** to obtain the UART baud rate. + + +``` +int32_t UartGetBaud(DevHandle handle, uint32_t *baudRate); +``` + + **Table 4** Description of UartGetBaud + +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle.| +| baudRate | Pointer to the UART baud rate obtained.| +| **Return Value**| **Description**| +| 0 | The operation is successful.| +| Negative value| The operation failed.| + +Example: Obtain the UART baud rate. + + ``` int32_t ret; uint32_t baudRate; @@ -267,168 +153,102 @@ if (ret != 0) { } ``` -### Setting the UART Device Attributes - -Before performing UART communication, set the UART device attributes by calling the following function: - -int32\_t UartSetAttribute\(DevHandle handle, struct UartAttribute \*attribute\); - -**Table 5** Description of UartSetAttribute - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-

attribute

-

Pointer to the UART device attributes to set.

-

Return Value

-

Description

-

0

-

Succeeded in setting the UART device attributes.

-

Negative value

-

Failed to set the UART device attributes.

-
- -The following example shows how to set the UART device attributes: +### Setting UART Device Attributes + +Call **UartSetAttribute()** to set UART device attributes. + + +``` +int32_t UartSetAttribute(DevHandle handle, struct UartAttribute *attribute); +``` + + **Table 5** Description of UartSetAttribute + +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle.| +| attribute | Pointer to the UART device attributes to set.| +| **Return Value**| **Description**| +| 0 | The operation is successful.| +| Negative value| The operation failed.| + +Example: Set UART device attributes. + + ``` int32_t ret; struct UartAttribute attribute; -attribute.dataBits = UART_ATTR_DATABIT_7; /* Set the number of data bits to 7. */ -attribute.parity = UART_ATTR_PARITY_NONE; /* Set the parity bit to no parity. */ +attribute.dataBits = UART_ATTR_DATABIT_7; /* Enable 7 bits to be transferred each time. */ +attribute.parity = UART_ATTR_PARITY_NONE; /* Disable parity check. */ attribute.stopBits = UART_ATTR_STOPBIT_1; /* Set the stop bit to 1. */ attribute.rts = UART_ATTR_RTS_DIS; /* Disable the RTS signal. */ attribute.cts = UART_ATTR_CTS_DIS; /* Disable the CTS signal. */ attribute.fifoRxEn = UART_ATTR_RX_FIFO_EN; /* Enable RX FIFO. */ attribute.fifoTxEn = UART_ATTR_TX_FIFO_EN; /* Enable TX FIFO. */ -/* Set the UART device attributes. */ +/* Set UART device attributes. */ ret = UartSetAttribute(handle, &attribute); if (ret != 0) { HDF_LOGE("UartSetAttribute: failed, ret %d\n", ret); } ``` -### Obtaining UART Device Attributes - -After setting the UART device attributes, obtain the current device attributes by calling the following function: - -int32\_t UartGetAttribute\(DevHandle handle, struct UartAttribute \*attribute\); - -**Table 6** Description of UartGetAttribute - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-

attribute

-

Pointer to the UART device attributes.

-

Return Value

-

Description

-

0

-

Succeeded in obtaining the UART device attributes.

-

Negative value

-

Failed to obtain the UART device attributes.

-
- -The following example shows how to obtain the UART device attributes: +### Obtaining UART Device Attributes + +Call **UartGetAttribute()** to obtain the current UART device attributes. + + +``` +int32_t UartGetAttribute(DevHandle handle, struct UartAttribute *attribute); +``` + + **Table 6** Description of UartGetAttribute + +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle.| +| attribute | Pointer to the UART device attributes obtained.| +| **Return Value**| **Description**| +| 0 | The operation is successful.| +| Negative value| The operation failed.| + +Example: Obtain UART device attributes. + + ``` int32_t ret; struct UartAttribute attribute; -/* Obtain the UART attributes. */ +/* Obtain UART device attributes. */ ret = UartGetAttribute(handle, &attribute); if (ret != 0) { HDF_LOGE("UartGetAttribute: failed, ret %d\n", ret); } ``` -### Setting the UART Transmission Mode - -Before performing UART communication, set the UART transmission mode by calling the following function: - -int32\_t UartSetTransMode\(DevHandle handle, enum UartTransMode mode\); - -**Table 7** Description of UartSetTransMode - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-

mode

-

UART transmission mode to set.

-

Return Value

-

Description

-

0

-

Succeeded in setting the UART transmission mode.

-

Negative value

-

Failed to set the UART transmission mode.

-
- -The following example shows how to set the transmission mode to **UART\_MODE\_RD\_BLOCK**: +### Setting the UART Transmission Mode + +Call **UartSetTransMode()** to set the UART transmission mode. + + +``` +int32_t UartSetTransMode(DevHandle handle, enum UartTransMode mode); +``` + + **Table 7** Description of UartSetTransMode + +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle.| +| mode | UART transmission mode to set.| +| **Return Value**| **Description**| +| 0 | The operation is successful.| +| Negative value| The operation failed.| + +Example: Set the UART transmission mode to **UART_MODE_RD_BLOCK**. + + ``` int32_t ret; /* Set the UART transmission mode. */ @@ -438,116 +258,64 @@ if (ret != 0) { } ``` -### Writing Data of a Specified Length into a UART Device - -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 - - - - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-

data

-

Pointer to the data to write.

-

size

-

Length of the data to write.

-

Return Value

-

Description

-

0

-

Succeeded in writing data into the UART device.

-

Negative value

-

Failed to write data into the UART device.

-
- -The following example shows how to write data of a specified length into the UART device: +### Writing Data to a UART Device + +Call **UartWrite()** to write data of the specified length to a UART device. + + +``` +int32_t UartWrite(DevHandle handle, uint8_t *data, uint32_t size); +``` + + **Table 8** Description of UartWrite + +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle.| +| data | Pointer to the data to write.| +| size | Length of the data to write.| +| **Return Value**| **Description**| +| 0 | The operation is successful.| +| Negative value| The operation failed.| + +Example: Write data to a UART device. + + ``` int32_t ret; uint8_t wbuff[5] = {1, 2, 3, 4, 5}; -/* Write 5-byte data into the UART device. */ +/* Write 5-byte data to the UART device. */ ret = UartWrite(handle, wbuff, 5); if (ret != 0) { HDF_LOGE("UartWrite: failed, ret %d\n", ret); } ``` -### Reading Data of a Specified Length from a UART Device - -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 - - - - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-

data

-

Pointer to the buffer for receiving the data.

-

size

-

Length of the data to read.

-

Return Value

-

Description

-

Non-negative value

-

Length of the data read from the UART device.

-

Negative value

-

Failed to read data from the UART device.

-
- -The following example shows how to read data of a specified length from the UART device: +### Reading Data from a UART Device + +Call **UartRead()** to read data of the specified length from a UART device. + + +``` +int32_t UartRead(DevHandle handle, uint8_t *data, uint32_t size); +``` + + **Table 9** Description of UartRead + +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle.| +| data | Pointer to the buffer for receiving the data.| +| size | Length of the data to read.| +| **Return Value**| **Description**| +| Non-negative value| The operation is successful. The length of the data read is returned.| +| Negative value| The operation failed.| + +Example: Read data of the specified length from a UART device. + + ``` int32_t ret; uint8_t rbuff[5] = {0}; @@ -558,44 +326,39 @@ 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. +> ![icon-caution.gif](../public_sys-resources/icon-caution.gif) **CAUTION**
+> Data is successfully read from the UART device if a non-negative value is returned. If **0** is returned, no valid data can be read from the UART device. A value greater than **0** indicates the length of the data read from the UART device. The data length must be less than or equal to the value of **size** and cannot exceed the maximum length of the data to read at a time specified by the UART controller in use. -### Destroying the UART Device Handle -After the UART communication, destroy the UART device handle by calling the following function: +### Closing a UART Device Handle -void UartClose\(DevHandle handle\); +Call **UartClose()** to close a UART device handle. -This function will release the resources previously obtained. + +``` +void UartClose(DevHandle handle); +``` -**Table 10** Description of UartClose +This function releases the resources requested by **UartOpen**. - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-
+ **Table 10** Description of UartClose -The following example shows how to destroy the UART device handle: +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle to close.| +Example: Close a UART device handle. + + ``` -UartClose(handle); /* Destroy the UART device handle. */ +UartClose(handle); /* Close the UART device handle. */ ``` -## Usage Example -The following is a usage example of a UART device, including how to obtain the UART device handle, set the baud rate, device attributes, and transmission mode, read data from or write data into the UART device, and then destroy the UART device handle. +## Example + The following example shows how to open a UART device handle, set the baud rate, device attributes, and transmission mode, read data from or write data into the UART device, and then close the UART device handle. + ``` #include "hdf_log.h" #include "uart_if.h" @@ -608,16 +371,16 @@ void UartTestSample(void) uint8_t wbuff[5] = { 1, 2, 3, 4, 5 }; uint8_t rbuff[5] = { 0 }; struct UartAttribute attribute; - attribute.dataBits = UART_ATTR_DATABIT_7; /* Set the number of data bits to 7. */ - attribute.parity = UART_ATTR_PARITY_NONE; /* Set the parity bit to no parity. */ + attribute.dataBits = UART_ATTR_DATABIT_7; /* Enable 7 bits to be transferred each time. */ + attribute.parity = UART_ATTR_PARITY_NONE; /* Disable parity check. */ attribute.stopBits = UART_ATTR_STOPBIT_1; /* Set the stop bit to 1. */ attribute.rts = UART_ATTR_RTS_DIS; /* Disable the RTS signal. */ attribute.cts = UART_ATTR_CTS_DIS; /* Disable the CTS signal. */ attribute.fifoRxEn = UART_ATTR_RX_FIFO_EN; /* Enable RX FIFO. */ attribute.fifoTxEn = UART_ATTR_TX_FIFO_EN; /* Enable TX FIFO. */ - /* Set the UART port number actually used. */ + /* Enter the UART port number. */ port = 1; - /* Obtain the UART device handle. */ + /* Open the UART device handle based on the port number. */ handle = UartOpen(port); if (handle == NULL) { HDF_LOGE("UartOpen: failed!\n"); @@ -629,7 +392,7 @@ void UartTestSample(void) HDF_LOGE("UartSetBaud: failed, ret %d\n", ret); goto _ERR; } - /* Set the UART device attributes. */ + /* Set UART device attributes. */ ret = UartSetAttribute(handle, &attribute); if (ret != 0) { HDF_LOGE("UartSetAttribute: failed, ret %d\n", ret); @@ -641,7 +404,7 @@ void UartTestSample(void) HDF_LOGE("UartSetTransMode: failed, ret %d\n", ret); goto _ERR; } - /* Write 5-byte data into the UART device. */ + /* Write 5-byte data to the UART device. */ ret = UartWrite(handle, wbuff, 5); if (ret != 0) { HDF_LOGE("UartWrite: failed, ret %d\n", ret); @@ -654,7 +417,7 @@ void UartTestSample(void) goto _ERR; } _ERR: - /* Destroy the UART device handle. */ + /* Close the UART device handle. */ UartClose(handle); } -``` \ No newline at end of file +``` diff --git a/en/device-dev/driver/driver-platform-uart-develop.md b/en/device-dev/driver/driver-platform-uart-develop.md index 5f5e3d25e3f8c801251fac77286bcc45489df717..cf3393d01505ceccb7c34b643a9ce218f148ce6c 100644 --- a/en/device-dev/driver/driver-platform-uart-develop.md +++ b/en/device-dev/driver/driver-platform-uart-develop.md @@ -14,7 +14,7 @@ In the Hardware Driver Foundation (HDF), the Universal Asynchronous Receiver/Tra **UartHostMethod**: - + ``` struct UartHostMethod { int32_t (*Init)(struct UartHost *host); @@ -32,18 +32,18 @@ struct UartHostMethod { **Table 1** Description of the callback functions in UartHostMethod -| Function| Input Parameter| Output Parameter| Return Value| Description| +| Function| Input Parameter| Output Parameter| Return Value| Description| | -------- | -------- | -------- | -------- | -------- | -| Init | **host**: structure pointer to the UART controller at the core layer.| –| HDF_STATUS| Initializes a UART device.| -| Deinit | **host**: structure pointer to the UART controller at the core layer.| –| HDF_STATUS| Deinitializes a UART device.| -| Read | **host**: structure pointer to the UART controller at the core layer.
**size**: data size, which is of the uint32_t type.| **data**: pointer to the output data. The value is of the uint8_t type.| HDF_STATUS| Reads data.| -| Write | **host**: structure pointer to the UART controller at the core layer.
**data**: pointer to the input data. The value is of the uint8_t type.
**size**: data size, which is of the uint32_t type.| –| HDF_STATUS| Writes data.| -| SetBaud | **host**: structure pointer to the UART controller at the core layer.
**baudRate**: pointer to the input baud rate. The value is of the uint32_t type. | –| HDF_STATUS| Sets the baud rate.| -| GetBaud | **host**: structure pointer to the UART controller at the core layer.| **baudRate**: pointer to the output baud rate. The value is of the uint32_t type.| HDF_STATUS| Obtains the current baud rate.| -| GetAttribute | **host**: structure pointer to the UART controller at the core layer.| **attribute**: structure pointer to the UART attributes. For details, see **UartAttribute** in **uart_if.h**.| HDF_STATUS| Obtains UART attributes.| -| SetAttribute | **host**: structure pointer to the UART controller at the core layer.
**attribute**: structure pointer to the UART attributes to set.| –| HDF_STATUS| Sets UART attributes.| -| SetTransMode | **host**: structure pointer to the UART controller at the core layer.
**mode**: transfer mode to set. For details, see **UartTransMode** in **uart_if.h**.| –| HDF_STATUS| Sets the UART transfer mode.| -| PollEvent | **host**: structure pointer to the UART controller at the core layer.
**filep**: void pointer to a file.
**table**: void pointer to poll_table.| –| HDF_STATUS| Polls for pending events.| +| Init | **host**: structure pointer to the UART controller at the core layer.| –| HDF_STATUS| Initializes a UART device.| +| Deinit | **host**: structure pointer to the UART controller at the core layer.| –| HDF_STATUS| Deinitializes a UART device.| +| Read | **host**: structure pointer to the UART controller at the core layer.
**size**: data size, which is of the uint32_t type.| **data**: pointer to the data read. The value is of the uint8_t type. | HDF_STATUS| Reads data.| +| Write | **host**: structure pointer to the UART controller at the core layer.
**data**: pointer to the data to write. The value is of the uint8_t type.
**size**: data size, which is of the uint32_t type. | –| HDF_STATUS| Writes data.| +| SetBaud | **host**: structure pointer to the UART controller at the core layer.
**baudRate**: pointer to the baud rate to set. The value is of the uint32_t type. | –| HDF_STATUS| Sets the baud rate.| +| GetBaud | **host**: structure pointer to the UART controller at the core layer.| **baudRate**: pointer to the baud rate obtained. The value is of the uint32_t type. | HDF_STATUS| Obtains the current baud rate.| +| GetAttribute | **host**: structure pointer to the UART controller at the core layer.| **attribute**: structure pointer to the attribute obtained. For details, see **UartAttribute** in **uart_if.h**. | HDF_STATUS| Obtains UART attributes.| +| SetAttribute | **host**: structure pointer to the UART controller at the core layer.
**attribute**: structure pointer to the attribute to set. | –| HDF_STATUS| Sets UART attributes.| +| SetTransMode | **host**: structure pointer to the UART controller at the core layer.
**mode**: transfer mode to set. For details, see **UartTransMode** in **uart_if.h**.| –| HDF_STATUS| Sets the UART transfer mode.| +| PollEvent | **host**: structure pointer to the UART controller at the core layer.
**filep**: void pointer to a file.
**table**: void pointer to poll_table.| –| HDF_STATUS| Polls for pending events.| ## How to Develop @@ -61,10 +61,11 @@ The UART module adaptation involves the following steps: 3. Instantiate the UART controller object. - Initialize **UartHost**. - Instantiate **UartHostMethod** in the **UartHost** object. - > ![icon-note.gif](../public_sys-resources/icon-note.gif) **NOTE**
+ > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> For details about the functions in **UartHostMethod**, see [Available APIs](#available-apis). -4. Debug the driver.
+4. Debug the driver. + (Optional) For new drivers, verify the basic functions, such as the UART status control and response to interrupts. @@ -72,11 +73,16 @@ The UART module adaptation involves the following steps: The following uses **uart_hi35xx.c** as an example to present the information required for implementing device functions. -1. Instantiate the driver entry.
The driver entry must be a global variable of the **HdfDriverEntry** type (defined in **hdf_device_desc.h**), and the value of **moduleName** must be the same as that in **device_info.hcs**. In the HDF, the start address of each **HdfDriverEntry** object of all loaded drivers is collected to form a segment address space similar to an array for the upper layer to invoke. +1. Instantiate the driver entry. + + The driver entry must be a global variable of the **HdfDriverEntry** type (defined in **hdf_device_desc.h**), and the value of **moduleName** must be the same as that in **device_info.hcs**. + + In the HDF, the start address of each **HdfDriverEntry** object of all loaded drivers is collected to form a segment address space similar to an array for the upper layer to invoke. + Generally, the HDF calls the **Bind** function and then the **Init** function to load a driver. If **Init** fails to be called, the HDF calls **Release** to release driver resources and exit. - UART driver entry example: - + UART driver entry example: + ``` struct HdfDriverEntry g_hdfUartDevice = { .moduleVersion = 1, @@ -89,11 +95,15 @@ The following uses **uart_hi35xx.c** as an example to present the information re HDF_INIT(g_hdfUartDevice); ``` -2. Add the **deviceNode** information to the **device_info.hcs** file and configure the device attributes in the **uart_config.hcs** file.
The **deviceNode** information is related to registration of the driver entry. The device attribute values are closely related to the default values or value ranges of the **UartHost** members at the core layer. - In this example, there is only one UART controller. If there are multiple UART controllers, you need to add the **deviceNode** information to the **device_info** file and add the corresponding device attributes to the **uart_config** file for each controller. - - **device_info.hcs** configuration example +2. Add the **deviceNode** information to the **device_info.hcs** file and configure the device attributes in the **uart_config.hcs** file. + + The **deviceNode** information is related to registration of the driver entry. The device attribute values are closely related to the default values or value ranges of the **UartHost** members at the core layer. + + In this example, there is only one UART controller. If there are multiple UART controllers, you need to add the **deviceNode** information to the **device_info** file and add the corresponding device attributes to the **uart_config** file for each controller. + + - **device_info.hcs** configuration example: - + ``` root { device_info { @@ -103,11 +113,11 @@ The following uses **uart_hi35xx.c** as an example to present the information re priority = 50; device_uart :: device { device0 :: deviceNode { - policy = 1; // The driver publishes services only for kernel-mode processes. - priority = 40; // Driver startup priority. - permission = 0644; // Permission for the driver to create a device node. - moduleName = "HDF_PLATFORM_UART"; // Driver name, which must be the same as moduleName in the HdfDriverEntry structure. - serviceName = "HDF_PLATFORM_UART_0";// Unique name of the service published by the driver. The name is in the HDF_PLATFORM_UART_X format. X indicates the UART controller number. + policy = 1; // The driver publishes services only for kernel-mode processes. + priority = 40; // Driver startup priority. + permission = 0644; // Permission for the driver to create a device node. + moduleName = "HDF_PLATFORM_UART"; // Driver name, which must be the same as moduleName in the HdfDriverEntry structure. + serviceName = "HDF_PLATFORM_UART_0"; // Unique name of the service published by the driver. The name is in the HDF_PLATFORM_UART_X format. X indicates the UART controller number. deviceMatchAttr = "hisilicon_hi35xx_uart_0"; // Keyword for matching the private data of the driver. The value must be the same as that of match_attr in the private data configuration table of the driver. } device1 :: deviceNode { @@ -127,20 +137,20 @@ The following uses **uart_hi35xx.c** as an example to present the information re - **uart_config.hcs** configuration example - + ``` root { platform { - template uart_controller { // Template configuration. In the template, you can configure the common parameters shared by device nodes. + template uart_controller { // Template configuration. In the template, you can configure the common parameters shared by device nodes. match_attr = ""; - num = 0; // (Mandatory) Device number - baudrate = 115200; // (Mandatory) Baud rate. Set the value based on service requirements. - fifoRxEn = 1; // (Mandatory) Enable FIFOs to be received. - fifoTxEn = 1; // (Mandatory) Enable FIFOs to be transferred. - flags = 4; // (Mandatory) Flag signal. - regPbase = 0x120a0000; // (Mandatory) Used for address mapping. - interrupt = 38; // (Mandatory) Interrupt number. - iomemCount = 0x48; // (Mandatory) Used for address mapping. + num = 0; // (Mandatory) Device number. + baudrate = 115200; // (Mandatory) Baud rate. Set the value based on service requirements. + fifoRxEn = 1; // (Mandatory) Enable FIFOs to be received. + fifoTxEn = 1; // (Mandatory) Enable FIFOs to be transferred. + flags = 4; // (Mandatory) Flag signal. + regPbase = 0x120a0000; // (Mandatory) Used for address mapping. + interrupt = 38; // (Mandatory) Interrupt number. + iomemCount = 0x48; // (Mandatory) Used for address mapping. } controller_0x120a0000 :: uart_controller { match_attr = "hisilicon_hi35xx_uart_0";// (Mandatory) The value must be the same as that of deviceMatchAttr of the corresponding device in device_info.hcs. @@ -159,43 +169,44 @@ The following uses **uart_hi35xx.c** as an example to present the information re ``` 3. Initialize the **UartHost** object at the core layer, including defining a custom structure (to pass parameters and data) and implementing the **HdfDriverEntry** member functions (**Bind**, **Init**, and **Release**) to instantiate **UartHostMethod** in **UartHost** (so that the underlying driver functions can be called). + - Defining a custom structure To the driver, the custom structure holds parameters and data. The **DeviceResourceIface** method provided by the HDF reads the values in the **uart_config.hcs** file to initialize the members in the custom structure and passes important parameters, such as the device number, to the **UartHost** object at the core layer. - + ``` - struct UartPl011Port { // Interface structure + struct UartPl011Port { // Interface structure int32_t enable; - unsigned long physBase; // Physical address + unsigned long physBase; // Physical address uint32_t irqNum; // Interrupt number - uint32_t defaultBaudrate;// Default baud rate - uint32_t flags; // Flags related to the following three macros. + uint32_t defaultBaudrate; // Default baud rate + uint32_t flags; // Flags related to the following three macros #define PL011_FLG_IRQ_REQUESTED (1 << 0) #define PL011_FLG_DMA_RX_REQUESTED (1 << 1) #define PL011_FLG_DMA_TX_REQUESTED (1 << 2) - struct UartDmaTransfer *rxUdt; // DMA transfer - struct UartDriverData *udd; // The data structure is defined as follows: + struct UartDmaTransfer *rxUdt; // DMA transfer + struct UartDriverData *udd; // The data structure is defined as follows: }; - struct UartDriverData { // Structure related to data transfer + struct UartDriverData { // Structure related to data transfer uint32_t num; - uint32_t baudrate; // Baud rate (configurable) - struct UartAttribute attr; // Attributes, such as the data bit and stop bit, related to data transfer - struct UartTransfer *rxTransfer; // Buffer (FIFO structure) - wait_queue_head_t wait; // Queuing signal related to conditional variables - int32_t count; // Data count - int32_t state; // UART controller state + uint32_t baudrate; // Baud rate (configurable) + struct UartAttribute attr; // Attributes, such as the data bit and stop bit, related to data transfer. + struct UartTransfer *rxTransfer; // Buffer (FIFO structure) + wait_queue_head_t wait; // Queuing signal related to conditional variables + int32_t count; // Data count + int32_t state; // UART controller state #define UART_STATE_NOT_OPENED 0 #define UART_STATE_OPENING 1 #define UART_STATE_USEABLE 2 #define UART_STATE_SUSPENDED 3 - uint32_t flags; // Status flags + uint32_t flags; // Status flags #define UART_FLG_DMA_RX (1 << 0) #define UART_FLG_DMA_TX (1 << 1) #define UART_FLG_RD_BLOCK (1 << 2) - RecvNotify recv; // Pointer to the function that receives serial port data - struct UartOps *ops; // Custom function pointer structure. For details, see device/hisilicon/drivers/uart/uart_pl011.c. - void *private; // It stores the pointer to the start address of UartPl011Port for easy invocation. + RecvNotify recv; // Pointer to the function that receives serial port data. + struct UartOps *ops; // Custom function pointer structure. For details, see device/hisilicon/drivers/uart/uart_pl011.c. + void *private; // It stores the pointer to the start address of UartPl011Port for easy invocation. }; // UartHost is the controller structure at the core layer. The Init function assigns values to the members of UartHost. @@ -205,12 +216,13 @@ The following uses **uart_hi35xx.c** as an example to present the information re uint32_t num; OsalAtomic atom; void *priv; // It stores the pointer to the start address of the vendor's custom structure for easy invocation. - struct UartHostMethod *method; // Hook at the core layer. You need to implement and instantiate its member functions. + struct UartHostMethod *method; // Hook at the core layer. You need to implement and instantiate its member functions. }; ``` + - Instantiating **UartHostMethod** in **UartHost** (other members are initialized by **Bind**) - + ``` // Example in uart_hi35xx.c: instantiate the hook. struct UartHostMethod g_uartHostMethod = { @@ -229,30 +241,30 @@ The following uses **uart_hi35xx.c** as an example to present the information re - **Bind** function - Input parameter: + **Input parameter**: **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information. - Return value: + **Return value**: - HDF_STATUS
The table below describes some status. For more information, see **HDF_STATUS** in the **/drivers/framework/include/utils/hdf_base.h** file. + **HDF_STATUS**
The table below describes some status. For more information, see **HDF_STATUS** in the **/drivers/framework/include/utils/hdf_base.h** file. - **Table 2** HDF_STATUS + **Table 2** Description of HDF_STATUS - | Status| Description| + | Status| Description| | -------- | -------- | - | HDF_ERR_INVALID_OBJECT | Invalid controller object.| - | HDF_ERR_MALLOC_FAIL | Failed to allocate memory.| - | HDF_ERR_INVALID_PARAM | Invalid parameter.| - | HDF_ERR_IO | I/O error.| - | HDF_SUCCESS | Initialization successful.| - | HDF_FAILURE | Initialization failed.| + | HDF_ERR_INVALID_OBJECT | Invalid controller object.| + | HDF_ERR_MALLOC_FAIL | Failed to allocate memory.| + | HDF_ERR_INVALID_PARAM | Invalid parameter.| + | HDF_ERR_IO | I/O error.| + | HDF_SUCCESS | Initialization successful.| + | HDF_FAILURE | Initialization failed.| - Function description: + **Function description**: Initializes the custom structure object and **UartHost**. - + ``` //uart_hi35xx.c static int32_t HdfUartDeviceBind(struct HdfDeviceObject *device) @@ -267,10 +279,10 @@ The following uses **uart_hi35xx.c** as an example to present the information re ... host = (struct UartHost *)OsalMemCalloc(sizeof(*host));// Allocate memory. ... - host->device = device; // (Mandatory) Prerequisites for conversion between HdfDeviceObject and UartHost - device->service = &(host->service; // (Mandatory) Prerequisites for conversion between HdfDeviceObject and UartHost - host->device->service->Dispatch = UartIoDispatch;// Assign values to Dispatch of service. - OsalAtomicSet(&host->atom, 0); // Initialize or set the atomic services. + host->device = device; // (Mandatory) Prerequisites for conversion between HdfDeviceObject and UartHost. + device->service = &(host->service; // (Mandatory) Prerequisites for conversion between HdfDeviceObject and UartHost. + host->device->service->Dispatch = UartIoDispatch; // Assign values to Dispatch of service. + OsalAtomicSet(&host->atom, 0); // Initialize or set the atomic services. host->priv = NULL; host->method = NULL; return host; @@ -279,19 +291,19 @@ The following uses **uart_hi35xx.c** as an example to present the information re - **Init** function - Input parameter: + **Input parameter**: **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information. - Return value: + **Return value**: - HDF_STATUS + **HDF_STATUS** - Function description: + **Function description**: Initializes the custom structure object and **UartHost**, calls the **artAddDev** function at the core layer, and connects to the VFS. - + ``` int32_t HdfUartDeviceInit(struct HdfDeviceObject *device) { @@ -303,7 +315,7 @@ The following uses **uart_hi35xx.c** as an example to present the information re ... ret = Hi35xxAttach(host, device); // Initialize the UartHost object. ... - host->method = &g_uartHostMethod; // Hook the UartHostMethod instance. + host->method = &g_uartHostMethod; // Attach the UartHostMethod instance. return ret; } // Initialize UartHost. @@ -351,30 +363,34 @@ The following uses **uart_hi35xx.c** as an example to present the information re ``` - **Release** function - Input parameter: + **Input parameter**: **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information. - Return value: + **Return value**: No value is returned. - Function description: + **Function description**: - Releases the memory and deletes the controller. This function assigns values to the **Release** API in the driver entry structure. When the HDF fails to call the **Init** function to initialize the driver, the **Release** function can be called to release driver resources. All forced conversion operations for obtaining the corresponding object can be successful only when **Init()** has the corresponding value assignment operations. + Releases the memory and deletes the controller. This function assigns values to the **Release** API in the driver entry structure. When the HDF fails to call the **Init** function to initialize the driver, the **Release** function can be called to release driver resources. - + > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** + > + > All forced conversion operations for obtaining the corresponding object can be successful only when **Init()** has the corresponding value assignment operations. + + ``` void HdfUartDeviceRelease(struct HdfDeviceObject *device) { struct UartHost *host = NULL; ... - host = UartHostFromDevice(device);// Forcibly convert HdfDeviceObject to UartHost by using service. For details about the value assignment, see the Bind function. + host = UartHostFromDevice(device); // Forcibly convert HdfDeviceObject to UartHost by using service. For details about the value assignment, see the Bind function. ... if (host->priv != NULL) { - Hi35xxDetach(host); // Customized memory release function. + Hi35xxDetach(host); // Customized memory release function. } - UartHostDestroy(host); // Call the function of the core layer to release the host. + UartHostDestroy(host); // Call the function of the core layer to release the host. } static void Hi35xxDetach(struct UartHost *host) @@ -382,10 +398,10 @@ The following uses **uart_hi35xx.c** as an example to present the information re struct UartDriverData *udd = NULL; struct UartPl011Port *port = NULL; ... - udd = host->priv; // Convert UartHost to UartDriverData. + udd = host->priv; // The conversion from UartHost to UartDriverData is involved. ... - UartRemoveDev(host);// Remove the VFS. - port = udd->private;// Convert UartDriverData to UartPl011Port. + UartRemoveDev (host); // Remove the VFS. + port = udd->private; // The conversion from UartDriverData to UartPl011Port is involved. if (port != NULL) { if (port->physBase != 0) { OsalIoUnmap((void *)port->physBase);// Unmap addresses. @@ -393,7 +409,7 @@ The following uses **uart_hi35xx.c** as an example to present the information re OsalMemFree(port); udd->private = NULL; } - OsalMemFree(udd);//Release UartDriverData. + OsalMemFree (udd); // Release UartDriverData. host->priv = NULL; } ```