Comtrol eCos - Manual (Page 675)

Implementing a Power Controller
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
libextras.a rather than the
default libtarget.a :
cdl_package CYGPKG_HAL_WUMPUS_ARCH {
...
compile -library=libextras.a data.c
}
If the file data.c 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
libextras.a . For power controllers defined inside
application code it is important that the power controllers end up in .o object files rather than in .a library archive
files.
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
power_set_controller_mode_now ). If no separate thread is used then the mode change
function will be invoked directly by power_set_mode or power_set_controller_mode .
The mode change function will be invoked with three arguments. The first argument identifies the power con-
troller. Usually this argument is not actually required since a given mode change function will only ever be in-
voked for a single power controller. For example,
xyzzy_device_power_mode_change will only ever be used
in conjunction with xyzzy_power_controller . 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
PowerMode_Active , PowerMode_Idle , PowerMode_Sleep or PowerMode_Off . The final argument will
be one of PowerModeChange_Controller , PowerModeChange_ControllerNow, or PowerModeChange_Global ,
and identifies the call that caused this invocation. For example, if the mode change function was invoked because
of a call to
power_set_mode then this argument will be PowerModeChange_Global . 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 off 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.
The PowerController data structure contains one field, mode , 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:
1. If the request can be satisfied without obvious detriment, do so and update the mode field. Reducing the power
consumption of a device that is not currently being used is generally harmless.
2. If a request is a no-op, for example if the system is switching from idle to sleep mode and the controller does
not distinguish between these modes, simply act as if the request was satisfied.
3. 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:
571