PSoC 6 Peripheral Driver Library

General Description

API Reference

 Low Power Callback
 The driver supports SysPm callback for Deep Sleep transition.
 

Functions

cy_en_i2s_status_t Cy_I2S_Init (I2S_Type *base, cy_stc_i2s_config_t const *config)
 Initializes the I2S module in accordance with a configuration structure. More...
 
void Cy_I2S_DeInit (I2S_Type *base)
 Uninitializes the I2S module (reverts default register values). More...
 
__STATIC_INLINE void Cy_I2S_EnableTx (I2S_Type *base)
 Starts an I2S transmission. More...
 
__STATIC_INLINE void Cy_I2S_PauseTx (I2S_Type *base)
 Pauses an I2S transmission. More...
 
__STATIC_INLINE void Cy_I2S_ResumeTx (I2S_Type *base)
 Resumes an I2S transmission. More...
 
__STATIC_INLINE void Cy_I2S_DisableTx (I2S_Type *base)
 Stops an I2S transmission. More...
 
__STATIC_INLINE void Cy_I2S_EnableRx (I2S_Type *base)
 Starts an I2S reception. More...
 
__STATIC_INLINE void Cy_I2S_DisableRx (I2S_Type *base)
 Stops an I2S reception. More...
 
__STATIC_INLINE uint32_t Cy_I2S_GetCurrentState (I2S_Type const *base)
 Returns the current I2S state (TX/RX running/paused/stopped). More...
 
__STATIC_INLINE void Cy_I2S_ClearTxFifo (I2S_Type *base)
 Clears the TX FIFO (resets the Read/Write FIFO pointers). More...
 
__STATIC_INLINE uint32_t Cy_I2S_GetNumInTxFifo (I2S_Type const *base)
 Gets the number of used words in the TX FIFO. More...
 
__STATIC_INLINE void Cy_I2S_WriteTxData (I2S_Type *base, uint32_t data)
 Writes data to the TX FIFO. More...
 
__STATIC_INLINE uint8_t Cy_I2S_GetTxReadPointer (I2S_Type const *base)
 Gets the TX FIFO Read pointer. More...
 
__STATIC_INLINE uint8_t Cy_I2S_GetTxWritePointer (I2S_Type const *base)
 Gets the TX FIFO Write pointer. More...
 
__STATIC_INLINE void Cy_I2S_FreezeTxFifo (I2S_Type *base)
 Freezes the TX FIFO. More...
 
__STATIC_INLINE void Cy_I2S_UnfreezeTxFifo (I2S_Type *base)
 Unfreezes the TX FIFO. More...
 
__STATIC_INLINE void Cy_I2S_ClearRxFifo (I2S_Type *base)
 Clears the RX FIFO (resets the Read/Write FIFO pointers). More...
 
__STATIC_INLINE uint32_t Cy_I2S_GetNumInRxFifo (I2S_Type const *base)
 Gets the number of used words in the RX FIFO. More...
 
__STATIC_INLINE uint32_t Cy_I2S_ReadRxData (I2S_Type const *base)
 Reads data from the RX FIFO. More...
 
__STATIC_INLINE uint32_t Cy_I2S_ReadRxDataSilent (I2S_Type const *base)
 Reads data from the RX FIFO without updating the RX FIFO read pointer. More...
 
__STATIC_INLINE uint8_t Cy_I2S_GetRxReadPointer (I2S_Type const *base)
 Gets the RX FIFO Read pointer. More...
 
__STATIC_INLINE uint8_t Cy_I2S_GetRxWritePointer (I2S_Type const *base)
 Gets the RX FIFO Write pointer. More...
 
__STATIC_INLINE void Cy_I2S_FreezeRxFifo (I2S_Type *base)
 Freezes the RX FIFO. More...
 
__STATIC_INLINE void Cy_I2S_UnfreezeRxFifo (I2S_Type *base)
 Unfreezes the RX FIFO. More...
 
__STATIC_INLINE uint32_t Cy_I2S_GetInterruptStatus (I2S_Type const *base)
 Gets an interrupt status (returns a content of the INTR register). More...
 
__STATIC_INLINE void Cy_I2S_ClearInterrupt (I2S_Type *base, uint32_t interrupt)
 Clears one or more interrupt factors (sets the INTR register). More...
 
__STATIC_INLINE void Cy_I2S_SetInterrupt (I2S_Type *base, uint32_t interrupt)
 Sets one or more interrupt factors (sets the INTR_SET register). More...
 
__STATIC_INLINE uint32_t Cy_I2S_GetInterruptMask (I2S_Type const *base)
 Returns the interrupt mask (a content of the INTR_MASK register). More...
 
__STATIC_INLINE void Cy_I2S_SetInterruptMask (I2S_Type *base, uint32_t interrupt)
 Sets one or more interrupt factor masks (the INTR_MASK register). More...
 
__STATIC_INLINE uint32_t Cy_I2S_GetInterruptStatusMasked (I2S_Type const *base)
 Returns the interrupt status masked (a content of the INTR_MASKED register). More...
 

Function Documentation

◆ Cy_I2S_Init()

cy_en_i2s_status_t Cy_I2S_Init ( I2S_Type base,
cy_stc_i2s_config_t const *  config 
)

Initializes the I2S module in accordance with a configuration structure.

Precondition
If the I2S module is initialized previously, the Cy_I2S_DeInit() must be called before calling this function.
Parameters
baseThe pointer to the I2S instance address.
configThe pointer to a configuration structure.
Returns
error / status code. See cy_en_i2s_status_t.
Function Usage
/* Scenario: Setup a duplex 16-bit I2S interface */
const cy_stc_i2s_config_t config =
{
/* .txEnabled */ true,
/* .rxEnabled */ true,
/* .txDmaTrigger */ false,
/* .rxDmaTrigger */ false,
/* .clkDiv */ 16U,
/* .extClk */ false,
/* .txMasterMode */ false,
/* .txAlignment */ CY_I2S_I2S_MODE,
/* .txWsPulseWidth */ CY_I2S_WS_ONE_CHANNEL_LENGTH,
/* .txWatchdogEnable */ false,
/* .txWatchdogValue */ 0xFFFFFFFFUL,
/* .txSdoLatchingTime */ false,
/* .txSckoInversion */ false,
/* .txSckiInversion */ false,
/* .txChannels */ 2U,
/* .txChannelLength */ CY_I2S_LEN16,
/* .txWordLength */ CY_I2S_LEN16,
/* .txOverheadValue */ CY_I2S_OVHDATA_ZERO,
/* .txFifoTriggerLevel */ 0U, /* In this example the trigger isn't used */
/* .rxMasterMode */ true,
/* .rxAlignment */ CY_I2S_I2S_MODE,
/* .rxWsPulseWidth */ CY_I2S_WS_ONE_CHANNEL_LENGTH,
/* .rxWatchdogEnable */ false,
/* .rxWatchdogValue */ 0xFFFFFFFFUL,
/* .rxSdiLatchingTime */ false,
/* .rxSckoInversion */ false,
/* .rxSckiInversion */ false,
/* .rxChannels */ 2U,
/* .rxChannelLength */ CY_I2S_LEN16,
/* .rxWordLength */ CY_I2S_LEN16,
/* .rxSignExtension */ false,
/* .rxFifoTriggerLevel */ 0U /* In this example the trigger isn't used */
};
if(CY_I2S_SUCCESS != Cy_I2S_Init (I2S0, &config))
{
/* Insert error handling */
}
/* Clear both FIFOs */
/* Put at least one frame (may be empty) into the Tx FIFO - two data words for I2S format */
Cy_I2S_WriteTxData (I2S0, 0UL);
Cy_I2S_WriteTxData (I2S0, 0UL);
/* Clear possible pending interrupts */
/* Enable interrupts */
/* Enable communication */

◆ Cy_I2S_DeInit()

void Cy_I2S_DeInit ( I2S_Type base)

Uninitializes the I2S module (reverts default register values).

Parameters
baseThe pointer to the I2S instance address.
Function Usage
/* Scenario: The I2S block is initialized/working and then no longer used or needs to be reset */
Cy_I2S_DeInit (I2S0);

◆ Cy_I2S_EnableTx()

__STATIC_INLINE void Cy_I2S_EnableTx ( I2S_Type base)

Starts an I2S transmission.

Interrupt enabling (by the Cy_I2S_SetInterruptMask) is required after this function call, in case if any I2S interrupts are used in the application.

Precondition
Cy_I2S_Init() must be called before.
Parameters
baseThe pointer to the I2S instance address.
Function Usage
/* Scenario: the I2S block is initialized to operate in TX mode
and its interrupt mask has been configured (if used).
The TX FIFOs are prepared and the block is ready to be enabled for TX communication.*/

◆ Cy_I2S_PauseTx()

__STATIC_INLINE void Cy_I2S_PauseTx ( I2S_Type base)

Pauses an I2S transmission.

Parameters
baseThe pointer to the I2S instance address.
Function Usage
/* Scenario: The I2S transmission is running and there is a need be paused */

◆ Cy_I2S_ResumeTx()

__STATIC_INLINE void Cy_I2S_ResumeTx ( I2S_Type base)

Resumes an I2S transmission.

Parameters
baseThe pointer to the I2S instance address.
Function Usage
/* Scenario: The I2S transmission is paused and there is a need be resumed */
Cy_I2S_ResumeTx (I2S0);

◆ Cy_I2S_DisableTx()

__STATIC_INLINE void Cy_I2S_DisableTx ( I2S_Type base)

Stops an I2S transmission.

Precondition
TX interrupt disabling (by the Cy_I2S_SetInterruptMask) is required prior to this function call, in case any TX I2S interrupts are used.
Parameters
baseThe pointer to the I2S instance address.
Function Usage
/* Scenario: The I2S transmission is running and no longer required
so needs to be turned off. */
/* Disable all the TX interrupts here */

◆ Cy_I2S_EnableRx()

__STATIC_INLINE void Cy_I2S_EnableRx ( I2S_Type base)

Starts an I2S reception.

Interrupt enabling (by the Cy_I2S_SetInterruptMask) is required after this function call, in case any I2S interrupts are used in the application.

Precondition
Cy_I2S_Init() must be called before.
Parameters
baseThe pointer to the I2S instance address.
Function Usage
/* Scenario: The I2S block is initialized to operate in RX mode
and its interrupt mask has been configured (if used).
The RX FIFO is cleared and ready for data reception. */

◆ Cy_I2S_DisableRx()

__STATIC_INLINE void Cy_I2S_DisableRx ( I2S_Type base)

Stops an I2S reception.

Precondition
RX interrupt disabling (by the Cy_I2S_SetInterruptMask) is required prior to this function call, in case any RX I2S interrupts are used.
Parameters
baseThe pointer to the I2S instance address.
Function Usage
/* Scenario: The I2S reception is running and no longer required
so needs to be turned off. */

◆ Cy_I2S_GetCurrentState()

__STATIC_INLINE uint32_t Cy_I2S_GetCurrentState ( I2S_Type const *  base)

Returns the current I2S state (TX/RX running/paused/stopped).

Parameters
baseThe pointer to the I2S instance address.
Returns
The current state Current State.
Function Usage
/* Scenario: Need to check whether the I2S transmission is running */
uint32_t state = Cy_I2S_GetCurrentState(I2S0);
if ((0UL != (CY_I2S_TX_START & state)) &&
(0UL == (CY_I2S_TX_PAUSE & state)))
{
/* The I2S transmission is running (enabled and not paused) */
}

◆ Cy_I2S_ClearTxFifo()

__STATIC_INLINE void Cy_I2S_ClearTxFifo ( I2S_Type base)

Clears the TX FIFO (resets the Read/Write FIFO pointers).

Parameters
baseThe pointer to the I2S instance address.
Function Usage
/* Scenario: Empty the contents of the TX FIFO in preparation for a new set of TX data */

◆ Cy_I2S_GetNumInTxFifo()

__STATIC_INLINE uint32_t Cy_I2S_GetNumInTxFifo ( I2S_Type const *  base)

Gets the number of used words in the TX FIFO.

Parameters
baseThe pointer to the I2S instance address.
Returns
The current number of used words in the TX FIFO.
Function Usage
/* Scenario: New data set needs to be loaded into the TX buffer.
However first check the number of data words currently in the TX FIFO. */
if (254UL > Cy_I2S_GetNumInTxFifo(I2S0))
{
/* There are more than 2 empty words in the TX FIFO,
so load the next I2S frame using Cy_I2S_WriteTxData */
}

◆ Cy_I2S_WriteTxData()

__STATIC_INLINE void Cy_I2S_WriteTxData ( I2S_Type base,
uint32_t  data 
)

Writes data to the TX FIFO.

Increases the TX FIFO level.

Parameters
baseThe pointer to the I2S instance address.
dataData to be written to the TX FIFO.
Function Usage
Cy_I2S_WriteTxData(I2S0, 1UL); /* The last word in the Tx FIFO is 0x00000001. */
Cy_I2S_WriteTxData(I2S0, 2UL); /* Now the last word in the Tx FIFO is 0x00000002,
and previous is 0x00000001. */

◆ Cy_I2S_GetTxReadPointer()

__STATIC_INLINE uint8_t Cy_I2S_GetTxReadPointer ( I2S_Type const *  base)

Gets the TX FIFO Read pointer.

This function is for debug purposes.

Parameters
baseThe pointer to the I2S instance address.
Returns
The current TX Read pointer value.
Function Usage
/* Scenario: Need to check the Tx FIFO read pointer */
uint8_t readPointer = Cy_I2S_GetTxReadPointer(I2S0);
/* readPointer now contains the read pointer of the Tx FIFO.
The Tx FIFO read pointer increments when transmission is enabled and
HW takes a data word from FIFO into the transmitter */

◆ Cy_I2S_GetTxWritePointer()

__STATIC_INLINE uint8_t Cy_I2S_GetTxWritePointer ( I2S_Type const *  base)

Gets the TX FIFO Write pointer.

This function is for debug purposes.

Parameters
baseThe pointer to the I2S instance address.
Returns
The current TX Write pointer value.
Function Usage
/* Scenario: Need to check the Tx FIFO write pointer */
uint8_t writePointer = Cy_I2S_GetTxWritePointer(I2S0);
/* writePointer now contains the write pointer of the Tx FIFO.
The Tx FIFO write pointer increments when a data word is written into the
FIFO by \ref Cy_I2S_WriteTxData. */

◆ Cy_I2S_FreezeTxFifo()

__STATIC_INLINE void Cy_I2S_FreezeTxFifo ( I2S_Type base)

Freezes the TX FIFO.

This function is for debug purposes.

Parameters
baseThe pointer to the I2S instance address.
Function Usage
/* Scenario: Need to freeze the Tx FIFO for debugging purposes */
/* Now the read pointer of the Tx FIFO will be not affected by HW. */

◆ Cy_I2S_UnfreezeTxFifo()

__STATIC_INLINE void Cy_I2S_UnfreezeTxFifo ( I2S_Type base)

Unfreezes the TX FIFO.

This function is for debug purposes.

Parameters
baseThe pointer to the I2S instance address.
Function Usage
/* Scenario: The Tx FIFO was previously frozen and now needs to be unfrozen */
/* Now the Tx FIFO works as usually. */

◆ Cy_I2S_ClearRxFifo()

__STATIC_INLINE void Cy_I2S_ClearRxFifo ( I2S_Type base)

Clears the RX FIFO (resets the Read/Write FIFO pointers).

Parameters
baseThe pointer to the I2S instance address.
Function Usage
/* Scenario: Empty the contents of the RX FIFO in preparation for a new data reception */

◆ Cy_I2S_GetNumInRxFifo()

__STATIC_INLINE uint32_t Cy_I2S_GetNumInRxFifo ( I2S_Type const *  base)

Gets the number of used words in the RX FIFO.

Parameters
baseThe pointer to the I2S instance address.
Returns
The current number of used words in rge RX FIFO.
Function Usage
/* Scenario: Waiting for new received data, check how many data words are in the Rx FIFO */
if (2UL < Cy_I2S_GetNumInRxFifo(I2S0))
{
/* There are more than 2 data words in the RX FIFO,
so get them using Cy_I2S_ReadRxData */
}

◆ Cy_I2S_ReadRxData()

__STATIC_INLINE uint32_t Cy_I2S_ReadRxData ( I2S_Type const *  base)

Reads data from the RX FIFO.

Decreases the RX FIFO level.

Parameters
baseThe pointer to the I2S instance address.
Returns
The read data.
Function Usage
/* Scenario: Need to get two data words from the Rx FIFO */
uint32_t data[2];
data[0] = Cy_I2S_ReadRxData(I2S0); /* The data[0] contains the first word from the Rx FIFO */
data[1] = Cy_I2S_ReadRxData(I2S0); /* The data[1] contains the next word
(which is actually the first now) from the Rx FIFO */

◆ Cy_I2S_ReadRxDataSilent()

__STATIC_INLINE uint32_t Cy_I2S_ReadRxDataSilent ( I2S_Type const *  base)

Reads data from the RX FIFO without updating the RX FIFO read pointer.

This function is for debug purposes.

Parameters
baseThe pointer to the I2S instance address.
Returns
The read data.
Function Usage
/* Scenario: Need to get a data silently from the Rx FIFO (don't increment FIFO read pointer) */
uint32_t data[4];
data[0] = Cy_I2S_ReadRxDataSilent(I2S0); /* The data[0] contains the first word from the Rx FIFO */
data[1] = Cy_I2S_ReadRxDataSilent(I2S0); /* The data[1] contains the same first word from the Rx FIFO */
data[2] = Cy_I2S_ReadRxData(I2S0); /* The data[2] contains the same first word from the Rx FIFO */
data[3] = Cy_I2S_ReadRxData(I2S0); /* The data[3] contains the next (the first now) word from the Rx FIFO */

◆ Cy_I2S_GetRxReadPointer()

__STATIC_INLINE uint8_t Cy_I2S_GetRxReadPointer ( I2S_Type const *  base)

Gets the RX FIFO Read pointer.

This function is for debug purposes.

Parameters
baseThe pointer to the I2S instance address.
Returns
The current RX Read pointer value.
Function Usage
/* Scenario: Need to check the Rx FIFO read pointer */
uint8_t readPointer = Cy_I2S_GetRxReadPointer(I2S0);
/* readPointer now contains the read pointer of the Rx FIFO.
The Rx FIFO read pointer increments when a data word is read from the
FIFO by \ref Cy_I2S_ReadRxData. */

◆ Cy_I2S_GetRxWritePointer()

__STATIC_INLINE uint8_t Cy_I2S_GetRxWritePointer ( I2S_Type const *  base)

Gets the RX FIFO Write pointer.

This function is for debug purposes.

Parameters
baseThe pointer to the I2S instance address.
Returns
The current RX Write pointer value.
Function Usage
/* Scenario: Need to check the Rx FIFO write pointer */
uint8_t writePointer = Cy_I2S_GetRxWritePointer(I2S0);
/* writePointer now contains the write pointer of the Rx FIFO.
The Rx FIFO write pointer increments when the I2S reception is running
and HW drops a data word into the FIFO. */

◆ Cy_I2S_FreezeRxFifo()

__STATIC_INLINE void Cy_I2S_FreezeRxFifo ( I2S_Type base)

Freezes the RX FIFO.

This function is for debug purposes.

Parameters
baseThe pointer to the I2S instance address.
Function Usage
/* Scenario: Need to freeze the Rx FIFO */
/* Now the write pointer of the Rx FIFO will be not affected by HW. */

◆ Cy_I2S_UnfreezeRxFifo()

__STATIC_INLINE void Cy_I2S_UnfreezeRxFifo ( I2S_Type base)

Unfreezes the RX FIFO.

This function is for debug purposes.

Parameters
baseThe pointer to the I2S instance address.
Function Usage
/* Scenario: The Rx FIFO was previously frozen and now needs to be unfrozen */
/* Now the Rx FIFO works as usually. */

◆ Cy_I2S_GetInterruptStatus()

__STATIC_INLINE uint32_t Cy_I2S_GetInterruptStatus ( I2S_Type const *  base)

Gets an interrupt status (returns a content of the INTR register).

Parameters
baseThe pointer to the I2S instance address.
Returns
The interrupt bit mask Interrupt Masks.
Function Usage
/* Scenario: Need to check TX_EMPTY interrupt status regardless of whether it is enabled (masked) or not */
{
/* The TX_EMPTY interrupt is pending */
}

◆ Cy_I2S_ClearInterrupt()

__STATIC_INLINE void Cy_I2S_ClearInterrupt ( I2S_Type base,
uint32_t  interrupt 
)

Clears one or more interrupt factors (sets the INTR register).

Parameters
baseThe pointer to the I2S instance address.
interruptInterrupt bit mask Interrupt Masks.
Function Usage
/* Scenario: Inside the I2S interrupt service routine */
/* Get all the enabled pending interrupts */
uint32_t interrupt = Cy_I2S_GetInterruptStatusMasked (I2S0);
if (0UL != (CY_I2S_INTR_TX_EMPTY & interrupt))
{
/* Handle the TX_EMPTY interrupt - fill the Tx FIFO, etc. */
}
/* Check and handle the rest of I2S interrupt types, if needed */
/* Clear the interrupt */
Cy_I2S_ClearInterrupt(I2S0, interrupt);

◆ Cy_I2S_SetInterrupt()

__STATIC_INLINE void Cy_I2S_SetInterrupt ( I2S_Type base,
uint32_t  interrupt 
)

Sets one or more interrupt factors (sets the INTR_SET register).

Parameters
baseThe pointer to the I2S instance address.
interruptInterrupt bit mask Interrupt Masks.
Function Usage
/* Scenario: Test the TX_EMPTY interrupt */
Cy_I2S_SetInterrupt(I2S0, CY_I2S_INTR_TX_EMPTY); /* Set the TX_EMPTY by software */
/* Now the TX_EMPTY interrupt should occur (if it is enabled, of course) */

◆ Cy_I2S_GetInterruptMask()

__STATIC_INLINE uint32_t Cy_I2S_GetInterruptMask ( I2S_Type const *  base)

Returns the interrupt mask (a content of the INTR_MASK register).

Parameters
baseThe pointer to the I2S instance address.
Returns
The interrupt bit mask Interrupt Masks.
Function Usage
/* Scenario: Need to enable the TX_EMPTY interrupt apart from all other interrupts */

◆ Cy_I2S_SetInterruptMask()

__STATIC_INLINE void Cy_I2S_SetInterruptMask ( I2S_Type base,
uint32_t  interrupt 
)

Sets one or more interrupt factor masks (the INTR_MASK register).

Parameters
baseThe pointer to the I2S instance address.
interruptInterrupt bit mask Interrupt Masks.
Function Usage
/* Scenario: Enable I2S interrupts (if any used) */
CY_I2S_INTR_RX_WD); /* Remove needless items */
/* Scenario: Disable I2S interrupts (if any enabled) */
Cy_I2S_SetInterruptMask (I2S0, 0UL); /* Disable all I2S interrupts */

◆ Cy_I2S_GetInterruptStatusMasked()

__STATIC_INLINE uint32_t Cy_I2S_GetInterruptStatusMasked ( I2S_Type const *  base)

Returns the interrupt status masked (a content of the INTR_MASKED register).

Parameters
baseThe pointer to the I2S instance address.
Returns
The interrupt bit mask(s) Interrupt Masks.
Function Usage
/* Scenario: Inside the I2S interrupt service routine */
/* Get all the enabled pending interrupts */
uint32_t interrupt = Cy_I2S_GetInterruptStatusMasked (I2S0);
if (0UL != (CY_I2S_INTR_TX_EMPTY & interrupt))
{
/* Handle the TX_EMPTY interrupt - fill the Tx FIFO, etc. */
}
/* Check and handle the rest of I2S interrupt types, if needed */
/* Clear the interrupt */
Cy_I2S_ClearInterrupt(I2S0, interrupt);