drivers/sai/fsl_sai_sdma.h

0001 /*
0002  * Copyright 2017 - 2021 NXP
0003  * All rights reserved.
0004  *
0005  *
0006  * SPDX-License-Identifier: BSD-3-Clause
0007  */
0008 #ifndef _FSL_SAI_SDMA_H_
0009 #define _FSL_SAI_SDMA_H_
0010
0011 #include "fsl_sai.h"
0012 #include "fsl_sdma.h"
0013
0014 /*!
0015  * @addtogroup sai_sdma SAI SDMA Driver
0016  * @ingroup sai
0017  * @{
0018  */
0019
0020 /*******************************************************************************
0021  * Definitions
0022  ******************************************************************************/
0023
0024 /*! @name Driver version */
0025 /*@{*/
0026 #define FSL_SAI_SDMA_DRIVER_VERSION (MAKE_VERSION(2, 5, 3)) /*!< Version 2.5.3 */
0027 /*@}*/
0028
0029 typedef struct _sai_sdma_handle sai_sdma_handle_t;
0030
0031 /*! @brief SAI SDMA transfer callback function for finish and error */
0032 typedef void (*sai_sdma_callback_t)(I2S_Type *base, sai_sdma_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_sdma_handle
0036 {
0037     sdma_handle_t *dmaHandle;     /*!< DMA handler for SAI send */
0038     uint8_t bytesPerFrame;        /*!< Bytes in a frame */
0039     uint8_t channel;              /*!< start data channel */
0040     uint8_t channelNums;          /*!< total transfer channel numbers, used for multififo */
0041     uint8_t channelMask;          /*!< enabled channel mask value, refernece _sai_channel_mask */
0042     uint8_t fifoOffset;           /*!< fifo address offset between multifo*/
0043     uint32_t count;               /*!< The transfer data count in a DMA request */
0044     uint32_t state;               /*!< Internal state for SAI SDMA transfer */
0045     uint32_t eventSource;         /*!< SAI event source number */
0046     sai_sdma_callback_t callback; /*!< Callback for users while transfer finish or error occurs */
0047     void *userData;               /*!< User callback parameter */
0048     sdma_buffer_descriptor_t bdPool[SAI_XFER_QUEUE_SIZE]; /*!< BD pool for SDMA transfer. */
0049     sai_transfer_t saiQueue[SAI_XFER_QUEUE_SIZE];         /*!< Transfer queue storing queued transfer. */
0050     size_t transferSize[SAI_XFER_QUEUE_SIZE];             /*!< Data bytes need to transfer */
0051     volatile uint8_t queueUser;                           /*!< Index for user to queue transfer. */
0052     volatile uint8_t queueDriver;                         /*!< Index for driver to get the transfer data and size */
0053 };
0054
0055 /*******************************************************************************
0056  * APIs
0057  ******************************************************************************/
0058 #if defined(__cplusplus)
0059 extern "C" {
0060 #endif
0061 /*!
0062  * @name SDMA Transactional
0063  * @{
0064  */
0065
0066 /*!
0067  * @brief Initializes the SAI SDMA 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 SDMA 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 dmaHandle SDMA handle pointer, this handle shall be static allocated by users.
0078  * @param eventSource SAI event source number.
0079  */
0080 void SAI_TransferTxCreateHandleSDMA(I2S_Type *base,
0081                                     sai_sdma_handle_t *handle,
0082                                     sai_sdma_callback_t callback,
0083                                     void *userData,
0084                                     sdma_handle_t *dmaHandle,
0085                                     uint32_t eventSource);
0086
0087 /*!
0088  * @brief Initializes the SAI Rx SDMA handle.
0089  *
0090  * This function initializes the SAI slave DMA handle, which can be used for other SAI master transactional APIs.
0091  * Usually, for a specified SAI instance, call this API once to get the initialized handle.
0092  *
0093  * @param base SAI base pointer.
0094  * @param handle SAI SDMA handle pointer.
0095  * @param base SAI peripheral base address.
0096  * @param callback Pointer to user callback function.
0097  * @param userData User parameter passed to the callback function.
0098  * @param dmaHandle SDMA handle pointer, this handle shall be static allocated by users.
0099  * @param eventSource SAI event source number.
0100  */
0101 void SAI_TransferRxCreateHandleSDMA(I2S_Type *base,
0102                                     sai_sdma_handle_t *handle,
0103                                     sai_sdma_callback_t callback,
0104                                     void *userData,
0105                                     sdma_handle_t *dmaHandle,
0106                                     uint32_t eventSource);
0107
0108 /*!
0109  * @brief Configures the SAI Tx audio format.
0110  *
0111  * The audio format can be changed at run-time. This function configures the sample rate and audio data
0112  * format to be transferred. This function also sets the SDMA parameter according to formatting requirements.
0113  *
0114  * @param base SAI base pointer.
0115  * @param handle SAI SDMA handle pointer.
0116  * @param format Pointer to SAI audio data format structure.
0117  * @param mclkSourceClockHz SAI master clock source frequency in Hz.
0118  * @param bclkSourceClockHz SAI bit clock source frequency in Hz. If bit clock source is master
0119  * clock, this value should equals to masterClockHz in format.
0120  * @retval kStatus_Success Audio format set successfully.
0121  * @retval kStatus_InvalidArgument The input argument is invalid.
0122  */
0123 void SAI_TransferTxSetFormatSDMA(I2S_Type *base,
0124                                  sai_sdma_handle_t *handle,
0125                                  sai_transfer_format_t *format,
0126                                  uint32_t mclkSourceClockHz,
0127                                  uint32_t bclkSourceClockHz);
0128
0129 /*!
0130  * @brief Configures the SAI Rx audio format.
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 SDMA parameter according to formatting requirements.
0134  *
0135  * @param base SAI base pointer.
0136  * @param handle SAI SDMA 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_TransferRxSetFormatSDMA(I2S_Type *base,
0145                                  sai_sdma_handle_t *handle,
0146                                  sai_transfer_format_t *format,
0147                                  uint32_t mclkSourceClockHz,
0148                                  uint32_t bclkSourceClockHz);
0149
0150 /*!
0151  * @brief Performs a non-blocking SAI transfer using DMA.
0152  *
0153  * @note This interface returns immediately after the transfer initiates. Call
0154  * SAI_GetTransferStatus to poll the transfer status and check whether the SAI transfer is finished.
0155  *
0156  * @param base SAI base pointer.
0157  * @param handle SAI SDMA handle pointer.
0158  * @param xfer Pointer to the DMA transfer structure.
0159  * @retval kStatus_Success Start a SAI SDMA send successfully.
0160  * @retval kStatus_InvalidArgument The input argument is invalid.
0161  * @retval kStatus_TxBusy SAI is busy sending data.
0162  */
0163 status_t SAI_TransferSendSDMA(I2S_Type *base, sai_sdma_handle_t *handle, sai_transfer_t *xfer);
0164
0165 /*!
0166  * @brief Performs a non-blocking SAI receive using SDMA.
0167  *
0168  * @note This interface returns immediately after the transfer initiates. Call
0169  * the SAI_GetReceiveRemainingBytes to poll the transfer status and check whether the SAI transfer is finished.
0170  *
0171  * @param base SAI base pointer
0172  * @param handle SAI SDMA handle pointer.
0173  * @param xfer Pointer to DMA transfer structure.
0174  * @retval kStatus_Success Start a SAI SDMA receive successfully.
0175  * @retval kStatus_InvalidArgument The input argument is invalid.
0176  * @retval kStatus_RxBusy SAI is busy receiving data.
0177  */
0178 status_t SAI_TransferReceiveSDMA(I2S_Type *base, sai_sdma_handle_t *handle, sai_transfer_t *xfer);
0179
0180 /*!
0181  * @brief Aborts a SAI transfer using SDMA.
0182  *
0183  * @param base SAI base pointer.
0184  * @param handle SAI SDMA handle pointer.
0185  */
0186 void SAI_TransferAbortSendSDMA(I2S_Type *base, sai_sdma_handle_t *handle);
0187
0188 /*!
0189  * @brief Aborts a SAI receive using SDMA.
0190  *
0191  * @param base SAI base pointer
0192  * @param handle SAI SDMA handle pointer.
0193  */
0194 void SAI_TransferAbortReceiveSDMA(I2S_Type *base, sai_sdma_handle_t *handle);
0195
0196 /*!
0197  * @brief Terminate all the SAI sdma receive transfer.
0198  *
0199  * @param base SAI base pointer.
0200  * @param handle SAI SDMA handle pointer.
0201  */
0202 void SAI_TransferTerminateReceiveSDMA(I2S_Type *base, sai_sdma_handle_t *handle);
0203
0204 /*!
0205  * @brief Terminate all the SAI sdma send transfer.
0206  *
0207  * @param base SAI base pointer.
0208  * @param handle SAI SDMA handle pointer.
0209  */
0210 void SAI_TransferTerminateSendSDMA(I2S_Type *base, sai_sdma_handle_t *handle);
0211
0212 /*!
0213  * brief Configures the SAI RX.
0214  *
0215  * param base SAI base pointer.
0216  * param handle SAI SDMA handle pointer.
0217  * param saiConig sai configurations.
0218  */
0219 void SAI_TransferRxSetConfigSDMA(I2S_Type *base, sai_sdma_handle_t *handle, sai_transceiver_t *saiConfig);
0220
0221 /*!
0222  * brief Configures the SAI Tx.
0223  *
0224  * param base SAI base pointer.
0225  * param handle SAI SDMA handle pointer.
0226  * param saiConig sai configurations.
0227  */
0228 void SAI_TransferTxSetConfigSDMA(I2S_Type *base, sai_sdma_handle_t *handle, sai_transceiver_t *saiConfig);
0229 /*! @} */
0230
0231 #if defined(__cplusplus)
0232 }
0233 #endif
0234
0235 /*!
0236  * @}
0237  */
0238 #endif