packages/services/power/common/v2_0/doc/power-info.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 >Power Management Information</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="Introduction"
  26 HREF="power-intro.html"><LINK
  27 REL="NEXT"
  28 TITLE="Changing Power Modes"
  29 HREF="power-change.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-intro.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-change.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-INFO"
  80 >Power Management Information</A
  81 ></H1
  82 ><DIV
  83 CLASS="REFNAMEDIV"
  84 ><A
  85 NAME="AEN97"
  86 ></A
  87 ><H2
  88 >Name</H2
  89 >Obtaining Power Management Information&nbsp;--&nbsp;finding out about the various power controllers in the system</DIV
  90 ><DIV
  91 CLASS="REFSYNOPSISDIV"
  92 ><A
  93 NAME="AEN100"
  94 ></A
  95 ><H2
  96 >Synopsis</H2
  97 ><DIV
  98 CLASS="FUNCSYNOPSIS"
  99 ><A
 100 NAME="AEN101"
 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;
 113
 114 extern PowerController __POWER__[], __POWER_END__;
 115 extern PowerController power_controller_cpu;
 116 extern cyg_handle_t    power_thread_handle;</PRE
 117 ></TD
 118 ></TR
 119 ></TABLE
 120 ><P
 121 ><CODE
 122 ><CODE
 123 CLASS="FUNCDEF"
 124 >    PowerMode power_get_mode
 125   </CODE
 126 >(void);</CODE
 127 ></P
 128 ><P
 129 ><CODE
 130 ><CODE
 131 CLASS="FUNCDEF"
 132 >    PowerMode power_get_desired_mode
 133   </CODE
 134 >(void);</CODE
 135 ></P
 136 ><P
 137 ><CODE
 138 ><CODE
 139 CLASS="FUNCDEF"
 140 >    PowerMode power_get_controller_mode
 141   </CODE
 142 >(    PowerController* controller
 143   );</CODE
 144 ></P
 145 ><P
 146 ><CODE
 147 ><CODE
 148 CLASS="FUNCDEF"
 149 >    PowerMode power_get_controller_desired_mode
 150   </CODE
 151 >(    PowerController* controller
 152   );</CODE
 153 ></P
 154 ><P
 155 ><CODE
 156 ><CODE
 157 CLASS="FUNCDEF"
 158 >    const char* power_get_controller_id
 159   </CODE
 160 >(    PowerController* controller
 161   );</CODE
 162 ></P
 163 ><P
 164 ></P
 165 ></DIV
 166 ></DIV
 167 ><DIV
 168 CLASS="REFSECT1"
 169 ><A
 170 NAME="POWER-INFO-ACCESS"
 171 ></A
 172 ><H2
 173 >Accessing Power Controllers</H2
 174 ><P
 175 >All the power controllers in a system are held in a table, filled in
 176 at link-time. The symbols <TT
 177 CLASS="VARNAME"
 178 >__POWER__</TT
 179 > and
 180 <TT
 181 CLASS="VARNAME"
 182 >__POWER_END</TT
 183 > can be used to iterate through this
 184 table, for example:</P
 185 ><TABLE
 186 BORDER="0"
 187 BGCOLOR="#E0E0E0"
 188 WIDTH="100%"
 189 ><TR
 190 ><TD
 191 ><PRE
 192 CLASS="PROGRAMLISTING"
 193 >PowerController* controller;
 194 for (controller  = &#38;(__POWER__[0]);
 195      controller != &#38;(__POWER_END__);
 196      controller++) {
 197
 198      &#8230;
 199 }</PRE
 200 ></TD
 201 ></TR
 202 ></TABLE
 203 ><P
 204 >Each controller has an associated priority, controlling the order in
 205 which they appear in the table. Typically a software-only component
 206 such as a TCP/IP stack would use a small number for the priority, so
 207 that it appears near the start of the table, whereas a device driver
 208 would be nearer the back of the table. When switching to a
 209 lower-powered mode the power management package will iterate through
 210 this table from front to back, thus ensuring that for example the
 211 TCP/IP stack gets a chance to shut down before the underlying ethernet
 212 or other hardware that the stack depends on. Similarly when switching
 213 to a higher-powered mode the power management package will iterate
 214 through this table from back to front.</P
 215 ><P
 216 >In most systems there will be one special controller,
 217 <TT
 218 CLASS="VARNAME"
 219 >power_controller_cpu</TT
 220 >, which should be provided by
 221 one of the architectural, variant or platform HAL packages. This
 222 controller will always be the last entry in the table. It is
 223 responsible for the final power down operation when switching to
 224 <SPAN
 225 CLASS="TYPE"
 226 >off</SPAN
 227 > mode. Other packages such as device drivers may or
 228 may not declare variable identifiers for their power controllers,
 229 allowing those controllers to be accessed by name as well as by their
 230 entries in the global table.</P
 231 ></DIV
 232 ><DIV
 233 CLASS="REFSECT1"
 234 ><A
 235 NAME="POWER-INFO-GLOBAL"
 236 ></A
 237 ><H2
 238 >Global Power Modes</H2
 239 ><P
 240 >The function <TT
 241 CLASS="FUNCTION"
 242 >power_get_mode</TT
 243 > can be called at any
 244 time to determine the current power mode for the system as a whole.
 245 The return value will be one of <TT
 246 CLASS="LITERAL"
 247 >PowerMode_Active</TT
 248 >,
 249 <TT
 250 CLASS="LITERAL"
 251 >PowerMode_Idle</TT
 252 >, <TT
 253 CLASS="LITERAL"
 254 >PowerMode_Sleep</TT
 255 >
 256 or <TT
 257 CLASS="LITERAL"
 258 >PowerMode_Off</TT
 259 >. In normal circumstances it is
 260 unlikely that <TT
 261 CLASS="LITERAL"
 262 >PowerMode_Off</TT
 263 > would be returned since
 264 that mode generally means that the cpu is no longer running.</P
 265 ><P
 266 >The function <TT
 267 CLASS="FUNCTION"
 268 >power_get_desired_mode</TT
 269 > returns the
 270 power mode that the system should be running at. Most of the time this
 271 will be the same value as returned by
 272 <TT
 273 CLASS="FUNCTION"
 274 >power_get_mode</TT
 275 >. However a different value may be
 276 returned when in the middle of changing power modes. For example, if
 277 the current thread runs at a higher priority than the power management
 278 thread then the latter may have been pre-empted in the middle of a
 279 mode change: <TT
 280 CLASS="FUNCTION"
 281 >power_get_mode</TT
 282 > will return the mode
 283 the system was running at before the mode change started, and
 284 <TT
 285 CLASS="FUNCTION"
 286 >power_get_desired_mode</TT
 287 > will return the mode the
 288 system should end up in when the mode change completes, barring
 289 further calls to <TT
 290 CLASS="FUNCTION"
 291 >power_set_mode</TT
 292 >.</P
 293 ></DIV
 294 ><DIV
 295 CLASS="REFSECT1"
 296 ><A
 297 NAME="POWER-INFO-INDIVIDUAL"
 298 ></A
 299 ><H2
 300 >Individual Controller Power Modes</H2
 301 ><P
 302 >The power management package keeps track of the current and desired
 303 modes for each power controller, as well as the modes for the system as
 304 a whole. The function <TT
 305 CLASS="FUNCTION"
 306 >power_get_controller_mode</TT
 307 >
 308 takes a single argument, a pointer to a power controller, and returns
 309 the power mode that controller is currently running at. Similarly
 310 <TT
 311 CLASS="FUNCTION"
 312 >power_get_controller_desired_mode</TT
 313 > returns the
 314 power mode that controller should be running at. Most of the time the
 315 current and desired modes for a given controller will be the same, and
 316 will also be the same as the global power mode. However if the power
 317 management thread is preeempted in the middle of a mode change then
 318 some of the controllers will have been updated to the desired global
 319 mode, whereas others will still be at the old mode. The power
 320 management package also provides functionality for manipulating
 321 <A
 322 HREF="power-change.html#POWER-CHANGE-CONTROLLER"
 323 >individual controllers</A
 324 >, and for <A
 325 HREF="power-attached.html"
 326 >detaching</A
 327 > controllers from
 328 global mode changes.</P
 329 ></DIV
 330 ><DIV
 331 CLASS="REFSECT1"
 332 ><A
 333 NAME="POWER-INFO-IDS"
 334 ></A
 335 ><H2
 336 >Power Controller Identification</H2
 337 ><P
 338 >In some scenarios the power management package will run completely
 339 automated, and there is no need to identify individual power
 340 controllers. Any form of identification such as a string
 341 description would serve no purpose, but would still consume memory in
 342 the final system. In other scenarios it may be very desirable to
 343 provide some means of identification. For example, while still
 344 debugging it may be useful to see a simple string when printing the
 345 contents of a power controller structure. Alternatively, if the
 346 application is expected to provide some sort of user interface that
 347 gives control over which parts of the system are enabled or disabled,
 348 a string identifier for each controller would be useful. To cope with
 349 these scenarios the power management package provides a configuration
 350 option <TT
 351 CLASS="VARNAME"
 352 >CYGIMP_POWER_PROVIDE_STRINGS</TT
 353 >. When enabled,
 354 each power controller will contain a pointer to a constant string
 355 which can be accessed via a function
 356 <TT
 357 CLASS="FUNCTION"
 358 >power_get_controller_id</TT
 359 >. When disabled the system
 360 will not contain these strings, and the function will not be provided.
 361 The following code illustrates how to use this function.</P
 362 ><TABLE
 363 BORDER="0"
 364 BGCOLOR="#E0E0E0"
 365 WIDTH="100%"
 366 ><TR
 367 ><TD
 368 ><PRE
 369 CLASS="PROGRAMLISTING"
 370 >#include &lt;stdio.h&gt;
 371 #include &lt;pkgconf/system.h&gt;
 372 #ifndef CYGPKG_POWER
 373 # error The power management package is not present.
 374 #endif
 375 #include &lt;pkgconf/power.h&gt;
 376 #ifndef CYGIMP_POWER_PROVIDE_STRINGS
 377 # error Power controller identifiers are not available.
 378 #endif
 379 #include &lt;cyg/power/power.h&gt;
 380
 381 static const char*
 382 mode_to_string(PowerMode mode)
 383 {
 384     const char* result;
 385     switch(mode) {
 386       case PowerMode_Active : result = "active"; break;
 387       case PowerMode_Idle   : result = "idle"; break;
 388       case PowerMode_Sleep  : result = "sleep"; break;
 389       case PowerMode_Off    : result = "off"; break;
 390       default               : result = "&lt;unknown&gt;"; break;
 391     }
 392     return result;
 393 }
 394
 395 int
 396 main(int argc, char** argv)
 397 {
 398     PowerController* controller;
 399
 400     for (controller = &amp;(__POWER__[0]);
 401          controller != &amp;(__POWER_END__);
 402          controller++) {
 403         printf("Controller @ %p: %s, %s\n", controller,
 404                power_get_controller_id(controller),
 405                mode_to_string(power_get_controller_mode(controller)));
 406     }
 407     return 0;
 408 }</PRE
 409 ></TD
 410 ></TR
 411 ></TABLE
 412 ></DIV
 413 ><DIV
 414 CLASS="REFSECT1"
 415 ><A
 416 NAME="POWER-INFO-THREAD"
 417 ></A
 418 ><H2
 419 >The Power Management Thread</H2
 420 ><P
 421 >If the power management package is configured to use a separate thread
 422 then a handle for that thread is made available to higher-level code
 423 via the variable <TT
 424 CLASS="VARNAME"
 425 >power_thread_handle</TT
 426 >. This handle
 427 can be used for a variety of purposes, including manipulating that
 428 thread's priority.</P
 429 ></DIV
 430 ><DIV
 431 CLASS="NAVFOOTER"
 432 ><HR
 433 ALIGN="LEFT"
 434 WIDTH="100%"><TABLE
 435 WIDTH="100%"
 436 BORDER="0"
 437 CELLPADDING="0"
 438 CELLSPACING="0"
 439 ><TR
 440 ><TD
 441 WIDTH="33%"
 442 ALIGN="left"
 443 VALIGN="top"
 444 ><A
 445 HREF="power-intro.html"
 446 >Prev</A
 447 ></TD
 448 ><TD
 449 WIDTH="34%"
 450 ALIGN="center"
 451 VALIGN="top"
 452 ><A
 453 HREF="services-power.html"
 454 >Home</A
 455 ></TD
 456 ><TD
 457 WIDTH="33%"
 458 ALIGN="right"
 459 VALIGN="top"
 460 ><A
 461 HREF="power-change.html"
 462 >Next</A
 463 ></TD
 464 ></TR
 465 ><TR
 466 ><TD
 467 WIDTH="33%"
 468 ALIGN="left"
 469 VALIGN="top"
 470 >Introduction</TD
 471 ><TD
 472 WIDTH="34%"
 473 ALIGN="center"
 474 VALIGN="top"
 475 >&nbsp;</TD
 476 ><TD
 477 WIDTH="33%"
 478 ALIGN="right"
 479 VALIGN="top"
 480 >Changing Power Modes</TD
 481 ></TR
 482 ></TABLE
 483 ></DIV
 484 ></BODY
 485 ></HTML
 486 >