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:

H4 HRP - OMAP2420 SDP +hardware reference platform referred to in these documents as examples of +the base port,
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,
The +core porting process.

This document refers to the reference implementation of the PRM PSL +for the H4 HRP platform wherever possible. The source code for the reference +implementation can be found in \omap_hrp\h4\resman. The +MMC and Sound_SC (in H4 HRP) device drivers are modified to use the new PRM +framework.

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().