Implement +the controllable power resources

Implementing power resources

The following tasks +are covered in this tutorial:

Create your resource by
Override +the pure virtual functions,
Create resource dependencies,
Create custom resources.

Override the pure +virtual functions

The pure virtual functions of DStaticPowerResource or DDynamicPowerResource must +be implemented.

Constructor

Information about the resource +based on the resources category must be set in the iFlags bit +mask. Static variables that define a resources classification can be found +within 32\include\drivers\resource.h.

Each resource +is classified based on:

usage,
operating levels,
latency,
resource sense.

Below is the example implementation of derived class constructor

// multilevel, shared, long latency, read and write, positive resource. +DMLSHLGLSPResource::DMLSHLGLSPResource() : DStaticPowerResource(KDBSHLGLSPResource, E_ON), + iMinLevel(E_OFF), iMaxLevel(E_ON), iCurrentLevel(E_ON), iPolled(ETrue) + { + iFlags = EMultilevel | KShared | KLongLatencySet | KLongLatencyGet; + . . . + }

GetInfo()

The PIL uses GetInfo() to +get resource information. The default implementation of this function provides +generic information about the resource by updating the passed descriptor that +contains an information structure TPowerResourceInfoV01. +Derived implementations must fill in all the PSL specific fields and call +the base class implementation. Below is an example implementation.

TInt DH4SndFclkResource::GetInfo(TDes8* info) const + { + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">DH4SndFclkResource::GetInfo\n")); + + /** Call base class implementation to fill generic details */ + DStaticPowerResource::GetInfo((TDes8*) info); + TPowerResourceInfoV01 *buf1 = (TPowerResourceInfoV01*) info; + buf1->iMinLevel = iMinLevel; + buf1->iMaxLevel = iMaxLevel; + __KTRACE_OPT(KRESMANAGER, Kern::Printf("<DH4SndFclkResource::GetInfo\n")); + return KErrNone; + }

The member variables of the TPowerResourceInfoV01 structure +are reserved for PSL information. These can be used to return resource specific +information to clients.

DoRequest()

DoRequest() is +used by the PIL to control resources. For example, to change and read the +state of resources. DoRequest() takes a TPowerRequest object +that contains all the request information. Note: This function needs +to be implemented for all resources.

Below is an example DoRequest() function +implementation for a binary, instantaneous resource.

TInt DH4MmcCtrllerPwrResource::DoRequest(TPowerRequest& aRequest) + { + TInt retVal = KErrNone; + TUint16 config; + /** Enable/disable the MMC controller by programming the MMC controller 'CON' register- 'POW' bit */ + if (aRequest.ReqType()==TPowerRequest::EGet) + { + PRM_PSL_RESOURCE_GET_STATE_START_TRACE + config = OMAPMMC_GET_REG(KHoMMC_Con_Reg); + if(config & KHtMMC_PowerUp) + { + aRequest.Level() = 1; + iCurLevel = 1; + } + else + { + aRequest.Level() = 0; + iCurLevel = 0; + } + PRM_PSL_RESOURCE_GET_STATE_END_TRACE + } + else if(aRequest.ReqType()==TPowerRequest::ESetDefaultLevel) + { + PRM_PSL_RESOURCE_CHANGE_STATE_START_TRACE + OMAPMMC_MOD_REG(KHoMMC_Con_Reg, KHtMMC_PowerUp, KClear32); + iCurLevel = iDefaultLevel; + aRequest.Level() = iDefaultLevel; + PRM_PSL_RESOURCE_CHANGE_STATE_END_TRACE + } + else + { + PRM_PSL_RESOURCE_CHANGE_STATE_START_TRACE + if(aRequest.Level() == 1) + { + OMAPMMC_MOD_REG(KHoMMC_Con_Reg, KClear32, KHtMMC_PowerUp); + } + else + { + OMAPMMC_MOD_REG(KHoMMC_Con_Reg, KHtMMC_PowerUp, KClear32); + } + iCurLevel = aRequest.Level(); + PRM_PSL_RESOURCE_CHANGE_STATE_END_TRACE + } + return retVal; + }

The DoRequest function implementation should take care +of blocking the Resource Controller thread as operations on a long latency +resource take a significant amount of time to complete (in hardware). Usually +the request completion is notified either through an ISR (interrupt driven) +or through register setting (polling wait) by hardware.

Below is an +example DoRequest() implementation for a long latency resource.

TInt DH4MmcPowerResource::DoRequest(TPowerRequest& aRequest) + { + TUint8 iMenelausConf; + TInt retVal = KErrNone; + + /** Access to Menelaus registers is over I2C bus. This is a long latency synchronous operation. + Create a Menelaus Request structure and send it to Menelaus chip, Wait until a response is received */ + + if (aRequest.ReqType()==TPowerRequest::EGet) + { + // Frame the request + ... + } + // Default level is off. + else if (aRequest.ReqType() == TPowerRequest::ESetDefaultLevel) + { + // Frame request to move the resource to default state + ... + } + // EChange + else + { + // Frame request to set the requested resource state + ... + } + + // Request the operation on the hardware + retVal = Menelaus::AccessRegister(iMenelausReq); + + // Wait for the request to complete + __KTRACE_OPT(KPBUS1, Kern::Printf("Waiting for menelaus req to signal sem\n")); + NKern::FSSetOwner(&iSemaphore,NULL); + iSemaphore.iCount = 0; + + // This will be signalled in Menelaus access functions callback below + NKern::FSWait(&(iSemaphore)); + + // Menelaus chip has responded + if(iMenelausAccessErr == KErrNone) + { + switch(iMenelausState) + { + case EMenelausRead: + // Return 0/1 depending on the value set + iMenelausConf = (*(iRdBuffer.Ptr())) & KHoMenelausVmmcModeMask; + if(iMenelausConf == 3) + { + iCurLevel=aRequest.Level()=1; + } + else + { + iCurLevel=aRequest.Level()=0; + } + PRM_PSL_RESOURCE_GET_STATE_END_TRACE + break; + + case EMenelausSingleWrite: + iCurLevel = aRequest.Level(); + PRM_PSL_RESOURCE_CHANGE_STATE_END_TRACE + break; + } + } + return iMenelausAccessErr; + } + +/** Below is the Menelaus access functions callback where the semaphore is signalled. */ +void DH4MmcPowerResource::MenelausAccessDone(TAny* aPtr, TInt aResult) + { + DH4MmcPowerResource* ptr = reinterpret_cast<DH4MmcPowerResource*>(aPtr); + ptr->iMenelausAccessErr = aResult; + if(aResult != KErrNone) + { + __KTRACE_OPT(KRESMANAGER, + Kern::Printf("Menelaus::MenelausAccessRegister ERR(%d)\n", aResult)); + } + // Signal the waiting thread + NKern::FSSignal(&(ptr->iSemaphore)); + return; + }

Create +resource dependencies

A resource has a dependency if the state +of the resource depends on the state of one or more resources. For example, +a clock whose frequency is derived from another clock or voltage is a dependent +resource. The PSL usually handles resource dependencies transparently. However, +if the resources have public users (clients of the PRM), then these resources +should be registered with the PRM as Resource +dependencies that are linked.

Each dependency must be assigned +a priority value. The priority is used by the PIL when propagating the change +and propagating the request for notifications. Each link stemming from a resource +must have a unique priority value.

Note: Resource dependencies +are only supported in the extended version of the PRM. Only long latency resources +are allowed to have dependents and no closed loop dependencies are allowed.

Register +resource dependencies for dynamic and static resources

Static +resources that support dependencies are created and registered with the PRM +during resource controller creation time and are derived from DStaticPowerResourceD:

DXXXStaticPowerResourceD : public DStaticPowerResourceD + { +public: + DXXXStaticPowerResourceD(); + TInt DoRequest(TPowerRequest &req); + TInt GetInfo(TDes8* aInfo) const; + TChangePropagationStatus TranslateDependentState(TInt aDepId, TInt aDepState, TInt& aResState); +private: + TInt iMinLevel; + TInt iMaxLevel; + TInt iCurrentLevel; + ... + };

Dependencies between static resources should be established +by the PSL before registering these resources with the PIL. Use the DStaticPowerResourceD::AddNode() function +provided in the base class to establish a dependency link between static resources. +See Creating +dependencies between static resources.

Dynamic resources that +support dependency are derived from DDynamicPowerResourceD. +These can be registered and deregistered from the PRM at any time after the +PRM is fully initialised. Dependencies between resources are established by +the client using PowerResourceManager::RegisterResourceDependency().

DXXXDynamicPowerResourceD : public DDynamicPowerResourceD + { +public: + DXXXDynamicPowerResourceD(); + TInt DoRequest(TPowerRequest &req); + TInt GetInfo(TDes8* aInfo) const; + TChangePropagationStatus TranslateDependentState(TInt aDepId, TInt aDepState, TInt& aResState); +private: + TInt iMinLevel; + TInt iMaxLevel; + TInt iCurrentLevel; + ... + };

Dependencies can be established between a dynamic resource +and a static (dependency enabled) resource using the same API. A client can +deregister dependencies between a pair of dynamic resource (or between a dynamic +and static resource) using PowerResourceManager::DeRegisterResourceDependency(). +When a dynamic resource that supports dependency deregisters from the PRM, +dependencies are removed automatically by the PIL.

Change the state +of dependent resources

When a state change is requested by a client +on any resource in a dependency tree before proceeding with the change the +PIL must check if the change is allowed by its dependents and the ones it +depends on. The PIL does this by calling the TranslateDependentState() function +on each resource. This is a pure virtual function in the base class and must +be implemented in the derived class.

This function is called by the +PIL prior to a resource change on any of its dependents. The function returns +one of these values:

EChange - +If the resource accepts the state change of the dependent resource and, as +a result of the dependent resources state change this resource needs to change +its own state. The new state of this resource is updated in aResState,
ENoChange - +if the resource accepts the dependent resources state change and this resource +does not need to change its state,
ENotAllowed - +if the resource does not accept the dependent resources state change.

TChangePropagationStatus DXXDependResource::TranslateDependentState(TInt /*aDepId*/, TInt aDepState, + TInt& aResState) + { + /* Switch ON if the dependent resource is ON */ + if((aDepState == 1) && (iCurrentLevel == 0) + { + aResState = iMaxLevel; + return EChange; + } + + /* Don’t allow dependent to OFF, if this is still ON */ + else if (aDepState == 0) && (iCurrentLevel == 1) + { + return ENotAllowed; + } + + return ENoChange; + }

Create +custom resources

Clients on a shared resource may have different +requirements on the state of a shared resource. The resource sense is used +by the PIL to determine whose requirement prevails:

positive sense resources +- when shared can have their value increased without prejudice to their clients,
negative sense resources +- when shared can have their value decreased without prejudice to their clients,
custom sense resources +- when shared may be increased or decreased freely by some privileged clients +but not by others, which are bound by the requirement of the privileged clients.

A custom function must be supplied for every Power resources resource. This function is called by the PIL every +time a change request is issued to determine if the change requested by the +client is allowed as a decision to allow the resource change is determined +solely by the PSL. The resource object contains a pointer that must be set +at construction for custom sense resources by calling this function:

inline void SetCustomFunction(TCustomFunction aCustomFunction)

This +function sets the custom function for the resource. If a custom function is +not supplied for a custom sense resource the PIL panics during a resource +state change. An example of a custom sense resource is a shared domain clock +when a domain client uses it as a bit clock.

TCustomFunction is +a function pointer:

typedef TBool (*TCustomFunction) (TInt& /*aClientId*/, + TUint /*aResourceId*/, + TInt& /*aLevel*/, + TAny* /*aLevelList*/);

The +values held in TCustomFunction are:

the Id of the client +requesting the change,
the Id of the resource +on which the change is requested (this allows a single function to handle +multiple resources),
the level the client +is requesting,
a pointer to the list +of the resource’s client +levels.

Custom functions can be set at any time before a resource state change +is requested on a resource. Ideally a custom function is set at resource creation +time in the resource's constructor.

DBSHLGLSCResource::DBSHLGLSCResource() : DStaticPowerResource(KDBSHLGLSCResource, E_ON), iMinLevel(E_OFF), iMaxLevel(E_ON), iCurrentLevel(E_ON), iPolled(EFalse) + { + iFlags = KMultiLevel | KShared | KLongLatencySet | KSenseCustom; + SetCustomFunction(CustomFunction); + ... + }

The decision to allow the requested resource state change +is specified in the custom function return value. This is ETrue if +the change is allowed and EFalse if the change is not allowed.

The +function can change the state of the resource to a level other than the one +requested and can choose a client other than the passed client to hold the Caching +the prevailing level of the resource.

Supporting dependencies

If +the custom sense resource supports dependencies then use the function pointer TDependencyCustomFunction. +This takes an additional parameter that specifies the resource Client level objects.