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

Using the Power Resource Manager

Porting the PRM consists of implementing the PSL layer for a given hardware platform and modifying clients, such as device drivers, to use the PRM framework.

The following tasks are covered in this tutorial:

• Implement the controllable power resources,

• Implement the PSL for the target,

• Port the client drivers to use the PRM (to control the implemented resources),

• Debugging the PRM,

• Testing the PRM PSL.