// Copyright (c) 2002-2010 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/dma_v2.h

// DMA Framework - Client API v2 definition.

//

// NB: DMA clients should never include this file directly, but only ever the

// generic header file <drivers/dma.h>.

//

/** @file

	@publishedPartner

*/

#ifndef __DMA_H__

#error "dma_v2.h must'n be included directly - use <drivers/dma.h> instead"

#endif	// #ifndef __DMA_H__

#ifndef __DMA_V2_H__

#define __DMA_V2_H__

#include <kernel/kernel.h>

#include <drivers/dmadefs.h>

//////////////////////////////////////////////////////////////////////////////

// Debug Support - KDmaPanicCat is defined in each source file

#define __DMA_ASSERTD(e) __ASSERT_DEBUG(e, Kern::Fault(KDmaPanicCat, __LINE__))

#define __DMA_ASSERTA(e) __ASSERT_ALWAYS(e, Kern::Fault(KDmaPanicCat, __LINE__))

#ifdef _DEBUG

#define __DMA_CANT_HAPPEN() Kern::Fault(KDmaPanicCat, __LINE__)

#define __DMA_DECLARE_INVARIANT public: void Invariant();

#define __DMA_INVARIANT() Invariant()

#else

#define __DMA_CANT_HAPPEN()

#define __DMA_DECLARE_INVARIANT

#define __DMA_INVARIANT()

#endif

//////////////////////////////////////////////////////////////////////////////

// INTERFACE EXPOSED TO DEVICE-DRIVERS

//////////////////////////////////////////////////////////////////////////////

//////////////////////////////////////////////////////////////////////////////

/** Bitmasks used for configuring a DMA request.

	In general, specify KDmaMemSrc|KDmaIncSrc (resp. KDmaMemDest|KDmaIncDest)

	if the source (resp. destination) is a memory buffer and clear

	KDmaMemSrc|KDmaIncSrc (resp. KDmaMemDest|KDmaIncDest) if the source

	(resp. destination) is a peripheral.

	If the location is given as a physical address (rather than a linear one)

	then also specify KDmaPhysAddrSrc and/or KDmaPhysAddrDest.

	The EKA1 "Fill Mode" can be implemented by omitting KDmaIncSrc.

	Some peripherals may require a post-increment address mode.

	@see DDmaRequest::Fragment()

	Note: This enum is only required for backwards compatibility with the old

	DMA framework, it can be removed once this is no longer needed.

	@deprecated

*/

enum TDmaRequestFlags

	{

	/** Source is address of memory buffer */

	KDmaMemSrc       = 0x01,

	/** Destination is address of memory buffer */

	KDmaMemDest      = 0x02,

	/** Source address must be post-incremented during transfer */

	KDmaIncSrc       = 0x04,

	/** Destination address must be post-incremented during transfer */

	KDmaIncDest      = 0x08,

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

	KDmaPhysAddrSrc  = 0x10,

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

	KDmaPhysAddrDest = 0x20,

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

	KDmaAltTransferLen = 0x40

	};

/** Each hardware or pseudo descriptor is associated with a header.  Headers

	are needed because hardware descriptors can not easily be extended to store

	additional information.

	@released

*/

struct SDmaDesHdr

	{

	SDmaDesHdr* iNext;

	};

/** Pointer to signature of the new extended callback function.

	TUint       - bitmask of one or more TDmaCallbackType values

	TDmaResult  - just that

	TAny*       - was provided by client in DDmaRequest constructor

	SDmaDesHdr* - points to header (and thus descriptor) which caused a

	'descriptor completed' or 'descriptor paused' event

	@released

 */

typedef void (*TDmaCallback)(TUint, TDmaResult, TAny*, SDmaDesHdr*);

class TDmaChannel;

/** A DMA request is a list of fragments small enough to be transferred in one go

	by the DMAC.

	In general, fragmentation is done in the framework by calling Fragment() but

	clients with special needs can allocate a blank descriptor list with

	ExpandDesList() and customise it to fit their needs.

	Clients should not set attributes directly, but should use the various functions

	instead.

	This class has not been designed to be called from several concurrent threads.

	Multithreaded clients must implement their own locking scheme (via DMutex).

	Mutexes are used internally to protect data structures accessed both by the

	client thread and the DFC thread. Therefore no fast mutex can be held when

	calling a request function.

*/

class DDmaRequest : public DBase

	{

	friend class TDmaChannel;

public:

	/** The outcome of the transfer

		@see TDmaResult

		@deprecated

	*/

	enum TResult {EBadResult=0, EOk, EError};

	/** The signature of the completion/failure callback function

		@see TDmaCallback

		@deprecated

	*/

	typedef void (*TCallback)(TResult, TAny*);

public:

    /** Constructor.

		Create a new transfer request.

		@param aChannel The channel this request is bound to.

		@param aCb Callback function called on transfer completion or failure

		(in channel DFC context).  Can be NULL.

		@param aCbArg   Argument passed to callback function.

		@param aMaxTransferSize Maximum fragment size.  If not specified, defaults to the maximum size

		supported by the DMA controller for the type of transfer that is later scheduled.

		@deprecated

    */

	IMPORT_C DDmaRequest(TDmaChannel& aChannel, TCallback aCb=NULL, TAny* aCbArg=NULL,

						 TInt aMaxTransferSize=0);

	/** Constructor.

		Create a new transfer request.

		@param aChannel The channel this request is bound to.

		@param aDmaCb Callback function called on transfer completion or

		failure (in channel DFC or ISR context). Can be NULL.

		@param aCbArg Argument passed to callback function.

		@param aMaxTransferSize Maximum fragment size. If not specified,

		defaults to the maximum size supported by the DMA controller for the

		type of transfer that is later scheduled.

		@released

	*/

	IMPORT_C DDmaRequest(TDmaChannel& aChannel, TDmaCallback aDmaCb,

						 TAny* aCbArg=NULL, TUint aMaxTransferSize=0);

	/** Destructor.

		Assume the request is not being transferred or pending.

		@released

	*/

	IMPORT_C ~DDmaRequest();

	/** Split request into a list of fragments small enough to be fed to the

		DMAC.

		The size of each fragment is smaller than or equal to the maximum

		transfer size supported by the DMAC. If the source and/or destination

		is memory, each fragment points to memory which is physically

		contiguous.

		The kind of transfer to perform is specified via a set of flags used by

		a PIL and a magic cookie passed to the PSL. If the source

		(resp. destination) is a peripheral, aSrc (resp. aDest) is treated as a

		magic cookie by the PIL and passed straight to the PSL.

		The request can be uninitialised or may have been fragmented

		previously. The previous configuration if any is lost whether or not

		the function succeeds.

		The client must ensure that any memory buffers involved in the transfer

		have been suitably prepared for DMA. For memory allocated on the kernel

		side or in a shared chunk this amounts to ensuring cache consistency

		before Queue() is called. However for memory that was allocated on the

		user side the client must also ensure that the memory is protected from

		both data paging and RAM defragmentation before Fragment() is called

		@see Kern::MapAndPinMemory(). Note however, that this function is only

		available if the flexible memory model (FMM) is in use.

		@param aSrc Source memory buffer linear address or peripheral magic

		cookie.

		@param aDest Destination memory buffer linear address or peripheral

		magic cookie.

		@param aCount Number of bytes to transfer.

		@param aFlags Bitmask characterising the transfer.

		@param aPslInfo Hardware-specific information passed to PSL.

		@return KErrNone if success. KErrArgument if aFlags and/or aPslInfo are

		invalid when finding the maximum transfer size. May also fail if

		running out of descriptors.

		@pre The request is not being transferred or pending.

		@pre The various parameters must be valid. The PIL or PSL will fault the

		kernel if not.

		@see TDmaRequestFlags

		@deprecated

    */

	IMPORT_C TInt Fragment(TUint32 aSrc, TUint32 aDest, TInt aCount, TUint aFlags, TUint32 aPslInfo);

	/** New version of the DMA request fragment function, to be used with the

		TDmaTransferArgs structure.

		Split request into a list of fragments small enough to be fed to the

		DMAC.

		The size of each fragment is smaller than or equal to the maximum

		transfer size supported by the DMAC. If the source and/or destination

		is memory, each fragment points to memory which is physically

		contiguous.

		The request can be uninitialised or may have been fragmented

		previously. Any previous configuration is lost whether or not the

		function succeeds.

		The client must ensure that any memory buffers involved in the transfer

		have been suitably prepared for DMA. For memory allocated on the kernel

		side or in a shared chunk this amounts to ensuring cache consistency

		before Queue() is called. However for memory that was allocated on the

		user side the client must also ensure that the memory is protected from

		both data paging and RAM defragmentation before Fragment() is called

		@see Kern::MapAndPinMemory(). Note however, that this function is only

		available if the flexible memory model (FMM) is in use.

		@param aTransferArgs Describes the transfer to be performed.

		@return KErrNone if success. KErrArgument if certain arguments are

		invalid. May also fail if running out of descriptors.

		@pre The request is not being transferred or pending.

		@pre The various parameters must be valid. The PIL or PSL will fault

		the kernel if not.

		@released

	*/

	IMPORT_C TInt Fragment(const TDmaTransferArgs& aTransferArgs);

	/** Transfer asynchronously this request.

		If this request's channel is idle, the request is transferred

		immediately. Otherwise, it is queued and transferred later.

		The client is responsible for ensuring cache consistency before and/or

		after the transfer if necessary.

		@return KErrNone if success, KErrGeneral otherwise.

		@released

	*/

	IMPORT_C TInt Queue();

	/** Append new descriptor(s) to existing list.

		Clients needing to build a custom descriptor list should call this

		function to allocate the list and access the resulting list through

		iFirstHdr and iLastHdr.

		Clients should not change the value of iFirstHdr, iLastHdr and the

		iNext field of the descriptor headers to ensure descriptors can be

		deallocated. Clients are free to change hardware descriptors, including

		chaining, in whatever way suit them.

		Assume the request is not being transferred or pending.

		@param aCount Number of descriptors to append.

		@return KErrNone or standard error code.

		@released

	*/

	IMPORT_C TInt ExpandDesList(TInt aCount=1);

	/** Append new descriptor(s) to existing list. This function variant

		operates on the source port descriptor chain.

		Works like ExpandDesList except that it uses the iSrcFirstHdr and

		iSrcLastHdr fields.

		@see ExpandDesList()

		This function should only be used if SDmacCaps::iAsymHwDescriptors is

		reported as true, as only then the framework will actually use the

		allocated descriptors.

		@param aCount Number of descriptors to append.

		@return KErrNone or standard error code.

		@prototype

	*/

	IMPORT_C TInt ExpandSrcDesList(TInt aCount=1);

	/** Append new descriptor(s) to existing list. This function variant

		operates on the destination port descriptor chain.

		Works like ExpandDesList except that it uses the iDstFirstHdr and

		iDstLastHdr fields.

		@see ExpandDesList()

		This function should only be used if SDmacCaps::iAsymHwDescriptors is

		reported as true, as only then the framework will actually use the

		allocated descriptors.

		@param aCount Number of descriptors to append.

		@return KErrNone or standard error code.

		@prototype

	*/

	IMPORT_C TInt ExpandDstDesList(TInt aCount=1);

	/** Free resources associated with this request.

		Assumes the request is not being transferred or pending.

		@see ExpandDesList()

		@released

	*/

	IMPORT_C void FreeDesList();

	/** Free resources associated with this request. This function variant

		operates on the source port descriptor chain.

		Assumes the request is not being transferred or pending.

		@see ExpandSrcDesList()

		@prototype

	*/

	IMPORT_C void FreeSrcDesList();

	/** Free resources associated with this request. This function variant

		operates on the destination port descriptor chain.

		Assumes the request is not being transferred or pending.

		@see ExpandDstDesList()

		@prototype

	*/

	IMPORT_C void FreeDstDesList();

	/** Enables the functionality for counting the transferred source

		elements.

		This function can be called at any time, but the enabled/disabled

		status is checked by the framework only at two points in time.

		The first one is after a request has been queued, and if it is enabled

		then the counting will commence as soon as the transfer starts.

		The second point is when Resume() is called for a paused transfer, and

		in this case the following applies. If counting was enabled when the

		transfer was paused and it is now disabled then the counting is stopped

		at that point and the count value frozen. If counting was disabled when

		the transfer was paused and it is now enabled then the counting will

		commence when the transfer resumes. (The starting value will depend on

		the argument of the enable function.) Otherwise nothing will change,

		i.e. counting will either continue normally (enabled/enabled) or

		neither stop nor continue (disabled/disabled).

		Once a status has been set, it remains valid for the entire duration of

		the transfer (and beyond, if it is not changed again).

		@param aResetElementCount If ETrue (the default) then the count

		variable will be reset to zero, otherwise it will retain its current

		value.

		@see Queue()

		@see TotalNumSrcElementsTransferred()

		@prototype

	*/

	IMPORT_C void EnableSrcElementCounting(TBool aResetElementCount=ETrue);

	/** Enables the functionality for counting the transferred destination

		elements.

		This function can be called at any time, but the enabled/disabled

		status is checked by the framework only at two points in time.

		The first one is after a request has been queued, and if it is enabled

		then the counting will commence as soon as the transfer starts.

		The second point is when Resume() is called for a paused transfer, and

		in this case the following applies. If counting was enabled when the

		transfer was paused and it is now disabled then the counting is stopped

		at that point and the count value frozen. If counting was disabled when

		the transfer was paused and it is now enabled then the counting will

		commence when the transfer resumes. (The starting value will depend on

		the argument of the enable function.) Otherwise nothing will change,

		i.e. counting will either continue normally (enabled/enabled) or

		neither stop nor continue (disabled/disabled).

		Once a status has been set, it remains valid for the entire duration of

		the transfer (and beyond, if it is not changed again).

		@param aResetElementCount If ETrue (the default) then the count

		variable will be reset to zero, otherwise it will retain its current

		value.

		@see Queue()

		@see TotalNumDstElementsTransferred()

		@prototype

	*/

	IMPORT_C void EnableDstElementCounting(TBool aResetElementCount=ETrue);

	/** Disables the functionality for counting the transferred source

		elements.

		This function can be called at any time, but the enabled/disabled

		status is checked by the framework only at two points in time.

		The first one is after a request has been queued, and if it is enabled

		then the counting will commence as soon as the transfer starts.

		The second point is when Resume() is called for a paused transfer, and

		in this case the following applies. If counting was enabled when the

		transfer was paused and it is now disabled then the counting is stopped

		at that point and the count value frozen. If counting was disabled when

		the transfer was paused and it is now enabled then the counting will

		commence when the transfer resumes. (The starting value will depend on

		the argument of the enable function.) Otherwise nothing will change,

		i.e. counting will either continue normally (enabled/enabled) or

		neither stop nor continue (disabled/disabled).

		Once a status has been set, it remains valid for the entire duration of

		the transfer (and beyond, if it is not changed again).

		@see Queue()

		@see TotalNumSrcElementsTransferred()