drivers/sai/fsl_sai_edma.h

0001 /*
0002  * Copyright (c) 2015, Freescale Semiconductor, Inc.
0003  * Copyright 2016-2021 NXP
0004  * All rights reserved.
0005  *
0006  * SPDX-License-Identifier: BSD-3-Clause
0007  */
0008 #ifndef _FSL_SAI_EDMA_H_
0009 #define _FSL_SAI_EDMA_H_
0010
0011 #include "fsl_edma.h"
0012 #include "fsl_sai.h"
0013
0014 /*!
0015  * @addtogroup sai_edma SAI EDMA Driver
0016  * @ingroup sai
0017  * @{
0018  */
0019
0020 /*******************************************************************************
0021  * Definitions
0022  ******************************************************************************/
0023
0024 /*! @name Driver version */
0025 /*@{*/
0026 #define FSL_SAI_EDMA_DRIVER_VERSION (MAKE_VERSION(2, 5, 0)) /*!< Version 2.5.0 */
0027 /*@}*/
0028
0029 typedef struct sai_edma_handle sai_edma_handle_t;
0030
0031 /*! @brief SAI eDMA transfer callback function for finish and error */
0032 typedef void (*sai_edma_callback_t)(I2S_Type *base, sai_edma_handle_t *handle, status_t status, void *userData);
0033
0034 /*! @brief SAI DMA transfer handle, users should not touch the content of the handle.*/
0035 struct sai_edma_handle
0036 {
0037     edma_handle_t *dmaHandle;     /*!< DMA handler for SAI send */
0038     uint8_t nbytes;               /*!< eDMA minor byte transfer count initially configured. */
0039     uint8_t bytesPerFrame;        /*!< Bytes in a frame */
0040     uint8_t channelMask;          /*!< Enabled channel mask value, reference _sai_channel_mask */
0041     uint8_t channelNums;          /*!< total enabled channel nums */
0042     uint8_t channel;              /*!< Which data channel */
0043     uint8_t count;                /*!< The transfer data count in a DMA request */
0044     uint32_t state;               /*!< Internal state for SAI eDMA transfer */
0045     sai_edma_callback_t callback; /*!< Callback for users while transfer finish or error occurs */
0046     void *userData;               /*!< User callback parameter */
0047     uint8_t tcd[(SAI_XFER_QUEUE_SIZE + 1U) * sizeof(edma_tcd_t)]; /*!< TCD pool for eDMA transfer. */
0048     sai_transfer_t saiQueue[SAI_XFER_QUEUE_SIZE];                 /*!< Transfer queue storing queued transfer. */
0049     size_t transferSize[SAI_XFER_QUEUE_SIZE];                     /*!< Data bytes need to transfer */
0050     volatile uint8_t queueUser;                                   /*!< Index for user to queue transfer. */
0051     volatile uint8_t queueDriver; /*!< Index for driver to get the transfer data and size */
0052 };
0053
0054 /*******************************************************************************
0055  * APIs
0056  ******************************************************************************/
0057 #if defined(__cplusplus)
0058 extern "C" {
0059 #endif
0060
0061 /*!
0062  * @name eDMA Transactional
0063  * @{
0064  */
0065
0066 /*!
0067  * @brief Initializes the SAI eDMA handle.
0068  *
0069  * This function initializes the SAI master DMA handle, which can be used for other SAI master transactional APIs.
0070  * Usually, for a specified SAI instance, call this API once to get the initialized handle.
0071  *
0072  * @param base SAI base pointer.
0073  * @param handle SAI eDMA handle pointer.
0074  * @param base SAI peripheral base address.
0075  * @param callback Pointer to user callback function.
0076  * @param userData User parameter passed to the callback function.
0077  * @param txDmaHandle eDMA handle pointer, this handle shall be static allocated by users.
0078  */
0079 void SAI_TransferTxCreateHandleEDMA(I2S_Type *base,
0080                                     sai_edma_handle_t *handle,
0081                                     sai_edma_callback_t callback,
0082                                     void *userData,
0083                                     edma_handle_t *txDmaHandle);
0084
0085 /*!
0086  * @brief Initializes the SAI Rx eDMA handle.
0087  *
0088  * This function initializes the SAI slave DMA handle, which can be used for other SAI master transactional APIs.
0089  * Usually, for a specified SAI instance, call this API once to get the initialized handle.
0090  *
0091  * @param base SAI base pointer.
0092  * @param handle SAI eDMA handle pointer.
0093  * @param base SAI peripheral base address.
0094  * @param callback Pointer to user callback function.
0095  * @param userData User parameter passed to the callback function.
0096  * @param rxDmaHandle eDMA handle pointer, this handle shall be static allocated by users.
0097  */
0098 void SAI_TransferRxCreateHandleEDMA(I2S_Type *base,
0099                                     sai_edma_handle_t *handle,
0100                                     sai_edma_callback_t callback,
0101                                     void *userData,
0102                                     edma_handle_t *rxDmaHandle);
0103
0104 /*!
0105  * @brief Configures the SAI Tx audio format.
0106  *
0107  * @deprecated Do not use this function.  It has been superceded by @ref SAI_TransferTxSetConfigEDMA
0108  *
0109  * The audio format can be changed at run-time. This function configures the sample rate and audio data
0110  * format to be transferred. This function also sets the eDMA parameter according to formatting requirements.
0111  *
0112  * @param base SAI base pointer.
0113  * @param handle SAI eDMA handle pointer.
0114  * @param format Pointer to SAI audio data format structure.
0115  * @param mclkSourceClockHz SAI master clock source frequency in Hz.
0116  * @param bclkSourceClockHz SAI bit clock source frequency in Hz. If bit clock source is master
0117  * clock, this value should equals to masterClockHz in format.
0118  * @retval kStatus_Success Audio format set successfully.
0119  * @retval kStatus_InvalidArgument The input argument is invalid.
0120  */
0121 void SAI_TransferTxSetFormatEDMA(I2S_Type *base,
0122                                  sai_edma_handle_t *handle,
0123                                  sai_transfer_format_t *format,
0124                                  uint32_t mclkSourceClockHz,
0125                                  uint32_t bclkSourceClockHz);
0126
0127 /*!
0128  * @brief Configures the SAI Rx audio format.
0129  *
0130  * @deprecated Do not use this function.  It has been superceded by @ref SAI_TransferRxSetConfigEDMA
0131  *
0132  * The audio format can be changed at run-time. This function configures the sample rate and audio data
0133  * format to be transferred. This function also sets the eDMA parameter according to formatting requirements.
0134  *
0135  * @param base SAI base pointer.
0136  * @param handle SAI eDMA handle pointer.
0137  * @param format Pointer to SAI audio data format structure.
0138  * @param mclkSourceClockHz SAI master clock source frequency in Hz.
0139  * @param bclkSourceClockHz SAI bit clock source frequency in Hz. If a bit clock source is the master
0140  * clock, this value should equal to masterClockHz in format.
0141  * @retval kStatus_Success Audio format set successfully.
0142  * @retval kStatus_InvalidArgument The input argument is invalid.
0143  */
0144 void SAI_TransferRxSetFormatEDMA(I2S_Type *base,
0145                                  sai_edma_handle_t *handle,
0146                                  sai_transfer_format_t *format,
0147                                  uint32_t mclkSourceClockHz,
0148                                  uint32_t bclkSourceClockHz);
0149
0150 /*!
0151  * @brief Configures the SAI Tx.
0152  *
0153  * @note SAI eDMA supports data transfer in a multiple SAI channels if the FIFO Combine feature is supported.
0154  * To activate the multi-channel transfer enable SAI channels by filling the channelMask
0155  * of sai_transceiver_t with the corresponding values of _sai_channel_mask enum, enable the FIFO Combine
0156  * mode by assigning kSAI_FifoCombineModeEnabledOnWrite to the fifoCombine member of sai_fifo_combine_t
0157  * which is a member of sai_transceiver_t.
0158  * This is an example of multi-channel data transfer configuration step.
0159  *  @code
0160  *   sai_transceiver_t config;
0161  *   SAI_GetClassicI2SConfig(&config, kSAI_WordWidth16bits, kSAI_Stereo, kSAI_Channel0Mask|kSAI_Channel1Mask);
0162  *   config.fifo.fifoCombine = kSAI_FifoCombineModeEnabledOnWrite;
0163  *   SAI_TransferTxSetConfigEDMA(I2S0, &edmaHandle, &config);
0164  *  @endcode
0165  *
0166  * @param base SAI base pointer.
0167  * @param handle SAI eDMA handle pointer.
0168  * @param saiConfig sai configurations.
0169  */
0170 void SAI_TransferTxSetConfigEDMA(I2S_Type *base, sai_edma_handle_t *handle, sai_transceiver_t *saiConfig);
0171
0172 /*!
0173  * @brief Configures the SAI Rx.
0174  *
0175  * @note SAI eDMA supports data transfer in a multiple SAI channels if the FIFO Combine feature is supported.
0176  * To activate the multi-channel transfer enable SAI channels by filling the channelMask
0177  * of sai_transceiver_t with the corresponding values of _sai_channel_mask enum, enable the FIFO Combine
0178  * mode by assigning kSAI_FifoCombineModeEnabledOnRead to the fifoCombine member of sai_fifo_combine_t
0179  * which is a member of sai_transceiver_t.
0180  * This is an example of multi-channel data transfer configuration step.
0181  *  @code
0182  *   sai_transceiver_t config;
0183  *   SAI_GetClassicI2SConfig(&config, kSAI_WordWidth16bits, kSAI_Stereo, kSAI_Channel0Mask|kSAI_Channel1Mask);
0184  *   config.fifo.fifoCombine = kSAI_FifoCombineModeEnabledOnRead;
0185  *   SAI_TransferRxSetConfigEDMA(I2S0, &edmaHandle, &config);
0186  *  @endcode
0187  * @param base SAI base pointer.
0188  * @param handle SAI eDMA handle pointer.
0189  * @param saiConfig sai configurations.
0190  */
0191 void SAI_TransferRxSetConfigEDMA(I2S_Type *base, sai_edma_handle_t *handle, sai_transceiver_t *saiConfig);
0192
0193 /*!
0194  * @brief Performs a non-blocking SAI transfer using DMA.
0195  *
0196  * @note This interface returns immediately after the transfer initiates. Call
0197  * SAI_GetTransferStatus to poll the transfer status and check whether the SAI transfer is finished.
0198  *
0199  * This function support multi channel transfer,
0200  * 1. for the sai IP support fifo combine mode, application should enable the fifo combine mode, no limitation
0201  *    on channel numbers
0202  * 2. for the sai IP not support fifo combine mode, sai edma provide another solution which using
0203  *    EDMA modulo feature, but support 2 or 4 channels only.
0204  *
0205  * @param base SAI base pointer.
0206  * @param handle SAI eDMA handle pointer.
0207  * @param xfer Pointer to the DMA transfer structure.
0208  * @retval kStatus_Success Start a SAI eDMA send successfully.
0209  * @retval kStatus_InvalidArgument The input argument is invalid.
0210  * @retval kStatus_TxBusy SAI is busy sending data.
0211  */
0212 status_t SAI_TransferSendEDMA(I2S_Type *base, sai_edma_handle_t *handle, sai_transfer_t *xfer);
0213
0214 /*!
0215  * @brief Performs a non-blocking SAI receive using eDMA.
0216  *
0217  * @note This interface returns immediately after the transfer initiates. Call
0218  * the SAI_GetReceiveRemainingBytes to poll the transfer status and check whether the SAI transfer is finished.
0219  *
0220  * This function support multi channel transfer,
0221  * 1. for the sai IP support fifo combine mode, application should enable the fifo combine mode, no limitation
0222  *    on channel numbers
0223  * 2. for the sai IP not support fifo combine mode, sai edma provide another solution which using
0224  *    EDMA modulo feature, but support 2 or 4 channels only.
0225  *
0226  * @param base SAI base pointer
0227  * @param handle SAI eDMA handle pointer.
0228  * @param xfer Pointer to DMA transfer structure.
0229  * @retval kStatus_Success Start a SAI eDMA receive successfully.
0230  * @retval kStatus_InvalidArgument The input argument is invalid.
0231  * @retval kStatus_RxBusy SAI is busy receiving data.
0232  */
0233 status_t SAI_TransferReceiveEDMA(I2S_Type *base, sai_edma_handle_t *handle, sai_transfer_t *xfer);
0234
0235 /*!
0236  * @brief Performs a non-blocking SAI loop transfer using eDMA.
0237  *
0238  * @note This function support loop transfer only,such as A->B->...->A, application must be aware of
0239  * that the more counts of the loop transfer, then more tcd memory required, as the function use the tcd pool in
0240  * sai_edma_handle_t, so application could redefine the SAI_XFER_QUEUE_SIZE to determine the proper TCD pool size.
0241  * This function support one sai channel only.
0242  *
0243  * Once the loop transfer start, application can use function SAI_TransferAbortSendEDMA to stop the loop transfer.
0244  *
0245  * @param base SAI base pointer.
0246  * @param handle SAI eDMA handle pointer.
0247  * @param xfer Pointer to the DMA transfer structure, should be a array with elements counts >=1(loopTransferCount).
0248  * @param loopTransferCount the counts of xfer array.
0249  * @retval kStatus_Success Start a SAI eDMA send successfully.
0250  * @retval kStatus_InvalidArgument The input argument is invalid.
0251  */
0252 status_t SAI_TransferSendLoopEDMA(I2S_Type *base,
0253                                   sai_edma_handle_t *handle,
0254                                   sai_transfer_t *xfer,
0255                                   uint32_t loopTransferCount);
0256
0257 /*!
0258  * @brief Performs a non-blocking SAI loop transfer using eDMA.
0259  *
0260  * @note This function support loop transfer only,such as A->B->...->A, application must be aware of
0261  * that the more counts of the loop transfer, then more tcd memory required, as the function use the tcd pool in
0262  * sai_edma_handle_t, so application could redefine the SAI_XFER_QUEUE_SIZE to determine the proper TCD pool size.
0263  * This function support one sai channel only.
0264  *
0265  * Once the loop transfer start, application can use function SAI_TransferAbortReceiveEDMA to stop the loop transfer.
0266  *
0267  * @param base SAI base pointer.
0268  * @param handle SAI eDMA handle pointer.
0269  * @param xfer Pointer to the DMA transfer structure, should be a array with elements counts >=1(loopTransferCount).
0270  * @param loopTransferCount the counts of xfer array.
0271  * @retval kStatus_Success Start a SAI eDMA receive successfully.
0272  * @retval kStatus_InvalidArgument The input argument is invalid.
0273  */
0274 status_t SAI_TransferReceiveLoopEDMA(I2S_Type *base,
0275                                      sai_edma_handle_t *handle,
0276                                      sai_transfer_t *xfer,
0277                                      uint32_t loopTransferCount);
0278
0279 /*!
0280  * @brief Terminate all SAI send.
0281  *
0282  * This function will clear all transfer slots buffered in the sai queue. If users only want to abort the
0283  * current transfer slot, please call SAI_TransferAbortSendEDMA.
0284  *
0285  * @param base SAI base pointer.
0286  * @param handle SAI eDMA handle pointer.
0287  */
0288 void SAI_TransferTerminateSendEDMA(I2S_Type *base, sai_edma_handle_t *handle);
0289
0290 /*!
0291  * @brief Terminate all SAI receive.
0292  *
0293  * This function will clear all transfer slots buffered in the sai queue. If users only want to abort the
0294  * current transfer slot, please call SAI_TransferAbortReceiveEDMA.
0295  *
0296  * @param base SAI base pointer.
0297  * @param handle SAI eDMA handle pointer.
0298  */
0299 void SAI_TransferTerminateReceiveEDMA(I2S_Type *base, sai_edma_handle_t *handle);
0300
0301 /*!
0302  * @brief Aborts a SAI transfer using eDMA.
0303  *
0304  * This function only aborts the current transfer slots, the other transfer slots' information still kept
0305  * in the handler. If users want to terminate all transfer slots, just call SAI_TransferTerminateSendEDMA.
0306  *
0307  * @param base SAI base pointer.
0308  * @param handle SAI eDMA handle pointer.
0309  */
0310 void SAI_TransferAbortSendEDMA(I2S_Type *base, sai_edma_handle_t *handle);
0311
0312 /*!
0313  * @brief Aborts a SAI receive using eDMA.
0314  *
0315  * This function only aborts the current transfer slots, the other transfer slots' information still kept
0316  * in the handler. If users want to terminate all transfer slots, just call SAI_TransferTerminateReceiveEDMA.
0317  *
0318  * @param base SAI base pointer
0319  * @param handle SAI eDMA handle pointer.
0320  */
0321 void SAI_TransferAbortReceiveEDMA(I2S_Type *base, sai_edma_handle_t *handle);
0322
0323 /*!
0324  * @brief Gets byte count sent by SAI.
0325  *
0326  * @param base SAI base pointer.
0327  * @param handle SAI eDMA handle pointer.
0328  * @param count Bytes count sent by SAI.
0329  * @retval kStatus_Success Succeed get the transfer count.
0330  * @retval kStatus_NoTransferInProgress There is no non-blocking transaction in progress.
0331  */
0332 status_t SAI_TransferGetSendCountEDMA(I2S_Type *base, sai_edma_handle_t *handle, size_t *count);
0333
0334 /*!
0335  * @brief Gets byte count received by SAI.
0336  *
0337  * @param base SAI base pointer
0338  * @param handle SAI eDMA handle pointer.
0339  * @param count Bytes count received by SAI.
0340  * @retval kStatus_Success Succeed get the transfer count.
0341  * @retval kStatus_NoTransferInProgress There is no non-blocking transaction in progress.
0342  */
0343 status_t SAI_TransferGetReceiveCountEDMA(I2S_Type *base, sai_edma_handle_t *handle, size_t *count);
0344
0345 /*!
0346  * @brief Gets valid transfer slot.
0347  *
0348  * This function can be used to query the valid transfer request slot that the application can submit.
0349  * It should be called in the critical section, that means the application could call it in the corresponding callback
0350  * function or disable IRQ before calling it in the application, otherwise, the returned value may not correct.
0351  *
0352  * @param base SAI base pointer
0353  * @param handle SAI eDMA handle pointer.
0354  * @retval valid slot count that application submit.
0355  */
0356 uint32_t SAI_TransferGetValidTransferSlotsEDMA(I2S_Type *base, sai_edma_handle_t *handle);
0357
0358 /*! @} */
0359
0360 #if defined(__cplusplus)
0361 }
0362 #endif
0363
0364 /*!
0365  * @}
0366  */
0367 #endif