352 	   This function allows the Platform Specific Layer (PSL) to control the

   352 		This function allows the Platform Specific Layer (PSL) to control the

   353 	   power management of the channel or its controller by overriding the

   353 		power management of the channel or its controller by overriding the

   354 	   PIL's default implementation (which does nothing) and making appropriate

   354 		PIL's default implementation (which does nothing) and making

   355 	   use of the Power Resource Manager (PRM).

   355 		appropriate use of the Power Resource Manager (PRM).

   356 

   356 

   357 	   The function gets called by the PIL whenever the channel's queued

   357 		The function gets called by the PIL whenever the channel's queued

   358 	   requests count has changed in a significant way, either before the

   358 		requests count has changed in a significant way, either before the

   359 	   channel's Transfer() method is invoked for a request on a previously

   359 		channel's Transfer() method is invoked for a request on a previously

   360 	   empty request queue, or immediately after the request count has become

   360 		empty request queue, or immediately after the request count has become

   361 	   zero because of request cancellation or completion.

   361 		zero because of request cancellation or completion.

   362 

   362 

   363 	   Depending on the current value of iQueuedRequests, the PSL may power

   363 		Depending on the current and previous observed values of

   364 	   down or power up the channel. Note that iQueuedRequests gets accessed

   364 		iQueuedRequests, the PSL may power down or power up the channel.

   365 	   and changed by different threads, so the PSL needs to take the usual

   365 

   366 	   precautions when evaluating the variable's value.

   366 		Note that iQueuedRequests gets accessed and changed by different

   367 

   367 		threads, so the PSL needs to take the usual precautions when evaluating

   368 	   None of the internal DMA framework mutexes is being held by the PIL when

   368 		the variable's value. Also, due to the multithreaded framework

   369 	   calling this function.

   369 		architecture, there is no guarantee that the function calls always

   370 

   370 		arrive at the PSL level in the strict chronological order of

   371 	   @see iQueuedRequests

   371 		iQueuedRequests being incremented/decremented in the PIL, i.e. it might

   372 	 */

   372 		happen that the PSL finds iQueuedRequests to have the same value in two

   373 		or more consecutive calls (that's why the previous observed value needs

   374 		to be locally available and taken into account). It is however promised

   375 		that before any actual transfer commences the PSL will find the request

   376 		count to be greater than zero and that after the last request has

   377 		finished it will be found to be zero.

   378 

   379 		None of the internal DMA framework mutexes is being held by the PIL

   380 		when calling this function.

   381 

   382 		Here is an example implementation for a derived channel class:

   383 

   384 		@code

   385 

   386 		class TFooDmaChannel : public TDmaSgChannel

   387 			{

   388 			DMutex* iDmaMutex;

   389 			TInt iPrevQueuedRequests;

   390 			virtual void QueuedRequestCountChanged();

   391 			};

   392 

   393 		void TFooDmaChannel::QueuedRequestCountChanged()

   394 			{

   395 			Kern::MutexWait(*iDmaMutex);

   396 			if ((iQueuedRequests > 0) && (iPrevQueuedRequests == 0))

   397 				{

   398 				IncreasePowerCount(); // Base port specific

   399 				}

   400 			else if ((iQueuedRequests == 0) && (iPrevQueuedRequests > 0))

   401 				{

   402 				DecreasePowerCount(); // Base port specific

   403 				}

   404 			iPrevQueuedRequests = iQueuedRequests;

   405 			Kern::MutexSignal(*iDmaMutex);

   406 			}

   407 

   408 		@endcode

   409 

   410 		@see iQueuedRequests

   411 	*/