Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
I2S.h File Reference

Detailed Description

Inter-Integrated Circuit Sound (I2S) Bus Driver.


The I2S header file should be included in an application as follows:

#include <ti/drivers/I2S.h>

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.


Usage

The I2S driver provides the following APIs:


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 I2S driver provides the following elements (fields of the I2S_Transaction):

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.


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.


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:

Note

Examples


Mode Play and Stop

The following example shows how to simultaneously receive and send out a given amount of data.


static I2S_Handle i2sHandle;
static I2S_Config i2sConfig;
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) {
// 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) {
// 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;
// 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
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);
}
}
}
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.

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)


static I2S_Handle i2sHandle;
static I2S_Config i2sConfig;
// 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
Semaphore_post(dataReadyForTreatment);
// 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 *myTreatmentThread(void *arg0){
int k;
while(1) {
Semaphore_pend(dataReadyForTreatment, BIOS_WAIT_FOREVER);
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] ++;}
}
}
}
void *echoExampleThread(void *arg0)
{
I2S_Params i2sParams;
// 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
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);
}

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.


static I2S_Handle i2sHandle;
static I2S_Config i2sConfig;
static I2SCC26XX_Object i2sObject;
// 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
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
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);
}
}
}
Note
In the case of circular lists, there is no problem to put only one buffer in the queue.

Configuration

Refer to the Driver's Configuration section for driver configuration information.


#include <stddef.h>
#include <stdbool.h>
#include <stdint.h>
#include <ti/drivers/utils/List.h>
Include dependency graph for I2S.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  I2S_Config
 I2S Global configuration. More...
 
struct  I2S_Transaction
 I2S transaction descriptor. More...
 
struct  I2S_Params
 Basic I2S Parameters. More...
 

Macros

#define I2S_ALL_TRANSACTIONS_SUCCESS   (0x0001U)
 Successful status code returned by I2S driver functions. More...
 
#define I2S_TRANSACTION_SUCCESS   (0x0002U)
 Successful status code returned by I2S driver functions. More...
 
#define I2S_TIMEOUT_ERROR   (0x0100U)
 Error status code returned by I2S driver functions. More...
 
#define I2S_BUS_ERROR   (0x0200U)
 Error status code returned by I2S driver functions. More...
 
#define I2S_WS_ERROR   (0x0400U)
 Error status code returned by I2S driver functions. More...
 
#define I2S_PTR_READ_ERROR   (0x0800U)
 Error status code returned by I2S driver functions. More...
 
#define I2S_PTR_WRITE_ERROR   (0x1000U)
 Error status code returned by I2S driver functions. More...
 

Typedefs

typedef I2S_ConfigI2S_Handle
 A handle that is returned from a I2S_open() call. More...
 
typedef void(* I2S_Callback) (I2S_Handle handle, int_fast16_t status, I2S_Transaction *transactionPtr)
 The definition of a user-callback function used by the I2S driver. More...
 
typedef void(* I2S_RegUpdate) (uint32_t ui32Base, uint32_t ui32NextPointer)
 The definition of a function used to set the I2S register. More...
 
typedef void(* I2S_StopInterface) (I2S_Handle handle)
 The definition of a function used to stop an I2S interface. More...
 

Enumerations

enum  I2S_MemoryLength { I2S_MEMORY_LENGTH_8BITS = 8U, I2S_MEMORY_LENGTH_16BITS = 16U, I2S_MEMORY_LENGTH_24BITS = 24U, I2S_MEMORY_LENGTH_32BITS = 32U }
 I2S slot memory length setting. More...
 
enum  I2S_Role { I2S_SLAVE = 0, I2S_MASTER = 1 }
 I2S master / slave selection. More...
 
enum  I2S_SamplingEdge { I2S_SAMPLING_EDGE_FALLING = 0, I2S_SAMPLING_EDGE_RISING = 1 }
 I2S sampling setting. More...
 
enum  I2S_PhaseType { I2S_PHASE_TYPE_SINGLE = 0U, I2S_PHASE_TYPE_DUAL = 1U }
 I2S phase setting. More...
 
enum  I2S_DataInterfaceUse {
  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 data interface configuration. More...
 
enum  I2S_ChannelConfig {
  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
}
 Channels used selection. More...
 

Functions

void I2S_close (I2S_Handle handle)
 Function to close a given I2S peripheral specified by the I2S handle. More...
 
void I2S_init (void)
 Function to initializes the I2S module. More...
 
I2S_Handle I2S_open (uint_least8_t index, I2S_Params *params)
 Function to initialize a given I2S peripheral specified by the particular index value. The parameter specifies which mode the I2S will operate. More...
 
void I2S_Params_init (I2S_Params *params)
 Function to initialize the I2S_Params struct to its defaults. More...
 
void I2S_Transaction_init (I2S_Transaction *transaction)
 Initialize an I2S_Transaction struct to known state. More...
 
void I2S_setReadQueueHead (I2S_Handle handle, I2S_Transaction *transaction)
 Function to set the first read-transaction to consider. More...
 
void I2S_setWriteQueueHead (I2S_Handle handle, I2S_Transaction *transaction)
 Function to set the first write-transaction to consider. More...
 
void I2S_startClocks (I2S_Handle handle)
 Start the WS, SCK and MCLK clocks. More...
 
void I2S_stopClocks (I2S_Handle handle)
 Stops the WS, SCK and MCLK clocks. More...
 
void I2S_startRead (I2S_Handle handle)
 Start read transactions. More...
 
void I2S_startWrite (I2S_Handle handle)
 Start write transactions. More...
 
void I2S_stopRead (I2S_Handle handle)
 Stop read transactions. More...
 
void I2S_stopWrite (I2S_Handle handle)
 Stop write transactions. More...
 

Variables

const I2S_Params I2S_defaultParams
 Default I2S_Params structure. More...
 

Typedef Documentation

§ I2S_Handle

A handle that is returned from a I2S_open() call.

§ I2S_Callback

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

The definition of a user-callback function used by the I2S driver.

Parameters
I2S_HandleI2S_Handle
statusStatus of the operation (possible values are : :I2S_STATUS_SUCCESS, :I2S_STATUS_ERROR, :I2S_STATUS_BUFFER_UNAVAILABLE, :I2S_STATUS_TIMEOUT)
I2S_Transaction*transactionPtr: Pointer on the transaction that has just started. For error callbacks, transactionPtr points on NULL.

§ I2S_RegUpdate

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

The definition of a function used to set the I2S register.

Parameters
uint32_tui32Base: base address of the I2S module.
uint32_tui32NextPointer: pointer on an I2S buffer.

§ I2S_StopInterface

typedef void(* I2S_StopInterface) (I2S_Handle handle)

The definition of a function used to stop an I2S interface.

Parameters
I2S_HandleI2S_Handle

Enumeration Type Documentation

§ I2S_MemoryLength

I2S slot memory length setting.

The enum defines if the module uses a 16 bits or a 24 bits buffer in memory. This value has no influence on the number of bit transmitted.

Enumerator
I2S_MEMORY_LENGTH_8BITS 

Buffer used is 8 bits length. Not available for CC26XX.

I2S_MEMORY_LENGTH_16BITS 

Buffer used is 16 bits length.

I2S_MEMORY_LENGTH_24BITS 

Buffer used is 24 bits length.

I2S_MEMORY_LENGTH_32BITS 

Buffer used is 32 bits length. Not available for CC26XX.

§ I2S_Role

enum I2S_Role

I2S master / slave selection.

The enum defines if the module acts like a master (clocks are internally generated) or a slave (the clocks are externally generated).

Enumerator
I2S_SLAVE 

Module is a slave, clocks are externally generated.

I2S_MASTER 

Module is a master, clocks are internally generated.

§ I2S_SamplingEdge

I2S sampling setting.

The enum defines if sampling is done on BLCK rising or falling edges.

Enumerator
I2S_SAMPLING_EDGE_FALLING 

Sampling on falling edges.

I2S_SAMPLING_EDGE_RISING 

Sampling on rising edges.

§ I2S_PhaseType

I2S phase setting.

The enum defines if the I2S if set with single or dual phase.

Enumerator
I2S_PHASE_TYPE_SINGLE 

Single phase

I2S_PHASE_TYPE_DUAL 

Dual phase

§ I2S_DataInterfaceUse

I2S data interface configuration.

The enum defines the different settings for the data interfaces (SD0 and SD1).

Enumerator
I2S_SD0_DISABLED 

SD0 is disabled

I2S_SD0_INPUT 

SD0 is an input

I2S_SD0_OUTPUT 

SD0 is an output

I2S_SD1_DISABLED 

SD1 is disabled

I2S_SD1_INPUT 

SD1 is an input

I2S_SD1_OUTPUT 

SD1 is an output

§ I2S_ChannelConfig

Channels used selection.

The enum defines different settings to activate the expected channels.

Enumerator
I2S_CHANNELS_NONE 

No channel activated

I2S_CHANNELS_MONO 

MONO: only channel one is activated

I2S_CHANNELS_MONO_INV 

MONO INVERERTED: only channel two is activated

I2S_CHANNELS_STEREO 

STEREO: channels one and two are activated

I2S_1_CHANNEL 

1 channel is activated

I2S_2_CHANNELS 

2 channels are activated

I2S_3_CHANNELS 

3 channels are activated

I2S_4_CHANNELS 

4 channels are activated

I2S_5_CHANNELS 

5 channels are activated

I2S_6_CHANNELS 

6 channels are activated

I2S_7_CHANNELS 

7 channels are activated

I2S_8_CHANNELS 

8 channels are activated

I2S_CHANNELS_ALL 

All the eight channels are activated

Function Documentation

§ I2S_close()

void I2S_close ( I2S_Handle  handle)

Function to close a given I2S peripheral specified by the I2S handle.

Precondition
I2S_open() had to be called first.
Parameters
[in]handleAn I2S_Handle returned from I2S_open
See also
I2S_open()

§ I2S_init()

void I2S_init ( void  )

Function to initializes the I2S module.

Precondition
The I2S_config structure must exist and be persistent before this function can be called. This function must also be called before any other I2S driver APIs. This function call does not modify any peripheral registers.

§ I2S_open()

I2S_Handle I2S_open ( uint_least8_t  index,
I2S_Params params 
)

Function to initialize a given I2S peripheral specified by the particular index value. The parameter specifies which mode the I2S will operate.

Precondition
I2S controller has been initialized
Parameters
[in,out]indexLogical peripheral number for the I2S indexed into the I2S_config table
[in]paramsPointer to an parameter block. All the fields in this structure are RO (read-only). Provide a NULL pointer cannot open the module.
Returns
An I2S_Handle on success or a NULL on an error or if it has been opened already.
See also
I2S_init()
I2S_close()

§ I2S_Params_init()

void I2S_Params_init ( I2S_Params params)

Function to initialize the I2S_Params struct to its defaults.

Parameters
[out]paramsAn pointer to I2S_Params structure for initialization

Defaults values are:

params.samplingFrequency = 8000;
params.isMemory24Bits = I2S_MEMORY_LENGTH_16BITS;
params.isMaster = I2S_MASTER;
params.trueI2sFormat = (bool)true;
params.invertWS = (bool)true;
params.isMSBFirst = (bool)true;
params.isDMAUnused = (bool)false;
params.samplingEdge = I2S_SAMPLING_EDGE_RISING;
params.beforeWordPadding = 0;
params.bitsPerWord = 16;
params.afterWordPadding = 0;
params.fixedBufferLength = 1;
params.SD0Use = I2S_SD0_OUTPUT;
params.SD1Use = I2S_SD1_INPUT;
params.SD0Channels = I2S_CHANNELS_STEREO;
params.SD1Channels = I2S_CHANNELS_STEREO;
params.phaseType = I2S_PHASE_TYPE_DUAL;
params.startUpDelay = 0;
params.MCLKDivider = 40;
params.readCallback = NULL;
params.writeCallback = NULL;
params.errorCallback = NULL;
params.custom = NULL;
Parameters
paramsParameter structure to initialize

§ I2S_Transaction_init()

void I2S_Transaction_init ( I2S_Transaction transaction)

Initialize an I2S_Transaction struct to known state.

The I2S_Transaction struct is put in a known state. The application is still responsible for populating some of the fields. For example, the user is responsible to provide the buffer containing the data and the size of it. User provided buffer's size must matche with the I2S settings. If the buffer size is not adapted, the I2S module will truncate it. Authorized buffer sizes depend on the number of activated outputs, the number of channels activated, the memory slots length (16 or 24 bits), and the fixed-buffer-size eventually provided. Authorized buffer sizes are all the multiple values of the value of handle->object->memoryStepOut.

Parameters
[out]transactionTransaction struct to initialize.

§ I2S_setReadQueueHead()

void I2S_setReadQueueHead ( I2S_Handle  handle,
I2S_Transaction transaction 
)

Function to set the first read-transaction to consider.

At the end of each transaction, I2S driver takes in consideration the next transaction. Application is responsible to handle the queue.

Parameters
[in]handleAn I2S_Handle.
[in]transactionA pointer to an I2S_Transaction object. The bufPtr and bufSize fields must be set to a buffer and the size of the buffer before passing to this function.
Returns
void
See also
I2S_setWriteQueueHead()

§ I2S_setWriteQueueHead()

void I2S_setWriteQueueHead ( I2S_Handle  handle,
I2S_Transaction transaction 
)

Function to set the first write-transaction to consider.

At the end of each transaction, I2S driver takes in consideration the next transaction. Application is responsible to handle the queue.

Parameters
[in]handleAn I2S_Handle.
[in]transactionA pointer to an I2S_Transaction object. The bufPtr and bufSize fields must be set to a buffer and the size of the buffer before passing to this function.
Returns
void
See also
I2S_setReadQueueHead()

§ I2S_startClocks()

void I2S_startClocks ( I2S_Handle  handle)

Start the WS, SCK and MCLK clocks.

This function enable WS, SCK and MCLK (if activated) clocks. This is required before starting any reading or a writing transaction. This function is supposed to be executed both in slave and master mode.

Parameters
[in]handleAn I2S_Handle.
Returns
void
See also
I2S_stopClocks()

§ I2S_stopClocks()

void I2S_stopClocks ( I2S_Handle  handle)

Stops the WS, SCK and MCLK clocks.

This function disable WS, SCK and MCLK clocks. This function must be executed only if no transaction is in progress. This function is supposed to be executed in a Task context (NOT in a HWI or Callback context). This function is supposed to be executed both in slave and master mode.

Warning
This function is supposed to be executed in a Task context (NOT in a HWI or Callback context).
Parameters
[in]handleAn I2S_Handle.
Returns
void
See also
I2S_stopRead()
I2S_stopWrite()

§ I2S_startRead()

void I2S_startRead ( I2S_Handle  handle)

Start read transactions.

This function starts reception of the transactions stored in the read-queue. and returns immediately. At the completion of each transaction the readCallback provided is executed.

If the queue for read transactions becomes empty (i.e. the read Callback is triggered with status I2S_ALL_TRANSACTIONS_SUCCESS and the application has not queued new transactions or defined a new first read-transaction to consider using I2S_setReadQueueHead()), the driver will stop the read interface on its own in order to avoid the occurrence of errors (such as I2S_PTR_READ_ERROR).

Precondition
First read-transaction to consider must be set and clocks must be running before calling this function.
Parameters
[in]handleAn I2S_Handle.
Returns
void
See also
I2S_startClocks()
I2S_setReadQueueHead()

§ I2S_startWrite()

void I2S_startWrite ( I2S_Handle  handle)

Start write transactions.

This function starts transmission of the transactions stored in the write-queue and returns immediately. At the completion of each transaction the write Callback provided is executed.

If the queue for write transactions becomes empty (i.e. the write Callback is triggered with status I2S_ALL_TRANSACTIONS_SUCCESS and the application has not queued new transactions or defined a new first write-transaction to consider using I2S_setWriteQueueHead()), the driver will stop the write interface on its own in order to avoid the occurrence of errors (such as I2S_PTR_WRITE_ERROR).

Precondition
First write-transaction to consider must be set and clocks must be running before calling this function.
Parameters
[in]handleAn I2S_Handle.
Returns
void
See also
I2S_startClocks()
I2S_setWriteQueueHead()

§ I2S_stopRead()

void I2S_stopRead ( I2S_Handle  handle)

Stop read transactions.

This function stops the reception of read transactions correctly so that read operations can be safely restarted later.

The application can decide at any time to suspend the reception of data by calling this function. In this case (and because the transaction queue is not empty) the execution of I2S_stopRead() is blocked until the current transaction is completed (this ensures that the I2S read interface is correctly stopped). Therefore, this function must be executed in a Task context (not in a HWI or Callback context).

After the transfers have been stopped (either by calling I2S_stopRead() or because the queue has been empty), the application can resume the transfers using the function I2S_startRead(). If the read-queue was empty application must beforehand set the first read-transaction using I2S_setReadQueueHead().

Parameters
[in]handleAn I2S_Handle.
Returns
void

§ I2S_stopWrite()

void I2S_stopWrite ( I2S_Handle  handle)

Stop write transactions.

This function stops the transmission of write transactions correctly so that writing operations can be safely restarted later.

The application can decide at any time to suspend the sending of data by calling this function. In this case (and because the transaction queue is not empty) the execution of I2S_stopWrite() is blocked until the current transaction is completed (this ensures that the I2S write interface is correctly stopped). Therefore, this function must be executed in a Task context (not in a HWI or Callback context).

After the transfers have been stopped (either by calling I2S_stopWrite() or because the queue has been empty), the application can resume the transfers using the function I2S_startWrite(). If the write-queue was empty application must beforehand set the first write-transaction using I2S_setWriteQueueHead().

Parameters
[in]handleAn I2S_Handle.
Returns
void

Variable Documentation

§ I2S_defaultParams

const I2S_Params I2S_defaultParams

Default I2S_Params structure.

See also
I2S_Params_init()
© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale