// Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of the License "Eclipse Public License v1.0"
// which accompanies this distribution, and is available
// at the URL "http://www.eclipse.org/legal/epl-v10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
// e32\include\drivers\resource.h
// 
// WARNING: This file contains some APIs which are internal and are subject
//          to change without notice. Such APIs should therefore not be used
//          outside the Kernel and Hardware Services package.
//

#ifndef __RESOURCE_H__
#define __RESOURCE_H__
#include <kernel/kernel.h>
#include <kernel/kern_priv.h>
#include <drivers/resourcecontrol_trace.h>
#include <drivers/resource_category.h>

//Definition for resource flag setting. Used by PSL.
static const TUint KTypeMask= 0x3;
static const TUint KUsageOffset=0x1F;
static const TUint KLongLatencySetOffset=0x1E;
static const TUint KLongLatencyGetOffset=0x1D;
static const TUint KClassOffset=0x1C;
static const TUint KSenseOffset=0x1A;
static const TUint KShared=0x1U<<KUsageOffset;
static const TUint KLongLatencySet=0x1<<KLongLatencySetOffset;
static const TUint KLongLatencyGet=0x1<<KLongLatencyGetOffset;
static const TUint KLogical=0x1<<KClassOffset;
static const TUint KSenseNegative=0x01<<KSenseOffset;
static const TUint KSenseCustom=0x2<<KSenseOffset;

struct TPowerRequest;
struct SIdleResourceInfo;


/**
 * List of operations that a Custom Function may be informed of. 
 *
 * @publishedPartner
 * @prototype 9.5
 */
enum TCustomOperation
    {
	/**
	Client has requested the given level.
	*/
	EClientRequestLevel,

	/**
	Client has relinquished the given level.
    */
	EClientRelinquishLevel,
	
	/**
	Client is changing the level.
	*/
	EClientChangeLevel,
	
	/**
	A dynamic resource is being deregistered.
	*/
	EDynamicResourceDeregister
	};


/**
 *  Function prototype for the Custom Function.
 *  
 *  @publishedPartner
 *  @prototype 9.5
 */
typedef TBool (*TCustomFunction) (TInt& /*aClientId*/,
								  const TDesC8& /*aClientName*/,
                                  TUint /*aResourceId*/,
                                  TCustomOperation /*aCustomOperation*/,
                                  TInt& /*aLevel*/,
                                  TAny* /*aLevelList*/,
                                  TAny* /*aReserved*/);  // For future use

/**
@publishedPartner
@prototype 9.5
class to represent static resources
*/
class DStaticPowerResource : public DBase
	{
public:
    enum TType {EBinary = EResBinary, EMultilevel, EMultiProperty};
    enum TUsage {ESingleUse = EResSingleUse, EShared};
    enum TLatency {EInstantaneous = EResInstantaneous, ELongLatency};
    enum TClass {EPhysical = EResPhysical, ELogical};
    enum TSense {EPositive = EResPositive, ENegative, ECustom};
public:
    //exported to allow construction from other base port components.
    IMPORT_C DStaticPowerResource(const TDesC8& aName, TInt aDefaultLevel);
    IMPORT_C virtual TInt GetInfo(TDes8* aInfo)const;
    inline void SetCustomFunction(TCustomFunction aCustomFunction)
           {iCustomFunction=aCustomFunction;}

    //private data inlined accessors
    TType Type() const {return TType(iFlags&KTypeMask);}
    TClass Class() const {return TClass((iFlags>>KClassOffset)&0x1);}
    TUsage Usage() const {return TUsage((iFlags>>KUsageOffset)&0x1);}
    TLatency LatencyGet() const
             {return TLatency((iFlags>>KLongLatencyGetOffset)&0x1);}
    TLatency LatencySet() const
             {return TLatency((iFlags>>KLongLatencySetOffset)&0x1);}
    TSense Sense() const {return TSense((iFlags>>KSenseOffset)&0x3);}
protected:
    //pure virtual function to be implement by PSL
    virtual TInt DoRequest(TPowerRequest& aRequest)=0;
public:
	HBuf8* iName;
protected:
    TInt iPostBootLevel;
	TInt iDefaultLevel;
protected:
    TInt iCachedLevel;
	TUint iResourceId;
    SDblQue iNotificationList;
    SDblQue iClientList;
    TCustomFunction iCustomFunction;
    TInt iLevelOwnerId;
    SIdleResourceInfo* iIdleListEntry;
protected:
    TUint iFlags;
#ifdef PRM_CONTROLLER
    friend class DPowerResourceController;
#endif
	};

typedef void (*TPowerResourceCbFn)(TUint /*aClientId*/,
                                   TUint /*aResourceId*/,
                                   TInt /*aLevel*/,
								   TInt /*aLevelOwnerId*/,
                                   TInt /*aResult*/,
                                   TAny* /*aParam*/);

/**
@publishedPartner
@prototype 9.5
An object of this type prepresents a customised Dfc
used to signal completion of the resource manager's asynchronous APIs
and completion of notifications
@see TPowerResourceManager
 */
class TPowerResourceCb : public TDfc
	{
public:
	inline TPowerResourceCb(TPowerResourceCbFn aFn, TAny* aPtr, TInt aPriority) : TDfc(DfcFunc, this, aPriority), 
		                                                            iParam(aPtr), iCallback(aFn){ }
	inline TPowerResourceCb(TPowerResourceCbFn aFn, TAny* aPtr, TDfcQue* aQue, TInt aPriority):  
	                              TDfc(DfcFunc, this, aQue, aPriority), iParam(aPtr), iCallback(aFn) { }
private:
    inline static void DfcFunc(TAny* aPtr)
        {
        TPowerResourceCb* pCb = (TPowerResourceCb*) aPtr;
	    __KTRACE_OPT(KRESMANAGER, Kern::Printf(">TPowerResourceCb::DfcFunc ClientId = 0x%x, ResourceId = %d, Level = %d, \
			                    LevelOwnerId = %d, Result = %d", pCb->iClientId, pCb->iResourceId, pCb->iLevel, \
								pCb->iLevelOwnerId, pCb->iResult));

        pCb->Lock();
        TUint ClientId = pCb->iClientId;
        TUint ResourceId = pCb->iResourceId;
        TInt Level = pCb->iLevel;
        TInt LevelOwnerId = pCb->iLevelOwnerId;
        TInt Result = pCb->iResult;
        TAny* Param = pCb->iParam;
        pCb->UnLock();

        // Call the client specified callback function
        pCb->iCallback(ClientId, ResourceId, Level, LevelOwnerId, Result, Param);    

        pCb->Lock();
        pCb->iPendingRequestCount--;
        if(pCb->iPendingRequestCount == 0)
            pCb->iResult = KErrCompletion; //Mark the callback object to act properly during cancellation of this request.
        pCb->UnLock();
        PRM_CALLBACK_COMPLETION_TRACE
        }
private:
    void Lock()
        {
        NKern::ThreadEnterCS();
        Kern::MutexWait(*iMutex);
        }
    void UnLock()
        {
        Kern::MutexSignal(*iMutex);
        NKern::ThreadLeaveCS();
        }
    TAny* iParam; //Stores the aPtr argument passed in the constructor, to be passed as 5th argument to the callback function
    TInt iResult; //Used to store the result aswell as binary usage count for the callback
    TInt iLevel; // Level of the resource
	TInt iLevelOwnerId; // Stores owner of the resource for asynchronous get operation
    TUint iResourceId; //Stores the ID of the resource whose state is changed/read asynchronously
    TUint iClientId; //Stores the ID of the client that requested the asynchronous operation
    TPowerResourceCbFn iCallback; //Callback function object
	DMutex* iMutex;   
    TInt iPendingRequestCount;
#ifdef PRM_CONTROLLER
    friend class DPowerResourceController;
#endif
	};

/**
@publishedPartner
@prototype 9.5
Notifications class. Conditional and unconditional notifications are encapsulated in this class. 
It uses TPowerResourceCb to perform the actual notification call.
@see TPowerResourceCb
 */
class DPowerResourceNotification : public DBase
    {
public:
    enum TType {EUnconditional, EConditional};
	enum TResNotiPanic {ENotificationObjectStillInList = 25}; 
public:
	inline DPowerResourceNotification(TPowerResourceCbFn aFn, TAny* aPtr, TInt aPriority): 
	                                                 iCallback(aFn, aPtr, aPriority) {}
	inline DPowerResourceNotification(TPowerResourceCbFn aFn, TAny* aPtr, TDfcQue* aQue, TInt aPriority) : 
	                                                 iCallback(aFn, aPtr, aQue, aPriority) {}
	inline ~DPowerResourceNotification() 
		{
		if(iRegistered)
			Kern::Fault("Power Resource Controller", ENotificationObjectStillInList);
		}
public:
	TInt iPreviousLevel; //Previous level of the resource. This is used for checking the threshold condition
	TUint8 iRegistered;
private:
    TUint8 iType; // the type of notification required (conditional or unconditional).
    TUint16 iOwnerId; // the bottom 16 bits of the Id of the client which requested the notification
    TInt iThreshold; // the threshold which when crossed on a specified direction will cause a notification to be issued.
    TBool iDirection; // the direction of the resource change that together with the threshold to be crossed will result in the notification
    TPowerResourceCb iCallback; //Callback object associated with this notification
    SDblQueLink iNotificationLink; 
    DPowerResourceNotification* iNextInClient;
#ifdef PRM_CONTROLLER
    friend class DPowerResourceController;
#endif
	};

/**
@publishedPartner
@prototype 9.5
class to represent resource properties
*/
class TPowerResourceInfoV01
	{
public:
    DStaticPowerResource::TClass iClass;
    DStaticPowerResource::TLatency iLatencyGet;
    DStaticPowerResource::TLatency iLatencySet;
    DStaticPowerResource::TType iType;
    DStaticPowerResource::TUsage iUsage;
    DStaticPowerResource::TSense iSense;
    TDesC8* iResourceName;
    TUint iResourceId;
    TInt iDefaultLevel;  
    TInt iMinLevel;      //PSL mandatory field
    TInt iMaxLevel;      //PSL mandatory field
	TInt iReserved1;	 //Reserved for future use.	
	TInt iReserved2;	 //Reserved for future use.
	TInt iReserved3;	 //Reserved for future use.
    TInt iPslReserved1;  //PSL specific field
    TInt iPslReserved2;  //PSL specific field
    TInt iPslReserved3;  //PSL specific field
	};

/**
@publishedPartner
@prototype 9.5
*/
typedef TPckgBuf<TPowerResourceInfoV01> TPowerResourceInfoBuf01;

/**
@publishedPartner
@prototype 9.5
structure to represent client properties
*/
struct TPowerClientInfoV01
	{
    TUint iClientId;
    TDesC8* iClientName;
	};

#endif // __RESOURCE_H__