I2S.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015-2021, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
 *  @file       I2S.h
 *  @brief      Inter-Integrated Circuit Sound (I2S) Bus Driver
 *
 *  The I2S header file should be included in an application as follows:
 *  @code
 *  #include <ti/drivers/I2S.h>
 *  @endcode
 *
 *  @anchor ti_drivers_I2S_Overview
 *  # Overview #
 *
 *  The I2S driver facilitates the use of Inter-IC Sound (I2S), which is
 *  used to connect digital audio devices so that audio signals can be
 *  communicated between devices. The I2S driver simplifies reading and
 *  writing to any of the Multichannel Audio Serial Port (McASP) peripherals
 *  on the board with Receive and Transmit support. These include read and
 *  write characters on the McASP peripheral.
 *
 *  I2S interfaces typically consist of 4 or 5 signals. The 5th signal is not
 *  systematically used.
 *  @li <b>Serial Clock (SCK)</b> also called Bit Clock (BCLK) or Multichannel
 *      Audio Frame Synchronization (McAFSX)
 *  @li <b>Word Select (WS)</b> also called Word Clock (WCLK), Left Right
 *      Clock (LRCLK) or Multichannel Audio Clock (McACLK)
 *  @li <b>Serial Data (SD0)</b> also called AD0, AD1, McAXR0, or possibly SDI
 *  @li <b>Serial Data (SD1)</b> also called AD1, ADI, McAXR1, or possibly SDI
 *  @li <b>Master Clock (MCLK)</b>
 *
 *  <hr>
 *  @anchor ti_drivers_I2S_Usage
 *  # Usage #
 *
 *  <b>The I2S driver provides the following APIs:</b>
 *  @li I2S_init(): @copybrief I2S_init
 *  @li I2S_open(): @copybrief I2S_open
 *  @li I2S_Params_init(): @copybrief I2S_Params_init
 *  @li I2S_Transaction_init(): @copybrief I2S_Transaction_init
 *  @li I2S_setReadQueueHead(): @copybrief I2S_setReadQueueHead
 *  @li I2S_setWriteQueueHead(): @copybrief I2S_setWriteQueueHead
 *  @li I2S_startClocks(): @copybrief I2S_startClocks
 *  @li I2S_startRead(): @copybrief I2S_startRead
 *  @li I2S_startWrite(): @copybrief I2S_startWrite
 *  @li I2S_stopRead(): @copybrief I2S_stopRead
 *  @li I2S_stopWrite(): @copybrief I2S_stopWrite
 *  @li I2S_stopClocks(): @copybrief I2S_stopClocks
 *  @li I2S_close(): @copybrief I2S_close
 *
 *  <hr>
 *  @anchor ti_drivers_I2S_Driver_Transactions
 *  ### Transactions #
 *
 *  Data transfers are achieved through #I2S_Transaction structures. Application is
 *  responsible to maintain the transactions queues. The I2S driver completes the
 *  transactions one by one. When a transaction is over, the I2S driver takes in
 *  consideration the next transaction (if the next transaction is NULL, the I2S
 *  drivers signals this to the user).
 *  The I2S driver relies on the following fields of the #I2S_Transaction to
 *  complete it:
 *  - the buffer
 *  - the length of the buffer
 *  - a pointer on the next transaction to achieve (kept in a List_Elem structure)
 *  .
 *  The I2S driver provides the following elements (fields of the #I2S_Transaction):
 *  - the number of untransferred bytes: the driver is designed to avoid memory corruption and will
 *  not complete an incomplete transaction (meaning a transaction where the buffer size would not
 *  permit to send or receive a whole number of samples). In this case, the system considers the
 *  samples of the beginning of the buffer and read/write as much as possible samples and ignore the
 *  end of the buffer. The number of untransafered bytes is the number of bytes left at the end of
 *  the buffer)
 *  - the number of completions of the transaction. This value is basically incremented by one
 *  every time the transaction is completed.
 *
 *  Please note that these two fields are valid only when the transaction has been completed.
 *  Consult examples to get more details on the transaction usage.
 *
 *  <hr>
 *  @anchor ti_drivers_I2S_Driver_ProvidingData
 *  ### Providing data to the I2S driver #
 *  Application is responsible to handle the queues of transactions.
 *  Application is also responsible to provide to the driver a pointer on
 *  the first transaction to consider (considering that all the following
 *  transactions are correctly queued).
 *  #I2S_setReadQueueHead() and #I2S_setWriteQueueHead()  allow the user to
 *  set the first transaction to consider. These functions should be used only
 *  when no transaction is running on the considered interface.
 *
 *  <hr>
 *  @anchor ti_drivers_I2S_Driver_StartStopClocks
 *  ### Start and stop clocks and transactions #
 *  Clocks can be started and stopped by the application.
 *  Read and write can be started and stopped independently.
 *  To start a transfer, clocks must be running.
 *  To stop the clocks no transfer must be running.
 *  Refer to the following functions for more details:
 *  @li I2S_startClocks() @li I2S_startRead() @li I2S_startWrite()
 *  @li I2S_stopRead() @li I2S_stopWrite() @li I2S_stopClocks()
 *
 *  @note
 *  @li In #I2S_SLAVE mode, clocks must be started and stopped exactly like
 *  it is done in #I2S_MASTER mode.
 *  @li If the queue of transaction is not empty, the calls to #I2S_stopRead()
 *  and #I2S_stopWrite() are blocking and potentially long.
 *
 *  <hr>
 *  @anchor ti_drivers_I2S_Examples
 *  ## Examples #
 *
 *  @li @ref ti_drivers_I2S_Example_PlayAndStop "Play and Stop"
 *  @li @ref ti_drivers_I2S_Example_Streaming "Streaming"
 *  @li @ref ti_drivers_I2S_Example_RepeatMode "Repeat"
 *
 *  <hr>
 *  @anchor ti_drivers_I2S_Example_PlayAndStop
 *  ### Mode Play and Stop #
 *  The following example shows how to simultaneously receive and send out a given amount of data.
 *
 *  <hr>
 *  @anchor ti_drivers_I2S_Example_PlayAndStop_Code
 *  @code
 *  static I2S_Handle i2sHandle;
 *
 *  static uint16_t readBuf1[500]; // the data read will end up in this buffer
 *  static uint16_t readBuf2[500]; // the data read will end up in this buffer
 *  static uint16_t readBuf3[500]; // the data read will end up in this buffer
 *  static uint16_t writeBuf1[250] = {...some data...}; // this buffer will be sent out
 *  static uint16_t writeBuf2[250] = {...some data...}; // this buffer will be sent out
 *  static uint16_t writeBuf3[250] = {...some data...}; // this buffer will be sent out
 *
 *  static I2S_Transaction i2sRead1;
 *  static I2S_Transaction i2sRead2;
 *  static I2S_Transaction i2sRead3;
 *  static I2S_Transaction i2sWrite1;
 *  static I2S_Transaction i2sWrite2;
 *  static I2S_Transaction i2sWrite3;
 *
 *  List_List i2sReadList;
 *  List_List i2sWriteList;
 *
 *  static volatile bool readStopped = (bool)true;
 *  static volatile bool writeStopped = (bool)true;
 *
 *  static void writeCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) {
 *
 *      if(status & I2S_ALL_TRANSACTIONS_SUCCESS){
 *
 *          // Note: Here we do not queue new transfers or set a new queue-head.
 *          // The driver will stop sending out data on its own.
 *          writeStopped = (bool)true;
 *      }
 *  }
 *
 *  static void readCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) {
 *
 *      if(status & I2S_ALL_TRANSACTIONS_SUCCESS){
 *
 *          // Note: Here we do not queue new transfers or set a new queue-head.
 *          // The driver will stop receiving data on its own.
 *          readStopped = (bool)true;
 *      }
 *  }
 *
 *  static void errCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) {
 *
 *      // Handle the I2S error
 *  }
 *
 *  void *modePlayAndStopThread(void *arg0)
 *  {
 *      I2S_Params i2sParams;
 *
 *      I2S_init();
 *
 *      // Initialize I2S opening parameters
 *      I2S_Params_init(&i2sParams);
 *      i2sParams.fixedBufferLength     =  500; // fixedBufferLength is the greatest common
 *                                              // divisor of all the different buffers
 *                                              // (here buffers' size are 500 and 1000 bytes)
 *      i2sParams.writeCallback         =  writeCallbackFxn ;
 *      i2sParams.readCallback          =  readCallbackFxn ;
 *      i2sParams.errorCallback         =  errCallbackFxn;
 *
 *      i2sHandle = I2S_open(CONFIG_I2S0, &i2sParams);
 *
 *      // Initialize the read-transactions
 *      I2S_Transaction_init(&i2sRead1);
 *      I2S_Transaction_init(&i2sRead2);
 *      I2S_Transaction_init(&i2sRead3);
 *      i2sRead1.bufPtr            = readBuf1;
 *      i2sRead2.bufPtr            = readBuf2;
 *      i2sRead3.bufPtr            = readBuf3;
 *      i2sRead1.bufSize           = sizeof(readBuf1);
 *      i2sRead2.bufSize           = sizeof(readBuf2);
 *      i2sRead3.bufSize           = sizeof(readBuf3);
 *      List_put(&i2sReadList, (List_Elem*)&i2sRead1);
 *      List_put(&i2sReadList, (List_Elem*)&i2sRead2);
 *      List_put(&i2sReadList, (List_Elem*)&i2sRead3);
 *
 *      I2S_setReadQueueHead(i2sHandle, &i2sRead1);
 *
 *      // Initialize the write-transactions
 *      I2S_Transaction_init(&i2sWrite1);
 *      I2S_Transaction_init(&i2sWrite2);
 *      I2S_Transaction_init(&i2sWrite3);
 *      i2sWrite1.bufPtr           = writeBuf1;
 *      i2sWrite2.bufPtr           = writeBuf2;
 *      i2sWrite3.bufPtr           = writeBuf3;
 *      i2sWrite1.bufSize          = sizeof(writeBuf1);
 *      i2sWrite2.bufSize          = sizeof(writeBuf2);
 *      i2sWrite3.bufSize          = sizeof(writeBuf3);
 *      List_put(&i2sWriteList, (List_Elem*)&i2sWrite1);
 *      List_put(&i2sWriteList, (List_Elem*)&i2sWrite2);
 *      List_put(&i2sWriteList, (List_Elem*)&i2sWrite3);
 *
 *      I2S_setWriteQueueHead(i2sHandle, &i2sWrite1);
 *
 *      I2S_startClocks(i2sHandle);
 *      I2S_startWrite(i2sHandle);
 *      I2S_startRead(i2sHandle);
 *
 *      readStopped = (bool)false;
 *      writeStopped = (bool)false;
 *
 *      while (1) {
 *
 *          if(readStopped && writeStopped) {
 *              I2S_stopClocks(i2sHandle);
 *              I2S_close(i2sHandle);
 *              while (1);
 *          }
 *      }
 *  }
 *  @endcode
 *
 *  \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.
 *
 *  <hr>
 *  @anchor ti_drivers_I2S_Example_Streaming
 *  ### Writing Data in Continuous Streaming Mode #
 *  The following example shows how to read and write data in streaming mode.
 *  A dummy treatment of the data is also done.
 *  This example is not complete (semaphore and tasks creation are not shown)
 *
 *  <hr>
 *  @anchor ti_drivers_I2S_Example_Streaming_Code
 *  @code
 *  static I2S_Handle i2sHandle;
 *  static sem_t semDataReadyForTreatment;
 *
 *  // These buffers will successively be written, treated and sent out
 *  static uint16_t readBuf1[500];
 *  static uint16_t readBuf2[500];
 *  static uint16_t readBuf3[500];
 *  static uint16_t readBuf4[500];
 *  static uint16_t writeBuf1[500]={0};
 *  static uint16_t writeBuf2[500]={0};
 *  static uint16_t writeBuf3[500]={0};
 *  static uint16_t writeBuf4[500]={0};
 *
 *  // These transactions will successively be part of the
 *  // i2sReadList, the treatmentList and the i2sWriteList
 *  static I2S_Transaction i2sRead1;
 *  static I2S_Transaction i2sRead2;
 *  static I2S_Transaction i2sRead3;
 *  static I2S_Transaction i2sRead4;
 *  static I2S_Transaction i2sWrite1;
 *  static I2S_Transaction i2sWrite2;
 *  static I2S_Transaction i2sWrite3;
 *  static I2S_Transaction i2sWrite4;
 *
 *  List_List i2sReadList;
 *  List_List treatmentList;
 *  List_List i2sWriteList;
 *
 *  static void writeCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) {
 *
 *      // We must remove the previous transaction (the current one is not over)
 *      I2S_Transaction *transactionFinished = (I2S_Transaction*)List_prev(&transactionPtr->queueElement);
 *
 *      if(transactionFinished != NULL){
 *          // Remove the finished transaction from the write queue
 *          List_remove(&i2sWriteList, (List_Elem*)transactionFinished);
 *
 *          // This transaction must now feed the read queue (we do not need anymore the data of this transaction)
 *          transactionFinished->queueElement.next = NULL;
 *          List_put(&i2sReadList, (List_Elem*)transactionFinished);
 *
 *          // We need to queue a new transaction: let's take one in the treatment queue
 *          I2S_Transaction *newTransaction = (I2S_Transaction*)List_head(&treatmentList);
 *          if(newTransaction != NULL){
 *              List_remove(&treatmentList, (List_Elem*)newTransaction);
 *              newTransaction->queueElement.next = NULL;
 *              List_put(&i2sWriteList, (List_Elem*)newTransaction);
 *          }
 *      }
 *  }
 *
 *  static void readCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) {
 *
 *      // We must remove the previous transaction (the current one is not over)
 *      I2S_Transaction *transactionFinished = (I2S_Transaction*)List_prev(&transactionPtr->queueElement);
 *
 *      if(transactionFinished != NULL){
 *          // The finished transaction contains data that must be treated
 *          List_remove(&i2sReadList, (List_Elem*)transactionFinished);
 *          transactionFinished->queueElement.next = NULL;
 *          List_put(&treatmentList, (List_Elem*)transactionFinished);
 *
 *          // Start the treatment of the data
 *          sem_post(&semDataReadyForTreatment);
 *
 *          // We do not need to queue transaction here: writeCallbackFxn takes care of this :)
 *      }
 *  }
 *
 *  static void errCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) {
 *
 *      // Handle the I2S error
 *  }
 *
 *  void *echoExampleThread(void *arg0)
 *  {
 *      I2S_Params i2sParams;
 *
 *      I2S_init();
 *
 *      int retc = sem_init(&semDataReadyForTreatment, 0, 0);
 *      if (retc == -1) {
 *          while (1);
 *      }
 *
 *      // Initialize the treatmentList (this list is initially empty)
 *      List_clearList(&treatmentList);
 *
 *      //Initialize I2S opening parameters
 *      I2S_Params_init(&i2sParams);
 *      i2sParams.fixedBufferLength     =  1000;
 *      i2sParams.writeCallback         =  writeCallbackFxn ;
 *      i2sParams.readCallback          =  readCallbackFxn ;
 *      i2sParams.errorCallback         =  errCallbackFxn;
 *
 *      i2sHandle = I2S_open(CONFIG_I2S0, &i2sParams);
 *
 *      // Initialize the read-transactions
 *      I2S_Transaction_init(&i2sRead1);
 *      I2S_Transaction_init(&i2sRead2);
 *      I2S_Transaction_init(&i2sRead3);
 *      I2S_Transaction_init(&i2sRead4);
 *      i2sRead1.bufPtr            = readBuf1;
 *      i2sRead2.bufPtr            = readBuf2;
 *      i2sRead3.bufPtr            = readBuf3;
 *      i2sRead4.bufPtr            = readBuf4;
 *      i2sRead1.bufSize           = sizeof(readBuf1);
 *      i2sRead2.bufSize           = sizeof(readBuf2);
 *      i2sRead3.bufSize           = sizeof(readBuf3);
 *      i2sRead4.bufSize           = sizeof(readBuf4);
 *      List_clearList(&i2sReadList);
 *      List_put(&i2sReadList, (List_Elem*)&i2sRead1);
 *      List_put(&i2sReadList, (List_Elem*)&i2sRead2);
 *      List_put(&i2sReadList, (List_Elem*)&i2sRead3);
 *      List_put(&i2sReadList, (List_Elem*)&i2sRead4);
 *
 *      I2S_setReadQueueHead(i2sHandle, &i2sRead1);
 *
 *      // Initialize the write-transactions
 *      I2S_Transaction_init(&i2sWrite1);
 *      I2S_Transaction_init(&i2sWrite2);
 *      I2S_Transaction_init(&i2sWrite3);
 *      I2S_Transaction_init(&i2sWrite4);
 *      i2sWrite1.bufPtr           = writeBuf1;
 *      i2sWrite2.bufPtr           = writeBuf2;
 *      i2sWrite3.bufPtr           = writeBuf3;
 *      i2sWrite4.bufPtr           = writeBuf4;
 *      i2sWrite1.bufSize          = sizeof(writeBuf1);
 *      i2sWrite2.bufSize          = sizeof(writeBuf2);
 *      i2sWrite3.bufSize          = sizeof(writeBuf3);
 *      i2sWrite4.bufSize          = sizeof(writeBuf4);
 *      List_clearList(&i2sWriteList);
 *      List_put(&i2sWriteList, (List_Elem*)&i2sWrite1);
 *      List_put(&i2sWriteList, (List_Elem*)&i2sWrite2);
 *      List_put(&i2sWriteList, (List_Elem*)&i2sWrite3);
 *      List_put(&i2sWriteList, (List_Elem*)&i2sWrite4);
 *
 *      I2S_setWriteQueueHead(i2sHandle, &i2sWrite1);
 *
 *      I2S_startClocks(i2sHandle);
 *      I2S_startWrite(i2sHandle);
 *      I2S_startRead(i2sHandle);
 *
 *      while (1) {
 *          uint8_t k = 0;
 *          I2S_Transaction* lastAchievedReadTransaction = NULL;
 *
 *          retc = sem_wait(&semDataReadyForTreatment);
 *          if (retc == -1) {
 *              while (1);
 *          }
 *
 *          lastAchievedReadTransaction = (I2S_Transaction*) List_head(&treatmentList);
 *
 *          if(lastAchievedReadTransaction != NULL) {
 *
 *              // Need a critical section to be sure to have corresponding bufPtr and bufSize
 *              uintptr_t key = HwiP_disable();
 *              uint16_t *buf = lastAchievedReadTransaction->bufPtr;
 *              uint16_t bufLength = lastAchievedReadTransaction->bufSize / sizeof(uint16_t);
 *              HwiP_restore(key);
 *
 *              // My dummy data treatment...
 *              for(k=0; k<bufLength; k++) {
 *                  buf[k]--;
 *              }
 *              for(k=0; k<bufLength; k++) {
 *                  buf[k]++;
 *              }
 *          }
 *      }
 *  }
 *  @endcode
 *
 *  <hr>
 *  @anchor ti_drivers_I2S_Example_RepeatMode
 *  ### Writing Data in repeat Mode #
 *  The following example shows how to read and write data in repeat mode.
 *  The same buffers are continuously written and send out while the driver is not stopped.
 *  Here, we decide to only stop sending out after an arbitrary number of sending.
 *
 *  <hr>
 *  @anchor ti_drivers_I2S_Example_RepeatMode_Code
 *  @code
 *  static I2S_Handle i2sHandle;
 *
 *  // This buffer will be continuously re-written
 *  static uint16_t readBuf[500];
 *  // This data will be continuously sent out
 *  static uint16_t writeBuf[500] = {...some cool data...};
 *
 *  static I2S_Transaction i2sRead;
 *  static I2S_Transaction i2sWrite;
 *
 *  List_List i2sReadList;
 *  List_List i2sWriteList;
 *
 *  static volatile bool writeFinished = (bool)false;
 *  static void writeCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) {
 *
 *      // Nothing to do here: the buffer(s) are queued in a ring list, the transfers are
 *      // executed without any action from the application.
 *
 *      // We must consider the previous transaction (ok, when you have only one transaction it's the same)
 *      I2S_Transaction *transactionFinished = (I2S_Transaction*)List_prev(&transactionPtr->queueElement);
 *
 *      if(transactionFinished != NULL){
 *          // After an arbitrary number of completion of the transaction, we will stop writting
 *          if(transactionFinished->numberOfCompletions >= 10) {
 *
 *              // Note: You cannot use I2S_stopRead() / I2S_stopWrite() in the callback.
 *              // The execution of these functions is potentially blocking and can mess up the
 *              // system.
 *
 *              writeFinished = (bool)true;
 *          }
 *      }
 *  }
 *
 *  static void readCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) {
 *      // Nothing to do here: the buffer(s) are queued in a ring list, the transfers are
 *      // executed without any action from the application.
 *  }
 *
 *  static void errCallbackFxn(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr) {
 *
 *      // Handle the I2S error
 *  }
 *
 *  void *modeRepeat(void *arg0)
 *  {
 *      I2S_Params i2sParams;
 *
 *      // Initialize I2S opening parameters
 *      I2S_Params_init(&i2sParams);
 *      i2sParams.fixedBufferLength     =  1000; // No problem here: the driver consider
 *                                               // the list as an infinite list.
 *      i2sParams.writeCallback         =  writeCallbackFxn ;
 *      i2sParams.readCallback          =  readCallbackFxn ;
 *      i2sParams.errorCallback         =  errCallbackFxn;
 *
 *      i2sHandle = I2S_open(CONFIG_I2S0, &i2sParams);
 *
 *      // Initialize the read-transactions
 *      I2S_Transaction_init(&i2sRead);
 *      i2sRead.bufPtr            = readBuf;
 *      i2sRead.bufSize           = sizeof(readBuf);
 *      List_put(&i2sReadList, (List_Elem*)&i2sRead);
 *      List_tail(&i2sReadList)->next = List_head(&i2sReadList);// Read buffers are queued in a ring-list
 *      List_head(&i2sReadList)->prev = List_tail(&i2sReadList);
 *
 *      I2S_setReadQueueHead(i2sHandle, &i2sRead);
 *
 *      // Initialize the write-transactions
 *      I2S_Transaction_init(&i2sWrite);
 *      i2sWrite.bufPtr           = writeBuf;
 *      i2sWrite.bufSize          = sizeof(writeBuf);
 *      List_put(&i2sWriteList, (List_Elem*)&i2sWrite);
 *      List_tail(&i2sWriteList)->next = List_head(&i2sWriteList); // Write buffers are queued in a ring-list
 *      List_head(&i2sWriteList)->prev = List_tail(&i2sWriteList);
 *
 *      I2S_setWriteQueueHead(i2sHandle, &i2sWrite);
 *
 *      I2S_startClocks(i2sHandle);
 *      I2S_startWrite(i2sHandle);
 *      I2S_startRead(i2sHandle);
 *
 *      while (1) {
 *
 *          if(writeFinished){
 *              writeFinished = (bool)false;
 *              I2S_stopWrite(i2sHandle);
 *          }
 *      }
 *  }
 *  @endcode
 *
 *  @note In the case of circular lists, there is no problem to put only
 *  one buffer in the queue.
 *
 *  <hr>
 *  @anchor ti_drivers_I2S_Configuration
 *  # Configuration
 *
 *  Refer to the @ref driver_configuration "Driver's Configuration" section
 *  for driver configuration information.
 *  <hr>
 ******************************************************************************
 */

#ifndef ti_drivers_I2S__include
#define ti_drivers_I2S__include

#include <stddef.h>
#include <stdbool.h>
#include <stdint.h>

#include <ti/drivers/utils/List.h>

#ifdef __cplusplus
extern "C" {
#endif

#define I2S_ALL_TRANSACTIONS_SUCCESS (0x0001U)

#define I2S_TRANSACTION_SUCCESS (0x0002U)

#define I2S_TIMEOUT_ERROR (0x0100U)

#define I2S_BUS_ERROR (0x0200U)

#define I2S_WS_ERROR (0x0400U)

#define I2S_PTR_READ_ERROR (0x0800U)

#define I2S_PTR_WRITE_ERROR (0x1000U)

typedef struct
{
    void *object;

    void const *hwAttrs;
} I2S_Config;

typedef I2S_Config *I2S_Handle;

typedef struct
{
    List_Elem queueElement;
    void *bufPtr;
    size_t bufSize;
    size_t bytesTransferred;
    size_t untransferredBytes;
    uint16_t numberOfCompletions;
    uintptr_t arg;
} I2S_Transaction;

typedef void (*I2S_Callback)(I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr);

typedef void (*I2S_RegUpdate)(uint32_t ui32Base, uint32_t ui32NextPointer);

typedef void (*I2S_StopInterface)(I2S_Handle handle);

typedef enum
{

    I2S_MEMORY_LENGTH_8BITS  = 8U,  
    I2S_MEMORY_LENGTH_16BITS = 16U, 
    I2S_MEMORY_LENGTH_24BITS = 24U, 
    I2S_MEMORY_LENGTH_32BITS = 32U  
} I2S_MemoryLength;

typedef enum
{

    I2S_SLAVE  = 0, 
    I2S_MASTER = 1  
} I2S_Role;

typedef enum
{

    I2S_SAMPLING_EDGE_FALLING = 0, 
    I2S_SAMPLING_EDGE_RISING  = 1  
} I2S_SamplingEdge;

typedef enum
{

    I2S_PHASE_TYPE_SINGLE = 0U, 
    I2S_PHASE_TYPE_DUAL   = 1U, 
} I2S_PhaseType;

typedef enum
{

    I2S_SD0_DISABLED = 0x00U, 
    I2S_SD0_INPUT    = 0x01U, 
    I2S_SD0_OUTPUT   = 0x02U, 
    I2S_SD1_DISABLED = 0x00U, 
    I2S_SD1_INPUT    = 0x10U, 
    I2S_SD1_OUTPUT   = 0x20U  
} I2S_DataInterfaceUse;

typedef enum
{

    I2S_CHANNELS_NONE     = 0x00U, 
    I2S_CHANNELS_MONO     = 0x01U, 
    I2S_CHANNELS_MONO_INV = 0x02U, 
    I2S_CHANNELS_STEREO   = 0x03U, 
    I2S_1_CHANNEL         = 0x01U, 
    I2S_2_CHANNELS        = 0x03U, 
    I2S_3_CHANNELS        = 0x07U, 
    I2S_4_CHANNELS        = 0x0FU, 
    I2S_5_CHANNELS        = 0x1FU, 
    I2S_6_CHANNELS        = 0x3FU, 
    I2S_7_CHANNELS        = 0x7FU, 
    I2S_8_CHANNELS        = 0xFFU, 
    I2S_CHANNELS_ALL      = 0xFFU  
} I2S_ChannelConfig;

typedef struct
{

    bool trueI2sFormat;
    bool invertWS;
    bool isMSBFirst;
    bool isDMAUnused;
    I2S_MemoryLength memorySlotLength;
    uint8_t beforeWordPadding;
    uint8_t afterWordPadding;
    uint8_t bitsPerWord;
    I2S_Role moduleRole;
    I2S_SamplingEdge samplingEdge;
    I2S_DataInterfaceUse SD0Use;
    I2S_DataInterfaceUse SD1Use;
    I2S_ChannelConfig SD0Channels;
    I2S_ChannelConfig SD1Channels;
    I2S_PhaseType phaseType;
    uint16_t fixedBufferLength;
    uint16_t startUpDelay;
    uint16_t MCLKDivider;
    uint32_t samplingFrequency;
    I2S_Callback readCallback;
    I2S_Callback writeCallback;
    I2S_Callback errorCallback;
    void *custom;
} I2S_Params;

extern const I2S_Params I2S_defaultParams;

extern void I2S_close(I2S_Handle handle);

extern void I2S_init(void);

extern I2S_Handle I2S_open(uint_least8_t index, I2S_Params *params);

extern void I2S_Params_init(I2S_Params *params);

extern void I2S_Transaction_init(I2S_Transaction *transaction);

extern void I2S_setReadQueueHead(I2S_Handle handle, I2S_Transaction *transaction);

extern void I2S_setWriteQueueHead(I2S_Handle handle, I2S_Transaction *transaction);

extern void I2S_startClocks(I2S_Handle handle);

extern void I2S_stopClocks(I2S_Handle handle);

extern void I2S_startRead(I2S_Handle handle);

extern void I2S_startWrite(I2S_Handle handle);

extern void I2S_stopRead(I2S_Handle handle);

extern void I2S_stopWrite(I2S_Handle handle);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_I2S__include */