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

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

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

     5 // which accompanies this distribution, and is available

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

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // include/drivers/dma_hai.h

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

    16 //

    17 //

    18 

    19 /** @file

    20 	@publishedPartner

    21 	@released

    22 */

    23 

    24 #ifndef __DMA_HAI_H__

    25 #define __DMA_HAI_H__

    26 

    27 

    28 #include <kernel/kern_priv.h>

    29 

    30 

    31 //////////////////////////////////////////////////////////////////////////////

    32 

    33 

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

    35 

    36 	Must be implemented by the PSL.

    37 */

    38 class DmaChannelMgr

    39 	{

    40 

    41 public:

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

    43 

    44 		This function must be implemented by the PSL.

    45 

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

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

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

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

    50 		be set to zero always if all channels are equivalent.

    51 

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

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

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

    55 		certain resources (but not including the number of available physical

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

    57 		channel may be serviced using different actual channels.

    58 

    59 		@param aPriority The desired channel priority as requested by the

    60 		client. This may be an actual hardware priority or a

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

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

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

    64 		priority may be requested by a client later via

    65 		TDmaTransferArgs::iChannelPriority.

    66 		@see SDmacCaps::iChannelPriorities

    67 		@see TDmaPriority

    68 

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

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

    71 		error occurred.

    72 

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

    74 		race conditions.

    75 

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

    77 		iController, iDmacCaps, iPslId, iDynChannel and iPriority members set

    78 		to valid states.

    79 

    80 		iController should point to the controller handling the

    81 		channel.

    82 

    83 		iDmacCaps should point to a SDmacCaps structure containing values

    84 		relating to this particular channel.

    85 

    86 		iPslId should contain a value uniquely identifying the channel - the

    87 		PIL assigns this value later during request fragmentation to

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

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

    90 

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

    92 		requested and has been opened.

    93 

    94 		If applicable, iPriority should contain the actual hardware priority

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

    96 		default value TDmaPriority::KDmaPriorityNone.

    97 	*/

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

    99 

   100 

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

   102 

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

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

   105 		transfer requests via this channel.

   106 

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

   108 		be a no-op.

   109 

   110 		@param aChannel The channel to close

   111 

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

   113 		race conditions.

   114 	*/

   115 	static void Close(TDmaChannel* aChannel);

   116 

   117 

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

   119 		operations.

   120 

   121 		This function must be implemented by the PSL.

   122 

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

   124 		internal use.

   125 

   126 		@param aArg PSL-specific

   127 

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

   129 		otherwise.

   130 	*/

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

   132 

   133 

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

   135 		closing a channel.

   136 	*/

   137 	static void Wait();

   138 

   139 

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

   141 		closing a channel.

   142 	*/

   143 	static void Signal();

   144 

   145 private:

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

   147 	friend TInt InitExtension();

   148 

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

   150 	static TInt Initialise();

   151 

   152 	static NFastMutex Lock;

   153 	};

   154 

   155 

   156 //////////////////////////////////////////////////////////////////////////////

   157 

   158 

   159 /** Abstract base class representing a DMA controller.

   160 

   161 	The class has two purposes.

   162 

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

   164 

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

   166 	(platform-specific layer).

   167 

   168 	These functions are the main interfaces between the PIL

   169 	(platform-independent layer) and PSL.

   170 */

   171 class TDmac

   172 	{

   173 friend class DmaChannelMgr;

   174 

   175 // The following friend declaration will become obsolete once header

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

   177 // class instead of the request class.

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

   179 friend class DDmaRequest;

   180 

   181 friend class TSkelDmac;

   182 

   183 protected:

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

   185 	struct SCreateInfo

   186 		{

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

   188 			scatter/gather mode).

   189 		*/

   190 		TBool iCapsHwDes;

   191 

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

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

   194 			descriptors are needed then they will be dynamically allocated and

   195 			added to the available pool.

   196 

   197 			The PSL may consider a number of factors when providing this

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

   199 			the maximum transfer size per descriptor and also likely usage

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

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

   202 

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

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

   205 			number of descriptors.)

   206 		*/

   207 		TInt iDesCount;

   208 

   209 		/** Size of an individual descriptor.

   210 

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

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

   213 		*/

   214 		TInt iDesSize;

   215 

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

   217 			pool in the PIL. Used only for hardware descriptors.

   218 

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

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

   221 			write buffer in InitHwDes() and related functions.

   222 

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

   224 		 	size aligned.

   225 

   226 		 	@see TMappingAttributes

   227 		 */

   228 		TUint iDesChunkAttribs;

   229 		};

   230 

   231 	/** Base class constructor.

   232 	 */

   233 	TDmac(const SCreateInfo& aInfo);

   234 

   235 	/** Base class 2nd-phase constructor.

   236 	 */

   237 	TInt Create(const SCreateInfo& aInfo);

   238 

   239 public:

   240 	/** Base class virtual destructor.

   241 	 */

   242 	virtual ~TDmac();

   243 

   244 

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

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

   247 		PSL.

   248 	*/

   249 	TInt ReserveSetOfDes(TInt aCount);

   250 

   251 

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

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

   254 		the PSL.

   255 	*/

   256 	void ReleaseSetOfDes(TInt aCount);

   257 

   258 

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

   260 		pseudo descriptor with transfer arguments.

   261 	*/

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

   263 

   264 

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

   266 		latter's arguments is non-zero.

   267 	*/

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

   269 				   TUint aTransferCount, TUint32 aPslRequestInfo);

   270 

   271 

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

   273 		descriptor header. For use by PIL and PSL.

   274 	*/

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

   276 

   277 

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

   279 		descriptor header. For use by PIL and PSL.

   280 	*/

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

   282 

   283 

   284 	/** Returns the physical address of the hardware descriptor

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

   286 	*/

   287 	inline TUint32 HwDesLinToPhys(TAny* aDes) const;

   288 

   289 

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

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

   292 

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

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

   295 		one is ongoing.

   296 

   297 		The function must be implemented by the PSL if

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

   299 

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

   301 

   302 		@param aChannel The channel to use.

   303 		@param aHdr Header associated with fragment to transfer.

   304 	*/

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

   306 

   307 

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

   309 		asymmetrical linked-list capability) are to be transferred.

   310 

   311 		Called when initiating a new transfer.

   312 

   313 		The function must be implemented by the PSL if

   314 		SDmaCaps::iAsymHwDescriptors is reported as true.

   315 

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

   317 

   318 		@param aChannel The channel to use.

   319 		@param aSrcHdr Header associated with descriptor to transfer on the

   320 		source side.

   321 		@param aDstHdr Header associated with descriptor to transfer on the

   322 		destination side.

   323 	*/

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

   325 						  const SDmaDesHdr& aDstHdr);

   326 

   327 

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

   329 

   330 		The stopping must occur synchronously as the PIL assumes the channel

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

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

   333 		implemented by the PSL.

   334 

   335 		@param aChannel The channel to stop

   336 		@post The channel will be idle

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

   338 		request is queued.

   339 	*/

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

   341 

   342 

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

   344 

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

   346 		ResumeTransfer().

   347 

   348 		The function must be implemented by the PSL if

   349 		SDmacCaps::iChannelPauseAndResume is reported as true.

   350 

   351 		@return KErrNone if the transfer has been paused successfully,

   352 		KErrCompletion if the transfer was already paused, KErrGeneral

   353 		if a general error occurred preventing a successful outcome.

   354 

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

   356 		resumed.

   357 	*/

   358 	virtual TInt PauseTransfer(const TDmaChannel& aChannel);

   359 

   360 

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

   362 		channel.

   363 

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

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

   366 		Pause bit in a H/W descriptor.

   367 

   368 		The function must be implemented by the PSL if

   369 		SDmacCaps::iChannelPauseAndResume or

   370 		SDmacCaps::iLinkedListPausedInterrupt is reported as true.

   371 

   372 		@return KErrNone if the transfer has been resumed successfully,

   373 		KErrCompletion if there was no paused transfer, KErrGeneral

   374 		if a general error occurred preventing a successful outcome.

   375 	*/

   376 	virtual TInt ResumeTransfer(const TDmaChannel& aChannel);

   377 

   378 

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

   380 

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

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

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

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

   385 		transfer.

   386 

   387 		@param aChannel The channel to test

   388 

   389 		@return ETrue if channel idle, EFalse if transferring.

   390 	*/

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

   392 

   393 

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

   395 		based on the parameters passed.

   396 

   397 		@param aChannel Channel to be used for the transfer

   398 		@param aSrcFlags Bitmask characterising transfer source

   399 		@see TDmaTransferArgs::iSrcConfig::iFlags

   400 		@param aDstFlags Bitmask characterising transfer destination

   401 		@see TDmaTransferArgs::iDstConfig::iFlags

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

   403 		@see TDmaTransferArgs::iPslRequestInfo

   404 

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

   406 		length in bytes otherwise.

   407 	*/

   408 	virtual TUint MaxTransferLength(TDmaChannel& aChannel, TUint aSrcFlags,

   409 									TUint aDstFlags, TUint32 aPslInfo) = 0;

   410 

   411 

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

   413 		on the parameters passed. Some DMA controllers impose alignment

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

   415 		against memory addresses computed during fragmentation.

   416 

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

   418 

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

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

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

   422 		are the values of the relevant configuration parameters.

   423 

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

   425 		DMAC with potentially different values for source and destination does

   426 		not depend on the configuration of the respective other port.

   427 

   428 		@param aChannel Channel used for the transfer

   429 		@param aTargetFlags Bitmask characterising transfer source or

   430 		destination

   431 		@see TDmaTransferArgs::iSrcConfig::iFlags

   432 		@see TDmaTransferArgs::iDstConfig::iFlags

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

   434 		not known or 'don't care'.

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

   436 		@see TDmaTransferArgs::iPslRequestInfo

   437 

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

   439 		be 4-byte aligned)

   440 	*/

   441 	virtual TUint AddressAlignMask(TDmaChannel& aChannel, TUint aTargetFlags,

   442 								   TUint aElementSize, TUint32 aPslInfo) = 0;

   443 

   444 

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

   446 

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

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

   449 		marker.

   450 

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

   452 		supports hardware descriptors and SDmaCaps::iAsymHwDescriptors is

   453 		reported as false.

   454 

   455 		@param aHdr Header associated with the hardware descriptor to

   456 		initialise

   457 		@param aTransferArgs The transfer parameters for this descriptor

   458 

   459 		@return KErrNone if the descriptor was successfully initialized,

   460 		KErrArgument if any of the transfer arguments were detected to be

   461 		invalid, KErrGeneral if a general error occurred preventing a

   462 		successful outcome.

   463 	*/

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

   465 

   466 

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

   468 		on the source side of an asymmetric linked list.

   469 

   470 		The function must be implemented by the PSL if

   471 		SDmaCaps::iAsymHwDescriptors is reported as true.

   472 

   473 		@param aHdr Header associated with the hardware descriptor to

   474 		initialise

   475 		@param aTransferArgs The transfer parameters for this descriptor. Only

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

   477 		implementation.

   478 

   479 		@return KErrNone if the descriptor was successfully initialized,

   480 		KErrArgument if any of the transfer arguments were detected to be

   481 		invalid, KErrGeneral if a general error occurred preventing a

   482 		successful outcome.

   483 	*/

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

   485 

   486 

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

   488 		on the destination side of an asymmetric linked list.

   489 

   490 		The function must be implemented by the PSL if

   491 		SDmaCaps::iAsymHwDescriptors is reported as true.

   492 

   493 		@param aHdr Header associated with the hardware descriptor to

   494 		initialise

   495 		@param aTransferArgs The transfer parameters for this descriptor. Only

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

   497 		implementation.

   498 

   499 		@return KErrNone if the descriptor was successfully initialized,

   500 		KErrArgument if any of the transfer arguments were detected to be

   501 		invalid, KErrGeneral if a general error occurred preventing a

   502 		successful outcome.

   503 	*/

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

   505 

   506 

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

   508 		hardware descriptor.

   509 

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

   511 		supports hardware descriptors and SDmaCaps::iAsymHwDescriptors is

   512 		reported as false.

   513 

   514 		@param aHdr Header associated with the hardware descriptor to be

   515 		updated

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

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

   518 		@param aTransferCount @see TDmaTransferArgs::iTransferCount

   519 		@param aPslRequestInfo @see TDmaTransferArgs::iPslRequestInfo

   520 

   521 		Since Epoc::LinearToPhysical() cannot be called in ISR context the

   522 		addresses passed into this function are always physical ones, i.e.

   523 		TDmaTransferFlags::KDmaPhysAddr is implied.

   524 

   525 		@return KErrNone if the descriptor was successfully modified,

   526 		KErrArgument if any of the transfer arguments were detected to be

   527 		invalid, KErrGeneral if a general error occurred preventing a

   528 		successful outcome.

   529 	*/

   530 	virtual TInt UpdateHwDes(const SDmaDesHdr& aHdr, TUint32 aSrcAddr, TUint32 aDstAddr,

   531 							 TUint aTransferCount, TUint32 aPslRequestInfo);

   532 

   533 

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

   535 		hardware descriptor.

   536 

   537 		The function must be implemented by the PSL if

   538 		SDmaCaps::iAsymHwDescriptors is reported as true.

   539 

   540 		@param aHdr Header associated with the hardware descriptor to be

   541 		updated

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

   543 		@param aTransferCount @see TDmaTransferArgs::iTransferCount

   544 		@param aPslRequestInfo @see TDmaTransferArgs::iPslRequestInfo

   545 

   546 		Since Epoc::LinearToPhysical() cannot be called in ISR context the

   547 		address passed into this function is always a physical ones, i.e.

   548 		TDmaTransferFlags::KDmaPhysAddr is implied.

   549 

   550 		@return KErrNone if the descriptor was successfully modified,

   551 		KErrArgument if any of the transfer arguments were detected to be

   552 		invalid, KErrGeneral if a general error occurred preventing a

   553 		successful outcome.

   554 	*/

   555 	virtual TInt UpdateSrcHwDes(const SDmaDesHdr& aHdr, TUint32 aSrcAddr,

   556 								TUint aTransferCount, TUint32 aPslRequestInfo);

   557 

   558 

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

   560 		hardware descriptor.

   561 

   562 		The function must be implemented by the PSL if

   563 		SDmaCaps::iAsymHwDescriptors is reported as true.

   564 

   565 		@param aHdr Header associated with the hardware descriptor to be

   566 		updated

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

   568 		@param aTransferCount @see TDmaTransferArgs::iTransferCount

   569 		@param aPslRequestInfo @see TDmaTransferArgs::iPslRequestInfo

   570 

   571 		Since Epoc::LinearToPhysical() cannot be called in ISR context the

   572 		address passed into this function is always a physical ones, i.e.

   573 		TDmaTransferFlags::KDmaPhysAddr is implied.

   574 

   575 		@return KErrNone if the descriptor was successfully modified,

   576 		KErrArgument if any of the transfer arguments were detected to be

   577 		invalid, KErrGeneral if a general error occurred preventing a

   578 		successful outcome.

   579 	*/

   580 	virtual TInt UpdateDstHwDes(const SDmaDesHdr& aHdr, TUint32 aDstAddr,

   581 								TUint aTransferCount, TUint32 aPslRequestInfo);

   582 

   583 

   584 	/** Called by PIL, when fragmenting a request, to append a new hardware

   585 		descriptor to an existing descriptor chain. May also be called by

   586 		clients who wish to create their own descriptor chains.

   587 

   588 		Must clear the interrupt bit of the descriptor associated with aHdr.

   589 

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

   591 		supports hardware descriptors.

   592 

   593 		@param aHdr Header associated with last fragment in chain

   594 		@param aNextHdr Header associated with fragment to append

   595 	*/

   596 	virtual void ChainHwDes(const SDmaDesHdr& aHdr, const SDmaDesHdr& aNextHdr);

   597 

   598 

   599 	/** Called by PIL when queuing a new request while the channel is running.

   600 

   601 		Must append the first hardware descriptor of the new request to the

   602 		last descriptor in the existing chain.

   603 

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

   605 		supports hardware descriptors.

   606 

   607 		@param aChannel The channel where the transfer takes place

   608 		@param aLastHdr Header associated with last hardware descriptor in

   609 		chain

   610 		@param aNewHdr Header associated with first hardware descriptor in new

   611 		request

   612 	*/

   613 	virtual void AppendHwDes(const TDmaChannel& aChannel, const SDmaDesHdr& aLastHdr,

   614 							 const SDmaDesHdr& aNewHdr);

   615 

   616 

   617 	/** Called by PIL when queuing a new request while the channel is running.

   618 

   619 		Must append the first hardware descriptor of the new request to the

   620 		last descriptor in the existing chain.

   621 

   622 		The function must be implemented by the PSL if

   623 		SDmaCaps::iAsymHwDescriptors is reported as true.

   624 

   625 		@param aChannel The channel where the transfer takes place

   626 		@param aSrcLastHdr Header associated with the last descriptor in the

   627 		source side chain

   628 		@param aSrcNewHdr Header associated with the first source side

   629 		descriptor of the new request

   630 		@param aDstLastHdr Header associated with the last descriptor in the

   631 		destination side chain

   632 		@param aDstNewHdr Header associated with the first destination side

   633 		descriptor of the new request

   634 	*/

   635 	virtual void AppendHwDes(const TDmaChannel& aChannel,

   636 							 const SDmaDesHdr& aSrcLastHdr, const SDmaDesHdr& aSrcNewHdr,

   637 							 const SDmaDesHdr& aDstLastHdr, const SDmaDesHdr& aDstNewHdr);

   638 

   639 

   640 	/** Called by PIL when completing or cancelling a request to cause the PSL

   641 		to unlink the last item in the h/w descriptor chain from a subsequent

   642 		chain that it was possibly linked to.

   643 

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

   645 		supports hardware descriptors.

   646 

   647 		@param aChannel The channel where the request (and thus the descriptor)

   648 		was queued

   649 		@param aHdr Header associated with last h/w descriptor in

   650 		completed / cancelled chain

   651 	*/

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

   653 

   654 

   655 	/** Called by PIL when freeing descriptors back to the shared pool in

   656 		FreeDesList(). The PSL inside ClearHwDes() can clear the contents of

   657 		the h/w descriptor.

   658 

   659 		This may be necessary if the PSL implementation uses the h/w descriptor

   660 		as another header which in turn points to the actual DMA h/w descriptor

   661 		(aka LLI).

   662 

   663 		The function may be implemented by the PSL if the DMAC supports

   664 		hardware descriptors.

   665 

   666 		@param aHdr Header associated with the h/w descriptor being freed.

   667 	*/

   668 	virtual void ClearHwDes(const SDmaDesHdr& aHdr);

   669 

   670 

   671 	/** Called by PIL to logically link two physical channels.

   672 

   673 		The function must be implemented by the PSL if the DMAC supports

   674 		logical channel linking.

   675 

   676 		@see SDmacCaps::iChannelLinking

   677 

   678 		@param a1stChannel The channel which is to be linked to another channel

   679 		@param a2ndChannel The channel the first one is to be linked to

   680 

   681 		@return KErrNone if the two channels have been linked successfully,

   682 		KErrCompletion if a1stChannel was already linked to a2ndChannel,

   683 		KErrArgument if a1stChannel was already linked to a different channel,

   684 		KErrGeneral if a general error occurred preventing a successful

   685 		outcome. The default PIL implementation returns KErrNotSupported.

   686 	*/

   687 	virtual TInt LinkChannels(TDmaChannel& a1stChannel, TDmaChannel& a2ndChannel);

   688 

   689 

   690 	/** Called by PIL to logically unlink a physical channel from its linked-to

   691 		successor.

   692 

   693 		The function must be implemented by the PSL if the DMAC supports

   694 		logical channel linking.

   695 

   696 		@see SDmacCaps::iChannelLinking

   697 

   698 		@param aChannel The channel which is to be unlinked from its successor

   699 

   700 		@return KErrNone if the channel has been unlinked successfully,

   701 		KErrCompletion if the channel was not linked to another channel,

   702 		KErrGeneral if a general error occurred preventing a successful

   703 		outcome. The default PIL implementation returns KErrNotSupported.

   704 	*/

   705 	virtual TInt UnlinkChannel(TDmaChannel& aChannel);

   706 

   707 

   708 	/** Called by a test harness to force an error when the next fragment is

   709 		transferred.

   710 

   711 		Must be implemented by the PSL only if possible.

   712 

   713 		@param aChannel The channel where the error is to occur.

   714 

   715 		@return KErrNone if implemented. The default PIL implementation

   716 		returns KErrNotSupported.

   717 	*/

   718 	virtual TInt FailNext(const TDmaChannel& aChannel);

   719 

   720 

   721 	/** Called by a test harness to force the DMA controller to miss one or

   722 		more interrupts.

   723 

   724 		The function must be implemented by the PSL only if possible.

   725 

   726 		@param aChannel The channel where the error is to occur

   727 		@param aInterruptCount The number of interrupt to miss.

   728 

   729 		@return KErrNone if implemented. The default PIL implementation

   730 		returns KErrNotSupported.

   731 	*/

   732 	virtual TInt MissNextInterrupts(const TDmaChannel& aChannel, TInt aInterruptCount);

   733 

   734 

   735 	/** Function allowing platform-specific layer to extend channel API with

   736 		new channel-specific operations.

   737 

   738 		@see TDmaChannel::ChannelExtension

   739 

   740 		@param aChannel Channel to operate on

   741 		@param aCmd Command identifier. Negative values are reserved for use by

   742 		Nokia.

   743 		@param aArg PSL-specific argument

   744 

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

   746 		otherwise.

   747 	*/

   748 	virtual TInt Extension(TDmaChannel& aChannel, TInt aCmd, TAny* aArg);

   749 

   750 

   751 	/** Called by the PIL to query the number of elements that have so far been

   752 		transferred by the hardware descriptor associated with aHdr at the

   753 		source port.

   754 

   755 		If SDmacCaps::iAsymHwDescriptors is true then the PIL will call this

   756 		function only for source-side descriptors, and the PSL should fault the

   757 		kernel if this is not the case.

   758 

   759 		The function must be implemented (i.e. overridden) by the PSL if and

   760 		only if the DMAC supports hardware descriptors.

   761 

   762 		@param aHdr Descriptor header associated with the hardware descriptor

   763 		to be queried

   764 

   765 		@return The number of elements that have been transferred by the

   766 		hardware descriptor associated with aHdr at the source port

   767 	*/

   768 	virtual TUint32 HwDesNumSrcElementsTransferred(const SDmaDesHdr& aHdr);

   769 

   770 

   771 	/** Called by the PIL to query the number of elements that have so far been

   772 		transferred by the hardware descriptor associated with aHdr at the

   773 		destination port.

   774 

   775 		If SDmacCaps::iAsymHwDescriptors is true then the PIL will call this

   776 		function only for destination-side descriptors, and the PSL should

   777 		panic if this is not the case.

   778 

   779 		The function must be implemented (i.e. overridden) by the PSL if and

   780 		only if the DMAC supports hardware descriptors.

   781 

   782 		@param aHdr Descriptor header associated with the hardware descriptor

   783 		to be queried

   784 

   785 		@return The number of elements that have been transferred by the

   786 		hardware descriptor associated with aHdr at the destination port

   787 	*/

   788 	virtual TUint32 HwDesNumDstElementsTransferred(const SDmaDesHdr& aHdr);

   789 

   790 protected:

   791 	/** Called by the PSL in interrupt context upon a channel interrupt event.

   792 

   793 		@param aChannel The channel the ISR relates to

   794 		@param aEventMask Bitmask of one or more TDmaCallbackType values

   795 		@param aIsComplete Set to ETrue if no error was encountered

   796 	*/

   797 	static void HandleIsr(TDmaChannel& aChannel, TUint aEventMask, TBool aIsComplete);

   798 

   799 private:

   800 	/** Called in Create() */

   801 	TInt AllocDesPool(TUint aAttribs);

   802 

   803 	/** Called in ~TDmac() */

   804 	void FreeDesPool();

   805 

   806 	/** Called by the PIL to acquire the controller lock which protects the

   807 		header and descriptor pools.

   808 	*/

   809 	inline void Wait();

   810 

   811 	/** Called by the PIL to release the controller lock which protects the

   812 		header and descriptor pools.

   813 	*/

   814 	inline void Signal();

   815 

   816 private:

   817 	NFastMutex iLock;			 // protect descriptor reservation and allocation

   818 	const TInt iMaxDesCount;	 // initial number of descriptors and headers

   819 	TInt iAvailDesCount;		 // current available number of descriptors and headers

   820 	SDmaDesHdr* iHdrPool;		 // descriptor header dynamic array

   821 #ifndef __WINS__

   822 	DPlatChunkHw* iHwDesChunk;	 // chunk for hardware descriptor pool

   823 #endif

   824 	TAny* iDesPool;				 // hardware or pseudo descriptor dynamic array

   825 	const TInt iDesSize;		 // descriptor size in bytes

   826 

   827 public:

   828 	const TBool iCapsHwDes;		 /*< True if DMAC uses h/w descriptors */

   829 	SDmaDesHdr* iFreeHdr;		 /*< head of unallocated descriptors linked list */

   830 

   831 #ifdef _DEBUG

   832 	/** Tests whether aHdr points into the descriptor header array. */

   833 	TBool IsValidHdr(const SDmaDesHdr* aHdr);

   834 #endif

   835 	__DMA_DECLARE_INVARIANT

   836 	};

   837 

   838 

   839 //////////////////////////////////////////////////////////////////////////////

   840 

   841 

   842 /** Single-buffer DMA channel.

   843 

   844 	Can be instantiated or further derived by the PSL.

   845 */

   846 class TDmaSbChannel : public TDmaChannel

   847 	{

   848 private:

   849 	virtual void DoQueue(const DDmaRequest& aReq);

   850 	virtual void DoCancelAll();

   851 	virtual void DoDfc(const DDmaRequest& aCurReq, SDmaDesHdr*& aCompletedHdr);

   852 

   853 protected:

   854 	enum {EIdle = 0, ETransferring} iState;

   855 	};

   856 

   857 

   858 /** Double-buffer DMA channel.

   859 

   860 	Can be instantiated or further derived by the PSL.

   861 */

   862 class TDmaDbChannel : public TDmaChannel

   863 	{

   864 private:

   865 	virtual void DoQueue(const DDmaRequest& aReq);

   866 	virtual void DoCancelAll();

   867 	virtual void DoDfc(const DDmaRequest& aCurReq, SDmaDesHdr*& aCompletedHdr);

   868 

   869 protected:

   870 	enum {EIdle = 0, ETransferring, ETransferringLast} iState;

   871 	};

   872 

   873 

   874 /** Scatter-gather DMA channel.

   875 

   876 	Can be instantiated or further derived by the PSL.

   877 */

   878 class TDmaSgChannel : public TDmaChannel

   879 	{

   880 private:

   881 	virtual void DoQueue(const DDmaRequest& aReq);

   882 	virtual void DoCancelAll();

   883 	virtual void DoUnlink(SDmaDesHdr& aHdr);

   884 	virtual void DoDfc(const DDmaRequest& aCurReq, SDmaDesHdr*& aCompletedHdr);

   885 

   886 protected:

   887 	enum {EIdle = 0, ETransferring} iState;

   888 	};

   889 

   890 

   891 /** Scatter-gather DMA channel with asymmetric linked-lists.

   892 

   893 	Can be instantiated or further derived by the PSL.

   894 

   895 	@prototype

   896 */

   897 class TDmaAsymSgChannel : public TDmaChannel

   898 	{

   899 public:

   900 	TDmaAsymSgChannel();

   901 

   902 private:

   903 	virtual void DoQueue(const DDmaRequest& aReq);

   904 	virtual void DoCancelAll();

   905 	virtual void DoUnlink(SDmaDesHdr& aHdr);

   906 	virtual void DoDfc(const DDmaRequest& aCurReq, SDmaDesHdr*& aSrcCompletedHdr,

   907 					   SDmaDesHdr*& aDstCompletedHdr);

   908 	virtual void SetNullPtr(const DDmaRequest& aReq);

   909 	virtual void ResetNullPtr();

   910 

   911 protected:

   912 	SDmaDesHdr* iSrcCurHdr;	  // source fragment being transferred or NULL

   913 	SDmaDesHdr** iSrcNullPtr; // Pointer to NULL pointer following last source fragment

   914 	SDmaDesHdr* iDstCurHdr;	  // destination fragment being transferred or NULL

   915 	SDmaDesHdr** iDstNullPtr; // Pointer to NULL pointer following last destination fragment

   916 	enum {EIdle = 0, ETransferring} iState;

   917 

   918 	__DMA_DECLARE_VIRTUAL_INVARIANT

   919 	};

   920 

   921 

   922 //////////////////////////////////////////////////////////////////////////////

   923 

   924 // Trace macros intended for use by the DMA PSL

   925 #define DMA_PRINTF(MSG) __KTRACE_OPT(KDMA, Kern::Printf((MSG)))

   926 #define DMA_PRINTF1(MSG, ARG1) __KTRACE_OPT(KDMA, Kern::Printf((MSG), (ARG1)))

   927 #define DMA_PRINTF2(MSG, ARG1, ARG2) __KTRACE_OPT(KDMA, Kern::Printf((MSG), (ARG1), (ARG2)))

   928 

   929 #define DMA_PSL_MESG "DMA PSL: "

   930 

   931 // General PSL tracing

   932 #define DMA_PSL_TRACE(MSG) DMA_PRINTF(DMA_PSL_MESG MSG)

   933 #define DMA_PSL_TRACE1(MSG, ARG1) DMA_PRINTF1(DMA_PSL_MESG MSG, (ARG1))

   934 #define DMA_PSL_TRACE2(MSG, ARG1, ARG2) DMA_PRINTF2(DMA_PSL_MESG MSG, (ARG1), (ARG2))

   935 

   936 

   937 #define DMA_PSL_CHAN_MESG DMA_PSL_MESG "ChanId %d: "

   938 #define DMA_PSL_CHAN_ARGS(CHAN) ((CHAN).PslId())

   939 

   940 // For channel specific tracing (where CHAN is a TDmaChannel)

   941 #define DMA_PSL_CHAN_TRACE_STATIC(CHAN, MSG) DMA_PRINTF1(DMA_PSL_CHAN_MESG MSG, DMA_PSL_CHAN_ARGS(CHAN))

   942 #define DMA_PSL_CHAN_TRACE_STATIC1(CHAN, MSG, ARG1) DMA_PRINTF2(DMA_PSL_CHAN_MESG MSG, DMA_PSL_CHAN_ARGS(CHAN), (ARG1))

   943 

   944 // For channel specific tracing, for use within methods of TDmaChannel derived

   945 // class

   946 #define DMA_PSL_CHAN_TRACE(MSG) DMA_PSL_CHAN_TRACE_STATIC(*this, MSG)

   947 #define DMA_PSL_CHAN_TRACE1(MSG, ARG1) DMA_PSL_CHAN_TRACE_STATIC1(*this, MSG, (ARG1))

   948 

   949 

   950 

   951 #include <drivers/dma_hai.inl>

   952 

   953 

   954 #endif	// #ifndef __DMA_HAI_H__