doc/html/ref/power-policy.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 >Support for Policy Modules</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="Changing Power Modes"
  26 HREF="power-change.html"><LINK
  27 REL="NEXT"
  28 TITLE="Attached and Detached Controllers"
  29 HREF="power-attached.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-change.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-attached.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-POLICY">Support for Policy Modules</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN15836"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >Support for Policy Modules&nbsp;--&nbsp;closer integration with higher-level code</DIV
  91 ><DIV
  92 CLASS="REFSYNOPSISDIV"
  93 ><A
  94 NAME="AEN15839"><H2
  95 >Synopsis</H2
  96 ><DIV
  97 CLASS="FUNCSYNOPSIS"
  98 ><A
  99 NAME="AEN15840"><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_policy_callback
 118   </CODE
 119 >(    void (*)(PowerController*, PowerMode, PowerMode, PowerMode, PowerMode) callback
 120   );</CODE
 121 ></P
 122 ><P
 123 ><CODE
 124 ><CODE
 125 CLASS="FUNCDEF"
 126 >    void (*)(PowerController*, PowerMode, PowerMode, PowerMode, PowerMode) power_get_policy_callback
 127   </CODE
 128 >(void);</CODE
 129 ></P
 130 ><P
 131 ><CODE
 132 ><CODE
 133 CLASS="FUNCDEF"
 134 >    CYG_ADDRWORD power_get_controller_policy_data
 135   </CODE
 136 >(    PowerController* controller
 137   );</CODE
 138 ></P
 139 ><P
 140 ><CODE
 141 ><CODE
 142 CLASS="FUNCDEF"
 143 >    void power_set_controller_policy_data
 144   </CODE
 145 >(    PowerController* controller
 146   ,     CYG_ADDRWORD data
 147   );</CODE
 148 ></P
 149 ><P
 150 ></P
 151 ></DIV
 152 ></DIV
 153 ><DIV
 154 CLASS="REFSECT1"
 155 ><A
 156 NAME="POWER-POLICY-CALLBACK"
 157 ></A
 158 ><H2
 159 >Policy Callbacks</H2
 160 ><P
 161 >The use of a separate thread to perform power mode changes in typical
 162 configurations can cause problems for some policy modules.
 163 Specifically, the policy module can request a mode change for the
 164 system as a whole or for an individual controller, but it does not
 165 know when the power management thread actually gets scheduled to run
 166 again and carry out the request. Although it would be possible for the
 167 policy module to perform some sort of polling, in general that is
 168 undesirable.</P
 169 ><P
 170 >To avoid such problems the policy module can install a callback
 171 function using <TT
 172 CLASS="FUNCTION"
 173 >power_set_policy_callback</TT
 174 >. The
 175 current callback function can be retrieved using
 176 <TT
 177 CLASS="FUNCTION"
 178 >power_get_policy_callback</TT
 179 >. If a callback function
 180 has been installed then it will be called by the power management
 181 package whenever a power controller has been invoked to perform a mode
 182 change. The callback will be called in the context of the power
 183 management thread, so usually it will have to make use of thread
 184 synchronisation primitives to interact with the main policy module. It
 185 is passed five arguments:</P
 186 ><P
 187 ></P
 188 ><OL
 189 TYPE="1"
 190 ><LI
 191 ><P
 192 >The power controller that has just been invoked to perform a mode
 193 change. </P
 194 ></LI
 195 ><LI
 196 ><P
 197 >The mode this controller was running at before the invocation.</P
 198 ></LI
 199 ><LI
 200 ><P
 201 >The current mode this controller is now running at.</P
 202 ></LI
 203 ><LI
 204 ><P
 205 >The desired mode before the power controller was invoked. Usually this
 206 will be the same as the current mode, unless the controller has
 207 decided for some reason that this was inappropriate.</P
 208 ></LI
 209 ><LI
 210 ><P
 211 >The current desired mode. This will differ from the previous argument
 212 only if there has was another call to
 213 <TT
 214 CLASS="FUNCTION"
 215 >power_set_mode</TT
 216 > or
 217 <TT
 218 CLASS="FUNCTION"
 219 >power_set_controller_mode</TT
 220 > while the power
 221 controller was being invoked, probably by the power controller itself.</P
 222 ></LI
 223 ></OL
 224 ><P
 225 >A simple example of a policy callback function would be:</P
 226 ><TABLE
 227 BORDER="5"
 228 BGCOLOR="#E0E0F0"
 229 WIDTH="70%"
 230 ><TR
 231 ><TD
 232 ><PRE
 233 CLASS="PROGRAMLISTING"
 234 >static void
 235 power_callback(
 236     PowerController* controller,
 237     PowerMode old_mode,
 238     PowerMode new_mode,
 239     PowerMode old_desired_mode,
 240     powerMode new_desired_mode)
 241 {
 242     printf("Power mode change: %s, %s -&#62; %d\n",
 243         power_get_controller_id(controller),
 244         mode_to_string(old_mode),
 245         mode_to_string(new_mode));
 246
 247     CYG_UNUSED_PARAM(PowerMode, old_desired_mode);
 248     CYG_UNUSED_PARAM(PowerMode, new_desired_mode);
 249 }
 250
 251 int
 252 main(int argc, char** argv)
 253 {
 254     &#8230;
 255     power_set_policy_callback(&amp;power_callback);
 256     &#8230;
 257 }</PRE
 258 ></TD
 259 ></TR
 260 ></TABLE
 261 ><P
 262 >If <TT
 263 CLASS="FUNCTION"
 264 >power_set_controller_mode_now</TT
 265 > is used to
 266 manipulate an individual controller the policy callback will not be
 267 invoked. This function may get called from any context including DSRs,
 268 and even if there is already a call to the policy callback happening
 269 in some other context, so invoking the callback would usually be
 270 unsafe.</P
 271 ><P
 272 >If the power management package has not been configured to use a
 273 separate thread then <TT
 274 CLASS="FUNCTION"
 275 >power_set_mode</TT
 276 > and
 277 <TT
 278 CLASS="FUNCTION"
 279 >power_set_controller_mode</TT
 280 > will manipulate the
 281 power controllers immediately and invoke the policy callback
 282 afterwards. Therefore the policy callback will typically run in the
 283 same context as the main policy module.</P
 284 ></DIV
 285 ><DIV
 286 CLASS="REFSECT1"
 287 ><A
 288 NAME="POWER-POLICY-DATA"
 289 ></A
 290 ><H2
 291 >Policy-specific Controller Data</H2
 292 ><P
 293 >Some policy modules may want to associate some additional data with
 294 each power controller. This could be achieved by for example
 295 maintaining a hash table or similar data structure, but for
 296 convenience the power management package allows higher-level code,
 297 typically the policy module, to store and retrieve one word of data in
 298 each power controller. The function
 299 <TT
 300 CLASS="FUNCTION"
 301 >power_set_controller_policy_data</TT
 302 > takes two
 303 arguments, a pointer to a power controller and a
 304 <SPAN
 305 CLASS="TYPE"
 306 >CYG_ADDRWORD</SPAN
 307 > of data: by appropriate use of casts this
 308 word could be an integer or a pointer to some data structure. The
 309 matching function
 310 <TT
 311 CLASS="FUNCTION"
 312 >power_get_controller_policy_data</TT
 313 > retrieves the
 314 word previously installed, and can be cast back to an integer or
 315 pointer. The default value for the policy data is 0.</P
 316 ><P
 317 >For example the following code fragment stores a simple index value in
 318 each power controller. This could then be retrieved by the policy
 319 callback.</P
 320 ><TABLE
 321 BORDER="5"
 322 BGCOLOR="#E0E0F0"
 323 WIDTH="70%"
 324 ><TR
 325 ><TD
 326 ><PRE
 327 CLASS="PROGRAMLISTING"
 328 >    unsigned int     i = 0;
 329     PowerController* controller;
 330
 331     for (controller = &amp;(__POWER__[0]);
 332          controller != &amp;(__POWER_END__);
 333          controller++) {
 334         power_set_controller_policy_data(controller, (CYG_ADDRWORD) i++);
 335     }</PRE
 336 ></TD
 337 ></TR
 338 ></TABLE
 339 ><P
 340 >Not all policy modules will require per-controller data. The
 341 configuration option
 342 <TT
 343 CLASS="VARNAME"
 344 >CYGIMP_POWER_PROVIDE_POLICY_DATA</TT
 345 > can be used to
 346 control this functionality, thus avoiding wasting a small amount of
 347 memory inside each power controller structure.</P
 348 ></DIV
 349 ><DIV
 350 CLASS="NAVFOOTER"
 351 ><HR
 352 ALIGN="LEFT"
 353 WIDTH="100%"><TABLE
 354 SUMMARY="Footer navigation table"
 355 WIDTH="100%"
 356 BORDER="0"
 357 CELLPADDING="0"
 358 CELLSPACING="0"
 359 ><TR
 360 ><TD
 361 WIDTH="33%"
 362 ALIGN="left"
 363 VALIGN="top"
 364 ><A
 365 HREF="power-change.html"
 366 ACCESSKEY="P"
 367 >Prev</A
 368 ></TD
 369 ><TD
 370 WIDTH="34%"
 371 ALIGN="center"
 372 VALIGN="top"
 373 ><A
 374 HREF="ecos-ref.html"
 375 ACCESSKEY="H"
 376 >Home</A
 377 ></TD
 378 ><TD
 379 WIDTH="33%"
 380 ALIGN="right"
 381 VALIGN="top"
 382 ><A
 383 HREF="power-attached.html"
 384 ACCESSKEY="N"
 385 >Next</A
 386 ></TD
 387 ></TR
 388 ><TR
 389 ><TD
 390 WIDTH="33%"
 391 ALIGN="left"
 392 VALIGN="top"
 393 >Changing Power Modes</TD
 394 ><TD
 395 WIDTH="34%"
 396 ALIGN="center"
 397 VALIGN="top"
 398 ><A
 399 HREF="services-power.html"
 400 ACCESSKEY="U"
 401 >Up</A
 402 ></TD
 403 ><TD
 404 WIDTH="33%"
 405 ALIGN="right"
 406 VALIGN="top"
 407 >Attached and Detached Controllers</TD
 408 ></TR
 409 ></TABLE
 410 ></DIV
 411 ></BODY
 412 ></HTML
 413 >