1 /*
2  * Copyright 2022 NXP
3  * All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  */
7 
8 #ifndef FSL_LPSPI_EDMA_H_
9 #define FSL_LPSPI_EDMA_H_
10 
11 #include "fsl_lpspi.h"
12 #include "fsl_edma.h"
13 
14 /*!
15  * @addtogroup lpspi_edma_driver
16  * @{
17  */
18 
19 /***********************************************************************************************************************
20  * Definitions
21  **********************************************************************************************************************/
22 /*! @name Driver version */
23 /*@{*/
24 /*! @brief LPSPI EDMA driver version. */
25 #define FSL_LPSPI_EDMA_DRIVER_VERSION (MAKE_VERSION(2, 1, 0))
26 /*@}*/
27 
28 /*!
29  * @brief Forward declaration of the _lpspi_master_edma_handle typedefs.
30  */
31 typedef struct _lpspi_master_edma_handle lpspi_master_edma_handle_t;
32 
33 /*!
34  * @brief Forward declaration of the _lpspi_slave_edma_handle typedefs.
35  */
36 typedef struct _lpspi_slave_edma_handle lpspi_slave_edma_handle_t;
37 
38 /*!
39  * @brief Completion callback function pointer type.
40  *
41  * @param base LPSPI peripheral base address.
42  * @param handle Pointer to the handle for the LPSPI master.
43  * @param status Success or error code describing whether the transfer completed.
44  * @param userData Arbitrary pointer-dataSized value passed from the application.
45  */
46 typedef void (*lpspi_master_edma_transfer_callback_t)(LPSPI_Type *base,
47                                                       lpspi_master_edma_handle_t *handle,
48                                                       status_t status,
49                                                       void *userData);
50 /*!
51  * @brief Completion callback function pointer type.
52  *
53  * @param base LPSPI peripheral base address.
54  * @param handle Pointer to the handle for the LPSPI slave.
55  * @param status Success or error code describing whether the transfer completed.
56  * @param userData Arbitrary pointer-dataSized value passed from the application.
57  */
58 typedef void (*lpspi_slave_edma_transfer_callback_t)(LPSPI_Type *base,
59                                                      lpspi_slave_edma_handle_t *handle,
60                                                      status_t status,
61                                                      void *userData);
62 
63 /*! @brief LPSPI master eDMA transfer handle structure used for transactional API. */
64 struct _lpspi_master_edma_handle
65 {
66     volatile bool isPcsContinuous; /*!< Is PCS continuous in transfer. */
67 
68     volatile bool isByteSwap; /*!< A flag that whether should byte swap. */
69 
70     volatile uint8_t fifoSize; /*!< FIFO dataSize. */
71 
72     volatile uint8_t rxWatermark; /*!< Rx watermark. */
73 
74     volatile uint8_t bytesEachWrite; /*!< Bytes for each write TDR. */
75     volatile uint8_t bytesEachRead;  /*!< Bytes for each read RDR. */
76 
77     volatile uint8_t bytesLastRead;    /*!< Bytes for last read RDR. */
78     volatile bool isThereExtraRxBytes; /*!< Is there extra RX byte. */
79 
80     uint8_t *volatile txData;             /*!< Send buffer. */
81     uint8_t *volatile rxData;             /*!< Receive buffer. */
82     volatile size_t txRemainingByteCount; /*!< Number of bytes remaining to send.*/
83     volatile size_t rxRemainingByteCount; /*!< Number of bytes remaining to receive.*/
84 
85     volatile uint32_t writeRegRemainingTimes; /*!< Write TDR register remaining times. */
86     volatile uint32_t readRegRemainingTimes;  /*!< Read RDR register remaining times. */
87 
88     uint32_t totalByteCount; /*!< Number of transfer bytes*/
89 
90     uint32_t txBuffIfNull; /*!< Used if there is not txData for DMA purpose.*/
91     uint32_t rxBuffIfNull; /*!< Used if there is not rxData for DMA purpose.*/
92 
93     uint32_t transmitCommand; /*!< Used to write TCR for DMA purpose.*/
94 
95     volatile uint8_t state; /*!< LPSPI transfer state , _lpspi_transfer_state.*/
96 
97     uint8_t nbytes; /*!< eDMA minor byte transfer count initially configured. */
98 
99     lpspi_master_edma_transfer_callback_t callback; /*!< Completion callback. */
100     void *userData;                                 /*!< Callback user data. */
101 
102     edma_handle_t *edmaRxRegToRxDataHandle; /*!<edma_handle_t handle point used for RxReg to RxData buff*/
103     edma_handle_t *edmaTxDataToTxRegHandle; /*!<edma_handle_t handle point used for TxData to TxReg buff*/
104 
105     edma_tcd_t lpspiSoftwareTCD[3]; /*!<SoftwareTCD, internal used*/
106 };
107 
108 /*! @brief LPSPI slave eDMA transfer handle structure used for transactional API.*/
109 struct _lpspi_slave_edma_handle
110 {
111     volatile bool isByteSwap; /*!< A flag that whether should byte swap. */
112 
113     volatile uint8_t fifoSize; /*!< FIFO dataSize. */
114 
115     volatile uint8_t rxWatermark; /*!< Rx watermark. */
116 
117     volatile uint8_t bytesEachWrite; /*!< Bytes for each write TDR. */
118     volatile uint8_t bytesEachRead;  /*!< Bytes for each read RDR. */
119 
120     volatile uint8_t bytesLastRead;    /*!< Bytes for last read RDR. */
121     volatile bool isThereExtraRxBytes; /*!< Is there extra RX byte. */
122 
123     uint8_t nbytes; /*!< eDMA minor byte transfer count initially configured. */
124 
125     uint8_t *volatile txData;             /*!< Send buffer. */
126     uint8_t *volatile rxData;             /*!< Receive buffer. */
127     volatile size_t txRemainingByteCount; /*!< Number of bytes remaining to send.*/
128     volatile size_t rxRemainingByteCount; /*!< Number of bytes remaining to receive.*/
129 
130     volatile uint32_t writeRegRemainingTimes; /*!< Write TDR register remaining times. */
131     volatile uint32_t readRegRemainingTimes;  /*!< Read RDR register remaining times. */
132 
133     uint32_t totalByteCount; /*!< Number of transfer bytes*/
134 
135     uint32_t txBuffIfNull; /*!< Used if there is not txData for DMA purpose.*/
136     uint32_t rxBuffIfNull; /*!< Used if there is not rxData for DMA purpose.*/
137 
138     volatile uint8_t state; /*!< LPSPI transfer state.*/
139 
140     uint32_t errorCount; /*!< Error count for slave transfer.*/
141 
142     lpspi_slave_edma_transfer_callback_t callback; /*!< Completion callback. */
143     void *userData;                                /*!< Callback user data. */
144 
145     edma_handle_t *edmaRxRegToRxDataHandle; /*!<edma_handle_t handle point used for RxReg to RxData buff*/
146     edma_handle_t *edmaTxDataToTxRegHandle; /*!<edma_handle_t handle point used for TxData to TxReg*/
147 
148     edma_tcd_t lpspiSoftwareTCD[2]; /*!<SoftwareTCD, internal used*/
149 };
150 
151 /***********************************************************************************************************************
152  * API
153  **********************************************************************************************************************/
154 #if defined(__cplusplus)
155 extern "C" {
156 #endif /*_cplusplus*/
157 
158 /*Transactional APIs*/
159 
160 /*!
161  * @brief Initializes the LPSPI master eDMA handle.
162  *
163  * This function initializes the LPSPI eDMA handle which can be used for other LPSPI transactional APIs.  Usually, for a
164  * specified LPSPI instance, call this API once to get the initialized handle.
165  *
166  * Note that the LPSPI eDMA has a separated (Rx and Tx as two sources) or shared (Rx  and Tx are the same source) DMA
167  * request source.
168  * (1) For a separated DMA request source, enable and set the Rx DMAMUX source for edmaRxRegToRxDataHandle and
169  * Tx DMAMUX source for edmaTxDataToTxRegHandle.
170  * (2) For a shared DMA request source, enable and set the Rx/Tx DMAMUX source for edmaRxRegToRxDataHandle.
171  *
172  * @param base LPSPI peripheral base address.
173  * @param handle LPSPI handle pointer to lpspi_master_edma_handle_t.
174  * @param callback LPSPI callback.
175  * @param userData callback function parameter.
176  * @param edmaRxRegToRxDataHandle edmaRxRegToRxDataHandle pointer to edma_handle_t.
177  * @param edmaTxDataToTxRegHandle edmaTxDataToTxRegHandle pointer to edma_handle_t.
178  */
179 void LPSPI_MasterTransferCreateHandleEDMA(LPSPI_Type *base,
180                                           lpspi_master_edma_handle_t *handle,
181                                           lpspi_master_edma_transfer_callback_t callback,
182                                           void *userData,
183                                           edma_handle_t *edmaRxRegToRxDataHandle,
184                                           edma_handle_t *edmaTxDataToTxRegHandle);
185 
186 /*!
187  * @brief LPSPI master transfer data using eDMA.
188  *
189  * This function transfers data using eDMA. This is a non-blocking function, which returns right away. When all data
190  * is transferred, the callback function is called.
191  *
192  * Note:
193  * The transfer data size should be an integer multiple of bytesPerFrame if bytesPerFrame is less than or equal to 4.
194  * For bytesPerFrame greater than 4:
195  * The transfer data size should be equal to bytesPerFrame if the bytesPerFrame is not an integer multiple of 4.
196  * Otherwise, the transfer data size can be an integer multiple of bytesPerFrame.
197  *
198  * @param base LPSPI peripheral base address.
199  * @param handle pointer to lpspi_master_edma_handle_t structure which stores the transfer state.
200  * @param transfer pointer to lpspi_transfer_t structure.
201  * @return status of status_t.
202  */
203 status_t LPSPI_MasterTransferEDMA(LPSPI_Type *base, lpspi_master_edma_handle_t *handle, lpspi_transfer_t *transfer);
204 
205 /*!
206  * @brief LPSPI master config transfer parameter while using eDMA.
207  *
208  * This function is preparing to transfer data using eDMA, work with LPSPI_MasterTransferEDMALite.
209  *
210  * @param base LPSPI peripheral base address.
211  * @param handle pointer to lpspi_master_edma_handle_t structure which stores the transfer state.
212  * @param configFlags transfer configuration flags. @ref _lpspi_transfer_config_flag_for_master.
213  * @return Indicates whether LPSPI master transfer was successful or not.
214  * @retval kStatus_Success          Execution successfully.
215  * @retval kStatus_LPSPI_Busy       The LPSPI device is busy.
216  */
217 status_t LPSPI_MasterTransferPrepareEDMALite(LPSPI_Type *base, lpspi_master_edma_handle_t *handle, uint32_t configFlags);
218 
219 /*!
220  * @brief LPSPI master transfer data using eDMA without configs.
221  *
222  * This function transfers data using eDMA. This is a non-blocking function, which returns right away. When all data
223  * is transferred, the callback function is called.
224  *
225  * Note:
226  * This API is only for transfer through DMA without configuration.
227  * Before calling this API, you must call LPSPI_MasterTransferPrepareEDMALite to configure it once.
228  * The transfer data size should be an integer multiple of bytesPerFrame if bytesPerFrame is less than or equal to 4.
229  * For bytesPerFrame greater than 4:
230  * The transfer data size should be equal to bytesPerFrame if the bytesPerFrame is not an integer multiple of 4.
231  * Otherwise, the transfer data size can be an integer multiple of bytesPerFrame.
232  *
233  * @param base LPSPI peripheral base address.
234  * @param handle pointer to lpspi_master_edma_handle_t structure which stores the transfer state.
235  * @param transfer pointer to lpspi_transfer_t structure, config field is not uesed.
236  * @return Indicates whether LPSPI master transfer was successful or not.
237  * @retval kStatus_Success          Execution successfully.
238  * @retval kStatus_LPSPI_Busy       The LPSPI device is busy.
239  * @retval kStatus_InvalidArgument  The transfer structure is invalid.
240  */
241 status_t LPSPI_MasterTransferEDMALite(LPSPI_Type *base, lpspi_master_edma_handle_t *handle, lpspi_transfer_t *transfer);
242 
243 /*!
244  * @brief LPSPI master aborts a transfer which is using eDMA.
245  *
246  * This function aborts a transfer which is using eDMA.
247  *
248  * @param base LPSPI peripheral base address.
249  * @param handle pointer to lpspi_master_edma_handle_t structure which stores the transfer state.
250  */
251 void LPSPI_MasterTransferAbortEDMA(LPSPI_Type *base, lpspi_master_edma_handle_t *handle);
252 
253 /*!
254  * @brief Gets the master eDMA transfer remaining bytes.
255  *
256  * This function gets the master eDMA transfer remaining bytes.
257  *
258  * @param base LPSPI peripheral base address.
259  * @param handle pointer to lpspi_master_edma_handle_t structure which stores the transfer state.
260  * @param count Number of bytes transferred so far by the EDMA transaction.
261  * @return status of status_t.
262  */
263 status_t LPSPI_MasterTransferGetCountEDMA(LPSPI_Type *base, lpspi_master_edma_handle_t *handle, size_t *count);
264 
265 /*!
266  * @brief Initializes the LPSPI slave eDMA handle.
267  *
268  * This function initializes the LPSPI eDMA handle which can be used for other LPSPI transactional APIs.  Usually, for a
269  * specified LPSPI instance, call this API once to get the initialized handle.
270  *
271  * Note that LPSPI eDMA has a separated (Rx and Tx as two sources) or shared (Rx  and Tx as the same source) DMA request
272  * source.
273  *
274  * (1) For a separated DMA request source, enable and set the Rx DMAMUX source for edmaRxRegToRxDataHandle and
275  * Tx DMAMUX source for edmaTxDataToTxRegHandle.
276  * (2) For a shared DMA request source, enable and set the Rx/Rx DMAMUX source for edmaRxRegToRxDataHandle .
277  *
278  * @param base LPSPI peripheral base address.
279  * @param handle LPSPI handle pointer to lpspi_slave_edma_handle_t.
280  * @param callback LPSPI callback.
281  * @param userData callback function parameter.
282  * @param edmaRxRegToRxDataHandle edmaRxRegToRxDataHandle pointer to edma_handle_t.
283  * @param edmaTxDataToTxRegHandle edmaTxDataToTxRegHandle pointer to edma_handle_t.
284  */
285 void LPSPI_SlaveTransferCreateHandleEDMA(LPSPI_Type *base,
286                                          lpspi_slave_edma_handle_t *handle,
287                                          lpspi_slave_edma_transfer_callback_t callback,
288                                          void *userData,
289                                          edma_handle_t *edmaRxRegToRxDataHandle,
290                                          edma_handle_t *edmaTxDataToTxRegHandle);
291 
292 /*!
293  * @brief LPSPI slave transfers data using eDMA.
294  *
295  * This function transfers data using eDMA. This is a non-blocking function, which return right away. When all data
296  * is transferred, the callback function is called.
297  *
298  * Note:
299  * The transfer data size should be an integer multiple of bytesPerFrame if bytesPerFrame is less than or equal to 4.
300  * For bytesPerFrame greater than 4:
301  * The transfer data size should be equal to bytesPerFrame if the bytesPerFrame is not an integer multiple of 4.
302  * Otherwise, the transfer data size can be an integer multiple of bytesPerFrame.
303  *
304  * @param base LPSPI peripheral base address.
305  * @param handle pointer to lpspi_slave_edma_handle_t structure which stores the transfer state.
306  * @param transfer pointer to lpspi_transfer_t structure.
307  * @return status of status_t.
308  */
309 status_t LPSPI_SlaveTransferEDMA(LPSPI_Type *base, lpspi_slave_edma_handle_t *handle, lpspi_transfer_t *transfer);
310 
311 /*!
312  * @brief LPSPI slave aborts a transfer which is using eDMA.
313  *
314  * This function aborts a transfer which is using eDMA.
315  *
316  * @param base LPSPI peripheral base address.
317  * @param handle pointer to lpspi_slave_edma_handle_t structure which stores the transfer state.
318  */
319 void LPSPI_SlaveTransferAbortEDMA(LPSPI_Type *base, lpspi_slave_edma_handle_t *handle);
320 
321 /*!
322  * @brief Gets the slave eDMA transfer remaining bytes.
323  *
324  * This function gets the slave eDMA transfer remaining bytes.
325  *
326  * @param base LPSPI peripheral base address.
327  * @param handle pointer to lpspi_slave_edma_handle_t structure which stores the transfer state.
328  * @param count Number of bytes transferred so far by the eDMA transaction.
329  * @return status of status_t.
330  */
331 status_t LPSPI_SlaveTransferGetCountEDMA(LPSPI_Type *base, lpspi_slave_edma_handle_t *handle, size_t *count);
332 
333 #if defined(__cplusplus)
334 }
335 #endif
336 
337 /*! @}*/
338 
339 #endif /*FSL_LPSPI_EDMA_H_*/
340