eCos Reference Manual
Prev |  | Next

# Changing Power Modes

## Name

Changing Power Modes -- reducing or increasing power consumption as needed

## Synopsis

    #include <cyg/power/power.h>

``void power_set_mode` ( PowerMode new_mode );`

``void power_set_controller_mode` ( PowerController* controller , PowerMode new_mode );`

``void power_set_controller_mode_now` ( PowerController* controller , PowerMode new_mode );`

## Changing the Global Power Mode

The primary functionality supported by the power management package is to change the system's global power mode. This is achieved by calling the function `power_set_mode` with a single argument, which should be one of `PowerMode_Active`, `PowerMode_Idle`, `PowerMode_Sleep` or `PowerMode_Off`. Typically this function will only be invoked in certain scenarios:

1. A typical system will contain a policy module which is primarily responsible for initiating power mode changes, and a thread inside the power management package. The policy module will call `power_set_mode`, which has the effect of manipulating some internal state in the power management package and waking up its thread. When this thread gets scheduled to run (its priority is controlled by a configuration option), it will iterate over the power controllers and invoke each controller to change its power mode. There is support for a callback function, and for detached power controllers.

2. After a call to `power_set_mode` but before the power management thread has had a chance to iterate over all the controllers, or even before the thread has been rescheduled at all, the policy module may decide that a different power mode would be more appropriate for the current situation and calls `power_set_mode` again. This has the effect of aborting the previous mode change, followed by the power management thread iterating over the power controllers again for the new mode.

3. If there is no single policy module responsible for power mode changes, any code can call `power_set_mode`. If there are multiple calls in quick succession, earlier calls will be aborted and the system should end up in the power mode corresponding to the last call

4. As a special case, it is possible for a power controller to call `power_set_mode` when invoked by the power management thread. For example a power controller could decide that it is inappropriate for the system to go to sleep because the device it is associated with is still busy. The effect is as if the policy module had called `power_set_mode` again before the mode change had completed.

If the power management package has been configured not to use a separate thread then obviously the behaviour is somewhat different. The call to `power_set_mode` will now iterate over the various power controllers immediately, rather than leaving this to a separate thread, and the whole mode change completes before `power_set_mode` returns. If some other thread or a DSR calls `power_set_mode` concurrently the behaviour of the system is undefined. However, it is still legal for a power controller to call `power_set_mode`: effectively this is a recursive call; it is detected by the system, and internal state is updated; the recursive `power_set_mode` call now returns, and when the power controller returns back to the original `power_set_mode` call it detects what has happened, aborts the previous mode change, and starts a new mode change as requested by the controller.

`power_set_mode` is normally invoked from thread context. If a separate power management thread is used it can be invoked safely from DSR context. If the system is configured not to use such a thread, it may or may not be safe to invoke this function from DSR context: essentially the function just iterates through the various power controllers, and the documentation or source code of each controller present in the current system will have to be examined to determine whether or not this can happen safely in DSR context. `power_set_mode` should never be invoked from ISR context.

## Manipulating an Individual Power Controller

In some cases it is desirable to set the power mode of an individual controller separately from the mode for the system as a whole. For example if a device is not currently being used then the associated power controller could be set to `PowerMode_Off`, even while the system as a whole is still active. This can be achieved by calling the function `power_set_controller_mode`. It takes two arguments: the first identifies a particular controller; the second specifies the desired new power mode for that controller. The function operates in much the same way as `power_set_mode`, for example if a separate power management thread is being used then `power_set_controller_mode` operates by manipulating some internal state and waking up that thread. The limitations are also much the same as for `power_set_mode`, so for example `power_set_controller_mode` should not be invoked from inside ISRs.

Manipulating individual controllers is often used in conjunction with the function `power_set_controller_attached`, allowing the policy module to specify which controllers are affected by global mode changes.

## Direct Manipulation of a Power Controller

In exceptional circumstances it may be necessary to invoke a power controller directly, bypassing the power management thread and higher-level functionality such as callback functions. The function `power_set_controller_mode_now` allows this. It takes two arguments, a controller and a mode, just like `power_set_controller_mode`.

Use of `power_set_controller_mode_now` is dangerous. For example no attempt is made to synchronise with any other power mode changes that might be happening concurrently. A possible use is when the system gets woken up out of sleep mode: depending on the hardware, on which power controllers are present, and on the application code it may be necessary to wake up some power controllers immediately before the system as a whole is ready to run again.

Prev | Home | Next
Power Management Information | Up | Support for Policy Modules