--- /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
+>Introduction</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="eCos Power Management Support"
+HREF="services-power.html"><LINK
+REL="NEXT"
+TITLE="Power Management Information"
+HREF="power-info.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="services-power.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+></TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="power-info.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><H1
+><A
+NAME="POWER-INTRO">Introduction</H1
+><DIV
+CLASS="REFNAMEDIV"
+><A
+NAME="AEN15587"
+></A
+><H2
+>Name</H2
+>Introduction -- eCos support for Power Management</DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="POWER-INTRO-INTRO"
+></A
+><H2
+>Introduction</H2
+><P
+>The eCos Power Management package provides a framework for
+incorporating power management facilities in an embedded application.
+However its functionality is deliberately limited.</P
+><P
+></P
+><OL
+TYPE="1"
+><LI
+><P
+>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 <I
+CLASS="FIRSTTERM"
+>power
+controllers</I
+>. The power management package groups these
+power controllers together and provides an interface for manipulating
+them.</P
+></LI
+><LI
+><P
+>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.</P
+></LI
+></OL
+></DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="POWER-INTRO-INCLUDE"
+></A
+><H2
+>Including Power Management</H2
+><P
+>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 <B
+CLASS="COMMAND"
+>ecosconfig</B
+> tool this
+can be achieved using a command such as:</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>$ ecosconfig add power</PRE
+></TD
+></TR
+></TABLE
+><P
+>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
+<TT
+CLASS="FILENAME"
+>cyg/power/power.h</TT
+>. This header
+file can be used by both C and C++ code.</P
+></DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="POWER-INTRO-MODES"
+></A
+><H2
+>Power Modes</H2
+><P
+>There are four defined modes of operation:</P
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+>active</DT
+><DD
+><P
+>The system is fully operational, and power consumption is expected to
+be high.</P
+></DD
+><DT
+>idle</DT
+><DD
+><P
+>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.</P
+><P
+>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.</P
+></DD
+><DT
+>sleep</DT
+><DD
+><P
+>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.</P
+></DD
+><DT
+>off</DT
+><DD
+><P
+>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.</P
+></DD
+></DL
+></DIV
+><P
+>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.</P
+></DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="POWER-INTRO-CONTROLLERS"
+></A
+><H2
+>Power Controllers</H2
+><P
+>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:</P
+><P
+></P
+><OL
+TYPE="1"
+><LI
+><P
+>Usually there will be one power controller
+<TT
+CLASS="VARNAME"
+>power_controller_cpu</TT
+> 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 <SPAN
+CLASS="TYPE"
+>off</SPAN
+> 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.</P
+><P
+>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
+<TT
+CLASS="VARNAME"
+>power_controller_cpu</TT
+> 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.</P
+></LI
+><LI
+><P
+>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,
+<TT
+CLASS="VARNAME"
+>power_controller_cpu</TT
+> 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.</P
+></LI
+><LI
+><P
+>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 <SPAN
+CLASS="TYPE"
+>off</SPAN
+> mode while there were
+open connections).</P
+></LI
+></OL
+></DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="POWER-INTRO-OPERATION"
+></A
+><H2
+>Basic Operation</H2
+><P
+>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
+<TT
+CLASS="VARNAME"
+>CYGNUM_POWER_THREAD_STACKSIZE</TT
+> and
+<TT
+CLASS="VARNAME"
+>CYGNUM_POWER_THREAD_PRIORITY</TT
+>. 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.</P
+><P
+>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 <TT
+CLASS="FUNCTION"
+>power_set_mode</TT
+>,
+provided by the power management package and declared in <TT
+CLASS="FILENAME"
+>cyg/power/power.h</TT
+>, with a single
+argument, <TT
+CLASS="LITERAL"
+>PowerMode_Idle</TT
+>. 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.</P
+><P
+>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
+<SPAN
+CLASS="TYPE"
+>idle</SPAN
+> 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.</P
+><DIV
+CLASS="NOTE"
+><BLOCKQUOTE
+CLASS="NOTE"
+><P
+><B
+>Note: </B
+>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 <SPAN
+CLASS="TYPE"
+>off</SPAN
+> 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.</P
+></BLOCKQUOTE
+></DIV
+><P
+>Although usually calls to <TT
+CLASS="FUNCTION"
+>power_set_mode</TT
+> 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 <TT
+CLASS="FUNCTION"
+>power_set_mode</TT
+> 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.</P
+><P
+>In addition to changing the power mode for the system as a whole,
+individual controllers can be manipulated using the function
+<TT
+CLASS="FUNCTION"
+>power_set_controller_mode</TT
+>. For example, while the
+system as a whole might be in <SPAN
+CLASS="TYPE"
+>active</SPAN
+> mode certain devices
+might be kept in <SPAN
+CLASS="TYPE"
+>sleep</SPAN
+> mode until they are explicitly
+activated. It is possible to mix concurrent calls to
+<TT
+CLASS="FUNCTION"
+>power_set_mode</TT
+> and
+<TT
+CLASS="FUNCTION"
+>power_set_controller_mode</TT
+>, and when a power
+controller is invoked it may use
+<TT
+CLASS="FUNCTION"
+>power_set_controller_mode</TT
+> to request further
+changes to its own or to another controller's mode as required.</P
+><P
+>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
+operations are synchronous with respect to the calling thread. The use
+of a separate thread inside the power management package is controlled
+by the configuration option <TT
+CLASS="VARNAME"
+>CYGPKG_POWER_THREAD</TT
+>,
+which is active only if the kernel package is present and enabled by
+default.</P
+><P
+>If no separate power management thread is used then obviously the
+implementations of <TT
+CLASS="FUNCTION"
+>power_set_mode</TT
+> and
+<TT
+CLASS="FUNCTION"
+>power_set_controller_mode</TT
+> will be somewhat
+different: instead of waking up a separate thread to do the work,
+these functions will now manipulate the power controllers directly. If
+the system does still involve multiple threads then only one thread
+may call <TT
+CLASS="FUNCTION"
+>power_set_mode</TT
+> or
+<TT
+CLASS="FUNCTION"
+>power_set_controller_mode</TT
+> at a time: the power
+management package will not provide any synchronization, that must
+happen at a higher level. However when a power controller is invoked
+it can still call these functions as required.</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="services-power.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-info.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>eCos Power Management Support</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"
+>Power Management Information</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file