I2S (r_ssi)

Functions
fsp_err_t	R_SSI_Open (i2s_ctrl_t *const p_ctrl, i2s_cfg_t const *const p_cfg)
fsp_err_t	R_SSI_Write (i2s_ctrl_t *const p_ctrl, void const *const p_src, uint32_t const bytes)
fsp_err_t	R_SSI_Read (i2s_ctrl_t *const p_ctrl, void *const p_dest, uint32_t const bytes)
fsp_err_t	R_SSI_WriteRead (i2s_ctrl_t *const p_ctrl, void const *const p_src, void *const p_dest, uint32_t const bytes)
fsp_err_t	R_SSI_Stop (i2s_ctrl_t *const p_ctrl)
fsp_err_t	R_SSI_Mute (i2s_ctrl_t *const p_ctrl, i2s_mute_t const mute_enable)
fsp_err_t	R_SSI_StatusGet (i2s_ctrl_t *const p_ctrl, i2s_status_t *const p_status)
fsp_err_t	R_SSI_Close (i2s_ctrl_t *const p_ctrl)
fsp_err_t	R_SSI_CallbackSet (i2s_ctrl_t *const p_api_ctrl, void(*p_callback)(i2s_callback_args_t *), void const *const p_context, i2s_callback_args_t *const p_callback_memory)

Detailed Description

Driver for the SSIE peripheral on RA MCUs. This module implements the I2S Interface.

Overview

Features

The SSI module supports the following features:

• Transmission and reception of uncompressed audio data using the standard I2S protocol in master and slave modes
• Full-duplex I2S communication (channel 0 only)
• Integration with the DTC transfer module
• Internal connection to GPT timer output to generate the audio clock
• Callback function notification when all data is loaded into the SSI FIFO

Configuration

Build Time Configurations for r_ssi

The following build time configurations are defined in fsp_cfg/r_ssi_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.
DTC Support	Enabled Disabled	Enabled	If code for DTC transfer support is included in the build.

Configurations for Connectivity > I2S (r_ssi)

This module can be added to the Stacks tab via New Stack > Connectivity > I2S (r_ssi). Non-secure callable guard functions can be generated for this module by right clicking the module in the RA Configuration tool and checking the "Non-secure Callable" box.

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_i2s0	Module name.
Channel	Value must be a non-negative integer	0	Specify the I2S channel.
Operating Mode (Master/Slave)	Master Mode Slave Mode	Master Mode	Select if the MCU is I2S master or slave.
Bit Depth	8 Bits 16 Bits 18 Bits 20 Bits 22 Bits 24 Bits 32 Bits	16 Bits	Select the bit depth of one sample of audio data.
Word Length	8 Bits 16 Bits 24 Bits 32 Bits 48 Bits 64 Bits 128 Bits 256 Bits	16 Bits	Select the word length of audio data. Must be at least as large as Data bits.
WS Continue Mode	Enabled Disabled	Disabled	Enable WS continue mode to output the word select (WS) pin even when transmission is idle.
Bit Clock Source(available only in Master mode)	MCU Specific Options		Select External AUDIO_CLK for external signal to AUDIO_CLK input pin or Internal AUDIO_CLK for internal connection to MCU specific GPT channel. Please refer to the hardware manual for which GPT channel is connected to the internal signal
Bit Clock Divider(available only in Master mode)	Refer to the RA Configuration tool for available options.	Audio Clock / 1	Select divider used to generate bit clock from audio clock.
Callback	Name must be a valid C symbol	NULL	A user callback function can be provided. If this callback function is provided, it will be called from all three interrupt service routines (ISR).
Transmit Interrupt Priority	MCU Specific Options		Select the transmit interrupt priority.
Receive Interrupt Priority	MCU Specific Options		Select the receive interrupt priority.
Idle/Error Interrupt Priority	MCU Specific Options		Select the Idle/Error interrupt priority.

Clock Configuration

The SSI peripheral runs on PCLKB. The PCLKB frequency can be configured on the Clocks tab of the RA Configuration editor. The SSI audio clock can optionally be supplied from an external source through the AUDIO_CLK pin in master mode.

Pin Configuration

The SSI uses the following pins:

• AUDIO_CLK (optional, master mode only): The AUDIO_CLK pin is used to supply the audio clock from an external source.
• SSIBCKn: Bit clock pin for channel n
• SSILRCKn/SSIFSn: Channel selection pin for channel n
• SSIRXD0: Reception pin for channel 0
• SSITXD0: Transmission pin for channel 0
• SSIDATA1: Transmission or reception pin for channel 1

Usage Notes

SSI Frames

An SSI frame is 2 samples worth of data. The frame boundary (end of previous frame, start of next frame) is on the falling edge of the SSILRCKn signal.

SSI Frame Diagram (8-bit word, 8-bit samples)

Note

If the word length is longer than the sample bit depth, padding bits (0) will be added after the sample.

Audio Data

Only uncompressed PCM data is supported.

Data arrays have the following size, alignment, and length based on the "Bit Depth" setting:

Bit Depth	Array Data Type	Required Alignment	Required Length (bytes)
8 Bits	8-bit integer	1 byte alignment	Multiple of 2
16 Bits	16-bit integer	2 byte alignment	Multiple of 4
18 Bits	32-bit integer, right justified	4 byte alignment	Multiple of 8
20 Bits	32-bit integer, right justified	4 byte alignment	Multiple of 8
22 Bits	32-bit integer, right justified	4 byte alignment	Multiple of 8
24 Bits	32-bit integer, right justified	4 byte alignment	Multiple of 8
32 Bits	32-bit integer	4 byte alignment	Multiple of 8

Note

The length of the array must be a multiple of 2 when the data type is the recommended data type. The 2 represents the frame size (left and right channel) of I2S communication. The SSIE peripheral does not support odd read/write lengths in I2S mode.

Audio Clock

The audio clock is only required for master mode.

Audio Clock Frequency

The bit clock frequency is the product of the sampling frequency and channels and bits per system word:

bit_clock (Hz) = sampling_frequency (Hz) * channels * system_word_bits

I2S data always has 2 channels.

For example, the bit clock for transmitting 2 channels of 16-bit data (using a 16-bit system word) at 44100 Hz would be:

44100 * 2 * 16 = 1,411,200 Hz

The audio clock frequency is used to generate the bit clock frequency. It must be a multiple of the bit clock frequency. Refer to the Bit Clock Divider configuration for divider options. The input audio clock frequency must be:

audio_clock (Hz) = desired_bit_clock (Hz) * bit_clock_divider

To get a bit clock of 1.4 MHz from an audio clock of 2.8 MHz, select the divider Audio Clock / 2.

Audio Clock Source

The audio clock source can come from:

• An external source input to the AUDIO_CLK pin
• An internal connection to the GPT timer output

Note

When using the internal GPT timer output, Pin Output Support must be Enabled, and GTIOCA Output Enabled must be True.

See the SSIE section in the MCU hardware manual for information about which GPT channel may be used.

Limitations

Developers should be aware of the following limitations when using the SSI:

• When using channel 1, full duplex communication is not possible. Only tranmission or reception is possible.
• SSI must go idle before changing the communication mode (between read only, write only, and full duplex)

Examples

Basic Example

This is a basic example of minimal use of the SSI in an application.

#define SSI_EXAMPLE_SAMPLES_TO_TRANSFER    (1024)
#define SSI_EXAMPLE_TONE_FREQUENCY_HZ      (800)
int16_t g_src[SSI_EXAMPLE_SAMPLES_TO_TRANSFER];
int16_t g_dest[SSI_EXAMPLE_SAMPLES_TO_TRANSFER];
void ssi_basic_example (void)
{
    fsp_err_t err = FSP_SUCCESS;

    /* Create a stereo sine wave. Using formula sample = sin(2 * pi * tone_frequency * t / sampling_frequency) */
    uint32_t freq = SSI_EXAMPLE_TONE_FREQUENCY_HZ;
    for (uint32_t t = 0; t < SSI_EXAMPLE_SAMPLES_TO_TRANSFER / 2; t += 1)
    {
        float input = (((float) (freq * t)) * (float) (M_TWOPI)) / SSI_EXAMPLE_AUDIO_SAMPLING_FREQUENCY_HZ;
        g_src[2 * t]     = (int16_t) ((INT16_MAX * sinf(input)));
        g_src[2 * t + 1] = (int16_t) ((INT16_MAX * sinf(input)));
    }


    /* Initialize the module. */
    err = R_SSI_Open(&g_i2s_ctrl, &g_i2s_cfg);


    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);


    /* Transfer data. */
    (void) R_SSI_WriteRead(&g_i2s_ctrl,
                           (uint8_t *) &g_src[0],
                           (uint8_t *) &g_dest[0],
                           SSI_EXAMPLE_SAMPLES_TO_TRANSFER * sizeof(int16_t));

}

Streaming Example

This is an example of using SSI to stream audio data. This application uses a double buffer to store PCM sine wave data. It starts transmitting in the main loop, then loads the next buffer if it is ready in the callback. If the next buffer is not ready, a flag is set in the callback so the application knows to restart transmission in the main loop.

This example also checks the return code of R_SSI_Write() because R_SSI_Write() can return an error if a transmit overflow occurs before the FIFO is reloaded. If a transmit overflow occurs before the FIFO is reloaded, the SSI will be stopped in the error interrupt, and it cannot be restarted until the I2S_EVENT_IDLE callback is received.

#define SSI_STREAMING_EXAMPLE_AUDIO_SAMPLING_FREQUENCY_HZ    (22050)
#define SSI_STREAMING_EXAMPLE_SAMPLES_PER_CHUNK              (1024)
#define SSI_STREAMING_EXAMPLE_TONE_FREQUENCY_HZ              (800)

int16_t       g_stream_src[2][SSI_EXAMPLE_SAMPLES_TO_TRANSFER];
uint32_t      g_buffer_index           = 0;
volatile bool g_send_data_in_main_loop = true;
volatile bool g_data_ready             = false;

/* Example callback called when SSI is ready for more data. */
void ssi_example_callback (i2s_callback_args_t * p_args)
{
    /* Reload the FIFO if we hit the transmit watermark or restart transmission if the SSI is idle because it was
     * stopped after a transmit FIFO overflow. */
    if ((I2S_EVENT_TX_EMPTY == p_args->event) || (I2S_EVENT_IDLE == p_args->event))
    {
        if (g_data_ready)
        {
            /* Reload FIFO and handle errors. */
            ssi_example_write();
        }
        else
        {
            /* Data was not ready yet, send it in the main loop. */
            g_send_data_in_main_loop = true;
        }
    }
}

/* Load the transmit FIFO and check for error conditions. */
void ssi_example_write (void)
{
    /* Transfer data. This call is non-blocking. */
    fsp_err_t err = R_SSI_Write(&g_i2s_ctrl,
                                (uint8_t *) &g_stream_src[g_buffer_index][0],
                                SSI_STREAMING_EXAMPLE_SAMPLES_PER_CHUNK * sizeof(int16_t));

    if (FSP_SUCCESS == err)
    {
        /* Switch the buffer after data is sent. */
        g_buffer_index = !g_buffer_index;

        /* Allow loop to calculate next buffer only if transmission was successful. */
        g_data_ready = false;
    }
    else
    {
        /* Getting here most likely means a transmit overflow occurred before the FIFO could be reloaded. The
         * application must wait until the SSI is idle, then restart transmission. In this example, the idle
         * callback transmits data or resets the flag g_send_data_in_main_loop. */
    }
}

/* Calculate samples. This example is just a sine wave. For this type of data, it would be better to calculate
 * one period and loop it. This example should be updated for the audio data used by the application. */
void ssi_example_calculate_samples (uint32_t buffer_index)
{
    static uint32_t t = 0U;

    /* Create a stereo sine wave. Using formula sample = sin(2 * pi * tone_frequency * t / sampling_frequency) */
    uint32_t freq = SSI_STREAMING_EXAMPLE_TONE_FREQUENCY_HZ;
    for (uint32_t i = 0; i < SSI_STREAMING_EXAMPLE_SAMPLES_PER_CHUNK / 2; i += 1)
    {
        float input = (((float) (freq * t)) * (float) M_TWOPI) / SSI_STREAMING_EXAMPLE_AUDIO_SAMPLING_FREQUENCY_HZ;
        t++;

        /* Store sample twice, once for left channel and once for right channel. */
        int16_t sample = (int16_t) ((INT16_MAX * sinf(input)));
        g_stream_src[buffer_index][2 * i]     = sample;
        g_stream_src[buffer_index][2 * i + 1] = sample;
    }

    /* Data is ready to be sent in the interrupt. */
    g_data_ready = true;
}

void ssi_streaming_example (void)
{
    fsp_err_t err = FSP_SUCCESS;

    /* Initialize the module. */
    err = R_SSI_Open(&g_i2s_ctrl, &g_i2s_cfg);

    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);

    while (true)
    {
        /* Prepare data in a buffer that is not currently used for transmission. */
        ssi_example_calculate_samples(g_buffer_index);

        /* Send data in main loop the first time, and if it was not ready in the interrupt. */
        if (g_send_data_in_main_loop)
        {
            /* Clear flag. */
            g_send_data_in_main_loop = false;

            /* Reload FIFO and handle errors. */
            ssi_example_write();
        }

        /* If the next buffer is ready, wait for the data to be sent in the interrupt. */
        while (g_data_ready)
        {
            /* Do nothing. */
        }
    }
}

Data Structures
struct	ssi_instance_ctrl_t
struct	ssi_extended_cfg_t

Enumerations
enum	ssi_audio_clock_t
enum	ssi_clock_div_t

---

Data Structure Documentation

ssi_instance_ctrl_t

struct ssi_instance_ctrl_t

Channel instance control block. DO NOT INITIALIZE. Initialization occurs when i2s_api_t::open is called.

ssi_extended_cfg_t

struct ssi_extended_cfg_t

SSI configuration extension. This extension is optional.

Data Fields
ssi_audio_clock_t	audio_clock	Audio clock source, default is SSI_AUDIO_CLOCK_EXTERNAL.
ssi_clock_div_t	bit_clock_div	Select bit clock division ratio.

Enumeration Type Documentation

ssi_audio_clock_t

enum ssi_audio_clock_t

Audio clock source.

Enumerator
SSI_AUDIO_CLOCK_EXTERNAL	Audio clock source is the AUDIO_CLK input pin.
SSI_AUDIO_CLOCK_INTERNAL	Audio clock source is internal connection to a MCU specific GPT channel output.

ssi_clock_div_t

enum ssi_clock_div_t

Bit clock division ratio. Bit clock frequency = audio clock frequency / bit clock division ratio.

Enumerator
SSI_CLOCK_DIV_1	Clock divisor 1.
SSI_CLOCK_DIV_2	Clock divisor 2.
SSI_CLOCK_DIV_4	Clock divisor 4.
SSI_CLOCK_DIV_6	Clock divisor 6.
SSI_CLOCK_DIV_8	Clock divisor 8.
SSI_CLOCK_DIV_12	Clock divisor 12.
SSI_CLOCK_DIV_16	Clock divisor 16.
SSI_CLOCK_DIV_24	Clock divisor 24.
SSI_CLOCK_DIV_32	Clock divisor 32.
SSI_CLOCK_DIV_48	Clock divisor 48.
SSI_CLOCK_DIV_64	Clock divisor 64.
SSI_CLOCK_DIV_96	Clock divisor 96.
SSI_CLOCK_DIV_128	Clock divisor 128.

Function Documentation

R_SSI_Open()

fsp_err_t R_SSI_Open	(	i2s_ctrl_t *const	p_ctrl,
		i2s_cfg_t const *const	p_cfg
	)

Opens the SSI. Implements i2s_api_t::open.

This function sets this clock divisor and the configurations specified in i2s_cfg_t. It also opens the timer and transfer instances if they are provided.

Return values

FSP_SUCCESS	Ready for I2S communication.
FSP_ERR_ASSERTION	The pointer to p_ctrl or p_cfg is null.
FSP_ERR_ALREADY_OPEN	The control block has already been opened.
FSP_ERR_IP_CHANNEL_NOT_PRESENT	Channel number is not available on this MCU.

Returns

See Common Error Codes or functions called by this function for other possible return codes. This function calls:

• transfer_api_t::open

R_SSI_Write()

fsp_err_t R_SSI_Write	(	i2s_ctrl_t *const	p_ctrl,
		void const *const	p_src,
		uint32_t const	bytes
	)

Writes data buffer to SSI. Implements i2s_api_t::write.

This function resets the transfer if the transfer interface is used, or writes the length of data that fits in the FIFO then stores the remaining write buffer in the control block to be written in the ISR.

Write() cannot be called if another write(), read() or writeRead() operation is in progress. Write can be called when the SSI is idle, or after the I2S_EVENT_TX_EMPTY event.

Return values

FSP_SUCCESS	Write initiated successfully.
FSP_ERR_ASSERTION	The pointer to p_ctrl or p_src was null, or bytes requested was 0.
FSP_ERR_IN_USE	Another transfer is in progress, data was not written.
FSP_ERR_NOT_OPEN	The channel is not opened.
FSP_ERR_UNDERFLOW	A transmit underflow error is pending. Wait for the SSI to go idle before resuming communication.

Returns

See Common Error Codes or functions called by this function for other possible return codes. This function calls:

• transfer_api_t::reset

R_SSI_Read()

fsp_err_t R_SSI_Read	(	i2s_ctrl_t *const	p_ctrl,
		void *const	p_dest,
		uint32_t const	bytes
	)

Reads data into provided buffer. Implements i2s_api_t::read.

This function resets the transfer if the transfer interface is used, or reads the length of data available in the FIFO then stores the remaining read buffer in the control block to be filled in the ISR.

Read() cannot be called if another write(), read() or writeRead() operation is in progress. Read can be called when the SSI is idle, or after the I2S_EVENT_RX_FULL event.

Return values

FSP_SUCCESS	Read initiated successfully.
FSP_ERR_IN_USE	Peripheral is in the wrong mode or not idle.
FSP_ERR_ASSERTION	The pointer to p_ctrl or p_dest was null, or bytes requested was 0.
FSP_ERR_NOT_OPEN	The channel is not opened.
FSP_ERR_OVERFLOW	A receive overflow error is pending. Wait for the SSI to go idle before resuming communication.

Returns

See Common Error Codes or functions called by this function for other possible return codes. This function calls:

• transfer_api_t::reset

R_SSI_WriteRead()

fsp_err_t R_SSI_WriteRead	(	i2s_ctrl_t *const	p_ctrl,
		void const *const	p_src,
		void *const	p_dest,
		uint32_t const	bytes
	)

Writes from source buffer and reads data into destination buffer. Implements i2s_api_t::writeRead.

This function calls R_SSI_Write and R_SSI_Read.

writeRead() cannot be called if another write(), read() or writeRead() operation is in progress. writeRead() can be called when the SSI is idle, or after the I2S_EVENT_RX_FULL event.

Return values

FSP_SUCCESS	Write and read initiated successfully.
FSP_ERR_IN_USE	Peripheral is in the wrong mode or not idle.
FSP_ERR_ASSERTION	An input parameter was invalid.
FSP_ERR_NOT_OPEN	The channel is not opened.
FSP_ERR_UNDERFLOW	A transmit underflow error is pending. Wait for the SSI to go idle before resuming communication.
FSP_ERR_OVERFLOW	A receive overflow error is pending. Wait for the SSI to go idle before resuming communication.

Returns

See Common Error Codes or functions called by this function for other possible return codes. This function calls:

• transfer_api_t::reset

R_SSI_Stop()

fsp_err_t R_SSI_Stop

(

i2s_ctrl_t *const

p_ctrl

)

Stops SSI. Implements i2s_api_t::stop.

This function disables both transmission and reception, and disables any transfer instances used.

The SSI will stop on the next frame boundary. Do not restart SSI until it is idle.

Return values

FSP_SUCCESS	I2S communication stop request issued.
FSP_ERR_ASSERTION	The pointer to p_ctrl was null.
FSP_ERR_NOT_OPEN	The channel is not opened.

Returns

See Common Error Codes or lower level drivers for other possible return codes.

R_SSI_Mute()

fsp_err_t R_SSI_Mute	(	i2s_ctrl_t *const	p_ctrl,
		i2s_mute_t const	mute_enable
	)

Mutes SSI on the next frame boundary. Implements i2s_api_t::mute.

Data is still written while mute is enabled, but the transmit line outputs zeros.

Return values

FSP_SUCCESS	Transmission is muted.
FSP_ERR_ASSERTION	The pointer to p_ctrl was null.
FSP_ERR_NOT_OPEN	The channel is not opened.

R_SSI_StatusGet()

fsp_err_t R_SSI_StatusGet	(	i2s_ctrl_t *const	p_ctrl,
		i2s_status_t *const	p_status
	)

Gets SSI status and stores it in provided pointer p_status. Implements i2s_api_t::statusGet.

Return values

FSP_SUCCESS	Information stored successfully.
FSP_ERR_ASSERTION	The p_instance_ctrl or p_status parameter was null.
FSP_ERR_NOT_OPEN	The channel is not opened.

R_SSI_Close()

fsp_err_t R_SSI_Close

(

i2s_ctrl_t *const

p_ctrl

)

Closes SSI. Implements i2s_api_t::close.

This function powers down the SSI and closes the lower level timer and transfer drivers if they are used.

Return values

FSP_SUCCESS	Device closed successfully.
FSP_ERR_ASSERTION	The pointer to p_ctrl was null.
FSP_ERR_NOT_OPEN	The channel is not opened.

R_SSI_CallbackSet()

fsp_err_t R_SSI_CallbackSet	(	i2s_ctrl_t *const	p_api_ctrl,
		void(*)(i2s_callback_args_t *)	p_callback,
		void const *const	p_context,
		i2s_callback_args_t *const	p_callback_memory
	)

Updates the user callback and has option of providing memory for callback structure. Implements i2s_api_t::callbackSet

Return values

FSP_SUCCESS	Callback updated successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.
FSP_ERR_NO_CALLBACK_MEMORY	p_callback is non-secure and p_callback_memory is either secure or NULL.