1# SPI<a name="EN-US_TOPIC_0000001053057951"></a> 2 3- [Overview](#section193356154511) 4 - [Available APIs](#section232141411476) 5 6- [Usage Guidelines](#section71363452477) 7 - [How to Use](#section32846814820) 8 - [Obtaining an SPI Device Handle](#section1927265711481) 9 - [Obtaining SPI Device Configuration Parameters](#section541133418493) 10 - [Setting SPI Device Configuration Parameters](#section7870106145010) 11 - [Performing SPI Communication](#section13324155195013) 12 - [Destroying the SPI Device Handle](#section19661632135117) 13 14- [Usage Example](#section06541058155120) 15 16## Overview<a name="section193356154511"></a> 17 18- Serial Peripheral Interface \(SPI\) is a serial bus specification used for high-speed, full-duplex, and synchronous communication. 19- SPI is developed by Motorola. It is commonly used for communication with flash memory, real-time clocks, sensors, and analog-to-digital \(A/D\) converters. 20- SPI works in controller/device mode. Generally, there is one SPI controller that controls one or more SPI devices. They are connected via four wires: 21 - SCLK: clock signals output from the SPI controller 22 - MOSI: data output from the SPI controller and input into an SPI device 23 - MISO: data output from an SPI device and input into the SPI controller 24 - CS: signals enabled by an SPI device and controlled by the SPI controller 25 26 27- [Figure 1](#fig15227181812587) shows the connection between one SPI controller and two SPI devices \(device A and device B\). In this figure, device A and device B share three pins \(SCLK, MISO, and MOSI\) of the controller. CS0 of device A and CS1 of device B are connected to CS0 and CS1 of the controller, respectively. 28 29**Figure 1** SPI controller/device connection<a name="fig15227181812587"></a> 30 31 32 33 34- SPI communication is usually initiated by the SPI controller and is operated as follows: 35 361. A single SPI device is selected at a time via the CS to communicate with the SPI controller. 372. Clock signals are provided for the selected SPI device via the SCLK. 383. The SPI controller sends data to SPI devices via the MOSI, and receives data from SPI devices via the MISO. 39 40- SPI can work in one of the following four modes, equivalent to one of the four possible states for Clock Polarity \(CPOL\) and Clock Phase \(CPHA\): 41 - If both CPOL and CPHA are **0**, the clock signal level is low in the idle state and data is sampled on the first clock edge. 42 - If CPOL is **0** and CPHA is **1**, the clock signal level is low in the idle state and data is sampled on the second clock edge. 43 - If CPOL is **1** and CPHA is **0**, the clock signal level is high in the idle state and data is sampled on the first clock edge. 44 - If both CPOL and CPHA are **1**, the clock signal level is high in the idle state and data is sampled on the second clock edge. 45 46 47- SPI defines a set of common functions for operating an SPI device, including those for: 48 - Obtaining and releasing the handle of an SPI device. 49 - Reading or writing data of a specified length from or into an SPI device. 50 - Customizing data reading or writing via **SpiMsg**. 51 - Obtaining and setting SPI device configuration parameters. 52 53 54> **NOTE:** 55>Currently, these functions are only applicable in the communication initiated by the SPI controller. 56 57### Available APIs<a name="section232141411476"></a> 58 59**Table 1** APIs for the SPI driver 60 61<a name="table1731550155318"></a> 62<table><thead align="left"><tr id="row4419501537"><th class="cellrowborder" align="left" valign="top" width="20.857914208579142%" id="mcps1.2.4.1.1"><p id="p641050105320"><a name="p641050105320"></a><a name="p641050105320"></a><strong id="b17365506414"><a name="b17365506414"></a><a name="b17365506414"></a>Capability</strong></p> 63</th> 64<th class="cellrowborder" align="left" valign="top" width="23.36766323367663%" id="mcps1.2.4.1.2"><p id="p54150165315"><a name="p54150165315"></a><a name="p54150165315"></a><strong id="b191701618154210"><a name="b191701618154210"></a><a name="b191701618154210"></a>Function</strong></p> 65</th> 66<th class="cellrowborder" align="left" valign="top" width="55.77442255774422%" id="mcps1.2.4.1.3"><p id="p941150145313"><a name="p941150145313"></a><a name="p941150145313"></a><strong id="b64281840104214"><a name="b64281840104214"></a><a name="b64281840104214"></a>Description</strong></p> 67</th> 68</tr> 69</thead> 70<tbody><tr id="row1651292212306"><td class="cellrowborder" rowspan="2" valign="top" width="20.857914208579142%" headers="mcps1.2.4.1.1 "><p id="p1387414255305"><a name="p1387414255305"></a><a name="p1387414255305"></a>SPI device handle obtaining/releasing</p> 71</td> 72<td class="cellrowborder" valign="top" width="23.36766323367663%" headers="mcps1.2.4.1.2 "><p id="p8874825143014"><a name="p8874825143014"></a><a name="p8874825143014"></a>SpiOpen</p> 73</td> 74<td class="cellrowborder" valign="top" width="55.77442255774422%" headers="mcps1.2.4.1.3 "><p id="p1087432513307"><a name="p1087432513307"></a><a name="p1087432513307"></a>Obtains an SPI device handle.</p> 75</td> 76</tr> 77<tr id="row1429083612305"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1956614106311"><a name="p1956614106311"></a><a name="p1956614106311"></a>SpiClose</p> 78</td> 79<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p829111362306"><a name="p829111362306"></a><a name="p829111362306"></a>Releases an SPI device handle.</p> 80</td> 81</tr> 82<tr id="row34145016535"><td class="cellrowborder" rowspan="3" valign="top" width="20.857914208579142%" headers="mcps1.2.4.1.1 "><p id="p229610227124"><a name="p229610227124"></a><a name="p229610227124"></a>SPI reading/writing</p> 83</td> 84<td class="cellrowborder" valign="top" width="23.36766323367663%" headers="mcps1.2.4.1.2 "><p id="p19389143041518"><a name="p19389143041518"></a><a name="p19389143041518"></a>SpiRead</p> 85</td> 86<td class="cellrowborder" valign="top" width="55.77442255774422%" headers="mcps1.2.4.1.3 "><p id="p8738101941716"><a name="p8738101941716"></a><a name="p8738101941716"></a>Reads data of a specified length from an SPI device.</p> 87</td> 88</tr> 89<tr id="row5632152611414"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p143890309153"><a name="p143890309153"></a><a name="p143890309153"></a>SpiWrite</p> 90</td> 91<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p573815197171"><a name="p573815197171"></a><a name="p573815197171"></a>Writes data of a specified length into an SPI device.</p> 92</td> 93</tr> 94<tr id="row1766145611414"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p183904373018"><a name="p183904373018"></a><a name="p183904373018"></a>SpiTransfer</p> 95</td> 96<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1639011313303"><a name="p1639011313303"></a><a name="p1639011313303"></a>Transfers SPI data.</p> 97</td> 98</tr> 99<tr id="row1020919129159"><td class="cellrowborder" rowspan="2" valign="top" width="20.857914208579142%" headers="mcps1.2.4.1.1 "><p id="p82092126154"><a name="p82092126154"></a><a name="p82092126154"></a>SPI device configuration</p> 100<p id="p6794153701111"><a name="p6794153701111"></a><a name="p6794153701111"></a></p> 101</td> 102<td class="cellrowborder" valign="top" width="23.36766323367663%" headers="mcps1.2.4.1.2 "><p id="p1739013012154"><a name="p1739013012154"></a><a name="p1739013012154"></a>SpiSetCfg</p> 103</td> 104<td class="cellrowborder" valign="top" width="55.77442255774422%" headers="mcps1.2.4.1.3 "><p id="p073910197173"><a name="p073910197173"></a><a name="p073910197173"></a>Sets configuration parameters for an SPI device.</p> 105</td> 106</tr> 107<tr id="row379443710118"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p4333154919111"><a name="p4333154919111"></a><a name="p4333154919111"></a>SpiGetCfg</p> 108</td> 109<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p11333649171117"><a name="p11333649171117"></a><a name="p11333649171117"></a>Obtains configuration parameters of an SPI device.</p> 110</td> 111</tr> 112</tbody> 113</table> 114 115> **NOTE:** 116>All functions provided in this document can be called only in kernel space. 117 118## Usage Guidelines<a name="section71363452477"></a> 119 120### How to Use<a name="section32846814820"></a> 121 122[Figure 2](#fig23885455594) shows the process of using an SPI device. 123 124**Figure 2** Process of using an SPI device<a name="fig23885455594"></a> 125 126 127 128 129### Obtaining an SPI Device Handle<a name="section1927265711481"></a> 130 131Before performing SPI communication, obtain an SPI device handle by calling **SpiOpen**. This function returns an SPI device handle with a specified bus number and CS number. 132 133DevHandle SpiOpen\(const struct SpiDevInfo \*info\); 134 135**Table 2** Description of SpiOpen 136 137<a name="table7603619123820"></a> 138<table><tbody><tr id="row1060351914386"><td class="cellrowborder" valign="top" width="50%"><p id="p14603181917382"><a name="p14603181917382"></a><a name="p14603181917382"></a><strong id="b139290298482"><a name="b139290298482"></a><a name="b139290298482"></a>Parameter</strong></p> 139</td> 140<td class="cellrowborder" valign="top" width="50%"><p id="p36031519183819"><a name="p36031519183819"></a><a name="p36031519183819"></a><strong id="b17557183010484"><a name="b17557183010484"></a><a name="b17557183010484"></a>Description</strong></p> 141</td> 142</tr> 143<tr id="row1960431983813"><td class="cellrowborder" valign="top" width="50%"><p id="p3604719123817"><a name="p3604719123817"></a><a name="p3604719123817"></a>info</p> 144</td> 145<td class="cellrowborder" valign="top" width="50%"><p id="p1560441923818"><a name="p1560441923818"></a><a name="p1560441923818"></a>Pointer to the SPI device descriptor.</p> 146</td> 147</tr> 148<tr id="row380484160"><td class="cellrowborder" valign="top" width="50%"><p id="p460381915385"><a name="p460381915385"></a><a name="p460381915385"></a><strong id="b1431414320486"><a name="b1431414320486"></a><a name="b1431414320486"></a>Return Value</strong></p> 149</td> 150<td class="cellrowborder" valign="top" width="50%"><p id="p96031619153812"><a name="p96031619153812"></a><a name="p96031619153812"></a><strong id="b164533311485"><a name="b164533311485"></a><a name="b164533311485"></a>Description</strong></p> 151</td> 152</tr> 153<tr id="row5793818161"><td class="cellrowborder" valign="top" width="50%"><p id="p1060418195389"><a name="p1060418195389"></a><a name="p1060418195389"></a>NULL</p> 154</td> 155<td class="cellrowborder" valign="top" width="50%"><p id="p760471912388"><a name="p760471912388"></a><a name="p760471912388"></a>Failed to obtain an SPI device handle.</p> 156</td> 157</tr> 158<tr id="row187914871618"><td class="cellrowborder" valign="top" width="50%"><p id="p5604719133811"><a name="p5604719133811"></a><a name="p5604719133811"></a>Device handle</p> 159</td> 160<td class="cellrowborder" valign="top" width="50%"><p id="p3604181933818"><a name="p3604181933818"></a><a name="p3604181933818"></a>Returns the pointer to the SPI device handle.</p> 161</td> 162</tr> 163</tbody> 164</table> 165 166The following example shows how to obtain an SPI device handle based on the assumption that both the bus number and CS number of the SPI device are **0**. 167 168``` 169struct SpiDevInfo spiDevinfo; /* SPI device descriptor */ 170DevHandle spiHandle = NULL; /* SPI device handle */ 171spiDevinfo.busNum = 0; /* SPI device bus number */ 172spiDevinfo.csNum = 0; /* SPI device CS number */ 173 174/* Obtain an SPI device handle. */ 175spiHandle = SpiOpen(&spiDevinfo); 176if (spiHandle == NULL) { 177 HDF_LOGE("SpiOpen: failed\n"); 178 return; 179} 180``` 181 182### Obtaining SPI Device Configuration Parameters<a name="section541133418493"></a> 183 184After obtaining the SPI device handle, obtain the SPI device configuration parameters by calling the following function: 185 186int32\_t SpiGetCfg\(DevHandle handle, struct SpiCfg \*cfg\); 187 188**Table 3** Description of SpiGetCfg 189 190<a name="table14209152141313"></a> 191<table><tbody><tr id="row1420918529133"><td class="cellrowborder" valign="top" width="50%"><p id="p42091852141314"><a name="p42091852141314"></a><a name="p42091852141314"></a><strong id="b6279123012486"><a name="b6279123012486"></a><a name="b6279123012486"></a>Parameter</strong></p> 192</td> 193<td class="cellrowborder" valign="top" width="50%"><p id="p202099523137"><a name="p202099523137"></a><a name="p202099523137"></a><strong id="b18243194818"><a name="b18243194818"></a><a name="b18243194818"></a>Description</strong></p> 194</td> 195</tr> 196<tr id="row142091352171310"><td class="cellrowborder" valign="top" width="50%"><p id="p1520915529131"><a name="p1520915529131"></a><a name="p1520915529131"></a>handle</p> 197</td> 198<td class="cellrowborder" valign="top" width="50%"><p id="p720995291310"><a name="p720995291310"></a><a name="p720995291310"></a>SPI device handle.</p> 199</td> 200</tr> 201<tr id="row6209152161314"><td class="cellrowborder" valign="top" width="50%"><p id="p720916522139"><a name="p720916522139"></a><a name="p720916522139"></a>cfg</p> 202</td> 203<td class="cellrowborder" valign="top" width="50%"><p id="p172091452131319"><a name="p172091452131319"></a><a name="p172091452131319"></a>Pointer to SPI device configuration parameters.</p> 204</td> 205</tr> 206<tr id="row12092522139"><td class="cellrowborder" valign="top" width="50%"><p id="p18209125211134"><a name="p18209125211134"></a><a name="p18209125211134"></a><strong id="b16646173219483"><a name="b16646173219483"></a><a name="b16646173219483"></a>Return Value</strong></p> 207</td> 208<td class="cellrowborder" valign="top" width="50%"><p id="p420975231318"><a name="p420975231318"></a><a name="p420975231318"></a><strong id="b184316334486"><a name="b184316334486"></a><a name="b184316334486"></a>Description</strong></p> 209</td> 210</tr> 211<tr id="row8209155251310"><td class="cellrowborder" valign="top" width="50%"><p id="p13210145291312"><a name="p13210145291312"></a><a name="p13210145291312"></a>0</p> 212</td> 213<td class="cellrowborder" valign="top" width="50%"><p id="p152101952141315"><a name="p152101952141315"></a><a name="p152101952141315"></a>Succeeded in obtaining SPI device configuration parameters.</p> 214</td> 215</tr> 216<tr id="row102101452121320"><td class="cellrowborder" valign="top" width="50%"><p id="p10210175219134"><a name="p10210175219134"></a><a name="p10210175219134"></a>Negative value</p> 217</td> 218<td class="cellrowborder" valign="top" width="50%"><p id="p72101252101312"><a name="p72101252101312"></a><a name="p72101252101312"></a>Failed to obtain SPI device configuration parameters.</p> 219</td> 220</tr> 221</tbody> 222</table> 223 224``` 225int32_t ret; 226struct SpiCfg cfg = {0}; /* SPI configuration information */ 227ret = SpiGetCfg(spiHandle, &cfg); /* Obtain SPI device configuration parameters. */ 228if (ret != 0) { 229 HDF_LOGE("SpiGetCfg: failed, ret %d\n", ret); 230} 231``` 232 233### Setting SPI Device Configuration Parameters<a name="section7870106145010"></a> 234 235After obtaining the SPI device handle, set SPI device configuration parameters by calling the following function: 236 237int32\_t SpiSetCfg\(DevHandle handle, struct SpiCfg \*cfg\); 238 239**Table 4** Description of SpiSetCfg 240 241<a name="table219052945210"></a> 242<table><tbody><tr id="row14191192918522"><td class="cellrowborder" valign="top" width="50%"><p id="p17424155016529"><a name="p17424155016529"></a><a name="p17424155016529"></a><strong id="b11281163011480"><a name="b11281163011480"></a><a name="b11281163011480"></a>Parameter</strong></p> 243</td> 244<td class="cellrowborder" valign="top" width="50%"><p id="p942512508520"><a name="p942512508520"></a><a name="p942512508520"></a><strong id="b1330312487"><a name="b1330312487"></a><a name="b1330312487"></a>Description</strong></p> 245</td> 246</tr> 247<tr id="row219152915524"><td class="cellrowborder" valign="top" width="50%"><p id="p2191122985218"><a name="p2191122985218"></a><a name="p2191122985218"></a>handle</p> 248</td> 249<td class="cellrowborder" valign="top" width="50%"><p id="p1519162913524"><a name="p1519162913524"></a><a name="p1519162913524"></a>SPI device handle.</p> 250</td> 251</tr> 252<tr id="row1719110297526"><td class="cellrowborder" valign="top" width="50%"><p id="p181911292523"><a name="p181911292523"></a><a name="p181911292523"></a>cfg</p> 253</td> 254<td class="cellrowborder" valign="top" width="50%"><p id="p91911729155216"><a name="p91911729155216"></a><a name="p91911729155216"></a>Pointer to SPI device configuration parameters.</p> 255</td> 256</tr> 257<tr id="row036524131716"><td class="cellrowborder" valign="top" width="50%"><p id="p6425165035214"><a name="p6425165035214"></a><a name="p6425165035214"></a><strong id="b96476326489"><a name="b96476326489"></a><a name="b96476326489"></a>Return Value</strong></p> 258</td> 259<td class="cellrowborder" valign="top" width="50%"><p id="p18425650165215"><a name="p18425650165215"></a><a name="p18425650165215"></a><strong id="b17432193311481"><a name="b17432193311481"></a><a name="b17432193311481"></a>Description</strong></p> 260</td> 261</tr> 262<tr id="row43653411178"><td class="cellrowborder" valign="top" width="50%"><p id="p1319132918520"><a name="p1319132918520"></a><a name="p1319132918520"></a>0</p> 263</td> 264<td class="cellrowborder" valign="top" width="50%"><p id="p1719117292522"><a name="p1719117292522"></a><a name="p1719117292522"></a>Succeeded in setting SPI device configuration parameters.</p> 265</td> 266</tr> 267<tr id="row536594171715"><td class="cellrowborder" valign="top" width="50%"><p id="p719119296522"><a name="p719119296522"></a><a name="p719119296522"></a>Negative value</p> 268</td> 269<td class="cellrowborder" valign="top" width="50%"><p id="p20191192925212"><a name="p20191192925212"></a><a name="p20191192925212"></a>Failed to set SPI device configuration parameters.</p> 270</td> 271</tr> 272</tbody> 273</table> 274 275``` 276int32_t ret; 277struct SpiCfg cfg = {0}; /* SPI configuration information */ 278cfg.mode = SPI_MODE_LOOP; /* Communication in loopback mode */ 279cfg.transferMode = PAL_SPI_POLLING_TRANSFER; /* Communication in polling mode */ 280cfg.maxSpeedHz = 115200; /* Maximum transmission frequency */ 281cfg.bitsPerWord = 8; /* The width of per word to be read or written is 8 bits. */ 282ret = SpiSetCfg(spiHandle, &cfg); /* Set SPI device configuration parameters. */ 283if (ret != 0) { 284 HDF_LOGE("SpiSetCfg: failed, ret %d\n", ret); 285} 286``` 287 288### Performing SPI Communication<a name="section13324155195013"></a> 289 290- Writing data of a specific length into an SPI device 291 292To write data into an SPI device only once, call the following function: 293 294int32\_t SpiWrite\(DevHandle handle, uint8\_t \*buf, uint32\_t len\); 295 296**Table 5** Description of SpiWrite 297 298<a name="table1018490043"></a> 299<table><tbody><tr id="row31848013417"><td class="cellrowborder" valign="top" width="50%"><p id="p1415816132411"><a name="p1415816132411"></a><a name="p1415816132411"></a><strong id="b42810303484"><a name="b42810303484"></a><a name="b42810303484"></a>Parameter</strong></p> 300</td> 301<td class="cellrowborder" valign="top" width="50%"><p id="p11158111316410"><a name="p11158111316410"></a><a name="p11158111316410"></a><strong id="b03103112484"><a name="b03103112484"></a><a name="b03103112484"></a>Description</strong></p> 302</td> 303</tr> 304<tr id="row10184701945"><td class="cellrowborder" valign="top" width="50%"><p id="p104891871157"><a name="p104891871157"></a><a name="p104891871157"></a>handle</p> 305</td> 306<td class="cellrowborder" valign="top" width="50%"><p id="p204891671156"><a name="p204891671156"></a><a name="p204891671156"></a>SPI device handle.</p> 307</td> 308</tr> 309<tr id="row928111518418"><td class="cellrowborder" valign="top" width="50%"><p id="p4282955412"><a name="p4282955412"></a><a name="p4282955412"></a>buf</p> 310</td> 311<td class="cellrowborder" valign="top" width="50%"><p id="p7282752412"><a name="p7282752412"></a><a name="p7282752412"></a>Pointer to the data to write.</p> 312</td> 313</tr> 314<tr id="row149041113651"><td class="cellrowborder" valign="top" width="50%"><p id="p139051213357"><a name="p139051213357"></a><a name="p139051213357"></a>len</p> 315</td> 316<td class="cellrowborder" valign="top" width="50%"><p id="p16905313854"><a name="p16905313854"></a><a name="p16905313854"></a>Length of the data to write.</p> 317</td> 318</tr> 319<tr id="row1148818622017"><td class="cellrowborder" valign="top" width="50%"><p id="p8158313248"><a name="p8158313248"></a><a name="p8158313248"></a><strong id="b9649732154818"><a name="b9649732154818"></a><a name="b9649732154818"></a>Return Value</strong></p> 320</td> 321<td class="cellrowborder" valign="top" width="50%"><p id="p161591413741"><a name="p161591413741"></a><a name="p161591413741"></a><strong id="b12433113344813"><a name="b12433113344813"></a><a name="b12433113344813"></a>Description</strong></p> 322</td> 323</tr> 324<tr id="row14488762202"><td class="cellrowborder" valign="top" width="50%"><p id="p103191916578"><a name="p103191916578"></a><a name="p103191916578"></a>0</p> 325</td> 326<td class="cellrowborder" valign="top" width="50%"><p id="p1231981611712"><a name="p1231981611712"></a><a name="p1231981611712"></a>Succeeded in writing data into an SPI device.</p> 327</td> 328</tr> 329<tr id="row164881464201"><td class="cellrowborder" valign="top" width="50%"><p id="p531916166716"><a name="p531916166716"></a><a name="p531916166716"></a>Negative value</p> 330</td> 331<td class="cellrowborder" valign="top" width="50%"><p id="p93191161174"><a name="p93191161174"></a><a name="p93191161174"></a>Failed to write data into an SPI device.</p> 332</td> 333</tr> 334</tbody> 335</table> 336 337``` 338int32_t ret; 339uint8_t wbuff[4] = {0x12, 0x34, 0x56, 0x78}; 340/* Write data of a specific length into an SPI device. */ 341ret = SpiWrite(spiHandle, wbuff, 4); 342if (ret != 0) { 343 HDF_LOGE("SpiWrite: failed, ret %d\n", ret); 344} 345``` 346 347- Reading data of a specific length from an SPI device 348 349To read data from an SPI device only once, call the following function: 350 351int32\_t SpiRead\(DevHandle handle, uint8\_t \*buf, uint32\_t len\); 352 353**Table 6** Description of SpiRead 354 355<a name="table0265191412124"></a> 356<table><tbody><tr id="row42651914141213"><td class="cellrowborder" valign="top" width="50%"><p id="p1483184123"><a name="p1483184123"></a><a name="p1483184123"></a><strong id="b528223019480"><a name="b528223019480"></a><a name="b528223019480"></a>Parameter</strong></p> 357</td> 358<td class="cellrowborder" valign="top" width="50%"><p id="p9831871216"><a name="p9831871216"></a><a name="p9831871216"></a><strong id="b3416318489"><a name="b3416318489"></a><a name="b3416318489"></a>Description</strong></p> 359</td> 360</tr> 361<tr id="row1926651415123"><td class="cellrowborder" valign="top" width="50%"><p id="p389183129"><a name="p389183129"></a><a name="p389183129"></a>handle</p> 362</td> 363<td class="cellrowborder" valign="top" width="50%"><p id="p168151817124"><a name="p168151817124"></a><a name="p168151817124"></a>SPI device handle.</p> 364</td> 365</tr> 366<tr id="row202661414201220"><td class="cellrowborder" valign="top" width="50%"><p id="p158161821210"><a name="p158161821210"></a><a name="p158161821210"></a>buf</p> 367</td> 368<td class="cellrowborder" valign="top" width="50%"><p id="p98131811126"><a name="p98131811126"></a><a name="p98131811126"></a>Pointer to the data to read.</p> 369</td> 370</tr> 371<tr id="row1926621451212"><td class="cellrowborder" valign="top" width="50%"><p id="p2918182124"><a name="p2918182124"></a><a name="p2918182124"></a>len</p> 372</td> 373<td class="cellrowborder" valign="top" width="50%"><p id="p169718191220"><a name="p169718191220"></a><a name="p169718191220"></a>Length of the data to read.</p> 374</td> 375</tr> 376<tr id="row05841310206"><td class="cellrowborder" valign="top" width="50%"><p id="p38171818128"><a name="p38171818128"></a><a name="p38171818128"></a><strong id="b1364973254814"><a name="b1364973254814"></a><a name="b1364973254814"></a>Return Value</strong></p> 377</td> 378<td class="cellrowborder" valign="top" width="50%"><p id="p881918161220"><a name="p881918161220"></a><a name="p881918161220"></a><strong id="b04341333484"><a name="b04341333484"></a><a name="b04341333484"></a>Description</strong></p> 379</td> 380</tr> 381<tr id="row15584173192016"><td class="cellrowborder" valign="top" width="50%"><p id="p14871820128"><a name="p14871820128"></a><a name="p14871820128"></a>0</p> 382</td> 383<td class="cellrowborder" valign="top" width="50%"><p id="p88118101211"><a name="p88118101211"></a><a name="p88118101211"></a>Succeeded in reading data from an SPI device.</p> 384</td> 385</tr> 386<tr id="row1058418317204"><td class="cellrowborder" valign="top" width="50%"><p id="p10841817125"><a name="p10841817125"></a><a name="p10841817125"></a>Negative value</p> 387</td> 388<td class="cellrowborder" valign="top" width="50%"><p id="p986183127"><a name="p986183127"></a><a name="p986183127"></a>Failed to read data from an SPI device.</p> 389</td> 390</tr> 391</tbody> 392</table> 393 394``` 395int32_t ret; 396uint8_t rbuff[4] = {0}; 397/* Read data of a specific length from an SPI device. */ 398ret = SpiRead(spiHandle, rbuff, 4); 399if (ret != 0) { 400 HDF_LOGE("SpiRead: failed, ret %d\n", ret); 401} 402``` 403 404- Launching a custom transfer 405 406To launch a custom transfer, call the following function: 407 408int32\_t SpiTransfer\(DevHandle handle, struct SpiMsg \*msgs, uint32\_t count\); 409 410**Table 7** Description of SpiTransfer 411 412<a name="table1934414174212"></a> 413<table><tbody><tr id="row1134415176216"><td class="cellrowborder" valign="top" width="50%"><p id="p13295152320217"><a name="p13295152320217"></a><a name="p13295152320217"></a><strong id="b1628393012482"><a name="b1628393012482"></a><a name="b1628393012482"></a>Parameter</strong></p> 414</td> 415<td class="cellrowborder" valign="top" width="50%"><p id="p1295112352115"><a name="p1295112352115"></a><a name="p1295112352115"></a><strong id="b175931204814"><a name="b175931204814"></a><a name="b175931204814"></a>Description</strong></p> 416</td> 417</tr> 418<tr id="row5344101702113"><td class="cellrowborder" valign="top" width="50%"><p id="p19295132382111"><a name="p19295132382111"></a><a name="p19295132382111"></a>handle</p> 419</td> 420<td class="cellrowborder" valign="top" width="50%"><p id="p829510232213"><a name="p829510232213"></a><a name="p829510232213"></a>SPI device handle.</p> 421</td> 422</tr> 423<tr id="row17344171722117"><td class="cellrowborder" valign="top" width="50%"><p id="p9295122332113"><a name="p9295122332113"></a><a name="p9295122332113"></a>msgs</p> 424</td> 425<td class="cellrowborder" valign="top" width="50%"><p id="p202951238218"><a name="p202951238218"></a><a name="p202951238218"></a>Pointer to the message array to be transferred.</p> 426</td> 427</tr> 428<tr id="row45812466213"><td class="cellrowborder" valign="top" width="50%"><p id="p1659246112117"><a name="p1659246112117"></a><a name="p1659246112117"></a>count</p> 429</td> 430<td class="cellrowborder" valign="top" width="50%"><p id="p259124622119"><a name="p259124622119"></a><a name="p259124622119"></a>Number of messages in the message array.</p> 431</td> 432</tr> 433<tr id="row45187318214"><td class="cellrowborder" valign="top" width="50%"><p id="p17295142322113"><a name="p17295142322113"></a><a name="p17295142322113"></a><strong id="b5650532164818"><a name="b5650532164818"></a><a name="b5650532164818"></a>Return Value</strong></p> 434</td> 435<td class="cellrowborder" valign="top" width="50%"><p id="p142959232211"><a name="p142959232211"></a><a name="p142959232211"></a><strong id="b84349335480"><a name="b84349335480"></a><a name="b84349335480"></a>Description</strong></p> 436</td> 437</tr> 438<tr id="row175186313217"><td class="cellrowborder" valign="top" width="50%"><p id="p929532313211"><a name="p929532313211"></a><a name="p929532313211"></a>0</p> 439</td> 440<td class="cellrowborder" valign="top" width="50%"><p id="p829512237217"><a name="p829512237217"></a><a name="p829512237217"></a>Succeeded in launching the custom transfer.</p> 441</td> 442</tr> 443<tr id="row1451803152114"><td class="cellrowborder" valign="top" width="50%"><p id="p12958234217"><a name="p12958234217"></a><a name="p12958234217"></a>Negative value</p> 444</td> 445<td class="cellrowborder" valign="top" width="50%"><p id="p1295192312112"><a name="p1295192312112"></a><a name="p1295192312112"></a>Failed to launch the custom transfer.</p> 446</td> 447</tr> 448</tbody> 449</table> 450 451``` 452int32_t ret; 453uint8_t wbuff[1] = {0x12}; 454uint8_t rbuff[1] = {0}; 455struct SpiMsg msg; /* Custom message to be transferred */ 456msg.wbuf = wbuff; /* Pointer to the data to write */ 457msg.rbuf = rbuff; /* Pointer to the data to read */ 458msg.len = 1; /* The length of the data to read or write is 1 bit. */ 459msg.csChange = 1; /* Disable the CS before the next transfer. */ 460msg.delayUs = 0; /* No delay before the next transfer */ 461msg.speed = 115200; /* Speed of this transfer */ 462/* Launch a custom transfer. The number of messages to be transferred is 1. */ 463ret = SpiTransfer(spiHandle, &msg, 1); 464if (ret != 0) { 465 HDF_LOGE("SpiTransfer: failed, ret %d\n", ret); 466} 467``` 468 469### Destroying the SPI Device Handle<a name="section19661632135117"></a> 470 471After the SPI communication, destroy the SPI device handle by calling the following function: 472 473void SpiClose\(DevHandle handle\); 474 475This function will release the resources previously obtained. 476 477**Table 8** Description of SpiClose 478 479<a name="table72517953115"></a> 480<table><tbody><tr id="row1525793312"><td class="cellrowborder" valign="top" width="50%"><p id="p115402031153111"><a name="p115402031153111"></a><a name="p115402031153111"></a><strong id="b1728493044820"><a name="b1728493044820"></a><a name="b1728493044820"></a>Parameter</strong></p> 481</td> 482<td class="cellrowborder" valign="top" width="50%"><p id="p65406313319"><a name="p65406313319"></a><a name="p65406313319"></a><strong id="b176133134814"><a name="b176133134814"></a><a name="b176133134814"></a>Description</strong></p> 483</td> 484</tr> 485<tr id="row1926109193116"><td class="cellrowborder" valign="top" width="50%"><p id="p105419317318"><a name="p105419317318"></a><a name="p105419317318"></a>handle</p> 486</td> 487<td class="cellrowborder" valign="top" width="50%"><p id="p16541153110317"><a name="p16541153110317"></a><a name="p16541153110317"></a>SPI device handle.</p> 488</td> 489</tr> 490</tbody> 491</table> 492 493``` 494SpiClose(spiHandle); /* Destroy the SPI device handle. */ 495``` 496 497## Usage Example<a name="section06541058155120"></a> 498 499The following example shows how to obtain an SPI device handle, set the configuration parameters, and then read or write data from or into the SPI device, and finally destroy the SPI device handle. 500 501``` 502#include "hdf_log.h" 503#include "spi_if.h" 504 505void SpiTestSample(void) 506{ 507 int32_t ret; 508 struct SpiCfg cfg; /* SPI device configuration information */ 509 struct SpiDevInfo spiDevinfo; /* SPI device descriptor */ 510 DevHandle spiHandle = NULL; /* SPI device handle */ 511 struct SpiMsg msg; /* Custom message to be transferred */ 512 uint8_t rbuff[4] = { 0 }; 513 uint8_t wbuff[4] = { 0x12, 0x34, 0x56, 0x78 }; 514 uint8_t wbuff2[4] = { 0xa1, 0xb2, 0xc3, 0xd4 }; 515 516 spiDevinfo.busNum = 0; /* SPI device bus number */ 517 spiDevinfo.csNum = 0; /* SPI device CS number */ 518 spiHandle = SpiOpen(&spiDevinfo); /* Obtain an SPI device handle based on spiDevinfo. */ 519 if (spiHandle == NULL) { 520 HDF_LOGE("SpiOpen: failed\n"); 521 return; 522 } 523 /* Obtain configuration parameters of an SPI device. */ 524 ret = SpiGetCfg(spiHandle, &cfg); 525 if (ret != 0) { 526 HDF_LOGE("SpiGetCfg: failed, ret %d\n", ret); 527 goto err; 528 } 529 cfg.maxSpeedHz = 115200; /* Change the maximum clock frequency to 115200. */ 530 cfg.bitsPerWord = 8; /* Change the word width to 8 bits. */ 531 /* Set configuration parameters for an SPI device. */ 532 ret = SpiSetCfg(spiHandle, &cfg); 533 if (ret != 0) { 534 HDF_LOGE("SpiSetCfg: failed, ret %d\n", ret); 535 goto err; 536 } 537 /* Write specified length of data into an SPI device. */ 538 ret = SpiWrite(spiHandle, wbuff, 4); 539 if (ret != 0) { 540 HDF_LOGE("SpiWrite: failed, ret %d\n", ret); 541 goto err; 542 } 543 /* Read data of a specific length from an SPI device. */ 544 ret = SpiRead(spiHandle, rbuff, 4); 545 if (ret != 0) { 546 HDF_LOGE("SpiRead: failed, ret %d\n", ret); 547 goto err; 548 } 549 msg.wbuf = wbuff2; /* Pointer to the data to write */ 550 msg.rbuf = rbuff; /* Pointer to the data to read */ 551 msg.len = 4; /* The length of the data to read or write is 4 bits. */ 552 msg.csChange = 1; /* Disable the CS before the next transfer. */ 553 msg.delayUs = 0; /* No delay before the next transfer */ 554 msg.speed = 115200; /* Speed of this transfer */ 555 /* Launch a custom transfer. The number of messages to be transferred is 1. */ 556 ret = SpiTransfer(spiHandle, &msg, 1); 557 if (ret != 0) { 558 HDF_LOGE("SpiTransfer: failed, ret %d\n", ret); 559 goto err; 560 } 561err: 562 /* Destroy the SPI device handle. */ 563 SpiClose(spiHandle); 564} 565``` 566 567
