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. -->
12 >Support for Policy Modules</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="eCos Power Management Support"
23 HREF="services-power.html"><LINK
25 TITLE="Changing Power Modes"
26 HREF="power-change.html"><LINK
28 TITLE="Attached and Detached Controllers"
29 HREF="power-attached.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="power-change.html"
71 HREF="power-attached.html"
82 NAME="POWER-POLICY">Support for Policy Modules</H1
90 >Support for Policy Modules -- closer integration with higher-level code</DIV
92 CLASS="REFSYNOPSISDIV"
108 CLASS="FUNCSYNOPSISINFO"
109 >#include <cyg/power/power.h></PRE
117 > void power_set_policy_callback
119 >( void (*)(PowerController*, PowerMode, PowerMode, PowerMode, PowerMode) callback
126 > void (*)(PowerController*, PowerMode, PowerMode, PowerMode, PowerMode) power_get_policy_callback
134 > CYG_ADDRWORD power_get_controller_policy_data
136 >( PowerController* controller
143 > void power_set_controller_policy_data
145 >( PowerController* controller
156 NAME="POWER-POLICY-CALLBACK"
159 >Policy Callbacks</H2
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
170 >To avoid such problems the policy module can install a callback
173 >power_set_policy_callback</TT
175 current callback function can be retrieved using
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
192 >The power controller that has just been invoked to perform a mode
197 >The mode this controller was running at before the invocation.</P
201 >The current mode this controller is now running at.</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
211 >The current desired mode. This will differ from the previous argument
212 only if there has was another call to
219 >power_set_controller_mode</TT
221 controller was being invoked, probably by the power controller itself.</P
225 >A simple example of a policy callback function would be:</P
233 CLASS="PROGRAMLISTING"
236 PowerController* controller,
239 PowerMode old_desired_mode,
240 powerMode new_desired_mode)
242 printf("Power mode change: %s, %s -> %d\n",
243 power_get_controller_id(controller),
244 mode_to_string(old_mode),
245 mode_to_string(new_mode));
247 CYG_UNUSED_PARAM(PowerMode, old_desired_mode);
248 CYG_UNUSED_PARAM(PowerMode, new_desired_mode);
252 main(int argc, char** argv)
255 power_set_policy_callback(&power_callback);
264 >power_set_controller_mode_now</TT
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
272 >If the power management package has not been configured to use a
273 separate thread then <TT
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
288 NAME="POWER-POLICY-DATA"
291 >Policy-specific Controller Data</H2
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
301 >power_set_controller_policy_data</TT
303 arguments, a pointer to a power controller and a
307 > of data: by appropriate use of casts this
308 word could be an integer or a pointer to some data structure. The
312 >power_get_controller_policy_data</TT
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
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
327 CLASS="PROGRAMLISTING"
328 > unsigned int i = 0;
329 PowerController* controller;
331 for (controller = &(__POWER__[0]);
332 controller != &(__POWER_END__);
334 power_set_controller_policy_data(controller, (CYG_ADDRWORD) i++);
340 >Not all policy modules will require per-controller data. The
344 >CYGIMP_POWER_PROVIDE_POLICY_DATA</TT
346 control this functionality, thus avoiding wasting a small amount of
347 memory inside each power controller structure.</P
354 SUMMARY="Footer navigation table"
365 HREF="power-change.html"
383 HREF="power-attached.html"
393 >Changing Power Modes</TD
399 HREF="services-power.html"
407 >Attached and Detached Controllers</TD