1 /* 2 * Copyright (c) 2015-2020, Texas Instruments Incorporated 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of Texas Instruments Incorporated nor the names of 17 * its contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 /*!**************************************************************************** 33 * @file I2S.h 34 * @brief Inter-Integrated Circuit Sound (I2S) Bus Driver 35 * 36 * The I2S header file should be included in an application as follows: 37 * @code 38 * #include <ti/drivers/I2S.h> 39 * @endcode 40 * 41 * @anchor ti_drivers_I2S_Overview 42 * # Overview # 43 * 44 * The I2S driver facilitates the use of Inter-IC Sound (I2S), which is 45 * used to connect digital audio devices so that audio signals can be 46 * communicated between devices. The I2S driver simplifies reading and 47 * writing to any of the Multichannel Audio Serial Port (McASP) peripherals 48 * on the board with Receive and Transmit support. These include read and 49 * write characters on the McASP peripheral. 50 * 51 * I2S interfaces typically consist of 4 or 5 signals. The 5th signal is not 52 * systematically used. 53 * @li <b>Serial Clock (SCK)</b> also called Bit Clock (BCLK) or Multichannel 54 * Audio Frame Synchronization (McAFSX) 55 * @li <b>Word Select (WS)</b> also called Word Clock (WCLK), Left Right 56 * Clock (LRCLK) or Multichannel Audio Clock (McACLK) 57 * @li <b>Serial Data (SD0)</b> also called AD0, AD1, McAXR0, or possibly SDI 58 * @li <b>Serial Data (SD1)</b> also called AD1, ADI, McAXR1, or possibly SDI 59 * @li <b>Master Clock (MCLK)</b> 60 * 61 * <hr> 62 * @anchor ti_drivers_I2S_Usage 63 * # Usage # 64 * 65 * <b>The I2S driver provides the following APIs:</b> 66 * @li I2S_init(): @copybrief I2S_init 67 * @li I2S_open(): @copybrief I2S_open 68 * @li I2S_Params_init(): @copybrief I2S_Params_init 69 * @li I2S_Transaction_init(): @copybrief I2S_Transaction_init 70 * @li I2S_setReadQueueHead(): @copybrief I2S_setReadQueueHead 71 * @li I2S_setWriteQueueHead(): @copybrief I2S_setWriteQueueHead 72 * @li I2S_startClocks(): @copybrief I2S_startClocks 73 * @li I2S_startRead(): @copybrief I2S_startRead 74 * @li I2S_startWrite(): @copybrief I2S_startWrite 75 * @li I2S_stopRead(): @copybrief I2S_stopRead 76 * @li I2S_stopWrite(): @copybrief I2S_stopWrite 77 * @li I2S_stopClocks(): @copybrief I2S_stopClocks 78 * @li I2S_close(): @copybrief I2S_close 79 * 80 * <hr> 81 * @anchor ti_drivers_I2S_Driver_Transactions 82 * ### Transactions # 83 * 84 * Data transfers are achieved through #I2S_Transaction structures. Application is 85 * responsible to maintain the transactions queues. The I2S driver completes the 86 * transactions one by one. When a transaction is over, the I2S driver takes in 87 * consideration the next transaction (if the next transaction is NULL, the I2S 88 * drivers signals this to the user). 89 * The I2S driver relies on the following fields of the #I2S_Transaction to 90 * complete it: 91 * - the buffer 92 * - the length of the buffer 93 * - a pointer on the next transaction to achieve (kept in a List_Elem structure) 94 * . 95 * The I2S driver provides the following elements (fields of the #I2S_Transaction): 96 * - the number of untransferred bytes: the driver is designed to avoid memory corruption and will 97 * not complete an incomplete transaction (meaning a transaction where the buffer size would not 98 * permit to send or receive a whole number of samples). In this case, the system considers the 99 * samples of the beginning of the buffer and read/write as much as possible samples and ignore the 100 * end of the buffer. The number of untransafered bytes is the number of bytes left at the end of 101 * the buffer) 102 * - the number of completions of the transaction. This value is basically incremented by one 103 * every time the transaction is completed. 104 * 105 * Please note that these two fields are valid only when the transaction has been completed. 106 * Consult examples to get more details on the transaction usage. 107 * 108 * <hr> 109 * @anchor ti_drivers_I2S_Driver_ProvidingData 110 * ### Providing data to the I2S driver # 111 * Application is responsible to handle the queues of transactions. 112 * Application is also responsible to provide to the driver a pointer on 113 * the first transaction to consider (considering that all the following 114 * transactions are correctly queued). 115 * #I2S_setReadQueueHead() and #I2S_setWriteQueueHead() allow the user to 116 * set the first transaction to consider. These functions should be used only 117 * when no transaction is running on the considered interface. 118 * 119 * <hr> 120 * @anchor ti_drivers_I2S_Driver_StartStopClocks 121 * ### Start and stop clocks and transactions # 122 * Clocks can be started and stopped by the application. 123 * Read and write can be started and stopped independently. 124 * To start a transfer, clocks must be running. 125 * To stop the clocks no transfer must be running. 126 * Refer to the following functions for more details: 127 * @li I2S_startClocks() @li I2S_startRead() @li I2S_startWrite() 128 * @li I2S_stopRead() @li I2S_stopWrite() @li I2S_stopClocks() 129 * 130 * @note 131 * @li In #I2S_SLAVE mode, clocks must be started and stopped exactly like 132 * it is done in #I2S_MASTER mode. 133 * @li If the queue of transaction is not empty, the calls to #I2S_stopRead() 134 * and #I2S_stopWrite() are blocking and potentially long. 135 * 136 * <hr> 137 * @anchor ti_drivers_I2S_Examples 138 * ## Examples # 139 * 140 * @li @ref ti_drivers_I2S_Example_PlayAndStop "Play and Stop" 141 * @li @ref ti_drivers_I2S_Example_Streaming "Streaming" 142 * @li @ref ti_drivers_I2S_Example_RepeatMode "Repeat" 143 * 144 * <hr> 145 * @anchor ti_drivers_I2S_Example_PlayAndStop 146 * ### Mode Play and Stop # 147 * The following example shows how to simultaneously receive and send out a given amount of data. 148 * 149 * <hr> 150 * @anchor ti_drivers_I2S_Example_PlayAndStop_Code 151 * @code 152 * static I2S_Handle i2sHandle; 153 * 154 * static uint16_t readBuf1[500]; // the data read will end up in this buffer 155 * static uint16_t readBuf2[500]; // the data read will end up in this buffer 156 * static uint16_t readBuf3[500]; // the data read will end up in this buffer 157 * static uint16_t writeBuf1[250] = {...some data...}; // this buffer will be sent out 158 * static uint16_t writeBuf2[250] = {...some data...}; // this buffer will be sent out 159 * static uint16_t writeBuf3[250] = {...some data...}; // this buffer will be sent out 160 * 161 * static I2S_Transaction i2sRead1; 162 * static I2S_Transaction i2sRead2; 163 * static I2S_Transaction i2sRead3; 164 * static I2S_Transaction i2sWrite1; 165 * static I2S_Transaction i2sWrite2; 166 * static I2S_Transaction i2sWrite3; 167 * 168 * List_List i2sReadList; 169 * List_List i2sWriteList; 170 * 171 * static volatile bool readStopped = (bool)true; 172 * static volatile bool writeStopped = (bool)true; 173 * 174 * static void writeCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) { 175 * 176 * if(status & I2S_ALL_TRANSACTIONS_SUCCESS){ 177 * 178 * // Note: Here we do not queue new transfers or set a new queue-head. 179 * // The driver will stop sending out data on its own. 180 * writeStopped = (bool)true; 181 * } 182 * } 183 * 184 * static void readCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) { 185 * 186 * if(status & I2S_ALL_TRANSACTIONS_SUCCESS){ 187 * 188 * // Note: Here we do not queue new transfers or set a new queue-head. 189 * // The driver will stop receiving data on its own. 190 * readStopped = (bool)true; 191 * } 192 * } 193 * 194 * static void errCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) { 195 * 196 * // Handle the I2S error 197 * } 198 * 199 * void *modePlayAndStopThread(void *arg0) 200 * { 201 * I2S_Params i2sParams; 202 * 203 * I2S_init(); 204 * 205 * // Initialize I2S opening parameters 206 * I2S_Params_init(&i2sParams); 207 * i2sParams.fixedBufferLength = 500; // fixedBufferLength is the greatest common 208 * // divisor of all the different buffers 209 * // (here buffers' size are 500 and 1000 bytes) 210 * i2sParams.writeCallback = writeCallbackFxn ; 211 * i2sParams.readCallback = readCallbackFxn ; 212 * i2sParams.errorCallback = errCallbackFxn; 213 * 214 * i2sHandle = I2S_open(CONFIG_I2S0, &i2sParams); 215 * 216 * // Initialize the read-transactions 217 * I2S_Transaction_init(&i2sRead1); 218 * I2S_Transaction_init(&i2sRead2); 219 * I2S_Transaction_init(&i2sRead3); 220 * i2sRead1.bufPtr = readBuf1; 221 * i2sRead2.bufPtr = readBuf2; 222 * i2sRead3.bufPtr = readBuf3; 223 * i2sRead1.bufSize = sizeof(readBuf1); 224 * i2sRead2.bufSize = sizeof(readBuf2); 225 * i2sRead3.bufSize = sizeof(readBuf3); 226 * List_put(&i2sReadList, (List_Elem*)&i2sRead1); 227 * List_put(&i2sReadList, (List_Elem*)&i2sRead2); 228 * List_put(&i2sReadList, (List_Elem*)&i2sRead3); 229 * 230 * I2S_setReadQueueHead(i2sHandle, &i2sRead1); 231 * 232 * // Initialize the write-transactions 233 * I2S_Transaction_init(&i2sWrite1); 234 * I2S_Transaction_init(&i2sWrite2); 235 * I2S_Transaction_init(&i2sWrite3); 236 * i2sWrite1.bufPtr = writeBuf1; 237 * i2sWrite2.bufPtr = writeBuf2; 238 * i2sWrite3.bufPtr = writeBuf3; 239 * i2sWrite1.bufSize = sizeof(writeBuf1); 240 * i2sWrite2.bufSize = sizeof(writeBuf2); 241 * i2sWrite3.bufSize = sizeof(writeBuf3); 242 * List_put(&i2sWriteList, (List_Elem*)&i2sWrite1); 243 * List_put(&i2sWriteList, (List_Elem*)&i2sWrite2); 244 * List_put(&i2sWriteList, (List_Elem*)&i2sWrite3); 245 * 246 * I2S_setWriteQueueHead(i2sHandle, &i2sWrite1); 247 * 248 * I2S_startClocks(i2sHandle); 249 * I2S_startWrite(i2sHandle); 250 * I2S_startRead(i2sHandle); 251 * 252 * readStopped = (bool)false; 253 * writeStopped = (bool)false; 254 * 255 * while (1) { 256 * 257 * if(readStopped && writeStopped) { 258 * I2S_stopClocks(i2sHandle); 259 * I2S_close(i2sHandle); 260 * while (1); 261 * } 262 * } 263 * } 264 * @endcode 265 * 266 * \note If you desire to put only one transaction in the queue, fixedBufferLength must be inferior to half the length (in bytes) of the buffer to transfer. 267 * 268 * <hr> 269 * @anchor ti_drivers_I2S_Example_Streaming 270 * ### Writing Data in Continuous Streaming Mode # 271 * The following example shows how to read and write data in streaming mode. 272 * A dummy treatment of the data is also done. 273 * This example is not complete (semaphore and tasks creation are not shown) 274 * 275 * <hr> 276 * @anchor ti_drivers_I2S_Example_Streaming_Code 277 * @code 278 * static I2S_Handle i2sHandle; 279 * static sem_t semDataReadyForTreatment; 280 * 281 * // These buffers will successively be written, treated and sent out 282 * static uint16_t readBuf1[500]; 283 * static uint16_t readBuf2[500]; 284 * static uint16_t readBuf3[500]; 285 * static uint16_t readBuf4[500]; 286 * static uint16_t writeBuf1[500]={0}; 287 * static uint16_t writeBuf2[500]={0}; 288 * static uint16_t writeBuf3[500]={0}; 289 * static uint16_t writeBuf4[500]={0}; 290 * 291 * // These transactions will successively be part of the 292 * // i2sReadList, the treatmentList and the i2sWriteList 293 * static I2S_Transaction i2sRead1; 294 * static I2S_Transaction i2sRead2; 295 * static I2S_Transaction i2sRead3; 296 * static I2S_Transaction i2sRead4; 297 * static I2S_Transaction i2sWrite1; 298 * static I2S_Transaction i2sWrite2; 299 * static I2S_Transaction i2sWrite3; 300 * static I2S_Transaction i2sWrite4; 301 * 302 * List_List i2sReadList; 303 * List_List treatmentList; 304 * List_List i2sWriteList; 305 * 306 * static void writeCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) { 307 * 308 * // We must remove the previous transaction (the current one is not over) 309 * I2S_Transaction *transactionFinished = (I2S_Transaction*)List_prev(&transactionPtr->queueElement); 310 * 311 * if(transactionFinished != NULL){ 312 * // Remove the finished transaction from the write queue 313 * List_remove(&i2sWriteList, (List_Elem*)transactionFinished); 314 * 315 * // This transaction must now feed the read queue (we do not need anymore the data of this transaction) 316 * transactionFinished->queueElement.next = NULL; 317 * List_put(&i2sReadList, (List_Elem*)transactionFinished); 318 * 319 * // We need to queue a new transaction: let's take one in the treatment queue 320 * I2S_Transaction *newTransaction = (I2S_Transaction*)List_head(&treatmentList); 321 * if(newTransaction != NULL){ 322 * List_remove(&treatmentList, (List_Elem*)newTransaction); 323 * newTransaction->queueElement.next = NULL; 324 * List_put(&i2sWriteList, (List_Elem*)newTransaction); 325 * } 326 * } 327 * } 328 * 329 * static void readCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) { 330 * 331 * // We must remove the previous transaction (the current one is not over) 332 * I2S_Transaction *transactionFinished = (I2S_Transaction*)List_prev(&transactionPtr->queueElement); 333 * 334 * if(transactionFinished != NULL){ 335 * // The finished transaction contains data that must be treated 336 * List_remove(&i2sReadList, (List_Elem*)transactionFinished); 337 * transactionFinished->queueElement.next = NULL; 338 * List_put(&treatmentList, (List_Elem*)transactionFinished); 339 * 340 * // Start the treatment of the data 341 * sem_post(&semDataReadyForTreatment); 342 * 343 * // We do not need to queue transaction here: writeCallbackFxn takes care of this :) 344 * } 345 * } 346 * 347 * static void errCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) { 348 * 349 * // Handle the I2S error 350 * } 351 * 352 * void *echoExampleThread(void *arg0) 353 * { 354 * I2S_Params i2sParams; 355 * 356 * I2S_init(); 357 * 358 * int retc = sem_init(&semDataReadyForTreatment, 0, 0); 359 * if (retc == -1) { 360 * while (1); 361 * } 362 * 363 * // Initialize the treatmentList (this list is initially empty) 364 * List_clearList(&treatmentList); 365 * 366 * //Initialize I2S opening parameters 367 * I2S_Params_init(&i2sParams); 368 * i2sParams.fixedBufferLength = 1000; 369 * i2sParams.writeCallback = writeCallbackFxn ; 370 * i2sParams.readCallback = readCallbackFxn ; 371 * i2sParams.errorCallback = errCallbackFxn; 372 * 373 * i2sHandle = I2S_open(CONFIG_I2S0, &i2sParams); 374 * 375 * // Initialize the read-transactions 376 * I2S_Transaction_init(&i2sRead1); 377 * I2S_Transaction_init(&i2sRead2); 378 * I2S_Transaction_init(&i2sRead3); 379 * I2S_Transaction_init(&i2sRead4); 380 * i2sRead1.bufPtr = readBuf1; 381 * i2sRead2.bufPtr = readBuf2; 382 * i2sRead3.bufPtr = readBuf3; 383 * i2sRead4.bufPtr = readBuf4; 384 * i2sRead1.bufSize = sizeof(readBuf1); 385 * i2sRead2.bufSize = sizeof(readBuf2); 386 * i2sRead3.bufSize = sizeof(readBuf3); 387 * i2sRead4.bufSize = sizeof(readBuf4); 388 * List_clearList(&i2sReadList); 389 * List_put(&i2sReadList, (List_Elem*)&i2sRead1); 390 * List_put(&i2sReadList, (List_Elem*)&i2sRead2); 391 * List_put(&i2sReadList, (List_Elem*)&i2sRead3); 392 * List_put(&i2sReadList, (List_Elem*)&i2sRead4); 393 * 394 * I2S_setReadQueueHead(i2sHandle, &i2sRead1); 395 * 396 * // Initialize the write-transactions 397 * I2S_Transaction_init(&i2sWrite1); 398 * I2S_Transaction_init(&i2sWrite2); 399 * I2S_Transaction_init(&i2sWrite3); 400 * I2S_Transaction_init(&i2sWrite4); 401 * i2sWrite1.bufPtr = writeBuf1; 402 * i2sWrite2.bufPtr = writeBuf2; 403 * i2sWrite3.bufPtr = writeBuf3; 404 * i2sWrite4.bufPtr = writeBuf4; 405 * i2sWrite1.bufSize = sizeof(writeBuf1); 406 * i2sWrite2.bufSize = sizeof(writeBuf2); 407 * i2sWrite3.bufSize = sizeof(writeBuf3); 408 * i2sWrite4.bufSize = sizeof(writeBuf4); 409 * List_clearList(&i2sWriteList); 410 * List_put(&i2sWriteList, (List_Elem*)&i2sWrite1); 411 * List_put(&i2sWriteList, (List_Elem*)&i2sWrite2); 412 * List_put(&i2sWriteList, (List_Elem*)&i2sWrite3); 413 * List_put(&i2sWriteList, (List_Elem*)&i2sWrite4); 414 * 415 * I2S_setWriteQueueHead(i2sHandle, &i2sWrite1); 416 * 417 * I2S_startClocks(i2sHandle); 418 * I2S_startWrite(i2sHandle); 419 * I2S_startRead(i2sHandle); 420 * 421 * while (1) { 422 * uint8_t k = 0; 423 * I2S_Transaction* lastAchievedReadTransaction = NULL; 424 * 425 * retc = sem_wait(&semDataReadyForTreatment); 426 * if (retc == -1) { 427 * while (1); 428 * } 429 * 430 * lastAchievedReadTransaction = (I2S_Transaction*) List_head(&treatmentList); 431 * 432 * if(lastAchievedReadTransaction != NULL) { 433 * 434 * // Need a critical section to be sure to have corresponding bufPtr and bufSize 435 * uintptr_t key = HwiP_disable(); 436 * uint16_t *buf = lastAchievedReadTransaction->bufPtr; 437 * uint16_t bufLength = lastAchievedReadTransaction->bufSize / sizeof(uint16_t); 438 * HwiP_restore(key); 439 * 440 * // My dummy data treatment... 441 * for(k=0; k<bufLength; k++) { 442 * buf[k]--; 443 * } 444 * for(k=0; k<bufLength; k++) { 445 * buf[k]++; 446 * } 447 * } 448 * } 449 * } 450 * @endcode 451 * 452 * <hr> 453 * @anchor ti_drivers_I2S_Example_RepeatMode 454 * ### Writing Data in repeat Mode # 455 * The following example shows how to read and write data in repeat mode. 456 * The same buffers are continuously written and send out while the driver is not stopped. 457 * Here, we decide to only stop sending out after an arbitrary number of sending. 458 * 459 * <hr> 460 * @anchor ti_drivers_I2S_Example_RepeatMode_Code 461 * @code 462 * static I2S_Handle i2sHandle; 463 * 464 * // This buffer will be continuously re-written 465 * static uint16_t readBuf[500]; 466 * // This data will be continuously sent out 467 * static uint16_t writeBuf[500] = {...some cool data...}; 468 * 469 * static I2S_Transaction i2sRead; 470 * static I2S_Transaction i2sWrite; 471 * 472 * List_List i2sReadList; 473 * List_List i2sWriteList; 474 * 475 * static volatile bool writeFinished = (bool)false; 476 * static void writeCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) { 477 * 478 * // Nothing to do here: the buffer(s) are queued in a ring list, the transfers are 479 * // executed without any action from the application. 480 * 481 * // We must consider the previous transaction (ok, when you have only one transaction it's the same) 482 * I2S_Transaction *transactionFinished = (I2S_Transaction*)List_prev(&transactionPtr->queueElement); 483 * 484 * if(transactionFinished != NULL){ 485 * // After an arbitrary number of completion of the transaction, we will stop writting 486 * if(transactionFinished->numberOfCompletions >= 10) { 487 * 488 * // Note: You cannot use I2S_stopRead() / I2S_stopWrite() in the callback. 489 * // The execution of these functions is potentially blocking and can mess up the 490 * // system. 491 * 492 * writeFinished = (bool)true; 493 * } 494 * } 495 * } 496 * 497 * static void readCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) { 498 * // Nothing to do here: the buffer(s) are queued in a ring list, the transfers are 499 * // executed without any action from the application. 500 * } 501 * 502 * static void errCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) { 503 * 504 * // Handle the I2S error 505 * } 506 * 507 * void *modeRepeat(void *arg0) 508 * { 509 * I2S_Params i2sParams; 510 * 511 * // Initialize I2S opening parameters 512 * I2S_Params_init(&i2sParams); 513 * i2sParams.fixedBufferLength = 1000; // No problem here: the driver consider 514 * // the list as an infinite list. 515 * i2sParams.writeCallback = writeCallbackFxn ; 516 * i2sParams.readCallback = readCallbackFxn ; 517 * i2sParams.errorCallback = errCallbackFxn; 518 * 519 * i2sHandle = I2S_open(CONFIG_I2S0, &i2sParams); 520 * 521 * // Initialize the read-transactions 522 * I2S_Transaction_init(&i2sRead); 523 * i2sRead.bufPtr = readBuf; 524 * i2sRead.bufSize = sizeof(readBuf); 525 * List_put(&i2sReadList, (List_Elem*)&i2sRead); 526 * List_tail(&i2sReadList)->next = List_head(&i2sReadList);// Read buffers are queued in a ring-list 527 * List_head(&i2sReadList)->prev = List_tail(&i2sReadList); 528 * 529 * I2S_setReadQueueHead(i2sHandle, &i2sRead); 530 * 531 * // Initialize the write-transactions 532 * I2S_Transaction_init(&i2sWrite); 533 * i2sWrite.bufPtr = writeBuf; 534 * i2sWrite.bufSize = sizeof(writeBuf); 535 * List_put(&i2sWriteList, (List_Elem*)&i2sWrite); 536 * List_tail(&i2sWriteList)->next = List_head(&i2sWriteList); // Write buffers are queued in a ring-list 537 * List_head(&i2sWriteList)->prev = List_tail(&i2sWriteList); 538 * 539 * I2S_setWriteQueueHead(i2sHandle, &i2sWrite); 540 * 541 * I2S_startClocks(i2sHandle); 542 * I2S_startWrite(i2sHandle); 543 * I2S_startRead(i2sHandle); 544 * 545 * while (1) { 546 * 547 * if(writeFinished){ 548 * writeFinished = (bool)false; 549 * I2S_stopWrite(i2sHandle); 550 * } 551 * } 552 * } 553 * @endcode 554 * 555 * @note In the case of circular lists, there is no problem to put only 556 * one buffer in the queue. 557 * 558 * <hr> 559 * @anchor ti_drivers_I2S_Configuration 560 * # Configuration 561 * 562 * Refer to the @ref driver_configuration "Driver's Configuration" section 563 * for driver configuration information. 564 * <hr> 565 ****************************************************************************** 566 */ 567 568 #ifndef ti_drivers_I2S__include 569 #define ti_drivers_I2S__include 570 571 #include <stddef.h> 572 #include <stdbool.h> 573 #include <stdint.h> 574 575 #include <ti/drivers/utils/List.h> 576 577 578 #ifdef __cplusplus 579 extern "C" { 580 #endif 581 582 /** 583 * @defgroup I2S_STATUS Status Codes 584 * I2S_STATUS_* macros are general status codes used when user callback is called 585 * @{ 586 * @ingroup I2S_CONTROL 587 */ 588 589 /*! 590 * @brief Successful status code returned by I2S driver functions. 591 * 592 * I2S driver functions return I2S_ALL_TRANSACTION_SUCCESS if ALL the queued transactions 593 * were executed successfully. 594 */ 595 #define I2S_ALL_TRANSACTIONS_SUCCESS (0x0001U) 596 597 /*! 598 * @brief Successful status code returned by I2S driver functions. 599 * 600 * I2S driver functions return I2S_TRANSACTION_SUCCESS if ONE queued transaction 601 * was executed successfully. 602 */ 603 #define I2S_TRANSACTION_SUCCESS (0x0002U) 604 605 /*! 606 * @brief Error status code returned by I2S driver functions. 607 * 608 * I2S driver functions return I2S_TIMEOUT_ERROR if I2S module lost the audio clock. 609 * If this error has been raised, I2S module must be reseted and restarted. 610 */ 611 #define I2S_TIMEOUT_ERROR (0x0100U) 612 613 /*! 614 * @brief Error status code returned by I2S driver functions. 615 * 616 * I2S driver functions return I2S_BUS_ERROR if I2S module faced problem with the DMA 617 * bus (DMA transfer not completed in time). 618 * If this error has been raised, I2S module must be reseted and restarted. 619 */ 620 #define I2S_BUS_ERROR (0x0200U) 621 622 /*! 623 * @brief Error status code returned by I2S driver functions. 624 * 625 * I2S driver functions return I2S_WS_ERROR if I2S module detect noise on the WS signal. 626 * If this error has been raised, I2S module must be reseted and restarted. 627 */ 628 #define I2S_WS_ERROR (0x0400U) 629 630 /*! 631 * @brief Error status code returned by I2S driver functions. 632 * 633 * I2S driver functions return I2S_PTR_READ_ERROR if I2S module ran out of data 634 * on the read interface (DMA pointer not loaded in time). 635 * If this error has been raised, I2S module must be reseted and restarted. 636 */ 637 #define I2S_PTR_READ_ERROR (0x0800U) 638 639 /*! 640 * @brief Error status code returned by I2S driver functions. 641 * 642 * I2S driver functions return I2S_PTR_WRITE_ERROR if I2S module ran out of data 643 * on the write interface (DMA pointer not loaded in time). 644 * If this error has been raised, I2S module must be reseted and restarted. 645 */ 646 #define I2S_PTR_WRITE_ERROR (0x1000U) 647 /** @}*/ 648 649 /*! @brief I2S Global configuration 650 * 651 * The I2S_Config structure contains a set of pointers used to characterize 652 * the I2S driver implementation. 653 * 654 * This structure needs to be defined before calling I2S_init() and it must 655 * not be changed thereafter. 656 * 657 * @sa I2S_init() 658 */ 659 typedef struct { 660 /*! Pointer to a driver specific data object */ 661 void *object; 662 663 /*! Pointer to a driver specific hardware attributes structure */ 664 void const *hwAttrs; 665 } I2S_Config; 666 667 /*! 668 * @brief A handle that is returned from a I2S_open() call. 669 */ 670 typedef I2S_Config *I2S_Handle; 671 672 /*! 673 * @brief I2S transaction descriptor. 674 */ 675 typedef struct { 676 /*! Used internally to link descriptors together */ 677 List_Elem queueElement; 678 /*! Pointer to the buffer */ 679 void *bufPtr; 680 /*! Size of the buffer. */ 681 size_t bufSize; 682 /*! Internal use only. Number of bytes written to or read from the buffer. */ 683 size_t bytesTransferred; 684 /*! Number of non-transfered bytes at transaction's end. */ 685 size_t untransferredBytes; 686 /*! Parameter incremented each time the transaction is completed. */ 687 uint16_t numberOfCompletions; 688 /*! Internal argument. Application must not modify this element. */ 689 uintptr_t arg; 690 } I2S_Transaction; 691 692 /*! 693 * @brief The definition of a user-callback function used by the I2S driver 694 * 695 * @param I2S_Handle I2S_Handle 696 * 697 * @param status Status of the operation (possible values are : 698 * :I2S_STATUS_SUCCESS, :I2S_STATUS_ERROR, 699 * :I2S_STATUS_BUFFER_UNAVAILABLE, :I2S_STATUS_TIMEOUT) 700 * 701 * @param I2S_Transaction *transactionPtr: Pointer on the transaction that has just started. 702 * For error callbacks, transactionPtr points on NULL. 703 * 704 */ 705 typedef void (*I2S_Callback)(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr); 706 707 /*! 708 * @brief The definition of a function used to set the I2S register 709 * 710 * @param uint32_t ui32Base: base address of the I2S module. 711 * 712 * @param uint32_t ui32NextPointer: pointer on an I2S buffer. 713 * 714 */ 715 typedef void (*I2S_RegUpdate)(uint32_t ui32Base, uint32_t ui32NextPointer); 716 717 /*! 718 * @brief The definition of a function used to stop an I2S interface 719 * 720 * @param I2S_Handle I2S_Handle 721 * 722 */ 723 typedef void (*I2S_StopInterface)(I2S_Handle handle); 724 725 /*! 726 * @brief I2S slot memory length setting 727 * 728 * The enum defines if the module uses a 16 bits or a 24 bits buffer in memory. 729 * This value has no influence on the number of bit transmitted. 730 */ 731 typedef enum { 732 733 I2S_MEMORY_LENGTH_8BITS = 8U, /*!< Buffer used is 8 bits length. Not available for CC26XX. */ 734 I2S_MEMORY_LENGTH_16BITS = 16U, /*!< Buffer used is 16 bits length. */ 735 I2S_MEMORY_LENGTH_24BITS = 24U, /*!< Buffer used is 24 bits length. */ 736 I2S_MEMORY_LENGTH_32BITS = 32U /*!< Buffer used is 32 bits length. Not available for CC26XX. */ 737 738 } I2S_MemoryLength; 739 740 /*! 741 * @brief I2S master / slave selection 742 * 743 * The enum defines if the module acts like a master (clocks are internally generated) 744 * or a slave (the clocks are externally generated). 745 */ 746 typedef enum { 747 748 I2S_SLAVE = 0, /*!< Module is a slave, clocks are externally generated. */ 749 I2S_MASTER = 1 /*!< Module is a master, clocks are internally generated. */ 750 751 } I2S_Role; 752 753 /*! 754 * @brief I2S sampling setting 755 * 756 * The enum defines if sampling is done on BLCK rising or falling edges. 757 */ 758 typedef enum { 759 760 I2S_SAMPLING_EDGE_FALLING = 0, /*!< Sampling on falling edges. */ 761 I2S_SAMPLING_EDGE_RISING = 1 /*!< Sampling on rising edges. */ 762 763 } I2S_SamplingEdge; 764 765 /*! 766 * @brief I2S phase setting 767 * 768 * The enum defines if the I2S if set with single or dual phase. 769 */ 770 typedef enum { 771 772 I2S_PHASE_TYPE_SINGLE = 0U, /*!< Single phase */ 773 I2S_PHASE_TYPE_DUAL = 1U, /*!< Dual phase */ 774 775 } I2S_PhaseType; 776 777 /*! 778 * @brief I2S data interface configuration 779 * 780 * The enum defines the different settings for the data interfaces (SD0 and SD1). 781 */ 782 typedef enum { 783 784 I2S_SD0_DISABLED = 0x00U, /*!< SD0 is disabled */ 785 I2S_SD0_INPUT = 0x01U, /*!< SD0 is an input */ 786 I2S_SD0_OUTPUT = 0x02U, /*!< SD0 is an output */ 787 I2S_SD1_DISABLED = 0x00U, /*!< SD1 is disabled */ 788 I2S_SD1_INPUT = 0x10U, /*!< SD1 is an input */ 789 I2S_SD1_OUTPUT = 0x20U /*!< SD1 is an output */ 790 791 } I2S_DataInterfaceUse; 792 793 /*! 794 * @brief Channels used selection 795 * 796 * The enum defines different settings to activate the expected channels. 797 */ 798 typedef enum { 799 800 I2S_CHANNELS_NONE = 0x00U, /*!< No channel activated */ 801 I2S_CHANNELS_MONO = 0x01U, /*!< MONO: only channel one is activated */ 802 I2S_CHANNELS_MONO_INV = 0x02U, /*!< MONO INVERERTED: only channel two is activated */ 803 I2S_CHANNELS_STEREO = 0x03U, /*!< STEREO: channels one and two are activated */ 804 I2S_1_CHANNEL = 0x01U, /*!< 1 channel is activated */ 805 I2S_2_CHANNELS = 0x03U, /*!< 2 channels are activated */ 806 I2S_3_CHANNELS = 0x07U, /*!< 3 channels are activated */ 807 I2S_4_CHANNELS = 0x0FU, /*!< 4 channels are activated */ 808 I2S_5_CHANNELS = 0x1FU, /*!< 5 channels are activated */ 809 I2S_6_CHANNELS = 0x3FU, /*!< 6 channels are activated */ 810 I2S_7_CHANNELS = 0x7FU, /*!< 7 channels are activated */ 811 I2S_8_CHANNELS = 0xFFU, /*!< 8 channels are activated */ 812 I2S_CHANNELS_ALL = 0xFFU /*!< All the eight channels are activated */ 813 814 } I2S_ChannelConfig; 815 816 /*! 817 * @brief Basic I2S Parameters 818 * 819 * I2S parameters are used to with the I2S_open() call. Default values for 820 * these parameters are set using I2S_Params_init(). 821 * 822 * @sa I2S_Params_init() 823 */ 824 typedef struct { 825 826 bool trueI2sFormat; 827 /*!< Activate "true I2S format". 828 * false: Data are read/write on the data lines from the first SCK period of 829 * the WS half-period to the last SCK edge of the WS half-period. 830 * true: Data are read/write on the data lines from the second SCK period of 831 * the WS half-period to the first SCK edge of the next WS half-period. 832 * If no padding is activated, this corresponds to the I2S standard. */ 833 834 bool invertWS; 835 /*!< WS must be internally inverted when using I2S data format. 836 * false: The WS signal is not internally inverted. 837 * true: The WS signal is internally inverted. */ 838 839 bool isMSBFirst; 840 /*!< Endianness selection. Not available on CC26XX. 841 * false: The samples are transmitted LSB first. 842 * true: The samples are transmitted MSB first. */ 843 844 bool isDMAUnused; 845 /*!< Selection between DMA transmissions and CPU transmissions. 846 * false: Transmission are performed by DMA. 847 * true: Transmission are performed by CPU. 848 * Not available for CC26XX: all transmissions are performed by CPU. */ 849 850 I2S_MemoryLength memorySlotLength; 851 /*!< Memory buffer used. 852 * #I2S_MEMORY_LENGTH_8BITS: Memory length is 8 bits (not available for CC26XX). 853 * #I2S_MEMORY_LENGTH_16BITS: Memory length is 16 bits. 854 * #I2S_MEMORY_LENGTH_24BITS: Memory length is 24 bits. 855 * #I2S_MEMORY_LENGTH_32BITS: Memory length is 32 bits (not available for CC26XX).*/ 856 857 uint8_t beforeWordPadding; 858 /*!< Number of SCK periods between the first WS edge and the MSB of the first audio channel data transferred during the phase.*/ 859 860 uint8_t afterWordPadding; 861 /*!< Number of SCK periods between the LSB of the an audio channel and the MSB of the next audio channel.*/ 862 863 uint8_t bitsPerWord; 864 /*!< Bits per sample (Word length): must be between 8 and 24 bits. */ 865 866 I2S_Role moduleRole; 867 /*!< Select if the I2S module is a Slave or a Master. 868 * - #I2S_SLAVE: The device is a slave (clocks are generated externally). 869 * - #I2S_MASTER: The device is a master (clocks are generated internally). */ 870 871 I2S_SamplingEdge samplingEdge; 872 /*!< Select edge sampling type. 873 * - #I2S_SAMPLING_EDGE_FALLING: Sampling on falling edges (for DSP data format). 874 * - #I2S_SAMPLING_EDGE_RISING: Sampling on rising edges (for I2S, LJF and RJF data formats). */ 875 876 I2S_DataInterfaceUse SD0Use; 877 /*!< Select if SD0 is an input, an output or disabled. 878 * - #I2S_SD0_DISABLED: Disabled. 879 * - #I2S_SD0_INPUT: Input. 880 * - #I2S_SD0_OUTPUT: Output. */ 881 882 I2S_DataInterfaceUse SD1Use; 883 /*!< Select if SD1 is an input, an output or disabled. 884 * - #I2S_SD1_DISABLED: Disabled. 885 * - #I2S_SD1_INPUT: Input. 886 * - #I2S_SD1_OUTPUT: Output. */ 887 888 I2S_ChannelConfig SD0Channels; 889 /*!< This parameter is a bit mask indicating which channels are valid on SD0. 890 * If phase type is "dual", maximum channels number is two. 891 * Valid channels on SD1 and SD0 can be different. 892 * For dual phase mode: 893 * - #I2S_CHANNELS_NONE: No channel activated: 894 * read -> I2S does not receive anything (no buffer consumption) 895 * write -> I2S does not send anything (no buffer consumption) 896 * - #I2S_CHANNELS_MONO: Only channel 1 is activated: 897 * read -> I2S only reads channel 1 898 * write -> I2S transmits the data on channel 1 and duplicates it on channel 2 899 * - #I2S_CHANNELS_MONO_INV: Only channel 2 is activated: 900 * read -> I2S only reads channel 2 901 * write -> I2S transmits the data on channel 2 and duplicates it on the channel 1 of the next word 902 * - #I2S_CHANNELS_STEREO: STEREO: 903 * read -> I2S reads both channel 1 and channel 2 904 * write -> I2S transmits data both on channel 1 and channel 2 905 * . 906 * For single phase mode: 907 * - Various number of channels can be activated using: #I2S_1_CHANNEL, #I2S_2_CHANNELS, #I2S_3_CHANNELS, #I2S_4_CHANNELS, 908 * #I2S_5_CHANNELS, #I2S_6_CHANNELS, #I2S_7_CHANNELS, #I2S_8_CHANNELS. 909 * - #I2S_CHANNELS_ALL: The eight channels are activated */ 910 911 I2S_ChannelConfig SD1Channels; 912 /*!< This parameter is a bit mask indicating which channels are valid on SD1. 913 * If phase type is "dual", maximum channels number is two. 914 * Valid channels on SD1 and SD0 can be different. 915 * For dual phase mode: 916 * - #I2S_CHANNELS_NONE: No channel activated: 917 * read -> I2S does not receive anything (no buffer consumption) 918 * write -> I2S does not send anything (no buffer consumption) 919 * - #I2S_CHANNELS_MONO: Only channel 1 is activated: 920 * read -> I2S only reads channel 1 921 * write -> I2S transmits the data on channel 1 and duplicates it on channel 2 922 * - #I2S_CHANNELS_MONO_INV: Only channel 2 is activated: 923 * read -> I2S only reads channel 2 924 * write -> I2S transmits the data on channel 2 and duplicates it on the channel 1 of the next word 925 * - #I2S_CHANNELS_STEREO: STEREO: 926 * read -> I2S reads both channel 1 and channel 2 927 * write -> I2S transmits data both on channel 1 and channel 2 928 * . 929 * For single phase mode: 930 * - Various number of channels can be activated using: #I2S_1_CHANNEL, #I2S_2_CHANNELS, #I2S_3_CHANNELS, #I2S_4_CHANNELS, 931 * #I2S_5_CHANNELS, #I2S_6_CHANNELS, #I2S_7_CHANNELS, #I2S_8_CHANNELS. 932 * - #I2S_CHANNELS_ALL: The eight channels are activated */ 933 934 I2S_PhaseType phaseType; 935 /*!< Select phase type. 936 * - #I2S_PHASE_TYPE_SINGLE: Single phase (for DSP format): up to eight channels are usable. 937 * - #I2S_PHASE_TYPE_DUAL: Dual phase (for I2S, LJF and RJF data formats): up to two channels are usable. 938 * . 939 * This parameter must not be considered on CC32XX. This chip only allows dual phase formats.*/ 940 941 uint16_t fixedBufferLength; 942 /*!< Number of consecutive bytes of the samples buffers. This field must be set to a value x different from 0. 943 * All the data buffers used (both for input and output) must contain N*x bytes (with N an integer verifying N>0). */ 944 945 uint16_t startUpDelay; 946 /*!< Time (in number of WS cycles) to wait before the first transfer. */ 947 948 uint16_t MCLKDivider; 949 /*!< Select the frequency divider for MCLK signal. Final value of MCLK is 48MHz/MCLKDivider. Value must be selected between 2 and 1024. */ 950 951 uint32_t samplingFrequency; 952 /*!< I2S sampling frequency configuration in samples/second. 953 * SCK frequency limits: 954 *- For CC26XX, SCK frequency should be between 47 kHz and 4 MHz. 955 *- For CC32XX, SCK frequency should be between 57 Hz and 8 MHz. */ 956 957 I2S_Callback readCallback; 958 /*!< Pointer to read callback. Cannot be NULL if a read interface is activated. */ 959 960 I2S_Callback writeCallback; 961 /*!< Pointer to write callback. Cannot be NULL if a write interface is activated. */ 962 963 I2S_Callback errorCallback; 964 /*!< Pointer to error callback. Cannot be NULL. */ 965 966 void *custom; 967 /*!< Pointer to device specific custom params */ 968 } I2S_Params; 969 970 /*! 971 * @brief Default I2S_Params structure 972 * 973 * @sa I2S_Params_init() 974 */ 975 extern const I2S_Params I2S_defaultParams; 976 977 /*! 978 * @brief Function to close a given I2S peripheral specified by the I2S 979 * handle. 980 * 981 * @pre I2S_open() had to be called first. 982 * 983 * @param [in] handle An I2S_Handle returned from I2S_open 984 * 985 * @sa I2S_open() 986 */ 987 extern void I2S_close(I2S_Handle handle); 988 989 /*! 990 * @brief Function to initializes the I2S module 991 * 992 * @pre The I2S_config structure must exist and be persistent before this 993 * function can be called. This function must also be called before 994 * any other I2S driver APIs. This function call does not modify any 995 * peripheral registers. 996 */ 997 extern void I2S_init(void); 998 999 /*! 1000 * @brief Function to initialize a given I2S peripheral specified by the 1001 * particular index value. The parameter specifies which mode the I2S 1002 * will operate. 1003 * 1004 * @pre I2S controller has been initialized 1005 * 1006 * @param [inout] index Logical peripheral number for the I2S indexed into 1007 * the I2S_config table 1008 * 1009 * @param [in] params Pointer to an parameter block. 1010 * All the fields in this structure are RO (read-only). 1011 * Provide a NULL pointer cannot open the module. 1012 * 1013 * @return An I2S_Handle on success or a NULL on an error or if it has been 1014 * opened already. 1015 * 1016 * @sa I2S_init() 1017 * @sa I2S_close() 1018 */ 1019 extern I2S_Handle I2S_open(uint_least8_t index, I2S_Params *params); 1020 1021 /*! 1022 * @brief Function to initialize the I2S_Params struct to its defaults 1023 * 1024 * @param [out] params An pointer to I2S_Params structure for 1025 * initialization 1026 * 1027 * Defaults values are: 1028 * @code 1029 * params.samplingFrequency = 8000; 1030 * params.memorySlotLength = I2S_MEMORY_LENGTH_16BITS; 1031 * params.moduleRole = I2S_MASTER; 1032 * params.trueI2sFormat = (bool)true; 1033 * params.invertWS = (bool)true; 1034 * params.isMSBFirst = (bool)true; 1035 * params.isDMAUnused = (bool)false; 1036 * params.samplingEdge = I2S_SAMPLING_EDGE_RISING; 1037 * params.beforeWordPadding = 0; 1038 * params.bitsPerWord = 16; 1039 * params.afterWordPadding = 0; 1040 * params.fixedBufferLength = 1; 1041 * params.SD0Use = I2S_SD0_OUTPUT; 1042 * params.SD1Use = I2S_SD1_INPUT; 1043 * params.SD0Channels = I2S_CHANNELS_STEREO; 1044 * params.SD1Channels = I2S_CHANNELS_STEREO; 1045 * params.phaseType = I2S_PHASE_TYPE_DUAL; 1046 * params.startUpDelay = 0; 1047 * params.MCLKDivider = 40; 1048 * params.readCallback = NULL; 1049 * params.writeCallback = NULL; 1050 * params.errorCallback = NULL; 1051 * params.custom = NULL; 1052 * @endcode 1053 * 1054 * @param params Parameter structure to initialize 1055 */ 1056 extern void I2S_Params_init(I2S_Params *params); 1057 1058 /*! 1059 * @brief Initialize an I2S_Transaction struct to known state. 1060 * 1061 * The I2S_Transaction struct is put in a known state. The application is 1062 * still responsible for populating some of the fields. 1063 * For example, the user is responsible to provide the buffer containing the 1064 * data and the size of it. 1065 * User provided buffer's size must matche with the I2S settings. 1066 * If the buffer size is not adapted, the I2S module will truncate it. 1067 * Authorized buffer sizes depend on the number of activated outputs, the number 1068 * of channels activated, the memory slots length (16 or 24 bits), and the 1069 * fixed-buffer-size eventually provided. 1070 * Authorized buffer sizes are all the multiple values of the value of 1071 * handle->object->memoryStepOut. 1072 * 1073 * @param [out] transaction Transaction struct to initialize. 1074 */ 1075 extern void I2S_Transaction_init(I2S_Transaction *transaction); 1076 1077 /*! 1078 * @brief Function to set the first read-transaction to consider 1079 * 1080 * At the end of each transaction, I2S driver takes in consideration the next 1081 * transaction. Application is responsible to handle the queue. 1082 * 1083 * @param [in] handle An I2S_Handle. 1084 * 1085 * @param [in] transaction A pointer to an I2S_Transaction object. The bufPtr 1086 * and bufSize fields must be set to a buffer and the 1087 * size of the buffer before passing to this function. 1088 * 1089 * @return void 1090 * 1091 * @sa I2S_setWriteQueueHead() 1092 */ 1093 extern void I2S_setReadQueueHead(I2S_Handle handle, I2S_Transaction *transaction); 1094 1095 /*! 1096 * @brief Function to set the first write-transaction to consider 1097 * 1098 * At the end of each transaction, I2S driver takes in consideration the next 1099 * transaction. Application is responsible to handle the queue. 1100 * 1101 * @param [in] handle An I2S_Handle. 1102 * 1103 * @param [in] transaction A pointer to an I2S_Transaction object. The bufPtr 1104 * and bufSize fields must be set to a buffer and the 1105 * size of the buffer before passing to this function. 1106 * 1107 * @return void 1108 * 1109 * @sa I2S_setReadQueueHead() 1110 */ 1111 extern void I2S_setWriteQueueHead(I2S_Handle handle, I2S_Transaction *transaction); 1112 1113 /*! 1114 * @brief Start the WS, SCK and MCLK clocks. 1115 * 1116 * This function enable WS, SCK and MCLK (if activated) clocks. This is required before starting 1117 * any reading or a writing transaction. 1118 * This function is supposed to be executed both in slave and master mode. 1119 * 1120 * @param [in] handle An I2S_Handle. 1121 * 1122 * @return void 1123 * 1124 * @sa I2S_stopClocks() 1125 */ 1126 extern void I2S_startClocks(I2S_Handle handle); 1127 1128 /*! 1129 * @brief Stops the WS, SCK and MCLK clocks. 1130 * 1131 * This function disable WS, SCK and MCLK clocks. 1132 * This function must be executed only if no transaction is in progress. 1133 * This function is supposed to be executed in a Task context (NOT in a HWI or Callback context). 1134 * This function is supposed to be executed both in slave and master mode. 1135 * 1136 * @warning This function is supposed to be executed in a Task context 1137 * (NOT in a HWI or Callback context). 1138 * 1139 * @param [in] handle An I2S_Handle. 1140 * 1141 * @return void 1142 * 1143 * @sa I2S_stopRead() 1144 * @sa I2S_stopWrite() 1145 */ 1146 extern void I2S_stopClocks(I2S_Handle handle); 1147 1148 /*! 1149 * @brief Start read transactions. 1150 * 1151 * This function starts reception of the transactions stored in the read-queue. 1152 * and returns immediately. At the completion of each transaction the readCallback 1153 * provided is executed. 1154 * 1155 * If the queue for read transactions becomes empty (i.e. the read Callback is 1156 * triggered with status #I2S_ALL_TRANSACTIONS_SUCCESS and the application has 1157 * not queued new transactions or defined a new first read-transaction to consider 1158 * using #I2S_setReadQueueHead()), the driver will stop the read interface on its 1159 * own in order to avoid the occurrence of errors (such as #I2S_PTR_READ_ERROR). 1160 * 1161 * @pre First read-transaction to consider must be set and clocks must be running 1162 * before calling this function. 1163 * 1164 * @param [in] handle An I2S_Handle. 1165 * 1166 * @return void 1167 * 1168 * @sa I2S_startClocks() 1169 * @sa I2S_setReadQueueHead() 1170 */ 1171 extern void I2S_startRead(I2S_Handle handle); 1172 1173 /*! 1174 * @brief Start write transactions. 1175 * 1176 * This function starts transmission of the transactions stored in the write-queue 1177 * and returns immediately. At the completion of each transaction the write Callback 1178 * provided is executed. 1179 * 1180 * If the queue for write transactions becomes empty (i.e. the write Callback is 1181 * triggered with status #I2S_ALL_TRANSACTIONS_SUCCESS and the application has not 1182 * queued new transactions or defined a new first write-transaction to consider using 1183 * #I2S_setWriteQueueHead()), the driver will stop the write interface on its own in 1184 * order to avoid the occurrence of errors (such as #I2S_PTR_WRITE_ERROR). 1185 * 1186 * @pre First write-transaction to consider must be set and clocks must be running 1187 * before calling this function. 1188 * 1189 * @param [in] handle An I2S_Handle. 1190 * 1191 * @return void 1192 * 1193 * @sa I2S_startClocks() 1194 * @sa I2S_setWriteQueueHead() 1195 */ 1196 extern void I2S_startWrite(I2S_Handle handle); 1197 1198 /*! 1199 * @brief Stop read transactions. 1200 * 1201 * This function stops the reception of read transactions correctly so that 1202 * read operations can be safely restarted later. 1203 * 1204 * The application can decide at any time to suspend the reception of data by calling 1205 * this function. In this case (and because the transaction queue is not empty) the 1206 * execution of #I2S_stopRead() is blocked until the current transaction is completed 1207 * (this ensures that the I2S read interface is correctly stopped). Therefore, this 1208 * function must be executed in a Task context (not in a HWI or Callback context). 1209 * 1210 * After the transfers have been stopped (either by calling #I2S_stopRead() or because 1211 * the queue has been empty), the application can resume the transfers using the 1212 * function #I2S_startRead(). If the read-queue was empty application must beforehand 1213 * set the first read-transaction using #I2S_setReadQueueHead(). 1214 * 1215 * @param [in] handle An I2S_Handle. 1216 * 1217 * @return void 1218 */ 1219 extern void I2S_stopRead(I2S_Handle handle); 1220 1221 /*! 1222 * @brief Stop write transactions. 1223 * 1224 * This function stops the transmission of write transactions correctly so that 1225 * writing operations can be safely restarted later. 1226 * 1227 * The application can decide at any time to suspend the sending of data by calling 1228 * this function. In this case (and because the transaction queue is not empty) the 1229 * execution of #I2S_stopWrite() is blocked until the current transaction is completed 1230 * (this ensures that the I2S write interface is correctly stopped). Therefore, this 1231 * function must be executed in a Task context (not in a HWI or Callback context). 1232 * 1233 * After the transfers have been stopped (either by calling #I2S_stopWrite() or because 1234 * the queue has been empty), the application can resume the transfers using the 1235 * function #I2S_startWrite(). If the write-queue was empty application must beforehand 1236 * set the first write-transaction using #I2S_setWriteQueueHead(). 1237 * 1238 * @param [in] handle An I2S_Handle. 1239 * 1240 * @return void 1241 */ 1242 extern void I2S_stopWrite(I2S_Handle handle); 1243 1244 #ifdef __cplusplus 1245 } 1246 #endif 1247 1248 #endif /* ti_drivers_I2S__include */ 1249
