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 >Changing Power Modes</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="Power Management Information"
26 HREF="power-info.html"><LINK
28 TITLE="Support for Policy Modules"
29 HREF="power-policy.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="power-info.html"
71 HREF="power-policy.html"
82 NAME="POWER-CHANGE">Changing Power Modes</H1
90 >Changing Power Modes -- reducing or increasing power consumption as needed</DIV
92 CLASS="REFSYNOPSISDIV"
108 CLASS="FUNCSYNOPSISINFO"
109 >#include <cyg/power/power.h></PRE
117 > void power_set_mode
119 >( PowerMode new_mode
126 > void power_set_controller_mode
128 >( PowerController* controller
136 > void power_set_controller_mode_now
138 >( PowerController* controller
149 NAME="POWER-CHANGE-GLOBAL"
152 >Changing the Global Power Mode</H2
154 >The primary functionality supported by the power management package is
155 to change the system's global power mode. This is achieved by calling
160 argument, which should be one of <TT
162 >PowerMode_Active</TT
174 >. Typically this function will only
175 be invoked in certain scenarios:</P
182 >A typical system will contain a policy module which is primarily
183 responsible for initiating power mode changes, and a thread inside the
184 power management package. The policy module will call
188 >, which has the effect of
189 manipulating some internal state in the power management package and
190 waking up its thread. When this thread gets scheduled to run (its
191 priority is controlled by a configuration option), it will iterate
192 over the power controllers and invoke each controller to change its
193 power mode. There is support for a <A
194 HREF="power-policy.html#POWER-POLICY-CALLBACK"
195 >callback function</A
198 HREF="power-attached.html"
200 > power controllers.</P
208 power management thread has had a chance to iterate over all the
209 controllers, or even before the thread has been rescheduled at all,
210 the policy module may decide that a different power mode would be more
211 appropriate for the current situation and calls
215 > again. This has the effect of
216 aborting the previous mode change, followed by the power management
217 thread iterating over the power controllers again for the new mode.</P
221 >If there is no single policy module responsible for power mode
222 changes, any code can call <TT
226 there are multiple calls in quick succession, earlier calls will
227 be aborted and the system should end up in the power mode
228 corresponding to the last call</P
232 >As a special case, it is possible for a power controller to call
236 > when invoked by the power
237 management thread. For example a power controller could decide that it
238 is inappropriate for the system to go to sleep because the device it
239 is associated with is still busy. The effect is as if the policy
240 module had called <TT
244 the mode change had completed.</P
248 >If the power management package has been configured not to use a
249 separate thread then obviously the behaviour is somewhat different.
253 > will now iterate over
254 the various power controllers immediately, rather than leaving this to
255 a separate thread, and the whole mode change completes before
259 > returns. If some other thread or a
264 behaviour of the system is undefined. However, it is still legal for a
265 power controller to call <TT
269 effectively this is a recursive call; it is detected by the system,
270 and internal state is updated; the recursive
274 > call now returns, and when the
275 power controller returns back to the original
279 > call it detects what has happened,
280 aborts the previous mode change, and starts a new mode change as
281 requested by the controller.</P
286 > is normally invoked from thread
287 context. If a separate power management thread is used it can be
288 invoked safely from DSR context. If the system is configured not to
289 use such a thread, it may or may not be safe to invoke this function
290 from DSR context: essentially the function just iterates through
291 the various power controllers, and the documentation or source code of
292 each controller present in the current system will have to be examined
293 to determine whether or not this can happen safely in DSR context.
297 > should never be invoked from
303 NAME="POWER-CHANGE-CONTROLLER"
306 >Manipulating an Individual Power Controller</H2
308 >In some cases it is desirable to set the power mode of an individual
309 controller separately from the mode for the system as a whole. For
310 example if a device is not currently being used then the associated
311 power controller could be set to <TT
315 even while the system as a whole is still active. This can be achieved
316 by calling the function
319 >power_set_controller_mode</TT
321 arguments: the first identifies a particular controller; the second
322 specifies the desired new power mode for that controller. The function
323 operates in much the same way as <TT
327 for example if a separate power management thread is being used then
330 >power_set_controller_mode</TT
332 manipulating some internal state and waking up that thread. The
333 limitations are also much the same as for
340 >power_set_controller_mode</TT
341 > should not be invoked
344 >Manipulating individual controllers is often used in conjunction with
346 HREF="power-attached.html"
349 >power_set_controller_attached</TT
352 allowing the policy module to specify which controllers are affected
353 by global mode changes.</P
358 NAME="POWER-CHANGE-CONTROLLER-NOW"
361 >Direct Manipulation of a Power Controller</H2
363 >In exceptional circumstances it may be necessary to invoke a power
364 controller directly, bypassing the power management thread and
365 higher-level functionality such as <A
366 HREF="power-policy.html#POWER-POLICY-CALLBACK"
367 >callback functions</A
371 >power_set_controller_mode_now</TT
373 this. It takes two arguments, a controller and a mode, just like
376 >power_set_controller_mode</TT
381 >power_set_controller_mode_now</TT
383 dangerous. For example no attempt is made to synchronise with any
384 other power mode changes that might be happening concurrently. A
385 possible use is when the system gets woken up out of
389 > mode: depending on the hardware, on which power
390 controllers are present, and on the application code it may be
391 necessary to wake up some power controllers immediately before the
392 system as a whole is ready to run again.</P
399 SUMMARY="Footer navigation table"
410 HREF="power-info.html"
428 HREF="power-policy.html"
438 >Power Management Information</TD
444 HREF="services-power.html"
452 >Support for Policy Modules</TD