I2S (Inter-IC Sound)

General Description

High level interface for interacting with the Inter-IC Sound (I2S).

The I2S protocol is a asynchronous serial interface protocol. This driver supports both transmit and receive modes of operation. The communication frequency, sample rate, word size, and channel size can all be configured.

Note

Certain platforms may not support all of the functionality and configuration options provided by this driver. Please refer to implementation specific documentation for details on available options.

Features

• Transmit and receive functionality
• Configurable data rates
• Configurable channel and word size
• Configurable interrupt and callback assignment from I2S events - cyhal_i2s_event_t

Quick Start

Initialize an I2S instance using the cyhal_i2s_init and provide the transmit (tx) and/or receive (rx) pins. Call cyhal_i2s_start_tx and/or cyhal_i2s_start_rx to enable transmit and/or receive functionality as desired.
See Snippet 1: I2S Initialization and Configuration for example initialization as transmit or receive.

Note

The clock parameter (const cyhal_clock_t *clk) is optional and can be set to NULL to generate and use an available clock resource with a default frequency.

The sclk frequency is determined as sclk = sample_rate_hz * channel_length * 2 (multiplying by 2 for 2 channels - left and right). The input clock must be a multiple of this sclk frequency; see the implementation specific documentation for the supported multipliers.

It is possible to use either only TX functionality, only RX functionality, or both RX and TX functionality at the same time. If RX and TX are both in use, the same sample rate, channel length, word length, sclk frequency will be used for both.

Code Snippets

Snippet 1: I2S Initialization and Configuration

This snippet initializes an I2S resource for transmit or receive and assigns the pins.

Initializing as I2S transmitter

    #if defined(CYHAL_DRIVER_AVAILABLE_I2S_TX)
    cyhal_i2s_t        i2s;
    cyhal_i2s_pins_t   tx_pins = { .sck = P5_1, .ws = P5_2, .data = P5_3, .mclk = NC };
    cyhal_i2s_config_t config  =
    {
        .is_tx_slave    = false,
        .is_rx_slave    = false,
        .mclk_hz        = 0,
        .channel_length = 32,
        .word_length    = 32,
        .sample_rate_hz = 44000
    };
    cy_rslt_t result = cyhal_i2s_init(&i2s, &tx_pins, NULL, &config, NULL);
    if (CY_RSLT_SUCCESS != result)
    {
        // Handle error
    }
    #endif // if defined(CYHAL_DRIVER_AVAILABLE_I2S_TX)

Initializing as I2S receiver

    #if defined(CYHAL_DRIVER_AVAILABLE_I2S_RX)
    cyhal_i2s_t        i2s;
    cyhal_i2s_pins_t   rx_pins = { .sck = P5_4, .ws = P5_5, .data = P5_6, .mclk = NC };
    cyhal_i2s_config_t config  =
    {
        .is_tx_slave    = false,
        .is_rx_slave    = true,
        .mclk_hz        = 0,
        .channel_length = 32,
        .word_length    = 32,
        .sample_rate_hz = 44000
    };
    cy_rslt_t result = cyhal_i2s_init(&i2s, NULL, &rx_pins, &config, NULL);
    if (CY_RSLT_SUCCESS != result)
    {
        // Handle error
    }
    #endif // if defined(CYHAL_DRIVER_AVAILABLE_I2S_RX)

Snippet 2: I2S Transmit One-shot

This snippet shows how to transmit data using cyhal_i2s_write_async when the entire sample is available at once.

#if defined(CYHAL_DRIVER_AVAILABLE_I2S_TX)
static void i2s_event_handler_transmit_one_shot(void* arg, cyhal_i2s_event_t event)
{
    // When we registered the callback, we set 'arg' to point to the i2s object
    cyhal_i2s_t* i2s = (cyhal_i2s_t*)arg;
    if (0u != (event & CYHAL_I2S_TX_EMPTY))
    {
        cyhal_i2s_stop_tx(i2s);
    }
}
 
 
// Data to transmit, defined e.g. an array stored in flash
extern const uint32_t* i2s_tx_buffer;
extern const size_t    i2s_tx_buffer_len;
cy_rslt_t snippet_cyhal_i2s_async_transmit_one_shot(void)
{
    cyhal_i2s_t i2s;
    // Initialize the object as shown in Snippet 1
 
    // Register a callback and set the callback argument to be a pointer to the I2S object, so that
    // we can easily reference it from the callback handler.
    cyhal_i2s_register_callback(&i2s, &i2s_event_handler_transmit_one_shot, &i2s);
 
    // Subscribe to the TX Empty event so that we can stop the interface when the transfer is
    // complete
    cyhal_i2s_enable_event(&i2s, CYHAL_I2S_TX_EMPTY, CYHAL_ISR_PRIORITY_DEFAULT, true);
 
    cy_rslt_t result = cyhal_i2s_write_async(&i2s, i2s_tx_buffer, i2s_tx_buffer_len);
 
    if (CY_RSLT_SUCCESS == result)
    {
        result = cyhal_i2s_start_tx(&i2s);
    }
 
    return result;
}
 
 
#endif // if defined(CYHAL_DRIVER_AVAILABLE_I2S_TX)

Snippet 3: I2S Transmit Streaming

This snippet shows how to transmit data using cyhal_i2s_write_async when sample data is being continuously loaded and transmitted (e.g. streaming over the network).

#if defined(CYHAL_DRIVER_AVAILABLE_I2S_TX)
// We use a dual buffer system so that one buffer can be transmitting while the other is being
// filled
#define BUFFER_SIZE 128u
const uint32_t  tx_buffer0[BUFFER_SIZE];
const uint32_t  tx_buffer1[BUFFER_SIZE];
const uint32_t* active_tx_buffer;
const uint32_t* next_tx_buffer;
static void i2s_event_handler_transmit_streaming(void* arg, cyhal_i2s_event_t event)
{
    // When we registered the callback, we set 'arg' to point to the i2s object
    cyhal_i2s_t* i2s = (cyhal_i2s_t*)arg;
    if (0u != (event & CYHAL_I2S_ASYNC_TX_COMPLETE))
    {
        // Flip the active and the next tx buffers
        const uint32_t* temp = active_tx_buffer;
        active_tx_buffer = next_tx_buffer;
        next_tx_buffer   = temp;
 
        // Start writing the next buffer while the just-freed one is repopulated
        cy_rslt_t result = cyhal_i2s_write_async(i2s, active_tx_buffer, BUFFER_SIZE);
 
        if (CY_RSLT_SUCCESS == result)
        {
            // Load the next set of data into next_tx_buffer
        }
    }
}
 
 
cy_rslt_t snippet_cyhal_i2s_async_transmit_streaming(void)
{
    cyhal_i2s_t i2s;
    // Initialize the object as shown in Snippet 1
 
    // Register a callback and set the callback argument to be a pointer to the I2S object, so that
    // we can easily reference it from the callback handler.
    cyhal_i2s_register_callback(&i2s, &i2s_event_handler_transmit_streaming, &i2s);
 
    // Subscribe to the async complete event so that we can queue up another transfer when this one
    // completes
    cyhal_i2s_enable_event(&i2s, CYHAL_I2S_ASYNC_TX_COMPLETE, CYHAL_ISR_PRIORITY_DEFAULT, true);
 
    // Configure asynchronous transfers to use DMA to free up the CPU during transfers
    cy_rslt_t result = cyhal_i2s_set_async_mode(&i2s, CYHAL_ASYNC_DMA, CYHAL_DMA_PRIORITY_DEFAULT);
 
    if (CY_RSLT_SUCCESS == result)
    {
        // Populate initial data in the two tx buffers (e.g. by streaming over the network)
 
        active_tx_buffer = tx_buffer0;
        next_tx_buffer   = tx_buffer1;
 
        result = cyhal_i2s_write_async(&i2s, active_tx_buffer, BUFFER_SIZE);
    }
 
    if (CY_RSLT_SUCCESS == result)
    {
        result = cyhal_i2s_start_tx(&i2s);
    }
 
    return result;
}
 
 
#endif // if defined(CYHAL_DRIVER_AVAILABLE_I2S_TX)

Snippet 4: I2S Receive

This snippet shows how to receive data using cyhal_i2s_read_async.

#if defined(CYHAL_DRIVER_AVAILABLE_I2S_RX)
// We use a dual buffer system so that one buffer can be filling while the other is being processed
#define BUFFER_SIZE 128u
uint32_t  rx_buffer0[BUFFER_SIZE];
uint32_t  rx_buffer1[BUFFER_SIZE];
uint32_t* active_rx_buffer;
uint32_t* full_rx_buffer;
static void i2s_event_handler_receive(void* arg, cyhal_i2s_event_t event)
{
    // When we registered the callback, we set 'arg' to point to the i2s object
    cyhal_i2s_t* i2s = (cyhal_i2s_t*)arg;
    if (0u != (event & CYHAL_I2S_ASYNC_RX_COMPLETE))
    {
        // Flip the active and the next rx buffers
        uint32_t* temp = active_rx_buffer;
        active_rx_buffer = full_rx_buffer;
        full_rx_buffer   = temp;
 
        // Start reading into the next buffer while the just-filled one is being processed
        cy_rslt_t result = cyhal_i2s_read_async(i2s, active_rx_buffer, BUFFER_SIZE);
 
        if (CY_RSLT_SUCCESS == result)
        {
            // Process the data in the full_rx_buffer
        }
    }
}
 
 
cy_rslt_t snippet_cyhal_i2s_async_receive(void)
{
    cyhal_i2s_t i2s;
    // Initialize the object as shown in Snippet 1
 
    // Register a callback and set the callback argument to be a pointer to the I2S object, so that
    // we can easily reference it from the callback handler.
    cyhal_i2s_register_callback(&i2s, &i2s_event_handler_receive, &i2s);
 
    // Subscribe to the async complete event so that we can queue up another transfer when this one
    // completes
    cyhal_i2s_enable_event(&i2s, CYHAL_I2S_ASYNC_RX_COMPLETE, CYHAL_ISR_PRIORITY_DEFAULT, true);
 
    // Configure asynchronous transfers to use DMA to free up the CPU during transfers
    cy_rslt_t result = cyhal_i2s_set_async_mode(&i2s, CYHAL_ASYNC_DMA, CYHAL_DMA_PRIORITY_DEFAULT);
 
    if (CY_RSLT_SUCCESS == result)
    {
        active_rx_buffer = rx_buffer0;
        full_rx_buffer   = rx_buffer1;
        result           = cyhal_i2s_read_async(&i2s, active_rx_buffer, BUFFER_SIZE);
    }
 
    if (CY_RSLT_SUCCESS == result)
    {
        result = cyhal_i2s_start_rx(&i2s);
    }
 
    return result;
}
 
 
#endif // if defined(CYHAL_DRIVER_AVAILABLE_I2S_RX)

More Information

Code examples (Github)

• PSoC™ 6 MCU: Inter-IC Sound (I2S)
• PSoC™ 6 MCU: PDM to I2S

API Reference
	I2S HAL Results
	I2S specific return codes.

Data Structures
struct	cyhal_i2s_pins_t
	Pins to use for one I2S direction. More...
struct	cyhal_i2s_config_t
	I2S Configuration. More...

Typedefs
typedef void(*	cyhal_i2s_event_callback_t) (void *callback_arg, cyhal_i2s_event_t event)
	Handler for I2S event callbacks.

Enumerations
enum	cyhal_i2s_event_t {   CYHAL_I2S_TX_NOT_FULL = 1 << 0 ,   CYHAL_I2S_TX_HALF_EMPTY = 1 << 1 ,   CYHAL_I2S_TX_EMPTY = 1 << 2 ,   CYHAL_I2S_TX_OVERFLOW = 1 << 3 ,   CYHAL_I2S_TX_UNDERFLOW = 1 << 4 ,   CYHAL_I2S_ASYNC_TX_COMPLETE = 1 << 5 ,   CYHAL_I2S_RX_NOT_EMPTY = 1 << 6 ,   CYHAL_I2S_RX_HALF_FULL = 1 << 7 ,   CYHAL_I2S_RX_FULL = 1 << 8 ,   CYHAL_I2S_RX_OVERFLOW = 1 << 9 ,   CYHAL_I2S_RX_UNDERFLOW = 1 << 10 ,   CYHAL_I2S_ASYNC_RX_COMPLETE = 1 << 11 }
	I2S events. More...
enum	cyhal_i2s_output_t {   CYHAL_I2S_TRIGGER_RX_HALF_FULL ,   CYHAL_I2S_TRIGGER_TX_HALF_EMPTY }
	Selections for I2S output signals More...

Functions
cy_rslt_t	cyhal_i2s_init (cyhal_i2s_t *obj, const cyhal_i2s_pins_t *tx_pins, const cyhal_i2s_pins_t *rx_pins, const cyhal_i2s_config_t *config, cyhal_clock_t *clk)
	Initialize the I2S peripheral. More...
cy_rslt_t	cyhal_i2s_init_cfg (cyhal_i2s_t *obj, const cyhal_i2s_configurator_t *cfg)
	Initialize the I2S peripheral using a configurator generated configuration struct. More...
void	cyhal_i2s_free (cyhal_i2s_t *obj)
	Deinitialize the i2s object. More...
cy_rslt_t	cyhal_i2s_set_sample_rate (cyhal_i2s_t *obj, uint32_t sample_rate_hz)
	Set the I2S sample rate. More...
cy_rslt_t	cyhal_i2s_start_tx (cyhal_i2s_t *obj)
	Starts transmitting data. More...
cy_rslt_t	cyhal_i2s_stop_tx (cyhal_i2s_t *obj)
	Stops transmitting data. More...
cy_rslt_t	cyhal_i2s_clear_tx (cyhal_i2s_t *obj)
	Clears the tx hardware buffer. More...
cy_rslt_t	cyhal_i2s_start_rx (cyhal_i2s_t *obj)
	Starts receiving data. More...
cy_rslt_t	cyhal_i2s_stop_rx (cyhal_i2s_t *obj)
	Stops receiving data. More...
cy_rslt_t	cyhal_i2s_clear_rx (cyhal_i2s_t *obj)
	Clears the rx hardware buffer. More...
cy_rslt_t	cyhal_i2s_read (cyhal_i2s_t *obj, void *data, size_t *length)
	Read data synchronously. More...
cy_rslt_t	cyhal_i2s_write (cyhal_i2s_t *obj, const void *data, size_t *length)
	Send data synchronously. More...
bool	cyhal_i2s_is_tx_enabled (cyhal_i2s_t *obj)
	Checks if the transmit functionality is enabled for the specified I2S peripheral (regardless of whether data is currently queued for transmission). More...
bool	cyhal_i2s_is_tx_busy (cyhal_i2s_t *obj)
	Checks if the specified I2S peripheral is transmitting data, including if a pending async transfer is waiting to write more data to the transmit buffer. More...
bool	cyhal_i2s_is_rx_enabled (cyhal_i2s_t *obj)
	Checks if the receive functionality is enabled for the specified I2S peripheral (regardless of whether any unread data has been received). More...
bool	cyhal_i2s_is_rx_busy (cyhal_i2s_t *obj)
	Checks if the specified I2S peripheral has received data that has not yet been read out of the hardware buffer. More...
cy_rslt_t	cyhal_i2s_read_async (cyhal_i2s_t *obj, void *rx, size_t rx_length)
	Start I2S asynchronous read. More...
cy_rslt_t	cyhal_i2s_write_async (cyhal_i2s_t *obj, const void *tx, size_t tx_length)
	Start I2S asynchronous write. More...
cy_rslt_t	cyhal_i2s_set_async_mode (cyhal_i2s_t *obj, cyhal_async_mode_t mode, uint8_t dma_priority)
	Set the mechanism that is used to perform I2S asynchronous transfers. More...
bool	cyhal_i2s_is_read_pending (cyhal_i2s_t *obj)
	Checks if the specified I2S peripheral is in the process of reading data from the hardware buffer into RAM. More...
bool	cyhal_i2s_is_write_pending (cyhal_i2s_t *obj)
	Checks if the specified I2S peripheral is in the process of writing data into the hardware buffer. More...
cy_rslt_t	cyhal_i2s_abort_read_async (cyhal_i2s_t *obj)
	Abort I2S asynchronous read. More...
cy_rslt_t	cyhal_i2s_abort_write_async (cyhal_i2s_t *obj)
	Abort I2S asynchronous write. More...
void	cyhal_i2s_register_callback (cyhal_i2s_t *obj, cyhal_i2s_event_callback_t callback, void *callback_arg)
	Register an I2S callback handler. More...
void	cyhal_i2s_enable_event (cyhal_i2s_t *obj, cyhal_i2s_event_t event, uint8_t intr_priority, bool enable)
	Configure I2S events. More...
cy_rslt_t	cyhal_i2s_enable_output (cyhal_i2s_t *obj, cyhal_i2s_output_t output, cyhal_source_t *source)
	Enables the specified output signal. More...
cy_rslt_t	cyhal_i2s_disable_output (cyhal_i2s_t *obj, cyhal_i2s_output_t output)
	Disables the specified output signal. More...

---

Data Structure Documentation

cyhal_i2s_pins_t

struct cyhal_i2s_pins_t

Data Fields
cyhal_gpio_t	sck	Clock pin.
cyhal_gpio_t	ws	Word select.
cyhal_gpio_t	data	Data pin (sdo or sdi)
cyhal_gpio_t	mclk	Mclk input pin. Set to NC if an internal clock source should be used.

cyhal_i2s_config_t

struct cyhal_i2s_config_t

Data Fields
bool	is_tx_slave	Configure TX to operate a slave (true) or master (false)
bool	is_rx_slave	Configure RX to operate a slave (true) or master (false)
uint32_t	mclk_hz	Frequency, in hertz, of the master clock if it is provided by an external pin. If at least one mclk pin is not NC, this must be nonzero. If both mclk pins are NC, this must be zero.
uint8_t	channel_length	Number of bits in each channel. See the implementation specific documentation for supported values.
uint8_t	word_length	Number of bits in each word. Must be less than or equal to channel_length. If word_length < channel_length, the excess bits will be padded with 0's.
uint32_t	sample_rate_hz	Sample rate in Hz.

Enumeration Type Documentation

cyhal_i2s_event_t

enum cyhal_i2s_event_t

I2S events.

Enumerator
CYHAL_I2S_TX_NOT_FULL	TX HW Buffer is not full.
CYHAL_I2S_TX_HALF_EMPTY	TX HW Buffer is half empty.
CYHAL_I2S_TX_EMPTY	TX HW Buffer is Empty.
CYHAL_I2S_TX_OVERFLOW	Attempt to write when TX HW Buffer is full.
CYHAL_I2S_TX_UNDERFLOW	Interface ready to transfer data but HW TX buffer is empty.
CYHAL_I2S_ASYNC_TX_COMPLETE	Pending async transmit is complete (but the HW buffer may still contain unsent data)
CYHAL_I2S_RX_NOT_EMPTY	RX HW Buffer is not Empty.
CYHAL_I2S_RX_HALF_FULL	RX HW Buffer is half full.
CYHAL_I2S_RX_FULL	RX HW Buffer is FULL.
CYHAL_I2S_RX_OVERFLOW	Attempt to write when RX HW Buffer is full.
CYHAL_I2S_RX_UNDERFLOW	Attempt to read when HW RX buffer is empty.
CYHAL_I2S_ASYNC_RX_COMPLETE	Pending async receive is complete.

cyhal_i2s_output_t

enum cyhal_i2s_output_t

Selections for I2S output signals

Enumerator
CYHAL_I2S_TRIGGER_RX_HALF_FULL	An output signal should be triggered when the receive buffer is half full.
CYHAL_I2S_TRIGGER_TX_HALF_EMPTY	An output signal should be triggered when the transmit buffer is half empty.

Function Documentation

cyhal_i2s_init()

cy_rslt_t cyhal_i2s_init	(	cyhal_i2s_t *	obj,
		const cyhal_i2s_pins_t *	tx_pins,
		const cyhal_i2s_pins_t *	rx_pins,
		const cyhal_i2s_config_t *	config,
		cyhal_clock_t *	clk
	)

Initialize the I2S peripheral.

It sets the default parameters for I2S peripheral, and configures its specifieds pins. If only one direction is to be used, then the pins for the other direction need not be specified (i.e. they may be set to NC). For example, if only RX is needed, tx_sck, tx_ws, and tx_sdo may all be set to NC. If one pin is specified for a direction, all pins for that direction must be specified.

Parameters

[out]	obj	Pointer to an I2S object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]	tx_pins	Pins for I2S transmit. If NULL, transmit functionality will be disabled.
[in]	rx_pins	Pins for I2S receive. If NULL, receive functionality will be disabled.
[in]	config	Initial block configuration
[in]	clk	Clock source to use for this instance. If NULL, a dedicated clock divider will be allocated for this instance.

Returns

The status of the init request

cyhal_i2s_init_cfg()

cy_rslt_t cyhal_i2s_init_cfg	(	cyhal_i2s_t *	obj,
		const cyhal_i2s_configurator_t *	cfg
	)

Initialize the I2S peripheral using a configurator generated configuration struct.

Parameters

[out]	obj	Pointer to a I2S object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]	cfg	Configuration structure generated by a configurator.

Returns

The status of the init request

cyhal_i2s_free()

void cyhal_i2s_free

(

cyhal_i2s_t *

obj

)

Deinitialize the i2s object.

Parameters

[in,out]

obj

The i2s object

cyhal_i2s_set_sample_rate()

cy_rslt_t cyhal_i2s_set_sample_rate	(	cyhal_i2s_t *	obj,
		uint32_t	sample_rate_hz
	)

Set the I2S sample rate.

Parameters

[in]	obj	The I2S object
[in]	sample_rate_hz	Sample rate in Hz

Returns

The status of the set sample rate request

cyhal_i2s_start_tx()

cy_rslt_t cyhal_i2s_start_tx

(

cyhal_i2s_t *

obj

)

Starts transmitting data.

Transmission will continue until it is stopped by calling cyhal_i2s_stop_tx.

Parameters

[in]

obj

The I2S object

Returns

The status of the start request.

cyhal_i2s_stop_tx()

cy_rslt_t cyhal_i2s_stop_tx

(

cyhal_i2s_t *

obj

)

Stops transmitting data.

This immediately terminates transmission.

Parameters

[in]

obj

The I2S object

Returns

The status of the stop request.

cyhal_i2s_clear_tx()

cy_rslt_t cyhal_i2s_clear_tx

(

cyhal_i2s_t *

obj

)

Clears the tx hardware buffer.

Parameters

[in]

obj

The i2s peripheral

Returns

The status of the clear request

cyhal_i2s_start_rx()

cy_rslt_t cyhal_i2s_start_rx

(

cyhal_i2s_t *

obj

)

Starts receiving data.

Data will continue to be received until it is stopped by calling cyhal_i2s_stop_rx.

Parameters

[in]

obj

The I2S object

Returns

The status of the start request.

cyhal_i2s_stop_rx()

cy_rslt_t cyhal_i2s_stop_rx

(

cyhal_i2s_t *

obj

)

Stops receiving data.

This immediately terminates data receipt.

Parameters

[in]

obj

The I2S object

Returns

The status of the stop request.

cyhal_i2s_clear_rx()

cy_rslt_t cyhal_i2s_clear_rx

(

cyhal_i2s_t *

obj

)

Clears the rx hardware buffer.

Parameters

[in]

obj

The i2s peripheral

Returns

The status of the clear request

cyhal_i2s_read()

cy_rslt_t cyhal_i2s_read	(	cyhal_i2s_t *	obj,
		void *	data,
		size_t *	length
	)

Read data synchronously.

This will read the number of words specified by the length parameter, or the number of words that are currently available in the receive buffer, whichever is less, then return. The value pointed to by length will be updated to reflect the number of words that were actually read.

Parameters

[in]	obj	The I2S object
[out]	data	The buffer for receiving
[in,out]	length	Number of words to (as configured in cyhal_i2s_config_t.word_length) read, updated with the number actually read

Returns

The status of the read request

Note

Each word will be aligned to the next largest power of 2. For example, if the word length is 16 bits, each word will consume two bytes. But if the word length is 20, each word will consume 32 bytes.

Returns

The status of the read request

cyhal_i2s_write()

cy_rslt_t cyhal_i2s_write	(	cyhal_i2s_t *	obj,
		const void *	data,
		size_t *	length
	)

Send data synchronously.

This will write either length words or until the write buffer is full, whichever is less, then return. The value pointed to by length will be updated to reflect the number of words that were actually written.

Note

This function only queues data into the write buffer; it does not block until the data has all been sent out over the wire.

Parameters

[in]	obj	The I2S object
[in]	data	The buffer for sending
[in,out]	length	Number of words to write (as configured in cyhal_i2s_config_t.word_length, updated with the number actually written

Returns

The status of the write request

Note

Each word will be aligned to the next largest power of 2. For example, if the word length is 16 bits, each word will consume two bytes. But if the word length is 20, each word will consume 32 bytes.

cyhal_i2s_is_tx_enabled()

bool cyhal_i2s_is_tx_enabled

(

cyhal_i2s_t *

obj

)

Checks if the transmit functionality is enabled for the specified I2S peripheral (regardless of whether data is currently queued for transmission).

The transmit functionality can be enabled by calling cyhal_i2s_start_tx and disabled by calling cyhal_i2s_stop_tx

Parameters

[in]

obj

The I2S peripheral to check

Returns

Whether the I2S transmit function is enabled.

cyhal_i2s_is_tx_busy()

bool cyhal_i2s_is_tx_busy

(

cyhal_i2s_t *

obj

)

Checks if the specified I2S peripheral is transmitting data, including if a pending async transfer is waiting to write more data to the transmit buffer.

Parameters

[in]

obj

The I2S peripheral to check

Returns

Whether the I2S is still transmitting

cyhal_i2s_is_rx_enabled()

bool cyhal_i2s_is_rx_enabled

(

cyhal_i2s_t *

obj

)

Checks if the receive functionality is enabled for the specified I2S peripheral (regardless of whether any unread data has been received).

The receive functionality can be enabled by calling cyhal_i2s_start_rx and disabled by calling cyhal_i2s_stop_rx

Parameters

[in]

obj

The I2S peripheral to check

Returns

Whether the I2S receive function is enabled.

cyhal_i2s_is_rx_busy()

bool cyhal_i2s_is_rx_busy

(

cyhal_i2s_t *

obj

)

Checks if the specified I2S peripheral has received data that has not yet been read out of the hardware buffer.

This includes if an async read transfer is pending.

Parameters

[in]

obj

The I2S peripheral to check

Returns

Whether the I2S is still transmitting

cyhal_i2s_read_async()

cy_rslt_t cyhal_i2s_read_async	(	cyhal_i2s_t *	obj,
		void *	rx,
		size_t	rx_length
	)

Start I2S asynchronous read.

This will transfer rx_length words into the buffer pointed to by rx in the background. When the requested quantity of data has been read, the CYHAL_I2S_ASYNC_RX_COMPLETE event will be raised. See cyhal_i2s_register_callback and cyhal_i2s_enable_event.

cyhal_i2s_set_async_mode can be used to control whether this uses DMA or a CPU-driven transfer.

Note

If D-cache is enabled, cyhal_i2s_set_async_mode is DMA and data Cache line is 32 bytes, the user needs to make sure that the rx pointer passed to the cyhal_i2s_read_async function points to a 32 byte aligned array of words that contains the buffer data. The size of buffer data must be a multiple of 32 bytes to ensure cache coherency. CY_ALIGN(__SCB_DCACHE_LINE_SIZE) macro can be used for 32 byte alignment.

Refer to DCACHE_Management for more information.

Note

Each word will be aligned to the next largest power of 2. For example, if the word length is 16 bits, each word will consume two bytes. But if the word length is 20, each word will consume 32 bytes.

Parameters

[in]	obj	The I2S object
[out]	rx	The receive buffer.
[in]	rx_length	Number of words (as configured in cyhal_i2s_config_t.word_length) to read.

Returns

The status of the read_async request

cyhal_i2s_write_async()

cy_rslt_t cyhal_i2s_write_async	(	cyhal_i2s_t *	obj,
		const void *	tx,
		size_t	tx_length
	)

Start I2S asynchronous write.

This will transfer tx_length words into the tx buffer in the background. When the requested quantity of data has been queued in the transmit buffer, the CYHAL_I2S_ASYNC_TX_COMPLETE event will be raised. See cyhal_i2s_register_callback and cyhal_i2s_enable_event.

cyhal_i2s_set_async_mode can be used to control whether this uses DMA or a SW (CPU-driven) transfer.

Note

If D-cache is enabled, cyhal_i2s_set_async_mode is DMA and data Cache line is 32 bytes, the user needs to make sure that the tx pointer passed to the cyhal_i2s_write_async function points to a 32 byte aligned array of words that contains the buffer data. The size of buffer data must be a multiple of 32 bytes to ensure cache coherency. CY_ALIGN(__SCB_DCACHE_LINE_SIZE) macro can be used for 32 byte alignment.

Refer to DCACHE_Management for more information.

Note

Each word will be aligned to the next largest power of 2. For example, if the word length is 16 bits, each word will consume two bytes. But if the word length is 20, each word will consume 32 bytes.

Parameters

[in]	obj	The I2S object
[in]	tx	The transmit buffer.
[in]	tx_length	The number of words to transmit.

Returns

The status of the transfer_async request

cyhal_i2s_set_async_mode()

cy_rslt_t cyhal_i2s_set_async_mode	(	cyhal_i2s_t *	obj,
		cyhal_async_mode_t	mode,
		uint8_t	dma_priority
	)

Set the mechanism that is used to perform I2S asynchronous transfers.

The default is SW.

Warning

The effect of calling this function while an async transfer is pending is undefined.

Parameters

[in]	obj	The I2S object
[in]	mode	The transfer mode
[in]	dma_priority	The priority, if DMA is used. Valid values are the same as for cyhal_dma_init. If DMA is not selected, the only valid value is CYHAL_DMA_PRIORITY_DEFAULT, and no guarantees are made about prioritization.

Returns

The status of the set mode request

cyhal_i2s_is_read_pending()

bool cyhal_i2s_is_read_pending

(

cyhal_i2s_t *

obj

)

Checks if the specified I2S peripheral is in the process of reading data from the hardware buffer into RAM.

Note

: This only checks whether there is an ongoing transfer (e.g. via cyhal_i2s_read_async) into RAM from the I2S peripheral's hardware buffer. It does not check whether unread data exists in the hardware buffer.

Parameters

[in]

obj

The I2S peripheral to check

Returns

Whether an asynchronous read operation is still in progress

cyhal_i2s_is_write_pending()

bool cyhal_i2s_is_write_pending

(

cyhal_i2s_t *

obj

)

Checks if the specified I2S peripheral is in the process of writing data into the hardware buffer.

Note

: This only checks whether there is an ongoing transfer (e.g. via cyhal_i2s_transfer_async) from RAM into the I2S peripheral's hardware buffer. It does not check whether unwritten data exists in the hardware buffer.

Parameters

[in]

obj

The I2S peripheral to check

Returns

Whether an asynchronous write operation is still in progress

cyhal_i2s_abort_read_async()

cy_rslt_t cyhal_i2s_abort_read_async

(

cyhal_i2s_t *

obj

)

Abort I2S asynchronous read.

This function does not perform any validation before aborting the transfer. Any validation which is required is the responsibility of the application.

Parameters

[in]

obj

The I2S object

Returns

The status of the abort_async_read request

cyhal_i2s_abort_write_async()

cy_rslt_t cyhal_i2s_abort_write_async

(

cyhal_i2s_t *

obj

)

Abort I2S asynchronous write.

This function does not perform any validation before aborting the transfer. Any validation which is required is the responsibility of the application.

Parameters

[in]

obj

The I2S object

Returns

The status of the abort_async_write request

cyhal_i2s_register_callback()

void cyhal_i2s_register_callback	(	cyhal_i2s_t *	obj,
		cyhal_i2s_event_callback_t	callback,
		void *	callback_arg
	)

Register an I2S callback handler.

This function will be called when one of the events enabled by cyhal_i2s_enable_event occurs.

Parameters

[in]	obj	The I2S object
[in]	callback	The callback handler which will be invoked when the interrupt fires
[in]	callback_arg	Generic argument that will be provided to the callback when called

cyhal_i2s_enable_event()

void cyhal_i2s_enable_event	(	cyhal_i2s_t *	obj,
		cyhal_i2s_event_t	event,
		uint8_t	intr_priority,
		bool	enable
	)

Configure I2S events.

When an enabled event occurs, the function specified by cyhal_i2s_register_callback will be called.

Parameters

[in]	obj	The I2S object
[in]	event	The I2S event type
[in]	intr_priority	The priority for NVIC interrupt events
[in]	enable	True to turn on specified events, False to turn off

cyhal_i2s_enable_output()

cy_rslt_t cyhal_i2s_enable_output	(	cyhal_i2s_t *	obj,
		cyhal_i2s_output_t	output,
		cyhal_source_t *	source
	)

Enables the specified output signal.

Parameters

[in]	obj	The I2S object
[in]	output	Which output signal to enable
[out]	source	Pointer to user-allocated source signal object which will be initialized by enable_output. source should be passed to (dis)connect_digital functions to (dis)connect the associated endpoints.

Returns

The status of the output enable

cyhal_i2s_disable_output()

cy_rslt_t cyhal_i2s_disable_output	(	cyhal_i2s_t *	obj,
		cyhal_i2s_output_t	output
	)

Disables the specified output signal.

Parameters

[in]	obj	The I2S object
[in]	output	Which output signal to disable

Returns

The status of the disablement