514 lines
16 KiB
C
514 lines
16 KiB
C
/*
|
|
* Copyright (c) 2016, Freescale Semiconductor, Inc.
|
|
* Copyright 2016-2022 NXP
|
|
* All rights reserved.
|
|
*
|
|
* SPDX-License-Identifier: BSD-3-Clause
|
|
*/
|
|
#ifndef FSL_I2S_H_
|
|
#define FSL_I2S_H_
|
|
|
|
#include "fsl_device_registers.h"
|
|
#include "fsl_common.h"
|
|
#include "fsl_flexcomm.h"
|
|
|
|
/*******************************************************************************
|
|
* Definitions
|
|
******************************************************************************/
|
|
|
|
/*!
|
|
* @addtogroup i2s_driver
|
|
* @{
|
|
*/
|
|
|
|
/*! @file */
|
|
|
|
/*! @name Driver version */
|
|
/*! @{ */
|
|
|
|
/*! @brief I2S driver version 2.3.2. */
|
|
#define FSL_I2S_DRIVER_VERSION (MAKE_VERSION(2, 3, 2))
|
|
/*! @} */
|
|
|
|
#ifndef I2S_NUM_BUFFERS
|
|
|
|
/*! @brief Number of buffers . */
|
|
#define I2S_NUM_BUFFERS (4U)
|
|
|
|
#endif
|
|
|
|
/*! @brief _i2s_status I2S status codes. */
|
|
enum
|
|
{
|
|
kStatus_I2S_BufferComplete =
|
|
MAKE_STATUS(kStatusGroup_I2S, 0), /*!< Transfer from/into a single buffer has completed */
|
|
kStatus_I2S_Done = MAKE_STATUS(kStatusGroup_I2S, 1), /*!< All buffers transfers have completed */
|
|
kStatus_I2S_Busy =
|
|
MAKE_STATUS(kStatusGroup_I2S, 2), /*!< Already performing a transfer and cannot queue another buffer */
|
|
};
|
|
|
|
/*!
|
|
* @brief I2S flags.
|
|
*
|
|
* @note These enums are meant to be OR'd together to form a bit mask.
|
|
*/
|
|
typedef enum _i2s_flags
|
|
{
|
|
kI2S_TxErrorFlag = I2S_FIFOINTENSET_TXERR_MASK, /*!< TX error interrupt */
|
|
kI2S_TxLevelFlag = I2S_FIFOINTENSET_TXLVL_MASK, /*!< TX level interrupt */
|
|
kI2S_RxErrorFlag = I2S_FIFOINTENSET_RXERR_MASK, /*!< RX error interrupt */
|
|
kI2S_RxLevelFlag = I2S_FIFOINTENSET_RXLVL_MASK /*!< RX level interrupt */
|
|
} i2s_flags_t;
|
|
|
|
/*! @brief Master / slave mode. */
|
|
typedef enum _i2s_master_slave
|
|
{
|
|
kI2S_MasterSlaveNormalSlave = 0x0, /*!< Normal slave */
|
|
kI2S_MasterSlaveWsSyncMaster = 0x1, /*!< WS synchronized master */
|
|
kI2S_MasterSlaveExtSckMaster = 0x2, /*!< Master using existing SCK */
|
|
kI2S_MasterSlaveNormalMaster = 0x3 /*!< Normal master */
|
|
} i2s_master_slave_t;
|
|
|
|
/*! @brief I2S mode. */
|
|
typedef enum _i2s_mode
|
|
{
|
|
kI2S_ModeI2sClassic = 0x0, /*!< I2S classic mode */
|
|
kI2S_ModeDspWs50 = 0x1, /*!< DSP mode, WS having 50% duty cycle */
|
|
kI2S_ModeDspWsShort = 0x2, /*!< DSP mode, WS having one clock long pulse */
|
|
kI2S_ModeDspWsLong = 0x3 /*!< DSP mode, WS having one data slot long pulse */
|
|
} i2s_mode_t;
|
|
|
|
/*! @brief _i2s_secondary_channel I2S secondary channel. */
|
|
enum
|
|
{
|
|
kI2S_SecondaryChannel1 = 0U, /*!< secondary channel 1 */
|
|
kI2S_SecondaryChannel2 = 1U, /*!< secondary channel 2 */
|
|
kI2S_SecondaryChannel3 = 2U, /*!< secondary channel 3 */
|
|
};
|
|
|
|
/*! @brief I2S configuration structure. */
|
|
typedef struct _i2s_config
|
|
{
|
|
i2s_master_slave_t masterSlave; /*!< Master / slave configuration */
|
|
i2s_mode_t mode; /*!< I2S mode */
|
|
bool rightLow; /*!< Right channel data in low portion of FIFO */
|
|
bool leftJust; /*!< Left justify data in FIFO */
|
|
#if (defined(FSL_FEATURE_FLEXCOMM_I2S_HAS_DMIC_INTERCONNECTION) && FSL_FEATURE_FLEXCOMM_I2S_HAS_DMIC_INTERCONNECTION)
|
|
bool pdmData; /*!< Data source is the D-Mic subsystem */
|
|
#endif
|
|
bool sckPol; /*!< SCK polarity */
|
|
bool wsPol; /*!< WS polarity */
|
|
uint16_t divider; /*!< Flexcomm function clock divider (1 - 4096) */
|
|
bool oneChannel; /*!< true mono, false stereo */
|
|
uint8_t dataLength; /*!< Data length (4 - 32) */
|
|
uint16_t frameLength; /*!< Frame width (4 - 512) */
|
|
uint16_t position; /*!< Data position in the frame */
|
|
uint8_t watermark; /*!< FIFO trigger level */
|
|
bool txEmptyZero; /*!< Transmit zero when buffer becomes empty or last item */
|
|
bool pack48; /*!< Packing format for 48-bit data (false - 24 bit values, true - alternating 32-bit and 16-bit
|
|
values) */
|
|
} i2s_config_t;
|
|
|
|
/*! @brief Buffer to transfer from or receive audio data into. */
|
|
typedef struct _i2s_transfer
|
|
{
|
|
uint8_t *data; /*!< Pointer to data buffer. */
|
|
size_t dataSize; /*!< Buffer size in bytes. */
|
|
} i2s_transfer_t;
|
|
|
|
/*! @brief Transactional state of the intialized transfer or receive I2S operation. */
|
|
typedef struct _i2s_handle i2s_handle_t;
|
|
|
|
/*!
|
|
* @brief Callback function invoked from transactional API
|
|
* on completion of a single buffer transfer.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param handle pointer to I2S transaction.
|
|
* @param completionStatus status of the transaction.
|
|
* @param userData optional pointer to user arguments data.
|
|
*/
|
|
typedef void (*i2s_transfer_callback_t)(I2S_Type *base,
|
|
i2s_handle_t *handle,
|
|
status_t completionStatus,
|
|
void *userData);
|
|
|
|
/*! @brief Members not to be accessed / modified outside of the driver. */
|
|
struct _i2s_handle
|
|
{
|
|
volatile uint32_t state; /*!< State of transfer */
|
|
i2s_transfer_callback_t completionCallback; /*!< Callback function pointer */
|
|
void *userData; /*!< Application data passed to callback */
|
|
bool oneChannel; /*!< true mono, false stereo */
|
|
uint8_t dataLength; /*!< Data length (4 - 32) */
|
|
bool pack48; /*!< Packing format for 48-bit data (false - 24 bit values, true - alternating 32-bit and 16-bit
|
|
values) */
|
|
uint8_t watermark; /*!< FIFO trigger level */
|
|
bool useFifo48H; /*!< When dataLength 17-24: true use FIFOWR48H, false use FIFOWR */
|
|
|
|
volatile i2s_transfer_t i2sQueue[I2S_NUM_BUFFERS]; /*!< Transfer queue storing transfer buffers */
|
|
volatile uint8_t queueUser; /*!< Queue index where user's next transfer will be stored */
|
|
volatile uint8_t queueDriver; /*!< Queue index of buffer actually used by the driver */
|
|
volatile uint32_t errorCount; /*!< Number of buffer underruns/overruns */
|
|
volatile uint32_t transferCount; /*!< Number of bytes transferred */
|
|
};
|
|
|
|
/*******************************************************************************
|
|
* API
|
|
******************************************************************************/
|
|
|
|
#if defined(__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
/*!
|
|
* @name Initialization and deinitialization
|
|
* @{
|
|
*/
|
|
|
|
/*!
|
|
* @brief Initializes the FLEXCOMM peripheral for I2S transmit functionality.
|
|
*
|
|
* Ungates the FLEXCOMM clock and configures the module
|
|
* for I2S transmission using a configuration structure.
|
|
* The configuration structure can be custom filled or set with default values by
|
|
* I2S_TxGetDefaultConfig().
|
|
*
|
|
* @note This API should be called at the beginning of the application to use
|
|
* the I2S driver.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param config pointer to I2S configuration structure.
|
|
*/
|
|
void I2S_TxInit(I2S_Type *base, const i2s_config_t *config);
|
|
|
|
/*!
|
|
* @brief Initializes the FLEXCOMM peripheral for I2S receive functionality.
|
|
*
|
|
* Ungates the FLEXCOMM clock and configures the module
|
|
* for I2S receive using a configuration structure.
|
|
* The configuration structure can be custom filled or set with default values by
|
|
* I2S_RxGetDefaultConfig().
|
|
*
|
|
* @note This API should be called at the beginning of the application to use
|
|
* the I2S driver.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param config pointer to I2S configuration structure.
|
|
*/
|
|
void I2S_RxInit(I2S_Type *base, const i2s_config_t *config);
|
|
|
|
/*!
|
|
* @brief Sets the I2S Tx configuration structure to default values.
|
|
*
|
|
* This API initializes the configuration structure for use in I2S_TxInit().
|
|
* The initialized structure can remain unchanged in I2S_TxInit(), or it can be modified
|
|
* before calling I2S_TxInit().
|
|
* Example:
|
|
@code
|
|
i2s_config_t config;
|
|
I2S_TxGetDefaultConfig(&config);
|
|
@endcode
|
|
*
|
|
* Default values:
|
|
* @code
|
|
* config->masterSlave = kI2S_MasterSlaveNormalMaster;
|
|
* config->mode = kI2S_ModeI2sClassic;
|
|
* config->rightLow = false;
|
|
* config->leftJust = false;
|
|
* config->pdmData = false;
|
|
* config->sckPol = false;
|
|
* config->wsPol = false;
|
|
* config->divider = 1;
|
|
* config->oneChannel = false;
|
|
* config->dataLength = 16;
|
|
* config->frameLength = 32;
|
|
* config->position = 0;
|
|
* config->watermark = 4;
|
|
* config->txEmptyZero = true;
|
|
* config->pack48 = false;
|
|
* @endcode
|
|
*
|
|
* @param config pointer to I2S configuration structure.
|
|
*/
|
|
void I2S_TxGetDefaultConfig(i2s_config_t *config);
|
|
|
|
/*!
|
|
* @brief Sets the I2S Rx configuration structure to default values.
|
|
*
|
|
* This API initializes the configuration structure for use in I2S_RxInit().
|
|
* The initialized structure can remain unchanged in I2S_RxInit(), or it can be modified
|
|
* before calling I2S_RxInit().
|
|
* Example:
|
|
@code
|
|
i2s_config_t config;
|
|
I2S_RxGetDefaultConfig(&config);
|
|
@endcode
|
|
*
|
|
* Default values:
|
|
* @code
|
|
* config->masterSlave = kI2S_MasterSlaveNormalSlave;
|
|
* config->mode = kI2S_ModeI2sClassic;
|
|
* config->rightLow = false;
|
|
* config->leftJust = false;
|
|
* config->pdmData = false;
|
|
* config->sckPol = false;
|
|
* config->wsPol = false;
|
|
* config->divider = 1;
|
|
* config->oneChannel = false;
|
|
* config->dataLength = 16;
|
|
* config->frameLength = 32;
|
|
* config->position = 0;
|
|
* config->watermark = 4;
|
|
* config->txEmptyZero = false;
|
|
* config->pack48 = false;
|
|
* @endcode
|
|
*
|
|
* @param config pointer to I2S configuration structure.
|
|
*/
|
|
void I2S_RxGetDefaultConfig(i2s_config_t *config);
|
|
|
|
/*!
|
|
* @brief De-initializes the I2S peripheral.
|
|
*
|
|
* This API gates the FLEXCOMM clock. The I2S module can't operate unless I2S_TxInit
|
|
* or I2S_RxInit is called to enable the clock.
|
|
*
|
|
* @param base I2S base pointer.
|
|
*/
|
|
void I2S_Deinit(I2S_Type *base);
|
|
|
|
/*!
|
|
* @brief Transmitter/Receiver bit clock rate configurations.
|
|
*
|
|
* @param base SAI base pointer.
|
|
* @param sourceClockHz bit clock source frequency.
|
|
* @param sampleRate audio data sample rate.
|
|
* @param bitWidth audio data bitWidth.
|
|
* @param channelNumbers audio channel numbers.
|
|
*/
|
|
void I2S_SetBitClockRate(
|
|
I2S_Type *base, uint32_t sourceClockHz, uint32_t sampleRate, uint32_t bitWidth, uint32_t channelNumbers);
|
|
|
|
/*! @} */
|
|
|
|
/*!
|
|
* @name Non-blocking API
|
|
* @{
|
|
*/
|
|
|
|
/*!
|
|
* @brief Initializes handle for transfer of audio data.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param handle pointer to handle structure.
|
|
* @param callback function to be called back when transfer is done or fails.
|
|
* @param userData pointer to data passed to callback.
|
|
*/
|
|
void I2S_TxTransferCreateHandle(I2S_Type *base, i2s_handle_t *handle, i2s_transfer_callback_t callback, void *userData);
|
|
|
|
/*!
|
|
* @brief Begins or queue sending of the given data.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param handle pointer to handle structure.
|
|
* @param transfer data buffer.
|
|
*
|
|
* @retval kStatus_Success
|
|
* @retval kStatus_I2S_Busy if all queue slots are occupied with unsent buffers.
|
|
*/
|
|
status_t I2S_TxTransferNonBlocking(I2S_Type *base, i2s_handle_t *handle, i2s_transfer_t transfer);
|
|
|
|
/*!
|
|
* @brief Aborts sending of data.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param handle pointer to handle structure.
|
|
*/
|
|
void I2S_TxTransferAbort(I2S_Type *base, i2s_handle_t *handle);
|
|
|
|
/*!
|
|
* @brief Initializes handle for reception of audio data.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param handle pointer to handle structure.
|
|
* @param callback function to be called back when transfer is done or fails.
|
|
* @param userData pointer to data passed to callback.
|
|
*/
|
|
void I2S_RxTransferCreateHandle(I2S_Type *base, i2s_handle_t *handle, i2s_transfer_callback_t callback, void *userData);
|
|
|
|
/*!
|
|
* @brief Begins or queue reception of data into given buffer.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param handle pointer to handle structure.
|
|
* @param transfer data buffer.
|
|
*
|
|
* @retval kStatus_Success
|
|
* @retval kStatus_I2S_Busy if all queue slots are occupied with buffers which are not full.
|
|
*/
|
|
status_t I2S_RxTransferNonBlocking(I2S_Type *base, i2s_handle_t *handle, i2s_transfer_t transfer);
|
|
|
|
/*!
|
|
* @brief Aborts receiving of data.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param handle pointer to handle structure.
|
|
*/
|
|
void I2S_RxTransferAbort(I2S_Type *base, i2s_handle_t *handle);
|
|
|
|
/*!
|
|
* @brief Returns number of bytes transferred so far.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param handle pointer to handle structure.
|
|
* @param[out] count number of bytes transferred so far by the non-blocking transaction.
|
|
*
|
|
* @retval kStatus_Success
|
|
* @retval kStatus_NoTransferInProgress there is no non-blocking transaction currently in progress.
|
|
*/
|
|
status_t I2S_TransferGetCount(I2S_Type *base, i2s_handle_t *handle, size_t *count);
|
|
|
|
/*!
|
|
* @brief Returns number of buffer underruns or overruns.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param handle pointer to handle structure.
|
|
* @param[out] count number of transmit errors encountered so far by the non-blocking transaction.
|
|
*
|
|
* @retval kStatus_Success
|
|
* @retval kStatus_NoTransferInProgress there is no non-blocking transaction currently in progress.
|
|
*/
|
|
status_t I2S_TransferGetErrorCount(I2S_Type *base, i2s_handle_t *handle, size_t *count);
|
|
|
|
/*! @} */
|
|
|
|
/*!
|
|
* @name Enable / disable
|
|
* @{
|
|
*/
|
|
|
|
/*!
|
|
* @brief Enables I2S operation.
|
|
*
|
|
* @param base I2S base pointer.
|
|
*/
|
|
static inline void I2S_Enable(I2S_Type *base)
|
|
{
|
|
base->CFG1 |= I2S_CFG1_MAINENABLE(1U);
|
|
}
|
|
|
|
#if (defined(FSL_FEATURE_I2S_SUPPORT_SECONDARY_CHANNEL) && FSL_FEATURE_I2S_SUPPORT_SECONDARY_CHANNEL)
|
|
/*!
|
|
* @brief Enables I2S secondary channel.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param channel seondary channel channel number, reference _i2s_secondary_channel.
|
|
* @param oneChannel true is treated as single channel, functionality left channel for this pair.
|
|
* @param position define the location within the frame of the data, should not bigger than 0x1FFU.
|
|
*/
|
|
void I2S_EnableSecondaryChannel(I2S_Type *base, uint32_t channel, bool oneChannel, uint32_t position);
|
|
|
|
/*!
|
|
* @brief Disables I2S secondary channel.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param channel seondary channel channel number, reference _i2s_secondary_channel.
|
|
*/
|
|
static inline void I2S_DisableSecondaryChannel(I2S_Type *base, uint32_t channel)
|
|
{
|
|
#if defined FSL_FEATURE_FLEXCOMM_INSTANCE_I2S_SUPPORT_SECONDARY_CHANNELn
|
|
assert(FSL_FEATURE_FLEXCOMM_INSTANCE_I2S_SUPPORT_SECONDARY_CHANNELn((FLEXCOMM_Type *)(uint32_t)base) == 1);
|
|
#endif
|
|
|
|
base->SECCHANNEL[channel].PCFG1 &= ~I2S_CFG1_MAINENABLE_MASK;
|
|
}
|
|
#endif
|
|
/*!
|
|
* @brief Disables I2S operation.
|
|
*
|
|
* @param base I2S base pointer.
|
|
*/
|
|
static inline void I2S_Disable(I2S_Type *base)
|
|
{
|
|
base->CFG1 &= (~I2S_CFG1_MAINENABLE(1U));
|
|
}
|
|
|
|
/*! @} */
|
|
|
|
/*!
|
|
* @name Interrupts
|
|
* @{
|
|
*/
|
|
|
|
/*!
|
|
* @brief Enables I2S FIFO interrupts.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param interruptMask bit mask of interrupts to enable. See #i2s_flags_t for the set
|
|
* of constants that should be OR'd together to form the bit mask.
|
|
*/
|
|
static inline void I2S_EnableInterrupts(I2S_Type *base, uint32_t interruptMask)
|
|
{
|
|
base->FIFOINTENSET = interruptMask;
|
|
}
|
|
|
|
/*!
|
|
* @brief Disables I2S FIFO interrupts.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param interruptMask bit mask of interrupts to enable. See #i2s_flags_t for the set
|
|
* of constants that should be OR'd together to form the bit mask.
|
|
*/
|
|
static inline void I2S_DisableInterrupts(I2S_Type *base, uint32_t interruptMask)
|
|
{
|
|
base->FIFOINTENCLR = interruptMask;
|
|
}
|
|
|
|
/*!
|
|
* @brief Returns the set of currently enabled I2S FIFO interrupts.
|
|
*
|
|
* @param base I2S base pointer.
|
|
*
|
|
* @return A bitmask composed of #i2s_flags_t enumerators OR'd together
|
|
* to indicate the set of enabled interrupts.
|
|
*/
|
|
static inline uint32_t I2S_GetEnabledInterrupts(I2S_Type *base)
|
|
{
|
|
return base->FIFOINTENSET;
|
|
}
|
|
|
|
/*!
|
|
* @brief Flush the valid data in TX fifo.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @return kStatus_Fail empty TX fifo failed, kStatus_Success empty tx fifo success.
|
|
*/
|
|
status_t I2S_EmptyTxFifo(I2S_Type *base);
|
|
|
|
/*!
|
|
* @brief Invoked from interrupt handler when transmit FIFO level decreases.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param handle pointer to handle structure.
|
|
*/
|
|
void I2S_TxHandleIRQ(I2S_Type *base, i2s_handle_t *handle);
|
|
|
|
/*!
|
|
* @brief Invoked from interrupt handler when receive FIFO level decreases.
|
|
*
|
|
* @param base I2S base pointer.
|
|
* @param handle pointer to handle structure.
|
|
*/
|
|
void I2S_RxHandleIRQ(I2S_Type *base, i2s_handle_t *handle);
|
|
|
|
/*! @} */
|
|
|
|
/*! @} */
|
|
|
|
#if defined(__cplusplus)
|
|
}
|
|
#endif
|
|
|
|
#endif /* FSL_I2S_H_ */
|