Porting the Power Resource Manager

Purpose

The PRM is a framework for managing system power resources. This +framework improves portability across different platforms and reduces +device driver complexity.

The PRM framework is split into +two layers:

Platform Independent +Layer - the PIL is a generic software layer that is implemented by +Symbian. This is the base virtual class for the Power Resource Controller +(DPowerResourceController),
Platform Specific +Layer - the PSL is developed specifically to interface with the target +hardware by licensees. This is the class derived from DPowerResourceController.

Other acronyms used in this document set:

LDD - Logical +Device Driver. The higher layer of abstraction within the Symbian +platform device driver framework which implements common functionality +among differing pieces of hardware of one type,
PDD - Physical +Device Driver. The lower layer of abstraction within the Symbian platform +device driver framework which implements functionality that is specific +to a particular piece of hardware.

Intended audience

This document is intended +to be used by Symbian platform device creators.

Required +background

The reader of this document is assumed to have +knowledge of the Symbian platform device driver model and base port layering and components.

Device Driver Concepts,

Introduction

The PRM provides a unique place +where all the current power states for resources can be obtained at +any time. The sum of all internal and external power states defines +the current system-wide power state.

Setup and configuration +requirements

The PRM component is implemented as a kernel +extension with an exported public interface that is accessible to +kernel side components through statically linking against its export +library. The export library is built from the resource manager and +the resource manager libraries.

There are two versions available:

basic resource +manager - provides essential or required functionality for static +resources.

The basic version of the PIL layer is compiled +into resmanpsl.lib. This kernel library must +be included by the PSL to produce the kernel extension.
extended resource +manager - provides additional support for dynamic resources and resource +dependencies.

The extended version of the PIL layer is complied +into resmanextenedpsl.lib. This kernel library +must be included by the PSL to produce the kernel extension.

Device drivers that require the use of the PRM should link +against the appropriate library. resman.lib to +use the basic version and resmanextended.lib to +use the extended version of the PRM.

Building the PRM for +the target platform

The PRM is an early extension, so +the targettype in the mmp file +must be set to kext. If the PRM is implemented as +a PDD the targettype in the mmp file should be should +be pdd.

Boot sequence

The +PRM cannot be used to operate on power resources until later in the +boot sequence when the kernel allows the scheduling of other threads. +During this time it is not possible to read or change the state of +resources, but DPowerResourceController::PostBootLevel() can be used to specify the state of specific resources and the PRM +can change the state of resources to appropriate levels before the +PRM is fully initialised.

PostBootLevel() is used within the extension entry point, during this time PRM is +not fully initialised. Note: This function can only be used +for static resources and static resources with dependencies.

static TInt PostBootLevel(TUint aResId, TInt aLevel);

PostBootLevel() takes the resource ID and the +post boot level that the level a resource needs to be after it is +initialised. Typically the post boot level is only known to the PSL. +However kernel extensions (and the variant) may request a post boot +level.

If a kernel extension needs to know if certain resources +have reached the post boot state in order to complete its own initialisation +then the kernel extension should queue resource state change notifications +for the resource when first registering as clients with the PRM. Note: notification requests are accepted before the PRM is fully +initialised.

Variants or kernel extensions can register static +resources before the PRM is fully initialised with DPowerResourceController::RegisterStaticResource(). This API can only be used by static resources and not by static +resource that support dependency. See DoRegisterStaticResources().