sl@0: // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of the License "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // e32\include\nkern\dfcs.h
sl@0: // 
sl@0: // WARNING: This file contains some APIs which are internal and are subject
sl@0: //          to change without notice. Such APIs should therefore not be used
sl@0: //          outside the Kernel and Hardware Services package.
sl@0: //
sl@0: 
sl@0: #ifndef __DFCS_H__
sl@0: #define __DFCS_H__
sl@0: 
sl@0: #include <nklib.h>
sl@0: 
sl@0: class NThreadBase;
sl@0: class NThread;
sl@0: class NFastSemaphore;
sl@0: class NFastMutex;
sl@0: 
sl@0: /********************************************
sl@0:  * Delayed function call queue
sl@0:  ********************************************/
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @released
sl@0: 
sl@0: The number of DFC priorities the system has, which range from 0
sl@0: to KNumDfcPriorities - 1.
sl@0: */
sl@0: const TInt KNumDfcPriorities=8;
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @released
sl@0: 
sl@0: The highest priority level for a DFC, which is equal to KNumDfcPriorities + 1.
sl@0: */
sl@0: const TInt KMaxDfcPriority=KNumDfcPriorities-1;
sl@0: 
sl@0: class TDfc;
sl@0: /**
sl@0: @publishedPartner
sl@0: @released
sl@0: 
sl@0: Defines a DFC queue.
sl@0: 
sl@0: Each DFC queue is associated with a thread.
sl@0: 
sl@0: @see TDfc
sl@0: */
sl@0: class TDfcQue : public TPriList<TDfc,KNumDfcPriorities>
sl@0: 	{
sl@0: public:
sl@0: 	IMPORT_C TDfcQue();
sl@0: 
sl@0: 	inline TBool IsEmpty();		/**< @internalComponent */
sl@0: 	static void ThreadFunction(TAny* aDfcQ);
sl@0: public:
sl@0: 	NThreadBase* iThread;		/**< @internalComponent */
sl@0: 	};
sl@0: 
sl@0: /**
sl@0: @internalComponent
sl@0: */
sl@0: inline TBool TDfcQue::IsEmpty()
sl@0: 	{ return (iPresent[0]==0); }
sl@0: 
sl@0: /********************************************
sl@0:  * Delayed function call
sl@0:  ********************************************/
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @released
sl@0: 
sl@0: The function type that can be set to run as a DFC or IDFC.
sl@0: 
sl@0: @see TDfc
sl@0: */
sl@0: typedef void (*TDfcFn)(TAny*);
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @released
sl@0: 
sl@0: Defines a Deferred Function Call (DFC) or Immediate Deferred Function Call (IDFC).
sl@0: 
sl@0: A DFC is a kernel object that specifies a function to be run in a thread,
sl@0: which is processing a DFC queue. A DFC is added to a DFC queue that is 
sl@0: associated with a given thread, where it is cooperatively scheduled with other
sl@0: DFCs on that queue.  Queued DFCs are run in order of their priority, followed
sl@0: by the order they where queued.  When the DFC gets to run, the function is run
sl@0: kernel side, and no other DFC in this queue will get to run until it 
sl@0: completes. A DFC can be queued from any context.
sl@0: 
sl@0: An IDFC is run as soon as the scheduler is next run, which is during the IRQ
sl@0: postamble if queued from an ISR; when the currently-running IDFC completes if
sl@0: queued from an IDFC; or when the kernel is next unlocked if queued from thread
sl@0: context.  Unlike a DFC, the IDFC is not run from a thread context, and its
sl@0: execution time must be much smaller.  For these reasons, IDFCs are rarely used
sl@0: directly, but are used for implementation of the kernel and RTOS personality
sl@0: layers.  An important use of IDFCs is in the implementation of queuing DFCs from
sl@0: an ISR context.  IDFCs are run with interrupts enabled but the kernel locked.
sl@0: */
sl@0: class TDfc : public TPriListLink
sl@0: 	{
sl@0: 	// iPriority<KNumDfcPriorities => DFC, otherwise IDFC
sl@0: 	// iSpare2!=0 if on final queue, 0 if not queued or on pending queue
sl@0: 	// iSpare3!=0 if on pending or final queue, 0 if not queued
sl@0: public:
sl@0: 	IMPORT_C TDfc(TDfcFn aFunction, TAny* aPtr);									// create IDFC
sl@0: 	IMPORT_C TDfc(TDfcFn aFunction, TAny* aPtr, TInt aPriority);					// create DFC, queue to be set later
sl@0: 	IMPORT_C TDfc(TDfcFn aFunction, TAny* aPtr, TDfcQue* aDfcQ, TInt aPriority);	// create DFC
sl@0: 	IMPORT_C TBool Add();						// call from ISR or IDFC or thread with kernel locked
sl@0: 	IMPORT_C TBool Cancel();					// call from anywhere except ISR
sl@0: 	IMPORT_C TBool Enque();						// call from thread
sl@0: 	IMPORT_C TBool Enque(NFastMutex* aMutex);	// call from thread, signal fast mutex (anti-thrash)
sl@0: 	IMPORT_C TBool DoEnque();					// call from IDFC or thread with kernel locked
sl@0: 	IMPORT_C TBool RawAdd();					// same as Add() but without checks for 'correct' usage or other instrumentation
sl@0: 	IMPORT_C TBool QueueOnIdle();				// queue the DFC to be run when the system goes idle
sl@0: 	IMPORT_C NThreadBase* Thread();				// thread on which DFC runs, NULL for IDFC
sl@0: 	void DoEnqueFinal();
sl@0: 	inline TBool Queued();
sl@0: 	inline TBool IsIDFC();
sl@0: 	inline TBool TestAndSetQueued();			/**< @internalComponent */
sl@0: 	inline void SetDfcQ(TDfcQue* aDfcQ);
sl@0: 	inline void SetFunction(TDfcFn aDfcFn);
sl@0: 	inline void SetPriority(TInt aPriority);	/**< @internalComponent */
sl@0: public:
sl@0: 	TAny* iPtr;			/**< @internalComponent */
sl@0: 	TDfcFn iFunction;	/**< @internalComponent */
sl@0: 	TDfcQue *iDfcQ;		/**< @internalComponent */
sl@0: 	};
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @released
sl@0: 
sl@0: Used to find out if the DFC/IDFC is queued on either the pending or final DFC queue.
sl@0: 
sl@0: @return TRUE if the DFC/IDFC is queued, otherwise FALSE.
sl@0: 
sl@0: */
sl@0: inline TBool TDfc::Queued()
sl@0: 	{ return iSpare3; }
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @released
sl@0: 
sl@0: Determines if the object represents a DFC or an IDFC.
sl@0: 
sl@0: @return TRUE if this represents an IDFC, otherwise FALSE meaning it is a DFC.
sl@0: */
sl@0: inline TBool TDfc::IsIDFC()
sl@0: 	{ return iPriority>=KNumDfcPriorities; }
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @released
sl@0: 
sl@0: Sets the DFC queue that the DFC is to added to and executed by.
sl@0: 
sl@0: Note that this function should only be used in the initialisation of the DFC, 
sl@0: when it is not on any queue.  This function does not move the DFC from one 
sl@0: queue to another.
sl@0: 
sl@0: @param aDfcQ
sl@0: 
sl@0: 	The DFC queue that the DFC is to be added to and executed by.
sl@0: 
sl@0: */
sl@0: inline void TDfc::SetDfcQ(TDfcQue* aDfcQ)
sl@0: 	{ iDfcQ=aDfcQ; }
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @released
sl@0: 
sl@0: Sets the function that is run when the DFC/IDFC is scheduled.
sl@0: 
sl@0: @param aDfcFn
sl@0: 
sl@0: 	The function that the DFC/IDFC runs when it is scheduled.
sl@0: 
sl@0: */
sl@0: inline void TDfc::SetFunction(TDfcFn aDfcFn)
sl@0: 	{ iFunction=aDfcFn; }
sl@0: 
sl@0: /**
sl@0: @internalComponent
sl@0: */
sl@0: inline void TDfc::SetPriority(TInt aPriority)
sl@0: 	{ iPriority = (TUint8)aPriority; }
sl@0: 
sl@0: #ifdef __INCLUDE_TDFC_DEFINES__
sl@0: #define	iOnFinalQ		iSpare2
sl@0: #define	iQueued			iSpare3
sl@0: #endif
sl@0: 
sl@0: 
sl@0: /********************************************
sl@0:  * Kernel-side asynchronous request,
sl@0:  * based on DFC queueing
sl@0:  ********************************************/
sl@0: 
sl@0: class TAsyncRequest : protected TDfc
sl@0: 	{
sl@0: public:
sl@0: 	IMPORT_C void Send(TDfc* aCompletionDfc);
sl@0: 	IMPORT_C void Send(NFastSemaphore* aCompletionSemaphore);
sl@0: 	IMPORT_C TInt SendReceive();
sl@0: 	IMPORT_C void Cancel();
sl@0: 	IMPORT_C void Complete(TInt aResult);
sl@0: 	inline TBool PollForCancel()
sl@0: 		{ return iCancel; }
sl@0: protected:
sl@0: 	IMPORT_C TAsyncRequest(TDfcFn aFunction, TDfcQue* aDfcQ, TInt aPriority);
sl@0: protected:
sl@0: 	TAny*	iCompletionObject;
sl@0: 	volatile TBool	iCancel;
sl@0: 	TInt	iResult;
sl@0: 	};
sl@0: 
sl@0: 
sl@0: #endif