Power Management Information

Accessing Power Controllers

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.

Global Power Modes

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.

Individual Controller Power Modes

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 detaching controllers from global mode changes.

Power Controller Identification

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;
}

The Power Management Thread

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.