1 /*
2  * Copyright 2021, 2024 NXP
3  * All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  */
7 
8 #ifndef FSL_LCDIC_DMA_H_
9 #define FSL_LCDIC_DMA_H_
10 
11 #include "fsl_lcdic.h"
12 #include "fsl_dma.h"
13 
14 /*!
15  * @addtogroup lcdic_dma
16  * @{
17  */
18 
19 /*******************************************************************************
20  * Definitions
21  ******************************************************************************/
22 
23 /*! @name Driver version */
24 /*! @{ */
25 #define FSL_LCDIC_DMA_DRIVER_VERSION (MAKE_VERSION(2, 1, 0))
26 /*! @} */
27 
28 /* Forward declaration of the handle typedef. */
29 typedef struct _lcdic_dma_handle lcdic_dma_handle_t;
30 
31 /*! @brief LCDIC DMA callback called at the end of transfer. */
32 typedef void (*lcdic_dma_callback_t)(LCDIC_Type *base, lcdic_dma_handle_t *handle, status_t status, void *userData);
33 
34 /*! @brief LCDIC DMA transfer handle, users should not touch the content of the handle.*/
35 struct _lcdic_dma_handle
36 {
37     LCDIC_Type *lcdic;
38     volatile bool xferInProgress;  /*!< Transfer in progress */
39     lcdic_xfer_mode_t xferMode;    /*!< On-going transfer mode. */
40     dma_handle_t *txDmaHandle;     /*!< DMA handler for send */
41     dma_handle_t *rxDmaHandle;     /*!< DMA handler for receive */
42     lcdic_dma_callback_t callback; /*!< Callback when transfer finished. */
43     void *userData;                /*!< User Data for callback */
44     union
45     {
46         const uint8_t *txData; /*!< Pointer to the TX data. */
47         uint8_t *rxData;       /*!< Pointer to the RX data. */
48     };
49     uint32_t xferSizeWordAligned;  /*!< 4-byte size aligned part or the transfer data size. */
50     uint8_t xferSizeWordUnaligned; /*!< 4-byte size unaligned part of the transfer data size. */
51     uint8_t rxSizeWordUnaligned;   /*!< Same as xferSizeWordUnaligned, it is only used for RX. */
52     uint32_t tmpData;              /*!< To save temporary data during transfer. */
53     dma_descriptor_t *dmaDesc;     /*!< Pointer to two DMA descriptor, should be 16-byte aligned. */
54 };
55 
56 /*******************************************************************************
57  * API
58  ******************************************************************************/
59 
60 #if defined(__cplusplus)
61 extern "C" {
62 #endif
63 
64 /*!
65  * @name DMA Transactional
66  * @{
67  */
68 
69 /*!
70  * @brief Initialize the LCDIC DMA handle.
71  *
72  * This function initializes the LCDIC DMA handle which can be used for other LCDIC transactional APIs.
73  * Usually, for a specified LCDIC instance, user need only call this API once to get the initialized handle.
74  *
75  * @param base LCDIC peripheral base address.
76  * @param handle LCDIC handle pointer.
77  * @param callback User callback function called at the end of a transfer.
78  * @param userData User data for callback.
79  * @param txDmaHandle DMA handle pointer for LCDIC Tx, the handle shall be static allocated by users.
80  * @param rxDmaHandle DMA handle pointer for LCDIC Rx, the handle shall be static allocated by users.
81  * @param dmaDesc User allocated dma descriptor, it should be in non-cacheable region and 16-byte aligned.
82  */
83 status_t LCDIC_TransferCreateHandleDMA(LCDIC_Type *base,
84                                        lcdic_dma_handle_t *handle,
85                                        lcdic_dma_callback_t callback,
86                                        void *userData,
87                                        dma_handle_t *txDmaHandle,
88                                        dma_handle_t *rxDmaHandle,
89                                        dma_descriptor_t dmaDesc[2]);
90 
91 /*!
92  * @brief Perform a non-blocking LCDIC transfer using DMA.
93  *
94  * This function returned immediately after transfer initiates, monitor the transfer
95  * done by callback.
96  *
97  * @param base LCDIC peripheral base address.
98  * @param handle LCDIC DMA handle pointer.
99  * @param xfer Pointer to dma transfer structure.
100  * @retval kStatus_Success Successfully start a transfer.
101  * @retval kStatus_InvalidArgument Input argument is invalid.
102  * @retval kStatus_Busy LCDIC is not idle, is running another transfer.
103  */
104 status_t LCDIC_TransferDMA(LCDIC_Type *base, lcdic_dma_handle_t *handle, const lcdic_xfer_t *xfer);
105 
106 /*!
107  * @brief Send data array using DMA.
108  *
109  * @param base LCDIC peripheral base address.
110  * @param handle Pointer to the lcdic_handle_t structure to store the transfer state.
111  * @param xfer LCDIC transfer structure.
112  * @retval kStatus_Success Successfully start a transfer.
113  * @retval kStatus_InvalidArgument Input argument is invalid.
114  * @retval kStatus_Busy LCDIC driver is busy with another transfer.
115  */
116 status_t LCDIC_SendDataArrayDMA(LCDIC_Type *base, lcdic_dma_handle_t *handle, const lcdic_tx_xfer_t *xfer);
117 
118 /*!
119  * @brief Read data array using DMA.
120  *
121  * @param base LCDIC peripheral base address.
122  * @param handle Pointer to the lcdic_handle_t structure to store the transfer state.
123  * @param xfer LCDIC transfer structure.
124  * @retval kStatus_Success Successfully start a transfer.
125  * @retval kStatus_InvalidArgument Input argument is invalid.
126  * @retval kStatus_Busy LCDIC driver is busy with another transfer.
127  */
128 status_t LCDIC_ReadDataArrayDMA(LCDIC_Type *base, lcdic_dma_handle_t *handle, const lcdic_rx_xfer_t *xfer);
129 
130 /*!
131  * @brief LCDIC IRQ handler function work with DMA transactional APIs.
132  *
133  * IRQ handler to work with @ref LCDIC_TransferDMA.
134  *
135  * @param base LCDIC peripheral base address.
136  * @param handle Pointer to the lcdic_dma_handle_t structure to store the transfer state.
137  */
138 void LCDIC_TransferHandleIRQDMA(LCDIC_Type *base, void *handle);
139 
140 /*! @} */
141 
142 #if defined(__cplusplus)
143 }
144 #endif
145 
146 /*! @} */
147 
148 #endif /* FSL_LCDIC_DMA_H_ */
149