FCL/sf/os/kernelhwsrv: comparison kernel/eka/include/drivers/dma

equal deleted inserted replaced

-:a990138eda40
+:c30940f6d922
 //
 // 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__
 	The EKA1 "Fill Mode" can be implemented by omitting KDmaIncSrc.
 	Some peripherals may require a post-increment address mode.
 	@see DDmaRequest::Fragment
-	@publishedPartner
-	@released
+	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
 	{
-	// Note: This enum is only required for backwards compatibility with the
-	// old DMA framework, it can be removed once this is no longer needed.
 	/** Source is address of memory buffer */
 	KDmaMemSrc       = 0x01,
 	/** Destination is address of memory buffer */
 	KDmaMemDest      = 0x02,
 	/** Source address must be post-incremented during transfer */
 /** 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.
-	@publishedPartner
 	@released
 */
 struct SDmaDesHdr
 	{
 	SDmaDesHdr* iNext;
 	};
 /** Pointer to signature of the new extended callback function.
-	TUint - bitmask of one or more TDmaCallbackType values
+	TUint       - bitmask of one or more TDmaCallbackType values
-	TDmaResult - just that
+	TDmaResult  - just that
-	TAny* - was provided by client in DDmaRequest constructor
+	TAny*       - was provided by client in DDmaRequest constructor
 	SDmaDesHdr* - points to header (and thus descriptor) which caused a
-	'descriptor completed' or 'descriptor paused' event.
+	'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
 	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.
+*/
-	@publishedPartner
-	@released
-*/
 class DDmaRequest : public DBase
 	{
 	friend class TDmaChannel;
 public:
 	/** The outcome of the transfer
+		@see TDmaResult
 		@deprecated
-		@see TDmaResult
 	*/
 	enum TResult {EBadResult=0, EOk, EError};
 	/** The signature of the completion/failure callback function
+		@see TDmaCallback
 		@deprecated
-		@see TDmaCallback
 	*/
 	typedef void (*TCallback)(TResult, TAny*);
 public:
 /** Constructor.
 		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.
-	*/
-	IMPORT_C DDmaRequest(TDmaChannel& aChannel, TDmaCallback aDmaCb, TAny* aCbArg=NULL,
+		@released
-						 TUint aMaxTransferSize=0);
+	*/
+	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.
 		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.
 	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.
 		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.
+	/** 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.
 		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
+	/** 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.
 		true, otherwise it will just return KErrGeneral.
 		@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
+	/** 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.
 		true, otherwise it will just return KErrGeneral.
 		@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.
 		Assume the request is not being transferred or pending.
-*/
+		@released
+	*/
 	IMPORT_C void FreeDesList();
 	/** Free resources associated with this request. This function variant
 		operates on the source port descriptor chain.
 		@see FreeDesList
 		This function can only be used if SDmacCaps::iAsymHwDescriptors is
 		true, otherwise it will do nothing.
-*/
+		@prototype
+	*/
 	IMPORT_C void FreeSrcDesList();
 	/** Free resources associated with this request. This function variant
 		operates on the destination port descriptor chain.
 		@see FreeDesList
 		This function can only be used if SDmacCaps::iAsymHwDescriptors is
 		true, otherwise it will do nothing.
-*/
+		@prototype
+	*/
 	IMPORT_C void FreeDstDesList();
 	/** Enables the functionality for counting the transferred source
 		elements.
 		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
 		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
 		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()
+		@prototype
 	*/
 	IMPORT_C void DisableSrcElementCounting();
 	/** Disables the functionality for counting the transferred destination
 		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 TotalNumDstElementsTransferred()
+		@prototype
 	*/
 	IMPORT_C void DisableDstElementCounting();
 	/** Returns the number of elements that have been transferred by this
 		(completed with or without error, or because it was cancelled) or while
 		it is paused. Otherwise it may just return 0.
 		@return The number of elements that have been transferred by this
 		transfer request at the source port.
+		@prototype
 	*/
 	IMPORT_C TUint32 TotalNumSrcElementsTransferred();
 	/** Returns the number of elements that have been transferred by this
 		(completed with or without error, or because it was cancelled) or while
 		it is paused. Otherwise it may just return 0.
 		@return The number of elements that have been transferred by this
 		transfer request at the destination port.
+		@prototype
 	*/
 	IMPORT_C TUint32 TotalNumDstElementsTransferred();
 	/** Returns the number of fragments that this transfer request has been
 		return 0, and SrcFragmentCount() / DstFragmentCount() should be used
 		instead.
 		@return The number of fragments (descriptors / pseudo descriptors) that
 		this transfer request has been split into.
-	 */
+		@released
+	*/
 	IMPORT_C TInt FragmentCount();
 	/** Returns the number of source port fragments that this transfer request
 		has been split into.
 		This number will only be different from 0 once Fragment() has been
 		This function can only be used if SDmacCaps::iAsymHwDescriptors is
 		true, otherwise it will always return 0.
 		@return The number of source port fragments (descriptors) that this
 		transfer request has been split into.
-	 */
+		@prototype
+	*/
 	IMPORT_C TInt SrcFragmentCount();
 	/** Returns the number of destination port fragments that this transfer
 		request has been split into.
 		This function can only be used if SDmacCaps::iAsymHwDescriptors is
 		true, otherwise it will always return 0.
 		@return The number of destination port fragments (descriptors) that
 		this transfer request has been split into.
-	 */
+		@prototype
+	*/
 	IMPORT_C TInt DstFragmentCount();
 private:
 	inline void OnDeque();
-	TUint GetTransferCount(const TDmaTransferArgs& aTransferArgs);
+	TInt CheckTransferConfig(const TDmaTransferConfig& aTarget, TUint aCount) const;
+	TInt CheckMemFlags(const TDmaTransferConfig& aTarget, TUint aCount) const;
+	TInt AdjustFragmentSize(TUint& aFragSize, TUint aElementSize, TUint aFrameSize);
+	TUint GetTransferCount(const TDmaTransferArgs& aTransferArgs) const;
+	TUint GetMaxTransferlength(const TDmaTransferArgs& aTransferArgs, TUint aCount) const;
 	TInt Frag(TDmaTransferArgs& aTransferArgs);
 	TInt FragSym(TDmaTransferArgs& aTransferArgs, TUint aCount, TUint aMaxTransferLen);
 	TInt FragAsym(TDmaTransferArgs& aTransferArgs, TUint aCount, TUint aMaxTransferLen);
 	TInt FragAsymSrc(TDmaTransferArgs& aTransferArgs, TUint aCount, TUint aMaxTransferLen);
 	TInt FragAsymDst(TDmaTransferArgs& aTransferArgs, TUint aCount, TUint aMaxTransferLen);
+	TInt FragBalancedAsym(TDmaTransferArgs& aTransferArgs, TUint aCount, TUint aMaxTransferLen);
 	TInt ExpandDesList(TInt aCount, TInt& aDesCount, SDmaDesHdr*& aFirstHdr,
 					   SDmaDesHdr*& aLastHdr);
 	void FreeDesList(TInt& aDesCount, SDmaDesHdr*& aFirstHdr, SDmaDesHdr*& aLastHdr);
 	TInt FragmentCount(const SDmaDesHdr* aHdr);
 public:
 	// WARNING: The following attributes are accessed both in client and DFC
-	// context and so accesses must be protected with the channel lock.
+	// thread context, so accesses must be protected with the channel lock.
 	TDmaChannel& iChannel;		/**< The channel this request is bound to */
 	TCallback iCb;			 /**< Called on completion/failure (can be NULL) */
 	TAny* iCbArg;			 /**< Callback argument */
 	TDmaCallback iDmaCb;		// the new-style callback function
 	TAny* iDmaCbArg;			// the new-style callback arg
 	scheme (via DMutex).
 	Mutexes are used internally to protect data structures accessed both by the
 	client thread and the DFC one. Therefore no fast mutex can be held when
 	calling a channel function.
+*/
-	@publishedPartner
-	@released
-*/
 class TDmaChannel
 	{
 	friend class DDmaRequest;
 	friend class TDmac;
 	friend class DmaChannelMgr;
 public:
+	/** Information passed by client when opening a channel. */
-	/** Information passed by client when opening a channel */
 	struct SCreateInfo
 		{
 		/** Default constructor. Initializes all fields with meaningful default
 			values.
 			Must be inline (for now) because exporting it would break existing
 			custom DMA libs as their clients would need the export which would
 			be missing from the custom .def files.
+			@released
 		*/
 		SCreateInfo() : iPriority(KDmaPriorityNone), iDynChannel(EFalse) {};
-		/** Identifier used by PSL to select channel to open */
+		/** Identifier used by PSL to select channel to open.
+			@released
+		*/
 		TUint32 iCookie;
-		/** Number of descriptors this channel can use.
+		/** Number of descriptors this channel can maximally use.
-			This number is not used in the upgraded version of the DMA
+			This value will not be used in the fully implemented new version of
-			framework and is kept there only for source compatibility. If the
+			the DMA framework. Until then it is still required.
-			client is certain that it will only ever use that version, then the
-			value passed here doesn't matter - the framework will ignore it.
+			@released
+		*/
-			@deprecated
-		 */
 		TInt iDesCount;
 		/** DFC queue used to service DMA interrupts.
 			The DFC thread priority must be higher than any client thread
 			priority to avoid a situation where a transfer completes while
 			being cancelled and another transfer is started before the DFC
 			thread gets a chance to run. This would lead to a stray DFC.
+			@released
 		*/
 		TDfcQue* iDfcQ;
-		/** DFC priority */
+		/** DFC priority.
+			@released
+		*/
 		TUint8 iDfcPriority;
 		/** Used by PSL to configure a channel priority (if possible).
 			The default is KDmaPriorityNone (the don't care value).
-		    @see TDmaPriority
+			@see TDmaPriority
+			@prototype
 		*/
 		TUint iPriority;
 		/** Request a dynamic DMA channel.
 			If this is set to ETrue then the Open call is for a 'dynamic' as
 			opposed to a static and solely owned DMA channel. A number of
 			properties of the opened TDmaChannel object will be different in
 			that case.
 			The default value is EFalse.
+			@prototype
 		 */
 		TBool iDynChannel;
 		};
 public:
-/** Opens the DMA channel.
+	/** Opens the DMA channel.
 		Channel selection is done by the hardware-specific layer using a cookie
 		passed in via aInfo.
 		The client should not delete the returned pointer as the framework owns
 		@param aChannel Points to open channel on successful return. NULL
 		otherwise.
 		@return KErrNone or standard error code.
-	*/
+		@released
+	*/
 	IMPORT_C static TInt Open(const SCreateInfo& aInfo, TDmaChannel*& aChannel);
 	/** Closes a previously opened DMA channel.
 		The call will cause the resources associated with this channel to be
 		released, and the pointer/reference to it mustn't therefore be accessed
 		any longer after the function has returned. The channel pointer should
 		be set to NULL by the client.
+		@released
 	*/
 	IMPORT_C void Close();
 	/** Logically links this channel to the one specified as an argument, or,
 		successfully, KErrCompletion if this channel was already linked to
 		aChannel or already unlinked, KErrNotSupported if the DMAC doesn't
 		support channel linking, KErrArgument if this channel was already
 		linked to a different channel, KErrGeneral if a general error occurred
 		preventing a successful outcome.
-	 */
+		@prototype
+	*/
 	IMPORT_C TInt LinkToChannel(TDmaChannel* aChannel);
 	/** Pauses an active transfer on this channel.
 		A paused channel transfer can be resumed by calling Resume() or it can
 		be stopped altogether by calling CancelAll().
 		@return KErrNone if a transfer has been paused successfully,
 		KErrCompletion if a transfer was already paused, KErrNotSupported if
 		the DMAC doesn't support channel transfer pausing/resuming, KErrGeneral
 		if a general error occurred preventing a successful outcome.
-	 */
+		@released
+	*/
 	IMPORT_C TInt Pause();
 	/** Resumes a transfer on this channel that is paused.
 		@see TDmaCallbackType::EDmaCallbackLinkedListPaused
 		Function can only be used if the DMAC supports this functionality.
 		@see SDmacCaps::iChannelPauseAndResume
+		@see SDmacCaps::iLinkedListPausedInterrupt
 		@return KErrNone if a paused transfer has been resumed successfully,
 		KErrCompletion if there was no paused transfer, KErrNotSupported if the
 		DMAC doesn't support channel transfer pausing/resuming, KErrGeneral if
 		a general error occurred preventing a successful outcome.
-	 */
+		@released
+	*/
 	IMPORT_C TInt Resume();
 	/** Cancels the current request and all the pending ones.
-	 */
+		@released
+	*/
 	IMPORT_C void CancelAll();
 	/** Returns the channel's maximum transfer length based on the passed
 		arguments.
 		@param aPslInfo Cookie passed to the PSL
 		@see TDmaTransferArgs::iPslRequestInfo
 		@return 0 if transfer length is not limited, the maximum transfer
 		length in bytes otherwise.
+		@released
 	*/
 	IMPORT_C TUint MaxTransferLength(TUint aSrcFlags, TUint aDstFlags, TUint32 aPslInfo);
 	/** Retrieves from the PSL the address / memory alignment mask based on the
 		@param aPslInfo Cookie passed to the PSL
 		@see TDmaTransferArgs::iPslRequestInfo
 		@return A value representing the alignment mask (e.g. 3 if buffer must
 		be 4-byte aligned)
-	 */
+		@released
+	*/
 	IMPORT_C TUint AddressAlignMask(TUint aTargetFlags, TUint aElementSize,
 									TUint32 aPslInfo);
 	/** Returns a reference to a structure containing the capabilities and
 		features of the DMA controller associated with this channel.
 		@return A reference to a structure containing the capabilities and
 		features of the DMA controller associated with this channel.
-	 */
+		@released
+	*/
 	IMPORT_C const SDmacCaps& DmacCaps();
 	/** Sets up once more the transfer request that has just completed, after
 		optionally having adjusted the transfer parameters as specified.
 		@see DDmaRequest::DDmaRequest(TDmaChannel&, TDmaCallback, TAny*, TUint)
 		@see TDmaCallbackType::EDmaCallbackRequestCompletion
 		@see TDmaPILFlags::KDmaRequestCallbackFromIsr
 		@return KErrGeneral if there was an error, KErrNone otherwise.
-	 */
+		@released
+	*/
 	IMPORT_C TInt IsrRedoRequest(TUint32 aSrcAddr=KPhysAddrInvalid,
 								 TUint32 aDstAddr=KPhysAddrInvalid,
 								 TUint aTransferCount=0,
 								 TUint32 aPslRequestInfo=0,
 								 TBool aIsrCb=ETrue);
 		@return ETrue if channel is currently opened, EFalse otherwise.
 		NB: This API should not be used any longer.
 		After calling TDmaChannel::Open() successfully the channel is
-		guaranteed to be open. Therefore there seems no good reason for this
+		guaranteed to be open, hence there seems no good reason for this API to
-		API to exist.
+		exist.
 		@deprecated
-	 */
+	*/
 	inline TBool IsOpened() const;
 	/** Tests whether the channel's request queue is currently empty.
 		@return ETrue if request queue is currently empty, EFalse otherwise.
-	 */
+		@released
+	*/
 	inline TBool IsQueueEmpty() const;
 	/** Returns a PSL-specific value which uniquely identifies this channel -
 		it is used for debug tracing by the PIL.
 		@return PSL-specific value which uniquely identifies this channel.
-	 */
+		@released
+	*/
 	inline TUint32 PslId() const;
 	/** Called by a test harness to force an error when the next fragment is
 		transferred.
 		@param aFragmentCount The number of consecutive fragments to fail
-	 */
+		@released
+	*/
 	IMPORT_C TInt FailNext(TInt aFragmentCount);
 	/** Called by a test harness to force the DMA controller to miss one or
 		more interrupts.
 		@param aInterruptCount The number of consecutive interrupts to miss
-	 */
+		@released
+	*/
 	IMPORT_C TInt MissNextInterrupts(TInt aInterruptCount);
 	/** Function allowing platform-specific layer to extend channel API with
 		new channel-specific operations.
-		@param aCmd Command identifier. Negative values are reserved for use by
+		@param aCmd Command identifier.
-		Nokia.
 		@param aArg PSL-specific argument
 		@return KErrNotSupported if aCmd is not supported. PSL-specific value
 		otherwise.
-	 */
+		@released
+	*/
 	IMPORT_C TInt Extension(TInt aCmd, TAny* aArg);
 	/** This is a function that allows the Platform Specific Layer (PSL) to
 		extend the DMA API with new channel-independent operations.
-		@param aCmd Command identifier. Negative values are reserved for
+		@param aCmd Command identifier.
-		Symbian use.
 		@param aArg PSL-specific.
 		@return KErrNotSupported if aCmd is not supported; a PSL specific value
 		otherwise.
+		@released
 	*/
 	IMPORT_C TInt StaticExtension(TInt aCmd, TAny* aArg);
-	/** @deprecated
+	/** @see DmacCaps()
-		@see DmacCaps()
-	 */
+		@deprecated
+	*/
 	inline const TDmac* Controller() const;
-	/** @deprecated
+	/** @see MaxTransferLength()
-		@see MaxTransferLength()
-	 */
+		@deprecated
+	*/
 	inline TInt MaxTransferSize(TUint aFlags, TUint32 aPslInfo);
-	/** @deprecated
+	/** @see AddressAlignMask()
-		@see AddressAlignMask()
-	 */
+		@deprecated
+	*/
 	inline TUint MemAlignMask(TUint aFlags, TUint32 aPslInfo);
 protected:
 	// Interface with state machines
+	/** Constructor.
+		@released
+	*/
 	TDmaChannel();
 	/** Called by the PIL when adding a new request to the channel's queue.
 		The implementation should update the channel's state as appropriate
 		and begin transfer of aReq if possible.
 		@param aReq The request which has been added to the queue
+		@released
 	*/
 	virtual void DoQueue(const DDmaRequest& aReq);
 	/** Called by the PIL in response to a CancelAll call. It should update
 		the channel state appropriately.
+		@released
 	*/
 	virtual void DoCancelAll() = 0;
 	/** This is called by the PIL when a DDmaRequest is removed from the
 		channel's queue. In general the implementation simply needs to unlink
 		is completed so that the request may be requeued by the client without
 		having called DDmaRequest::Fragment again.
 		@param aHdr The header for a descriptor, which must be unlinked
 		from its next descriptor (if there is one)
+		@released
 	*/
 	virtual void DoUnlink(SDmaDesHdr& aHdr);
 	/** Called by the PIL whenever a transfer associated with aCurReq is
 		done. The implementation must advance the channel's state and
 		complete.
 		@param aCurReq The current request.
 		@param aCompletedHdr Must be set by the implementation to the header
 		of the last transfer to complete.
+		@released
 	*/
 	virtual void DoDfc(const DDmaRequest& aCurReq, SDmaDesHdr*& aCompletedHdr);
 	/** Called by the PIL whenever a transfer associated with aCurReq is
 		done. The implementation must advance the channel's state and
 		@param aSrcCompletedHdr Must be set by the implementation to
 		the header of the last source descriptor to complete.
 		@param aDstCompletedHdr Must be set by the implementation to
 		the header of the last destination descriptor to complete.
+		@prototype
 	*/
 	virtual void DoDfc(const DDmaRequest& aCurReq, SDmaDesHdr*& aSrcCompletedHdr,
 					   SDmaDesHdr*& aDstCompletedHdr);
 	/** This function allows the Platform Specific Layer (PSL) to control the
 	TBool iDynChannel;		 // this is a dynamically allocated channel
 	TUint iPriority;		 // hardware priority of this channel
 	NFastMutex iLock;		 // for data accessed in both client & DFC context
 	SDmaDesHdr* iCurHdr;	 // fragment being transferred or NULL
 	SDmaDesHdr** iNullPtr;	 // Pointer to NULL pointer following last fragment
-	TDfc iDfc;				  // transfer completion/failure DFC
+	TDfc iDfc;				 // transfer completion/failure DFC
-	TInt iMaxDesCount;		  // maximum number of allocable descriptors
+	TInt iMaxDesCount;		 // maximum number of allocable descriptors
-	TInt iAvailDesCount;	  // available number of descriptors
+	TInt iAvailDesCount;	 // available number of descriptors
 	volatile TUint32 iIsrDfc; // Interface between ISR and DFC:
 	enum {KErrorFlagMask = 0x80000000};	   // bit 31 - error flag
 	enum {KCancelFlagMask = 0x40000000};   // bit 30 - cancel flag
 	enum {KDfcCountMask = 0x3FFFFFFF};	   // bits 0-29 - number of queued DFCs
-	SDblQue iReqQ;				 // being/about to be transferred request queue
+	SDblQue iReqQ;			// being/about to be transferred request queue
-	TInt iReqCount;				 // number of requests attached to this channel
+	TInt iReqCount;			// number of requests attached to this channel
-	TInt iQueuedRequests; // number of requests currently queued on this channel
+	TInt iQueuedRequests; 	// number of requests currently queued on this channel
 private:
 	TDmaCancelInfo* iCancelInfo; // ...
-	TBool iRedoRequest;			 // client ISR callback wants a redo of request
+	TBool iRedoRequest;		// client ISR callback wants a redo of request
-	TBool iIsrCbRequest;		 // request on queue using ISR callback
+	TBool iIsrCbRequest;	// request on queue using ISR callback
 	__DMA_DECLARE_INVARIANT
 	};
 //////////////////////////////////////////////////////////////////////////////
 // INTERFACE WITH TEST HARNESS
 //////////////////////////////////////////////////////////////////////////////
-/** Set of information used by test harness.
-	@publishedPartner
-	@released
-*/
-struct TDmaTestInfo
-	{
-	/** Maximum transfer size in bytes for all channels (ie. the minimum of all channels' maximum size)*/
-	TUint iMaxTransferSize;
-	/** 3->Memory buffers must be 4-byte aligned, 7->8-byte aligned, ... */
-	TUint iMemAlignMask;
-	/** Cookie to pass to DDmaRequest::Fragment for memory-memory transfer*/
-	TUint32 iMemMemPslInfo;
-	/** Number of test single-buffer channels */
-	TInt iMaxSbChannels;
-	/** Pointer to array containing single-buffer test channel ids */
-	TUint32* iSbChannels;
-	/** Number of test double-buffer channels */
-	TInt iMaxDbChannels;
-	/** Pointer to array containing double-buffer test channel ids */
-	TUint32* iDbChannels;
-	/** Number of test scatter-gather channels */
-	TInt iMaxSgChannels;
-	/** Pointer to array containing scatter-gather test channel ids */
-	TUint32* iSgChannels;
-	};
 /** Provides access to test information structure stored in the PSL.
-	Must be implemented by the PSL.
+	Must be implemented by the PSL (v1).
-	@publishedPartner
+	@deprecated
-	@released
 */
 IMPORT_C const TDmaTestInfo& DmaTestInfo();
 /** Provides access to test information structure stored in the PSL.
-	Must be implemented by the PSL.
+	Must be implemented by the PSL (v2).
-	@publishedPartner
 	@released
 */
 IMPORT_C const TDmaV2TestInfo& DmaTestInfoV2();
 //////////////////////////////////////////////////////////////////////////////
 #include <drivers/dma_compat.inl>
 #include <drivers/dma_v2.inl>

changeset 130	c30940f6d922
parent 90	947f0dc9f7a8
child 132	e4a7b1cbe40c
child 152	657f875b013e