Inter-Integrated Circuit Sound (I2S) Bus Driver.
The I2S header file should be included in an application as follows:
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.
The I2S driver provides the following APIs:
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.
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.
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:
The following example shows how to simultaneously receive and send out a given amount of data.
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)
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.
Refer to the Driver's Configuration section for driver configuration information.
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_Config * | I2S_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... | |
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 CCLK clocks. More... | |
void | I2S_stopClocks (I2S_Handle handle) |
Stops the WS, SCK and CCLK 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 I2S_Config* I2S_Handle |
A handle that is returned from a I2S_open() call.
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.
I2S_Handle | I2S_Handle |
status | Status 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. |
typedef void(* I2S_RegUpdate) (uint32_t ui32Base, uint32_t ui32NextPointer) |
The definition of a function used to set the I2S register.
uint32_t | ui32Base: base address of the I2S module. |
uint32_t | ui32NextPointer: pointer on an I2S buffer. |
typedef void(* I2S_StopInterface) (I2S_Handle handle) |
The definition of a function used to stop an I2S interface.
I2S_Handle | I2S_Handle |
enum 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 bits transmitted, but it should be consistent with the chosen word length.
enum I2S_Role |
I2S controller / target selection.
The enum defines if the module acts like a controller (clocks are internally generated) or a target (the clocks are externally generated).
Enumerator | |
---|---|
I2S_TARGET | Module is a target, clocks are externally generated. |
I2S_CONTROLLER | Module is a controller, clocks are internally generated. |
enum I2S_SamplingEdge |
enum I2S_PhaseType |
enum 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 |
enum I2S_ChannelConfig |
Channels used selection.
The enum defines different settings to activate the expected channels.
void I2S_close | ( | I2S_Handle | handle | ) |
Function to close a given I2S peripheral specified by the I2S handle.
[in] | handle | An I2S_Handle returned from I2S_open |
void I2S_init | ( | void | ) |
Function to initializes the I2S module.
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.
[in,out] | index | Logical peripheral number for the I2S indexed into the I2S_config table |
[in] | params | Pointer to an parameter block. All the fields in this structure are RO (read-only). Provide a NULL pointer cannot open the module. |
void I2S_Params_init | ( | I2S_Params * | params | ) |
Function to initialize the I2S_Params struct to its defaults.
[out] | params | An pointer to I2S_Params structure for initialization |
Defaults values are:
params | Parameter structure to initialize |
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.
[out] | transaction | Transaction struct to initialize. |
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.
[in] | handle | An I2S_Handle. |
[in] | transaction | A 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. |
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.
[in] | handle | An I2S_Handle. |
[in] | transaction | A 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. |
void I2S_startClocks | ( | I2S_Handle | handle | ) |
Start the WS, SCK and CCLK clocks.
This function enable WS, SCK and CCLK (if activated) clocks. This is required before starting any reading or a writing transaction. This function is supposed to be executed both in target and controller mode.
[in] | handle | An I2S_Handle. |
void I2S_stopClocks | ( | I2S_Handle | handle | ) |
Stops the WS, SCK and CCLK clocks.
This function disable WS, SCK and CCLK 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 target and controller mode.
[in] | handle | An I2S_Handle. |
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).
[in] | handle | An I2S_Handle. |
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).
[in] | handle | An I2S_Handle. |
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().
[in] | handle | An I2S_Handle. |
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().
[in] | handle | An I2S_Handle. |
const I2S_Params I2S_defaultParams |
Default I2S_Params structure.