// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// include/drivers/dmadefs.h

// DMA Framework - General class, enum, constant and type definitions.

//

//

#ifndef __DMADEFS_H__

#define __DMADEFS_H__

#include <e32def.h>

/** The client request callback type */

enum TDmaCallbackType

	{

	/** Transfer request completion callback */

	EDmaCallbackRequestCompletion        = 0x01,

	/** Transfer request completion callback - source side */

	EDmaCallbackRequestCompletion_Src    = 0x02,

	/** Transfer request completion callback - destination side */

	EDmaCallbackRequestCompletion_Dst    = 0x04,

	/** Descriptor completion callback */

	EDmaCallbackDescriptorCompletion     = 0x08,

	/** Descriptor completion callback - source side */

	EDmaCallbackDescriptorCompletion_Src = 0x10,

	/** Descriptor completion callback - destination side */

	EDmaCallbackDescriptorCompletion_Dst = 0x20,

	/** Frame completion callback */

	EDmaCallbackFrameCompletion          = 0x40,

	/** Frame completion callback - source side */

	EDmaCallbackFrameCompletion_Src      = 0x80,

	/** Frame completion callback - destination side */

	EDmaCallbackFrameCompletion_Dst      = 0x100,

	/** H/W descriptor pause event callback */

	EDmaCallbackLinkedListPaused        = 0x200,

	/** H/W descriptor pause event callback - source side */

	EDmaCallbackLinkedListPaused_Src    = 0x400,

	/** H/W descriptor pause event callback - destination side */

	EDmaCallbackLinkedListPaused_Dst    = 0x800

	};

/** The outcome of the transfer request */

enum TDmaResult

	{

	/** Completed without error */

	EDmaResultOK = 0,

	/** There was an error */

	EDmaResultError

	};

/** To be used with address mode field of the DMA transfer config struct.

	@see TDmaTransferConfig::iAddrMode

*/

enum TDmaAddrMode

	{

	/** Constant addressing. The address remains the same for consecutive

		accesses.

	*/

	KDmaAddrModeConstant,

	/** Post-increment addressing. The address increases by the element size

		after each access.

	*/

	KDmaAddrModePostIncrement,

	/** Post-decrement addressing. The address decreases by the element size

		after each access.

	*/

	KDmaAddrModePostDecrement,

	/** 1D-index addressing. The address always increases by the element size

		plus the element skip value after each access.

	*/

	KDmaAddrMode1DIndex,

	/** 2D-index addressing. The address increases by the element size plus the

		element skip value - but only within a frame. Once a full frame has been

		transferred, the address increases by the element size plus the element

		skip value plus the frame skip value.

	*/

	KDmaAddrMode2DIndex

	};

/** To be used with the burst size field of the DMA transfer config struct.

	@see SDmacCaps::iBurstTransactions

	@see TDmaTransferConfig::iBurstSize

*/

enum TDmaBurstSize

	{

	/** Don't use burst transactions */

	KDmaNoBursts     = -1,

	/** Don't care (the default) */

	KDmaBurstSizeAny = 0x00,

	/** 4 bytes */

	KDmaBurstSize4   = 0x04,

	/** 8 bytes */

	KDmaBurstSize8   = 0x08,

	/** 16 bytes */

	KDmaBurstSize16  = 0x10,

	/** 32 bytes */

	KDmaBurstSize32  = 0x20,

	/** 64 bytes */

	KDmaBurstSize64  = 0x40,

	/** 128 bytes */

	KDmaBurstSize128 = 0x80

	};

/** To be used with the flags field of the DMA transfer config struct.

	@see TDmaTransferConfig::iFlags

*/

enum TDmaTransferFlags

	{

	/** Location is address of a memory buffer (as opposed to a peripheral or a

		register).

	*/

	KDmaMemAddr                      = 0x01,

	/** Address is a physical address (as opposed to a linear one).

		If it is a memory address then KDmaMemIsContiguous will need to be set

		as well.

	 */

	KDmaPhysAddr                     = 0x02,

	/** Target memory is known to be physically contiguous, hence there is

		no need for the framework to check for memory fragmentation.

	*/

	KDmaMemIsContiguous              = 0x04,

	/** Don't use packed access (if possible) */

	KDmaDontUsePacked                = 0x08,

	/** Location is big endian (little endian if not set).

		To have any effect, this flag requires the DMAC to support endianness

		conversion.

		@see SDmacCaps::iEndiannessConversion

	*/

	KDmaBigEndian                    = 0x10,

	/** Don't do endianness conversion even if applicable.

		To have any effect, this flag requires the DMAC to support endianness

		conversion.

		@see SDmacCaps::iEndiannessConversion

	*/

	KDmaLockEndian                   = 0x20,

	/** Execute client request callback after each subtransfer (streaming /

		loop case).

		This option is only taken into account if the respective

		TDmaTransferConfig::iRepeatCount is non-zero.

		The callback will complete with a TDmaCallbackType of

		EDmaCallbackRequestCompletion (even if the repeat counts for source and

		destination are different), unless the flag

		TDmaPILFlags::KDmaAsymCompletionCallback is set too, in which case what

		is described there applies.

	*/

	KDmaCallbackAfterEveryTransfer   = 0x40,

	/** Execute client request callback after each completed hardware

		descriptor.

		Requires the DMAC to support this feature. Unless the DMAC supports

		asymmetric descriptor interrupts as well, this flag should not be set

		on only one (source or destination) side.

		@see SDmacCaps::iDescriptorInterrupt

		@see SDmacCaps::iAsymDescriptorInterrupt

	*/

	KDmaCallbackAfterEveryDescriptor = 0x80,

	/** Execute client request callback after each completed frame.

		Requires the DMAC to support this feature. Unless the DMAC supports

		asymmetric frame interrupts as well, this flag should not be set on

		only one (source or destination) side.

		@see SDmacCaps::iFrameInterrupt

		@see SDmacCaps::iAsymFrameInterrupt

	*/

	KDmaCallbackAfterEveryFrame      = 0x100

	};

/** To be used with the synchronization flags field of a DMA transfer

	config struct.

	@see SDmacCaps::iSynchronizationTypes

	@see TDmaTransferConfig::iSyncFlags

*/

enum TDmaTransferSyncFlags

	{

	/** Leave the decision on whether the transfer is hardware synchronized at

		this end (either source or destination) to the Framework. This is the

		default.

	*/

	KDmaSyncAuto        = 0x00,

	/** Transfer is not hardware synchronized at this end (either source or

		destination).

	*/

	KDmaSyncNone        = 0x01,

	/** Transfer is hardware synchronized at this end (either source or

		destination). This option can also be used on its own, without any

		of the following sync sizes.

	*/

	KDmaSyncHere        = 0x02,

	/** H/W synchronized at this end: transfer one ELEMENT (a number of

		bytes, depending on the configured element size) per sync event.

	*/

	KDmaSyncSizeElement = 0x04,

	/** H/W synchronized at this end: transfer one FRAME (a number of

		elements, depending on the configured frame size) per sync event.

	*/

	KDmaSyncSizeFrame   = 0x08,

	/** H/W synchronized at this end: transfer one BLOCK (a number of

		frames, depending on the configured transfer size) per sync

		event. This is the most common use case.

	*/

	KDmaSyncSizeBlock   = 0x10,

	/** H/W synchronized at this end: transfer one PACKET (a number of

		elements, depending on the configured packet size) per sync event.

		In cases where the transfer block size is not a multiple of the

		packet size the last packet will consist of the remaining elements.

	*/

	KDmaSyncSizePacket  = 0x20

	};

/** To be used with the Graphics operation field of a DMA transfer request.

	@see TDmaTransferArgs::iGraphicsOps

*/

enum TDmaGraphicsOps

	{

	/** Don't use any graphics acceleration feature (the default) */

	KDmaGraphicsOpNone            = 0x00,

	/** Enable graphics acceleration feature 'Constant Fill' */

	KDmaGraphicsOpConstantFill    = 0x01,

	/** Enable graphics acceleration feature 'TransparentCopy' */

	KDmaGraphicsOpTransparentCopy = 0x02

	};

/** To be used with the PIL flags field of a DMA transfer request.

	@see TDmaTransferArgs::iFlags

*/

enum TDmaPILFlags

	{

	/** Request a different max transfer size (for instance for test

		purposes).

	*/

	KDmaAltTransferLength         = 0x01,

	/** Execute client request callback in ISR context instead of from a

		DFC.

	*/

	KDmaRequestCallbackFromIsr    = 0x02,

	/** Execute descriptor completion callback in ISR context instead of

		from a DFC. This option is to be used in conjunction with the

		TDmaTransferFlags::KDmaCallbackAfterEveryDescriptor flag.

	*/

	KDmaDescriptorCallbackFromIsr = 0x04,

	/** Execute frame completion callback in ISR context instead of

		from a DFC. This option is to be used in conjunction with the

		TDmaTransferFlags::KDmaCallbackAfterEveryFrame flag.

	*/

	KDmaFrameCallbackFromIsr      = 0x08,

	/** Execute the client request callback separately for source and

		destination subtransfers.

		This flag also determines the TDmaCallbackType value returned. If set,

		the callback will complete with EDmaCallbackRequestCompletion_Src or

		EDmaCallbackRequestCompletion_Dst, respectively, instead of with

		EDmaCallbackRequestCompletion.

		Requires the DMAC to support this feature.

		@see SDmacCaps::iAsymCompletionInterrupt

	*/

	KDmaAsymCompletionCallback    = 0x10,

	/** Execute the descriptor completion callback separately for source

		and destination subtransfers.

		This flag modifies the behaviour of the

		TDmaTransferFlags::KDmaCallbackAfterEveryDescriptor flag and also

		determines the TDmaCallbackType value returned. If set, the callback

		will complete with EDmaCallbackDescriptorCompletion_Src or

		EDmaCallbackDescriptorCompletion_Dst, respectively, instead of with

		EDmaCallbackDescriptorCompletion.

		Requires the DMAC to support this feature.

		@see SDmacCaps::iAsymDescriptorInterrupt

	*/

	KDmaAsymDescriptorCallback    = 0x20,

	/** Execute the frame completion callback separately for source and

		destination subtransfers.

		This flag modifies the behaviour of the

		TDmaTransferFlags::KDmaCallbackAfterEveryFrame flag. If set, the

		callback will complete with EDmaCallbackFrameCompletion_Src or

		EDmaCallbackFrameCompletion_Dst, respectively, instead of with

		EDmaCallbackFrameCompletion.

		Requires the DMAC to support this feature.

		@see SDmacCaps::iAsymFrameInterrupt

	*/

	KDmaAsymFrameCallback         = 0x40,

	/** This transfer (only) should use the channel priority indicated by

		TDmaTransferArgs::iChannelPriority.

	*/

	KDmaRequestChannelPriority    = 0x80

	};

/** Values which can be used with the priority field when opening a channel

	and/or when fragmenting a transfer request.

	@see TDmaChannel::SCreateInfo::iPriority

	@see TDmaTransferArgs::iChannelPriority

*/

enum TDmaPriority

	{

	/** No transfer priority preference (don't care value) */

	KDmaPriorityNone = 0x0,

	/** Platform-independent transfer priority 1 (lowest) */

	KDmaPriority1 = 0x80000001,

	/** Platform-independent transfer priority 2 */

	KDmaPriority2 = 0x80000002,

	/** Platform-independent transfer priority 3 */

	KDmaPriority3 = 0x80000003,

	/** Platform-independent transfer priority 4 */

	KDmaPriority4 = 0x80000004,

	/** Platform-independent transfer priority 5 */

	KDmaPriority5 = 0x80000005,

	/** Platform-independent transfer priority 6 */

	KDmaPriority6 = 0x80000006,

	/** Platform-independent transfer priority 7 */

	KDmaPriority7 = 0x80000007,

	/** Platform-independent transfer priority 8 (highest) */

	KDmaPriority8 = 0x80000008

	};

/** Contains the configuration values for either the source or the

	destination side of a DMA transfer.

	Note that some fields (notably iElementSize, iElementsPerFrame and

	iFramesPerTransfer) may only differ between source and destination if

	the underlying DMAC supports this.

	@see SDmacCaps::iSrcDstAsymmetry

	@see TDmaTransferArgs::iSrcConfig

	@see TDmaTransferArgs::iDstConfig

*/

struct TDmaTransferConfig

	{

friend struct TDmaTransferArgs;

	/** Default constructor. Initializes all fields with meaningful default

		values.

	*/

#ifdef DMA_APIV2

	KIMPORT_C

#endif

	TDmaTransferConfig();

	/**	Intended for general use ie. not 2D or 1D transfers

	 */

#ifdef DMA_APIV2

	KIMPORT_C

#endif

	TDmaTransferConfig (

		TUint32 aAddr,

		TUint aTransferFlags,

		TDmaAddrMode aAddrMode = KDmaAddrModePostIncrement,

		TUint aSyncFlags = KDmaSyncAuto,

		TDmaBurstSize aBurstSize = KDmaBurstSizeAny,

		TUint aElementSize = 0,

		TUint aElementsPerPacket = 0,

		TUint aPslTargetInfo = 0,

		TInt aRepeatCount = 0

		);

	/**	Intended for 1D and 2D transfers

	 */

#ifdef DMA_APIV2

	KIMPORT_C

#endif

	TDmaTransferConfig (

		TUint32 aAddr,

		TUint aElementSize,

		TUint aElementsPerFrame,

		TUint aFramesPerTransfer,

		TInt aElementSkip,

		TInt aFrameSkip,

		TUint aTransferFlags,

		TUint aSyncFlags = KDmaSyncAuto,

		TDmaBurstSize aBurstSize = KDmaBurstSizeAny,

		TUint aElementsPerPacket = 0,

		TUint aPslTargetInfo = 0,

		TInt aRepeatCount = 0

		);

	/** Transfer start address */

	TUint32 iAddr;

	/** Address mode */

	TDmaAddrMode iAddrMode;

	/** Element size in bytes (1/2/4/8) */

	TUint iElementSize;

	/** Number of elements per frame */

	TUint iElementsPerFrame;

	/** Number of elements per packet */

	TUint iElementsPerPacket;

	/** Number of frames to transfer (result is the transfer block) */

	TUint iFramesPerTransfer;

	/** Element skip in bytes (for addr modes E1DIndex or E2DIndex) */

	TInt iElementSkip;

	/** Frame skip in bytes (for addr mode E2DIndex) */

	TInt iFrameSkip;

	/** Use burst transactions of the specified size (in bytes)

		@see TDmaBurstSize

	*/

	TInt iBurstSize;

	/** PIL src/dst config flags.

		@see TDmaTransferFlags

	 */

	TUint32 iFlags;

	/** Transfer synchronization flags.

		@see TDmaTransferSyncFlags

	*/

	TUint32 iSyncFlags;

	/** Information passed to the PSL */

	TUint iPslTargetInfo;

	/** How often to repeat this (sub-)transfer:

		0     no repeat (the default)

		1..n  once / n times

		-1     endlessly.

	*/

	TInt iRepeatCount;

	/** Structure contents delta vector (usage tbd) */

	TUint32 iDelta;

	/** Reserved for future use */

	TUint32 iReserved;

private:

	/** Private constructor. Initializes fields with the values passed in by

		the legacy version of the DDmaRequest::Fragment() call.

	*/

	TDmaTransferConfig(TUint32 aAddr, TUint aFlags, TBool aAddrInc);

	};

/** To be used by the client to pass DMA transfer request details to the

	framework.

	Also used internally by the framework as a pseudo descriptor if the

	controller doesn't support hardware descriptors (scatter/gather LLI).

	@see DDmaRequest::Fragment

*/

struct TDmaTransferArgs

	{

	friend class DDmaRequest;

	friend class TDmaChannel;

	friend class TDmac;

	friend class DmaChannelMgr;

	/** Default constructor. Initializes all fields with meaningful default

		values.

	*/

#ifdef DMA_APIV2

	KIMPORT_C

#endif

	TDmaTransferArgs();

	/**	For transfers where src and dst TDmaTransferConfig structs share some

		of the same options ie. iDmaTransferFlags, iAddrMode, iSyncFlags,

		iBurstSize, and iElementSize.

		@param aSrcAddr

		@param aDstAddr

		@param aCount Number of bytes to transfer

		@param aDmaTransferFlags Bitmask of TDmaTransferFlags for src and dst

		@param aDmaSyncFlags Bitmask of TDmaTransferSyncFlags for src and dst

		@param aMode Address mode for src and dst

		@param aDmaPILFlags Bitmask of TDmaPILFlags

		@param aElementSize In bytes (1/2/4/8) for src and dst

		@param aChannelPriority

		@param aBurstSize for src and dst

		@param aPslRequestInfo Info word passed to the PSL

		@param aGraphicOp Graphics operation to be executed

		@param aColour Colour value for graphics operation

	*/

#ifdef DMA_APIV2

	KIMPORT_C

#endif

	TDmaTransferArgs (

		TUint aSrcAddr, TUint aDstAddr, TUint aCount,

		TUint aDmaTransferFlags, TUint aDmaSyncFlags = KDmaSyncAuto,

		TUint aDmaPILFlags = 0,

		TDmaAddrMode aMode = KDmaAddrModePostIncrement, TUint aElementSize = 0,

		TUint aChannelPriority = KDmaPriorityNone,

		TDmaBurstSize aBurstSize = KDmaBurstSizeAny, TUint aPslRequestInfo = 0,

		TDmaGraphicsOps aGraphicOp = KDmaGraphicsOpNone, TUint32 aColour = 0

		);

	/** For transfers needing specific options for source and destination

		TDmaTransferConfig structs.

		@param aSrc Configuration values for the source