URL
https://opencores.org/ocsvn/or1k/or1k/trunk
Subversion Repositories or1k
[/] [or1k/] [trunk/] [ecos-2.0/] [doc/] [html/] [ref/] [power-policy.html] - Rev 1765
Compare with Previous | Blame | View Log
<!-- Copyright (C) 2003 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 is obtained from the copyright holder. -->
<HTML
><HEAD
><TITLE
>Support for Policy Modules</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="eCos Reference Manual"
HREF="ecos-ref.html"><LINK
REL="UP"
TITLE="eCos Power Management Support"
HREF="services-power.html"><LINK
REL="PREVIOUS"
TITLE="Changing Power Modes"
HREF="power-change.html"><LINK
REL="NEXT"
TITLE="Attached and Detached Controllers"
HREF="power-attached.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>eCos Reference Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="power-change.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="power-attached.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="POWER-POLICY">Support for Policy Modules</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN15836"
></A
><H2
>Name</H2
>Support for Policy Modules -- closer integration with higher-level code</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN15839"><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN15840"><P
></P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include <cyg/power/power.h></PRE
></TD
></TR
></TABLE
><P
><CODE
><CODE
CLASS="FUNCDEF"
> void power_set_policy_callback
</CODE
>( void (*)(PowerController*, PowerMode, PowerMode, PowerMode, PowerMode) callback
);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
> void (*)(PowerController*, PowerMode, PowerMode, PowerMode, PowerMode) power_get_policy_callback
</CODE
>(void);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
> CYG_ADDRWORD power_get_controller_policy_data
</CODE
>( PowerController* controller
);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
> void power_set_controller_policy_data
</CODE
>( PowerController* controller
, CYG_ADDRWORD data
);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="POWER-POLICY-CALLBACK"
></A
><H2
>Policy Callbacks</H2
><P
>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.</P
><P
>To avoid such problems the policy module can install a callback
function using <TT
CLASS="FUNCTION"
>power_set_policy_callback</TT
>. The
current callback function can be retrieved using
<TT
CLASS="FUNCTION"
>power_get_policy_callback</TT
>. 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:</P
><P
></P
><OL
TYPE="1"
><LI
><P
>The power controller that has just been invoked to perform a mode
change. </P
></LI
><LI
><P
>The mode this controller was running at before the invocation.</P
></LI
><LI
><P
>The current mode this controller is now running at.</P
></LI
><LI
><P
>The desired mode before the power controller was invoked. Usually this
will be the same as the current mode, unless the controller has
decided for some reason that this was inappropriate.</P
></LI
><LI
><P
>The current desired mode. This will differ from the previous argument
only if there has was another call to
<TT
CLASS="FUNCTION"
>power_set_mode</TT
> or
<TT
CLASS="FUNCTION"
>power_set_controller_mode</TT
> while the power
controller was being invoked, probably by the power controller itself.</P
></LI
></OL
><P
>A simple example of a policy callback function would be:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>static void
power_callback(
PowerController* controller,
PowerMode old_mode,
PowerMode new_mode,
PowerMode old_desired_mode,
powerMode new_desired_mode)
{
printf("Power mode change: %s, %s -> %d\n",
power_get_controller_id(controller),
mode_to_string(old_mode),
mode_to_string(new_mode));
CYG_UNUSED_PARAM(PowerMode, old_desired_mode);
CYG_UNUSED_PARAM(PowerMode, new_desired_mode);
}
int
main(int argc, char** argv)
{
…
power_set_policy_callback(&power_callback);
…
}</PRE
></TD
></TR
></TABLE
><P
>If <TT
CLASS="FUNCTION"
>power_set_controller_mode_now</TT
> is used to
manipulate an individual controller the policy callback will not be
invoked. This function may get called from any context including DSRs,
and even if there is already a call to the policy callback happening
in some other context, so invoking the callback would usually be
unsafe.</P
><P
>If the power management package has not been configured to use a
separate thread then <TT
CLASS="FUNCTION"
>power_set_mode</TT
> and
<TT
CLASS="FUNCTION"
>power_set_controller_mode</TT
> will manipulate the
power controllers immediately and invoke the policy callback
afterwards. Therefore the policy callback will typically run in the
same context as the main policy module.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="POWER-POLICY-DATA"
></A
><H2
>Policy-specific Controller Data</H2
><P
>Some policy modules may want to associate some additional data with
each power controller. This could be achieved by for example
maintaining a hash table or similar data structure, but for
convenience the power management package allows higher-level code,
typically the policy module, to store and retrieve one word of data in
each power controller. The function
<TT
CLASS="FUNCTION"
>power_set_controller_policy_data</TT
> takes two
arguments, a pointer to a power controller and a
<SPAN
CLASS="TYPE"
>CYG_ADDRWORD</SPAN
> of data: by appropriate use of casts this
word could be an integer or a pointer to some data structure. The
matching function
<TT
CLASS="FUNCTION"
>power_get_controller_policy_data</TT
> retrieves the
word previously installed, and can be cast back to an integer or
pointer. The default value for the policy data is 0.</P
><P
>For example the following code fragment stores a simple index value in
each power controller. This could then be retrieved by the policy
callback.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> unsigned int i = 0;
PowerController* controller;
for (controller = &(__POWER__[0]);
controller != &(__POWER_END__);
controller++) {
power_set_controller_policy_data(controller, (CYG_ADDRWORD) i++);
}</PRE
></TD
></TR
></TABLE
><P
>Not all policy modules will require per-controller data. The
configuration option
<TT
CLASS="VARNAME"
>CYGIMP_POWER_PROVIDE_POLICY_DATA</TT
> can be used to
control this functionality, thus avoiding wasting a small amount of
memory inside each power controller structure.</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="power-change.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="ecos-ref.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="power-attached.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Changing Power Modes</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="services-power.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Attached and Detached Controllers</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>