drivers/lpspi/fsl_lpspi_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_LPSPI_EDMA_H_
0009 #define _FSL_LPSPI_EDMA_H_
0010
0011 #include "fsl_lpspi.h"
0012 #include "fsl_edma.h"
0013
0014 /*!
0015  * @addtogroup lpspi_edma_driver
0016  * @{
0017  */
0018
0019 /***********************************************************************************************************************
0020  * Definitions
0021  **********************************************************************************************************************/
0022 /*! @name Driver version */
0023 /*@{*/
0024 /*! @brief LPSPI EDMA driver version. */
0025 #define FSL_LPSPI_EDMA_DRIVER_VERSION (MAKE_VERSION(2, 3, 1))
0026 /*@}*/
0027
0028 /*!
0029  * @brief Forward declaration of the _lpspi_master_edma_handle typedefs.
0030  */
0031 typedef struct _lpspi_master_edma_handle lpspi_master_edma_handle_t;
0032
0033 /*!
0034  * @brief Forward declaration of the _lpspi_slave_edma_handle typedefs.
0035  */
0036 typedef struct _lpspi_slave_edma_handle lpspi_slave_edma_handle_t;
0037
0038 /*!
0039  * @brief Completion callback function pointer type.
0040  *
0041  * @param base LPSPI peripheral base address.
0042  * @param handle Pointer to the handle for the LPSPI master.
0043  * @param status Success or error code describing whether the transfer completed.
0044  * @param userData Arbitrary pointer-dataSized value passed from the application.
0045  */
0046 typedef void (*lpspi_master_edma_transfer_callback_t)(LPSPI_Type *base,
0047                                                       lpspi_master_edma_handle_t *handle,
0048                                                       status_t status,
0049                                                       void *userData);
0050 /*!
0051  * @brief Completion callback function pointer type.
0052  *
0053  * @param base LPSPI peripheral base address.
0054  * @param handle Pointer to the handle for the LPSPI slave.
0055  * @param status Success or error code describing whether the transfer completed.
0056  * @param userData Arbitrary pointer-dataSized value passed from the application.
0057  */
0058 typedef void (*lpspi_slave_edma_transfer_callback_t)(LPSPI_Type *base,
0059                                                      lpspi_slave_edma_handle_t *handle,
0060                                                      status_t status,
0061                                                      void *userData);
0062
0063 /*! @brief LPSPI master eDMA transfer handle structure used for transactional API. */
0064 struct _lpspi_master_edma_handle
0065 {
0066     volatile bool isPcsContinuous; /*!< Is PCS continuous in transfer. */
0067
0068     volatile bool isByteSwap; /*!< A flag that whether should byte swap. */
0069
0070     volatile uint8_t fifoSize; /*!< FIFO dataSize. */
0071
0072     volatile uint8_t rxWatermark; /*!< Rx watermark. */
0073
0074     volatile uint8_t bytesEachWrite; /*!< Bytes for each write TDR. */
0075     volatile uint8_t bytesEachRead;  /*!< Bytes for each read RDR. */
0076
0077     volatile uint8_t bytesLastRead;    /*!< Bytes for last read RDR. */
0078     volatile bool isThereExtraRxBytes; /*!< Is there extra RX byte. */
0079
0080     uint8_t *volatile txData;             /*!< Send buffer. */
0081     uint8_t *volatile rxData;             /*!< Receive buffer. */
0082     volatile size_t txRemainingByteCount; /*!< Number of bytes remaining to send.*/
0083     volatile size_t rxRemainingByteCount; /*!< Number of bytes remaining to receive.*/
0084
0085     volatile uint32_t writeRegRemainingTimes; /*!< Write TDR register remaining times. */
0086     volatile uint32_t readRegRemainingTimes;  /*!< Read RDR register remaining times. */
0087
0088     uint32_t totalByteCount; /*!< Number of transfer bytes*/
0089
0090     uint32_t txBuffIfNull; /*!< Used if there is not txData for DMA purpose.*/
0091     uint32_t rxBuffIfNull; /*!< Used if there is not rxData for DMA purpose.*/
0092
0093     uint32_t transmitCommand; /*!< Used to write TCR for DMA purpose.*/
0094
0095     volatile uint8_t state; /*!< LPSPI transfer state , _lpspi_transfer_state.*/
0096
0097     uint8_t nbytes; /*!< eDMA minor byte transfer count initially configured. */
0098
0099     lpspi_master_edma_transfer_callback_t callback; /*!< Completion callback. */
0100     void *userData;                                 /*!< Callback user data. */
0101
0102     edma_handle_t *edmaRxRegToRxDataHandle; /*!<edma_handle_t handle point used for RxReg to RxData buff*/
0103     edma_handle_t *edmaTxDataToTxRegHandle; /*!<edma_handle_t handle point used for TxData to TxReg buff*/
0104
0105     edma_tcd_t lpspiSoftwareTCD[3]; /*!<SoftwareTCD, internal used*/
0106 };
0107
0108 /*! @brief LPSPI slave eDMA transfer handle structure used for transactional API.*/
0109 struct _lpspi_slave_edma_handle
0110 {
0111     volatile bool isByteSwap; /*!< A flag that whether should byte swap. */
0112
0113     volatile uint8_t fifoSize; /*!< FIFO dataSize. */
0114
0115     volatile uint8_t rxWatermark; /*!< Rx watermark. */
0116
0117     volatile uint8_t bytesEachWrite; /*!< Bytes for each write TDR. */
0118     volatile uint8_t bytesEachRead;  /*!< Bytes for each read RDR. */
0119
0120     volatile uint8_t bytesLastRead;    /*!< Bytes for last read RDR. */
0121     volatile bool isThereExtraRxBytes; /*!< Is there extra RX byte. */
0122
0123     uint8_t nbytes; /*!< eDMA minor byte transfer count initially configured. */
0124
0125     uint8_t *volatile txData;             /*!< Send buffer. */
0126     uint8_t *volatile rxData;             /*!< Receive buffer. */
0127     volatile size_t txRemainingByteCount; /*!< Number of bytes remaining to send.*/
0128     volatile size_t rxRemainingByteCount; /*!< Number of bytes remaining to receive.*/
0129
0130     volatile uint32_t writeRegRemainingTimes; /*!< Write TDR register remaining times. */
0131     volatile uint32_t readRegRemainingTimes;  /*!< Read RDR register remaining times. */
0132
0133     uint32_t totalByteCount; /*!< Number of transfer bytes*/
0134
0135     uint32_t txBuffIfNull; /*!< Used if there is not txData for DMA purpose.*/
0136     uint32_t rxBuffIfNull; /*!< Used if there is not rxData for DMA purpose.*/
0137
0138     volatile uint8_t state; /*!< LPSPI transfer state.*/
0139
0140     uint32_t errorCount; /*!< Error count for slave transfer.*/
0141
0142     lpspi_slave_edma_transfer_callback_t callback; /*!< Completion callback. */
0143     void *userData;                                /*!< Callback user data. */
0144
0145     edma_handle_t *edmaRxRegToRxDataHandle; /*!<edma_handle_t handle point used for RxReg to RxData buff*/
0146     edma_handle_t *edmaTxDataToTxRegHandle; /*!<edma_handle_t handle point used for TxData to TxReg*/
0147
0148     edma_tcd_t lpspiSoftwareTCD[2]; /*!<SoftwareTCD, internal used*/
0149 };
0150
0151 /***********************************************************************************************************************
0152  * API
0153  **********************************************************************************************************************/
0154 #if defined(__cplusplus)
0155 extern "C" {
0156 #endif /*_cplusplus*/
0157
0158 /*Transactional APIs*/
0159
0160 /*!
0161  * @brief Initializes the LPSPI master eDMA handle.
0162  *
0163  * This function initializes the LPSPI eDMA handle which can be used for other LPSPI transactional APIs.  Usually, for a
0164  * specified LPSPI instance, call this API once to get the initialized handle.
0165  *
0166  * Note that the LPSPI eDMA has a separated (Rx and Tx as two sources) or shared (Rx  and Tx are the same source) DMA
0167  * request source.
0168  * (1) For a separated DMA request source, enable and set the Rx DMAMUX source for edmaRxRegToRxDataHandle and
0169  * Tx DMAMUX source for edmaTxDataToTxRegHandle.
0170  * (2) For a shared DMA request source, enable and set the Rx/Tx DMAMUX source for edmaRxRegToRxDataHandle.
0171  *
0172  * @param base LPSPI peripheral base address.
0173  * @param handle LPSPI handle pointer to lpspi_master_edma_handle_t.
0174  * @param callback LPSPI callback.
0175  * @param userData callback function parameter.
0176  * @param edmaRxRegToRxDataHandle edmaRxRegToRxDataHandle pointer to edma_handle_t.
0177  * @param edmaTxDataToTxRegHandle edmaTxDataToTxRegHandle pointer to edma_handle_t.
0178  */
0179 void LPSPI_MasterTransferCreateHandleEDMA(LPSPI_Type *base,
0180                                           lpspi_master_edma_handle_t *handle,
0181                                           lpspi_master_edma_transfer_callback_t callback,
0182                                           void *userData,
0183                                           edma_handle_t *edmaRxRegToRxDataHandle,
0184                                           edma_handle_t *edmaTxDataToTxRegHandle);
0185
0186 /*!
0187  * @brief LPSPI master transfer data using eDMA.
0188  *
0189  * This function transfers data using eDMA. This is a non-blocking function, which returns right away. When all data
0190  * is transferred, the callback function is called.
0191  *
0192  * Note:
0193  * The transfer data size should be an integer multiple of bytesPerFrame if bytesPerFrame is less than or equal to 4.
0194  * For bytesPerFrame greater than 4:
0195  * The transfer data size should be equal to bytesPerFrame if the bytesPerFrame is not an integer multiple of 4.
0196  * Otherwise, the transfer data size can be an integer multiple of bytesPerFrame.
0197  *
0198  * @param base LPSPI peripheral base address.
0199  * @param handle pointer to lpspi_master_edma_handle_t structure which stores the transfer state.
0200  * @param transfer pointer to lpspi_transfer_t structure.
0201  * @return status of status_t.
0202  */
0203 status_t LPSPI_MasterTransferEDMA(LPSPI_Type *base, lpspi_master_edma_handle_t *handle, lpspi_transfer_t *transfer);
0204
0205 /*!
0206  * @brief LPSPI master aborts a transfer which is using eDMA.
0207  *
0208  * This function aborts a transfer which is using eDMA.
0209  *
0210  * @param base LPSPI peripheral base address.
0211  * @param handle pointer to lpspi_master_edma_handle_t structure which stores the transfer state.
0212  */
0213 void LPSPI_MasterTransferAbortEDMA(LPSPI_Type *base, lpspi_master_edma_handle_t *handle);
0214
0215 /*!
0216  * @brief Gets the master eDMA transfer remaining bytes.
0217  *
0218  * This function gets the master eDMA transfer remaining bytes.
0219  *
0220  * @param base LPSPI peripheral base address.
0221  * @param handle pointer to lpspi_master_edma_handle_t structure which stores the transfer state.
0222  * @param count Number of bytes transferred so far by the EDMA transaction.
0223  * @return status of status_t.
0224  */
0225 status_t LPSPI_MasterTransferGetCountEDMA(LPSPI_Type *base, lpspi_master_edma_handle_t *handle, size_t *count);
0226
0227 /*!
0228  * @brief Initializes the LPSPI slave eDMA handle.
0229  *
0230  * This function initializes the LPSPI eDMA handle which can be used for other LPSPI transactional APIs.  Usually, for a
0231  * specified LPSPI instance, call this API once to get the initialized handle.
0232  *
0233  * Note that LPSPI eDMA has a separated (Rx and Tx as two sources) or shared (Rx  and Tx as the same source) DMA request
0234  * source.
0235  *
0236  * (1) For a separated DMA request source, enable and set the Rx DMAMUX source for edmaRxRegToRxDataHandle and
0237  * Tx DMAMUX source for edmaTxDataToTxRegHandle.
0238  * (2) For a shared DMA request source, enable and set the Rx/Rx DMAMUX source for edmaRxRegToRxDataHandle .
0239  *
0240  * @param base LPSPI peripheral base address.
0241  * @param handle LPSPI handle pointer to lpspi_slave_edma_handle_t.
0242  * @param callback LPSPI callback.
0243  * @param userData callback function parameter.
0244  * @param edmaRxRegToRxDataHandle edmaRxRegToRxDataHandle pointer to edma_handle_t.
0245  * @param edmaTxDataToTxRegHandle edmaTxDataToTxRegHandle pointer to edma_handle_t.
0246  */
0247 void LPSPI_SlaveTransferCreateHandleEDMA(LPSPI_Type *base,
0248                                          lpspi_slave_edma_handle_t *handle,
0249                                          lpspi_slave_edma_transfer_callback_t callback,
0250                                          void *userData,
0251                                          edma_handle_t *edmaRxRegToRxDataHandle,
0252                                          edma_handle_t *edmaTxDataToTxRegHandle);
0253
0254 /*!
0255  * @brief LPSPI slave transfers data using eDMA.
0256  *
0257  * This function transfers data using eDMA. This is a non-blocking function, which return right away. When all data
0258  * is transferred, the callback function is called.
0259  *
0260  * Note:
0261  * The transfer data size should be an integer multiple of bytesPerFrame if bytesPerFrame is less than or equal to 4.
0262  * For bytesPerFrame greater than 4:
0263  * The transfer data size should be equal to bytesPerFrame if the bytesPerFrame is not an integer multiple of 4.
0264  * Otherwise, the transfer data size can be an integer multiple of bytesPerFrame.
0265  *
0266  * @param base LPSPI peripheral base address.
0267  * @param handle pointer to lpspi_slave_edma_handle_t structure which stores the transfer state.
0268  * @param transfer pointer to lpspi_transfer_t structure.
0269  * @return status of status_t.
0270  */
0271 status_t LPSPI_SlaveTransferEDMA(LPSPI_Type *base, lpspi_slave_edma_handle_t *handle, lpspi_transfer_t *transfer);
0272
0273 /*!
0274  * @brief LPSPI slave aborts a transfer which is using eDMA.
0275  *
0276  * This function aborts a transfer which is using eDMA.
0277  *
0278  * @param base LPSPI peripheral base address.
0279  * @param handle pointer to lpspi_slave_edma_handle_t structure which stores the transfer state.
0280  */
0281 void LPSPI_SlaveTransferAbortEDMA(LPSPI_Type *base, lpspi_slave_edma_handle_t *handle);
0282
0283 /*!
0284  * @brief Gets the slave eDMA transfer remaining bytes.
0285  *
0286  * This function gets the slave eDMA transfer remaining bytes.
0287  *
0288  * @param base LPSPI peripheral base address.
0289  * @param handle pointer to lpspi_slave_edma_handle_t structure which stores the transfer state.
0290  * @param count Number of bytes transferred so far by the eDMA transaction.
0291  * @return status of status_t.
0292  */
0293 status_t LPSPI_SlaveTransferGetCountEDMA(LPSPI_Type *base, lpspi_slave_edma_handle_t *handle, size_t *count);
0294
0295 #if defined(__cplusplus)
0296 }
0297 #endif
0298
0299 /*! @}*/
0300
0301 #endif /*_FSL_LPSPI_EDMA_H_*/