1 /*
2  * Copyright (c) 2016, Freescale Semiconductor, Inc.
3  * Copyright 2016-2022 NXP
4  * All rights reserved.
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  */
8 #ifndef FSL_DMIC_DMA_H_
9 #define FSL_DMIC_DMA_H_
10 
11 #include "fsl_common.h"
12 #include "fsl_dma.h"
13 
14 /*!
15  * @addtogroup dmic_dma_driver
16  * @{
17  */
18 
19 /*! @file */
20 
21 /*******************************************************************************
22  * Definitions
23  ******************************************************************************/
24 
25 /*!
26  * @name DMIC DMA version
27  * @{
28  */
29 
30 /*! @brief DMIC DMA driver version 2.4.0 */
31 #define FSL_DMIC_DMA_DRIVER_VERSION (MAKE_VERSION(2, 4, 0))
32 /*! @} */
33 
34 /*! @brief DMIC transfer structure. */
35 typedef struct _dmic_transfer
36 {
37     void *data;                     /*!< The buffer of data to be transfer.*/
38     uint8_t dataWidth;              /*!< DMIC support 16bit/32bit */
39     size_t dataSize;                /*!< The byte count to be transfer. */
40     uint8_t dataAddrInterleaveSize; /*!< destination address interleave size */
41 
42     struct _dmic_transfer *linkTransfer; /*!< use to support link transfer */
43 } dmic_transfer_t;
44 
45 /* Forward declaration of the handle typedef. */
46 typedef struct _dmic_dma_handle dmic_dma_handle_t;
47 
48 /*! @brief DMIC transfer callback function. */
49 typedef void (*dmic_dma_transfer_callback_t)(DMIC_Type *base,
50                                              dmic_dma_handle_t *handle,
51                                              status_t status,
52                                              void *userData);
53 
54 /*!
55  * @brief DMIC DMA handle
56  */
57 struct _dmic_dma_handle
58 {
59     DMIC_Type *base;                       /*!< DMIC peripheral base address. */
60     dma_handle_t *rxDmaHandle;             /*!< The DMA RX channel used. */
61     dmic_dma_transfer_callback_t callback; /*!< Callback function. */
62     void *userData;                        /*!< DMIC callback function parameter.*/
63     size_t transferSize;                   /*!< Size of the data to receive. */
64     volatile uint8_t state;                /*!< Internal state of DMIC DMA transfer */
65     uint32_t channel;                      /*!< DMIC channel used. */
66     bool isChannelValid;                   /*!< DMIC channel initialization flag*/
67 
68     dma_descriptor_t *desLink; /*!< descriptor pool pointer */
69     size_t linkNum;            /*!< number of descriptor in descriptors pool */
70 };
71 
72 /*******************************************************************************
73  * API
74  ******************************************************************************/
75 
76 #ifdef __cplusplus
77 extern "C" {
78 #endif /* _cplusplus */
79 
80 /*!
81  * @name DMA transactional
82  * @{
83  */
84 
85 /*!
86  * @brief Initializes the DMIC handle which is used in transactional functions.
87  * @param base DMIC peripheral base address.
88  * @param handle Pointer to dmic_dma_handle_t structure.
89  * @param callback Callback function.
90  * @param userData User data.
91  * @param rxDmaHandle User-requested DMA handle for RX DMA transfer.
92  */
93 status_t DMIC_TransferCreateHandleDMA(DMIC_Type *base,
94                                       dmic_dma_handle_t *handle,
95                                       dmic_dma_transfer_callback_t callback,
96                                       void *userData,
97                                       dma_handle_t *rxDmaHandle);
98 
99 /*!
100  * @brief Receives data using DMA.
101  *
102  * This function receives data using DMA. This is a non-blocking function, which returns
103  * right away. When all data is received, the receive callback function is called.
104  *
105  * @param base USART peripheral base address.
106  * @param handle Pointer to usart_dma_handle_t structure.
107  * @param xfer DMIC DMA transfer structure. See #dmic_transfer_t.
108  * @param channel DMIC start channel number.
109  * @retval kStatus_Success
110  */
111 status_t DMIC_TransferReceiveDMA(DMIC_Type *base, dmic_dma_handle_t *handle, dmic_transfer_t *xfer, uint32_t channel);
112 
113 /*!
114  * @brief Aborts the received data using DMA.
115  *
116  * This function aborts the received data using DMA.
117  *
118  * @param base DMIC peripheral base address
119  * @param handle Pointer to dmic_dma_handle_t structure
120  */
121 void DMIC_TransferAbortReceiveDMA(DMIC_Type *base, dmic_dma_handle_t *handle);
122 
123 /*!
124  * @brief Get the number of bytes that have been received.
125  *
126  * This function gets the number of bytes that have been received.
127  *
128  * @param base DMIC peripheral base address.
129  * @param handle DMIC handle pointer.
130  * @param count Receive bytes count.
131  * @retval kStatus_NoTransferInProgress No receive in progress.
132  * @retval kStatus_InvalidArgument Parameter is invalid.
133  * @retval kStatus_Success Get successfully through the parameter count;
134  */
135 status_t DMIC_TransferGetReceiveCountDMA(DMIC_Type *base, dmic_dma_handle_t *handle, uint32_t *count);
136 
137 /*!
138  * @brief Install DMA descriptor memory.
139  *
140  * This function used to register DMA descriptor memory for linked transfer, a typical case is ping pong
141  * transfer which will request more than one DMA descriptor memory space, it should be called after
142  * DMIC_TransferCreateHandleDMA.
143  * User should be take care about the address of DMA descriptor pool which required align with 16BYTE at least.
144  *
145  * @param handle Pointer to DMA channel transfer handle.
146  * @param linkAddr DMA link descriptor address.
147  * @param linkNum DMA link descriptor number.
148  */
149 void DMIC_InstallDMADescriptorMemory(dmic_dma_handle_t *handle, void *linkAddr, size_t linkNum);
150 
151 /*! @} */
152 
153 #if defined(__cplusplus)
154 }
155 #endif
156 
157 /*! @}*/
158 
159 #endif /* FSL_DMIC_DMA_H_ */
160