Subversion Repositories openrisc_2011-10-31

Introduction

Introduction

eCos support for Power Management

The eCos Power Management package provides a framework for

incorporating power management facilities in an embedded application.

However its functionality is deliberately limited.

The package does not contain any support for controlling the current

power mode of any given processor, device or board. Instead it is the

responsibility of the appropriate HAL or device driver package to

implement such support, by implementing power

controllers. The power management package groups these

power controllers together and provides an interface for manipulating

them.

The package does not contain any power management policy support.

Specifically, including this package in an application does not by

itself ever cause the system to go into low-power mode. Instead it is

the responsibility of a separate policy module, provided by

higher-level application code or by some other package, to decide when

it would be appropriate to switch from one power mode to another. The

power management package then provides the mechanisms for making it

happen.

The power management package is never included automatically in an

eCos configuration: it is not part of any target specification or of

any template. Instead it must be added explicitly to a configuration

if the intended application requires power management functionality.

When using the command-line ecosconfig tool this

can be achieved using a command such as:

$ ecosconfig add power

The generic eCos user documentation should be consulted for more

information on how to use the various tools. The functionality

provided by the power management package is defined in the header file

cyg/power/power.h. This header

file can be used by both C and C++ code.

There are four defined modes of operation:

active

The system is fully operational, and power consumption is expected to

be high.

idle

There has been little or no activity for a short period of time. It is

up to the policy module to determine what constitutes a short period

of time, but typically it will be some tenths of a second or some

small number of seconds. A possible action when entering idle mode is

to reduce the system's clock speed, thus reducing the power drawn by

the cpu.

Note that typically this power mode is not entered automatically

whenever the idle thread starts running. Instead it is entered when

the policy module discovers that for a certain period of time the

system has been spending most of its time in the idle thread.

Theoretically it is possible to implement a policy module that would

cause a switch to idle mode as soon as the idle thread starts running,

but that could result in a great many power mode changes for no

immediate benefit.

sleep

The system has been idle for a significant period of time, perhaps

some tens of seconds. It is desirable to shut down any hardware that

is drawing a significant amount of power, for example a screen

backlight.

off

The system is powered down. Power consumption should be minimized.

Some special action may be needed before the system comes back up, for

example the user may need to press a specific button.

The exact transitions that will happen are decided by the policy

module. One policy module might include transitions from active to

idle, from idle to sleep, from sleep to off, and from any of idle,

sleep or off directly back to active. Another policy module might

only use the active and off states, bypassing the intermediate ones.

The power management package operates primarily on power controllers.

The main functionality provided by a power controller is to switch the

power mode for some part of the system, for example the lcd display or

the cpu. A power controller consists primarily of a function which

will be invoked to switch the power mode for the part of the overall

system being controlled, plus some auxiliary data. A typical system

will include a number of different power controllers:

Usually there will be one power controller

power_controller_cpu associated with the processor

or with the target platform, and provided by the corresponding HAL

package. It is this controller which is responsible for switching off

the system when entering the off mode, which makes it

somewhat special: attempting to switch off the cpu before other

devices like the lcd display does not make sense because the cpu would

no longer be executing any instructions for the latter operation.

Therefore this power controller has to be invoked last when switching

to a lower-power mode, and similarly when switching back to a

higher-power mode it will be invoked first.

It should be noted that providing power management support is not a

hard requirement when porting eCos to a new processor or platform, and

many eCos ports predate the availability of power management support.

Therefore for any given platform it is distinctly possible that

power_controller_cpu is not yet provided, and if

full power management functionality is desired then the appropriate

HAL package would have to be extended first. System developers should

examine the relevant HAL documentation and sources to determine what

is actually available.

Some or all of the device drivers will supply their own power

controllers, as part of the device driver package. It is not required

that all device drivers provide power controllers. In some cases,

especially for devices that are integrated with the processor,

power_controller_cpu will take care of the

integrated devices as a side effect. In other cases the hardware may

not provide any functionality that allows power consumption to be

controlled. For any given device driver it is also possible that no

power controller exists either because it was not required when the

driver was written, or because the driver predates the availability of

power management. Again the relevant documentation and sources should

be consulted for further information.

There may be power controllers which are not associated directly with

any specific hardware. For example a TCP/IP stack could provide a

power controller so that it gets informed when the system has been

reactivated: by looking at the system clock it can determine for how

long the system has been switched off; using this information it can

then recover from expired dhcp leases, or even to shut down any stream

connections that may have become invalid (although arguably the stack

should have refused to go to off mode while there were

open connections).

By default the Power Management package creates a thread during

initialization. It is also possible for the package to be used without

such a thread, for example in configurations which do not include a

full kernel, and this alternative is described below. When a separate

thread is used the stacksize and priority for this thread can be

controlled by configuration options

CYGNUM_POWER_THREAD_STACKSIZE and

CYGNUM_POWER_THREAD_PRIORITY. Typically the thread

will just wait on a semaphore internal to the package, and will do

nothing until some other part of the system requests a change to the

power mode.

At some point the policy module will decide that the system should

move into a lower-power mode, for example from active to idle. This is

achieved by calling the function power_set_mode,

provided by the power management package and declared in 

class="headerfile">cyg/power/power.h, with a single

argument, PowerMode_Idle. This function manipulates

some internal state and posts the semaphore, thus waking up the power

management thread. Note that the function returns before the mode

change has completed, and in fact depending on thread priorities this

return may happen before any power controller has been invoked.

When the power management thread wakes up it examines the internal

state to figure out what it should be doing. In this case it is

supposed to change the global power mode, so it will iterate over all

the power controllers requesting each one to switch to the

idle mode. It is up to each power controller to handle

this request appropriately. Optionally the thread will invoke a

callback function after processing each power controller, so that

higher-level code such as the policy module can more easily keep

track of the actual state of each controller. Once the thread has

iterated through all the power controllers it will again wait on the

internal semaphore for the next request to arrive.

At present the power management thread always runs at a single

priority, which defaults to a low priority. A possible future

enhancement would be to support two separate priorities. When

switching to a lower-powered mode the thread would run at a low

priority as before, thus allowing other threads to run and get a

chance to cancel this mode change. When switching to a higher-powered

mode the thread would run at a high priority. This could be especially

important when moving out of the off state: for example

it would ensure that all device drivers get a chance to wake up before

ordinary application threads get to run again and possibly attempt I/O

operations.

Although usually calls to power_set_mode will

come from just one place in the policy module, this is not a hard

requirement. It is possible for multiple threads to call this

function, with no need for any synchronization. If the power

management thread is in the middle of performing a mode change and a

new request comes in, the thread will detect this, abort the current

operation, and start iterating through the power controllers again

with the new mode. This check happens between every power controller

invocation. Usefully this makes it possible for power controllers

themselves to manipulate power modes: a power controller is invoked to

change mode; for some reason it determines that the new mode is

inappropriate; it calls power_set_mode to move

the system back to another mode; when the power controller returns

this event will be detected; the power management thread will abort

the current mode change, and start the new one.

In addition to changing the power mode for the system as a whole,

individual controllers can be manipulated using the function

power_set_controller_mode. For example, while the

system as a whole might be in active mode certain devices

might be kept in sleep mode until they are explicitly

activated. It is possible to mix concurrent calls to

power_set_mode and

power_set_controller_mode, and when a power

controller is invoked it may use

power_set_controller_mode to request further

changes to its own or to another controller's mode as required.

There are some scenarios where the power management package should not

use its own thread. One scenario is if the configuration is

specifically for a single-threaded application such as RedBoot.

Another scenario is if the policy module already involves a separate

thread: it may make more sense if the various power management

operations are synchronous with respect to the calling thread. The use

of a separate thread inside the power management package is controlled

by the configuration option CYGPKG_POWER_THREAD,

which is active only if the kernel package is present and enabled by

default.

If no separate power management thread is used then obviously the

implementations of power_set_mode and

power_set_controller_mode will be somewhat

different: instead of waking up a separate thread to do the work,

these functions will now manipulate the power controllers directly. If

the system does still involve multiple threads then only one thread

may call power_set_mode or

power_set_controller_mode at a time: the power

management package will not provide any synchronization, that must

happen at a higher level. However when a power controller is invoked

it can still call these functions as required.

Power Management Information

Obtaining Power Management Information

finding out about the various power controllers in the system

#include <cyg/power/power.h>

extern PowerController __POWER__[], __POWER_END__;

extern PowerController power_controller_cpu;

extern cyg_handle_t    power_thread_handle;

    PowerMode power_get_mode

    PowerMode power_get_desired_mode

    PowerMode power_get_controller_mode

    PowerController* controller

    PowerMode power_get_controller_desired_mode

    PowerController* controller

    const char* power_get_controller_id

    PowerController* controller

All the power controllers in a system are held in a table, filled in

at link-time. The symbols __POWER__ and

__POWER_END can be used to iterate through this

table, for example:

PowerController* controller;

for (controller  = &(__POWER__[0]);

     controller != &(__POWER_END__);

     controller++) {

     …

}

Each controller has an associated priority, controlling the order in

which they appear in the table. Typically a software-only component

such as a TCP/IP stack would use a small number for the priority, so

that it appears near the start of the table, whereas a device driver

would be nearer the back of the table. When switching to a

lower-powered mode the power management package will iterate through

this table from front to back, thus ensuring that for example the

TCP/IP stack gets a chance to shut down before the underlying ethernet

or other hardware that the stack depends on. Similarly when switching

to a higher-powered mode the power management package will iterate

through this table from back to front.

In most systems there will be one special controller,

power_controller_cpu, which should be provided by

one of the architectural, variant or platform HAL packages. This

controller will always be the last entry in the table. It is

responsible for the final power down operation when switching to

off mode. Other packages such as device drivers may or

may not declare variable identifiers for their power controllers,

allowing those controllers to be accessed by name as well as by their

entries in the global table.

The function power_get_mode can be called at any

time to determine the current power mode for the system as a whole.

The return value will be one of PowerMode_Active,

PowerMode_Idle, PowerMode_Sleep

or PowerMode_Off. In normal circumstances it is

unlikely that PowerMode_Off would be returned since

that mode generally means that the cpu is no longer running.

The function power_get_desired_mode returns the

power mode that the system should be running at. Most of the time this

will be the same value as returned by

power_get_mode. However a different value may be

returned when in the middle of changing power modes. For example, if

the current thread runs at a higher priority than the power management

thread then the latter may have been pre-empted in the middle of a

mode change: power_get_mode will return the mode

the system was running at before the mode change started, and

power_get_desired_mode will return the mode the

system should end up in when the mode change completes, barring

further calls to power_set_mode.

The power management package keeps track of the current and desired

modes for each power controller, as well as the modes for the system as

a whole. The function power_get_controller_mode

takes a single argument, a pointer to a power controller, and returns

the power mode that controller is currently running at. Similarly

power_get_controller_desired_mode returns the

power mode that controller should be running at. Most of the time the

current and desired modes for a given controller will be the same, and

will also be the same as the global power mode. However if the power

management thread is preeempted in the middle of a mode change then

some of the controllers will have been updated to the desired global

mode, whereas others will still be at the old mode. The power

management package also provides functionality for manipulating

individual controllers, and for 

linkend="power-attached">detaching controllers from

global mode changes.

In some scenarios the power management package will run completely

automated, and there is no need to identify individual power

controllers. Any form of identification such as a string

description would serve no purpose, but would still consume memory in

the final system. In other scenarios it may be very desirable to

provide some means of identification. For example, while still

debugging it may be useful to see a simple string when printing the

contents of a power controller structure. Alternatively, if the

application is expected to provide some sort of user interface that

gives control over which parts of the system are enabled or disabled,

a string identifier for each controller would be useful. To cope with

these scenarios the power management package provides a configuration

option CYGIMP_POWER_PROVIDE_STRINGS. When enabled,

each power controller will contain a pointer to a constant string

which can be accessed via a function

power_get_controller_id. When disabled the system

will not contain these strings, and the function will not be provided.

The following code illustrates how to use this function.

#include <stdio.h>

#include <pkgconf/system.h>

#ifndef CYGPKG_POWER

# error The power management package is not present.

#endif

#include <pkgconf/power.h>

#ifndef CYGIMP_POWER_PROVIDE_STRINGS

# error Power controller identifiers are not available.

#endif

#include <cyg/power/power.h>

static const char*

mode_to_string(PowerMode mode)

{

    const char* result;

    switch(mode) {

      case PowerMode_Active : result = "active"; break;

      case PowerMode_Idle   : result = "idle"; break;

      case PowerMode_Sleep  : result = "sleep"; break;

      case PowerMode_Off    : result = "off"; break;

      default               : result = "<unknown>"; break;

    }

    return result;

}

int

main(int argc, char** argv)

{

    PowerController* controller;

    for (controller = &(__POWER__[0]);

         controller != &(__POWER_END__);

         controller++) {

        printf("Controller @ %p: %s, %s\n", controller,

               power_get_controller_id(controller),

               mode_to_string(power_get_controller_mode(controller)));

    }

    return 0;

}

If the power management package is configured to use a separate thread

then a handle for that thread is made available to higher-level code

via the variable power_thread_handle. This handle

can be used for a variety of purposes, including manipulating that

thread's priority.

Changing Power Modes

Changing Power Modes

reducing or increasing power consumption as needed

#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

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:

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 

linkend="power-policy-callback">callback function, and for

detached power controllers.

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.

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

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.

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 

linkend="power-attached">power_set_controller_attached,

allowing the policy module to specify which controllers are affected

by global mode changes.

In exceptional circumstances it may be necessary to invoke a power

controller directly, bypassing the power management thread and

higher-level functionality such as 

linkend="power-policy-callback">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.

Support for Policy Modules

Support for Policy Modules

closer integration with higher-level code

#include <cyg/power/power.h>

    void power_set_policy_callback

    void (*)(PowerController*, PowerMode, PowerMode, PowerMode, PowerMode) callback

    void (*)(PowerController*, PowerMode, PowerMode, PowerMode, PowerMode) power_get_policy_callback

    CYG_ADDRWORD power_get_controller_policy_data

    PowerController* controller

    void power_set_controller_policy_data

    PowerController* controller

    CYG_ADDRWORD data

The use of a separate thread to perform power mode changes in typical

configurations can cause problems for some policy modules.

Specifically, the policy module can request a mode change for the

system as a whole or for an individual controller, but it does not

know when the power management thread actually gets scheduled to run

again and carry out the request. Although it would be possible for the

policy module to perform some sort of polling, in general that is

undesirable.

To avoid such problems the policy module can install a callback

function using power_set_policy_callback. The

current callback function can be retrieved using

power_get_policy_callback. If a callback function

has been installed then it will be called by the power management

package whenever a power controller has been invoked to perform a mode

change. The callback will be called in the context of the power

management thread, so usually it will have to make use of thread

synchronisation primitives to interact with the main policy module. It

is passed five arguments:

The power controller that has just been invoked to perform a mode

change.