power.sgml

eCos操作系统源码

<!-- DOCTYPE reference  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     power.sgml                                                  -->
<!--                                                                 -->
<!--     Generic power management documentation.                     -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN####                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- Copyright (C) 2001, 2002 Red Hat, Inc.                          -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!--                                                                 -->      
<!-- ####COPYRIGHTEND####                                            -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- Author(s):   bartv                                              -->
<!-- Contact(s):  bartv                                              -->
<!-- Date:        2001/06/26                                         -->
<!-- Version:     0.01                                               -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->
<part id="services-power">
<!-- reference id="services-power" -->
  <title>eCos Power Management Support</title>

<!-- {{{ Intro                          -->

<refentry id="power-intro">
<refmeta>
<refentrytitle>Introduction</refentrytitle>
</refmeta>
<refnamediv>
<refname>Introduction</refname>
<refpurpose>eCos support for Power Management</refpurpose>
</refnamediv>

<!-- {{{ Intro                          -->

<refsect1 id="power-intro-intro">
<title>Introduction</title>
<para>
The eCos Power Management package provides a framework for
incorporating power management facilities in an embedded application.
However its functionality is deliberately limited.
</para>
<orderedlist>
<listitem>
<para>
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 <firstterm>power
controllers</firstterm>. The power management package groups these
power controllers together and provides an interface for manipulating
them.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
</orderedlist>
</refsect1>

<!-- }}} -->
<!-- {{{ including                      -->

<refsect1 id="power-intro-include">
<title>Including Power Management</title>
<para>
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 <command>ecosconfig</command> tool this
can be achieved using a command such as:
</para>
<screen>
$ ecosconfig add power
</screen>
<para>
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
<filename class="headerfile">cyg/power/power.h</filename>. This header
file can be used by both C and C++ code.
</para>

</refsect1>

<!-- }}} -->
<!-- {{{ modes                          -->

<refsect1 id="power-intro-modes">
<title>Power Modes</title>
<para>
There are four defined modes of operation:
</para>
<variablelist>

<varlistentry><term>active</term>
<listitem>
<para>
The system is fully operational, and power consumption is expected to
be high.
</para>
</listitem>
</varlistentry>

<varlistentry><term>idle</term>
<listitem>
<para>
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.
</para>
<para>
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.
</para>
</listitem>
</varlistentry>

<varlistentry><term>sleep</term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>

<varlistentry><term>off</term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>

</variablelist>

<para>
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.
</para>

</refsect1>

<!-- }}} -->
<!-- {{{ Power Controllers              -->

<refsect1 id="power-intro-controllers">
<title>Power Controllers</title>
<para>
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:
</para>
<orderedlist>
<listitem>
<para>
Usually there will be one power controller
<varname>power_controller_cpu</varname> 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 <type>off</type> 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.
</para>
<para>
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
<varname>power_controller_cpu</varname> 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.
</para>
</listitem>
<listitem>
<para>
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,
<varname>power_controller_cpu</varname> 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.
</para>
</listitem>
<listitem>
<para>
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 <type>off</type> mode while there were
open connections).
</para>
</listitem>
</orderedlist>
</refsect1>

<!-- }}} -->
<!-- {{{ Basic Operation                -->

<refsect1 id="power-intro-operation">
<title>Basic Operation</title>
<para>
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
<varname>CYGNUM_POWER_THREAD_STACKSIZE</varname> and
<varname>CYGNUM_POWER_THREAD_PRIORITY</varname>. 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.
</para>
<para>
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 <function>power_set_mode</function>,
provided by the power management package and declared in <filename
class="headerfile">cyg/power/power.h</filename>, with a single
argument, <literal>PowerMode_Idle</literal>. 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.
</para>
<para>
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
<type>idle</type> 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.
</para>
<note>
<para>
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 <type>off</type> 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.
</para>
</note>
<para>
Although usually calls to <function>power_set_mode</function> 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 <function>power_set_mode</function> 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.
</para>
<para>
In addition to changing the power mode for the system as a whole,
individual controllers can be manipulated using the function
<function>power_set_controller_mode</function>. For example, while the
system as a whole might be in <type>active</type> mode certain devices
might be kept in <type>sleep</type> mode until they are explicitly
activated. It is possible to mix concurrent calls to
<function>power_set_mode</function> and
<function>power_set_controller_mode</function>, and when a power
controller is invoked it may use
<function>power_set_controller_mode</function> to request further
changes to its own or to another controller's mode as required.
</para>
<para>
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