1 /* 2 * Copyright (c) 2015, Freescale Semiconductor, Inc. 3 * Copyright 2016-2022 NXP 4 * All rights reserved. 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 #ifndef FSL_LPI2C_EDMA_H_ 9 #define FSL_LPI2C_EDMA_H_ 10 11 #include "fsl_lpi2c.h" 12 #include "fsl_edma.h" 13 14 /******************************************************************************* 15 * Definitions 16 ******************************************************************************/ 17 18 /*! 19 * @name Driver version 20 * @{ 21 */ 22 /*! @brief LPI2C EDMA driver version. */ 23 #define FSL_LPI2C_EDMA_DRIVER_VERSION (MAKE_VERSION(2, 4, 1)) 24 /*! @} */ 25 26 /*! 27 * @addtogroup lpi2c_master_edma_driver 28 * @{ 29 */ 30 31 /* Forward declaration of the transfer descriptor and handle typedefs. */ 32 /*! @brief LPI2C master EDMA handle of the transfer. */ 33 typedef struct _lpi2c_master_edma_handle lpi2c_master_edma_handle_t; 34 35 /*! 36 * @brief Master DMA completion callback function pointer type. 37 * 38 * This callback is used only for the non-blocking master transfer API. Specify the callback you wish to use 39 * in the call to LPI2C_MasterCreateEDMAHandle(). 40 * 41 * @param base The LPI2C peripheral base address. 42 * @param handle Handle associated with the completed transfer. 43 * @param completionStatus Either kStatus_Success or an error code describing how the transfer completed. 44 * @param userData Arbitrary pointer-sized value passed from the application. 45 */ 46 typedef void (*lpi2c_master_edma_transfer_callback_t)(LPI2C_Type *base, 47 lpi2c_master_edma_handle_t *handle, 48 status_t completionStatus, 49 void *userData); 50 51 /*! 52 * @brief Driver handle for master DMA APIs. 53 * @note The contents of this structure are private and subject to change. 54 */ 55 struct _lpi2c_master_edma_handle 56 { 57 LPI2C_Type *base; /*!< LPI2C base pointer. */ 58 bool isBusy; /*!< Transfer state machine current state. */ 59 uint8_t nbytes; /*!< eDMA minor byte transfer count initially configured. */ 60 uint16_t commandBuffer[10]; /*!< LPI2C command sequence. When all 10 command words are used: 61 Start&addr&write[1 word] + subaddr[4 words] + restart&addr&read[1 word] + receive&Size[4 words] */ 62 lpi2c_master_transfer_t transfer; /*!< Copy of the current transfer info. */ 63 lpi2c_master_edma_transfer_callback_t completionCallback; /*!< Callback function pointer. */ 64 void *userData; /*!< Application data passed to callback. */ 65 edma_handle_t *rx; /*!< Handle for receive DMA channel. */ 66 edma_handle_t *tx; /*!< Handle for transmit DMA channel. */ 67 edma_tcd_t tcds[3]; /*!< Software TCD. Three are allocated to provide enough room to align to 32-bytes. */ 68 }; 69 70 /*! @} */ 71 72 /******************************************************************************* 73 * API 74 ******************************************************************************/ 75 76 #if defined(__cplusplus) 77 extern "C" { 78 #endif 79 80 /*! 81 * @addtogroup lpi2c_master_edma_driver 82 * @{ 83 */ 84 85 /*! 86 * @name Master DMA 87 * @{ 88 */ 89 90 /*! 91 * @brief Create a new handle for the LPI2C master DMA APIs. 92 * 93 * The creation of a handle is for use with the DMA APIs. Once a handle 94 * is created, there is not a corresponding destroy handle. If the user wants to 95 * terminate a transfer, the LPI2C_MasterTransferAbortEDMA() API shall be called. 96 * 97 * For devices where the LPI2C send and receive DMA requests are OR'd together, the @a txDmaHandle 98 * parameter is ignored and may be set to NULL. 99 * 100 * @param base The LPI2C peripheral base address. 101 * @param[out] handle Pointer to the LPI2C master driver handle. 102 * @param rxDmaHandle Handle for the eDMA receive channel. Created by the user prior to calling this function. 103 * @param txDmaHandle Handle for the eDMA transmit channel. Created by the user prior to calling this function. 104 * @param callback User provided pointer to the asynchronous callback function. 105 * @param userData User provided pointer to the application callback data. 106 */ 107 void LPI2C_MasterCreateEDMAHandle(LPI2C_Type *base, 108 lpi2c_master_edma_handle_t *handle, 109 edma_handle_t *rxDmaHandle, 110 edma_handle_t *txDmaHandle, 111 lpi2c_master_edma_transfer_callback_t callback, 112 void *userData); 113 114 /*! 115 * @brief Performs a non-blocking DMA-based transaction on the I2C bus. 116 * 117 * The callback specified when the @a handle was created is invoked when the transaction has 118 * completed. 119 * 120 * @param base The LPI2C peripheral base address. 121 * @param handle Pointer to the LPI2C master driver handle. 122 * @param transfer The pointer to the transfer descriptor. 123 * @retval kStatus_Success The transaction was started successfully. 124 * @retval #kStatus_LPI2C_Busy Either another master is currently utilizing the bus, or another DMA 125 * transaction is already in progress. 126 */ 127 status_t LPI2C_MasterTransferEDMA(LPI2C_Type *base, 128 lpi2c_master_edma_handle_t *handle, 129 lpi2c_master_transfer_t *transfer); 130 131 /*! 132 * @brief Returns number of bytes transferred so far. 133 * 134 * @param base The LPI2C peripheral base address. 135 * @param handle Pointer to the LPI2C master driver handle. 136 * @param[out] count Number of bytes transferred so far by the non-blocking transaction. 137 * @retval kStatus_Success 138 * @retval kStatus_NoTransferInProgress There is not a DMA transaction currently in progress. 139 */ 140 status_t LPI2C_MasterTransferGetCountEDMA(LPI2C_Type *base, lpi2c_master_edma_handle_t *handle, size_t *count); 141 142 /*! 143 * @brief Terminates a non-blocking LPI2C master transmission early. 144 * 145 * @note It is not safe to call this function from an IRQ handler that has a higher priority than the 146 * eDMA peripheral's IRQ priority. 147 * 148 * @param base The LPI2C peripheral base address. 149 * @param handle Pointer to the LPI2C master driver handle. 150 * @retval kStatus_Success A transaction was successfully aborted. 151 * @retval #kStatus_LPI2C_Idle There is not a DMA transaction currently in progress. 152 */ 153 status_t LPI2C_MasterTransferAbortEDMA(LPI2C_Type *base, lpi2c_master_edma_handle_t *handle); 154 155 /*! @} */ 156 157 /*! @} */ 158 159 #if defined(__cplusplus) 160 } 161 #endif 162 163 #endif /* FSL_LPI2C_EDMA_H_ */ 164
