1# UART<a name="EN-US_TOPIC_0000001052215244"></a> 2 3- [Overview](#section833012453535) 4 - [Available APIs](#section1680292311549) 5 6- [Usage Guidelines](#section12779050105412) 7 - [How to Use](#section1858116395510) 8 - [Obtaining a UART Device Handle](#section124512065617) 9 - [Setting the UART Baud Rate](#section86881004579) 10 - [Obtaining the UART Baud Rate](#section897032965712) 11 - [Setting the UART Device Attributes](#section129141884588) 12 - [Obtaining UART Device Attributes](#section18689637165812) 13 - [Setting the UART Transmission Mode](#section72713435918) 14 - [Writing Data of a Specified Length into a UART Device](#section128001736155919) 15 - [Reading Data of a Specified Length from a UART Device](#section92851601604) 16 - [Destroying the UART Device Handle](#section1477410521406) 17 18- [Usage Example](#section35404241311) 19 20## Overview<a name="section833012453535"></a> 21 22- 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. 23- UART is widely used to print information for debugging or to connect to various external modules such as GPS and Bluetooth. 24- A UART is connected to other modules through two wires \(as shown in [Figure 1](#fig209936401896)\) or four wires \(as shown in [Figure 2](#fig1435614171015)\). 25 - TX: TX pin of the transmitting UART. It is connected to the RX pin of the peer UART. 26 - RX: RX pin of the receiving UART. It is connected to the TX pin of the peer UART. 27 - 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. 28 - 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. 29 30 **Figure 1** 2-wire UART communication<a name="fig209936401896"></a> 31 32 33  34 35 **Figure 2** 4-wire UART communication<a name="fig1435614171015"></a> 36 37 38  39 40 41- 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. 42- 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. 43 44### Available APIs<a name="section1680292311549"></a> 45 46**Table 1** APIs for the UART driver 47 48<a name="table1731550155318"></a> 49<table><thead align="left"><tr id="row1223152681611"><th class="cellrowborder" valign="top" width="26.619999999999997%" id="mcps1.2.4.1.1"><p id="p210413571619"><a name="p210413571619"></a><a name="p210413571619"></a><strong id="b4100105545211"><a name="b4100105545211"></a><a name="b4100105545211"></a>Capability</strong></p> 50</th> 51<th class="cellrowborder" valign="top" width="31.369999999999997%" id="mcps1.2.4.1.2"><p id="p810403511614"><a name="p810403511614"></a><a name="p810403511614"></a><strong id="b1653121711186"><a name="b1653121711186"></a><a name="b1653121711186"></a>Function</strong></p> 52</th> 53<th class="cellrowborder" valign="top" width="42.01%" id="mcps1.2.4.1.3"><p id="p110418354161"><a name="p110418354161"></a><a name="p110418354161"></a><strong id="b69108168153412"><a name="b69108168153412"></a><a name="b69108168153412"></a>Description</strong></p> 54</th> 55</tr> 56</thead> 57<tbody><tr id="row1638573613415"><td class="cellrowborder" rowspan="2" valign="top" width="26.619999999999997%" headers="mcps1.2.4.1.1 "><p id="p917154316414"><a name="p917154316414"></a><a name="p917154316414"></a>Obtaining and releasing device handles</p> 58<p id="p9596111154212"><a name="p9596111154212"></a><a name="p9596111154212"></a></p> 59</td> 60<td class="cellrowborder" valign="top" width="31.369999999999997%" headers="mcps1.2.4.1.2 "><p id="p20385163614412"><a name="p20385163614412"></a><a name="p20385163614412"></a>UartOpen</p> 61</td> 62<td class="cellrowborder" valign="top" width="42.01%" headers="mcps1.2.4.1.3 "><p id="p12101135184213"><a name="p12101135184213"></a><a name="p12101135184213"></a>Obtains the UART device handle.</p> 63</td> 64</tr> 65<tr id="row5950143316415"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p149501733134113"><a name="p149501733134113"></a><a name="p149501733134113"></a>UartClose</p> 66</td> 67<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p371073520422"><a name="p371073520422"></a><a name="p371073520422"></a>Releases a specified UART device handle.</p> 68</td> 69</tr> 70<tr id="row34145016535"><td class="cellrowborder" rowspan="2" valign="top" width="26.619999999999997%" headers="mcps1.2.4.1.1 "><p id="p229610227124"><a name="p229610227124"></a><a name="p229610227124"></a>Reading and writing data</p> 71<p id="p131072201215"><a name="p131072201215"></a><a name="p131072201215"></a></p> 72</td> 73<td class="cellrowborder" valign="top" width="31.369999999999997%" headers="mcps1.2.4.1.2 "><p id="p8296182221219"><a name="p8296182221219"></a><a name="p8296182221219"></a>UartRead</p> 74</td> 75<td class="cellrowborder" valign="top" width="42.01%" headers="mcps1.2.4.1.3 "><p id="p16297172213125"><a name="p16297172213125"></a><a name="p16297172213125"></a>Reads data of a specified length from a UART device.</p> 76</td> 77</tr> 78<tr id="row11585016539"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1095722493616"><a name="p1095722493616"></a><a name="p1095722493616"></a>UartWrite</p> 79</td> 80<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p15297162215122"><a name="p15297162215122"></a><a name="p15297162215122"></a>Writes data of a specified length into a UART device.</p> 81</td> 82</tr> 83<tr id="row8687115843715"><td class="cellrowborder" rowspan="2" valign="top" width="26.619999999999997%" headers="mcps1.2.4.1.1 "><p id="p196317143813"><a name="p196317143813"></a><a name="p196317143813"></a>Obtaining and setting the baud rate</p> 84</td> 85<td class="cellrowborder" valign="top" width="31.369999999999997%" headers="mcps1.2.4.1.2 "><p id="p166885582375"><a name="p166885582375"></a><a name="p166885582375"></a>UartGetBaud</p> 86</td> 87<td class="cellrowborder" valign="top" width="42.01%" headers="mcps1.2.4.1.3 "><p id="p13688358183716"><a name="p13688358183716"></a><a name="p13688358183716"></a>Obtains the UART baud rate.</p> 88</td> 89</tr> 90<tr id="row18987529382"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p698719214383"><a name="p698719214383"></a><a name="p698719214383"></a>UartSetBaud</p> 91</td> 92<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1398712123810"><a name="p1398712123810"></a><a name="p1398712123810"></a>Sets the UART baud rate.</p> 93</td> 94</tr> 95<tr id="row1551850115317"><td class="cellrowborder" rowspan="2" valign="top" width="26.619999999999997%" headers="mcps1.2.4.1.1 "><p id="p1629782201218"><a name="p1629782201218"></a><a name="p1629782201218"></a>Obtaining and setting device attributes</p> 96<p id="p10308192211216"><a name="p10308192211216"></a><a name="p10308192211216"></a></p> 97</td> 98<td class="cellrowborder" valign="top" width="31.369999999999997%" headers="mcps1.2.4.1.2 "><p id="p32972022151218"><a name="p32972022151218"></a><a name="p32972022151218"></a>UartGetAttribute</p> 99</td> 100<td class="cellrowborder" valign="top" width="42.01%" headers="mcps1.2.4.1.3 "><p id="p13297122216123"><a name="p13297122216123"></a><a name="p13297122216123"></a>Obtains the UART device attributes.</p> 101</td> 102</tr> 103<tr id="row7545065311"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p102974224120"><a name="p102974224120"></a><a name="p102974224120"></a>UartSetAttribute</p> 104</td> 105<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p152971322111219"><a name="p152971322111219"></a><a name="p152971322111219"></a>Sets the UART device attributes.</p> 106</td> 107</tr> 108<tr id="row14614115403"><td class="cellrowborder" valign="top" width="26.619999999999997%" headers="mcps1.2.4.1.1 "><p id="p1746281144010"><a name="p1746281144010"></a><a name="p1746281144010"></a>Setting the transmission mode</p> 109</td> 110<td class="cellrowborder" valign="top" width="31.369999999999997%" headers="mcps1.2.4.1.2 "><p id="p1146215112405"><a name="p1146215112405"></a><a name="p1146215112405"></a>UartSetTransMode</p> 111</td> 112<td class="cellrowborder" valign="top" width="42.01%" headers="mcps1.2.4.1.3 "><p id="p11303181216414"><a name="p11303181216414"></a><a name="p11303181216414"></a>Sets the UART transmission mode.</p> 113</td> 114</tr> 115</tbody> 116</table> 117 118> **NOTE:** 119>All functions provided in this document can be called only in kernel space. 120 121## Usage Guidelines<a name="section12779050105412"></a> 122 123### How to Use<a name="section1858116395510"></a> 124 125[Figure 3](#fig1852173020185) shows the process of using a UART device. 126 127**Figure 3** Process of using a UART device<a name="fig1852173020185"></a> 128 129 130 131 132### Obtaining a UART Device Handle<a name="section124512065617"></a> 133 134Before 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. 135 136DevHandle UartOpen\(uint32\_t port\); 137 138**Table 2** Description of UartOpen 139 140<a name="table14222165114310"></a> 141<table><thead align="left"><tr id="row1022175133111"><th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.1"><p id="p13221551153117"><a name="p13221551153117"></a><a name="p13221551153117"></a><strong id="b538194163718"><a name="b538194163718"></a><a name="b538194163718"></a>Parameter</strong></p> 142</th> 143<th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.2"><p id="p122211251103111"><a name="p122211251103111"></a><a name="p122211251103111"></a><strong id="b20924204203714"><a name="b20924204203714"></a><a name="b20924204203714"></a>Description</strong></p> 144</th> 145</tr> 146</thead> 147<tbody><tr id="row6222451133114"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p92221518315"><a name="p92221518315"></a><a name="p92221518315"></a>port</p> 148</td> 149<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p1322217518318"><a name="p1322217518318"></a><a name="p1322217518318"></a>UART port number.</p> 150</td> 151</tr> 152<tr id="row1122245153112"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p102221451123118"><a name="p102221451123118"></a><a name="p102221451123118"></a><strong id="b101754483378"><a name="b101754483378"></a><a name="b101754483378"></a>Return Value</strong></p> 153</td> 154<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p1122215143113"><a name="p1122215143113"></a><a name="p1122215143113"></a><strong id="b647184919374"><a name="b647184919374"></a><a name="b647184919374"></a>Description</strong></p> 155</td> 156</tr> 157<tr id="row522275114317"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p422235114313"><a name="p422235114313"></a><a name="p422235114313"></a>NULL</p> 158</td> 159<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p5222351203112"><a name="p5222351203112"></a><a name="p5222351203112"></a>Failed to obtain the UART device handle.</p> 160</td> 161</tr> 162<tr id="row1222212513311"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p5222125115316"><a name="p5222125115316"></a><a name="p5222125115316"></a>Device handle</p> 163</td> 164<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p192228515311"><a name="p192228515311"></a><a name="p192228515311"></a>UART device handle.</p> 165</td> 166</tr> 167</tbody> 168</table> 169 170The following example shows how to obtain a UART device handle based on the assumption that the UART port number is **3**: 171 172``` 173DevHandle handle = NULL; /* The UART device handle */ 174uint32_t port = 3; /* UART port number */ 175handle = UartOpen(port); 176if (handle == NULL) { 177 HDF_LOGE("UartOpen: failed!\n"); 178 return; 179} 180``` 181 182### Setting the UART Baud Rate<a name="section86881004579"></a> 183 184After obtaining the UART device handle, set the UART baud rate by calling the following function: 185 186int32\_t UartSetBaud\(DevHandle handle, uint32\_t baudRate\); 187 188**Table 3** Description of UartSetBaud 189 190<a name="table539135313325"></a> 191<table><thead align="left"><tr id="row15391205311323"><th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.1"><p id="p11390453103216"><a name="p11390453103216"></a><a name="p11390453103216"></a><strong id="b0704124143717"><a name="b0704124143717"></a><a name="b0704124143717"></a>Parameter</strong></p> 192</th> 193<th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.2"><p id="p839065316328"><a name="p839065316328"></a><a name="p839065316328"></a><strong id="b10127164520376"><a name="b10127164520376"></a><a name="b10127164520376"></a>Description</strong></p> 194</th> 195</tr> 196</thead> 197<tbody><tr id="row2039115373216"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p1639165310324"><a name="p1639165310324"></a><a name="p1639165310324"></a>handle</p> 198</td> 199<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p539115320328"><a name="p539115320328"></a><a name="p539115320328"></a>UART device handle.</p> 200</td> 201</tr> 202<tr id="row163911753143214"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p13911653203215"><a name="p13911653203215"></a><a name="p13911653203215"></a>baudRate</p> 203</td> 204<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p163919537322"><a name="p163919537322"></a><a name="p163919537322"></a>Baud rate of the UART to set.</p> 205</td> 206</tr> 207<tr id="row539155343218"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p1039185313321"><a name="p1039185313321"></a><a name="p1039185313321"></a><strong id="b1551834812373"><a name="b1551834812373"></a><a name="b1551834812373"></a>Return Value</strong></p> 208</td> 209<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p123911753143213"><a name="p123911753143213"></a><a name="p123911753143213"></a><strong id="b43667492373"><a name="b43667492373"></a><a name="b43667492373"></a>Description</strong></p> 210</td> 211</tr> 212<tr id="row2391853153218"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p17391185310322"><a name="p17391185310322"></a><a name="p17391185310322"></a>0</p> 213</td> 214<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p14391653193210"><a name="p14391653193210"></a><a name="p14391653193210"></a>Succeeded in setting the UART baud rate.</p> 215</td> 216</tr> 217<tr id="row23912053143211"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p7391165320321"><a name="p7391165320321"></a><a name="p7391165320321"></a>Negative value</p> 218</td> 219<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p639185318322"><a name="p639185318322"></a><a name="p639185318322"></a>Failed to set the UART baud rate.</p> 220</td> 221</tr> 222</tbody> 223</table> 224 225The following example shows how to set the UART baud rate to **9600**: 226 227``` 228int32_t ret; 229/* Set the UART baud rate to 9600. */ 230ret = UartSetBaud(handle, 9600); 231if (ret != 0) { 232 HDF_LOGE("UartSetBaud: failed, ret %d\n", ret); 233} 234``` 235 236### Obtaining the UART Baud Rate<a name="section897032965712"></a> 237 238After setting the UART baud rate, obtain the current baud rate by calling the following function: 239 240int32\_t UartGetBaud\(DevHandle handle, uint32\_t \*baudRate\); 241 242**Table 4** Description of UartGetBaud 243 244<a name="table20393185311326"></a> 245<table><thead align="left"><tr id="row19392653123215"><th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.1"><p id="p6392105315326"><a name="p6392105315326"></a><a name="p6392105315326"></a><strong id="b13706541173716"><a name="b13706541173716"></a><a name="b13706541173716"></a>Parameter</strong></p> 246</th> 247<th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.2"><p id="p53920531329"><a name="p53920531329"></a><a name="p53920531329"></a><strong id="b15128194510378"><a name="b15128194510378"></a><a name="b15128194510378"></a>Description</strong></p> 248</th> 249</tr> 250</thead> 251<tbody><tr id="row103921553103211"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p1539220536326"><a name="p1539220536326"></a><a name="p1539220536326"></a>handle</p> 252</td> 253<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p6392553203217"><a name="p6392553203217"></a><a name="p6392553203217"></a>UART device handle.</p> 254</td> 255</tr> 256<tr id="row1539211532322"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p93921053123210"><a name="p93921053123210"></a><a name="p93921053123210"></a>baudRate</p> 257</td> 258<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p93926536328"><a name="p93926536328"></a><a name="p93926536328"></a>Pointer to the UART baud rate.</p> 259</td> 260</tr> 261<tr id="row1239318531326"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p17392653123213"><a name="p17392653123213"></a><a name="p17392653123213"></a><strong id="b55191048113716"><a name="b55191048113716"></a><a name="b55191048113716"></a>Return Value</strong></p> 262</td> 263<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p1339365316327"><a name="p1339365316327"></a><a name="p1339365316327"></a><strong id="b193671249193713"><a name="b193671249193713"></a><a name="b193671249193713"></a>Description</strong></p> 264</td> 265</tr> 266<tr id="row143939531328"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p2393953153213"><a name="p2393953153213"></a><a name="p2393953153213"></a>0</p> 267</td> 268<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p8393165383218"><a name="p8393165383218"></a><a name="p8393165383218"></a>Succeeded in obtaining the UART baud rate.</p> 269</td> 270</tr> 271<tr id="row5393105363210"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p17393125363215"><a name="p17393125363215"></a><a name="p17393125363215"></a>Negative value</p> 272</td> 273<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p1539325393211"><a name="p1539325393211"></a><a name="p1539325393211"></a>Failed to obtain the UART baud rate.</p> 274</td> 275</tr> 276</tbody> 277</table> 278 279The following example shows how to obtain the UART baud rate: 280 281``` 282int32_t ret; 283uint32_t baudRate; 284/* Obtain the UART baud rate. */ 285ret = UartGetBaud(handle, &baudRate); 286if (ret != 0) { 287 HDF_LOGE("UartGetBaud: failed, ret %d\n", ret); 288} 289``` 290 291### Setting the UART Device Attributes<a name="section129141884588"></a> 292 293Before performing UART communication, set the UART device attributes by calling the following function: 294 295int32\_t UartSetAttribute\(DevHandle handle, struct UartAttribute \*attribute\); 296 297**Table 5** Description of UartSetAttribute 298 299<a name="table1453119335341"></a> 300<table><thead align="left"><tr id="row3530433103416"><th class="cellrowborder" valign="top" width="49.980000000000004%" id="mcps1.2.3.1.1"><p id="p1853073310341"><a name="p1853073310341"></a><a name="p1853073310341"></a><strong id="b8706441133719"><a name="b8706441133719"></a><a name="b8706441133719"></a>Parameter</strong></p> 301</th> 302<th class="cellrowborder" valign="top" width="50.019999999999996%" id="mcps1.2.3.1.2"><p id="p553083393417"><a name="p553083393417"></a><a name="p553083393417"></a><strong id="b16129154519371"><a name="b16129154519371"></a><a name="b16129154519371"></a>Description</strong></p> 303</th> 304</tr> 305</thead> 306<tbody><tr id="row55303331347"><td class="cellrowborder" valign="top" width="49.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p1530113313341"><a name="p1530113313341"></a><a name="p1530113313341"></a>handle</p> 307</td> 308<td class="cellrowborder" valign="top" width="50.019999999999996%" headers="mcps1.2.3.1.2 "><p id="p3530173313346"><a name="p3530173313346"></a><a name="p3530173313346"></a>UART device handle.</p> 309</td> 310</tr> 311<tr id="row45309337342"><td class="cellrowborder" valign="top" width="49.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p553083319348"><a name="p553083319348"></a><a name="p553083319348"></a>attribute</p> 312</td> 313<td class="cellrowborder" valign="top" width="50.019999999999996%" headers="mcps1.2.3.1.2 "><p id="p5530133314343"><a name="p5530133314343"></a><a name="p5530133314343"></a>Pointer to the UART device attributes to set.</p> 314</td> 315</tr> 316<tr id="row12530833103415"><td class="cellrowborder" valign="top" width="49.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p185309331345"><a name="p185309331345"></a><a name="p185309331345"></a><strong id="b18520248203717"><a name="b18520248203717"></a><a name="b18520248203717"></a>Return Value</strong></p> 317</td> 318<td class="cellrowborder" valign="top" width="50.019999999999996%" headers="mcps1.2.3.1.2 "><p id="p145309332344"><a name="p145309332344"></a><a name="p145309332344"></a><strong id="b5367174913370"><a name="b5367174913370"></a><a name="b5367174913370"></a>Description</strong></p> 319</td> 320</tr> 321<tr id="row14530203310348"><td class="cellrowborder" valign="top" width="49.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p1653014339343"><a name="p1653014339343"></a><a name="p1653014339343"></a>0</p> 322</td> 323<td class="cellrowborder" valign="top" width="50.019999999999996%" headers="mcps1.2.3.1.2 "><p id="p1453023323419"><a name="p1453023323419"></a><a name="p1453023323419"></a>Succeeded in setting the UART device attributes.</p> 324</td> 325</tr> 326<tr id="row6531163373412"><td class="cellrowborder" valign="top" width="49.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p16530123310345"><a name="p16530123310345"></a><a name="p16530123310345"></a>Negative value</p> 327</td> 328<td class="cellrowborder" valign="top" width="50.019999999999996%" headers="mcps1.2.3.1.2 "><p id="p1953118334347"><a name="p1953118334347"></a><a name="p1953118334347"></a>Failed to set the UART device attributes.</p> 329</td> 330</tr> 331</tbody> 332</table> 333 334The following example shows how to set the UART device attributes: 335 336``` 337int32_t ret; 338struct UartAttribute attribute; 339attribute.dataBits = UART_ATTR_DATABIT_7; /* Set the number of data bits to 7. */ 340attribute.parity = UART_ATTR_PARITY_NONE; /* Set the parity bit to no parity. */ 341attribute.stopBits = UART_ATTR_STOPBIT_1; /* Set the stop bit to 1. */ 342attribute.rts = UART_ATTR_RTS_DIS; /* Disable the RTS signal. */ 343attribute.cts = UART_ATTR_CTS_DIS; /* Disable the CTS signal. */ 344attribute.fifoRxEn = UART_ATTR_RX_FIFO_EN; /* Enable RX FIFO. */ 345attribute.fifoTxEn = UART_ATTR_TX_FIFO_EN; /* Enable TX FIFO. */ 346/* Set the UART device attributes. */ 347ret = UartSetAttribute(handle, &attribute); 348if (ret != 0) { 349 HDF_LOGE("UartSetAttribute: failed, ret %d\n", ret); 350} 351``` 352 353### Obtaining UART Device Attributes<a name="section18689637165812"></a> 354 355After setting the UART device attributes, obtain the current device attributes by calling the following function: 356 357int32\_t UartGetAttribute\(DevHandle handle, struct UartAttribute \*attribute\); 358 359**Table 6** Description of UartGetAttribute 360 361<a name="table17532123316342"></a> 362<table><thead align="left"><tr id="row18531193383420"><th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.1"><p id="p85311833143420"><a name="p85311833143420"></a><a name="p85311833143420"></a><strong id="b1770784123715"><a name="b1770784123715"></a><a name="b1770784123715"></a>Parameter</strong></p> 363</th> 364<th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.2"><p id="p17531103319348"><a name="p17531103319348"></a><a name="p17531103319348"></a><strong id="b0130114519373"><a name="b0130114519373"></a><a name="b0130114519373"></a>Description</strong></p> 365</th> 366</tr> 367</thead> 368<tbody><tr id="row35311533153413"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p453133333418"><a name="p453133333418"></a><a name="p453133333418"></a>handle</p> 369</td> 370<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p753193323420"><a name="p753193323420"></a><a name="p753193323420"></a>UART device handle.</p> 371</td> 372</tr> 373<tr id="row1953103315344"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p35315333346"><a name="p35315333346"></a><a name="p35315333346"></a>attribute</p> 374</td> 375<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p14531633133416"><a name="p14531633133416"></a><a name="p14531633133416"></a>Pointer to the UART device attributes.</p> 376</td> 377</tr> 378<tr id="row45321433143415"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p653273363417"><a name="p653273363417"></a><a name="p653273363417"></a><strong id="b15211548193719"><a name="b15211548193719"></a><a name="b15211548193719"></a>Return Value</strong></p> 379</td> 380<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p1653203312347"><a name="p1653203312347"></a><a name="p1653203312347"></a><strong id="b836815498379"><a name="b836815498379"></a><a name="b836815498379"></a>Description</strong></p> 381</td> 382</tr> 383<tr id="row175320339342"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p10532163383412"><a name="p10532163383412"></a><a name="p10532163383412"></a>0</p> 384</td> 385<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p5532143319341"><a name="p5532143319341"></a><a name="p5532143319341"></a>Succeeded in obtaining the UART device attributes.</p> 386</td> 387</tr> 388<tr id="row125327337340"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p19532153317345"><a name="p19532153317345"></a><a name="p19532153317345"></a>Negative value</p> 389</td> 390<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p175321933163410"><a name="p175321933163410"></a><a name="p175321933163410"></a>Failed to obtain the UART device attributes.</p> 391</td> 392</tr> 393</tbody> 394</table> 395 396The following example shows how to obtain the UART device attributes: 397 398``` 399int32_t ret; 400struct UartAttribute attribute; 401/* Obtain the UART attributes. */ 402ret = UartGetAttribute(handle, &attribute); 403if (ret != 0) { 404 HDF_LOGE("UartGetAttribute: failed, ret %d\n", ret); 405} 406``` 407 408### Setting the UART Transmission Mode<a name="section72713435918"></a> 409 410Before performing UART communication, set the UART transmission mode by calling the following function: 411 412int32\_t UartSetTransMode\(DevHandle handle, enum UartTransMode mode\); 413 414**Table 7** Description of UartSetTransMode 415 416<a name="table131892266313"></a> 417<table><thead align="left"><tr id="row018922615318"><th class="cellrowborder" valign="top" width="49.980000000000004%" id="mcps1.2.3.1.1"><p id="p131891826835"><a name="p131891826835"></a><a name="p131891826835"></a><strong id="b197086411379"><a name="b197086411379"></a><a name="b197086411379"></a>Parameter</strong></p> 418</th> 419<th class="cellrowborder" valign="top" width="50.019999999999996%" id="mcps1.2.3.1.2"><p id="p101894269314"><a name="p101894269314"></a><a name="p101894269314"></a><strong id="b813014510375"><a name="b813014510375"></a><a name="b813014510375"></a>Description</strong></p> 420</th> 421</tr> 422</thead> 423<tbody><tr id="row11893261734"><td class="cellrowborder" valign="top" width="49.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p81897261333"><a name="p81897261333"></a><a name="p81897261333"></a>handle</p> 424</td> 425<td class="cellrowborder" valign="top" width="50.019999999999996%" headers="mcps1.2.3.1.2 "><p id="p5190142618310"><a name="p5190142618310"></a><a name="p5190142618310"></a>UART device handle.</p> 426</td> 427</tr> 428<tr id="row1119082615317"><td class="cellrowborder" valign="top" width="49.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p1519012261314"><a name="p1519012261314"></a><a name="p1519012261314"></a>mode</p> 429</td> 430<td class="cellrowborder" valign="top" width="50.019999999999996%" headers="mcps1.2.3.1.2 "><p id="p121901026632"><a name="p121901026632"></a><a name="p121901026632"></a>UART transmission mode to set.</p> 431</td> 432</tr> 433<tr id="row19190152612317"><td class="cellrowborder" valign="top" width="49.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p131900266316"><a name="p131900266316"></a><a name="p131900266316"></a><strong id="b1352194823717"><a name="b1352194823717"></a><a name="b1352194823717"></a>Return Value</strong></p> 434</td> 435<td class="cellrowborder" valign="top" width="50.019999999999996%" headers="mcps1.2.3.1.2 "><p id="p1519022616315"><a name="p1519022616315"></a><a name="p1519022616315"></a><strong id="b1836924917371"><a name="b1836924917371"></a><a name="b1836924917371"></a>Description</strong></p> 436</td> 437</tr> 438<tr id="row919016261932"><td class="cellrowborder" valign="top" width="49.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p10190526334"><a name="p10190526334"></a><a name="p10190526334"></a>0</p> 439</td> 440<td class="cellrowborder" valign="top" width="50.019999999999996%" headers="mcps1.2.3.1.2 "><p id="p1219012264318"><a name="p1219012264318"></a><a name="p1219012264318"></a>Succeeded in setting the UART transmission mode.</p> 441</td> 442</tr> 443<tr id="row1219017262313"><td class="cellrowborder" valign="top" width="49.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p15190162616316"><a name="p15190162616316"></a><a name="p15190162616316"></a>Negative value</p> 444</td> 445<td class="cellrowborder" valign="top" width="50.019999999999996%" headers="mcps1.2.3.1.2 "><p id="p131906262311"><a name="p131906262311"></a><a name="p131906262311"></a>Failed to set the UART transmission mode.</p> 446</td> 447</tr> 448</tbody> 449</table> 450 451The following example shows how to set the transmission mode to **UART\_MODE\_RD\_BLOCK**: 452 453``` 454int32_t ret; 455/* Set the UART transmission mode. */ 456ret = UartSetTransMode(handle, UART_MODE_RD_BLOCK); 457if (ret != 0) { 458 HDF_LOGE("UartSetTransMode: failed, ret %d\n", ret); 459} 460``` 461 462### Writing Data of a Specified Length into a UART Device<a name="section128001736155919"></a> 463 464To write data into a UART device, call the following function: 465 466int32\_t UartWrite\(DevHandle handle, uint8\_t \*data, uint32\_t size\); 467 468**Table 8** Description of UartWrite 469 470<a name="table27825111368"></a> 471<table><thead align="left"><tr id="row1578171123619"><th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.1"><p id="p078112115360"><a name="p078112115360"></a><a name="p078112115360"></a><strong id="b14708841203711"><a name="b14708841203711"></a><a name="b14708841203711"></a>Parameter</strong></p> 472</th> 473<th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.2"><p id="p37811711163612"><a name="p37811711163612"></a><a name="p37811711163612"></a><strong id="b2131174553712"><a name="b2131174553712"></a><a name="b2131174553712"></a>Description</strong></p> 474</th> 475</tr> 476</thead> 477<tbody><tr id="row1878291143611"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p07818112360"><a name="p07818112360"></a><a name="p07818112360"></a>handle</p> 478</td> 479<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p178281113369"><a name="p178281113369"></a><a name="p178281113369"></a>UART device handle.</p> 480</td> 481</tr> 482<tr id="row7782811123614"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p8782911173610"><a name="p8782911173610"></a><a name="p8782911173610"></a>data</p> 483</td> 484<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p17782171120366"><a name="p17782171120366"></a><a name="p17782171120366"></a>Pointer to the data to write.</p> 485</td> 486</tr> 487<tr id="row1578251112367"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p3782911183612"><a name="p3782911183612"></a><a name="p3782911183612"></a>size</p> 488</td> 489<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p17782161110366"><a name="p17782161110366"></a><a name="p17782161110366"></a>Length of the data to write.</p> 490</td> 491</tr> 492<tr id="row1378281113363"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p87821411183616"><a name="p87821411183616"></a><a name="p87821411183616"></a><strong id="b2052274863718"><a name="b2052274863718"></a><a name="b2052274863718"></a>Return Value</strong></p> 493</td> 494<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p13782111116361"><a name="p13782111116361"></a><a name="p13782111116361"></a><strong id="b73704492377"><a name="b73704492377"></a><a name="b73704492377"></a>Description</strong></p> 495</td> 496</tr> 497<tr id="row47822112365"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p107821011103613"><a name="p107821011103613"></a><a name="p107821011103613"></a>0</p> 498</td> 499<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p11782191103610"><a name="p11782191103610"></a><a name="p11782191103610"></a>Succeeded in writing data into the UART device.</p> 500</td> 501</tr> 502<tr id="row11782911113611"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p1578221111367"><a name="p1578221111367"></a><a name="p1578221111367"></a>Negative value</p> 503</td> 504<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p9782151110366"><a name="p9782151110366"></a><a name="p9782151110366"></a>Failed to write data into the UART device.</p> 505</td> 506</tr> 507</tbody> 508</table> 509 510The following example shows how to write data of a specified length into the UART device: 511 512``` 513int32_t ret; 514uint8_t wbuff[5] = {1, 2, 3, 4, 5}; 515/* Write 5-byte data into the UART device. */ 516ret = UartWrite(handle, wbuff, 5); 517if (ret != 0) { 518 HDF_LOGE("UartWrite: failed, ret %d\n", ret); 519} 520``` 521 522### Reading Data of a Specified Length from a UART Device<a name="section92851601604"></a> 523 524To write data into a UART device, call the following function: 525 526int32\_t UartRead\(DevHandle handle, uint8\_t \*data, uint32\_t size\); 527 528**Table 9** Description of UartRead 529 530<a name="table162341717123713"></a> 531<table><thead align="left"><tr id="row023313171377"><th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.1"><p id="p1123331710376"><a name="p1123331710376"></a><a name="p1123331710376"></a><strong id="b970911411374"><a name="b970911411374"></a><a name="b970911411374"></a>Parameter</strong></p> 532</th> 533<th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.2"><p id="p523321783715"><a name="p523321783715"></a><a name="p523321783715"></a><strong id="b16132114553713"><a name="b16132114553713"></a><a name="b16132114553713"></a>Description</strong></p> 534</th> 535</tr> 536</thead> 537<tbody><tr id="row6234417133712"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p7233121716379"><a name="p7233121716379"></a><a name="p7233121716379"></a>handle</p> 538</td> 539<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p17234101753712"><a name="p17234101753712"></a><a name="p17234101753712"></a>UART device handle.</p> 540</td> 541</tr> 542<tr id="row18234151718372"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p16234191783711"><a name="p16234191783711"></a><a name="p16234191783711"></a>data</p> 543</td> 544<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p923417175378"><a name="p923417175378"></a><a name="p923417175378"></a>Pointer to the buffer for receiving the data.</p> 545</td> 546</tr> 547<tr id="row82341017193711"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p13234917103717"><a name="p13234917103717"></a><a name="p13234917103717"></a>size</p> 548</td> 549<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p182341817153717"><a name="p182341817153717"></a><a name="p182341817153717"></a>Length of the data to read.</p> 550</td> 551</tr> 552<tr id="row102341617123717"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p172341617163712"><a name="p172341617163712"></a><a name="p172341617163712"></a><strong id="b1352319486376"><a name="b1352319486376"></a><a name="b1352319486376"></a>Return Value</strong></p> 553</td> 554<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p1623431763718"><a name="p1623431763718"></a><a name="p1623431763718"></a><strong id="b73711949113718"><a name="b73711949113718"></a><a name="b73711949113718"></a>Description</strong></p> 555</td> 556</tr> 557<tr id="row4234151719372"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p3234131716375"><a name="p3234131716375"></a><a name="p3234131716375"></a>Non-negative value</p> 558</td> 559<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p7234171783718"><a name="p7234171783718"></a><a name="p7234171783718"></a>Length of the data read from the UART device.</p> 560</td> 561</tr> 562<tr id="row112340173378"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p1423431743714"><a name="p1423431743714"></a><a name="p1423431743714"></a>Negative value</p> 563</td> 564<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p32349178378"><a name="p32349178378"></a><a name="p32349178378"></a>Failed to read data from the UART device.</p> 565</td> 566</tr> 567</tbody> 568</table> 569 570The following example shows how to read data of a specified length from the UART device: 571 572``` 573int32_t ret; 574uint8_t rbuff[5] = {0}; 575/* Read 5-byte data from the UART device. */ 576ret = UartRead(handle, rbuff, 5); 577if (ret < 0) { 578 HDF_LOGE("UartRead: failed, ret %d\n", ret); 579} 580``` 581 582> **CAUTION:** 583>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. 584 585### Destroying the UART Device Handle<a name="section1477410521406"></a> 586 587After the UART communication, destroy the UART device handle by calling the following function: 588 589void UartClose\(DevHandle handle\); 590 591This function will release the resources previously obtained. 592 593**Table 10** Description of UartClose 594 595<a name="table03348317351"></a> 596<table><thead align="left"><tr id="row15334837351"><th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.1"><p id="p933411316354"><a name="p933411316354"></a><a name="p933411316354"></a><strong id="b1710184115375"><a name="b1710184115375"></a><a name="b1710184115375"></a>Parameter</strong></p> 597</th> 598<th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.2"><p id="p16334103143517"><a name="p16334103143517"></a><a name="p16334103143517"></a><strong id="b2013254513370"><a name="b2013254513370"></a><a name="b2013254513370"></a>Description</strong></p> 599</th> 600</tr> 601</thead> 602<tbody><tr id="row733483103513"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p7334530358"><a name="p7334530358"></a><a name="p7334530358"></a>handle</p> 603</td> 604<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p133341331356"><a name="p133341331356"></a><a name="p133341331356"></a>UART device handle.</p> 605</td> 606</tr> 607</tbody> 608</table> 609 610The following example shows how to destroy the UART device handle: 611 612``` 613UartClose(handle); /* Destroy the UART device handle. */ 614``` 615 616## Usage Example<a name="section35404241311"></a> 617 618The 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. 619 620``` 621#include "hdf_log.h" 622#include "uart_if.h" 623 624void UartTestSample(void) 625{ 626 int32_t ret; 627 uint32_t port; 628 DevHandle handle = NULL; 629 uint8_t wbuff[5] = { 1, 2, 3, 4, 5 }; 630 uint8_t rbuff[5] = { 0 }; 631 struct UartAttribute attribute; 632 attribute.dataBits = UART_ATTR_DATABIT_7; /* Set the number of data bits to 7. */ 633 attribute.parity = UART_ATTR_PARITY_NONE; /* Set the parity bit to no parity. */ 634 attribute.stopBits = UART_ATTR_STOPBIT_1; /* Set the stop bit to 1. */ 635 attribute.rts = UART_ATTR_RTS_DIS; /* Disable the RTS signal. */ 636 attribute.cts = UART_ATTR_CTS_DIS; /* Disable the CTS signal. */ 637 attribute.fifoRxEn = UART_ATTR_RX_FIFO_EN; /* Enable RX FIFO. */ 638 attribute.fifoTxEn = UART_ATTR_TX_FIFO_EN; /* Enable TX FIFO. */ 639 /* Set the UART port number actually used. */ 640 port = 1; 641 /* Obtain the UART device handle. */ 642 handle = UartOpen(port); 643 if (handle == NULL) { 644 HDF_LOGE("UartOpen: failed!\n"); 645 return; 646 } 647 /* Set the UART baud rate to 9600. */ 648 ret = UartSetBaud(handle, 9600); 649 if (ret != 0) { 650 HDF_LOGE("UartSetBaud: failed, ret %d\n", ret); 651 goto _ERR; 652 } 653 /* Set the UART device attributes. */ 654 ret = UartSetAttribute(handle, &attribute); 655 if (ret != 0) { 656 HDF_LOGE("UartSetAttribute: failed, ret %d\n", ret); 657 goto _ERR; 658 } 659 /* Set the UART transmission mode to non-blocking mode. */ 660 ret = UartSetTransMode(handle, UART_MODE_RD_NONBLOCK); 661 if (ret != 0) { 662 HDF_LOGE("UartSetTransMode: failed, ret %d\n", ret); 663 goto _ERR; 664 } 665 /* Write 5-byte data into the UART device. */ 666 ret = UartWrite(handle, wbuff, 5); 667 if (ret != 0) { 668 HDF_LOGE("UartWrite: failed, ret %d\n", ret); 669 goto _ERR; 670 } 671 /* Read 5-byte data from the UART device. */ 672 ret = UartRead(handle, rbuff, 5); 673 if (ret < 0) { 674 HDF_LOGE("UartRead: failed, ret %d\n", ret); 675 goto _ERR; 676 } 677_ERR: 678 /* Destroy the UART device handle. */ 679 UartClose(handle); 680} 681``` 682 683
