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