1 /*
2  * Copyright (c) 2015, Freescale Semiconductor, Inc.
3  * Copyright 2016-2020 NXP
4  * All rights reserved.
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  */
8 #ifndef FSL_SPI_DMA_H_
9 #define FSL_SPI_DMA_H_
10 
11 #include "fsl_spi.h"
12 #include "fsl_dma.h"
13 
14 /*!
15  * @addtogroup spi_dma_driver
16  * @{
17  */
18 
19 /*******************************************************************************
20  * Definitions
21  ******************************************************************************/
22 
23 /*! @name Driver version */
24 /*! @{ */
25 /*! @brief SPI DMA driver version. */
26 #define FSL_SPI_DMA_DRIVER_VERSION (MAKE_VERSION(2, 1, 1))
27 /*! @} */
28 
29 typedef struct _spi_dma_handle spi_dma_handle_t;
30 
31 /*! @brief SPI DMA callback called at the end of transfer. */
32 typedef void (*spi_dma_callback_t)(SPI_Type *base, spi_dma_handle_t *handle, status_t status, void *userData);
33 
34 /*! @brief SPI DMA transfer handle, users should not touch the content of the handle.*/
35 struct _spi_dma_handle
36 {
37     bool txInProgress;           /*!< Send transfer finished */
38     bool rxInProgress;           /*!< Receive transfer finished */
39     dma_handle_t *txHandle;      /*!< DMA handler for SPI send */
40     dma_handle_t *rxHandle;      /*!< DMA handler for SPI receive */
41     uint8_t bytesPerFrame;       /*!< Bytes in a frame for SPI transfer */
42     spi_dma_callback_t callback; /*!< Callback for SPI DMA transfer */
43     void *userData;              /*!< User Data for SPI DMA callback */
44     uint32_t state;              /*!< Internal state of SPI DMA transfer */
45     size_t transferSize;         /*!< Bytes need to be transfer */
46 };
47 
48 /*******************************************************************************
49  * APIs
50  ******************************************************************************/
51 #if defined(__cplusplus)
52 extern "C" {
53 #endif
54 
55 /*!
56  * @name DMA Transactional
57  * @{
58  */
59 
60 /*!
61  * @brief Initialize the SPI master DMA handle.
62  *
63  * This function initializes the SPI master DMA handle which can be used for other SPI master transactional APIs.
64  * Usually, for a specified SPI instance, user need only call this API once to get the initialized handle.
65  *
66  * @param base SPI peripheral base address.
67  * @param handle SPI handle pointer.
68  * @param callback User callback function called at the end of a transfer.
69  * @param userData User data for callback.
70  * @param txHandle DMA handle pointer for SPI Tx, the handle shall be static allocated by users.
71  * @param rxHandle DMA handle pointer for SPI Rx, the handle shall be static allocated by users.
72  */
73 void SPI_MasterTransferCreateHandleDMA(SPI_Type *base,
74                                        spi_dma_handle_t *handle,
75                                        spi_dma_callback_t callback,
76                                        void *userData,
77                                        dma_handle_t *txHandle,
78                                        dma_handle_t *rxHandle);
79 
80 /*!
81  * @brief Perform a non-blocking SPI transfer using DMA.
82  *
83  * @note This interface returned immediately after transfer initiates, users should call
84  * SPI_GetTransferStatus to poll the transfer status to check whether SPI transfer finished.
85  *
86  * @param base SPI peripheral base address.
87  * @param handle SPI DMA handle pointer.
88  * @param xfer Pointer to dma transfer structure.
89  * @retval kStatus_Success Successfully start a transfer.
90  * @retval kStatus_InvalidArgument Input argument is invalid.
91  * @retval kStatus_SPI_Busy SPI is not idle, is running another transfer.
92  */
93 status_t SPI_MasterTransferDMA(SPI_Type *base, spi_dma_handle_t *handle, spi_transfer_t *xfer);
94 
95 /*!
96  * @brief Abort a SPI transfer using DMA.
97  *
98  * @param base SPI peripheral base address.
99  * @param handle SPI DMA handle pointer.
100  */
101 void SPI_MasterTransferAbortDMA(SPI_Type *base, spi_dma_handle_t *handle);
102 
103 /*!
104  * @brief Get the transferred bytes for SPI slave DMA.
105  *
106  * @param base SPI peripheral base address.
107  * @param handle SPI DMA handle pointer.
108  * @param count Transferred bytes.
109  * @retval kStatus_SPI_Success Succeed get the transfer count.
110  * @retval kStatus_NoTransferInProgress There is not a non-blocking transaction currently in progress.
111  */
112 status_t SPI_MasterTransferGetCountDMA(SPI_Type *base, spi_dma_handle_t *handle, size_t *count);
113 
114 /*!
115  * @brief Initialize the SPI slave DMA handle.
116  *
117  * This function initializes the SPI slave DMA handle which can be used for other SPI master transactional APIs.
118  * Usually, for a specified SPI instance, user need only call this API once to get the initialized handle.
119  *
120  * @param base SPI peripheral base address.
121  * @param handle SPI handle pointer.
122  * @param callback User callback function called at the end of a transfer.
123  * @param userData User data for callback.
124  * @param txHandle DMA handle pointer for SPI Tx, the handle shall be static allocated by users.
125  * @param rxHandle DMA handle pointer for SPI Rx, the handle shall be static allocated by users.
126  */
SPI_SlaveTransferCreateHandleDMA(SPI_Type * base,spi_dma_handle_t * handle,spi_dma_callback_t callback,void * userData,dma_handle_t * txHandle,dma_handle_t * rxHandle)127 static inline void SPI_SlaveTransferCreateHandleDMA(SPI_Type *base,
128                                                     spi_dma_handle_t *handle,
129                                                     spi_dma_callback_t callback,
130                                                     void *userData,
131                                                     dma_handle_t *txHandle,
132                                                     dma_handle_t *rxHandle)
133 {
134     SPI_MasterTransferCreateHandleDMA(base, handle, callback, userData, txHandle, rxHandle);
135 }
136 
137 /*!
138  * @brief Perform a non-blocking SPI transfer using DMA.
139  *
140  * @note This interface returned immediately after transfer initiates, users should call
141  * SPI_GetTransferStatus to poll the transfer status to check whether SPI transfer finished.
142  *
143  * @param base SPI peripheral base address.
144  * @param handle SPI DMA handle pointer.
145  * @param xfer Pointer to dma transfer structure.
146  * @retval kStatus_Success Successfully start a transfer.
147  * @retval kStatus_InvalidArgument Input argument is invalid.
148  * @retval kStatus_SPI_Busy SPI is not idle, is running another transfer.
149  */
SPI_SlaveTransferDMA(SPI_Type * base,spi_dma_handle_t * handle,spi_transfer_t * xfer)150 static inline status_t SPI_SlaveTransferDMA(SPI_Type *base, spi_dma_handle_t *handle, spi_transfer_t *xfer)
151 {
152     return SPI_MasterTransferDMA(base, handle, xfer);
153 }
154 
155 /*!
156  * @brief Abort a SPI transfer using DMA.
157  *
158  * @param base SPI peripheral base address.
159  * @param handle SPI DMA handle pointer.
160  */
SPI_SlaveTransferAbortDMA(SPI_Type * base,spi_dma_handle_t * handle)161 static inline void SPI_SlaveTransferAbortDMA(SPI_Type *base, spi_dma_handle_t *handle)
162 {
163     SPI_MasterTransferAbortDMA(base, handle);
164 }
165 
166 /*!
167  * @brief Get the transferred bytes for SPI slave DMA.
168  *
169  * @param base SPI peripheral base address.
170  * @param handle SPI DMA handle pointer.
171  * @param count Transferred bytes.
172  * @retval kStatus_SPI_Success Succeed get the transfer count.
173  * @retval kStatus_NoTransferInProgress There is not a non-blocking transaction currently in progress.
174  */
SPI_SlaveTransferGetCountDMA(SPI_Type * base,spi_dma_handle_t * handle,size_t * count)175 static inline status_t SPI_SlaveTransferGetCountDMA(SPI_Type *base, spi_dma_handle_t *handle, size_t *count)
176 {
177     return SPI_MasterTransferGetCountDMA(base, handle, count);
178 }
179 
180 /*! @} */
181 
182 #if defined(__cplusplus)
183 }
184 #endif
185 
186 /*!
187  * @}
188  */
189 #endif
190