Porting -the Power Resource Manager

Porting -the Power Resource ManagerThis tutorial describes how to port the Platform Specific Layer -(PSL) of the Power Resource Manager (PRM) and how to modify -clients, such as device drivers, to use the PRM framework. -

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

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.

-Power Resource -Manager (PRM) -Power Management -Tutorials + + + + + +Porting +the Power Resource ManagerThis tutorial describes how to port the Platform Specific Layer +(PSL) of the Power Resource Manager (PRM) and how to modify +clients, such as device drivers, to use the PRM framework. +

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

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.

+Power Resource +Manager (PRM) +Power Management +Tutorials

\ No newline at end of file