1 /*
2  * Copyright (c) 2015, Freescale Semiconductor, Inc.
3  * Copyright 2016-2019 NXP
4  * All rights reserved.
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  */
8 #ifndef FSL_FLEXIO_I2S_DMA_H_
9 #define FSL_FLEXIO_I2S_DMA_H_
10 
11 #include "fsl_flexio_i2s.h"
12 #include "fsl_dma.h"
13 
14 /*!
15  * @addtogroup flexio_dma_i2s
16  * @{
17  */
18 
19 /*******************************************************************************
20  * Definitions
21  ******************************************************************************/
22 
23 /*! @name Driver version */
24 /*! @{ */
25 /*! @brief FlexIO I2S DMA driver version 2.1.7. */
26 #define FSL_FLEXIO_I2S_DMA_DRIVER_VERSION (MAKE_VERSION(2, 1, 7))
27 /*! @} */
28 
29 typedef struct _flexio_i2s_dma_handle flexio_i2s_dma_handle_t;
30 
31 /*! @brief FlexIO I2S DMA transfer callback function for finish and error */
32 typedef void (*flexio_i2s_dma_callback_t)(FLEXIO_I2S_Type *base,
33                                           flexio_i2s_dma_handle_t *handle,
34                                           status_t status,
35                                           void *userData);
36 
37 /*! @brief FlexIO I2S DMA transfer handle, users should not touch the content of the handle.*/
38 struct _flexio_i2s_dma_handle
39 {
40     dma_handle_t *dmaHandle;            /*!< DMA handler for FlexIO I2S send */
41     uint8_t bytesPerFrame;              /*!< Bytes in a frame */
42     uint32_t state;                     /*!< Internal state for FlexIO I2S DMA transfer */
43     flexio_i2s_dma_callback_t callback; /*!< Callback for users while transfer finish or error occurred */
44     void *userData;                     /*!< User callback parameter */
45     flexio_i2s_transfer_t queue[FLEXIO_I2S_XFER_QUEUE_SIZE]; /*!< Transfer queue storing queued transfer. */
46     size_t transferSize[FLEXIO_I2S_XFER_QUEUE_SIZE];         /*!< Data bytes need to transfer */
47     volatile uint8_t queueUser;                              /*!< Index for user to queue transfer. */
48     volatile uint8_t queueDriver;                            /*!< Index for driver to get the transfer data and size */
49 };
50 
51 /*******************************************************************************
52  * APIs
53  ******************************************************************************/
54 #if defined(__cplusplus)
55 extern "C" {
56 #endif
57 
58 /*!
59  * @name DMA Transactional
60  * @{
61  */
62 
63 /*!
64  * @brief Initializes the FlexIO I2S DMA handle.
65  *
66  * This function initializes the FlexIO I2S master DMA handle which can be used for other FlexIO I2S master
67  * transactional APIs.
68  * Usually, for a specified FlexIO I2S instance, call this API once to get the initialized handle.
69  *
70  * @param base FlexIO I2S peripheral base address.
71  * @param handle FlexIO I2S DMA handle pointer.
72  * @param callback FlexIO I2S DMA callback function called while finished a block.
73  * @param userData User parameter for callback.
74  * @param dmaHandle DMA handle for FlexIO I2S. This handle is a static value allocated by users.
75  */
76 void FLEXIO_I2S_TransferTxCreateHandleDMA(FLEXIO_I2S_Type *base,
77                                           flexio_i2s_dma_handle_t *handle,
78                                           flexio_i2s_dma_callback_t callback,
79                                           void *userData,
80                                           dma_handle_t *dmaHandle);
81 
82 /*!
83  * @brief Initializes the FlexIO I2S Rx DMA handle.
84  *
85  * This function initializes the FlexIO I2S slave DMA handle which can be used for other FlexIO I2S master transactional
86  * APIs.
87  * Usually, for a specified FlexIO I2S instance, call this API once to get the initialized handle.
88  *
89  * @param base FlexIO I2S peripheral base address.
90  * @param handle FlexIO I2S DMA handle pointer.
91  * @param callback FlexIO I2S DMA callback function called while finished a block.
92  * @param userData User parameter for callback.
93  * @param dmaHandle DMA handle for FlexIO I2S. This handle is a static value allocated by users.
94  */
95 void FLEXIO_I2S_TransferRxCreateHandleDMA(FLEXIO_I2S_Type *base,
96                                           flexio_i2s_dma_handle_t *handle,
97                                           flexio_i2s_dma_callback_t callback,
98                                           void *userData,
99                                           dma_handle_t *dmaHandle);
100 
101 /*!
102  * @brief Configures the FlexIO I2S Tx audio format.
103  *
104  * Audio format can be changed at run-time of FlexIO I2S. This function configures the sample rate and audio data
105  * format to be transferred. This function also sets the DMA parameter according to the format.
106  *
107  * @param base FlexIO I2S peripheral base address.
108  * @param handle FlexIO I2S DMA handle pointer
109  * @param format Pointer to FlexIO I2S audio data format structure.
110  * @param srcClock_Hz FlexIO I2S clock source frequency in Hz. It should be 0 while in slave mode.
111  */
112 void FLEXIO_I2S_TransferSetFormatDMA(FLEXIO_I2S_Type *base,
113                                      flexio_i2s_dma_handle_t *handle,
114                                      flexio_i2s_format_t *format,
115                                      uint32_t srcClock_Hz);
116 
117 /*!
118  * @brief Performs a non-blocking FlexIO I2S transfer using DMA.
119  *
120  * @note This interface returns immediately after transfer initiates. Call
121  * FLEXIO_I2S_GetTransferStatus to poll the transfer status and check whether FLEXIO I2S transfer finished.
122  *
123  * @param base FlexIO I2S peripheral base address.
124  * @param handle FlexIO I2S DMA handle pointer.
125  * @param xfer Pointer to DMA transfer structure.
126  * @retval kStatus_Success Start a FlexIO I2S DMA send successfully.
127  * @retval kStatus_InvalidArgument The input arguments is invalid.
128  * @retval kStatus_TxBusy FlexIO I2S is busy sending data.
129  */
130 status_t FLEXIO_I2S_TransferSendDMA(FLEXIO_I2S_Type *base,
131                                     flexio_i2s_dma_handle_t *handle,
132                                     flexio_i2s_transfer_t *xfer);
133 
134 /*!
135  * @brief Performs a non-blocking FlexIO I2S receive using DMA.
136  *
137  * @note This interface returns immediately after transfer initiates. Call
138  * FLEXIO_I2S_GetReceiveRemainingBytes to poll the transfer status to check whether the FlexIO I2S transfer is finished.
139  *
140  * @param base FlexIO I2S peripheral base address.
141  * @param handle FlexIO I2S DMA handle pointer.
142  * @param xfer Pointer to DMA transfer structure.
143  * @retval kStatus_Success Start a FlexIO I2S DMA receive successfully.
144  * @retval kStatus_InvalidArgument The input arguments is invalid.
145  * @retval kStatus_RxBusy FlexIO I2S is busy receiving data.
146  */
147 status_t FLEXIO_I2S_TransferReceiveDMA(FLEXIO_I2S_Type *base,
148                                        flexio_i2s_dma_handle_t *handle,
149                                        flexio_i2s_transfer_t *xfer);
150 
151 /*!
152  * @brief Aborts a FlexIO I2S transfer using DMA.
153  *
154  * @param base FlexIO I2S peripheral base address.
155  * @param handle FlexIO I2S DMA handle pointer.
156  */
157 void FLEXIO_I2S_TransferAbortSendDMA(FLEXIO_I2S_Type *base, flexio_i2s_dma_handle_t *handle);
158 
159 /*!
160  * @brief Aborts a FlexIO I2S receive using DMA.
161  *
162  * @param base FlexIO I2S peripheral base address.
163  * @param handle FlexIO I2S DMA handle pointer.
164  */
165 void FLEXIO_I2S_TransferAbortReceiveDMA(FLEXIO_I2S_Type *base, flexio_i2s_dma_handle_t *handle);
166 
167 /*!
168  * @brief Gets the remaining bytes to be sent.
169  *
170  * @param base FlexIO I2S peripheral base address.
171  * @param handle FlexIO I2S DMA handle pointer.
172  * @param count Bytes sent.
173  * @retval kStatus_Success Succeed get the transfer count.
174  * @retval kStatus_NoTransferInProgress There is not a non-blocking transaction currently in progress.
175  */
176 status_t FLEXIO_I2S_TransferGetSendCountDMA(FLEXIO_I2S_Type *base, flexio_i2s_dma_handle_t *handle, size_t *count);
177 
178 /*!
179  * @brief Gets the remaining bytes to be received.
180  *
181  * @param base FlexIO I2S peripheral base address.
182  * @param handle FlexIO I2S DMA handle pointer.
183  * @param count Bytes received.
184  * @retval kStatus_Success Succeed get the transfer count.
185  * @retval kStatus_NoTransferInProgress There is not a non-blocking transaction currently in progress.
186  */
187 status_t FLEXIO_I2S_TransferGetReceiveCountDMA(FLEXIO_I2S_Type *base, flexio_i2s_dma_handle_t *handle, size_t *count);
188 
189 /*! @} */
190 
191 #if defined(__cplusplus)
192 }
193 #endif
194 
195 /*!
196  * @}
197  */
198 #endif
199