文章目录
本文主要讲解为了使用驱动程序EDMA而需要调用的所有导出的API
getNumInstances
函数原型：
uint8_t EDMA_getNumInstances(
void
)
函数功能：
得到设备上EDMA实例的数量
函数参数：
void
函数返回值：
EDMA实例的数量
init
函数原型：
int32_t EDMA_init(
uint8_t instanceId
)
函数功能：
初始化指定的EDMA实例，执行以下操作：
- 禁用并清除事件
- 禁用并清除中断
- 清除错误状态
- 将所有参数集设置为全零(硬件重置状态)
函数参数：
instanceId是一个输入参数，是要初始化的实例的instanceId Id
函数返回值：
当函数执行成功后返回值为EDMA_NO_ERROR0，宏定义为
#define EDMA_NO_ERROR ((int32_t)0)
当函数执行失败后，返回值为下列错误中的一个
#define EDMA_E_INVALID__HANDLE_NULL (MMWAVE_ERRNO_EDMA_BASE-0)
Handle argument is NULL pointer.
#define EDMA_E_INVALID__CONFIG_POINTER_NULL (MMWAVE_ERRNO_EDMA_BASE-1)
Config argument is NULL pointer.
#define EDMA_E_INVALID__DMA_CHANNEL_TYPE (MMWAVE_ERRNO_EDMA_BASE-2)
Config's channelType is invalid.
#define EDMA_E_INVALID__DMA_CHANNEL_ID (MMWAVE_ERRNO_EDMA_BASE-3)
Config's channelId out of range.
#define EDMA_E_INVALID__PARAM_ID (MMWAVE_ERRNO_EDMA_BASE-4)
Config's paramId out of range.
#define EDMA_E_INVALID__EVENT_QUEUE_ID (MMWAVE_ERRNO_EDMA_BASE-5)
Config's eventQueueId out of range.
#define EDMA_E_INVALID__TRNSFR_COMPLETION_PARAMS (MMWAVE_ERRNO_EDMA_BASE-6)
Config's both interrupt completion flags are false but transfer completion call back function is configured (non NULL).
#define EDMA_E_INVALID__TRANSFER_COMPLETION_CODE (MMWAVE_ERRNO_EDMA_BASE-7)
Config's transferCompletionCode is invalid.
#define EDMA_E_INVALID__TRANSFER_TYPE (MMWAVE_ERRNO_EDMA_BASE-8)
Config's transferType is invalid.
#define EDMA_E_INVALID__QDMA_CHANNEL_ID (MMWAVE_ERRNO_EDMA_BASE-9)
Invalid Qdma channelId.
#define EDMA_E_INVALID__INSTANCE_ID (MMWAVE_ERRNO_EDMA_BASE-10)
Invalid Instance Id during open.
#define EDMA_E_INVALID__QDMA_TRIGGER_WORD (MMWAVE_ERRNO_EDMA_BASE-11)
Invalid QDMA trigger word.
#define EDMA_E_INVALID__TRANSFER_CONTROLLER_ID (MMWAVE_ERRNO_EDMA_BASE-12)
Invalid transfer controller Id.
#define EDMA_E_INVALID__TRANSFER_CONTROLLER_READ_RATE (MMWAVE_ERRNO_EDMA_BASE-13)
Invalid transfer controller read rate.
#define EDMA_E_INVALID__QUEUE_PRIORITY (MMWAVE_ERRNO_EDMA_BASE-14)
Invalid queue priority in performance config.
#define EDMA_E_INVALID__EVENT_QUEUE_THRESHOLD (MMWAVE_ERRNO_EDMA_BASE-15)
During EDMA_startTransfer, unexpected QDMA miss event detected.
#define EDMA_E_INVALID__PARAM_ID_NOT_SAME_AS_CHANNEL_ID (MMWAVE_ERRNO_EDMA_BASE-16)
During EDMA_configChannel, param ID must be same as channel ID for DMA channel because channel mapping does not exist in the hardware.
#define EDMA_E_INVALID__STATUS_POINTER_NULL (MMWAVE_ERRNO_EDMA_BASE-17)
Status argument is NULL pointer.
#define EDMA_E_INVALID__INSTANCEINFO_POINTER_NULL (MMWAVE_ERRNO_EDMA_BASE-18)
InstanceInfo argument is NULL pointer.
#define EDMA_E_INVALID__ERROR_CALL_BACK_FN_NON_NULL (MMWAVE_ERRNO_EDMA_BASE-19)
Error Call back function was expected to be NULL because error interrupt is not connected to the CPU on the device.
#define EDMA_E_INVALID__TC_ERROR_CALL_BACK_FN_NON_NULL (MMWAVE_ERRNO_EDMA_BASE-20)
TC error Call back function was expected to be NULL because at least one of the TC error interrupts are not connected to the CPU on the device.
#define EDMA_E_UNEXPECTED__DMA_EVENT_MISS_DETECTED (MMWAVE_ERRNO_EDMA_BASE-25)
During EDMA_startTransfer, unexpected DMA miss event detected.
#define EDMA_E_UNEXPECTED__QDMA_EVENT_MISS_DETECTED (MMWAVE_ERRNO_EDMA_BASE-26)
During EDMA_startTransfer, unexpected QDMA miss event detected.
#define EDMA_E_UNEXPECTED__EDMA_INSTANCE_REOPEN (MMWAVE_ERRNO_EDMA_BASE-27)
Attempt to reopen and already opened instance.
#define EDMA_E_UNEXPECTED__ATTEMPT_TO_TEST_COMPLETION (MMWAVE_ERRNO_EDMA_BASE-28)
Attempt to issue EDMA_isTransferComplete despite non-NULL completion call-back function.
#define EDMA_E_OSAL__HWIP_CREATE_TRANSFER_COMPLETION_ISR_RETURNED_NULL (MMWAVE_ERRNO_EDMA_BASE-40)
HwiP_create returned NULL on transfer completion Isr creation.
#define EDMA_E_OSAL__HWIP_CREATE_ERROR_ISR_RETURNED_NULL (MMWAVE_ERRNO_EDMA_BASE-41)
HwiP_create returned NULL on CC error Isr creation.
#define EDMA_E_OSAL__HWIP_CREATE_TRANSFER_CONTROLLER_ERROR_ISRS_RETURNED_NULL (MMWAVE_ERRNO_EDMA_BASE-42)
HwiP_create returned NULL on one of transfer controller error Isrs creation.
#define EDMA_E_OSAL__HWIP_DELETE_TRANSFER_COMPLETION_ISR_ERROR (MMWAVE_ERRNO_EDMA_BASE-43)
HwiP_delete returned NULL on transfer completion Isr deletion.
#define EDMA_E_OSAL__HWIP_DELETE_ERROR_ISR_ERROR (MMWAVE_ERRNO_EDMA_BASE-44)
HwiP_delete returned NULL on CC error Isr deletion.
#define EDMA_E_OSAL__HWIP_DELETE_TRANSFER_CONTROLLER_ERROR_ISRS_ERROR (MMWAVE_ERRNO_EDMA_BASE-45)
HwiP_delete returned NULL on one of transfer controller error Isrs deletion.
#define EDMA_E_SILICON_ERRATA__4K_DATA_INTEGRITY_VIOLATION_OR_HANG_POSSIBLE_ERROR (MMWAVE_ERRNO_EDMA_BASE-50)
4K source boundary cross-over related errata of data integrity violation or hang.
#define EDMA_E_SILICON_ERRATA__4K_EXTRA_READ_ERROR (MMWAVE_ERRNO_EDMA_BASE-51)
4K source boundary cross-over related errata of extra read (no data integrity) violation.
#define EDMA_E_INUSE (MMWAVE_ERRNO_EDMA_BASE-60)
Operation cannot be implemented because a previous operation is still not complete.
#define EDMA_E_NOTIMPL (MMWAVE_ERRNO_EDMA_BASE-80)
Operation is not implemented.
其中MMWAVE_ERRNO_EDMA_BASE的宏定义为：
#define MMWAVE_ERRNO_EDMA_BASE (-3000)
open
函数原型：
EDMA_Handle EDMA_open(
uint8_t instanceId,
int32_t * errorCode,
EDMA_instanceInfo_t * instanceInfo
)
函数功能：
打开一个指定的EDMA实例
函数参数：
第一个参数是instanceId，为输入参数，要打开的实例Id，范围为[0，instances - 1]，其中instances是通过调用 EDMA_getNumInstances来获得的。
第二个参数是errorCode，为输出参数，当产生一个错误时，被赋值为init执行错误后，返回值中的一个，当没有错误时，被赋值为EDMA_NO_ERROR
第三个参数是instanceInfo，为输出参数，指的是实例的信息，是一个结构体信息，如下：
typedef struct EDMA_instanceInfo_t_
{
/*! @brief Number of event queues, same as number of transfer controllers */
uint8_t numEventQueues;
/*! @brief Number of PaRAM sets. */
uint16_t numParamSets;
/*! @brief Shows if channel mapping feature is supported. If this is supported (true)
then it is possible to associate any DMA channel with any PaRAM set,
otherwise (false), the PaRAM set must be identical to DMA channel i.e
DMA channels 0 to 63 correspond to PaRAM sets 0 to 63 respectively. */
bool isChannelMapExist;
/*! @brief true if transfer completion interrupt is routed from EDMA to the
processor interrupt controller. */
bool isTransferCompletionInterruptConnected;
/*! @brief true if error interrupt is is routed from EDMA to the
processor interrupt controller. */
bool isErrorInterruptConnected;
/*! @brief true if a transfer controller error interrupt is is routed from EDMA to the
processor interrupt controller. */
bool isTransferControllerErrorInterruptConnected[EDMA_MAX_NUM_EVENT_QUEUES];
} EDMA_instanceInfo_t;
函数返回值：
EDMA的实例handle，如果输出参数errorCode返回一个错误，而不是EDMA_NO_ERROR的话，此时handle为NULL
configErrorMonitoring
函数原型：
int32_t EDMA_configErrorMonitoring(
EDMA_Handle handle,
EDMA_errorConfig_t const * config
)
函数功能：
配置错误监视。如EDMA UG所述，EDMA IP具有监控CC和TC错误的若干功能：
- 错误的事件
- 超过队列的阈值
- 由于地址超出物理地址的界限(即EDMA没有得到任何ACK)的传输中的读/写操作而导致的总线错误
- 读/写CC/TC寄存器内存映射中的无效/保留地址
- 超过未完成的传输控制器代码
这个API允许选择性地控制要监控的内容(如果在h/w中可用)。它应该在初始化时调用。为了安全起见，提出这个API很重要，除了对调试有用之外
函数参数：
第一个参数是handle，是输入参数，是指通过调用EDMA_open后返回的handle
第二个参数是config，是输入参数，是指向错误配置的指针，是一个EDMA_errorConfig_t结构体指针，结构体内容如下：
typedef struct EDMA_errorConfig_t_
{
/*! @brief Set to true if want to configure all event queues. */
bool isConfigAllEventQueues;
/*! @brief if @ref isConfigAllEventQueues is false, used to specify the
event queue to be configured. */
uint8_t eventQueueId;
/*! @brief Set to true if want to enable event queue thresholding. */
bool isEventQueueThresholdingEnabled;
/*! @brief event Queue threshold, should be in the range
* [0, @ref EDMA_EVENT_QUEUE_THRESHOLD_MAX], convenient defines in
* @ref EDMA_EVENT_QUEUE_THRESHOLD
*/
uint8_t eventQueueThreshold;
/*! @brief Set to true if want to configure all transfer controllers. */
bool isConfigAllTransferControllers;
/*! @brief If @ref isConfigAllTransferControllers is false, used to
specify the transfer controler Id to be configured. */
uint8_t transferControllerId;
/*! @brief Set to true if want to enable all transfer controller errors,
* this is provided for convenience so as not to have to specific each
* error in @ref transferControllerErrorConfig. */
uint8_t isEnableAllTransferControllerErrors;
/*! @brief If @ref isEnableAllTransferControllerErrors is false, used to
* specify which errors to enable. */
EDMA_transferControllerErrorConfig_t transferControllerErrorConfig;
/*! @brief Call back function associated with CC errors. */
EDMA_errorCallbackFxn_t callbackFxn;
/*! @brief Call back function associated with queue/TC (Transfer Controller)
* errors. */
edmaTransferControllerErrorCallbackFxn_t transferControllerCallbackFxn;
} EDMA_errorConfig_t;
函数返回值：
和init函数的返回值一样
configChannel
函数原型：
int32_t EDMA_configChannel(
EDMA_Handle handle,
EDMA_channelConfig_t const * config,
bool isEnableChannel
)
函数功能：
对EDMA通道进行配置
函数参数：
第一个参数是handle，是输入参数，指的是调用EDMA_open后返回的handle
第二个参数是config，是输入参数，指向的是EDMA_channelConfig_t_结构体，结构体如下：
typedef struct EDMA_channelConfig_t_
{
/**
* \brief channelType can be either @ref EDMA3_CHANNEL_TYPE_DMA or
* @ref EDMA3_CHANNEL_TYPE_QDMA
*/
uint8_t channelType;
/**
* \brief qdmaParamTriggerWordOffset represents the offset (0-7)
* of the PaRAM that is used
* when @ref channelType is @ref EDMA3_CHANNEL_TYPE_QDMA,
* use one of @ref EDMA_TRIG_WORDS for
* convenience of specifying which parameter in the Param is to be used
* as the trigger word.
*/
uint8_t qdmaParamTriggerWordOffset;
/**
* \brief
* 0 to (@ref EDMA_NUM_DMA_CHANNELS - 1) when channelType is @ref EDMA3_CHANNEL_TYPE_DMA. \n
* 0 to (@ref EDMA_NUM_QDMA_CHANNELS - 1) when channelType is @ref EDMA3_CHANNEL_TYPE_QDMA.
*/
uint8_t channelId;
/**
* \brief Id of the PaRAM set, valid range is from 0 to (N - 1),
* where N is the number of param sets in the EDMA's CC that is opened,
* must be identical to @ref channelId for
* DMA channel (@ref channelType is @ref EDMA3_CHANNEL_TYPE_DMA) if channel mapping does
* not exist in the hardware.
*/
uint16_t paramId;
/**
* \brief Id of the event queue in which the channel transfer request is submitted,
* valid range is from 0 to (Q - 1),
* where Q is the number of event queues in the EDMA's CC that is opened.
*/
uint8_t eventQueueId;
/**
* \brief configuration of the PaRAM set
*/
EDMA_paramSetConfig_t paramSetConfig;
/**
* \brief call back function for intermediate or final transfer completion
* depending on configuration of interrupt related flags in @ref paramSetConfig.
* If NULL, it is assumed that the intent of the user is to poll for the
* completion of the transfer using @ref EDMA_isTransferComplete.
*/
EDMA_transferCompletionCallbackFxn_t transferCompletionCallbackFxn;
/**
* \brief argument to be returned by the call back function @ref transferCompletionCallbackFxn.
*/
uintptr_t transferCompletionCallbackFxnArg;
} EDMA_channelConfig_t;
EDMA_paramSetConfig_t_结构体如下：
typedef struct EDMA_paramSetConfig_t_
{
/**
* \brief Starting byte address of source.
*/
uint32_t sourceAddress;
/**
* \brief Starting byte address of destination.
*/
uint32_t destinationAddress;
/**
* \brief Number of bytes in each Array (ACNT).
*/
uint16_t aCount;
/**
* \brief Number of Arrays in each Frame (BCNT).
*/
uint16_t bCount;
/**
* \brief Number of Frames in a block (CCNT).
*/
uint16_t cCount;
/**
* \brief Reload value of the numArrInFrame (BCNT)
* Relevant only for A-sync transfers.
*/
uint16_t bCountReload;
/**
* \brief Index between consec. arrays of a Source Frame (SRCBIDX).
*/
int16_t sourceBindex;
/**
* \brief Index between consec. arrays of a Destination Frame (DSTBIDX).
*/
int16_t destinationBindex;
/**
* \brief Index between consecutive frames of a Source Block (SRCCIDX).
*/
int16_t sourceCindex;
/**
* \brief Index between consecutive frames of a Dest Block (DSTCIDX).
*/
int16_t destinationCindex;
/**
* \brief Address for linking (AutoReloading of a PaRAM Set)
* This must point to a valid aligned 32-byte PaRAM set
* A value of 0xFFFF means (@ref EDMA_NULL_LINK_ADDRESS) no linking.
*/
uint16_t linkAddress;
/**
* \brief transfer type which can be one of those defined in
* @ref EDMA_TRANSFER_TYPE_DEFS.
*/
uint8_t transferType;
/**
* \brief transfer Completion Code, must be in the range [0,63].
*/
uint8_t transferCompletionCode;
/**
* \brief Source addressing mode, see @ref EDMA_ADDRESSING_MODE_DEFS.
*/
uint8_t sourceAddressingMode;
/**
* \brief Destination addressing mode, see @ref EDMA_ADDRESSING_MODE_DEFS.
*/
uint8_t destinationAddressingMode;
/**
* \brief FIFO width, see @ref EDMA_FIFO_WIDTH_DEFS.
*/
uint8_t fifoWidth;
/**
* \brief STATIC bit of OPT as described in the EDMA UG.
*/
bool isStaticSet;
/**
* \brief This is bit TCCMODE of OPT as defined in EDMA UG.
*/
bool isEarlyCompletion;
/**
* \brief This is bit TCINTEN of OPT as defined in EDMA UG.
*/
bool isFinalTransferInterruptEnabled;
/**
* \brief This is bit ITCINTEN of OPT as defined in EDMA UG.
*/
bool isIntermediateTransferInterruptEnabled;
/**
* \brief This is bit TCCHEN of OPT as defined in EDMA UG.
*/
bool isFinalChainingEnabled;
/**
* \brief This is bit ITCCHEN of OPT as defined in EDMA UG.
*/
bool isIntermediateChainingEnabled;
} EDMA_paramSetConfig_t;
函数返回值：
和init函数的返回值一样
startDmaTransfer
函数原型：
int32_t EDMA_startDmaTransfer(
EDMA_Handle handle,
uint8_t channelId
)
函数功能：
启动DMA信道传输，当已知信道为DMA类型时，它是EDMA_startTransfer的更简单/快速版本
函数参数：
第一个参数是handle，是输入参数，指的是调用EDMA_open后返回的handle
第二个参数是channelId，是输入参数，取值范围是0至(EDMA_NUM_DMA_CHANNELS(64) - 1)
函数返回值：
和init函数的返回值一样
isTransferComplete
函数原型：
int32_t EDMA_isTransferComplete(
EDMA_Handle handle,
uint8_t transferCompletionCode,
bool * isTransferComplete
)
函数功能：
查询传输完成情况。如果提供的transferCompletionCode的传输完成回调函数配置为非空，则此函数将返回错误。这是因为清除通道的负担不在回调函数中，而是在调用用户提供的回调之后的驱动程序中。因此，在已清除的通道上轮询将给出错误的结果，即使传输已完成，也会指示传输未完成。回调完成和这个API是排斥的
函数参数：
第一个参数是handle，是输入参数，指的是调用EDMA_open后返回的handle
第二个参数是transferCompletionCode，是输入参数，指的是要查询的transferCompletionCode，范围是[0，(EDMA_NUM_TCC - 1)63]
第三个参数是isTransferComplete，是输出参数，如果传输完成返回true，否则返回false，注意：如果为真，则已完成传输的IPR(H)位将被清除，允许新的传输完成
函数返回值：
和init函数的返回值一样
disableChannel
函数原型：
int32_t EDMA_disableChannel(
EDMA_Handle handle,
uint8_t channelId,
uint8_t channelType
)
函数功能：
关闭一个通道
函数参数：
第一个参数是handle，是输入参数，指的是调用EDMA_open后返回的handle
第二个参数是channelId，是输入参数，当channelType是EDMA3_CHANNEL_TYPE_DMA时，值为0到EDMA_NUM_DMA_CHANNELS - 1，当channelType是EDMA3_CHANNEL_TYPE_QDMA时，值为0到EDMA_NUM_QDMA_CHANNELS - 1
第三个参数是channelType，是输入参数，通道类型可以是EDMA3_CHANNEL_TYPE_DMA或EDMA3_CHANNEL_TYPE_QDMA
函数返回值：
和init函数的返回值一样
函数原型：
在这里插入代码片
函数功能：
函数参数：
函数返回值：