1 /*
2  * Copyright (c) 2015, Freescale Semiconductor, Inc.
3  * Copyright 2016-2020, 2022 NXP
4  * All rights reserved.
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  */
8 #ifndef FSL_FLEXIO_SPI_DMA_H_
9 #define FSL_FLEXIO_SPI_DMA_H_
10 
11 #include "fsl_flexio_spi.h"
12 #include "fsl_dma.h"
13 
14 /*!
15  * @addtogroup flexio_dma_spi
16  * @{
17  */
18 
19 /*******************************************************************************
20  * Definitions
21  ******************************************************************************/
22 
23 /*! @name Driver version */
24 /*! @{ */
25 /*! @brief FlexIO SPI DMA driver version 2.3.0. */
26 #define FSL_FLEXIO_SPI_DMA_DRIVER_VERSION (MAKE_VERSION(2, 3, 0))
27 /*! @} */
28 
29 /*! @brief  typedef for flexio_spi_master_dma_handle_t in advance. */
30 typedef struct _flexio_spi_master_dma_handle flexio_spi_master_dma_handle_t;
31 
32 /*! @brief  Slave handle is the same with master handle. */
33 typedef flexio_spi_master_dma_handle_t flexio_spi_slave_dma_handle_t;
34 
35 /*! @brief FlexIO SPI master callback for finished transmit */
36 typedef void (*flexio_spi_master_dma_transfer_callback_t)(FLEXIO_SPI_Type *base,
37                                                           flexio_spi_master_dma_handle_t *handle,
38                                                           status_t status,
39                                                           void *userData);
40 
41 /*! @brief FlexIO SPI slave callback for finished transmit */
42 typedef void (*flexio_spi_slave_dma_transfer_callback_t)(FLEXIO_SPI_Type *base,
43                                                          flexio_spi_slave_dma_handle_t *handle,
44                                                          status_t status,
45                                                          void *userData);
46 
47 /*! @brief FlexIO SPI DMA transfer handle, users should not touch the content of the handle.*/
48 struct _flexio_spi_master_dma_handle
49 {
50     size_t transferSize;                                /*!< Total bytes to be transferred. */
51     bool txInProgress;                                  /*!< Send transfer in progress */
52     bool rxInProgress;                                  /*!< Receive transfer in progress */
53     dma_handle_t *txHandle;                             /*!< DMA handler for SPI send */
54     dma_handle_t *rxHandle;                             /*!< DMA handler for SPI receive */
55     flexio_spi_master_dma_transfer_callback_t callback; /*!< Callback for SPI DMA transfer */
56     void *userData;                                     /*!< User Data for SPI DMA callback */
57 };
58 
59 /*******************************************************************************
60  * APIs
61  ******************************************************************************/
62 #if defined(__cplusplus)
63 extern "C" {
64 #endif
65 
66 /*!
67  * @name DMA Transactional
68  * @{
69  */
70 
71 /*!
72  * @brief Initializes the FLEXO SPI master DMA handle.
73  *
74  * This function initializes the FLEXO SPI master DMA handle which can be used for other FLEXO SPI master transactional
75  * APIs.
76  * Usually, for a specified FLEXO SPI instance, call this API once to get the initialized handle.
77  *
78  * @param base Pointer to FLEXIO_SPI_Type structure.
79  * @param handle Pointer to flexio_spi_master_dma_handle_t structure to store the transfer state.
80  * @param callback SPI callback, NULL means no callback.
81  * @param userData callback function parameter.
82  * @param txHandle User requested DMA handle for FlexIO SPI RX DMA transfer.
83  * @param rxHandle User requested DMA handle for FlexIO SPI TX DMA transfer.
84  * @retval kStatus_Success Successfully create the handle.
85  * @retval kStatus_OutOfRange The FlexIO SPI DMA type/handle table out of range.
86  */
87 status_t FLEXIO_SPI_MasterTransferCreateHandleDMA(FLEXIO_SPI_Type *base,
88                                                   flexio_spi_master_dma_handle_t *handle,
89                                                   flexio_spi_master_dma_transfer_callback_t callback,
90                                                   void *userData,
91                                                   dma_handle_t *txHandle,
92                                                   dma_handle_t *rxHandle);
93 
94 /*!
95  * @brief Performs a non-blocking FlexIO SPI transfer using DMA.
96  *
97  * @note This interface returned immediately after transfer initiates. Call
98  * FLEXIO_SPI_MasterGetTransferCountDMA to poll the transfer status to check
99  * whether the FlexIO SPI transfer is finished.
100  *
101  * @param base Pointer to FLEXIO_SPI_Type structure.
102  * @param handle Pointer to flexio_spi_master_dma_handle_t structure to store the transfer state.
103  * @param xfer Pointer to FlexIO SPI transfer structure.
104  * @retval kStatus_Success Successfully start a transfer.
105  * @retval kStatus_InvalidArgument Input argument is invalid.
106  * @retval kStatus_FLEXIO_SPI_Busy FlexIO SPI is not idle, is running another transfer.
107  */
108 status_t FLEXIO_SPI_MasterTransferDMA(FLEXIO_SPI_Type *base,
109                                       flexio_spi_master_dma_handle_t *handle,
110                                       flexio_spi_transfer_t *xfer);
111 
112 /*!
113  * @brief Aborts a FlexIO SPI transfer using DMA.
114  *
115  * @param base Pointer to FLEXIO_SPI_Type structure.
116  * @param handle FlexIO SPI DMA handle pointer.
117  */
118 void FLEXIO_SPI_MasterTransferAbortDMA(FLEXIO_SPI_Type *base, flexio_spi_master_dma_handle_t *handle);
119 
120 /*!
121  * @brief Gets the remaining bytes for FlexIO SPI DMA transfer.
122  *
123  * @param base Pointer to FLEXIO_SPI_Type structure.
124  * @param handle FlexIO SPI DMA handle pointer.
125  * @param count Number of bytes transferred so far by the non-blocking transaction.
126  */
127 status_t FLEXIO_SPI_MasterTransferGetCountDMA(FLEXIO_SPI_Type *base,
128                                               flexio_spi_master_dma_handle_t *handle,
129                                               size_t *count);
130 
131 /*!
132  * @brief Initializes the FlexIO SPI slave DMA handle.
133  *
134  * This function initializes the FlexIO SPI slave DMA handle.
135  *
136  * @param base Pointer to FLEXIO_SPI_Type structure.
137  * @param handle Pointer to flexio_spi_slave_dma_handle_t structure to store the transfer state.
138  * @param callback SPI callback, NULL means no callback.
139  * @param userData callback function parameter.
140  * @param txHandle User requested DMA handle for FlexIO SPI TX DMA transfer.
141  * @param rxHandle User requested DMA handle for FlexIO SPI RX DMA transfer.
142  */
FLEXIO_SPI_SlaveTransferCreateHandleDMA(FLEXIO_SPI_Type * base,flexio_spi_slave_dma_handle_t * handle,flexio_spi_slave_dma_transfer_callback_t callback,void * userData,dma_handle_t * txHandle,dma_handle_t * rxHandle)143 static inline void FLEXIO_SPI_SlaveTransferCreateHandleDMA(FLEXIO_SPI_Type *base,
144                                                            flexio_spi_slave_dma_handle_t *handle,
145                                                            flexio_spi_slave_dma_transfer_callback_t callback,
146                                                            void *userData,
147                                                            dma_handle_t *txHandle,
148                                                            dma_handle_t *rxHandle)
149 {
150     (void)FLEXIO_SPI_MasterTransferCreateHandleDMA(base, handle, callback, userData, txHandle, rxHandle);
151 }
152 
153 /*!
154  * @brief Performs a non-blocking FlexIO SPI transfer using DMA.
155  *
156  * @note This interface returns immediately after transfer initiates. Call
157  * FLEXIO_SPI_SlaveGetTransferCountDMA to poll the transfer status and
158  * check whether the FlexIO SPI transfer is finished.
159  *
160  * @param base Pointer to FLEXIO_SPI_Type structure.
161  * @param handle Pointer to flexio_spi_slave_dma_handle_t structure to store the transfer state.
162  * @param xfer Pointer to FlexIO SPI transfer structure.
163  * @retval kStatus_Success Successfully start a transfer.
164  * @retval kStatus_InvalidArgument Input argument is invalid.
165  * @retval kStatus_FLEXIO_SPI_Busy FlexIO SPI is not idle, is running another transfer.
166  */
167 status_t FLEXIO_SPI_SlaveTransferDMA(FLEXIO_SPI_Type *base,
168                                      flexio_spi_slave_dma_handle_t *handle,
169                                      flexio_spi_transfer_t *xfer);
170 
171 /*!
172  * @brief Aborts a FlexIO SPI transfer using DMA.
173  *
174  * @param base Pointer to FLEXIO_SPI_Type structure.
175  * @param handle Pointer to flexio_spi_slave_dma_handle_t structure to store the transfer state.
176  */
FLEXIO_SPI_SlaveTransferAbortDMA(FLEXIO_SPI_Type * base,flexio_spi_slave_dma_handle_t * handle)177 static inline void FLEXIO_SPI_SlaveTransferAbortDMA(FLEXIO_SPI_Type *base, flexio_spi_slave_dma_handle_t *handle)
178 {
179     FLEXIO_SPI_MasterTransferAbortDMA(base, handle);
180 }
181 
182 /*!
183  * @brief Gets the remaining bytes to be transferred for FlexIO SPI DMA.
184  *
185  * @param base Pointer to FLEXIO_SPI_Type structure.
186  * @param handle FlexIO SPI DMA handle pointer.
187  * @param count Number of bytes transferred so far by the non-blocking transaction.
188  */
FLEXIO_SPI_SlaveTransferGetCountDMA(FLEXIO_SPI_Type * base,flexio_spi_slave_dma_handle_t * handle,size_t * count)189 static inline status_t FLEXIO_SPI_SlaveTransferGetCountDMA(FLEXIO_SPI_Type *base,
190                                                            flexio_spi_slave_dma_handle_t *handle,
191                                                            size_t *count)
192 {
193     return FLEXIO_SPI_MasterTransferGetCountDMA(base, handle, count);
194 }
195 
196 /*! @} */
197 
198 #if defined(__cplusplus)
199 }
200 #endif
201 
202 /*!
203  * @}
204  */
205 #endif
206