--- /dev/null
+<!-- 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
+>Implementing a Power Controller</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="Attached and Detached Controllers"
+HREF="power-attached.html"><LINK
+REL="NEXT"
+TITLE="eCos USB Slave Support"
+HREF="io-usb-slave.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-attached.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+></TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="io-usb-slave.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><H1
+><A
+NAME="POWER-CONTROLLER">Implementing a Power Controller</H1
+><DIV
+CLASS="REFNAMEDIV"
+><A
+NAME="AEN15936"
+></A
+><H2
+>Name</H2
+>Implementing a Power Controller -- adding power management support to device drivers and
+other packages</DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="AEN15939"
+></A
+><H2
+>Implementing a Power Controller</H2
+><P
+>A system will have some number of power controllers. Usually there
+will be one power controller for the cpu,
+<TT
+CLASS="VARNAME"
+>power_controller_cpu</TT
+>, 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 <TT
+CLASS="VARNAME"
+>power_controller_cpu</TT
+> be
+provided.</P
+><P
+>Each power controller involves a single data structure of type
+<SPAN
+CLASS="STRUCTNAME"
+>PowerController</SPAN
+>, defined in the header file
+<TT
+CLASS="FILENAME"
+>cyg/power/power.h</TT
+>. These data
+structures should all be placed in the table
+<TT
+CLASS="LITERAL"
+>__POWER__</TT
+>, 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,
+<TT
+CLASS="LITERAL"
+>POWER_CONTROLLER()</TT
+> and
+<TT
+CLASS="LITERAL"
+>POWER_CONTROLLER_CPU()</TT
+>.</P
+><P
+>The macro <TT
+CLASS="LITERAL"
+>POWER_CONTROLLER</TT
+> takes four arguments:</P
+><P
+></P
+><OL
+TYPE="1"
+><LI
+><P
+>A variable name. This can be used to access the power controller
+directly, as well as via the table.</P
+></LI
+><LI
+><P
+>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 <TT
+CLASS="VARNAME"
+>power_controller_cpu</TT
+>
+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.</P
+><P
+>The header file <TT
+CLASS="FILENAME"
+>cyg/power/power.h</TT
+> defines three
+priorities <TT
+CLASS="LITERAL"
+>PowerPri_Early</TT
+>,
+<TT
+CLASS="LITERAL"
+>PowerPri_Typical</TT
+> and
+<TT
+CLASS="LITERAL"
+>PowerPri_Late</TT
+>. 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
+<A
+HREF="power-info.html#POWER-INFO-IDS"
+>test program</A
+> that iterates over
+the table will quickly eliminate any confusion.</P
+></LI
+><LI
+><P
+>A constant string identifier. If the system has been configured
+without support for such identifiers
+(<TT
+CLASS="VARNAME"
+>CYGIMP_POWER_PROVIDE_STRINGS</TT
+>) then this identifer
+will be discarded at compile-time. Otherwise it will be made available
+to higher-level code using the function
+<TT
+CLASS="FUNCTION"
+>power_get_controller_id</TT
+>. </P
+></LI
+><LI
+><P
+>A function pointer. This will be invoked to perform actual mode
+changes, as described below.</P
+></LI
+></OL
+><P
+>A typical example of the use of the
+<TT
+CLASS="LITERAL"
+>POWER_CONTROLLER</TT
+> macro would be as follows:</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>#include <pkgconf/system.h>
+
+#ifdef CYGPKG_POWER
+# include <cyg/power/power.h>
+
+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", \
+ &xyzzy_device_power_mode_change);
+#endif</PRE
+></TD
+></TR
+></TABLE
+><P
+>This creates a variable <TT
+CLASS="VARNAME"
+>xyzzy_power_controller</TT
+>,
+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 <TT
+CLASS="LITERAL"
+>"xyzzy
+device"</TT
+> to the user. Whenever there is a mode change
+operation that affects this controller, the function
+<TT
+CLASS="FUNCTION"
+>xyzzy_device_power_mode_change</TT
+> 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.</P
+><P
+>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.</P
+><P
+>The macro <TT
+CLASS="LITERAL"
+>POWER_CONTROLLER_CPU</TT
+> only takes two
+arguments, a string identifier and a mode change function pointer.
+This macro always instantiates a variable
+<TT
+CLASS="VARNAME"
+>power_controller_cpu</TT
+> 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 <TT
+CLASS="LITERAL"
+>POWER_CONTROLLER_CPU</TT
+>
+macro would be:</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>static void
+wumpus_processor_power_mode_change(
+ PowerController* controller,
+ PowerMode desired_mode,
+ PowerModeChange change)
+{
+ // Do the work
+}
+
+POWER_CONTROLLER_CPU("wumpus processor", \
+ &wumpus_processor_power_mode_change);</PRE
+></TD
+></TR
+></TABLE
+><P
+>This defines a power controller structure
+<TT
+CLASS="VARNAME"
+>power_controller_cpu</TT
+>. 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.</P
+><P
+>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 <TT
+CLASS="FILENAME"
+>libextras.a</TT
+> rather
+than the default <TT
+CLASS="FILENAME"
+>libtarget.a</TT
+>:</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>cdl_package CYGPKG_HAL_WUMPUS_ARCH {
+ …
+ compile -library=libextras.a data.c
+}</PRE
+></TD
+></TR
+></TABLE
+><P
+>If the file <TT
+CLASS="FILENAME"
+>data.c</TT
+> 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
+<TT
+CLASS="FILENAME"
+>libextras.a</TT
+>. For power controllers defined inside
+application code it is important that the power controllers end up in
+<TT
+CLASS="FILENAME"
+>.o</TT
+> object files rather than in
+<TT
+CLASS="FILENAME"
+>.a</TT
+> library archive files.</P
+><P
+>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 <A
+HREF="power-change.html#POWER-CHANGE-CONTROLLER-NOW"
+><TT
+CLASS="FUNCTION"
+>power_set_controller_mode_now</TT
+></A
+>).
+If no separate thread is used then the mode change function will be
+invoked directly by <TT
+CLASS="FUNCTION"
+>power_set_mode</TT
+> or
+<TT
+CLASS="FUNCTION"
+>power_set_controller_mode</TT
+>.</P
+><P
+>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,
+<TT
+CLASS="FUNCTION"
+>xyzzy_device_power_mode_change</TT
+> will only ever be
+used in conjunction with <TT
+CLASS="VARNAME"
+>xyzzy_power_controller</TT
+>.
+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 <TT
+CLASS="LITERAL"
+>PowerMode_Active</TT
+>,
+<TT
+CLASS="LITERAL"
+>PowerMode_Idle</TT
+>, <TT
+CLASS="LITERAL"
+>PowerMode_Sleep</TT
+>
+or <TT
+CLASS="LITERAL"
+>PowerMode_Off</TT
+>. The final argument will be one of
+<TT
+CLASS="LITERAL"
+>PowerModeChange_Controller</TT
+>,
+PowerModeChange_ControllerNow, or
+<TT
+CLASS="LITERAL"
+>PowerModeChange_Global</TT
+>, and identifies the call
+that caused this invocation. For example, if the mode change function
+was invoked because of a call to <TT
+CLASS="FUNCTION"
+>power_set_mode</TT
+>
+then this argument will be <TT
+CLASS="LITERAL"
+>PowerModeChange_Global</TT
+>.
+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 <SPAN
+CLASS="TYPE"
+>off</SPAN
+> 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.</P
+><P
+>The <SPAN
+CLASS="STRUCTNAME"
+>PowerController</SPAN
+> data structure contains
+one field, <TT
+CLASS="STRUCTFIELD"
+><I
+>mode</I
+></TT
+>, 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:</P
+><P
+></P
+><OL
+TYPE="1"
+><LI
+><P
+>If the request can be satisfied without obvious detriment, do so and
+update the <TT
+CLASS="STRUCTFIELD"
+><I
+>mode</I
+></TT
+> field. Reducing the power
+consumption of a device that is not currently being used is generally
+harmless.</P
+></LI
+><LI
+><P
+>If a request is a no-op, for example if the system is switching
+from <SPAN
+CLASS="TYPE"
+>idle</SPAN
+> to <SPAN
+CLASS="TYPE"
+>sleep</SPAN
+> mode and the controller
+does not distinguish between these modes, simply act as if the request
+was satisfied.</P
+></LI
+><LI
+><P
+>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:</P
+><P
+></P
+><OL
+TYPE="a"
+><LI
+><P
+>If the request cannot be satisfied immediately but may be feasible in
+a short while, leave the <TT
+CLASS="STRUCTFIELD"
+><I
+>mode</I
+></TT
+> 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.</P
+></LI
+><LI
+><P
+>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 <TT
+CLASS="FUNCTION"
+>power_set_controller_mode</TT
+> 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.</P
+></LI
+><LI
+><P
+>For a global mode change, if the new mode is felt to be inappropriate
+then the power controller can call <TT
+CLASS="FUNCTION"
+>power_set_mode</TT
+>
+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.</P
+></LI
+></OL
+></LI
+></OL
+><P
+>Mode change functions should not directly manipulate any other fields
+in the <SPAN
+CLASS="STRUCTNAME"
+>PowerController</SPAN
+> data structure. If it
+is necessary to keep track of additional data then static variables
+can be used.</P
+><P
+>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
+<SPAN
+CLASS="PRODUCTNAME"
+>eCos</SPAN
+> allows system developers to fine-tune
+power controllers to meet their exact requirements.</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-attached.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="io-usb-slave.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>Attached and Detached Controllers</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"
+>eCos USB Slave Support</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff