sl@0: // Copyright (c) 2007-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\drivers\resource.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 __RESOURCE_H__
sl@0: #define __RESOURCE_H__
sl@0: #include <kernel/kernel.h>
sl@0: #include <kernel/kern_priv.h>
sl@0: #include <drivers/resourcecontrol_trace.h>
sl@0: #include <drivers/resource_category.h>
sl@0: 
sl@0: //Definition for resource flag setting. Used by PSL.
sl@0: static const TUint KTypeMask= 0x3;
sl@0: static const TUint KUsageOffset=0x1F;
sl@0: static const TUint KLongLatencySetOffset=0x1E;
sl@0: static const TUint KLongLatencyGetOffset=0x1D;
sl@0: static const TUint KClassOffset=0x1C;
sl@0: static const TUint KSenseOffset=0x1A;
sl@0: static const TUint KShared=0x1<<KUsageOffset;
sl@0: static const TUint KLongLatencySet=0x1<<KLongLatencySetOffset;
sl@0: static const TUint KLongLatencyGet=0x1<<KLongLatencyGetOffset;
sl@0: static const TUint KLogical=0x1<<KClassOffset;
sl@0: static const TUint KSenseNegative=0x01<<KSenseOffset;
sl@0: static const TUint KSenseCustom=0x2<<KSenseOffset;
sl@0: 
sl@0: struct TPowerRequest;
sl@0: struct SIdleResourceInfo;
sl@0: 
sl@0: 
sl@0: /**
sl@0:  * List of operations that a Custom Function may be informed of. 
sl@0:  *
sl@0:  * @publishedPartner
sl@0:  * @prototype 9.5
sl@0:  */
sl@0: enum TCustomOperation
sl@0:     {
sl@0: 	/**
sl@0: 	Client has requested the given level.
sl@0: 	*/
sl@0: 	EClientRequestLevel,
sl@0: 
sl@0: 	/**
sl@0: 	Client has relinquished the given level.
sl@0:     */
sl@0: 	EClientRelinquishLevel,
sl@0: 	
sl@0: 	/**
sl@0: 	Client is changing the level.
sl@0: 	*/
sl@0: 	EClientChangeLevel,
sl@0: 	
sl@0: 	/**
sl@0: 	A dynamic resource is being deregistered.
sl@0: 	*/
sl@0: 	EDynamicResourceDeregister
sl@0: 	};
sl@0: 
sl@0: 
sl@0: /**
sl@0:  *  Function prototype for the Custom Function.
sl@0:  *  
sl@0:  *  @publishedPartner
sl@0:  *  @prototype 9.5
sl@0:  */
sl@0: typedef TBool (*TCustomFunction) (TInt& /*aClientId*/,
sl@0: 								  const TDesC8& /*aClientName*/,
sl@0:                                   TUint /*aResourceId*/,
sl@0:                                   TCustomOperation /*aCustomOperation*/,
sl@0:                                   TInt& /*aLevel*/,
sl@0:                                   TAny* /*aLevelList*/,
sl@0:                                   TAny* /*aReserved*/);  // For future use
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: class to represent static resources
sl@0: */
sl@0: class DStaticPowerResource : public DBase
sl@0: 	{
sl@0: public:
sl@0:     enum TType {EBinary = EResBinary, EMultilevel, EMultiProperty};
sl@0:     enum TUsage {ESingleUse = EResSingleUse, EShared};
sl@0:     enum TLatency {EInstantaneous = EResInstantaneous, ELongLatency};
sl@0:     enum TClass {EPhysical = EResPhysical, ELogical};
sl@0:     enum TSense {EPositive = EResPositive, ENegative, ECustom};
sl@0: public:
sl@0:     //exported to allow construction from other base port components.
sl@0:     IMPORT_C DStaticPowerResource(const TDesC8& aName, TInt aDefaultLevel);
sl@0:     IMPORT_C virtual TInt GetInfo(TDes8* aInfo)const;
sl@0:     inline void SetCustomFunction(TCustomFunction aCustomFunction)
sl@0:            {iCustomFunction=aCustomFunction;}
sl@0: 
sl@0:     //private data inlined accessors
sl@0:     TType Type() const {return TType(iFlags&KTypeMask);}
sl@0:     TClass Class() const {return TClass((iFlags>>KClassOffset)&0x1);}
sl@0:     TUsage Usage() const {return TUsage((iFlags>>KUsageOffset)&0x1);}
sl@0:     TLatency LatencyGet() const
sl@0:              {return TLatency((iFlags>>KLongLatencyGetOffset)&0x1);}
sl@0:     TLatency LatencySet() const
sl@0:              {return TLatency((iFlags>>KLongLatencySetOffset)&0x1);}
sl@0:     TSense Sense() const {return TSense((iFlags>>KSenseOffset)&0x3);}
sl@0: protected:
sl@0:     //pure virtual function to be implement by PSL
sl@0:     virtual TInt DoRequest(TPowerRequest& aRequest)=0;
sl@0: public:
sl@0: 	HBuf8* iName;
sl@0: protected:
sl@0:     TInt iPostBootLevel;
sl@0: 	TInt iDefaultLevel;
sl@0: protected:
sl@0:     TInt iCachedLevel;
sl@0: 	TUint iResourceId;
sl@0:     SDblQue iNotificationList;
sl@0:     SDblQue iClientList;
sl@0:     TCustomFunction iCustomFunction;
sl@0:     TInt iLevelOwnerId;
sl@0:     SIdleResourceInfo* iIdleListEntry;
sl@0: protected:
sl@0:     TUint iFlags;
sl@0: #ifdef PRM_CONTROLLER
sl@0:     friend class DPowerResourceController;
sl@0: #endif
sl@0: 	};
sl@0: 
sl@0: typedef void (*TPowerResourceCbFn)(TUint /*aClientId*/,
sl@0:                                    TUint /*aResourceId*/,
sl@0:                                    TInt /*aLevel*/,
sl@0: 								   TInt /*aLevelOwnerId*/,
sl@0:                                    TInt /*aResult*/,
sl@0:                                    TAny* /*aParam*/);
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: An object of this type prepresents a customised Dfc
sl@0: used to signal completion of the resource manager's asynchronous APIs
sl@0: and completion of notifications
sl@0: @see TPowerResourceManager
sl@0:  */
sl@0: class TPowerResourceCb : public TDfc
sl@0: 	{
sl@0: public:
sl@0: 	inline TPowerResourceCb(TPowerResourceCbFn aFn, TAny* aPtr, TInt aPriority) : TDfc(DfcFunc, this, aPriority), 
sl@0: 		                                                            iParam(aPtr), iCallback(aFn){ }
sl@0: 	inline TPowerResourceCb(TPowerResourceCbFn aFn, TAny* aPtr, TDfcQue* aQue, TInt aPriority):  
sl@0: 	                              TDfc(DfcFunc, this, aQue, aPriority), iParam(aPtr), iCallback(aFn) { }
sl@0: private:
sl@0:     inline static void DfcFunc(TAny* aPtr)
sl@0:         {
sl@0:         TPowerResourceCb* pCb = (TPowerResourceCb*) aPtr;
sl@0: 	    __KTRACE_OPT(KRESMANAGER, Kern::Printf(">TPowerResourceCb::DfcFunc ClientId = 0x%x, ResourceId = %d, Level = %d, \
sl@0: 			                    LevelOwnerId = %d, Result = %d", pCb->iClientId, pCb->iResourceId, pCb->iLevel, \
sl@0: 								pCb->iLevelOwnerId, pCb->iResult));
sl@0: 	    // Call the client specified callback function
sl@0:         pCb->iCallback(pCb->iClientId, pCb->iResourceId, pCb->iLevel, pCb->iLevelOwnerId, pCb->iResult, pCb->iParam);
sl@0: 		pCb->iResult = KErrCompletion; //Mark the callback object to act properly during cancellation of this request.
sl@0:         PRM_CALLBACK_COMPLETION_TRACE
sl@0:         }
sl@0: private:
sl@0:     TAny* iParam; //Stores the aPtr argument passed in the constructor, to be passed as 5th argument to the callback function
sl@0:     TInt iResult; //Used to store the result aswell as binary usage count for the callback
sl@0:     TInt iLevel; // Level of the resource
sl@0: 	TInt iLevelOwnerId; // Stores owner of the resource for asynchronous get operation
sl@0:     TUint iResourceId; //Stores the ID of the resource whose state is changed/read asynchronously
sl@0:     TUint iClientId; //Stores the ID of the client that requested the asynchronous operation
sl@0:     TPowerResourceCbFn iCallback; //Callback function object
sl@0: #ifdef PRM_CONTROLLER
sl@0:     friend class DPowerResourceController;
sl@0: #endif
sl@0: 	};
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: Notifications class. Conditional and unconditional notifications are encapsulated in this class. 
sl@0: It uses TPowerResourceCb to perform the actual notification call.
sl@0: @see TPowerResourceCb
sl@0:  */
sl@0: class DPowerResourceNotification : public DBase
sl@0:     {
sl@0: public:
sl@0:     enum TType {EUnconditional, EConditional};
sl@0: 	enum TResNotiPanic {ENotificationObjectStillInList = 25}; 
sl@0: public:
sl@0: 	inline DPowerResourceNotification(TPowerResourceCbFn aFn, TAny* aPtr, TInt aPriority): 
sl@0: 	                                                 iCallback(aFn, aPtr, aPriority) {}
sl@0: 	inline DPowerResourceNotification(TPowerResourceCbFn aFn, TAny* aPtr, TDfcQue* aQue, TInt aPriority) : 
sl@0: 	                                                 iCallback(aFn, aPtr, aQue, aPriority) {}
sl@0: 	inline ~DPowerResourceNotification() 
sl@0: 		{
sl@0: 		if(iRegistered)
sl@0: 			Kern::Fault("Power Resource Controller", ENotificationObjectStillInList);
sl@0: 		}
sl@0: public:
sl@0: 	TInt iPreviousLevel; //Previous level of the resource. This is used for checking the threshold condition
sl@0: 	TUint8 iRegistered;
sl@0: private:
sl@0:     TUint8 iType; // the type of notification required (conditional or unconditional).
sl@0:     TUint16 iOwnerId; // the bottom 16 bits of the Id of the client which requested the notification
sl@0:     TInt iThreshold; // the threshold which when crossed on a specified direction will cause a notification to be issued.
sl@0:     TBool iDirection; // the direction of the resource change that together with the threshold to be crossed will result in the notification
sl@0:     TPowerResourceCb iCallback; //Callback object associated with this notification
sl@0:     SDblQueLink iNotificationLink; 
sl@0:     DPowerResourceNotification* iNextInClient;
sl@0: #ifdef PRM_CONTROLLER
sl@0:     friend class DPowerResourceController;
sl@0: #endif
sl@0: 	};
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: class to represent resource properties
sl@0: */
sl@0: class TPowerResourceInfoV01
sl@0: 	{
sl@0: public:
sl@0:     DStaticPowerResource::TClass iClass;
sl@0:     DStaticPowerResource::TLatency iLatencyGet;
sl@0:     DStaticPowerResource::TLatency iLatencySet;
sl@0:     DStaticPowerResource::TType iType;
sl@0:     DStaticPowerResource::TUsage iUsage;
sl@0:     DStaticPowerResource::TSense iSense;
sl@0:     TDesC8* iResourceName;
sl@0:     TUint iResourceId;
sl@0:     TInt iDefaultLevel;  
sl@0:     TInt iMinLevel;      //PSL mandatory field
sl@0:     TInt iMaxLevel;      //PSL mandatory field
sl@0: 	TInt iReserved1;	 //Reserved for future use.	
sl@0: 	TInt iReserved2;	 //Reserved for future use.
sl@0: 	TInt iReserved3;	 //Reserved for future use.
sl@0:     TInt iPslReserved1;  //PSL specific field
sl@0:     TInt iPslReserved2;  //PSL specific field
sl@0:     TInt iPslReserved3;  //PSL specific field
sl@0: 	};
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: */
sl@0: typedef TPckgBuf<TPowerResourceInfoV01> TPowerResourceInfoBuf01;
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: structure to represent client properties
sl@0: */
sl@0: struct TPowerClientInfoV01
sl@0: 	{
sl@0:     TUint iClientId;
sl@0:     TDesC8* iClientName;
sl@0: 	};
sl@0: 
sl@0: #endif // __RESOURCE_H__