doc/html/ref/power-intro.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 >Introduction</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="eCos Power Management Support"
  26 HREF="services-power.html"><LINK
  27 REL="NEXT"
  28 TITLE="Power Management Information"
  29 HREF="power-info.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="services-power.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-info.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-INTRO">Introduction</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN15587"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >Introduction&nbsp;--&nbsp;eCos support for Power Management</DIV
  91 ><DIV
  92 CLASS="REFSECT1"
  93 ><A
  94 NAME="POWER-INTRO-INTRO"
  95 ></A
  96 ><H2
  97 >Introduction</H2
  98 ><P
  99 >The eCos Power Management package provides a framework for
 100 incorporating power management facilities in an embedded application.
 101 However its functionality is deliberately limited.</P
 102 ><P
 103 ></P
 104 ><OL
 105 TYPE="1"
 106 ><LI
 107 ><P
 108 >The package does not contain any support for controlling the current
 109 power mode of any given processor, device or board. Instead it is the
 110 responsibility of the appropriate HAL or device driver package to
 111 implement such support, by implementing <I
 112 CLASS="FIRSTTERM"
 113 >power
 114 controllers</I
 115 >. The power management package groups these
 116 power controllers together and provides an interface for manipulating
 117 them.</P
 118 ></LI
 119 ><LI
 120 ><P
 121 >The package does not contain any power management policy support.
 122 Specifically, including this package in an application does not by
 123 itself ever cause the system to go into low-power mode. Instead it is
 124 the responsibility of a separate policy module, provided by
 125 higher-level application code or by some other package, to decide when
 126 it would be appropriate to switch from one power mode to another. The
 127 power management package then provides the mechanisms for making it
 128 happen.</P
 129 ></LI
 130 ></OL
 131 ></DIV
 132 ><DIV
 133 CLASS="REFSECT1"
 134 ><A
 135 NAME="POWER-INTRO-INCLUDE"
 136 ></A
 137 ><H2
 138 >Including Power Management</H2
 139 ><P
 140 >The power management package is never included automatically in an
 141 eCos configuration: it is not part of any target specification or of
 142 any template. Instead it must be added explicitly to a configuration
 143 if the intended application requires power management functionality.
 144 When using the command-line <B
 145 CLASS="COMMAND"
 146 >ecosconfig</B
 147 > tool this
 148 can be achieved using a command such as:</P
 149 ><TABLE
 150 BORDER="5"
 151 BGCOLOR="#E0E0F0"
 152 WIDTH="70%"
 153 ><TR
 154 ><TD
 155 ><PRE
 156 CLASS="SCREEN"
 157 >$ ecosconfig add power</PRE
 158 ></TD
 159 ></TR
 160 ></TABLE
 161 ><P
 162 >The generic eCos user documentation should be consulted for more
 163 information on how to use the various tools. The functionality
 164 provided by the power management package is defined in the header file
 165 <TT
 166 CLASS="FILENAME"
 167 >cyg/power/power.h</TT
 168 >. This header
 169 file can be used by both C and C++ code.</P
 170 ></DIV
 171 ><DIV
 172 CLASS="REFSECT1"
 173 ><A
 174 NAME="POWER-INTRO-MODES"
 175 ></A
 176 ><H2
 177 >Power Modes</H2
 178 ><P
 179 >There are four defined modes of operation:</P
 180 ><P
 181 ></P
 182 ><DIV
 183 CLASS="VARIABLELIST"
 184 ><DL
 185 ><DT
 186 >active</DT
 187 ><DD
 188 ><P
 189 >The system is fully operational, and power consumption is expected to
 190 be high.</P
 191 ></DD
 192 ><DT
 193 >idle</DT
 194 ><DD
 195 ><P
 196 >There has been little or no activity for a short period of time. It is
 197 up to the policy module to determine what constitutes a short period
 198 of time, but typically it will be some tenths of a second or some
 199 small number of seconds. A possible action when entering idle mode is
 200 to reduce the system's clock speed, thus reducing the power drawn by
 201 the cpu.</P
 202 ><P
 203 >Note that typically this power mode is not entered automatically
 204 whenever the idle thread starts running. Instead it is entered when
 205 the policy module discovers that for a certain period of time the
 206 system has been spending most of its time in the idle thread.
 207 Theoretically it is possible to implement a policy module that would
 208 cause a switch to idle mode as soon as the idle thread starts running,
 209 but that could result in a great many power mode changes for no
 210 immediate benefit.</P
 211 ></DD
 212 ><DT
 213 >sleep</DT
 214 ><DD
 215 ><P
 216 >The system has been idle for a significant period of time, perhaps
 217 some tens of seconds. It is desirable to shut down any hardware that
 218 is drawing a significant amount of power, for example a screen
 219 backlight.</P
 220 ></DD
 221 ><DT
 222 >off</DT
 223 ><DD
 224 ><P
 225 >The system is powered down. Power consumption should be minimized.
 226 Some special action may be needed before the system comes back up, for
 227 example the user may need to press a specific button.</P
 228 ></DD
 229 ></DL
 230 ></DIV
 231 ><P
 232 >The exact transitions that will happen are decided by the policy
 233 module. One policy module might include transitions from active to
 234 idle, from idle to sleep, from sleep to off, and from any of idle,
 235 sleep or off directly back to active. Another policy module might
 236 only use the active and off states, bypassing the intermediate ones.</P
 237 ></DIV
 238 ><DIV
 239 CLASS="REFSECT1"
 240 ><A
 241 NAME="POWER-INTRO-CONTROLLERS"
 242 ></A
 243 ><H2
 244 >Power Controllers</H2
 245 ><P
 246 >The power management package operates primarily on power controllers.
 247 The main functionality provided by a power controller is to switch the
 248 power mode for some part of the system, for example the lcd display or
 249 the cpu. A power controller consists primarily of a function which
 250 will be invoked to switch the power mode for the part of the overall
 251 system being controlled, plus some auxiliary data. A typical system
 252 will include a number of different power controllers:</P
 253 ><P
 254 ></P
 255 ><OL
 256 TYPE="1"
 257 ><LI
 258 ><P
 259 >Usually there will be one power controller
 260 <TT
 261 CLASS="VARNAME"
 262 >power_controller_cpu</TT
 263 > associated with the processor
 264 or with the target platform, and provided by the corresponding HAL
 265 package. It is this controller which is responsible for switching off
 266 the system when entering the <SPAN
 267 CLASS="TYPE"
 268 >off</SPAN
 269 > mode, which makes it
 270 somewhat special: attempting to switch off the cpu before other
 271 devices like the lcd display does not make sense because the cpu would
 272 no longer be executing any instructions for the latter operation.
 273 Therefore this power controller has to be invoked last when switching
 274 to a lower-power mode, and similarly when switching back to a
 275 higher-power mode it will be invoked first.</P
 276 ><P
 277 >It should be noted that providing power management support is not a
 278 hard requirement when porting eCos to a new processor or platform, and
 279 many eCos ports predate the availability of power management support.
 280 Therefore for any given platform it is distinctly possible that
 281 <TT
 282 CLASS="VARNAME"
 283 >power_controller_cpu</TT
 284 > is not yet provided, and if
 285 full power management functionality is desired then the appropriate
 286 HAL package would have to be extended first. System developers should
 287 examine the relevant HAL documentation and sources to determine what
 288 is actually available.</P
 289 ></LI
 290 ><LI
 291 ><P
 292 >Some or all of the device drivers will supply their own power
 293 controllers, as part of the device driver package. It is not required
 294 that all device drivers provide power controllers. In some cases,
 295 especially for devices that are integrated with the processor,
 296 <TT
 297 CLASS="VARNAME"
 298 >power_controller_cpu</TT
 299 > will take care of the
 300 integrated devices as a side effect. In other cases the hardware may
 301 not provide any functionality that allows power consumption to be
 302 controlled. For any given device driver it is also possible that no
 303 power controller exists either because it was not required when the
 304 driver was written, or because the driver predates the availability of
 305 power management. Again the relevant documentation and sources should
 306 be consulted for further information.</P
 307 ></LI
 308 ><LI
 309 ><P
 310 >There may be power controllers which are not associated directly with
 311 any specific hardware. For example a TCP/IP stack could provide a
 312 power controller so that it gets informed when the system has been
 313 reactivated: by looking at the system clock it can determine for how
 314 long the system has been switched off; using this information it can
 315 then recover from expired dhcp leases, or even to shut down any stream
 316 connections that may have become invalid (although arguably the stack
 317 should have refused to go to <SPAN
 318 CLASS="TYPE"
 319 >off</SPAN
 320 > mode while there were
 321 open connections).</P
 322 ></LI
 323 ></OL
 324 ></DIV
 325 ><DIV
 326 CLASS="REFSECT1"
 327 ><A
 328 NAME="POWER-INTRO-OPERATION"
 329 ></A
 330 ><H2
 331 >Basic Operation</H2
 332 ><P
 333 >By default the Power Management package creates a thread during
 334 initialization. It is also possible for the package to be used without
 335 such a thread, for example in configurations which do not include a
 336 full kernel, and this alternative is described below. When a separate
 337 thread is used the stacksize and priority for this thread can be
 338 controlled by configuration options
 339 <TT
 340 CLASS="VARNAME"
 341 >CYGNUM_POWER_THREAD_STACKSIZE</TT
 342 > and
 343 <TT
 344 CLASS="VARNAME"
 345 >CYGNUM_POWER_THREAD_PRIORITY</TT
 346 >. Typically the thread
 347 will just wait on a semaphore internal to the package, and will do
 348 nothing until some other part of the system requests a change to the
 349 power mode.</P
 350 ><P
 351 >At some point the policy module will decide that the system should
 352 move into a lower-power mode, for example from active to idle. This is
 353 achieved by calling the function <TT
 354 CLASS="FUNCTION"
 355 >power_set_mode</TT
 356 >,
 357 provided by the power management package and declared in <TT
 358 CLASS="FILENAME"
 359 >cyg/power/power.h</TT
 360 >, with a single
 361 argument, <TT
 362 CLASS="LITERAL"
 363 >PowerMode_Idle</TT
 364 >. This function manipulates
 365 some internal state and posts the semaphore, thus waking up the power
 366 management thread. Note that the function returns before the mode
 367 change has completed, and in fact depending on thread priorities this
 368 return may happen before any power controller has been invoked.</P
 369 ><P
 370 >When the power management thread wakes up it examines the internal
 371 state to figure out what it should be doing. In this case it is
 372 supposed to change the global power mode, so it will iterate over all
 373 the power controllers requesting each one to switch to the
 374 <SPAN
 375 CLASS="TYPE"
 376 >idle</SPAN
 377 > mode. It is up to each power controller to handle
 378 this request appropriately. Optionally the thread will invoke a
 379 callback function after processing each power controller, so that
 380 higher-level code such as the policy module can more easily keep
 381 track of the actual state of each controller. Once the thread has
 382 iterated through all the power controllers it will again wait on the
 383 internal semaphore for the next request to arrive.</P
 384 ><DIV
 385 CLASS="NOTE"
 386 ><BLOCKQUOTE
 387 CLASS="NOTE"
 388 ><P
 389 ><B
 390 >Note: </B
 391 >At present the power management thread always runs at a single
 392 priority, which defaults to a low priority. A possible future
 393 enhancement would be to support two separate priorities. When
 394 switching to a lower-powered mode the thread would run at a low
 395 priority as before, thus allowing other threads to run and get a
 396 chance to cancel this mode change. When switching to a higher-powered
 397 mode the thread would run at a high priority. This could be especially
 398 important when moving out of the <SPAN
 399 CLASS="TYPE"
 400 >off</SPAN
 401 > state: for example
 402 it would ensure that all device drivers get a chance to wake up before
 403 ordinary application threads get to run again and possibly attempt I/O
 404 operations.</P
 405 ></BLOCKQUOTE
 406 ></DIV
 407 ><P
 408 >Although usually calls to <TT
 409 CLASS="FUNCTION"
 410 >power_set_mode</TT
 411 > will
 412 come from just one place in the policy module, this is not a hard
 413 requirement. It is possible for multiple threads to call this
 414 function, with no need for any synchronization. If the power
 415 management thread is in the middle of performing a mode change and a
 416 new request comes in, the thread will detect this, abort the current
 417 operation, and start iterating through the power controllers again
 418 with the new mode. This check happens between every power controller
 419 invocation. Usefully this makes it possible for power controllers
 420 themselves to manipulate power modes: a power controller is invoked to
 421 change mode; for some reason it determines that the new mode is
 422 inappropriate; it calls <TT
 423 CLASS="FUNCTION"
 424 >power_set_mode</TT
 425 > to move
 426 the system back to another mode; when the power controller returns
 427 this event will be detected; the power management thread will abort
 428 the current mode change, and start the new one.</P
 429 ><P
 430 >In addition to changing the power mode for the system as a whole,
 431 individual controllers can be manipulated using the function
 432 <TT
 433 CLASS="FUNCTION"
 434 >power_set_controller_mode</TT
 435 >. For example, while the
 436 system as a whole might be in <SPAN
 437 CLASS="TYPE"
 438 >active</SPAN
 439 > mode certain devices
 440 might be kept in <SPAN
 441 CLASS="TYPE"
 442 >sleep</SPAN
 443 > mode until they are explicitly
 444 activated. It is possible to mix concurrent calls to
 445 <TT
 446 CLASS="FUNCTION"
 447 >power_set_mode</TT
 448 > and
 449 <TT
 450 CLASS="FUNCTION"
 451 >power_set_controller_mode</TT
 452 >, and when a power
 453 controller is invoked it may use
 454 <TT
 455 CLASS="FUNCTION"
 456 >power_set_controller_mode</TT
 457 > to request further
 458 changes to its own or to another controller's mode as required.</P
 459 ><P
 460 >There are some scenarios where the power management package should not
 461 use its own thread. One scenario is if the configuration is
 462 specifically for a single-threaded application such as RedBoot.
 463 Another scenario is if the policy module already involves a separate
 464 thread: it may make more sense if the various power management
 465 operations are synchronous with respect to the calling thread. The use
 466 of a separate thread inside the power management package is controlled
 467 by the configuration option <TT
 468 CLASS="VARNAME"
 469 >CYGPKG_POWER_THREAD</TT
 470 >,
 471 which is active only if the kernel package is present and enabled by
 472 default.</P
 473 ><P
 474 >If no separate power management thread is used then obviously the
 475 implementations of <TT
 476 CLASS="FUNCTION"
 477 >power_set_mode</TT
 478 > and
 479 <TT
 480 CLASS="FUNCTION"
 481 >power_set_controller_mode</TT
 482 > will be somewhat
 483 different: instead of waking up a separate thread to do the work,
 484 these functions will now manipulate the power controllers directly. If
 485 the system does still involve multiple threads then only one thread
 486 may call <TT
 487 CLASS="FUNCTION"
 488 >power_set_mode</TT
 489 > or
 490 <TT
 491 CLASS="FUNCTION"
 492 >power_set_controller_mode</TT
 493 > at a time: the power
 494 management package will not provide any synchronization, that must
 495 happen at a higher level. However when a power controller is invoked
 496 it can still call these functions as required.</P
 497 ></DIV
 498 ><DIV
 499 CLASS="NAVFOOTER"
 500 ><HR
 501 ALIGN="LEFT"
 502 WIDTH="100%"><TABLE
 503 SUMMARY="Footer navigation table"
 504 WIDTH="100%"
 505 BORDER="0"
 506 CELLPADDING="0"
 507 CELLSPACING="0"
 508 ><TR
 509 ><TD
 510 WIDTH="33%"
 511 ALIGN="left"
 512 VALIGN="top"
 513 ><A
 514 HREF="services-power.html"
 515 ACCESSKEY="P"
 516 >Prev</A
 517 ></TD
 518 ><TD
 519 WIDTH="34%"
 520 ALIGN="center"
 521 VALIGN="top"
 522 ><A
 523 HREF="ecos-ref.html"
 524 ACCESSKEY="H"
 525 >Home</A
 526 ></TD
 527 ><TD
 528 WIDTH="33%"
 529 ALIGN="right"
 530 VALIGN="top"
 531 ><A
 532 HREF="power-info.html"
 533 ACCESSKEY="N"
 534 >Next</A
 535 ></TD
 536 ></TR
 537 ><TR
 538 ><TD
 539 WIDTH="33%"
 540 ALIGN="left"
 541 VALIGN="top"
 542 >eCos Power Management Support</TD
 543 ><TD
 544 WIDTH="34%"
 545 ALIGN="center"
 546 VALIGN="top"
 547 ><A
 548 HREF="services-power.html"
 549 ACCESSKEY="U"
 550 >Up</A
 551 ></TD
 552 ><TD
 553 WIDTH="33%"
 554 ALIGN="right"
 555 VALIGN="top"
 556 >Power Management Information</TD
 557 ></TR
 558 ></TABLE
 559 ></DIV
 560 ></BODY
 561 ></HTML
 562 >