Detailed Description

I2S driver interface.

============================================================================

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

Operation

The I2S driver simplifies reading and writing to any of the McASP peripherals on the board with Receive and Transmit support. These include blocking, non-blocking, read and write characters on the McASP peripheral. The board's I2S peripheral and pins must be configured before initializing the I2S driver. The application initializes the I2S driver by calling I2S_init() and is then ready to open a I2S by calling I2S_open() and passing in a I2S parameters data structure.

The APIs in this driver serve as an interface to a typical OSAL application. The specific peripheral implementations are responsible to create all the OSAL specific primitives to allow for thread-safe operation.

Opening the driver

I2S_Handle      handle;
I2S_Params      params;
I2SCC3200DMA_SerialPinParams customParams;
I2S_Params_init(&params);
params.operationMode                     = I2S_MODE_TX_RX_SYNC;
< Change other params as required >
I2SCC3200DMA_Params_init(&customParams);
< Change custom params as required >
params->customParams = (I2SCC3200DMA_SerialPinParams *)&customParams;
handle = I2S_open(someI2S_configIndexValue, &params);
if (!handle) {
    System_printf("I2S did not open");
}

Writing data

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_write(handle, &writeBuffer1);
ret = I2S_write(handle, &writeBuffer2);
while(1)
{
    ret = I2S_writeReclaim(handle, &pDesc);
    System_printf("The I2S wrote %d bytes\n", ret);
    pDesc->bufPtr  = &hello;;
    pDesc->bufSize = sizeof(hello);
    ret = I2S_write(handle, pDesc);
}

Reading 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_read(handle, &readBuffer1);
ret = I2S_read(handle, &readBuffer2);
while(1)
{
    ret = I2S_readReclaim(handle, &pDesc);
    System_printf("The I2S read %d bytes\n", ret);
    pDesc->bufPtr = &rxBuffer;
    pDesc->bufSize = 20;
    ret = I2S_read(handle, pDesc);
}

Implementation

This module serves as the main interface for OSAL applications. Its purpose is to redirect the module's APIs to specific peripheral implementations which are specified using a pointer to a I2S_FxnTable.

The I2S driver interface module is joined (at link time) to a NULL-terminated 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:

(I2S_FxnTable *) to a set of functions that implement a I2S peripheral
(void *) data object that is associated with the I2S_FxnTable
(void *) hardware attributes that are associated to the I2S_FxnTable

#include <stdint.h>
#include <stddef.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_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 ~(0)
	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, 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(*	I2S_ControlFxn) (I2S_Handle handle, unsigned int 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(*	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	I2S_control (I2S_Handle handle, unsigned int 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 (unsigned int 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	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	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	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	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

#define I2S_ERROR I2S_STATUS_ERROR

#define I2S_WAIT_FOREVER ~(0)

Wait forever define.

Typedef Documentation

typedef struct I2S_Config* I2S_Handle

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

typedef struct I2S_BufDesc I2S_BufDesc

I2S buffer descriptor for issue/reclaim mode.

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

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

Parameters

I2S_Handle	I2S_Handle
buf	Pointer to read/write buffer
count	Number of elements read/written

typedef enum I2S_DataMode I2S_DataMode

I2S mode settings.

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

typedef enum I2S_OpMode I2S_OpMode

I2S mode settings.

This enumeration defines the mode for I2S operation.

typedef enum I2S_SerInActiveConfig I2S_SerInActiveConfig

I2S Serializer InActive state settings.

This enumeration defines the Serializer configuration in inactive state.

typedef enum I2S_PinMode I2S_PinMode

I2S serial pin mode.

This enumeration defines the Serial pin configuration

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()

typedef void(* I2S_CloseFxn) (I2S_Handle handle)

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

typedef int(* I2S_ControlFxn) (I2S_Handle handle, unsigned int cmd, void *arg)

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

typedef void(* I2S_InitFxn) (I2S_Handle handle)

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

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

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

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

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

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

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

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.

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

enum 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.

enum 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

enum 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

enum 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

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

handle A I2S_Handle returned from I2S_open

See also: I2S_open()

int I2S_control	(	I2S_Handle	handle,
		unsigned int	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 (I2SCC3200.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

handle	A I2S handle returned from I2S_open()
cmd	I2S.h or I2S*.h commands.
arg	An optional R/W (read/write) command argument accompanied with cmd

Returns: Implementation specific return codes. Negative values indicate unsuccessful operations.

See also: I2S_open()

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_Handle I2S_open	(	unsigned int	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

index	Logical peripheral number for the I2S indexed into the I2S_config table
params	Pointer 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()

void I2S_Params_init ( I2S_Params * params )

Function to initialize the I2S_Params struct to its defaults.

Parameters

params An pointer to I2S_Params structure for initialization

Defaults values are: params.operationMode = I2S_MODE_TX_RX_SYNC; params.samplingFrequency = 16000; params.slotLength = 16; params.bitsPerSample = 16; params.numChannels = 2; params.readMode = I2S_MODE_ISSUERECLAIM; params.readCallback = NULL; params.readTimeout = I2S_WAIT_FOREVER; params.writeMode = I2S_MODE_ISSUERECLAIM; params.writeCallback = NULL; params.writeTimeout = I2S_WAIT_FOREVER; params.customParams = NULL;

Parameters

params Parameter structure to initialize

int I2S_read	(	I2S_Handle	handle,
		I2S_BufDesc *	desc
	)

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

Parameters

handle	A I2S_Handle
desc	A 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.

int 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

handle	A I2S_Handle
desc	A 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.

size_t I2S_readReclaim	(	I2S_Handle	handle,
		I2S_BufDesc **	pDesc
	)

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

Parameters

handle	A I2S_Handle
pDesc	A pointer to a I2S_BufDesc pointer.

Returns: Returns the number of bytes read from the I2S, or I2S_ERROR on an error.

int I2S_write	(	I2S_Handle	handle,
		I2S_BufDesc *	desc
	)

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

Parameters

handle	A I2S_Handle
desc	A 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.

int 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

handle	A I2S_Handle
desc	A 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.

size_t I2S_writeReclaim	(	I2S_Handle	handle,
		I2S_BufDesc **	pDesc
	)

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

Parameters

handle	A I2S_Handle
pDesc	A pointer to a I2S_BufDesc pointer.

Returns: Returns the number of bytes that have been written to the I2S, I2S_ERROR on an error.

Detailed Description

Operation

Opening the driver

Writing data

Reading data

Implementation

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation