SlideShare a Scribd company logo

DPM-mobilinux

S
Sholeh Gregory

The document provides information about the Mobilinux 4.0 Dynamic Power Management Programmer's Guide, including who should read it, conventions used, the documentation set it is part of, how to access documentation, and where to find support. It describes the intended audience as embedded systems developers using Linux or Windows and covers typographical conventions. It lists other manuals in the Mobilinux documentation set and describes where online documentation is located.

1 of 153
Download to read offline
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 3 7 E A S T A RQU E S A V E NU E , S U NN Y V A L E , CA 94 0 8 5 Mobilinux™ 4.0 Dynamic Power Management Programmer’s Guide 1237 East Arques Avenue, Sunnyvale, CA 94085
C O P Y R I G HT Copyright © 2005 MontaVista Software, Inc. All Rights Reserved. This product and related documentation are protected by copyright and distributed under licenses controlling its use, copying, and distribution. No part of this product or its related documentation may be reproduced in any form or by any means except under such licenses and this copyright notice. MontaVista Software, Inc. makes no representations or warranties with respect to the contents or use of this manual, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. MontaVista Software, Inc. makes no representations or warranties with respect to MontaVista® Linux® , and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. MontaVista is a registered trademark of MontaVista Software, Inc. The registered trademark Linux is used pursuant to a sublicense from the Linux Mark Institute, the exclusive licensee of Linus Torvalds, owner of the mark on a world-wide basis. All other names mentioned herein — trademarks, registered trademarks, and service marks — are the property of their respective owners. R E V I S I O N H I S T O R Y This document was prepared by MontaVista Software, Inc. C O NT AC T You are welcome to contact us: sales@mvista.com Edition Version Revision Documentation Release Date Notes ............................................................. Mobilinux 4.0.2 A September 13, 2005 First Release
..... iii . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CONTENTS PREFACE ...............................................................................15 Who Should Read this Manual?................................................................................16 Conventions.................................................................................................................16 Mobilinux 4.0 Documentation Set...........................................................................17 Mobilinux 4.0 Documentation Set Locations ..........................................................17 Other Related MontaVista Documentation .............................................................17 Accessing Online Documentation ...........................................................................18 Accessing man Pages....................................................................................................18 Accessing HTML Man Pages .....................................................................................19 Accessing info Pages....................................................................................................19 Shell Prompts...............................................................................................................20 Using a Bash Shell ........................................................................................................20 Support .........................................................................................................................20 MontaVista Zone..........................................................................................................21 Contact..........................................................................................................................21 Third-Party Documentation......................................................................................21 1 Power Management Background Technology ................1 Background....................................................................................................................2 Power Management Background................................................................................. 2 Why Dynamic Power Management is Needed .......................................................... 2 What is Dynamic Power Management?.....................................................................3 What is an Embedded System?...................................................................................3 What is Embedded Linux?............................................................................................ 4 Dynamic Power Management for Embedded Systems ........................................... 4
iv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Architectural Summary.................................................................................................4 What is a DPM Policy?.................................................................................................. 5 What is a DPM Power Policy Manager?..................................................................... 5 Dynamic Power Management and Mobile Devices ................................................5 Mobile Devices Conserving Energy ............................................................................ 6 Plugable Power Management Policies......................................................................... 6 2 What is Mobilinux Dynamic Power Management?.........9 What is Mobilinux?.....................................................................................................10 What is Mobilinux Dynamic Power Management? ...............................................10 Mobilinux Dynamic Power Management Benefits................................................10 Mobilinux Dynamic Power Management Features ...............................................11 MontaVista Power Manager .......................................................................................11 DPM Library .................................................................................................................12 Hotplug Agents.............................................................................................................12 Clock Events Tracking ................................................................................................12 Power Profiler Plugin...................................................................................................12 Tick Elimination...........................................................................................................12 High-level Power Manager Interface.........................................................................13 Event Handling.............................................................................................................13 Suspend and Resume Handling..................................................................................13 3 What is MontaVista Power Manager? ...........................15 What is MontaVista Power Manager?......................................................................16 MontaVista Power Manager Features......................................................................16 DPM Interface ..............................................................................................................16 Integrated Components...............................................................................................17 Default Operating Points ............................................................................................17 User-Defined Power Parameters................................................................................17 Default Power Policies.................................................................................................17 Overview of MontaVista Power Manager Tools ...................................................18 Command-Line.............................................................................................................18 Plugin APIs....................................................................................................................18
..... v . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 MontaVista Power Manager Building Blocks ................19 Operating Points ........................................................................................................20 Operating Points Parameters......................................................................................20 Operating Points Examples ........................................................................................21 Operating Classes........................................................................................................21 Operating States..........................................................................................................22 What is an Operating State?........................................................................................22 Operating States Architecture.....................................................................................22 Operating States Types................................................................................................23 DPM Power Policy.....................................................................................................25 What is a DPM Power Policy?....................................................................................25 Power Policy Architecture...........................................................................................25 5 DPM Device Driver Interfaces .........................................27 DPM Device Driver Background.............................................................................28 DPM Device Constraints Background....................................................................28 How Device Constraints Work..................................................................................28 Device Constraints Features.......................................................................................29 Forced Operating Points............................................................................................29 DPM Classes................................................................................................................30 DPM Driver Scale Callbacks.....................................................................................30 Driver Model and Device Suspend/Resume..........................................................31 6 MontaVista Power Manager Out-of-the-Box ................33 Using Power Manager Out-of-the-Box...................................................................34 Installing Configuration File......................................................................................35 Exiting your Power Manager.....................................................................................35 Power Manager Default Configuration Files..........................................................36 TI-OMAP1710 Board Configuration........................................................................36 Intel PXA27x Mainstone Board Configuration.......................................................37
vi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Designing Your Power Manager Building Blocks..........41 Studying Your Hardware’s Power Management Characteristics .........................42 Configuring Your Board..............................................................................................42 Device Power Constraints...........................................................................................42 Guidelines for Setting up DPM Operating Points.................................................42 Designing High-Level Power Management Software Architecture....................43 Designing Power Policy with MontaVista Power Manager...................................44 Designing DPM Suspend/Resume Devices...........................................................44 Specifying Power State Values....................................................................................45 Designing DPM Driver Scale Callbacks..................................................................45 Designing Power-Related Events.............................................................................45 Designing Power Policies ..........................................................................................46 Designing Programmable Sleep/Wakeup Sources ................................................46 Designing DPM Task States......................................................................................47 Designing Sleep/Standby Behavior .........................................................................47 8 Designing Device Interactions with DPM ......................49 Design Considerations ...............................................................................................50 Hardware Restrictions..................................................................................................50 Constraints v.s. Event Messages ................................................................................50 Handeling Conflicting Devices...................................................................................50 Scale Callback................................................................................................................51 Specifying Device Constraints ..................................................................................51 Constraints for an Operating Point ...........................................................................51 Constraints for an Operating Class............................................................................52 Specifying Power Event Userspace Notification...................................................52 Power Hotplug Agents ................................................................................................52 Specifying Device Constraints Interfaces................................................................52 Specifying Constraints through SYSFS.....................................................................53 Asserting Constraints...................................................................................................53 Creating Driver Interface to DPM...........................................................................54 Exporting Driver DPM to Userspace......................................................................55
..... vii . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Implementing Your Power Manager Building Blocks...57 Implementing Power Management for Custom Drivers......................................58 Implementing Precompiled Device Constraints....................................................59 Implementing Driver Scale Callbacks......................................................................59 Implementing Notification of Kernel Power Events............................................60 Developing Your Power Manager............................................................................60 Implementing Notification of Application Power Events...................................61 Implementing DPM Operating Points....................................................................61 Examples........................................................................................................................61 Implementing DPM Operating Classes...................................................................62 Examples........................................................................................................................63 Implementing DPM Operating Policies..................................................................63 Examples........................................................................................................................64 Implementing Policy Manager Handling of Events ..............................................65 Implementing Other Logic for Determining Power Policy.................................66 Implementing Runtime Device Constraints ...........................................................66 Implementing System Suspend/Resume ................................................................67 Event Handling.............................................................................................................67 Suspend and Resume Handling..................................................................................68 Implementing Device Power State Modifications .................................................68 10 Starting Your Power Manager ......................................69 Running Your Power Manager.................................................................................70 Starting Power Manager Manually .............................................................................70 Starting Power Manager Automatically.....................................................................70 Starting Applications with DPM interactions.........................................................70 dpmlib.............................................................................................................................70 /proc...............................................................................................................................71 Testing Your Power Management System..............................................................71 Activating a Policy ......................................................................................................72 Using dpmmgr ..............................................................................................................72 Using sysfs .....................................................................................................................72
viii . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Power Manager Commands ...........................................73 Power Manager commands Accessibility................................................................74 Commands Syntax........................................................................................................74 Operating Points and Classes Commands..............................................................74 Power Policy Commands...........................................................................................74 Power State Commands.............................................................................................75 Device Power State Commands ...............................................................................75 Device Constraint Commands..................................................................................75 System Status Commands..........................................................................................75 Power Events Commands.........................................................................................76 12Plugin Commands and APIs............................................77 Power Manager Commands Accessibility...............................................................78 Commands Syntax........................................................................................................78 Plugin Commands.......................................................................................................78 Plugin APIs..................................................................................................................79 13Power Manager Profiler Plugin ......................................81 DPM-Profiler Plugin Commands.............................................................................82 Terms Definitions.......................................................................................................83 Power Profile.................................................................................................................83 Power Metric.................................................................................................................83 14 DPM APIs .........................................................................85 libdpm DPM APIs Interface.....................................................................................86 int dpm_init() ................................................................................................................86 int dpm_set_state (char *statename) .........................................................................86 int dpm_create_op (char *opname, char *params).................................................86 int dpm_set_op_param (char *opname, char *paramname, int paramvalue).....87 int dpm_get_op_param (char *opname, char *paramname, char *buf, size_t bufsiz)...................................................87 int dpm_create_class (char *classname, char *opnames).......................................87
..... ix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . int dpm_create_policy (char *policyname, char *opsclasses)................................88 int dpm_set_policy_state_map (char *policyname, char *statename, char *opclass) .........................................................88 int dpm_get_policy_state_map(char *policyname, char *statename, char *buf, size_t bufsiz).........................................88 int dpm_set_active_policy (char *policyname)........................................................89 int dpm_get_active_policy (char *buf, size_t bufsiz)..............................................89 sys-dpm APIs Interface..............................................................................................90 sys_dpm .........................................................................................................................90 DPM_INIT ...................................................................................................................92 DPM_TERMINATE ..................................................................................................93 DPM_DISABLE..........................................................................................................95 DPM_ENABLE...........................................................................................................97 DPM_CREATE_OPT................................................................................................98 DPM_CREATE_CLASS..........................................................................................100 DPM_CREATE_POLICY.......................................................................................101 DPM_DESTROY_POLICY ...................................................................................103 DPM_SET_POLICY ................................................................................................106 DPM_GET_POLICY...............................................................................................108 DPM_GET_ALL_POLICIES.................................................................................110 DPM_GET_CLASSES.............................................................................................112 DPM_SET_TASK_STATE.....................................................................................113 DPM_GET_TASK_STATE....................................................................................116 DPM_GET_POLICY_STATS................................................................................118 DPM_GET_CLASS_STATS...................................................................................120 DPM_GET_OPT_ STATS......................................................................................122 DPM_GET_OS_STATS ..........................................................................................124 INDEX..................................................................................133
x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PREFACE Welcome to the Mobilinux 4.0 Dynamic Power Management Programmer’s Guide! The MontaVista Dynamic Power Management (DPM) feature provides applications and tools to control power policy for power-conscious Linux-based mobile devices. Additionally, it enables rapid modifications to power parameters of these systems, such as their CPU, bus frequency, and core voltage scaling. The Mobilinux 4.0 Dynamic Power Management Programmer’s Guide provides clear and concise information about the DPM background technology, MontaVista DPM features, concepts, out-of-the-box Power Manager, and tasks needed to design and to implement user-defined power management for two supported software development platforms: TI-OMAP 1710 and Intel PXA27x. The following topics are covered in Preface: • “Who Should Read this Manual?” • “Conventions” • “Mobilinux 4.0 Documentation Set” • “Accessing Online Documentation” • “Shell Prompts” • “Support” • “Contact” • “Third-Party Documentation”
Who Should Read this Manual? 16 Who Should Read this Manual? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . W H O S H O U LD R E A D T HI S M A N U A L ? The intended audience for this guide are systems developers able to build embedded systems using one of the following operating systems: • Linux • Microsoft® Windows C O N V E N T I O N S The following list contains typographical conventions used throughout this manual: Convention Meaning Example .............................................................. Courier Programming code, commands on-screen output, tools, applications Edit your .login file. Type ls -l to list all files. machine_name% test.doc. Bold Courier What you type, File names machine_name% su dpmmgr.log Courier Italics Variables to be replace with actual values set policy <name> italics new terms, word to be emphasized A forced operating point ..............................................................
..... Mobilinux 4.0 Documentation Set Mobilinux 4.0 Documentation Set 17 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . M O BI L I N UX 4 . 0 D O C UM E N T A T I O N S E T The Mobilinux 4.0 Dynamic Power Management Programmer’s Guide is a companion document to the following manuals in the Mobilinux documentation set: • Mobilinux 4.0 Release Notes—Contains open issues and late-breaking product-related information that are not published in the product manuals. • Mobilinux 4.0 Installation Guide—Provides step-by-step installation instructions. • Mobilinux 4.0 Kernel Developer's Guide—Provides information on kernel development and debugging features and instructions on how to use them. • Mobilinux 4.0 Development Environment Guide—Defines the MontaVista Software development environment and provides an overview of the development life cycle. • Mobilinux 4.0 Kernel Migration Guide—Provides the instructions needed to migrate from the Linux 2.4 kernel to the 2.6 kernel. It a list of obsolete and upgraded features. • Mobilinux 4.0 Platform Developer’s Guide—Provides information on how to integrate system components (file system, kernel, applications) and deploy them to a target system. • Mobilinux 4.0 Security Reference Guide—Provides information on locating MontaVista Security Alerts and provides methods for developing a secure system. • Mobilinux 4.0 Event Broker Programmer’s Guide—Provides instructions and common error codes for the MontaVista Linux Event Broker. MOBILINUX 4.0 DOCUMENTATION SET LOCATIONS Mobilinux 4.0 online documentation are provided on the product CD in the following directories: • /opt/montavista/mobilinux/devkit/<architecture>/<processor>/doc • /opt/montavista/common/doc OTHER RELATED MONTAVISTA DOCUMENTATION MontaVista Web site at http://www.mvista.com as well as “MontaVista Zone” at http://w.ww.support.mvista.com offer up-to-date information on a variety of topics, including online product documentation, late-breaking updates, product information, technical whitepapers, and press coverage.
Accessing Online Documentation 18 Accessing Online Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A C C E S S I N G O N L I N E D O CU M E N T A T I O N In addition to mobilinux documentation set and other related information available on the company’s Web site, the following documentation is also available online: • Manual (man) pages—Help pages that provide a description of the application, its options and usage, links to related documentation, and a list of known problems. • Information (info) pages—Online manuals. Note: If you install mobilinux in a different directory, replace the /opt directory with the location you choose. ACCESSING MAN PAGES Mobilinux 4.0 provides man pages in HTML and in standard ASCII formats, located in the following directories: SE TTI NG U P Y OUR M AN P AT H Before accessing standard man pages, first you must include their location (MANPATH) in your executable search path. To avoid a conflict with the host man pages, creating an alias for the mobilinux man pages is recommended. To create an alias for the mobilinux MANPATH, first open a Bash shell and then enter: alias mvman=”MANPATH=/opt/montavista/mobilinux/man man” VIE W ING A SC II MA N PA GE S To display the ASCII version of the man pages, first open a Bash shell and then enter mvman <application> to display the first page or enter mvman -a <application> to display all application man pages. Application Directory ............................................................. Target /opt/montavista/mobilinux/devkit/<architecture>/ <processor>/target/usr/share/man Common /opt/montavista/common/man Cross-Development /opt/montavista/mobilinux/devkit/<architecture>/ <processor>/man .............................................................
..... Accessing Online Documentation Accessing Online Documentation 19 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ACCESSING HTML MAN PAGES To access the HTML man pages, enter /opt/montavista/mobilinux/devkit/html/ in a Web browser. ACCESSING INFO PAGES The mobilinux application info pages are located in the following directories: SE TTI NG U P Y OUR I NF OP AT H Before you can access info pages, you must include their location at INFOPATH into your executable search path. To avoid a conflict with the host info pages, creating an alias for the mobilinux info pages is recommended. To create an alias for the mobilinux INFOPATH, first open a Bash shell and then enter: alias mvinfo=”INFOPATH=/opt/montavista/mobilinux/info info” VIE W ING A SC II IN FO PA G ES To display the ASCII version of the info pages, first open a Bash shell and then enter: mvinfo <application> Application Directory ............................................................. Target /opt/montavista/mobilinux/devkit/<architecture>/ <processor>/target/usr/share/info Common /opt/montavista/common/info Cross-Development /opt/montavista/mobilinux/devkit/<architecture>/ <processor>/info .............................................................
Shell Prompts 20 Shell Prompts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . S H E L L P R O M P T S The following table shows the default system prompt and superuser prompt for the C shell, Bourne shell, and Korn shell interfaces: USING A BASH SHELL The instructions throughout this manual use a Bash shell terminal window. To open a Bash shell on a Windows host, open the Start menu and select Programs > MontaVista > Bash Shell. S U P P O RT In-depth technical assistance is available. Customers can request help with installation, configuration, usage and other questions concerning Mobilinux 4.0. Generally, this software is fully supported for application developers doing development of their project. General technical assistance is only provided for third-party products that MontaVista Software recommends for use with Mobilinux 4.0. This service may range from answering questions to providing workarounds. Because MontaVista Software is not responsible for the development of these third-party products, some issues might require input from the original application vendor. MontaVista only provides assistance for these products when they are being used with Mobilinux 4.0. MontaVista Software, Inc. wants your input regarding how well we are performing, as well as any suggestions or comments that you have for improvement. Please e-mail comments to suggestions@mvista.com. Shell Prompt ............................................................. C shell prompt machine_name% C shell superuser prompt machine_name# Bourne shell and Korn shell prompt $ Bourne shell and Korn shell superuser prompt # .............................................................
..... Contact Contact 21 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MONTAVISTA ZONE MontaVista Zone is the MontaVista Software, Inc. subscriber-only support Web site. It provides focused information about embedded Linux systems, access to MontaVista developed software, and provides answers to frequently asked questions (FAQs) about products and services. MontaVista Zone is located at http://support.mvista.com. C O NT AC T You are welcome to contact MontaVista. For suggestions, please send e-mail to suggestions@mvista.com. For questions about future availability, what you purchased, supported targets and so forth, please contact your sales manager or generally you can e-mail sales@mvista.com. If you purchased a named contact seat, contact information for MontaVista Technical Support is located under the Contact Support link on MontaVista Zone. If you cannot see this link, then you purchased a platform developer or application developer seat and you will need to contact your designated named contact. T H I RD -P AR T Y DO CU M E N T A T I O N A variety of Linux, Unix, and Java documentation is currently available. The following list contains some sources of available third-party documentation: • O’Reilly Safari—Publishes computer software developer books (http://safari.oreilly.com/). • Addison Wesley professional publications—Publishes professional computer books (http://www.awprofessional.com/). • Prentice Hall—Publishes academic and reference books (http://www.awprofessional.com/). • Wrox—Publishes Programmer-to-programmer books (http://www.wrox.com/WileyCDA/). • Online news groups—Provides a forum for computer-focused news groups (for example, Google, Yahoo, and similar services). For examples of Google news groups, see http://groups.google.com/. Note: This list are provided for your convenience only—MontaVista Software does not specifically endorse them.
Third-Party Documentation 22 Third-Party Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 POWER MANAGEMENT ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BACKGROUND TECHNOLOGY This chapter provides brief descriptions of the concepts of the Dynamic Power Management (DPM) background technology in embedded Linux environments that apply to mobile devices. Understanding these DPM background technology concepts permits better utilization of the Mobilinux Dynamic Power Management feature. The following topics are covered in this chapter: • “Background” • “What is Dynamic Power Management?” • “What is an Embedded System?” • “Architectural Summary” • “Dynamic Power Management and Mobile Devices”
POWER M A N A G EM E N T B A C K G R OU N D TE C HN O LOG Y Background 2 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B AC K G R O U ND Topics in this section include: • “Power Management Background” • “Why Dynamic Power Management is Needed” POWER MANAGEMENT BACKGROUND Power management was first introduced in laptop computers to allow longer operating times while running on battery power; later, it was brought into the desktop PC market. Many early power management systems had long recovery times, difficult configuration methods, and low energy savings. Since the early days, however, power management has improved rapidly, becoming more powerful, reliable, and easier to use. It now delivers considerably more energy savings. Power management in personal computers relies on the fact that for most of the time a typical PC is on, it is not doing anything productive. As long as the computer is idle, energy use can be reduced without interfering with work. Common methods to reduce energy usage are slowing down or stopping the processor clock, spinning down the hard disk, and turning off entire system components such as video, sound cards, or disk controllers. WHY DYNAMIC POWER MANAGEMENT IS NEEDED The dynamic power management (DPM) technology provides the ability to reduce energy consumption by devices when they are not in active use. In addition to the environmental benefits of reduced energy consumption, power management can improve equipment reliability by reducing wasted heat. The DPM technology improves power conservation capabilities based on open source platforms. It applies to running systems, adjusting power parameters on-the-fly, while ensuring real-time deadlines of running software are met. These deadlines could be either hard real-time systems, which guarantees a deterministic response time to an event so that a late response is considered to be a system failure, or they could be soft real-time systems to indicate that attempts to minimize event response time and does not consider a late response as a system failure.
..... POW ER M A N A G EM E NT BA CK G R O U ND TE C HN OL OG Y What is Dynamic Power Management? What is Dynamic Power Management? 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . W H AT IS DY NA M I C P O W E R M A N AG E M E N T ? Traditional power management for computer systems focused on regulating the power consumption in static modes such as sleep and suspend. These are de-activating states, often requiring a user action to re-activate the system. There are usually significant latencies and overheads for entering and exiting these states, and in desktop and server systems a firmware layer typically supports these modes. Recent advances in processor design techniques have led to the development of systems that support advances in hardware to scale clocking information such as CPU and core bus frequencies as well as core voltages with low latency. It enables dynamically adjusting power management parameters to realize power savings during brief idle periods or execution of tasks with lower performance and power demands. Since CPU power consumption typically decreases with the cube of voltage while frequencies scale linearly with voltage, significant opportunities exist for tuning the power-performance trade-off to the needs of the application. Dynamic power management is basically a set of schemes implemented while programs are running. Many architectures provide the equivalent of a halt instruction that reduces CPU power during idle periods. The operating system and device drivers can also manage power of peripheral devices, for example spinning down disks during periods of inactivity. Highly integrated processors with on-board peripherals often include software-controlled clock management capabilities to reduce power consumption by inactive peripherals and peripheral controllers. The memory subsystem also provides a profitable area for dynamic power management, either through the memory controller implementation or through software-based schemes. In support of these dynamic power management strategies, several processors supported by Mobilinux allow dynamic voltage and frequency scaling of the processor core. DPM targets the Linux operating system and the characteristics of hardware used for embedded Linux.
POWER M A N A G EM E N T B A C K G R OU N D TE C HN O LOG Y What is an Embedded System? 4 What is an Embedded System? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . W H A T IS A N E M B E D DE D S Y S T E M ? Typically, embedded systems perform specific tasks that are stored in the system firmware. While desktop computers and handheld devices are general-purpose computing devices that are capable of running software to perform many different tasks, an embedded system is primarily designed for a specific task, for example a TV controller. In the past, it was easier to distinguish an embedded system from a general-purpose computers than it is today. Clearly, the increase in hardware performance and the lower cost of that hardware has blurred the line between general-purpose computers and embedded systems. Embedded systems usually do not have machine abstractions to insulate the operating system from low-level device and power management activities. In embedded Linux, as in other operating systems that target battery-powered applications, power management activities thereby require specific intervention on the part of the operating system kernel and device drivers. Notice, however, while low-level implementation of dynamic power management is resident in the operating system kernel, power management strategies and policies can and do emanate from middleware and user application code. WHAT IS EMBEDDED LINUX? Using Linux in embedded system designs enables saving innumerable hours in creating codes, developing reliable products, and featuring packed, robust, and quick to market. DYNAMIC POWER MANAGEMENT FOR EMBEDDED SYSTEMS The processors mentioned above are highly integrated system-on-a-chip (SOC) processors designed for embedded applications. The applications of these processors typically do not include a traditional BIOS, therefore control of the dynamic power state of the system must be implemented in the operating system.
..... POW ER M A N A G EM E NT BA CK G R O U ND TE C HN OL OG Y Architectural Summary Architectural Summary 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A R C H I T E C T U R AL S U M M A R Y The low-level implementation of the dynamic power management architecture resides in the kernel of the operating system, whereas the power management strategies come from outside of the system. Notice that DPM is not a self-contained device driver. The low-level implementation of DPM requires enhancements at a few key places in the operating system. A system designer familiar with the characteristics of the embedded system and its special features and requirements needs to define a complete dynamic power management strategy for each application in advance. The strategy is communicated to DPM in two ways: as a predefined set of policies and as an application or policy-set specific policy manager that manages the policies. WHAT IS A DPM POLICY? DPM policies are named data structures. Policies may be defined in such a way that they exert very fine-grained control over the dynamic state of the system. For this reason, policies must be installed into the operating system kernel for efficiency. Policies specify the component and device-state transitions that ensure reliable operations in line with the power management strategy. The structure of DPM policies and the effects of policies on the system are covered in Chapter 3, “What is MontaVista Power Manager?” A major component of the policy mechanism deals with the interaction of device states with policies. WHAT IS A DPM POWER POLICY MANAGER? DPM policy managers are executable programs that activate policies by name. Policy managers implement user-defined and/or application-specific power management strategies. They can execute either as part of the kernel or in userspace (or both) as required by the strategy. Policy managers may be very active, responding in real-time to changes in application power or performance requirements. However, they may be more passive, for example by changing policies on a longer time scale in response to changes in available battery power. In fact, DPM supports strategies that do not require any policy manager at all. Effective strategies for some applications may consist of a single policy installed at system initialization, perhaps modified by critical applications that interact directly with DPM.
POWER M A N A G EM E N T B A C K G R OU N D TE C HN O LOG Y Dynamic Power Management and Mobile Devices 6 Dynamic Power Management and Mobile Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DYNAMIC POWER MANAGEMENT AND MOBILE DEVICES Hand-held device makers highlight battery life and power management as key features to stay competitive in the market. While users perceive results of power management in terms of battery life, it’s really a combination of CPU capabilities, system software, middleware, and policy that lets users enjoy their devices for more time between charges or battery changes. Any portable device owner notices that the device behaves differently when running on battery versus on ac power—the screen dims, the processor clock slows, and the system drifts off to standby or sleep whenever possible after an inactive period. System behaviors such as standby and sleep leverage native CPU capabilities to reduce operational voltage and/or clock frequency to save power. What users need to understand is that in addition to wholesale changes among system-wide states, actual power management can also be incremental and can occur many hundreds of times each second. Any DPM strategy begins with scaling the operating voltage and frequency of the one or more processor cores present in a portable device. Highly integrated processors such as the Intel PXA27x and the Texas Instrument OMAP family offer dynamic scaling of core voltage and frequency. MOBILE DEVICES CONSERVING ENERGY The overriding power management goal in portable systems is to reduce system-wide energy consumption. The current generation of embedded processors are so power-efficient that the processor may no longer be the major energy-consumer in systems that include high- performance memories and large color displays. Therefore, a dynamic power management system that is only concerned with voltage and frequency scaling the processor core may be of limited use. Instead, aggressive power management strategies that encompass the entire system are needed. For example, scaling bus frequencies can drive significant reductions in system-wide energy consumption.
..... POW ER M A N A G EM E NT BA CK G R O U ND TE C HN OL OG Y Dynamic Power Management and Mobile Devices Dynamic Power Management and Mobile Devices 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PLUGABLE POWER MANAGEMENT POLICIES The breakdowns of system-wide energy consumption agree that are the most effective way to manage energy consumption are highly application dependent. Therefore, a dynamic power management architecture needs to be flexible enough to support multiple platforms with differing requirements. Part of this flexibility is the requirement to support plug-able power management policies that allow device manufacturers to specialize policies for their applications and differentiate their products based on their own unique approaches to power management. The requirements for simplicity and flexibility are best served by leaving the workings of the dynamic power management system completely transparent to most tasks. Where this chapter provided background knowledge on the dynamic power management technology, the next chapter introduces the MontaVista Dynamic Power Management feature and provide specifics about it.
POWER M A N A G EM E N T B A C K G R OU N D TE C HN O LOG Y Dynamic Power Management and Mobile Devices 8 Dynamic Power Management and Mobile Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 WHAT IS MOBILINUX ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DYNAMIC POWER MANAGEMENT? The Mobilinux Dynamic Power Management feature provides applications and tools that enable the users to control power policy for power-conscious Linux-based mobile devices. Additionally, it allows rapid modifications to power parameters of these systems, such as their CPU, bus frequencies, and core voltage scaling. This chapter covers the following topics: • “What is Mobilinux?” • “What is Mobilinux Dynamic Power Management?” • “Mobilinux Dynamic Power Management Benefits” • “Mobilinux Dynamic Power Management Features”
W H A T I S M OB I LI NUX DY N A M IC POW ER M A N A G E M EN T ? 10 What is Mobilinux? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . W H AT IS M O B I L I N UX ? Mobilinux is an optimized Linux operating system and development environment, ideally suited for wireless handsets and mobile devices. It is based on a 2.6 kernel and meets the requirements for power management, hard real-time performance, fast start-up, and small footprint. Mobilinux is built to address key areas of development for mobile and wireless devices. MontaVista Mobilinux along with the Intel PXA27x™ and TI OMAP™ processors provides wireless devices with flexible and scalable solutions. Mobilinux enables setting up a power management profile that best meets the requirements of your device by helping you implement it for maximum performance and lowest cost. W H AT IS M O B I L I N UX D Y N A M I C P O W E R M A N AG E M E N T ? Mobilinux Dynamic Power Management (DPM) provides mechanisms to aggressively control power policy for Linux-based mobile devices. Mobilinux DPM feature rapidly scales power parameters such as CPU frequency as the operating system transitions between idling and running tasks as well as when the system switches among tasks with different power requirements. M O BI L I N UX DY N A M I C P O W E R M A N AG E M E N T B E N E F I T S Mobilinux DPM feature provides the following benefits: • Saves on system power by consuming less power during periods of reduced activities. • Increases system efficiency and frees up system and cooling power capacity by providing operating system independent power management. • Provides more power saving options by supporting dynamic power savings modes. • Protects the environment. • Conserves energy through increased efficiency in portable devices.
..... W HA T IS M O B IL INU X DY NA MI C POWE R MA NA G E M EN T ? Mobilinux Dynamic Power Management Features Mobilinux Dynamic Power Management Features 11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . M O BI L I N UX DY N A M I C P O W E R M A N AG E M E N T F E A T U RE S The following is a list of features provided by Mobilinux 4.0 Power Management: • “MontaVista Power Manager” • “DPM Library” • “Hotplug Agents” • “Clock Events Tracking” • “Power Profiler Plugin” • “Timer Interrupt Event Reduction” • “Tick Elimination” • “Power Manager Interface” • “High-level Power Manager Interface” • “Event Handling” • “Suspend and Resume Handling” MONTAVISTA POWER MANAGER The MontaVista Power Manager software provides default operating points and operating policies for each Mobilinux board, allowing DPM to be used out-of-the-box. It implements basic DPM policy management and modifies power settings according to simple heuristics, such as system load. The Power Manager allows for customizing of power parameters and policy heuristics as well as user-defined suspend and resume scripts for userspace actions at suspend and resume time. A plugin is added by creating a shared library that conforms to the Plugin API and by loading the plugin into the Power Manager through using the load command. This enable users to add value by adding better power policy management plugins to further extend the features of the MontaVista Power Manager. See Chapter 3,“What is MontaVista Power Manager?”
W H A T I S M OB I LI NUX DY N A M IC POW ER M A N A G E M EN T ? 12 Mobilinux Dynamic Power Management Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM LIBRARY The DPM library conveniently provides a set of API-based functions that control DPM through the sysfs interface. Using the sysfs interface, the DPM library provides backward compatibility for existing sys-dpm-based applications that perform the same functions. HOTPLUG AGENTS In a variety of situations it may be useful to communicate information on power requirements or state changes from the kernel to a userspace Power Manager. For example, the information may request a system suspend in response to an interrupt received due to a button press, or the information may communicate device status changes that could lead the Power Manager to change system power state. For this reason, DPM provides functions that notify userspace through the Hotplug mechanism, instead of traditional method of notifying userspace policy handlers of changes in devices present (along with their associated chores such as downloading firmware for new devices). Hotplug executes an agent script to perform userspace handling of the power event. CLOCK EVENTS TRACKING The Mobilinux DPM Trace Toolkit Integration feature provides a method that tracks changes in any clock frequency by DPM. The clock events tracking feature provides a way to examine the system operating state transitions that DPM invokes. See Chapter 4, “MontaVista Power Manager Building Blocks.” POWER PROFILER PLUGIN The Power Profiler Plugin is provided along with the Power Manager. This plugin is enables measuring the CPU load and set profiles and DPM policies according to these commands. See Chapter 4, “MontaVista Power Manager Building Blocks.” TICK ELIMINATION The purpose of this feature is to prevent system wake ups for timers that serve no useful purpose while the system is in sleep or idle mode. This enables longer sleeps and thus more power savings.
..... W HA T IS M O B IL INU X DY NA MI C POWE R MA NA G E M EN T ? Mobilinux Dynamic Power Management Features Mobilinux Dynamic Power Management Features 13 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The kernel relies on periodic timer interrupts to allow the kernel keep the current time and date up-to-date, to do accounting, and to see if the software timer service routines should be called. Even when the processor is otherwise idle, these interrupts occur and can cause the processor to be brought out of a power savings mode even though there may not be anything for it to do other than update the time and go back to sleep. HIGH-LEVEL POWER MANAGER INTERFACE Power Manager serves as the preferred DPM interface instead of users directly accessing the lower-level interfaces. Embedded systems usually do not have BIOS and typically do not provide machine abstractions to insulate the operating system from low-level device and power management activities. In operating systems that target battery-powered applications, power management activities thereby require specific intervention on the part of the operating system kernel and device drivers. Notice, however, that while low-level implementation of DPM is resident in the operating system kernel, power management strategies and policies can and do emanate from middleware and user application code. EVENT HANDLING The Power Manager has features that allow power policy to be adjusted in reaction to various system and device power events. See Chapter 9, “What is Mobilinux Dynamic Power Management?.” SUSPEND AND RESUME HANDLING The Power Manager is able to check the requested (or defaulted) sleep operating state against device constraints. If not rejected by the previous methods, these user-defined scripts are executed (if present) before and after the actual system suspend, respectively. Power managed device drivers continue to receive notifications of system suspend and resume states. During an operating system suspend state, the microprocessor will no longer be active. In theory Power Manager puts all devices into a device power state that is appropriate to an operating state suspend state. However, it is possible that a suspend system power state configuration or an application device power requirement not be appropriate for a particular device.
W H A T I S M OB I LI NUX DY N A M IC POW ER M A N A G E M EN T ? 14 Mobilinux Dynamic Power Management Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 WHAT IS ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MONTAVISTA POWER MANAGER? The MontaVista Power Manager software is the interface to the Mobilinux Dynamic Power Management (DPM). It provides default operating points and operating policies for each Mobilinux board, allowing DPM to be used out-of-the-box. The following topics are covered in this chapter: • “What is MontaVista Power Manager?.” • “MontaVista Power Manager Features.” • “Overview of MontaVista Power Manager Tools.”
W H A T I S M O N T A VI S T A POWE R MA NA G E R? What is MontaVista Power Manager? 16 What is MontaVista Power Manager? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . W H AT IS M O N T A V I S T A P O W E R M A NA G E R ? The MontaVista Power Manager implements basic DPM policy management and modifies power settings according to simple heuristics, such as system load. It allows for customizing of power parameters and policy heuristics as well as user-defined suspend and resume scripts for userspace actions at suspend and resume time. MontaVista Power Manager features can be further extended to meet the needs of a particular system by adding by adding custom power policy management plugins. When a system sleep or suspend mode is required, the power manager requests the appropriate mode after executing custom actions necessary to prepare for the suspend, according to the needs of the particular system. M O NT AV IS T A P O W E R M A NA G E R F E A T U RE S The MontaVista Power Manager features the following: • “DPM Interface” • “Integrated Components” • “Default Operating Points” • “User-Defined Power Parameters” • “Default Power Policies” See Chapter 4, “MontaVista Power Manager Building Blocks” DPM INTERFACE The new interface for Power Manager is a sysfs interface. It provides an interface that no longer requires that DPM-aware applications be compiled with board-specific kernel header files. Knowledge of kernel implementation details are defined in those header files, such as array indices of power parameters, number of power parameters, operating state numeric identifiers, and so on.
..... W HA T I S M O N TA V I S T A POWE R M A N A G ER ? MontaVista Power Manager Features MontaVista Power Manager Features 17 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INTEGRATED COMPONENTS Power Manager integrates the various components involved in a power management system, such as kernel drivers and power-aware application, into a framework that users can use for their products. DEFAULT OPERATING POINTS Power Manager provides default operating points and policies for each Mobilinux supported board, allowing DPM to be used out-of-the-box. DPM runs the system at a certain operating point at any given time, chosen from a set of possible operating points according to rules set by the system designer. USER-DEFINED POWER PARAMETERS The DPM implementation for a platform is based on information from the silicon or board vendor describing the available power parameters and operating points that have been validated to operate successfully on the platform. MontaVista can then support DPM software modification of these power parameters and can support DPM running at the validated operating points. Power Manager allows for customer extensions to power parameters and policy switching heuristics, as well as customer-written suspend and resume scripts for userspace actions at suspend and resume time. DEFAULT POWER POLICIES Power management policies or schemes are used to make decisions on the state of operation of electronic systems such as portable devices. Dynamic power management schemes or policies can be used to control the power consumption levels of electronic systems, by setting their components in different states, where each is characterized by a performance level and a power consumption. The power consumption can be formulated as an optimization problem called policy optimization. It enables basic DPM policy management, switching power settings according to simple heuristics, for example, switching to a higher performance level when system load increases.
W H A T I S M O N T A VI S T A POWE R MA NA G E R? Overview of MontaVista Power Manager Tools 18 Overview of MontaVista Power Manager Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OVERVIEW OF MONTAVISTA POWER MANAGER TOOLS The following tools allow for modifications to Power Manager. COMMAND-LINE Power Manager reads commands from any source, including the following: • Configuration file selected by the startup script by default. • Another dpmmgr invoked by the command-line parameters. • FIFO /tmp/dpmmgr.fifo at runtime to receive commands from applications and kernel event messages, such as from power hotplug scripts. • Plugins through plugin API function calls. The command line may consist of several dpmmgr commands that are separated by semicolons ";". A number of commands refer to devices by using the syntax bus/device, where bus is a string comprised of a sysfs bus name, and devices is a sysfs device name. For example, platform/omap1710 refers to the device named omap1710 on the platform bus. See Chapter 11, “Power Manager Commands.” The Power Manager enables the users to add value by adding plugins that extend the features of the base policy manager. The dpm-profiler plugin can measure the CPU load and set the profiles and DPM policies according to these commands. See Chapter 13, “Power Manager Profiler Plugin.” PLUGIN APIS Plugins can be added by creating a shared library that conforms to the Plugin APIs and by loading the plugin into the policy manager using the load command. The Power Manager Plugin API includes callbacks or functions that are called by dpmmgr into the plugin. See Chapter 12, “Plugin Commands and APIs.”
19 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 MONTAVISTA POWER MANAGER ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BUILDING BLOCKS Mobilinux Dynamic Power Manager (DPM) responds with low latency to the system workload and environment by dynamically adjusting system operating parameters to balance system performance and power consumption, without requiring user interactions. The key to design a power efficient DPM is to implement a power manager policy that meets the needs of your system. This requires understanding your overall power management goals, the CPU execution states of your system, and the available power want DPM to manage. MontaVista Power Manger allows you to design a power policy that is specific to your development platform by building the following components: • “Operating Points” • “Operating Classes” • “Operating States” • “DPM Power Policy” Note: This chapter explains the concepts of each of these building blocks. See Chapter 8, “Designing Device Interactions with DPM,” for specific instructions for building these blocks.
M ON T A VI S TA POWER M A N A G ER B U I LD IN G B L OC K S Operating Points 20 Operating Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . O P E RA T I N G P O I N T S A system executes at a particular operating point at any given point in time. The operating point, in turn, can be described by such parameters as the core voltage, CPU and bus frequencies, and the states of peripheral devices. A dynamic power management system is defined as a set of rules and procedures that move the system from one operating point to another as events occur. Selecting appropriate operating points has a critical impact on system energy consumption. Additionally, modern voltage and frequency scalable systems support multiple operating points. Operating points are the lowest-level objects in the DPM system hierarchy. An operating point object encapsulates the minimal set of inter-dependent, physical, and discrete parameters that define a specific system performance level along with its associated energy cost. A good example of inter-dependency is the relationship between voltage and frequency of a CPU core. The core voltage limits the maximum operating frequency of a voltage- scalable CPU, while the frequency of the processor cannot be considered without also considering the voltage. Operating points, by nature, are processor- and system-dependent. The system designer is responsible for defining as many operating points as are necessary to satisfy the power management need of the application, such as core voltage levels, CPU and bus frequencies, memory timing parameters, and other clocking related data. Note: For a complete list of the default operating points provided for your board see the chapter specific to your supported platform in this manual. OPERATING POINTS PARAMETERS For a list of power parameters used by operating points see the DPM header files. Any value associated with each parameter in these files is an integer. You can modify or adjust each parameter for your specific platform; however, you must make your modifications according to the rules specified by the manufacturer of your board.
..... M ON T A VI S TA POWER M A N A G E R B U I LD IN G B L OC K S Operating Classes Operating Classes 21 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OPERATING POINTS EXAMPLES An operating point is a specific set of values of the hardware operating parameters. Each operating point is labeled with a name. The following table provides an example of four operating points for a theoretical system: O P E RA T I N G CL A S S E S An operating class is a set of operating points. Operating point classes allow DPM to automatically choose an appropriate operating point from among a list of available operating points, according to the constraints set by drivers. Constraints describe the required relationships between the hardware operating parameters. For example, for a network adapter to function properly, it may require that the frequency of the IO bus, to which it is attached, be greater than 10 Mhz. To learn more about device constraints, see Chapter 5, “DPM Device Driver Interfaces.” An example of an operating class may be a class that offers a choice of a lower power operating point or a higher power operating point, allowing the lower power operating point to be set if no drivers have asserted a constraint disallowing the lower power operating point. A power policy can map an operating state to a single operating point, or it can map an operating state to a class that contain multiple operating points. When switching operating points to match a change in operating state, DPM will choose the first operating point in the class that is allowed under the current device constraints. For example, the following shows how to create an operating class using the sysfs interface: create class-name op-name op-name... > /sys/dpm/class/control The variable class-name must be unique among other classes and operating points. Operating Point Voltage Processor Clock Processor Clock Bus I/O Bus Clock ................................... ......................fast_cpu 5000 mV 400 Mhz 200 Mhz 100 Mhz slow_cpu 5000 mV 100 Mhz 50 Mhz 100 Mhz med_cpu 5000 mV 50 Mhz 25 Mhz 100 Mhz Sleep 0 mV 0 Mhz 0 Mhz 0 Mhz ................................... ......................
M ON T A VI S TA POWER M A N A G ER B U I LD IN G B L OC K S Operating States 22 Operating States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Each op-name is the name of an operating point within the class. The order of names is significant. When choosing an operating point from the class, DPM will evaluate each operating point in left-to-right order, choosing the first operating point that meets the current constraints. The variable class-name is specified in a policy to map an operating state to the class. O P E RA T I N G S T A T E S Operating states are CPU execution states that are triggered by the scheduler when performing a context switch, other kernel-specific actions (such as entering the idle loop), or an explicit command using a DPM API. WHAT IS AN OPERATING STATE? The concept of the operating state was first introduced by observing that significant system- wide energy savings can be achieved by reducing CPU and bus frequencies and core voltage while the system is in idle state. Therefore a mechanism was required to specify a different operating point during the time that programs are executing, versus the times that the system is idle. This led to a distinction between an active state and an idle state, each with a potentially different operating point. The transition from the active state operating point to an idle state operating point and back is smoothly and efficiently managed by the DPM implementation in the operating system. OPERATING STATES ARCHITECTURE The concept of an operating state applies to task-specific operating points for power-aware tasks. This requires multiple task-specific active states or task states. The DPM architecture allows for any number of task states. The default task state is expected to be used by the large majority of tasks, analogous to the way that most tasks now use the default scheduling policy of the operating system. Tasks with special requirements may specify how to run in different task states, each of which may be associated with a different operating point. Note: Tasks never explicitly specify an operating point. Instead, the operating point is implied by the task state and the current policy.
..... M ON T A VI S TA POWER M A N A G E R B U I LD IN G B L OC K S Operating States Operating States 23 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operating states also appear in the DPM policy architecture. Conceptually, a DPM policy simply associates an operating point with each of the system operating states. Changing to a new DPM policy simply changes the association. The operating state is an abstraction that software uses to request a specific level of system performance. The system’s current operating state is set from each process’ operating state when the process is active. The default operating state of each process is inherited from its parent. A process’ operating state can be changed using a DPM API. The board-specific implementation portion of DPM can alter the system’s current operating state while kernel code is executing. For example, the kernel idle loop code might set the system’s current operating state to idle while there is no task that is ready to be executed. OPERATING STATES TYPES In general, DPM defines the following three basic operating states for kernel use: • DPM_SLEEP_STATE • DPM_IDLE_STATE • DPM_DPM_TASK_STATE SL E EP The sleep operating state instructs DPM to suspend the system to a low-power sleep or standby state. When DPM enters the sleep operating state, the following actions take place: 1 The device suspend() function is invoked for each device, saving device state for later resume, and placing the device in a low-power state. 2 Other board-specific actions, such as to place SDRAM in auto refresh mode, may occur. 3 The CPU in placed in a low-power mode selected by the operating point parameters. When the system is resumed due to receipt of a wake-up event, the following actions take place:
M ON T A VI S TA POWER M A N A G ER B U I LD IN G B L OC K S Operating States 24 Operating States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 The CPU comes out of sleep/standby mode and resumes execution. 2 Other board-specific actions may occur, such as to take SDRAM out of auto refresh mode. 3 The operating state changes to DPM_TASK_STATE. 4 The device resume() function is invoked for each device in order to restore state and power up the device. ID LE The idle operating state is entered whenever the Linux scheduler executes the idle loop. The idle loop typically executes a wait-for-interrupt instruction that will temporarily halt processor execution cause kernel execution to resume upon receipt of the next interrupt. There may also be other actions performed by the idle loop for your board, such as to place SDRAM into self-refresh state. The DPM operating point selected for the idle operating state may modify additional power parameters for reduced power consumption during idle periods, such as to reduce the frequency of clocks. TA SK The task state function is the default operating state for all processes. DPM by default supports nine task states. The following list displays the names of all of the default task states: • task-4 • task-3 • task-2 • task-1 • task • task+1 • task+2 • task+3 • task+4 Applications can either be assigned a task state by the policy manager or can set their own task state directly. In both cases use the DPM API calls, see Chapter 12, “Plugin Commands and APIs.”
..... M ON T A VI S TA POWER M A N A G E R B U I LD IN G B L OC K S DPM Power Policy DPM Power Policy 25 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DP M P O W E R P O L I C Y The DPM Power Policy is the highest-level abstraction of the DPM architecture. A DPM Power Policy is a named data structure, which is installed into the DPM implementation in the operating system and is managed by the Power Manager that resides outside of the operating system. Once a DPM system is initialized and activated, the system will always be executing under a particular DPM policy. WHAT IS A DPM POWER POLICY? A policy is a mapping of an operating state or class invoked for each operating state. For example, a low-battery-strength policy might map all operating states to low power operating points. Or, a high-battery-strength policy might map a task operating state used by interactive processes to a high power operating point, a task operating state used by background processes to a medium power operating point, and an operating state used by the kernel idle loop to a low power and low wake up latency operating point. POWER POLICY ARCHITECTURE The highest-level abstraction of the DPM architecture is the Power Policy, which maps each operating state to an operating point or a harmonized class of operating point. A power management strategy specifies at least one policy and may specify as many different policies as are necessary for different scenarios. The policy in effect at any given point in time controls the operating point of the system in every operating state. The DPM architecture does not require the presence of any operating states other than a single task state common to all platforms. The number of task states may vary from platform to platform, however on all platforms the task states are only given meaning by the policies and Power Manager. If multiple policies are needed, then Power Manager needs to coordinate the activation of different policies at different times. Power Manager may collect information from the operating system, user preferences, running programs, configuration files and physical devices to make its policy decisions. The location of the policy manager (kernel space or userspace), the types of information required, and all of the actions taken in response to that information are not specified. The intention of this architecture is simply to define a consistent way for policy developers to express policies that are controlled by the policy manager and implemented by DPM.
M ON T A VI S TA POWER M A N A G ER B U I LD IN G B L OC K S DPM Power Policy 26 DPM Power Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM DEVICE DRIVER INTERFACES Ideally, a power management system would be entirely transparent to as many levels of the software stack as possible. Developers experienced in building handheld devices believe that some degree of explicit participation is required across the system, including the kernel and driver interfaces. In the DPM architecture for Linux, the DPM subsystem within the kernel maintains the system’s power state and ties together the various power-managed elements of a DPM system. DPM serves as a service provider to drivers, middleware, and applications. The following topics are covered in this chapter: • “DPM Device Driver Background” • “DPM Device Constraints Background” • “Forced Operating Points” • “DPM Classes” • “DPM Driver Scale Callbacks” • “Driver Model and Device Suspend/Resume”
DP M D EV I C E DR IVE R IN T ER F AC ES DPM Device Driver Background 28 DPM Device Driver Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DP M D E V I CE DR IVER B A CK GR OU N D The automatic selection of operating points as devices change state is a central feature of DPM. Embedded systems may not have a BIOS or machine abstraction layer to insulate the operating system from low-level device and power management. Therefore, this task falls to the operating system and its device drivers. As the complexity of embedded systems increases and the interrelationships between clock sources and power management modes become more complex, this becomes an increasingly difficult task. Under the DPM abstraction, the system designer needs to design the power management system by pre-selecting sets of meaningful operating points for the application and organizing these operating points within power management policies that are suitable for the application. DP M D E V I CE CO N S T R AI N T S B A C K G RO UN D Device constraints allow drivers to control entry to DPM operating points. Constraints restrict entry to operating points that are incompatible with correct operation of devices. The appropriate device constraints to use, and the consequences of violating these constraints, is determined by the characteristics of the hardware platform. Constraints may also restrict DPM operations in ways considered useful by the system designer, such as allowing DPM to transition to a low-power idle mode only if a set of devices are not in use, regardless of whether or not the underlying hardware is capable of operating the devices in that mode. HOW DEVICE CONSTRAINTS WORK The manner in which DPM interprets constraints depends on the way the current DPM policy is defined. DPM policies can map a system operating state to a specific DPM operating point or to a DPM class of operating points. Devices specify their requirements as sets of constraints associated with particular device states. For example, an LCD controller might specify a pixel clock in the range of 16 to 25 MHz while active and no constraint while inactive. When devices change state, and their requirements for system resources change, these requirements are communicated to DPM. Simple rules are defined to invalidate inappropriate operating points and to automatically
..... DP M D EV I C E D R IVE R IN T ER F A CE S Forced Operating Points Forced Operating Points 29 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . select one of possibly several valid operating points from the operating classes under the new constraints. This mechanism frees the policy manager to focus on high-level management, while ensuring that the system always operates at the best operating point, as defined by the system designer, consistent with the current policy and device states. This mechanism also supports systems that include simple policy managers, or that do not implement any run-time DPM policy management at all. The system designer may be able to describe a suitable dynamic power management strategy using only a single DPM policy, based on operating point operating classes that anticipate the significant states of peripheral devices with regard to power management. To design DPM operating classes, see Chapter 8, “Designing Device Interactions with DPM.” DEVICE CONSTRAINTS FEATURES DPM checks device constraints and either chooses an operating point from an operating class that does not violate the constraints, or it blocks transition to any new operating point if there is no operating point that does not violates those constraints. The following are some of the features of the constraints interfaces: • Writing a constraint with the same power parameter ID as an existing constraint overwrites the previous constraint with the new settings. • Power parameter with the minimum or maximum value -1 means no constraint. • Existing constraints can be removed using this syntax. • Reading the device sysfs constraints attribute returns more information, including asserted=yes/no status, as well as the number of times an operating point was rejected due to this constraint. F O R CE D O P E R A T I N G P O I N T S A forced operating point may be set even if device constraints would normally disallow it. Devices with constraints incompatible with the operating point are first suspended before the operating point is set.
DP M D EV I C E DR IVE R IN T ER F AC ES DPM Classes 30 DPM Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . This feature is implemented as a per-operating point attribute, named force. The force attribute is only supported for sleep operating points, that is, operating points that place the system into a low-power sleep, suspend, or standby state. Force flag handling is implemented by Power Manager. If you are implementing your own power policy manager and want to have similar functionality, then you may implement the code to check the force attribute and power down the affected devices in your power policy manager. D P M C L A S S E S DPM classes are fully supported in Mobilinux and may contain more than one operating point. DPM classes allow DPM to automatically choose an appropriate operating point from among a choice of several operating points, according to the constraints set by drivers. For example, a class may offer a choice of a lower power operating point or a higher power operating point, allowing the lower power operating point to be set if no drivers have asserted a constraint disallowing the lower power operating point. In Mobilinux, a DPM policy can map an operating state to a single operating point, or it can map an operating state to a class containing multiple operating points. D P M D R I V E R S C A LE C A L L B A C K S DPM-enabled device drivers are more stateful than default drivers. They are driven through various states by external events and through callbacks from the kernel DPM subsystem to reflect operational policies. Mobilinux DPM has the capability to call drivers when scaling clock frequencies. This enables drivers to react to any necessary change on all platforms. This is done using the scale driver callback.
..... DP M D EV I C E D R IVE R IN T ER F A CE S Driver Model and Device Suspend/Resume Driver Model and Device Suspend/Resume 31 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DR I V E R M O D E L A ND D E V I C E S U S P E N D /R E S U M E The device suspend and resume features associated with DPM are a standard part of the 2.6 kernel on which Mobilinux is based. The 2.6 code typically registers such devices as platform devices on the built-in platform bus. This avoids the need to issue separate LDM registration or deregistration calls for each platform that supports a particular driver. The platform bus uses the following sequence: suspend: 1. SUSPEND_DISABLE; 2. SUSPEND_SAVE_STATE; 3. SUSPEND_POWER_DOWN resume: 1. RESUME_POWER_ON; 2. RESUME_RESTORE_STATE; 3. RESUME_ENABLE Depending on the particulars of the platform, the suspend mode requested, and the device driver, all 3 levels may or may not be useful, and some may be ignored if not useful.
DP M D EV I C E DR IVE R IN T ER F AC ES Driver Model and Device Suspend/Resume 32 Driver Model and Device Suspend/Resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
33 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 MONTAVISTA POWER MANAGER ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OUT-OF-THE-BOX MontaVista Power Manager provides configuration files that are specific to each supported development platform board. This chapter provides lists of default operating points and policies as well as configurations for each supported board, as follows: • “Using Power Manager Out-of-the-Box” • “Installing Configuration File” • “Exiting From your Power Manager” • “Power Manager Default Configuration Files”
M ON T A VI S TA POWER M A N A G ER O U T -OF -T H E-B OX Using Power Manager Out-of-the-Box 34 Using Power Manager Out-of-the-Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . US I NG P O W E R M A N AG E R O U T - O F -T H E - BO X MontaVista provides system startup scripts to start and stop the MontaVista Power Manager, dpmmgr. These scripts pass the board-specific configuration file at /lib/modules/$(uname -r)/dpmmgr.conf to dpmmgr, where $(uname -r) is the release number of the Linux kernel and Mobilinux product. The following shows the syntax to dpmmgr: dpmmgr [options] [command-line] where [options] are, -f <file> set configuration file -v verbose debugging info -l enable logging -d run as a daemon Note: -l saves information in /var/log/dpmmgr.log file. [command-line] is a command line to send to the Power Manager, which must have been previously started. dpmmgr sends the command-line to the Power Manager and exits, providing a convenient way to execute dpmmgr commands on-the-fly. You may want to setup both a high-power and low-power policy specific to your board, assuming reasonable operating points for higher-power and lower-power that are still running are known for the board. You may also choose an operating point for the idle state if an appropriate low-power operating point with low latency to enter and exit is known for the board. As part of the installation of MontaVista Power Manager, the dpm-profiler will also be installed by default. See Chapter 13, “Plugin Commands and APIs.”
..... M ON T A VI S TA POWER M A N A G ER O U T- OF -T HE -B OX Installing Configuration File Installing Configuration File 35 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I N S T A L LI N G CO N F I G U R A T I O N F I LE During the installation of Mobilinux, the dpmmgr.conf file specific to your board will be installed as well. 1 After installing your LSP, you may you may start MontaVista Power Manager as shown below: /var/log/dpmmgr -v “status” 2 Check the output in dpmmgr.log file if logging is enabled to see any messages logged during Power Manager startup. /etc/init.d/dpmmgr.log start Initialized from configuration file: /lib/modules/2.6.10_mobilinux402-mainstone_pxa27x/dpmmgr.conf Poll interval: 3 seconds. Plugins loaded: dpm-profiler load-scale: active profile is "battery-hi". load-scale: power metric is 0 => "set policy lo-power". E X I T I NG F RO M Y O UR P O W E R M A N AG E R To exist from your MontaVista Power Manager enter the following command: dpmmgr -v "exit" dpmmgr shut down 04 Jan 1970 05:34
M ON T A VI S TA POWER M A N A G ER O U T -OF -T H E-B OX Power Manager Default Configuration Files 36 Power Manager Default Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P O W E R M A NA G E R DE F AU L T C O N FI G U R AT IO N F I L E S This section provides the default configuration files for each one of the supported development platform provided by MontaVista. Note: Check the MontaVista Zone for the latest changes to the default configuration files. TI-OMAP1710 BOARD CONFIGURATION The following is the MontaVista Power Manager configuration for the TI-OMAP1710 H3 development platform board. Note: Please refer to the TI-supplied documentation for your board and processor model to verify the operating points supported on your hardware. load /usr/lib/dpm-profiler.so Specifies operating points to run the CPU at 192, 168, 84, and 60 MHz, respectively. op 192dpll-mult=16 dpll-div=1 arm-div=1 tc-div=2 op 168dpll-mult=14 dpll-div=1 arm-div=1 tc-div=2 op 84dpll-mult=14 dpll-div=1 arm-div=2 tc-div=2 op 60dpll-mult=5 dpll-div=1 arm-div=1 tc-div=1 Specifies operating points to place the 168 and 60 MHz CPU system into Sleep mode, respectively. op sleep-168 dpll-mult=14 dpll-div=1 arm-div=0 op sleep-60 dpll-mult=1 dpll-div=2 arm-div=0 tc-div=2 Defines hi-power policies for the above system. policy hi-power idle, idle-task,task,task+1,task+2,task+3,task+4=192 policy hi-power task-1,task-2,task-3,task-4=168 sleep=sleep-168 Defines low-power policies for the above system. policy lo-power idle, idle-task, task, task-1,task-2,task-3,task-4=60 policy lo-power task+1,task+2,task+3,task+4=84 sleep=sleep-60 Configuration plugin to increase the power by 50 when CPU at 50% utilization. tell dpm-profiler cpu 50% +50 Configuration plugin to specify battery-hi profile to lo-power or hi-power policy depending on the given value of 0 or 50, respectively.
..... M ON T A VI S TA POWER M A N A G ER O U T- OF -T HE -B OX Power Manager Default Configuration Files Power Manager Default Configuration Files 37 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tell dpm-profiler profile battery-hi at 0 set policy lo-power tell dpm-profiler profile battery-hi at 50 set policy hi-power Configuration plugin to specify battery-low profile to lo-power or hi- power policy depending on the given value of 0 or 90, respectively. tell dpm-profiler profile battery-lo at 0 set policy lo-power tell dpm-profiler profile battery-lo at 90 set policy hi-power Configuration plugin to activate the battery-hi profile which will remain in effect until it is overridden by another set profile command. tell dpm-profiler set profile battery-hi Command to report a status summary to stdout. status INTEL PXA27X MAINSTONE BOARD CONFIGURATION The following is the MontaVista Power Manager configuration for the Intel PXA27x Mainstone II development platform. Note: Please refer to the Intel-supplied documentation for your board and processor model to verify the operating points supported on your hardware. load /usr/lib/dpm-profiler.so Specifies operating points to run the CPU at 104, 208, and 312 MHz. op 104mhz v=900 l=8 n=2 b=1 half_turbo=0 cccra=1 cpll-on=1 ppll-on=1 sleep_mode=0 op 208mhz v=1050 l=16 n=2 b=1 half_turbo=0 cccra=0 cpll-on=1 ppll-on=1 sleep_mode=0 op 312mhz v=1250 l=16 n=3 b=1 half_turbo=0 cccra=0 cpll-on=1 ppll-on=1 sleep_mode=0 Specifies operating points to put the system into Sleep, Deep Sleep, and Standby mode, respectively: # Sleep Mode op sleep v=1500 l=0 n=0 b=0 half_turbo=-1 cccra=0 cpll-on=0 ppll-on=0 sleep_mode=3 # Deep Sleep Mode op dsleep v=1500 l=0 n=0 b=0 half_turbo=-1 cccra=0 cpll-on=0 ppll-on=0 sleep_mode=7
M ON T A VI S TA POWER M A N A G ER O U T -OF -T H E-B OX Power Manager Default Configuration Files 38 Power Manager Default Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . # Standby Mode op stndby v=1500 l=0 n=0 b=0 half_turbo=-1 cccra=0 cpll-on=0 ppll-on=0 sleep_mode=2 Specifies operating points to put the system into the Sleep mode, where the second statement enables the Peripheral PLL. # 13m op 13m v=1500 l=1 n=2 b=0 half_turbo=0 cccra=0 cpll-on=0 ppll-on=0 sleep_mode=-1 # 13mext op 13mext v=1500 l=1 n=2 b=0 half_turbo=0 cccra=0 cpll-on=0 ppll-on=1 sleep_mode=-1 Specifies operating points to run the CPU at 520, 416, 312, and 208 MHz, respectively. The operating points specified for 520mhz and 416mhz may fail on some B0 hardware: op 520mhz v=1450 l=16 n=5 b=1 half_turbo=0 cccra=1 cpll-on=1 ppll-on=1 sleep_mode=0 op 416mhz v=1350 l=16 n=4 b=1 half_turbo=0 cccra=1 cpll-on=1 ppll-on=1 sleep_mode=0 op 312mhz_2 v=1250 l=16 n=3 b=1 half_turbo=0 cccra=1 cpll-on=1 ppll-on=1 sleep_mode=0 op 208mhz_2 v=1150 l=16 n=2 b=1 half_turbo=0 cccra=1 cpll-on=1 ppll-on=1 sleep_mode=0 Defines hi-power policies for the above system. policy hi-power idle, idle-task,task,task+1,task+2,task+3, task+4=312mhz policy hi-power task-1,task-2,task-3,task-4=208mhz sleep=sleep Defines lo-power policies for the above system. policy lo-power idle, idle-task, task, task-1, task-2,task-3,task- 4=104mhz policy lo-power task+1,task+2,task+3,task+4=208mhz sleep=dsleep Configuration plugin to increase the power by 50 when CPU at 50% utilization. tell dpm-profiler cpu 50% +50
..... M ON T A VI S TA POWER M A N A G ER O U T- OF -T HE -B OX Power Manager Default Configuration Files Power Manager Default Configuration Files 39 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration plugin to increase the power by 90 when CPU at 90% utilization. tell dpm-profiler cpu 90% +90 Configuration plugin to activate the battery-hi profile, which will remain in effect until it is overridden by another set profile command. tell dpm-profiler profile battery-hi at 0 set policy lo-power tell dpm-profiler profile battery-hi at 50 set policy hi-power Configuration plugin to activate the battery-lo profile, which will remain in effect until it is overridden by another set profile command. tell dpm-profiler profile battery-lo at 0 set policy lo-power tell dpm-profiler profile battery-lo at 90 set policy hi-power Configuration plugin to activate the battery-hi profile which will remain in effect until it is overridden by another set profile command. tell dpm-profiler set profile battery-hi Command to report a status summary to stdout. status
M ON T A VI S TA POWER M A N A G ER O U T -OF -T H E-B OX Power Manager Default Configuration Files 40 Power Manager Default Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
41 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 DESIGNING YOUR ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . POWER MANAGER BUILDING BLOCKS Chapter 4, “MontaVista Power Manager Building Blocks,” explained that MontaVista Power Manger allows you design a power policy that is specific to your development platform by building its components: operating points, classes, policies, and states. This chapter explains how to build these blocks. This chapter covers the following chapters: • “Studying Your Hardware’s Power Management Characteristics” • “Guidelines for Setting up DPM Operating Points” • “Designing High-Level Power Management Software Architecture” • “Designing DPM Suspend/Resume Devices” • “Designing DPM Driver Scale Callbacks” • “Designing Power-Related Events” • “Designing Power Policies” • “Designing Programmable Sleep/Wakeup Sources” • “Designing DPM Task States” • “Designing Sleep/Standby Behavior”
DE SIG NI N G YO UR POWER M A N A GER BUIL DI N G B LO CK S 42 Studying Your Hardware’s Power Management Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . S T U D Y I N G Y O U R H A R D W AR E ’ S P O W E R M A N AG E M E N T C H AR A C T E R I S T I CS Before designing your MontaVista Power Manager building blocks, first consult your silicon or board vendor technical reference manuals, errata, application notes on power management for the following information: • Validated or supported operating points. • Power consumption of hardware components running at different operating points. • Latencies associated with entering different operating points. • Clocking dependencies and other information on device dependencies on power states. CONFIGURING YOUR BOARD By default, dpmmgr will be preconfigured with a selection of operating points expected to function properly on the evaluation supported board supported by your Mobilinux LSP. Comments in the dpmmgr configuration file may indicate known issues with certain operating points on particular hardware revisions. DEVICE POWER CONSTRAINTS Mobilinux Dynamic Power Management for your board is typically preconfigured with device power constraints in the drivers for devices that have dependencies on power states, preventing DPM from setting runtime operating points incompatible with active devices. See Chapter 8, “Designing Your Power Manager Building Blocks,” for information about your board and how to set operating points through DPM software interfaces and other power management programming information.
..... D ES I G N IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Guidelines for Setting up DPM Operating Points Guidelines for Setting up DPM Operating Points 43 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GU I D E L I NE S F O R S E T T I N G U P D P M O P E RA T I N G P O I N T S Software system designers generally like to have a range of power levels available through the supported operating points available for the platform. This includes at least one relatively low-performance low-power point, one midrange point, and a full-performance high-power state. They may also be interested in measured power consumption levels by core system components at various operating points to better understand the power savings that may be expected to result from different power policies. • What are the tunable power parameters of the hardware, such as core voltage, CPU speed, etc.? • What collections of values for power parameters have been validated to function correctly in the hardware? That is, what operating points are supported by the hardware vendor? In many cases, sets of discrete values of power parameters are appropriate, although ranges of values may also be validated. • What steps are necessary to set a new operating point? When switching from one operating point to another, is it necessary to delay while PLLs relock or clocks or voltages settle, etc.? Is a significant latency involved so that it may not be appropriate to switch between the two operating points potentially hundreds of times a second? Note that DPM may switch operating points at every entry into the kernel scheduler, such as switch to executing a new process or to enter the system idle loop when no task is ready to run. DPM may therefore potentially request operating point changes more frequently than originally expected. • Are any of the operating points incompatible with device operation? Does the operating point stop or slow down a clock that is needed for correct operation of any devices? DPM provides facilities to coordinate these kinds of device impacts, for example, to block setting an operating point that would interfere with correct operation of an active device, or to forcibly shut down conflicting devices. • Does a device need to be reconfigure to match a change in system operating point? For example, does any device that sources a changing clock need to change divisors etc. to function correctly after the change? DPM offers a method of calling into drivers when operating points are changed to reconfigure such devices. • Does the system have specialized power management features that also set system power levels and may need coordination with or management by DPM?
DE SIG NI N G YO UR POWER M A N A GER BUIL DI N G B LO CK S 44 Designing High-Level Power Management Software Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DE S I G NI N G HI G H -L E V E L P O W E R M AN A GE M E NT S O F T W AR E A R CH I T E CT UR E It is common to implement the MontaVista Power Manager software authority on making decisions that are based on a power management policy. This authority might, for example, be responsible for • Activating different DPM policies based on changes in system state. • Powering up and down devices as needed to place the system in appropriate states to meet power management goals. • Receiving notifications of power-related events from other portions of the system and making power policy decisions based on that information. DESIGNING A POWER POLICY WITH MONTAVISTA POWER MANAGER The MontaVista Power Manager, dpmmgr, provides the basis for such a power policy control application. It implements a number of commonly-needed power control operations and serves as a communication point for power-related event notifications. dpmmgr may be customized for your system's requirements through configuration files and plugin modules. Alternatively, you may develop your own Power Manager from scratch, configuring and controlling DPM by using the APIs documented in Chapter 12, “Plugin Commands and APIs.” DE S I G NI N G DP M S U S P E N D /R E S U M E D E V I CE S The MontaVista Power Manager can suspend and resume power to a device by writing to the sysfs power/state file for that particular device. Writing to the power/state file causes the driver suspend or resume function to be called, powering down or up the associated device. For example, the following command tells the LCD on any platform to suspend to state 3, which is a common number for the default low-power state supported by drivers: #echo -n 3 > /sys/devices/platform/<name>/power/state Where <name> is the name given by driver
..... D ES I G N IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Designing DPM Driver Scale Callbacks Designing DPM Driver Scale Callbacks 45 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . If you are writing your own drivers with suspend/resume callbacks, the exact calling sequence may vary depending on the kind of bus associated with the device. Many embedded devices are registered on the platform bus, which passes a level parameter to the callbacks. The levels are shown below: DE VIC E SU SP EN D 1. SUSPEND_DISABLE; 2. SUSPEND_SAVE_STATE; 3. SUSPEND_POWER_DOWN DE VIC E RE SU ME 1. RESUME_POWER_ON; 2. RESUME_RESTORE_STATE; 3. RESUME_ENABLE Depending on the specifics of the platform, the suspend mode requested and the device or driver, all three levels may or may not be useful and some may be ignored if not useful. Many drivers perform actions only at levels SUSPEND_DISABLE and RESUME_ENABLE. SPECIFYING POWER STATE VALUES Linux uses integer values from the ACPI standard to indicate device power states. Use value 0 to indicate full-on and a non-zero value to indicate lower-power state. The value 3 is a common default choice for device low power state. See Chapter 9, “Implementing Your Power Manager Building Blocks,” for how to use Power Manager commands to suspend and resume a system as well as how to suspend devices. DE S I G NI N G DP M D R I V E R S C A LE CA L L BA C K S DPM-enabled device drivers are more stateful than default drivers. They are driven through various states by external events and through callbacks from the kernel DPM subsystem to reflect operational policies. Mobilinux DPM has the capability to call drivers when scaling clock frequencies. This enables drivers to react to any necessary change on all platforms. This is done through the scale driver callback.
DE SIG NI N G YO UR POWER M A N A GER BUIL DI N G B LO CK S 46 Designing Power-Related Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DE S I G NI N G P O W E R- RE L AT E D E V E NT S In order to make decisions on power state, you need to determine the power-related information that is to be communicated to the Power Manager from kernel drivers and applications. For example: • A device has been inactive for a period of time. • Application started or terminated. • Charger plugged in or remaining battery strength information. • Lid closed or other physical states of the product. • User has not interacted with the product for a period of time. The messages may come from kernel drivers or from other applications. The MontaVista Power Manager may perform some processing based on the event messages and will pass the event messages on to plugins and in some cases will also execute shell scripts. The event command enables provide the ability to inform the MontaVista Power Manager about various system and device power events, as explained in See Chapter 9, “Implementing Your Power Manager Building Blocks.” DE S I G NI N G P O W E R P O L I CI E S Policies may correspond to differing states of the product that have different power or performance needs. For example: • Product is in active use performing higher-power function. • Product is in active use performing lower-power function. • Product has been idle for a short period of time. • Product has been idle for an extended period of time. • Remaining battery strength has dropped below a certain threshold. • CPU usage is above a certain threshold. Each of these states might be associated with a different power policy to make desired tradeoffs between power consumption and performance appropriate for the different situations. dpmmgr is preconfigured with policies that may be appropriate for many of these situations.
..... D ES I G N IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Designing Programmable Sleep/Wakeup Sources Designing Programmable Sleep/Wakeup Sources 47 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D E S I G NI N G P R O G R A M M A B L E S L E E P / W A K E U P S O U R C E S Each platform may have one or more mechanisms available to wakeup the system from a sleep state. For example, the platform may support wakeup via one or more General- Purpose I/O (GPIO) interrupts, or from serial console activity, or from a Real Time Clock (RTC) alarm, etc. You may need to add code to enable the desired wakeup method. This may be performed by custom drivers, by board-specific bootup code, or by the code that places the system to sleep. Each Mobilinux LSP is typically preconfigured with at least one wakeup source for the board supported. D E S I G NI N G D P M T A S K S T A T E S You may wish to assign different operating points to different tasks, such that certain tasks run at a higher or lower power or performance level, as compared to the default level at which tasks not specially designated run. For example, a multimedia playback application that requires significant performance might be assigned a task state that boosts power or performance, while the default task state sets a lower power or performance point for other tasks without realtime response requirements that run in the background. Mobilinux LSPs are typically preconfigured with several task states. If more or less of these are desired then the kernel source must be recompiled with a new setting for DPM_TASK_STATE_LIMIT in the architecture-specific dpm.h header file under include/asm/. DE S I G NI N G S L E E P / S T A N DB Y B E H A V I O R If your product can enter sleep/standby/idle modes (as might occur when the user presses the off u button or closes the lid, or the product goes idle for a period of time), there may be a choice of platform sleep states to enter. DPM is preconfigured with one sleep operating state that can be used to enter a selected sleep mode through DPM interfaces. The choice of which mode to enter is a matter for the system designer to decide. This is chosen through the DPM policy, which maps the sleep
DE SIG NI N G YO UR POWER M A N A GER BUIL DI N G B LO CK S 48 Designing Sleep/Standby Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . operating state to the operating point that enters the sleep mode appropriate for the situation in which each policy is activate. For example, a policy is activated when the product has been idle for a short period of time might map the DPM sleep operating state to a standby mode that is quick to enter and exit, while a policy for an extended period of idle might map sleep to a lower-power mode that requires a longer wakeup time. An explicitly requested sleep operating state is the correct way to enter a sleep mode through DPM. Associating a task state with a sleep operating point will probably not have the desired effect. That is, each time a task associated with that state is scheduled, the system will go to sleep and require a wakeup, as this may repeat each time the scheduler again chooses that task for rescheduling. Most DPM operating states are entered due to system scheduling and interrupt processing activity, but sleep states need to be specifically requested at appropriate times. The Power Manager application is typically the component that decides that the system should go to sleep and requests the sleep operating state be activated. You may find it useful to have your product perform custom actions prior to sleeping and/or after wakeup, for example, to save application state or to turn on or off devices.
49 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DESIGNING DEVICE INTERACTIONS WITH DPM A DPM power management strategy requires that the system designer carefully consider the influence of attached devices on the strategy. Typically, changing a policy or an operating point may require notification of device drivers for some actions, such as reprogramming bus controllers for a new frequency to insure correct and efficient operations. It is up to the underlying DPM implementation to handle this requirement during the change in the operating point. In general, the most efficient policies for flexible systems will minimize operating point changes that require device driver notification. This chapter covers the following topics: • “Design Considerations” • “Specifying Device Constraints” • “Specifying Power Event Userspace Notification” • “Specifying Device Constraints Interfaces” • “Creating Driver Interface to DPM” • “Exporting Driver DPM to Userspace”
DE S IG NI N G D EV I C E I N TE R A C TI ON S W IT H DP M Design Considerations 50 Design Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DE S I G N C O N S I D E R A T I O N S In order to design device power management interactions with DPM consider the following design issues: HARDWARE RESTRICTIONS Some platforms place restrictions on the operating points that may be entered when certain devices are in use. Making use of those operating points in your DPM policies may need some coordination. This can take the form of power event messages from the driver letting Power Manager know that the device is active, or that it can be accomplished by using DPM device constraints. CONSTRAINTS V.S. EVENT MESSAGES Power event messages may be more appropriate when major changes in power policy might be needed in response to relatively infrequent changes in device state. For example, a device that has been inactive for a period of time may tell the MontaVista Power Manager about this event to allow the MontaVista Power Manager activate a new low-power policy, or to prepare the system enter a sleep state. Device constraints may be more appropriate for finer adjustments to power policy, especially for more frequent changes in device state. When used in conjunction with the DPM feature of operating point classes, constraints can cause DPM to choose a desired operating point from among a few alternatives provided in the class. For example, it may be possible to enter a lower-power operating point whenever a certain device is idle, and so DPM classes could be constructed to offer two operating points: one for when the device is active, and one for when the device is idle. HANDLING CONFLICTING DEVICES dpmmgr implements commands to power up and power down devices. This may be useful in situations in which power policy requires entering a low-power state that is incompatible with active devices: dpmmgr can power down the conflicting devices and then enter the needed state.
..... DE S IG NI N G D EV I C E I N TE R A C TI ON S W IT H DP M Specifying Device Constraints Specifying Device Constraints 51 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SCALE CALLBACKS In some cases a driver may need to implement the scale callback to be notified when a DPM operating point modifies a clock upon which correct operation of the device depends. The Mobilinux kernel source may already provide scale callbacks for drivers supported in Mobilinux that need to adjust device parameters in response to clocking changes performed by DPM. If you are adding additional drivers to the kernel in your product then you may need to add scale callbacks for some drivers. For example, the pixel clock of an LCD or other display device may need to be reprogrammed when the rate of the higher-layer clock that the LCD sources is modified. See Chapter 9, “Designing Device Interactions with DPM.” S P E C IF Y IN G DE V I C E C O N S T R A I NT S Typically, validating that policies do not violate device constraints is done by the DPM core. However, in some cases Power Manager performs some constraints processing itself. The sections that follow discuss the behaviors of the DPM core and Power Manager for device constraints. Upon reviewing their behavior, we can decide what sort of general description might best be used to describe the roles the DPM core and userspace Power Manager play. Power Manager can read and install constraints using the devices sysfs constraint file. CONSTRAINTS FOR AN OPERATING POINT If the active policy specifies a single operating point for the current operating state and the operating point violates a device constraint, the DPM kernel module will not set the operating point, leaving the system running at the previous operating point. This situation is best avoided whenever possible, since the intended power policy is not in effect and the system may be running at an inappropriate operating point that does not suit the power and performance needs of the current system state. Power Manager, however, avoids the above-mentioned situation in the case in which the system is being suspended and the operating point for the sleep state to enter has the force attribute set. If the force attribute is set for the sleep operating point and the operating point violates a device constraint, then Power Manager will power off the device that registered the constraint before activating the sleep operating point. The system designer can thus inform Power Manager to shut down devices and enter a low-power state when critical to do so, such as in low-battery conditions.
DE S IG NI N G D EV I C E I N TE R A C TI ON S W IT H DP M Specifying Power Event Userspace Notification 52 Specifying Power Event Userspace Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CONSTRAINTS FOR AN OPERATING CLASS If the active policy specifies an operating class of operating points for the current operating state then DPM chooses one of the operating points in the class that do not violate device constraints. SPECIFYING POWER EVENT USERSPACE NOTIFICATION For a variety of reasons, communicating information on power requirements or state changes from the kernel to a userspace MontaVista Power Manager may be necessary. This notification of kernel and application power events may, for example, request a system suspend in response to an interrupt received due to a button press, or it may communicate device status changes that could lead the MontaVista Power Manager to change the system power state. POWER HOTPLUG AGENTS DPM provides functions to notify userspace through the hotplug mechanism, which traditionally notifies userspace policy handlers of changes in devices present along with associated chores such as downloading firmware for new devices. When the DPM power event functions are called, hotplug executes an agent script to perform userspace handling of the power event. The DPM power events are sent to script /etc/hotplug/power.agent, supplying parameters that are described in the sections that follow for the particular types of power. Mobilinux provides the necessary agent scripts to communicate power events to the MontaVista Power Manager. If you are using your own power manager you may want to customize these scripts to communicate with your application.
..... DE S IG NI N G D EV I C E I N TE R A C TI ON S W IT H DP M Specifying Device Constraints Interfaces Specifying Device Constraints Interfaces 53 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . S P E C IF Y IN G D E V I C E C O N S T R A I N T S I N T E R F A C E S Device constraints may be specified and managed by driver code in the kernel, or from userspace through the sysfs interface under the control of a power policy management application. The ability to enforce constrained operating points is handled by the kernel platform code or from userspace through sysfs. SPECIFYING CONSTRAINTS THROUGH SYSFS The following is the syntax to specify constraints: <param-name> <min-value> <max-value> These values are written to the power/constraints attribute of the sysfs file for the device. Writing a constraint with the same power parameter as an existing constraint overwrites the previous constraint: echo "dpll-mult 14 16" > /sys/devices/platform/omapfb0/power/constraints echo "dpll-mult 12 14" > /sys/devices/platform/omapfb0/power/constraints changes the constraint minimum and maximum values for the dpll-mult power parameter. Minimum or maximum value -1 indicates no constraint has been assigned. The above constraints could be removed through: echo "dpll-mult -1 -1" > /sys/devices/platform/omapfb0/power/constraints To read or write constraints, see Chapter 5, “DPM Device Driver Interfaces.” Device constraints may also be specified using the constraints field of the struct device, which is a pointer to a struct constraints. Constraint parameters are identified by the same constants used to index the hardware parameters in the operating point dpm_md_pp_t array. An example for a platform that interprets identifier DPM_MD_PLL as the index of a power parameter that indicates if the PLL is on or off: static struct constraints my_constraints = { count: 1, param: {{DPM_MD_PLL, 1, 1},}, /* require the PLL be on */ }; static struct device my_device = { ... constraints: &my_constraints, }
DE S IG NI N G D EV I C E I N TE R A C TI ON S W IT H DP M Creating Driver Interface to DPM 54 Creating Driver Interface to DPM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The values of the param field correspond to the power_param_id, min_value, and max_value, parameters of the sysfs attribute described above. ASSERTING CONSTRAINTS Device constraints are normally asserted whenever the device is powered on and are deasserted whenever the device is powered off. DPM activates and deactivates device constraints when a device is suspended and resumed. Constraints can also be managed by the driver by calling: assert_constraints(dev->constraints) deassert_constraints(dev->constraints) C RE AT I NG D RI V E R I N T E RF A C E T O D P M Each driver must declare a struct device_driver data structure for itself and a struct device for each device it manages. Examples for a hypothetical driver (excluding power management information) are provided in the following example. Note: Non-power-management-related LDM features such as the probe driver callbacks, or registering operating classes or interfaces, are not used in these code examples. Most embedded devices that do no appear on a standard bus such as PCI can be registered as platform devices on the built-in platform bus. Example code for Mobilinux: static struct device_driver mydriver = { .name = "mydevice", .bus = &platform_bus_type, .probe = mydriver_probe, .suspend = mydriver_suspend, .resume = mydriver_resume, }; driver_register(&mydriver); The LDM code will call mydriver_probe to establish a binding between the driver and the device when any device with a name starting with mydevice is registered on the platform bus. The device data structures and registration call typically appear in a board-specific file (not the driver itself), allowing for board-specific customization of the device characteristics.
..... DE S IG NI N G D EV I C E I N TE R A C TI ON S W IT H DP M Exporting Driver DPM to Userspace Exporting Driver DPM to Userspace 55 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . For example, your platform may define: static struct platform_device mydevice = { .name = mydevice, .id = -1, .dev = { .platform_data = &myboard_data}, }; platform_device_register(&mydevice); Note: Your particular platform may have special conventions or requirements that require use of board-specific or other busses for some drivers. E X P O R T I N G D R I V E R D P M T O U S E R S P A C E This section describes the user-space interface to driver power management information. The sysfs file system is used to export driver power management attributes to user-space. The /sys directory is the recommended mount point, for example: mount -t sysfs /sys Each device is associated with a logical bus. The logical bus definition is based on the categorization of devices in documentation specific to your board. For example, the command ls -1 /sys/bus on a particular board might display the following: i2c mmc platform scsi serio Likewise, the command ls -1 /sys/bus/platform/devices might display the following contents: mmci-omap.1 omap_rtc omapfb omapflash.0 ps2 serial8250 serial8250.0 smc91x.0
DE S IG NI N G D EV I C E I N TE R A C TI ON S W IT H DP M Exporting Driver DPM to Userspace 56 Exporting Driver DPM to Userspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Each device is a directory, so you can display the contents using the standard list command. For example, ls -1 /sys/bus/platform/devices/omapfb displays the contents of omapfb: bus caps_num caps_text ctrl driver panel power
57 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 IMPLEMENTING YOUR POWER MANAGER ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BUILDING BLOCKS Chapter 8, “Designing Device Interactions with DPM,” explained how to design different components of your power management system. This chapter covers the specific tasks that you need to execute to implement your design. The following topics are covered in this chapter: • “Implementing Power Management for Custom Drivers” • “Implementing Precompiled Device Constraints” • “Implementing Driver Scale Callbacks” • “Implementing Notification of Kernel Power Events” • “Developing Your Power Manager” • “Implementing Notification of Application Power Events” • “Implementing DPM Operating Points” • “Implementing DPM Operating Classes” • “Implementing DPM Operating Policies” • “Implementing Policy Manager Handling of Events” • “Implementing Other Logic for Determining Power Policy” • “Implementing Runtime Device Constraints” • “Implementing System Suspend/Resume” • “Implementing Device Power State Modifications”
IM P LE M EN T IN G YOU R POWE R M A N A G E R BU I LD IN G B LO CK S 58 Implementing Power Management for Custom Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG P O W E R M A NA G E M E N T F O R C US T O M D R I V E RS Mobilinux provides suspend/resume power management capability for most or all devices that are supplied with the board supported by your LSP. If additional drivers are added to your product, you may need to add suspend/resume callbacks to those drivers. This ensures that devices are properly shut down and restarted across a system sleep, as well as decreasing power consumption during sleep is accomplished. The following two generic power management functions and header file need to be added to a platform_device driver for it to respond to suspend and resume commands: # include <linux/device.h> # ifdef CONFIG_PM static int dpm_example_suspend (struct device *dev, u32 state, u32 level) { int ret = 0; if (level == SUSPEND_DISABLE) printk("suspendingn"); return ret; } static int dpm_example_resume (struct device *dev, u32 level) { int ret = 0; if (level == RESUME_ENABLE) printk("resumingn"); return ret; } # endif The driver device structure needs to have those two function pointers initialized. static struct device_driver dpm_example_driver = { .name = “dpm-example”, .bus = &platform_bus_type, .suspend = dpm_example_suspend, .resume = dpm_example_resume, };
..... IM P LE M EN T IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Implementing Precompiled Device Constraints Implementing Precompiled Device Constraints 59 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I N G P R E C O M P I L E D D E V I C E C O N S T R A I N T S You can add precompiled device constraints to drivers, in addition to any device constraints already supplied in the Mobilinux kernel source. You can instead create and modify device constraints from an application or from dpmmgr during runtime, which will reduce the kernel changes needed for DPM. See “Implementing Runtime Device Constraints.” The device constraint structure needs to be initialized. # ifdef CONFIG_DPM # include <asm/dpm.h> static struct constraints dpm_example_constraints = { .count = 1, /* constrain the clock to be > 0 */ .param = {{DPM_MD_CLOCK, 1, 999999},}, /* target specific */ }; # endif I M P LE M E NT I NG D RI V E R S C AL E C A L LB A C K S You may need to add scale callbacks to drivers to react to changes in upstream clocks, as determined in Chapter 8, “Designing Device Interactions with DPM.” static struct device_driver dpm_example_driver = { .name = “dpm-example”, .bus = &platform_bus_type, .suspend = dpm_example_suspend, .resume = dpm_example_resume, .scale = dpm_example_scale, }; The following is an example of a scale call back function: static int dpm_example_scale(u32 level) { int ret = 0; printk("scalingn"); return ret; }
IM P LE M EN T IN G YOU R POWE R M A N A G E R BU I LD IN G B LO CK S 60 Implementing Notification of Kernel Power Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG N O T I F I C AT IO N O F K E R NE L P O W E R E V E NT S Choose a unique name for the event that the MontaVista Power Manager can use to recognize that event. Other parameters to fully describe the event may also be needed. Communicating information on power requirements or state changes from the kernel to a userspace power policy manager may serve several purposes. The information may, for example, request a system suspend in response to an interrupt received due to a button press, or may communicate device status changes that could lead the policy manager to change system power state. DPM provides functions to notify userspace through the hotplug mechanism, which traditionally notifies userspace policy handlers of changes in devices present, along with associated tasks such as downloading firmware for new devices. Hotplug executes an agent script to perform userspace handling of the power event. The DPM power events are sent to script /etc/hotplug/power.agent, supplying parameters that are described in the subsections for the particular types of power events below. All other events are passed through to the plugin_event_handler functions for the loaded plugins, without further processing by dpmmgr. D E V E L O P I N G Y O U R P O W E R M A N A G E R If you are developing your own MontaVista Power Manager from scratch, you first need to initialize DPM. dpmmgr will automatically initialize DPM at startup. If you are using dpmmgr as a starting point, you need to customize its default configuration file in /lib/modules/$(uname -r)/dpmmgr.conf. You might also write a plugin to customize dpmmgr for your product’s needs. Your MontaVista Power Manager will probably also be the software that configures DPM with operating points, classes, and policies, as described in the following sections.
..... IM P LE M EN T IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Implementing Notification of Application Power Events Implementing Notification of Application Power Events 61 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG N O T I F I C AT IO N O F A P P LI C A T I O N P O W E R E V E N T S Choose a unique name that the MontaVista Power Manager can use to recognize the event. Other parameters to fully describe the event may also be needed. General-purpose power information may be communicated using function power_event(): power_event(char *msg); msg a free-format string to be sent to your userspace power policy manager. The msg string is passed to power.agent in variable EVENT. The ACTION variable is event. A sample script fragment for this is: case $ACTION in event) DEBUG=yes debug_mesg "Power event: $EVENT" ;; I M P LE M E NT I NG D P M O P E R A T I N G P O I NT S Based on the kinds of power policies to be employed, create the DPM operating points needed for the DPM policies. See “Designing Power Policies,” Chapter 7, “Designing Your Power Manager Building Blocks.” Information on choices of values of power parameters for your operating points may be available from the following sources: • The power parameter values or operating points supported by the vendor for your hardware. See “Studying Your Hardware’s Power Management Characteristics,” in Chapter 8, “Designing Device Interactions with DPM.” • The DPM Developer’s Guide for the Mobilinux LSP for your hardware.
IM P LE M EN T IN G YOU R POWE R M A N A G E R BU I LD IN G B LO CK S 62 Implementing DPM Operating Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXAMPLES The following examples create an operating point named “312mhz” with several power parameters for a PX27x Mainstone board: US IN G DP MMG R .C ON F # operation points op 312mhz v=1250 l=16 n=3 b=1 half_turbo=0 cccra=0 cpll-on=1 ppll-on=1 sleep_mode=0 US IN G DP ML IB if (dpm_create_op("312mhz", NULL)) { perror("dpm_create_op"); exit(1); } if (dpm_set_op_param("312mhz", "v", 1250)) { perror("dpm_set_op_param"); exit(1); } if (dpm_set_op_param("312mhz", "l", 16)) { perror("dpm_set_op_param"); exit(1); } ... US IN G SYS F S echo create 312mhz >/sys/dpm/op/control echo -n 1250 >/sys/dpm/op/312mhz/v echo -n 16 > /sys/dpm/op/312mhz/l ...
..... IM P LE M EN T IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Implementing DPM Operating Classes Implementing DPM Operating Classes 63 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG D P M O P E R A T I N G C L A S S E S If you are using DPM operating point classes first see “Guidelines for Setting up DPM Operating Points,” in Chapter 7, “Designing Your Power Manager Building Blocks.” Next, you will need to create the needed classes. You will probably want to construct classes such that one operating point is never constrained by devices and can always be chosen, in case device constraints prevent setting the other operating points in the class. If all operating points in the class are constrained then DPM will simply not set an operating point in response to the change in operating state or policy that triggered DPM to check the class for an appropriate operating point. This will leave the system executing at the operating point that was active prior to the change, which may not be appropriate for the new state. EXAMPLES The following examples create an operating class named “full” that contains two operating points that were previously created, named “256Khz” and “312Khz”. US IN G DP MMG R .C ON F class full 256Khz 312Khz US IN G DP ML IB if (dpm_create_class("full", "256Khz 312Khz")) { perror("dpm_create_class"); exit(1); } US IN G SYS F S echo create full 256Khz 312Khz > /sys/dpm/class/control
IM P LE M EN T IN G YOU R POWE R M A N A G E R BU I LD IN G B LO CK S 64 Implementing DPM Operating Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG D P M O P E R A T I N G P O L I CI E S You need to create DPM policies that correspond to the needed power policies, as discussed in “Designing Power Policies,” in Chapter 8, “Designing Your Power Manager Building Blocks.” Choose operating points, as shown in “Implementing DPM Operating Points,” or choose operating classes, as shown in “Implementing DPM Operating Classes.” Next, set the operating points or operating classes you have chosen here for each operating state, according to the power/performance levels appropriate for the state and for the situation in which the particular policy will be activated. If you are using task states, as determined in “Designing DPM Task States,” in Chapter 7, “Designing Your Power Manager Building Blocks.” Next, you will need to assign relatively higher- or lower-powered operating points for the task states that are designated higher- or lower-powered than the default task state. The following descriptions are helpful in making decisions regarding which operating point to associate with operating states. ID LE S TA TE The idle operating state is set whenever the Linux scheduler determines that there is no task to be run and so the idle loop is executed. The idle loop waits for an interrupt to arrive, and can, in general, run at a low-power operating point. This state may be entered and exited very often. Depending on application real time deadlines and system power consumption goals, it may be necessary to choose an operating point with low latency to enter and exit, and not necessarily the lowest-power operating point available. ID L E- TA SK S TA TE The idle-task operating state is set when woken from idle but before scheduling a task to run. Interrupts that arrive while the system was idle are serviced in this state, and certain kernel daemons that extend interrupt processing, such as ksoftirqd. The scheduler processing that decides which process to execute next also run in this state for interrupts that arrive during idle. Interrupts that are serviced while in a task state, on the other hand, are serviced while in that task state. The operating point used for idle-task state should be powerful enough to handle interrupts in a timely manner, while conserving power if possible, since the highest
..... IM P LE M EN T IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Implementing DPM Operating Policies Implementing DPM Operating Policies 65 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . power/performance levels of the platform would not be needed to service low-power interrupts. The system transitions between idle, idle-task, and task very frequently. If long latencies are involved in transitioning between the operating points chosen for these states then the performance or realtime response of applications might be impaired. EXAMPLES The following examples create a policy named “hi-power” that maps all operating states to an operating point or an operating class named “full” that was previously created. US IN G DP MMG R .C ON F policy hi-power idle,idle-task,task,task+1,task+2,task+3,task+4=full US IN G LI BD P M if (dpm_create_policy("hi-power", NULL)) { perror("dpm_create_policy"); exit(1); } if (dpm_set_policy_state_map("hi-power", "idle" "full")) { perror("dpm_set_policy_state_map"); exit(1); } if (dpm_set_policy_state_map("hi-power", "idle-task" "full")) { perror("dpm_set_policy_state_map"); exit(1); } ... US IN G SYS F S echo create hi-power > /sys/dpm/policy/control echo -n full > /sys/dpm/policy/hi-power/idle echo -n full > /sys/dpm/policy/hi-power/idle-task
IM P LE M EN T IN G YOU R POWE R M A N A G E R BU I LD IN G B LO CK S 66 Implementing Policy Manager Handling of Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IMPLEMENTING POLICY MANAGER HANDLING OF EVENTS If drivers or applications are expected to send power-related events to your MontaVista Power Manager, as shown in “Designing Power-Related Events,” in Chapter 7, “Designing Your Power Manager Building Blocks,” then Power Manager logic to read and/or handle these events needs to be implemented. Power Manager would typically recognize the events by name and adjust power state accordingly, taking an action such activating a different policy or to power or down devices. If you used dpmmgr, then it provides the code to read events and commands, to perform various actions upon receipt of events, and to pass event messages to plugins for custom handling. The event handlers may perform such actions as: • Activate a new DPM policy. See “Activating a Policy,” in Chapter 10,“Starting Your Power Manager.” • Power up or down a device. See “Implementing System Suspend/Resume.” • Feed new information to custom algorithms that select policies. See “Implementing Other Logic for Determining Power Policy.” • Put the system into sleep. See “Implementing System Suspend/Resume.” I M P LE M E NT I NG O T H E R L O G I C F O R D E T E R M I N I NG P O W E R P O L I CY There may be other information useful for making power policy decisions to be factored into your Power Manager’s algorithms. For example, information on Linux system state or hardware profiling registers might help decide appropriate power policy and/or device power states. If using dpmmgr, the dpm-profiler plugin is available to make decisions based on how busy the system is.
..... IM P LE M EN T IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Implementing Runtime Device Constraints Implementing Runtime Device Constraints 67 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG R UN T I M E D E V I C E C O N S T RA I N T S Device constraints can be set or modified through the DPM sysfs interface or using dpmmgr commands, rather than hard-coding these into kernel driver sources. This may be useful if the necessary constraints can be managed from the Power Manager application, or to avoid modifying drivers to precompile constraints when these can be set from Power Manager instead. Constraints may be read and written using the sysfs constraints power attribute of the device, /sys/devices/bus/device-id/power/constraints. The format of strings written to this attribute is: power_param min_value max_value where: power_param is the name of a power parameter for the platform, min_value is the minimum value of that power parameter, or -1 for no minimum, max_value is the maximum value of that power parameter, or -1 for no maximum. For example: echo "pll 66 266" > /sys/devices/my-bus/my-device/power/constraints The above example causes device my-device to constrain the power parameter named pll to values between 66 and 266. Writing new values for a different power parameter to the constraints attribute adds new constraints for that device. Writing new values for a power parameter that already appears overwrites the old values. If the new maximum or minimum value is -1, the existing maximum or minimum constraint is removed.
IM P LE M EN T IN G YOU R POWE R M A N A G E R BU I LD IN G B LO CK S 68 Implementing System Suspend/Resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG S Y S T E M S U S P E N D/ R E S UM E In “Designing Sleep/Standby Behavior,” in Chapter 7, “Designing Your Power Manager Building Blocks,” the needed platform suspend modes were identified and policies were created to map the sleep operating state to operating points that enter the needed sleep modes. There may also be other actions appropriate to take prior to suspend and after resume. The interfaces to enter the sleep state and perform these custom actions are described below. dpmmgr is typically configured to setup at least one operating point that enters a sleep mode for the platform. It also provides scripts that may be executed at suspend and resume times to perform custom actions at those times. EVENT HANDLING The Power Manager event command informs the user about various system and device power events. The messages may come from kernel drivers or from other applications. The Power Manger may perform some processing based on the event messages and will pass the event messages on to plugins, and in some cases will also execute shell scripts. The parameter to the event command is a word that describes the type of the event, along with a string of parameters that further describes the event. All other events are passed through the plugin_event_handler functions for the loaded plugins, without further processing by dpmmgr. In some cases, it may be useful to communicate device-specific information on power requirements from drivers to a userspace Power Manager. For example, the information may request a change in a system power state to accommodate a change in the device power state, or it may be a hint regarding expected device activity that Power Manager may use for device system or device power levels. SUSPEND AND RESUME HANDLING The Power Manager suspend command, or an event mapped to a suspend command first executes dpmmgr to check the requested (or defaulted) sleep operating state against device constraints. If not rejected by the previous methods, these suspend-resume scripts are executed (if present) before and after the actual system suspend, respectively.
..... IM P LE M EN T IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Implementing Device Power State Modifications Implementing Device Power State Modifications 69 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG D E V I C E P O W E R S T A T E M O D I F I C A T I O N S It may be necessary for the MontaVista Power Manager to manage the power state of devices. For example, Power Manager may decide to power down devices due to an event, such as an indication of battery low. If you are using dpmmgr, an example command is: suspend device platform/omapfb
IM P LE M EN T IN G YOU R POWE R M A N A G E R BU I LD IN G B LO CK S 70 Implementing Device Power State Modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
71 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . STARTING YOUR POWER MANAGER After designing and then implementing the building blocks of your MontaVista Power Manager, next you may start Power Manager, dpmmgr. The following topics are covered in this chapter: • “Running Your Power Manager” • “Starting Applications with DPM interactions” • “Testing Your Power Management System.” • “Activating a Policy”
S T A R T IN G YOU R POWE R M A N A G E R Running Your Power Manager 72 Running Your Power Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R UN N I NG Y O U R P O W E R M A NA G E R This section provides instructions that can automatically start dpmmgr during each boot. STARTING POWER MANAGER MANUALLY You can start dpmmgr manually from the Mobilinux development kit by entering the following command: # /etc/init.d/dpmmgr start To check for errors, enter the following: # /var/log/dpmmgr.log STARTING POWER MANAGER AUTOMATICALLY In order to have Power Manger auto start or shut down with the system, use the utility initdconfig: initdconfig dpmmgr on This will enable the dpmmgr rc script. S T A R T I N G A P P L IC A T I O N S W I T H D P M I N T E R A CT I O N S Now that your MontaVista Power Manager is ready to receive power event notifications and DPM is initialized, applications that interact with your Power Manager or that should run under a particular DPM task state can be started. To run a process with a non-default task state enter the following: DPMLIB This example sets the caller's task state to task-1: include <linux/dpm.h> struct dpm_param params; params.pid = getpid(); params.task_state = DPM_TASK_STATE-1; if (sys_dpm(DPM_SET_TASK_STATE, &params)) perror("sys_dpm(DPM_SET_TASK_STATE)");
..... S T A R TI N G YO U R POW ER M A N A G ER Testing Your Power Management System Testing Your Power Management System 73 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . /PROC This example sets the shell's task state to task-1: echo -n "task-1" > /proc/$$/dpmstate A new process will inherit the DPM task state of its parent process. If a process is running at a non-default task state then all processes it forks will be assigned the same task state. This can be a convenient way to run non-DPM-aware processes at a specific task state. There may be a correlation between the DPM task state at which a process is to run and the scheduling priority at which it is to run. In general, applications that are given high scheduling priority are often also assigned a high power/performance level. However, there may be situations in which the application can meet its deadlines while conserving power by running at a lower power level but with high scheduling priority, to ensure that it completes prior to scheduling a less important task. T E S T I N G Y O U R P O W E R M A N AG E M E N T S Y S T E M The following tools for testing your power management system are available: • Test equipment such as multimeters and logic analyzers to probe points of interest on the board or to measure current drawn, etc. • The following command shows the number of times each operating state has been entered, to help understand what operating states are being set while your system runs: cat /sys/dpm/state/stats For example, if you have processes running at non-default task states, this will help verify how often those tasks are being scheduled. • The following command displays the number of times each operating point has been set, to help understand the operating points at which your system runs. cat /sys/dpm/op/stats • The following displays the number of times each policy has been activated, to help understand the policies at which your system runs: cat /sys/dpm/policy/stats • Kernel and application power events can be simulated by sending the messages from a command-line dpmmgr execution. For example the following command will send the named event and argument to dpmmgr in much the same way as would an actual event message from the kernel via power_event ("buttonpress topbutton"): /usr/sbin/dpmmgr "event buttonpress topbutton"
S T A R T IN G YOU R POWE R M A N A G E R Activating a Policy 74 Activating a Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AC T IV AT I NG A P O L I C Y In order to start DPM managing the power state of your system, you need to activate a power policy. Choose which policy to activate initially, which might be hard-coded to high- or low-power policy depending on anticipated power needs at the time the Power Manager begins to run, or might be selected by a custom algorithm based on system state. USING DPMMGR dpmmgr "set policy <name>" USING SYSFS echo -n <name> > /sys/dpm/policy/active
75 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . POWER MANAGER COMMANDS MontaVista Power Manager serves as the preferred DPM interface, instead of direct access of the lower-level interfaces. It provides basic DPM policy management, switching power settings, for example, to a higher performance level when system load increases. Power Manager ties together the various components involved in a power management system, such as kernel drivers and power-aware applications, into a framework that you may want to use for your products. The following topics are covered in this chapter: • “Power Manager commands Accessibility” • “Operating Points and Classes Commands” • “Power Policy Commands” • “Power State Commands” • “Device Power State Commands” • “Device Constraint Commands” • “System Status Commands” • “Power Events Commands”
POWER M A N A G ER C O M M A ND S Power Manager commands Accessibility 76 Power Manager commands Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P O W E R M A NA G E R C O M M A ND S A C CE S S I B I L I T Y The Power Manager commands provided in this chapter are available from the configuration file during startup, or from another dpmmgr invocation through the command-line parameter. COMMANDS SYNTAX Command lines may consist of several dpmmgr commands separated by semicolons (;). A pound sign (#) begins a comment line. There are no quoting characters to escape the interpretation of semicolons or pound signs. Various commands refer to devices using syntax bus/device. This is a string comprised of a sysfs bus name and a sysfs device name separated by a forward slash (/). For example, platform/omapfb0 refers to the device named omapfb0 on the platform bus. O P E RA T I N G P O I N T S A N D C L A S S E S C O M M A ND S op name [param=value...] Define a new operating point or modify parameters for an existing operating point. Any parameters not named for a new operating point are set to -1 (the no change / use default value parameter value). Other named attributes of operating points, such as the force flag, may also be set this way: op myop force=1. class name op op... Define a new class of operating points, or modify an existing class. P O W E R P O L I CY CO M M AN D S policy name state[,state...]=class/op... Define a new policy or modify an existing policy. set policy name Set the policy to activate.
..... POWER M A N A G ER C O M MA ND S Power State Commands Power State Commands 77 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P O W E R S T A T E C O M M A N D S suspend system [state [args]] Suspend the system, eventually entering the DPM sleep operating state state, or state sleep if not specified. args are passed to the plugins and scripts that handle the suspend. D E V I C E P O W E R S T A T E C O M M A N D S suspend device bus/device [state] Suspend a device, entering state state, or state 3 if not specified. resume device bus/device Resume a device. DE V I C E C O N S T R A I NT CO M M AN D S constrain bus/device param min max Set or remove a device power parameter constraint. S Y S T E M S T A T U S C O M M AN D S status Report a status summary to stdout.
POWER M A N A G ER C O M M A ND S Power Events Commands 78 Power Events Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P O W E R E V E N T S C O M M A N D S on event event command-line Execute a command line, which may consist of multiple commands separated by semicolons, upon receipt of an event. Can be used to requested a system suspend in response to an event, or to activate a different policy. This command consumes the rest of the command line: any subsequent commands separated by semicolons are added to the command line to be executed upon the named event. The following strings are substituted in the command-line: %e event name (the event parameter) %a event arguments (the args parameter from the event or suspend command) event event-args Process a power event. See the section on Event Handling for more information.
79 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PLUGIN COMMANDS AND APIS The MontaVista Power Manager enables you to add value by adding plugins that extend the features of a base policy manager. The following topics are covered in this chapter: • “Power Manager Commands Accessibility” • “Plugin Commands” • “Plugin APIs”
P LU G IN CO M M A N DS A ND A P I S Power Manager Commands Accessibility 80 Power Manager Commands Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P O W E R M A NA G E R C O M M A ND S A C CE S S I B I L I T Y The Power Manager commands provided in this chapter are available from any source, including FIFO /tmp/dpmmgr.fifo during runtime to receive commands from applications and kernel event messages (as from power hotplug scripts), as well as from plugins through plugin API function calls. COMMANDS SYNTAX Command lines may consist of several dpmmgr commands separated by semicolons (;). A pound sign (#) begins a comment line. There are no quoting characters to escape the interpretation of semicolons or pound signs. Various commands refer to devices using syntax bus/device. This is a string comprised of a sysfs bus name and a sysfs device name separated by a forward slash (/). For example, platform/omapfb0 refers to the device named omapfb0 on the platform bus. P L U GI N C O M M A ND S The following Power Manager commands are provided from plugins: load file Load a plugin from the specified dynamic library file. The plugin will be referred to by the filename (without extension) in other commands. tell plugin command-string Send command-string to the named plugin. interval n Call the plugin_poll_handler callback for all loaded plugins every n seconds. shell command Execute a shell command through system().
..... P LU G I N C OM M A N DS A N D A PI S Plugin APIs Plugin APIs 81 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P L U G I N A P I S A plugin is added by creating a shared library that conforms to the Plugin API and loading the plugin into the policy manager using the load command. The Power Manager Plugin API includes these callbacks (functions called by dpmmgr into the plugin): int command_handler(char *cmd) Called to handle a tell command string. void poll_handler(void) Called periodically to poll for changes in system state. The poll interval is set using the interval command. int suspend_handler(char *args, char *sleep_state) Callback to notify of an impending system suspend request. The plugin may return an error to veto the suspend request. See the section on Event Handling for more information. void resume_handler(void) Callback to notify of system resume. void event_handler(char *event, char *args) Callback to notify of a non- suspend/resume power event. See Chapter 9, “Implementing Your Power Manager Building Blocks,” for more information about event handling. void status_handler(char *event, char *args) Callback to report plugin-specific status as part of a status command. int dpmmgr_command(char *cmdline) The Plugin API includes this function in dpmmgr that the plugin may call. This function execute a dpmmgr command line to switch to a different policy.
P LU G IN CO M M A N DS A ND A P I S Plugin APIs 82 Plugin APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
83 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . POWER MANAGER PROFILER PLUGIN MontaVista provides the dpm-profiler plugin with the Power Manager. This plugin measures the CPU load and sets profiles and DPM policies according to the dpm-profiler commands. The following topic is covered int his chapter: • “DPM-Profiler Plugin Commands” • “Terms Definitions”
POWER M A N A G ER P R OF IL ER P LU G I N DPM-Profiler Plugin Commands 84 DPM-Profiler Plugin Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D P M - P R O F I L E R P L U G I N CO M M A N D S The following are the DPM-profiler plugin commands. For definitions of terms metric and profile used by these commands, see “Terms Definitions.” tell dpm-profiler cpu percentage[%] [+]n Increase the power metric by n when the CPU is at the given utilization. tell dpm-profiler [profile profile] at n command Perform the specified command when the power metric is at or above the given value, and when the named power profile is active. The command might be to activate a certain policy, or to remap the task operating state to a new operating point under the current policy, etc. The mapping of power metric to command takes effect only when the associated power profile is active. A power profile may be named in order to associate the mapping with a specific profile (activated using the tell dpm-profiler set profile command), or may be omitted, in which case the mapping is associated with the power profile named default. tell dpm-profiler set metric [+/-]n Set the power metric to the parameter, or adjust the power metric up or down according to the parameter. tell dpm-profiler set profile profile Activate the named power profile, which will become the power profile in effect until another tell dpm-profiler set profile command is given. May specify the built-in profile names default (for commands given without a profile specified) and none (no power profile activated, disabling profile-selector from evaluating power metrics and executing commands associated with metrics through tell dpm-profiler at commands).
..... POWE R M A N A G E R P R OF I LE R P L UG IN Terms Definitions Terms Definitions 85 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . T E R M S D E F I N I T I O N S The following terms are used by DPM-profiler plugin commands: POWER PROFILE A power profile describes a high-level state of your power management system. It can be thought of as a level above the DPM policy that describes which set of policies are appropriate for the current state of the power management system. For example, there may be one profile for use when the battery is at high or medium strength, and another profile for when battery strength is low. dpm-profiler is configured to take certain actions based on the value currently computed for the power metric (described below), with the most common action being to activate a different policy. These mappings of power metric values to actions are configured differently for different power profiles. Activating a different profile will switch to a different set of mappings between power metrics and actions. Activating a different profile might occur in response to an event notification of, for example, battery strength falling below a certain level. The active DPM policy maps operating states to operating points, dpm-profiler adds logic to switch policies based on metrics such as CPU usage, and the power profile selects which set of mappings between metrics and policies is appropriate for the current overall system state, commonly based on remaining battery strength. POWER METRIC The power metric is a value that can be used to tell dpm-profiler to select different power profiles or policies, based on system profiling information collected by your power manager plugin or based on rules built into dpm-profiler. The power metric can be specified using dpm-profiler commands that adjust the value up or down in response to calculations performed in your plugin, or that set the value according to built-in calculations that dpm-profiler performs, such as to set the value based on CPU usage. dpm-profiler will recalculate the power metric at each poll interval and take the action for which it has been configured, based on the resulting value and the currently-active profile. Typical actions might be to activate a different power profile or DPM policy.
POWER M A N A G ER P R OF IL ER P LU G I N Terms Definitions 86 Terms Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
87 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM APIS This chapter provides DPM library functions for libdpm DPM API-based as well as sys_dpm-based interfaces. The following topics are covered in this chapter: • “libdpm DPM APIs Interface” • “sys-dpm APIs Interface”
DP M AP I S libdpm DPM APIs Interface 88 libdpm DPM APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . L IB D P M D P M A P I S I N T E RF A C E The API based functions in this section are able to control the operations of DPM through the libdpm DPM API interface, as follows: INT DPM_INIT() DE SC R IPT ION Initialize DPM. EXA MP L E if (dpm_init()< 0) perror("sys_init"); INT DPM_SET_STATE (CHAR *STATENAME) DE SC R IPT ION Set an operating state by name. EXA MP L E if (dpm_set_state(name) < 0) perror("dpm_set_state"); INT DPM_CREATE_OP (CHAR *OPNAME, CHAR *PARAMS) DE SC R IPT ION Create an operating point. params is recommended to be NULL, but it may specify a list of parameter values in board-specific order according to the numeric order of power parameter indices that was defined for the board. Using this parameter is discouraged; instead using dpm_set_op_param() to set each power parameter is recommended. EXA MP L E if(dpm_create_op("600M", NULL) < 0) perror("dpm_create_op");
..... D PM A PI S libdpm DPM APIs Interface libdpm DPM APIs Interface 89 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INT DPM_SET_OP_PARAM (CHAR *OPNAME, CHAR *PARAMNAME, INT PARAMVALUE) DE SC R IPT ION Set a power parameter for an existing operating point. EXA MP L E if (dpm_set_op_param("600M", "cpu", "600") < 0){ perror("dpm_set_op_param"); INT DPM_GET_OP_PARAM (CHAR *OPNAME, CHAR *PARAMNAME, CHAR *BUF, SIZE_T BUFSIZ) DE SC R IPT ION Read a power parameter for an operating point into buf. EXA MP L E if(dpm_get_op_param("Static", "cpu", buf, sizeof(buf)) < 0){ perror("dpm_get_op_param"); INT DPM_CREATE_CLASS (CHAR *CLASSNAME, CHAR *OPNAMES) DE SC R IPT ION Create a new class (or re-create an existing class with new list of operating points). EXA MP L E if (dpm_create_class("on", "600M") < 0){ perror("sys_dpm(DPM_CREATE_CLASS)");
DP M AP I S libdpm DPM APIs Interface 90 libdpm DPM APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INT DPM_CREATE_POLICY (CHAR *POLICYNAME, CHAR *OPSCLASSES) DE SC R IPT ION Create a policy. The opsclasses parameter is recommended to be NULL, but may also specify a list of operating point or class names in board-specific order according to the numeric order of operating states for the board. This parameter is deprecated; it is recommended to use dpm_set_policy_state_map() to set each operating point or class for the policy instead. EXA MP L E if (dpm_create_policy("Static", NULL) < 0) perror("sys_dpm(DPM_CREATE_POLICY)"); INT DPM_SET_POLICY_STATE_MAP (CHAR *POLICYNAME, CHAR *STATENAME, CHAR *OPCLASS) DE SC R IPT ION Map an operating state to an operating point or class in a policy. opclass is the operating point or class name to map the named operating state to under the named policy. EXA MP L E if (dpm_set_policy_state_map("Static" , "Idle", "600M") < 0) perror("dpm_set_policy_state_map)"); INT DPM_GET_POLICY_STATE_MAP(CHAR *POLICYNAME, CHAR *STATENAME, CHAR *BUF, SIZE_T BUFSIZ) DE SC R IPT ION Read the operating point or class mapped by an operating state in a policy into buf. EXA MP L E if(dpm_get_policy_state_map("Static", "Idle" , buf, sizeof(buf)) < 0) perror("dpm_get_active_policy)");
..... D PM A PI S libdpm DPM APIs Interface libdpm DPM APIs Interface 91 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INT DPM_SET_ACTIVE_POLICY (CHAR *POLICYNAME) DE SC R IPT ION Activate the named policy. The system will run under that DPM policy. EXA MP L E if (dpm_set_active_policy(dflt_pdomains[num].name) < 0){ perror("dpm_set_active_policy)"); return 0; }else { printf("nnSet policy to %sn", dflt_pdomains[num].name); } INT DPM_GET_ACTIVE_POLICY (CHAR *BUF, SIZE_T BUFSIZ) DE SC R IPT ION Return the currently active policy name into buf. EXA MP L E #include <stdlib.h> #include <stdio.h> #include <dpmlib.h> int main (void) { char buf[256]; if (dpm_get_active_policy(buf, sizeof(buf)) < 0) { perror("policy manager"); return 0; } printf("Active Policy: %sn", buf); return 1; }
DP M AP I S sys-dpm APIs Interface 92 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . S Y S -D P M A P I S I N T E R F A C E The Power Manager interface manages the installation and activation of power policies. This interface is supported by a single function (sys_dpm) that provides several policy management functions. It is also supported through the /proc interface. Supported functions are described in the following sections. SYS_DPM NA ME sys_dpm—Manages the policy manager. Gives access to the DPM functions described in the following sections. SYN OP SIS # include <linux/dpm.h> long sys_dpm (int func, struct dpm_param *params); DE SC R IPT ION The sys_dpm function is used from a user-space policy manager to control DPM by specifying power policies to be used by DPM. PA R AM ETE R S The func parameter selects which function to perform. The params parameter points to a control block containing information needed by the selected function. The use of the parameter block is described for each individual function in the sections that follow. /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; };
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 93 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . struct dpm_stats{ dpm_md_count_t count; dpm_md_time_t total_time; dpm_md_time_t start_time; dpm_md_time_t end_time; }; R ETU R N CO DE S Each sys_dpm function returns 0 (zero) on success and -1 on failure. An error code, errno is provided on failure. Most error codes are common to several functions listed within this chapter. Duplicate error codes are described here and other functions reference this section. Note: Note: Only error codes that are unique to that function are explained in the following sections. The following list contains the common DPM error codes: EBADRQC—An unknown function code was passed to sys_dpm in the func parameter. EINVAL—The name of a policy, class, or operating point contains a blank or other white- space character. Some of the individual functions also use EINVAL for additional error conditions. EEXIST—A request to create a named policy, class, or operating point is made and a like- named entity of the same type already exists. ENOENT—A request attempted to identify an existing policy, class, or operating point by name, but an entity of that type and name could not be found. ENOMEM—The kernel could not allocate enough memory to perform the requested function. EFAUL—The kernel could not access the parameter block pointed to by params or memory indirectly addressed by following pointers starting in the parameter block. EACCE—The caller is not the root user. TH E / PR OC IN TER F A C E The individual functions can also be accessed by reading and writing files in /proc/driver/dpm as explained in the sections that follow.
DP M AP I S sys-dpm APIs Interface 94 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_INIT NA ME DPM_INT—Initializes Dynamic Power Management. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_INIT, dpm_param_t *params); DE SC R IPT ION Initializes DPM. A call to DPM_INIT must precede all other DPM_* calls. If DPM_TERMINATE is called then a call to DPM_INIT must precede all other DPM_* calls. DPM_INIT does not block. PA R AM ETE R S Use the DPM_INIT function code with sys_dpm to perform this function. The params parameter is ignored and must be set to NULL. R ETU R N CO DE S DPM_INIT returns 0 (zero) on success and -1 on failure. The following error codes are used: EALREADY—DPM is already initialized. EFAULT—The params value is set to a value other than NULL, and the kernel could not access the parameter block pointed to by params. DI SC US SIO N DPM_INIT does not activate DPM. To activate DPM, use DPM_SET_POLICY. TH E / PR OC IN TER F A C E Write init to /proc/drivers/dpm/cmd to perform this function.
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 95 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXA MP L E U SE The following example program initializes DPM. # include <stdio.h> # include <linux/dpm.h> int main (int argc, char** argv) { /* initialize DPM */ if (sys_dpm(DPM_INIT,0)) { perror("policy manager"); printf("DPM_INIT failedn"); return 1; } } The following example shell script uses /proc/driver/dpm to perform this function: # !/bin/bash # # Initialize DPM. echo init > /proc/driver/dpm/cmd || echo Failed to initialize DPM
DP M AP I S sys-dpm APIs Interface 96 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_TERMINATE NA ME DPM_TERMINATE—Terminates DPM and uninstalls all policies, classes, and operating points. SYN OP SIS # include <linux/dpm.h> int sys_dpm (DPM_TERMINATE, struct dpm_param *params); DE SC R IPT ION Terminates DPM control of the system and uninstalls all policies, classes, and operating points. The system continues to run at the operating point in effect at the time DPM_TERMINATE completes. Most other DPM_* functions will fail once DPM has been terminated. To resume DPM control of the system and allow other DPM_* functions to operate, you must perform the following: 1 The DPM_INIT function must be called. 2 New policies, classes, and operating points must be created using the DPM_CREATE_* functions. 3 The DPM_SET_POLICY function must be called to specify the active policy. DPM_TERMINATE may block. PA R AM ETE R S Use the DPM_TERMINATE function code with sys_dpm to perform this function. The params parameter is ignored and must be set to NULL. R ETU R N CO DE S DPM_TERMINATE returns 0 (zero) on success and -1 on failure. The following error codes are used:
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 97 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EFAULT—parms is set to a value other than NULL and the kernel could not access the parameter block pointed to by params. DI SC US SIO N If you want to force a specific operating point, create and activate a simple policy where all classes map to the desired operating point. Then use DPM_TERMINATE. The operating point will remain in effect until the DPM is re-initialized (using DPM_INIT) and re- activated (using DPM_SET_POLICY) unless changed by something outside the DPM control. See also “DPM_DISABLE” on page 98. TH E / PR OC IN TER F A C E Write terminate to /proc/driver/dpm/cmd to perform this function. EXA MP L E U SE The following example program terminates the DPM. # include <stdio.h> # include <linux/dpm.h> int main (int argc, char** argv) { /* initialize the DPM */ if (sys_dpm(DPM_TERMINATE,0)){ perror ("policy_manager”); printf("DPM_TERMINATE failedn”); return 1; } return 0; } The following example shell script uses /proc/driver/dpm/cmd to perform this function. # !/bin/bash # # Terminate the Dynamic Power Manager. echo terminate > /proc/driver/dpm/cmd
DP M AP I S sys-dpm APIs Interface 98 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_DISABLE NA ME DPM_DISABLE—Temporarily disables DPM. SYN OP SIS # include <linux/dpm.h> int sys_dpm (DPM_DISABLE, struct dpm_param *params); DE SC R IPT ION Temporarily disables DPM control of the system. The system continues to run at the operating point in effect at the time DPM_DISABLE completes. The active policy is remembered and re-activated when DPM_ENABLE is called. DESTROY_POLICY is prevented from destroying the active policy even while the DPM is disabled. To re-enable DPM control of the system with the currently installed polices, classes, and operating points, call DPM_ENABLE. Use DPM_TERMINATE and DPM_INIT to start over with new policies, classes, and operating points. DPM_DISABLE does not block. PA R AM ETE R S Use the DPM_DISABLE function code with sys_dpm to perform this function. The params field is unused and must be set to NULL. R ETU R N CO DE S DPM_DISABLE returns 0 (zero) on success and -1 on failure. EFAULT—parms is set to a value other than NULL, and the kernel could not access the parameter block pointed to by params.
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 99 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DI SC US SIO N If you want to force a specific operating point, you must create and activate a simple policy where all classes map to the desired operating point. Then use DPM_DISABLE. The operating point will remain in effect until the next DPM_ENABLE unless changed by something outside the DPM control. TH E / PR OC IN TER F A C E Write disable to /proc/driver/dpm/cmd to perform this function. EXA MP L E U SE The following example program disables DPM. # include <stdio.h> # include <linux/dpm.h> int main (int argc, char** argv) { sys_dpm (DPM_DISABLE, 0); return 0; } The following example shell script uses /proc/driver/dpm/cmd to perform this function. # !/bin/bash # # Temporarily disable the Dynamic Power Manager. echo disable > /proc/driver/dpm/cmd
DP M AP I S sys-dpm APIs Interface 100 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_ENABLE NA ME DPM_ENABLE—Re-enables DPM after DPM_DISABLE is used. SYN OP SIS # include <linux/dpm.h> int sys_dpm (DPM_ENABLE, struct dpm_param *params); DE SC R IPT ION Re-enable DPM after a DPM_DISABLE. The policy that was active at the time of the DPM_DISABLE is re-activated. DPM_ENABLE may block. PA R AM ETE R S Use the DPM_ENABLE function code with sys_dpm to perform this function. The params field is unused and must be set to NULL. R ETU R N CO DE S If DPM was not disabled or if there is no active policy selected, DPM_ENABLE ignores the situation, does nothing, and returns zero. DPM_DISABLE returns 0 (zero) on success and -1 on failure. EFAULT—Params is set to a value other than NULL, and the kernel could not access the parameter block pointed to by params. EXA MP L E U SE The following example program enables DPM. # include <stdio.h> # include <linux/dpm.h> int main (int argc, char** argv) { sys_dpm (DPM_ENABLE) return 0; }
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 101 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The following example shell script uses /proc/driver/dpm/cmd to perform this function. # !/bin/bash # # Re-enable the Dynamic Power Manager. echo enable > /proc/driver/dpm/cmd
DP M AP I S sys-dpm APIs Interface 102 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_CREATE_OPT NA ME DPM_CREATE_OPT—Creates and installs an operating point. SYN OP SIS # include <linux/dpm.h> int sys_dpm (DPM_CREATE_OPT, struct dpm_param *params); DE SC R IPT ION Creates a named operating point from an array of power parameters and installs it in DPM. The operating point name must be unique. DPM_CREATE_OPT may block. PA R AM ETE R S Use the DPM_CREATE_OPT function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; };
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 103 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The following parameter fields are used: name—Names the operating point. The name must not contain any blanks or other whitespace characters. pp—Points to an array of machine-dependent, machine-defined parameters. The number of required parameters is given by DPM_PP_NBR. It is (or was anyway) in the machine- specific portion on operating points that describe the power parameters, will check whether that info still appears. The other params fields are not used. R ETU R N CO DE S DPM_CREATE_OPT returns 0 (zero) on success and -1 on failure. The following error codes are defined: EINVAL—The specified power parameters were invalid or inconsistent for the system, and the operating point could not be initialized by the machine-dependent code. others—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E Write create_opt <op_name> <param_1> ... <param_n> to /proc/driver/dpm/cmd to create an operating point. EXA MP L E U SE For examples, see Chapter 6, “MontaVista Power Manager Out-of-the-Box.”
DP M AP I S sys-dpm APIs Interface 104 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_CREATE_CLASS NA ME DPM_CREATE_CLASS—Creates and installs a class of named operating points. SYN OP SIS # include <linux/dpm.h> int sys_dpm (DPM_CREATE_CLASS, struct dpm_param *params); DE SC R IPT ION Creates a class of named operating points and installs it into DPM. DPM_CREATE_CLASS may block. PA R AM ETE R S Use the DPM_CREATE_CLASS function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameter fields are used: name—Names the class. The name must not contain any blanks or other white space characters. m_names—Points to an array of operating point names. There must be at least one operating point name specified. The names must not contain any blanks or other white space characters.
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 105 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The current DPM implementation supports one operating point per class. m_count—Provides the number of elements in the array pointed to by m_names. Note: The other params fields are not used. R ETU R N CO DE S DPM_CREATE_CLASS returns 0 (zero) on success and -1 on failure. The following error codes are defined: EINVAL—No operating point name was specified. At least one is required. others—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E Write create_class <class_name> <op_name_1> ... <op_name_n> to /proc/driver/dpm/cmd to create a class. There must be at least one operating point named. EXA MP L E U SE For examples, Chapter 6, “MontaVista Power Manager Out-of-the-Box.”
DP M AP I S sys-dpm APIs Interface 106 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_CREATE_POLICY NA ME DPM_CREATE_POLICY—Creates and installs a policy. SYN OP SIS # include <linux/dpm.h> int sys_dpm (DPM_CREATE_POLICY, struct dpm_param *params); DE SC R IPT ION Creates a named policy from a set of named operating points or classes and installs it into DPM. The operating points or classes are mapped one-to-one with the operating states, so there must be as many operating points or class names given as there are operating states. A policy must not already be installed with the same name. DPM_CREATE_POLICY may block. PA R AM ETE R S Use the DPM_CREATE_POLICY function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameters are used as follows: name—Names the policy. The name must not contain any blanks or other white space characters.
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 107 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . m_names—Points to an array of operating point or class names. There must be names supplied. This number is given by the value DPM_STATES from the header file linux/dpm.h. The names must not contain any blanks or other white space characters, and are specified in the order defined previously. Note: The other params fields are not used. RE TU R N C O D ES DPM_CREATE_POLICY returns 0 (zero) on success and -1 on failure. See “sys_dpm” on page 92. DIS C US SION To replace an existing policy, first use DPM_DESTROY_POLICY to remove it, and then use DPM_CREATE_POLICY to install the new version. DPM_TERMINATE can also be used to remove all installed polices, classes, and operating points, allowing replacements to be installed. DPM_CREATE_POLICY does not activate the policy. It only makes it available to other DPM_* functions. Those functions must choose a policy that has been created by this function. In particular, DPM_SET_POLICY is used to activate DPM, naming a particular policy to be in effect. DPM_CREATE_POLICY can be used at system boot time to initialize DPM with all the policies needed by the system. It can also be used at any time on a running system to add additional power polices. This allows for run-time upgrades. TH E /P RO C INT ER F A CE Write create_policy <policy_name> <name_1> ... <name_n> to /proc/driver/dpm/cmd to create a policy. DPM_STATES classes must be named. EXA MP L E U SE For examples, see Chapter 6, “MontaVista Power Manager Out-of-the-Box.”
DP M AP I S sys-dpm APIs Interface 108 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_DESTROY_POLICY N AM E DPM_DESTROY_POLICY—Removes a policy from DPM. SY NOP SIS #include <linux/dpm.h> int sys_dpm (DPM_DESTROY_POLICY, struct dpm_param *params); D ESC R IP TION Removes a policy from the DPM. The policy must not be the currently active policy. DPM_DESTROY_POLICY may block. PA R AM ET ER S Use the DPM_DESTROY_POLICY function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameters are used as follows: name—Names the policy to be removed. Note: The other params fields are not used.
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 109 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R ETU R N CO DE S DPM_DESTROY_POLICY returns 0 (zero) on success and -1 on failure. The following error codes are defined: EBUSY—The named policy is the currently active policy. others—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to destroy a single policy. The terminate command will destroy all policies. For more information, see “DPM_TERMINATE” on page 96. EXA MP L E U SE The following example program destroys a policy: #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main (int argc, char** argv) { struct dpm_param params; params.name="example"; if (sys_dpm (DPM_DESTROY_POLICY, &params)){ perror("policy manager"); printf("failed to destroy policyn"); return 1; } printf("policy destroyed OKn"); return 0; }
DP M AP I S sys-dpm APIs Interface 110 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_SET_POLICY NA ME DPM_SET_POLICY—Activates a policy to use to power-manage the system. SYN OP SIS # include <linux/dpm.h> int sys_dpm (DPM_SET_POLICY, struct dpm_param *params); DE SC R IPT ION Changes the active policy to a named policy. Activates DPM if not already activated. DPM must have already been initialized using DPM_INIT and the named policy installed using DPM_INSTALL_POLICY. DPM_SET_POLICY may block. PA R AM ETE R S Use the DPM_SET_POLICY function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameter fields are used: name—identifies the policy that DPM should use to power-manage the system. The name must not contain any blanks or other white space characters. Note: The other params fields are not used.
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 111 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TH E / PR OC IN TER F A C E Write set_policy <policy_name> to /proc/driver/dpm/cmd to activate a policy. R ETU R N CO DE S DPM_SET_POLICY returns 0 (zero) on success and -1 on failure. The following error codes are defined: EPERM—The policy cannot be activated because it conflicts with the current device constraints. others—See “sys_dpm” on page 92. EXA MP L E U SE The following example program sets a policy: #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main (int argc, char** argv) { struct dpm_param params; params.name="example"; if (sys_dpm(DPM_SET_POLICY, &params)){ perror("policy manager"); printf("DPM_SET_POLICY failedn"); return 1; } printf("policy set OKn"); return 0; } The following example shell script uses /proc/driver/dpm to perform this function. # !/bin/bash # # activate a policy echo set_policy $1 > /proc/driver/dpm/policy || echo Failed to activate policy.
DP M AP I S sys-dpm APIs Interface 112 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_POLICY NA ME DPM_GET_POLICY—Returns the name of the system’s currently active policy. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_GET_POLICY, struct dpm_param *params); DE SC R IPT ION Returns the name of the system’s currently active policy. DPM_GET_POLICY may block. PA R AM ETE R S Use the DPM_GET_POLICY function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameter field is used: name—Specifies the location to which the policy name is to be copied. A buffer of size DPM_NAME_SIZE must be provided to receive the name. Note: The other params fields are not used.
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 113 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R ETU R N CO DE S DPM_GET_POLICY returns 0 (zero) on success and -1 on failure. The following error codes are defined: ENOENT—There is no active policy. others—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E Read from /proc/driver/dpm/state to get the name of the currently active policy. If DPM is enabled, the following items are reported on a single line: • Name of the current policy. • Current state index. • Current state name. • Current class name. • Current implied operating point name. • Current actual operating point name. • Statistics timer frequency. If DPM is disabled, the following output is displayed: N/A -1 N/A N/A N/A N/A frequency
DP M AP I S sys-dpm APIs Interface 114 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXA MP L E U SE The following example program gets the name of the active policy. #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main(int argc, char** argv) { char policy_name[DPM_NAME_SIZE]={0}; struct dpm_param params; params.name=policy_name; if (sys_dpm (DPM_GET_POLICY, &params)){ perror("policy manager"); printf("failed to get active policy namen"); return 1; } printf("the active policy is %sn",policy_name); return 0; } The following example shell script uses /proc/driver/dpm to perform this function: # !/bin/bash # # get the active policy’s name cat /proc/driver/dpm/state| cut -d “ “-f1
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 115 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_ALL_POLICIES NA ME DPM_GET_ALL_POLICIES—Returns the names of all installed policies. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_GET_ALL_POLICIES, struct dpm_param *params); DE SC R IPT ION Returns the names of the system’s currently installed policies. DPM_GET_ALL_POLICIES may block. PA R AM ETE R S Use the DPM_GET_ALL_POLICIES function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameter field is used: m_names—An array of pointers to the buffers. This array must contain at least as many elements as the number of policies currently installed. The size of each buffer must be
DP M AP I S sys-dpm APIs Interface 116 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_NAME_SIZE. The names of the currently installed policies will be returned in the buffers. Note: The other params fields are not used. R ETU R N CO DE S DPM_GET_ALL_POLICIES returns 0 (zero) on success and -1 on failure. The following error codes are defined: others—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to report all policies. EXA MP L E For examples, see Chapter 6, “MontaVista Power Manager Out-of-the-Box.”
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 117 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_CLASSES NA ME DPM_GET_CLASSES—Returns the names of a policy’s classes. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_GET_CLASSES, struct dpm_param *params); DE SC R IPT ION Returns the class name assigned to each state for the given policy. DPM_GET_CLASSES may block. PA R AM ETE R S Use the DPM_GET_CLASSES function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameter fields are used: name—A pointer to a buffer containing the name of the policy.
DP M AP I S sys-dpm APIs Interface 118 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . m_names—An array of pointers to the buffers. This array must contain DPM_STATES elements. The size of each buffer must be DPM_NAME_SIZE. The names of the classes will be returned in the buffers. The order of the class names is the same as the m_names field for DPM_CREATE_POLICY. Note: The other params fields are not used. R ETU R N CO DE S DPM_GET_CLASSES returns 0 (zero) on success and -1 on failure. The following error codes are defined: EEXIST—The policy does not exist. other—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to report classes for a policy.
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 119 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_SET_TASK_STATE NA ME DPM_SET_TASK_STATE—Changes the DPM state of a process. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_SET_TASK_STATE, struct dpm_param *params); DE SC R IPT ION Changes the DPM state for a particular process. Note: This change of the state might cause an immediate change to the current operating point. DPM_SET_TASK_STATE may block. PA R AM ETE R S Use the DPM_SET_TASK_STATE function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following params fields are used: pid—Process id (PID) of the task for which a task state is to be set. A PID of 0 (zero) indicates that the invoking process is to have its task state set.
DP M AP I S sys-dpm APIs Interface 120 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . task_state—Identifies the task state to be set. It must be an integer in the range - DPM_TASK_LIMIT to +DPM_TASK_LIMIT. Currently this is -4 to +4. The process’ DPM state will be set to DPM_TASK_STATE + task_state. Note: The other params fields are not used. R ETU R N CO DE S DPM_SET_TASK_STATE returns 0 (zero) on success and -1 on failure. The following error codes are defined: ENOENT—No process with the specified PID was found. others—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E Write set_task_state <pid> <task_state> to /proc/driver/dpm/cmd to perform this function. EXA MP L E U SE The following example program sets a task state: #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main(int argc, char** argv) { struct dpm_param params; params.pid=0; /* set this process’ task state */ params.task_state = DPM_TASK_STATE-3; if (sys_dpm (DPM_SET_TASK_STATE, &params)){ perror("policy manager"); printf("DPM_SET_TASK_STATE failedn"); return 1; } printf("task state set OKn"); return 0; }
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 121 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The following example shell script uses /proc/driver/dpm/cmd to perform this function. #!/bin/bash # # set a task state if [ $1 != 0 ] ; then echo set_task_state $1 3 > /proc/driver/dpm/cmd || echo Failed to set task state fi
DP M AP I S sys-dpm APIs Interface 122 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_TASK_STATE NA ME DPM_GET_TASK_STATE—Queries the task state of a particular process. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_GET_TASK_STATE, struct dpm_param *params); DE SC R IPT ION Queries the task state of a process. DPM_GET_TASK_STATE may block. PA R AM ETE R S Use the DPM_GET_TASK_STATE function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; };
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 123 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The following parameter fields are used: pid—Process ID (PID) of the task for which a task state is queried. A PID of 0 (zero) indicates that the invoking process is to have its task state queried. task_state—The state for the process is returned in this field. The value returned has the same definition as the value of the task_state in DPM_SET_TASK_STATE. Note: The other parameter fields are not used. R ETU R N CO DE S DPM_GET_TASK_STATE returns 0 (zero) on success and -1 on failure. The following are defined: ENOENT—No process with the specified PID was found. others—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to read the task state of a process. EXA MP L E U SE The following example program sets a policy: #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main(int argc, char** argv) { struct dpm_param params; params.pid=0; /* get this process’ task state */ if (sys_dpm (DPM_GET_TASK_STATE, &params)){ perror("policy manager"); printf("DPM_GET_TASK_STATE failedn"); return 1; } printf ("This process’ task state is %dn",params.task); return 0; }
DP M AP I S sys-dpm APIs Interface 124 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_POLICY_STATS NA ME DPM_GET_POLICY_STATS—Returns statistics about the use of a policy. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_GET_POLICY_STATS, struct dpm_param *params); DE SC R IPT ION Returns statistics about the use of a policy. DPM_GET_POLICY_STATS may block. PA R AM ETE R S Use the DPM_GET_POLICY_STATS function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following params fields are used: name—The name of the policy for which statistics are being requested. stats—The statistics are returned in the structure pointed to by stats. Note: The other params fields are not used.
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 125 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R ETU R N CO DE S DPM_GET_POLICY_STATS returns 0 (zero) on success and -1 on failure. See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to get statistics for a policy. EXA MP L E U SE The following example program gets statistics for a policy. #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main(int argc, char** argv) { struct dpm_param params; params.name="Example_policy"; params.stats=(char*)malloc(sizeof (struct dpm_stats)); if (sys_dpm(DPM_GET_POLICY_STATS, &params)){ perror("policy manager"); printf("failed to get policy statsn"); return 1; } printf(Statistics for %sn",params.name); printf("activated %lld timesn",params.stats->count); printf("active %lld microsecsn",params.stats->total_time); printf("last activated at %lldn",params.stats->start_time); printf("last de-activated at %lldn",params.stats->end_time); return 0; }
DP M AP I S sys-dpm APIs Interface 126 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_CLASS_STATS NA ME DPM_GET_CLASS_STATS—Returns statistics about the use of a class. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_GET_CLASS_STATS, struct dpm_param *params); DE SC R IPT ION Returns statistics about the use of a class. DPM_GET_CLASS_STATS may block. PA R AM ETE R S Use the DPM_GET_CLASS_STATS function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameter fields are used: name—The name of the class for which statistics are being requested. stats—The statistics are returned in the structure pointed to by stats. Note: The other params fields are not used.
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 127 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R ETU R N CO DE S DPM_GET_CLASS_STATS returns 0 (zero) on success and -1 on failure. For information on error codes, see “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to get statistics for a class. EXA MP L E U SE The following example program gets statistics for a class. #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main(int argc, char** argv) { struct dpm_param params; params.name="Example_class"; params.stats=(char*)malloc(sizeof (struct dpm_stats)); if (sys_dpm(DPM_GET_CLASS_STATS, &params)){ perror("policy manager"); printf("failed to get class statsn"); return 1; } printf(Statistics for %sn",params.name); printf("activated %lld timesn",params.stats->count); printf("active %lld microsecsn",params.stats->total_time); printf("last activated at %lldn",params.stats->start_time); printf("last de-activated at %lldn",params.stats->end_time); return 0; }
DP M AP I S sys-dpm APIs Interface 128 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_OPT_ STATS NA ME DPM_GET_OPT_STATS—Returns statistics about the use of an operating point. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_GET_OPT_STATS, struct dpm_param *params); DE SC R IPT ION Returns statistics about the use of an operating point. DPM_GET_OPT_STATS may block. PA R AM ETE R S Use the DPM_GET_OPT_STATS function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following params fields are used: name—The name of the operating point for which statistics are being requested. stats—The statistics are returned in the structure pointed to by stats. Note: The other params fields are not used.
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 129 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R ETU R N CO DE S DPM_GET_OPT_STATS returns 0 (zero) on success and -1 on failure. For information on error codes, see “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to get statistics for an operating point. EXA MP L E U SE The following example program gets statistics for a operating point. #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main(int argc, char** argv) { struct dpm_param params; params.name="Example_opt"; params.stats=(char*)malloc(sizeof(struct dpm_stats)) if (sys_dpm(DPM_GET_OPT_STATS, &params)){ perror("policy manager"); printf("failed to get opt statsn"); return 1; } printf(Statistics for %sn",params.name); printf("activated %lld timesn",params.stats->count); printf("active %lld microsecsn",params.stats->total_time); printf("last activated at %lldn",params.stats->start_time); printf("last de-activated at %lldn",params.stats->end_time); return 0; }
DP M AP I S sys-dpm APIs Interface 130 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_OS_STATS NA ME DPM_GET_OS_STATS—Returns statistics about the use of all operating states. SYN OP SIS #include <linux/dpm.h> int sys_dpm(DPM_GET_OS_STATS, struct dpm_param *params); DE SC R IPT ION Returns statistics about the use of all operating states. DPM_GET_OS_STATS may block. PA R AM ETE R S Use the DPM_GET_OS_STATS function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following params fields are used: op_state—The operating state for which statistics are being queried. stats—The statistics are returned in the array of structures pointed to by stats. Each element of the array describes an operating state. Note: The other params fields are not used.
..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 131 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R ETU R N CO DE S DPM_GET_OS_STATS returns 0 (zero) on success and -1 on failure. For information on error codes, see “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to get statistics for all operating states. EXA MP L E U SE The following example program gets statistics for an operating state. #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main(int argc, char** argv) { struct dpm_param params; params.op_state=DPM_APPL; params.stats=(char*)malloc(DPM_STATES* sizeof (struct dpm_stats)); if (sys_dpm (DPM_GET_OS_STATS, &params)){ perror("policy manager"); printf("failed to get os statsn"); return 1; } printf (Statistics for %dn",params.op_state); printf ("activated %lld timesn",params.stats->count); printf ("active %lld microsecsn",params.stats->total_time); printf ("last activated at %lldn",params.stats->start_time); printf ("last de-activated at %lldn",params.stats->end_time); return 0;
DP M AP I S sys-dpm APIs Interface 132 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
..... 133 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INDEX A APIs 87 libdpm DPM interface 88 sys-dpm DPM interface 92 Applications DPM startup 72 B Bash shell using 20 C Clock events tracking Definition of 12 Command-line Power Manager tool 18 Commands Accessibility 76 Operating classes 76 Operating points 76 Power policy 76 Power state 77 Syntax for 76 Configuration files Default 36 Installing 35 D Default configuration files Intel PXA27x 37 Power Manager 36 TI-OMAP1710 36 Device constraints Asserting 54 Configuration of 42 Definition of 28 Features of 29 Interfaces for 53 Runtime 67 Specifying 51 Specifying by syfs 53 Device drivers background of 28 interface of 27 Mobilinux DPM 27 Device interactions Design considerations 50 Design with DPM 49 Device constraints design of 51 DPM to userspace design of 55 Driver interfaces 54 Device suspend/resume Definition of 31 Implementation of 68 Power values 44 DPM Hotplug agents for 12 Mobilinux 9 dpmlib Operating classes 63 Operating points 62 Starting applications 72 dpmmgr Configuration file for 35 Syntax for 34 dpmmgr.conf Operating classes 63 Operating points 62 Power policies 65 Driver interfaces to DPM Creating 54 Example for 54 Driver scale callbacks Definition of 30 Design of 45 Dynamic power management Benefits of 10 Clock event tracking 12 Definition of 10 Features of 11 Library of 12 Mobile devices 6 E Embedded Linux Definition of 4 Embedded systems Embedded Linux 4 Power management for 4 Event handeling Definition of 13
134 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event handling suspend/resume 68 F Forced operating points Definition of 29 H Handling of events Implementation of 66 Hotplug agents Definition of 12 I Idle state Operating state type 24 INFOPATH 19 Intel PXA27x Configuration file for 37 DPM for 6 L libdpm DPM API interface 88 Operating policies 65 M MANPATH 18 setting 18 Mobile devices Conserving energy for 6 Dynamic Power Management 6 Mobilinux for 9 Power Management 1 Mobilinux Definition of 10 DPM for 9 Mobilinux DPM APIs 87 Building blocks of 19 Mobilinux DPM features Clock event tracking 12 DPM library 12 Event handling 13 Hotplug agents 12 MontaVista Power Manager 11 Power Manager interface 13 Power profiler plugin 12 Suspend/resume handling 13 Tick elimination 12 Mobilinux DPM library Definition of 12 MontaVista Power Manager Building blocks of 19 Definition of 16 Features of 16 Out-of-the-box 33 Tools for 18 MontaVista Power Manager features Deafult power policies 17 Integrated components 17 User-defined power parameters 17 MontaVista Zone 21 O Operating classes Constraints for 52 Definition of 21, 30 dpmlib 63 dpmmgr.conf 63 Examples of 21 Implementation of 63 sysfs 63 Operating points Constraints for 51 Definition of 20 dpmlib 62 dpmmgr.conf 62 Examples of 21 Forced 29 Parameters 20 sysfs 62 Operating policy Implementation of 66 Operating state types Idle 24 Sleep 23 Task 24 Operating states Architecure of 22 Definition of 22 Types of 23 P Plugin APIs Power Manager tools 18 Policies dpmmgr.conf 65 Idle state 64 Idle-task state 64 Implementation of 64 libdpm 65 sysfs 65 Power event userspace Hotplug agents for 52 Power events notification 61 Power hotplug Agents for 52 Power Management Architecture of 5 Background 1 Benefits of 2 Definition of 3 DPM policy 5 DPM Power Manager 5
..... 135 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Embedded systems 4 Power Manager Applications startup 72 Authomatic startup 72 Building blocks of 19 Default configuration files 36 Definition of 5 Development of 60 Exiting from 35 Installation of 35 Manual startup 72 Out-of-the-box 33 Power Manager 11 Running 72 Startup 71 Power Manager building blocks Design of 41 Driver scale callbacks 45 Hardware study 42 Implementation of 57, 61 Operating points guidelines 43 Power policy 46 Power-related events 46 Promrammable sleep/wakeup sources 47 Sleep/standby behavior 47 Software architecture 44 Suspend/resume device 44 Task states 47 Power Manager building blocks implementation Custom drivers 58 Device constraints 59 Device suspend/resume 68 Driver scale callbacks 59 Handling of events 66 Kernel power events notification 60 Logic for power policy 66 Operating classes 63 Power Manager 60 Power policies 64 Power state modifications 69 Runtime device constraints 67 Power Manager features DPM interface 16 Power Manager interface Definition of 13 Power Manager tools Command-line 18 Plugin APIs 18 Power Managr building blocks Operating classes 21 Operating points 20 Operating states 22 Power parameters 20 Power policy 25 Power policy Architecure of 25 Definition of 25 Designing 46 Plugable power 7 Using Power Manager 44 Power profiler plugin Definition of 12 Power state Modifications 69 Power-related events Design of 46 Profiler Definition of 12 Programmable sleep/wakeup sources Design of 47 R Resume devices levels of 45 Runtime device constraints Example of 67 Implementation of 67 S Sleep Operating state type 23 Sleep/standby behavior Design of 47 Suspend/resume devices Designing 44 Event handling 68 Handling 68 Levels of 45 Suspend/resume handling Definition of 13 sysfs Constraints specification 53 Operating classes 63 Operating points 62 Power policies 65 System suspend/resume Implementation of 68 T Task states Design of 47 Operating state type 24 Tick elimination Definition of 12 TI-OMAP1710 DPM for 6 U Using Power Manager Out-of-the box 33, 34

More Related Content

PDF
Spartan 3e用户手册
zhaojk90
 
PDF
Dell poweredge-rc-s140 users-guide-en-us-nhat-thien-minh
Mr Cuong
 
PDF
Whats-New-VMware-vCloud-Director-15-Technical-Whitepaper
Djbilly Mixe Pour Toi
 
PDF
Ms Patch Man Ch8
gopi1985
 
PDF
Reeldvd User Guide
gueste6b460
 
PDF
Dcp 2000 field-instmanual_000344_v1_5
xacho1
 
PDF
Manual CV41
Codeprint Soluçoes em Identificaçao e Captura de Ddos
 
PDF
Stopping Malware
GFI Software
 
Spartan 3e用户手册
zhaojk90
 
Dell poweredge-rc-s140 users-guide-en-us-nhat-thien-minh
Mr Cuong
 
Whats-New-VMware-vCloud-Director-15-Technical-Whitepaper
Djbilly Mixe Pour Toi
 
Ms Patch Man Ch8
gopi1985
 
Reeldvd User Guide
gueste6b460
 
Dcp 2000 field-instmanual_000344_v1_5
xacho1
 
Manual CV41
Codeprint Soluçoes em Identificaçao e Captura de Ddos
 
Stopping Malware
GFI Software
 

What's hot (20)

PDF
Vrs User Guide
guest121f02
 
PDF
ZebraNet Bridge Enterprise - Manual do Software
UseZ
 
PDF
Plesk Modules
webhostingguy
 
PDF
strength of materials
Mouna Guru
 
PDF
EMC Cisco SAP HANA Appliance Disaster Tolerance
EMC
 
PDF
Inter-Tel Web Conferencing and Remote Support User Guide
Videoguy
 
PDF
AccuProcess Modeler User Guide
D S
 
PDF
Java Complete Reference Fifth Edition
umavanth
 
PDF
Dell Inspiron 7537 Card rời 2GB hỗ trợ đồ họa
LAPTOP TRẦN PHÁT
 
PDF
Spartan-3A/3AN FPGA Starter Kit Board User Guide
Remmy Fuentes Telleria
 
PDF
Windowstweaksguide updated
AngelJulianGomezMend
 
PDF
Power shell desired state configuration for Devops and ALM practitioners
Willy Marroquin (WillyDevNET)
 
PDF
Deep Freeze for Mac User Guide
Faronics
 
PDF
Newfies dialer Auto dialer Software
Areski Belaid
 
PDF
Faronics Deep Freeze Enterprise User Guide
Faronics
 
PDF
Newfies-Dialer : Autodialer software - Documentation version 1.1.0
Areski Belaid
 
PDF
XSLATE_B10_Users_Guide_FINAL
Rochelle Zimmerman
 
PDF
Manual cinema 4 d
Venise Melo
 
PDF
Dell SC4020 and SC9000 All Flash Solutions For MEDITECH Magic, CS 5.x and MT 6.x
Richard Fletcher
 
PDF
Black berry java_sdk-development_guide--1239696-0730090812-001-6.0-us
Reliance Jio USA, Inc.
 
Vrs User Guide
guest121f02
 
ZebraNet Bridge Enterprise - Manual do Software
UseZ
 
Plesk Modules
webhostingguy
 
strength of materials
Mouna Guru
 
EMC Cisco SAP HANA Appliance Disaster Tolerance
EMC
 
Inter-Tel Web Conferencing and Remote Support User Guide
Videoguy
 
AccuProcess Modeler User Guide
D S
 
Java Complete Reference Fifth Edition
umavanth
 
Dell Inspiron 7537 Card rời 2GB hỗ trợ đồ họa
LAPTOP TRẦN PHÁT
 
Spartan-3A/3AN FPGA Starter Kit Board User Guide
Remmy Fuentes Telleria
 
Windowstweaksguide updated
AngelJulianGomezMend
 
Power shell desired state configuration for Devops and ALM practitioners
Willy Marroquin (WillyDevNET)
 
Deep Freeze for Mac User Guide
Faronics
 
Newfies dialer Auto dialer Software
Areski Belaid
 
Faronics Deep Freeze Enterprise User Guide
Faronics
 
Newfies-Dialer : Autodialer software - Documentation version 1.1.0
Areski Belaid
 
XSLATE_B10_Users_Guide_FINAL
Rochelle Zimmerman
 
Manual cinema 4 d
Venise Melo
 
Dell SC4020 and SC9000 All Flash Solutions For MEDITECH Magic, CS 5.x and MT 6.x
Richard Fletcher
 
Black berry java_sdk-development_guide--1239696-0730090812-001-6.0-us
Reliance Jio USA, Inc.
 
Ad

Viewers also liked (18)

PPTX
Wishing you a happy Thanksgiving
Debera Salam, CPP
 
PDF
Knowurture Introduction web ver 1.0
Madhukar Kalsapura
 
PPS
Beautiful Hearts
Imtiaz Ahmed
 
PPT
presentation
Нигяр Нармин
 
PDF
McAfee EMM vs. Good Competitive Reviews
Sholeh Gregory
 
PPTX
Presentación3
scifuentesarias
 
PPT
Places
kar1322
 
PPSX
Gm s3
caminantapeu
 
PDF
Roger
Xancale Flores
 
PPTX
How to move Interspire to Magento using LitExtension tool
LitExtension
 
PPTX
Nuevas tecnologias cami
camiykrishi
 
PDF
Bloomberg BNA Daily Tax Report NY Payroll Audits are on the Rise 5-13-2016 - ...
Debera Salam, CPP
 
PPT
La telefonia
ricper911
 
PDF
Sun Internet Mail Server 4.0 Concepts Guide
Sholeh Gregory
 
PDF
Sihi etal-bg-13-1733-2016
Debjani Sihi
 
PDF
Sholeh gregory-technical-writer
Sholeh Gregory
 
PDF
Trafik Şaka Yapmaz
İsmail RÜZGAR
 
DOC
Solucionario del cuaderno del alumno. bach1.2016
oliviaradop
 
Wishing you a happy Thanksgiving
Debera Salam, CPP
 
Knowurture Introduction web ver 1.0
Madhukar Kalsapura
 
Beautiful Hearts
Imtiaz Ahmed
 
presentation
Нигяр Нармин
 
McAfee EMM vs. Good Competitive Reviews
Sholeh Gregory
 
Presentación3
scifuentesarias
 
Places
kar1322
 
Gm s3
caminantapeu
 
Roger
Xancale Flores
 
How to move Interspire to Magento using LitExtension tool
LitExtension
 
Nuevas tecnologias cami
camiykrishi
 
Bloomberg BNA Daily Tax Report NY Payroll Audits are on the Rise 5-13-2016 - ...
Debera Salam, CPP
 
La telefonia
ricper911
 
Sun Internet Mail Server 4.0 Concepts Guide
Sholeh Gregory
 
Sihi etal-bg-13-1733-2016
Debjani Sihi
 
Sholeh gregory-technical-writer
Sholeh Gregory
 
Trafik Şaka Yapmaz
İsmail RÜZGAR
 
Solucionario del cuaderno del alumno. bach1.2016
oliviaradop
 
Ad

Similar to DPM-mobilinux (20)

PDF
inSync Cloud Administrator's Guide 5.1
druva_slideshare
 
PDF
ISE-802.1X-MAB
Emerson Barros Rivas
 
PDF
Getting Started Guide
webhostingguy
 
PDF
Presentation data center design overview
xKinAnx
 
PDF
Installing and conf guide for hp sm connector
TheEnferRimbaud
 
PDF
Faronics Anti-executable Standard User Guide
Faronics
 
PDF
Eva9000 9150 um_27_mar09
Billy81
 
PDF
Incisive_Enterprise_Manager_Getting_Star.pdf
Mohammed Moufti
 
PDF
Coherence developer's guide
wangdun119
 
PDF
Presentation data center deployment guide
xKinAnx
 
PDF
Admin
katikireddy
 
PDF
Hfs to zfs migration
satish090909
 
PDF
Prometheus Up Running Infrastructure And Application Performance Monitoring 2...
rzeczycozin
 
PDF
Informatica installation guide
cbosepandian
 
PDF
Plesk 8.1 for Linux/UNIX
webhostingguy
 
PDF
Pc 811 transformation_guide
Venkat Madduru
 
PDF
Fscm91sbil b1109
shivram2511
 
PDF
Delta v emerson_getting_started
JoseLuisPallyZegarra
 
PDF
121poug
Nawaz Sk
 
PDF
Plesk 8.0 for Linux/UNIX
webhostingguy
 
inSync Cloud Administrator's Guide 5.1
druva_slideshare
 
ISE-802.1X-MAB
Emerson Barros Rivas
 
Getting Started Guide
webhostingguy
 
Presentation data center design overview
xKinAnx
 
Installing and conf guide for hp sm connector
TheEnferRimbaud
 
Faronics Anti-executable Standard User Guide
Faronics
 
Eva9000 9150 um_27_mar09
Billy81
 
Incisive_Enterprise_Manager_Getting_Star.pdf
Mohammed Moufti
 
Coherence developer's guide
wangdun119
 
Presentation data center deployment guide
xKinAnx
 
Admin
katikireddy
 
Hfs to zfs migration
satish090909
 
Prometheus Up Running Infrastructure And Application Performance Monitoring 2...
rzeczycozin
 
Informatica installation guide
cbosepandian
 
Plesk 8.1 for Linux/UNIX
webhostingguy
 
Pc 811 transformation_guide
Venkat Madduru
 
Fscm91sbil b1109
shivram2511
 
Delta v emerson_getting_started
JoseLuisPallyZegarra
 
121poug
Nawaz Sk
 
Plesk 8.0 for Linux/UNIX
webhostingguy
 

More from Sholeh Gregory (6)

PDF
Sholeh gregory-technical-writer
Sholeh Gregory
 
PDF
dcVAST-Case-Study
Sholeh Gregory
 
PDF
Sun Internet Mail Server 4.0 installation Guide
Sholeh Gregory
 
PDF
PN985-MG3500-SDK-Guide
Sholeh Gregory
 
PDF
PN984-MG3500-Programming-Getting-Started-Guide
Sholeh Gregory
 
PDF
IKANOW System Architecture Guide
Sholeh Gregory
 
Sholeh gregory-technical-writer
Sholeh Gregory
 
dcVAST-Case-Study
Sholeh Gregory
 
Sun Internet Mail Server 4.0 installation Guide
Sholeh Gregory
 
PN985-MG3500-SDK-Guide
Sholeh Gregory
 
PN984-MG3500-Programming-Getting-Started-Guide
Sholeh Gregory
 
IKANOW System Architecture Guide
Sholeh Gregory
 

DPM-mobilinux

  • 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 3 7 E A S T A RQU E S A V E NU E , S U NN Y V A L E , CA 94 0 8 5 Mobilinux™ 4.0 Dynamic Power Management Programmer’s Guide 1237 East Arques Avenue, Sunnyvale, CA 94085
  • 2. C O P Y R I G HT Copyright © 2005 MontaVista Software, Inc. All Rights Reserved. This product and related documentation are protected by copyright and distributed under licenses controlling its use, copying, and distribution. No part of this product or its related documentation may be reproduced in any form or by any means except under such licenses and this copyright notice. MontaVista Software, Inc. makes no representations or warranties with respect to the contents or use of this manual, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. MontaVista Software, Inc. makes no representations or warranties with respect to MontaVista® Linux® , and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. MontaVista is a registered trademark of MontaVista Software, Inc. The registered trademark Linux is used pursuant to a sublicense from the Linux Mark Institute, the exclusive licensee of Linus Torvalds, owner of the mark on a world-wide basis. All other names mentioned herein — trademarks, registered trademarks, and service marks — are the property of their respective owners. R E V I S I O N H I S T O R Y This document was prepared by MontaVista Software, Inc. C O NT AC T You are welcome to contact us: sales@mvista.com Edition Version Revision Documentation Release Date Notes ............................................................. Mobilinux 4.0.2 A September 13, 2005 First Release
  • 3. ..... iii . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CONTENTS PREFACE ...............................................................................15 Who Should Read this Manual?................................................................................16 Conventions.................................................................................................................16 Mobilinux 4.0 Documentation Set...........................................................................17 Mobilinux 4.0 Documentation Set Locations ..........................................................17 Other Related MontaVista Documentation .............................................................17 Accessing Online Documentation ...........................................................................18 Accessing man Pages....................................................................................................18 Accessing HTML Man Pages .....................................................................................19 Accessing info Pages....................................................................................................19 Shell Prompts...............................................................................................................20 Using a Bash Shell ........................................................................................................20 Support .........................................................................................................................20 MontaVista Zone..........................................................................................................21 Contact..........................................................................................................................21 Third-Party Documentation......................................................................................21 1 Power Management Background Technology ................1 Background....................................................................................................................2 Power Management Background................................................................................. 2 Why Dynamic Power Management is Needed .......................................................... 2 What is Dynamic Power Management?.....................................................................3 What is an Embedded System?...................................................................................3 What is Embedded Linux?............................................................................................ 4 Dynamic Power Management for Embedded Systems ........................................... 4
  • 4. iv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Architectural Summary.................................................................................................4 What is a DPM Policy?.................................................................................................. 5 What is a DPM Power Policy Manager?..................................................................... 5 Dynamic Power Management and Mobile Devices ................................................5 Mobile Devices Conserving Energy ............................................................................ 6 Plugable Power Management Policies......................................................................... 6 2 What is Mobilinux Dynamic Power Management?.........9 What is Mobilinux?.....................................................................................................10 What is Mobilinux Dynamic Power Management? ...............................................10 Mobilinux Dynamic Power Management Benefits................................................10 Mobilinux Dynamic Power Management Features ...............................................11 MontaVista Power Manager .......................................................................................11 DPM Library .................................................................................................................12 Hotplug Agents.............................................................................................................12 Clock Events Tracking ................................................................................................12 Power Profiler Plugin...................................................................................................12 Tick Elimination...........................................................................................................12 High-level Power Manager Interface.........................................................................13 Event Handling.............................................................................................................13 Suspend and Resume Handling..................................................................................13 3 What is MontaVista Power Manager? ...........................15 What is MontaVista Power Manager?......................................................................16 MontaVista Power Manager Features......................................................................16 DPM Interface ..............................................................................................................16 Integrated Components...............................................................................................17 Default Operating Points ............................................................................................17 User-Defined Power Parameters................................................................................17 Default Power Policies.................................................................................................17 Overview of MontaVista Power Manager Tools ...................................................18 Command-Line.............................................................................................................18 Plugin APIs....................................................................................................................18
  • 5. ..... v . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 MontaVista Power Manager Building Blocks ................19 Operating Points ........................................................................................................20 Operating Points Parameters......................................................................................20 Operating Points Examples ........................................................................................21 Operating Classes........................................................................................................21 Operating States..........................................................................................................22 What is an Operating State?........................................................................................22 Operating States Architecture.....................................................................................22 Operating States Types................................................................................................23 DPM Power Policy.....................................................................................................25 What is a DPM Power Policy?....................................................................................25 Power Policy Architecture...........................................................................................25 5 DPM Device Driver Interfaces .........................................27 DPM Device Driver Background.............................................................................28 DPM Device Constraints Background....................................................................28 How Device Constraints Work..................................................................................28 Device Constraints Features.......................................................................................29 Forced Operating Points............................................................................................29 DPM Classes................................................................................................................30 DPM Driver Scale Callbacks.....................................................................................30 Driver Model and Device Suspend/Resume..........................................................31 6 MontaVista Power Manager Out-of-the-Box ................33 Using Power Manager Out-of-the-Box...................................................................34 Installing Configuration File......................................................................................35 Exiting your Power Manager.....................................................................................35 Power Manager Default Configuration Files..........................................................36 TI-OMAP1710 Board Configuration........................................................................36 Intel PXA27x Mainstone Board Configuration.......................................................37
  • 6. vi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Designing Your Power Manager Building Blocks..........41 Studying Your Hardware’s Power Management Characteristics .........................42 Configuring Your Board..............................................................................................42 Device Power Constraints...........................................................................................42 Guidelines for Setting up DPM Operating Points.................................................42 Designing High-Level Power Management Software Architecture....................43 Designing Power Policy with MontaVista Power Manager...................................44 Designing DPM Suspend/Resume Devices...........................................................44 Specifying Power State Values....................................................................................45 Designing DPM Driver Scale Callbacks..................................................................45 Designing Power-Related Events.............................................................................45 Designing Power Policies ..........................................................................................46 Designing Programmable Sleep/Wakeup Sources ................................................46 Designing DPM Task States......................................................................................47 Designing Sleep/Standby Behavior .........................................................................47 8 Designing Device Interactions with DPM ......................49 Design Considerations ...............................................................................................50 Hardware Restrictions..................................................................................................50 Constraints v.s. Event Messages ................................................................................50 Handeling Conflicting Devices...................................................................................50 Scale Callback................................................................................................................51 Specifying Device Constraints ..................................................................................51 Constraints for an Operating Point ...........................................................................51 Constraints for an Operating Class............................................................................52 Specifying Power Event Userspace Notification...................................................52 Power Hotplug Agents ................................................................................................52 Specifying Device Constraints Interfaces................................................................52 Specifying Constraints through SYSFS.....................................................................53 Asserting Constraints...................................................................................................53 Creating Driver Interface to DPM...........................................................................54 Exporting Driver DPM to Userspace......................................................................55
  • 7. ..... vii . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Implementing Your Power Manager Building Blocks...57 Implementing Power Management for Custom Drivers......................................58 Implementing Precompiled Device Constraints....................................................59 Implementing Driver Scale Callbacks......................................................................59 Implementing Notification of Kernel Power Events............................................60 Developing Your Power Manager............................................................................60 Implementing Notification of Application Power Events...................................61 Implementing DPM Operating Points....................................................................61 Examples........................................................................................................................61 Implementing DPM Operating Classes...................................................................62 Examples........................................................................................................................63 Implementing DPM Operating Policies..................................................................63 Examples........................................................................................................................64 Implementing Policy Manager Handling of Events ..............................................65 Implementing Other Logic for Determining Power Policy.................................66 Implementing Runtime Device Constraints ...........................................................66 Implementing System Suspend/Resume ................................................................67 Event Handling.............................................................................................................67 Suspend and Resume Handling..................................................................................68 Implementing Device Power State Modifications .................................................68 10 Starting Your Power Manager ......................................69 Running Your Power Manager.................................................................................70 Starting Power Manager Manually .............................................................................70 Starting Power Manager Automatically.....................................................................70 Starting Applications with DPM interactions.........................................................70 dpmlib.............................................................................................................................70 /proc...............................................................................................................................71 Testing Your Power Management System..............................................................71 Activating a Policy ......................................................................................................72 Using dpmmgr ..............................................................................................................72 Using sysfs .....................................................................................................................72
  • 8. viii . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Power Manager Commands ...........................................73 Power Manager commands Accessibility................................................................74 Commands Syntax........................................................................................................74 Operating Points and Classes Commands..............................................................74 Power Policy Commands...........................................................................................74 Power State Commands.............................................................................................75 Device Power State Commands ...............................................................................75 Device Constraint Commands..................................................................................75 System Status Commands..........................................................................................75 Power Events Commands.........................................................................................76 12Plugin Commands and APIs............................................77 Power Manager Commands Accessibility...............................................................78 Commands Syntax........................................................................................................78 Plugin Commands.......................................................................................................78 Plugin APIs..................................................................................................................79 13Power Manager Profiler Plugin ......................................81 DPM-Profiler Plugin Commands.............................................................................82 Terms Definitions.......................................................................................................83 Power Profile.................................................................................................................83 Power Metric.................................................................................................................83 14 DPM APIs .........................................................................85 libdpm DPM APIs Interface.....................................................................................86 int dpm_init() ................................................................................................................86 int dpm_set_state (char *statename) .........................................................................86 int dpm_create_op (char *opname, char *params).................................................86 int dpm_set_op_param (char *opname, char *paramname, int paramvalue).....87 int dpm_get_op_param (char *opname, char *paramname, char *buf, size_t bufsiz)...................................................87 int dpm_create_class (char *classname, char *opnames).......................................87
  • 9. ..... ix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . int dpm_create_policy (char *policyname, char *opsclasses)................................88 int dpm_set_policy_state_map (char *policyname, char *statename, char *opclass) .........................................................88 int dpm_get_policy_state_map(char *policyname, char *statename, char *buf, size_t bufsiz).........................................88 int dpm_set_active_policy (char *policyname)........................................................89 int dpm_get_active_policy (char *buf, size_t bufsiz)..............................................89 sys-dpm APIs Interface..............................................................................................90 sys_dpm .........................................................................................................................90 DPM_INIT ...................................................................................................................92 DPM_TERMINATE ..................................................................................................93 DPM_DISABLE..........................................................................................................95 DPM_ENABLE...........................................................................................................97 DPM_CREATE_OPT................................................................................................98 DPM_CREATE_CLASS..........................................................................................100 DPM_CREATE_POLICY.......................................................................................101 DPM_DESTROY_POLICY ...................................................................................103 DPM_SET_POLICY ................................................................................................106 DPM_GET_POLICY...............................................................................................108 DPM_GET_ALL_POLICIES.................................................................................110 DPM_GET_CLASSES.............................................................................................112 DPM_SET_TASK_STATE.....................................................................................113 DPM_GET_TASK_STATE....................................................................................116 DPM_GET_POLICY_STATS................................................................................118 DPM_GET_CLASS_STATS...................................................................................120 DPM_GET_OPT_ STATS......................................................................................122 DPM_GET_OS_STATS ..........................................................................................124 INDEX..................................................................................133
  • 10. x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  • 11. 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PREFACE Welcome to the Mobilinux 4.0 Dynamic Power Management Programmer’s Guide! The MontaVista Dynamic Power Management (DPM) feature provides applications and tools to control power policy for power-conscious Linux-based mobile devices. Additionally, it enables rapid modifications to power parameters of these systems, such as their CPU, bus frequency, and core voltage scaling. The Mobilinux 4.0 Dynamic Power Management Programmer’s Guide provides clear and concise information about the DPM background technology, MontaVista DPM features, concepts, out-of-the-box Power Manager, and tasks needed to design and to implement user-defined power management for two supported software development platforms: TI-OMAP 1710 and Intel PXA27x. The following topics are covered in Preface: • “Who Should Read this Manual?” • “Conventions” • “Mobilinux 4.0 Documentation Set” • “Accessing Online Documentation” • “Shell Prompts” • “Support” • “Contact” • “Third-Party Documentation”
  • 12. Who Should Read this Manual? 16 Who Should Read this Manual? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . W H O S H O U LD R E A D T HI S M A N U A L ? The intended audience for this guide are systems developers able to build embedded systems using one of the following operating systems: • Linux • Microsoft® Windows C O N V E N T I O N S The following list contains typographical conventions used throughout this manual: Convention Meaning Example .............................................................. Courier Programming code, commands on-screen output, tools, applications Edit your .login file. Type ls -l to list all files. machine_name% test.doc. Bold Courier What you type, File names machine_name% su dpmmgr.log Courier Italics Variables to be replace with actual values set policy <name> italics new terms, word to be emphasized A forced operating point ..............................................................
  • 13. ..... Mobilinux 4.0 Documentation Set Mobilinux 4.0 Documentation Set 17 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . M O BI L I N UX 4 . 0 D O C UM E N T A T I O N S E T The Mobilinux 4.0 Dynamic Power Management Programmer’s Guide is a companion document to the following manuals in the Mobilinux documentation set: • Mobilinux 4.0 Release Notes—Contains open issues and late-breaking product-related information that are not published in the product manuals. • Mobilinux 4.0 Installation Guide—Provides step-by-step installation instructions. • Mobilinux 4.0 Kernel Developer's Guide—Provides information on kernel development and debugging features and instructions on how to use them. • Mobilinux 4.0 Development Environment Guide—Defines the MontaVista Software development environment and provides an overview of the development life cycle. • Mobilinux 4.0 Kernel Migration Guide—Provides the instructions needed to migrate from the Linux 2.4 kernel to the 2.6 kernel. It a list of obsolete and upgraded features. • Mobilinux 4.0 Platform Developer’s Guide—Provides information on how to integrate system components (file system, kernel, applications) and deploy them to a target system. • Mobilinux 4.0 Security Reference Guide—Provides information on locating MontaVista Security Alerts and provides methods for developing a secure system. • Mobilinux 4.0 Event Broker Programmer’s Guide—Provides instructions and common error codes for the MontaVista Linux Event Broker. MOBILINUX 4.0 DOCUMENTATION SET LOCATIONS Mobilinux 4.0 online documentation are provided on the product CD in the following directories: • /opt/montavista/mobilinux/devkit/<architecture>/<processor>/doc • /opt/montavista/common/doc OTHER RELATED MONTAVISTA DOCUMENTATION MontaVista Web site at http://www.mvista.com as well as “MontaVista Zone” at http://w.ww.support.mvista.com offer up-to-date information on a variety of topics, including online product documentation, late-breaking updates, product information, technical whitepapers, and press coverage.
  • 14. Accessing Online Documentation 18 Accessing Online Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A C C E S S I N G O N L I N E D O CU M E N T A T I O N In addition to mobilinux documentation set and other related information available on the company’s Web site, the following documentation is also available online: • Manual (man) pages—Help pages that provide a description of the application, its options and usage, links to related documentation, and a list of known problems. • Information (info) pages—Online manuals. Note: If you install mobilinux in a different directory, replace the /opt directory with the location you choose. ACCESSING MAN PAGES Mobilinux 4.0 provides man pages in HTML and in standard ASCII formats, located in the following directories: SE TTI NG U P Y OUR M AN P AT H Before accessing standard man pages, first you must include their location (MANPATH) in your executable search path. To avoid a conflict with the host man pages, creating an alias for the mobilinux man pages is recommended. To create an alias for the mobilinux MANPATH, first open a Bash shell and then enter: alias mvman=”MANPATH=/opt/montavista/mobilinux/man man” VIE W ING A SC II MA N PA GE S To display the ASCII version of the man pages, first open a Bash shell and then enter mvman <application> to display the first page or enter mvman -a <application> to display all application man pages. Application Directory ............................................................. Target /opt/montavista/mobilinux/devkit/<architecture>/ <processor>/target/usr/share/man Common /opt/montavista/common/man Cross-Development /opt/montavista/mobilinux/devkit/<architecture>/ <processor>/man .............................................................
  • 15. ..... Accessing Online Documentation Accessing Online Documentation 19 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ACCESSING HTML MAN PAGES To access the HTML man pages, enter /opt/montavista/mobilinux/devkit/html/ in a Web browser. ACCESSING INFO PAGES The mobilinux application info pages are located in the following directories: SE TTI NG U P Y OUR I NF OP AT H Before you can access info pages, you must include their location at INFOPATH into your executable search path. To avoid a conflict with the host info pages, creating an alias for the mobilinux info pages is recommended. To create an alias for the mobilinux INFOPATH, first open a Bash shell and then enter: alias mvinfo=”INFOPATH=/opt/montavista/mobilinux/info info” VIE W ING A SC II IN FO PA G ES To display the ASCII version of the info pages, first open a Bash shell and then enter: mvinfo <application> Application Directory ............................................................. Target /opt/montavista/mobilinux/devkit/<architecture>/ <processor>/target/usr/share/info Common /opt/montavista/common/info Cross-Development /opt/montavista/mobilinux/devkit/<architecture>/ <processor>/info .............................................................
  • 16. Shell Prompts 20 Shell Prompts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . S H E L L P R O M P T S The following table shows the default system prompt and superuser prompt for the C shell, Bourne shell, and Korn shell interfaces: USING A BASH SHELL The instructions throughout this manual use a Bash shell terminal window. To open a Bash shell on a Windows host, open the Start menu and select Programs > MontaVista > Bash Shell. S U P P O RT In-depth technical assistance is available. Customers can request help with installation, configuration, usage and other questions concerning Mobilinux 4.0. Generally, this software is fully supported for application developers doing development of their project. General technical assistance is only provided for third-party products that MontaVista Software recommends for use with Mobilinux 4.0. This service may range from answering questions to providing workarounds. Because MontaVista Software is not responsible for the development of these third-party products, some issues might require input from the original application vendor. MontaVista only provides assistance for these products when they are being used with Mobilinux 4.0. MontaVista Software, Inc. wants your input regarding how well we are performing, as well as any suggestions or comments that you have for improvement. Please e-mail comments to suggestions@mvista.com. Shell Prompt ............................................................. C shell prompt machine_name% C shell superuser prompt machine_name# Bourne shell and Korn shell prompt $ Bourne shell and Korn shell superuser prompt # .............................................................
  • 17. ..... Contact Contact 21 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MONTAVISTA ZONE MontaVista Zone is the MontaVista Software, Inc. subscriber-only support Web site. It provides focused information about embedded Linux systems, access to MontaVista developed software, and provides answers to frequently asked questions (FAQs) about products and services. MontaVista Zone is located at http://support.mvista.com. C O NT AC T You are welcome to contact MontaVista. For suggestions, please send e-mail to suggestions@mvista.com. For questions about future availability, what you purchased, supported targets and so forth, please contact your sales manager or generally you can e-mail sales@mvista.com. If you purchased a named contact seat, contact information for MontaVista Technical Support is located under the Contact Support link on MontaVista Zone. If you cannot see this link, then you purchased a platform developer or application developer seat and you will need to contact your designated named contact. T H I RD -P AR T Y DO CU M E N T A T I O N A variety of Linux, Unix, and Java documentation is currently available. The following list contains some sources of available third-party documentation: • O’Reilly Safari—Publishes computer software developer books (http://safari.oreilly.com/). • Addison Wesley professional publications—Publishes professional computer books (http://www.awprofessional.com/). • Prentice Hall—Publishes academic and reference books (http://www.awprofessional.com/). • Wrox—Publishes Programmer-to-programmer books (http://www.wrox.com/WileyCDA/). • Online news groups—Provides a forum for computer-focused news groups (for example, Google, Yahoo, and similar services). For examples of Google news groups, see http://groups.google.com/. Note: This list are provided for your convenience only—MontaVista Software does not specifically endorse them.
  • 18. Third-Party Documentation 22 Third-Party Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  • 19. 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 POWER MANAGEMENT ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BACKGROUND TECHNOLOGY This chapter provides brief descriptions of the concepts of the Dynamic Power Management (DPM) background technology in embedded Linux environments that apply to mobile devices. Understanding these DPM background technology concepts permits better utilization of the Mobilinux Dynamic Power Management feature. The following topics are covered in this chapter: • “Background” • “What is Dynamic Power Management?” • “What is an Embedded System?” • “Architectural Summary” • “Dynamic Power Management and Mobile Devices”
  • 20. POWER M A N A G EM E N T B A C K G R OU N D TE C HN O LOG Y Background 2 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B AC K G R O U ND Topics in this section include: • “Power Management Background” • “Why Dynamic Power Management is Needed” POWER MANAGEMENT BACKGROUND Power management was first introduced in laptop computers to allow longer operating times while running on battery power; later, it was brought into the desktop PC market. Many early power management systems had long recovery times, difficult configuration methods, and low energy savings. Since the early days, however, power management has improved rapidly, becoming more powerful, reliable, and easier to use. It now delivers considerably more energy savings. Power management in personal computers relies on the fact that for most of the time a typical PC is on, it is not doing anything productive. As long as the computer is idle, energy use can be reduced without interfering with work. Common methods to reduce energy usage are slowing down or stopping the processor clock, spinning down the hard disk, and turning off entire system components such as video, sound cards, or disk controllers. WHY DYNAMIC POWER MANAGEMENT IS NEEDED The dynamic power management (DPM) technology provides the ability to reduce energy consumption by devices when they are not in active use. In addition to the environmental benefits of reduced energy consumption, power management can improve equipment reliability by reducing wasted heat. The DPM technology improves power conservation capabilities based on open source platforms. It applies to running systems, adjusting power parameters on-the-fly, while ensuring real-time deadlines of running software are met. These deadlines could be either hard real-time systems, which guarantees a deterministic response time to an event so that a late response is considered to be a system failure, or they could be soft real-time systems to indicate that attempts to minimize event response time and does not consider a late response as a system failure.
  • 21. ..... POW ER M A N A G EM E NT BA CK G R O U ND TE C HN OL OG Y What is Dynamic Power Management? What is Dynamic Power Management? 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . W H AT IS DY NA M I C P O W E R M A N AG E M E N T ? Traditional power management for computer systems focused on regulating the power consumption in static modes such as sleep and suspend. These are de-activating states, often requiring a user action to re-activate the system. There are usually significant latencies and overheads for entering and exiting these states, and in desktop and server systems a firmware layer typically supports these modes. Recent advances in processor design techniques have led to the development of systems that support advances in hardware to scale clocking information such as CPU and core bus frequencies as well as core voltages with low latency. It enables dynamically adjusting power management parameters to realize power savings during brief idle periods or execution of tasks with lower performance and power demands. Since CPU power consumption typically decreases with the cube of voltage while frequencies scale linearly with voltage, significant opportunities exist for tuning the power-performance trade-off to the needs of the application. Dynamic power management is basically a set of schemes implemented while programs are running. Many architectures provide the equivalent of a halt instruction that reduces CPU power during idle periods. The operating system and device drivers can also manage power of peripheral devices, for example spinning down disks during periods of inactivity. Highly integrated processors with on-board peripherals often include software-controlled clock management capabilities to reduce power consumption by inactive peripherals and peripheral controllers. The memory subsystem also provides a profitable area for dynamic power management, either through the memory controller implementation or through software-based schemes. In support of these dynamic power management strategies, several processors supported by Mobilinux allow dynamic voltage and frequency scaling of the processor core. DPM targets the Linux operating system and the characteristics of hardware used for embedded Linux.
  • 22. POWER M A N A G EM E N T B A C K G R OU N D TE C HN O LOG Y What is an Embedded System? 4 What is an Embedded System? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . W H A T IS A N E M B E D DE D S Y S T E M ? Typically, embedded systems perform specific tasks that are stored in the system firmware. While desktop computers and handheld devices are general-purpose computing devices that are capable of running software to perform many different tasks, an embedded system is primarily designed for a specific task, for example a TV controller. In the past, it was easier to distinguish an embedded system from a general-purpose computers than it is today. Clearly, the increase in hardware performance and the lower cost of that hardware has blurred the line between general-purpose computers and embedded systems. Embedded systems usually do not have machine abstractions to insulate the operating system from low-level device and power management activities. In embedded Linux, as in other operating systems that target battery-powered applications, power management activities thereby require specific intervention on the part of the operating system kernel and device drivers. Notice, however, while low-level implementation of dynamic power management is resident in the operating system kernel, power management strategies and policies can and do emanate from middleware and user application code. WHAT IS EMBEDDED LINUX? Using Linux in embedded system designs enables saving innumerable hours in creating codes, developing reliable products, and featuring packed, robust, and quick to market. DYNAMIC POWER MANAGEMENT FOR EMBEDDED SYSTEMS The processors mentioned above are highly integrated system-on-a-chip (SOC) processors designed for embedded applications. The applications of these processors typically do not include a traditional BIOS, therefore control of the dynamic power state of the system must be implemented in the operating system.
  • 23. ..... POW ER M A N A G EM E NT BA CK G R O U ND TE C HN OL OG Y Architectural Summary Architectural Summary 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A R C H I T E C T U R AL S U M M A R Y The low-level implementation of the dynamic power management architecture resides in the kernel of the operating system, whereas the power management strategies come from outside of the system. Notice that DPM is not a self-contained device driver. The low-level implementation of DPM requires enhancements at a few key places in the operating system. A system designer familiar with the characteristics of the embedded system and its special features and requirements needs to define a complete dynamic power management strategy for each application in advance. The strategy is communicated to DPM in two ways: as a predefined set of policies and as an application or policy-set specific policy manager that manages the policies. WHAT IS A DPM POLICY? DPM policies are named data structures. Policies may be defined in such a way that they exert very fine-grained control over the dynamic state of the system. For this reason, policies must be installed into the operating system kernel for efficiency. Policies specify the component and device-state transitions that ensure reliable operations in line with the power management strategy. The structure of DPM policies and the effects of policies on the system are covered in Chapter 3, “What is MontaVista Power Manager?” A major component of the policy mechanism deals with the interaction of device states with policies. WHAT IS A DPM POWER POLICY MANAGER? DPM policy managers are executable programs that activate policies by name. Policy managers implement user-defined and/or application-specific power management strategies. They can execute either as part of the kernel or in userspace (or both) as required by the strategy. Policy managers may be very active, responding in real-time to changes in application power or performance requirements. However, they may be more passive, for example by changing policies on a longer time scale in response to changes in available battery power. In fact, DPM supports strategies that do not require any policy manager at all. Effective strategies for some applications may consist of a single policy installed at system initialization, perhaps modified by critical applications that interact directly with DPM.
  • 24. POWER M A N A G EM E N T B A C K G R OU N D TE C HN O LOG Y Dynamic Power Management and Mobile Devices 6 Dynamic Power Management and Mobile Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DYNAMIC POWER MANAGEMENT AND MOBILE DEVICES Hand-held device makers highlight battery life and power management as key features to stay competitive in the market. While users perceive results of power management in terms of battery life, it’s really a combination of CPU capabilities, system software, middleware, and policy that lets users enjoy their devices for more time between charges or battery changes. Any portable device owner notices that the device behaves differently when running on battery versus on ac power—the screen dims, the processor clock slows, and the system drifts off to standby or sleep whenever possible after an inactive period. System behaviors such as standby and sleep leverage native CPU capabilities to reduce operational voltage and/or clock frequency to save power. What users need to understand is that in addition to wholesale changes among system-wide states, actual power management can also be incremental and can occur many hundreds of times each second. Any DPM strategy begins with scaling the operating voltage and frequency of the one or more processor cores present in a portable device. Highly integrated processors such as the Intel PXA27x and the Texas Instrument OMAP family offer dynamic scaling of core voltage and frequency. MOBILE DEVICES CONSERVING ENERGY The overriding power management goal in portable systems is to reduce system-wide energy consumption. The current generation of embedded processors are so power-efficient that the processor may no longer be the major energy-consumer in systems that include high- performance memories and large color displays. Therefore, a dynamic power management system that is only concerned with voltage and frequency scaling the processor core may be of limited use. Instead, aggressive power management strategies that encompass the entire system are needed. For example, scaling bus frequencies can drive significant reductions in system-wide energy consumption.
  • 25. ..... POW ER M A N A G EM E NT BA CK G R O U ND TE C HN OL OG Y Dynamic Power Management and Mobile Devices Dynamic Power Management and Mobile Devices 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PLUGABLE POWER MANAGEMENT POLICIES The breakdowns of system-wide energy consumption agree that are the most effective way to manage energy consumption are highly application dependent. Therefore, a dynamic power management architecture needs to be flexible enough to support multiple platforms with differing requirements. Part of this flexibility is the requirement to support plug-able power management policies that allow device manufacturers to specialize policies for their applications and differentiate their products based on their own unique approaches to power management. The requirements for simplicity and flexibility are best served by leaving the workings of the dynamic power management system completely transparent to most tasks. Where this chapter provided background knowledge on the dynamic power management technology, the next chapter introduces the MontaVista Dynamic Power Management feature and provide specifics about it.
  • 26. POWER M A N A G EM E N T B A C K G R OU N D TE C HN O LOG Y Dynamic Power Management and Mobile Devices 8 Dynamic Power Management and Mobile Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  • 27. 9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 WHAT IS MOBILINUX ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DYNAMIC POWER MANAGEMENT? The Mobilinux Dynamic Power Management feature provides applications and tools that enable the users to control power policy for power-conscious Linux-based mobile devices. Additionally, it allows rapid modifications to power parameters of these systems, such as their CPU, bus frequencies, and core voltage scaling. This chapter covers the following topics: • “What is Mobilinux?” • “What is Mobilinux Dynamic Power Management?” • “Mobilinux Dynamic Power Management Benefits” • “Mobilinux Dynamic Power Management Features”
  • 28. W H A T I S M OB I LI NUX DY N A M IC POW ER M A N A G E M EN T ? 10 What is Mobilinux? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . W H AT IS M O B I L I N UX ? Mobilinux is an optimized Linux operating system and development environment, ideally suited for wireless handsets and mobile devices. It is based on a 2.6 kernel and meets the requirements for power management, hard real-time performance, fast start-up, and small footprint. Mobilinux is built to address key areas of development for mobile and wireless devices. MontaVista Mobilinux along with the Intel PXA27x™ and TI OMAP™ processors provides wireless devices with flexible and scalable solutions. Mobilinux enables setting up a power management profile that best meets the requirements of your device by helping you implement it for maximum performance and lowest cost. W H AT IS M O B I L I N UX D Y N A M I C P O W E R M A N AG E M E N T ? Mobilinux Dynamic Power Management (DPM) provides mechanisms to aggressively control power policy for Linux-based mobile devices. Mobilinux DPM feature rapidly scales power parameters such as CPU frequency as the operating system transitions between idling and running tasks as well as when the system switches among tasks with different power requirements. M O BI L I N UX DY N A M I C P O W E R M A N AG E M E N T B E N E F I T S Mobilinux DPM feature provides the following benefits: • Saves on system power by consuming less power during periods of reduced activities. • Increases system efficiency and frees up system and cooling power capacity by providing operating system independent power management. • Provides more power saving options by supporting dynamic power savings modes. • Protects the environment. • Conserves energy through increased efficiency in portable devices.
  • 29. ..... W HA T IS M O B IL INU X DY NA MI C POWE R MA NA G E M EN T ? Mobilinux Dynamic Power Management Features Mobilinux Dynamic Power Management Features 11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . M O BI L I N UX DY N A M I C P O W E R M A N AG E M E N T F E A T U RE S The following is a list of features provided by Mobilinux 4.0 Power Management: • “MontaVista Power Manager” • “DPM Library” • “Hotplug Agents” • “Clock Events Tracking” • “Power Profiler Plugin” • “Timer Interrupt Event Reduction” • “Tick Elimination” • “Power Manager Interface” • “High-level Power Manager Interface” • “Event Handling” • “Suspend and Resume Handling” MONTAVISTA POWER MANAGER The MontaVista Power Manager software provides default operating points and operating policies for each Mobilinux board, allowing DPM to be used out-of-the-box. It implements basic DPM policy management and modifies power settings according to simple heuristics, such as system load. The Power Manager allows for customizing of power parameters and policy heuristics as well as user-defined suspend and resume scripts for userspace actions at suspend and resume time. A plugin is added by creating a shared library that conforms to the Plugin API and by loading the plugin into the Power Manager through using the load command. This enable users to add value by adding better power policy management plugins to further extend the features of the MontaVista Power Manager. See Chapter 3,“What is MontaVista Power Manager?”
  • 30. W H A T I S M OB I LI NUX DY N A M IC POW ER M A N A G E M EN T ? 12 Mobilinux Dynamic Power Management Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM LIBRARY The DPM library conveniently provides a set of API-based functions that control DPM through the sysfs interface. Using the sysfs interface, the DPM library provides backward compatibility for existing sys-dpm-based applications that perform the same functions. HOTPLUG AGENTS In a variety of situations it may be useful to communicate information on power requirements or state changes from the kernel to a userspace Power Manager. For example, the information may request a system suspend in response to an interrupt received due to a button press, or the information may communicate device status changes that could lead the Power Manager to change system power state. For this reason, DPM provides functions that notify userspace through the Hotplug mechanism, instead of traditional method of notifying userspace policy handlers of changes in devices present (along with their associated chores such as downloading firmware for new devices). Hotplug executes an agent script to perform userspace handling of the power event. CLOCK EVENTS TRACKING The Mobilinux DPM Trace Toolkit Integration feature provides a method that tracks changes in any clock frequency by DPM. The clock events tracking feature provides a way to examine the system operating state transitions that DPM invokes. See Chapter 4, “MontaVista Power Manager Building Blocks.” POWER PROFILER PLUGIN The Power Profiler Plugin is provided along with the Power Manager. This plugin is enables measuring the CPU load and set profiles and DPM policies according to these commands. See Chapter 4, “MontaVista Power Manager Building Blocks.” TICK ELIMINATION The purpose of this feature is to prevent system wake ups for timers that serve no useful purpose while the system is in sleep or idle mode. This enables longer sleeps and thus more power savings.
  • 31. ..... W HA T IS M O B IL INU X DY NA MI C POWE R MA NA G E M EN T ? Mobilinux Dynamic Power Management Features Mobilinux Dynamic Power Management Features 13 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The kernel relies on periodic timer interrupts to allow the kernel keep the current time and date up-to-date, to do accounting, and to see if the software timer service routines should be called. Even when the processor is otherwise idle, these interrupts occur and can cause the processor to be brought out of a power savings mode even though there may not be anything for it to do other than update the time and go back to sleep. HIGH-LEVEL POWER MANAGER INTERFACE Power Manager serves as the preferred DPM interface instead of users directly accessing the lower-level interfaces. Embedded systems usually do not have BIOS and typically do not provide machine abstractions to insulate the operating system from low-level device and power management activities. In operating systems that target battery-powered applications, power management activities thereby require specific intervention on the part of the operating system kernel and device drivers. Notice, however, that while low-level implementation of DPM is resident in the operating system kernel, power management strategies and policies can and do emanate from middleware and user application code. EVENT HANDLING The Power Manager has features that allow power policy to be adjusted in reaction to various system and device power events. See Chapter 9, “What is Mobilinux Dynamic Power Management?.” SUSPEND AND RESUME HANDLING The Power Manager is able to check the requested (or defaulted) sleep operating state against device constraints. If not rejected by the previous methods, these user-defined scripts are executed (if present) before and after the actual system suspend, respectively. Power managed device drivers continue to receive notifications of system suspend and resume states. During an operating system suspend state, the microprocessor will no longer be active. In theory Power Manager puts all devices into a device power state that is appropriate to an operating state suspend state. However, it is possible that a suspend system power state configuration or an application device power requirement not be appropriate for a particular device.
  • 32. W H A T I S M OB I LI NUX DY N A M IC POW ER M A N A G E M EN T ? 14 Mobilinux Dynamic Power Management Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  • 33. 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 WHAT IS ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MONTAVISTA POWER MANAGER? The MontaVista Power Manager software is the interface to the Mobilinux Dynamic Power Management (DPM). It provides default operating points and operating policies for each Mobilinux board, allowing DPM to be used out-of-the-box. The following topics are covered in this chapter: • “What is MontaVista Power Manager?.” • “MontaVista Power Manager Features.” • “Overview of MontaVista Power Manager Tools.”
  • 34. W H A T I S M O N T A VI S T A POWE R MA NA G E R? What is MontaVista Power Manager? 16 What is MontaVista Power Manager? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . W H AT IS M O N T A V I S T A P O W E R M A NA G E R ? The MontaVista Power Manager implements basic DPM policy management and modifies power settings according to simple heuristics, such as system load. It allows for customizing of power parameters and policy heuristics as well as user-defined suspend and resume scripts for userspace actions at suspend and resume time. MontaVista Power Manager features can be further extended to meet the needs of a particular system by adding by adding custom power policy management plugins. When a system sleep or suspend mode is required, the power manager requests the appropriate mode after executing custom actions necessary to prepare for the suspend, according to the needs of the particular system. M O NT AV IS T A P O W E R M A NA G E R F E A T U RE S The MontaVista Power Manager features the following: • “DPM Interface” • “Integrated Components” • “Default Operating Points” • “User-Defined Power Parameters” • “Default Power Policies” See Chapter 4, “MontaVista Power Manager Building Blocks” DPM INTERFACE The new interface for Power Manager is a sysfs interface. It provides an interface that no longer requires that DPM-aware applications be compiled with board-specific kernel header files. Knowledge of kernel implementation details are defined in those header files, such as array indices of power parameters, number of power parameters, operating state numeric identifiers, and so on.
  • 35. ..... W HA T I S M O N TA V I S T A POWE R M A N A G ER ? MontaVista Power Manager Features MontaVista Power Manager Features 17 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INTEGRATED COMPONENTS Power Manager integrates the various components involved in a power management system, such as kernel drivers and power-aware application, into a framework that users can use for their products. DEFAULT OPERATING POINTS Power Manager provides default operating points and policies for each Mobilinux supported board, allowing DPM to be used out-of-the-box. DPM runs the system at a certain operating point at any given time, chosen from a set of possible operating points according to rules set by the system designer. USER-DEFINED POWER PARAMETERS The DPM implementation for a platform is based on information from the silicon or board vendor describing the available power parameters and operating points that have been validated to operate successfully on the platform. MontaVista can then support DPM software modification of these power parameters and can support DPM running at the validated operating points. Power Manager allows for customer extensions to power parameters and policy switching heuristics, as well as customer-written suspend and resume scripts for userspace actions at suspend and resume time. DEFAULT POWER POLICIES Power management policies or schemes are used to make decisions on the state of operation of electronic systems such as portable devices. Dynamic power management schemes or policies can be used to control the power consumption levels of electronic systems, by setting their components in different states, where each is characterized by a performance level and a power consumption. The power consumption can be formulated as an optimization problem called policy optimization. It enables basic DPM policy management, switching power settings according to simple heuristics, for example, switching to a higher performance level when system load increases.
  • 36. W H A T I S M O N T A VI S T A POWE R MA NA G E R? Overview of MontaVista Power Manager Tools 18 Overview of MontaVista Power Manager Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OVERVIEW OF MONTAVISTA POWER MANAGER TOOLS The following tools allow for modifications to Power Manager. COMMAND-LINE Power Manager reads commands from any source, including the following: • Configuration file selected by the startup script by default. • Another dpmmgr invoked by the command-line parameters. • FIFO /tmp/dpmmgr.fifo at runtime to receive commands from applications and kernel event messages, such as from power hotplug scripts. • Plugins through plugin API function calls. The command line may consist of several dpmmgr commands that are separated by semicolons ";". A number of commands refer to devices by using the syntax bus/device, where bus is a string comprised of a sysfs bus name, and devices is a sysfs device name. For example, platform/omap1710 refers to the device named omap1710 on the platform bus. See Chapter 11, “Power Manager Commands.” The Power Manager enables the users to add value by adding plugins that extend the features of the base policy manager. The dpm-profiler plugin can measure the CPU load and set the profiles and DPM policies according to these commands. See Chapter 13, “Power Manager Profiler Plugin.” PLUGIN APIS Plugins can be added by creating a shared library that conforms to the Plugin APIs and by loading the plugin into the policy manager using the load command. The Power Manager Plugin API includes callbacks or functions that are called by dpmmgr into the plugin. See Chapter 12, “Plugin Commands and APIs.”
  • 37. 19 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 MONTAVISTA POWER MANAGER ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BUILDING BLOCKS Mobilinux Dynamic Power Manager (DPM) responds with low latency to the system workload and environment by dynamically adjusting system operating parameters to balance system performance and power consumption, without requiring user interactions. The key to design a power efficient DPM is to implement a power manager policy that meets the needs of your system. This requires understanding your overall power management goals, the CPU execution states of your system, and the available power want DPM to manage. MontaVista Power Manger allows you to design a power policy that is specific to your development platform by building the following components: • “Operating Points” • “Operating Classes” • “Operating States” • “DPM Power Policy” Note: This chapter explains the concepts of each of these building blocks. See Chapter 8, “Designing Device Interactions with DPM,” for specific instructions for building these blocks.
  • 38. M ON T A VI S TA POWER M A N A G ER B U I LD IN G B L OC K S Operating Points 20 Operating Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . O P E RA T I N G P O I N T S A system executes at a particular operating point at any given point in time. The operating point, in turn, can be described by such parameters as the core voltage, CPU and bus frequencies, and the states of peripheral devices. A dynamic power management system is defined as a set of rules and procedures that move the system from one operating point to another as events occur. Selecting appropriate operating points has a critical impact on system energy consumption. Additionally, modern voltage and frequency scalable systems support multiple operating points. Operating points are the lowest-level objects in the DPM system hierarchy. An operating point object encapsulates the minimal set of inter-dependent, physical, and discrete parameters that define a specific system performance level along with its associated energy cost. A good example of inter-dependency is the relationship between voltage and frequency of a CPU core. The core voltage limits the maximum operating frequency of a voltage- scalable CPU, while the frequency of the processor cannot be considered without also considering the voltage. Operating points, by nature, are processor- and system-dependent. The system designer is responsible for defining as many operating points as are necessary to satisfy the power management need of the application, such as core voltage levels, CPU and bus frequencies, memory timing parameters, and other clocking related data. Note: For a complete list of the default operating points provided for your board see the chapter specific to your supported platform in this manual. OPERATING POINTS PARAMETERS For a list of power parameters used by operating points see the DPM header files. Any value associated with each parameter in these files is an integer. You can modify or adjust each parameter for your specific platform; however, you must make your modifications according to the rules specified by the manufacturer of your board.
  • 39. ..... M ON T A VI S TA POWER M A N A G E R B U I LD IN G B L OC K S Operating Classes Operating Classes 21 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OPERATING POINTS EXAMPLES An operating point is a specific set of values of the hardware operating parameters. Each operating point is labeled with a name. The following table provides an example of four operating points for a theoretical system: O P E RA T I N G CL A S S E S An operating class is a set of operating points. Operating point classes allow DPM to automatically choose an appropriate operating point from among a list of available operating points, according to the constraints set by drivers. Constraints describe the required relationships between the hardware operating parameters. For example, for a network adapter to function properly, it may require that the frequency of the IO bus, to which it is attached, be greater than 10 Mhz. To learn more about device constraints, see Chapter 5, “DPM Device Driver Interfaces.” An example of an operating class may be a class that offers a choice of a lower power operating point or a higher power operating point, allowing the lower power operating point to be set if no drivers have asserted a constraint disallowing the lower power operating point. A power policy can map an operating state to a single operating point, or it can map an operating state to a class that contain multiple operating points. When switching operating points to match a change in operating state, DPM will choose the first operating point in the class that is allowed under the current device constraints. For example, the following shows how to create an operating class using the sysfs interface: create class-name op-name op-name... > /sys/dpm/class/control The variable class-name must be unique among other classes and operating points. Operating Point Voltage Processor Clock Processor Clock Bus I/O Bus Clock ................................... ......................fast_cpu 5000 mV 400 Mhz 200 Mhz 100 Mhz slow_cpu 5000 mV 100 Mhz 50 Mhz 100 Mhz med_cpu 5000 mV 50 Mhz 25 Mhz 100 Mhz Sleep 0 mV 0 Mhz 0 Mhz 0 Mhz ................................... ......................
  • 40. M ON T A VI S TA POWER M A N A G ER B U I LD IN G B L OC K S Operating States 22 Operating States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Each op-name is the name of an operating point within the class. The order of names is significant. When choosing an operating point from the class, DPM will evaluate each operating point in left-to-right order, choosing the first operating point that meets the current constraints. The variable class-name is specified in a policy to map an operating state to the class. O P E RA T I N G S T A T E S Operating states are CPU execution states that are triggered by the scheduler when performing a context switch, other kernel-specific actions (such as entering the idle loop), or an explicit command using a DPM API. WHAT IS AN OPERATING STATE? The concept of the operating state was first introduced by observing that significant system- wide energy savings can be achieved by reducing CPU and bus frequencies and core voltage while the system is in idle state. Therefore a mechanism was required to specify a different operating point during the time that programs are executing, versus the times that the system is idle. This led to a distinction between an active state and an idle state, each with a potentially different operating point. The transition from the active state operating point to an idle state operating point and back is smoothly and efficiently managed by the DPM implementation in the operating system. OPERATING STATES ARCHITECTURE The concept of an operating state applies to task-specific operating points for power-aware tasks. This requires multiple task-specific active states or task states. The DPM architecture allows for any number of task states. The default task state is expected to be used by the large majority of tasks, analogous to the way that most tasks now use the default scheduling policy of the operating system. Tasks with special requirements may specify how to run in different task states, each of which may be associated with a different operating point. Note: Tasks never explicitly specify an operating point. Instead, the operating point is implied by the task state and the current policy.
  • 41. ..... M ON T A VI S TA POWER M A N A G E R B U I LD IN G B L OC K S Operating States Operating States 23 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operating states also appear in the DPM policy architecture. Conceptually, a DPM policy simply associates an operating point with each of the system operating states. Changing to a new DPM policy simply changes the association. The operating state is an abstraction that software uses to request a specific level of system performance. The system’s current operating state is set from each process’ operating state when the process is active. The default operating state of each process is inherited from its parent. A process’ operating state can be changed using a DPM API. The board-specific implementation portion of DPM can alter the system’s current operating state while kernel code is executing. For example, the kernel idle loop code might set the system’s current operating state to idle while there is no task that is ready to be executed. OPERATING STATES TYPES In general, DPM defines the following three basic operating states for kernel use: • DPM_SLEEP_STATE • DPM_IDLE_STATE • DPM_DPM_TASK_STATE SL E EP The sleep operating state instructs DPM to suspend the system to a low-power sleep or standby state. When DPM enters the sleep operating state, the following actions take place: 1 The device suspend() function is invoked for each device, saving device state for later resume, and placing the device in a low-power state. 2 Other board-specific actions, such as to place SDRAM in auto refresh mode, may occur. 3 The CPU in placed in a low-power mode selected by the operating point parameters. When the system is resumed due to receipt of a wake-up event, the following actions take place:
  • 42. M ON T A VI S TA POWER M A N A G ER B U I LD IN G B L OC K S Operating States 24 Operating States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 The CPU comes out of sleep/standby mode and resumes execution. 2 Other board-specific actions may occur, such as to take SDRAM out of auto refresh mode. 3 The operating state changes to DPM_TASK_STATE. 4 The device resume() function is invoked for each device in order to restore state and power up the device. ID LE The idle operating state is entered whenever the Linux scheduler executes the idle loop. The idle loop typically executes a wait-for-interrupt instruction that will temporarily halt processor execution cause kernel execution to resume upon receipt of the next interrupt. There may also be other actions performed by the idle loop for your board, such as to place SDRAM into self-refresh state. The DPM operating point selected for the idle operating state may modify additional power parameters for reduced power consumption during idle periods, such as to reduce the frequency of clocks. TA SK The task state function is the default operating state for all processes. DPM by default supports nine task states. The following list displays the names of all of the default task states: • task-4 • task-3 • task-2 • task-1 • task • task+1 • task+2 • task+3 • task+4 Applications can either be assigned a task state by the policy manager or can set their own task state directly. In both cases use the DPM API calls, see Chapter 12, “Plugin Commands and APIs.”
  • 43. ..... M ON T A VI S TA POWER M A N A G E R B U I LD IN G B L OC K S DPM Power Policy DPM Power Policy 25 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DP M P O W E R P O L I C Y The DPM Power Policy is the highest-level abstraction of the DPM architecture. A DPM Power Policy is a named data structure, which is installed into the DPM implementation in the operating system and is managed by the Power Manager that resides outside of the operating system. Once a DPM system is initialized and activated, the system will always be executing under a particular DPM policy. WHAT IS A DPM POWER POLICY? A policy is a mapping of an operating state or class invoked for each operating state. For example, a low-battery-strength policy might map all operating states to low power operating points. Or, a high-battery-strength policy might map a task operating state used by interactive processes to a high power operating point, a task operating state used by background processes to a medium power operating point, and an operating state used by the kernel idle loop to a low power and low wake up latency operating point. POWER POLICY ARCHITECTURE The highest-level abstraction of the DPM architecture is the Power Policy, which maps each operating state to an operating point or a harmonized class of operating point. A power management strategy specifies at least one policy and may specify as many different policies as are necessary for different scenarios. The policy in effect at any given point in time controls the operating point of the system in every operating state. The DPM architecture does not require the presence of any operating states other than a single task state common to all platforms. The number of task states may vary from platform to platform, however on all platforms the task states are only given meaning by the policies and Power Manager. If multiple policies are needed, then Power Manager needs to coordinate the activation of different policies at different times. Power Manager may collect information from the operating system, user preferences, running programs, configuration files and physical devices to make its policy decisions. The location of the policy manager (kernel space or userspace), the types of information required, and all of the actions taken in response to that information are not specified. The intention of this architecture is simply to define a consistent way for policy developers to express policies that are controlled by the policy manager and implemented by DPM.
  • 44. M ON T A VI S TA POWER M A N A G ER B U I LD IN G B L OC K S DPM Power Policy 26 DPM Power Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  • 45. 27 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM DEVICE DRIVER INTERFACES Ideally, a power management system would be entirely transparent to as many levels of the software stack as possible. Developers experienced in building handheld devices believe that some degree of explicit participation is required across the system, including the kernel and driver interfaces. In the DPM architecture for Linux, the DPM subsystem within the kernel maintains the system’s power state and ties together the various power-managed elements of a DPM system. DPM serves as a service provider to drivers, middleware, and applications. The following topics are covered in this chapter: • “DPM Device Driver Background” • “DPM Device Constraints Background” • “Forced Operating Points” • “DPM Classes” • “DPM Driver Scale Callbacks” • “Driver Model and Device Suspend/Resume”
  • 46. DP M D EV I C E DR IVE R IN T ER F AC ES DPM Device Driver Background 28 DPM Device Driver Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DP M D E V I CE DR IVER B A CK GR OU N D The automatic selection of operating points as devices change state is a central feature of DPM. Embedded systems may not have a BIOS or machine abstraction layer to insulate the operating system from low-level device and power management. Therefore, this task falls to the operating system and its device drivers. As the complexity of embedded systems increases and the interrelationships between clock sources and power management modes become more complex, this becomes an increasingly difficult task. Under the DPM abstraction, the system designer needs to design the power management system by pre-selecting sets of meaningful operating points for the application and organizing these operating points within power management policies that are suitable for the application. DP M D E V I CE CO N S T R AI N T S B A C K G RO UN D Device constraints allow drivers to control entry to DPM operating points. Constraints restrict entry to operating points that are incompatible with correct operation of devices. The appropriate device constraints to use, and the consequences of violating these constraints, is determined by the characteristics of the hardware platform. Constraints may also restrict DPM operations in ways considered useful by the system designer, such as allowing DPM to transition to a low-power idle mode only if a set of devices are not in use, regardless of whether or not the underlying hardware is capable of operating the devices in that mode. HOW DEVICE CONSTRAINTS WORK The manner in which DPM interprets constraints depends on the way the current DPM policy is defined. DPM policies can map a system operating state to a specific DPM operating point or to a DPM class of operating points. Devices specify their requirements as sets of constraints associated with particular device states. For example, an LCD controller might specify a pixel clock in the range of 16 to 25 MHz while active and no constraint while inactive. When devices change state, and their requirements for system resources change, these requirements are communicated to DPM. Simple rules are defined to invalidate inappropriate operating points and to automatically
  • 47. ..... DP M D EV I C E D R IVE R IN T ER F A CE S Forced Operating Points Forced Operating Points 29 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . select one of possibly several valid operating points from the operating classes under the new constraints. This mechanism frees the policy manager to focus on high-level management, while ensuring that the system always operates at the best operating point, as defined by the system designer, consistent with the current policy and device states. This mechanism also supports systems that include simple policy managers, or that do not implement any run-time DPM policy management at all. The system designer may be able to describe a suitable dynamic power management strategy using only a single DPM policy, based on operating point operating classes that anticipate the significant states of peripheral devices with regard to power management. To design DPM operating classes, see Chapter 8, “Designing Device Interactions with DPM.” DEVICE CONSTRAINTS FEATURES DPM checks device constraints and either chooses an operating point from an operating class that does not violate the constraints, or it blocks transition to any new operating point if there is no operating point that does not violates those constraints. The following are some of the features of the constraints interfaces: • Writing a constraint with the same power parameter ID as an existing constraint overwrites the previous constraint with the new settings. • Power parameter with the minimum or maximum value -1 means no constraint. • Existing constraints can be removed using this syntax. • Reading the device sysfs constraints attribute returns more information, including asserted=yes/no status, as well as the number of times an operating point was rejected due to this constraint. F O R CE D O P E R A T I N G P O I N T S A forced operating point may be set even if device constraints would normally disallow it. Devices with constraints incompatible with the operating point are first suspended before the operating point is set.
  • 48. DP M D EV I C E DR IVE R IN T ER F AC ES DPM Classes 30 DPM Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . This feature is implemented as a per-operating point attribute, named force. The force attribute is only supported for sleep operating points, that is, operating points that place the system into a low-power sleep, suspend, or standby state. Force flag handling is implemented by Power Manager. If you are implementing your own power policy manager and want to have similar functionality, then you may implement the code to check the force attribute and power down the affected devices in your power policy manager. D P M C L A S S E S DPM classes are fully supported in Mobilinux and may contain more than one operating point. DPM classes allow DPM to automatically choose an appropriate operating point from among a choice of several operating points, according to the constraints set by drivers. For example, a class may offer a choice of a lower power operating point or a higher power operating point, allowing the lower power operating point to be set if no drivers have asserted a constraint disallowing the lower power operating point. In Mobilinux, a DPM policy can map an operating state to a single operating point, or it can map an operating state to a class containing multiple operating points. D P M D R I V E R S C A LE C A L L B A C K S DPM-enabled device drivers are more stateful than default drivers. They are driven through various states by external events and through callbacks from the kernel DPM subsystem to reflect operational policies. Mobilinux DPM has the capability to call drivers when scaling clock frequencies. This enables drivers to react to any necessary change on all platforms. This is done using the scale driver callback.
  • 49. ..... DP M D EV I C E D R IVE R IN T ER F A CE S Driver Model and Device Suspend/Resume Driver Model and Device Suspend/Resume 31 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DR I V E R M O D E L A ND D E V I C E S U S P E N D /R E S U M E The device suspend and resume features associated with DPM are a standard part of the 2.6 kernel on which Mobilinux is based. The 2.6 code typically registers such devices as platform devices on the built-in platform bus. This avoids the need to issue separate LDM registration or deregistration calls for each platform that supports a particular driver. The platform bus uses the following sequence: suspend: 1. SUSPEND_DISABLE; 2. SUSPEND_SAVE_STATE; 3. SUSPEND_POWER_DOWN resume: 1. RESUME_POWER_ON; 2. RESUME_RESTORE_STATE; 3. RESUME_ENABLE Depending on the particulars of the platform, the suspend mode requested, and the device driver, all 3 levels may or may not be useful, and some may be ignored if not useful.
  • 50. DP M D EV I C E DR IVE R IN T ER F AC ES Driver Model and Device Suspend/Resume 32 Driver Model and Device Suspend/Resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  • 51. 33 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 MONTAVISTA POWER MANAGER ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OUT-OF-THE-BOX MontaVista Power Manager provides configuration files that are specific to each supported development platform board. This chapter provides lists of default operating points and policies as well as configurations for each supported board, as follows: • “Using Power Manager Out-of-the-Box” • “Installing Configuration File” • “Exiting From your Power Manager” • “Power Manager Default Configuration Files”
  • 52. M ON T A VI S TA POWER M A N A G ER O U T -OF -T H E-B OX Using Power Manager Out-of-the-Box 34 Using Power Manager Out-of-the-Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . US I NG P O W E R M A N AG E R O U T - O F -T H E - BO X MontaVista provides system startup scripts to start and stop the MontaVista Power Manager, dpmmgr. These scripts pass the board-specific configuration file at /lib/modules/$(uname -r)/dpmmgr.conf to dpmmgr, where $(uname -r) is the release number of the Linux kernel and Mobilinux product. The following shows the syntax to dpmmgr: dpmmgr [options] [command-line] where [options] are, -f <file> set configuration file -v verbose debugging info -l enable logging -d run as a daemon Note: -l saves information in /var/log/dpmmgr.log file. [command-line] is a command line to send to the Power Manager, which must have been previously started. dpmmgr sends the command-line to the Power Manager and exits, providing a convenient way to execute dpmmgr commands on-the-fly. You may want to setup both a high-power and low-power policy specific to your board, assuming reasonable operating points for higher-power and lower-power that are still running are known for the board. You may also choose an operating point for the idle state if an appropriate low-power operating point with low latency to enter and exit is known for the board. As part of the installation of MontaVista Power Manager, the dpm-profiler will also be installed by default. See Chapter 13, “Plugin Commands and APIs.”
  • 53. ..... M ON T A VI S TA POWER M A N A G ER O U T- OF -T HE -B OX Installing Configuration File Installing Configuration File 35 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I N S T A L LI N G CO N F I G U R A T I O N F I LE During the installation of Mobilinux, the dpmmgr.conf file specific to your board will be installed as well. 1 After installing your LSP, you may you may start MontaVista Power Manager as shown below: /var/log/dpmmgr -v “status” 2 Check the output in dpmmgr.log file if logging is enabled to see any messages logged during Power Manager startup. /etc/init.d/dpmmgr.log start Initialized from configuration file: /lib/modules/2.6.10_mobilinux402-mainstone_pxa27x/dpmmgr.conf Poll interval: 3 seconds. Plugins loaded: dpm-profiler load-scale: active profile is "battery-hi". load-scale: power metric is 0 => "set policy lo-power". E X I T I NG F RO M Y O UR P O W E R M A N AG E R To exist from your MontaVista Power Manager enter the following command: dpmmgr -v "exit" dpmmgr shut down 04 Jan 1970 05:34
  • 54. M ON T A VI S TA POWER M A N A G ER O U T -OF -T H E-B OX Power Manager Default Configuration Files 36 Power Manager Default Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P O W E R M A NA G E R DE F AU L T C O N FI G U R AT IO N F I L E S This section provides the default configuration files for each one of the supported development platform provided by MontaVista. Note: Check the MontaVista Zone for the latest changes to the default configuration files. TI-OMAP1710 BOARD CONFIGURATION The following is the MontaVista Power Manager configuration for the TI-OMAP1710 H3 development platform board. Note: Please refer to the TI-supplied documentation for your board and processor model to verify the operating points supported on your hardware. load /usr/lib/dpm-profiler.so Specifies operating points to run the CPU at 192, 168, 84, and 60 MHz, respectively. op 192dpll-mult=16 dpll-div=1 arm-div=1 tc-div=2 op 168dpll-mult=14 dpll-div=1 arm-div=1 tc-div=2 op 84dpll-mult=14 dpll-div=1 arm-div=2 tc-div=2 op 60dpll-mult=5 dpll-div=1 arm-div=1 tc-div=1 Specifies operating points to place the 168 and 60 MHz CPU system into Sleep mode, respectively. op sleep-168 dpll-mult=14 dpll-div=1 arm-div=0 op sleep-60 dpll-mult=1 dpll-div=2 arm-div=0 tc-div=2 Defines hi-power policies for the above system. policy hi-power idle, idle-task,task,task+1,task+2,task+3,task+4=192 policy hi-power task-1,task-2,task-3,task-4=168 sleep=sleep-168 Defines low-power policies for the above system. policy lo-power idle, idle-task, task, task-1,task-2,task-3,task-4=60 policy lo-power task+1,task+2,task+3,task+4=84 sleep=sleep-60 Configuration plugin to increase the power by 50 when CPU at 50% utilization. tell dpm-profiler cpu 50% +50 Configuration plugin to specify battery-hi profile to lo-power or hi-power policy depending on the given value of 0 or 50, respectively.
  • 55. ..... M ON T A VI S TA POWER M A N A G ER O U T- OF -T HE -B OX Power Manager Default Configuration Files Power Manager Default Configuration Files 37 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tell dpm-profiler profile battery-hi at 0 set policy lo-power tell dpm-profiler profile battery-hi at 50 set policy hi-power Configuration plugin to specify battery-low profile to lo-power or hi- power policy depending on the given value of 0 or 90, respectively. tell dpm-profiler profile battery-lo at 0 set policy lo-power tell dpm-profiler profile battery-lo at 90 set policy hi-power Configuration plugin to activate the battery-hi profile which will remain in effect until it is overridden by another set profile command. tell dpm-profiler set profile battery-hi Command to report a status summary to stdout. status INTEL PXA27X MAINSTONE BOARD CONFIGURATION The following is the MontaVista Power Manager configuration for the Intel PXA27x Mainstone II development platform. Note: Please refer to the Intel-supplied documentation for your board and processor model to verify the operating points supported on your hardware. load /usr/lib/dpm-profiler.so Specifies operating points to run the CPU at 104, 208, and 312 MHz. op 104mhz v=900 l=8 n=2 b=1 half_turbo=0 cccra=1 cpll-on=1 ppll-on=1 sleep_mode=0 op 208mhz v=1050 l=16 n=2 b=1 half_turbo=0 cccra=0 cpll-on=1 ppll-on=1 sleep_mode=0 op 312mhz v=1250 l=16 n=3 b=1 half_turbo=0 cccra=0 cpll-on=1 ppll-on=1 sleep_mode=0 Specifies operating points to put the system into Sleep, Deep Sleep, and Standby mode, respectively: # Sleep Mode op sleep v=1500 l=0 n=0 b=0 half_turbo=-1 cccra=0 cpll-on=0 ppll-on=0 sleep_mode=3 # Deep Sleep Mode op dsleep v=1500 l=0 n=0 b=0 half_turbo=-1 cccra=0 cpll-on=0 ppll-on=0 sleep_mode=7
  • 56. M ON T A VI S TA POWER M A N A G ER O U T -OF -T H E-B OX Power Manager Default Configuration Files 38 Power Manager Default Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . # Standby Mode op stndby v=1500 l=0 n=0 b=0 half_turbo=-1 cccra=0 cpll-on=0 ppll-on=0 sleep_mode=2 Specifies operating points to put the system into the Sleep mode, where the second statement enables the Peripheral PLL. # 13m op 13m v=1500 l=1 n=2 b=0 half_turbo=0 cccra=0 cpll-on=0 ppll-on=0 sleep_mode=-1 # 13mext op 13mext v=1500 l=1 n=2 b=0 half_turbo=0 cccra=0 cpll-on=0 ppll-on=1 sleep_mode=-1 Specifies operating points to run the CPU at 520, 416, 312, and 208 MHz, respectively. The operating points specified for 520mhz and 416mhz may fail on some B0 hardware: op 520mhz v=1450 l=16 n=5 b=1 half_turbo=0 cccra=1 cpll-on=1 ppll-on=1 sleep_mode=0 op 416mhz v=1350 l=16 n=4 b=1 half_turbo=0 cccra=1 cpll-on=1 ppll-on=1 sleep_mode=0 op 312mhz_2 v=1250 l=16 n=3 b=1 half_turbo=0 cccra=1 cpll-on=1 ppll-on=1 sleep_mode=0 op 208mhz_2 v=1150 l=16 n=2 b=1 half_turbo=0 cccra=1 cpll-on=1 ppll-on=1 sleep_mode=0 Defines hi-power policies for the above system. policy hi-power idle, idle-task,task,task+1,task+2,task+3, task+4=312mhz policy hi-power task-1,task-2,task-3,task-4=208mhz sleep=sleep Defines lo-power policies for the above system. policy lo-power idle, idle-task, task, task-1, task-2,task-3,task- 4=104mhz policy lo-power task+1,task+2,task+3,task+4=208mhz sleep=dsleep Configuration plugin to increase the power by 50 when CPU at 50% utilization. tell dpm-profiler cpu 50% +50
  • 57. ..... M ON T A VI S TA POWER M A N A G ER O U T- OF -T HE -B OX Power Manager Default Configuration Files Power Manager Default Configuration Files 39 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration plugin to increase the power by 90 when CPU at 90% utilization. tell dpm-profiler cpu 90% +90 Configuration plugin to activate the battery-hi profile, which will remain in effect until it is overridden by another set profile command. tell dpm-profiler profile battery-hi at 0 set policy lo-power tell dpm-profiler profile battery-hi at 50 set policy hi-power Configuration plugin to activate the battery-lo profile, which will remain in effect until it is overridden by another set profile command. tell dpm-profiler profile battery-lo at 0 set policy lo-power tell dpm-profiler profile battery-lo at 90 set policy hi-power Configuration plugin to activate the battery-hi profile which will remain in effect until it is overridden by another set profile command. tell dpm-profiler set profile battery-hi Command to report a status summary to stdout. status
  • 58. M ON T A VI S TA POWER M A N A G ER O U T -OF -T H E-B OX Power Manager Default Configuration Files 40 Power Manager Default Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  • 59. 41 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 DESIGNING YOUR ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . POWER MANAGER BUILDING BLOCKS Chapter 4, “MontaVista Power Manager Building Blocks,” explained that MontaVista Power Manger allows you design a power policy that is specific to your development platform by building its components: operating points, classes, policies, and states. This chapter explains how to build these blocks. This chapter covers the following chapters: • “Studying Your Hardware’s Power Management Characteristics” • “Guidelines for Setting up DPM Operating Points” • “Designing High-Level Power Management Software Architecture” • “Designing DPM Suspend/Resume Devices” • “Designing DPM Driver Scale Callbacks” • “Designing Power-Related Events” • “Designing Power Policies” • “Designing Programmable Sleep/Wakeup Sources” • “Designing DPM Task States” • “Designing Sleep/Standby Behavior”
  • 60. DE SIG NI N G YO UR POWER M A N A GER BUIL DI N G B LO CK S 42 Studying Your Hardware’s Power Management Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . S T U D Y I N G Y O U R H A R D W AR E ’ S P O W E R M A N AG E M E N T C H AR A C T E R I S T I CS Before designing your MontaVista Power Manager building blocks, first consult your silicon or board vendor technical reference manuals, errata, application notes on power management for the following information: • Validated or supported operating points. • Power consumption of hardware components running at different operating points. • Latencies associated with entering different operating points. • Clocking dependencies and other information on device dependencies on power states. CONFIGURING YOUR BOARD By default, dpmmgr will be preconfigured with a selection of operating points expected to function properly on the evaluation supported board supported by your Mobilinux LSP. Comments in the dpmmgr configuration file may indicate known issues with certain operating points on particular hardware revisions. DEVICE POWER CONSTRAINTS Mobilinux Dynamic Power Management for your board is typically preconfigured with device power constraints in the drivers for devices that have dependencies on power states, preventing DPM from setting runtime operating points incompatible with active devices. See Chapter 8, “Designing Your Power Manager Building Blocks,” for information about your board and how to set operating points through DPM software interfaces and other power management programming information.
  • 61. ..... D ES I G N IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Guidelines for Setting up DPM Operating Points Guidelines for Setting up DPM Operating Points 43 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GU I D E L I NE S F O R S E T T I N G U P D P M O P E RA T I N G P O I N T S Software system designers generally like to have a range of power levels available through the supported operating points available for the platform. This includes at least one relatively low-performance low-power point, one midrange point, and a full-performance high-power state. They may also be interested in measured power consumption levels by core system components at various operating points to better understand the power savings that may be expected to result from different power policies. • What are the tunable power parameters of the hardware, such as core voltage, CPU speed, etc.? • What collections of values for power parameters have been validated to function correctly in the hardware? That is, what operating points are supported by the hardware vendor? In many cases, sets of discrete values of power parameters are appropriate, although ranges of values may also be validated. • What steps are necessary to set a new operating point? When switching from one operating point to another, is it necessary to delay while PLLs relock or clocks or voltages settle, etc.? Is a significant latency involved so that it may not be appropriate to switch between the two operating points potentially hundreds of times a second? Note that DPM may switch operating points at every entry into the kernel scheduler, such as switch to executing a new process or to enter the system idle loop when no task is ready to run. DPM may therefore potentially request operating point changes more frequently than originally expected. • Are any of the operating points incompatible with device operation? Does the operating point stop or slow down a clock that is needed for correct operation of any devices? DPM provides facilities to coordinate these kinds of device impacts, for example, to block setting an operating point that would interfere with correct operation of an active device, or to forcibly shut down conflicting devices. • Does a device need to be reconfigure to match a change in system operating point? For example, does any device that sources a changing clock need to change divisors etc. to function correctly after the change? DPM offers a method of calling into drivers when operating points are changed to reconfigure such devices. • Does the system have specialized power management features that also set system power levels and may need coordination with or management by DPM?
  • 62. DE SIG NI N G YO UR POWER M A N A GER BUIL DI N G B LO CK S 44 Designing High-Level Power Management Software Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DE S I G NI N G HI G H -L E V E L P O W E R M AN A GE M E NT S O F T W AR E A R CH I T E CT UR E It is common to implement the MontaVista Power Manager software authority on making decisions that are based on a power management policy. This authority might, for example, be responsible for • Activating different DPM policies based on changes in system state. • Powering up and down devices as needed to place the system in appropriate states to meet power management goals. • Receiving notifications of power-related events from other portions of the system and making power policy decisions based on that information. DESIGNING A POWER POLICY WITH MONTAVISTA POWER MANAGER The MontaVista Power Manager, dpmmgr, provides the basis for such a power policy control application. It implements a number of commonly-needed power control operations and serves as a communication point for power-related event notifications. dpmmgr may be customized for your system's requirements through configuration files and plugin modules. Alternatively, you may develop your own Power Manager from scratch, configuring and controlling DPM by using the APIs documented in Chapter 12, “Plugin Commands and APIs.” DE S I G NI N G DP M S U S P E N D /R E S U M E D E V I CE S The MontaVista Power Manager can suspend and resume power to a device by writing to the sysfs power/state file for that particular device. Writing to the power/state file causes the driver suspend or resume function to be called, powering down or up the associated device. For example, the following command tells the LCD on any platform to suspend to state 3, which is a common number for the default low-power state supported by drivers: #echo -n 3 > /sys/devices/platform/<name>/power/state Where <name> is the name given by driver
  • 63. ..... D ES I G N IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Designing DPM Driver Scale Callbacks Designing DPM Driver Scale Callbacks 45 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . If you are writing your own drivers with suspend/resume callbacks, the exact calling sequence may vary depending on the kind of bus associated with the device. Many embedded devices are registered on the platform bus, which passes a level parameter to the callbacks. The levels are shown below: DE VIC E SU SP EN D 1. SUSPEND_DISABLE; 2. SUSPEND_SAVE_STATE; 3. SUSPEND_POWER_DOWN DE VIC E RE SU ME 1. RESUME_POWER_ON; 2. RESUME_RESTORE_STATE; 3. RESUME_ENABLE Depending on the specifics of the platform, the suspend mode requested and the device or driver, all three levels may or may not be useful and some may be ignored if not useful. Many drivers perform actions only at levels SUSPEND_DISABLE and RESUME_ENABLE. SPECIFYING POWER STATE VALUES Linux uses integer values from the ACPI standard to indicate device power states. Use value 0 to indicate full-on and a non-zero value to indicate lower-power state. The value 3 is a common default choice for device low power state. See Chapter 9, “Implementing Your Power Manager Building Blocks,” for how to use Power Manager commands to suspend and resume a system as well as how to suspend devices. DE S I G NI N G DP M D R I V E R S C A LE CA L L BA C K S DPM-enabled device drivers are more stateful than default drivers. They are driven through various states by external events and through callbacks from the kernel DPM subsystem to reflect operational policies. Mobilinux DPM has the capability to call drivers when scaling clock frequencies. This enables drivers to react to any necessary change on all platforms. This is done through the scale driver callback.
  • 64. DE SIG NI N G YO UR POWER M A N A GER BUIL DI N G B LO CK S 46 Designing Power-Related Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DE S I G NI N G P O W E R- RE L AT E D E V E NT S In order to make decisions on power state, you need to determine the power-related information that is to be communicated to the Power Manager from kernel drivers and applications. For example: • A device has been inactive for a period of time. • Application started or terminated. • Charger plugged in or remaining battery strength information. • Lid closed or other physical states of the product. • User has not interacted with the product for a period of time. The messages may come from kernel drivers or from other applications. The MontaVista Power Manager may perform some processing based on the event messages and will pass the event messages on to plugins and in some cases will also execute shell scripts. The event command enables provide the ability to inform the MontaVista Power Manager about various system and device power events, as explained in See Chapter 9, “Implementing Your Power Manager Building Blocks.” DE S I G NI N G P O W E R P O L I CI E S Policies may correspond to differing states of the product that have different power or performance needs. For example: • Product is in active use performing higher-power function. • Product is in active use performing lower-power function. • Product has been idle for a short period of time. • Product has been idle for an extended period of time. • Remaining battery strength has dropped below a certain threshold. • CPU usage is above a certain threshold. Each of these states might be associated with a different power policy to make desired tradeoffs between power consumption and performance appropriate for the different situations. dpmmgr is preconfigured with policies that may be appropriate for many of these situations.
  • 65. ..... D ES I G N IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Designing Programmable Sleep/Wakeup Sources Designing Programmable Sleep/Wakeup Sources 47 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D E S I G NI N G P R O G R A M M A B L E S L E E P / W A K E U P S O U R C E S Each platform may have one or more mechanisms available to wakeup the system from a sleep state. For example, the platform may support wakeup via one or more General- Purpose I/O (GPIO) interrupts, or from serial console activity, or from a Real Time Clock (RTC) alarm, etc. You may need to add code to enable the desired wakeup method. This may be performed by custom drivers, by board-specific bootup code, or by the code that places the system to sleep. Each Mobilinux LSP is typically preconfigured with at least one wakeup source for the board supported. D E S I G NI N G D P M T A S K S T A T E S You may wish to assign different operating points to different tasks, such that certain tasks run at a higher or lower power or performance level, as compared to the default level at which tasks not specially designated run. For example, a multimedia playback application that requires significant performance might be assigned a task state that boosts power or performance, while the default task state sets a lower power or performance point for other tasks without realtime response requirements that run in the background. Mobilinux LSPs are typically preconfigured with several task states. If more or less of these are desired then the kernel source must be recompiled with a new setting for DPM_TASK_STATE_LIMIT in the architecture-specific dpm.h header file under include/asm/. DE S I G NI N G S L E E P / S T A N DB Y B E H A V I O R If your product can enter sleep/standby/idle modes (as might occur when the user presses the off u button or closes the lid, or the product goes idle for a period of time), there may be a choice of platform sleep states to enter. DPM is preconfigured with one sleep operating state that can be used to enter a selected sleep mode through DPM interfaces. The choice of which mode to enter is a matter for the system designer to decide. This is chosen through the DPM policy, which maps the sleep
  • 66. DE SIG NI N G YO UR POWER M A N A GER BUIL DI N G B LO CK S 48 Designing Sleep/Standby Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . operating state to the operating point that enters the sleep mode appropriate for the situation in which each policy is activate. For example, a policy is activated when the product has been idle for a short period of time might map the DPM sleep operating state to a standby mode that is quick to enter and exit, while a policy for an extended period of idle might map sleep to a lower-power mode that requires a longer wakeup time. An explicitly requested sleep operating state is the correct way to enter a sleep mode through DPM. Associating a task state with a sleep operating point will probably not have the desired effect. That is, each time a task associated with that state is scheduled, the system will go to sleep and require a wakeup, as this may repeat each time the scheduler again chooses that task for rescheduling. Most DPM operating states are entered due to system scheduling and interrupt processing activity, but sleep states need to be specifically requested at appropriate times. The Power Manager application is typically the component that decides that the system should go to sleep and requests the sleep operating state be activated. You may find it useful to have your product perform custom actions prior to sleeping and/or after wakeup, for example, to save application state or to turn on or off devices.
  • 67. 49 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DESIGNING DEVICE INTERACTIONS WITH DPM A DPM power management strategy requires that the system designer carefully consider the influence of attached devices on the strategy. Typically, changing a policy or an operating point may require notification of device drivers for some actions, such as reprogramming bus controllers for a new frequency to insure correct and efficient operations. It is up to the underlying DPM implementation to handle this requirement during the change in the operating point. In general, the most efficient policies for flexible systems will minimize operating point changes that require device driver notification. This chapter covers the following topics: • “Design Considerations” • “Specifying Device Constraints” • “Specifying Power Event Userspace Notification” • “Specifying Device Constraints Interfaces” • “Creating Driver Interface to DPM” • “Exporting Driver DPM to Userspace”
  • 68. DE S IG NI N G D EV I C E I N TE R A C TI ON S W IT H DP M Design Considerations 50 Design Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DE S I G N C O N S I D E R A T I O N S In order to design device power management interactions with DPM consider the following design issues: HARDWARE RESTRICTIONS Some platforms place restrictions on the operating points that may be entered when certain devices are in use. Making use of those operating points in your DPM policies may need some coordination. This can take the form of power event messages from the driver letting Power Manager know that the device is active, or that it can be accomplished by using DPM device constraints. CONSTRAINTS V.S. EVENT MESSAGES Power event messages may be more appropriate when major changes in power policy might be needed in response to relatively infrequent changes in device state. For example, a device that has been inactive for a period of time may tell the MontaVista Power Manager about this event to allow the MontaVista Power Manager activate a new low-power policy, or to prepare the system enter a sleep state. Device constraints may be more appropriate for finer adjustments to power policy, especially for more frequent changes in device state. When used in conjunction with the DPM feature of operating point classes, constraints can cause DPM to choose a desired operating point from among a few alternatives provided in the class. For example, it may be possible to enter a lower-power operating point whenever a certain device is idle, and so DPM classes could be constructed to offer two operating points: one for when the device is active, and one for when the device is idle. HANDLING CONFLICTING DEVICES dpmmgr implements commands to power up and power down devices. This may be useful in situations in which power policy requires entering a low-power state that is incompatible with active devices: dpmmgr can power down the conflicting devices and then enter the needed state.
  • 69. ..... DE S IG NI N G D EV I C E I N TE R A C TI ON S W IT H DP M Specifying Device Constraints Specifying Device Constraints 51 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SCALE CALLBACKS In some cases a driver may need to implement the scale callback to be notified when a DPM operating point modifies a clock upon which correct operation of the device depends. The Mobilinux kernel source may already provide scale callbacks for drivers supported in Mobilinux that need to adjust device parameters in response to clocking changes performed by DPM. If you are adding additional drivers to the kernel in your product then you may need to add scale callbacks for some drivers. For example, the pixel clock of an LCD or other display device may need to be reprogrammed when the rate of the higher-layer clock that the LCD sources is modified. See Chapter 9, “Designing Device Interactions with DPM.” S P E C IF Y IN G DE V I C E C O N S T R A I NT S Typically, validating that policies do not violate device constraints is done by the DPM core. However, in some cases Power Manager performs some constraints processing itself. The sections that follow discuss the behaviors of the DPM core and Power Manager for device constraints. Upon reviewing their behavior, we can decide what sort of general description might best be used to describe the roles the DPM core and userspace Power Manager play. Power Manager can read and install constraints using the devices sysfs constraint file. CONSTRAINTS FOR AN OPERATING POINT If the active policy specifies a single operating point for the current operating state and the operating point violates a device constraint, the DPM kernel module will not set the operating point, leaving the system running at the previous operating point. This situation is best avoided whenever possible, since the intended power policy is not in effect and the system may be running at an inappropriate operating point that does not suit the power and performance needs of the current system state. Power Manager, however, avoids the above-mentioned situation in the case in which the system is being suspended and the operating point for the sleep state to enter has the force attribute set. If the force attribute is set for the sleep operating point and the operating point violates a device constraint, then Power Manager will power off the device that registered the constraint before activating the sleep operating point. The system designer can thus inform Power Manager to shut down devices and enter a low-power state when critical to do so, such as in low-battery conditions.
  • 70. DE S IG NI N G D EV I C E I N TE R A C TI ON S W IT H DP M Specifying Power Event Userspace Notification 52 Specifying Power Event Userspace Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CONSTRAINTS FOR AN OPERATING CLASS If the active policy specifies an operating class of operating points for the current operating state then DPM chooses one of the operating points in the class that do not violate device constraints. SPECIFYING POWER EVENT USERSPACE NOTIFICATION For a variety of reasons, communicating information on power requirements or state changes from the kernel to a userspace MontaVista Power Manager may be necessary. This notification of kernel and application power events may, for example, request a system suspend in response to an interrupt received due to a button press, or it may communicate device status changes that could lead the MontaVista Power Manager to change the system power state. POWER HOTPLUG AGENTS DPM provides functions to notify userspace through the hotplug mechanism, which traditionally notifies userspace policy handlers of changes in devices present along with associated chores such as downloading firmware for new devices. When the DPM power event functions are called, hotplug executes an agent script to perform userspace handling of the power event. The DPM power events are sent to script /etc/hotplug/power.agent, supplying parameters that are described in the sections that follow for the particular types of power. Mobilinux provides the necessary agent scripts to communicate power events to the MontaVista Power Manager. If you are using your own power manager you may want to customize these scripts to communicate with your application.
  • 71. ..... DE S IG NI N G D EV I C E I N TE R A C TI ON S W IT H DP M Specifying Device Constraints Interfaces Specifying Device Constraints Interfaces 53 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . S P E C IF Y IN G D E V I C E C O N S T R A I N T S I N T E R F A C E S Device constraints may be specified and managed by driver code in the kernel, or from userspace through the sysfs interface under the control of a power policy management application. The ability to enforce constrained operating points is handled by the kernel platform code or from userspace through sysfs. SPECIFYING CONSTRAINTS THROUGH SYSFS The following is the syntax to specify constraints: <param-name> <min-value> <max-value> These values are written to the power/constraints attribute of the sysfs file for the device. Writing a constraint with the same power parameter as an existing constraint overwrites the previous constraint: echo "dpll-mult 14 16" > /sys/devices/platform/omapfb0/power/constraints echo "dpll-mult 12 14" > /sys/devices/platform/omapfb0/power/constraints changes the constraint minimum and maximum values for the dpll-mult power parameter. Minimum or maximum value -1 indicates no constraint has been assigned. The above constraints could be removed through: echo "dpll-mult -1 -1" > /sys/devices/platform/omapfb0/power/constraints To read or write constraints, see Chapter 5, “DPM Device Driver Interfaces.” Device constraints may also be specified using the constraints field of the struct device, which is a pointer to a struct constraints. Constraint parameters are identified by the same constants used to index the hardware parameters in the operating point dpm_md_pp_t array. An example for a platform that interprets identifier DPM_MD_PLL as the index of a power parameter that indicates if the PLL is on or off: static struct constraints my_constraints = { count: 1, param: {{DPM_MD_PLL, 1, 1},}, /* require the PLL be on */ }; static struct device my_device = { ... constraints: &my_constraints, }
  • 72. DE S IG NI N G D EV I C E I N TE R A C TI ON S W IT H DP M Creating Driver Interface to DPM 54 Creating Driver Interface to DPM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The values of the param field correspond to the power_param_id, min_value, and max_value, parameters of the sysfs attribute described above. ASSERTING CONSTRAINTS Device constraints are normally asserted whenever the device is powered on and are deasserted whenever the device is powered off. DPM activates and deactivates device constraints when a device is suspended and resumed. Constraints can also be managed by the driver by calling: assert_constraints(dev->constraints) deassert_constraints(dev->constraints) C RE AT I NG D RI V E R I N T E RF A C E T O D P M Each driver must declare a struct device_driver data structure for itself and a struct device for each device it manages. Examples for a hypothetical driver (excluding power management information) are provided in the following example. Note: Non-power-management-related LDM features such as the probe driver callbacks, or registering operating classes or interfaces, are not used in these code examples. Most embedded devices that do no appear on a standard bus such as PCI can be registered as platform devices on the built-in platform bus. Example code for Mobilinux: static struct device_driver mydriver = { .name = "mydevice", .bus = &platform_bus_type, .probe = mydriver_probe, .suspend = mydriver_suspend, .resume = mydriver_resume, }; driver_register(&mydriver); The LDM code will call mydriver_probe to establish a binding between the driver and the device when any device with a name starting with mydevice is registered on the platform bus. The device data structures and registration call typically appear in a board-specific file (not the driver itself), allowing for board-specific customization of the device characteristics.
  • 73. ..... DE S IG NI N G D EV I C E I N TE R A C TI ON S W IT H DP M Exporting Driver DPM to Userspace Exporting Driver DPM to Userspace 55 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . For example, your platform may define: static struct platform_device mydevice = { .name = mydevice, .id = -1, .dev = { .platform_data = &myboard_data}, }; platform_device_register(&mydevice); Note: Your particular platform may have special conventions or requirements that require use of board-specific or other busses for some drivers. E X P O R T I N G D R I V E R D P M T O U S E R S P A C E This section describes the user-space interface to driver power management information. The sysfs file system is used to export driver power management attributes to user-space. The /sys directory is the recommended mount point, for example: mount -t sysfs /sys Each device is associated with a logical bus. The logical bus definition is based on the categorization of devices in documentation specific to your board. For example, the command ls -1 /sys/bus on a particular board might display the following: i2c mmc platform scsi serio Likewise, the command ls -1 /sys/bus/platform/devices might display the following contents: mmci-omap.1 omap_rtc omapfb omapflash.0 ps2 serial8250 serial8250.0 smc91x.0
  • 74. DE S IG NI N G D EV I C E I N TE R A C TI ON S W IT H DP M Exporting Driver DPM to Userspace 56 Exporting Driver DPM to Userspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Each device is a directory, so you can display the contents using the standard list command. For example, ls -1 /sys/bus/platform/devices/omapfb displays the contents of omapfb: bus caps_num caps_text ctrl driver panel power
  • 75. 57 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 IMPLEMENTING YOUR POWER MANAGER ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BUILDING BLOCKS Chapter 8, “Designing Device Interactions with DPM,” explained how to design different components of your power management system. This chapter covers the specific tasks that you need to execute to implement your design. The following topics are covered in this chapter: • “Implementing Power Management for Custom Drivers” • “Implementing Precompiled Device Constraints” • “Implementing Driver Scale Callbacks” • “Implementing Notification of Kernel Power Events” • “Developing Your Power Manager” • “Implementing Notification of Application Power Events” • “Implementing DPM Operating Points” • “Implementing DPM Operating Classes” • “Implementing DPM Operating Policies” • “Implementing Policy Manager Handling of Events” • “Implementing Other Logic for Determining Power Policy” • “Implementing Runtime Device Constraints” • “Implementing System Suspend/Resume” • “Implementing Device Power State Modifications”
  • 76. IM P LE M EN T IN G YOU R POWE R M A N A G E R BU I LD IN G B LO CK S 58 Implementing Power Management for Custom Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG P O W E R M A NA G E M E N T F O R C US T O M D R I V E RS Mobilinux provides suspend/resume power management capability for most or all devices that are supplied with the board supported by your LSP. If additional drivers are added to your product, you may need to add suspend/resume callbacks to those drivers. This ensures that devices are properly shut down and restarted across a system sleep, as well as decreasing power consumption during sleep is accomplished. The following two generic power management functions and header file need to be added to a platform_device driver for it to respond to suspend and resume commands: # include <linux/device.h> # ifdef CONFIG_PM static int dpm_example_suspend (struct device *dev, u32 state, u32 level) { int ret = 0; if (level == SUSPEND_DISABLE) printk("suspendingn"); return ret; } static int dpm_example_resume (struct device *dev, u32 level) { int ret = 0; if (level == RESUME_ENABLE) printk("resumingn"); return ret; } # endif The driver device structure needs to have those two function pointers initialized. static struct device_driver dpm_example_driver = { .name = “dpm-example”, .bus = &platform_bus_type, .suspend = dpm_example_suspend, .resume = dpm_example_resume, };
  • 77. ..... IM P LE M EN T IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Implementing Precompiled Device Constraints Implementing Precompiled Device Constraints 59 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I N G P R E C O M P I L E D D E V I C E C O N S T R A I N T S You can add precompiled device constraints to drivers, in addition to any device constraints already supplied in the Mobilinux kernel source. You can instead create and modify device constraints from an application or from dpmmgr during runtime, which will reduce the kernel changes needed for DPM. See “Implementing Runtime Device Constraints.” The device constraint structure needs to be initialized. # ifdef CONFIG_DPM # include <asm/dpm.h> static struct constraints dpm_example_constraints = { .count = 1, /* constrain the clock to be > 0 */ .param = {{DPM_MD_CLOCK, 1, 999999},}, /* target specific */ }; # endif I M P LE M E NT I NG D RI V E R S C AL E C A L LB A C K S You may need to add scale callbacks to drivers to react to changes in upstream clocks, as determined in Chapter 8, “Designing Device Interactions with DPM.” static struct device_driver dpm_example_driver = { .name = “dpm-example”, .bus = &platform_bus_type, .suspend = dpm_example_suspend, .resume = dpm_example_resume, .scale = dpm_example_scale, }; The following is an example of a scale call back function: static int dpm_example_scale(u32 level) { int ret = 0; printk("scalingn"); return ret; }
  • 78. IM P LE M EN T IN G YOU R POWE R M A N A G E R BU I LD IN G B LO CK S 60 Implementing Notification of Kernel Power Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG N O T I F I C AT IO N O F K E R NE L P O W E R E V E NT S Choose a unique name for the event that the MontaVista Power Manager can use to recognize that event. Other parameters to fully describe the event may also be needed. Communicating information on power requirements or state changes from the kernel to a userspace power policy manager may serve several purposes. The information may, for example, request a system suspend in response to an interrupt received due to a button press, or may communicate device status changes that could lead the policy manager to change system power state. DPM provides functions to notify userspace through the hotplug mechanism, which traditionally notifies userspace policy handlers of changes in devices present, along with associated tasks such as downloading firmware for new devices. Hotplug executes an agent script to perform userspace handling of the power event. The DPM power events are sent to script /etc/hotplug/power.agent, supplying parameters that are described in the subsections for the particular types of power events below. All other events are passed through to the plugin_event_handler functions for the loaded plugins, without further processing by dpmmgr. D E V E L O P I N G Y O U R P O W E R M A N A G E R If you are developing your own MontaVista Power Manager from scratch, you first need to initialize DPM. dpmmgr will automatically initialize DPM at startup. If you are using dpmmgr as a starting point, you need to customize its default configuration file in /lib/modules/$(uname -r)/dpmmgr.conf. You might also write a plugin to customize dpmmgr for your product’s needs. Your MontaVista Power Manager will probably also be the software that configures DPM with operating points, classes, and policies, as described in the following sections.
  • 79. ..... IM P LE M EN T IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Implementing Notification of Application Power Events Implementing Notification of Application Power Events 61 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG N O T I F I C AT IO N O F A P P LI C A T I O N P O W E R E V E N T S Choose a unique name that the MontaVista Power Manager can use to recognize the event. Other parameters to fully describe the event may also be needed. General-purpose power information may be communicated using function power_event(): power_event(char *msg); msg a free-format string to be sent to your userspace power policy manager. The msg string is passed to power.agent in variable EVENT. The ACTION variable is event. A sample script fragment for this is: case $ACTION in event) DEBUG=yes debug_mesg "Power event: $EVENT" ;; I M P LE M E NT I NG D P M O P E R A T I N G P O I NT S Based on the kinds of power policies to be employed, create the DPM operating points needed for the DPM policies. See “Designing Power Policies,” Chapter 7, “Designing Your Power Manager Building Blocks.” Information on choices of values of power parameters for your operating points may be available from the following sources: • The power parameter values or operating points supported by the vendor for your hardware. See “Studying Your Hardware’s Power Management Characteristics,” in Chapter 8, “Designing Device Interactions with DPM.” • The DPM Developer’s Guide for the Mobilinux LSP for your hardware.
  • 80. IM P LE M EN T IN G YOU R POWE R M A N A G E R BU I LD IN G B LO CK S 62 Implementing DPM Operating Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXAMPLES The following examples create an operating point named “312mhz” with several power parameters for a PX27x Mainstone board: US IN G DP MMG R .C ON F # operation points op 312mhz v=1250 l=16 n=3 b=1 half_turbo=0 cccra=0 cpll-on=1 ppll-on=1 sleep_mode=0 US IN G DP ML IB if (dpm_create_op("312mhz", NULL)) { perror("dpm_create_op"); exit(1); } if (dpm_set_op_param("312mhz", "v", 1250)) { perror("dpm_set_op_param"); exit(1); } if (dpm_set_op_param("312mhz", "l", 16)) { perror("dpm_set_op_param"); exit(1); } ... US IN G SYS F S echo create 312mhz >/sys/dpm/op/control echo -n 1250 >/sys/dpm/op/312mhz/v echo -n 16 > /sys/dpm/op/312mhz/l ...
  • 81. ..... IM P LE M EN T IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Implementing DPM Operating Classes Implementing DPM Operating Classes 63 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG D P M O P E R A T I N G C L A S S E S If you are using DPM operating point classes first see “Guidelines for Setting up DPM Operating Points,” in Chapter 7, “Designing Your Power Manager Building Blocks.” Next, you will need to create the needed classes. You will probably want to construct classes such that one operating point is never constrained by devices and can always be chosen, in case device constraints prevent setting the other operating points in the class. If all operating points in the class are constrained then DPM will simply not set an operating point in response to the change in operating state or policy that triggered DPM to check the class for an appropriate operating point. This will leave the system executing at the operating point that was active prior to the change, which may not be appropriate for the new state. EXAMPLES The following examples create an operating class named “full” that contains two operating points that were previously created, named “256Khz” and “312Khz”. US IN G DP MMG R .C ON F class full 256Khz 312Khz US IN G DP ML IB if (dpm_create_class("full", "256Khz 312Khz")) { perror("dpm_create_class"); exit(1); } US IN G SYS F S echo create full 256Khz 312Khz > /sys/dpm/class/control
  • 82. IM P LE M EN T IN G YOU R POWE R M A N A G E R BU I LD IN G B LO CK S 64 Implementing DPM Operating Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG D P M O P E R A T I N G P O L I CI E S You need to create DPM policies that correspond to the needed power policies, as discussed in “Designing Power Policies,” in Chapter 8, “Designing Your Power Manager Building Blocks.” Choose operating points, as shown in “Implementing DPM Operating Points,” or choose operating classes, as shown in “Implementing DPM Operating Classes.” Next, set the operating points or operating classes you have chosen here for each operating state, according to the power/performance levels appropriate for the state and for the situation in which the particular policy will be activated. If you are using task states, as determined in “Designing DPM Task States,” in Chapter 7, “Designing Your Power Manager Building Blocks.” Next, you will need to assign relatively higher- or lower-powered operating points for the task states that are designated higher- or lower-powered than the default task state. The following descriptions are helpful in making decisions regarding which operating point to associate with operating states. ID LE S TA TE The idle operating state is set whenever the Linux scheduler determines that there is no task to be run and so the idle loop is executed. The idle loop waits for an interrupt to arrive, and can, in general, run at a low-power operating point. This state may be entered and exited very often. Depending on application real time deadlines and system power consumption goals, it may be necessary to choose an operating point with low latency to enter and exit, and not necessarily the lowest-power operating point available. ID L E- TA SK S TA TE The idle-task operating state is set when woken from idle but before scheduling a task to run. Interrupts that arrive while the system was idle are serviced in this state, and certain kernel daemons that extend interrupt processing, such as ksoftirqd. The scheduler processing that decides which process to execute next also run in this state for interrupts that arrive during idle. Interrupts that are serviced while in a task state, on the other hand, are serviced while in that task state. The operating point used for idle-task state should be powerful enough to handle interrupts in a timely manner, while conserving power if possible, since the highest
  • 83. ..... IM P LE M EN T IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Implementing DPM Operating Policies Implementing DPM Operating Policies 65 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . power/performance levels of the platform would not be needed to service low-power interrupts. The system transitions between idle, idle-task, and task very frequently. If long latencies are involved in transitioning between the operating points chosen for these states then the performance or realtime response of applications might be impaired. EXAMPLES The following examples create a policy named “hi-power” that maps all operating states to an operating point or an operating class named “full” that was previously created. US IN G DP MMG R .C ON F policy hi-power idle,idle-task,task,task+1,task+2,task+3,task+4=full US IN G LI BD P M if (dpm_create_policy("hi-power", NULL)) { perror("dpm_create_policy"); exit(1); } if (dpm_set_policy_state_map("hi-power", "idle" "full")) { perror("dpm_set_policy_state_map"); exit(1); } if (dpm_set_policy_state_map("hi-power", "idle-task" "full")) { perror("dpm_set_policy_state_map"); exit(1); } ... US IN G SYS F S echo create hi-power > /sys/dpm/policy/control echo -n full > /sys/dpm/policy/hi-power/idle echo -n full > /sys/dpm/policy/hi-power/idle-task
  • 84. IM P LE M EN T IN G YOU R POWE R M A N A G E R BU I LD IN G B LO CK S 66 Implementing Policy Manager Handling of Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IMPLEMENTING POLICY MANAGER HANDLING OF EVENTS If drivers or applications are expected to send power-related events to your MontaVista Power Manager, as shown in “Designing Power-Related Events,” in Chapter 7, “Designing Your Power Manager Building Blocks,” then Power Manager logic to read and/or handle these events needs to be implemented. Power Manager would typically recognize the events by name and adjust power state accordingly, taking an action such activating a different policy or to power or down devices. If you used dpmmgr, then it provides the code to read events and commands, to perform various actions upon receipt of events, and to pass event messages to plugins for custom handling. The event handlers may perform such actions as: • Activate a new DPM policy. See “Activating a Policy,” in Chapter 10,“Starting Your Power Manager.” • Power up or down a device. See “Implementing System Suspend/Resume.” • Feed new information to custom algorithms that select policies. See “Implementing Other Logic for Determining Power Policy.” • Put the system into sleep. See “Implementing System Suspend/Resume.” I M P LE M E NT I NG O T H E R L O G I C F O R D E T E R M I N I NG P O W E R P O L I CY There may be other information useful for making power policy decisions to be factored into your Power Manager’s algorithms. For example, information on Linux system state or hardware profiling registers might help decide appropriate power policy and/or device power states. If using dpmmgr, the dpm-profiler plugin is available to make decisions based on how busy the system is.
  • 85. ..... IM P LE M EN T IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Implementing Runtime Device Constraints Implementing Runtime Device Constraints 67 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG R UN T I M E D E V I C E C O N S T RA I N T S Device constraints can be set or modified through the DPM sysfs interface or using dpmmgr commands, rather than hard-coding these into kernel driver sources. This may be useful if the necessary constraints can be managed from the Power Manager application, or to avoid modifying drivers to precompile constraints when these can be set from Power Manager instead. Constraints may be read and written using the sysfs constraints power attribute of the device, /sys/devices/bus/device-id/power/constraints. The format of strings written to this attribute is: power_param min_value max_value where: power_param is the name of a power parameter for the platform, min_value is the minimum value of that power parameter, or -1 for no minimum, max_value is the maximum value of that power parameter, or -1 for no maximum. For example: echo "pll 66 266" > /sys/devices/my-bus/my-device/power/constraints The above example causes device my-device to constrain the power parameter named pll to values between 66 and 266. Writing new values for a different power parameter to the constraints attribute adds new constraints for that device. Writing new values for a power parameter that already appears overwrites the old values. If the new maximum or minimum value is -1, the existing maximum or minimum constraint is removed.
  • 86. IM P LE M EN T IN G YOU R POWE R M A N A G E R BU I LD IN G B LO CK S 68 Implementing System Suspend/Resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG S Y S T E M S U S P E N D/ R E S UM E In “Designing Sleep/Standby Behavior,” in Chapter 7, “Designing Your Power Manager Building Blocks,” the needed platform suspend modes were identified and policies were created to map the sleep operating state to operating points that enter the needed sleep modes. There may also be other actions appropriate to take prior to suspend and after resume. The interfaces to enter the sleep state and perform these custom actions are described below. dpmmgr is typically configured to setup at least one operating point that enters a sleep mode for the platform. It also provides scripts that may be executed at suspend and resume times to perform custom actions at those times. EVENT HANDLING The Power Manager event command informs the user about various system and device power events. The messages may come from kernel drivers or from other applications. The Power Manger may perform some processing based on the event messages and will pass the event messages on to plugins, and in some cases will also execute shell scripts. The parameter to the event command is a word that describes the type of the event, along with a string of parameters that further describes the event. All other events are passed through the plugin_event_handler functions for the loaded plugins, without further processing by dpmmgr. In some cases, it may be useful to communicate device-specific information on power requirements from drivers to a userspace Power Manager. For example, the information may request a change in a system power state to accommodate a change in the device power state, or it may be a hint regarding expected device activity that Power Manager may use for device system or device power levels. SUSPEND AND RESUME HANDLING The Power Manager suspend command, or an event mapped to a suspend command first executes dpmmgr to check the requested (or defaulted) sleep operating state against device constraints. If not rejected by the previous methods, these suspend-resume scripts are executed (if present) before and after the actual system suspend, respectively.
  • 87. ..... IM P LE M EN T IN G YOU R POWER M A N A G E R B U I LD IN G B L OC K S Implementing Device Power State Modifications Implementing Device Power State Modifications 69 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I M P LE M E NT I NG D E V I C E P O W E R S T A T E M O D I F I C A T I O N S It may be necessary for the MontaVista Power Manager to manage the power state of devices. For example, Power Manager may decide to power down devices due to an event, such as an indication of battery low. If you are using dpmmgr, an example command is: suspend device platform/omapfb
  • 88. IM P LE M EN T IN G YOU R POWE R M A N A G E R BU I LD IN G B LO CK S 70 Implementing Device Power State Modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  • 89. 71 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . STARTING YOUR POWER MANAGER After designing and then implementing the building blocks of your MontaVista Power Manager, next you may start Power Manager, dpmmgr. The following topics are covered in this chapter: • “Running Your Power Manager” • “Starting Applications with DPM interactions” • “Testing Your Power Management System.” • “Activating a Policy”
  • 90. S T A R T IN G YOU R POWE R M A N A G E R Running Your Power Manager 72 Running Your Power Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R UN N I NG Y O U R P O W E R M A NA G E R This section provides instructions that can automatically start dpmmgr during each boot. STARTING POWER MANAGER MANUALLY You can start dpmmgr manually from the Mobilinux development kit by entering the following command: # /etc/init.d/dpmmgr start To check for errors, enter the following: # /var/log/dpmmgr.log STARTING POWER MANAGER AUTOMATICALLY In order to have Power Manger auto start or shut down with the system, use the utility initdconfig: initdconfig dpmmgr on This will enable the dpmmgr rc script. S T A R T I N G A P P L IC A T I O N S W I T H D P M I N T E R A CT I O N S Now that your MontaVista Power Manager is ready to receive power event notifications and DPM is initialized, applications that interact with your Power Manager or that should run under a particular DPM task state can be started. To run a process with a non-default task state enter the following: DPMLIB This example sets the caller's task state to task-1: include <linux/dpm.h> struct dpm_param params; params.pid = getpid(); params.task_state = DPM_TASK_STATE-1; if (sys_dpm(DPM_SET_TASK_STATE, &params)) perror("sys_dpm(DPM_SET_TASK_STATE)");
  • 91. ..... S T A R TI N G YO U R POW ER M A N A G ER Testing Your Power Management System Testing Your Power Management System 73 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . /PROC This example sets the shell's task state to task-1: echo -n "task-1" > /proc/$$/dpmstate A new process will inherit the DPM task state of its parent process. If a process is running at a non-default task state then all processes it forks will be assigned the same task state. This can be a convenient way to run non-DPM-aware processes at a specific task state. There may be a correlation between the DPM task state at which a process is to run and the scheduling priority at which it is to run. In general, applications that are given high scheduling priority are often also assigned a high power/performance level. However, there may be situations in which the application can meet its deadlines while conserving power by running at a lower power level but with high scheduling priority, to ensure that it completes prior to scheduling a less important task. T E S T I N G Y O U R P O W E R M A N AG E M E N T S Y S T E M The following tools for testing your power management system are available: • Test equipment such as multimeters and logic analyzers to probe points of interest on the board or to measure current drawn, etc. • The following command shows the number of times each operating state has been entered, to help understand what operating states are being set while your system runs: cat /sys/dpm/state/stats For example, if you have processes running at non-default task states, this will help verify how often those tasks are being scheduled. • The following command displays the number of times each operating point has been set, to help understand the operating points at which your system runs. cat /sys/dpm/op/stats • The following displays the number of times each policy has been activated, to help understand the policies at which your system runs: cat /sys/dpm/policy/stats • Kernel and application power events can be simulated by sending the messages from a command-line dpmmgr execution. For example the following command will send the named event and argument to dpmmgr in much the same way as would an actual event message from the kernel via power_event ("buttonpress topbutton"): /usr/sbin/dpmmgr "event buttonpress topbutton"
  • 92. S T A R T IN G YOU R POWE R M A N A G E R Activating a Policy 74 Activating a Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AC T IV AT I NG A P O L I C Y In order to start DPM managing the power state of your system, you need to activate a power policy. Choose which policy to activate initially, which might be hard-coded to high- or low-power policy depending on anticipated power needs at the time the Power Manager begins to run, or might be selected by a custom algorithm based on system state. USING DPMMGR dpmmgr "set policy <name>" USING SYSFS echo -n <name> > /sys/dpm/policy/active
  • 93. 75 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . POWER MANAGER COMMANDS MontaVista Power Manager serves as the preferred DPM interface, instead of direct access of the lower-level interfaces. It provides basic DPM policy management, switching power settings, for example, to a higher performance level when system load increases. Power Manager ties together the various components involved in a power management system, such as kernel drivers and power-aware applications, into a framework that you may want to use for your products. The following topics are covered in this chapter: • “Power Manager commands Accessibility” • “Operating Points and Classes Commands” • “Power Policy Commands” • “Power State Commands” • “Device Power State Commands” • “Device Constraint Commands” • “System Status Commands” • “Power Events Commands”
  • 94. POWER M A N A G ER C O M M A ND S Power Manager commands Accessibility 76 Power Manager commands Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P O W E R M A NA G E R C O M M A ND S A C CE S S I B I L I T Y The Power Manager commands provided in this chapter are available from the configuration file during startup, or from another dpmmgr invocation through the command-line parameter. COMMANDS SYNTAX Command lines may consist of several dpmmgr commands separated by semicolons (;). A pound sign (#) begins a comment line. There are no quoting characters to escape the interpretation of semicolons or pound signs. Various commands refer to devices using syntax bus/device. This is a string comprised of a sysfs bus name and a sysfs device name separated by a forward slash (/). For example, platform/omapfb0 refers to the device named omapfb0 on the platform bus. O P E RA T I N G P O I N T S A N D C L A S S E S C O M M A ND S op name [param=value...] Define a new operating point or modify parameters for an existing operating point. Any parameters not named for a new operating point are set to -1 (the no change / use default value parameter value). Other named attributes of operating points, such as the force flag, may also be set this way: op myop force=1. class name op op... Define a new class of operating points, or modify an existing class. P O W E R P O L I CY CO M M AN D S policy name state[,state...]=class/op... Define a new policy or modify an existing policy. set policy name Set the policy to activate.
  • 95. ..... POWER M A N A G ER C O M MA ND S Power State Commands Power State Commands 77 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P O W E R S T A T E C O M M A N D S suspend system [state [args]] Suspend the system, eventually entering the DPM sleep operating state state, or state sleep if not specified. args are passed to the plugins and scripts that handle the suspend. D E V I C E P O W E R S T A T E C O M M A N D S suspend device bus/device [state] Suspend a device, entering state state, or state 3 if not specified. resume device bus/device Resume a device. DE V I C E C O N S T R A I NT CO M M AN D S constrain bus/device param min max Set or remove a device power parameter constraint. S Y S T E M S T A T U S C O M M AN D S status Report a status summary to stdout.
  • 96. POWER M A N A G ER C O M M A ND S Power Events Commands 78 Power Events Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P O W E R E V E N T S C O M M A N D S on event event command-line Execute a command line, which may consist of multiple commands separated by semicolons, upon receipt of an event. Can be used to requested a system suspend in response to an event, or to activate a different policy. This command consumes the rest of the command line: any subsequent commands separated by semicolons are added to the command line to be executed upon the named event. The following strings are substituted in the command-line: %e event name (the event parameter) %a event arguments (the args parameter from the event or suspend command) event event-args Process a power event. See the section on Event Handling for more information.
  • 97. 79 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PLUGIN COMMANDS AND APIS The MontaVista Power Manager enables you to add value by adding plugins that extend the features of a base policy manager. The following topics are covered in this chapter: • “Power Manager Commands Accessibility” • “Plugin Commands” • “Plugin APIs”
  • 98. P LU G IN CO M M A N DS A ND A P I S Power Manager Commands Accessibility 80 Power Manager Commands Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P O W E R M A NA G E R C O M M A ND S A C CE S S I B I L I T Y The Power Manager commands provided in this chapter are available from any source, including FIFO /tmp/dpmmgr.fifo during runtime to receive commands from applications and kernel event messages (as from power hotplug scripts), as well as from plugins through plugin API function calls. COMMANDS SYNTAX Command lines may consist of several dpmmgr commands separated by semicolons (;). A pound sign (#) begins a comment line. There are no quoting characters to escape the interpretation of semicolons or pound signs. Various commands refer to devices using syntax bus/device. This is a string comprised of a sysfs bus name and a sysfs device name separated by a forward slash (/). For example, platform/omapfb0 refers to the device named omapfb0 on the platform bus. P L U GI N C O M M A ND S The following Power Manager commands are provided from plugins: load file Load a plugin from the specified dynamic library file. The plugin will be referred to by the filename (without extension) in other commands. tell plugin command-string Send command-string to the named plugin. interval n Call the plugin_poll_handler callback for all loaded plugins every n seconds. shell command Execute a shell command through system().
  • 99. ..... P LU G I N C OM M A N DS A N D A PI S Plugin APIs Plugin APIs 81 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P L U G I N A P I S A plugin is added by creating a shared library that conforms to the Plugin API and loading the plugin into the policy manager using the load command. The Power Manager Plugin API includes these callbacks (functions called by dpmmgr into the plugin): int command_handler(char *cmd) Called to handle a tell command string. void poll_handler(void) Called periodically to poll for changes in system state. The poll interval is set using the interval command. int suspend_handler(char *args, char *sleep_state) Callback to notify of an impending system suspend request. The plugin may return an error to veto the suspend request. See the section on Event Handling for more information. void resume_handler(void) Callback to notify of system resume. void event_handler(char *event, char *args) Callback to notify of a non- suspend/resume power event. See Chapter 9, “Implementing Your Power Manager Building Blocks,” for more information about event handling. void status_handler(char *event, char *args) Callback to report plugin-specific status as part of a status command. int dpmmgr_command(char *cmdline) The Plugin API includes this function in dpmmgr that the plugin may call. This function execute a dpmmgr command line to switch to a different policy.
  • 100. P LU G IN CO M M A N DS A ND A P I S Plugin APIs 82 Plugin APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  • 101. 83 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . POWER MANAGER PROFILER PLUGIN MontaVista provides the dpm-profiler plugin with the Power Manager. This plugin measures the CPU load and sets profiles and DPM policies according to the dpm-profiler commands. The following topic is covered int his chapter: • “DPM-Profiler Plugin Commands” • “Terms Definitions”
  • 102. POWER M A N A G ER P R OF IL ER P LU G I N DPM-Profiler Plugin Commands 84 DPM-Profiler Plugin Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D P M - P R O F I L E R P L U G I N CO M M A N D S The following are the DPM-profiler plugin commands. For definitions of terms metric and profile used by these commands, see “Terms Definitions.” tell dpm-profiler cpu percentage[%] [+]n Increase the power metric by n when the CPU is at the given utilization. tell dpm-profiler [profile profile] at n command Perform the specified command when the power metric is at or above the given value, and when the named power profile is active. The command might be to activate a certain policy, or to remap the task operating state to a new operating point under the current policy, etc. The mapping of power metric to command takes effect only when the associated power profile is active. A power profile may be named in order to associate the mapping with a specific profile (activated using the tell dpm-profiler set profile command), or may be omitted, in which case the mapping is associated with the power profile named default. tell dpm-profiler set metric [+/-]n Set the power metric to the parameter, or adjust the power metric up or down according to the parameter. tell dpm-profiler set profile profile Activate the named power profile, which will become the power profile in effect until another tell dpm-profiler set profile command is given. May specify the built-in profile names default (for commands given without a profile specified) and none (no power profile activated, disabling profile-selector from evaluating power metrics and executing commands associated with metrics through tell dpm-profiler at commands).
  • 103. ..... POWE R M A N A G E R P R OF I LE R P L UG IN Terms Definitions Terms Definitions 85 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . T E R M S D E F I N I T I O N S The following terms are used by DPM-profiler plugin commands: POWER PROFILE A power profile describes a high-level state of your power management system. It can be thought of as a level above the DPM policy that describes which set of policies are appropriate for the current state of the power management system. For example, there may be one profile for use when the battery is at high or medium strength, and another profile for when battery strength is low. dpm-profiler is configured to take certain actions based on the value currently computed for the power metric (described below), with the most common action being to activate a different policy. These mappings of power metric values to actions are configured differently for different power profiles. Activating a different profile will switch to a different set of mappings between power metrics and actions. Activating a different profile might occur in response to an event notification of, for example, battery strength falling below a certain level. The active DPM policy maps operating states to operating points, dpm-profiler adds logic to switch policies based on metrics such as CPU usage, and the power profile selects which set of mappings between metrics and policies is appropriate for the current overall system state, commonly based on remaining battery strength. POWER METRIC The power metric is a value that can be used to tell dpm-profiler to select different power profiles or policies, based on system profiling information collected by your power manager plugin or based on rules built into dpm-profiler. The power metric can be specified using dpm-profiler commands that adjust the value up or down in response to calculations performed in your plugin, or that set the value according to built-in calculations that dpm-profiler performs, such as to set the value based on CPU usage. dpm-profiler will recalculate the power metric at each poll interval and take the action for which it has been configured, based on the resulting value and the currently-active profile. Typical actions might be to activate a different power profile or DPM policy.
  • 104. POWER M A N A G ER P R OF IL ER P LU G I N Terms Definitions 86 Terms Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  • 105. 87 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM APIS This chapter provides DPM library functions for libdpm DPM API-based as well as sys_dpm-based interfaces. The following topics are covered in this chapter: • “libdpm DPM APIs Interface” • “sys-dpm APIs Interface”
  • 106. DP M AP I S libdpm DPM APIs Interface 88 libdpm DPM APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . L IB D P M D P M A P I S I N T E RF A C E The API based functions in this section are able to control the operations of DPM through the libdpm DPM API interface, as follows: INT DPM_INIT() DE SC R IPT ION Initialize DPM. EXA MP L E if (dpm_init()< 0) perror("sys_init"); INT DPM_SET_STATE (CHAR *STATENAME) DE SC R IPT ION Set an operating state by name. EXA MP L E if (dpm_set_state(name) < 0) perror("dpm_set_state"); INT DPM_CREATE_OP (CHAR *OPNAME, CHAR *PARAMS) DE SC R IPT ION Create an operating point. params is recommended to be NULL, but it may specify a list of parameter values in board-specific order according to the numeric order of power parameter indices that was defined for the board. Using this parameter is discouraged; instead using dpm_set_op_param() to set each power parameter is recommended. EXA MP L E if(dpm_create_op("600M", NULL) < 0) perror("dpm_create_op");
  • 107. ..... D PM A PI S libdpm DPM APIs Interface libdpm DPM APIs Interface 89 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INT DPM_SET_OP_PARAM (CHAR *OPNAME, CHAR *PARAMNAME, INT PARAMVALUE) DE SC R IPT ION Set a power parameter for an existing operating point. EXA MP L E if (dpm_set_op_param("600M", "cpu", "600") < 0){ perror("dpm_set_op_param"); INT DPM_GET_OP_PARAM (CHAR *OPNAME, CHAR *PARAMNAME, CHAR *BUF, SIZE_T BUFSIZ) DE SC R IPT ION Read a power parameter for an operating point into buf. EXA MP L E if(dpm_get_op_param("Static", "cpu", buf, sizeof(buf)) < 0){ perror("dpm_get_op_param"); INT DPM_CREATE_CLASS (CHAR *CLASSNAME, CHAR *OPNAMES) DE SC R IPT ION Create a new class (or re-create an existing class with new list of operating points). EXA MP L E if (dpm_create_class("on", "600M") < 0){ perror("sys_dpm(DPM_CREATE_CLASS)");
  • 108. DP M AP I S libdpm DPM APIs Interface 90 libdpm DPM APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INT DPM_CREATE_POLICY (CHAR *POLICYNAME, CHAR *OPSCLASSES) DE SC R IPT ION Create a policy. The opsclasses parameter is recommended to be NULL, but may also specify a list of operating point or class names in board-specific order according to the numeric order of operating states for the board. This parameter is deprecated; it is recommended to use dpm_set_policy_state_map() to set each operating point or class for the policy instead. EXA MP L E if (dpm_create_policy("Static", NULL) < 0) perror("sys_dpm(DPM_CREATE_POLICY)"); INT DPM_SET_POLICY_STATE_MAP (CHAR *POLICYNAME, CHAR *STATENAME, CHAR *OPCLASS) DE SC R IPT ION Map an operating state to an operating point or class in a policy. opclass is the operating point or class name to map the named operating state to under the named policy. EXA MP L E if (dpm_set_policy_state_map("Static" , "Idle", "600M") < 0) perror("dpm_set_policy_state_map)"); INT DPM_GET_POLICY_STATE_MAP(CHAR *POLICYNAME, CHAR *STATENAME, CHAR *BUF, SIZE_T BUFSIZ) DE SC R IPT ION Read the operating point or class mapped by an operating state in a policy into buf. EXA MP L E if(dpm_get_policy_state_map("Static", "Idle" , buf, sizeof(buf)) < 0) perror("dpm_get_active_policy)");
  • 109. ..... D PM A PI S libdpm DPM APIs Interface libdpm DPM APIs Interface 91 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INT DPM_SET_ACTIVE_POLICY (CHAR *POLICYNAME) DE SC R IPT ION Activate the named policy. The system will run under that DPM policy. EXA MP L E if (dpm_set_active_policy(dflt_pdomains[num].name) < 0){ perror("dpm_set_active_policy)"); return 0; }else { printf("nnSet policy to %sn", dflt_pdomains[num].name); } INT DPM_GET_ACTIVE_POLICY (CHAR *BUF, SIZE_T BUFSIZ) DE SC R IPT ION Return the currently active policy name into buf. EXA MP L E #include <stdlib.h> #include <stdio.h> #include <dpmlib.h> int main (void) { char buf[256]; if (dpm_get_active_policy(buf, sizeof(buf)) < 0) { perror("policy manager"); return 0; } printf("Active Policy: %sn", buf); return 1; }
  • 110. DP M AP I S sys-dpm APIs Interface 92 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . S Y S -D P M A P I S I N T E R F A C E The Power Manager interface manages the installation and activation of power policies. This interface is supported by a single function (sys_dpm) that provides several policy management functions. It is also supported through the /proc interface. Supported functions are described in the following sections. SYS_DPM NA ME sys_dpm—Manages the policy manager. Gives access to the DPM functions described in the following sections. SYN OP SIS # include <linux/dpm.h> long sys_dpm (int func, struct dpm_param *params); DE SC R IPT ION The sys_dpm function is used from a user-space policy manager to control DPM by specifying power policies to be used by DPM. PA R AM ETE R S The func parameter selects which function to perform. The params parameter points to a control block containing information needed by the selected function. The use of the parameter block is described for each individual function in the sections that follow. /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; };
  • 111. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 93 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . struct dpm_stats{ dpm_md_count_t count; dpm_md_time_t total_time; dpm_md_time_t start_time; dpm_md_time_t end_time; }; R ETU R N CO DE S Each sys_dpm function returns 0 (zero) on success and -1 on failure. An error code, errno is provided on failure. Most error codes are common to several functions listed within this chapter. Duplicate error codes are described here and other functions reference this section. Note: Note: Only error codes that are unique to that function are explained in the following sections. The following list contains the common DPM error codes: EBADRQC—An unknown function code was passed to sys_dpm in the func parameter. EINVAL—The name of a policy, class, or operating point contains a blank or other white- space character. Some of the individual functions also use EINVAL for additional error conditions. EEXIST—A request to create a named policy, class, or operating point is made and a like- named entity of the same type already exists. ENOENT—A request attempted to identify an existing policy, class, or operating point by name, but an entity of that type and name could not be found. ENOMEM—The kernel could not allocate enough memory to perform the requested function. EFAUL—The kernel could not access the parameter block pointed to by params or memory indirectly addressed by following pointers starting in the parameter block. EACCE—The caller is not the root user. TH E / PR OC IN TER F A C E The individual functions can also be accessed by reading and writing files in /proc/driver/dpm as explained in the sections that follow.
  • 112. DP M AP I S sys-dpm APIs Interface 94 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_INIT NA ME DPM_INT—Initializes Dynamic Power Management. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_INIT, dpm_param_t *params); DE SC R IPT ION Initializes DPM. A call to DPM_INIT must precede all other DPM_* calls. If DPM_TERMINATE is called then a call to DPM_INIT must precede all other DPM_* calls. DPM_INIT does not block. PA R AM ETE R S Use the DPM_INIT function code with sys_dpm to perform this function. The params parameter is ignored and must be set to NULL. R ETU R N CO DE S DPM_INIT returns 0 (zero) on success and -1 on failure. The following error codes are used: EALREADY—DPM is already initialized. EFAULT—The params value is set to a value other than NULL, and the kernel could not access the parameter block pointed to by params. DI SC US SIO N DPM_INIT does not activate DPM. To activate DPM, use DPM_SET_POLICY. TH E / PR OC IN TER F A C E Write init to /proc/drivers/dpm/cmd to perform this function.
  • 113. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 95 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXA MP L E U SE The following example program initializes DPM. # include <stdio.h> # include <linux/dpm.h> int main (int argc, char** argv) { /* initialize DPM */ if (sys_dpm(DPM_INIT,0)) { perror("policy manager"); printf("DPM_INIT failedn"); return 1; } } The following example shell script uses /proc/driver/dpm to perform this function: # !/bin/bash # # Initialize DPM. echo init > /proc/driver/dpm/cmd || echo Failed to initialize DPM
  • 114. DP M AP I S sys-dpm APIs Interface 96 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_TERMINATE NA ME DPM_TERMINATE—Terminates DPM and uninstalls all policies, classes, and operating points. SYN OP SIS # include <linux/dpm.h> int sys_dpm (DPM_TERMINATE, struct dpm_param *params); DE SC R IPT ION Terminates DPM control of the system and uninstalls all policies, classes, and operating points. The system continues to run at the operating point in effect at the time DPM_TERMINATE completes. Most other DPM_* functions will fail once DPM has been terminated. To resume DPM control of the system and allow other DPM_* functions to operate, you must perform the following: 1 The DPM_INIT function must be called. 2 New policies, classes, and operating points must be created using the DPM_CREATE_* functions. 3 The DPM_SET_POLICY function must be called to specify the active policy. DPM_TERMINATE may block. PA R AM ETE R S Use the DPM_TERMINATE function code with sys_dpm to perform this function. The params parameter is ignored and must be set to NULL. R ETU R N CO DE S DPM_TERMINATE returns 0 (zero) on success and -1 on failure. The following error codes are used:
  • 115. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 97 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EFAULT—parms is set to a value other than NULL and the kernel could not access the parameter block pointed to by params. DI SC US SIO N If you want to force a specific operating point, create and activate a simple policy where all classes map to the desired operating point. Then use DPM_TERMINATE. The operating point will remain in effect until the DPM is re-initialized (using DPM_INIT) and re- activated (using DPM_SET_POLICY) unless changed by something outside the DPM control. See also “DPM_DISABLE” on page 98. TH E / PR OC IN TER F A C E Write terminate to /proc/driver/dpm/cmd to perform this function. EXA MP L E U SE The following example program terminates the DPM. # include <stdio.h> # include <linux/dpm.h> int main (int argc, char** argv) { /* initialize the DPM */ if (sys_dpm(DPM_TERMINATE,0)){ perror ("policy_manager”); printf("DPM_TERMINATE failedn”); return 1; } return 0; } The following example shell script uses /proc/driver/dpm/cmd to perform this function. # !/bin/bash # # Terminate the Dynamic Power Manager. echo terminate > /proc/driver/dpm/cmd
  • 116. DP M AP I S sys-dpm APIs Interface 98 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_DISABLE NA ME DPM_DISABLE—Temporarily disables DPM. SYN OP SIS # include <linux/dpm.h> int sys_dpm (DPM_DISABLE, struct dpm_param *params); DE SC R IPT ION Temporarily disables DPM control of the system. The system continues to run at the operating point in effect at the time DPM_DISABLE completes. The active policy is remembered and re-activated when DPM_ENABLE is called. DESTROY_POLICY is prevented from destroying the active policy even while the DPM is disabled. To re-enable DPM control of the system with the currently installed polices, classes, and operating points, call DPM_ENABLE. Use DPM_TERMINATE and DPM_INIT to start over with new policies, classes, and operating points. DPM_DISABLE does not block. PA R AM ETE R S Use the DPM_DISABLE function code with sys_dpm to perform this function. The params field is unused and must be set to NULL. R ETU R N CO DE S DPM_DISABLE returns 0 (zero) on success and -1 on failure. EFAULT—parms is set to a value other than NULL, and the kernel could not access the parameter block pointed to by params.
  • 117. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 99 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DI SC US SIO N If you want to force a specific operating point, you must create and activate a simple policy where all classes map to the desired operating point. Then use DPM_DISABLE. The operating point will remain in effect until the next DPM_ENABLE unless changed by something outside the DPM control. TH E / PR OC IN TER F A C E Write disable to /proc/driver/dpm/cmd to perform this function. EXA MP L E U SE The following example program disables DPM. # include <stdio.h> # include <linux/dpm.h> int main (int argc, char** argv) { sys_dpm (DPM_DISABLE, 0); return 0; } The following example shell script uses /proc/driver/dpm/cmd to perform this function. # !/bin/bash # # Temporarily disable the Dynamic Power Manager. echo disable > /proc/driver/dpm/cmd
  • 118. DP M AP I S sys-dpm APIs Interface 100 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_ENABLE NA ME DPM_ENABLE—Re-enables DPM after DPM_DISABLE is used. SYN OP SIS # include <linux/dpm.h> int sys_dpm (DPM_ENABLE, struct dpm_param *params); DE SC R IPT ION Re-enable DPM after a DPM_DISABLE. The policy that was active at the time of the DPM_DISABLE is re-activated. DPM_ENABLE may block. PA R AM ETE R S Use the DPM_ENABLE function code with sys_dpm to perform this function. The params field is unused and must be set to NULL. R ETU R N CO DE S If DPM was not disabled or if there is no active policy selected, DPM_ENABLE ignores the situation, does nothing, and returns zero. DPM_DISABLE returns 0 (zero) on success and -1 on failure. EFAULT—Params is set to a value other than NULL, and the kernel could not access the parameter block pointed to by params. EXA MP L E U SE The following example program enables DPM. # include <stdio.h> # include <linux/dpm.h> int main (int argc, char** argv) { sys_dpm (DPM_ENABLE) return 0; }
  • 119. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 101 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The following example shell script uses /proc/driver/dpm/cmd to perform this function. # !/bin/bash # # Re-enable the Dynamic Power Manager. echo enable > /proc/driver/dpm/cmd
  • 120. DP M AP I S sys-dpm APIs Interface 102 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_CREATE_OPT NA ME DPM_CREATE_OPT—Creates and installs an operating point. SYN OP SIS # include <linux/dpm.h> int sys_dpm (DPM_CREATE_OPT, struct dpm_param *params); DE SC R IPT ION Creates a named operating point from an array of power parameters and installs it in DPM. The operating point name must be unique. DPM_CREATE_OPT may block. PA R AM ETE R S Use the DPM_CREATE_OPT function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; };
  • 121. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 103 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The following parameter fields are used: name—Names the operating point. The name must not contain any blanks or other whitespace characters. pp—Points to an array of machine-dependent, machine-defined parameters. The number of required parameters is given by DPM_PP_NBR. It is (or was anyway) in the machine- specific portion on operating points that describe the power parameters, will check whether that info still appears. The other params fields are not used. R ETU R N CO DE S DPM_CREATE_OPT returns 0 (zero) on success and -1 on failure. The following error codes are defined: EINVAL—The specified power parameters were invalid or inconsistent for the system, and the operating point could not be initialized by the machine-dependent code. others—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E Write create_opt <op_name> <param_1> ... <param_n> to /proc/driver/dpm/cmd to create an operating point. EXA MP L E U SE For examples, see Chapter 6, “MontaVista Power Manager Out-of-the-Box.”
  • 122. DP M AP I S sys-dpm APIs Interface 104 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_CREATE_CLASS NA ME DPM_CREATE_CLASS—Creates and installs a class of named operating points. SYN OP SIS # include <linux/dpm.h> int sys_dpm (DPM_CREATE_CLASS, struct dpm_param *params); DE SC R IPT ION Creates a class of named operating points and installs it into DPM. DPM_CREATE_CLASS may block. PA R AM ETE R S Use the DPM_CREATE_CLASS function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameter fields are used: name—Names the class. The name must not contain any blanks or other white space characters. m_names—Points to an array of operating point names. There must be at least one operating point name specified. The names must not contain any blanks or other white space characters.
  • 123. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 105 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The current DPM implementation supports one operating point per class. m_count—Provides the number of elements in the array pointed to by m_names. Note: The other params fields are not used. R ETU R N CO DE S DPM_CREATE_CLASS returns 0 (zero) on success and -1 on failure. The following error codes are defined: EINVAL—No operating point name was specified. At least one is required. others—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E Write create_class <class_name> <op_name_1> ... <op_name_n> to /proc/driver/dpm/cmd to create a class. There must be at least one operating point named. EXA MP L E U SE For examples, Chapter 6, “MontaVista Power Manager Out-of-the-Box.”
  • 124. DP M AP I S sys-dpm APIs Interface 106 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_CREATE_POLICY NA ME DPM_CREATE_POLICY—Creates and installs a policy. SYN OP SIS # include <linux/dpm.h> int sys_dpm (DPM_CREATE_POLICY, struct dpm_param *params); DE SC R IPT ION Creates a named policy from a set of named operating points or classes and installs it into DPM. The operating points or classes are mapped one-to-one with the operating states, so there must be as many operating points or class names given as there are operating states. A policy must not already be installed with the same name. DPM_CREATE_POLICY may block. PA R AM ETE R S Use the DPM_CREATE_POLICY function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameters are used as follows: name—Names the policy. The name must not contain any blanks or other white space characters.
  • 125. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 107 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . m_names—Points to an array of operating point or class names. There must be names supplied. This number is given by the value DPM_STATES from the header file linux/dpm.h. The names must not contain any blanks or other white space characters, and are specified in the order defined previously. Note: The other params fields are not used. RE TU R N C O D ES DPM_CREATE_POLICY returns 0 (zero) on success and -1 on failure. See “sys_dpm” on page 92. DIS C US SION To replace an existing policy, first use DPM_DESTROY_POLICY to remove it, and then use DPM_CREATE_POLICY to install the new version. DPM_TERMINATE can also be used to remove all installed polices, classes, and operating points, allowing replacements to be installed. DPM_CREATE_POLICY does not activate the policy. It only makes it available to other DPM_* functions. Those functions must choose a policy that has been created by this function. In particular, DPM_SET_POLICY is used to activate DPM, naming a particular policy to be in effect. DPM_CREATE_POLICY can be used at system boot time to initialize DPM with all the policies needed by the system. It can also be used at any time on a running system to add additional power polices. This allows for run-time upgrades. TH E /P RO C INT ER F A CE Write create_policy <policy_name> <name_1> ... <name_n> to /proc/driver/dpm/cmd to create a policy. DPM_STATES classes must be named. EXA MP L E U SE For examples, see Chapter 6, “MontaVista Power Manager Out-of-the-Box.”
  • 126. DP M AP I S sys-dpm APIs Interface 108 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_DESTROY_POLICY N AM E DPM_DESTROY_POLICY—Removes a policy from DPM. SY NOP SIS #include <linux/dpm.h> int sys_dpm (DPM_DESTROY_POLICY, struct dpm_param *params); D ESC R IP TION Removes a policy from the DPM. The policy must not be the currently active policy. DPM_DESTROY_POLICY may block. PA R AM ET ER S Use the DPM_DESTROY_POLICY function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameters are used as follows: name—Names the policy to be removed. Note: The other params fields are not used.
  • 127. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 109 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R ETU R N CO DE S DPM_DESTROY_POLICY returns 0 (zero) on success and -1 on failure. The following error codes are defined: EBUSY—The named policy is the currently active policy. others—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to destroy a single policy. The terminate command will destroy all policies. For more information, see “DPM_TERMINATE” on page 96. EXA MP L E U SE The following example program destroys a policy: #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main (int argc, char** argv) { struct dpm_param params; params.name="example"; if (sys_dpm (DPM_DESTROY_POLICY, &params)){ perror("policy manager"); printf("failed to destroy policyn"); return 1; } printf("policy destroyed OKn"); return 0; }
  • 128. DP M AP I S sys-dpm APIs Interface 110 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_SET_POLICY NA ME DPM_SET_POLICY—Activates a policy to use to power-manage the system. SYN OP SIS # include <linux/dpm.h> int sys_dpm (DPM_SET_POLICY, struct dpm_param *params); DE SC R IPT ION Changes the active policy to a named policy. Activates DPM if not already activated. DPM must have already been initialized using DPM_INIT and the named policy installed using DPM_INSTALL_POLICY. DPM_SET_POLICY may block. PA R AM ETE R S Use the DPM_SET_POLICY function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameter fields are used: name—identifies the policy that DPM should use to power-manage the system. The name must not contain any blanks or other white space characters. Note: The other params fields are not used.
  • 129. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 111 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TH E / PR OC IN TER F A C E Write set_policy <policy_name> to /proc/driver/dpm/cmd to activate a policy. R ETU R N CO DE S DPM_SET_POLICY returns 0 (zero) on success and -1 on failure. The following error codes are defined: EPERM—The policy cannot be activated because it conflicts with the current device constraints. others—See “sys_dpm” on page 92. EXA MP L E U SE The following example program sets a policy: #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main (int argc, char** argv) { struct dpm_param params; params.name="example"; if (sys_dpm(DPM_SET_POLICY, &params)){ perror("policy manager"); printf("DPM_SET_POLICY failedn"); return 1; } printf("policy set OKn"); return 0; } The following example shell script uses /proc/driver/dpm to perform this function. # !/bin/bash # # activate a policy echo set_policy $1 > /proc/driver/dpm/policy || echo Failed to activate policy.
  • 130. DP M AP I S sys-dpm APIs Interface 112 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_POLICY NA ME DPM_GET_POLICY—Returns the name of the system’s currently active policy. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_GET_POLICY, struct dpm_param *params); DE SC R IPT ION Returns the name of the system’s currently active policy. DPM_GET_POLICY may block. PA R AM ETE R S Use the DPM_GET_POLICY function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameter field is used: name—Specifies the location to which the policy name is to be copied. A buffer of size DPM_NAME_SIZE must be provided to receive the name. Note: The other params fields are not used.
  • 131. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 113 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R ETU R N CO DE S DPM_GET_POLICY returns 0 (zero) on success and -1 on failure. The following error codes are defined: ENOENT—There is no active policy. others—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E Read from /proc/driver/dpm/state to get the name of the currently active policy. If DPM is enabled, the following items are reported on a single line: • Name of the current policy. • Current state index. • Current state name. • Current class name. • Current implied operating point name. • Current actual operating point name. • Statistics timer frequency. If DPM is disabled, the following output is displayed: N/A -1 N/A N/A N/A N/A frequency
  • 132. DP M AP I S sys-dpm APIs Interface 114 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXA MP L E U SE The following example program gets the name of the active policy. #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main(int argc, char** argv) { char policy_name[DPM_NAME_SIZE]={0}; struct dpm_param params; params.name=policy_name; if (sys_dpm (DPM_GET_POLICY, &params)){ perror("policy manager"); printf("failed to get active policy namen"); return 1; } printf("the active policy is %sn",policy_name); return 0; } The following example shell script uses /proc/driver/dpm to perform this function: # !/bin/bash # # get the active policy’s name cat /proc/driver/dpm/state| cut -d “ “-f1
  • 133. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 115 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_ALL_POLICIES NA ME DPM_GET_ALL_POLICIES—Returns the names of all installed policies. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_GET_ALL_POLICIES, struct dpm_param *params); DE SC R IPT ION Returns the names of the system’s currently installed policies. DPM_GET_ALL_POLICIES may block. PA R AM ETE R S Use the DPM_GET_ALL_POLICIES function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameter field is used: m_names—An array of pointers to the buffers. This array must contain at least as many elements as the number of policies currently installed. The size of each buffer must be
  • 134. DP M AP I S sys-dpm APIs Interface 116 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_NAME_SIZE. The names of the currently installed policies will be returned in the buffers. Note: The other params fields are not used. R ETU R N CO DE S DPM_GET_ALL_POLICIES returns 0 (zero) on success and -1 on failure. The following error codes are defined: others—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to report all policies. EXA MP L E For examples, see Chapter 6, “MontaVista Power Manager Out-of-the-Box.”
  • 135. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 117 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_CLASSES NA ME DPM_GET_CLASSES—Returns the names of a policy’s classes. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_GET_CLASSES, struct dpm_param *params); DE SC R IPT ION Returns the class name assigned to each state for the given policy. DPM_GET_CLASSES may block. PA R AM ETE R S Use the DPM_GET_CLASSES function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameter fields are used: name—A pointer to a buffer containing the name of the policy.
  • 136. DP M AP I S sys-dpm APIs Interface 118 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . m_names—An array of pointers to the buffers. This array must contain DPM_STATES elements. The size of each buffer must be DPM_NAME_SIZE. The names of the classes will be returned in the buffers. The order of the class names is the same as the m_names field for DPM_CREATE_POLICY. Note: The other params fields are not used. R ETU R N CO DE S DPM_GET_CLASSES returns 0 (zero) on success and -1 on failure. The following error codes are defined: EEXIST—The policy does not exist. other—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to report classes for a policy.
  • 137. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 119 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_SET_TASK_STATE NA ME DPM_SET_TASK_STATE—Changes the DPM state of a process. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_SET_TASK_STATE, struct dpm_param *params); DE SC R IPT ION Changes the DPM state for a particular process. Note: This change of the state might cause an immediate change to the current operating point. DPM_SET_TASK_STATE may block. PA R AM ETE R S Use the DPM_SET_TASK_STATE function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following params fields are used: pid—Process id (PID) of the task for which a task state is to be set. A PID of 0 (zero) indicates that the invoking process is to have its task state set.
  • 138. DP M AP I S sys-dpm APIs Interface 120 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . task_state—Identifies the task state to be set. It must be an integer in the range - DPM_TASK_LIMIT to +DPM_TASK_LIMIT. Currently this is -4 to +4. The process’ DPM state will be set to DPM_TASK_STATE + task_state. Note: The other params fields are not used. R ETU R N CO DE S DPM_SET_TASK_STATE returns 0 (zero) on success and -1 on failure. The following error codes are defined: ENOENT—No process with the specified PID was found. others—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E Write set_task_state <pid> <task_state> to /proc/driver/dpm/cmd to perform this function. EXA MP L E U SE The following example program sets a task state: #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main(int argc, char** argv) { struct dpm_param params; params.pid=0; /* set this process’ task state */ params.task_state = DPM_TASK_STATE-3; if (sys_dpm (DPM_SET_TASK_STATE, &params)){ perror("policy manager"); printf("DPM_SET_TASK_STATE failedn"); return 1; } printf("task state set OKn"); return 0; }
  • 139. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 121 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The following example shell script uses /proc/driver/dpm/cmd to perform this function. #!/bin/bash # # set a task state if [ $1 != 0 ] ; then echo set_task_state $1 3 > /proc/driver/dpm/cmd || echo Failed to set task state fi
  • 140. DP M AP I S sys-dpm APIs Interface 122 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_TASK_STATE NA ME DPM_GET_TASK_STATE—Queries the task state of a particular process. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_GET_TASK_STATE, struct dpm_param *params); DE SC R IPT ION Queries the task state of a process. DPM_GET_TASK_STATE may block. PA R AM ETE R S Use the DPM_GET_TASK_STATE function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; };
  • 141. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 123 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The following parameter fields are used: pid—Process ID (PID) of the task for which a task state is queried. A PID of 0 (zero) indicates that the invoking process is to have its task state queried. task_state—The state for the process is returned in this field. The value returned has the same definition as the value of the task_state in DPM_SET_TASK_STATE. Note: The other parameter fields are not used. R ETU R N CO DE S DPM_GET_TASK_STATE returns 0 (zero) on success and -1 on failure. The following are defined: ENOENT—No process with the specified PID was found. others—See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to read the task state of a process. EXA MP L E U SE The following example program sets a policy: #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main(int argc, char** argv) { struct dpm_param params; params.pid=0; /* get this process’ task state */ if (sys_dpm (DPM_GET_TASK_STATE, &params)){ perror("policy manager"); printf("DPM_GET_TASK_STATE failedn"); return 1; } printf ("This process’ task state is %dn",params.task); return 0; }
  • 142. DP M AP I S sys-dpm APIs Interface 124 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_POLICY_STATS NA ME DPM_GET_POLICY_STATS—Returns statistics about the use of a policy. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_GET_POLICY_STATS, struct dpm_param *params); DE SC R IPT ION Returns statistics about the use of a policy. DPM_GET_POLICY_STATS may block. PA R AM ETE R S Use the DPM_GET_POLICY_STATS function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following params fields are used: name—The name of the policy for which statistics are being requested. stats—The statistics are returned in the structure pointed to by stats. Note: The other params fields are not used.
  • 143. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 125 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R ETU R N CO DE S DPM_GET_POLICY_STATS returns 0 (zero) on success and -1 on failure. See “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to get statistics for a policy. EXA MP L E U SE The following example program gets statistics for a policy. #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main(int argc, char** argv) { struct dpm_param params; params.name="Example_policy"; params.stats=(char*)malloc(sizeof (struct dpm_stats)); if (sys_dpm(DPM_GET_POLICY_STATS, &params)){ perror("policy manager"); printf("failed to get policy statsn"); return 1; } printf(Statistics for %sn",params.name); printf("activated %lld timesn",params.stats->count); printf("active %lld microsecsn",params.stats->total_time); printf("last activated at %lldn",params.stats->start_time); printf("last de-activated at %lldn",params.stats->end_time); return 0; }
  • 144. DP M AP I S sys-dpm APIs Interface 126 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_CLASS_STATS NA ME DPM_GET_CLASS_STATS—Returns statistics about the use of a class. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_GET_CLASS_STATS, struct dpm_param *params); DE SC R IPT ION Returns statistics about the use of a class. DPM_GET_CLASS_STATS may block. PA R AM ETE R S Use the DPM_GET_CLASS_STATS function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following parameter fields are used: name—The name of the class for which statistics are being requested. stats—The statistics are returned in the structure pointed to by stats. Note: The other params fields are not used.
  • 145. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 127 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R ETU R N CO DE S DPM_GET_CLASS_STATS returns 0 (zero) on success and -1 on failure. For information on error codes, see “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to get statistics for a class. EXA MP L E U SE The following example program gets statistics for a class. #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main(int argc, char** argv) { struct dpm_param params; params.name="Example_class"; params.stats=(char*)malloc(sizeof (struct dpm_stats)); if (sys_dpm(DPM_GET_CLASS_STATS, &params)){ perror("policy manager"); printf("failed to get class statsn"); return 1; } printf(Statistics for %sn",params.name); printf("activated %lld timesn",params.stats->count); printf("active %lld microsecsn",params.stats->total_time); printf("last activated at %lldn",params.stats->start_time); printf("last de-activated at %lldn",params.stats->end_time); return 0; }
  • 146. DP M AP I S sys-dpm APIs Interface 128 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_OPT_ STATS NA ME DPM_GET_OPT_STATS—Returns statistics about the use of an operating point. SYN OP SIS #include <linux/dpm.h> int sys_dpm (DPM_GET_OPT_STATS, struct dpm_param *params); DE SC R IPT ION Returns statistics about the use of an operating point. DPM_GET_OPT_STATS may block. PA R AM ETE R S Use the DPM_GET_OPT_STATS function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following params fields are used: name—The name of the operating point for which statistics are being requested. stats—The statistics are returned in the structure pointed to by stats. Note: The other params fields are not used.
  • 147. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 129 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R ETU R N CO DE S DPM_GET_OPT_STATS returns 0 (zero) on success and -1 on failure. For information on error codes, see “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to get statistics for an operating point. EXA MP L E U SE The following example program gets statistics for a operating point. #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main(int argc, char** argv) { struct dpm_param params; params.name="Example_opt"; params.stats=(char*)malloc(sizeof(struct dpm_stats)) if (sys_dpm(DPM_GET_OPT_STATS, &params)){ perror("policy manager"); printf("failed to get opt statsn"); return 1; } printf(Statistics for %sn",params.name); printf("activated %lld timesn",params.stats->count); printf("active %lld microsecsn",params.stats->total_time); printf("last activated at %lldn",params.stats->start_time); printf("last de-activated at %lldn",params.stats->end_time); return 0; }
  • 148. DP M AP I S sys-dpm APIs Interface 130 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DPM_GET_OS_STATS NA ME DPM_GET_OS_STATS—Returns statistics about the use of all operating states. SYN OP SIS #include <linux/dpm.h> int sys_dpm(DPM_GET_OS_STATS, struct dpm_param *params); DE SC R IPT ION Returns statistics about the use of all operating states. DPM_GET_OS_STATS may block. PA R AM ETE R S Use the DPM_GET_OS_STATS function code with sys_dpm to perform this function. The fields in the parameter block given by the params pointer are used as follows: /* parameter block for sys_dpm function interface */ typedef struct dpm_param { char *name; char **m_names; unsigned m_count; dpm_md_pp_t *pp; pid_t pid; dpm_state_t task_state; struct dpm_stats *stats; }; The following params fields are used: op_state—The operating state for which statistics are being queried. stats—The statistics are returned in the array of structures pointed to by stats. Each element of the array describes an operating state. Note: The other params fields are not used.
  • 149. ..... D PM A PI S sys-dpm APIs Interface sys-dpm APIs Interface 131 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R ETU R N CO DE S DPM_GET_OS_STATS returns 0 (zero) on success and -1 on failure. For information on error codes, see “sys_dpm” on page 92. TH E / PR OC IN TER F A C E There is no /proc interface to get statistics for all operating states. EXA MP L E U SE The following example program gets statistics for an operating state. #include <stdio.h> #include <linux/unistd.h> #include <linux/dpm.h> int main(int argc, char** argv) { struct dpm_param params; params.op_state=DPM_APPL; params.stats=(char*)malloc(DPM_STATES* sizeof (struct dpm_stats)); if (sys_dpm (DPM_GET_OS_STATS, &params)){ perror("policy manager"); printf("failed to get os statsn"); return 1; } printf (Statistics for %dn",params.op_state); printf ("activated %lld timesn",params.stats->count); printf ("active %lld microsecsn",params.stats->total_time); printf ("last activated at %lldn",params.stats->start_time); printf ("last de-activated at %lldn",params.stats->end_time); return 0;
  • 150. DP M AP I S sys-dpm APIs Interface 132 sys-dpm APIs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  • 151. ..... 133 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INDEX A APIs 87 libdpm DPM interface 88 sys-dpm DPM interface 92 Applications DPM startup 72 B Bash shell using 20 C Clock events tracking Definition of 12 Command-line Power Manager tool 18 Commands Accessibility 76 Operating classes 76 Operating points 76 Power policy 76 Power state 77 Syntax for 76 Configuration files Default 36 Installing 35 D Default configuration files Intel PXA27x 37 Power Manager 36 TI-OMAP1710 36 Device constraints Asserting 54 Configuration of 42 Definition of 28 Features of 29 Interfaces for 53 Runtime 67 Specifying 51 Specifying by syfs 53 Device drivers background of 28 interface of 27 Mobilinux DPM 27 Device interactions Design considerations 50 Design with DPM 49 Device constraints design of 51 DPM to userspace design of 55 Driver interfaces 54 Device suspend/resume Definition of 31 Implementation of 68 Power values 44 DPM Hotplug agents for 12 Mobilinux 9 dpmlib Operating classes 63 Operating points 62 Starting applications 72 dpmmgr Configuration file for 35 Syntax for 34 dpmmgr.conf Operating classes 63 Operating points 62 Power policies 65 Driver interfaces to DPM Creating 54 Example for 54 Driver scale callbacks Definition of 30 Design of 45 Dynamic power management Benefits of 10 Clock event tracking 12 Definition of 10 Features of 11 Library of 12 Mobile devices 6 E Embedded Linux Definition of 4 Embedded systems Embedded Linux 4 Power management for 4 Event handeling Definition of 13
  • 152. 134 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event handling suspend/resume 68 F Forced operating points Definition of 29 H Handling of events Implementation of 66 Hotplug agents Definition of 12 I Idle state Operating state type 24 INFOPATH 19 Intel PXA27x Configuration file for 37 DPM for 6 L libdpm DPM API interface 88 Operating policies 65 M MANPATH 18 setting 18 Mobile devices Conserving energy for 6 Dynamic Power Management 6 Mobilinux for 9 Power Management 1 Mobilinux Definition of 10 DPM for 9 Mobilinux DPM APIs 87 Building blocks of 19 Mobilinux DPM features Clock event tracking 12 DPM library 12 Event handling 13 Hotplug agents 12 MontaVista Power Manager 11 Power Manager interface 13 Power profiler plugin 12 Suspend/resume handling 13 Tick elimination 12 Mobilinux DPM library Definition of 12 MontaVista Power Manager Building blocks of 19 Definition of 16 Features of 16 Out-of-the-box 33 Tools for 18 MontaVista Power Manager features Deafult power policies 17 Integrated components 17 User-defined power parameters 17 MontaVista Zone 21 O Operating classes Constraints for 52 Definition of 21, 30 dpmlib 63 dpmmgr.conf 63 Examples of 21 Implementation of 63 sysfs 63 Operating points Constraints for 51 Definition of 20 dpmlib 62 dpmmgr.conf 62 Examples of 21 Forced 29 Parameters 20 sysfs 62 Operating policy Implementation of 66 Operating state types Idle 24 Sleep 23 Task 24 Operating states Architecure of 22 Definition of 22 Types of 23 P Plugin APIs Power Manager tools 18 Policies dpmmgr.conf 65 Idle state 64 Idle-task state 64 Implementation of 64 libdpm 65 sysfs 65 Power event userspace Hotplug agents for 52 Power events notification 61 Power hotplug Agents for 52 Power Management Architecture of 5 Background 1 Benefits of 2 Definition of 3 DPM policy 5 DPM Power Manager 5
  • 153. ..... 135 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Embedded systems 4 Power Manager Applications startup 72 Authomatic startup 72 Building blocks of 19 Default configuration files 36 Definition of 5 Development of 60 Exiting from 35 Installation of 35 Manual startup 72 Out-of-the-box 33 Power Manager 11 Running 72 Startup 71 Power Manager building blocks Design of 41 Driver scale callbacks 45 Hardware study 42 Implementation of 57, 61 Operating points guidelines 43 Power policy 46 Power-related events 46 Promrammable sleep/wakeup sources 47 Sleep/standby behavior 47 Software architecture 44 Suspend/resume device 44 Task states 47 Power Manager building blocks implementation Custom drivers 58 Device constraints 59 Device suspend/resume 68 Driver scale callbacks 59 Handling of events 66 Kernel power events notification 60 Logic for power policy 66 Operating classes 63 Power Manager 60 Power policies 64 Power state modifications 69 Runtime device constraints 67 Power Manager features DPM interface 16 Power Manager interface Definition of 13 Power Manager tools Command-line 18 Plugin APIs 18 Power Managr building blocks Operating classes 21 Operating points 20 Operating states 22 Power parameters 20 Power policy 25 Power policy Architecure of 25 Definition of 25 Designing 46 Plugable power 7 Using Power Manager 44 Power profiler plugin Definition of 12 Power state Modifications 69 Power-related events Design of 46 Profiler Definition of 12 Programmable sleep/wakeup sources Design of 47 R Resume devices levels of 45 Runtime device constraints Example of 67 Implementation of 67 S Sleep Operating state type 23 Sleep/standby behavior Design of 47 Suspend/resume devices Designing 44 Event handling 68 Handling 68 Levels of 45 Suspend/resume handling Definition of 13 sysfs Constraints specification 53 Operating classes 63 Operating points 62 Power policies 65 System suspend/resume Implementation of 68 T Task states Design of 47 Operating state type 24 Tick elimination Definition of 12 TI-OMAP1710 DPM for 6 U Using Power Manager Out-of-the box 33, 34