packages/services/power/common/v2_0/doc/power-change.html

   1 <!-- Copyright (C) 2001 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of substantively modified versions of this         -->
   7 <!-- document is prohibited without the explicit permission of the   -->
   8 <!-- copyright holder.                                               -->
   9 <!-- Distribution of the work or derivative of the work in any       -->
  10 <!-- standard (paper) book form is prohibited unless prior           -->
  11 <!-- permission is obtained from the copyright holder.               -->
  12 <HTML
  13 ><HEAD
  14 ><TITLE
  15 >Changing Power Modes</TITLE
  16 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  17 <META
  18 NAME="GENERATOR"
  19 CONTENT="Modular DocBook HTML Stylesheet Version 1.64
  20 "><LINK
  21 REL="HOME"
  22 TITLE="eCos Power Management Support"
  23 HREF="services-power.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Power Management Information"
  26 HREF="power-info.html"><LINK
  27 REL="NEXT"
  28 TITLE="Support for Policy Modules"
  29 HREF="power-policy.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 WIDTH="100%"
  41 BORDER="0"
  42 CELLPADDING="0"
  43 CELLSPACING="0"
  44 ><TR
  45 ><TH
  46 COLSPAN="3"
  47 ALIGN="center"
  48 >eCos Power Management Support</TH
  49 ></TR
  50 ><TR
  51 ><TD
  52 WIDTH="10%"
  53 ALIGN="left"
  54 VALIGN="bottom"
  55 ><A
  56 HREF="power-info.html"
  57 >Prev</A
  58 ></TD
  59 ><TD
  60 WIDTH="80%"
  61 ALIGN="center"
  62 VALIGN="bottom"
  63 ></TD
  64 ><TD
  65 WIDTH="10%"
  66 ALIGN="right"
  67 VALIGN="bottom"
  68 ><A
  69 HREF="power-policy.html"
  70 >Next</A
  71 ></TD
  72 ></TR
  73 ></TABLE
  74 ><HR
  75 ALIGN="LEFT"
  76 WIDTH="100%"></DIV
  77 ><H1
  78 ><A
  79 NAME="POWER-CHANGE"
  80 >Changing Power Modes</A
  81 ></H1
  82 ><DIV
  83 CLASS="REFNAMEDIV"
  84 ><A
  85 NAME="AEN171"
  86 ></A
  87 ><H2
  88 >Name</H2
  89 >Changing Power Modes&nbsp;--&nbsp;reducing or increasing power consumption as needed</DIV
  90 ><DIV
  91 CLASS="REFSYNOPSISDIV"
  92 ><A
  93 NAME="AEN174"
  94 ></A
  95 ><H2
  96 >Synopsis</H2
  97 ><DIV
  98 CLASS="FUNCSYNOPSIS"
  99 ><A
 100 NAME="AEN175"
 101 ></A
 102 ><P
 103 ></P
 104 ><TABLE
 105 BORDER="0"
 106 BGCOLOR="#E0E0E0"
 107 WIDTH="100%"
 108 ><TR
 109 ><TD
 110 ><PRE
 111 CLASS="FUNCSYNOPSISINFO"
 112 >#include &lt;cyg/power/power.h&gt;</PRE
 113 ></TD
 114 ></TR
 115 ></TABLE
 116 ><P
 117 ><CODE
 118 ><CODE
 119 CLASS="FUNCDEF"
 120 >    void power_set_mode
 121   </CODE
 122 >(    PowerMode new_mode
 123   );</CODE
 124 ></P
 125 ><P
 126 ><CODE
 127 ><CODE
 128 CLASS="FUNCDEF"
 129 >    void power_set_controller_mode
 130   </CODE
 131 >(    PowerController* controller
 132   ,     PowerMode new_mode
 133   );</CODE
 134 ></P
 135 ><P
 136 ><CODE
 137 ><CODE
 138 CLASS="FUNCDEF"
 139 >    void power_set_controller_mode_now
 140   </CODE
 141 >(    PowerController* controller
 142   ,     PowerMode new_mode
 143   );</CODE
 144 ></P
 145 ><P
 146 ></P
 147 ></DIV
 148 ></DIV
 149 ><DIV
 150 CLASS="REFSECT1"
 151 ><A
 152 NAME="POWER-CHANGE-GLOBAL"
 153 ></A
 154 ><H2
 155 >Changing the Global Power Mode</H2
 156 ><P
 157 >The primary functionality supported by the power management package is
 158 to change the system's global power mode. This is achieved by calling
 159 the function <TT
 160 CLASS="FUNCTION"
 161 >power_set_mode</TT
 162 > with a single
 163 argument, which should be one of <TT
 164 CLASS="LITERAL"
 165 >PowerMode_Active</TT
 166 >,
 167 <TT
 168 CLASS="LITERAL"
 169 >PowerMode_Idle</TT
 170 >, <TT
 171 CLASS="LITERAL"
 172 >PowerMode_Sleep</TT
 173 >
 174 or <TT
 175 CLASS="LITERAL"
 176 >PowerMode_Off</TT
 177 >. Typically this function will only
 178 be invoked in certain scenarios:</P
 179 ><P
 180 ></P
 181 ><OL
 182 TYPE="1"
 183 ><LI
 184 ><P
 185 >A typical system will contain a policy module which is primarily
 186 responsible for initiating power mode changes, and a thread inside the
 187 power management package. The policy module will call
 188 <TT
 189 CLASS="FUNCTION"
 190 >power_set_mode</TT
 191 >, which has the effect of
 192 manipulating some internal state in the power management package and
 193 waking up its thread. When this thread gets scheduled to run (its
 194 priority is controlled by a configuration option), it will iterate
 195 over the power controllers and invoke each controller to change its
 196 power mode. There is support for a <A
 197 HREF="power-policy.html#POWER-POLICY-CALLBACK"
 198 >callback function</A
 199 >, and for
 200 <A
 201 HREF="power-attached.html"
 202 >detached</A
 203 > power controllers.</P
 204 ></LI
 205 ><LI
 206 ><P
 207 >After a call to <TT
 208 CLASS="FUNCTION"
 209 >power_set_mode</TT
 210 > but before the
 211 power management thread has had a chance to iterate over all the
 212 controllers, or even before the thread has been rescheduled at all,
 213 the policy module may decide that a different power mode would be more
 214 appropriate for the current situation and calls
 215 <TT
 216 CLASS="FUNCTION"
 217 >power_set_mode</TT
 218 > again. This has the effect of
 219 aborting the previous mode change, followed by the power management
 220 thread iterating over the power controllers again for the new mode.</P
 221 ></LI
 222 ><LI
 223 ><P
 224 >If there is no single policy module responsible for power mode
 225 changes, any code can call <TT
 226 CLASS="FUNCTION"
 227 >power_set_mode</TT
 228 >. If
 229 there are multiple calls in quick succession, earlier calls will
 230 be aborted and the system should end up in the power mode
 231 corresponding to the last call</P
 232 ></LI
 233 ><LI
 234 ><P
 235 >As a special case, it is possible for a power controller to call
 236 <TT
 237 CLASS="FUNCTION"
 238 >power_set_mode</TT
 239 > when invoked by the power
 240 management thread. For example a power controller could decide that it
 241 is inappropriate for the system to go to sleep because the device it
 242 is associated with is still busy. The effect is as if the policy
 243 module had called <TT
 244 CLASS="FUNCTION"
 245 >power_set_mode</TT
 246 > again before
 247 the mode change had completed.</P
 248 ></LI
 249 ></OL
 250 ><P
 251 >If the power management package has been configured not to use a
 252 separate thread then obviously the behaviour is somewhat different.
 253 The call to <TT
 254 CLASS="FUNCTION"
 255 >power_set_mode</TT
 256 > will now iterate over
 257 the various power controllers immediately, rather than leaving this to
 258 a separate thread, and the whole mode change completes before
 259 <TT
 260 CLASS="FUNCTION"
 261 >power_set_mode</TT
 262 > returns. If some other thread or a
 263 DSR calls <TT
 264 CLASS="FUNCTION"
 265 >power_set_mode</TT
 266 > concurrently the
 267 behaviour of the system is undefined. However, it is still legal for a
 268 power controller to call <TT
 269 CLASS="FUNCTION"
 270 >power_set_mode</TT
 271 >:
 272 effectively this is a recursive call; it is detected by the system,
 273 and internal state is updated; the recursive
 274 <TT
 275 CLASS="FUNCTION"
 276 >power_set_mode</TT
 277 > call now returns, and when the
 278 power controller returns back to the original
 279 <TT
 280 CLASS="FUNCTION"
 281 >power_set_mode</TT
 282 > call it detects what has happened,
 283 aborts the previous mode change, and starts a new mode change as
 284 requested by the controller.</P
 285 ><P
 286 ><TT
 287 CLASS="FUNCTION"
 288 >power_set_mode</TT
 289 > is normally invoked from thread
 290 context. If a separate power management thread is used it can be
 291 invoked safely from DSR context. If the system is configured not to
 292 use such a thread, it may or may not be safe to invoke this function
 293 from DSR context: essentially the function just iterates through
 294 the various power controllers, and the documentation or source code of
 295 each controller present in the current system will have to be examined
 296 to determine whether or not this can happen safely in DSR context.
 297 <TT
 298 CLASS="FUNCTION"
 299 >power_set_mode</TT
 300 > should never be invoked from
 301 ISR context.</P
 302 ></DIV
 303 ><DIV
 304 CLASS="REFSECT1"
 305 ><A
 306 NAME="POWER-CHANGE-CONTROLLER"
 307 ></A
 308 ><H2
 309 >Manipulating an Individual Power Controller</H2
 310 ><P
 311 >In some cases it is desirable to set the power mode of an individual
 312 controller separately from the mode for the system as a whole. For
 313 example if a device is not currently being used then the associated
 314 power controller could be set to <TT
 315 CLASS="LITERAL"
 316 >PowerMode_Off</TT
 317 >,
 318 even while the system as a whole is still active. This can be achieved
 319 by calling the function
 320 <TT
 321 CLASS="FUNCTION"
 322 >power_set_controller_mode</TT
 323 >. It takes two
 324 arguments: the first identifies a particular controller; the second
 325 specifies the desired new power mode for that controller. The function
 326 operates in much the same way as <TT
 327 CLASS="FUNCTION"
 328 >power_set_mode</TT
 329 >,
 330 for example if a separate power management thread is being used then
 331 <TT
 332 CLASS="FUNCTION"
 333 >power_set_controller_mode</TT
 334 > operates by
 335 manipulating some internal state and waking up that thread. The
 336 limitations are also much the same as for
 337 <TT
 338 CLASS="FUNCTION"
 339 >power_set_mode</TT
 340 >, so for example
 341 <TT
 342 CLASS="FUNCTION"
 343 >power_set_controller_mode</TT
 344 > should not be invoked
 345 from inside ISRs.</P
 346 ><P
 347 >Manipulating individual controllers is often used in conjunction with
 348 the function <A
 349 HREF="power-attached.html"
 350 ><TT
 351 CLASS="FUNCTION"
 352 >power_set_controller_attached</TT
 353 ></A
 354 >,
 355 allowing the policy module to specify which controllers are affected
 356 by global mode changes.</P
 357 ></DIV
 358 ><DIV
 359 CLASS="REFSECT1"
 360 ><A
 361 NAME="POWER-CHANGE-CONTROLLER-NOW"
 362 ></A
 363 ><H2
 364 >Direct Manipulation of a Power Controller</H2
 365 ><P
 366 >In exceptional circumstances it may be necessary to invoke a power
 367 controller directly, bypassing the power management thread and
 368 higher-level functionality such as <A
 369 HREF="power-policy.html#POWER-POLICY-CALLBACK"
 370 >callback functions</A
 371 >. The
 372 function <TT
 373 CLASS="FUNCTION"
 374 >power_set_controller_mode_now</TT
 375 > allows
 376 this. It takes two arguments, a controller and a mode, just like
 377 <TT
 378 CLASS="FUNCTION"
 379 >power_set_controller_mode</TT
 380 >.</P
 381 ><P
 382 >Use of <TT
 383 CLASS="FUNCTION"
 384 >power_set_controller_mode_now</TT
 385 > is
 386 dangerous. For example no attempt is made to synchronise with any
 387 other power mode changes that might be happening concurrently. A
 388 possible use is when the system gets woken up out of
 389 <SPAN
 390 CLASS="TYPE"
 391 >sleep</SPAN
 392 > mode: depending on the hardware, on which power
 393 controllers are present, and on the application code it may be
 394 necessary to wake up some power controllers immediately before the
 395 system as a whole is ready to run again.</P
 396 ></DIV
 397 ><DIV
 398 CLASS="NAVFOOTER"
 399 ><HR
 400 ALIGN="LEFT"
 401 WIDTH="100%"><TABLE
 402 WIDTH="100%"
 403 BORDER="0"
 404 CELLPADDING="0"
 405 CELLSPACING="0"
 406 ><TR
 407 ><TD
 408 WIDTH="33%"
 409 ALIGN="left"
 410 VALIGN="top"
 411 ><A
 412 HREF="power-info.html"
 413 >Prev</A
 414 ></TD
 415 ><TD
 416 WIDTH="34%"
 417 ALIGN="center"
 418 VALIGN="top"
 419 ><A
 420 HREF="services-power.html"
 421 >Home</A
 422 ></TD
 423 ><TD
 424 WIDTH="33%"
 425 ALIGN="right"
 426 VALIGN="top"
 427 ><A
 428 HREF="power-policy.html"
 429 >Next</A
 430 ></TD
 431 ></TR
 432 ><TR
 433 ><TD
 434 WIDTH="33%"
 435 ALIGN="left"
 436 VALIGN="top"
 437 >Power Management Information</TD
 438 ><TD
 439 WIDTH="34%"
 440 ALIGN="center"
 441 VALIGN="top"
 442 >&nbsp;</TD
 443 ><TD
 444 WIDTH="33%"
 445 ALIGN="right"
 446 VALIGN="top"
 447 >Support for Policy Modules</TD
 448 ></TR
 449 ></TABLE
 450 ></DIV
 451 ></BODY
 452 ></HTML
 453 >