1.1.5 I2S Driver Library Help

This library provides an interface to manage the I2S Audio Protocol Interface Modes.

The I2S Driver is connected to a hardware module that provides the actual I2S stream, on some MCUs this is a Serial Peripheral Interface (SPI), on others it may be an I2S Controller (I2SC), or Serial Synchronous Controller (SSC).

The I2S hardware peripheral is then interfaced to various devices such as codecs and Bluetooth modules to provide microcontroller-based audio solutions.

This topic describes the basic architecture of the I2S Driver Library and provides information and examples on its use.

The I2S Driver provides a high level abstraction of the lower level (SPI/I2SC/SSC) I2S modules with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the I2S Driver Library interface.

Description

Different types of I2S capable PLIBs are available on various Microchip microcontrollers. Some have an internal buffer mechanism and some do not. The buffer depth varies across part families. The I2S Driver Library abstracts out these differences and provides a unified model for audio data transfer across different types of I2S modules.

Both the transmitter and receiver provide a buffer in the driver, which transmits and receives data to/from the hardware. The I2S Driver Library provides a set of interfaces to perform the read and the write. The following diagrams illustrate the abstraction model used by the I2S Driver Library. The I2SC Peripheral is used as an example of an I2S-capable PLIB.

I2S Driver Abstraction Model

The PLIBs currently provided, such as SSC and I2SC, only support an interrupt/DMA mode of operation. Polled mode of operation is not supported.

Refer to the Driver Library Overwiew section for information on how the driver operates in a system.

The I2S driver library provides an API interface to transfer/receive digital audio data using supported Audio protocols. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the I2S Driver Library.

The library provides interfaces to support:

• System Functionality

• Client Functionality

This section provides information on system access.

The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization, each instance of the I2S module would be initialized with the following configuration settings (either passed dynamically at run time using DRV_I2S_INIT or by using Initialization Overrides) that are supported by the specific I2S device hardware:

• Device requested power state: one of the System Module Power States. For specific details please refer to Data Types and Constants in the Library Interface section.

• The actual peripheral ID enumerated as the PLIB level module ID (e.g., SPI_ID_2)

• Defining the respective interrupt sources for TX, RX, DMA TX Channel, DMA RX Channel and Error Interrupt

The DRV_I2S_Initialize API returns an object handle of the type SYS_MODULE_OBJ. The object handle returned by the Initialize interface would be used by the other system interfaces such as DRV_I2S_Deinitialize, DRV_I2S_Status, DRV_I2S_Tasks, and DRV_I2S_TasksError.

1. The system initialization setting only effect the instance of the peripheral that is being initialized.

2. Configuration of the dynamic driver for DMA mode(uses DMA channel for data transfer) or Non DMA mode can be performed by appropriately setting the 'dmaChannelTransmit' and 'dmaChannelReceive' variables of the DRV_I2S_INIT structure. For example the TX will be in DMA mode when 'dmaChannelTransmit' is initialized to a valid supported channel number from the enum DMA_CHANNEL. TX will be in Non DMA mode when 'dmaChannelTransmit' is initialized to 'DMA_CHANNEL_NONE'.

Example:

DRV_I2S_INIT init;

SYS_MODULE_OBJ objectHandle;

_/* I2S Driver Initialization Data */_

DRV_I2S_INIT drvI2S0InitData =

{

.i2sPlib = &drvI2S0PlibAPI,

.interruptI2S = DRV_I2S_INT_SRC_IDX0,

.numClients = DRV_I2S_CLIENTS_NUMBER_IDX0,

.queueSize = DRV_I2S_QUEUE_SIZE_IDX0,

.dmaChannelTransmit = DRV_I2S_XMIT_DMA_CH_IDX0,

.dmaChannelReceive = DRV_I2S_RCV_DMA_CH_IDX0,

.i2sTransmitAddress = (void *)&(SSC_REGS->SSC_THR),

.i2sReceiveAddress = (void *)&(SSC_REGS->SSC_RHR),

.interruptDMA = XDMAC_IRQn,

.dmaDataLength = DRV_I2S_DATA_LENGTH_IDX0,

};

sysObj.drvI2S0 = DRV_I2S_Initialize(DRV_I2S_INDEX_0, (SYS_MODULE_INIT *)&drvI2S0InitData); Task Routine

There is no task routine, since polled mode is not currently supported.

For the application to start using an instance of the module, it must call the DRV_I2S_Open function. This provides the settings required to open the I2S instance for operation.

For the various options available for IO_INTENT, please refer to Data Types and Constants in the Library Interface section.

Example:

DRV_HANDLE handle; handle = DRV_I2S_Open(drvObj->i2sDriverModuleIndex, (DRV_IO_INTENT_WRITE | DRV_IO_INTENT_NONBLOCKING)); if (DRV_HANDLE_INVALID == handle) {

_// Unable to open the driver_ _// May be the driver is not initialized or the initialization_ _// is not complete._

}

This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library.

This table lists and describes the source and header files that must always be included in the MPLAB X IDE project to build this library.

This table lists and describes the source and header files that may optionally be included if required for the desired implementation.

The I2S Driver Library depends on the following modules:

• I2S Peripheral Library,

• SSC Peripheral Library,

• I2SC Peripheral Library