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_I2S_DMA_H_
9 #define _FSL_I2S_DMA_H_
10 
11 #include "fsl_device_registers.h"
12 #include "fsl_common.h"
13 #include "fsl_flexcomm.h"
14 
15 #include "fsl_dma.h"
16 #include "fsl_i2s.h"
17 
18 /*******************************************************************************
19  * Definitions
20  ******************************************************************************/
21 
22 /*!
23  * @addtogroup i2s_dma_driver
24  * @{
25  */
26 
27 /*! @name Driver version */
28 /*@{*/
29 /*! @brief I2S DMA driver version 2.2.2. */
30 #define FSL_I2S_DMA_DRIVER_VERSION (MAKE_VERSION(2, 2, 2))
31 /*@}*/
32 
33 /*! @brief Members not to be accessed / modified outside of the driver. */
34 typedef struct _i2s_dma_handle i2s_dma_handle_t;
35 
36 /*!
37  * @brief Callback function invoked from DMA API on completion.
38  *
39  * @param base I2S base pointer.
40  * @param handle pointer to I2S transaction.
41  * @param completionStatus status of the transaction.
42  * @param userData optional pointer to user arguments data.
43  */
44 typedef void (*i2s_dma_transfer_callback_t)(I2S_Type *base,
45                                             i2s_dma_handle_t *handle,
46                                             status_t completionStatus,
47                                             void *userData);
48 /*! @brief i2s dma handle */
49 struct _i2s_dma_handle
50 {
51     uint32_t state;                                    /*!< Internal state of I2S DMA transfer */
52     uint8_t bytesPerFrame;                             /*!< bytes per frame */
53     i2s_dma_transfer_callback_t completionCallback;    /*!< Callback function pointer */
54     void *userData;                                    /*!< Application data passed to callback */
55     dma_handle_t *dmaHandle;                           /*!< DMA handle */
56     volatile i2s_transfer_t i2sQueue[I2S_NUM_BUFFERS]; /*!< Transfer queue storing transfer buffers */
57     volatile uint8_t queueUser;                        /*!< Queue index where user's next transfer will be stored */
58     volatile uint8_t queueDriver;                      /*!< Queue index of buffer actually used by the driver */
59 };
60 
61 /*******************************************************************************
62  * API
63  ******************************************************************************/
64 
65 #if defined(__cplusplus)
66 extern "C" {
67 #endif
68 
69 /*!
70  * @name Initialization and deinitialization
71  * @{
72  */
73 
74 /*! @} */
75 
76 /*!
77  * @name DMA API
78  * @{
79  */
80 
81 /*!
82  * @brief Initializes handle for transfer of audio data.
83  *
84  * @param base I2S base pointer.
85  * @param handle pointer to handle structure.
86  * @param dmaHandle pointer to dma handle structure.
87  * @param callback function to be called back when transfer is done or fails.
88  * @param userData pointer to data passed to callback.
89  */
90 void I2S_TxTransferCreateHandleDMA(I2S_Type *base,
91                                    i2s_dma_handle_t *handle,
92                                    dma_handle_t *dmaHandle,
93                                    i2s_dma_transfer_callback_t callback,
94                                    void *userData);
95 
96 /*!
97  * @brief Begins or queue sending of the given data.
98  *
99  * @param base I2S base pointer.
100  * @param handle pointer to handle structure.
101  * @param transfer data buffer.
102  *
103  * @retval kStatus_Success
104  * @retval kStatus_I2S_Busy if all queue slots are occupied with unsent buffers.
105  */
106 status_t I2S_TxTransferSendDMA(I2S_Type *base, i2s_dma_handle_t *handle, i2s_transfer_t transfer);
107 
108 /*!
109  * @brief Aborts transfer of data.
110  *
111  * @param base I2S base pointer.
112  * @param handle pointer to handle structure.
113  */
114 void I2S_TransferAbortDMA(I2S_Type *base, i2s_dma_handle_t *handle);
115 
116 /*!
117  * @brief Initializes handle for reception of audio data.
118  *
119  * @param base I2S base pointer.
120  * @param handle pointer to handle structure.
121  * @param dmaHandle pointer to dma handle structure.
122  * @param callback function to be called back when transfer is done or fails.
123  * @param userData pointer to data passed to callback.
124  */
125 void I2S_RxTransferCreateHandleDMA(I2S_Type *base,
126                                    i2s_dma_handle_t *handle,
127                                    dma_handle_t *dmaHandle,
128                                    i2s_dma_transfer_callback_t callback,
129                                    void *userData);
130 
131 /*!
132  * @brief Begins or queue reception of data into given buffer.
133  *
134  * @param base I2S base pointer.
135  * @param handle pointer to handle structure.
136  * @param transfer data buffer.
137  *
138  * @retval kStatus_Success
139  * @retval kStatus_I2S_Busy if all queue slots are occupied with buffers
140  *         which are not full.
141  */
142 status_t I2S_RxTransferReceiveDMA(I2S_Type *base, i2s_dma_handle_t *handle, i2s_transfer_t transfer);
143 
144 /*!
145  * @brief Invoked from DMA interrupt handler.
146  *
147  * @param handle pointer to DMA handle structure.
148  * @param userData argument for user callback.
149  * @param transferDone if transfer was done.
150  * @param tcds
151  */
152 void I2S_DMACallback(dma_handle_t *handle, void *userData, bool transferDone, uint32_t tcds);
153 
154 /*! @} */
155 
156 /*! @} */
157 
158 #if defined(__cplusplus)
159 }
160 #endif
161 
162 #endif /* _FSL_I2S_DMA_H_ */
163