1 /*
2  * Copyright 2017 - 2020 NXP
3  * All rights reserved.
4  *
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  */
8 #ifndef _FSL_SAI_SDMA_H_
9 #define _FSL_SAI_SDMA_H_
10 
11 #include "fsl_sai.h"
12 #include "fsl_sdma.h"
13 
14 /*!
15  * @addtogroup sai_sdma
16  * @{
17  */
18 
19 /*******************************************************************************
20  * Definitions
21  ******************************************************************************/
22 
23 /*! @name Driver version */
24 /*@{*/
25 #define FSL_SAI_SDMA_DRIVER_VERSION (MAKE_VERSION(2, 3, 1)) /*!< Version 2.3.1 */
26 /*@}*/
27 
28 typedef struct _sai_sdma_handle sai_sdma_handle_t;
29 
30 /*! @brief SAI SDMA transfer callback function for finish and error */
31 typedef void (*sai_sdma_callback_t)(I2S_Type *base, sai_sdma_handle_t *handle, status_t status, void *userData);
32 
33 /*! @brief SAI DMA transfer handle, users should not touch the content of the handle. */
34 struct _sai_sdma_handle
35 {
36     sdma_handle_t *dmaHandle;     /*!< DMA handler for SAI send */
37     uint8_t bytesPerFrame;        /*!< Bytes in a frame */
38     uint8_t channel;              /*!< start data channel */
39     uint8_t channelNums;          /*!< total transfer channel numbers, used for multififo */
40     uint8_t channelMask;          /*!< enabled channel mask value, refernece _sai_channel_mask */
41     uint8_t fifoOffset;           /*!< fifo address offset between multifo*/
42     uint8_t count;                /*!< The transfer data count in a DMA request */
43     uint32_t state;               /*!< Internal state for SAI SDMA transfer */
44     uint32_t eventSource;         /*!< SAI event source number */
45     sai_sdma_callback_t callback; /*!< Callback for users while transfer finish or error occurs */
46     void *userData;               /*!< User callback parameter */
47     sdma_buffer_descriptor_t bdPool[SAI_XFER_QUEUE_SIZE]; /*!< BD pool for SDMA transfer. */
48     sai_transfer_t saiQueue[SAI_XFER_QUEUE_SIZE];         /*!< Transfer queue storing queued transfer. */
49     size_t transferSize[SAI_XFER_QUEUE_SIZE];             /*!< Data bytes need to transfer */
50     volatile uint8_t queueUser;                           /*!< Index for user to queue transfer. */
51     volatile uint8_t queueDriver;                         /*!< Index for driver to get the transfer data and size */
52 };
53 
54 /*******************************************************************************
55  * APIs
56  ******************************************************************************/
57 #if defined(__cplusplus)
58 extern "C" {
59 #endif
60 /*!
61  * @name SDMA Transactional
62  * @{
63  */
64 
65 /*!
66  * @brief Initializes the SAI SDMA handle.
67  *
68  * This function initializes the SAI master DMA handle, which can be used for other SAI master transactional APIs.
69  * Usually, for a specified SAI instance, call this API once to get the initialized handle.
70  *
71  * @param base SAI base pointer.
72  * @param handle SAI SDMA handle pointer.
73  * @param base SAI peripheral base address.
74  * @param callback Pointer to user callback function.
75  * @param userData User parameter passed to the callback function.
76  * @param dmaHandle SDMA handle pointer, this handle shall be static allocated by users.
77  * @param eventSource SAI event source number.
78  */
79 void SAI_TransferTxCreateHandleSDMA(I2S_Type *base,
80                                     sai_sdma_handle_t *handle,
81                                     sai_sdma_callback_t callback,
82                                     void *userData,
83                                     sdma_handle_t *dmaHandle,
84                                     uint32_t eventSource);
85 
86 /*!
87  * @brief Initializes the SAI Rx SDMA handle.
88  *
89  * This function initializes the SAI slave DMA handle, which can be used for other SAI master transactional APIs.
90  * Usually, for a specified SAI instance, call this API once to get the initialized handle.
91  *
92  * @param base SAI base pointer.
93  * @param handle SAI SDMA handle pointer.
94  * @param base SAI peripheral base address.
95  * @param callback Pointer to user callback function.
96  * @param userData User parameter passed to the callback function.
97  * @param dmaHandle SDMA handle pointer, this handle shall be static allocated by users.
98  * @param eventSource SAI event source number.
99  */
100 void SAI_TransferRxCreateHandleSDMA(I2S_Type *base,
101                                     sai_sdma_handle_t *handle,
102                                     sai_sdma_callback_t callback,
103                                     void *userData,
104                                     sdma_handle_t *dmaHandle,
105                                     uint32_t eventSource);
106 
107 /*!
108  * @brief Configures the SAI Tx audio format.
109  *
110  * The audio format can be changed at run-time. This function configures the sample rate and audio data
111  * format to be transferred. This function also sets the SDMA parameter according to formatting requirements.
112  *
113  * @param base SAI base pointer.
114  * @param handle SAI SDMA handle pointer.
115  * @param format Pointer to SAI audio data format structure.
116  * @param mclkSourceClockHz SAI master clock source frequency in Hz.
117  * @param bclkSourceClockHz SAI bit clock source frequency in Hz. If bit clock source is master
118  * clock, this value should equals to masterClockHz in format.
119  * @retval kStatus_Success Audio format set successfully.
120  * @retval kStatus_InvalidArgument The input argument is invalid.
121  */
122 void SAI_TransferTxSetFormatSDMA(I2S_Type *base,
123                                  sai_sdma_handle_t *handle,
124                                  sai_transfer_format_t *format,
125                                  uint32_t mclkSourceClockHz,
126                                  uint32_t bclkSourceClockHz);
127 
128 /*!
129  * @brief Configures the SAI Rx audio format.
130  *
131  * The audio format can be changed at run-time. This function configures the sample rate and audio data
132  * format to be transferred. This function also sets the SDMA parameter according to formatting requirements.
133  *
134  * @param base SAI base pointer.
135  * @param handle SAI SDMA handle pointer.
136  * @param format Pointer to SAI audio data format structure.
137  * @param mclkSourceClockHz SAI master clock source frequency in Hz.
138  * @param bclkSourceClockHz SAI bit clock source frequency in Hz. If a bit clock source is the master
139  * clock, this value should equal to masterClockHz in format.
140  * @retval kStatus_Success Audio format set successfully.
141  * @retval kStatus_InvalidArgument The input argument is invalid.
142  */
143 void SAI_TransferRxSetFormatSDMA(I2S_Type *base,
144                                  sai_sdma_handle_t *handle,
145                                  sai_transfer_format_t *format,
146                                  uint32_t mclkSourceClockHz,
147                                  uint32_t bclkSourceClockHz);
148 
149 /*!
150  * @brief Performs a non-blocking SAI transfer using DMA.
151  *
152  * @note This interface returns immediately after the transfer initiates. Call
153  * SAI_GetTransferStatus to poll the transfer status and check whether the SAI transfer is finished.
154  *
155  * @param base SAI base pointer.
156  * @param handle SAI SDMA handle pointer.
157  * @param xfer Pointer to the DMA transfer structure.
158  * @retval kStatus_Success Start a SAI SDMA send successfully.
159  * @retval kStatus_InvalidArgument The input argument is invalid.
160  * @retval kStatus_TxBusy SAI is busy sending data.
161  */
162 status_t SAI_TransferSendSDMA(I2S_Type *base, sai_sdma_handle_t *handle, sai_transfer_t *xfer);
163 
164 /*!
165  * @brief Performs a non-blocking SAI receive using SDMA.
166  *
167  * @note This interface returns immediately after the transfer initiates. Call
168  * the SAI_GetReceiveRemainingBytes to poll the transfer status and check whether the SAI transfer is finished.
169  *
170  * @param base SAI base pointer
171  * @param handle SAI SDMA handle pointer.
172  * @param xfer Pointer to DMA transfer structure.
173  * @retval kStatus_Success Start a SAI SDMA receive successfully.
174  * @retval kStatus_InvalidArgument The input argument is invalid.
175  * @retval kStatus_RxBusy SAI is busy receiving data.
176  */
177 status_t SAI_TransferReceiveSDMA(I2S_Type *base, sai_sdma_handle_t *handle, sai_transfer_t *xfer);
178 
179 /*!
180  * @brief Aborts a SAI transfer using SDMA.
181  *
182  * @param base SAI base pointer.
183  * @param handle SAI SDMA handle pointer.
184  */
185 void SAI_TransferAbortSendSDMA(I2S_Type *base, sai_sdma_handle_t *handle);
186 
187 /*!
188  * @brief Aborts a SAI receive using SDMA.
189  *
190  * @param base SAI base pointer
191  * @param handle SAI SDMA handle pointer.
192  */
193 void SAI_TransferAbortReceiveSDMA(I2S_Type *base, sai_sdma_handle_t *handle);
194 
195 /*!
196  * brief Configures the SAI RX.
197  *
198  * param base SAI base pointer.
199  * param handle SAI SDMA handle pointer.
200  * param saiConig sai configurations.
201  */
202 void SAI_TransferRxSetConfigSDMA(I2S_Type *base, sai_sdma_handle_t *handle, sai_transceiver_t *saiConfig);
203 
204 /*!
205  * brief Configures the SAI Tx.
206  *
207  * param base SAI base pointer.
208  * param handle SAI SDMA handle pointer.
209  * param saiConig sai configurations.
210  */
211 void SAI_TransferTxSetConfigSDMA(I2S_Type *base, sai_sdma_handle_t *handle, sai_transceiver_t *saiConfig);
212 /*! @} */
213 
214 #if defined(__cplusplus)
215 }
216 #endif
217 
218 /*!
219  * @}
220  */
221 #endif
222