drivers/lpi2c/fsl_lpi2c_edma.h

0001 /*
0002  * Copyright (c) 2015, Freescale Semiconductor, Inc.
0003  * Copyright 2016-2022 NXP
0004  * All rights reserved.
0005  *
0006  * SPDX-License-Identifier: BSD-3-Clause
0007  */
0008 #ifndef _FSL_LPI2C_EDMA_H_
0009 #define _FSL_LPI2C_EDMA_H_
0010
0011 #include "fsl_lpi2c.h"
0012 #include "fsl_edma.h"
0013
0014 /*******************************************************************************
0015  * Definitions
0016  ******************************************************************************/
0017
0018 /*! @name Driver version */
0019 /*@{*/
0020 /*! @brief LPI2C EDMA driver version. */
0021 #define FSL_LPI2C_EDMA_DRIVER_VERSION (MAKE_VERSION(2, 4, 1))
0022 /*@}*/
0023
0024 /*!
0025  * @addtogroup lpi2c_master_edma_driver
0026  * @{
0027  */
0028
0029 /* Forward declaration of the transfer descriptor and handle typedefs. */
0030 typedef struct _lpi2c_master_edma_handle lpi2c_master_edma_handle_t;
0031
0032 /*!
0033  * @brief Master DMA completion callback function pointer type.
0034  *
0035  * This callback is used only for the non-blocking master transfer API. Specify the callback you wish to use
0036  * in the call to LPI2C_MasterCreateEDMAHandle().
0037  *
0038  * @param base The LPI2C peripheral base address.
0039  * @param handle Handle associated with the completed transfer.
0040  * @param completionStatus Either kStatus_Success or an error code describing how the transfer completed.
0041  * @param userData Arbitrary pointer-sized value passed from the application.
0042  */
0043 typedef void (*lpi2c_master_edma_transfer_callback_t)(LPI2C_Type *base,
0044                                                       lpi2c_master_edma_handle_t *handle,
0045                                                       status_t completionStatus,
0046                                                       void *userData);
0047
0048 /*!
0049  * @brief Driver handle for master DMA APIs.
0050  * @note The contents of this structure are private and subject to change.
0051  */
0052 struct _lpi2c_master_edma_handle
0053 {
0054     LPI2C_Type *base;                 /*!< LPI2C base pointer. */
0055     bool isBusy;                      /*!< Transfer state machine current state. */
0056     uint8_t nbytes;                   /*!< eDMA minor byte transfer count initially configured. */
0057     uint16_t commandBuffer[10];       /*!< LPI2C command sequence. When all 10 command words are used:
0058          Start&addr&write[1 word] + subaddr[4 words] + restart&addr&read[1 word] + receive&Size[4 words] */
0059     lpi2c_master_transfer_t transfer; /*!< Copy of the current transfer info. */
0060     lpi2c_master_edma_transfer_callback_t completionCallback; /*!< Callback function pointer. */
0061     void *userData;                                           /*!< Application data passed to callback. */
0062     edma_handle_t *rx;                                        /*!< Handle for receive DMA channel. */
0063     edma_handle_t *tx;                                        /*!< Handle for transmit DMA channel. */
0064     edma_tcd_t tcds[3]; /*!< Software TCD. Three are allocated to provide enough room to align to 32-bytes. */
0065 };
0066
0067 /*! @} */
0068
0069 /*******************************************************************************
0070  * API
0071  ******************************************************************************/
0072
0073 #if defined(__cplusplus)
0074 extern "C" {
0075 #endif
0076
0077 /*!
0078  * @addtogroup lpi2c_master_edma_driver
0079  * @{
0080  */
0081
0082 /*! @name Master DMA */
0083 /*@{*/
0084
0085 /*!
0086  * @brief Create a new handle for the LPI2C master DMA APIs.
0087  *
0088  * The creation of a handle is for use with the DMA APIs. Once a handle
0089  * is created, there is not a corresponding destroy handle. If the user wants to
0090  * terminate a transfer, the LPI2C_MasterTransferAbortEDMA() API shall be called.
0091  *
0092  * For devices where the LPI2C send and receive DMA requests are OR'd together, the @a txDmaHandle
0093  * parameter is ignored and may be set to NULL.
0094  *
0095  * @param base The LPI2C peripheral base address.
0096  * @param[out] handle Pointer to the LPI2C master driver handle.
0097  * @param rxDmaHandle Handle for the eDMA receive channel. Created by the user prior to calling this function.
0098  * @param txDmaHandle Handle for the eDMA transmit channel. Created by the user prior to calling this function.
0099  * @param callback User provided pointer to the asynchronous callback function.
0100  * @param userData User provided pointer to the application callback data.
0101  */
0102 void LPI2C_MasterCreateEDMAHandle(LPI2C_Type *base,
0103                                   lpi2c_master_edma_handle_t *handle,
0104                                   edma_handle_t *rxDmaHandle,
0105                                   edma_handle_t *txDmaHandle,
0106                                   lpi2c_master_edma_transfer_callback_t callback,
0107                                   void *userData);
0108
0109 /*!
0110  * @brief Performs a non-blocking DMA-based transaction on the I2C bus.
0111  *
0112  * The callback specified when the @a handle was created is invoked when the transaction has
0113  * completed.
0114  *
0115  * @param base The LPI2C peripheral base address.
0116  * @param handle Pointer to the LPI2C master driver handle.
0117  * @param transfer The pointer to the transfer descriptor.
0118  * @retval kStatus_Success The transaction was started successfully.
0119  * @retval #kStatus_LPI2C_Busy Either another master is currently utilizing the bus, or another DMA
0120  *      transaction is already in progress.
0121  */
0122 status_t LPI2C_MasterTransferEDMA(LPI2C_Type *base,
0123                                   lpi2c_master_edma_handle_t *handle,
0124                                   lpi2c_master_transfer_t *transfer);
0125
0126 /*!
0127  * @brief Returns number of bytes transferred so far.
0128  *
0129  * @param base The LPI2C peripheral base address.
0130  * @param handle Pointer to the LPI2C master driver handle.
0131  * @param[out] count Number of bytes transferred so far by the non-blocking transaction.
0132  * @retval kStatus_Success
0133  * @retval kStatus_NoTransferInProgress There is not a DMA transaction currently in progress.
0134  */
0135 status_t LPI2C_MasterTransferGetCountEDMA(LPI2C_Type *base, lpi2c_master_edma_handle_t *handle, size_t *count);
0136
0137 /*!
0138  * @brief Terminates a non-blocking LPI2C master transmission early.
0139  *
0140  * @note It is not safe to call this function from an IRQ handler that has a higher priority than the
0141  *      eDMA peripheral's IRQ priority.
0142  *
0143  * @param base The LPI2C peripheral base address.
0144  * @param handle Pointer to the LPI2C master driver handle.
0145  * @retval kStatus_Success A transaction was successfully aborted.
0146  * @retval #kStatus_LPI2C_Idle There is not a DMA transaction currently in progress.
0147  */
0148 status_t LPI2C_MasterTransferAbortEDMA(LPI2C_Type *base, lpi2c_master_edma_handle_t *handle);
0149
0150 /*@}*/
0151
0152 /*! @} */
0153
0154 #if defined(__cplusplus)
0155 }
0156 #endif
0157
0158 #endif /* _FSL_LPI2C_EDMA_H_ */