// 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_hai.h

// DMA Framework - Symbian Hardware Abstraction Interface (SHAI).

//

//

/** @file

	@publishedPartner

	@released

*/

#ifndef __DMA_HAI_H__

#define __DMA_HAI_H__

#include <kernel/kern_priv.h>

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

/** Interface used by PIL to open and close DMA channels.

	Must be implemented by the PSL.

*/

class DmaChannelMgr

	{

public:

	/** Opens a channel using a client-provided identifier.

		This function must be implemented by the PSL.

		@param aOpenId PSL-specific magic cookie passed by client. This could

		identify the channel exactly (by being just the channel number), or at

		least sufficiently (for example for use with a certain peripheral), or

		it may indicate some properties which the channel must possess. It may

		be set to zero always if all channels are equivalent.

		@param aDynChannel ETrue if the Open call is for a dynamic channel. A

		dynamic channel is not exclusively reserved for just one client, and

		further Open calls for more dynamic channels should succeed as long as

		certain resources (but not including the number of available physical

		channels) are not exceeded. Different transfer requests on this dynamic

		channel may be serviced using different actual channels.

		@param aPriority The desired channel priority as requested by the

		client. This may be an actual hardware priority or a

		platform-independent value. Not being able to satisfy the requested

		value is not a reason for the PSL to return NULL. This parameter may be

		ignored if aDynChannel is passed as ETrue. An overriding per-transfer

		priority may be requested by a client later via

		TDmaTransferArgs::iChannelPriority.

		@see SDmacCaps::iChannelPriorities

		@see TDmaPriority

		@return Pointer to channel if available, NULL otherwise. It should not

		be NULL if the Open call was for a dynamic channel unless a processing

		error occurred.

		@pre The PIL calls this function with a global fast mutex held to avoid

		race conditions.

		@post If a non-NULL pointer is returned, the object pointed to has its

		iController, iDmacCaps, iPslId, iDynChannel and iPriority members set

		to valid states.

		iController should point to the controller handling the

		channel.

		iDmacCaps should point to a SDmacCaps structure containing values

		relating to this particular channel.

		iPslId should contain a value uniquely identifying the channel - the

		PIL assigns this value later during request fragmentation to

		TDmaTransferArgs::iChannelCookie. It can be given any convenient value

		by the PSL (channel index, I/O port address, etc.).

		iDynChannel should be set to ETrue by the PSL if a dynamic channel was

		requested and has been opened.

		If applicable, iPriority should contain the actual hardware priority

		that has been configured or reserved. Otherwise it may be left at its

		default value TDmaPriority::KDmaPriorityNone.

	*/

	static TDmaChannel* Open(TUint32 aOpenId, TBool aDynChannel, TUint aPriority);

	/** Performs platform-specific operations when a channel is closed.

		If aChannel was opened as a dynamic channel then this call is a sign

		that there is a client which does not intend to queue any further

		transfer requests via this channel.

		This function must be implemented by the PSL but the implementation can

		be a no-op.

		@param aChannel The channel to close

		@pre The PIL calls this function with a global fast mutex held to avoid

		race conditions.

	*/

	static void Close(TDmaChannel* aChannel);

	/** Function allowing PSL to extend DMA API with new channel-independent

		operations.

		This function must be implemented by the PSL.

		@param aCmd Command identifier. Negative values are reserved for FW

		internal use.

		@param aArg PSL-specific

		@return KErrNotSupported if aCmd is not supported. PSL-specific value

		otherwise.

	*/

	static TInt StaticExtension(TInt aCmd, TAny* aArg);

	/** Acquires the channel manager lock. Called by the PIL before opening and

		closing a channel.

	*/

	static void Wait();

	/** Releases the channel manager lock. Called by the PIL after opening and

		closing a channel.

	*/

	static void Signal();

private:

	/** Declared, defined, and called by PSL's DECLARE_STANDARD_EXTENSION(). */

	friend TInt InitExtension();

	/** Must be called in the PSL's DECLARE_STANDARD_EXTENSION(). */

	static TInt Initialise();

	static NFastMutex Lock;

	};

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

/** Abstract base class representing a DMA controller.

	The class has two purposes.

	First, it is a container for channels, descriptors and descriptor headers.

	Second, it exposes a set of virtual functions implemented by the PSL

	(platform-specific layer).

	These functions are the main interfaces between the PIL

	(platform-independent layer) and PSL.

*/

class TDmac

	{

friend class DmaChannelMgr;

// The following friend declaration will become obsolete once header

// pool manipulation functionality is owned and provided by the controller

// class instead of the request class.

// (TDmac::iFreeHdr could then also be made private.)

friend class DDmaRequest;

friend class TSkelDmac;

protected:

	/** Data required for creating a new instance. */

	struct SCreateInfo

		{

		/** True if DMAC uses hardware descriptors (i.e. supports

			scatter/gather mode).

		*/

		TBool iCapsHwDes;

		/** Initial maximum number of descriptors and headers (shared by all

			channels) to be allocated by the PIL. If at run time more

			descriptors are needed then they will be dynamically allocated and

			added to the available pool.

			The PSL may consider a number of factors when providing this

			initial value, such as the number of channels on this controller,

			the maximum transfer size per descriptor and also likely usage

			scenarios for the platform or device (number of drivers using DMA,

			their traffic patterns, simultaneity of operations, etc.).

			(NB: Dynamic growing of the descriptor pool is not yet implemented

			in the PIL, so this value is currently also the final maximum

			number of descriptors.)

		*/

		TInt iDesCount;

		/** Size of an individual descriptor.

			Use sizeof(TDmaTransferArgs) for single-buffer and double-buffer

		 	(i.e. non-s/g) controllers.

		*/

		TInt iDesSize;

		/** Bitmask used when creating the memory chunk storing the descriptor

			pool in the PIL. Used only for hardware descriptors.

			The access part must be EMapAttrSupRw. If the chunk is cached

			and/or buffered, the PSL must flush the data cache and/or drain the

			write buffer in InitHwDes() and related functions.

			The physical start address of the chunk will always be MMU page

		 	size aligned.

		 	@see TMappingAttributes

		 */

		TUint iDesChunkAttribs;

		};

	/** Base class constructor.

	 */

	TDmac(const SCreateInfo& aInfo);

	/** Base class 2nd-phase constructor.

	 */

	TInt Create(const SCreateInfo& aInfo);

public:

	/** Base class virtual destructor.

	 */

	virtual ~TDmac();

	/** Allocates a number of headers (and hence also descriptors) from the

		header/descriptor pools. Called by the PIL but may also be used by the

		PSL.

	*/

	TInt ReserveSetOfDes(TInt aCount);

	/** Returns previously allocated headers (and hence also descriptors) to

		the header/descriptor pools. Called by the PIL but may also be used by

		the PSL.

	*/

	void ReleaseSetOfDes(TInt aCount);

	/** Called by the PIL during request fragmentation to fill a descriptor or

		pseudo descriptor with transfer arguments.

	*/

	TInt InitDes(const SDmaDesHdr& aHdr, const TDmaTransferArgs& aTransferArgs);

	/** Called by the PIL in TDmaChannel::IsrRedoRequest() if any of the

		latter's arguments is non-zero.

	*/

	TInt UpdateDes(const SDmaDesHdr& aHdr, TUint32 aSrcAddr, TUint32 aDstAddr,

				   TUint aTransferCount, TUint32 aPslRequestInfo);

	/** Returns a reference to the associated pseudo descriptor for a given

		descriptor header. For use by PIL and PSL.

	*/

	inline TDmaTransferArgs& HdrToDes(const SDmaDesHdr& aHdr) const;

	/** Returns a reference to the associated hardware descriptor for a given

		descriptor header. For use by PIL and PSL.

	*/

	inline TAny* HdrToHwDes(const SDmaDesHdr& aHdr) const;

	/** Returns the physical address of the hardware descriptor

		pointed to by aDes. For use by PIL and PSL.

	*/

	inline TUint32 HwDesLinToPhys(TAny* aDes) const;

	/** Called by PIL when one fragment (single-buffer and double-buffer DMACs)

		or list of fragments (scatter/gather DMAC) is to be transferred.

		Called when initiating a new transfer and also, for double-buffer

		DMACs, for configuring the next fragment to transfer while the current

		one is ongoing.

		The function must be implemented by the PSL if

		SCreateInfo::iCaps::iAsymHwDescriptors is reported as false.

		@note This function may be called in thread or ISR context by the PIL

		@param aChannel The channel to use.

		@param aHdr Header associated with fragment to transfer.

	*/

	virtual void Transfer(const TDmaChannel& aChannel, const SDmaDesHdr& aHdr);

	/** Called by PIL when two lists of fragments (scatter/gather DMAC with

		asymmetrical linked-list capability) are to be transferred.

		Called when initiating a new transfer.

		The function must be implemented by the PSL if

		SDmaCaps::iAsymHwDescriptors is reported as true.

		@note This function may be called in thread or ISR context by the PIL

		@param aChannel The channel to use.

		@param aSrcHdr Header associated with descriptor to transfer on the

		source side.

		@param aDstHdr Header associated with descriptor to transfer on the

		destination side.

	*/

	virtual void Transfer(const TDmaChannel& aChannel, const SDmaDesHdr& aSrcHdr,

						  const SDmaDesHdr& aDstHdr);

	/** Called by PIL to stop a transfer on a given channel.

		The stopping must occur synchronously as the PIL assumes the channel

		is halted after calling this function. A channel stopped via this

		function is not intended to be resumed. Function must always be

		implemented by the PSL.

		@param aChannel The channel to stop

		@post The channel will be idle

		@post No interrupt will occur from this channel until a new

		request is queued.

	*/

	virtual void StopTransfer(const TDmaChannel& aChannel) = 0;

	/** Called by PIL to pause (suspend) a transfer on a given channel.

		A paused channel transfer must be able to be resumed by calling

		ResumeTransfer().

		The function must be implemented by the PSL if

		SDmacCaps::iChannelPauseAndResume is reported as true.

		@return KErrNone if the transfer has been paused successfully,

		KErrCompletion if the transfer was already paused, KErrGeneral

		if a general error occurred preventing a successful outcome.

		@post No interrupt will occur from this channel until it is

		resumed.

	*/

	virtual TInt PauseTransfer(const TDmaChannel& aChannel);

	/** Called by PIL to resume a paused (suspended) transfer on a given

		channel.

		Resume() can be called when the transfer is paused as a result of a

		previous call to PauseTransfer() or because the DMAC has encountered a

		Pause bit in a H/W descriptor.

		The function must be implemented by the PSL if

		SDmacCaps::iChannelPauseAndResume or

		SDmacCaps::iLinkedListPausedInterrupt is reported as true.

		@return KErrNone if the transfer has been resumed successfully,

		KErrCompletion if there was no paused transfer, KErrGeneral

		if a general error occurred preventing a successful outcome.

	*/

	virtual TInt ResumeTransfer(const TDmaChannel& aChannel);

	/** Called by PIL to check whether a DMA channel is idle.

		'Idle' here means that the channel is ultimately stopped, for example

		because the transfer has finished, or an error was encountered, or it

		was manually stopped, but not because it was manually suspended (aka

		'paused'), or it is waiting for a request line assertion to start the

		transfer.

		@param aChannel The channel to test

		@return ETrue if channel idle, EFalse if transferring.

	*/

	virtual TBool IsIdle(const TDmaChannel& aChannel) = 0;

	/** Called by PIL to retrieve from the PSL the maximum transfer length

		based on the parameters passed.

		@param aChannel Channel to be used for the transfer

		@param aSrcFlags Bitmask characterising transfer source

		@see TDmaTransferArgs::iSrcConfig::iFlags

		@param aDstFlags Bitmask characterising transfer destination

		@see TDmaTransferArgs::iDstConfig::iFlags

		@param aPslInfo Cookie passed by client and used by the PSL

		@see TDmaTransferArgs::iPslRequestInfo

		@return 0 if transfer length is not limited, the maximum transfer

		length in bytes otherwise.

	*/

	virtual TUint MaxTransferLength(TDmaChannel& aChannel, TUint aSrcFlags,

									TUint aDstFlags, TUint32 aPslInfo) = 0;

	/** Called by PIL to retrieve from the PSL the memory alignment mask based

		on the parameters passed. Some DMA controllers impose alignment

		constraints on the base address of memory buffers. This mask is AND'ed

		against memory addresses computed during fragmentation.

		The PIL will call this function separately for source and destination.

		An assumption is that the PSL doesn't need to know if a call to this

		function is for the source or the destination side, i.e. both ports

		are, as far as the alignment is concerned, equivalent. All that matters

		are the values of the relevant configuration parameters.

		Another assumption is that the alignment requirement for a port on a

		DMAC with potentially different values for source and destination does

		not depend on the configuration of the respective other port.

		@param aChannel Channel used for the transfer

		@param aTargetFlags Bitmask characterising transfer source or

		destination

		@see TDmaTransferArgs::iSrcConfig::iFlags

		@see TDmaTransferArgs::iDstConfig::iFlags

		@param aElementSize Element size used for the transfer. May be zero if

		not known or 'don't care'.

		@param aPslInfo Cookie passed by client and used by the PSL

		@see TDmaTransferArgs::iPslRequestInfo

		@return A value representing the alignment mask (e.g. 3 if buffer must

		be 4-byte aligned)

	*/

	virtual TUint AddressAlignMask(TDmaChannel& aChannel, TUint aTargetFlags,

								   TUint aElementSize, TUint32 aPslInfo) = 0;

	/** Called by PIL during fragmentation to initialise a hardware descriptor.

		The PSL must assume the descriptor is the last in the chain and so set

		the interrupt bit and set the next descriptor field to an end of chain

		marker.

		The function must be implemented by the PSL if and only if the DMAC

		supports hardware descriptors and SDmaCaps::iAsymHwDescriptors is

		reported as false.

		@param aHdr Header associated with the hardware descriptor to

		initialise

		@param aTransferArgs The transfer parameters for this descriptor

		@return KErrNone if the descriptor was successfully initialized,

		KErrArgument if any of the transfer arguments were detected to be

		invalid, KErrGeneral if a general error occurred preventing a

		successful outcome.

	*/

	virtual TInt InitHwDes(const SDmaDesHdr& aHdr, const TDmaTransferArgs& aTransferArgs);

	/** Called by PIL during fragmentation to initialise a hardware descriptor

		on the source side of an asymmetric linked list.

		The function must be implemented by the PSL if

		SDmaCaps::iAsymHwDescriptors is reported as true.

		@param aHdr Header associated with the hardware descriptor to

		initialise

		@param aTransferArgs The transfer parameters for this descriptor. Only

		the elements relating to the source side should be relevant to the

		implementation.

		@return KErrNone if the descriptor was successfully initialized,

		KErrArgument if any of the transfer arguments were detected to be

		invalid, KErrGeneral if a general error occurred preventing a

		successful outcome.

	*/

	virtual TInt InitSrcHwDes(const SDmaDesHdr& aHdr, const TDmaTransferArgs& aTransferArgs);

	/** Called by PIL during fragmentation to initialise a hardware descriptor

		on the destination side of an asymmetric linked list.

		The function must be implemented by the PSL if

		SDmaCaps::iAsymHwDescriptors is reported as true.

		@param aHdr Header associated with the hardware descriptor to

		initialise

		@param aTransferArgs The transfer parameters for this descriptor. Only

		the elements relating to the destination side should be relevant to the

		implementation.

		@return KErrNone if the descriptor was successfully initialized,

		KErrArgument if any of the transfer arguments were detected to be

		invalid, KErrGeneral if a general error occurred preventing a

		successful outcome.

	*/

	virtual TInt InitDstHwDes(const SDmaDesHdr& aHdr, const TDmaTransferArgs& aTransferArgs);

	/** Called by the PIL in ISR context to change specific fields in a

		hardware descriptor.

		The function must be implemented by the PSL if and only if the DMAC

		supports hardware descriptors and SDmaCaps::iAsymHwDescriptors is

		reported as false.

		@param aHdr Header associated with the hardware descriptor to be

		updated

		@param aSrcAddr @see TDmaTransferArgs::iSrcConfig::iAddr

		@param aDstAddr @see TDmaTransferArgs::iDstConfig::iAddr

		@param aTransferCount @see TDmaTransferArgs::iTransferCount

		@param aPslRequestInfo @see TDmaTransferArgs::iPslRequestInfo