/*
* Copyright 2019 - 2020, NXP
* All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
#ifndef _FSL_PDM_EDMA_H_
#define _FSL_PDM_EDMA_H_
#include "fsl_edma.h"
#include "fsl_pdm.h"
/*!
* @addtogroup pdm_edma PDM EDMA Driver
* @ingroup pdm
* @{
*/
/*******************************************************************************
* Definitions
******************************************************************************/
/*! @name Driver version */
/*@{*/
#define FSL_PDM_EDMA_DRIVER_VERSION (MAKE_VERSION(2, 6, 1)) /*!< Version 2.6.1 */
/*@}*/
/*! @brief PDM edma handler */
typedef struct _pdm_edma_handle pdm_edma_handle_t;
/*!@brief pdm multi channel interleave type */
typedef enum _pdm_edma_multi_channel_interleave
{
kPDM_EDMAMultiChannelInterleavePerChannelSample =
0U, /*!< multi channel PDM data interleave per channel sample
* -------------------------------------------------------------------------
* |CHANNEL0 | CHANNEL1 | CHANNEL0 | CHANNEL1 | CHANNEL0 | CHANNEL 1 | ....|
* -------------------------------------------------------------------------
*/
kPDM_EDMAMultiChannelInterleavePerChannelBlock =
1U, /*!< multi channel PDM data interleave per channel block
* ----------------------------------------------------------------------------------------------------------------------------
* |CHANNEL0 | CHANNEL0 | CHANNEL0 | ...... | CHANNEL1 | CHANNEL 1 | CHANNEL 1 | ....| CHANNEL2 | CHANNEL 2
* | CHANNEL 2 | ....|
* ----------------------------------------------------------------------------------------------------------------------------
*/
} pdm_edma_multi_channel_interleave_t;
/*! @brief PDM edma transfer */
typedef struct _pdm_edma_transfer
{
volatile uint8_t *data; /*!< Data start address to transfer. */
volatile size_t dataSize; /*!< Total Transfer bytes size. */
struct _pdm_edma_transfer *linkTransfer; /*!< linked transfer configurations */
} pdm_edma_transfer_t;
/*! @brief PDM eDMA transfer callback function for finish and error */
typedef void (*pdm_edma_callback_t)(PDM_Type *base, pdm_edma_handle_t *handle, status_t status, void *userData);
/*! @brief PDM DMA transfer handle, users should not touch the content of the handle.*/
struct _pdm_edma_handle
{
edma_handle_t *dmaHandle; /*!< DMA handler for PDM send */
uint8_t count; /*!< The transfer data count in a DMA request */
uint32_t receivedBytes; /*!< total transfer count */
uint32_t state; /*!< Internal state for PDM eDMA transfer */
pdm_edma_callback_t callback; /*!< Callback for users while transfer finish or error occurs */
bool isLoopTransfer; /*!< loop transfer */
void *userData; /*!< User callback parameter */
edma_tcd_t *tcd; /*!< TCD pool for eDMA transfer. */
uint32_t tcdNum; /*!< TCD number */
uint32_t tcdUser; /*!< Index for user to queue transfer. */
uint32_t tcdDriver; /*!< Index for driver to get the transfer data and size */
volatile uint32_t tcdUsedNum; /*!< Index for user to queue transfer. */
pdm_edma_multi_channel_interleave_t interleaveType; /*!< multi channel transfer interleave type */
uint8_t endChannel; /*!< The last enabled channel */
uint8_t channelNums; /*!< total channel numbers */
};
/*******************************************************************************
* APIs
******************************************************************************/
#if defined(__cplusplus)
extern "C" {
#endif
/*!
* @name PDM eDMA Transactional
* @{
*/
/*!
* @brief Install EDMA descriptor memory.
*
* @param handle Pointer to EDMA channel transfer handle.
* @param tcdAddr EDMA head descriptor address.
* @param tcdNum EDMA link descriptor address.
*/
void PDM_TransferInstallEDMATCDMemory(pdm_edma_handle_t *handle, void *tcdAddr, size_t tcdNum);
/*!
* @brief Initializes the PDM Rx eDMA handle.
*
* This function initializes the PDM slave DMA handle, which can be used for other PDM master transactional APIs.
* Usually, for a specified PDM instance, call this API once to get the initialized handle.
*
* @param base PDM base pointer.
* @param handle PDM eDMA handle pointer.
* @param callback Pointer to user callback function.
* @param userData User parameter passed to the callback function.
* @param dmaHandle eDMA handle pointer, this handle shall be static allocated by users.
*/
void PDM_TransferCreateHandleEDMA(
PDM_Type *base, pdm_edma_handle_t *handle, pdm_edma_callback_t callback, void *userData, edma_handle_t *dmaHandle);
/*!
* @brief Initializes the multi PDM channel interleave type.
*
* This function initializes the PDM DMA handle member interleaveType, it shall be called only when application would
* like to use type kPDM_EDMAMultiChannelInterleavePerChannelBlock, since the default interleaveType is
* kPDM_EDMAMultiChannelInterleavePerChannelSample always
*
* @param handle PDM eDMA handle pointer.
* @param multiChannelInterleaveType Multi channel interleave type.
*/
void PDM_TransferSetMultiChannelInterleaveType(pdm_edma_handle_t *handle,
pdm_edma_multi_channel_interleave_t multiChannelInterleaveType);
/*!
* @brief Configures the PDM channel.
*
* @param base PDM base pointer.
* @param handle PDM eDMA handle pointer.
* @param channel channel index.
* @param config pdm channel configurations.
*/
void PDM_TransferSetChannelConfigEDMA(PDM_Type *base,
pdm_edma_handle_t *handle,
uint32_t channel,
const pdm_channel_config_t *config);
/*!
* @brief Performs a non-blocking PDM receive using eDMA.
*
* @note This interface returns immediately after the transfer initiates. Call
* the PDM_GetReceiveRemainingBytes to poll the transfer status and check whether the PDM transfer is finished.
*
* 1. Scatter gather case:
* This functio support dynamic scatter gather and staic scatter gather,
* a. for the dynamic scatter gather case:
* Application should call PDM_TransferReceiveEDMA function continuously to make sure new receive request is submit
* before the previous one finish. b. for the static scatter gather case: Application should use the link transfer
* feature and make sure a loop link transfer is provided, such as:
* @code pdm_edma_transfer_t pdmXfer[2] =
* {
* {
* .data = s_buffer,
* .dataSize = BUFFER_SIZE,
* .linkTransfer = &pdmXfer[1],
* },
*
* {
* .data = &s_buffer[BUFFER_SIZE],
* .dataSize = BUFFER_SIZE,
* .linkTransfer = &pdmXfer[0]
* },
* };
* @endcode
*
* 2. Multi channel case:
* This function support receive multi pdm channel data, for example, if two channel is requested,
* @code
* PDM_TransferSetChannelConfigEDMA(DEMO_PDM, &s_pdmRxHandle_0, DEMO_PDM_ENABLE_CHANNEL_0, &channelConfig);
* PDM_TransferSetChannelConfigEDMA(DEMO_PDM, &s_pdmRxHandle_0, DEMO_PDM_ENABLE_CHANNEL_1, &channelConfig);
* PDM_TransferReceiveEDMA(DEMO_PDM, &s_pdmRxHandle_0, pdmXfer);
* @endcode
* The output data will be formatted as below if handle->interleaveType =
* kPDM_EDMAMultiChannelInterleavePerChannelSample :
* -------------------------------------------------------------------------
* |CHANNEL0 | CHANNEL1 | CHANNEL0 | CHANNEL1 | CHANNEL0 | CHANNEL 1 | ....|
* -------------------------------------------------------------------------
*
* The output data will be formatted as below if handle->interleaveType = kPDM_EDMAMultiChannelInterleavePerChannelBlock
* :
* ----------------------------------------------------------------------------------------------------------------------
* |CHANNEL3 | CHANNEL3 | CHANNEL3 | .... | CHANNEL4 | CHANNEL 4 | CHANNEL4 |....| CHANNEL5 | CHANNEL 5 | CHANNEL5
* |....|
* ----------------------------------------------------------------------------------------------------------------------
* Note: the dataSize of xfer is the total data size, while application using
* kPDM_EDMAMultiChannelInterleavePerChannelBlock, the buffer size for each PDM channel is channelSize = dataSize /
* channelNums, then there are limitation for this feature,
* 1. 3 DMIC array: the dataSize shall be 4 * (channelSize)
* The addtional buffer is mandantory for edma modulo feature.
* 2. The kPDM_EDMAMultiChannelInterleavePerChannelBlock feature support below dmic array only,
* 2 DMIC array: CHANNEL3, CHANNEL4
* 3 DMIC array: CHANNEL3, CHANNEL4, CHANNEL5
* 4 DMIC array: CHANNEL3, CHANNEL4, CHANNEL5, CHANNEL6
* Any other combinations is not support, that is to SAY, THE FEATURE SUPPORT RECEIVE START FROM CHANNEL3 ONLY AND 4
* MAXIMUM DMIC CHANNELS.
*
* @param base PDM base pointer
* @param handle PDM eDMA handle pointer.
* @param xfer Pointer to DMA transfer structure.
* @retval kStatus_Success Start a PDM eDMA receive successfully.
* @retval kStatus_InvalidArgument The input argument is invalid.
* @retval kStatus_RxBusy PDM is busy receiving data.
*/
status_t PDM_TransferReceiveEDMA(PDM_Type *base, pdm_edma_handle_t *handle, pdm_edma_transfer_t *xfer);
/*!
* @brief Terminate all PDM receive.
*
* This function will clear all transfer slots buffered in the pdm queue. If users only want to abort the
* current transfer slot, please call PDM_TransferAbortReceiveEDMA.
*
* @param base PDM base pointer.
* @param handle PDM eDMA handle pointer.
*/
void PDM_TransferTerminateReceiveEDMA(PDM_Type *base, pdm_edma_handle_t *handle);
/*!
* @brief Aborts a PDM receive using eDMA.
*
* This function only aborts the current transfer slots, the other transfer slots' information still kept
* in the handler. If users want to terminate all transfer slots, just call PDM_TransferTerminateReceiveEDMA.
*
* @param base PDM base pointer
* @param handle PDM eDMA handle pointer.
*/
void PDM_TransferAbortReceiveEDMA(PDM_Type *base, pdm_edma_handle_t *handle);
/*!
* @brief Gets byte count received by PDM.
*
* @param base PDM base pointer
* @param handle PDM eDMA handle pointer.
* @param count Bytes count received by PDM.
* @retval kStatus_Success Succeed get the transfer count.
* @retval kStatus_NoTransferInProgress There is no non-blocking transaction in progress.
*/
status_t PDM_TransferGetReceiveCountEDMA(PDM_Type *base, pdm_edma_handle_t *handle, size_t *count);
/*! @} */
#if defined(__cplusplus)
}
#endif
/*!
* @}
*/
#endif
