power.sgml

eCos操作系统源码

and another to specify the desired new state.
<function>power_get_controller_attached</function> can be used to
determine whether or not a specific controller is currently attached.
</para>
<para>
The attached or detached state of a controller only affects what
happens during a global mode change, in other words following a call
to <function>power_set_mode</function>. It is still possible to
manipulate a detached controller using
<function>power_set_controller_mode</function> or
<function>power_set_controller_mode_now</function>.
</para>

</refsect1>
</refentry>

<!-- }}} -->
<!-- {{{ Implementing                   -->

<refentry id="power-controller">
<refmeta>
<refentrytitle>Implementing a Power Controller</refentrytitle>
</refmeta>
<refnamediv>
<refname>Implementing a Power Controller</refname>
<refpurpose>adding power management support to device drivers and
other packages</refpurpose>
</refnamediv>

<refsect1>
<title>Implementing a Power Controller</title>
<para>
A system will have some number of power controllers. Usually there
will be one power controller for the cpu,
<varname>power_controller_cpu</varname>, typically provided by one of
the HAL packages and responsible for managing the processor itself and
associated critical components such as memory. Some or all of the
device drivers will provide power controllers, allowing the power
consumption of the associated devices to be controlled. There may be
some arbitrary number of other controllers present in the system. The
power management package does not impose any restrictions on the
number or nature of the power controllers in the system, other than
insisting that at most one <varname>power_controller_cpu</varname> be
provided.
</para>
<para>
Each power controller involves a single data structure of type
<structname>PowerController</structname>, defined in the header file
<filename class="headerfile">cyg/power/power.h</filename>. These data
structures should all be placed in the table
<literal>__POWER__</literal>, so that the power management package and
other code can easily locate all the controllers in the system. This
table is constructed at link-time, avoiding code-size or run-time
overheads. To facilitate this the package provides two macros which
should be used to define a power controller,
<literal>POWER_CONTROLLER()</literal> and
<literal>POWER_CONTROLLER_CPU()</literal>.
</para>
<para>
The macro <literal>POWER_CONTROLLER</literal> takes four arguments:
</para>
<orderedlist>
<listitem>
<para>
A variable name. This can be used to access the power controller
directly, as well as via the table.
</para>
</listitem>
<listitem>
<para>
A priority. The table of power controllers is sorted, such that power
controllers with a numerically lower priority come earlier in the
table. The special controller <varname>power_controller_cpu</varname>
always comes at the end of the table. When moving from a high-power
mode to a lower-powered mode, the power management package iterates
through the table from front to back. When moving to a higher-powered
mode the reverse direction is used. The intention is that the power
controller for a software-only package such as a TCP/IP stack should
appear near the start of the table, whereas the controllers for the
ethernet and similar devices would be near the end of the table. Hence
when the policy module initiates a mode change to a lower-powered mode
the TCP/IP stack gets a chance to cancel this mode change, before the
devices it depends on are powered down. Similarly when moving to a
higher-powered mode the devices will be re-activated before any
software that depends on those devices.
</para>
<para>
The header file <filename
class="headerfile">cyg/power/power.h</filename> defines three
priorities <literal>PowerPri_Early</literal>,
<literal>PowerPri_Typical</literal> and
<literal>PowerPri_Late</literal>. For most controllers one of these
priorities, possibly with a small number added or subtracted, will
give sufficient control. If an application developer is uncertain
about the relative priorities of the various controllers, a simple
<link linkend="power-info-ids">test program</link> that iterates over
the table will quickly eliminate any confusion.
</para>
</listitem>
<listitem>
<para>
A constant string identifier. If the system has been configured
without support for such identifiers
(<varname>CYGIMP_POWER_PROVIDE_STRINGS</varname>) then this identifer
will be discarded at compile-time. Otherwise it will be made available
to higher-level code using the function
<function>power_get_controller_id</function>. 
</para>
</listitem>
<listitem>
<para>
A function pointer. This will be invoked to perform actual mode
changes, as described below.
</para>
</listitem>
</orderedlist>
<para>
A typical example of the use of the
<literal>POWER_CONTROLLER</literal> macro would be as follows:
</para>
<programlisting>
#include &lt;pkgconf/system.h&gt;

#ifdef CYGPKG_POWER
# include &lt;cyg/power/power.h&gt;

static void
xyzzy_device_power_mode_change(
    PowerController* controller,
    PowerMode        desired_mode,
    PowerModeChange  change)
{
   // Do the work
}

static POWER_CONTROLLER(xyzzy_power_controller, \
                        PowerPri_Late,          \
                        "xyzzy device",         \
                        &amp;xyzzy_device_power_mode_change);
#endif
</programlisting>
<para>
This creates a variable <varname>xyzzy_power_controller</varname>,
which is a power controller data structure that will end up near the
end of the table of power controllers. Higher-level code can
iterate through this table and report the string <literal>"xyzzy
device"</literal> to the user. Whenever there is a mode change
operation that affects this controller, the function
<function>xyzzy_device_power_mode_change</function> will be invoked.
The variable is declared static so this controller cannot be
manipulated by name in any other code. Alternatively, if the variable
had not been declared static other code could manipulate this
controller by name as well as through the table, especially if the
package for the xyzzy device driver explicitly declared this
variable in an exported header file. Obviously exporting the variable
involves a slight risk of a name clash at link time.
</para>
<para>
The above code explicitly checks for the presence of the power
management package before including that package's header file or
providing any related functionality. Since power management
functionality is optional, such checks are recommended.
</para>
<para>
The macro <literal>POWER_CONTROLLER_CPU</literal> only takes two
arguments, a string identifier and a mode change function pointer.
This macro always instantiates a variable
<varname>power_controller_cpu</varname> so there is no need to provide
a variable name. The resulting power controller structure always
appears at the end of the table, so there is no need to specify a
priority. Typical usage of the <literal>POWER_CONTROLLER_CPU</literal>
macro would be:
</para>
<programlisting>
static void
wumpus_processor_power_mode_change(
    PowerController* controller,
    PowerMode        desired_mode,
    PowerModeChange  change)
{
   // Do the work
}

POWER_CONTROLLER_CPU("wumpus processor", \
                     &amp;wumpus_processor_power_mode_change);
</programlisting>
<para>
This defines a power controller structure
<varname>power_controller_cpu</varname>. It should not be declared
static since higher-level code may well want to manipulate the cpu's
power mode directly, and the variable is declared by the power
management package's header file.
</para>
<para>
Some care has to be taken to ensure that the power controllers
actually end up in the final executable. If a power controller
variable ends up in an ordinary library and is never referenced
directly then typically the linker will believe that the variable is
not needed and it will not end up in the executable. For eCos packages
this can be achieved in the CDL, by specifying that the containing
source file should end up in <filename>libextras.a</filename> rather
than the default <filename>libtarget.a</filename>:
</para>
<programlisting>
cdl_package CYGPKG_HAL_WUMPUS_ARCH {
    &hellip;
    compile -library=libextras.a data.c
}
</programlisting>
<para>
If the file <filename>data.c</filename> instantiates a power
controller this is now guaranteed to end up in the final executable,
as intended. Typically HAL and device driver packages will already
have some data that must not be eliminated by the linker, so they will
already contain a file that gets built into
<filename>libextras.a</filename>. For power controllers defined inside
application code it is important that the power controllers end up in
<filename>.o</filename> object files rather than in
<filename>.a</filename> library archive files.
</para>
<para>
All the real work of a power controller is done by the mode change
function. If the power management package has been configured to use a
separate thread then this mode change function will be invoked by that
thread (except for the special case of <link
linkend="power-change-controller-now"><function>power_set_controller_mode_now</function></link>). 
If no separate thread is used then the mode change function will be
invoked directly by <function>power_set_mode</function> or
<function>power_set_controller_mode</function>.
</para>
<para>
The mode change function will be invoked with three arguments. The
first argument identifies the power controller. Usually this argument
is not actually required since a given mode change function will only
ever be invoked for a single power controller. For example,
<function>xyzzy_device_power_mode_change</function> will only ever be
used in conjunction with <varname>xyzzy_power_controller</varname>.
However there may be some packages which contain multiple controllers,
all of which can share a single mode change function, and in that case
it is essential to identify the specific controller. The second
argument specifies the mode the controller should switch to, if
possible: it will be one of <literal>PowerMode_Active</literal>,
<literal>PowerMode_Idle</literal>, <literal>PowerMode_Sleep</literal>
or <literal>PowerMode_Off</literal>. The final argument will be one of
<literal>PowerModeChange_Controller</literal>,
PowerModeChange_ControllerNow, or
<literal>PowerModeChange_Global</literal>, and identifies the call
that caused this invocation. For example, if the mode change function
was invoked because of a call to <function>power_set_mode</function>
then this argument will be <literal>PowerModeChange_Global</literal>.
It is up to each controller to decide how to interpret this final
argument. A typical controller might reject a global request to switch
to <type>off</type> mode if the associated device is still busy, but
if the request was aimed specifically at this controller then it could
instead abort any current I/O operations and switch off the device.
</para>
<para>
The <structname>PowerController</structname> data structure contains
one field, <structfield>mode</structfield>, that needs to be updated
by the power mode change function. At all times it should indicate the
current mode for this controller. When a mode change is requested the
desired mode is passed as the second argument. The exact operation of
the power mode change function depends very much on what is being
controlled and the current circumstances, but some guidelines are
possible:
</para>
<orderedlist>
<listitem>
<para>
If the request can be satisfied without obvious detriment, do so and
update the <structfield>mode</structfield> field. Reducing the power
consumption of a device that is not currently being used is generally
harmless.
</para>
</listitem>
<listitem>
<para>
If a request is a no-op, for example if the system is switching
from <type>idle</type> to <type>sleep</type> mode and the controller
does not distinguish between these modes, simply act as if the request
was satisfied.
</para>
</listitem>
<listitem>
<para>
If a request is felt to be unsafe, for example shutting down a
device that is still in use, then the controller may decide
to reject this request. This is especially true if the request was a
global mode change as opposed to one intended specifically for this
controller: in the latter case the policy module should be given due
deference. There are a number of ways in which a request can be
rejected:
</para>
<orderedlist>
<listitem>
<para>
If the request cannot be satisfied immediately but may be feasible in
a short while, leave the <structfield>mode</structfield> field
unchanged. Higher-level code in the policy module can interpret this
as a hint to retry the operation a little bit later. This approach is
also useful if the mode change can be started but will take some time
to complete, for example shutting down a socket connection, and
additional processing will be needed later on.
</para>
</listitem>
<listitem>
<para>
If the request is felt to be inappropriate, for example switching off
a device that is still in use, the mode change function can
call <function>power_set_controller_mode</function> to reset the
desired mode for this controller back to the current mode.
Higher-level code can then interpret this as a hint that there is more
activity in the system than had been apparent.
</para>
</listitem>
<listitem>
<para>
For a global mode change, if the new mode is felt to be inappropriate
then the power controller can call <function>power_set_mode</function>
to indicate this. An example of this would be the policy module
deciding to switch off the whole unit while there is still I/O
activity.
</para>
</listitem>
</orderedlist>
</listitem>
</orderedlist>
<para>
Mode change functions should not directly manipulate any other fields
in the <structname>PowerController</structname> data structure. If it
is necessary to keep track of additional data then static variables
can be used.
</para>
<para>
It should be noted that the above are only guidelines. Their
application in any given situation may be unclear. In addition the
detailed requirements of specific systems will vary, so even if the
power controller for a given device driver follows the above
guidelines exactly it may turn out that slightly different behaviour
would be more appropriate for the actual system that is being
developed. Fortunately the open source nature of
<productname>eCos</productname> allows system developers to fine-tune
power controllers to meet their exact requirements.
</para>

</refsect1>
</refentry>

<!-- }}} -->

<!-- /reference -->
</part>