1 /*
2  * Copyright (c) 2016, Freescale Semiconductor, Inc.
3  * Copyright 2016-2020 NXP
4  * All rights reserved.
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  */
8 #ifndef _FSL_ESAI_EDMA_H_
9 #define _FSL_ESAI_EDMA_H_
10 
11 #include "fsl_esai.h"
12 #include "fsl_edma.h"
13 
14 /*!
15  * @addtogroup esai_edma
16  * @{
17  */
18 
19 /*******************************************************************************
20  * Definitions
21  ******************************************************************************/
22 
23 /*! @name Driver version */
24 /*@{*/
25 #define FSL_ESAI_EDMA_DRIVER_VERSION (MAKE_VERSION(2, 1, 1)) /*!< Version 2.1.1 */
26 /*@}*/
27 
28 typedef struct _esai_edma_handle esai_edma_handle_t;
29 
30 /*! @brief ESAI eDMA transfer callback function for finish and error */
31 typedef void (*esai_edma_callback_t)(ESAI_Type *base, esai_edma_handle_t *handle, status_t status, void *userData);
32 
33 /*! @brief ESAI DMA transfer handle, users should not touch the content of the handle.*/
34 struct _esai_edma_handle
35 {
36     edma_handle_t *dmaHandle;                        /*!< DMA handler for ESAI send */
37     uint8_t nbytes;                                  /*!< eDMA minor byte transfer count initially configured. */
38     uint8_t bitWidth;                                /*!< Bit width for transfer, 8/16/24/32 bits */
39     uint8_t slotLen;                                 /*!< Slot length of the audio data */
40     uint8_t count;                                   /*!< The transfer data count in a DMA request */
41     uint8_t sectionMap;                              /*!< Section enabled for transfer */
42     uint32_t state;                                  /*!< Internal state for ESAI eDMA transfer */
43     esai_edma_callback_t callback;                   /*!< Callback for users while transfer finish or error occurs */
44     void *userData;                                  /*!< User callback parameter */
45     edma_tcd_t tcd[ESAI_XFER_QUEUE_SIZE + 1U];       /*!< TCD pool for eDMA transfer. */
46     esai_transfer_t esaiQueue[ESAI_XFER_QUEUE_SIZE]; /*!< Transfer queue storing queued transfer. */
47     size_t transferSize[ESAI_XFER_QUEUE_SIZE];       /*!< Data bytes need to transfer */
48     volatile uint8_t queueUser;                      /*!< Index for user to queue transfer. */
49     volatile uint8_t queueDriver;                    /*!< Index for driver to get the transfer data and size */
50 };
51 
52 /*******************************************************************************
53  * APIs
54  ******************************************************************************/
55 #if defined(__cplusplus)
56 extern "C" {
57 #endif
58 
59 /*!
60  * @name eDMA Transactional
61  * @{
62  */
63 
64 /*!
65  * @brief Initializes the ESAI eDMA handle.
66  *
67  * This function initializes the ESAI master DMA handle, which can be used for other ESAI master transactional APIs.
68  * Usually, for a specified ESAI instance, call this API once to get the initialized handle.
69  *
70  * @param base ESAI base pointer.
71  * @param handle ESAI eDMA handle pointer.
72  * @param base ESAI peripheral base address.
73  * @param callback Pointer to user callback function.
74  * @param userData User parameter passed to the callback function.
75  * @param dmaHandle eDMA handle pointer, this handle shall be static allocated by users.
76  */
77 void ESAI_TransferTxCreateHandleEDMA(ESAI_Type *base,
78                                      esai_edma_handle_t *handle,
79                                      esai_edma_callback_t callback,
80                                      void *userData,
81                                      edma_handle_t *dmaHandle);
82 
83 /*!
84  * @brief Initializes the ESAI Rx eDMA handle.
85  *
86  * This function initializes the ESAI slave DMA handle, which can be used for other ESAI master transactional APIs.
87  * Usually, for a specified ESAI instance, call this API once to get the initialized handle.
88  *
89  * @param base ESAI base pointer.
90  * @param handle ESAI eDMA handle pointer.
91  * @param base ESAI peripheral base address.
92  * @param callback Pointer to user callback function.
93  * @param userData User parameter passed to the callback function.
94  * @param dmaHandle eDMA handle pointer, this handle shall be static allocated by users.
95  */
96 void ESAI_TransferRxCreateHandleEDMA(ESAI_Type *base,
97                                      esai_edma_handle_t *handle,
98                                      esai_edma_callback_t callback,
99                                      void *userData,
100                                      edma_handle_t *dmaHandle);
101 
102 /*!
103  * @brief Configures the ESAI Tx audio format.
104  *
105  * The audio format can be changed at run-time. This function configures the sample rate and audio data
106  * format to be transferred. This function also sets the eDMA parameter according to formatting requirements.
107  *
108  * @param base ESAI base pointer.
109  * @param handle ESAI eDMA handle pointer.
110  * @param format Pointer to ESAI audio data format structure.
111  * @param hckClockHz HCK clock frequency in Hz.
112  * @param hclkSourceClockHz HCK clock source frequency in Hz.
113  * @retval kStatus_Success Audio format set successfully.
114  * @retval kStatus_InvalidArgument The input argument is invalid.
115  */
116 void ESAI_TransferTxSetFormatEDMA(ESAI_Type *base,
117                                   esai_edma_handle_t *handle,
118                                   esai_format_t *format,
119                                   uint32_t hckClockHz,
120                                   uint32_t hclkSourceClockHz);
121 
122 /*!
123  * @brief Configures the ESAI Rx audio format.
124  *
125  * The audio format can be changed at run-time. This function configures the sample rate and audio data
126  * format to be transferred. This function also sets the eDMA parameter according to formatting requirements.
127  *
128  * @param base ESAI base pointer.
129  * @param handle ESAI eDMA handle pointer.
130  * @param format Pointer to ESAI audio data format structure.
131  * @param hckClockHz HCK clock frequency in Hz.
132  * @param hclkSourceClockHz HCK clock source frequency in Hz.
133  * @retval kStatus_Success Audio format set successfully.
134  * @retval kStatus_InvalidArgument The input argument is invalid.
135  */
136 void ESAI_TransferRxSetFormatEDMA(ESAI_Type *base,
137                                   esai_edma_handle_t *handle,
138                                   esai_format_t *format,
139                                   uint32_t hckClockHz,
140                                   uint32_t hclkSourceClockHz);
141 
142 /*!
143  * @brief Performs a non-blocking ESAI transfer using DMA.
144  *
145  * @note This interface returns immediately after the transfer initiates. Call
146  * ESAI_GetTransferStatus to poll the transfer status and check whether the ESAI transfer is finished.
147  *
148  * @param base ESAI base pointer.
149  * @param handle ESAI eDMA handle pointer.
150  * @param xfer Pointer to the DMA transfer structure.
151  * @retval kStatus_Success Start a ESAI eDMA send successfully.
152  * @retval kStatus_InvalidArgument The input argument is invalid.
153  * @retval kStatus_TxBusy ESAI is busy sending data.
154  */
155 status_t ESAI_TransferSendEDMA(ESAI_Type *base, esai_edma_handle_t *handle, esai_transfer_t *xfer);
156 
157 /*!
158  * @brief Performs a non-blocking ESAI receive using eDMA.
159  *
160  * @note This interface returns immediately after the transfer initiates. Call
161  * the ESAI_GetReceiveRemainingBytes to poll the transfer status and check whether the ESAI transfer is finished.
162  *
163  * @param base ESAI base pointer
164  * @param handle ESAI eDMA handle pointer.
165  * @param xfer Pointer to DMA transfer structure.
166  * @retval kStatus_Success Start a ESAI eDMA receive successfully.
167  * @retval kStatus_InvalidArgument The input argument is invalid.
168  * @retval kStatus_RxBusy ESAI is busy receiving data.
169  */
170 status_t ESAI_TransferReceiveEDMA(ESAI_Type *base, esai_edma_handle_t *handle, esai_transfer_t *xfer);
171 
172 /*!
173  * @brief Aborts a ESAI transfer using eDMA.
174  *
175  * @param base ESAI base pointer.
176  * @param handle ESAI eDMA handle pointer.
177  */
178 void ESAI_TransferAbortSendEDMA(ESAI_Type *base, esai_edma_handle_t *handle);
179 
180 /*!
181  * @brief Aborts a ESAI receive using eDMA.
182  *
183  * @param base ESAI base pointer
184  * @param handle ESAI eDMA handle pointer.
185  */
186 void ESAI_TransferAbortReceiveEDMA(ESAI_Type *base, esai_edma_handle_t *handle);
187 
188 /*!
189  * @brief Gets byte count sent by ESAI.
190  *
191  * @param base ESAI base pointer.
192  * @param handle ESAI eDMA handle pointer.
193  * @param count Bytes count sent by ESAI.
194  * @retval kStatus_Success Succeed get the transfer count.
195  * @retval kStatus_NoTransferInProgress There is no non-blocking transaction in progress.
196  */
197 status_t ESAI_TransferGetSendCountEDMA(ESAI_Type *base, esai_edma_handle_t *handle, size_t *count);
198 
199 /*!
200  * @brief Gets byte count received by ESAI.
201  *
202  * @param base ESAI base pointer
203  * @param handle ESAI eDMA handle pointer.
204  * @param count Bytes count received by ESAI.
205  * @retval kStatus_Success Succeed get the transfer count.
206  * @retval kStatus_NoTransferInProgress There is no non-blocking transaction in progress.
207  */
208 status_t ESAI_TransferGetReceiveCountEDMA(ESAI_Type *base, esai_edma_handle_t *handle, size_t *count);
209 
210 /*! @} */
211 
212 #if defined(__cplusplus)
213 }
214 #endif
215 
216 /*!
217  * @}
218  */
219 #endif
220