Introduction

This is DMA Utils related configuration parameters and API

Files
file	dmautils_autoincrement_3d.h
	This file contains the data types and util function prototype for configuring DMA Utility autoincrement 3D usecase.

Data Structures
struct	DmaUtilsAutoInc3d_TransferDim
	This structure specifies the properties of the transfer for auto increment usecase. More...

struct	DmaUtilsAutoInc3d_TransferCirc
	This structure specifies the circular properties for each level of the transfer count. User can specify 2 different sizes for each level. More...

struct	DmaUtilsAutoInc3d_IOPointers
	This structure specifies the input and output pointers for the transfer. More...

struct	DmaUtilsAutoInc3d_TransferProp
	This structure specifies the properties of the transfer for auto increment usecase. More...

struct	DmaUtilsAutoInc3d_ChannelInitParam
	This structure specifies the parameter to initialize auto increment related properties. More...

struct	DmaUtilsAutoInc3d_InitParam

struct	DmaUtilsAutoInc3d_TrPrepareParam

Functions
int32_t	DmaUtilsAutoInc3d_getContextSize (int32_t numChannels)
	Returns the size of dmautils context. More...

int32_t	DmaUtilsAutoInc3d_init (void autoIncrementContext, DmaUtilsAutoInc3d_InitParam initParams, DmaUtilsAutoInc3d_ChannelInitParam chInitParams[])
	This function initializes the DMA UTILS context for autoincrement usecase. More...

int32_t	DmaUtilsAutoInc3d_getTrMemReq (int32_t numTRs)
	This function returns the size of the TR descriptor required for the transfer configuration given by the user. More...

int32_t	DmaUtilsAutoInc3d_prepareTr (DmaUtilsAutoInc3d_TrPrepareParam *trPrepParam, DmaUtilsAutoInc3d_TransferProp transferProp[])
	This function will prepare a TR/ TR descriptor depending on the number of Tr's to be submitted on a particular channel. Note this function will use the addresses as given by the user without any conversion. If user wants to convert addresses from virtual to physical address they should use DmaUtilsAutoInc3d_convertTrVirtToPhyAddr API. Other way to do the same is to call DmaUtilsAutoInc3d_convertToPhysicalAddr to explicitly convert the address in TR to physical address. More...

int32_t	DmaUtilsAutoInc3d_prepareTrWithPhysicalAddress (void autoIncrementContext, DmaUtilsAutoInc3d_TrPrepareParam trPrepParam, DmaUtilsAutoInc3d_TransferProp transferProp[])
	This function will prepare a TR/ TR descriptor depending on the number of Tr's to be submitted on a particular channel. The only difference between this function and DmaUtilsAutoInc3d_prepareTr function is that this function will call UDMA driver's Udma_VirtToPhyFxn function if its not NULL to convert virtual address to physical address. Note that this function will convert the virtual addresses given to physical addresses if UDMA driver Udma_VirtToPhyFxn function is not NULL using the same function. If user is preparing TR without using this API then it is user's responsibity to provide the physical addresses or call DmaUtilsAutoInc3d_convertToPhysicalAddr API to covert the addresses given in TR to physical addresses. More...

int32_t	DmaUtilsAutoInc3d_convertTrVirtToPhyAddr (void autoIncrementContext, DmaUtilsAutoInc3d_TrPrepareParam trPrepParam, uint32_t convertMask)
	This function should be called whenever provides TR with virtual addresses of src and dst pointer. This function will convert the virtual addresses given to physical addresses using UDMA driver initialized function Udma_VirtToPhyFxn. If UDMA driver Udma_VirtToPhyFxn function is NULL then this API results into no change. More...

int32_t	DmaUtilsAutoInc3d_configure (void autoIncrementContext, int32_t channelId, uint8_t trMem, int32_t numTr)
	This function configures autoincrement for a particular channel. More...

int32_t	DmaUtilsAutoInc3d_trigger (void *autoIncrementContext, int32_t channelId)
	This function triggers transfer on a particular channel. More...

void	DmaUtilsAutoInc3d_wait (void *autoIncrementContext, int32_t channelId)
	This function waits for completion transfer on a particular channel. More...

int32_t	DmaUtilsAutoInc3d_deconfigure (void autoIncrementContext, int32_t channelId, uint8_t trMem, int32_t numTr)
	This function deconfigures autoincrement for a particular channel. More...

int32_t	DmaUtilsAutoInc3d_deinit (void *autoIncrementContext)
	This function deinit autoincrement by releasing all the resorces allocated. More...

Enumerations
enum	DmaUtilsAutoInc3d_SyncType { DMAUTILSAUTOINC3D_SYNC_1D = 0, DMAUTILSAUTOINC3D_SYNC_2D = 1, DMAUTILSAUTOINC3D_SYNC_3D = 2, DMAUTILSAUTOINC3D_SYNC_4D = 3 }
	Describes the boundary at which the DMA is suppose to get synced. More...

enum	DmaUtilsAutoInc3d_AddrType { DMAUTILSAUTOINC3D_ADDR_LINEAR = 0, DMAUTILSAUTOINC3D_ADDR_CIRC1 = 1, DMAUTILSAUTOINC3D_ADDR_CIRC2 = 2 }
	Describes the boundary at which the DMA is suppose to get synced. More...

enum	DmaUtilsAutoInc3d_CircDirType { DMAUTILSAUTOINC3D_CIRCDIR_SRC = 0, DMAUTILSAUTOINC3D_CIRCDIR_DST = 1 }
	Describes the direction in which circular addressing is applied. More...

enum	DmaUtilsAutoInc3d_druOwner { DMAUTILSAUTOINC3D_DRUOWNER_DIRECT_TR = 0, DMAUTILSAUTOINC3D_DRUOWNER_UDMA = 1 }

enum	DmaUtilsAutoInc3d_addrConvertMask { DMAUTILSAUTOINC3D_ADDRCONVERTMASK_SRCADDR = (uint32_t)1U << 0, DMAUTILSAUTOINC3D_ADDRCONVERTMASK_DSTADDR = (uint32_t)1U << 1 }
	Describes the addresses that needs to be converted while using DmaUtilsAutoInc3d_convertToPhysicalAddr update API.User can create a mask with more than one fields of this enumby "OR"ing these fields to update more than one parameters. e.g. if user wants to convert both src and destination addresses then they can create this mask as follows : mask = DMAUTILSAUTOINC3D_ADDRCONVERTMASK_SRCADDR \| DMAUTILSAUTOINC3D_ADDRCONVERTMASK_DSTADDR. More...

Macros
#define	DMAUTILS_MAX_NUM_TR_DIRECT_TR_MODE (1U)
	Number of TR's that can be submitted back to back channel. More...

Macro Definition Documentation

◆ DMAUTILS_MAX_NUM_TR_DIRECT_TR_MODE

#define DMAUTILS_MAX_NUM_TR_DIRECT_TR_MODE (1U)

Number of TR's that can be submitted back to back channel.

Enumeration Type Documentation

◆ DmaUtilsAutoInc3d_SyncType

enum DmaUtilsAutoInc3d_SyncType

Describes the boundary at which the DMA is suppose to get synced.

Enumerator
DMAUTILSAUTOINC3D_SYNC_1D	DMA is synced at each 1D transfer i.e. it is synced whenever icnt1 is decremented by 1
DMAUTILSAUTOINC3D_SYNC_2D	DMA is synced at each 2D transfer i.e. it is synced whenever icnt2 is decremented by 1
DMAUTILSAUTOINC3D_SYNC_3D	DMA is synced at each 3D transfer i.e. it is synced whenever icnt3 is decremented by 1
DMAUTILSAUTOINC3D_SYNC_4D	DMA is synced at each 4D transfer i.e. it is synced whenever one TR is completed

◆ DmaUtilsAutoInc3d_AddrType

enum DmaUtilsAutoInc3d_AddrType

Describes the boundary at which the DMA is suppose to get synced.

Enumerator
DMAUTILSAUTOINC3D_ADDR_LINEAR	Linear addressing, addresses will be updated linearly as per the dim's and icnt's
DMAUTILSAUTOINC3D_ADDR_CIRC1	Circular addressing, address will hold the upper bits of the addresses to be constant. This enum is to use circSize1 for circularity
DMAUTILSAUTOINC3D_ADDR_CIRC2	Circular addressing, address will hold the upper bits of the addresses to be constant. This enum is to use circSize2 for circularity

◆ DmaUtilsAutoInc3d_CircDirType

enum DmaUtilsAutoInc3d_CircDirType

Describes the direction in which circular addressing is applied.

Enumerator
DMAUTILSAUTOINC3D_CIRCDIR_SRC	Circular addressing if enabled is applied on source side
DMAUTILSAUTOINC3D_CIRCDIR_DST	Circular addressing if enabled is applied on desination side

◆ DmaUtilsAutoInc3d_druOwner

enum DmaUtilsAutoInc3d_druOwner

Enumerator
DMAUTILSAUTOINC3D_DRUOWNER_DIRECT_TR	DRU channel is used in Direct TR mode
DMAUTILSAUTOINC3D_DRUOWNER_UDMA	Dru channel is used via ring based mechanism

◆ DmaUtilsAutoInc3d_addrConvertMask

enum DmaUtilsAutoInc3d_addrConvertMask

Describes the addresses that needs to be converted while using DmaUtilsAutoInc3d_convertToPhysicalAddr update API.User can create a mask with more than one fields of this enumby "OR"ing these fields to update more than one parameters. e.g. if user wants to convert both src and destination addresses then they can create this mask as follows : mask = DMAUTILSAUTOINC3D_ADDRCONVERTMASK_SRCADDR | DMAUTILSAUTOINC3D_ADDRCONVERTMASK_DSTADDR.

Enumerator
DMAUTILSAUTOINC3D_ADDRCONVERTMASK_SRCADDR	Convert Source Address Pointer
DMAUTILSAUTOINC3D_ADDRCONVERTMASK_DSTADDR	Convert Destination Address Pointer

Function Documentation

◆ DmaUtilsAutoInc3d_getContextSize()

int32_t DmaUtilsAutoInc3d_getContextSize ( int32_t numChannels )

Returns the size of dmautils context.

This function returns the size of the DMA UTILS autoincrement 3D handle. User is then expected to allocate this memory and provide it to DMA UTILS autoincrement 3D function as an input.

Parameters

numChannels [IN] Number of channels required for a usecase

Returns: Size of the DMA UTILS context in bytes

◆ DmaUtilsAutoInc3d_init()

int32_t DmaUtilsAutoInc3d_init	(	void *	autoIncrementContext,
		DmaUtilsAutoInc3d_InitParam *	initParams,
		DmaUtilsAutoInc3d_ChannelInitParam	chInitParams[]
	)

This function initializes the DMA UTILS context for autoincrement usecase.

This function initializes the DMA UTILS context for autoincrement usecase. Internally it allocates numChannels DRU channels for the use case

Parameters

autoIncrementContext	[IN] Memory allocated by the user as per DmaUtilsAutoInc3d_getContextSize API. Try to allocate this memory in the fastest available memory for optimal performance
initParams	[IN] Init params for the dmautils
chInitParams	[IN] Init parameter for each channel. This is an array and number of enteries should be same as numChannels

Returns: Udma_ErrorCodes

◆ DmaUtilsAutoInc3d_getTrMemReq()

int32_t DmaUtilsAutoInc3d_getTrMemReq ( int32_t numTRs )

This function returns the size of the TR descriptor required for the transfer configuration given by the user.

Parameters

numTRs [IN] Number of Transfer Records (TR's) that will be submitted to a particular channel

Returns: Size of the TR descriptor in bytes.

◆ DmaUtilsAutoInc3d_prepareTr()

int32_t DmaUtilsAutoInc3d_prepareTr	(	DmaUtilsAutoInc3d_TrPrepareParam *	trPrepParam,
		DmaUtilsAutoInc3d_TransferProp	transferProp[]
	)

This function will prepare a TR/ TR descriptor depending on the number of Tr's to be submitted on a particular channel. Note this function will use the addresses as given by the user without any conversion. If user wants to convert addresses from virtual to physical address they should use DmaUtilsAutoInc3d_convertTrVirtToPhyAddr API. Other way to do the same is to call DmaUtilsAutoInc3d_convertToPhysicalAddr to explicitly convert the address in TR to physical address.

Parameters

trPrepParam	[IN] Parameters required for preparing TR
transferProp	[IN] Transfer properties of all the TR'sr which needs to be submitted to a single channel

Returns: Udma_ErrorCodes

◆ DmaUtilsAutoInc3d_prepareTrWithPhysicalAddress()

int32_t DmaUtilsAutoInc3d_prepareTrWithPhysicalAddress	(	void *	autoIncrementContext,
		DmaUtilsAutoInc3d_TrPrepareParam *	trPrepParam,
		DmaUtilsAutoInc3d_TransferProp	transferProp[]
	)

This function will prepare a TR/ TR descriptor depending on the number of Tr's to be submitted on a particular channel. The only difference between this function and DmaUtilsAutoInc3d_prepareTr function is that this function will call UDMA driver's Udma_VirtToPhyFxn function if its not NULL to convert virtual address to physical address. Note that this function will convert the virtual addresses given to physical addresses if UDMA driver Udma_VirtToPhyFxn function is not NULL using the same function. If user is preparing TR without using this API then it is user's responsibity to provide the physical addresses or call DmaUtilsAutoInc3d_convertToPhysicalAddr API to covert the addresses given in TR to physical addresses.

Parameters

autoIncrementContext	[IN] Context allocated for dmautils usecase
trPrepParam	[IN] Parameters required for preparing TR
transferProp	[IN] Transfer properties of all the TR'sr which needs to be submitted to a single channel

Returns: Udma_ErrorCodes

◆ DmaUtilsAutoInc3d_convertTrVirtToPhyAddr()

int32_t DmaUtilsAutoInc3d_convertTrVirtToPhyAddr	(	void *	autoIncrementContext,
		DmaUtilsAutoInc3d_TrPrepareParam *	trPrepParam,
		uint32_t	convertMask
	)

This function should be called whenever provides TR with virtual addresses of src and dst pointer. This function will convert the virtual addresses given to physical addresses using UDMA driver initialized function Udma_VirtToPhyFxn. If UDMA driver Udma_VirtToPhyFxn function is NULL then this API results into no change.

Parameters

autoIncrementContext	[IN] Context allocated for dmautils usecase
trPrepParam	[IN] Parameters required for preparing TR
convertMask	[IN] Mask to inform which fields address to be converted. Refer DmaUtilsAutoInc3d_addrConvertMask for its usage.

Returns: Udma_ErrorCodes

◆ DmaUtilsAutoInc3d_configure()

int32_t DmaUtilsAutoInc3d_configure	(	void *	autoIncrementContext,
		int32_t	channelId,
		uint8_t *	trMem,
		int32_t	numTr
	)

This function configures autoincrement for a particular channel.

Parameters

autoIncrementContext	[IN] Context allocated for dmautils usecase
channelId	[IN] Channel Id which needs to be configured. It is important to note that this id is a virtual id for channel and is not related to the actual channel used internally to do the transfer
trMem	[IN] Populated TrMem after calling DmaUtilsAutoInc3d_prepareTr function. This API expects all addresses to be physical memory addresses. This is automatically taken care if user prepares TR using DmaUtilsAutoInc3d_prepareTr or user can call DmaUtilsAutoInc3d_convertToPhysicalAddr to convert addresses to physical addresses.
numTr	[IN] Number of Transfer Records (TR's) that will be submitted to a particular channel

Returns: Udma_ErrorCodes

◆ DmaUtilsAutoInc3d_trigger()

int32_t DmaUtilsAutoInc3d_trigger	(	void *	autoIncrementContext,
		int32_t	channelId
	)

This function triggers transfer on a particular channel.

Parameters

autoIncrementContext	[IN] Context allocated for dmautils usecase
channelId	[IN] Channel Id which needs to be triggered. It is important to note that this id is a virtual id for channel and is not related to the actual channel used internally to do the transfer

Returns: Number of triggered required to complete the full transfer

◆ DmaUtilsAutoInc3d_wait()

void DmaUtilsAutoInc3d_wait	(	void *	autoIncrementContext,
		int32_t	channelId
	)

This function waits for completion transfer on a particular channel.

Parameters

autoIncrementContext	[IN] Context allocated for dmautils usecase
channelId	[IN] Channel Id for which we need to wait for transfer completion. It is important to note that this id is a virtual id for channel and is not related to the actual channel used internally to do the transfer

Returns: Number of triggered required to complete the full transfer

◆ DmaUtilsAutoInc3d_deconfigure()

int32_t DmaUtilsAutoInc3d_deconfigure	(	void *	autoIncrementContext,
		int32_t	channelId,
		uint8_t *	trMem,
		int32_t	numTr
	)

This function deconfigures autoincrement for a particular channel.

Parameters

autoIncrementContext	[IN] Context allocated for dmautils usecase
channelId	[IN] Channel Id which needs to be de-configured. It is important to note that this id is a virtual id for channel and is not related to the actual channel used internally to do the transfer
trMem	[IN] Populated TrMem after calling DmaUtilsAutoInc3d_prepareTr function
numTr	[IN] Number of Transfer Records (TR's) that will be submitted to a particular channel

Returns: Udma_ErrorCodes

◆ DmaUtilsAutoInc3d_deinit()

int32_t DmaUtilsAutoInc3d_deinit ( void * autoIncrementContext )

This function deinit autoincrement by releasing all the resorces allocated.

Parameters

autoIncrementContext [IN] Context allocated for dmautils usecase

Returns: Udma_ErrorCodes

Introduction

Files

Data Structures

Functions

Enumerations

Macros

Macro Definition Documentation

◆ DMAUTILS_MAX_NUM_TR_DIRECT_TR_MODE

Enumeration Type Documentation

◆ DmaUtilsAutoInc3d_SyncType

◆ DmaUtilsAutoInc3d_AddrType

◆ DmaUtilsAutoInc3d_CircDirType

◆ DmaUtilsAutoInc3d_druOwner

◆ DmaUtilsAutoInc3d_addrConvertMask

Function Documentation

◆ DmaUtilsAutoInc3d_getContextSize()

◆ DmaUtilsAutoInc3d_init()

◆ DmaUtilsAutoInc3d_getTrMemReq()

◆ DmaUtilsAutoInc3d_prepareTr()

◆ DmaUtilsAutoInc3d_prepareTrWithPhysicalAddress()

◆ DmaUtilsAutoInc3d_convertTrVirtToPhyAddr()

◆ DmaUtilsAutoInc3d_configure()

◆ DmaUtilsAutoInc3d_trigger()

◆ DmaUtilsAutoInc3d_wait()

◆ DmaUtilsAutoInc3d_deconfigure()

◆ DmaUtilsAutoInc3d_deinit()