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

Detailed Description

I2S driver interface.


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 blocking, non-blocking, read and write characters on the McASP peripheral.

The APIs in this driver serve as an interface to a typical RTOS application. Its purpose is to redirect the I2S APIs to specific driver implementations which are specified using a pointer to an I2S_FxnTable. The specific peripheral implementations are responsible for creating all the RTOS specific primitives to allow for thread-safe operation.

Usage

To use the I2S driver for reaading and writing data to the I2S peripheral, the application calls the following APIs:

I2S Driver Configuration

In order to use the I2S APIs, the application is required to provide device-specific I2S configuration in the Board.c file. The I2S driver interface defines a configuration data structure:

typedef struct I2S_Config_ {
// Pointer to driver-specific implementation of I2S functions
void *object; // Driver specific data object
void const *hwAttrs; // Driver specific hardware attributes

The application must declare an array of I2S_Config elements, named I2S_config[]. Each element of I2S_config[] must be populated with pointers to a device specific I2S driver implementation's function table, driver object, and hardware attributes. The hardware attributes define properties such as the I2S peripheral's base address and pins. Each element in I2S_config[] corresponds to an I2S instance, and and none of the elements should have NULL pointers. There is no correlation between the index and the peripheral designation (such as I2S0 or I2S1). For example, it is possible to use I2S_config[0] for I2S1.

Because I2S configuration is very device dependent, you will need to check the doxygen for the device specific I2S implementation. There you will find a description of the I2S hardware attributes. Please also refer to the board.c file of any of your examples to see the I2S configuration.

Initializing the I2S Driver

I2S_init() must be called before any other I2S APIs. This function iterates through the elements of the I2S_config[] array, calling the element's device implementation I2S initialization function.

I2S Parameters

The I2S_Params structure is passed to the I2S_open() call. If NULL is passed for the parameters, I2S_open() uses default parameters. An I2S_Params structure is initialized with default values by passing it to I2S_Params_init(). Some of the I2S parameters are described below. To see brief descriptions of all the parameters, see I2S_Params.

I2S Operation Mode

The I2S operation mode determines whether transmit and/or receive modes are enabled. The mode is specified with one of the following constants:

I2S Data Mode

A separate data mode may be specified for read calls and write calls. The available modes are:

Opening the I2S Driver

After initializing the I2S driver by calling I2S_init(), the application can open an I2S instance by calling I2S_open(). This function takes an index into the I2S_config[] array, and an I2S parameters data structure. The I2S instance is specified by the index of the I2S in I2S_config[]. Only one I2S index can be used at a time; calling I2S_open() a second time with the same index previosly passed to I2S_open() will result in an error. You can, though, re-use the index if the instance is closed via I2S_close().

If NULL is passed for the I2S_Params structure to I2S_open(), default values are used. If the open call is successful, it returns a non-NULL value.

Example opening an I2S driver instance:

I2S_Handle handle;
I2S_Params params;
I2S_Params_init(&params);
params.operationMode = I2S_MODE_TX_RX_SYNC;
< Change other params as required >
handle = I2S_open(Board_I2S0, &params);
if (!handle) {
// Error opening I2S, handle accordingly
}

Writing Data

The following example calls I2S_writeIssue() to write to an I2S driver instance that has been opened. It first queues up two buffers of text. Within an infinite loop, it calls I2S_writeReclaim() to retrieve a buffer and then re-queues the buffer.

const unsigned char hello[] = "Hello World\n";
const unsigned char hello1[] = "Hello World1\n";
I2S_BufDesc writeBuffer1;
I2S_BufDesc writeBuffer2;
I2S_BufDesc *pDesc = NULL;
writeBuffer1.bufPtr = &hello;
writeBuffer1.bufSize = sizeof(hello);
writeBuffer2.bufPtr = &hello1;
writeBuffer2.bufSize = sizeof(hello1);
ret = I2S_writeIssue(handle, &writeBuffer1);
ret = I2S_writeIssue(handle, &writeBuffer2);
while(1) {
ret = I2S_writeReclaim(handle, &pDesc);
pDesc->bufPtr = &hello;;
pDesc->bufSize = sizeof(hello);
ret = I2S_writeIssue(handle, pDesc);
}

Reading Data

The following example calls I2S_readIssue() to queue a buffer for reading from an I2S driver instance. It first queues up two buffers of text. Within an infinite loop, it then calls I2S_readReclaim() to retrieve a full buffer of data.

unsigned char rxBuffer[20];
unsigned char rxBuffer1[20];
I2S_BufDesc readBuffer1;
I2S_BufDesc readBuffer2;
I2S_BufDesc *pDesc = NULL;
readBuffer1.bufPtr = &rxBuffer;
readBuffer1.bufSize = 20;
readBuffer2.bufPtr = &rxBuffer1;
readBuffer2.bufSize = 20;
ret = I2S_readIssue(handle, &readBuffer1);
ret = I2S_readIssue(handle, &readBuffer2);
while(1)
{
ret = I2S_readReclaim(handle, &pDesc);
pDesc->bufPtr = &rxBuffer;
pDesc->bufSize = 20;
ret = I2S_readIssue(handle, pDesc);
}

Implementation

The I2S driver interface module is joined (at link time) to an array of I2S_Config data structures named I2S_config. I2S_config is implemented in the application with each entry being an instance of a I2S peripheral. Each entry in I2S_config contains a:

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

Go to the source code of this file.

Data Structures

struct  I2S_BufDesc_
 I2S buffer descriptor for issue/reclaim mode. More...
 
struct  I2S_Params_
 Basic I2S Parameters. More...
 
struct  I2S_FxnTable_
 The definition of a I2S function table that contains the required set of functions to control a specific I2S driver implementation. More...
 
struct  I2S_Config_
 I2S Global configuration. More...
 

Macros

#define I2S_CMD_RESERVED   (32)
 
#define I2S_STATUS_RESERVED   (-32)
 
#define I2S_STATUS_SUCCESS   (0)
 Successful status code returned by I2S_control(). More...
 
#define I2S_STATUS_ERROR   (-1)
 Generic error status code returned by I2S_control(). More...
 
#define I2S_STATUS_UNDEFINEDCMD   (-2)
 An error status code returned by I2S_control() for undefined command codes. More...
 
#define I2S_ERROR   (I2S_STATUS_ERROR)
 
#define I2S_WAIT_FOREVER   (~(0U))
 Wait forever define. More...
 

Typedefs

typedef struct I2S_Config_I2S_Handle
 A handle that is returned from a I2S_open() call. More...
 
typedef struct I2S_BufDesc_ I2S_BufDesc
 I2S buffer descriptor for issue/reclaim mode. More...
 
typedef void(* I2S_Callback) (I2S_Handle handle, I2S_BufDesc *desc)
 The definition of a callback function used by the I2S driver when used in I2S_MODE_CALLBACK. More...
 
typedef enum I2S_DataMode_ I2S_DataMode
 I2S mode settings. More...
 
typedef enum I2S_OpMode_ I2S_OpMode
 I2S mode settings. More...
 
typedef enum I2S_SerInActiveConfig_ I2S_SerInActiveConfig
 I2S Serializer InActive state settings. More...
 
typedef enum I2S_PinMode_ I2S_PinMode
 I2S serial pin mode. More...
 
typedef struct I2S_Params_ I2S_Params
 Basic I2S Parameters. More...
 
typedef void(* I2S_CloseFxn) (I2S_Handle handle)
 A function pointer to a driver specific implementation of I2S_CloseFxn(). More...
 
typedef int_fast16_t(* I2S_ControlFxn) (I2S_Handle handle, uint_fast16_t cmd, void *arg)
 A function pointer to a driver specific implementation of I2S_control(). More...
 
typedef void(* I2S_InitFxn) (I2S_Handle handle)
 A function pointer to a driver specific implementation of I2S_init(). More...
 
typedef I2S_Handle(* I2S_OpenFxn) (I2S_Handle handle, I2S_Params *params)
 A function pointer to a driver specific implementation of I2S_OpenFxn(). More...
 
typedef int_fast16_t(* I2S_IssueFxn) (I2S_Handle handle, I2S_BufDesc *desc)
 A function pointer to a driver specific implementation of I2S_IssueFxn(). More...
 
typedef size_t(* I2S_ReclaimFxn) (I2S_Handle handle, I2S_BufDesc **desc)
 A function pointer to a driver specific implementation of I2S_ReclaimFxn(). More...
 
typedef struct I2S_FxnTable_ I2S_FxnTable
 The definition of a I2S function table that contains the required set of functions to control a specific I2S driver implementation. More...
 
typedef struct I2S_Config_ I2S_Config
 I2S Global configuration. More...
 

Enumerations

enum  I2S_DataMode_ { I2S_MODE_CALLBACK, I2S_MODE_ISSUERECLAIM }
 I2S mode settings. More...
 
enum  I2S_OpMode_ { I2S_OPMODE_TX_ONLY, I2S_OPMODE_RX_ONLY, I2S_OPMODE_TX_RX_SYNC }
 I2S mode settings. More...
 
enum  I2S_SerInActiveConfig_ { I2S_SERCONFIG_INACT_TRI_STATE, I2S_SERCONFIG_INACT_LOW_LEVEL, I2S_SERCONFIG_INACT_HIGH_LEVEL }
 I2S Serializer InActive state settings. More...
 
enum  I2S_PinMode_ { I2S_PINMODE_RX, I2S_PINMODE_TX, I2S_PINMODE_INACTIVE }
 I2S serial pin mode. More...
 

Functions

void I2S_close (I2S_Handle handle)
 Function to close a given I2S peripheral specified by the I2S handle. More...
 
int_fast16_t I2S_control (I2S_Handle handle, uint_fast16_t cmd, void *arg)
 Function performs implementation specific features on a given 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...
 
int_fast16_t I2S_read (I2S_Handle handle, I2S_BufDesc *desc)
 Function to queue a buffer of data to the I2S in callback mode for reading. More...
 
int_fast16_t I2S_readIssue (I2S_Handle handle, I2S_BufDesc *desc)
 Function to queue a buffer of data to the I2S in Issue/Reclaim mode for reading. More...
 
size_t I2S_readReclaim (I2S_Handle handle, I2S_BufDesc **pDesc)
 Function to retrieve a full buffer of data read by the I2S. More...
 
int_fast16_t I2S_write (I2S_Handle handle, I2S_BufDesc *desc)
 Function to queue a buffer of data to the I2S in callback mode for writing. More...
 
int_fast16_t I2S_writeIssue (I2S_Handle handle, I2S_BufDesc *desc)
 Function to queue a buffer of data to the I2S in Issue/Reclaim mode for writing. More...
 
size_t I2S_writeReclaim (I2S_Handle handle, I2S_BufDesc **pDesc)
 Function to retrieve a buffer that the I2S has finished writing. More...
 

Macro Definition Documentation

§ I2S_ERROR

#define I2S_ERROR   (I2S_STATUS_ERROR)

§ I2S_WAIT_FOREVER

#define I2S_WAIT_FOREVER   (~(0U))

Wait forever define.

Typedef Documentation

§ I2S_Handle

typedef struct I2S_Config_* I2S_Handle

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

§ I2S_BufDesc

typedef struct I2S_BufDesc_ I2S_BufDesc

I2S buffer descriptor for issue/reclaim mode.

§ I2S_Callback

typedef void(* I2S_Callback) (I2S_Handle handle, I2S_BufDesc *desc)

The definition of a callback function used by the I2S driver when used in I2S_MODE_CALLBACK.

Parameters
I2S_HandleI2S_Handle
bufPointer to read/write buffer
countNumber of elements read/written

§ I2S_DataMode

I2S mode settings.

This enum defines the read and write modes for the configured I2S.

§ I2S_OpMode

typedef enum I2S_OpMode_ I2S_OpMode

I2S mode settings.

This enumeration defines the mode for I2S operation.

§ I2S_SerInActiveConfig

I2S Serializer InActive state settings.

This enumeration defines the Serializer configuration in inactive state.

§ I2S_PinMode

typedef enum I2S_PinMode_ I2S_PinMode

I2S serial pin mode.

This enumeration defines the Serial pin configuration

§ I2S_Params

typedef struct I2S_Params_ I2S_Params

Basic I2S Parameters.

I2S parameters are used to with the I2S_open() call. Default values for these parameters are set using I2S_Params_init().

See also
I2S_Params_init()

§ I2S_CloseFxn

typedef void(* I2S_CloseFxn) (I2S_Handle handle)

A function pointer to a driver specific implementation of I2S_CloseFxn().

§ I2S_ControlFxn

typedef int_fast16_t(* I2S_ControlFxn) (I2S_Handle handle, uint_fast16_t cmd, void *arg)

A function pointer to a driver specific implementation of I2S_control().

§ I2S_InitFxn

typedef void(* I2S_InitFxn) (I2S_Handle handle)

A function pointer to a driver specific implementation of I2S_init().

§ I2S_OpenFxn

typedef I2S_Handle(* I2S_OpenFxn) (I2S_Handle handle, I2S_Params *params)

A function pointer to a driver specific implementation of I2S_OpenFxn().

§ I2S_IssueFxn

typedef int_fast16_t(* I2S_IssueFxn) (I2S_Handle handle, I2S_BufDesc *desc)

A function pointer to a driver specific implementation of I2S_IssueFxn().

§ I2S_ReclaimFxn

typedef size_t(* I2S_ReclaimFxn) (I2S_Handle handle, I2S_BufDesc **desc)

A function pointer to a driver specific implementation of I2S_ReclaimFxn().

§ I2S_FxnTable

typedef struct I2S_FxnTable_ I2S_FxnTable

The definition of a I2S function table that contains the required set of functions to control a specific I2S driver implementation.

§ I2S_Config

typedef struct I2S_Config_ I2S_Config

I2S Global configuration.

The I2S_Config structure contains a set of pointers used to characterize the I2S driver implementation.

This structure needs to be defined before calling I2S_init() and it must not be changed thereafter.

See also
I2S_init()

Enumeration Type Documentation

§ I2S_DataMode_

I2S mode settings.

This enum defines the read and write modes for the configured I2S.

Enumerator
I2S_MODE_CALLBACK 

Non-blocking and will return immediately. When the transfer by the intr is finished the configured callback function is called.

I2S_MODE_ISSUERECLAIM 

Use I2S_readIssue, I2S_writeIssue calls to queue buffers to the I2S. I2S_readReclaim() blocks until a buffer of data is available. I2S_writeReclaim() blocks until a buffer of data has been written and the descriptor can be returned back to the caller.

§ I2S_OpMode_

I2S mode settings.

This enumeration defines the mode for I2S operation.

Enumerator
I2S_OPMODE_TX_ONLY 

Only Transmit enabled

I2S_OPMODE_RX_ONLY 

Only Receive enabled

I2S_OPMODE_TX_RX_SYNC 

Receive and Transmit are enabled in Sync

§ I2S_SerInActiveConfig_

I2S Serializer InActive state settings.

This enumeration defines the Serializer configuration in inactive state.

Enumerator
I2S_SERCONFIG_INACT_TRI_STATE 

Inactive state to tristate

I2S_SERCONFIG_INACT_LOW_LEVEL 

Inactive state to low

I2S_SERCONFIG_INACT_HIGH_LEVEL 

Inactive state to high

§ I2S_PinMode_

I2S serial pin mode.

This enumeration defines the Serial pin configuration

Enumerator
I2S_PINMODE_RX 

Operate the pin in Rx mode

I2S_PINMODE_TX 

Operate the pin in Tx mode

I2S_PINMODE_INACTIVE 

Pin in inactive mode

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
handleA I2S_Handle returned from I2S_open
See also
I2S_open()

§ I2S_control()

int_fast16_t I2S_control ( I2S_Handle  handle,
uint_fast16_t  cmd,
void *  arg 
)

Function performs implementation specific features on a given I2S_Handle.

Commands for I2S_control can originate from I2S.h or from implementation specific I2S*.h (I2SCC32XX.h, etc.. ) files. While commands from I2S.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific I2S*.h files add unique driver capabilities but are not API portable across all I2S driver implementations.

Commands supported by I2S.h follow a I2S_CMD_<cmd> naming convention.
Commands supported by I2S*.h follow a I2S*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.

See I2S_control command codes for command codes.

See I2S_control return status codes for status codes.

Precondition
I2S_open() has to be called first.
Parameters
handleA I2S handle returned from I2S_open()
cmdI2S.h or I2S*.h commands.
argAn optional R/W (read/write) command argument accompanied with cmd
Returns
Implementation specific return codes. Negative values indicate unsuccessful operations.
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
indexLogical peripheral number for the I2S indexed into the I2S_config table
paramsPointer to an parameter block, if NULL it will use default values. All the fields in this structure are RO (read-only).
Returns
A 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
paramsAn pointer to I2S_Params structure for initialization

Defaults values are:

params.samplingFrequency = 16000;
params.slotLength = 16;
params.bitsPerSample = 16;
params.numChannels = 2;
params.readCallback = NULL;
params.writeCallback = NULL;
params.customParams = NULL;
Parameters
paramsParameter structure to initialize

§ I2S_read()

int_fast16_t I2S_read ( I2S_Handle  handle,
I2S_BufDesc desc 
)

Function to queue a buffer of data to the I2S in callback mode for reading.

Parameters
handleA I2S_Handle
descA pointer to a I2S_BufDesc object. The bufPtr and bufSize fields must be set to a buffer and the size of the buffer before passing to this function.
Returns
Returns 0 if successful else would return I2S_STATUS_UNDEFINEDCMD on an error.

§ I2S_readIssue()

int_fast16_t I2S_readIssue ( I2S_Handle  handle,
I2S_BufDesc desc 
)

Function to queue a buffer of data to the I2S in Issue/Reclaim mode for reading.

Parameters
handleA I2S_Handle
descA pointer to a I2S_BufDesc object. The bufPtr and bufSize fields must be set to a buffer and the size of the buffer before passing to this function.
Returns
Returns 0 if successful else would return I2S_STATUS_UNDEFINEDCMD on an error.

§ I2S_readReclaim()

size_t I2S_readReclaim ( I2S_Handle  handle,
I2S_BufDesc **  pDesc 
)

Function to retrieve a full buffer of data read by the I2S.

Parameters
handleA I2S_Handle
pDescA pointer to a I2S_BufDesc pointer.
Returns
Returns the number of bytes read from the I2S, or 0 on timeout.

§ I2S_write()

int_fast16_t I2S_write ( I2S_Handle  handle,
I2S_BufDesc desc 
)

Function to queue a buffer of data to the I2S in callback mode for writing.

Parameters
handleA I2S_Handle
descA pointer to a I2S_BufDesc object. The bufPtr and bufSize fields must be set to a buffer and the size of the buffer before passing to this function.
Returns
Returns 0 if successful else would return I2S_STATUS_UNDEFINEDCMD on an error.

§ I2S_writeIssue()

int_fast16_t I2S_writeIssue ( I2S_Handle  handle,
I2S_BufDesc desc 
)

Function to queue a buffer of data to the I2S in Issue/Reclaim mode for writing.

Parameters
handleA I2S_Handle
descA pointer to a I2S_BufDesc object. The bufPtr and bufSize fields must be set to a buffer and the size of the buffer before passing to this function.
Returns
Returns 0 if successful else would return I2S_STATUS_UNDEFINEDCMD on an error.

§ I2S_writeReclaim()

size_t I2S_writeReclaim ( I2S_Handle  handle,
I2S_BufDesc **  pDesc 
)

Function to retrieve a buffer that the I2S has finished writing.

Parameters
handleA I2S_Handle
pDescA pointer to a I2S_BufDesc pointer.
Returns
Returns the number of bytes that have been written to the I2S, 0 on timeout.
Copyright 2017, Texas Instruments Incorporated