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