doc/html/ref/power-change.html

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