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