I2SWFF3.h File Reference

Detailed Description

I2S driver implementation for WFF3 devices.

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

Limitations

Supported I2S_MemoryLength values

Only the following memory lengths are supported:

• I2S_MEMORY_LENGTH_16BITS
• I2S_MEMORY_LENGTH_32BITS

I2S_Params Attributes Limitations

Some attributes in the I2S_Params structure have a limited set of supported values. These limitations are described below:

• I2S_Params.isDMAUnused
  • Must be false. All transmissions are always performed by the I2S module's own DMA.
• I2S_Params.isMSBFirst
  • Must be true. All samples are always transmitted MSB first.
• I2S_Params.memorySlotLength
  • Must be one of the suported I2S_MemoryLength values listed in the above section.
• I2S_Params.fixedBufferLength
  • Additional restriction: Must be an even multiple of the number of bytes in a frame.

---

Sample Buffers

This section describes the structure and requirements for the sample buffers used in the I2S_Transaction objects.

Sample words are read from or written to the sample buffers in little-endian byte order, meaning that the least significant byte (LSByte) is stored at the lower byte address, and the most significant byte (MSByte) is stored at the higher byte address.

The sample buffers are divided into frames which are further subdivided into channels, and if a channel is used by both SD0 and SD1 (where the direction of the two pins are the same), then that channel is further subdivided into a sample word for first SD0 and then SD1.

Buffer Size Requirements

The size of the buffers used in I2S_Transaction objects must be an even multiple of the number of bytes per frame. I.e. the number of bytes in the buffers must be of the form: 2*n*k, where k is the size of a frame in bytes and n is an integer satisfying n>=2. 2*n is the number of frames in the buffer.

General Sample Buffer Structure

Below code describes the general structure of a sample buffer if SD0 and SD1 are configured to the same direction.

struct
{
#if SD0_USE_CHANNEL_0 || SD1_USE_CHANNEL_0
    struct
    {
  #if SD0_USE_CHANNEL_0
        uint8_t sd0SampleWord[BYTES_PER_WORD];
  #endif
  #if SD1_USE_CHANNEL_0
        uint8_t sd1SampleWord[BYTES_PER_WORD];
  #endif
    } channel0;
#endif
#if SD0_USE_CHANNEL_1 || SD1_USE_CHANNEL_1
    struct
    {
  #if SD0_USE_CHANNEL_1
        uint8_t sd0SampleWord[BYTES_PER_WORD];
  #endif
  #if SD1_USE_CHANNEL_1
        uint8_t sd1SampleWord[BYTES_PER_WORD];
  #endif
    } channel1;
#endif
// ...
#if SD0_USE_CHANNEL_8 || SD1_USE_CHANNEL_8
    struct
    {
  #if SD0_USE_CHANNEL_8
        uint8_t sd0SampleWord[BYTES_PER_WORD];
  #endif
  #if SD1_USE_CHANNEL_8
        uint8_t sd1SampleWord[BYTES_PER_WORD];
  #endif
    } channel8;
#endif
} sampleBufferFrames[FRAMES_PER_BUFFER];

Notes:

• SD0_USE_CHANNEL_n should be true if SD0 uses channel n, otherwise false.
• SD1_USE_CHANNEL_n should be true if SD1 uses channel n, otherwise false.
• BYTES_PER_WORD is based on the configured memory length:
  • I2S_MEMORY_LENGTH_16BITS: 2
  • I2S_MEMORY_LENGTH_32BITS: 4
• FRAMES_PER_BUFFER must be divisible by 2
• sampleBufferFrames needs to be cast to an uint8_t pointer to be used with the I2S driver.

If SD0 and SD1 are not configured to the same direction (or only one is used) then the structure can be simplified as below:

struct
{
#if USE_CHANNEL_0
    uint8_t channel0SampleWord[BYTES_PER_WORD];
#endif
#if USE_CHANNEL_1
    uint8_t channel1SampleWord[BYTES_PER_WORD];
#endif
// ...
#if USE_CHANNEL_8
    uint8_t channel8SampleWord[BYTES_PER_WORD];
#endif
} sampleBufferFrames[FRAMES_PER_BUFFER];

Notes:

• USE_CHANNEL_n should be true if channel n is used, otherwise false.

Sample Buffer Structure Example

If for example SD0 and SD1 are configured to the same direction and if channel 0 and 1 are used for SD0 and channel 0 is used for SD1, then the sample buffer would be structured as in the code below.

struct
{
    struct
    {
        uint8_t sd0SampleWord[BYTES_PER_WORD];
        uint8_t sd1SampleWord[BYTES_PER_WORD];
    } channel0;
    struct
    {
        uint8_t sd0SampleWord[BYTES_PER_WORD];
    } channel1;
} sampleBufferFrames[FRAMES_PER_BUFFER];

 // Access LSB of sample 10 of channel 0 on SD1
 uint8_t tmp = sampleBufferFrames[10].channel0.sd1SampleWord[0];

---

Adaptive Digital Frequency Synthesizer (ADFS)

The I2S module uses an Adaptive Digital Frequency Synthesizer (ADFS) to divide a selected clock source and produce the audio clock (ACLK) frequency.

Using the ADFS it is possible to achieve an ACLK frequency that is a multiple of the most common sample rates, which can then be used to achieve the most common sample frequencies. It is also possible to configre the ADFS to use the selected clock source as the audio clock. This is not intended for any standard sample rate, but it can still be selected if desired.

Selecting the Clock Source

Using I2SWFF3_HWAttrs.clkSrc it is possible to select the input clock to the ADFS. The selected input is the clock cource used by the ADFS used to generate the audio clock frequency.

The following clock sources are available:

• I2SWFF3_CLK_SRC_SOC_CLK
• I2S_CLK_SRC_SOC_PLL_CLK
• I2SWFF3_CLK_SRC_HFXT_CLK

To achieve the best performance, it is suggested to use I2SWFF3_CLK_SRC_SOC_PLL_CLK as the clock source. This is because this clock is un-swallowed. Swallowing is a clock division technique that works by eliminating/delaying pulses, which has the downside of introducing jitter. Note that I2SWFF3_CLK_SRC_SOC_CLK uses swallowing.

Another advantage of selecting the SOC PLL clock is its ability to produce the largest division factor in the ADFS due to its higher frequency. This also reduces jitter.

Selecting the Audio Clock Frequency

The audio clock (ACLK) is the output of the ADFS. This is used by the I2S hardware module when the I2S driver is opened in Controller mode (I2S_Params.moduleRole == I2S_CONTROLLER). The I2S hardware module will divide the ACLK to generate the I2S clocks (BCLK (SCK), WCLK (Ws) and CCLK). The ACLK therefore directly determines the possible sample rates, i.e. the frequency of WCLK.

To achieve a desired sample frequency (f_s), the following requirements must be met, where f_aclk is the frequency of the ACLK:

• f_aclk/f_s must be an integer. I.e. f_aclk = n * f_s, where n is an integer.
• The total number of bits per frame must evenly divide into f_aclk/f_s

For example, if f_s = 44.1 kHz, then the first requirement is met if for example f_aclk = 11.2896 MHz = 256 * 44.1 kHz. The second requirement is met if for example the number of bits per frame is 32, because it evenly divides into 256.

If the requirements are not met, the closest possible sampling frequency to the desired sampling frequency will be used.

The frequencies most suited to be used with I2S are listed below:

• 12.288 MHz:
  • This can be used to achieve sample rates of 8 kHz, 16 kHz, 24 kHz, 32 kHz and 48 kHz.
    • For 8 kHz, 16 kHz and 32 kHz the number of bits per frame must be of the form: 2^n * 3^k, where n is an integer and k is either 0 or 1. The range of valid values of n for 8 kHz, 16 kHz and 32 kHz is [0-9], [0-8] and [0-7] respectively.
    • For 24 kHz and 48 kHz the number of bits per frame must be of the form: 2^n, where n is an integer. The range of valid values of n for 24 kHz and 48 kHz is [0-9] and [0-8] respectively.
• 11.2896 MHz:
  • This can be used to achieve sample rates of 22.05 kHz and 44.1 kHz. The number of bits per frame must be of the form: 2^n, where n is an integer. The range of valid values of n for 22.05 kHz and 44.1 kHz is [0-9] and [0-8] respectively.

Using the ADFS

The ADFS is used to generate an arbitrary clock frequency from a given input clock by division and adaptive swallowing. The resultant clock frequency mean is equal to the desired value although a significant jitter may occur. The best results are achieved when there is a large factor between the input clock frequency (Fref) and the desired output frequency (Freq).

In I2S, the ADFS is used to divide the clock source into an ACLK that is a multiple of the most common sample rates. To achieve this, the ADFS is configured with the following parameters:

• tref: Freq period in picoseconds, represented as a fixed-point number with 17 integer bits and 4 fractional bits.
• div: Divisor used to approximate the ratio between Fref and Freq. It is calculated to minimize the error (delta) between the actual and desired frequency ratios. Should be an integer higher or equal than 1.
• delta: Error in picoseconds that quantifies how far the achieved period (using the chosen divider) deviates from the desired period. It is represented as a fixed-point number with 13 integer bits and 4 fractional bits.
• deltaSign: Represents whether delta is negative (1) or non-negative (0).

The next equations can be used to compute the parameters:

tref = floor((1 / Fref) * 16)

div_temp1 = floor(Fref / Freq);
div_temp2 = ceil(Fref / Freq);

delta_temp1 = ((1/(Freq*div_temp1))-(1/Fref));
delta_temp2 = ((1/(Freq*div_temp2))-(1/Fref));

if (abs(delta_temp1) < abs(delta_temp2))
{
    div = div_temp1;
    delta = delta_temp1;
}
else
{
    div = div_temp2;
    delta = delta_temp2;
}

deltaSign = (delta < 0) ? 1 : 0;

delta = floor(abs(delta)*16)

Populate the I2SWFF3_ADFS structure with the computed parameters in order to use the ADFS. The computation should be done using one of the supported clock sorces as Fref and the desired audio clock as Freq.

Due to rounding errors, the ADFS may not be able to achieve the desired audio clock frequency. To compute the actual output frequency in hertz use the following formula (Fref must be in hertz):

if (deltaSign == 0)
{
    adfsOutputFreq = 1E12 / (((1E12 / Fref) + (delta/16)) * div);
}
else
{
    adfsOutputFreq = 1E12 / (((1E12 / Fref) - (delta/16)) * div);
}

Assign the calculated adfsOutputFreq to I2SWFF3_HWAttrs.audioClkFreq to specify the actual ACLK frequency used by the module.

---

#include <stdint.h>
#include <stdbool.h>
#include <ti/drivers/I2S.h>
#include <ti/drivers/dpl/SemaphoreP.h>
#include <ti/drivers/dpl/HwiP.h>
#include <ti/drivers/Power.h>
#include <ti/devices/DeviceFamily.h>
#include <DeviceFamily_constructPath(driverlib/i2s.h)>

Include dependency graph for I2SWFF3.h:

Go to the source code of this file.

Data Structures
struct	I2SWFF3_ADFS
	Adaptive Digital Frequency Synthesizer (ADFS) More...
struct	I2SWFF3_HWAttrs
	I2S Hardware attributes. More...

Enumerations
enum	I2SWFF3_ClkSrc { I2SWFF3_CLK_SRC_SOC_CLK = I2S_CLK_SRC_SOC_CLK, I2SWFF3_CLK_SRC_SOC_PLL_CLK = I2S_CLK_SRC_SOC_PLL_CLK, I2SWFF3_CLK_SRC_HFXT_CLK = I2S_CLK_SRC_HFXT_CLK }
	Clock Source. More...

Enumeration Type Documentation

I2SWFF3_ClkSrc

enum I2SWFF3_ClkSrc

Clock Source.

Option to select the clock source used by the I2S hardware module when the I2S driver is opened in Controller mode.

See also

Selecting the Clock Source

Enumerator
I2SWFF3_CLK_SRC_SOC_CLK	System-on-Chip clock, 80 Mhz.
I2SWFF3_CLK_SRC_SOC_PLL_CLK	Divided Phase-Locked Loop clock, 160 Mhz.
I2SWFF3_CLK_SRC_HFXT_CLK	High-Frequency Crystal clock, 40 Mhz.